@limetech/lime-crm-building-blocks 2.0.4 → 2.2.0

package/dist/collection/components/condition-tree/condition-tree.js

@@ -0,0 +1,461 @@
+import { Host, h, } from "@stencil/core";
+import { CONDITION_TREE_COMBINATORS, oppositeCombinator, } from "./condition-tree-combinators";
+import { ConditionTreeWalker } from "./condition-tree-nodes";
+import { ConditionTreeOpenState } from "./condition-tree-open-state";
+import { GroupView, NodeView } from "./group-node-view";
+import { createTranslator } from "./condition-tree-translate";
+/**
+ * The group drawn when there is no tree yet. Nothing is inside it, so no
+ * combinator is offered and there is nothing to delete or to group.
+ */
+const EMPTY_GROUP = {
+    kind: 'group',
+    combinator: 'all',
+    children: [],
+};
+/**
+ * The shared skeleton for editing a tree of conditions: nested groups joined by
+ * "All of the following" or "Any of the following", or the negations of those
+ * two, each holding conditions shown as chips, with the buttons that add,
+ * remove and regroup them.
+ *
+ * This component is deliberately ignorant of what a condition *is*.
+ *
+ * A condition is visualized as a chip, plus the tag name of an editor to open.
+ * So the same skeleton serves a condition that tests a property ("Deal value is
+ * greater than 100 000") and one that is opaque ("User is a member of a group")
+ * without either model leaking into it.
+ *
+ * It holds no tree of its own either. The consumer passes in its own tree, and
+ * an adapter that reads one node and rebuilds one group. Every structural edit
+ * — add, delete, regroup, rejoin, negate — is applied here and handed back as a
+ * tree of the same kind, so no consumer has to write that code twice.
+ *
+ * @exampleComponent limebb-example-condition-tree-basic
+ * @exampleComponent limebb-example-condition-tree-combinators
+ * @exampleComponent limebb-example-condition-tree-editors
+ * @exampleComponent limebb-example-condition-tree-palette
+ *
+ * @beta
+ */
+export class ConditionTree {
+    constructor() {
+        /**
+         * Which combinators to offer in the group dropdowns, in the order given.
+         *
+         * All four are offered by default. "Not all of the following" and "None of
+         * the following" are harder to reason about than the two they negate, so a
+         * consumer whose users would be better served without them passes
+         * `['all', 'any']`. A group that already uses a combinator left off this
+         * list still shows it, rather than misrepresenting itself as using one of
+         * the offered ones.
+         */
+        this.combinators = [
+            ...CONDITION_TREE_COMBINATORS,
+        ];
+        /**
+         * Set to `true` when the tree is not the viewer's to change: the add,
+         * delete and negate controls are not rendered at all, leaving the
+         * conditions to be read. Use it where the tree is being shown rather than
+         * edited — a saved filter summarized on a card, or a rule the viewer has
+         * no rights over.
+         */
+        this.readonly = false;
+        /**
+         * Set to `true` when the tree *is* the viewer's to change, but not at this
+         * moment: every control stays where it is, dimmed and inert. Use it for a
+         * state that will pass — a form mid-save, or a tree behind an "Apply a
+         * filter" switch that is currently off.
+         */
+        this.disabled = false;
+        /**
+         * Which editor is open, and what the user has already been through — see
+         * `condition-tree-open-state.ts`.
+         */
+        this.openState = ConditionTreeOpenState.empty();
+    }
+    componentWillLoad() {
+        this.buildWalker();
+    }
+    buildWalker() {
+        this.walker = new ConditionTreeWalker(this.adapter, (node) => this.openState.hasSeen(node));
+        this.syncOpenState();
+    }
+    /**
+     * Nothing can be read out of a tree until there is an adapter to read it
+     * with, so a tree that arrives first waits here. `buildWalker` catches it
+     * up when the adapter turns up.
+     */
+    syncOpenState() {
+        if (!this.adapter) {
+            return;
+        }
+        this.openState = this.openState.sync(this.value, this.walker);
+    }
+    render() {
+        if (!this.adapter) {
+            return h(Host, null);
+        }
+        return (h(Host, null, this.isEmpty ? (this.renderEmptyState()) : (h(NodeView, { node: this.value, description: this.walker.describe(this.value), path: [], ctx: this.renderContext() }))));
+    }
+    /**
+     * The empty tree is drawn as the group it is about to become, rather than
+     * as a lone button: every condition here ends up inside a group, so the
+     * first one lands in a frame that was already on screen instead of
+     * conjuring one around itself. It can be filled either way round, with a
+     * condition or with a nested group.
+     */
+    renderEmptyState() {
+        if (this.readonly) {
+            return null;
+        }
+        return (h(GroupView, { description: EMPTY_GROUP, path: [], ctx: this.renderContext(), placeholder: true }));
+    }
+    renderContext() {
+        return {
+            platform: this.platform,
+            context: this.context,
+            walker: this.walker,
+            translate: createTranslator(this.platform),
+            combinators: this.combinators,
+            readonly: this.readonly,
+            disabled: this.disabled,
+            negatable: !!this.adapter.negate,
+            openNode: this.openState.openNode,
+            addOptions: this.addOptions,
+            onAddLeaf: (path, item) => this.addLeaf(path, item),
+            onAddGroup: (path) => this.addGroup(path),
+            onDelete: (path) => this.applyEdit((root) => this.walker.replaceAt(root, path, undefined)),
+            onCombinator: (path, combinator) => this.applyEdit((root) => this.walker.rejoinAt(root, path, combinator)),
+            onNegate: (path, negated) => this.applyEdit((root) => this.walker.negateAt(root, path, negated)),
+            onConditionChange: (path, next) => {
+                this.openState = this.openState.expect(next);
+                this.applyEdit((root) => this.walker.replaceAt(root, path, next));
+            },
+            onOpen: (node) => {
+                this.openState = this.openState.moveTo(node);
+            },
+        };
+    }
+    addLeaf(path, item) {
+        this.grow(path, this.adapter.createLeaf(item));
+    }
+    /**
+     * A nested group is joined the other way round from the one holding it: a
+     * group joined the same way as its parent would say nothing the parent does
+     * not already say.
+     * @param path
+     */
+    addGroup(path) {
+        var _a, _b;
+        const combinator = (_b = (_a = this.walker.groupAt(this.value, path)) === null || _a === void 0 ? void 0 : _a.combinator) !== null && _b !== void 0 ? _b : this.rootCombinator();
+        this.grow(path, this.adapter.group(oppositeCombinator(combinator), this.newGroupChildren()));
+    }
+    /**
+     * What a new group starts with: one blank condition, so that a group is
+     * never handed over saying nothing — the same rule by which a group emptied
+     * of its last condition is dropped rather than kept. A consumer offering a
+     * menu of kinds is the exception, since the tree cannot know which kind to
+     * make.
+     */
+    newGroupChildren() {
+        var _a;
+        if ((_a = this.addOptions) === null || _a === void 0 ? void 0 : _a.length) {
+            return [];
+        }
+        return [this.adapter.createLeaf()];
+    }
+    /**
+     * Add a condition, or a group to put conditions in.
+     *
+     * Everything in this tree lives inside a group, so the first thing added
+     * to an empty one gets a root group to live in. After that the walker
+     * places it.
+     * @param path
+     * @param child
+     */
+    grow(path, child) {
+        if (this.isEmpty) {
+            this.emitChange(this.adapter.group(this.rootCombinator(), [child]));
+            return;
+        }
+        this.emitChange(this.walker.appendAt(this.value, path, child));
+    }
+    /**
+     * An empty tree has nothing to edit.
+     * @param edit
+     */
+    applyEdit(edit) {
+        if (this.isEmpty) {
+            return;
+        }
+        this.emitChange(edit(this.value));
+    }
+    /**
+     * Announce a tree the user has changed — unless it was not theirs to
+     * change. Every control is hidden or dimmed by then, so what this catches
+     * is an editor: the tree mounts whatever component a condition names, and
+     * has no way to make it honour the `readonly` it was handed.
+     * @param next
+     */
+    emitChange(next) {
+        if (this.readonly || this.disabled) {
+            return;
+        }
+        this.change.emit(next);
+    }
+    /**
+     * Whether there is no tree yet — which is not the same as a tree that
+     * happens to be an empty group.
+     */
+    get isEmpty() {
+        return this.value === undefined || this.value === null;
+    }
+    /**
+     * The combinator a group made here is joined by: the first one the consumer
+     * offers, so a tree that never offers "All of the following" never invents
+     * one.
+     */
+    rootCombinator() {
+        var _a;
+        return (_a = this.combinators[0]) !== null && _a !== void 0 ? _a : 'all';
+    }
+    static get is() { return "limebb-condition-tree"; }
+    static get encapsulation() { return "shadow"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["condition-tree.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["condition-tree.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "platform": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "LimeWebComponentPlatform",
+                    "resolved": "LimeWebComponentPlatform",
+                    "references": {
+                        "LimeWebComponentPlatform": {
+                            "location": "import",
+                            "path": "@limetech/lime-web-components",
+                            "id": "node_modules::LimeWebComponentPlatform",
+                            "referenceLocation": "LimeWebComponentPlatform"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Platform service provider"
+                },
+                "getter": false,
+                "setter": false
+            },
+            "context": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "LimeWebComponentContext",
+                    "resolved": "LimeWebComponentContext",
+                    "references": {
+                        "LimeWebComponentContext": {
+                            "location": "import",
+                            "path": "@limetech/lime-web-components",
+                            "id": "node_modules::LimeWebComponentContext",
+                            "referenceLocation": "LimeWebComponentContext"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Component context, forwarded to each condition's editor."
+                },
+                "getter": false,
+                "setter": false
+            },
+            "value": {
+                "type": "any",
+                "mutable": false,
+                "complexType": {
+                    "original": "any",
+                    "resolved": "any",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "The consumer's own tree, rendered as-is \u2014 the root node, in whatever\nshape `adapter` reads. Leave it unset for a tree with nothing in it yet,\nwhich draws an empty group asking for its first condition."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "value"
+            },
+            "adapter": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "ConditionTreeAdapter<any>",
+                    "resolved": "ConditionTreeAdapter<any>",
+                    "references": {
+                        "ConditionTreeAdapter": {
+                            "location": "import",
+                            "path": "./condition-tree.types",
+                            "id": "src/components/condition-tree/condition-tree.types.ts::ConditionTreeAdapter",
+                            "referenceLocation": "ConditionTreeAdapter"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "How to read and rebuild `value`. Build it once and hold on to it: one\nbuilt inside a consumer's `render()` is a new object every time, which\nmakes this component re-render for no reason.\n\nA Stencil element cannot be generic, so this is typed loosely here.\nDeclare the adapter as `ConditionTreeAdapter<YourNode>` where you write\nit, and the compiler checks it against your own model."
+                },
+                "getter": false,
+                "setter": false
+            },
+            "combinators": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "ConditionTreeCombinator[]",
+                    "resolved": "ConditionTreeCombinator[]",
+                    "references": {
+                        "ConditionTreeCombinator": {
+                            "location": "import",
+                            "path": "./condition-tree.types",
+                            "id": "src/components/condition-tree/condition-tree.types.ts::ConditionTreeCombinator",
+                            "referenceLocation": "ConditionTreeCombinator"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Which combinators to offer in the group dropdowns, in the order given.\n\nAll four are offered by default. \"Not all of the following\" and \"None of\nthe following\" are harder to reason about than the two they negate, so a\nconsumer whose users would be better served without them passes\n`['all', 'any']`. A group that already uses a combinator left off this\nlist still shows it, rather than misrepresenting itself as using one of\nthe offered ones."
+                },
+                "getter": false,
+                "setter": false,
+                "defaultValue": "[\n        ...CONDITION_TREE_COMBINATORS,\n    ]"
+            },
+            "addOptions": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "Array<MenuItem | ListSeparator>",
+                    "resolved": "(ListSeparator | MenuItem<any>)[] | undefined",
+                    "references": {
+                        "Array": {
+                            "location": "global",
+                            "id": "global::Array"
+                        },
+                        "MenuItem": {
+                            "location": "import",
+                            "path": "@limetech/lime-elements",
+                            "id": "node_modules::MenuItem",
+                            "referenceLocation": "MenuItem"
+                        },
+                        "ListSeparator": {
+                            "location": "import",
+                            "path": "@limetech/lime-elements",
+                            "id": "node_modules::ListSeparator",
+                            "referenceLocation": "ListSeparator"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "The kinds of condition a user can add, offered as a menu when the add\nbutton is pressed. The chosen item is passed to `adapter.createLeaf`.\n\nLeave it unset when every condition in the tree is of the same kind:\na blank one can simply be inserted, and its editor settles the rest, so\npressing the button is the whole interaction. Set it when conditions come\nin kinds that have nothing in common \u2014 \"the deal is worth more than\n100 000\", \"the user belongs to a group\", \"it is the first day of the\nmonth\" \u2014 where nothing can be inserted until the user says which.\n\nThe menu has to be rendered here rather than by the consumer, because\nthe button it hangs from lives inside this component."
+                },
+                "getter": false,
+                "setter": false
+            },
+            "readonly": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Set to `true` when the tree is not the viewer's to change: the add,\ndelete and negate controls are not rendered at all, leaving the\nconditions to be read. Use it where the tree is being shown rather than\nedited \u2014 a saved filter summarized on a card, or a rule the viewer has\nno rights over."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "readonly",
+                "defaultValue": "false"
+            },
+            "disabled": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Set to `true` when the tree *is* the viewer's to change, but not at this\nmoment: every control stays where it is, dimmed and inert. Use it for a\nstate that will pass \u2014 a form mid-save, or a tree behind an \"Apply a\nfilter\" switch that is currently off."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "disabled",
+                "defaultValue": "false"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "openState": {}
+        };
+    }
+    static get events() {
+        return [{
+                "method": "change",
+                "name": "change",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted with the whole tree, of the consumer's own kind, whenever the\nuser changes it. `null` means the last condition went and there is\nnothing left \u2014 an event carries no detail otherwise."
+                },
+                "complexType": {
+                    "original": "any",
+                    "resolved": "any",
+                    "references": {}
+                }
+            }];
+    }
+    static get watchers() {
+        return [{
+                "propName": "adapter",
+                "methodName": "buildWalker"
+            }, {
+                "propName": "value",
+                "methodName": "syncOpenState"
+            }];
+    }
+}

