@pilotiq/pilotiq 0.1.0

package/dist/filters/DateRangeFilter.d.ts

@@ -0,0 +1,68 @@
+import { Filter, type FilterKind, type FilterMeta } from './Filter.js';
+/**
+ * Parsed shape of a `DateRangeFilter`'s URL value. Either side may be
+ * absent; `{ from, to }` are kept as raw strings so callers can decide
+ * whether to coerce to `Date` or pass straight through to the ORM.
+ */
+export interface DateRangeValue {
+    from?: string;
+    to?: string;
+}
+/**
+ * Round-trip a `from..to`-encoded URL value to `{ from?, to? }`. Either
+ * side may be empty (`'2026-01-01..'` → `{ from: '2026-01-01' }`). The
+ * empty string and `'..'` both parse to `{}`.
+ *
+ * Exposed as a public helper so users writing a custom `Filter.query(fn)`
+ * can avoid re-parsing the encoding by hand.
+ */
+export declare function parseDateRangeValue(value: string): DateRangeValue;
+/**
+ * Encode a `{ from?, to? }` pair as the canonical `from..to` URL value.
+ * The empty / both-missing case returns `''` (caller should drop the
+ * URL key entirely rather than emitting `..`).
+ */
+export declare function encodeDateRangeValue(range: DateRangeValue): string;
+/**
+ * Pair-of-date-inputs filter. Encodes the URL value as `from..to`
+ * keyed off the filter name so the existing single-key `parseFilterValues`
+ * contract holds:
+ *
+ *   `?publishedAt=2026-01-01..2026-12-31`  closed range
+ *   `?publishedAt=2026-01-01..`            open-ended `>=` from
+ *   `?publishedAt=..2026-12-31`            open-ended `<=` to
+ *
+ * Default ORM clauses:
+ *
+ *   from + to → `where(name,'>=',from).where(name,'<=',to)`
+ *   from only → `where(name,'>=',from)`
+ *   to only   → `where(name,'<=',to)`
+ *
+ * `to` is treated as inclusive — for `DateTime` columns with
+ * `includesTime(false)`, callers wanting "all of 2026-12-31" should
+ * widen the upper bound via `Filter.query(fn)`.
+ *
+ * @example
+ * DateRangeFilter.make('publishedAt').label('Published')
+ * DateRangeFilter.make('createdAt').includesTime(true).maxDate(new Date())
+ */
+export declare class DateRangeFilter extends Filter {
+    private _includesTime;
+    private _minDate?;
+    private _maxDate?;
+    static make(name: string): DateRangeFilter;
+    /** Switch the inputs to `<input type="datetime-local">` and the URL
+     *  values to ISO timestamps. Default: `false`. */
+    includesTime(value?: boolean): this;
+    /** Lower bound for the input's `min` attribute. Accepts an ISO string or `Date`. */
+    minDate(value: string | Date): this;
+    /** Upper bound for the input's `max` attribute. Accepts an ISO string or `Date`. */
+    maxDate(value: string | Date): this;
+    getIncludesTime(): boolean;
+    getMinDate(): string | undefined;
+    getMaxDate(): string | undefined;
+    getKind(): FilterKind;
+    protected formatActiveValue(value: string): string;
+    toMeta(): FilterMeta;
+}
+//# sourceMappingURL=DateRangeFilter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DateRangeFilter.d.ts","sourceRoot":"","sources":["../../src/filters/DateRangeFilter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAGtE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,EAAE,CAAC,EAAI,MAAM,CAAA;CACd;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAejE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAKlE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,eAAgB,SAAQ,MAAM;IACzC,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,QAAQ,CAAC,CAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,CAAW;IAE5B,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe;IAY1C;sDACkD;IAClD,YAAY,CAAC,KAAK,UAAO,GAAG,IAAI;IAEhC,oFAAoF;IACpF,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAKnC,oFAAoF;IACpF,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAMnC,eAAe,IAAI,OAAO;IAC1B,UAAU,IAAQ,MAAM,GAAG,SAAS;IACpC,UAAU,IAAQ,MAAM,GAAG,SAAS;IAE3B,OAAO,IAAI,UAAU;cAEX,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAQlD,MAAM,IAAI,UAAU;CAS9B"}

package/dist/filters/DateRangeFilter.js

