@zeyos/zx 2.2.1 → 2.3.0

package/CHANGELOG.md

@@ -8,6 +8,116 @@ and friends remain the complete record.
 
 ## Unreleased
 
+## 2.3.0 — 2026-08-23
+
+### Added
+
+- **Six standard themes, as an attribute.** `data-zx-preset="zx" | "zeyos" | "ocean" | "violet" |
+  "rose" | "slate"` picks the accent ramp, orthogonally to `data-zx-theme` picking the polarity.
+  A preset is five tier-1 declarations — `--zx-accent-300` … `--zx-accent-700` — because the accent
+  roles now resolve through that ramp rather than through the green palette directly, so one block
+  rethemes light, dark, and auto together with no second list to keep in sync. Every shipped
+  preset keeps its 600 stop above 4.5:1 against white and its 400 stop above 4.5:1 against the dark
+  page, which is what lets `--zx-color-on-accent` stay a single value per theme. Status colours are
+  deliberately not part of a preset.
+- **A theme studio at `/theme.html`.** Every component on one page under a live theme: cycle the
+  standard presets (or press `[` and `]`), set a custom accent that is derived into a full ramp in
+  OKLab with the contrast ratio reported as you go, tint the neutral ramp, and change radius,
+  control height, base text size, type stack, and density — then copy the result out as CSS.
+  What you pick applies to the whole documentation site until you reset it.
+
+- **`Select` takes fixed choices.** `fixedItems` pins entries to the top of the list, above a rule,
+  and treats them as part of the control rather than of its data: a `filter` function replaces the
+  item list on every query, so a pinned entry is narrowed locally against the same query instead,
+  survives `setItems()`, shows below `minQuery`, and stays resolvable by `set()` once the first
+  results have landed. That is what a choice with no row in the source needs — "Unassigned",
+  "Everyone", "Private". `setFixedItems()` replaces them later.
+- **`Select.permission()`**, the record-access picker: Private and Public pinned above the groups a
+  record may be shared with, carrying the tri-state ZeyOS stores — `false`, `true`, or a group ID —
+  so it binds straight to the record field. `groups` takes an array, or a loader `(query) => items`
+  for an installation whose group list is too long to ship with the form.
+
+- **`MultiValueEditor` rows reorder by dragging.** Each row grows a handle that drags it to a new
+  position, with a line showing where it will land. `reorder` picks what a row offers — `'both'`
+  (the default), `'drag'` for the handle alone, `'buttons'` for the arrows alone, or `'none'`.
+  Dragging goes through the handle rather than the whole row, so selecting text inside a row's
+  input still works, and the handle is a keyboard control too (arrow keys, Home, End) — which is
+  what keeps `reorder: 'drag'` operable without a pointer.
+
+### Changed
+
+- **The documentation shows the demo data behind an example.** `items: catalogue()` documented
+  nothing on its own — the shape the component wants was in a helper the reader could only find by
+  opening the whole module. Every example's code block now carries a tab per module-level
+  declaration it uses, transitively, extracted from the demo module's own text. Nothing about
+  writing a demo changes: declare the data at the top of the module and it appears.
+
+### Deprecated
+
+- **`Permission`.** Its three radios and a disabled group picker spend a form row on a choice
+  `Select.permission()` makes in one control, and the group list could only ever be an array held
+  in memory. The class stays for `gx.zeyos.Permission` and goes away in 3.0; the value and the
+  `groups` option are identical, so replacing it is a one-line change.
+
+### Fixed
+
+- **`MultiValueEditor` no longer collapses in a host that sizes to its contents.** It is no longer
+  a size container at all. `inline-size: 100%` does not rescue one: the percentage resolves against
+  a containing block the host measured from the contribution containment had already zeroed, so the
+  editor still came out 26px wide in an inline-block, a table cell, or a shrink-to-fit flex row,
+  with the row spilling out to the left of it. The rows reflow on their own now — the controls wrap
+  under the value when the row runs out of room — which also reads the width that decides the
+  layout, the row's, rather than the editor's. Verified from a 1000px grid down to a 100px pane
+  with nothing overflowing. `DateRangePicker`, `Fieldset`, and `NavigationBar` still use
+  containment and are only partly rescued — see below.
+- **`MultiValueEditor` keeps focus on the move button.** Up and down disabled themselves at the
+  ends of the list, so a row that reached the top took focus down to the document with it, and a
+  move sent focus to the value input rather than leaving it on the button that had just moved the
+  row — pressing up twice was impossible without going back for it. The ends now mark themselves
+  `aria-disabled` and stay focusable.
+- **`MultiValueEditor` keeps a stored value its option list has lost.** A value with no matching
+  option displayed as the first option while `getValues()` went on returning the stored one, so a
+  form that was only opened and saved rewrote the field. The unknown value is now an option in its
+  own right.
+
+- **The × on a closable `Tabbox` tab closes it.** It was drawn as a decorative glyph with no
+  handler, so clicking it merely activated the tab and closing was reachable only through the
+  Delete key. It is now a real hit target that emits `close` and hands focus to the neighbouring
+  tab, with Delete unchanged. It stays a `<span>` rather than a nested `<button>`, which buttons
+  cannot contain.
+- **Size containers fill their host instead of collapsing inside it.** `DateRangePicker`,
+  `Fieldset`, and `NavigationBar` declare `container-type: inline-size` to pick their own layout,
+  which means they contribute nothing to their own intrinsic width — so in a flex row, an
+  inline-block, or a grid `auto` track they were squeezed to a few pixels and their contents
+  spilled out on top of each other. They now take `inline-size: 100%`, and `Form` does too, because
+  containment travels upward: a form shrink-wrapped to its action buttons while the fieldset inside
+  it overflowed. Eight examples on the documentation site were rendering this way.
+
+  This fixes every host that has a width of its own, which is the case that was actually biting.
+  It cannot fix a host that shrink-wraps its contents — an `inline-block` or a `fit-content` track
+  with no width of its own — because there 100% resolves against a containing block the collapse
+  has already zeroed. Only dropping containment does, as `MultiValueEditor` now has;
+  `DateRangePicker`, `Fieldset`, and `NavigationBar` still need a definite width from their host.
+  `tests/unit/size-containers.test.js` keeps every `container-type` rule declaring a width.
+- **A focused `Search` field is ringed as one control.** The input carried its own focus ring on
+  top of the ring the field already draws on `:focus-within`, so a smaller rounded box appeared
+  inside the field and cut the submit button out of it — the field read as an input with a
+  detached button beside it. The input now rides the field's ring, and the clear and submit
+  buttons mark themselves with an inset ring so tabbing still shows which one has focus without
+  breaking the outline.
+
+- **The generated API reference stopped losing methods to inline type casts.** `/** @type {X} */
+  (expr)` is a doc comment with no method behind it, and the scanner in `tools/build-api.js` was
+  allowed to run past it to the next one — swallowing that method's own comment, and with it the
+  method. Sixty-three public methods across forty-four components had no row on the documentation
+  site, `Dialog.open()` and `Table.commitEdit()` among them, and a few of the rows that did appear
+  had absorbed a neighbour's parameters into signatures like
+  `destroy(options, column, index, node)`.
+- **A horizontal `Stepper` spans its container.** The connectors were already written to absorb
+  whatever space was left over, but the steps themselves could not grow, so there was never any
+  slack to absorb and the rail bunched up on the left of a wide card. The labels still size to
+  themselves; the rules between them now stretch.
+
 ## 2.2.1 — 2026-08-21
 
 ### Fixed

