@genesislcap/expression-builder 14.260.1 → 14.260.2

package/dist/dts/types/public.types.d.ts

@@ -1,133 +1,256 @@
-/** @alpha **/
+/** @beta
+ * By default the expression builder uses the basic html components such as buttons and inputs. If you want to integrate your
+ * own components from a design system or otherwise you can add the tag names for your elements here. For your custom components
+ * to work they must expose the same API as the underlying HTML element they're overriding.
+ *
+ * `checkbox`: Custom element tag for checkbox inputs
+ *
+ * `text`: Custom element tag for text inputs
+ *
+ * `number`: Custom element tag for number inputs
+ *
+ * `date`: Custom element tag for date inputs
+ *
+ * `datetimeLocal`: Custom element tag for datetime-local inputs
+ *
+ * `select`: Custom element tag for select inputs
+ *
+ * `option`: Custom element tag for option elements
+ *
+ * `button`: Custom element tag for button elements
+ *
+ * `radio`: Custom element tag for radio and radio group elements. When using a custom element for a radio you require a parent radio group component to semantically link the radios into a group. The parent radio group must expose the `change` event and `value` attribute.
+ */
 export type CustomElements = {
-    /** Custom element tag for checkbox inputs */
     checkbox?: string;
-    /** Custom element tag for text inputs */
     text?: string;
-    /** Custom element tag for number inputs */
     number?: string;
-    /** Custom element tag for date inputs */
     date?: string;
-    /** Custom element tag for datetime-local inputs */
     datetimeLocal?: string;
-    /** Custom element tag for select inputs */
     select?: string;
-    /** Custom element tag for option elements */
     option?: string;
-    /** Custom element tag for button elements */
     button?: string;
-    /** Custom element tag for radio and radio group elements
-     * Assume that the radio group still exposes change event and value attribute */
     radio?: {
         input: string;
         group: string;
     };
 };
-/** @alpha **/
+/**
+ * @beta
+ * Optional strings for configuring css to be applied inside of each constituent element's shadow DOM.
+ * To apply styles to components which are used inside of multiple different components (such as buttons which are used in groups,
+ * rules, and values) you must ensure the styling is set in each block. If your styling isn't showing the ensure that you're
+ * using more specific css rules to override the precedence of your rule.
+ *
+ * `rule`: Additional CSS for expression rule component
+ *
+ * `value`: Additional CSS for rule value component
+ *
+ * `field`: Additional CSS for rule field component
+ *
+ * `operator`: Additional CSS for rule operator component
+ *
+ * `group`: Additional CSS for expression group component
+ *
+ * @privateRemarks
+ * Use css layers to help with the precedence in future.
+ */
 export type CustomStyles = {
-    /** Additional CSS for expression rule component */
     rule?: string;
-    /** Additional CSS for rule value component */
     value?: string;
-    /** Additional CSS for rule field component */
     field?: string;
-    /** Additional CSS for rule operator component */
     operator?: string;
-    /** Additional CSS for expression group component */
     group?: string;
 };
-/** @alpha **/
+/**
+ * Configuration items for the expression builder styles.
+ *
+ * `customElements`: optional `Types.CustomElements` block for overriding the html tags used in the expression builder
+ *
+ * `customStyles`: optional `Types.CustomStyles` block to configure custom css for components.
+ *
+ * @beta
+
+ **/
 export type Styles = {
-    /** Custom element tags for HTML elements */
     customElements?: CustomElements;
-    /** Custom styles for components */
     customStyles?: CustomStyles;
 };
