Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
102 lines (83 loc) · 6.32 KB

CONTRIBUTING.md

File metadata and controls

102 lines (83 loc) · 6.32 KB

Contributing

Feel free to open PRs to fix bugs, add new features, add new reusable types/widgets/operators (eg., regex operator/widget, IP type/widget etc.). Pull Requests are always welcomed :)

Development

We use pnpm. Please install pnpm:

npm install -g pnpm@9

Clone this repo, install deps with pnpm i.

Start with the demo app (with hot reload of demo code and local library code):

  • Run pnpm start.
  • Open http://localhost:3001/ in a browser.

Or with VSCode:

  • Open Run and Debug in VS Code
  • Run Run examples
  • Run Open Chrome with examples

Directory structure

  • packages/core/modules - Core functionality, does not depend from React
    • config - Core config. See CONFIG docs.
    • export - Code for export to JsonLogic, MongoDb, SQL, ElasticSearch, plain string, SpEL
    • import - Code for import from JsonLogic, SpEL
    • stores - Tree store reducer
    • actions - Actions to dispatch on store
    • index.d.ts - TS definitions
  • packages/sql/modules - SQL support
  • packages/ui/modules - Core React components
    • stores - Tree store reducer for Redux (reused from core)
    • actions - Actions to dispatch on store (reused from core, added drag)
    • config - Basic config with vanilla widgets (extends core config with factory methods to render UI components)
    • hooks - Hooks. Contains useful hook for autocomplete for other UI frameworks
    • components - Core React components
      • item - Components representing building blocks of query - rule, group, more complex "rule-group" and switch/case (for ternary mode in SpEL)
      • containers - Containers to support drag-n-drop
      • operators - Custom operators (proximity)
      • rule - Components representing building blocks of rule - field, operator, widget
      • widgets - Vanilla widgets - components to render list of fields, operators, values of different types
    • index.d.ts - TS definitions
  • packages/ui/styles - Styles for query builder
  • packages/antd - Provides config with Ant Design widgets
  • packages/mui - Provides config with MUI widgets
  • packages/material - Provides config with Material-UI v4 widgets
  • packages/bootstrap - Provides config with Bootstrap widgets
  • packages/fluent - Provides config with Fluent UI widgets
  • packages/examples - Demo app with hot reload of demo code and local library code, uses TS, uses complex config to demonstrate anvanced usage.
  • packages/sandbox - Demo app with hot reload of only demo code (uses latest version of library from npm), uses TS, uses AntDesign widgets.
  • packages/sandbox_simple - Demo app with hot reload of only demo code (uses latest version of library from npm), not uses TS, uses vanilla widgets.
  • packages/sandbox_next - Demo app on Next.js with SSR, simple server-side query storage and export
  • packages/tests - All tests are here. Uses Karma, Mocha, Chai, Enzyme

Scripts

Useful scripts:

  • pnpm i - Install packages in all workspaces. Required for other scripts!
  • pnpm start - Run examples
  • pnpm build - Build all packages and examples
  • pnpm test - Run all tests with Karma and update coverage.
  • pnpm test-dev - Run all tests with Karma in watch mode.
  • pnpm test-debug - Run tests with Karma in watch & debug mode.
  • pnpm test-debug --filter Validation WidgetsVanilla - Run only selected tests with Karma.
  • pnpm lint - Run ESLint and TSC (in all workspaces)
  • pnpm lint-fix - Run ESLint with --fix option (in in all workspaces)
  • pnpm clean - Clean all data that can be re-generated (like node_modules, build, coverage)
  • pnpm smoke - Run lint, test, build all packages and examples. Recommended before making PR

Other UI frameworks

Currently there are 5 collections of widgets:

Let's say you want to create new collection of widgets for new UI framework X to be used in this lib (and submit PR which is always welcomed!).
You can use any of this packages as a skeleton, eg. mui. I don't recommend to take antd as example as it's more complicated.
Create new package @react-awesome-query-builder/x in packages. For a playground integrate it in examples - add to dependecies in package.json, paths in tsconfig.json, aliases in webpack.config.js, skinToConfig in config.tsx.

Take PR #727 to add Fluent UI widgets as an example.

Tests

See tests readme