@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/focus.gts

@@ -0,0 +1,459 @@
+// Pretui — the focus / keyboard / owned-timer foundation.
+//
+// The single home of `focusWhen` and `rovingTabindex`; components import them
+// from here rather than keeping private copies.
+//
+// It also owns the two things the menu work needed and nobody had:
+//
+//  1. **Owned timers.** The realm law forbids *unowned* timers — handles that
+//     outlive the element that scheduled them. A `setTimeout` is permitted when
+//     an `ember-modifier` owns it and clears it in the destructor. `OwnedTimers`
+//     makes that ownership structural rather than a promise: nothing can be
+//     scheduled until `adopt()` has run, and `release()` clears every handle.
+//     `ownsTimers` is the modifier that calls both. A component that forgets
+//     to install the modifier does not leak — it simply never schedules, and
+//     every consumer here degrades to a working, timer-free behaviour.
+//
+//  2. **The safe triangle** (`inSafeTriangle`) — the diagonal-travel fix Ben
+//     Kamens described in "Breaking down Amazon's mega dropdown". Kept as
+//     PURE GEOMETRY, deliberately: it takes numbers and returns a boolean, so
+//     it is unit-testable without a DOM (see menu.test.gts) and reusable by
+//     anything else that opens a panel beside a hovered row.
+//
+// Nothing here reads `Date.now()` or `Math.random()` — those stay forbidden
+// for a different reason (indexing determinism), which the timer ruling does
+// not touch.
+import { modifier } from 'ember-modifier';
+
+// ── Roving focus ─────────────────────────────────────────────────────────
+
+/** Focuses the element only on the render where it BECAME the keyboard
+ * target — never steals focus on a plain re-render. */
+export const focusWhen = modifier((el: HTMLElement, [should]: [boolean]) => {
+  if (should) {
+    el.focus();
+  }
+});
+
+/** Roving tabindex, set as a property rather than an attribute: exactly one
+ * member of a composite is in the tab sequence, the rest are -1. Set as a
+ * property because the no-positive-tabindex lint rule cannot statically
+ * verify a dynamic template attribute. */
+export const rovingTabindex = modifier(
+  (el: HTMLElement, [active]: [boolean]) => {
+    el.tabIndex = active ? 0 : -1;
+  },
+);
+
+/** One delegated listener on a composite root, removed on cleanup. This is
+ * how a `role='tree'` / `role='menu'` container gets its keyboard without
+ * `{{on}}` on a non-interactive element (lint: no-invalid-interactive) and
+ * without one listener per node. */
+export const listen = modifier(
+  (el: HTMLElement, [type, handler]: [string, (event: Event) => void]) => {
+    el.addEventListener(type, handler);
+    return () => el.removeEventListener(type, handler);
+  },
+);
+
+/** A document-level listener whose lifetime is an element's lifetime. Used
+ * for outside-pointer dismissal and for the Alt/Option watch — both of which
+ * must hear events that never reach the overlay. Passive by default; pass
+ * `capture` for dismissal so a stopPropagation inside the page cannot
+ * strand an open overlay. */
+export const listenDocument = modifier(
+  (
+    _el: HTMLElement,
+    [type, handler, capture]: [
+      string,
+      (event: Event) => void,
+      boolean | undefined,
+    ],
+  ) => {
+    let options: AddEventListenerOptions = {
+      capture: capture ?? false,
+      passive: true,
+    };
+    document.addEventListener(type, handler, options);
+    return () => document.removeEventListener(type, handler, options);
+  },
+);
+
+/**
+ * A document-level listener in the CAPTURE phase, non-passive so the handler
+ * may `preventDefault`.
+ *
+ * This is how an open overlay takes ownership of a key. Handlers for one
+ * event type share a single listener that calls them newest first and stops
+ * at the first one that calls `stopPropagation`, so an Escape inside nested
+ * overlays closes only the innermost one.
+ */
+const captureStacks = new Map<string, ((event: Event) => void)[]>();
+
+function dispatchCapture(event: Event) {
+  let stack = captureStacks.get(event.type);
+  if (!stack) {
+    return;
+  }
+  for (let handler of [...stack].reverse()) {
+    handler(event);
+    if (event.cancelBubble) {
+      return;
+    }
+  }
+}
+
+export const listenDocumentCapture = modifier(
+  (_el: HTMLElement, [type, handler]: [string, (event: Event) => void]) => {
+    let stack = captureStacks.get(type);
+    if (!stack) {
+      stack = [];
+      captureStacks.set(type, stack);
+      document.addEventListener(type, dispatchCapture, true);
+    }
+    stack.push(handler);
+    return () => {
+      let current = captureStacks.get(type);
+      if (!current) {
+        return;
+      }
+      let at = current.lastIndexOf(handler);
+      if (at !== -1) {
+        current.splice(at, 1);
+      }
+      if (current.length === 0) {
+        captureStacks.delete(type);
+        document.removeEventListener(type, dispatchCapture, true);
+      }
+    };
+  },
+);
+
+// ── Owned timers ─────────────────────────────────────────────────────────
+
+/**
+ * A set of `setTimeout` handles whose owner is an `ember-modifier`.
+ *
+ * `after()` is inert until `adopt()` has been called and inert again after
+ * `release()`, so a handle can never outlive the element that owns it — the
+ * exact property the realm's no-unowned-timers law protects. Install
+ * `{{ownsTimers this.timers}}` on the element whose life the timers should
+ * share.
+ */
+export class OwnedTimers {
+  private handles = new Set<ReturnType<typeof setTimeout>>();
+  private owned = false;
+
+  /** Called by `ownsTimers`. */
+  adopt() {
+    this.owned = true;
+  }
+
+  /** Called by `ownsTimers`' destructor: clears every outstanding handle. */
+  release() {
+    this.owned = false;
+    this.clear();
+  }
+
+  /** True once a modifier has taken ownership — consumers branch on this to
+   * pick their timer-free degradation. */
+  get active(): boolean {
+    return this.owned;
+  }
+
+  /** Schedules `run` in `ms`. Returns a handle for `cancel`, or undefined
+   * when unowned (in which case nothing was scheduled). */
+  after(
+    ms: number,
+    run: () => void,
+  ): ReturnType<typeof setTimeout> | undefined {
+    if (!this.owned) {
+      return undefined;
+    }
+    let handle = setTimeout(() => {
+      this.handles.delete(handle);
+      run();
+    }, ms);
+    this.handles.add(handle);
+    return handle;
+  }
+
+  cancel(handle: ReturnType<typeof setTimeout> | undefined) {
+    if (handle !== undefined) {
+      clearTimeout(handle);
+      this.handles.delete(handle);
+    }
+  }
+
+  /** Clears every outstanding handle without giving up ownership. */
+  clear() {
+    for (let handle of this.handles) {
+      clearTimeout(handle);
+    }
+    this.handles.clear();
+  }
+}
+
+/** Ties an `OwnedTimers` set to the lifetime of the element it is installed
+ * on. This modifier IS the ownership the ruling requires. */
+export const ownsTimers = modifier(
+  (_el: HTMLElement, [timers]: [OwnedTimers]) => {
+    timers.adopt();
+    return () => timers.release();
+  },
+);
+
+// ── Type-ahead ───────────────────────────────────────────────────────────
+
+/**
+ * The multi-character type-ahead buffer the APG asks for: letters accumulate,
+ * and the buffer resets after `window` ms of no typing.
+ *
+ * Degradation is the point of the design. With owned timers the buffer is a
+ * real multi-character prefix ("pr" jumps to "Preferences"); without them it
+ * collapses to single-character cycling — which is what `Tree` shipped when
+ * timers were categorically forbidden, and is still a usable behaviour rather
+ * than a broken one.
+ */
+export class TypeaheadBuffer {
+  private text = '';
+  private handle: ReturnType<typeof setTimeout> | undefined;
+
+  constructor(
+    private timers: OwnedTimers,
+    /** ms of silence after which the buffer resets */
+    private window = 700,
+  ) {}
+
+  /** Adds a character and returns the prefix to search for. */
+  push(character: string): string {
+    if (!this.timers.active) {
+      this.text = character;
+      return this.text;
+    }
+    this.timers.cancel(this.handle);
+    this.text += character;
+    this.handle = this.timers.after(this.window, () => {
+      this.text = '';
+      this.handle = undefined;
+    });
+    return this.text;
+  }
+
+  /** True when the buffer is one character repeated — the APG's signal to
+   * CYCLE through matches on that character rather than narrow. */
+  get isCycling(): boolean {
+    return this.text.length > 1 && new Set(this.text).size === 1;
+  }
+
+  get value(): string {
+    return this.text;
+  }
+
+  reset() {
+    this.timers.cancel(this.handle);
+    this.handle = undefined;
+    this.text = '';
+  }
+}
+
+/**
+ * The index of the next item matching a type-ahead prefix, searching forward
+ * from `from` and wrapping. Returns -1 when nothing matches.
+ *
+ * `cycling` implements the APG rule: when the buffer is one repeated
+ * character, match on that single character and step to the NEXT match rather
+ * than staying on the current one.
+ */
+export function typeaheadIndex(
+  labels: string[],
+  prefix: string,
+  from: number,
+  cycling = false,
+): number {
+  let needle = (cycling ? prefix.slice(0, 1) : prefix).toLowerCase();
+  if (!needle) {
+    return -1;
+  }
+  // A narrowing (non-cycling) buffer may still match where it already is —
+  // "pr" after "p" must not skip past Preferences.
+  let start = cycling || prefix.length > 1 ? 0 : 1;
+  for (let step = start; step <= labels.length; step++) {
+    let index = (from + step) % labels.length;
+    if (labels[index]?.toLowerCase().startsWith(needle)) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+// ── The safe triangle ────────────────────────────────────────────────────
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/** The near vertical edge of an open submenu: the base of the safe triangle. */
+export interface SafeEdge {
+  x: number;
+  top: number;
+  bottom: number;
+}
+
+export interface RectLike {
+  left: number;
+  right: number;
+  top: number;
+  bottom: number;
+}
+
+/**
+ * The base of the safe triangle for a submenu occupying `rect`, opened on
+ * `side` of its parent item. The near edge is the one facing the pointer:
+ * a submenu opened to the RIGHT is approached across its LEFT edge.
+ *
+ * `tolerance` grows the edge vertically so a pointer aiming a few pixels
+ * above or below the panel still counts as travelling toward it.
+ */
+export function safeEdgeFor(
+  rect: RectLike,
+  side: 'right' | 'left',
+  tolerance = 10,
+): SafeEdge {
+  return {
+    x: side === 'right' ? rect.left : rect.right,
+    top: rect.top - tolerance,
+    bottom: rect.bottom + tolerance,
+  };
+}
+
+function cross(ax: number, ay: number, bx: number, by: number): number {
+  return ax * by - ay * bx;
+}
+
+/** Inclusive point-in-triangle by consistent sign of the three edge crosses. */
+export function pointInTriangle(
+  p: Point,
+  a: Point,
+  b: Point,
+  c: Point,
+): boolean {
+  let d1 = cross(p.x - a.x, p.y - a.y, b.x - a.x, b.y - a.y);
+  let d2 = cross(p.x - b.x, p.y - b.y, c.x - b.x, c.y - b.y);
+  let d3 = cross(p.x - c.x, p.y - c.y, a.x - c.x, a.y - c.y);
+  let hasNeg = d1 < 0 || d2 < 0 || d3 < 0;
+  let hasPos = d1 > 0 || d2 > 0 || d3 > 0;
+  return !(hasNeg && hasPos);
+}
+
+/**
+ * **The Amazon mega-dropdown rule.** True when the pointer's travel from
+ * `from` to `to` is aimed at the open submenu — i.e. `to` lies inside the
+ * triangle whose apex is `from` and whose base is the submenu's near `edge`.
+ *
+ * While this is true, a sibling item the pointer happens to cross must NOT
+ * take over the hover: the reader is travelling to the submenu, not choosing
+ * the row under the cursor. That diagonal is the single most common menu
+ * defect on the web, and the naive `mouseenter`-wins implementation makes the
+ * submenu flicker away exactly as it is reached for.
+ *
+ * A pointer that has not moved (`from` equals `to`) is not travelling
+ * anywhere: it returns false, which is what stops a stationary cursor from
+ * deferring the sibling forever.
+ */
+export function inSafeTriangle(
+  from: Point,
+  to: Point,
+  edge: SafeEdge,
+): boolean {
+  if (from.x === to.x && from.y === to.y) {
+    return false;
+  }
+  // Travelling AWAY from the submenu (past its near edge, on the wrong side)
+  // is never a safe-triangle case.
+  let towardRight = edge.x >= from.x;
+  if (towardRight ? to.x > edge.x : to.x < edge.x) {
+    return false;
+  }
+  return pointInTriangle(
+    to,
+    from,
+    { x: edge.x, y: edge.top },
+    { x: edge.x, y: edge.bottom },
+  );
+}
+
+/**
+ * Pointer position tracking for the safe triangle, plus the submenu edge it
+ * is measured against. The component holds one of these; `tracksPointer`
+ * gives it its listener and its lifetime.
+ */
+export class PointerTrack {
+  private previous: Point | undefined;
+  private current: Point | undefined;
+  private moves = 0;
+  /** The open submenu's near edge, set when the submenu opens/resizes. */
+  edge: SafeEdge | undefined;
+
+  /** Increments on every pointer move. A consumer that defers on the strength
+   * of `travellingToSubmenu` must record this stamp and refuse to defer twice
+   * on the SAME move — otherwise a pointer that stops inside the triangle
+   * defers forever, which is both a stuck menu and a timer that re-arms
+   * without end (Kamens guards the same case with `lastDelayLoc`). */
+  get stamp(): number {
+    return this.moves;
+  }
+
+  record(x: number, y: number) {
+    this.previous = this.current;
+    this.current = { x, y };
+    this.moves++;
+  }
+
+  /** True while the pointer is travelling toward the open submenu. */
+  get travellingToSubmenu(): boolean {
+    if (!this.edge || !this.previous || !this.current) {
+      return false;
+    }
+    return inSafeTriangle(this.previous, this.current, this.edge);
+  }
+
+  clear() {
+    this.previous = undefined;
+    this.current = undefined;
+    this.edge = undefined;
+  }
+}
+
+/**
+ * Owns the `pointermove` listener feeding a `PointerTrack`, and removes it on
+ * teardown. `pointermove` rather than `mousemove` so pens and touch report
+ * too; passive because the handler only reads coordinates. Listening on
+ * `document` (not the panel) keeps the track continuous across the gap
+ * between a menu and its submenu.
+ */
+export const tracksPointer = modifier(
+  (_el: HTMLElement, [track]: [PointerTrack]) => {
+    let onMove = (event: Event) => {
+      let pointer = event as PointerEvent;
+      track.record(pointer.clientX, pointer.clientY);
+    };
+    document.addEventListener('pointermove', onMove, { passive: true });
+    return () => {
+      document.removeEventListener('pointermove', onMove);
+      track.clear();
+    };
+  },
+);
+
+/** Elements that own the keys a container would otherwise take: text entry
+ *  and composite widgets. A container's keydown handler skips events whose
+ *  target is inside one. */
+export const OWNS_KEYS =
+  'input, textarea, select, [contenteditable=""], [contenteditable="true"], [role="textbox"], [role="slider"], [role="spinbutton"], [role="listbox"], [role="combobox"], [role="menu"], [role="tree"], [role="grid"]';
+
+/** Elements whose press is their own: a container's pointer gesture skips
+ *  presses that start inside one. */
+export const OWNS_PRESS =
+  'a[href], button, input, select, textarea, label, summary, [role="button"], [role="link"], [contenteditable=""], [contenteditable="true"]';

package/bundled-realms/pretui/gridstack/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019-2025 Alain Dumesny. v0.4.0 and older (c) 2014-2018 Pavel Reznikov, Dylan Weiss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bundled-realms/pretui/gridstack/README.md

@@ -0,0 +1,103 @@
+# gridstack/ — gridstack.js, vendored
+
+`index.js` is [gridstack.js](https://github.com/gridstack/gridstack.js) bundled
+to a single self-contained ES module. gridstack has **zero runtime
+dependencies**, so nothing had to be inlined and no bare specifier survives —
+the realm loader resolves the whole engine from this one file.
+
+## Provenance
+
+| | |
+|---|---|
+| **Source** | local checkout, **not** npm |
+| **Commit** | `d9c9bc41e73fd1a0164bf6760f2834269d0cf8af` (`git describe`: `v13.1.2-18-gd9c9bc41`, working tree clean, authored 2026-08-10) |
+| **Version** | `package.json` says **13.1.2**; the commit is **18 ahead** of that tag |
+| **Licence** | **MIT** (SPDX `MIT`) — verified by reading the repo's `LICENSE`: "MIT License / Copyright (c) 2019-2025 Alain Dumesny. v0.4.0 and older (c) 2014-2018 Pavel Reznikov, Dylan Weiss"; the full notice ships beside the bundle as `LICENSE` |
+| **Size** | 87 KB minified / 24 KB gzipped |
+
+Three commits land in `src/` between the tag and this one, and one of them is
+directly load-bearing here: **`c1d0978d` "fix: detach resize-handle document
+listeners on destroy before move threshold"** — a listener leak on the exact
+teardown path this component drives from a modifier destructor. Bundling the
+published 13.1.2 would have shipped that leak.
+
+**The trade-off, stated:** an untagged commit does not correspond to any
+published release, so "gridstack 13.1.2" is not enough to reproduce these
+bytes. The SHA above is what makes it reproducible — never omit it, and
+re-record it on every rebuild.
+
+**No build step was skipped.** gridstack publishes TypeScript source in `src/`
+and its npm `main` points at a webpack UMD build; the recipe below compiles
+the TypeScript directly with esbuild, so bundling from a checkout needs
+nothing the published package would have done for us. There was no fallback
+to npm.
+
+Exported (a lean entry — not gridstack's full `export *` surface):
+
+    GridStack        the DOM grid: init, makeWidget, removeWidget, update,
+                     save, column, cellHeight, margin, float, setAnimation,
+                     batchUpdate, on/off, destroy
+    GridStackEngine  the DOM-FREE layout engine: collision resolution,
+                     packing, float, column re-flow
+    Utils            gridstack's own helpers (kept for `Utils.getElement`)
+
+Built with, from the checkout root:
+
+    esbuild lean.ts --bundle --format=esm --minify --line-limit=500 \
+      --legal-comments=none --target=es2022 \
+      --banner:js="/*! gridstack.js 13.1.2+18 (d9c9bc41) | SPDX-License-Identifier: MIT | Copyright (c) 2019-2025 Alain Dumesny | https://gridstackjs.com | see ./LICENSE */" \
+      --outfile=index.js
+
+where `lean.ts` is three re-export lines pointing at that checkout's
+`src/gridstack`, `src/gridstack-engine` and `src/utils`.
+
+## Six things to know before using it
+
+- **Import is DOM-free.** Evaluating this module touches no DOM API (verified
+  under plain Node: `dd-touch`'s `isTouch` probe is guarded by
+  `typeof window !== 'undefined' && typeof document !== 'undefined'`), so it is
+  safe anywhere in the realm graph. `GridStack.init()` needs `document` and may
+  only be called from an `ember-modifier` or other browser context.
+
+- **`GridStackEngine` runs headless.** `new GridStackEngine({column, float})`
+  plus `addNode()` resolves collisions and packs with no DOM at all. That is
+  what lets read-only mode and the unit tests share one layout truth with the
+  interactive grid. Use it for anything that only needs coordinates.
+
+- **The stylesheet is NOT bundled.** `src/gridstack.scss` is not imported by
+  the TS sources, and a side-effect CSS import would fail realm indexing (the
+  loader parses CSS as JS). The engine-required rules are restated in Pretui
+  tokens in `../structure-dashboard-css.ts` and injected into `document.head`
+  by a refcounted modifier. Only what the engine genuinely needs is kept —
+  absolute positioning, the `--gs-*` variable contract, the placeholder and
+  the resize handle. gridstack's own look (grey placeholder, grey SVG arrow
+  handle, print rules, rtl loop, `!important` blocks) is dropped.
+
+- **Timers are the engine's, and are owned.** gridstack schedules
+  `setTimeout`s around drag/animation and one `requestAnimationFrame`
+  auto-scroll loop while dragging; both are cancelled on drag end. That is
+  legal in a realm because the modifier that creates the instance calls `grid.destroy(false)` in its destructor.
+  **Always pass `false`** — `destroy(true)` removes the container from the
+  DOM, which is Glimmer's node.
+
+- **`auto: false` at init is mandatory here.** Item elements already exist
+  (Glimmer rendered them, and child modifiers install before parent ones), so
+  letting gridstack auto-adopt `.grid-stack-item` children would race the
+  explicit `makeWidget()` registration. See the DOM-ownership header in
+  `../internal/structure-dashboard.gts`.
+
+- **`_sortDom()` must be neutralised.** After every change gridstack
+  re-`appendChild`s each item so DOM order matches visual order. There is no
+  option for it, it moves nodes Glimmer owns and has bounds for, and moving a
+  node blurs anything focused inside it — which killed the keyboard move path
+  on its very first arrow key. `internal/structure-dashboard.gts` overrides the method
+  per instance and says why; the render proof asserts focus survives an
+  engine move, so a future upgrade cannot quietly undo it.
+
+## Not wired
+
+`acceptWidgets` / drag between grids, nested subgrids, `lazyLoad`,
+`sizeToContent`, `removable` trash zones, `columnOpts` responsive breakpoints
+(Pretui owns its own `ResizeObserver` so gridstack never installs one of its
+own), and `GridStack.addGrid()` / `load()` markup generation — all of the
+paths where gridstack would create or destroy DOM Glimmer believes it owns.