-/** @alpha **/
+/**
+ * @beta
+ * The configuration object to set on an expression builder object. The expression builder always requires `operators`,
+ * `fields` and `combinators` to be configured.
+ *
+ * Specific implementations of the expression builder may expose these options via a different attribute and automatically
+ * configure some options. E.g. a rule (boolean) expression builder may configure boolean operators and combinators so the user
+ * doesn't have to.
+ *
+ * `operators`: Array of {@link Operator} objects
+ *
+ * `fields`: Array of {@link Field} objects
+ *
+ * `combinators`: Array of {@link Combinator} objects
+ *
+ * `model`: Optional {@link Group} model to hydrate
+ *
+ * `maxNesting`: If set and more than 0, is a 1-indexed config for the maximum nesting level of groups.
+ *
+ * `partialRuleValidationWarning`: If set a rule will highlight in an error colour when it's not complete (doesn't have a field + operator + (maybe value) selected)
+ */
+/** @beta **/
 export type Config = {
     operators: Operator[];
     fields: Field[];
     combinators: Combinator[];
-    /** Model to hydrate */
     model?: Group;
-    /** If set and more than 0, is a 1-indexed config for the nesting of groups */
     maxNesting?: number;
-    /** If set a rule will highlight in an error colour when it's not complete
-     * (doesn't have a field + operator + (maybe value) selected) */
     partialRuleValidationWarning?: boolean;
 };
-/** @alpha **/
+/**
+ * The shared configuration properties of an operator
+ * @beta
+ *
+ * `applyTo`: Only allow this operator to be used on a field type (e.g. only allow this on an enum)
+ *
+ * `optgroup`: Group the operators inside of the select component
+ *
+ * `type`: The name of the operator (e.g. one_of)
+ *
+ * `tooltip`: Optional tooltip to display on mouse hover
+ */
+/** @beta **/
 export type _Operator = {
     applyTo: FieldTypes['type'][];
     optgroup?: string | null;
     type: string;
     tooltip?: string;
 };
-/** @alpha **/
+/**
+ * An operator which doesn't have any value. Example `is_null`
+ * @beta
+ * **/
 export type UniraryOperator = {
     nbInputs: 0;
 } & _Operator;
-/** @alpha **/
+/**
+ * An operator which has one value. Example `greater_than`
+ * @beta **/
 export type BinaryOperator = {
     nbInputs: 1;
 } & _Operator;
-/** @alpha **/
+/**
+ * An operator which has two values. Example `between_inclusive`
+ * @beta **/
 export type TernararyOperator = {
     nbInputs: 2;
 } & _Operator;
-/** @alpha **/
+/**
+ * An operator which can have any number of values where `NumVals >= 1`, defaulting to 1. Example `one_of`.
+ * @beta **/
 export type VariadicOperator = {
     nbInputs: 'many';
 } & _Operator;
-/** @alpha **/
+/** @beta **/
 export type Operator = UniraryOperator | BinaryOperator | TernararyOperator | VariadicOperator;
-/** @alpha **/
+/**
+ * Configuration for a text-type input, which has a string value and a text input.
+ * @beta **/
 export type TextInput = {
     type: 'string';
     input: 'text';
     validation?: (x: unknown) => string | null;
 };
-/** @alpha **/
+/**
+ * Configuration for a number-type input, which has a number value and a number input.
+ * @beta **/
 export type NumberInput = {
     input: 'number';
     type: 'int' | 'short' | 'double' | 'long' | 'bigdecimal';
     validation?: (x: unknown) => string | null;
 };
-/** @alpha **/
+/**
+ * Configuration for a boolean-type input, which has a boolean value and a checkbox.
+ * @beta **/
 export type CheckboxInput = {
     input: 'checkbox';
     type: 'boolean';
 };
-/** @alpha **/
+/**
+ * Configuration for an enum-type input, which as a string or number value, and uses a select input.
+ * @beta **/
 export type SelectInput = {
     input: 'select';
     type: 'enum';
     values: Record<string, string | number>;
 };
-/** @alpha **/
+/**
+ * Configuration for a date input, which has s string value and a date field input
+ * @beta **/
 export type DateInput = {
     input: 'date';
     type: 'date';
     validation?: (x: unknown) => string | null;
 };
