@zeyos/zx 2.3.0 → 4.0.0

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);
+}

package/src/components/sheet/sheet.css

@@ -0,0 +1,351 @@
+/*
+ * Sheet builds on `.zx-modal` and `.zx-dialog`, so this file must be imported after both: the
+ * overrides below share their specificity and win on source order alone.
+ */
+.zx-sheet {
+  position: fixed;
+  margin: 0;
+  padding: 0;
+  max-inline-size: 100vw;
+  max-block-size: 100dvh;
+  border: 0;
+  border-radius: 0;
+  /* The header and footer stay put; `.zx-dialog__body` is what scrolls. */
+  overflow: hidden;
+  box-shadow: var(--zx-overlay-shadow);
+}
+
+/* Horizontal sheets: full height, sized across the inline axis. */
+.zx-sheet[data-side="start"],
+.zx-sheet[data-side="end"] {
+  inset-block: 0;
+  block-size: 100dvh;
+  inline-size: var(--zx-sheet-size, min(24rem, 100vw));
+}
+
+.zx-sheet[data-side="start"] {
+  inset-inline-start: 0;
+  inset-inline-end: auto;
+  border-inline-end: 1px solid var(--zx-color-border);
+  --zx-sheet-enter: -100% 0;
+}
+
+.zx-sheet[data-side="end"] {
+  inset-inline-start: auto;
+  inset-inline-end: 0;
+  border-inline-start: 1px solid var(--zx-color-border);
+  --zx-sheet-enter: 100% 0;
+}
+
+/*
+ * `translate` is physical, so the logical sides need the one direction-aware rule in the library.
+ * Attribute rather than `:dir()` because the latter only reached Chrome in December 2023, at the
+ * very edge of the supported baseline, and this is the sole place it would buy anything.
+ */
+[dir="rtl"] .zx-sheet[data-side="start"] { --zx-sheet-enter: 100% 0; }
+[dir="rtl"] .zx-sheet[data-side="end"] { --zx-sheet-enter: -100% 0; }
+
+/* Vertical sheets: full width, sized down the block axis, inner corners rounded like a drawer. */
+.zx-sheet[data-side="top"],
+.zx-sheet[data-side="bottom"] {
+  inset-inline: 0;
+  inline-size: 100vw;
+  block-size: var(--zx-sheet-size, min(60dvh, 100dvh));
+}
+
+.zx-sheet[data-side="top"] {
+  inset-block-start: 0;
+  inset-block-end: auto;
+  border-block-end: 1px solid var(--zx-color-border);
+  border-end-start-radius: var(--zx-sheet-radius, var(--zx-radius-xl));
+  border-end-end-radius: var(--zx-sheet-radius, var(--zx-radius-xl));
+  --zx-sheet-enter: 0 -100%;
+}
+
+.zx-sheet[data-side="bottom"] {
+  inset-block-start: auto;
+  inset-block-end: 0;
+  border-block-start: 1px solid var(--zx-color-border);
+  border-start-start-radius: var(--zx-sheet-radius, var(--zx-radius-xl));
+  border-start-end-radius: var(--zx-sheet-radius, var(--zx-radius-xl));
+  --zx-sheet-enter: 0 100%;
+}
+
+/*
+ * Backdrop treatments. Only a modal sheet has a `::backdrop` at all, which is why `backdrop` is
+ * documented as meaningful only alongside `modal: true`.
+ */
+.zx-sheet[data-backdrop="none"]::backdrop {
+  background: transparent;
+}
+
+.zx-sheet[data-backdrop="blur"]::backdrop {
+  backdrop-filter: blur(var(--zx-overlay-blur));
+}
+
+/*
+ * Entry and exit both animate. A `<dialog>` normally cannot animate out — `close()` applies
+ * `display: none` immediately — so `display` and `overlay` transition with `allow-discrete`, which
+ * defers the discrete jump until the rest of the transition has finished. `@starting-style` gives
+ * the entry its from-state. Where either is unsupported the sheet simply appears and disappears.
+ */
+@media (prefers-reduced-motion: no-preference) {
+  .zx-sheet {
+    transition:
+      translate var(--zx-dur-base) var(--zx-ease),
+      opacity var(--zx-dur-base) var(--zx-ease),
+      display var(--zx-dur-base) allow-discrete,
+      overlay var(--zx-dur-base) allow-discrete;
+  }
+
+  /* Modal's entry keyframes animate the centre-screen case and would fight the slide. */
+  .zx-sheet[data-state="open"] {
+    animation: none;
+  }
+
+  .zx-sheet:not([open]) {
+    translate: var(--zx-sheet-enter, 0 0);
+    opacity: 0;
+  }
+
+  @starting-style {
+    .zx-sheet[open] {
+      translate: var(--zx-sheet-enter, 0 0);
+      opacity: 0;
+    }
+  }
+
+  .zx-sheet::backdrop {
+    transition:
+      opacity var(--zx-dur-base) var(--zx-ease),
+      display var(--zx-dur-base) allow-discrete,
+      overlay var(--zx-dur-base) allow-discrete;
+  }
+
+  .zx-sheet[data-state="open"]::backdrop {
+    animation: none;
+  }
+
+  .zx-sheet:not([open])::backdrop {
+    opacity: 0;
+  }
+
+  @starting-style {
+    .zx-sheet[open]::backdrop {
+      opacity: 0;
+    }
+  }
+}
+
+/*
+ * A docked sheet is a track in its dock's flow, not an overlay: it drops out of fixed positioning
+ * and takes its size from the dock's own custom property, the same one the dock's panes use. It is
+ * always non-modal while docked, so there is no backdrop to consider.
+ *
+ * Closing animates the track to zero rather than sliding the sheet away — in the flow there is
+ * nowhere to slide to, and collapsing the space is what the surrounding layout should see.
+ */
+.zx-sheet[data-docked] {
+  position: relative;
+  inset: auto;
+  flex: 0 0 var(--zx-pane-size, var(--zx-sheet-size, min(24rem, 100%)));
+  inline-size: auto;
+  block-size: auto;
+  max-inline-size: none;
+  max-block-size: none;
+  min-inline-size: 0;
+  min-block-size: 0;
+  border-radius: 0;
+  box-shadow: none;
+}
+
+.zx-dock[data-orientation="vertical"] > .zx-sheet[data-docked] {
+  border-inline: 0;
+  border-block: 1px solid var(--zx-color-border);
+}
+
+.zx-dock[data-orientation="horizontal"] > .zx-sheet[data-docked] {
+  border-block: 0;
+  border-inline: 1px solid var(--zx-color-border);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .zx-sheet[data-docked] {
+    transition:
+      flex-basis var(--zx-dur-base) var(--zx-ease),
+      opacity var(--zx-dur-base) var(--zx-ease),
+      display var(--zx-dur-base) allow-discrete,
+      overlay var(--zx-dur-base) allow-discrete;
+    /* The slide belongs to the overlay life; in the flow the track itself is what moves. */
+    translate: none;
+  }
+
+  .zx-sheet[data-docked]:not([open]) {
+    flex-basis: 0;
+    translate: none;
+    opacity: 0;
+  }
+
+  @starting-style {
+    .zx-sheet[data-docked][open] {
+      flex-basis: 0;
+      translate: none;
+      opacity: 0;
+    }
+  }
+}
+
+/*
+ * The grab handle sits just inside the sheet's inner edge — the one facing the page. It is a
+ * `separator` with live values, so it is draggable, focusable, and steppable with the arrow keys.
+ * The hit area is deliberately wider than the pill it draws.
+ */
+.zx-sheet__handle {
+  position: absolute;
+  z-index: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  touch-action: none;
+  user-select: none;
+}
+
+.zx-sheet__handle::after {
+  content: "";
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-border-strong);
+  opacity: 0;
+  transition: opacity var(--zx-dur-fast) var(--zx-ease);
+}
+
+.zx-sheet__handle:hover::after,
+.zx-sheet__handle:focus-visible::after,
+.zx-sheet[data-dragging] .zx-sheet__handle::after {
+  opacity: 1;
+}
+
+.zx-sheet__handle:focus-visible {
+  outline: none;
+  box-shadow: var(--zx-focus-ring);
+}
+
+/* Inner edge for each side, and the pill drawn across it. */
+.zx-sheet[data-side="start"] > .zx-sheet__handle,
+.zx-sheet[data-side="end"] > .zx-sheet__handle {
+  inset-block: 0;
+  inline-size: var(--zx-space-3);
+  cursor: col-resize;
+}
+
+.zx-sheet[data-side="start"] > .zx-sheet__handle { inset-inline-end: 0; }
+.zx-sheet[data-side="end"] > .zx-sheet__handle { inset-inline-start: 0; }
+
+.zx-sheet[data-side="start"] > .zx-sheet__handle::after,
+.zx-sheet[data-side="end"] > .zx-sheet__handle::after {
+  inline-size: 3px;
+  block-size: var(--zx-space-8);
+}
+
+.zx-sheet[data-side="top"] > .zx-sheet__handle,
+.zx-sheet[data-side="bottom"] > .zx-sheet__handle {
+  inset-inline: 0;
+  block-size: var(--zx-space-4);
+  cursor: row-resize;
+}
+
+.zx-sheet[data-side="top"] > .zx-sheet__handle { inset-block-end: 0; }
+.zx-sheet[data-side="bottom"] > .zx-sheet__handle { inset-block-start: 0; }
+
+.zx-sheet[data-side="top"] > .zx-sheet__handle::after,
+.zx-sheet[data-side="bottom"] > .zx-sheet__handle::after {
+  inline-size: var(--zx-space-8);
+  block-size: 4px;
+}
+
+/* A drawer's handle is a standing invitation, so it does not wait to be hovered. */
+.zx-sheet[data-side="top"] > .zx-sheet__handle::after,
+.zx-sheet[data-side="bottom"] > .zx-sheet__handle::after {
+  opacity: 1;
+}
+
+/* A docked sheet is resized by the dock's divider, so its own handle stands down. */
+.zx-sheet[data-docked] > .zx-sheet__handle {
+  display: none;
+}
+
+/* Nothing may animate while the pointer is driving the size, or the sheet lags behind it. */
+.zx-sheet[data-dragging] {
+  transition: none;
+}
+
+/*
+ * Stacking. Depth is written by `SheetStack` as `--zx-sheet-depth`; the direction it moves in is
+ * a per-side unit vector pointing at the sheet's own edge, so one rule covers all four sides.
+ *
+ * `transform` rather than `translate`, because the enter and exit animation already owns
+ * `translate` — the two are independent properties and compose, so a sheet can slide in and sit at
+ * a depth at the same time.
+ */
+.zx-sheet[data-side="start"] { --zx-sheet-dx: -1; --zx-sheet-dy: 0; }
+.zx-sheet[data-side="end"] { --zx-sheet-dx: 1; --zx-sheet-dy: 0; }
+.zx-sheet[data-side="top"] { --zx-sheet-dx: 0; --zx-sheet-dy: -1; }
+.zx-sheet[data-side="bottom"] { --zx-sheet-dx: 0; --zx-sheet-dy: 1; }
+
+/* Scaling a covered sheet shrinks it toward its own edge, so it never unglues from it. */
+.zx-sheet[data-side="start"] { transform-origin: left center; }
+.zx-sheet[data-side="end"] { transform-origin: right center; }
+.zx-sheet[data-side="top"] { transform-origin: center top; }
+.zx-sheet[data-side="bottom"] { transform-origin: center bottom; }
+
+.zx-sheet[data-stack="stack"] {
+  transform:
+    translate(
+      calc(var(--zx-sheet-dx, 0) * var(--zx-sheet-depth, 0) * var(--zx-sheet-stack-offset, 24px)),
+      calc(var(--zx-sheet-dy, 0) * var(--zx-sheet-depth, 0) * var(--zx-sheet-stack-offset, 24px))
+    )
+    scale(calc(1 - var(--zx-sheet-depth, 0) * var(--zx-sheet-stack-scale, 0.04)));
+}
+
+/* A cascade moves each covered sheet clear of everything in front of it, so all stay readable. */
+.zx-sheet[data-stack="cascade"] {
+  transform: translate(
+    calc(var(--zx-sheet-dx, 0) * var(--zx-sheet-depth-offset, 0px) * -1),
+    calc(var(--zx-sheet-dy, 0) * var(--zx-sheet-depth-offset, 0px) * -1)
+  );
+}
+
+/* Past `max` a sheet stays open and in the stack, but stops being drawn. */
+.zx-sheet[data-stack-hidden] {
+  opacity: 0;
+  pointer-events: none;
+}
+
+/*
+ * Only the topmost backdrop shades the page — one per depth would compound into black.
+ */
+.zx-sheet[data-depth]:not([data-depth="0"])::backdrop {
+  background: transparent;
+  backdrop-filter: none;
+}
+
+/*
+ * A cascade shades nothing at all. Its whole point is that the covered sheets stay readable and
+ * usable beside the top one, and a backdrop is painted directly beneath its own dialog in the top
+ * layer — so the topmost sheet's backdrop would dim exactly the sheets the layout exists to keep
+ * available. Pair a cascade with `modal: false` when the page behind should stay live too.
+ */
+.zx-sheet[data-stack="cascade"]::backdrop {
+  background: transparent;
+  backdrop-filter: none;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .zx-sheet[data-stack] {
+    transition:
+      transform var(--zx-dur-base) var(--zx-ease),
+      translate var(--zx-dur-base) var(--zx-ease),
+      opacity var(--zx-dur-base) var(--zx-ease),
+      display var(--zx-dur-base) allow-discrete,
+      overlay var(--zx-dur-base) allow-discrete;
+  }
+}