@mono-lit/helper 0.0.0-stage → 0.0.1

package/dist/src/components/filter/filter-types.d.ts

@@ -0,0 +1,253 @@
+import { MonoTableController } from '../table/mono-data-grid.js';
+import { MonoEventProps } from '../../composables/element-props.js';
+/** Value types a field can hold — drives which operators are offered. */
+export type MonoFilterDataType = 'string' | 'number' | 'date' | 'datetime' | 'boolean';
+/** One selectable field in the builder's field dropdown. */
+export interface MonoFilterField {
+    /** Data field. Dotted nav paths (`Job.Name`) are allowed. */
+    field: string;
+    /** Label shown in the dropdown. Defaults to `field`. */
+    caption?: string;
+    /** Defaults to `'string'`. */
+    dataType?: MonoFilterDataType;
+    /** Fixed choices for the value editor — renders a select instead of a text input. */
+    values?: Array<{
+        value: unknown;
+        label?: string;
+    }>;
+}
+/**
+ * Operator tokens. These are the OData-expressible set: six comparisons, the three
+ * string functions plus a negated `contains`, `in`, `between`, and the two null
+ * checks (`eq null` / `ne null`).
+ */
+export type MonoFilterOperator = 'eq' | 'ne' | 'gt' | 'ge' | 'lt' | 'le' | 'contains' | 'notcontains' | 'startswith' | 'endswith' | 'in' | 'between' | 'isblank' | 'isnotblank';
+/** Visual size of the builder's inner controls — maps to the same theme tokens
+ * (`--theme-control-height-<size>`, `--theme-control-font-<size>`,
+ * `--theme-radius-<size>`) `mono-input` / `mono-button` use, so a builder sized
+ * `xs` matches an `xs` field beside it. */
+export type MonoFilterSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+/** How members of a group combine. `notAnd`/`notOr` wrap the group in `not (…)`. */
+export type MonoFilterGroupOperator = 'and' | 'or' | 'notAnd' | 'notOr';
+/** A single condition row. */
+export interface MonoFilterRule {
+    kind: 'rule';
+    /** Stable id for keyed rendering and edit addressing. */
+    id: string;
+    field: string;
+    operator: MonoFilterOperator;
+    /** One value; `in` holds several; `between` holds exactly two. */
+    value: unknown;
+}
+/** A group of rules and/or nested groups. */
+export interface MonoFilterGroup {
+    kind: 'group';
+    id: string;
+    operator: MonoFilterGroupOperator;
+    children: MonoFilterNode[];
+}
+export type MonoFilterNode = MonoFilterRule | MonoFilterGroup;
+/** Which representation to read a filter back as. */
+export type MonoFilterOutput = 'array' | 'string';
+/**
+ * A devextreme filter expression: a `[field, op, value]` triple, a nested array of
+ * those joined by `'and'` / `'or'`, or `['!', expr]` for negation.
+ */
+export type MonoFilterExpression = unknown[] | null;
+/** Every user-facing string, so the UI can be localised without forking it. */
+export interface MonoFilterTexts {
+    matchPrefix?: string;
+    matchSuffix?: string;
+    addRule?: string;
+    addGroup?: string;
+    addNested?: string;
+    remove?: string;
+    apply?: string;
+    clear?: string;
+    valuePlaceholder?: string;
+    multiValuePlaceholder?: string;
+    emptyHint?: string;
+    and?: string;
+    or?: string;
+    notAnd?: string;
+    notOr?: string;
+    eq?: string;
+    ne?: string;
+    gt?: string;
+    ge?: string;
+    lt?: string;
+    le?: string;
+    contains?: string;
+    notcontains?: string;
+    startswith?: string;
+    endswith?: string;
+    in?: string;
+    between?: string;
+    isblank?: string;
+    isnotblank?: string;
+}
+/**
+ * Props for `<mono-filter-builder>`, declared centrally on the controller
+ * (`controlMonoFilterBuilder({ props })`) so the element is wired with just
+ * `:control-filter-builder.prop="filter"`. Read back via `filter.props()` and
+ * updated with `filter.setProps()`.
+ *
+ * Flat rather than keyed by element (the way `monoDataGrid({ props })` is) because
+ * this family has a single element — `props` IS that element's bag.
+ *
+ * The controller-binding keys are deliberately absent: they name the controller
+ * itself, so setting them *from* the controller would be circular.
+ */
+export interface MonoFilterProps {
+    /** Visual size of the inner controls (default `sm`). */
+    size?: MonoFilterSize;
+    /** Fixed builder width (CSS length or px number). */
+    width?: string | number;
+    /**
+     * Fixed builder height — when set, the rules scroll between the pinned
+     * Apply/Clear row and the Add rule/group row.
+     */
+    height?: string | number;
+    minWidth?: string | number;
+    'min-width'?: string | number;
+    maxWidth?: string | number;
+    'max-width'?: string | number;
+    minHeight?: string | number;
+    'min-height'?: string | number;
+    /** Caps the builder height so a long rule list scrolls instead of growing. */
+    maxHeight?: string | number;
+    'max-height'?: string | number;
+    /** Anything else the element accepts. */
+    [key: string]: unknown;
+}
+export interface MonoFilterBuilderOptions {
+    /**
+     * Selectable fields. The source of truth — when `dataGrid` is also given, these
+     * win and the grid only fills in fields not listed here.
+     */
+    fields?: MonoFilterField[];
+    /**
+     * Props for `<mono-filter-builder>`, declared here so the element needs no
+     * appearance bindings of its own. Read back with `props()`, changed with
+     * `setProps()`. Where both this and the template declare a key, the
+     * **controller wins** — same rule as `monoDataGrid({ props })`. The builder's
+     * events are accepted as `on<Event>` keys (`onChange`, `onApply`, …) and
+     * attached to the element as listeners.
+     */
+    props?: MonoFilterProps & MonoEventProps<FilterBuilderEvents>;
+    /**
+     * Derive the field list from a table's `props.th` (`field` + `caption`), so a
+     * table filter dialog needs no duplicate list.
+     */
+    dataGrid?: MonoTableController;
+    /**
+     * Starting filter. **Shape-flexible**: a devextreme array is normalised, an OData
+     * `$filter` string is parsed — decided by `typeof`, no extra flag. A string
+     * outside the builder's expressible subset warns once and yields an empty tree
+     * rather than a wrong filter.
+     */
+    filter?: MonoFilterExpression | string;
+    /** Localised labels; anything omitted falls back to the English default. */
+    texts?: MonoFilterTexts;
+    /** Render the Apply / Clear row above the rules. Default `true`. */
+    actions?: boolean;
+    /**
+     * Replace the built-in array→string serializer — e.g. hand it
+     * `dxFilterToString` from `@mono-lit/utility`. Must be synchronous.
+     */
+    toODataString?: (filter: MonoFilterExpression) => string;
+}
+/** Read options for {@link MonoFilterController.original} / `.changed`. */
+export interface MonoFilterReadOptions {
+    /** Output shape. Omit to get the shape the filter was originally given in. */
+    type?: MonoFilterOutput;
+}
+export interface MonoFilterController {
+    /** The live node tree the UI edits. */
+    readonly tree: MonoFilterGroup;
+    /** Fields offered in the field dropdown (explicit + any derived from `dataGrid`). */
+    readonly fields: MonoFilterField[];
+    /** Resolved labels, defaults merged with `texts`. */
+    readonly texts: Required<MonoFilterTexts>;
+    /** Whether the Apply / Clear row shows. */
+    readonly actions: boolean;
+    /**
+     * The central element props (`controlMonoFilterBuilder({ props })`).
+     *
+     * One object with a **stable identity, mutated in place** — same contract as
+     * `monoDataGrid`'s `table.props()` — so the element keeps seeing updates without
+     * being re-bound.
+     */
+    props(): MonoFilterProps;
+    /**
+     * Merge a patch into `props()` and notify, so the bound element re-applies at
+     * once. A merge, not a replace: keys you omit keep their current value.
+     */
+    setProps(patch: MonoFilterProps): void;
+    /** The filter as first supplied, unaffected by UI edits. */
+    original(options?: MonoFilterReadOptions): MonoFilterExpression | string;
+    /** The filter as currently edited in the UI. */
+    changed(options?: MonoFilterReadOptions): MonoFilterExpression | string;
+    /** Replace the whole filter (either shape) and re-render. */
+    setFilter(filter: MonoFilterExpression | string): void;
+    /** Restore the originally supplied filter. */
+    reset(): void;
+    /** Empty the builder. */
+    clear(): void;
+    addRule(groupId?: string): void;
+    addGroup(groupId?: string): void;
+    /** Turn a rule into a group containing it, i.e. nest one level deeper. */
+    nest(nodeId: string): void;
+    remove(nodeId: string): void;
+    updateRule(ruleId: string, patch: Partial<Omit<MonoFilterRule, 'kind' | 'id'>>): void;
+    setGroupOperator(groupId: string, operator: MonoFilterGroupOperator): void;
+    /** Subscribe to any change; returns an unsubscribe. */
+    subscribe(cb: () => void): () => void;
+    dispose(): void;
+}
+/**
+ * `<mono-filter-builder>` element props. `data-filter` is the controller (from
+ * `monoFilterBuilder()` or `table.filterBuilder`); `size` scales the inner
+ * controls; the width/height props size the builder (and, when slotted into a
+ * `mono-table-search` filter panel, the floating panel that hosts it).
+ */
+/**
+ * Detail carried by `change` / `apply`. The filter is given in every shape
+ * so a listener doesn't have to re-read the controller: `filter` is whichever shape
+ * was passed in, `array` the devextreme expression, `string` the OData `$filter`.
+ */
+export interface MonoFilterChangeEventDetail {
+    filter: MonoFilterExpression | string;
+    array: MonoFilterExpression | string;
+    string: MonoFilterExpression | string;
+}
+/** Detail carried by `clear` — the filter is emptied, so there is nothing to report. */
+export interface MonoFilterClearEventDetail {
+    filter: null;
+}
+export type MonoFilterChangeEvent = CustomEvent<MonoFilterChangeEventDetail>;
+export type MonoFilterApplyEvent = CustomEvent<MonoFilterChangeEventDetail>;
+export type MonoFilterClearEvent = CustomEvent<MonoFilterClearEventDetail>;
+/**
+ * Events emitted by `<mono-filter-builder>`. Each name is listed twice — kebab and
+ * camel — because `dispatchMonoEvent` emits both spellings.
+ */
+export interface FilterBuilderEvents {
+    change: MonoFilterChangeEvent;
+    apply: MonoFilterApplyEvent;
+    clear: MonoFilterClearEvent;
+    'mno-change': MonoFilterChangeEvent;
+    mnoChange: MonoFilterChangeEvent;
+    'mno-apply': MonoFilterApplyEvent;
+    mnoApply: MonoFilterApplyEvent;
+    'mno-clear': MonoFilterClearEvent;
+    mnoClear: MonoFilterClearEvent;
+}
+export interface MonoFilterBuilderProps extends MonoFilterProps {
+    /** The controller, bound with `:data-filter.prop` / `:dataFilter`. */
+    dataFilter?: MonoFilterController;
+    'data-filter'?: MonoFilterController;
+    /** Renamed — `:control-filter-builder` / `:controlFilterBuilder` alias `dataFilter`. */
+    controlFilterBuilder?: MonoFilterController;
+    'control-filter-builder'?: MonoFilterController;
+}

