stimeo-ui 0.1.0-alpha.1

package/dist/positioning/index.d.ts

@@ -0,0 +1,226 @@
+import { Placement } from '@floating-ui/dom';
+export { Placement } from '@floating-ui/dom';
+import { Controller, Application } from '@hotwired/stimulus';
+
+/**
+ * Headless **anchored positioning**: keeps a `floating` element placed against an
+ * `anchor`, flipping/shifting it away from viewport edges as the page scrolls or
+ * resizes. It is the declarative surface of the opt-in {@link attachPositioning}
+ * engine (`@floating-ui/dom`-based) — Radix's anchored popper / floating-ui's
+ * `autoUpdate`, exposed as a controller. No dedicated APG pattern; it is the
+ * placement primitive the popup patterns (Tooltip / Menu / Popover …) build on.
+ *
+ * Markup contract (identifier: `stimeo--anchored`):
+ *   <div data-controller="stimeo--anchored"
+ *        data-stimeo--anchored-placement-value="bottom-start"
+ *        data-stimeo--anchored-offset-value="8">
+ *     <button data-stimeo--anchored-target="anchor">Open</button>
+ *     <div data-stimeo--anchored-target="floating" role="…">…</div>
+ *   </div>
+ *
+ * `active` drives tracking (start/stop) and fires on connect, mirroring Focus
+ * Scope's `trapValueChanged`; set it `false` while the floating element is hidden
+ * so no measurement runs. The other Values map to {@link PositioningOptions} and
+ * re-apply live while tracking. Only `position`/`left`/`top` inline styles are
+ * written — never decoration — and the resolved (post-flip) side is mirrored onto
+ * `data-anchored-placement` on the floating element for CSS hooks (e.g. an arrow).
+ *
+ * @remarks
+ * Behavior only. It does **not** open/close, manage focus, or render an overlay
+ * (pair with Dialog / Popover and {@link "../controllers/focus_controller"}), and
+ * it does **not** move DOM (pair with Portal). It lives in the opt-in
+ * `stimeo-ui/positioning` subpath so the core `import "stimeo-ui"` stays
+ * zero-dependency; only consumers who register it pull in `@floating-ui/dom`. The
+ * `autoUpdate` cleanup is released on `disconnect()` (Turbo navigation included)
+ * so no observer outlives the element, and `#sync` reconciles to a single live
+ * observer (keyed on the applied options) so reconnects never stack observers.
+ */
+declare class AnchoredController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        placement: {
+            type: StringConstructor;
+            default: string;
+        };
+        offset: {
+            type: NumberConstructor;
+            default: number;
+        };
+        flip: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        shift: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        padding: {
+            type: NumberConstructor;
+            default: number;
+        };
+        strategy: {
+            type: StringConstructor;
+            default: string;
+        };
+        active: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    };
+    static events: readonly ["position"];
+    readonly anchorTarget: HTMLElement;
+    readonly floatingTarget: HTMLElement;
+    readonly hasAnchorTarget: boolean;
+    readonly hasFloatingTarget: boolean;
+    placementValue: string;
+    offsetValue: number;
+    flipValue: boolean;
+    shiftValue: boolean;
+    paddingValue: number;
+    strategyValue: string;
+    activeValue: boolean;
+    connect(): void;
+    disconnect(): void;
+    activeValueChanged(): void;
+    placementValueChanged(): void;
+    offsetValueChanged(): void;
+    flipValueChanged(): void;
+    shiftValueChanged(): void;
+    paddingValueChanged(): void;
+    strategyValueChanged(): void;
+}
+
+/**
+ * Opt-in shared positioning helper for Stimeo's floating components
+ * (popover / tooltip / hover-card / context-menu).
+ *
+ * **Why this is a separate entry point.** The core library is zero-runtime-dep:
+ * `import "stimeo-ui"` pulls in nothing but `@hotwired/stimulus`. Dynamic
+ * placement — measuring the viewport / scroll parents to flip and shift a
+ * floating element away from screen edges — genuinely needs a small, trustworthy
+ * dependency (`@floating-ui/dom`). To keep that cost *opt-in*, this lives at
+ * `stimeo-ui/positioning` and is loaded only when a consumer explicitly imports
+ * it. The controllers themselves never import this module, so the core install
+ * stays dependency-free.
+ *
+ * **What it does and does not own.** This helper writes **coordinates only** —
+ * `position`, `left`, `top` inline
+ * styles on the floating element. It never emits color, border, shadow, size, or
+ * any other decoration: the consumer's CSS still owns the entire look. Static
+ * placement (a fixed `top`/`left` in CSS) needs no JS at all; reach for this only
+ * when you want edge-collision avoidance.
+ */
+/** Options accepted by {@link position} and {@link attachPositioning}. */
+interface PositioningOptions {
+    /**
+     * Preferred side of the anchor to place the floating element on. Mirrors
+     * floating-ui's `Placement` (e.g. `"bottom"`, `"top-start"`). Default `"bottom"`.
+     */
+    placement?: Placement;
+    /** Gap in pixels between the anchor and the floating element. Default `0`. */
+    offset?: number;
+    /**
+     * Flip to the opposite side when the preferred side would overflow the
+     * viewport. Default `true`.
+     */
+    flip?: boolean;
+    /**
+     * Shift the floating element along its axis to keep it in view. Default `true`.
+     */
+    shift?: boolean;
+    /**
+     * Padding (px) kept between the floating element and the viewport edge when
+     * flipping/shifting. Default `0`.
+     */
+    padding?: number;
+    /**
+     * CSS positioning strategy written to the floating element. `"absolute"`
+     * (default) positions against the nearest positioned ancestor; `"fixed"`
+     * positions against the viewport (useful inside `overflow` containers).
+     */
+    strategy?: "absolute" | "fixed";
+}
+/**
+ * The resolved outcome of one positioning pass: the coordinates written to the
+ * floating element and the **final** placement after flip/shift. Returned by
+ * {@link position} and surfaced per update through {@link attachPositioning}'s
+ * `onComputed` callback so callers can react to the resolved side (e.g. flip an
+ * arrow, mirror the placement onto a `data-*` hook) without re-measuring.
+ */
+interface PositionResult {
+    /** Final placement after flip/shift resolved it (e.g. `"top-start"`). */
+    placement: Placement;
+    /** X coordinate written as the floating element's inline `left`. */
+    x: number;
+    /** Y coordinate written as the floating element's inline `top`. */
+    y: number;
+}
+/**
+ * Computes a single placement for `floating` relative to `anchor` and writes the
+ * resulting coordinates as inline styles on `floating`.
+ *
+ * This is the one-shot form: it positions once and returns. For a floating
+ * element that must track scrolling/resizing while open, use
+ * {@link attachPositioning} instead.
+ *
+ * Only `position`, `left`, and `top` are written — never any decoration. The
+ * resolved {@link PositionResult} (final placement + coordinates) is returned so
+ * callers can react to the side flip/shift chose.
+ */
+declare function position(anchor: Element, floating: HTMLElement, options?: PositioningOptions): Promise<PositionResult>;
+/**
+ * Positions `floating` against `anchor` and keeps it positioned across scroll,
+ * resize, and layout changes via floating-ui's `autoUpdate`.
+ *
+ * Returns a cleanup function that stops tracking; call it when the floating
+ * element closes or the controller disconnects (Turbo navigation included) so no
+ * observer outlives the element.
+ *
+ * Pass `onComputed` to receive the resolved {@link PositionResult} on every
+ * update (initial placement and each scroll/resize re-computation) — used to
+ * mirror the final placement onto a hook or emit an event without re-measuring.
+ *
+ * @example
+ * ```ts
+ * import { attachPositioning } from "stimeo-ui/positioning";
+ *
+ * // when a popover opens:
+ * const stop = attachPositioning(trigger, panel, { placement: "bottom-start", offset: 8 });
+ * // when it closes:
+ * stop();
+ * ```
+ */
+declare function attachPositioning(anchor: Element, floating: HTMLElement, options?: PositioningOptions, onComputed?: (result: PositionResult) => void): () => void;
+/**
+ * Maps the opt-in positioning controller identifiers to their classes. Kept
+ * separate from the core `stimeoControllers` (`src/index.ts`) so the core
+ * install never imports `@floating-ui/dom`; the Inspector manifest reflects both
+ * core and positioning controllers so `stimeo check` recognizes them.
+ */
+declare const positioningControllers: {
+    readonly "stimeo--anchored": typeof AnchoredController;
+};
+/**
+ * Registers the opt-in positioning controllers (e.g. `stimeo--anchored`) on a
+ * Stimulus application. Call this **in addition to** `registerStimeo` only when
+ * you want the declarative positioning primitives — importing this module is
+ * what pulls in `@floating-ui/dom`, so the core stays zero-dependency for
+ * consumers who never call it.
+ *
+ * @param application - The Stimulus application to register controllers on.
+ *
+ * @example
+ * ```ts
+ * import { Application } from "@hotwired/stimulus";
+ * import { registerStimeo } from "stimeo-ui";
+ * import { registerPositioning } from "stimeo-ui/positioning";
+ *
+ * const application = Application.start();
+ * registerStimeo(application);
+ * registerPositioning(application); // opt-in: adds stimeo--anchored
+ * ```
+ */
+declare function registerPositioning(application: Application): void;
+
+export { AnchoredController, type PositionResult, type PositioningOptions, attachPositioning, position, positioningControllers, registerPositioning };

