@zeyos/zx 4.0.0 → 4.1.0

package/docs/llms.txt

@@ -22,30 +22,32 @@ exports and as `window.zx.*`.
 
 ## Components
 - Inputs and identity: `button()`, `buttonGroup()`, `badge()`/`badgeGroup()`, `CheckButton`,
-  `Toggle`, `Search`, `Launcher`, `Avatar`, `AccountMenu`, `Select` (APG combobox;
-  `filter: false|'local'|async`; priority, status, permission, and optional ZeyOS entity presets),
-  `Checklist`, `TagPicker`, `NumberField`, `Rating`, `Slider`,
+  `Toggle`, `Search`, `AppIcon` (+ `zeyosAppIcon()` presets), `Avatar`,
+  `Select` (APG combobox; `filter: false|'local'|async`; priority, status, permission, and
+  `Select.entity()` presets), `Checklist`, `TagPicker` (icon/color identity), `NumberField`, `Rating`, `Slider`,
   `copyButton()`/`CopyInput`, `DatePicker`, `MonthPicker`, `TimePicker`,
   `Datebox`/`DateTimeBox`, `DateRangePicker`/`DateRangeBox`, `Timebox`.
 - Overlays: `Message` (toasts/inline/progress), `Modal`, `Dialog` (+ `alert`/`confirm`/`prompt` Promises), `Sheet` (edge-anchored Dialog; `side`, `modal: true|'trap-focus'|false`, `backdrop`, `snap` detents, swipe-to-dismiss), `SheetStack` (drill-down; `stack`/`cascade`), `Dropdown`, `MenuButton`, `ContextMenu` (right-click; `selector` for per-row menus), `Tooltip`/`tooltip()`/`describe()`.
-- Data: `Table` (sortable, selectable, sticky header, opt-in inline cell/row editing via
-  `editMode`), `Grid` with `Grid.BillingItems()`, engine-neutral `Chart` with injected
-  `ChartJsAdapter`, `DataFilter`, `Pagination` (+ pure `paginationRange()`), `TreeView` (APG tree),
+- Data: `Table` (sortable, selectable, sticky header, opt-in inline cell/row editing, row reorder,
+  column visibility), `Grid` with single-click editing and `Grid.BillingItems()`, engine-neutral
+  `Chart` with injected `ChartJsAdapter`, backend-neutral nested `Filter`, simple client-side
+  `DataFilter`, `Pagination` (+ pure `paginationRange()`), `TreeView` (APG tree),
   `Finder` (Miller columns).
 - Forms: `Form`, `Fieldset`, `Questionnaire` (guided one-question-at-a-time flow with branching), `Field` (type registry), `ValueList`, `MultiValueEditor`, `FieldUpload`.
 - Layout: `stack()`/`grid()`/`aspect()` (spacing, an intrinsically reflowing grid, a fixed-ratio
   box), `Groupbox`, `Card` (media/title link/actions/footer), `Panel` (header/footer action
   buttons), `MasterPanel`, `Tabbox`
   (`variant: 'divided'|'bracket'|'line'|'segmented'`), `NavigationBar`, `AppSidebar` (expanded and
-  minimized vertical states plus horizontal rail layouts), `Toolbar` (APG toolbar with overflow menu), `SplitView`, `Dock`
+  minimized vertical states plus horizontal rail layouts), `AccountMenu`, `Launcher`,
+  `spinner()`/`ProgressBar`/`InlineLoading`, `skeleton()`/`skeletonText()`/`skeletonTable()`,
+  `Toolbar` (APG toolbar with overflow menu), `SplitView`, `Dock`
   (collapsible resizable pane stack; tab groups, regions, adopts a `Sheet`), `Stepper`,
   `Breadcrumb`, `emptyState()`.