-/** @alpha **/
+/**
+ * Configuration for a datetime input, which has s string value and a datetime field input
+ * @beta **/
 export type DateTimeInput = {
     input: 'datetime-local';
     type: 'date-time';
     validation?: (x: unknown) => string | null;
 };
-/** @alpha **/
+/**
+ * Union of all input types
+ * @beta **/
 export type FieldTypes = TextInput | NumberInput | CheckboxInput | SelectInput | DateInput | DateTimeInput;
-/** @alpha **/
+/**
+ * Configuration for the fields which the user can choose from per rule, the left hand side of each rule expression.
+ * @beta
+ *
+ * `optgroup`: Group the fields inside of the select component. This option currently isn't supported if you're using custom elements configured with {@link CustomElements}.
+ *
+ * `defaultValue`: Default value for the field. If set then the value of any rule operands is defaulted to this value, but the user can change the value to something else.
+ *
+ * `fieldId`: Id for the field
+ *
+ * `label`: Label for the field, what the user sees on the select input listbox.
+ *
+ * (not yet implemented) `operators`: Constrain the operators which can be used with this field (e.g. only allow starts_with on a string)
+ */
+/** @beta **/
 export type Field = {
     optgroup?: string | null;
-    data?: any;
     defaultValue?: any;
     fieldId: string;
     label: string;
     operators?: string[];
 } & FieldTypes;