@@ -0,0 +1,137 @@
+import { Filter } from './Filter.js';
+/**
+ * Round-trip a `from..to`-encoded URL value to `{ from?, to? }`. Either
+ * side may be empty (`'2026-01-01..'` → `{ from: '2026-01-01' }`). The
+ * empty string and `'..'` both parse to `{}`.
+ *
+ * Exposed as a public helper so users writing a custom `Filter.query(fn)`
+ * can avoid re-parsing the encoding by hand.
+ */
+export function parseDateRangeValue(value) {
+    if (!value || value === '..')
+        return {};
+    const idx = value.indexOf('..');
+    if (idx === -1) {
+        // No separator — treat as a single "from" bound. Rare; users are
+        // more likely to pass the encoded form.
+        const from = value.trim();
+        return from ? { from } : {};
+    }
+    const from = value.slice(0, idx).trim();
+    const to = value.slice(idx + 2).trim();
+    const out = {};
+    if (from)
+        out.from = from;
+    if (to)
+        out.to = to;
+    return out;
+}
+/**
+ * Encode a `{ from?, to? }` pair as the canonical `from..to` URL value.
+ * The empty / both-missing case returns `''` (caller should drop the
+ * URL key entirely rather than emitting `..`).
+ */
+export function encodeDateRangeValue(range) {
+    const from = range.from?.trim() ?? '';
+    const to = range.to?.trim() ?? '';
+    if (!from && !to)
+        return '';
+    return `${from}..${to}`;
+}
+/**
+ * Pair-of-date-inputs filter. Encodes the URL value as `from..to`
+ * keyed off the filter name so the existing single-key `parseFilterValues`
+ * contract holds:
+ *
+ *   `?publishedAt=2026-01-01..2026-12-31`  closed range
+ *   `?publishedAt=2026-01-01..`            open-ended `>=` from
+ *   `?publishedAt=..2026-12-31`            open-ended `<=` to
+ *
+ * Default ORM clauses:
+ *
+ *   from + to → `where(name,'>=',from).where(name,'<=',to)`
+ *   from only → `where(name,'>=',from)`
+ *   to only   → `where(name,'<=',to)`
+ *
+ * `to` is treated as inclusive — for `DateTime` columns with
+ * `includesTime(false)`, callers wanting "all of 2026-12-31" should
+ * widen the upper bound via `Filter.query(fn)`.
+ *
+ * @example
+ * DateRangeFilter.make('publishedAt').label('Published')
+ * DateRangeFilter.make('createdAt').includesTime(true).maxDate(new Date())
+ */
+export class DateRangeFilter extends Filter {
+    _includesTime = false;
+    _minDate;
+    _maxDate;
+    static make(name) {
+        const f = new DateRangeFilter(name);
+        f.query((q, value) => {
+            const { from, to } = parseDateRangeValue(value);
+            let next = q;
+            if (from)
+                next = next.where(f.name, '>=', from);
+            if (to)
+                next = next.where(f.name, '<=', to);
+            return next;
+        });
+        return f;
+    }
+    /** Switch the inputs to `<input type="datetime-local">` and the URL
+     *  values to ISO timestamps. Default: `false`. */
+    includesTime(value = true) { this._includesTime = value; return this; }
+    /** Lower bound for the input's `min` attribute. Accepts an ISO string or `Date`. */
+    minDate(value) {
+        this._minDate = toBoundString(value, this._includesTime);
+        return this;
+    }
+    /** Upper bound for the input's `max` attribute. Accepts an ISO string or `Date`. */
+    maxDate(value) {
+        this._maxDate = toBoundString(value, this._includesTime);
+        return this;
+    }
+    // Getters used by tests + the renderer.
+    getIncludesTime() { return this._includesTime; }
+    getMinDate() { return this._minDate; }
+    getMaxDate() { return this._maxDate; }
+    getKind() { return 'dateRange'; }
+    formatActiveValue(value) {
+        const { from, to } = parseDateRangeValue(value);
+        if (from && to)
+            return `${from} → ${to}`;
+        if (from)
+            return `≥ ${from}`;
+        if (to)
+            return `≤ ${to}`;
+        return value;
+    }
+    toMeta() {
+        return {
+            ...this.buildBaseMeta(),
+            includesTime: this._includesTime,
+            ...(this._minDate !== undefined ? { minDate: this._minDate } : {}),
+            ...(this._maxDate !== undefined ? { maxDate: this._maxDate } : {}),
+            placeholder: this.getPlaceholder() ?? 'Any',
+        };
+    }
+}
+/** Coerce a `Date | string` bound to the canonical `YYYY-MM-DD` or
+ *  `YYYY-MM-DDTHH:mm` input-friendly string. Strings pass through
+ *  trimmed; the renderer's `min` / `max` attributes accept either. */
+function toBoundString(value, includesTime) {
+    if (typeof value === 'string')
+        return value.trim();
+    // Use the local-time split so `<input type="date">` doesn't shift the
+    // bound a day under negative-UTC-offset clients.
+    const yyyy = value.getFullYear().toString().padStart(4, '0');
+    const mm = (value.getMonth() + 1).toString().padStart(2, '0');
+    const dd = value.getDate().toString().padStart(2, '0');
+    const date = `${yyyy}-${mm}-${dd}`;
+    if (!includesTime)
+        return date;
+    const hh = value.getHours().toString().padStart(2, '0');
+    const min = value.getMinutes().toString().padStart(2, '0');
+    return `${date}T${hh}:${min}`;
+}
+//# sourceMappingURL=DateRangeFilter.js.map