-- Feedback: `spinner()` (unknown duration), `ProgressBar` (known share; determinate or indeterminate), `InlineLoading` (a wait resolving into its outcome in place), `skeleton()`/`skeletonText()`/`skeletonTable()` (placeholders shaped like the content; `aria-hidden`, set `aria-busy` on the region).
 - Core: `Component`, `h`/`__`/`icon`, `position`, `breakpoints`/`breakpointOf`/`matchBreakpoint`/`onBreakpoint` (named width bands, observed on an element or the window), `Http`/`zeyosService`, i18n, date utils, `defineElements` (declarative `<zx-*>` custom elements).
 - Helpers: `formatNumber`/`formatCurrency`/`formatPercent`/`formatFileSize`/`formatRelativeTime` (locale-aware, cached `Intl`), `debounce`/`throttle`, `groupBy`/`sortBy`/`uniqueBy`, `escapeRegExp`/`highlightMatch`, `storage()` (namespaced JSON, degrades to memory), `toCsv`/`downloadBlob`/`copyToClipboard`, `truncate()`/`isTruncated()` (line clamp with the full value on hover).
 
 ## Theming
-Load `zx.css` once; set `data-zx-theme` (`light`|`dark`|`auto`) and `data-zx-density` (`cozy`|`compact`) on any ancestor. Define a product theme by overriding semantic `--zx-color-*` / `--zx-control-*` tokens under `[data-zx-theme="name"]`. Never use tier-1 palette tokens or raw color literals in application CSS.
+Load `zx.css` once; set `data-zx-theme` (`light`|`dark`|`auto`) and `data-zx-density` (`cozy`|`compact`) on any ancestor. Define a product theme by overriding semantic `--zx-color-*` / `--zx-control-*` tokens under `[data-zx-theme="name"]`. The theme studio controls accent, neutral tint, density, font, type size, radius, control height, and CSS-first glass material. Never use tier-1 palette tokens or raw color literals in application CSS.
 
 ## Talking to ZeyOS
 Use the dedicated ZeyOS client library **`@zeyos/client`** (`npm install @zeyos/client`) for ZeyOS business data: `createZeyosClient({ platform, auth })`, typed `client.api.list/get/create/update<Resource>` over the full OpenAPI surface, and `normalizeListResult`. Zx accepts the client by injection and does not bundle it. See the `website/layouts/zeyos-invoices.layout.js` layout for a Zx-components-on-@zeyos/client reference. Zx also ships a minimal `Http`/`zeyosService` for ad-hoc in-app `remotecall`, but `@zeyos/client` is the recommended default.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeyos/zx",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Dependency-free JavaScript implementation of the Xenon Design System.",
   "type": "module",
   "license": "MIT",

package/src/components/app-icon/app-icon.css

