@limetech/lime-crm-building-blocks 2.0.3 → 2.1.0

package/dist/types/components/condition-tree/condition-tree.types.d.ts

@@ -0,0 +1,323 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+import { IconName, MenuItem } from '@limetech/lime-elements';
+import { ComponentDescriptor, LimeWebComponentContext, LimeWebComponentPlatform } from '@limetech/lime-web-components';
+/**
+ * How a group joins the conditions inside it.
+ *
+ * - `all` — every condition must hold (`AND`)
+ * - `any` — at least one condition must hold (`OR`)
+ * - `not-all` — at least one condition must fail (`NOT AND`)
+ * - `none` — every condition must fail (`NOT OR`)
+ *
+ * The last two are the negations of the first two. Consumers whose data model
+ * expresses negation as a wrapper (`NOT[AND[…]]`, `not(all(…))`) fold that
+ * wrapper into the combinator in `describe`, and unfold it again in `group`. A
+ * consumer that would rather not expose the negated forms to its users lists
+ * only the ones it wants via `combinators`.
+ *
+ * @public
+ */
+export type ConditionTreeCombinator = 'all' | 'any' | 'not-all' | 'none';
+/**
+ * How one condition reads when it is collapsed.
+ *
+ * This is the whole vocabulary the tree itself has for a condition: a name, a
+ * value, an icon, and whether something is wrong with it. It says nothing
+ * about what the condition *means* — that is the consumer's business, and a
+ * consumer whose chips need to say more replaces the chip through
+ * `component`.
+ *
+ * @public
+ */
+export interface ConditionTreeChip {
+    /**
+     * The name of what is being tested — typically a property name, but for an
+     * opaque condition simply its title (e.g. "User is an administrator").
+     *
+     * It also becomes the heading of the editor when the condition is opened.
+     */
+    label?: string;
+    /**
+     * The value(s) tested against.
+     */
+    value?: string | string[];
+    /**
+     * The glyph shown between the label and the value.
+     */
+    icon?: IconName;
+    /**
+     * Set to `true` to mark the condition as unresolvable or malformed.
+     */
+    invalid?: boolean;
+    /**
+     * A component to draw in place of the built-in chip, for a condition whose
+     * summary needs more than the four fields above can say.
+     *
+     * The tree knows nothing about filters, operators or data types, so a
+     * consumer that wants the full `limebb-filter-chip` summary — the glyph
+     * and wording derived from a condition and a property type — names that
+     * component here and passes the rest through `props`:
+     *
+     * ```ts
+     * component: {
+     *     name: 'limebb-filter-chip',
+     *     props: { condition: 'greater-than', propertyType: 'date' },
+     * }
+     * ```
+     *
+     * The four fields above are still forwarded, and the tree's own state
+     * always wins over `props`. See {@link ConditionChip} for the contract the
+     * component is held to.
+     */
+    component?: ComponentDescriptor;
+}
+/**
+ * What the tree should draw for one of the consumer's nodes that holds others.
+ *
+ * @public
+ */
+export interface ConditionTreeGroupDescription<T> {
+    kind: 'group';
+    /**
+     * How the conditions inside the group are joined.
+     */
+    combinator: ConditionTreeCombinator;
+    /**
+     * The consumer's own nodes inside this group, in display order. They are
+     * passed straight back to `describe` one level down, so they need no
+     * translating: a group hands over what it already holds.
+     */
+    children: T[];
+    /**
+     * Problems to show on the group, for example from a validation pass.
+     */
+    issues?: string[];
+}
+/**
+ * What the tree should draw for one of the consumer's nodes that is a single
+ * condition: a chip, and the editor that opens when it is clicked.
+ *
+ * @public
+ */
+export interface ConditionTreeLeafDescription {
+    kind: 'leaf';
+    /**
+     * How the condition reads when collapsed.
+     */
+    chip: ConditionTreeChip;
+    /**
+     * The component to mount in the condition's editor popover. It is created
+     * by tag name and receives `platform`, `context` and the condition itself
+     * as `value`, alongside the `props` given here, so a consumer can hand over
+     * any editor it likes — including one supplied by a third party — without
+     * the tree knowing what it edits. See {@link ConditionEditor} for the
+     * contract that editor is held to.
+     *
+     * A leaf without an editor is not clickable.
+     */
+    editor?: ComponentDescriptor;
+    /**
+     * Whether this condition is negated.
+     *
+     * Leave it `undefined` when the condition carries its own polarity — one
+     * that tests a property can say "is not between" in its own vocabulary of
+     * conditions, and a second, outer negation there would be both redundant
+     * and ambiguous. The tree then renders no negation control.
+     *
+     * Set it — to `false` as much as to `true` — for an opaque condition that
+     * is simply true or false, with nothing inside it able to express the
+     * opposite, so that wrapping it is the only negation available. The tree
+     * then offers the control, and rebuilds the condition through
+     * `ConditionTreeAdapter.negate` when it is used.
+     */
+    negated?: boolean;
+    /**
+     * Set to `true` to open this condition's editor as soon as it appears,
+     * for example because the user just added it and it has nothing in it yet.
+     *
+     * It is acted on once per condition, so there is no need to clear it
+     * afterwards: a condition the user has closed stays closed, and the next
+     * condition to carry the flag still opens.
+     */
+    autoOpen?: boolean;
+    /**
+     * Problems to show on the condition, for example from a validation pass.
+     */
+    issues?: string[];
+}
+/**
+ * What the tree should draw for one of the consumer's nodes: either a group of
+ * others, or a single condition.
+ *
+ * @public
+ */
+export type ConditionTreeDescription<T> = ConditionTreeGroupDescription<T> | ConditionTreeLeafDescription;
+/**
+ * What the tree knows about the user's dealings with one node, handed to
+ * `describe` so a consumer does not have to keep the tally itself.
+ *
+ * @public
+ */
+export interface ConditionTreeNodeState {
+    /**
+     * Whether the user has opened this condition's editor and closed it again.
+     *
+     * The tree is the only thing that knows this — it opens the editors — so
+     * it is the tree that remembers. A consumer uses it to tell a condition
+     * nobody has reached yet from one the user saw and left as it is: the
+     * first is not at fault for being empty, the second may well be.
+     *
+     * Always `false` for a group, which has no editor to open.
+     */
+    visited: boolean;
+}
+/**
+ * How `limebb-condition-tree` reads and rebuilds a consumer's own tree.
+ *
+ * The tree holds no model of its own. It is given the consumer's tree as-is,
+ * asks this adapter what each node should look like, and — when the user
+ * changes something — hands back a tree of the same kind with the change
+ * applied. Conditions travel by identity: the tree moves the very objects it
+ * was given, and only asks for groups to be rebuilt, because only a group's
+ * combinator and children can change.
+ *
+ * Build the adapter once and hold on to it. One built inside `render()` is a
+ * new object every time, which makes the tree re-render for no reason.
+ *
+ * @public
+ */
+export interface ConditionTreeAdapter<T> {
+    /**
+     * What the tree should draw for one of the consumer's nodes.
+     *
+     * This runs for every node on every render, so it must be pure and cheap.
+     * Work that is not — resolving a property name against a repository, say —
+     * belongs in the consumer's own state, resolved once and read from here.
+     *
+     * `state` is what the tree knows about the user's dealings with this node.
+     * Most consumers ignore it; one that marks a condition the user left
+     * unfinished reads `visited` from it, rather than keeping that tally
+     * itself.
+     * @param node
+     * @param state
+     */
+    describe(node: T, state: ConditionTreeNodeState): ConditionTreeDescription<T>;
+    /**
+     * A group of the consumer's own kind, joining `children` the way
+     * `combinator` says.
+     *
+     * The tree calls this for every group along the path from the edit up to
+     * the root, so a consumer whose model wraps negation (`NOT[AND[…]]`)
+     * unfolds `not-all` and `none` back into that wrapper here.
+     *
+     * `children` is empty in one case only: the user asked for a new group
+     * while `addOptions` is set, so the tree cannot know which kind of
+     * condition to put in it and leaves that to the user. A group emptied by
+     * an edit is dropped rather than rebuilt, so it never reaches here.
+     * @param combinator
+     * @param children
+     */
+    group(combinator: ConditionTreeCombinator, children: T[]): T;
+    /**
+     * A new condition, for the user to fill in.
+     *
+     * `item` is the kind the user picked from `addOptions`, and is absent when
+     * the tree was given no options to offer: the consumer is then free to
+     * decide what a new condition is — typically a blank one, left for its
+     * editor to fill in.
+     * @param item
+     */
+    createLeaf(item?: MenuItem): T;
+    /**
+     * The same condition, negated or not.
+     *
+     * Leave it out and the tree offers no negation control, whatever a leaf
+     * description says about `negated`.
+     * @param node
+     * @param negated
+     */
+    negate?(node: T, negated: boolean): T;
+}
+/**
+ * The contract an editor mounted by `limebb-condition-tree` is held to.
+ *
+ * The tree sets all five props on the component named by
+ * `ConditionTreeLeafDescription.editor`, and listens for one event.
+ *
+ * @public
+ */
+export interface ConditionEditor<T> {
+    /**
+     * Platform service provider.
+     */
+    platform: LimeWebComponentPlatform;
+    /**
+     * Component context.
+     */
+    context: LimeWebComponentContext;
+    /**
+     * The condition being edited, in the consumer's own model.
+     */
+    value: T;
+    /**
+     * @inheritdoc
+     */
+    readonly: boolean;
+    /**
+     * @inheritdoc
+     */
+    disabled: boolean;
+    /**
+     * Emitted with the replacement condition when the user changes something.
+     *
+     * Named `conditionChange` rather than `change` on purpose: every
+     * `limel-input-field`, `limel-picker` and `limel-select` inside an editor
+     * emits a bubbling, composed `change`, and the tree would catch all of
+     * them.
+     */
+    conditionChange: EventEmitter<T>;
+}
+/**
+ * The contract a chip mounted by `limebb-condition-tree` is held to.
+ *
+ * The tree sets these props on the component named by
+ * `ConditionTreeChip.component`, and listens for two events. Anything else the
+ * chip needs comes from the descriptor's `props`, which the tree passes
+ * through untouched — except where a name below collides, and then the tree
+ * wins: a chip that stayed on screen while the tree was locked must not be the
+ * one place the lock does not reach.
+ *
+ * `limebb-filter-chip` satisfies this contract, which is why it is what the
+ * tree draws when no component is named.
+ *
+ * @public
+ */
+export interface ConditionChip extends Omit<ConditionTreeChip, 'component'> {
+    /**
+     * Platform service provider.
+     */
+    platform: LimeWebComponentPlatform;
+    /**
+     * Whether this condition's editor is the one currently open.
+     */
+    selected: boolean;
+    /**
+     * @inheritdoc
+     */
+    readonly: boolean;
+    /**
+     * @inheritdoc
+     */
+    disabled: boolean;
+    /**
+     * Whether the chip offers a control that deletes the condition. It is
+     * `false` while the tree is read-only.
+     */
+    removable: boolean;
+    /**
+     * Emitted when the user asks for the condition to be deleted. Its payload
+     * is ignored: the tree already knows which condition the chip stands for.
+     */
+    remove: EventEmitter<unknown>;
+}
+//# sourceMappingURL=condition-tree.types.d.ts.map