package/dist/filters/DateRangeFilter.js.map

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

package/dist/filters/Filter.d.ts

@@ -0,0 +1,140 @@
+import { Element, type ElementMeta } from '../schema/Element.js';
+import type { ModelQuery } from '../orm/modelDefaults.js';
+import type { RenderContext } from '../schema/resolveSchema.js';
+/**
+ * Discriminator for the renderer to pick a control.
+ *
+ * - `'select'`      — single-value dropdown (`SelectFilter`, `TrashedFilter`).
+ * - `'multiSelect'` — checkbox list; URL value is comma-separated.
+ * - `'boolean'`     — three-state yes/no/any.
+ * - `'ternary'`     — three-state with a meaningful "blank" (NULL) bucket.
+ * - `'dateRange'`   — pair of date / datetime inputs encoded as `from..to`.
+ * - `'form'`        — arbitrary-schema multi-field popover; URL value is
+ *                     a JSON-encoded object keyed by inner-field name.
+ * - `'queryBuilder'` — composable rules with per-column constraints; URL
+ *                     value is a JSON-encoded `{ operator, rules }` tree.
+ *
+ * Extends naturally — future kinds may include `'numberRange'`.
+ */
+export type FilterKind = 'select' | 'multiSelect' | 'boolean' | 'ternary' | 'dateRange' | 'form' | 'queryBuilder';
+export interface FilterMeta extends ElementMeta {
+    type: 'filter';
+    name: string;
+    label: string;
+    kind: FilterKind;
+    /** Currently-selected value, mirrored from the URL query at render time. */
+    value?: string;
+    /** Placeholder shown when no value is selected (e.g. "All", "Any"). */
+    placeholder?: string;
+    /** Options for `kind === 'select' | 'multiSelect' | 'ternary'`. Boolean uses fixed yes/no. */
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** `kind === 'dateRange'` — true switches the inputs to `datetime-local`. */
+    includesTime?: boolean;
+    /** `kind === 'dateRange'` — clamp the inputs' `min` attribute. */
+    minDate?: string;
+    /** `kind === 'dateRange'` — clamp the inputs' `max` attribute. */
+    maxDate?: string;
+    /**
+     * `kind === 'form'` — resolved schema for the popover sub-form. Each
+     * field's `defaultValue` is pre-hydrated from the active URL value so
+     * the inputs round-trip across navigations.
+     */
+    formSchema?: ElementMeta[];
+    /**
+     * `kind === 'queryBuilder'` — declared constraints (one per queryable
+     * column) the user can pick from when adding a rule. Wire shape comes
+     * from `Constraint.toMeta()`.
+     */
+    constraints?: Array<Record<string, unknown>>;
+    /**
+     * Active-filter indicator pill text. Present only when the filter has an
+     * active value. Default format is `"<label>: <displayValue>"`; users can
+     * override via `Filter.indicator(string | (value, filter) => string)`.
+     */
+    indicator?: string;
+}
+/**
+ * User-supplied query customizer. Receives the active filter value plus
+ * the running ORM query and returns the modified query. When supplied,
+ * `Filter.query(fn)` overrides the default `where(name, value)` clause.
+ */
+export type FilterQueryHandler = (query: ModelQuery, value: string) => ModelQuery;
+/**
+ * User-supplied indicator-pill formatter. Receives the active value plus
+ * the filter so callbacks can read its label / option set. The default
+ * indicator is `"<label>: <displayValue>"` where `displayValue` comes from
+ * each subclass's `formatActiveValue` hook.
+ */
+export type FilterIndicatorHandler = (value: string, filter: Filter) => string;
+/**
+ * Base class for table filters. Filters live as children of `Table` and
+ * surface as form controls in the table's header bar. Their values are
+ * carried through the URL query (`?status=published&featured=1`) and
+ * applied to the underlying ORM query for `Table.records`.
+ */
+export declare abstract class Filter extends Element {
+    readonly name: string;
+    protected _label?: string;
+    protected _value?: string;
+    protected _queryFn?: FilterQueryHandler;
+    protected _placeholder?: string;
+    protected _indicatorFn?: FilterIndicatorHandler;
+    protected constructor(name: string);
+    label(l: string): this;
+    /** Override the placeholder shown when no value is selected. */
+    placeholder(p: string): this;
+    /**
+     * Override the default `where(name, value)` clause this filter
+     * contributes to the ORM query. Receives the current `ModelQuery` plus
+     * the active value and must return the modified query.
+     */
+    query(fn: FilterQueryHandler): this;
+    /**
+     * Override the active-filter indicator pill text. Accepts either a
+     * literal string or a `(value, filter) => string` callback. The default
+     * indicator is `"<label>: <displayValue>"`, where `<displayValue>` comes
+     * from each subclass's `formatActiveValue(value)` hook (e.g. SelectFilter
+     * maps `'draft'` → its option label `'Draft'`).
+     */
+    indicator(fn: string | FilterIndicatorHandler): this;
+    /** Render-time setter: framework calls this with the URL-supplied value. */
+    withValue(v: string): this;
+    getLabel(): string;
+    getValue(): string | undefined;
+    getPlaceholder(): string | undefined;
+    getQuery(): FilterQueryHandler | undefined;
+    abstract getKind(): FilterKind;
+    /**
+     * Subclass hook — render the active value as a human-readable string for
+     * the indicator pill. Default is the raw value; SelectFilter/TernaryFilter
+     * map to option labels, BooleanFilter to "Yes"/"No", DateRangeFilter to a
+     * `from → to` range. Override when the URL value isn't user-friendly.
+     */
+    protected formatActiveValue(value: string): string;
+    /**
+     * Render the indicator pill text. Returns `undefined` when no value is
+     * active so the renderer can skip the pill entirely. Honours the user's
+     * `indicator(fn)` override when supplied.
+     */
+    getIndicator(): string | undefined;
+    getType(): string;
+    /**
+     * Sync by default — `kind: 'form'` filters override to async because they
+     * need to resolve their inner schema. The optional `_ctx` parameter is
+     * threaded by `resolveSchema` so subclasses can read the active user /
+     * record / values when building their meta. Existing typed filters
+     * (Select / Boolean / Ternary / DateRange / MultiSelect / Trashed)
+     * ignore the parameter.
+     */
+    toMeta(_ctx?: RenderContext): FilterMeta | Promise<FilterMeta>;
+    /**
+     * Shared meta construction for `Filter` subclasses — exposed as a
+     * protected helper so async subclasses (e.g. `FormFilter`) can pull
+     * the same shape without spreading a `Promise<FilterMeta>` union.
+     */
+    protected buildBaseMeta(): FilterMeta;
+}
+//# sourceMappingURL=Filter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Filter.d.ts","sourceRoot":"","sources":["../../src/filters/Filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAE/D;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,GAAG,cAAc,CAAA;AAEjH,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,IAAI,EAAS,QAAQ,CAAA;IACrB,IAAI,EAAS,MAAM,CAAA;IACnB,KAAK,EAAQ,MAAM,CAAA;IACnB,IAAI,EAAS,UAAU,CAAA;IACvB,4EAA4E;IAC5E,KAAK,CAAC,EAAO,MAAM,CAAA;IACnB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8FAA8F;IAC9F,OAAO,CAAC,EAAK,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACpD,6EAA6E;IAC7E,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,kEAAkE;IAClE,OAAO,CAAC,EAAK,MAAM,CAAA;IACnB,kEAAkE;IAClE,OAAO,CAAC,EAAK,MAAM,CAAA;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,WAAW,EAAE,CAAA;IAC1B;;;;OAIG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAC5C;;;;OAIG;IACH,SAAS,CAAC,EAAG,MAAM,CAAA;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,KAAK,UAAU,CAAA;AAEjF;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,CAAA;AAE9E;;;;;GAKG;AACH,8BAAsB,MAAO,SAAQ,OAAO;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACzB,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACzB,SAAS,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IACvC,SAAS,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC/B,SAAS,CAAC,YAAY,CAAC,EAAE,sBAAsB,CAAA;IAE/C,SAAS,aAAa,IAAI,EAAE,MAAM;IAKlC,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAEtB,gEAAgE;IAChE,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAE5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,EAAE,kBAAkB,GAAG,IAAI;IAEnC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,sBAAsB,GAAG,IAAI;IAKpD,4EAA4E;IAC5E,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAI1B,QAAQ,IAAI,MAAM;IAGlB,QAAQ,IAAI,MAAM,GAAG,SAAS;IAC9B,cAAc,IAAI,MAAM,GAAG,SAAS;IACpC,QAAQ,IAAI,kBAAkB,GAAG,SAAS;IAE1C,QAAQ,CAAC,OAAO,IAAI,UAAU;IAE9B;;;;;OAKG;IACH,SAAS,CAAC,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAElD;;;;OAIG;IACH,YAAY,IAAI,MAAM,GAAG,SAAS;IASlC,OAAO,IAAI,MAAM;IAEjB;;;;;;;OAOG;IACM,MAAM,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAIvE;;;;OAIG;IACH,SAAS,CAAC,aAAa,IAAI,UAAU;CAYtC"}

