@zeyos/zx 2.2.1 → 3.0.0

package/src/components/search/search.css

@@ -22,10 +22,18 @@
   padding-inline: var(--zx-control-pad-x) var(--zx-control-height);
 }
 
-.zx-search__input:focus-visible,
+/* The field draws one ring for the whole control (:focus-within above). Inner controls must not
+   add a second, smaller ring — an outset ring on the input cut the submit button out of the field.
+   The input rides the field ring; the buttons mark themselves with an inset one, as .zx-icon-btn
+   does, so the field's outline stays whole. The transparent outline from base.css is left in place
+   for forced-colors mode. */
+.zx-search__input:focus-visible {
+  box-shadow: none;
+}
+
 .zx-search__clear:focus-visible,
 .zx-search__submit:focus-visible {
-  box-shadow: var(--zx-focus-ring);
+  box-shadow: inset var(--zx-focus-ring);
 }
 
 .zx-search__input::-webkit-search-cancel-button {

package/src/components/select/select.css

@@ -118,7 +118,6 @@
   background: var(--zx-color-bg-selected);
 }
 
-.zx-select__option > svg,
 .zx-select__option > .zx-icon {
   flex: none;
   color: var(--zx-color-accent);
@@ -137,6 +136,12 @@
   text-transform: uppercase;
 }
 