-/** @alpha **/
+/**
+ * A combinator is a type of expression which can link two or more rules or groups. The most simple example is `AND` and `OR` which
+ * can take any number of expressions to produce one boolean value.
+ * @beta
+ *
+ * `type`: e.g., 'AND', 'OR', 'XOR', 'MULTIPLY', etc.
+ *
+ * `maxRules`: Controls number of nested rules. Max 1 only allows 1 rule, Max 2 allows 2 rules/groups, many allows any rules/groups
+ *
+ * `invisible`: If true then it won't appear on the component UI and is only selectable programmatically, or by default if it's the first and only value. If the only combinators are invisible then you're configuring the expression builder to not use combinators. Use the {@link NULL_COMBINATOR} for this purpose.
+ *
+ * `label`: Optional: Display label (if different from type)
+ *
+ * (not yet implemented) `description`: Optional: More details about the combinator
+ *
+ * (not yet implemented) `allowedFields`: Array of allowed field IDs (or `null` for all)
+ *
+ * (not yet implemented) `allowedOperators`: Explicit array of allowed operator types. (or `null` for all)
+ *
+ * (not yet implemented) `validator`: Optional: A validation function for the whole group. Null is valid, string is error message
+ *
+ * (not yet implemented) `allowLiterals`: Allow literal values instead of having to select a field
+ *
+ * (not yet implemented) `forceFieldOnly`: If the user selects a field they use it for it's value, without an operation on it
+ */
+/** @beta **/
 export type Combinator = {
     type: string;
     maxRules: 1 | 2 | 'many';
@@ -140,7 +263,18 @@ export type Combinator = {
     allowLiterals?: boolean;
     forceFieldOnly?: boolean;
 };
-/** @alpha **/
+/**
+ * A rule is a single constituent element of a larger expression, and is the smallest whole part of an expression.
+ *
+ * @example
+ * ```
+ * FIELD : PROFILE_AGE
+ * OPERATOR : GREATER_THAN
+ * VALUE : 18
+ *
+ * If you're constructing a boolean expression then this rule could be used to restrict users who are 17 or younger.
+ * ```
+  @beta **/
 export type Rule = {
     field: Field | null;
 } & ({
@@ -157,7 +291,36 @@ export type Rule = {
     operator: VariadicOperator;
     value: any[];
 });
-/** @alpha **/
+/**
+ * A group forms the overall model of the expression builder, and is recursive to itself allowing for a nested tree.
+ *
+ * @example
+ * ```
+ * RULE 1
+ * FIELD : PROFILE_AGE
+ * OPERATOR : GREATER_THAN
+ * VALUE : 18
+ *
+ * COMBINATOR : OR
+ *
+ * GROUP 2
+ *    RULE 2
+ *    FIELD : PARENT_ROLE
+ *    OPERATOR : ONE_OF
+ *    VALUE : GIVES_PERMISSION
+ *
+ *    COMBINATOR : AND
+ *
+ *    RULE 3
+ *    FIELD : GRANTS_CHILD_ACCESS
+ *    OPERATOR : EQUALS
+ *    VALUE : true
+ *
+ * If you're constructing a boolean expression then this rule could be used to restrict users who are 17 or younger, but
+ * allowing parents who have specific rights to be able to grant access too.
+ * ```
+ * @beta
+ */
 export type Group = {
     combinator: Combinator;
     children: (Rule | Group)[];

package/dist/dts/types/public.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"public.types.d.ts","sourceRoot":"","sources":["../../../src/types/public.types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"public.types.d.ts","sourceRoot":"","sources":["../../../src/types/public.types.ts"],"names":[],"mappings":"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"}

package/dist/dts/utils/formatting.d.ts

@@ -1,15 +1,19 @@
 /**
  * Gets the string representation from a `Date` which is the format a `date` input uses.
- * `yyyy-mm-dd`
+ * `yyyy-mm-dd`.
  * Uses UTC methods to ensure consistent output regardless of timezone.
- * @alpha
+ *
+ * Used to convert a javascript date object into the required string format expected by the expression builder.
+ * @beta
  */
 export declare const formatDateString: (date: Date) => string;
 /**
  * Gets the string representation from a `Date` which is the format a `datetime-local` input uses.
- * `yyyy-mm-ddThh:mm:ss`
+ * `yyyy-mm-ddThh:mm:ss`.
  * Uses UTC methods to ensure consistent output regardless of timezone.
- * @alpha
+ *
+ * Used to convert a javascript date object into the required string format expected by the expression builder.
+ * @beta
  */
 export declare const formatDateTimeString: (date: Date) => string;
 //# sourceMappingURL=formatting.d.ts.map

package/dist/dts/utils/formatting.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatting.d.ts","sourceRoot":"","sources":["../../../src/utils/formatting.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,SAAU,IAAI,WAK1C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,SAAU,IAAI,WAM9C,CAAC"}
+{"version":3,"file":"formatting.d.ts","sourceRoot":"","sources":["../../../src/utils/formatting.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,SAAU,IAAI,WAK1C,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,SAAU,IAAI,WAM9C,CAAC"}

package/dist/esm/config/combinators.js

@@ -1,4 +1,7 @@
-/** @alpha */
+/**
+ * Basic `AND` and `OR` logical combinators which can be used in the model config.
+ * @beta
+ * */
 export const BASE_LOGICAL_COMBINATORS = [
     {
         type: 'AND',
@@ -9,7 +12,10 @@ export const BASE_LOGICAL_COMBINATORS = [
         maxRules: 'many',
     },
 ];
-/** @alpha */
+/**
+ * A set of boolean logic combinators which configure the expression builder to produce boolean expressions.
+ * @beta
+ * */
 export const LOGICAL_COMBINATORS = [
     ...BASE_LOGICAL_COMBINATORS,
     {
@@ -29,7 +35,12 @@ export const LOGICAL_COMBINATORS = [
         maxRules: 2,
     },
 ];
-/** @alpha */
+/**
+ * A combinator which has a null action.
+ *
+ * If configured as the only combinator then it configures the expression builder to only create a single rule.
+ * @beta
+ * */
 export const NULL_COMBINATOR = {
     type: 'NULL',
     maxRules: 1,

package/dist/esm/main/expression-builder.js

@@ -9,10 +9,46 @@ import { ExpressionGroup } from './expression-group/expression-group';
 import { ExpressionRule } from './expression-rule/expression-rule';
 ExpressionGroup;
 ExpressionRule;
-/** @alpha **/
+/**
+ * Top level component to allow the user to build expressions. It produces a generic payload which doesn't have any system by itself
+ * to evaluate or execute the built expression.
+ *
+ * The basics required to work with this component:
+ *
+ * {@link ExpressionBuilder.config} property to configure and input data and models into the component.
+ *
+ * _Event_ change - `Types.Group` emits the model configuration on change. If you create a child component of the expression builder
+ * where you want to use a different (e.g. domain specific) model then it will likely override then emit event and instead emit
+ * it's own model. To check the underlying `Types.Group` model check the {@link ExpressionBuilder.model} property.
+ *
+ * @beta
+ */
 let ExpressionBuilder = class ExpressionBuilder extends GenesisElement {
     constructor() {
         super(...arguments);
+        /**
+         * model - `Types.Group` the current model which completely describes the state of the component.
+         *
+         * *IMPORTANT* you should not set this yourself via this property directly, you should always set it via the model property on the {@link ExpressionBuilder.config} block.
+         *
+         * You may want to read from this variable to get the most up to date state, for example if you create a child component which
+         * has a model which isn't valid for every single state (e.g. requires a complete rule) you can check this underlying model to
+         * verify what field or operator is selected.
+         *
+         * @beta
+         *
+         * @example
+         * ```ts
+         * const model = document.querySelector('expression-builder');
+         * // Once you have the model you can read it to check the applied config. While the primary use should be checking the updated model via
+         * the emited change event, you can use this to check more specific changes that a domain specific model might not.
+         *
+         * For example, imagine a RulExpressionBuilder which is an implementation specifically for a boolean logic expression. That component may not
+         * model a non-complete rule (a rule without a field, and operator, and value). In that case when it emits the event the payload will only change
+         * when the user has completely configured a new rule. But if you need to catch cases earlier when they've changed the field but before they've
+         * changed the value you can check the model here.
+         * ```
+         */
         this.model = null;
         this.ruleCount = 0;
         this.groupCount = 0;
@@ -48,7 +84,7 @@ let ExpressionBuilder = class ExpressionBuilder extends GenesisElement {
         this.dispatchChangeEvent(group);
     }
     /**
-     * @alpha
+     * @beta
      * Dispatches the provided model to the DOM.
      *
      * @remarks
@@ -78,6 +114,7 @@ let ExpressionBuilder = class ExpressionBuilder extends GenesisElement {
         return `rule-${this.ruleCount}`;
     }
     // Behaviour
+    /** @internal */
     connectedCallback() {
         super.connectedCallback();
         if (!this.config || !this.config.combinators || !this.config.operators || !this.config.fields) {
@@ -99,6 +136,7 @@ let ExpressionBuilder = class ExpressionBuilder extends GenesisElement {
             combinator: this.config.combinators[0],
         };
     }
+    /** @internal */
     disconnectedCallback() {
         super.disconnectedCallback();
         this.removeEventListener(Events.AddGroup, this.handleAddGroup);

package/dist/esm/utils/formatting.js

@@ -1,8 +1,10 @@
 /**
  * Gets the string representation from a `Date` which is the format a `date` input uses.
- * `yyyy-mm-dd`
+ * `yyyy-mm-dd`.
  * Uses UTC methods to ensure consistent output regardless of timezone.
- * @alpha
+ *
+ * Used to convert a javascript date object into the required string format expected by the expression builder.
+ * @beta
  */
 export const formatDateString = (date) => {
     const year = date.getUTCFullYear();
@@ -12,9 +14,11 @@ export const formatDateString = (date) => {
 };
 /**
  * Gets the string representation from a `Date` which is the format a `datetime-local` input uses.
- * `yyyy-mm-ddThh:mm:ss`
+ * `yyyy-mm-ddThh:mm:ss`.
  * Uses UTC methods to ensure consistent output regardless of timezone.
- * @alpha
+ *
+ * Used to convert a javascript date object into the required string format expected by the expression builder.
+ * @beta
  */
 export const formatDateTimeString = (date) => {
     const datePart = formatDateString(date);