@@ -0,0 +1,105 @@
+.zx-app-icon {
+  --zx-app-icon-size: 36px;
+  --zx-app-icon-glyph-size: 52%;
+  --zx-app-icon-color: var(--zx-color-accent);
+  position: relative;
+  isolation: isolate;
+  display: inline-grid;
+  place-items: center;
+  flex: none;
+  inline-size: var(--zx-app-icon-size);
+  block-size: var(--zx-app-icon-size);
+  overflow: hidden;
+  border: 1px solid var(--zx-color-glass-border);
+  border-radius: max(var(--zx-radius-md), calc(var(--zx-app-icon-size) * .22));
+  background: var(--zx-app-icon-color);
+  box-shadow: var(--zx-app-icon-shadow);
+  color: var(--zx-app-icon-glyph, var(--zx-color-text-invert));
+  font-size: var(--zx-app-icon-size);
+  vertical-align: middle;
+}
+
+.zx-app-icon[data-glass="subtle"],
+.zx-app-icon[data-glass="strong"] {
+  background:
+    linear-gradient(145deg, var(--zx-color-glass-highlight), transparent 44%),
+    color-mix(in srgb, var(--zx-app-icon-color) var(--zx-glass-color-strength), transparent);
+}
+
+.zx-app-icon[data-glass="strong"] {
+  backdrop-filter: blur(var(--zx-glass-blur)) saturate(var(--zx-glass-saturation));
+}
+
+.zx-app-icon[data-glass="none"] {
+  border-color: var(--zx-color-border);
+  box-shadow: none;
+}
+
+.zx-app-icon[data-glass="none"] .zx-app-icon__shine { display: none; }
+
+.zx-app-icon[data-selected] {
+  outline: 2px solid var(--zx-color-bg-page);
+  box-shadow: 0 0 0 3px var(--zx-color-ring), var(--zx-overlay-shadow);
+}
+
+.zx-app-icon__shine {
+  position: absolute;
+  z-index: -1;
+  inset: 1px 12% auto;
+  block-size: 42%;
+  border-radius: 999px;
+  background: linear-gradient(to bottom, var(--zx-color-glass-highlight-strong), transparent);
+  filter: blur(2px);
+  pointer-events: none;
+}
+
+.zx-app-icon__glyph {
+  display: inline-grid;
+  place-items: center;
+  inline-size: var(--zx-app-icon-glyph-size);
+  block-size: var(--zx-app-icon-glyph-size);
+  font-size: var(--zx-app-icon-glyph-size);
+  line-height: 1;
+  filter: drop-shadow(var(--zx-glass-glyph-shadow));
+}
+
+.zx-app-icon__glyph > .zx-icon,
+.zx-app-icon__glyph > svg,
+.zx-app-icon__glyph > i {
+  inline-size: 1em;
+  block-size: 1em;
+}
+
+.zx-app-icon__badge {
+  position: absolute;
+  inset-block-end: 1px;
+  inset-inline-end: 1px;
+  display: grid;
+  place-items: center;
+  min-inline-size: 14px;
+  block-size: 14px;
+  padding-inline: 3px;
+  border: 1px solid var(--zx-color-bg-raised);
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-danger);
+  color: var(--zx-color-text-invert);
+  font-size: 9px;
+  font-weight: 700;
+  line-height: 1;
+}
+
+@media (prefers-reduced-transparency: reduce) {
+  .zx-app-icon[data-glass="strong"] {
+    background: var(--zx-app-icon-color);
+    backdrop-filter: none;
+  }
+}
+
+@media (forced-colors: active) {
+  .zx-app-icon {
+    border-color: ButtonText;
+    background: ButtonFace;
+    color: ButtonText;
+    box-shadow: none;
+  }
+}

package/src/components/app-icon/app-icon.js

