@pilotiq/pilotiq 0.1.0

package/dist/filters/FormFilter.js

@@ -0,0 +1,180 @@
+import { Filter } from './Filter.js';
+import { resolveSchema } from '../schema/resolveSchema.js';
+export function parseFormFilterValue(value) {
+    if (!value)
+        return {};
+    try {
+        const parsed = JSON.parse(value);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Encode a `Record<string, unknown>` of form values as the canonical
+ * single-URL-key JSON payload. Empty / null / `''` entries are dropped
+ * so the URL doesn't bloat with no-op keys; the all-empty case returns
+ * `''` (caller should drop the URL key entirely rather than emitting `{}`).
+ */
+export function encodeFormFilterValue(values) {
+    const clean = {};
+    for (const [k, v] of Object.entries(values)) {
+        if (v === undefined || v === null || v === '')
+            continue;
+        if (Array.isArray(v) && v.length === 0)
+            continue;
+        clean[k] = v;
+    }
+    if (Object.keys(clean).length === 0)
+        return '';
+    return JSON.stringify(clean);
+}
+/**
+ * Multi-field filter with arbitrary form schema. The popover renders the
+ * declared fields verbatim (using the same SchemaRenderer field dispatch
+ * as a regular form), the values are JSON-encoded into a single URL key,
+ * and the user's `.handle((q, values) => …)` callback applies the values
+ * to the ORM query.
+ *
+ * Designed for cases where the existing typed kinds (Select / Boolean /
+ * Ternary / DateRange / MultiSelect) don't fit — e.g. a price filter that
+ * needs both `min` and `max`, or a search filter that combines a needle
+ * with a category dropdown.
+ *
+ * Inner fields are resolved at meta-build time with the same `RenderContext`
+ * that `resolveSchema` uses for the surrounding table, so dependent-options
+ * resolvers (e.g. user-aware role lookups) work the same as in a regular form.
+ *
+ * @example
+ *   FormFilter.make('amount')
+ *     .label('Price')
+ *     .form([
+ *       NumberField.make('min').label('Min'),
+ *       NumberField.make('max').label('Max'),
+ *     ])
+ *     .handle((q, { min, max }) => {
+ *       if (min !== undefined) q = q.where('price', '>=', Number(min))
+ *       if (max !== undefined) q = q.where('price', '<=', Number(max))
+ *       return q
+ *     })
+ *     .indicator(({ min, max }) => {
+ *       if (min !== undefined && max !== undefined) return `Price: ${min}–${max}`
+ *       if (min !== undefined) return `Price: ≥ ${min}`
+ *       if (max !== undefined) return `Price: ≤ ${max}`
+ *       return 'Price'
+ *     })
+ */
+export class FormFilter extends Filter {
+    _formSchema = [];
+    static make(name) {
+        const f = new FormFilter(name);
+        // Default no-op queryFn so modelDefaults' `if (customQuery)` short-
+        // circuits cleanly when the user hasn't called `.handle()` yet —
+        // otherwise the default `where(name, jsonString)` clause would fire
+        // with a JSON blob and most ORMs would NOT enjoy that.
+        f.query((q) => q);
+        return f;
+    }
+    /**
+     * Set the inner form schema. Any pilotiq Element is allowed — Field /
+     * Section / Grid / Group — though the filter popover is a small surface,
+     * so plain fields read best in v1.
+     */
+    form(elements) {
+        this._formSchema = elements;
+        return this;
+    }
+    /**
+     * Typed query callback. Receives the parsed form-values object
+     * (`Record<string, unknown>` keyed by inner-field name) plus the running
+     * ORM query. Wraps the inherited `Filter.query()` hook — when this is
+     * called, a `_queryFn` is installed that parses the URL value before
+     * delegating to `fn`.
+     */
+    handle(fn) {
+        this.query((q, value) => fn(q, parseFormFilterValue(value)));
+        return this;
+    }
+    /**
+     * Typed indicator override. Receives the parsed form-values object so
+     * users don't have to call `parseFormFilterValue` themselves. String
+     * arguments still work via the inherited `Filter.indicator(string)`.
+     */
+    formIndicator(fn) {
+        this.indicator((value) => fn(parseFormFilterValue(value), this));
+        return this;
+    }
+    getFormSchema() { return this._formSchema; }
+    getKind() { return 'form'; }
+    formatActiveValue(value) {
+        const parsed = parseFormFilterValue(value);
+        const entries = Object.entries(parsed).filter(([, v]) => v !== undefined && v !== null && v !== '');
+        if (entries.length === 0)
+            return '';
+        return entries.map(([k, v]) => `${k}: ${formatScalar(v)}`).join(', ');
+    }
+    /**
+     * Override so that a stored value of `'{}'` (legitimately parsed JSON
+     * with zero entries) doesn't paint an empty `"Label: "` pill. The base
+     * `getIndicator` only checks for raw empty-string / undefined.
+     */
+    getIndicator() {
+        const value = this.getValue();
+        if (value === undefined || value === '')
+            return undefined;
+        const parsed = parseFormFilterValue(value);
+        const hasAny = Object.values(parsed).some(v => v !== undefined && v !== null && v !== '');
+        if (!hasAny)
+            return undefined;
+        return super.getIndicator();
+    }
+    async toMeta(ctx) {
+        const base = this.buildBaseMeta();
+        const resolved = await resolveSchema(this._formSchema, ctx ?? {});
+        const parsed = parseFormFilterValue(this.getValue());
+        const hydrated = applyValuesToMeta(resolved, parsed);
+        return {
+            ...base,
+            formSchema: hydrated,
+            placeholder: this.getPlaceholder() ?? 'Filter',
+        };
+    }
+}
+/** Walk a resolved meta tree and stamp each Field's `defaultValue` from
+ *  the parsed URL values map. Recurses into containers via `children`. */
+function applyValuesToMeta(metas, values) {
+    return metas.map(m => applyToOne(m, values));
+}
+function applyToOne(meta, values) {
+    const next = { ...meta };
+    if (next.type === 'field') {
+        const f = next;
+        if (f.name in values) {
+            next.defaultValue = values[f.name];
+        }
+    }
+    const children = next.children;
+    if (Array.isArray(children)) {
+        next.children = applyValuesToMeta(children, values);
+    }
+    return next;
+}
+/** Friendly display for an arbitrary JSON-decoded value. Booleans / numbers
+ *  / strings stringify directly; arrays join with ", "; objects collapse to
+ *  `[object]` (rare — most form fields produce scalars). */
+function formatScalar(v) {
+    if (v === null || v === undefined)
+        return '';
+    if (Array.isArray(v))
+        return v.map(x => formatScalar(x)).join(', ');
+    if (typeof v === 'object')
+        return '[object]';
+    if (typeof v === 'boolean')
+        return v ? 'Yes' : 'No';
+    return String(v);
+}
+//# sourceMappingURL=FormFilter.js.map

package/dist/filters/FormFilter.js.map

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

package/dist/filters/MultiSelectFilter.d.ts

@@ -0,0 +1,41 @@
+import { Filter, type FilterKind, type FilterMeta } from './Filter.js';
+export interface MultiSelectFilterOption {
+    value: string;
+    label: string;
+}
+/**
+ * Parse a comma-separated multi-select URL value into its individual
+ * tokens. Empty / whitespace-only entries drop. Exposed as a public
+ * helper so callers writing a custom `Filter.query(fn)` can reuse the
+ * same encoding without re-implementing it.
+ */
+export declare function parseMultiSelectValue(value: string): string[];
+/**
+ * Encode a list of selected values into the canonical comma-separated
+ * URL value. The empty case returns `''` so the renderer can drop the
+ * URL key entirely rather than emitting a trailing `&name=`.
+ */
+export declare function encodeMultiSelectValue(values: ReadonlyArray<string>): string;
+/**
+ * Multi-value dropdown filter. Renders as a checkbox list inside the
+ * filter popover; the URL value is comma-separated (`?status=draft,published`).
+ * Default ORM clause is `where(name, 'IN', values)` — backends without
+ * SQL `IN` can swap in their own logic via `Filter.query(fn)`.
+ *
+ * @example
+ * MultiSelectFilter.make('status').options([
+ *   { value: 'draft',     label: 'Draft' },
+ *   { value: 'published', label: 'Published' },
+ *   { value: 'archived',  label: 'Archived' },
+ * ])
+ */
+export declare class MultiSelectFilter extends Filter {
+    private _options;
+    static make(name: string): MultiSelectFilter;
+    options(opts: MultiSelectFilterOption[]): this;
+    getOptions(): MultiSelectFilterOption[];
+    getKind(): FilterKind;
+    protected formatActiveValue(value: string): string;
+    toMeta(): FilterMeta;
+}
+//# sourceMappingURL=MultiSelectFilter.d.ts.map

package/dist/filters/MultiSelectFilter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MultiSelectFilter.d.ts","sourceRoot":"","sources":["../../src/filters/MultiSelectFilter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAGtE,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAG7D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAE5E;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAkB,SAAQ,MAAM;IAC3C,OAAO,CAAC,QAAQ,CAAgC;IAEhD,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB;IAU5C,OAAO,CAAC,IAAI,EAAE,uBAAuB,EAAE,GAAG,IAAI;IAK9C,UAAU,IAAI,uBAAuB,EAAE;IAE9B,OAAO,IAAI,UAAU;cAEX,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAOlD,MAAM,IAAI,UAAU;CAO9B"}

package/dist/filters/MultiSelectFilter.js

@@ -0,0 +1,67 @@
+import { Filter } from './Filter.js';
+/**
+ * Parse a comma-separated multi-select URL value into its individual
+ * tokens. Empty / whitespace-only entries drop. Exposed as a public
+ * helper so callers writing a custom `Filter.query(fn)` can reuse the
+ * same encoding without re-implementing it.
+ */
+export function parseMultiSelectValue(value) {
+    if (!value)
+        return [];
+    return value.split(',').map(s => s.trim()).filter(s => s !== '');
+}
+/**
+ * Encode a list of selected values into the canonical comma-separated
+ * URL value. The empty case returns `''` so the renderer can drop the
+ * URL key entirely rather than emitting a trailing `&name=`.
+ */
+export function encodeMultiSelectValue(values) {
+    return values.filter(v => v !== '').join(',');
+}
+/**
+ * Multi-value dropdown filter. Renders as a checkbox list inside the
+ * filter popover; the URL value is comma-separated (`?status=draft,published`).
+ * Default ORM clause is `where(name, 'IN', values)` — backends without
+ * SQL `IN` can swap in their own logic via `Filter.query(fn)`.
+ *
+ * @example
+ * MultiSelectFilter.make('status').options([
+ *   { value: 'draft',     label: 'Draft' },
+ *   { value: 'published', label: 'Published' },
+ *   { value: 'archived',  label: 'Archived' },
+ * ])
+ */
+export class MultiSelectFilter extends Filter {
+    _options = [];
+    static make(name) {
+        const f = new MultiSelectFilter(name);
+        f.query((q, value) => {
+            const values = parseMultiSelectValue(value);
+            if (values.length === 0)
+                return q;
+            return q.where(f.name, 'IN', values);
+        });
+        return f;
+    }
+    options(opts) {
+        this._options = opts;
+        return this;
+    }
+    getOptions() { return this._options; }
+    getKind() { return 'multiSelect'; }
+    formatActiveValue(value) {
+        const tokens = parseMultiSelectValue(value);
+        if (tokens.length === 0)
+            return value;
+        const labels = tokens.map(v => this._options.find(o => o.value === v)?.label ?? v);
+        return labels.join(', ');
+    }
+    toMeta() {
+        return {
+            ...this.buildBaseMeta(),
+            options: this._options,
+            placeholder: this.getPlaceholder() ?? 'Any',
+        };
+    }
+}
+//# sourceMappingURL=MultiSelectFilter.js.map

package/dist/filters/MultiSelectFilter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MultiSelectFilter.js","sourceRoot":"","sources":["../../src/filters/MultiSelectFilter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAoC,MAAM,aAAa,CAAA;AAQtE;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa;IACjD,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAA;IACrB,OAAO,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAA;AAClE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAA6B;IAClE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC/C,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,iBAAkB,SAAQ,MAAM;IACnC,QAAQ,GAA8B,EAAE,CAAA;IAEhD,MAAM,CAAC,IAAI,CAAC,IAAY;QACtB,MAAM,CAAC,GAAG,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAA;QACrC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAa,EAAE,KAAa,EAAE,EAAE;YACvC,MAAM,MAAM,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAA;YAC3C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,CAAC,CAAA;YACjC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAA;QACtC,CAAC,CAAC,CAAA;QACF,OAAO,CAAC,CAAA;IACV,CAAC;IAED,OAAO,CAAC,IAA+B;QACrC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAA;QACpB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,UAAU,KAAgC,OAAO,IAAI,CAAC,QAAQ,CAAA,CAAC,CAAC;IAEvD,OAAO,KAAiB,OAAO,aAAa,CAAA,CAAC,CAAC;IAEpC,iBAAiB,CAAC,KAAa;QAChD,MAAM,MAAM,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAA;QAC3C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAA;QACrC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC,CAAA;QAClF,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC1B,CAAC;IAEQ,MAAM;QACb,OAAO;YACL,GAAG,IAAI,CAAC,aAAa,EAAE;YACvB,OAAO,EAAM,IAAI,CAAC,QAAQ;YAC1B,WAAW,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,KAAK;SAC5C,CAAA;IACH,CAAC;CACF"}

package/dist/filters/QueryBuilderFilter.d.ts

@@ -0,0 +1,145 @@
+import { Filter, type FilterKind, type FilterMeta } from './Filter.js';
+import type { ModelQuery } from '../orm/modelDefaults.js';
+import { type Constraint, type ConstraintOperatorName } from './queryBuilder/Constraint.js';
+/**
+ * Wire shape of a single condition row in the QueryBuilder tree.
+ *
+ * - `constraint` — the `Constraint.name` to dispatch against
+ * - `operator`   — one of the constraint's advertised operator names
+ * - `value`      — operator-dependent payload (string / number / array)
+ *
+ * Rules whose `constraint` doesn't resolve at apply time are silently
+ * skipped — config drift (renaming a column) shouldn't 500 the page.
+ */
+export interface QueryBuilderRule {
+    constraint: string;
+    operator: ConstraintOperatorName;
+    value?: unknown;
+}
+/**
+ * Top-level (or nested) shape of the QueryBuilder URL value. Each node
+ * carries a connector (`'and' | 'or'`) and a list of child rules — every
+ * child is either a single condition (`QueryBuilderRule`) or another
+ * sub-tree, so groups can nest arbitrarily deep.
+ *
+ * v2 dispatches the tree through the rudder ORM's `whereGroup` /
+ * `orWhereGroup` callbacks so nested OR / nested AND compose without
+ * leaking conditions into surrounding `where` clauses (search / tab
+ * predicate / sibling filters). When the underlying query lacks
+ * `whereGroup` (custom test stubs, exotic adapters), `applyTreeToQuery`
+ * falls back to flat AND chaining for compatibility.
+ */
+export interface QueryBuilderTree {
+    operator: 'and' | 'or';
+    rules: QueryBuilderTreeChild[];
+}
+/** A child node in a tree — either a single rule or another sub-tree. */
+export type QueryBuilderTreeChild = QueryBuilderRule | QueryBuilderTree;
+/** Type predicate: is this node a sub-tree (vs. a leaf rule)? */
+export declare function isQueryBuilderTree(node: QueryBuilderTreeChild): node is QueryBuilderTree;
+/** Empty tree — used when the URL key is absent or unparseable. */
+export declare function emptyQueryBuilderTree(): QueryBuilderTree;
+/**
+ * Parse the URL-encoded JSON payload back into a tree. Empty string,
+ * non-object, or malformed payloads yield the empty tree (silently —
+ * never throws so a tampered URL can't 500 the list page).
+ *
+ * Recurses into nested groups; child nodes that are neither well-formed
+ * rules nor well-formed sub-trees are dropped silently.
+ */
+export declare function parseQueryBuilderValue(value: string | undefined): QueryBuilderTree;
+/**
+ * Encode a tree back into the canonical URL payload. Empty trees (zero
+ * meaningful descendants) yield `''` so the caller can drop the URL key
+ * entirely rather than emitting a stub envelope.
+ *
+ * Rules with no `value` AND a value-bearing operator are dropped on
+ * encode so the URL doesn't bloat with half-typed in-progress rows.
+ * Sub-trees that collapse to zero meaningful children are dropped too.
+ */
+export declare function encodeQueryBuilderValue(tree: QueryBuilderTree): string;
+/**
+ * Typed query callback — receives the parsed tree (vs the base
+ * `FilterQueryHandler`'s raw URL string). Override the default tree-walk
+ * via `QueryBuilderFilter.handle(fn)` when constraints can't model your
+ * query (e.g. cross-table joins).
+ */
+export type QueryBuilderQueryHandler = (query: ModelQuery, tree: QueryBuilderTree, filter: QueryBuilderFilter) => ModelQuery;
+/**
+ * Typed indicator-pill formatter — mirrors `FormFilter.formIndicator`.
+ * Default pill text is `"<Label>: N condition(s)"`.
+ */
+export type QueryBuilderIndicatorHandler = (tree: QueryBuilderTree, filter: QueryBuilderFilter) => string;
+/**
+ * Composable advanced-filter — Filament-style. Lets end users compose
+ * multiple constraint rules at runtime against any pre-declared column,
+ * without requiring a developer to add a per-column filter.
+ *
+ * v1 = single root operator (AND), flat rule list. URL value is a single
+ * JSON-encoded payload `?advanced={"operator":"and","rules":[…]}`. The
+ * default `query()` callback walks the tree depth-first and dispatches
+ * each rule through its `Constraint.apply()` — every clause AND's into
+ * the running query.
+ *
+ * @example
+ *   QueryBuilderFilter.make('advanced')
+ *     .label('Advanced')
+ *     .constraints([
+ *       TextConstraint.make('title'),
+ *       NumberConstraint.make('amount'),
+ *       SelectConstraint.make('status').options([
+ *         { value: 'draft',     label: 'Draft' },
+ *         { value: 'published', label: 'Published' },
+ *       ]),
+ *     ])
+ */
+export declare class QueryBuilderFilter extends Filter {
+    private _constraints;
+    static make(name: string): QueryBuilderFilter;
+    constraints(list: Constraint[]): this;
+    getConstraints(): Constraint[];
+    /**
+     * Override the default tree-walk. Receives the parsed tree (not the raw
+     * URL string) plus a back-reference to the filter so the handler can
+     * read `getConstraints()` if it wants to layer custom logic on top of
+     * the standard dispatch.
+     */
+    handle(fn: QueryBuilderQueryHandler): this;
+    /**
+     * Typed indicator override — receives the parsed tree (mirrors
+     * `FormFilter.formIndicator`).
+     */
+    treeIndicator(fn: QueryBuilderIndicatorHandler): this;
+    getKind(): FilterKind;
+    protected formatActiveValue(value: string): string;
+    /**
+     * Override so that a stored value of `'{"operator":"and","rules":[]}'`
+     * (legitimately parsed JSON with zero rules — including trees where every
+     * rule was dropped as empty) doesn't paint an empty `"Label: "` pill.
+     * The base `getIndicator` only checks for raw empty-string / undefined.
+     */
+    getIndicator(): string | undefined;
+    toMeta(): FilterMeta;
+}
+/**
+ * Walk a tree against an indexed constraint set and translate it into ORM
+ * `where` calls. v2 dispatches every sub-group through `whereGroup` /
+ * `orWhereGroup` so nested AND/OR composes without leaking into the query's
+ * surrounding `where` clauses (search / tab predicate / sibling filters).
+ *
+ * Falls back to flat AND chaining when the running query lacks
+ * `whereGroup` (custom test stubs or exotic adapters that haven't picked
+ * up the rudder ORM contract yet) — same behaviour as v1, but loses OR /
+ * nesting fidelity. Real rudder ORM queries always carry `whereGroup`.
+ *
+ * Exposed for tests + custom handlers that want the default behavior on
+ * top of their own pre-/post-processing.
+ */
+export declare function applyTreeToQuery(query: ModelQuery, tree: QueryBuilderTree, constraints: Constraint[]): ModelQuery;
+/**
+ * Recursive count of leaf rules in a tree — used by the indicator pill so
+ * "5 conditions" reflects all leaves regardless of how they're grouped.
+ * Exposed for tests + custom indicator formatters.
+ */
+export declare function countLeafRules(tree: QueryBuilderTree): number;
+//# sourceMappingURL=QueryBuilderFilter.d.ts.map

package/dist/filters/QueryBuilderFilter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryBuilderFilter.d.ts","sourceRoot":"","sources":["../../src/filters/QueryBuilderFilter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EACL,KAAK,UAAU,EACf,KAAK,sBAAsB,EAC5B,MAAM,8BAA8B,CAAA;AAErC;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAI,sBAAsB,CAAA;IAClC,KAAK,CAAC,EAAM,OAAO,CAAA;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,KAAK,GAAG,IAAI,CAAA;IACtB,KAAK,EAAK,qBAAqB,EAAE,CAAA;CAClC;AAED,yEAAyE;AACzE,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,GAAG,gBAAgB,CAAA;AAEvE,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,qBAAqB,GAAG,IAAI,IAAI,gBAAgB,CAIxF;AAED,mEAAmE;AACnE,wBAAgB,qBAAqB,IAAI,gBAAgB,CAExD;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,gBAAgB,CAQlF;AAkCD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAItE;AA8BD;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAAG,CACrC,KAAK,EAAE,UAAU,EACjB,IAAI,EAAG,gBAAgB,EACvB,MAAM,EAAE,kBAAkB,KACvB,UAAU,CAAA;AAEf;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG,CACzC,IAAI,EAAI,gBAAgB,EACxB,MAAM,EAAE,kBAAkB,KACvB,MAAM,CAAA;AAEX;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,kBAAmB,SAAQ,MAAM;IAC5C,OAAO,CAAC,YAAY,CAAmB;IAEvC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB;IAS7C,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,IAAI;IAKrC,cAAc,IAAI,UAAU,EAAE;IAE9B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,EAAE,wBAAwB,GAAG,IAAI;IAK1C;;;OAGG;IACH,aAAa,CAAC,EAAE,EAAE,4BAA4B,GAAG,IAAI;IAK5C,OAAO,IAAI,UAAU;cAEX,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAO3D;;;;;OAKG;IACM,YAAY,IAAI,MAAM,GAAG,SAAS;IAQlC,MAAM,IAAI,UAAU;CAQ9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAQ,UAAU,EACvB,IAAI,EAAS,gBAAgB,EAC7B,WAAW,EAAE,UAAU,EAAE,GACxB,UAAU,CAeZ;AAwFD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAM7D"}