package/dist/filters/Filter.js

@@ -0,0 +1,99 @@
+import { Element } from '../schema/Element.js';
+/**
+ * Base class for table filters. Filters live as children of `Table` and
+ * surface as form controls in the table's header bar. Their values are
+ * carried through the URL query (`?status=published&featured=1`) and
+ * applied to the underlying ORM query for `Table.records`.
+ */
+export class Filter extends Element {
+    name;
+    _label;
+    _value;
+    _queryFn;
+    _placeholder;
+    _indicatorFn;
+    constructor(name) {
+        super();
+        this.name = name;
+    }
+    label(l) { this._label = l; return this; }
+    /** Override the placeholder shown when no value is selected. */
+    placeholder(p) { this._placeholder = p; return this; }
+    /**
+     * Override the default `where(name, value)` clause this filter
+     * contributes to the ORM query. Receives the current `ModelQuery` plus
+     * the active value and must return the modified query.
+     */
+    query(fn) { this._queryFn = fn; return this; }
+    /**
+     * Override the active-filter indicator pill text. Accepts either a
+     * literal string or a `(value, filter) => string` callback. The default
+     * indicator is `"<label>: <displayValue>"`, where `<displayValue>` comes
+     * from each subclass's `formatActiveValue(value)` hook (e.g. SelectFilter
+     * maps `'draft'` → its option label `'Draft'`).
+     */
+    indicator(fn) {
+        this._indicatorFn = typeof fn === 'function' ? fn : () => fn;
+        return this;
+    }
+    /** Render-time setter: framework calls this with the URL-supplied value. */
+    withValue(v) { this._value = v; return this; }
+    // ─── Getters ──────────────────────────────────────────
+    getLabel() {
+        return this._label ?? this.name.charAt(0).toUpperCase() + this.name.slice(1);
+    }
+    getValue() { return this._value; }
+    getPlaceholder() { return this._placeholder; }
+    getQuery() { return this._queryFn; }
+    /**
+     * Subclass hook — render the active value as a human-readable string for
+     * the indicator pill. Default is the raw value; SelectFilter/TernaryFilter
+     * map to option labels, BooleanFilter to "Yes"/"No", DateRangeFilter to a
+     * `from → to` range. Override when the URL value isn't user-friendly.
+     */
+    formatActiveValue(value) { return value; }
+    /**
+     * Render the indicator pill text. Returns `undefined` when no value is
+     * active so the renderer can skip the pill entirely. Honours the user's
+     * `indicator(fn)` override when supplied.
+     */
+    getIndicator() {
+        const value = this._value;
+        if (value === undefined || value === '')
+            return undefined;
+        if (this._indicatorFn)
+            return this._indicatorFn(value, this);
+        return `${this.getLabel()}: ${this.formatActiveValue(value)}`;
+    }
+    // ─── Element contract ────────────────────────────────
+    getType() { return 'filter'; }
+    /**
+     * Sync by default — `kind: 'form'` filters override to async because they
+     * need to resolve their inner schema. The optional `_ctx` parameter is
+     * threaded by `resolveSchema` so subclasses can read the active user /
+     * record / values when building their meta. Existing typed filters
+     * (Select / Boolean / Ternary / DateRange / MultiSelect / Trashed)
+     * ignore the parameter.
+     */
+    toMeta(_ctx) {
+        return this.buildBaseMeta();
+    }
+    /**
+     * Shared meta construction for `Filter` subclasses — exposed as a
+     * protected helper so async subclasses (e.g. `FormFilter`) can pull
+     * the same shape without spreading a `Promise<FilterMeta>` union.
+     */
+    buildBaseMeta() {
+        const indicator = this.getIndicator();
+        return {
+            type: 'filter',
+            name: this.name,
+            label: this.getLabel(),
+            kind: this.getKind(),
+            ...(this._value !== undefined ? { value: this._value } : {}),
+            ...(this._placeholder !== undefined ? { placeholder: this._placeholder } : {}),
+            ...(indicator !== undefined ? { indicator } : {}),
+        };
+    }
+}
+//# sourceMappingURL=Filter.js.map