@@ -0,0 +1,134 @@
+import { Component } from '../../core/component.js';
+import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
+import { icon as renderIcon } from '../../core/icons.js';
+import { isCssColor } from '../../core/util.js';
+
+/**
+ * @typedef {Object} AppIconOptions
+ * @property {string|Node|(()=>string|Node)|null} [icon=null] Icon name, node, or lazy renderer.
+ * @property {string|null} [color=null] Identity colour; falls back to the accent colour.
+ * @property {number|string} [size=36] Edge length in pixels or any CSS length.
+ * @property {number|string} [iconSize='52%'] Glyph size.
+ * @property {string|null} [label=null] Accessible image label; null makes the icon decorative.
+ * @property {string|number|null} [badge=null] Optional corner badge.
+ * @property {boolean} [selected=false] Whether the icon represents the active application.
+ * @property {false|'subtle'|'strong'} [glass='subtle'] CSS-first glass treatment.
+ * @property {string|string[]} [class] Additional class names.
+ */
+
+/**
+ * Stable application-identity tile with progressive CSS glass treatment.
+ * @extends {Component<AppIconOptions>}
+ */
+export class AppIcon extends Component {
+  static cssName = 'app-icon';
+
+  /** @type {Readonly<AppIconOptions>} */
+  static defaults = {
+    icon: null,
+    color: null,
+    size: 36,
+    iconSize: '52%',
+    label: null,
+    badge: null,
+    selected: false,
+    glass: 'subtle',
+    class: []
+  };
+
+  /** @returns {HTMLElement} */
+  render() {
+    this._createdRoot = this.el === null;
+    const root = /** @type {HTMLElement} */ (this.el ?? h('span'));
+    this.el = root;
+    this._snapshot = this._createdRoot ? null : snapshotTarget(root);
+    this._state = { ...this.options };
+    this._appliedClasses = [];
+    this._sync();
+    return root;
+  }
+
+  /** Updates identity or presentation without replacing the root. @param {Partial<AppIconOptions>} values @returns {this} */
+  set(values = {}) {
+    if (!values || typeof values !== 'object') return this;
+    Object.assign(this._state, values);
+    this._sync();
+    return this;
+  }
+
+  /** Restores an enhanced target. @returns {void} */
+  destroy() {
+    const root = this.el;
+    const snapshot = this._snapshot;
+    super.destroy();
+    if (!this._createdRoot && root) restoreTarget(root, snapshot);
+  }
+
+  /** @returns {void} */
+  _sync() {
+    const state = this._state;
+    this.el.classList.remove(...this._appliedClasses);
+    this._appliedClasses = [state.class].flat()
+      .flatMap((value) => String(value ?? '').split(/\s+/)).filter(Boolean);
+    this.el.classList.add(...this._appliedClasses);
+    const size = cssLength(state.size, '36px');
+    const glyphSize = cssLength(state.iconSize, '52%');
+    this.el.style.setProperty('--zx-app-icon-size', size);
+    this.el.style.setProperty('--zx-app-icon-glyph-size', glyphSize);
+    if (isCssColor(state.color)) this.el.style.setProperty('--zx-app-icon-color', String(state.color));
+    else this.el.style.removeProperty('--zx-app-icon-color');
+    this.el.dataset.glass = normalizeGlass(state.glass);
+    this.el.toggleAttribute('data-selected', Boolean(state.selected));
+
+    const label = state.label == null ? '' : String(state.label).trim();
+    if (label) {
+      this.el.setAttribute('role', 'img');
+      this.el.setAttribute('aria-label', label);
+      this.el.removeAttribute('aria-hidden');
+    } else {
+      this.el.removeAttribute('role');
+      this.el.removeAttribute('aria-label');
+      this.el.setAttribute('aria-hidden', 'true');
+    }
+
+    const visual = resolveVisual(state.icon);
+    const badge = state.badge == null || state.badge === '' ? null : h('span', {
+      class: 'zx-app-icon__badge', ariaHidden: 'true'
+    }, String(state.badge));
+    this.el.replaceChildren(
+      h('span', { class: 'zx-app-icon__shine', ariaHidden: 'true' }),
+      h('span', { class: 'zx-app-icon__glyph', ariaHidden: 'true' }, visual),
+      badge
+    );
+  }
+}
+
+/**
+ * Creates an AppIcon element without retaining a component lifecycle handle.
+ * @param {AppIconOptions} [options={}] Icon options.
+ * @returns {HTMLElement}
+ */
+export function appIcon(options = {}) {
+  return new AppIcon(null, options).toElement();
+}
+
+/** @param {AppIconOptions['icon']} value @returns {Node|string|null} */
+function resolveVisual(value) {
+  const resolved = typeof value === 'function' ? value() : value;
+  if (typeof resolved === 'string') return renderIcon(resolved, { size: '1em' });
+  return resolved && typeof resolved === 'object' && typeof resolved.nodeType === 'number'
+    ? /** @type {Node} */ (resolved) : null;
+}
+
+/** @param {unknown} value @param {string} fallback @returns {string} */
+function cssLength(value, fallback) {
+  if (typeof value === 'number' && Number.isFinite(value)) return `${Math.max(1, value)}px`;
+  const text = String(value ?? '').trim();
+  return text && !/[;{}]/.test(text) ? text : fallback;
+}
+
+/** @param {unknown} value @returns {'none'|'subtle'|'strong'} */
+function normalizeGlass(value) {
+  if (value === false || value === 'none') return 'none';
+  return value === 'strong' ? 'strong' : 'subtle';
+}

