stimeo-ui 0.2.0 → 0.3.0

package/dist/controllers/local_time_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/controllers/local_time_controller.ts"],"names":[],"mappings":"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","file":"local_time_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/** A date/time style keyword accepted by `Intl` `dateStyle` / `timeStyle`. */\ntype DateTimeStyle = \"full\" | \"long\" | \"medium\" | \"short\";\n\n/** The valid `Intl` style keywords, used to validate the string-typed values. */\nconst STYLES = new Set<DateTimeStyle>([\"full\", \"long\", \"medium\", \"short\"]);\n\n/** Narrows an arbitrary string to a valid {@link DateTimeStyle}, or `undefined`. */\nfunction toStyle(value: string): DateTimeStyle | undefined {\n  return (STYLES as Set<string>).has(value) ? (value as DateTimeStyle) : undefined;\n}\n\n/**\n * Headless local-time behavior: renders the UTC instant in a `<time datetime>`\n * as an absolute, viewer-localized string via `Intl.DateTimeFormat`. No\n * dedicated APG pattern; it follows the HTML `<time>` semantics.\n *\n * Markup contract (identifier: `stimeo--local-time`):\n *   <time datetime=\"2026-06-08T12:30:00Z\"\n *         data-controller=\"stimeo--local-time\"\n *         data-stimeo--local-time-date-style-value=\"medium\"\n *         data-stimeo--local-time-time-style-value=\"short\">2026-06-08 12:30 UTC</time>\n *\n * The server emits UTC (cache-friendly — it never needs to know the viewer's\n * timezone), and the controller reformats the visible text into the viewer's\n * locale/zone on connect. This is the *absolute* localization axis, distinct from\n * {@link RelativeTimeController}'s \"3 minutes ago\".\n *\n * @remarks\n * Behavior only. The machine-readable `datetime` (UTC) is left untouched so\n * assistive tech and crawlers keep the canonical value while only the display\n * text — and an optional `title` — change. Formatting is a pure function of\n * `datetime` with no module-scope state, listeners, or timers, so a Turbo Drive\n * cache restore or morph re-runs `connect()` and stays consistent. A parse or\n * `Intl` error leaves the authored absolute text in place rather than throwing.\n */\nexport class LocalTimeController extends Controller<HTMLElement> {\n  static override values = {\n    locale: { type: String, default: \"\" },\n    timeZone: { type: String, default: \"\" },\n    dateStyle: { type: String, default: \"medium\" },\n    timeStyle: { type: String, default: \"short\" },\n    titleFormat: { type: String, default: \"\" },\n  };\n  static events = [\"format\"] as const;\n\n  declare localeValue: string;\n  declare timeZoneValue: string;\n  declare dateStyleValue: string;\n  declare timeStyleValue: string;\n  declare titleFormatValue: string;\n\n  override connect(): void {\n    const date = this.#parse();\n    if (date === null) return;\n\n    const formatted = this.#applyFormat(date, this.dateStyleValue, this.timeStyleValue);\n    if (formatted === null) return;\n\n    // Only the visible text (and optional title) change; `datetime` is the\n    // immutable machine-readable source and is never rewritten.\n    this.element.textContent = formatted;\n\n    const title = this.#title(date);\n    if (title !== null) this.element.setAttribute(\"title\", title);\n\n    this.dispatch(\"format\", { detail: { formatted } });\n  }\n\n  /** Parses the UTC `datetime` attribute into a {@link Date}, or `null`. */\n  #parse(): Date | null {\n    const raw = this.element.getAttribute(\"datetime\");\n    if (!raw) return null;\n    const ms = Date.parse(this.#asUtc(raw.trim()));\n    return Number.isNaN(ms) ? null : new Date(ms);\n  }\n\n  /**\n   * Reads a timezone-less date-time as UTC — the documented input contract —\n   * since `Date.parse` would otherwise interpret e.g. `\"2026-06-08T12:30:00\"` in\n   * the *runtime's* local zone, contradicting \"the server emits UTC\". Values that\n   * already carry `Z` or a `±hh:mm` offset (and bare `YYYY-MM-DD` dates, already\n   * parsed as UTC) are returned unchanged.\n   */\n  #asUtc(value: string): string {\n    const hasTime = /T\\d{2}:\\d{2}/.test(value);\n    const hasZone = /(Z|[+-]\\d{2}:?\\d{2})$/.test(value);\n    return hasTime && !hasZone ? `${value}Z` : value;\n  }\n\n  /**\n   * Builds the optional detailed `title`. `titleFormat` is an `Intl` style\n   * keyword applied to *both* date and time; empty (the default) adds no title.\n   */\n  #title(date: Date): string | null {\n    if (this.titleFormatValue.length === 0) return null;\n    return this.#applyFormat(date, this.titleFormatValue, this.titleFormatValue);\n  }\n\n  /**\n   * Formats `date` with `Intl.DateTimeFormat`, including each style only when it\n   * is a valid keyword (so a consumer can show date-only or time-only by clearing\n   * the other). Returns `null` when neither style is usable or `Intl` throws, so\n   * the caller can leave the authored text untouched.\n   */\n  #applyFormat(date: Date, dateStyle: string, timeStyle: string): string | null {\n    // `toStyle` yields `undefined` for an empty/invalid keyword; assigning it is\n    // equivalent to omitting the option, so a consumer can show date- or time-only.\n    const options: Intl.DateTimeFormatOptions = {\n      dateStyle: toStyle(dateStyle),\n      timeStyle: toStyle(timeStyle),\n    };\n    if (options.dateStyle === undefined && options.timeStyle === undefined) return null;\n    if (this.timeZoneValue.length > 0) options.timeZone = this.timeZoneValue;\n\n    try {\n      return new Intl.DateTimeFormat(this.#locale, options).format(date);\n    } catch {\n      // An invalid locale / timeZone (or unsupported style) must not break the\n      // page; the authored absolute text remains as the graceful fallback.\n      return null;\n    }\n  }\n\n  /** Locale precedence: the value, then the element's `lang`, then the document's. */\n  get #locale(): string | undefined {\n    return this.localeValue || this.element.lang || document.documentElement.lang || undefined;\n  }\n}\n"]}
+{"version":3,"sources":["../../src/controllers/local_time_controller.ts"],"names":[],"mappings":"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","file":"local_time_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/** A date/time style keyword accepted by `Intl` `dateStyle` / `timeStyle`. */\ntype DateTimeStyle = \"full\" | \"long\" | \"medium\" | \"short\";\n\n/** The valid `Intl` style keywords, used to validate the string-typed values. */\nconst STYLES = new Set<DateTimeStyle>([\"full\", \"long\", \"medium\", \"short\"]);\n\n/** Narrows an arbitrary string to a valid {@link DateTimeStyle}, or `undefined`. */\nfunction toStyle(value: string): DateTimeStyle | undefined {\n  return (STYLES as Set<string>).has(value) ? (value as DateTimeStyle) : undefined;\n}\n\n/**\n * Headless local-time behavior: renders the UTC instant in a `<time datetime>`\n * as an absolute, viewer-localized string via `Intl.DateTimeFormat`. No\n * dedicated APG pattern; it follows the HTML `<time>` semantics.\n *\n * Markup contract (identifier: `stimeo--local-time`):\n *   <time datetime=\"2026-06-08T12:30:00Z\"\n *         data-controller=\"stimeo--local-time\"\n *         data-stimeo--local-time-date-style-value=\"medium\"\n *         data-stimeo--local-time-time-style-value=\"short\">2026-06-08 12:30 UTC</time>\n *\n * The server emits UTC (cache-friendly — it never needs to know the viewer's\n * timezone), and the controller reformats the visible text into the viewer's\n * locale/zone on connect. This is the *absolute* localization axis, distinct from\n * {@link RelativeTimeController}'s \"3 minutes ago\".\n *\n * @remarks\n * Behavior only. The machine-readable `datetime` (UTC) is left untouched so\n * assistive tech and crawlers keep the canonical value while only the display\n * text — and an optional `title` — change. Formatting is a pure function of\n * `datetime` with no module-scope state, listeners, or timers, so a Turbo Drive\n * cache restore or morph re-runs `connect()` and stays consistent. A parse or\n * `Intl` error leaves the authored absolute text in place rather than throwing.\n */\nexport class LocalTimeController extends Controller<HTMLElement> {\n  static override values = {\n    locale: { type: String, default: \"\" },\n    timeZone: { type: String, default: \"\" },\n    dateStyle: { type: String, default: \"medium\" },\n    timeStyle: { type: String, default: \"short\" },\n    titleFormat: { type: String, default: \"\" },\n  };\n  static events = [\"format\"] as const;\n\n  declare localeValue: string;\n  declare timeZoneValue: string;\n  declare dateStyleValue: string;\n  declare timeStyleValue: string;\n  declare titleFormatValue: string;\n\n  override connect(): void {\n    const date = this.#parse();\n    if (date === null) return;\n\n    const formatted = this.#applyFormat(date, this.dateStyleValue, this.timeStyleValue);\n    if (formatted === null) return;\n\n    // Only the visible text (and optional title) change; `datetime` is the\n    // immutable machine-readable source and is never rewritten.\n    this.element.textContent = formatted;\n\n    const title = this.#title(date);\n    if (title !== null) this.element.setAttribute(\"title\", title);\n\n    this.dispatch(\"format\", { detail: { formatted } });\n  }\n\n  /** Parses the UTC `datetime` attribute into a {@link Date}, or `null`. */\n  #parse(): Date | null {\n    const raw = this.element.getAttribute(\"datetime\");\n    if (!raw) return null;\n    const ms = Date.parse(this.#asUtc(raw.trim()));\n    return Number.isNaN(ms) ? null : new Date(ms);\n  }\n\n  /**\n   * Reads a timezone-less date-time as UTC — the input contract of this\n   * controller — since `Date.parse` would otherwise read `\"2026-06-08T12:30:00\"` in\n   * the *runtime's* local zone, contradicting \"the server emits UTC\". Values that\n   * already carry `Z` or a `±hh:mm` offset (and bare `YYYY-MM-DD` dates, already\n   * parsed as UTC) are returned unchanged.\n   */\n  #asUtc(value: string): string {\n    const hasTime = /T\\d{2}:\\d{2}/.test(value);\n    const hasZone = /(Z|[+-]\\d{2}:?\\d{2})$/.test(value);\n    return hasTime && !hasZone ? `${value}Z` : value;\n  }\n\n  /**\n   * Builds the optional detailed `title`. `titleFormat` is an `Intl` style\n   * keyword applied to *both* date and time; empty (the default) adds no title.\n   */\n  #title(date: Date): string | null {\n    if (this.titleFormatValue.length === 0) return null;\n    return this.#applyFormat(date, this.titleFormatValue, this.titleFormatValue);\n  }\n\n  /**\n   * Formats `date` with `Intl.DateTimeFormat`, including each style only when it\n   * is a valid keyword (so a consumer can show date-only or time-only by clearing\n   * the other). Returns `null` when neither style is usable or `Intl` throws, so\n   * the caller can leave the authored text untouched.\n   */\n  #applyFormat(date: Date, dateStyle: string, timeStyle: string): string | null {\n    // `toStyle` yields `undefined` for an empty/invalid keyword; assigning it is\n    // equivalent to omitting the option, so a consumer can show date- or time-only.\n    const options: Intl.DateTimeFormatOptions = {\n      dateStyle: toStyle(dateStyle),\n      timeStyle: toStyle(timeStyle),\n    };\n    if (options.dateStyle === undefined && options.timeStyle === undefined) return null;\n    if (this.timeZoneValue.length > 0) options.timeZone = this.timeZoneValue;\n\n    try {\n      return new Intl.DateTimeFormat(this.#locale, options).format(date);\n    } catch {\n      // An invalid locale / timeZone (or unsupported style) must not break the\n      // page; the authored absolute text remains as the graceful fallback.\n      return null;\n    }\n  }\n\n  /** Locale precedence: the value, then the element's `lang`, then the document's. */\n  get #locale(): string | undefined {\n    return this.localeValue || this.element.lang || document.documentElement.lang || undefined;\n  }\n}\n"]}

