stimeo-ui 0.15.0 → 0.16.0

package/dist/positioning/index.js

@@ -112,6 +112,8 @@ var AnchoredController = class extends Controller {
    * declared last. The elements are part of the key because the engine holds the
    * pair it was handed: a swap leaves the same options behind and would otherwise
    * keep measuring the node that just left the document.
+   *
+   * @stimeoRenderRoot
    */
   #sync() {
     const shouldTrack = this.#connected && this.activeValue && this.hasAnchorTarget && this.hasFloatingTarget;

package/dist/positioning/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/positioning/anchored_controller.ts","../../src/positioning/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\nimport { attachPositioning, type Placement, type PositioningOptions, type PositionResult } from \".\";\n\n/**\n * Every placement the engine accepts. A declaration outside the set has no\n * resolved side to publish, so it falls back to the Value's default rather than\n * reaching the state hook and the event detail as-is.\n */\nconst PLACEMENTS: ReadonlySet<string> = new Set([\n  \"top\",\n  \"top-start\",\n  \"top-end\",\n  \"right\",\n  \"right-start\",\n  \"right-end\",\n  \"bottom\",\n  \"bottom-start\",\n  \"bottom-end\",\n  \"left\",\n  \"left-start\",\n  \"left-end\",\n]);\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), exposing its `autoUpdate` behavior as a\n * 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. A declaration the engine cannot use — a\n * `placement` outside its set, a non-finite `offset` or `padding` — falls back to\n * that Value's default, so a typo never reaches the coordinates or the hook. Only\n * `position`/`left`/`top` inline styles are written — never decoration — and the\n * resolved (post-flip) side is mirrored onto `data-anchored-placement` on the\n * floating element for CSS hooks (e.g. an arrow).\n *\n * Tracking follows the targets themselves, not just the Values: the engine holds\n * the two elements it was handed, so a target added, removed or swapped at\n * runtime re-attaches against whatever is there now.\n *\n * `position` dispatches `{ placement, x, y }`.\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 and elements) so reconnects never stack\n * observers. That cleanup stops future updates but cannot cancel one already\n * computing, so a pass that lands after its own attach was replaced stands down\n * instead of writing.\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  /** Identity of the live attach; `null` when detached — see {@link #onComputed}. */\n  #attachId: symbol | null = null;\n  /** True between connect and disconnect (Stimulus may fire value callbacks before connect). */\n  #connected = false;\n  /**\n   * Serialized options as of the last reconcile, empty only before the first one —\n   * a value no serialization produces, so it can never match a real key.\n   */\n  #appliedKey = \"\";\n  /** Elements the live observer holds, or `null` when detached — see {@link #sync}. */\n  #appliedAnchor: Element | null = null;\n  #appliedFloating: HTMLElement | 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) and every target arrival or\n  // departure re-syncs. `#sync` is idempotent and order-independent, so no Value\n  // has to be declared in a particular position.\n  anchorTargetConnected(): void {\n    this.#sync();\n  }\n  anchorTargetDisconnected(): void {\n    this.#sync();\n  }\n  floatingTargetConnected(): void {\n    this.#sync();\n  }\n  floatingTargetDisconnected(): void {\n    this.#sync();\n  }\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      // Narrow every free-form Value to what the engine can use. A placement\n      // outside the set would be published on the hook as a resolved side it is\n      // not, and a non-finite distance poisons the coordinate it feeds until the\n      // browser drops the whole declaration and leaves that axis unplaced.\n      placement: PLACEMENTS.has(this.placementValue)\n        ? (this.placementValue as Placement)\n        : \"bottom\",\n      offset: Number.isFinite(this.offsetValue) ? this.offsetValue : 0,\n      flip: this.flipValue,\n      shift: this.shiftValue,\n      padding: Number.isFinite(this.paddingValue) ? this.paddingValue : 0,\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, the\n   * options, or the elements actually changed. Stimulus fires the value-changed\n   * callbacks on connect in declaration order and may run them before or after\n   * `connect()`; keying on what is applied collapses that whole burst (in any\n   * order) to a single attach, while an option or target change at runtime\n   * re-attaches exactly once. So correctness never depends on `active` being\n   * declared last. The elements are part of the key because the engine holds the\n   * pair it was handed: a swap leaves the same options behind and would otherwise\n   * keep measuring the node that just left the document.\n   */\n  #sync(): void {\n    const shouldTrack =\n      this.#connected && this.activeValue && this.hasAnchorTarget && this.hasFloatingTarget;\n    const anchor = shouldTrack ? this.anchorTarget : null;\n    const floating = shouldTrack ? this.floatingTarget : null;\n    // The elements already say whether anything is tracked, so the key only has\n    // to say which options are on it.\n    const key = JSON.stringify(this.#options);\n    if (\n      key === this.#appliedKey &&\n      anchor === this.#appliedAnchor &&\n      floating === this.#appliedFloating\n    ) {\n      return;\n    }\n    this.#detach();\n    this.#appliedKey = key;\n    this.#appliedAnchor = anchor;\n    this.#appliedFloating = floating;\n    if (anchor && floating) this.#attach(anchor, floating);\n  }\n\n  #attach(anchor: Element, floating: HTMLElement): void {\n    const id = Symbol(\"anchored-attach\");\n    this.#attachId = id;\n    this.#stop = attachPositioning(anchor, floating, this.#options, (result) =>\n      this.#onComputed(id, floating, result),\n    );\n  }\n\n  #detach(): void {\n    this.#stop?.();\n    this.#stop = null;\n    this.#attachId = null;\n  }\n\n  /**\n   * Reflects the resolved side onto the CSS hook and announces the placement.\n   *\n   * The pass carries the attach that started it and the element it positioned,\n   * and lands only while that attach is still the live one: `autoUpdate`'s\n   * cleanup stops further updates but cannot cancel one already computing, so a\n   * pass superseded mid-flight would otherwise write and dispatch afterwards.\n   * The element cannot stand in for that identity — an option change re-attaches\n   * against the very same pair.\n   */\n  #onComputed(id: symbol, floating: HTMLElement, result: PositionResult): void {\n    if (id !== this.#attachId) return;\n    floating.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"]}
+{"version":3,"sources":["../../src/positioning/anchored_controller.ts","../../src/positioning/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\nimport { attachPositioning, type Placement, type PositioningOptions, type PositionResult } from \".\";\n\n/**\n * Every placement the engine accepts. A declaration outside the set has no\n * resolved side to publish, so it falls back to the Value's default rather than\n * reaching the state hook and the event detail as-is.\n */\nconst PLACEMENTS: ReadonlySet<string> = new Set([\n  \"top\",\n  \"top-start\",\n  \"top-end\",\n  \"right\",\n  \"right-start\",\n  \"right-end\",\n  \"bottom\",\n  \"bottom-start\",\n  \"bottom-end\",\n  \"left\",\n  \"left-start\",\n  \"left-end\",\n]);\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), exposing its `autoUpdate` behavior as a\n * 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. A declaration the engine cannot use — a\n * `placement` outside its set, a non-finite `offset` or `padding` — falls back to\n * that Value's default, so a typo never reaches the coordinates or the hook. Only\n * `position`/`left`/`top` inline styles are written — never decoration — and the\n * resolved (post-flip) side is mirrored onto `data-anchored-placement` on the\n * floating element for CSS hooks (e.g. an arrow).\n *\n * Tracking follows the targets themselves, not just the Values: the engine holds\n * the two elements it was handed, so a target added, removed or swapped at\n * runtime re-attaches against whatever is there now.\n *\n * `position` dispatches `{ placement, x, y }`.\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 and elements) so reconnects never stack\n * observers. That cleanup stops future updates but cannot cancel one already\n * computing, so a pass that lands after its own attach was replaced stands down\n * instead of writing.\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  /** Identity of the live attach; `null` when detached — see {@link #onComputed}. */\n  #attachId: symbol | null = null;\n  /** True between connect and disconnect (Stimulus may fire value callbacks before connect). */\n  #connected = false;\n  /**\n   * Serialized options as of the last reconcile, empty only before the first one —\n   * a value no serialization produces, so it can never match a real key.\n   */\n  #appliedKey = \"\";\n  /** Elements the live observer holds, or `null` when detached — see {@link #sync}. */\n  #appliedAnchor: Element | null = null;\n  #appliedFloating: HTMLElement | 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) and every target arrival or\n  // departure re-syncs. `#sync` is idempotent and order-independent, so no Value\n  // has to be declared in a particular position.\n  anchorTargetConnected(): void {\n    this.#sync();\n  }\n  anchorTargetDisconnected(): void {\n    this.#sync();\n  }\n  floatingTargetConnected(): void {\n    this.#sync();\n  }\n  floatingTargetDisconnected(): void {\n    this.#sync();\n  }\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      // Narrow every free-form Value to what the engine can use. A placement\n      // outside the set would be published on the hook as a resolved side it is\n      // not, and a non-finite distance poisons the coordinate it feeds until the\n      // browser drops the whole declaration and leaves that axis unplaced.\n      placement: PLACEMENTS.has(this.placementValue)\n        ? (this.placementValue as Placement)\n        : \"bottom\",\n      offset: Number.isFinite(this.offsetValue) ? this.offsetValue : 0,\n      flip: this.flipValue,\n      shift: this.shiftValue,\n      padding: Number.isFinite(this.paddingValue) ? this.paddingValue : 0,\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, the\n   * options, or the elements actually changed. Stimulus fires the value-changed\n   * callbacks on connect in declaration order and may run them before or after\n   * `connect()`; keying on what is applied collapses that whole burst (in any\n   * order) to a single attach, while an option or target change at runtime\n   * re-attaches exactly once. So correctness never depends on `active` being\n   * declared last. The elements are part of the key because the engine holds the\n   * pair it was handed: a swap leaves the same options behind and would otherwise\n   * keep measuring the node that just left the document.\n   *\n   * @stimeoRenderRoot\n   */\n  #sync(): void {\n    const shouldTrack =\n      this.#connected && this.activeValue && this.hasAnchorTarget && this.hasFloatingTarget;\n    const anchor = shouldTrack ? this.anchorTarget : null;\n    const floating = shouldTrack ? this.floatingTarget : null;\n    // The elements already say whether anything is tracked, so the key only has\n    // to say which options are on it.\n    const key = JSON.stringify(this.#options);\n    if (\n      key === this.#appliedKey &&\n      anchor === this.#appliedAnchor &&\n      floating === this.#appliedFloating\n    ) {\n      return;\n    }\n    this.#detach();\n    this.#appliedKey = key;\n    this.#appliedAnchor = anchor;\n    this.#appliedFloating = floating;\n    if (anchor && floating) this.#attach(anchor, floating);\n  }\n\n  #attach(anchor: Element, floating: HTMLElement): void {\n    const id = Symbol(\"anchored-attach\");\n    this.#attachId = id;\n    this.#stop = attachPositioning(anchor, floating, this.#options, (result) =>\n      this.#onComputed(id, floating, result),\n    );\n  }\n\n  #detach(): void {\n    this.#stop?.();\n    this.#stop = null;\n    this.#attachId = null;\n  }\n\n  /**\n   * Reflects the resolved side onto the CSS hook and announces the placement.\n   *\n   * The pass carries the attach that started it and the element it positioned,\n   * and lands only while that attach is still the live one: `autoUpdate`'s\n   * cleanup stops further updates but cannot cancel one already computing, so a\n   * pass superseded mid-flight would otherwise write and dispatch afterwards.\n   * The element cannot stand in for that identity — an option change re-attaches\n   * against the very same pair.\n   */\n  #onComputed(id: symbol, floating: HTMLElement, result: PositionResult): void {\n    if (id !== this.#attachId) return;\n    floating.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

@@ -1,6 +1,6 @@
 {
   "name": "stimeo-ui",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Headless Stimulus UI framework for Ruby on Rails — behavior-only, accessible components driven by HTML attributes.",
   "type": "module",
   "license": "MIT",
@@ -86,7 +86,7 @@
   "devDependencies": {
     "@biomejs/biome": "2.5.14",
     "@floating-ui/dom": "1.8.0",
-    "@guidepup/virtual-screen-reader": "0.32.1",
+    "@guidepup/virtual-screen-reader": "0.33.0",
     "@hotwired/stimulus": "3.2.2",
     "@hotwired/turbo": "8.0.23",
     "@rails/actioncable": "8.1.301",