package/README.md

@@ -217,8 +217,34 @@ the document. Select a built-in theme and density on any ancestor (normally `<ht
 ```
 
 Theme values are `light`, `dark`, and `auto`; density values are `cozy` and `compact`. `auto`
-follows the operating-system color preference. A product theme can override semantic tokens
-without reaching into component CSS:
+follows the operating-system color preference.
+
+A third attribute picks the **accent**, orthogonally to the other two:
+
+```html
+<html data-zx-theme="dark" data-zx-preset="ocean">
+```
+
+Six presets ship — `zx` (the ZeyOS green, and the default), `zeyos`, `ocean`, `violet`, `rose`,
+`slate`. Each is five declarations of the tier-1 accent ramp that the semantic tier resolves
+through, so a preset rethemes light, dark, and auto at once:
+
+```css
+[data-zx-preset="acme"] {
+  --zx-accent-300: #c4b4ff;
+  --zx-accent-400: #a684ff;
+  --zx-accent-500: #8e51ff;
+  --zx-accent-600: #7f22fe;
+  --zx-accent-700: #7008e7;
+}
+```
+
+Light surfaces take the 600 and 700 stops, dark ones take 300, 400, and 500 — so keep 600 legible
+against white and 400 against near-black, and `--zx-color-on-accent` stays correct in both. The
+[theme studio](https://zx.zeyos.com/theme.html) renders every component under a live theme and
+exports the result.
+
+Anything beyond the accent is a semantic token override, without reaching into component CSS:
 
 ```css
 :root[data-zx-theme="acme"] {

package/dist/types/components/multi-value-editor/multi-value-editor.d.ts

@@ -12,21 +12,28 @@ export type MultiValueEditorOptions = {
      * Add-row button text.
      */
     addLabel?: string;
+    /**
+     * Reordering affordances each row gets:
+     * a drag handle, the up/down buttons, both, or neither.
+     */
+    reorder?: 'both' | 'buttons' | 'drag' | 'none';
 };
-/**
- * @typedef {Object} MultiValueEditorOptions
- * @property {unknown[]} [values=[]] Initial ordered values.
- * @property {unknown[]|Record<string, string>|null} [options=null] Allowed values; null uses text inputs.
- * @property {string} [addLabel='Add value'] Add-row button text.
- */
 /**
  * Ordered value editor with explicit editable rows and controls.
+ *
+ * Rows reorder by dragging their handle or by pressing the up/down buttons — `reorder` picks which
+ * of the two a row offers. The handle is also a keyboard control (arrows, Home, End), so drag-only
+ * mode still reorders without a pointer.
  * @fires MultiValueEditor#change
  * @extends {Component<MultiValueEditorOptions>}
  */
 export declare class MultiValueEditor extends Component<MultiValueEditorOptions> {
     _values: string[];
     _ownedNodes: any[];
+    _initialState: string;
+    _dragIndex: number;
+    /** @type {HTMLElement|null} Row made draggable by a pointer press on its handle. */
+    _armed: HTMLElement | null;
     _rows: HTMLElement;
     _add: HTMLElement;
     static cssName: string;
@@ -48,12 +55,64 @@ export declare class MultiValueEditor extends Component<MultiValueEditorOptions>
     setValues(values: unknown[], { silent }?: {
         silent?: boolean;
     }): this;
-    /** @param {number} [focusIndex=-1] @returns {void} */
-    _renderRows(focusIndex?: number): void;
+    /** @returns {{drag: boolean, buttons: boolean}} */
+    _reorder(): {
+        drag: boolean;
+        buttons: boolean;
+    };
+    /**
+     * @param {number} [focusIndex=-1] Row to focus after the render, or -1 for none.
+     * @param {keyof PARTS} [focusPart='value'] Which control of that row takes focus.
+     * @returns {void}
+     */
+    _renderRows(focusIndex?: number, focusPart?: keyof PARTS): void;
     /** @param {MouseEvent} event @returns {void} */
     _handleClick(event: MouseEvent): void;
     /** @param {Event} event @returns {void} */
     _handleChange(event: Event): void;
+    /**
+     * The handle is the keyboard equivalent of dragging it, so `reorder: 'drag'` is still operable
+     * without a pointer.
+     * @param {KeyboardEvent} event
+     * @returns {void}
+     */
+    _handleKeydown(event: KeyboardEvent): void;
+    /**
+     * Arms the row for dragging. Only the handle does this, so text selection inside a row's input
+     * keeps working and a stray drag cannot reorder anything.
+     * @param {PointerEvent} event
+     * @returns {void}
+     */
+    _handlePointerDown(event: PointerEvent): void;
+    /** @returns {void} */
+    _disarm(): void;
+    /** @param {DragEvent} event @returns {void} */
+    _handleDragStart(event: DragEvent): void;
+    /** @param {DragEvent} event @returns {void} */
+    _handleDragOver(event: DragEvent): void;
+    /** @param {DragEvent} event @returns {void} */
+    _handleDragLeave(event: DragEvent): void;
+    /** @param {DragEvent} event @returns {void} */
+    _handleDrop(event: DragEvent): void;
+    /** @returns {void} */
+    _finishDrag(): void;
+    /**
+     * Insertion slot (0…length) for a pointer at `clientY`.
+     * @param {number} clientY Pointer position.
+     * @returns {number}
+     */
+    _dropTarget(clientY: number): number;
+    /** @param {number} slot Insertion slot to mark. @returns {void} */
+    _showDrop(slot: number): void;
+    /** @returns {void} */
+    _clearDrop(): void;
+    /**
+     * @param {number} from Index to move.
+     * @param {number} to Destination index.
+     * @param {keyof PARTS} part Control of the moved row that takes focus.
+     * @returns {boolean} Whether anything moved.
+     */
+    _move(from: number, to: number, part: keyof PARTS): boolean;
     /** @returns {void} */
     _emitChange(): void;
     /** @returns {void} */

package/dist/types/components/permission/permission.d.ts

@@ -44,6 +44,9 @@ export type PermissionChangeDetail = {
 /**
  * Record-permission choice for private, public, and group access.
  *
+ * @deprecated Use `Select.permission(target, {groups})`, which carries the same tri-state value in
+ * one control and accepts a loader function for installations whose group list is too long to ship
+ * with the form. This class stays for `gx.zeyos.Permission` and will be removed in 3.0.
  * @fires Permission#change
  * @extends {Component<PermissionOptions>}
  */

package/dist/types/components/select/select.d.ts

@@ -8,6 +8,10 @@ export type SelectOptions = {
      * Available values.
      */
     items?: SelectItem[];
+    /**
+     * Choices pinned above the list, kept through filtering and async loads.
+     */
+    fixedItems?: SelectItem[];
     /**
      * Item ID property or reader.
      */
@@ -120,7 +124,9 @@ export type SelectSetOptions = {
 export declare class Select extends Component<SelectOptions> {
     _items: any[] | SelectItem[];
     _visibleItems: any[];
-    _selected: any;
+    _fixedItems: any[] | SelectItem[];
+    _visibleFixed: any[] | SelectItem[];
+    _selected: SelectItem;
     _optionEntries: any[];
     _activeIndex: number;
     _open: boolean;
@@ -159,6 +165,12 @@ export declare class Select extends Component<SelectOptions> {
      * @returns {this}
      */
     setItems(items: SelectItem[]): this;
+    /**
+     * Replaces the pinned choices and preserves selection by ID when possible.
+     * @param {SelectItem[]} items New fixed items.
+     * @returns {this}
+     */
+    setFixedItems(items: SelectItem[]): this;
     /**
      * Restores the configured initial value.
      * @param {{silent?: boolean}} [options={}] Reset behavior.
@@ -184,6 +196,20 @@ export declare class Select extends Component<SelectOptions> {
      * @returns {Select}
      */
     static priority(target: Element | string | null, options?: SelectOptions): Select;
+    /**
+     * Creates the record-permission picker: the fixed Private and Public choices above the groups a
+     * record can be shared with. The value is the tri-state ZeyOS stores — `false` for private,
+     * `true` for public, or a group ID — so the control binds straight to the record field.
+     *
+     * @param {Element|string|null} target Component target.
+     * @param {SelectOptions & {groups?: SelectItem[]|((query: string) => Promise<SelectItem[]>|SelectItem[])}} [options={}]
+     *   Select overrides other than the fixed choices; `groups` holds the shareable groups, either as
+     *   an array (filtered locally) or as a loader function (queried remotely).
+     * @returns {Select}
+     */
+    static permission(target: Element | string | null, options?: SelectOptions & {
+        groups?: SelectItem[] | ((query: string) => Promise<SelectItem[]> | SelectItem[]);
+    }): Select;
     /** Cleans up the panel, pending async work, and enhanced target contents. @returns {void} */
     destroy(): void;
     /** @param {KeyboardEvent} event @returns {void} */
@@ -224,6 +250,15 @@ export declare class Select extends Component<SelectOptions> {
     _itemLabel(item: SelectItem | null): string;
     /** @param {SelectItem|null} item @param {SelectValueReader|SelectLabelReader} reader @returns {unknown} */
     _read(item: SelectItem | null, reader: SelectValueReader | SelectLabelReader): unknown;
+    /** @returns {Array<SelectValueReader|SelectLabelReader>} */
+    _searchKeys(): Array<SelectValueReader | SelectLabelReader>;
+    /**
+     * Narrows the pinned choices. They are always matched here and never handed to a filter
+     * function: a fixed choice belongs to the control, not to whatever the remote source returns.
+     * @param {string} query Search text.
+     * @returns {SelectItem[]}
+     */
+    _matchFixed(query: string): SelectItem[];
     /** @returns {number} */
     _selectedEntryIndex(): number;
     /** @param {number} itemIndex @returns {number} */

package/dist/types/components/tabbox/tabbox.d.ts

@@ -18,7 +18,7 @@ export type TabDefinition = {
      */
     icon?: string;
     /**
-     * Whether Delete can close the tab.
+     * Whether the tab shows a close control and Delete closes it.
      */
     closable?: boolean;
     /**
@@ -61,7 +61,8 @@ export type TabboxOptions = {
         previous: string | null;
     }>) => void;
     /**
-     * Close callback.
+     * Close callback, fired when the
+     * user dismisses a closable tab.
      */
     onclose?: (event: CustomEvent<{
         name: string;
@@ -107,7 +108,8 @@ export type TabRecord = {
  *   control, for a toolbar or card header.
  * @property {boolean} [keepAlive=true] Keep inactive panel elements mounted.
  * @property {(event: CustomEvent<{name: string, previous: string|null}>) => void} [onchange] Change callback.
- * @property {(event: CustomEvent<{name: string}>) => void} [onclose] Close callback.
+ * @property {(event: CustomEvent<{name: string}>) => void} [onclose] Close callback, fired when the
+ *   user dismisses a closable tab.
  */
 /**
  * @typedef {Object} TabRecord
@@ -211,6 +213,13 @@ export declare class Tabbox extends Component<TabboxOptions> {
     destroy(): void;
     /** @param {KeyboardEvent} event @returns {void} */
     _onKeydown(event: KeyboardEvent): void;
+    /**
+     * Closes a tab on a user gesture, keeping roving focus inside the tablist.
+     * @param {TabRecord} record Tab to close.
+     * @returns {void}
+     * @fires Tabbox#close
+     */
+    _closeTab(record: TabRecord): void;
     /** @param {string} name @param {boolean} emitClose @returns {boolean} */
     _removeTab(name: string, emitClose: boolean): boolean;
     /** @param {TabRecord} record @returns {void} */