package/dist/src/components/filter/index.d.ts

@@ -0,0 +1,6 @@
+/// <reference path="../../../vue.d.ts" />
+export { MonoFilterBuilder } from './mono-filter-builder.js';
+export { monoFilterBuilder, controlMonoFilterBuilder } from './filter-builder.js';
+export { arrayToODataString, arrayToTree, odataStringToArray, treeToArray, } from './filter-odata.js';
+export { DEFAULT_TEXTS, OPERATOR_ARITY, operatorsFor } from './filter-operators.js';
+export type { MonoFilterBuilderOptions, MonoFilterBuilderProps, MonoFilterController, MonoFilterDataType, MonoFilterExpression, MonoFilterField, MonoFilterGroup, MonoFilterGroupOperator, MonoFilterNode, MonoFilterOperator, MonoFilterOutput, MonoFilterChangeEvent, MonoFilterApplyEvent, MonoFilterClearEvent, MonoFilterChangeEventDetail, MonoFilterClearEventDetail, FilterBuilderEvents, MonoFilterProps, MonoFilterReadOptions, MonoFilterRule, MonoFilterSize, MonoFilterTexts, } from './filter-types.js';

package/dist/src/components/filter/index.shadow.d.ts

@@ -0,0 +1,7 @@
+/// <reference path="../../../vue.d.ts" />
+export { MonoFilterBuilderShadow } from './mono-filter-builder.shadow.js';
+export { MonoFilterBuilderCore } from './filter-builder-core.js';
+export { monoFilterBuilder } from './filter-builder.js';
+export { arrayToODataString, arrayToTree, odataStringToArray, treeToArray, } from './filter-odata.js';
+export { DEFAULT_TEXTS, OPERATOR_ARITY, operatorsFor } from './filter-operators.js';
+export type { MonoFilterBuilderOptions, MonoFilterController, MonoFilterDataType, MonoFilterExpression, MonoFilterField, MonoFilterGroup, MonoFilterGroupOperator, MonoFilterNode, MonoFilterOperator, MonoFilterOutput, MonoFilterChangeEvent, MonoFilterApplyEvent, MonoFilterClearEvent, MonoFilterChangeEventDetail, MonoFilterClearEventDetail, FilterBuilderEvents, MonoFilterProps, MonoFilterReadOptions, MonoFilterRule, MonoFilterTexts, } from './filter-types.js';

