stimeo-ui 0.2.0 → 0.2.1

data/dist/controllers/masonry_controller.js

@@ -0,0 +1,142 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/masonry_controller.ts
+
+// src/utils/layout_observer.ts
+var LayoutObserver = class {
+  #callback;
+  #resizeObserverFactory;
+  #resizeObserver = null;
+  #observingViewport = false;
+  /** Stable bound handler so add/removeEventListener target the same reference. */
+  #handleViewportResize = () => {
+    this.#callback();
+  };
+  constructor(callback, options = {}) {
+    this.#callback = callback;
+    this.#resizeObserverFactory = options.resizeObserverFactory ?? (typeof ResizeObserver === "undefined" ? null : (cb) => new ResizeObserver(cb));
+  }
+  /**
+   * Starts observing an element's size. Repeated calls observe additional
+   * elements through the same shared observer. No-ops when no
+   * `ResizeObserver` implementation is available.
+   */
+  observe(element) {
+    if (!this.#resizeObserverFactory) return;
+    if (!this.#resizeObserver) {
+      this.#resizeObserver = this.#resizeObserverFactory(() => {
+        this.#callback();
+      });
+    }
+    this.#resizeObserver.observe(element);
+  }
+  /** Stops observing a single element while leaving any others in place. */
+  unobserve(element) {
+    this.#resizeObserver?.unobserve(element);
+  }
+  /** Starts observing viewport resizes. Idempotent: the listener is added once. */
+  observeViewport() {
+    if (this.#observingViewport) return;
+    this.#observingViewport = true;
+    window.addEventListener("resize", this.#handleViewportResize);
+  }
+  /** Stops observing viewport resizes without affecting element observation. */
+  unobserveViewport() {
+    if (!this.#observingViewport) return;
+    this.#observingViewport = false;
+    window.removeEventListener("resize", this.#handleViewportResize);
+  }
+  /**
+   * Releases every observation: disconnects the {@link ResizeObserver} and
+   * removes the viewport listener. Safe to call multiple times. Call this from a
+   * controller's `disconnect()`.
+   */
+  disconnect() {
+    this.#resizeObserver?.disconnect();
+    this.#resizeObserver = null;
+    this.unobserveViewport();
+  }
+};
+
+// src/controllers/masonry_controller.ts
+var COLUMNS_PROPERTY = "--stimeo-masonry-columns";
+var MasonryController = class extends Controller {
+  static targets = ["item"];
+  static values = {
+    minColumnWidth: { type: Number, default: 240 },
+    gap: { type: Number, default: 16 }
+  };
+  static events = ["layout"];
+  #layout = new LayoutObserver(() => this.#relayout());
+  #mutationObserver = null;
+  /** Last published column count, so `layout` fires only on real changes. */
+  #lastColumns = 0;
+  /**
+   * Re-pack when a descendant resource finishes loading. Images/iframes report a
+   * height of 0 until loaded, which would skew the shortest-column packing if the
+   * first pass ran before they settled; `load` does not bubble, so this is bound in
+   * the capture phase to catch every descendant.
+   */
+  #onLoad = () => this.#relayout();
+  /** Observes size/content changes and performs the first layout pass. */
+  connect() {
+    this.#layout.observe(this.element);
+    this.#layout.observeViewport();
+    if (typeof MutationObserver !== "undefined") {
+      this.#mutationObserver = new MutationObserver(() => this.#relayout());
+      this.#mutationObserver.observe(this.element, { childList: true, subtree: true });
+    }
+    this.element.addEventListener("load", this.#onLoad, true);
+    this.#relayout();
+  }
+  /** Releases both observers and the load listener so nothing fires after detach. */
+  disconnect() {
+    this.#layout.disconnect();
+    this.#mutationObserver?.disconnect();
+    this.#mutationObserver = null;
+    this.element.removeEventListener("load", this.#onLoad, true);
+    this.#lastColumns = 0;
+  }
+  /**
+   * Recomputes the column count and assigns every item to the shortest column.
+   * Runs automatically on connect, on resize, on item add/remove, and when a
+   * descendant resource loads (private — there is no public action; the observers
+   * and the capture-phase `load` listener drive it). Items are walked in DOM
+   * order; each lands in the column with the least accumulated height, which
+   * keeps the packing balanced without reordering the DOM.
+   */
+  #relayout() {
+    const items = this.itemTargets;
+    const columns = this.#columnCount();
+    const heights = new Array(columns).fill(0);
+    for (const item of items) {
+      let shortest = 0;
+      for (let col = 1; col < columns; col++) {
+        if ((heights[col] ?? 0) < (heights[shortest] ?? 0)) shortest = col;
+      }
+      item.setAttribute("data-column", String(shortest));
+      heights[shortest] = (heights[shortest] ?? 0) + item.getBoundingClientRect().height + this.gapValue;
+    }
+    this.element.style.setProperty(COLUMNS_PROPERTY, String(columns));
+    if (columns !== this.#lastColumns) {
+      this.#lastColumns = columns;
+      this.dispatch("layout", { detail: { columns } });
+    }
+  }
+  /**
+   * Derives how many columns fit: `floor((width + gap) / (minColumnWidth + gap))`,
+   * never fewer than one. When the width is unmeasurable (detached, or a layout
+   * engine that reports `0`), it falls back to a single column so every item still
+   * gets a valid `data-column`.
+   */
+  #columnCount() {
+    const width = this.element.getBoundingClientRect().width;
+    const denominator = this.minColumnWidthValue + this.gapValue;
+    if (width <= 0 || denominator <= 0) return 1;
+    return Math.max(1, Math.floor((width + this.gapValue) / denominator));
+  }
+};
+
+export { MasonryController };
+//# sourceMappingURL=masonry_controller.js.map
+//# sourceMappingURL=masonry_controller.js.map

data/dist/controllers/menubar_controller.js

@@ -0,0 +1,433 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/menubar_controller.ts
+
+// src/utils/escape_layer.ts
+function claimsWhileFocusWithin(element) {
+  return () => {
+    const active = element.ownerDocument.activeElement;
+    return active === null || active === element.ownerDocument.body || element.contains(active);
+  };
+}
+var EscapeLayer = class _EscapeLayer {
+  static #registries = /* @__PURE__ */ new WeakMap();
+  #ownerDocument = null;
+  /** Dismissal callback while active; `null` when inactive. */
+  #onDismiss = null;
+  /** Live predicate deciding whether the layer claims a press; `null` = always. */
+  #claims = null;
+  /**
+   * Activates this layer at the top of its document's Escape stack, installing
+   * the document's shared resolver listener if this is its first layer.
+   * Re-activating an already-active layer moves it to the top.
+   */
+  activate(ownerDocument = document, options) {
+    this.deactivate();
+    let registry = _EscapeLayer.#registries.get(ownerDocument);
+    if (!registry) {
+      registry = _EscapeLayer.#createRegistry();
+      _EscapeLayer.#registries.set(ownerDocument, registry);
+      ownerDocument.addEventListener("keydown", registry.onKeydown);
+    }
+    registry.stack.push(this);
+    this.#ownerDocument = ownerDocument;
+    this.#onDismiss = options.onDismiss;
+    this.#claims = options.claims ?? null;
+  }
+  /**
+   * Removes this layer from its document's Escape stack, uninstalling the
+   * shared listener when the stack empties. Safe to call when inactive.
+   */
+  deactivate() {
+    const ownerDocument = this.#ownerDocument;
+    if (!ownerDocument) return;
+    const registry = _EscapeLayer.#registries.get(ownerDocument);
+    if (registry) {
+      const index = registry.stack.lastIndexOf(this);
+      if (index >= 0) registry.stack.splice(index, 1);
+      if (registry.stack.length === 0) {
+        ownerDocument.removeEventListener("keydown", registry.onKeydown);
+        _EscapeLayer.#registries.delete(ownerDocument);
+      }
+    }
+    this.#ownerDocument = null;
+    this.#onDismiss = null;
+    this.#claims = null;
+  }
+  /**
+   * Whether this active layer would own a press right now: it is the topmost
+   * layer whose {@link EscapeLayerOptions.claims} passes. Exposed for tests
+   * and diagnostics — production dismissal goes through the shared listener.
+   */
+  get ownsEscape() {
+    const ownerDocument = this.#ownerDocument;
+    if (!ownerDocument) return false;
+    const registry = _EscapeLayer.#registries.get(ownerDocument);
+    if (!registry) return false;
+    return _EscapeLayer.#resolveOwner(registry.stack) === this;
+  }
+  /** Builds a document's registry with its shared resolver listener. */
+  static #createRegistry() {
+    const registry = {
+      stack: [],
+      onKeydown: (event) => {
+        if (event.key !== "Escape" || event.defaultPrevented || event.isComposing) return;
+        const owner = _EscapeLayer.#resolveOwner(registry.stack);
+        if (!owner) return;
+        event.preventDefault();
+        owner.#onDismiss?.();
+      }
+    };
+    return registry;
+  }
+  /** The topmost stack layer whose claims predicate passes, or `null`. */
+  static #resolveOwner(stack) {
+    for (let index = stack.length - 1; index >= 0; index--) {
+      const layer = stack[index];
+      if (!layer) continue;
+      if (layer.#claims && !layer.#claims()) continue;
+      return layer;
+    }
+    return null;
+  }
+};
+
+// src/utils/roving_tabindex.ts
+var RovingTabindex = class {
+  /** Returns the current ordered item elements; called on every operation. */
+  #getItems;
+  /**
+   * @param getItems - Returns the current ordered item elements. Called on every
+   *   operation so the live target list is always used.
+   */
+  constructor(getItems) {
+    this.#getItems = getItems;
+  }
+  /** Index of the currently tabbable item (`tabindex="0"`), or `-1` if none. */
+  get activeIndex() {
+    return this.#getItems().findIndex((item) => item.tabIndex === 0);
+  }
+  /**
+   * Makes exactly the item at `index` tabbable (`tabindex="0"`) and removes every
+   * other item from the Tab sequence (`tabindex="-1"`). An out-of-range `index`
+   * (e.g. `-1`) leaves all items at `-1`, which a controller can use to express
+   * "nothing is currently tabbable".
+   *
+   * @param index - Position of the item to make tabbable.
+   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.
+   */
+  setActive(index, { focus = false } = {}) {
+    const items = this.#getItems();
+    items.forEach((item, i) => {
+      item.tabIndex = i === index ? 0 : -1;
+    });
+    if (focus) items[index]?.focus();
+  }
+};
+
+// src/utils/safe_timeout.ts
+var TimerRegistry = class {
+  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
+  ids = /* @__PURE__ */ new Set();
+  /**
+   * Cancels a single tracked timer.
+   *
+   * No-ops if the id is unknown (already cleared, fired, or never owned by this
+   * registry), so callers can clear defensively without guarding.
+   */
+  clear(id) {
+    if (this.ids.delete(id)) {
+      this.cancel(id);
+    }
+  }
+  /**
+   * Cancels every tracked timer. Call this from a controller's `disconnect()`
+   * to guarantee no timer outlives the element.
+   */
+  clearAll() {
+    for (const id of this.ids) {
+      this.cancel(id);
+    }
+    this.ids.clear();
+  }
+  /** Number of timers currently tracked (pending). */
+  get size() {
+    return this.ids.size;
+  }
+};
+var SafeTimeout = class extends TimerRegistry {
+  /**
+   * Schedules `callback` after `delay` ms and returns the timer id.
+   *
+   * The id is removed from the registry automatically when the timeout fires,
+   * so {@link TimerRegistry.size | size} reflects only still-pending timers.
+   */
+  set(callback, delay) {
+    const id = this.schedule(() => {
+      this.ids.delete(id);
+      callback();
+    }, delay);
+    this.ids.add(id);
+    return id;
+  }
+  schedule(callback, delay) {
+    return window.setTimeout(callback, delay);
+  }
+  cancel(id) {
+    window.clearTimeout(id);
+  }
+};
+
+// src/controllers/menubar_controller.ts
+var TYPEAHEAD_RESET_MS = 500;
+var MenubarController = class extends Controller {
+  static targets = ["top", "menu", "item"];
+  static actions = ["activate", "onItemKeydown", "onTopKeydown", "toggle"];
+  /** Roving tabindex across the top-level menuitems (one Tab stop). */
+  #roving = new RovingTabindex(() => this.topTargets);
+  /** Typeahead buffer and its idle-reset timer (scoped to the open menu). */
+  #typeahead = "";
+  #typeaheadId = 0;
+  #timers = new SafeTimeout();
+  /** Escape-stack membership while a menu is open; the shared resolver dismisses via it. */
+  #escapeLayer = new EscapeLayer();
+  /** Establishes the single tab stop and the closed baseline. */
+  connect() {
+    const active = this.#roving.activeIndex;
+    this.#roving.setActive(active === -1 ? 0 : active);
+    this.#closeAllMenus();
+    document.addEventListener("click", this.#onOutsideClick);
+  }
+  /** Removes the document listener, stack membership, and any pending typeahead timer. */
+  disconnect() {
+    this.#escapeLayer.deactivate();
+    document.removeEventListener("click", this.#onOutsideClick);
+    this.#timers.clearAll();
+  }
+  /** Toggles a top item's menu. Bound via `data-action` (click on the top item). */
+  toggle(event) {
+    const top = event.currentTarget;
+    if (this.#isExpanded(top)) {
+      this.#closeMenu(top);
+    } else {
+      this.#openMenu(top, "first");
+    }
+  }
+  /** Keyboard handling while focus is on a top item. */
+  onTopKeydown(event) {
+    const tops = this.topTargets;
+    const index = tops.indexOf(event.currentTarget);
+    if (index === -1) return;
+    const length = tops.length;
+    const anyOpen = this.#isAnyOpen;
+    switch (event.key) {
+      case "ArrowRight":
+        event.preventDefault();
+        this.#gotoTop((index + 1) % length, anyOpen);
+        break;
+      case "ArrowLeft":
+        event.preventDefault();
+        this.#gotoTop((index - 1 + length) % length, anyOpen);
+        break;
+      case "ArrowDown":
+        event.preventDefault();
+        this.#openMenu(tops[index], "first");
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        this.#openMenu(tops[index], "last");
+        break;
+      case "Home":
+        event.preventDefault();
+        this.#gotoTop(0, anyOpen);
+        break;
+      case "End":
+        event.preventDefault();
+        this.#gotoTop(length - 1, anyOpen);
+        break;
+    }
+  }
+  /** Keyboard handling while focus is on a menu item. */
+  onItemKeydown(event) {
+    const item = event.currentTarget;
+    const menu = item.closest("[role='menu']");
+    if (!menu) return;
+    const items = this.#itemsIn(menu);
+    const index = items.indexOf(item);
+    const length = items.length;
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault();
+        this.#focusAt(items, (index + 1) % length);
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        this.#focusAt(items, (index - 1 + length) % length);
+        break;
+      case "Home":
+        event.preventDefault();
+        this.#focusAt(items, 0);
+        break;
+      case "End":
+        event.preventDefault();
+        this.#focusAt(items, length - 1);
+        break;
+      case "ArrowRight":
+        event.preventDefault();
+        this.#moveToAdjacentMenu(menu, 1);
+        break;
+      case "ArrowLeft":
+        event.preventDefault();
+        this.#moveToAdjacentMenu(menu, -1);
+        break;
+      case "Tab":
+        this.#closeAllMenus();
+        break;
+      default:
+        if (this.#isTypeaheadKey(event)) {
+          event.preventDefault();
+          this.#typeaheadTo(items, index, event.key);
+        }
+        break;
+    }
+  }
+  /** Closes the owning menu after an item is activated and refocuses its top. */
+  activate(event) {
+    const item = event.currentTarget;
+    const menu = item.closest("[role='menu']");
+    const top = this.#topFor(menu);
+    this.#closeAllMenus();
+    this.#focusTop(top);
+  }
+  /** Moves the roving focus to top `index`, opening its menu when one was open. */
+  #gotoTop(index, reopen) {
+    const top = this.topTargets[index];
+    if (!top) return;
+    if (reopen) {
+      this.#openMenu(top, "first");
+    } else {
+      this.#roving.setActive(index, { focus: true });
+    }
+  }
+  /** Opens `top`'s menu (closing others) and focuses its first/last item. */
+  #openMenu(top, focus) {
+    if (!top) return;
+    this.#closeAllMenus();
+    const menu = this.#menuFor(top);
+    if (!menu) return;
+    menu.hidden = false;
+    top.setAttribute("aria-expanded", "true");
+    this.#escapeLayer.activate(document, {
+      onDismiss: () => this.#dismissOpenMenu(),
+      claims: claimsWhileFocusWithin(this.element)
+    });
+    this.#roving.setActive(this.topTargets.indexOf(top));
+    const items = this.#itemsIn(menu);
+    this.#focusAt(items, focus === "first" ? 0 : items.length - 1);
+  }
+  /** Hides `top`'s menu and reflects the collapsed state. */
+  #closeMenu(top) {
+    if (!top) return;
+    const menu = this.#menuFor(top);
+    if (menu) menu.hidden = true;
+    top.setAttribute("aria-expanded", "false");
+    if (!this.#isAnyOpen) this.#escapeLayer.deactivate();
+  }
+  /** Closes every menu and resets the typeahead buffer. */
+  #closeAllMenus() {
+    for (const top of this.topTargets) this.#closeMenu(top);
+    this.#resetTypeahead();
+  }
+  /**
+   * Escape path, invoked by the shared resolver: pressed inside an open menu it
+   * closes that menu and returns focus to its top item (the APG behavior);
+   * pressed while focus is on a top item (or fell to the body) it closes every
+   * menu without moving focus.
+   */
+  #dismissOpenMenu() {
+    const active = document.activeElement;
+    const menu = this.menuTargets.find((candidate) => candidate.contains(active));
+    if (menu) {
+      const top = this.#topFor(menu);
+      this.#closeMenu(top);
+      this.#focusTop(top);
+      return;
+    }
+    this.#closeAllMenus();
+  }
+  /** Opens the menu of the top item `delta` steps from the one owning `menu`. */
+  #moveToAdjacentMenu(menu, delta) {
+    const top = this.#topFor(menu);
+    if (!top) return;
+    const tops = this.topTargets;
+    const next = (tops.indexOf(top) + delta + tops.length) % tops.length;
+    this.#openMenu(tops[next], "first");
+  }
+  /** Closes when a click lands outside the controller's element. */
+  #onOutsideClick = (event) => {
+    if (this.#isAnyOpen && !this.element.contains(event.target)) this.#closeAllMenus();
+  };
+  /** The menu element controlled by `top` (matched by `aria-controls`/`id`). */
+  #menuFor(top) {
+    const id = top.getAttribute("aria-controls");
+    return id ? this.menuTargets.find((menu) => menu.id === id) ?? null : null;
+  }
+  /** The top item that controls `menu` (reverse of `#menuFor`). */
+  #topFor(menu) {
+    if (!menu) return null;
+    return this.topTargets.find((top) => top.getAttribute("aria-controls") === menu.id) ?? null;
+  }
+  /** The item targets that live inside `menu`, in DOM order. */
+  #itemsIn(menu) {
+    return this.itemTargets.filter((item) => menu.contains(item));
+  }
+  /** Moves DOM focus to the item at `index` (no-op if out of range). */
+  #focusAt(items, index) {
+    items[index]?.focus();
+  }
+  /** Returns roving focus to a top item (and makes it the single tab stop). */
+  #focusTop(top) {
+    if (!top) return;
+    this.#roving.setActive(this.topTargets.indexOf(top), { focus: true });
+  }
+  /** Whether `top`'s menu is currently expanded. */
+  #isExpanded(top) {
+    return top.getAttribute("aria-expanded") === "true";
+  }
+  /** Whether any top item's menu is currently open. */
+  get #isAnyOpen() {
+    return this.topTargets.some((top) => this.#isExpanded(top));
+  }
+  /**
+   * Whether the event is a single printable character usable for typeahead.
+   * `Space` is excluded: on a `<button>` menuitem it natively activates the item
+   * (Enter/Space → click), so swallowing it for typeahead would break activation.
+   */
+  #isTypeaheadKey(event) {
+    return event.key.length === 1 && event.key !== " " && !event.ctrlKey && !event.metaKey && !event.altKey;
+  }
+  /** Advances focus to the next item in `items` matching the accumulated buffer. */
+  #typeaheadTo(items, current, key) {
+    this.#typeahead += key.toLowerCase();
+    this.#timers.clear(this.#typeaheadId);
+    this.#typeaheadId = this.#timers.set(() => this.#resetTypeahead(), TYPEAHEAD_RESET_MS);
+    const count = items.length;
+    for (let step = 1; step <= count; step++) {
+      const candidate = items[(current + step) % count];
+      const label = (candidate?.textContent ?? "").trim().toLowerCase();
+      if (label.startsWith(this.#typeahead)) {
+        candidate?.focus();
+        return;
+      }
+    }
+  }
+  /** Clears the typeahead buffer and its timer. */
+  #resetTypeahead() {
+    this.#typeahead = "";
+    this.#timers.clear(this.#typeaheadId);
+  }
+};
+
+export { MenubarController };
+//# sourceMappingURL=menubar_controller.js.map
+//# sourceMappingURL=menubar_controller.js.map