package/dist/controllers/masonry_controller.d.ts

@@ -0,0 +1,54 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless **Masonry** layout helper: assigns each item to the shortest column so
+ * variable-height cards pack without vertical gaps. There is no APG widget — this
+ * is a layout-only utility that emits state hooks, never visual structure.
+ *
+ * Markup contract (identifier: `stimeo--masonry`):
+ *   <div data-controller="stimeo--masonry"
+ *        data-stimeo--masonry-min-column-width-value="240"
+ *        data-stimeo--masonry-gap-value="16">
+ *     <div data-stimeo--masonry-target="item">…</div>
+ *     <div data-stimeo--masonry-target="item">…</div>
+ *   </div>
+ *
+ * The column count is derived responsively from the container width and
+ * `minColumnWidth`; each item is then placed into whichever column is currently
+ * shortest (measured from item heights). The count is published on the controller
+ * element as the `--stimeo-masonry-columns` custom property and each item gets a
+ * `data-column` index, so the consumer's CSS owns the actual placement.
+ *
+ * @remarks
+ * Behavior only. **DOM order is never changed** — reading order and focus order
+ * stay the source markup order (WCAG 1.3.2). The visual packing is purely the
+ * column assignment a consumer reads from `data-column`; this controller writes no
+ * positioning styles. Re-layout runs on connect, on resize ({@link LayoutObserver}),
+ * and on item add/remove ({@link MutationObserver}); both observers are released on
+ * `disconnect()` (Turbo navigation included). Use only for independent cards whose
+ * visual order carries no meaning.
+ */
+declare class MasonryController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        minColumnWidth: {
+            type: NumberConstructor;
+            default: number;
+        };
+        gap: {
+            type: NumberConstructor;
+            default: number;
+        };
+    };
+    static events: readonly ["layout"];
+    readonly itemTargets: HTMLElement[];
+    minColumnWidthValue: number;
+    gapValue: number;
+    /** Observes size/content changes and performs the first layout pass. */
+    connect(): void;
+    /** Releases both observers and the load listener so nothing fires after detach. */
+    disconnect(): void;
+}
+
+export { MasonryController };