package/dist/src/components/filter/mono-filter-builder.d.ts

@@ -0,0 +1,21 @@
+import { LitElement, TemplateResult } from 'lit';
+import { FilterIconName } from './filter-builder-core.js';
+declare const MonoFilterBuilder_base: import('../../composables/hybird-prop').Constructor<import('./filter-builder-core.js').MonoFilterBuilderCoreInterface> & typeof LitElement;
+/**
+ * Light-DOM `mono-filter-builder` (default build, `@mono-lit/helper/ui/filter`).
+ * Icons use the global UnoCSS `.mono-icon i-mdi-*`.
+ *
+ * It renders `mono-input`'s classes for its selects/inputs, and those rules ship in
+ * the same global `dist/ui/index.css` — so no extra stylesheet is needed here.
+ */
+export declare class MonoFilterBuilder extends MonoFilterBuilder_base {
+    static styles: import('lit').CSSResult[];
+    protected createRenderRoot(): HTMLElement;
+    protected renderIcon(name: FilterIconName): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'mono-filter-builder': MonoFilterBuilder;
+    }
+}
+export {};

package/dist/src/components/filter/mono-filter-builder.shadow.d.ts

@@ -0,0 +1,17 @@
+import { LitElement, TemplateResult } from 'lit';
+import { FilterIconName } from './filter-builder-core.js';
+declare const MonoFilterBuilderShadow_base: import('../../composables/hybird-prop').Constructor<import('./filter-builder-core.js').MonoFilterBuilderCoreInterface> & typeof LitElement;
+/**
+ * Shadow-DOM `mono-filter-builder` (SSR build, `@mono-lit/helper/ui/shadow/filter`).
+ * Registers the DISTINCT `mono-shadow-filter-builder` tag; the light element
+ * coexists.
+ *
+ * `filter.css` alone is enough: this component styles its own controls rather than
+ * borrowing `input.css`'s inner classes, so there is no second sheet to adopt.
+ */
+export declare class MonoFilterBuilderShadow extends MonoFilterBuilderShadow_base {
+    static styles: import('lit').CSSResult[];
+    protected renderIcon(name: FilterIconName): TemplateResult;
+    connectedCallback(): void;
+}
+export {};