package/src/components/filter/filter-model.js

@@ -0,0 +1,226 @@
+import { uid } from '../../core/util.js';
+
+/** @typedef {null|boolean|number|string|FilterJson[]|{[key:string]: FilterJson}} FilterJson */
+/** @typedef {{kind:'condition', id:string, field:string, operator:string, value:FilterJson}} FilterCondition */
+/** @typedef {{kind:'group', id:string, logic:'and'|'or', children:FilterNode[]}} FilterGroup */
+/** @typedef {FilterCondition|FilterGroup} FilterNode */
+/** @typedef {{version:1, root:FilterGroup}} FilterAst */
+/** @typedef {{id:string, label:string, arity:'none'|'single'|'pair'|'many', types:string[]}} FilterOperator */
+/** @typedef {{id:string, label:string, type:string, operators?:string[], defaultOperator?:string}} FilterField */
+/** @typedef {{nodeId:string, code:string, message:string}} FilterValidationError */
+
+/** Core operators are application-neutral IDs; an adapter maps them to executable query syntax. */
+export const filterOperators = Object.freeze([
+  op('contains', 'contains', 'single', ['text']),
+  op('notContains', 'does not contain', 'single', ['text']),
+  op('eq', 'is', 'single', ['text', 'number', 'money', 'boolean', 'enum', 'status', 'priority', 'country', 'currency', 'unit', 'entity', 'date', 'datetime']),
+  op('neq', 'is not', 'single', ['text', 'number', 'money', 'boolean', 'enum', 'status', 'priority', 'country', 'currency', 'unit', 'entity', 'date', 'datetime']),
+  op('startsWith', 'starts with', 'single', ['text']),
+  op('endsWith', 'ends with', 'single', ['text']),
+  op('lt', 'is less than', 'single', ['number', 'money']),
+  op('lte', 'is at most', 'single', ['number', 'money']),
+  op('gt', 'is greater than', 'single', ['number', 'money']),
+  op('gte', 'is at least', 'single', ['number', 'money']),
+  op('on', 'is on', 'single', ['date', 'datetime']),
+  op('notOn', 'is not on', 'single', ['date', 'datetime']),
+  op('before', 'is before', 'single', ['date', 'datetime']),
+  op('onOrBefore', 'is on or before', 'single', ['date', 'datetime']),
+  op('after', 'is after', 'single', ['date', 'datetime']),
+  op('onOrAfter', 'is on or after', 'single', ['date', 'datetime']),
+  op('between', 'is between', 'pair', ['number', 'money', 'date', 'datetime']),
+  op('notBetween', 'is not between', 'pair', ['number', 'money', 'date', 'datetime']),
+  op('withinLast', 'is within the last', 'pair', ['date', 'datetime']),
+  op('withinNext', 'is within the next', 'pair', ['date', 'datetime']),
+  op('anyOf', 'is any of', 'many', ['enum', 'status', 'priority', 'country', 'currency', 'unit', 'entity']),
+  op('noneOf', 'is none of', 'many', ['enum', 'status', 'priority', 'country', 'currency', 'unit', 'entity']),
+  op('containsAny', 'contains any', 'many', ['tags']),
+  op('containsAll', 'contains all', 'many', ['tags']),
+  op('containsNone', 'contains none', 'many', ['tags']),
+  op('isEmpty', 'is empty', 'none', ['text', 'number', 'money', 'date', 'datetime', 'boolean', 'enum', 'status', 'priority', 'country', 'currency', 'unit', 'entity', 'tags']),
+  op('isNotEmpty', 'is not empty', 'none', ['text', 'number', 'money', 'date', 'datetime', 'boolean', 'enum', 'status', 'priority', 'country', 'currency', 'unit', 'entity', 'tags'])
+]);
+
+/** @returns {FilterAst} */
+export function emptyFilterAst() {
+  return { version: 1, root: { kind: 'group', id: uid('filter-root'), logic: 'and', children: [] } };
+}
+
+/** @param {Partial<FilterCondition>} [initial={}] @returns {FilterCondition} */
+export function filterCondition(initial = {}) {
+  return {
+    kind: 'condition',
+    id: String(initial.id || uid('filter-condition')),
+    field: String(initial.field ?? ''),
+    operator: String(initial.operator ?? ''),
+    value: cloneFilterValue(initial.value ?? null)
+  };
+}
+
+/**
+ * Returns a defensive JSON-safe copy suitable for a condition value.
+ * @param {unknown} value
+ * @returns {FilterJson}
+ */
+export function cloneFilterValue(value) {
+  return cloneJson(value);
+}
+
+/** @param {'and'|'or'} [logic='and'] @param {FilterNode[]} [children=[]] @returns {FilterGroup} */
+export function filterGroup(logic = 'and', children = []) {
+  return { kind: 'group', id: uid('filter-group'), logic, children };
+}
+
+/**
+ * Parses untrusted state into a defensive JSON-safe AST. It rejects structural corruption but
+ * deliberately keeps unknown field/operator IDs for semantic validation and migration UI.
+ * @param {unknown} value
+ * @param {{maxDepth?:number, maxConditions?:number}} [limits={}]
+ * @returns {FilterAst}
+ */
+export function parseFilterAst(value, limits = {}) {
+  const maxDepth = finiteLimit(limits.maxDepth, 3);
+  const maxConditions = finiteLimit(limits.maxConditions, 50);
+  if (!plainObject(value) || value.version !== 1 || !plainObject(value.root)) {
+    throw new TypeError('Filter AST must have version 1 and a root group');
+  }
+  const ids = new Set();
+  let conditions = 0;
+  const visit = (raw, depth, root = false) => {
+    if (!plainObject(raw)) throw new TypeError('Filter nodes must be plain objects');
+    const id = String(raw.id ?? '').trim();
+    if (!id || ids.has(id)) throw new TypeError('Filter node IDs must be non-empty and unique');
+    ids.add(id);
+    if (raw.kind === 'group') {
+      if (depth > maxDepth) throw new RangeError('Filter group depth exceeds maxDepth');
+      if (raw.logic !== 'and' && raw.logic !== 'or') throw new TypeError('Filter group logic must be and or or');
+      if (!Array.isArray(raw.children)) throw new TypeError('Filter group children must be an array');
+      return {
+        kind: 'group', id, logic: raw.logic,
+        children: raw.children.map((child) => visit(child, depth + 1, false))
+      };
+    }
+    if (root || raw.kind !== 'condition') throw new TypeError('Filter root must be a group');
+    conditions += 1;
+    if (conditions > maxConditions) throw new RangeError('Filter condition count exceeds maxConditions');
+    return {
+      kind: 'condition', id,
+      field: String(raw.field ?? ''), operator: String(raw.operator ?? ''),
+      value: cloneJson(raw.value)
+    };
+  };
+  const root = visit(value.root, 0, true);
+  if (root.kind !== 'group') throw new TypeError('Filter root must be a group');
+  return /** @type {FilterAst} */ ({ version: 1, root });
+}
+
+/** @param {FilterAst} value @returns {FilterAst} */
+export function cloneFilterAst(value) {
+  return parseFilterAst(value, { maxDepth: Infinity, maxConditions: Infinity });
+}
+
+/** @param {FilterAst} value @returns {string} */
+export function stringifyFilterAst(value) {
+  return JSON.stringify(cloneFilterAst(value));
+}
+
+/**
+ * Performs field/operator/arity validation without compiling or executing the expression.
+ * @param {FilterAst} ast
+ * @param {FilterField[]} fields
+ * @param {FilterOperator[]} [operators=filterOperators]
+ * @returns {{valid:boolean, errors:FilterValidationError[]}}
+ */
+export function validateFilterAst(ast, fields, operators = filterOperators) {
+  const errors = [];
+  const fieldMap = new Map((Array.isArray(fields) ? fields : []).map((field) => [String(field.id), field]));
+  const operatorMap = new Map((Array.isArray(operators) ? operators : []).map((operator) => [String(operator.id), operator]));
+  const visit = (node, root = false) => {
+    if (node.kind === 'group') {
+      if (!root && node.children.length === 0) errors.push(error(node.id, 'empty-group', 'Nested groups need at least one condition'));
+      node.children.forEach((child) => visit(child));
+      return;
+    }
+    const field = fieldMap.get(node.field);
+    if (!field) errors.push(error(node.id, 'unknown-field', node.field ? `Unavailable field: ${node.field}` : 'Choose a field'));
+    const operator = operatorMap.get(node.operator);
+    if (!operator) {
+      errors.push(error(node.id, 'unknown-operator', node.operator ? `Unavailable operator: ${node.operator}` : 'Choose an operator'));
+      return;
+    }
+    if (field) {
+      const allowed = Array.isArray(field.operators) && field.operators.length
+        ? field.operators : operators.filter((candidate) => candidate.types.includes(field.type)).map((candidate) => candidate.id);
+      if (!allowed.includes(operator.id) || !operator.types.includes(field.type)) {
+        errors.push(error(node.id, 'operator-type', `${operator.label} is not available for ${field.label}`));
+      }
+    }
+    if (!validArity(operator.arity, node.value)) {
+      errors.push(error(node.id, 'value', operator.arity === 'pair' ? 'Enter both values'
+        : operator.arity === 'many' ? 'Choose at least one value'
+          : operator.arity === 'none' ? 'This operator does not accept a value' : 'Enter a value'));
+    }
+  };
+  visit(ast.root, true);
+  return { valid: errors.length === 0, errors };
+}
+
+/** @param {string} id @param {string} label @param {FilterOperator['arity']} arity @param {string[]} types @returns {FilterOperator} */
+function op(id, label, arity, types) { return Object.freeze({ id, label, arity, types: Object.freeze(types) }); }
+
+/** @param {string} nodeId @param {string} code @param {string} message @returns {FilterValidationError} */
+function error(nodeId, code, message) { return { nodeId, code, message }; }
+
+/** @param {FilterOperator['arity']} arity @param {FilterJson} value @returns {boolean} */
+function validArity(arity, value) {
+  if (arity === 'none') return value === null;
+  if (arity === 'pair') return Array.isArray(value) && value.length === 2 && value.every(filled);
+  if (arity === 'many') return Array.isArray(value) && value.length > 0 && value.every(filled);
+  return filled(value);
+}
+
+/** @param {unknown} value @returns {boolean} */
+function filled(value) { return value !== null && value !== undefined && !(typeof value === 'string' && value.trim() === ''); }
+
+/** @param {unknown} value @param {WeakSet<object>} [seen=new WeakSet()] @returns {FilterJson} */
+function cloneJson(value, seen = new WeakSet()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new TypeError('Filter values cannot contain non-finite numbers');
+    return value;
+  }
+  if (typeof value !== 'object' || value instanceof Date || typeof value.nodeType === 'number') {
+    throw new TypeError('Filter values must be JSON-safe');
+  }
+  if (seen.has(value)) throw new TypeError('Filter values cannot contain cycles');
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const result = value.map((item) => cloneJson(item, seen));
+    seen.delete(value);
+    return result;
+  }
+  if (!plainObject(value)) throw new TypeError('Filter values must be plain JSON objects');
+  const result = {};
+  for (const [key, item] of Object.entries(value)) {
+    // Assignment to `__proto__` is special on ordinary objects. Defining an own data property
+    // preserves the JSON member without changing the clone's prototype.
+    Object.defineProperty(result, key, {
+      value: cloneJson(item, seen), enumerable: true, configurable: true, writable: true
+    });
+  }
+  seen.delete(value);
+  return result;
+}
+
+/** @param {unknown} value @returns {boolean} */
+function plainObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/** @param {unknown} value @param {number} fallback @returns {number} */
+function finiteLimit(value, fallback) {
+  if (value === Infinity) return Infinity;
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? Math.floor(number) : fallback;
+}