package/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

package/dist/controllers/masonry_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/layout_observer.ts","../../src/controllers/masonry_controller.ts"],"names":[],"mappings":"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","file":"masonry_controller.js","sourcesContent":["/**\n * Unified element-size and viewport observation for Stimeo controllers.\n *\n * Layout-sensitive widgets (sliders, resizable panes, scroll spies, popovers)\n * need to react both to their *own* box changing — via {@link ResizeObserver} —\n * and to the *viewport* changing — via the `window` `resize` event. Wiring those\n * two sources by hand in every controller risks leaked listeners on\n * `disconnect()`. {@link LayoutObserver} owns both behind one callback and one\n * {@link LayoutObserver.disconnect | disconnect()} that releases everything.\n *\n * Behavior only: the helper reports *that* layout changed; it never reads or\n * writes styles. Consumers decide what to recompute.\n */\n\n/** Invoked whenever an observed element or the viewport changes size. */\nexport type LayoutCallback = () => void;\n\n/** Constructs a {@link ResizeObserver}; injectable so tests stay deterministic. */\nexport type ResizeObserverFactory = (callback: ResizeObserverCallback) => ResizeObserver;\n\n/** Options for {@link LayoutObserver}. */\nexport interface LayoutObserverOptions {\n  /**\n   * Factory for the {@link ResizeObserver} used by {@link LayoutObserver.observe}.\n   * Defaults to the global constructor; override it in tests, or to no-op in\n   * environments where `ResizeObserver` is unavailable.\n   */\n  resizeObserverFactory?: ResizeObserverFactory;\n}\n\n/**\n * Observes element resizes and/or viewport resizes through a single callback,\n * with guaranteed teardown.\n *\n * @example\n * ```ts\n * #layout = new LayoutObserver(() => this.#reposition());\n *\n * connect() {\n *   this.#layout.observe(this.panelTarget);\n *   this.#layout.observeViewport();\n * }\n *\n * disconnect() {\n *   this.#layout.disconnect();\n * }\n * ```\n */\nexport class LayoutObserver {\n  readonly #callback: LayoutCallback;\n  readonly #resizeObserverFactory: ResizeObserverFactory | null;\n  #resizeObserver: ResizeObserver | null = null;\n  #observingViewport = false;\n\n  /** Stable bound handler so add/removeEventListener target the same reference. */\n  readonly #handleViewportResize = (): void => {\n    this.#callback();\n  };\n\n  constructor(callback: LayoutCallback, options: LayoutObserverOptions = {}) {\n    this.#callback = callback;\n    this.#resizeObserverFactory =\n      options.resizeObserverFactory ??\n      (typeof ResizeObserver === \"undefined\" ? null : (cb) => new ResizeObserver(cb));\n  }\n\n  /**\n   * Starts observing an element's size. Repeated calls observe additional\n   * elements through the same shared observer. No-ops when no\n   * `ResizeObserver` implementation is available.\n   */\n  observe(element: Element): void {\n    if (!this.#resizeObserverFactory) return;\n    if (!this.#resizeObserver) {\n      this.#resizeObserver = this.#resizeObserverFactory(() => {\n        this.#callback();\n      });\n    }\n    this.#resizeObserver.observe(element);\n  }\n\n  /** Stops observing a single element while leaving any others in place. */\n  unobserve(element: Element): void {\n    this.#resizeObserver?.unobserve(element);\n  }\n\n  /** Starts observing viewport resizes. Idempotent: the listener is added once. */\n  observeViewport(): void {\n    if (this.#observingViewport) return;\n    this.#observingViewport = true;\n    window.addEventListener(\"resize\", this.#handleViewportResize);\n  }\n\n  /** Stops observing viewport resizes without affecting element observation. */\n  unobserveViewport(): void {\n    if (!this.#observingViewport) return;\n    this.#observingViewport = false;\n    window.removeEventListener(\"resize\", this.#handleViewportResize);\n  }\n\n  /**\n   * Releases every observation: disconnects the {@link ResizeObserver} and\n   * removes the viewport listener. Safe to call multiple times. Call this from a\n   * controller's `disconnect()`.\n   */\n  disconnect(): void {\n    this.#resizeObserver?.disconnect();\n    this.#resizeObserver = null;\n    this.unobserveViewport();\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { LayoutObserver } from \"../utils/layout_observer\";\n\n/** CSS custom property exposing the current column count to consumer CSS. */\nconst COLUMNS_PROPERTY = \"--stimeo-masonry-columns\";\n\n/**\n * Headless **Masonry** layout helper: assigns each item to the shortest column so\n * variable-height cards pack without vertical gaps. There is no APG widget — this\n * is a layout-only utility that emits state hooks, never visual structure.\n *\n * Markup contract (identifier: `stimeo--masonry`):\n *   <div data-controller=\"stimeo--masonry\"\n *        data-stimeo--masonry-min-column-width-value=\"240\"\n *        data-stimeo--masonry-gap-value=\"16\">\n *     <div data-stimeo--masonry-target=\"item\">…</div>\n *     <div data-stimeo--masonry-target=\"item\">…</div>\n *   </div>\n *\n * The column count is derived responsively from the container width and\n * `minColumnWidth`; each item is then placed into whichever column is currently\n * shortest (measured from item heights). The count is published on the controller\n * element as the `--stimeo-masonry-columns` custom property and each item gets a\n * `data-column` index, so the consumer's CSS owns the actual placement.\n *\n * @remarks\n * Behavior only. **DOM order is never changed** — reading order and focus order\n * stay the source markup order (WCAG 1.3.2). The visual packing is purely the\n * column assignment a consumer reads from `data-column`; this controller writes no\n * positioning styles. Re-layout runs on connect, on resize ({@link LayoutObserver}),\n * and on item add/remove ({@link MutationObserver}); both observers are released on\n * `disconnect()` (Turbo navigation included). Use only for independent cards whose\n * visual order carries no meaning.\n */\nexport class MasonryController extends Controller<HTMLElement> {\n  static override targets = [\"item\"];\n  static override values = {\n    minColumnWidth: { type: Number, default: 240 },\n    gap: { type: Number, default: 16 },\n  };\n  static events = [\"layout\"] as const;\n\n  declare readonly itemTargets: HTMLElement[];\n  declare minColumnWidthValue: number;\n  declare gapValue: number;\n\n  readonly #layout = new LayoutObserver(() => this.#relayout());\n  #mutationObserver: MutationObserver | null = null;\n  /** Last published column count, so `layout` fires only on real changes. */\n  #lastColumns = 0;\n\n  /**\n   * Re-pack when a descendant resource finishes loading. Images/iframes report a\n   * height of 0 until loaded, which would skew the shortest-column packing if the\n   * first pass ran before they settled; `load` does not bubble, so this is bound in\n   * the capture phase to catch every descendant.\n   */\n  readonly #onLoad = (): void => this.#relayout();\n\n  /** Observes size/content changes and performs the first layout pass. */\n  override connect(): void {\n    this.#layout.observe(this.element);\n    this.#layout.observeViewport();\n\n    if (typeof MutationObserver !== \"undefined\") {\n      this.#mutationObserver = new MutationObserver(() => this.#relayout());\n      this.#mutationObserver.observe(this.element, { childList: true, subtree: true });\n    }\n    this.element.addEventListener(\"load\", this.#onLoad, true);\n    this.#relayout();\n  }\n\n  /** Releases both observers and the load listener so nothing fires after detach. */\n  override disconnect(): void {\n    this.#layout.disconnect();\n    this.#mutationObserver?.disconnect();\n    this.#mutationObserver = null;\n    this.element.removeEventListener(\"load\", this.#onLoad, true);\n    this.#lastColumns = 0;\n  }\n\n  /**\n   * Recomputes the column count and assigns every item to the shortest column.\n   * Runs automatically on connect, on resize, on item add/remove, and when a\n   * descendant resource loads (private — there is no public action; the observers\n   * and the capture-phase `load` listener drive it). Items are walked in DOM\n   * order; each lands in the column with the least accumulated height, which\n   * keeps the packing balanced without reordering the DOM.\n   */\n  #relayout(): void {\n    const items = this.itemTargets;\n    const columns = this.#columnCount();\n\n    const heights = new Array<number>(columns).fill(0);\n    for (const item of items) {\n      let shortest = 0;\n      for (let col = 1; col < columns; col++) {\n        if ((heights[col] ?? 0) < (heights[shortest] ?? 0)) shortest = col;\n      }\n      item.setAttribute(\"data-column\", String(shortest));\n      heights[shortest] =\n        (heights[shortest] ?? 0) + item.getBoundingClientRect().height + this.gapValue;\n    }\n\n    this.element.style.setProperty(COLUMNS_PROPERTY, String(columns));\n\n    if (columns !== this.#lastColumns) {\n      this.#lastColumns = columns;\n      this.dispatch(\"layout\", { detail: { columns } });\n    }\n  }\n\n  /**\n   * Derives how many columns fit: `floor((width + gap) / (minColumnWidth + gap))`,\n   * never fewer than one. When the width is unmeasurable (detached, or a layout\n   * engine that reports `0`), it falls back to a single column so every item still\n   * gets a valid `data-column`.\n   */\n  #columnCount(): number {\n    const width = this.element.getBoundingClientRect().width;\n    const denominator = this.minColumnWidthValue + this.gapValue;\n    if (width <= 0 || denominator <= 0) return 1;\n    return Math.max(1, Math.floor((width + this.gapValue) / denominator));\n  }\n}\n"]}

package/dist/controllers/menu_controller.d.ts

@@ -15,13 +15,20 @@ import { Controller } from '@hotwired/stimulus';
  *         data-stimeo--menu-target="menu" hidden>
  *       <li role="none">
  *         <button role="menuitem" tabindex="-1"
- *                 data-stimeo--menu-target="item"
- *                 data-action="click->stimeo--menu#activate
- *                              keydown->stimeo--menu#onItemKeydown">…</button>
+ *                 data-stimeo--menu-target="item">…</button>
  *       </li>
  *     </ul>
  *   </div>
  *
+ * The trigger's two actions are required. Items need none: their click and key
+ * handling is delegated from the controller element, so an item added, moved, or
+ * server-rendered after connect works without the consumer wiring anything onto
+ * it. The per-element form (`click->stimeo--menu#activate` /
+ * `keydown->stimeo--menu#onItemKeydown`) is supported alongside it. A
+ * focus-moving key runs once (the action claims it and the delegate stands
+ * down), and `activate`, reachable on both paths, claims the click so one
+ * gesture activates once. See {@link #onDelegatedItemClick}.
+ *
  * Implements the WAI-ARIA APG **Menu Button** pattern (a button that opens a menu
  * of commands). Unlike `stimeo--dropdown` (a disclosure for arbitrary content),
  * this is a true `role="menu"` widget with roving focus across `role="menuitem"`
@@ -42,14 +49,14 @@ import { Controller } from '@hotwired/stimulus';
  * - `Escape` closes and returns focus to the trigger. While open the menu is a
  *   layer on the shared {@link EscapeLayer} stack; it claims a press only while
  *   focus is inside the controller or fell to the body, so one keypress closes
- *   exactly one layer (the shared layered-Escape contract) and a newer layer
- *   (e.g. a tooltip shown over an item) is dismissed first.
+ *   exactly one layer and a newer layer (e.g. a tooltip shown over an item) is
+ *   dismissed first.
  * - A click outside the controller closes the menu without moving focus away
  *   from the clicked element.
  *
- * Roving focus skips items that are not navigable — `hidden`, natively
- * `disabled`, or `aria-disabled="true"` — so the keyboard never lands focus on an
- * inert command (matching `stimeo--command-palette` / `stimeo--toolbar`).
+ * Roving focus skips `hidden` and natively `disabled` items. An
+ * `aria-disabled="true"` item remains discoverable by arrow-key focus, while its
+ * activation is suppressed in the capture phase.
  */
 declare class MenuController extends Controller<HTMLElement> {
     #private;
@@ -60,7 +67,7 @@ declare class MenuController extends Controller<HTMLElement> {
     readonly itemTargets: HTMLButtonElement[];
     readonly hasTriggerTarget: boolean;
     readonly hasMenuTarget: boolean;
-    /** Starts closed and registers delegated listeners. */
+    /** Starts closed and registers activation / outside-click listeners. */
     connect(): void;
     /** Releases the listeners, stack membership, and any pending Tab-close task. */
     disconnect(): void;
@@ -81,8 +88,19 @@ declare class MenuController extends Controller<HTMLElement> {
     onTriggerKeydown(event: KeyboardEvent): void;
     /** Implements roving focus and closing keys inside the menu. */
     onItemKeydown(event: KeyboardEvent): void;
-    /** Closes the menu after an item is activated. Bound via `data-action`. */
-    activate(): void;
+    /**
+     * Closes the menu after an item is activated. Bound via `data-action`, and
+     * also reached from the delegated listener.
+     *
+     * Markup that carries the per-element action *and* gets the delegate would run
+     * this twice for one gesture. `close()` writes the state hooks (`hidden`,
+     * `aria-expanded`), and an identical reassign still queues a MutationRecord,
+     * so a second pass is observable to anyone watching them. The event is
+     * therefore claimed: the path that gets there first does the work, the other
+     * one finds it claimed and returns. A programmatic call with no event always
+     * runs.
+     */
+    activate(event?: Event): void;
 }
 
 export { MenuController };

package/dist/controllers/menu_controller.js

@@ -2,6 +2,12 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/menu_controller.ts
 
+// src/utils/arrow_step.ts
+function isReservedArrowChord(event, allow = []) {
+  if (!event.key.startsWith("Arrow")) return false;
+  return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
+}
+
 // src/utils/escape_layer.ts
 function claimsWhileFocusWithin(element) {
   return () => {
@@ -159,18 +165,30 @@ var MenuController = class extends Controller {
   #timers = new SafeTimeout();
   /** Escape-stack membership while open; the shared resolver dismisses via it. */
   #escapeLayer = new EscapeLayer();
-  /** Starts closed and registers delegated listeners. */
+  /**
+   * The item a click started on, recorded in the capture pass. Read once by the
+   * delegated bubble listener, which must not re-derive it: consumer handlers run
+   * in between and may detach the item.
+   */
+  #clickOwner = null;
+  /** Clicks already turned into an activation, so the two paths run it once. */
+  #activated = /* @__PURE__ */ new WeakSet();
+  /** Starts closed and registers activation / outside-click listeners. */
   connect() {
     this.close();
     this.element.addEventListener("click", this.#onItemClickCapture, true);
-    document.addEventListener("click", this.#onOutsideClick);
+    this.element.addEventListener("click", this.#onDelegatedItemClick);
+    this.element.addEventListener("keydown", this.#onDelegatedItemKeydown);
+    document.addEventListener("click", this.#onOutsideClick, true);
   }
   /** Releases the listeners, stack membership, and any pending Tab-close task. */
   disconnect() {
     this.#timers.clearAll();
     this.#escapeLayer.deactivate();
     this.element.removeEventListener("click", this.#onItemClickCapture, true);
-    document.removeEventListener("click", this.#onOutsideClick);
+    this.element.removeEventListener("click", this.#onDelegatedItemClick);
+    this.element.removeEventListener("keydown", this.#onDelegatedItemKeydown);
+    document.removeEventListener("click", this.#onOutsideClick, true);
   }
   /** Toggles the menu open/closed. Bound via `data-action` (click). */
   toggle() {
@@ -209,6 +227,8 @@ var MenuController = class extends Controller {
    * open and then immediately re-toggle the menu.
    */
   onTriggerKeydown(event) {
+    if (event.defaultPrevented) return;
+    if (isReservedArrowChord(event)) return;
     if (event.key === "ArrowDown") {
       event.preventDefault();
       this.open();
@@ -221,8 +241,18 @@ var MenuController = class extends Controller {
   }
   /** Implements roving focus and closing keys inside the menu. */
   onItemKeydown(event) {
+    this.#handleItemKeydown(event, event.currentTarget);
+  }
+  /**
+   * The roving-focus body, shared by the per-element action and its delegated
+   * twin. `from` is the item the key belongs to: the bound element for the
+   * action, the resolved owner of the event target for the delegate.
+   */
+  #handleItemKeydown(event, from) {
+    if (event.defaultPrevented) return;
+    if (isReservedArrowChord(event)) return;
     const items = this.#navigableItems;
-    const currentIndex = items.indexOf(event.currentTarget);
+    const currentIndex = items.indexOf(from);
     switch (event.key) {
       case "ArrowDown":
         event.preventDefault();
@@ -246,8 +276,23 @@ var MenuController = class extends Controller {
         break;
     }
   }
-  /** Closes the menu after an item is activated. Bound via `data-action`. */
-  activate() {
+  /**
+   * Closes the menu after an item is activated. Bound via `data-action`, and
+   * also reached from the delegated listener.
+   *
+   * Markup that carries the per-element action *and* gets the delegate would run
+   * this twice for one gesture. `close()` writes the state hooks (`hidden`,
+   * `aria-expanded`), and an identical reassign still queues a MutationRecord,
+   * so a second pass is observable to anyone watching them. The event is
+   * therefore claimed: the path that gets there first does the work, the other
+   * one finds it claimed and returns. A programmatic call with no event always
+   * runs.
+   */
+  activate(event) {
+    if (event !== void 0) {
+      if (this.#activated.has(event)) return;
+      this.#activated.add(event);
+    }
     this.#closeAndRestore();
   }
   /** Closes and returns focus to the trigger (Escape / item-activation path). */
@@ -260,16 +305,59 @@ var MenuController = class extends Controller {
     if (this.#isOpen && !this.element.contains(event.target)) this.close();
   };
   /**
-   * Captures clicks so `aria-disabled` commands cannot reach consumer handlers.
-   * Native Enter/Space activation also synthesizes a click and is blocked here.
+   * Delegated twin of {@link onItemKeydown}, bound on the controller element.
+   *
+   * An item that arrives *after* connect — Overflow Menu moves toolbar controls
+   * into this menu at runtime — carries whatever `data-action` its author wrote,
+   * and that is exactly the binding a consumer forgets, because the markup that
+   * declares the item lives nowhere near the menu. Listening on the container
+   * makes membership in the `item` target enough to be operable. The per-element
+   * action stays supported and is not double-handled: see
+   * {@link #handleItemKeydown}.
+   */
+  #onDelegatedItemKeydown = (event) => {
+    const item = this.#itemFrom(event.target);
+    if (item === null) return;
+    this.#handleItemKeydown(event, item);
+  };
+  /**
+   * Delegated twin of {@link activate}, for the same reason as the keydown one.
+   *
+   * It works from the item the capture pass recorded, not from a fresh lookup:
+   * by the time a click bubbles up here, a consumer handler may already have
+   * detached the row it lives in, and `itemTargets` is a live query that would
+   * then resolve nothing — the activation would be lost and the menu left open
+   * over an item that no longer exists. `aria-disabled` items never reach this
+   * listener at all: the capture pass stops the click outright.
+   */
+  #onDelegatedItemClick = (event) => {
+    const item = this.#clickOwner;
+    this.#clickOwner = null;
+    if (item === null) return;
+    this.activate(event);
+  };
+  /** The item target that is, or contains, `node`; `null` when it is neither. */
+  #itemFrom(node) {
+    if (!(node instanceof Node)) return null;
+    return this.itemTargets.find((item) => item === node || item.contains(node)) ?? null;
+  }
+  /**
+   * First look at every click inside the controller, and the only point at which
+   * the DOM is still the one the user clicked. Two jobs: record which item owns
+   * the click for the delegate above, and stop an `aria-disabled` command before
+   * it reaches consumer handlers (native Enter/Space activation synthesizes a
+   * click and is blocked here too).
    */
   #onItemClickCapture = (event) => {
     const target = event.target;
-    if (!(target instanceof Node)) return;
-    const disabled = this.itemTargets.some(
-      (item) => item.getAttribute("aria-disabled") === "true" && item.contains(target)
-    );
-    if (!disabled) return;
+    if (!(target instanceof Node)) {
+      this.#clickOwner = null;
+      return;
+    }
+    const item = this.#itemFrom(target);
+    this.#clickOwner = item;
+    if (item === null || item.getAttribute("aria-disabled") !== "true") return;
+    this.#clickOwner = null;
     event.preventDefault();
     event.stopImmediatePropagation();
   };
@@ -287,13 +375,12 @@ var MenuController = class extends Controller {
     return this.itemTargets.filter((item) => this.#isNavigable(item));
   }
   /**
-   * An item can take roving focus unless it is `hidden`, `aria-disabled="true"`,
-   * or a natively `disabled` form control. CSS-only visibility is not detectable
-   * here and is the consumer's responsibility.
+   * An item can take roving focus unless it is `hidden` or a natively `disabled`
+   * form control. `aria-disabled` remains focusable for discoverability; capture
+   * suppresses activation. CSS-only visibility is the consumer's responsibility.
    */
   #isNavigable(item) {
     if (item.hasAttribute("hidden")) return false;
-    if (item.getAttribute("aria-disabled") === "true") return false;
     return !item.disabled;
   }
   /** Whether the menu is currently visible. */