+.zx-select__separator {
+  block-size: 1px;
+  margin: var(--zx-space-1) var(--zx-control-pad-x);
+  background: var(--zx-color-border);
+}
+
 .zx-select__empty {
   color: var(--zx-color-text-muted);
   padding: var(--zx-space-3) var(--zx-control-pad-x);

package/src/components/select/select.js

@@ -13,6 +13,7 @@ import { matchItems } from './filter.js';
 /**
  * @typedef {Object} SelectOptions
  * @property {SelectItem[]} [items=[]] Available values.
+ * @property {SelectItem[]} [fixedItems=[]] Choices pinned above the list, kept through filtering and async loads.
  * @property {SelectValueReader} [valueKey='ID'] Item ID property or reader.
  * @property {SelectLabelReader} [labelKey='name'] Item label property or reader.
  * @property {((item: SelectItem) => Node|string)|null} [renderItem=null] Option renderer.
@@ -65,6 +66,7 @@ export class Select extends Component {
   /** @type {SelectOptions} */
   static defaults = {
     items: [],
+    fixedItems: [],
     valueKey: 'ID',
     labelKey: 'name',
     renderItem: null,
@@ -86,7 +88,7 @@ export class Select extends Component {
   render() {
     // Instance state initialized here because render() runs inside the base
     // constructor, before class-field initializers would run (and clobber it).
-    this._items = []; this._visibleItems = []; this._selected = null; this._optionEntries = []; this._activeIndex = -1; this._open = false; this._disabled = false; this._loading = false; this._requestSequence = 0; this._queryTimer = null; this._position = null; this._createdRoot = false; this._root = null; this._originalChildren = []; this._originalAttributes = new Map();
+    this._items = []; this._visibleItems = []; this._fixedItems = []; this._visibleFixed = []; this._selected = null; this._optionEntries = []; this._activeIndex = -1; this._open = false; this._disabled = false; this._loading = false; this._requestSequence = 0; this._queryTimer = null; this._position = null; this._createdRoot = false; this._root = null; this._originalChildren = []; this._originalAttributes = new Map();
     this._createdRoot = this.el === null;
     const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
     this.el = root;
@@ -151,6 +153,8 @@ export class Select extends Component {
 
     this._items = Array.isArray(this.options.items) ? this.options.items.slice() : [];
     this._visibleItems = this._items.slice();
+    this._fixedItems = Array.isArray(this.options.fixedItems) ? this.options.fixedItems.slice() : [];
+    this._visibleFixed = this._fixedItems.slice();
     this._disabled = Boolean(this.options.disabled);
     this._handleTypeahead = typeahead(
       () => this._optionEntries.filter((entry) => !entry.clear).map((entry) => entry.element),
@@ -228,8 +232,23 @@ export class Select extends Component {
     const selectedValue = this.value;
     this._items = Array.isArray(items) ? items.slice() : [];
     this._visibleItems = this._items.slice();
-    this._selected = selectedValue == null ? null :
-      this._items.find((item) => Object.is(this._itemValue(item), selectedValue)) ?? null;
+    this._selected = selectedValue == null ? null : this._findItem(selectedValue);
+    this._syncInputValue();
+    this._renderOptions();
+    this._position?.update();
+    return this;
+  }
+
+  /**
+   * Replaces the pinned choices and preserves selection by ID when possible.
+   * @param {SelectItem[]} items New fixed items.
+   * @returns {this}
+   */
+  setFixedItems(items) {
+    const selectedValue = this.value;
+    this._fixedItems = Array.isArray(items) ? items.slice() : [];
+    this._visibleFixed = this._fixedItems.slice();
+    this._selected = selectedValue == null ? null : this._findItem(selectedValue);
     this._syncInputValue();
     this._renderOptions();
     this._position?.update();
@@ -283,6 +302,7 @@ export class Select extends Component {
     this.refs.input.removeAttribute('aria-activedescendant');
     this._activeIndex = -1;
     this._visibleItems = this._items.slice();
+    this._visibleFixed = this._fixedItems.slice();
     this._syncInputValue();
     this.emit('close', {});
     return this;
@@ -341,6 +361,40 @@ export class Select extends Component {
     return 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, options = {}) {
+    const { groups = [], value = true, valueKey = 'ID', labelKey = 'name', ...rest } = options;
+    const loader = typeof groups === 'function' ? groups : null;
+    const shareable = loader ? [] : groups;
+    const choices = [{ ID: false, name: 'Private' }, { ID: true, name: 'Public' }];
+    const select = new Select(target, {
+      filter: loader ?? 'local',
+      ...rest,
+      value: null,
+      items: shareable,
+      fixedItems: [],
+      // The two choices carry their own ID and label, so a caller's group readers stay untouched.
+      valueKey: (item) => choices.includes(item) ? item.ID : readItem(item, valueKey),
+      labelKey: (item) => choices.includes(item) ?
+        item.name : String(readItem(item, labelKey) ?? '')
+    });
+    choices[0].name = select._message('permission.private', 'Private');
+    choices[1].name = select._message('permission.public', 'Public');
+    select.setFixedItems(choices);
+    select.set(value, { silent: true });
+    return select;
+  }
+
   /** Cleans up the panel, pending async work, and enhanced target contents. @returns {void} */
   destroy() {
     this._cancelQuery();
@@ -407,8 +461,8 @@ export class Select extends Component {
     const query = /** @type {HTMLInputElement} */ (this.refs.input).value;
     if (!this._open) this.open();
     if (this.options.filter === 'local') {
-      const keys = this.options.searchKeys ?? [this.options.labelKey];
-      this._visibleItems = matchItems(this._items, query, keys);
+      this._visibleFixed = this._matchFixed(query);
+      this._visibleItems = matchItems(this._items, query, this._searchKeys());
       this._renderOptions();
       this._setActive(this._optionEntries.length > 0 ? 0 : -1);
       this._position?.update();
@@ -466,6 +520,11 @@ export class Select extends Component {
     if (this.options.clearable) {
       this._appendOption(null, true, this.options.placeholder || this._message('select.none', 'No selection'));
     }
+    for (const item of this._visibleFixed) this._appendOption(item, false);
+    // A group heading already divides the two sections, and a rule right above one reads as a slip.
+    if (this._visibleFixed.length > 0 && this._visibleItems.length > 0 && !this.options.groupKey) {
+      list.append(h('div', { class: 'zx-select__separator', role: 'presentation' }));
+    }
     for (const item of this._visibleItems) {
       if (this.options.groupKey) {
         const group = this._read(item, this.options.groupKey);
@@ -479,7 +538,7 @@ export class Select extends Component {
       }
       this._appendOption(item, false);
     }
-    if (this._visibleItems.length === 0 && !this._loading) {
+    if (this._visibleItems.length === 0 && this._visibleFixed.length === 0 && !this._loading) {
       list.append(h('div', {
         class: 'zx-select__empty',
         role: 'status'
@@ -521,6 +580,7 @@ export class Select extends Component {
     if (this._queryTimer !== null) clearTimeout(this._queryTimer);
     this._requestSequence += 1;
     const sequence = this._requestSequence;
+    this._visibleFixed = this._matchFixed(query);
     if (query.length < Math.max(0, Number(this.options.minQuery) || 0)) {
       this._setLoading(false);
       this._visibleItems = [];
@@ -601,11 +661,14 @@ export class Select extends Component {
 
   /** @param {unknown} candidate @returns {SelectItem|null} */
   _findItem(candidate) {
-    const direct = this._items.find((item) => item === candidate);
+    // Fixed choices are searched too: an async filter replaces the item list on every query, so a
+    // pinned value would otherwise stop resolving the moment the first result arrived.
+    const pool = this._fixedItems.length === 0 ? this._items : [...this._fixedItems, ...this._items];
+    const direct = pool.find((item) => item === candidate);
     if (direct !== undefined) return direct;
     const value = candidate !== null && typeof candidate === 'object' ?
       this._itemValue(/** @type {SelectItem} */ (candidate)) : candidate;
-    return this._items.find((item) => Object.is(this._itemValue(item), value)) ?? null;
+    return pool.find((item) => Object.is(this._itemValue(item), value)) ?? null;
   }
 
   /** @param {SelectItem|null} item @returns {unknown} */
@@ -621,9 +684,22 @@ export class Select extends Component {
 
   /** @param {SelectItem|null} item @param {SelectValueReader|SelectLabelReader} reader @returns {unknown} */
   _read(item, reader) {
-    if (typeof reader === 'function') return reader(item);
-    if (item === null || typeof item !== 'object') return item;
-    return item[reader];
+    return readItem(item, reader);
+  }
+
+  /** @returns {Array<SelectValueReader|SelectLabelReader>} */
+  _searchKeys() {
+    return this.options.searchKeys ?? [this.options.labelKey];
+  }
+
+  /**
+   * 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) {
+    return matchItems(this._fixedItems, query, this._searchKeys());
   }
 
   /** @returns {number} */
@@ -657,6 +733,18 @@ export class Select extends Component {
 /** Async-query start notification. @event Select#query @type {CustomEvent<SelectQueryDetail>} */
 /** Async results notification. @event Select#loaded @type {CustomEvent<SelectLoadedDetail>} */
 
+/**
+ * Reads a value off an item through a property name or a reader function.
+ * @param {SelectItem|null} item Item to read.
+ * @param {SelectValueReader|SelectLabelReader} reader Property name or reader.
+ * @returns {unknown}
+ */
+function readItem(item, reader) {
+  if (typeof reader === 'function') return reader(item);
+  if (item === null || typeof item !== 'object') return item;
+  return item[reader];
+}
+
 /** @param {KeyboardEvent} event @returns {boolean} */
 function isPrintable(event) {
   return event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey;

package/src/components/sheet/sheet-stack.js

@@ -0,0 +1,304 @@
+/** @typedef {import('./sheet.js').Sheet} Sheet */
+
+/**
+ * @typedef {Object} SheetStackOptions
+ * @property {'stack'|'cascade'} [layout='stack'] How depth is expressed. `stack` slides each
+ *   covered sheet back toward its edge and scales it down, leaving only the top one usable —
+ *   the drill-down feel. `cascade` shifts each covered sheet clear of the ones in front so they
+ *   sit side by side and all stay usable, which is what an ERP screen usually wants: the parent
+ *   record stays readable while a line item is edited.
+ * @property {number} [offset=24] Pixels a `stack` layout moves per depth step.
+ * @property {number} [scale=0.04] How much a `stack` layout shrinks per depth step, as a fraction.
+ * @property {number} [max=3] Depth at which a sheet stops being drawn. Deeper sheets stay open and
+ *   in the stack; they are simply no longer visible behind the ones in front.
+ * @property {(event: CustomEvent<{sheet: Sheet, depth: number}>) => void} [onpush] Push listener.
+ * @property {(event: CustomEvent<{sheet: Sheet}>) => void} [onpop] Pop listener.
+ */
+
+/**
+ * An ordered group of Sheets that read as one drill-down.
+ *
+ * Deliberately tiny, because the browser already does the hard part: nested dialogs stack in the
+ * top layer by open order, so there is no z-index bookkeeping here, and Escape closes only the
+ * topmost, so unwinding one level at a time is native behaviour rather than something to
+ * implement. What is left is bookkeeping — which sheet is at which depth — written onto the
+ * elements as `data-depth` and `--zx-sheet-depth` for CSS to interpret.
+ *
+ * Owns no element of its own, so it is a controller rather than a `Component`: there is nothing
+ * to render, only sheets to arrange.
+ *
+ * @fires SheetStack#push
+ * @fires SheetStack#pop
+ */
+export class SheetStack extends EventTarget {
+  /** @type {Readonly<SheetStackOptions>} */
+  static defaults = Object.freeze({
+    layout: 'stack',
+    offset: 24,
+    scale: 0.04,
+    max: 3
+  });
+
+  /** @type {Sheet[]} Bottom first; the last entry is the top of the stack. */
+  #sheets = [];
+  /** @type {WeakMap<Sheet, () => void>} */
+  #closers = new WeakMap();
+  #destroyed = false;
+
+  /**
+   * Creates a sheet stack.
+   * @param {SheetStackOptions} [options={}] Stack options.
+   */
+  constructor(options = {}) {
+    super();
+    const merged = { ...SheetStack.defaults, ...(options && typeof options === 'object' ? options : {}) };
+    for (const [key, value] of Object.entries(merged)) {
+      if (!/^on[a-z]/.test(key) || typeof value !== 'function') continue;
+      this.on(key.slice(2), value);
+      delete merged[key];
+    }
+    this.options = Object.freeze(merged);
+  }
+
+  /**
+   * Adds a sheet to the top of the stack, opening it if it is closed. A sheet already in the stack
+   * is raised rather than added twice.
+   * @param {Sheet} sheet Sheet to push.
+   * @returns {this}
+   * @fires SheetStack#push
+   */
+  push(sheet) {
+    if (!sheet || typeof sheet.open !== 'function') throw new TypeError('SheetStack.push expects a Sheet');
+    const existing = this.#sheets.indexOf(sheet);
+    if (existing !== -1) this.#sheets.splice(existing, 1);
+    this.#sheets.push(sheet);
+
+    if (!this.#closers.has(sheet)) {
+      // A sheet dismissed by Escape, its close button, or its own code leaves the stack too.
+      const onClose = () => this.#drop(sheet);
+      this.#closers.set(sheet, onClose);
+      sheet.on('close', onClose);
+    }
+    if (!sheet.isOpen()) sheet.open();
+    this.#sync();
+    this.#emit('push', { sheet, depth: 0 });
+    return this;
+  }
+
+  /**
+   * Closes the top sheet and removes it from the stack.
+   *
+   * The removal is synchronous while the close is not — a dialog dispatches `close` in a queued
+   * task — so the stack updates itself here rather than waiting for the event. The close listener
+   * is left to handle the other direction: a sheet dismissed by Escape or its own button.
+   * @returns {Sheet|null} The sheet that was closed, or null on an empty stack.
+   * @fires SheetStack#pop
+   */
+  pop() {
+    const sheet = this.top();
+    if (!sheet) return null;
+    this.#remove(sheet);
+    sheet.close();
+    return sheet;
+  }
+
+  /**
+   * Closes everything above a sheet, leaving it on top.
+   * @param {Sheet} sheet Sheet to return to.
+   * @returns {this}
+   */
+  popTo(sheet) {
+    const index = this.#sheets.indexOf(sheet);
+    if (index === -1) return this;
+    while (this.#sheets.length > index + 1) this.pop();
+    return this;
+  }
+
+  /**
+   * Closes every sheet, from the top down.
+   * @returns {this}
+   */
+  clear() {
+    while (this.#sheets.length > 0) this.pop();
+    return this;
+  }
+
+  /**
+   * The sheet currently on top.
+   * @returns {Sheet|null}
+   */
+  top() {
+    return this.#sheets[this.#sheets.length - 1] ?? null;
+  }
+
+  /**
+   * How many sheets the stack holds.
+   * @returns {number}
+   */
+  size() {
+    return this.#sheets.length;
+  }
+
+  /**
+   * The sheets, bottom first.
+   * @returns {Sheet[]}
+   */
+  sheets() {
+    return [...this.#sheets];
+  }
+
+  /**
+   * Whether a sheet is in this stack.
+   * @param {Sheet} sheet Sheet to look for.
+   * @returns {boolean}
+   */
+  has(sheet) {
+    return this.#sheets.includes(sheet);
+  }
+
+  /**
+   * Subscribes to a stack event.
+   * @param {string} type Event name.
+   * @param {(event: any) => void} fn Listener.
+   * @returns {this}
+   */
+  on(type, fn) {
+    this.addEventListener(type, fn);
+    return this;
+  }
+
+  /**
+   * Removes a stack event listener.
+   * @param {string} type Event name.
+   * @param {(event: any) => void} fn Listener.
+   * @returns {this}
+   */
+  off(type, fn) {
+    this.removeEventListener(type, fn);
+    return this;
+  }
+
+  /**
+   * Subscribes to one occurrence of a stack event.
+   * @param {string} type Event name.
+   * @param {(event: any) => void} fn Listener.
+   * @returns {this}
+   */
+  once(type, fn) {
+    this.addEventListener(type, fn, { once: true });
+    return this;
+  }
+
+  /**
+   * Empties the stack without closing anything. The sheets are not the stack's to destroy, so
+   * they are simply released with their depth styling removed.
+   * @returns {void}
+   */
+  destroy() {
+    if (this.#destroyed) return;
+    this.#destroyed = true;
+    for (const sheet of this.#sheets) {
+      const onClose = this.#closers.get(sheet);
+      if (onClose) sheet.off('close', onClose);
+      clearDepth(sheet);
+    }
+    this.#sheets = [];
+  }
+
+  /**
+   * Handles a sheet that closed on its own. A sheet popped through `pop()` has already been
+   * removed by the time its close event lands, so this is a no-op for that path.
+   * @param {Sheet} sheet Sheet that closed.
+   * @returns {void}
+   */
+  #drop(sheet) {
+    if (this.#sheets.includes(sheet)) this.#remove(sheet);
+  }
+
+  /**
+   * Takes a sheet out of the stack and re-numbers what is left.
+   * @param {Sheet} sheet Sheet to remove.
+   * @returns {void}
+   * @fires SheetStack#pop
+   */
+  #remove(sheet) {
+    const index = this.#sheets.indexOf(sheet);
+    if (index === -1) return;
+    this.#sheets.splice(index, 1);
+    const onClose = this.#closers.get(sheet);
+    if (onClose) sheet.off('close', onClose);
+    this.#closers.delete(sheet);
+    clearDepth(sheet);
+    this.#sync();
+    this.#emit('pop', { sheet });
+  }
+
+  /**
+   * Writes each sheet's depth, and for a cascade the distance it must clear.
+   * @returns {void}
+   */
+  #sync() {
+    const { layout, offset, scale, max } = this.options;
+    const cascade = layout === 'cascade';
+    /** Cumulative extent of the sheets in front of the one being positioned. */
+    let ahead = 0;
+
+    // Top first, so `ahead` accumulates from the front of the stack backwards.
+    for (let depth = 0; depth < this.#sheets.length; depth += 1) {
+      const sheet = this.#sheets[this.#sheets.length - 1 - depth];
+      const element = /** @type {HTMLElement} */ (sheet.el);
+      element.dataset.stack = cascade ? 'cascade' : 'stack';
+      element.dataset.depth = String(depth);
+      element.style.setProperty('--zx-sheet-depth', String(depth));
+      element.style.setProperty('--zx-sheet-stack-offset', `${Number(offset) || 0}px`);
+      element.style.setProperty('--zx-sheet-stack-scale', String(Number(scale) || 0));
+      element.toggleAttribute('data-stack-hidden', depth >= Math.max(1, Number(max) || 1));
+      /*
+       * A covered sheet in a drill-down is not just visually behind — it must leave the tab order
+       * too. The browser does that for stacked *modal* dialogs on its own, but a non-modal stack
+       * gets nothing, so the attribute is set either way.
+       */
+      element.inert = !cascade && depth > 0;
+      if (cascade) {
+        element.style.setProperty('--zx-sheet-depth-offset', `${ahead}px`);
+        ahead += sheet.getSize();
+      } else {
+        element.style.removeProperty('--zx-sheet-depth-offset');
+      }
+    }
+  }
+
+  /**
+   * @param {string} type
+   * @param {Record<string, unknown>} detail
+   * @returns {void}
+   */
+  #emit(type, detail) {
+    this.dispatchEvent(new CustomEvent(type, { detail }));
+  }
+}
+
+/**
+ * Fired after a sheet is pushed onto the stack.
+ * @event SheetStack#push
+ * @type {CustomEvent<{sheet: Sheet, depth: number}>}
+ */
+
+/**
+ * Fired after a sheet leaves the stack, however it was dismissed.
+ * @event SheetStack#pop
+ * @type {CustomEvent<{sheet: Sheet}>}
+ */
+
+/** @param {Sheet} sheet @returns {void} */
+function clearDepth(sheet) {
+  const element = /** @type {HTMLElement} */ (sheet.el);
+  if (!element) return;
+  delete element.dataset.stack;
+  delete element.dataset.depth;
+  element.removeAttribute('data-stack-hidden');
+  element.inert = false;
+  for (const property of [
+    '--zx-sheet-depth', '--zx-sheet-stack-offset', '--zx-sheet-stack-scale', '--zx-sheet-depth-offset'
+  ]) element.style.removeProperty(property);
+}