package/dist/types/components/condition-tree/group-node-view.d.ts

@@ -0,0 +1,30 @@
+import { FunctionalComponent } from '../../stencil-public-runtime';
+import { ConditionTreeDescription, ConditionTreeGroupDescription } from './condition-tree.types';
+import { ConditionTreePath } from './condition-tree-nodes';
+import { ConditionTreeRenderContext } from './condition-tree-view-context';
+/**
+ * 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 declare const NodeView: FunctionalComponent<{
+    node: unknown;
+    description: ConditionTreeDescription<unknown>;
+    path: ConditionTreePath;
+    ctx: ConditionTreeRenderContext;
+}>;
+/**
+ * A box holding a combinator, the conditions joined by it, and the two buttons
+ * that grow it.
+ * @param props
+ */
+export declare const GroupView: FunctionalComponent<{
+    description: ConditionTreeGroupDescription<unknown>;
+    path: ConditionTreePath;
+    ctx: ConditionTreeRenderContext;
+    placeholder?: boolean;
+}>;
+//# sourceMappingURL=group-node-view.d.ts.map

package/dist/types/components/condition-tree/leaf-node-view.d.ts

@@ -0,0 +1,21 @@
+import { FunctionalComponent } from '../../stencil-public-runtime';
+import { ConditionTreeLeafDescription } from './condition-tree.types';
+import { ConditionTreePath } from './condition-tree-nodes';
+import { ConditionTreeRenderContext } from './condition-tree-view-context';
+/**
+ * What both halves of a condition need: the node itself, what to draw for it,
+ * where it sits, and the state and callbacks of the tree around it.
+ */
+interface LeafProps {
+    node: unknown;
+    description: ConditionTreeLeafDescription;
+    path: ConditionTreePath;
+    ctx: ConditionTreeRenderContext;
+}
+/**
+ * One condition: a chip that summarizes it, and the editor it opens.
+ * @param props
+ */
+export declare const LeafView: FunctionalComponent<LeafProps>;
+export {};
+//# sourceMappingURL=leaf-node-view.d.ts.map