package/dist/src/components/form/form-control-core.d.ts

@@ -0,0 +1,37 @@
+import { LitElement } from 'lit';
+import { Constructor } from '../../composables/hybird-prop';
+import { MonoVisibleType } from '../../composables/visibility';
+import { MonoFormController, MonoFormListEntry } from './form-types.js';
+/** Public surface added by the form-control mixin. */
+export declare class MonoFormControlCoreInterface {
+    dataForm?: MonoFormController;
+    keyForm?: string;
+    visible: boolean;
+    visibleType: MonoVisibleType;
+    protected _formOff?: () => void;
+    protected _syncFromForm(): void;
+    /** Publish resolved options onto `form.items()[key].list` — list controls only. */
+    protected _publishList(entries: MonoFormListEntry[]): void;
+}
+/**
+ * `MonoFormControlCore` — the element half of {@link monoForm}.
+ *
+ * Mirrors `table/table-controller-core.ts`: a `.prop`-bound controller
+ * (`attribute: false`), hybrid aliases so `:data-form` / `:dataForm` /
+ * `dataform` all land, and a subscribe lifecycle that re-syncs on notify. On top
+ * of that it does three things the table base doesn't need:
+ *
+ * 1. **Reports changes.** Listens to its own `mno-input` / `mno-change` and
+ *    pushes them into the controller with the matching timing (`live` /
+ *    `change`), which is what drives the rules.
+ * 2. **Applies state.** On every notify it writes the form's value, validation
+ *    and merged props onto itself — assigning ONLY when the value differs, so an
+ *    element updating itself can't feed back into another notify.
+ * 3. **Lets the form win.** The controller owns the value, so it overwrites a
+ *    local `:model-value`; `inputs[key].props` is merged last by the controller and so
+ *    beats both the `setProp()` method and anything the template set.
+ *
+ * SSR-safe: `dataForm` can't cross Declarative Shadow DOM, so on the server this
+ * is inert and the element renders its normal shell.
+ */
+export declare const MonoFormControlCore: <T extends Constructor<LitElement>>(superClass: T) => Constructor<MonoFormControlCoreInterface> & T;