package/src/components/filter/filter.css

@@ -0,0 +1,147 @@
+.zx-filter {
+  display: grid;
+  gap: var(--zx-space-3);
+  color: var(--zx-color-text);
+}
+
+.zx-filter__status {
+  position: absolute;
+  inline-size: 1px;
+  block-size: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+}
+
+.zx-filter__group,
+.zx-filter__group > fieldset {
+  min-inline-size: 0;
+  margin: 0;
+  border: 1px solid var(--zx-color-border);
+  border-radius: var(--zx-radius-lg);
+  background: var(--zx-color-bg-surface);
+  padding: var(--zx-space-3);
+}
+
+.zx-filter__group .zx-filter__group {
+  border: 0;
+  border-inline-start: 3px solid var(--zx-color-border-strong);
+  border-radius: 0;
+  background: transparent;
+  padding: 0 0 0 var(--zx-space-3);
+}
+
+.zx-filter__legend {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--zx-space-2);
+  padding-inline: var(--zx-space-1);
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-sm);
+}
+
+.zx-filter__logic,
+.zx-filter__field,
+.zx-filter__operator,
+.zx-filter__value input,
+.zx-filter__value select {
+  min-block-size: var(--zx-control-height);
+  border: 1px solid var(--zx-color-border-control);
+  border-radius: var(--zx-control-radius);
+  background: var(--zx-color-bg-control);
+  padding-inline: var(--zx-control-pad-x);
+  color: var(--zx-color-text);
+  font: inherit;
+}
+
+.zx-filter__logic {
+  inline-size: auto;
+  min-block-size: 28px;
+  font-size: var(--zx-text-sm);
+}
+
+.zx-filter__children {
+  display: grid;
+  gap: var(--zx-space-2);
+  margin: var(--zx-space-2) 0;
+  padding: 0;
+  list-style: none;
+}
+
+.zx-filter__condition {
+  display: grid;
+  grid-template-columns: minmax(9rem, 1fr) minmax(9rem, 1fr) minmax(10rem, 1.4fr) auto;
+  align-items: start;
+  gap: var(--zx-space-2);
+  border-radius: var(--zx-radius-md);
+}
+
+.zx-filter__condition[data-invalid] {
+  outline: 1px solid var(--zx-color-danger);
+  outline-offset: var(--zx-space-1);
+}
+
+.zx-filter__value {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: var(--zx-space-2);
+  min-inline-size: 0;
+}
+
+.zx-filter__value-control,
+.zx-filter__value-control > input {
+  inline-size: 100%;
+  min-inline-size: 0;
+}
+
+.zx-filter__value > :only-child,
+.zx-filter__value--empty {
+  grid-column: 1 / -1;
+}
+
+.zx-filter__value--empty {
+  display: flex;
+  align-items: center;
+  min-block-size: var(--zx-control-height);
+  padding-inline: var(--zx-control-pad-x);
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-sm);
+}
+
+.zx-filter__group-actions,
+.zx-filter__actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--zx-space-2);
+}
+
+.zx-filter__actions {
+  justify-content: flex-end;
+}
+
+.zx-filter[data-readonly] .zx-filter__group-actions,
+.zx-filter[data-readonly] .zx-filter__actions,
+.zx-filter[data-disabled] .zx-filter__group-actions,
+.zx-filter[data-disabled] .zx-filter__actions {
+  display: none;
+}
+
+@media (max-width: 680px) {
+  .zx-filter__condition {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .zx-filter__group .zx-filter__group {
+    padding-inline-start: var(--zx-space-2);
+  }
+
+  .zx-filter__value {
+    grid-template-columns: minmax(0, 1fr);
+  }
+}
+
+@media (forced-colors: active) {
+  .zx-filter__group,
+  .zx-filter__condition[data-invalid] {
+    border-color: CanvasText;
+  }
+}