package/dist/collection/components/condition-tree/condition-tree.types.js

@@ -0,0 +1 @@
+export {};

package/dist/collection/components/condition-tree/group-node-view.js

@@ -0,0 +1,153 @@
+import { h } from "@stencil/core";
+import { COMBINATOR_PRESENTATION } from "./condition-tree-combinators";
+import { pathKey } from "./condition-tree-nodes";
+import { handleDelete, IssuesView, } from "./condition-tree-view-context";
+import { LeafView } from "./leaf-node-view";
+/**
+ * Render one of the consumer's nodes, whichever kind the adapter says it is.
+ *
+ * It lives beside `GroupView` because a group is what holds nodes of either
+ * kind: the recursion is the group's, and keeping the choice here is what lets
+ * a group draw a group without two modules importing each other.
+ * @param props
+ */
+export const NodeView = (props) => {
+    const { description } = props;
+    if (description.kind === 'group') {
+        return (h(GroupView, { description: description, path: props.path, ctx: props.ctx }));
+    }
+    return (h(LeafView, { node: props.node, description: description, path: props.path, ctx: props.ctx }));
+};
+/**
+ * A box holding a combinator, the conditions joined by it, and the two buttons
+ * that grow it.
+ * @param props
+ */
+export const GroupView = (props) => {
+    const { description, path, ctx, placeholder } = props;
+    const presentation = COMBINATOR_PRESENTATION[description.combinator];
+    const delimiter = ctx.translate(presentation.delimiterKey, presentation.delimiter);
+    // The marker between two rows reads as the join itself: "&", "or", and
+    // for the negated combinators the same joins prefixed with "not".
+    const marker = presentation.negated
+        ? `${ctx.translate('webclient.delimiter.not', 'not')} ${delimiter}`
+        : delimiter;
+    return (h("div", { class: "group", key: pathKey(path), "data-combinator": description.combinator, style: { '--group-rail-color': presentation.color } }, h("div", { class: "group-header" }, renderCombinator(description, path, ctx), renderDeleteGroup(path, ctx, placeholder)), h(IssuesView, { issues: description.issues }), h("ul", { class: "rows" }, description.children.map((child, index) => {
+        const childDescription = ctx.walker.describe(child);
+        return (h("li", { class: {
+                row: true,
+                'row--group': childDescription.kind === 'group',
+            }, "data-marker": marker, key: pathKey([...path, index]) }, h(NodeView, { node: child, description: childDescription, path: [...path, index], ctx: ctx })));
+    }), renderAddCondition(path, marker, ctx)), renderAddGroup(path, ctx)));
+};
+/**
+ * The "+" that turns a noun into an action.
+ *
+ * The chips and buttons that grow the tree read as "+ Condition" and
+ * "+ Group": a sighted reader takes the glyph as the verb, so the label only
+ * has to carry the noun. A screen reader cannot — an icon without a `title`
+ * is hidden from it entirely, leaving nothing but a bare "Condition". The
+ * title supplies the missing verb, and lime-elements composes the two into
+ * "Add Condition" for assistive technology and for the tooltip alike.
+ *
+ * This is why the translated strings behind these are nouns, and must stay
+ * nouns: the verb lives here.
+ * @param ctx
+ * @param color
+ */
+function addIcon(ctx, color) {
+    return {
+        name: 'plus_math',
+        title: ctx.translate('webclient.add', 'Add'),
+        color: color,
+    };
+}
+/**
+ * The combinators to list, which is what the consumer offers — plus the one the
+ * group already uses, when that is not among them. A group saved before the
+ * consumer narrowed the list has to keep saying what it does, rather than
+ * misrepresenting itself as using one of the offered ones.
+ * @param ctx
+ * @param current
+ */
+function combinatorOptions(ctx, current) {
+    const combinators = [...ctx.combinators];
+    if (current && !combinators.includes(current)) {
+        combinators.push(current);
+    }
+    return combinators.map((combinator) => {
+        const presentation = COMBINATOR_PRESENTATION[combinator];
+        return {
+            value: combinator,
+            text: ctx.translate(presentation.labelKey, presentation.label),
+            secondaryText: ctx.translate(presentation.descriptionKey, presentation.description),
+            icon: {
+                name: presentation.iconName,
+                color: presentation.color,
+            },
+        };
+    });
+}
+/**
+ * The dropdown that says how a group joins what is inside it.
+ *
+ * A group holding fewer than two things has nothing to join yet, so choosing
+ * between "All of the following" and "Any of the following" would change
+ * nothing, and the dropdown is left out until there is a second thing for it to
+ * act on. A negating combinator is the exception: "None of the following" says
+ * something about a lone condition that "All of the following" does not, so
+ * leaving it out would leave out the negation with it.
+ * @param description
+ * @param path
+ * @param ctx
+ */
+function renderCombinator(description, path, ctx) {
+    const joins = description.children.length > 1;
+    if (!joins && !COMBINATOR_PRESENTATION[description.combinator].negated) {
+        return null;
+    }
+    const options = combinatorOptions(ctx, description.combinator);
+    // No label: every option is a full sentence about the group ("All of the
+    // following"), so a label above it could only name the same thing twice.
+    // The accessible name comes from the selected option for the same reason.
+    return (h("limel-select", { class: "combinator", value: options.find((option) => option.value === description.combinator), options: options, disabled: ctx.disabled, readonly: ctx.readonly, onChange: handleCombinator(path, ctx) }));
+}
+function renderDeleteGroup(path, ctx, placeholder) {
+    if (ctx.readonly) {
+        return null;
+    }
+    return (h("limel-icon-button", { class: "delete-group", icon: "trash", label: ctx.translate('webclient.delete-group', 'Delete this group'), disabled: ctx.disabled || !!placeholder, onClick: handleDelete(path, ctx) }));
+}
+function renderAddCondition(path, marker, ctx) {
+    var _a;
+    if (ctx.readonly) {
+        return null;
+    }
+    const offersChoice = !!((_a = ctx.addOptions) === null || _a === void 0 ? void 0 : _a.length);
+    const chip = (h("limel-chip", { slot: offersChoice ? 'trigger' : undefined, class: "add-condition", text: ctx.translate('webclient.condition', 'Condition'), disabled: ctx.disabled, icon: addIcon(ctx), onClick: offersChoice ? undefined : handleAddLeaf(path, ctx) }));
+    // A row of its own rather than a bare chip, so that the join between it
+    // and the condition before it is drawn by the same rule that joins any two
+    // rows: the button is where the next condition goes, and it reads as part
+    // of the sequence — "Won or 100000 or + Condition".
+    return (h("li", { class: "row", "data-marker": marker, key: `${pathKey(path)}.add` }, offersChoice ? (h("limel-menu", { class: "add-condition-menu", items: ctx.addOptions, openDirection: "bottom-start", onSelect: handleAddLeafPick(path, ctx) }, chip)) : (chip)));
+}
+function renderAddGroup(path, ctx) {
+    if (ctx.readonly) {
+        return null;
+    }
+    return (h("limel-chip", { class: "add-group", size: "small", text: ctx.translate('webclient.group', 'Group'), disabled: ctx.disabled, icon: addIcon(ctx, 'var(--group-rail-color)'), onClick: handleAddGroup(path, ctx) }));
+}
+const handleCombinator = (path, ctx) => (event) => {
+    var _a;
+    event.stopPropagation();
+    const combinator = (_a = event.detail) === null || _a === void 0 ? void 0 : _a.value;
+    if (combinator) {
+        ctx.onCombinator(path, combinator);
+    }
+};
+const handleAddLeaf = (path, ctx) => () => ctx.onAddLeaf(path);
+const handleAddLeafPick = (path, ctx) => (event) => {
+    event.stopPropagation();
+    ctx.onAddLeaf(path, event.detail);
+};
+const handleAddGroup = (path, ctx) => () => ctx.onAddGroup(path);