package/dist/src/components/form/form-rules.d.ts

@@ -0,0 +1,25 @@
+import { MonoFormRule, MonoFormRuleCtx } from './form-types.js';
+/** Empty for validation purposes: null/undefined, blank string, empty array. */
+export declare function isBlank(value: unknown): boolean;
+/**
+ * Run a single rule. Returns `true` when it passes, or the failure message.
+ *
+ * A `schema` on the rule takes precedence over its `type`/`validate` — that's
+ * the documented override, so a rule can be declared as a built-in and later
+ * swapped to a schema without moving it.
+ */
+export declare function runRule<V>(rule: MonoFormRule<V>, ctx: MonoFormRuleCtx<V>): Promise<true | string>;
+/**
+ * Run a field's rules and return the FIRST failure (so one message shows at a
+ * time, matching how the components render a single `validation-message`).
+ *
+ * `timing` filters which rules apply: `undefined` runs them all (that's
+ * `form.validate()`), otherwise only rules whose effective timing matches.
+ */
+export declare function runRules<V>(rules: MonoFormRule<V>[] | undefined, ctx: MonoFormRuleCtx<V>, opts: {
+    timing?: 'live' | 'change';
+    defaultTiming: 'live' | 'change';
+}): Promise<{
+    success: boolean;
+    message: string;
+}>;