package/dist/filters/Filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Filter.js","sourceRoot":"","sources":["../../src/filters/Filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAoB,MAAM,sBAAsB,CAAA;AAyEhE;;;;;GAKG;AACH,MAAM,OAAgB,MAAO,SAAQ,OAAO;IACjC,IAAI,CAAQ;IACX,MAAM,CAAS;IACf,MAAM,CAAS;IACf,QAAQ,CAAqB;IAC7B,YAAY,CAAS;IACrB,YAAY,CAAyB;IAE/C,YAAsB,IAAY;QAChC,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAED,KAAK,CAAC,CAAS,IAAU,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,OAAO,IAAI,CAAA,CAAC,CAAC;IAEvD,gEAAgE;IAChE,WAAW,CAAC,CAAS,IAAU,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,OAAO,IAAI,CAAA,CAAC,CAAC;IAEnE;;;;OAIG;IACH,KAAK,CAAC,EAAsB,IAAU,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC,CAAC,OAAO,IAAI,CAAA,CAAC,CAAC;IAEvE;;;;;;OAMG;IACH,SAAS,CAAC,EAAmC;QAC3C,IAAI,CAAC,YAAY,GAAG,OAAO,EAAE,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,CAAA;QAC5D,OAAO,IAAI,CAAA;IACb,CAAC;IAED,4EAA4E;IAC5E,SAAS,CAAC,CAAS,IAAU,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,OAAO,IAAI,CAAA,CAAC,CAAC;IAE3D,yDAAyD;IAEzD,QAAQ;QACN,OAAO,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IAC9E,CAAC;IACD,QAAQ,KAAoC,OAAO,IAAI,CAAC,MAAM,CAAA,CAAC,CAAC;IAChE,cAAc,KAA8B,OAAO,IAAI,CAAC,YAAY,CAAA,CAAC,CAAC;IACtE,QAAQ,KAAqC,OAAO,IAAI,CAAC,QAAQ,CAAA,CAAC,CAAC;IAInE;;;;;OAKG;IACO,iBAAiB,CAAC,KAAa,IAAY,OAAO,KAAK,CAAA,CAAC,CAAC;IAEnE;;;;OAIG;IACH,YAAY;QACV,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAA;QACzB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE;YAAE,OAAO,SAAS,CAAA;QACzD,IAAI,IAAI,CAAC,YAAY;YAAE,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;QAC5D,OAAO,GAAG,IAAI,CAAC,QAAQ,EAAE,KAAK,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAA;IAC/D,CAAC;IAED,wDAAwD;IAExD,OAAO,KAAa,OAAO,QAAQ,CAAA,CAAC,CAAC;IAErC;;;;;;;OAOG;IACM,MAAM,CAAC,IAAoB;QAClC,OAAO,IAAI,CAAC,aAAa,EAAE,CAAA;IAC7B,CAAC;IAED;;;;OAIG;IACO,aAAa;QACrB,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,EAAE,CAAA;QACrC,OAAO;YACL,IAAI,EAAG,QAAQ;YACf,IAAI,EAAG,IAAI,CAAC,IAAI;YAChB,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE;YACtB,IAAI,EAAG,IAAI,CAAC,OAAO,EAAE;YACrB,GAAG,CAAC,IAAI,CAAC,MAAM,KAAW,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAQ,IAAI,CAAC,MAAM,EAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9E,GAAG,CAAC,IAAI,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9E,GAAG,CAAC,SAAS,KAAa,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAuB,CAAC,CAAC,CAAC,EAAE,CAAC;SAC/E,CAAA;IACH,CAAC;CACF"}