package/dist/positioning/index.js

@@ -0,0 +1,145 @@
+import { computePosition, autoUpdate, offset, flip, shift } from '@floating-ui/dom';
+import { Controller } from '@hotwired/stimulus';
+
+// src/positioning/index.ts
+var AnchoredController = class extends Controller {
+  static targets = ["anchor", "floating"];
+  static values = {
+    placement: { type: String, default: "bottom" },
+    offset: { type: Number, default: 0 },
+    flip: { type: Boolean, default: true },
+    shift: { type: Boolean, default: true },
+    padding: { type: Number, default: 0 },
+    strategy: { type: String, default: "absolute" },
+    active: { type: Boolean, default: true }
+  };
+  static events = ["position"];
+  /** `autoUpdate` cleanup while tracking; `null` when detached. */
+  #stop = null;
+  /** True between connect and disconnect (Stimulus may fire value callbacks before connect). */
+  #connected = false;
+  /** Serialized options of the live observer, or `null` when detached — see {@link #sync}. */
+  #appliedKey = null;
+  connect() {
+    this.#connected = true;
+    this.#sync();
+  }
+  disconnect() {
+    this.#connected = false;
+    this.#sync();
+  }
+  // Every value change (active or an option) re-syncs. `#sync` is idempotent and
+  // order-independent, so no Value has to be declared in a particular position.
+  activeValueChanged() {
+    this.#sync();
+  }
+  placementValueChanged() {
+    this.#sync();
+  }
+  offsetValueChanged() {
+    this.#sync();
+  }
+  flipValueChanged() {
+    this.#sync();
+  }
+  shiftValueChanged() {
+    this.#sync();
+  }
+  paddingValueChanged() {
+    this.#sync();
+  }
+  strategyValueChanged() {
+    this.#sync();
+  }
+  /** Current Values mapped to the positioning engine's options. */
+  get #options() {
+    return {
+      placement: this.placementValue,
+      offset: this.offsetValue,
+      flip: this.flipValue,
+      shift: this.shiftValue,
+      padding: this.paddingValue,
+      // Narrow the free-form Value to the engine's union; anything but "fixed"
+      // falls back to the default "absolute".
+      strategy: this.strategyValue === "fixed" ? "fixed" : "absolute"
+    };
+  }
+  /**
+   * Reconciles the live observer with the desired state — track iff connected,
+   * `active`, and both targets exist — re-attaching only when that state or the
+   * options actually changed. Stimulus fires the value-changed callbacks on
+   * connect in declaration order and may run them before or after `connect()`;
+   * keying on the applied options collapses that whole burst (in any order) to a
+   * single attach, while an option change at runtime re-attaches exactly once. So
+   * correctness never depends on `active` being declared last.
+   */
+  #sync() {
+    const shouldTrack = this.#connected && this.activeValue && this.hasAnchorTarget && this.hasFloatingTarget;
+    const key = shouldTrack ? JSON.stringify(this.#options) : null;
+    if (key === this.#appliedKey) return;
+    this.#detach();
+    this.#appliedKey = key;
+    if (shouldTrack) this.#attach();
+  }
+  #attach() {
+    this.#stop = attachPositioning(
+      this.anchorTarget,
+      this.floatingTarget,
+      this.#options,
+      (result) => this.#onComputed(result)
+    );
+  }
+  #detach() {
+    this.#stop?.();
+    this.#stop = null;
+  }
+  /** Reflects the resolved side onto the CSS hook and announces the placement. */
+  #onComputed(result) {
+    this.floatingTarget.setAttribute("data-anchored-placement", result.placement);
+    this.dispatch("position", {
+      detail: { placement: result.placement, x: result.x, y: result.y }
+    });
+  }
+};
+
+// src/positioning/index.ts
+function buildMiddleware(options) {
+  const padding = options.padding ?? 0;
+  const middleware = [];
+  if (options.offset) middleware.push(offset(options.offset));
+  if (options.flip !== false) middleware.push(flip({ padding }));
+  if (options.shift !== false) middleware.push(shift({ padding }));
+  return middleware;
+}
+async function position(anchor, floating, options = {}) {
+  const strategy = options.strategy ?? "absolute";
+  const config = {
+    placement: options.placement ?? "bottom",
+    middleware: buildMiddleware(options),
+    strategy
+  };
+  const { x, y, placement } = await computePosition(anchor, floating, config);
+  Object.assign(floating.style, {
+    position: strategy,
+    left: `${x}px`,
+    top: `${y}px`
+  });
+  return { x, y, placement };
+}
+function attachPositioning(anchor, floating, options = {}, onComputed) {
+  return autoUpdate(anchor, floating, () => {
+    void position(anchor, floating, options).then((result) => onComputed?.(result));
+  });
+}
+var positioningControllers = {
+  "stimeo--anchored": AnchoredController
+};
+function registerPositioning(application) {
+  for (const [identifier, controller] of Object.entries(positioningControllers)) {
+    application.register(identifier, controller);
+  }
+}
+
+export { AnchoredController, attachPositioning, position, positioningControllers, registerPositioning };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/positioning/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/positioning/anchored_controller.ts","../../src/positioning/index.ts"],"names":[],"mappings":";;;;AAoCO,IAAM,kBAAA,GAAN,cAAiC,UAAA,CAAwB;AAAA,EAC9D,OAAgB,OAAA,GAAU,CAAC,QAAA,EAAU,UAAU,CAAA;AAAA,EAC/C,OAAgB,MAAA,GAAS;AAAA,IACvB,SAAA,EAAW,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,QAAA,EAAS;AAAA,IAC7C,MAAA,EAAQ,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,CAAA,EAAE;AAAA,IACnC,IAAA,EAAM,EAAE,IAAA,EAAM,OAAA,EAAS,SAAS,IAAA,EAAK;AAAA,IACrC,KAAA,EAAO,EAAE,IAAA,EAAM,OAAA,EAAS,SAAS,IAAA,EAAK;AAAA,IACtC,OAAA,EAAS,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,CAAA,EAAE;AAAA,IACpC,QAAA,EAAU,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,UAAA,EAAW;AAAA,IAC9C,MAAA,EAAQ,EAAE,IAAA,EAAM,OAAA,EAAS,SAAS,IAAA;AAAK,GACzC;AAAA,EACA,OAAO,MAAA,GAAS,CAAC,UAAU,CAAA;AAAA;AAAA,EAgB3B,KAAA,GAA6B,IAAA;AAAA;AAAA,EAE7B,UAAA,GAAa,KAAA;AAAA;AAAA,EAEb,WAAA,GAA6B,IAAA;AAAA,EAEpB,OAAA,GAAgB;AACvB,IAAA,IAAA,CAAK,UAAA,GAAa,IAAA;AAClB,IAAA,IAAA,CAAK,KAAA,EAAM;AAAA,EACb;AAAA,EAES,UAAA,GAAmB;AAC1B,IAAA,IAAA,CAAK,UAAA,GAAa,KAAA;AAClB,IAAA,IAAA,CAAK,KAAA,EAAM;AAAA,EACb;AAAA;AAAA;AAAA,EAIA,kBAAA,GAA2B;AACzB,IAAA,IAAA,CAAK,KAAA,EAAM;AAAA,EACb;AAAA,EACA,qBAAA,GAA8B;AAC5B,IAAA,IAAA,CAAK,KAAA,EAAM;AAAA,EACb;AAAA,EACA,kBAAA,GAA2B;AACzB,IAAA,IAAA,CAAK,KAAA,EAAM;AAAA,EACb;AAAA,EACA,gBAAA,GAAyB;AACvB,IAAA,IAAA,CAAK,KAAA,EAAM;AAAA,EACb;AAAA,EACA,iBAAA,GAA0B;AACxB,IAAA,IAAA,CAAK,KAAA,EAAM;AAAA,EACb;AAAA,EACA,mBAAA,GAA4B;AAC1B,IAAA,IAAA,CAAK,KAAA,EAAM;AAAA,EACb;AAAA,EACA,oBAAA,GAA6B;AAC3B,IAAA,IAAA,CAAK,KAAA,EAAM;AAAA,EACb;AAAA;AAAA,EAGA,IAAI,QAAA,GAA+B;AACjC,IAAA,OAAO;AAAA,MACL,WAAW,IAAA,CAAK,cAAA;AAAA,MAChB,QAAQ,IAAA,CAAK,WAAA;AAAA,MACb,MAAM,IAAA,CAAK,SAAA;AAAA,MACX,OAAO,IAAA,CAAK,UAAA;AAAA,MACZ,SAAS,IAAA,CAAK,YAAA;AAAA;AAAA;AAAA,MAGd,QAAA,EAAU,IAAA,CAAK,aAAA,KAAkB,OAAA,GAAU,OAAA,GAAU;AAAA,KACvD;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,KAAA,GAAc;AACZ,IAAA,MAAM,cACJ,IAAA,CAAK,UAAA,IAAc,KAAK,WAAA,IAAe,IAAA,CAAK,mBAAmB,IAAA,CAAK,iBAAA;AACtE,IAAA,MAAM,MAAM,WAAA,GAAc,IAAA,CAAK,SAAA,CAAU,IAAA,CAAK,QAAQ,CAAA,GAAI,IAAA;AAC1D,IAAA,IAAI,GAAA,KAAQ,KAAK,WAAA,EAAa;AAC9B,IAAA,IAAA,CAAK,OAAA,EAAQ;AACb,IAAA,IAAA,CAAK,WAAA,GAAc,GAAA;AACnB,IAAA,IAAI,WAAA,OAAkB,OAAA,EAAQ;AAAA,EAChC;AAAA,EAEA,OAAA,GAAgB;AACd,IAAA,IAAA,CAAK,KAAA,GAAQ,iBAAA;AAAA,MACX,IAAA,CAAK,YAAA;AAAA,MACL,IAAA,CAAK,cAAA;AAAA,MACL,IAAA,CAAK,QAAA;AAAA,MACL,CAAC,MAAA,KAAW,IAAA,CAAK,WAAA,CAAY,MAAM;AAAA,KACrC;AAAA,EACF;AAAA,EAEA,OAAA,GAAgB;AACd,IAAA,IAAA,CAAK,KAAA,IAAQ;AACb,IAAA,IAAA,CAAK,KAAA,GAAQ,IAAA;AAAA,EACf;AAAA;AAAA,EAGA,YAAY,MAAA,EAA8B;AACxC,IAAA,IAAA,CAAK,cAAA,CAAe,YAAA,CAAa,yBAAA,EAA2B,MAAA,CAAO,SAAS,CAAA;AAC5E,IAAA,IAAA,CAAK,SAAS,UAAA,EAAY;AAAA,MACxB,MAAA,EAAQ,EAAE,SAAA,EAAW,MAAA,CAAO,SAAA,EAAW,GAAG,MAAA,CAAO,CAAA,EAAG,CAAA,EAAG,MAAA,CAAO,CAAA;AAAE,KACjE,CAAA;AAAA,EACH;AACF;;;ACxEA,SAAS,gBAAgB,OAAA,EAA2C;AAClE,EAAA,MAAM,OAAA,GAAU,QAAQ,OAAA,IAAW,CAAA;AACnC,EAAA,MAAM,aAA2B,EAAC;AAClC,EAAA,IAAI,QAAQ,MAAA,EAAQ,UAAA,CAAW,KAAK,MAAA,CAAO,OAAA,CAAQ,MAAM,CAAC,CAAA;AAE1D,EAAA,IAAI,OAAA,CAAQ,SAAS,KAAA,EAAO,UAAA,CAAW,KAAK,IAAA,CAAK,EAAE,OAAA,EAAS,CAAC,CAAA;AAC7D,EAAA,IAAI,OAAA,CAAQ,UAAU,KAAA,EAAO,UAAA,CAAW,KAAK,KAAA,CAAM,EAAE,OAAA,EAAS,CAAC,CAAA;AAC/D,EAAA,OAAO,UAAA;AACT;AAcA,eAAsB,QAAA,CACpB,MAAA,EACA,QAAA,EACA,OAAA,GAA8B,EAAC,EACN;AACzB,EAAA,MAAM,QAAA,GAAW,QAAQ,QAAA,IAAY,UAAA;AACrC,EAAA,MAAM,MAAA,GAAyC;AAAA,IAC7C,SAAA,EAAW,QAAQ,SAAA,IAAa,QAAA;AAAA,IAChC,UAAA,EAAY,gBAAgB,OAAO,CAAA;AAAA,IACnC;AAAA,GACF;AACA,EAAA,MAAM,EAAE,GAAG,CAAA,EAAG,SAAA,KAAc,MAAM,eAAA,CAAgB,MAAA,EAAQ,QAAA,EAAU,MAAM,CAAA;AAC1E,EAAA,MAAA,CAAO,MAAA,CAAO,SAAS,KAAA,EAAO;AAAA,IAC5B,QAAA,EAAU,QAAA;AAAA,IACV,IAAA,EAAM,GAAG,CAAC,CAAA,EAAA,CAAA;AAAA,IACV,GAAA,EAAK,GAAG,CAAC,CAAA,EAAA;AAAA,GACV,CAAA;AACD,EAAA,OAAO,EAAE,CAAA,EAAG,CAAA,EAAG,SAAA,EAAU;AAC3B;AAwBO,SAAS,kBACd,MAAA,EACA,QAAA,EACA,OAAA,GAA8B,IAC9B,UAAA,EACY;AACZ,EAAA,OAAO,UAAA,CAAW,MAAA,EAAQ,QAAA,EAAU,MAAM;AACxC,IAAA,KAAK,QAAA,CAAS,MAAA,EAAQ,QAAA,EAAU,OAAO,CAAA,CAAE,KAAK,CAAC,MAAA,KAAW,UAAA,GAAa,MAAM,CAAC,CAAA;AAAA,EAChF,CAAC,CAAA;AACH;AAQO,IAAM,sBAAA,GAAyB;AAAA,EACpC,kBAAA,EAAoB;AACtB;AAsBO,SAAS,oBAAoB,WAAA,EAAgC;AAClE,EAAA,KAAA,MAAW,CAAC,UAAA,EAAY,UAAU,KAAK,MAAA,CAAO,OAAA,CAAQ,sBAAsB,CAAA,EAAG;AAC7E,IAAA,WAAA,CAAY,QAAA,CAAS,YAAY,UAAU,CAAA;AAAA,EAC7C;AACF","file":"index.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\nimport { attachPositioning, type Placement, type PositioningOptions, type PositionResult } from \".\";\n\n/**\n * Headless **anchored positioning**: keeps a `floating` element placed against an\n * `anchor`, flipping/shifting it away from viewport edges as the page scrolls or\n * resizes. It is the declarative surface of the opt-in {@link attachPositioning}\n * engine (`@floating-ui/dom`-based) — Radix's anchored popper / floating-ui's\n * `autoUpdate`, exposed as a controller. No dedicated APG pattern; it is the\n * placement primitive the popup patterns (Tooltip / Menu / Popover …) build on.\n *\n * Markup contract (identifier: `stimeo--anchored`):\n *   <div data-controller=\"stimeo--anchored\"\n *        data-stimeo--anchored-placement-value=\"bottom-start\"\n *        data-stimeo--anchored-offset-value=\"8\">\n *     <button data-stimeo--anchored-target=\"anchor\">Open</button>\n *     <div data-stimeo--anchored-target=\"floating\" role=\"…\">…</div>\n *   </div>\n *\n * `active` drives tracking (start/stop) and fires on connect, mirroring Focus\n * Scope's `trapValueChanged`; set it `false` while the floating element is hidden\n * so no measurement runs. The other Values map to {@link PositioningOptions} and\n * re-apply live while tracking. Only `position`/`left`/`top` inline styles are\n * written — never decoration — and the resolved (post-flip) side is mirrored onto\n * `data-anchored-placement` on the floating element for CSS hooks (e.g. an arrow).\n *\n * @remarks\n * Behavior only. It does **not** open/close, manage focus, or render an overlay\n * (pair with Dialog / Popover and {@link \"../controllers/focus_controller\"}), and\n * it does **not** move DOM (pair with Portal). It lives in the opt-in\n * `stimeo-ui/positioning` subpath so the core `import \"stimeo-ui\"` stays\n * zero-dependency; only consumers who register it pull in `@floating-ui/dom`. The\n * `autoUpdate` cleanup is released on `disconnect()` (Turbo navigation included)\n * so no observer outlives the element, and `#sync` reconciles to a single live\n * observer (keyed on the applied options) so reconnects never stack observers.\n */\nexport class AnchoredController extends Controller<HTMLElement> {\n  static override targets = [\"anchor\", \"floating\"];\n  static override values = {\n    placement: { type: String, default: \"bottom\" },\n    offset: { type: Number, default: 0 },\n    flip: { type: Boolean, default: true },\n    shift: { type: Boolean, default: true },\n    padding: { type: Number, default: 0 },\n    strategy: { type: String, default: \"absolute\" },\n    active: { type: Boolean, default: true },\n  };\n  static events = [\"position\"] as const;\n\n  declare readonly anchorTarget: HTMLElement;\n  declare readonly floatingTarget: HTMLElement;\n  declare readonly hasAnchorTarget: boolean;\n  declare readonly hasFloatingTarget: boolean;\n\n  declare placementValue: string;\n  declare offsetValue: number;\n  declare flipValue: boolean;\n  declare shiftValue: boolean;\n  declare paddingValue: number;\n  declare strategyValue: string;\n  declare activeValue: boolean;\n\n  /** `autoUpdate` cleanup while tracking; `null` when detached. */\n  #stop: (() => void) | null = null;\n  /** True between connect and disconnect (Stimulus may fire value callbacks before connect). */\n  #connected = false;\n  /** Serialized options of the live observer, or `null` when detached — see {@link #sync}. */\n  #appliedKey: string | null = null;\n\n  override connect(): void {\n    this.#connected = true;\n    this.#sync();\n  }\n\n  override disconnect(): void {\n    this.#connected = false;\n    this.#sync();\n  }\n\n  // Every value change (active or an option) re-syncs. `#sync` is idempotent and\n  // order-independent, so no Value has to be declared in a particular position.\n  activeValueChanged(): void {\n    this.#sync();\n  }\n  placementValueChanged(): void {\n    this.#sync();\n  }\n  offsetValueChanged(): void {\n    this.#sync();\n  }\n  flipValueChanged(): void {\n    this.#sync();\n  }\n  shiftValueChanged(): void {\n    this.#sync();\n  }\n  paddingValueChanged(): void {\n    this.#sync();\n  }\n  strategyValueChanged(): void {\n    this.#sync();\n  }\n\n  /** Current Values mapped to the positioning engine's options. */\n  get #options(): PositioningOptions {\n    return {\n      placement: this.placementValue as Placement,\n      offset: this.offsetValue,\n      flip: this.flipValue,\n      shift: this.shiftValue,\n      padding: this.paddingValue,\n      // Narrow the free-form Value to the engine's union; anything but \"fixed\"\n      // falls back to the default \"absolute\".\n      strategy: this.strategyValue === \"fixed\" ? \"fixed\" : \"absolute\",\n    };\n  }\n\n  /**\n   * Reconciles the live observer with the desired state — track iff connected,\n   * `active`, and both targets exist — re-attaching only when that state or the\n   * options actually changed. Stimulus fires the value-changed callbacks on\n   * connect in declaration order and may run them before or after `connect()`;\n   * keying on the applied options collapses that whole burst (in any order) to a\n   * single attach, while an option change at runtime re-attaches exactly once. So\n   * correctness never depends on `active` being declared last.\n   */\n  #sync(): void {\n    const shouldTrack =\n      this.#connected && this.activeValue && this.hasAnchorTarget && this.hasFloatingTarget;\n    const key = shouldTrack ? JSON.stringify(this.#options) : null;\n    if (key === this.#appliedKey) return;\n    this.#detach();\n    this.#appliedKey = key;\n    if (shouldTrack) this.#attach();\n  }\n\n  #attach(): void {\n    this.#stop = attachPositioning(\n      this.anchorTarget,\n      this.floatingTarget,\n      this.#options,\n      (result) => this.#onComputed(result),\n    );\n  }\n\n  #detach(): void {\n    this.#stop?.();\n    this.#stop = null;\n  }\n\n  /** Reflects the resolved side onto the CSS hook and announces the placement. */\n  #onComputed(result: PositionResult): void {\n    this.floatingTarget.setAttribute(\"data-anchored-placement\", result.placement);\n    this.dispatch(\"position\", {\n      detail: { placement: result.placement, x: result.x, y: result.y },\n    });\n  }\n}\n","import {\n  autoUpdate,\n  type ComputePositionConfig,\n  computePosition,\n  flip,\n  type Middleware,\n  offset,\n  type Placement,\n  shift,\n} from \"@floating-ui/dom\";\nimport type { Application } from \"@hotwired/stimulus\";\nimport { AnchoredController } from \"./anchored_controller\";\n\nexport type { Placement };\nexport { AnchoredController };\n\n/**\n * Opt-in shared positioning helper for Stimeo's floating components\n * (popover / tooltip / hover-card / context-menu).\n *\n * **Why this is a separate entry point.** The core library is zero-runtime-dep:\n * `import \"stimeo-ui\"` pulls in nothing but `@hotwired/stimulus`. Dynamic\n * placement — measuring the viewport / scroll parents to flip and shift a\n * floating element away from screen edges — genuinely needs a small, trustworthy\n * dependency (`@floating-ui/dom`). To keep that cost *opt-in*, this lives at\n * `stimeo-ui/positioning` and is loaded only when a consumer explicitly imports\n * it. The controllers themselves never import this module, so the core install\n * stays dependency-free.\n *\n * **What it does and does not own.** This helper writes **coordinates only** —\n * `position`, `left`, `top` inline\n * styles on the floating element. It never emits color, border, shadow, size, or\n * any other decoration: the consumer's CSS still owns the entire look. Static\n * placement (a fixed `top`/`left` in CSS) needs no JS at all; reach for this only\n * when you want edge-collision avoidance.\n */\n\n/** Options accepted by {@link position} and {@link attachPositioning}. */\nexport interface PositioningOptions {\n  /**\n   * Preferred side of the anchor to place the floating element on. Mirrors\n   * floating-ui's `Placement` (e.g. `\"bottom\"`, `\"top-start\"`). Default `\"bottom\"`.\n   */\n  placement?: Placement;\n  /** Gap in pixels between the anchor and the floating element. Default `0`. */\n  offset?: number;\n  /**\n   * Flip to the opposite side when the preferred side would overflow the\n   * viewport. Default `true`.\n   */\n  flip?: boolean;\n  /**\n   * Shift the floating element along its axis to keep it in view. Default `true`.\n   */\n  shift?: boolean;\n  /**\n   * Padding (px) kept between the floating element and the viewport edge when\n   * flipping/shifting. Default `0`.\n   */\n  padding?: number;\n  /**\n   * CSS positioning strategy written to the floating element. `\"absolute\"`\n   * (default) positions against the nearest positioned ancestor; `\"fixed\"`\n   * positions against the viewport (useful inside `overflow` containers).\n   */\n  strategy?: \"absolute\" | \"fixed\";\n}\n\n/**\n * The resolved outcome of one positioning pass: the coordinates written to the\n * floating element and the **final** placement after flip/shift. Returned by\n * {@link position} and surfaced per update through {@link attachPositioning}'s\n * `onComputed` callback so callers can react to the resolved side (e.g. flip an\n * arrow, mirror the placement onto a `data-*` hook) without re-measuring.\n */\nexport interface PositionResult {\n  /** Final placement after flip/shift resolved it (e.g. `\"top-start\"`). */\n  placement: Placement;\n  /** X coordinate written as the floating element's inline `left`. */\n  x: number;\n  /** Y coordinate written as the floating element's inline `top`. */\n  y: number;\n}\n\n/** Builds the floating-ui middleware stack from {@link PositioningOptions}. */\nfunction buildMiddleware(options: PositioningOptions): Middleware[] {\n  const padding = options.padding ?? 0;\n  const middleware: Middleware[] = [];\n  if (options.offset) middleware.push(offset(options.offset));\n  // flip before shift so a side change is considered before nudging along-axis.\n  if (options.flip !== false) middleware.push(flip({ padding }));\n  if (options.shift !== false) middleware.push(shift({ padding }));\n  return middleware;\n}\n\n/**\n * Computes a single placement for `floating` relative to `anchor` and writes the\n * resulting coordinates as inline styles on `floating`.\n *\n * This is the one-shot form: it positions once and returns. For a floating\n * element that must track scrolling/resizing while open, use\n * {@link attachPositioning} instead.\n *\n * Only `position`, `left`, and `top` are written — never any decoration. The\n * resolved {@link PositionResult} (final placement + coordinates) is returned so\n * callers can react to the side flip/shift chose.\n */\nexport async function position(\n  anchor: Element,\n  floating: HTMLElement,\n  options: PositioningOptions = {},\n): Promise<PositionResult> {\n  const strategy = options.strategy ?? \"absolute\";\n  const config: Partial<ComputePositionConfig> = {\n    placement: options.placement ?? \"bottom\",\n    middleware: buildMiddleware(options),\n    strategy,\n  };\n  const { x, y, placement } = await computePosition(anchor, floating, config);\n  Object.assign(floating.style, {\n    position: strategy,\n    left: `${x}px`,\n    top: `${y}px`,\n  });\n  return { x, y, placement };\n}\n\n/**\n * Positions `floating` against `anchor` and keeps it positioned across scroll,\n * resize, and layout changes via floating-ui's `autoUpdate`.\n *\n * Returns a cleanup function that stops tracking; call it when the floating\n * element closes or the controller disconnects (Turbo navigation included) so no\n * observer outlives the element.\n *\n * Pass `onComputed` to receive the resolved {@link PositionResult} on every\n * update (initial placement and each scroll/resize re-computation) — used to\n * mirror the final placement onto a hook or emit an event without re-measuring.\n *\n * @example\n * ```ts\n * import { attachPositioning } from \"stimeo-ui/positioning\";\n *\n * // when a popover opens:\n * const stop = attachPositioning(trigger, panel, { placement: \"bottom-start\", offset: 8 });\n * // when it closes:\n * stop();\n * ```\n */\nexport function attachPositioning(\n  anchor: Element,\n  floating: HTMLElement,\n  options: PositioningOptions = {},\n  onComputed?: (result: PositionResult) => void,\n): () => void {\n  return autoUpdate(anchor, floating, () => {\n    void position(anchor, floating, options).then((result) => onComputed?.(result));\n  });\n}\n\n/**\n * Maps the opt-in positioning controller identifiers to their classes. Kept\n * separate from the core `stimeoControllers` (`src/index.ts`) so the core\n * install never imports `@floating-ui/dom`; the Inspector manifest reflects both\n * core and positioning controllers so `stimeo check` recognizes them.\n */\nexport const positioningControllers = {\n  \"stimeo--anchored\": AnchoredController,\n} as const;\n\n/**\n * Registers the opt-in positioning controllers (e.g. `stimeo--anchored`) on a\n * Stimulus application. Call this **in addition to** `registerStimeo` only when\n * you want the declarative positioning primitives — importing this module is\n * what pulls in `@floating-ui/dom`, so the core stays zero-dependency for\n * consumers who never call it.\n *\n * @param application - The Stimulus application to register controllers on.\n *\n * @example\n * ```ts\n * import { Application } from \"@hotwired/stimulus\";\n * import { registerStimeo } from \"stimeo-ui\";\n * import { registerPositioning } from \"stimeo-ui/positioning\";\n *\n * const application = Application.start();\n * registerStimeo(application);\n * registerPositioning(application); // opt-in: adds stimeo--anchored\n * ```\n */\nexport function registerPositioning(application: Application): void {\n  for (const [identifier, controller] of Object.entries(positioningControllers)) {\n    application.register(identifier, controller);\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "stimeo-ui",
+  "version": "0.1.0-alpha.1",
+  "description": "Headless Stimulus UI framework for Ruby on Rails — behavior-only, accessible components driven by HTML attributes.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Stimeo Labs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taiyaky/stimeo-ui.git"
+  },
+  "homepage": "https://github.com/taiyaky/stimeo-ui#readme",
+  "bugs": {
+    "url": "https://github.com/taiyaky/stimeo-ui/issues"
+  },
+  "keywords": [
+    "stimulus",
+    "rails",
+    "hotwire",
+    "turbo",
+    "headless",
+    "ui",
+    "components",
+    "accessibility",
+    "wai-aria",
+    "a11y"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./controllers/*": {
+      "types": "./dist/controllers/*.d.ts",
+      "import": "./dist/controllers/*.js"
+    },
+    "./positioning": {
+      "types": "./dist/positioning/index.d.ts",
+      "import": "./dist/positioning/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "stimeo": "./dist/inspector/cli_bin.js"
+  },
+  "scripts": {
+    "build": "tsup && bun scripts/postbuild.ts",
+    "dev": "tsup --watch --onSuccess \"bun scripts/postbuild.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write ."
+  },
+  "peerDependencies": {
+    "@floating-ui/dom": ">=1.6.0",
+    "@hotwired/stimulus": ">=3.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@floating-ui/dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.16",
+    "@floating-ui/dom": "1.7.6",
+    "@guidepup/virtual-screen-reader": "0.32.1",
+    "@hotwired/stimulus": "3.2.2",
+    "@hotwired/turbo": "8.0.23",
+    "@types/node": "22.19.19",
+    "@vitest/coverage-istanbul": "4.1.8",
+    "axe-core": "4.12.0",
+    "happy-dom": "20.9.0",
+    "tsup": "8.5.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.8",
+    "vitest-axe": "0.1.0"
+  },
+  "overrides": {
+    "rollup": "4.61.1"
+  }
+}