package/dist/filters/FormFilter.d.ts

@@ -0,0 +1,103 @@
+import { Filter, type FilterKind, type FilterMeta } from './Filter.js';
+import type { Element } from '../schema/Element.js';
+import type { ModelQuery } from '../orm/modelDefaults.js';
+import { type RenderContext } from '../schema/resolveSchema.js';
+/**
+ * Parsed shape of a `FormFilter`'s URL value. JSON-encoded under a single
+ * URL key (`?amount={"min":100,"max":500}`). Empty / unparseable / non-
+ * object payloads round-trip as `{}`.
+ *
+ * Exposed as a public helper so users writing a custom `Filter.query(fn)`
+ * (or building their own server-side dispatch) can avoid re-parsing the
+ * encoding by hand.
+ */
+export type FormFilterValue = Record<string, unknown>;
+export declare function parseFormFilterValue(value: string | undefined): FormFilterValue;
+/**
+ * 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 declare function encodeFormFilterValue(values: FormFilterValue): string;
+/**
+ * User-supplied query callback for `FormFilter` — the parsed form values
+ * arrive as a `Record<string, unknown>` keyed by inner-field name (versus
+ * the base `FilterQueryHandler`, which sees the raw URL string).
+ */
+export type FormFilterQueryHandler = (query: ModelQuery, values: FormFilterValue) => ModelQuery;
+/**
+ * User-supplied indicator-pill formatter for `FormFilter`. Mirrors the
+ * base `FilterIndicatorHandler` but pre-parses the URL value.
+ */
+export type FormFilterIndicatorHandler = (values: FormFilterValue, filter: FormFilter) => string;
+/**
+ * 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 declare class FormFilter extends Filter {
+    private _formSchema;
+    static make(name: string): FormFilter;
+    /**
+     * 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: Element[]): 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: FormFilterQueryHandler): 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: FormFilterIndicatorHandler): this;
+    getFormSchema(): Element[];
+    getKind(): FilterKind;
+    protected formatActiveValue(value: string): string;
+    /**
+     * 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(): string | undefined;
+    toMeta(ctx?: RenderContext): Promise<FilterMeta>;
+}
+//# sourceMappingURL=FormFilter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FormFilter.d.ts","sourceRoot":"","sources":["../../src/filters/FormFilter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AACtE,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,sBAAsB,CAAA;AAEhE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAE9E;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAErD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,CAW/E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CASrE;AAED;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,CACnC,KAAK,EAAG,UAAU,EAClB,MAAM,EAAE,eAAe,KACpB,UAAU,CAAA;AAEf;;;GAGG;AACH,MAAM,MAAM,0BAA0B,GAAG,CACvC,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,UAAU,KACf,MAAM,CAAA;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,UAAW,SAAQ,MAAM;IACpC,OAAO,CAAC,WAAW,CAAgB;IAEnC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU;IAUrC;;;;OAIG;IACH,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI;IAK/B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,EAAE,sBAAsB,GAAG,IAAI;IAKxC;;;;OAIG;IACH,aAAa,CAAC,EAAE,EAAE,0BAA0B,GAAG,IAAI;IAKnD,aAAa,IAAI,OAAO,EAAE;IAEjB,OAAO,IAAI,UAAU;cAEX,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAO3D;;;;OAIG;IACM,YAAY,IAAI,MAAM,GAAG,SAAS;IAS5B,MAAM,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC;CAWhE"}