@wow-two-beta/ui-vue 0.0.4 → 0.0.6

package/dist/foundation/device/index.js

@@ -1,7 +1,8 @@
-import { computed, shallowRef, onMounted, toValue } from "vue";
-import { u as useMediaQuery } from "../../chunks/useMediaQuery-DwVcSgGk.js";
-import { u as useEventListener } from "../../chunks/useEventListener-gohT6zGs.js";
-import { i as isApplePlatform } from "../../chunks/Chord-D9Z-j3O0.js";
+import { computed, shallowRef, onMounted, toValue, watch, onScopeDispose } from "vue";
+import { a as useMediaQuery, s as subscribeMediaQuery } from "../../chunks/UseReducedMotion-NZ5fg-Xb.js";
+import { u } from "../../chunks/UseReducedMotion-NZ5fg-Xb.js";
+import { u as useEventListener } from "../../chunks/UseEventListener-C1WgWGoT.js";
+import { i as isApplePlatform } from "../../chunks/Chord-C3OKRsgk.js";
 const PointerType = {
   /** Low-precision primary pointer — a finger on a touchscreen, a TV remote. Size hit targets generously. */
   Coarse: "coarse",
@@ -10,12 +11,12 @@ const PointerType = {
   /** No pointing device at all — keyboard- or voice-driven. Also the SSR answer, where nothing is knowable yet. */
   None: "none"
 };
-const FINE_POINTER_QUERY = "(pointer: fine)";
-const COARSE_POINTER_QUERY = "(pointer: coarse)";
-const HOVER_QUERY = "(hover: hover)";
+const FinePointerQuery = "(pointer: fine)";
+const CoarsePointerQuery = "(pointer: coarse)";
+const HoverQuery = "(hover: hover)";
 function usePointerType() {
-  const fine = useMediaQuery(FINE_POINTER_QUERY);
-  const coarse = useMediaQuery(COARSE_POINTER_QUERY);
+  const fine = useMediaQuery(FinePointerQuery);
+  const coarse = useMediaQuery(CoarsePointerQuery);
   return computed(() => {
     if (fine.value) return PointerType.Fine;
     if (coarse.value) return PointerType.Coarse;
@@ -23,7 +24,7 @@ function usePointerType() {
   });
 }
 function useHoverCapability() {
-  const hover = useMediaQuery(HOVER_QUERY);
+  const hover = useMediaQuery(HoverQuery);
   return computed(() => hover.value);
 }
 const globalTarget = () => typeof window === "undefined" ? null : window;
@@ -66,13 +67,13 @@ const DisplayMode = {
   /** An ordinary browser tab. Also the SSR answer. */
   Browser: "browser"
 };
-const FULLSCREEN_QUERY = "(display-mode: fullscreen)";
-const STANDALONE_QUERY = "(display-mode: standalone)";
-const MINIMAL_UI_QUERY = "(display-mode: minimal-ui)";
+const FullscreenQuery = "(display-mode: fullscreen)";
+const StandaloneQuery = "(display-mode: standalone)";
+const MinimalUiQuery = "(display-mode: minimal-ui)";
 function useDisplayMode() {
-  const fullscreen = useMediaQuery(FULLSCREEN_QUERY);
-  const standalone = useMediaQuery(STANDALONE_QUERY);
-  const minimalUi = useMediaQuery(MINIMAL_UI_QUERY);
+  const fullscreen = useMediaQuery(FullscreenQuery);
+  const standalone = useMediaQuery(StandaloneQuery);
+  const minimalUi = useMediaQuery(MinimalUiQuery);
   return computed(() => {
     if (fullscreen.value) return DisplayMode.Fullscreen;
     if (standalone.value) return DisplayMode.Standalone;
@@ -113,7 +114,7 @@ function getPlatform(hint) {
   if (/linux|x11|cros|chrome ?os/i.test(source)) return Platform.Linux;
   return Platform.Unknown;
 }
-const TAILWIND_BREAKPOINTS = {
+const TailwindBreakpoints = {
   /** ≥ 640px. */
   sm: 640,
   /** ≥ 768px. */
@@ -125,7 +126,6 @@ const TAILWIND_BREAKPOINTS = {
   /** ≥ 1536px. */
   "2xl": 1536
 };
-const MAX_BREAKPOINTS = 8;
 function toBreakpointQueries(scale) {
   return Object.entries(scale).filter(([, minWidth]) => Number.isFinite(minWidth) && minWidth >= 0).sort(([, left], [, right]) => right - left).map(([key, minWidth]) => ({
     // `Object.entries` widens the key to `string`; by construction it is a key of `scale`.
@@ -140,40 +140,44 @@ function resolveBreakpoint(queries, matches) {
   }
   return null;
 }
-const NEVER_MATCHES = "not all";
-function queryAt(queries, index) {
-  return queries.at(index)?.query ?? NEVER_MATCHES;
-}
 function useBreakpoint(scale) {
   const queries = computed(() => toBreakpointQueries(toValue(scale)));
-  const match0 = useMediaQuery(() => queryAt(queries.value, 0));
-  const match1 = useMediaQuery(() => queryAt(queries.value, 1));
-  const match2 = useMediaQuery(() => queryAt(queries.value, 2));
-  const match3 = useMediaQuery(() => queryAt(queries.value, 3));
-  const match4 = useMediaQuery(() => queryAt(queries.value, 4));
-  const match5 = useMediaQuery(() => queryAt(queries.value, 5));
-  const match6 = useMediaQuery(() => queryAt(queries.value, 6));
-  const match7 = useMediaQuery(() => queryAt(queries.value, 7));
-  return computed(() => {
-    const matches = [
-      match0.value,
-      match1.value,
-      match2.value,
-      match3.value,
-      match4.value,
-      match5.value,
-      match6.value,
-      match7.value
-    ];
-    return resolveBreakpoint(queries.value, matches);
+  const active = shallowRef(null);
+  let mounted = false;
+  let dispose;
+  function subscribe() {
+    dispose?.();
+    dispose = void 0;
+    if (!mounted) return;
+    const current = queries.value;
+    const matches = current.map(() => false);
+    active.value = null;
+    const disposers = current.map(
+      (entry, index) => subscribeMediaQuery(entry.query, (value) => {
+        matches[index] = value;
+        active.value = resolveBreakpoint(current, matches);
+      })
+    );
+    dispose = () => {
+      for (const unsubscribe of disposers) unsubscribe();
+    };
+  }
+  onMounted(() => {
+    mounted = true;
+    subscribe();
+  });
+  watch(queries, subscribe);
+  onScopeDispose(() => {
+    mounted = false;
+    dispose?.();
   });
+  return computed(() => active.value);
 }
 export {
   DisplayMode,
-  MAX_BREAKPOINTS,
   Platform,
   PointerType,
-  TAILWIND_BREAKPOINTS,
+  TailwindBreakpoints,
   getPlatform,
   resolveBreakpoint,
   toBreakpointQueries,
@@ -181,7 +185,9 @@ export {
   useDisplayMode,
   useHoverCapability,
   useIsInstalled,
+  useMediaQuery,
   useOnlineStatus,
-  usePointerType
+  usePointerType,
+  u as useReducedMotion
 };
 //# sourceMappingURL=index.js.map

package/dist/foundation/device/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/foundation/device/PointerType.ts","../../../src/foundation/device/UsePointer.ts","../../../src/foundation/device/UseOnlineStatus.ts","../../../src/foundation/device/DisplayMode.ts","../../../src/foundation/device/UseDisplayMode.ts","../../../src/foundation/device/Platform.ts","../../../src/foundation/device/Breakpoints.ts","../../../src/foundation/device/UseBreakpoint.ts"],"sourcesContent":["// The pointer vocabulary, kept in its own file rather than inlined into the composable so a consumer can switch\n// on `PointerType.Coarse` without pulling Vue into a pure module — the same value/composable split `foundation/shortcuts`\n// uses for `Modifier` vs `UseHotkeys`.\n\n/** How precise the primary pointing device is, per the CSS `pointer` media feature. */\nexport const PointerType = {\n  /** Low-precision primary pointer — a finger on a touchscreen, a TV remote. Size hit targets generously. */\n  Coarse: 'coarse',\n  /** High-precision primary pointer — a mouse, trackpad, or stylus. Hover affordances are meaningful here. */\n  Fine: 'fine',\n  /** No pointing device at all — keyboard- or voice-driven. Also the SSR answer, where nothing is knowable yet. */\n  None: 'none',\n} as const;\n\n/** One of the {@link PointerType} values. */\nexport type PointerType = (typeof PointerType)[keyof typeof PointerType];\n","// Pointer precision and hover capability, read from the CSS `pointer` / `hover` media features through the shared\n// `useMediaQuery`.\n//\n// WHY NOT A USER-AGENT SNIFF: \"is this a touch device\" is not a device question, it is an INPUT question, and the\n// two diverge constantly. A Windows laptop with a touchscreen has both a fine mouse and a coarse finger; an iPad\n// with a Magic Keyboard reports a FINE pointer; a phone in desktop-site mode still has only a finger. A UA string\n// describes none of that, is trivially spoofed, and is frozen or deprecated on every Chromium browser. The media\n// features track the pointer the user is ACTUALLY holding and re-evaluate when it changes.\n//\n// WHY NOT `'ontouchstart' in window` AS THE PRIMARY SIGNAL: it proves the touch EVENT API is implemented, not that\n// a touchscreen is attached — every desktop Chromium build ships the API, so the check reads true on a mouse-only\n// machine and the UI grows finger-sized hit targets nobody needs. It is also a one-shot boolean with no change\n// event, so it can never react to a tablet being docked to a keyboard mid-session. `(pointer: coarse)` answers the\n// question that was actually being asked, and answers it reactively.\n\nimport { computed, type ComputedRef } from 'vue';\n\nimport { useMediaQuery } from '../hooks';\n\nimport { PointerType } from './PointerType';\n\n// `pointer` / `hover` describe the PRIMARY pointing device. The `any-pointer` / `any-hover` variants report every\n// attached device instead, which is the wrong question for layout: a touchscreen laptop matches `any-pointer:\n// coarse` while the user drives it entirely by mouse, and sizing every target for the finger they are not using\n// wastes the screen. Primary is what layout should follow.\nconst FINE_POINTER_QUERY = '(pointer: fine)';\nconst COARSE_POINTER_QUERY = '(pointer: coarse)';\nconst HOVER_QUERY = '(hover: hover)';\n\n/**\n * Reports the precision of the primary pointing device — `'fine'` (mouse, trackpad, stylus), `'coarse'` (finger),\n * or `'none'`.\n *\n * Reactive: a tablet gaining a mouse flips `'coarse'` → `'fine'` without a reload.\n *\n * Under SSR this reads `'none'` (there are no media features to read) and corrects on hydration. Treat `'none'`\n * as \"no pointer known\", not as a fact — never hide an essential affordance behind it.\n *\n * @returns The active {@link PointerType}.\n */\nexport function usePointerType(): ComputedRef<PointerType> {\n  const fine = useMediaQuery(FINE_POINTER_QUERY);\n  const coarse = useMediaQuery(COARSE_POINTER_QUERY);\n\n  // `pointer` names one primary device, so at most one of these matches in practice. `fine` is tested first so\n  // that a browser reporting both resolves to the more capable pointer rather than to a coincidence of ordering.\n  return computed(() => {\n    if (fine.value) return PointerType.Fine;\n    if (coarse.value) return PointerType.Coarse;\n    return PointerType.None;\n  });\n}\n\n/**\n * Whether the primary pointing device can hover — the `(hover: hover)` media feature.\n *\n * Gate hover-only affordances on this: a tooltip that opens on mouseover, a table row's hover-revealed actions. On\n * a touchscreen a hover-only control is simply unreachable and needs a tap target or an always-visible equivalent.\n *\n * Reads `false` under SSR, so hover-revealed content must never be the only path to an action.\n *\n * @returns `true` when the primary pointer can hover.\n */\nexport function useHoverCapability(): ComputedRef<boolean> {\n  const hover = useMediaQuery(HOVER_QUERY);\n  return computed(() => hover.value);\n}\n","// Network reachability — or as much of it as the browser is willing to admit to.\n//\n// WHAT `navigator.onLine` ACTUALLY MEANS: it is `false` only when the browser is certain there is NO network link\n// — airplane mode, Wi-Fi off, cable unplugged. It is `true` the moment a link exists and says NOTHING beyond that.\n// A captive portal nobody has logged into, hotel Wi-Fi that has not been paid for, a dropped VPN, a DNS failure,\n// or an API that is simply down all report `true`. So `false` is trustworthy and `true` is a hint.\n//\n// USE ACCORDINGLY: explain a failure that already happened (\"you appear to be offline\"), defer a retry, pause a\n// poll. Never treat `true` as a precondition — \"we are online, so this request will succeed\" is exactly the\n// inference this value cannot support. Proving the server that matters is reachable takes a request to it, which\n// is `foundation/http`'s job and not this slice's.\n//\n// The `online` / `offline` events bind through `foundation/hooks`' `useEventListener` rather than a hand-rolled\n// `addEventListener`, so handler identity, attach options, and teardown follow the same rules as every other\n// listener in the library. The target is a GETTER, not a module constant: resolving `window` at module scope\n// would evaluate during a server render, and the lazy getter is the same shape `useEventListener` uses for its\n// own default.\n\nimport { onMounted, shallowRef, type ShallowRef } from 'vue';\n\nimport { useEventListener } from '../hooks';\n\n/** Resolved lazily so importing this module in an SSR pass never touches `window`. */\nconst globalTarget = (): Window | null => (typeof window === 'undefined' ? null : window);\n\n/**\n * Reads `navigator.onLine`, defaulting to online when there is no `navigator` (SSR), when the property is missing\n * (a partial polyfill), or when the read throws. Optimistic by design — see the note on the composable.\n */\nfunction readOnlineStatus(): boolean {\n  try {\n    if (typeof navigator === 'undefined') return true;\n    return navigator.onLine !== false;\n  } catch {\n    return true;\n  }\n}\n\n/**\n * Tracks whether the browser believes it has a network link — seeded optimistically, synced from\n * `navigator.onLine` on mount, then kept current by the window `online` / `offline` events.\n *\n * Reads `true` under SSR and whenever the status cannot be read: an offline banner rendered by a server that has\n * never met the client is worse than a missing one, and the value corrects on mount either way. Read this file's\n * header before acting on it — `false` is reliable, `true` only means a link exists.\n *\n * @returns `true` while the browser reports a network link.\n */\nexport function useOnlineStatus(): Readonly<ShallowRef<boolean>> {\n  // Seeded `true` rather than read at setup: `readOnlineStatus` answers `true` under SSR anyway, and seeding a\n  // constant keeps `navigator` out of the setup pass entirely.\n  const online = shallowRef(true);\n\n  // Re-read once on mount. Two gaps the events alone can never close: the seed was unconditional, and the link\n  // can flip between setup and the listeners attaching.\n  onMounted(() => {\n    online.value = readOnlineStatus();\n  });\n\n  useEventListener(\n    'online',\n    () => {\n      online.value = true;\n    },\n    globalTarget,\n  );\n  useEventListener(\n    'offline',\n    () => {\n      online.value = false;\n    },\n    globalTarget,\n  );\n\n  return online;\n}\n","// The display-mode vocabulary. Split from its composable for the same reason as `PointerType` — a consumer\n// comparing against `DisplayMode.Standalone` should not have to import Vue to do it.\n\n/** How the document is being presented — the values of the CSS `display-mode` media feature. */\nexport const DisplayMode = {\n  /** Installed and running in its own window with no browser chrome. The usual \"is this a PWA\" answer. */\n  Standalone: 'standalone',\n  /** Filling the screen with no OS chrome either — kiosk displays, the Fullscreen API. */\n  Fullscreen: 'fullscreen',\n  /** Own window with a minimal navigation strip (back / reload). Installed, but not chrome-free. */\n  MinimalUi: 'minimal-ui',\n  /** An ordinary browser tab. Also the SSR answer. */\n  Browser: 'browser',\n} as const;\n\n/** One of the {@link DisplayMode} values. */\nexport type DisplayMode = (typeof DisplayMode)[keyof typeof DisplayMode];\n","// Display mode — how the document is presented, and by extension whether the app was installed.\n//\n// Read entirely through `display-mode` media queries on the shared `useMediaQuery`, which makes the answer\n// reactive: a window entering or leaving fullscreen updates live, where the one-shot check at startup that most\n// codebases write would be stale for the rest of the session.\n//\n// QUERY ORDER IS LOAD-BEARING, and is not alphabetical. Browsers do not reliably report exactly one match — a\n// standalone window driven into fullscreen can satisfy both `(display-mode: fullscreen)` and\n// `(display-mode: standalone)` — so the most specific presentation is tested first and wins.\n//\n// KNOWN GAP — iOS Safari only supports `display-mode` from 16.4. On older iOS an installed home-screen app reports\n// `'browser'` here. Its legacy signal is the non-standard `navigator.standalone`, deliberately NOT read: this\n// slice keeps a single detection mechanism, and adding a second, non-reactive sniffer for one stale OS version\n// buys a narrow tail at the cost of two code paths that can disagree. A consumer that needs that tail can read\n// `navigator.standalone` itself and OR it in.\n\nimport { computed, type ComputedRef } from 'vue';\n\nimport { useMediaQuery } from '../hooks';\n\nimport { DisplayMode } from './DisplayMode';\n\nconst FULLSCREEN_QUERY = '(display-mode: fullscreen)';\nconst STANDALONE_QUERY = '(display-mode: standalone)';\nconst MINIMAL_UI_QUERY = '(display-mode: minimal-ui)';\n\n/**\n * Reports how the document is being presented — its {@link DisplayMode}.\n *\n * Falls back to `'browser'` when no mode query matches, which is also what SSR and any browser without\n * `display-mode` support produce. `'browser'` therefore means \"an ordinary tab, as far as can be told\", not a\n * proof that the app is uninstalled.\n *\n * @returns The active {@link DisplayMode}.\n */\nexport function useDisplayMode(): ComputedRef<DisplayMode> {\n  const fullscreen = useMediaQuery(FULLSCREEN_QUERY);\n  const standalone = useMediaQuery(STANDALONE_QUERY);\n  const minimalUi = useMediaQuery(MINIMAL_UI_QUERY);\n\n  return computed(() => {\n    if (fullscreen.value) return DisplayMode.Fullscreen;\n    if (standalone.value) return DisplayMode.Standalone;\n    if (minimalUi.value) return DisplayMode.MinimalUi;\n    return DisplayMode.Browser;\n  });\n}\n\n/**\n * Whether the app is running as an installed app rather than in a browser tab — any display mode other than\n * `'browser'`.\n *\n * Reads `false` under SSR and on iOS < 16.4 (see this file's header). Use it to ADD an installed-only affordance\n * — suppressing an \"Install app\" prompt, showing a custom title bar — never to withhold functionality, because a\n * `false` here can mean \"installed, but undetectable\".\n *\n * @returns `true` when the app is presented outside an ordinary browser tab.\n */\nexport function useIsInstalled(): ComputedRef<boolean> {\n  const mode = useDisplayMode();\n  return computed(() => mode.value !== DisplayMode.Browser);\n}\n","// Platform identification — the LAST-RESORT signal in this slice, and the only one here that asks what the\n// environment IS rather than what it can DO.\n//\n// USE IT ONLY FOR COSMETICS: rendering `⌘K` vs `Ctrl+K` in a shortcut hint, naming a modifier in help text,\n// labelling a button \"Show in Finder\" vs \"Show in Explorer\". NEVER gate a feature on it. A user agent is freely\n// spoofed, `navigator.platform` is deprecated, Chromium freezes its UA, and every question worth gating on\n// (pointer precision, hover, display mode, viewport) has a real capability query in this slice that answers it\n// truthfully. Platform sniffing gates on a guess; a media feature gates on the fact.\n//\n// The Apple branch delegates to `foundation/shortcuts`' `isApplePlatform` rather than re-sniffing: that predicate\n// already backs `mod` → ⌘ resolution, and two sniffers that drift apart would render a ⌘ hint on a Ctrl machine.\n// This file adds the other three families around it and reuses its exact source-precedence rules.\n//\n// Ordering is load-bearing. Android is tested before Linux because Android's UA names the Linux kernel; the\n// Windows pattern is anchored on real tokens (`Windows` / `Win32` / `Win64` / `WOW64`) rather than a bare `win`,\n// which would misread `Darwin` — a substring collision that silently turns a Mac into a PC.\n\nimport { isApplePlatform } from '../shortcuts';\n\n/** The coarse OS families this slice distinguishes. */\nexport const Platform = {\n  /** macOS, iOS, or iPadOS. */\n  Apple: 'apple',\n  /** Any Windows desktop. */\n  Windows: 'windows',\n  /** Android phones and tablets. */\n  Android: 'android',\n  /** Desktop Linux, X11, and ChromeOS — all Ctrl-keyed, all Linux-idiomatic in their affordances. */\n  Linux: 'linux',\n  /** Nothing recognisable — SSR, a stripped user agent, or a platform outside the four above. */\n  Unknown: 'unknown',\n} as const;\n\n/** One of the {@link Platform} families. */\nexport type Platform = (typeof Platform)[keyof typeof Platform];\n\n/**\n * Reads the best available platform string, preferring the modern `userAgentData.platform` over the deprecated\n * `navigator.platform` and falling back to the full user agent. Mirrors `isApplePlatform`'s precedence exactly so\n * both predicates always judge the same text. Returns `''` under SSR or if any read throws.\n */\nfunction readPlatformSource(): string {\n  try {\n    if (typeof navigator === 'undefined') return '';\n    const nav = navigator as Navigator & { userAgentData?: { platform?: string } };\n    return nav.userAgentData?.platform || nav.platform || nav.userAgent || '';\n  } catch {\n    // A throwing `navigator` getter (polyfill, hardened environment) reads as \"no information\", never as a crash.\n    return '';\n  }\n}\n\n/**\n * Identifies the OS family. Read this file's header before using it: the answer is for cosmetic, platform-idiomatic\n * decisions only, never for feature gating.\n *\n * Never throws. Returns `'unknown'` under SSR, for an unrecognised platform, and for an empty hint.\n *\n * @param hint Forces the string that is matched, instead of reading the environment — makes tests deterministic and\n * lets a server render for a client whose platform it already knows. Accepts a full user agent, a\n * `userAgentData.platform` value, or a bare token such as `'Windows'`.\n * @returns The detected {@link Platform}.\n */\nexport function getPlatform(hint?: string): Platform {\n  const source = hint ?? readPlatformSource();\n\n  if (isApplePlatform(source)) return Platform.Apple;\n  if (/android/i.test(source)) return Platform.Android;\n  if (/windows|win32|win64|wow64/i.test(source)) return Platform.Windows;\n  if (/linux|x11|cros|chrome ?os/i.test(source)) return Platform.Linux;\n  return Platform.Unknown;\n}\n","// The breakpoint model — pure, DOM-free, and deliberately WITHOUT a built-in scale.\n//\n// WHY NO DEFAULT SCALE: this library is Tailwind-v4 token-driven, so the app owns its breakpoints in its `@theme`\n// block. A scale hardcoded here would be a second source of truth that silently disagrees with the CSS the same\n// app ships — a layout that switches at 768px in JS and 720px in CSS is a bug no test in this repo could see.\n// `TAILWIND_BREAKPOINTS` is offered as a constant the caller may opt into, never as a fallback a composable reaches for.\n//\n// Queries are plain `(min-width: …)` sorted WIDEST FIRST, so \"the first query that matches\" is the active\n// breakpoint. Mutually-exclusive bands (`min` and `max` together) are the alternative and were rejected: bands\n// need a sentinel max for the widest entry and a sub-pixel gap between neighbours (`max-width: 767.98px`), and\n// both are places for an off-by-one to hide. Independent min-width queries have neither, and match how the\n// mobile-first CSS beside them already cascades.\n\n/** A breakpoint scale — each key (`sm`, `md`, …) mapped to its minimum viewport width in CSS pixels. */\nexport type BreakpointScale = Readonly<Record<string, number>>;\n\n/**\n * Tailwind v4's default breakpoint scale, in CSS pixels. Opt-in: pass it to `useBreakpoint` explicitly. An app\n * that customised its `@theme` breakpoints must pass its own map instead, or JS and CSS will disagree.\n */\nexport const TAILWIND_BREAKPOINTS = {\n  /** ≥ 640px. */\n  sm: 640,\n  /** ≥ 768px. */\n  md: 768,\n  /** ≥ 1024px. */\n  lg: 1024,\n  /** ≥ 1280px. */\n  xl: 1280,\n  /** ≥ 1536px. */\n  '2xl': 1536,\n} as const;\n\n/**\n * How many breakpoints a scale may contain. `useBreakpoint` fans out to exactly this many `useMediaQuery` calls;\n * eight covers every mainstream scale with room to spare (Tailwind ships 5, Bootstrap 6). See `UseBreakpoint.ts`\n * for why the count has to be a compile-time constant at all.\n */\nexport const MAX_BREAKPOINTS = 8;\n\n/** One breakpoint compiled to the media query that detects it. */\nexport interface BreakpointQuery<TKey extends string = string> {\n  /** The scale key this query stands for. */\n  readonly key: TKey;\n  /** The minimum viewport width, in CSS pixels. */\n  readonly minWidth: number;\n  /** The `(min-width: …px)` string to hand to `matchMedia`. */\n  readonly query: string;\n}\n\n/**\n * Compiles a scale into widest-first `(min-width: …)` queries.\n *\n * Entries whose width is not a finite number `>= 0` are dropped: a malformed scale must not emit\n * `(min-width: NaNpx)`, which `matchMedia` accepts and then never matches, quietly skewing the resolved\n * breakpoint instead of failing.\n *\n * @param scale The caller's breakpoint map.\n * @returns The scale's valid entries as queries, widest first.\n */\nexport function toBreakpointQueries<TScale extends BreakpointScale>(\n  scale: TScale,\n): readonly BreakpointQuery<Extract<keyof TScale, string>>[] {\n  return Object.entries(scale)\n    .filter(([, minWidth]) => Number.isFinite(minWidth) && minWidth >= 0)\n    .sort(([, left], [, right]) => right - left)\n    .map(([key, minWidth]) => ({\n      // `Object.entries` widens the key to `string`; by construction it is a key of `scale`.\n      key: key as Extract<keyof TScale, string>,\n      minWidth,\n      query: `(min-width: ${minWidth}px)`,\n    }));\n}\n\n/**\n * Picks the active breakpoint from a widest-first query list and the match results for it.\n *\n * @param queries Compiled queries, widest first, as returned by {@link toBreakpointQueries}.\n * @param matches Match results positionally aligned with `queries`. A shorter array reads as \"did not match\" for\n * the missing tail, which is how a scale larger than {@link MAX_BREAKPOINTS} loses its narrowest entries.\n * @returns The key of the widest matching breakpoint, or `null` when the viewport is narrower than every entry —\n * the implicit mobile-first base band, which by definition has no key of its own.\n */\nexport function resolveBreakpoint<TKey extends string>(\n  queries: readonly BreakpointQuery<TKey>[],\n  matches: readonly boolean[],\n): TKey | null {\n  for (const [index, entry] of queries.entries()) {\n    if (matches[index] === true) return entry.key;\n  }\n  return null;\n}\n","// The active breakpoint, resolved from a caller-supplied scale.\n//\n// WHY THE FIXED-SLOT FAN-OUT BELOW — the one non-obvious thing in this slice:\n//\n// Every media query in this library must go through `foundation/hooks`' `useMediaQuery`, so there is exactly one\n// `matchMedia` implementation, one subscription model, and one SSR semantic. But the scale belongs to the caller,\n// so the NUMBER of queries is not known at compile time.\n//\n// Vue has no rules-of-hooks call-order constraint, so the React original's reason for a fixed arity is gone — but\n// the fixed arity stays, for a Vue-specific reason that is just as real: a composable's cleanup is registered on\n// the surrounding effect scope, so subscriptions created in a loop are only released when the WHOLE scope dies. A\n// scale that shrank mid-session would leak a live `MediaQueryList` per dropped entry. A FIXED number of\n// `useMediaQuery` calls — `MAX_BREAKPOINTS` of them, always — has no such leak, and the slots a smaller scale\n// leaves over are parked on `'not all'`, a valid media query that can never match.\n//\n// What Vue does buy is that each slot takes a GETTER rather than a fixed string, so a changed scale re-points the\n// existing subscriptions instead of needing a remount. The React version could not do that at all.\n//\n// The slot count below MUST equal `MAX_BREAKPOINTS`. Queries arrive widest-first, so a scale with more entries\n// than slots loses its NARROWEST ones — the widest, which decide the answer on large viewports, always get slots.\n\nimport { computed, toValue, type ComputedRef, type MaybeRefOrGetter } from 'vue';\n\nimport { useMediaQuery } from '../hooks';\n\nimport {\n  resolveBreakpoint,\n  toBreakpointQueries,\n  type BreakpointQuery,\n  type BreakpointScale,\n} from './Breakpoints';\n\n/** A valid media query that never matches — parks the slots a scale smaller than `MAX_BREAKPOINTS` leaves unused. */\nconst NEVER_MATCHES = 'not all';\n\n/** Reads slot `index`'s query string, falling back to the never-matching parking query. */\nfunction queryAt(queries: readonly BreakpointQuery[], index: number): string {\n  return queries.at(index)?.query ?? NEVER_MATCHES;\n}\n\n/**\n * Resolves the active breakpoint from a caller-supplied scale: the key of the widest breakpoint the viewport\n * currently satisfies.\n *\n * No scale is built in — this library is Tailwind-v4 token-driven and the app owns its `@theme` breakpoints. Pass\n * `TAILWIND_BREAKPOINTS` to opt into Tailwind's defaults, or your own map to match your tokens.\n *\n * The scale may be a ref or getter; changing it re-points the existing subscriptions.\n *\n * Reads `null` under SSR, where no media query matches. Layout that must be right before JS runs belongs in CSS;\n * this composable is for behaviour a media query alone cannot express — which list virtualiser to mount, how many\n * items to prefetch.\n *\n * @param scale Breakpoint key to minimum viewport width in CSS pixels. Entries beyond `MAX_BREAKPOINTS`, counted\n * widest-first, are ignored; invalid widths are dropped.\n * @returns The active breakpoint key, or `null` when the viewport is narrower than every entry in the scale.\n */\nexport function useBreakpoint<TScale extends BreakpointScale>(\n  scale: MaybeRefOrGetter<TScale>,\n): ComputedRef<Extract<keyof TScale, string> | null> {\n  const queries = computed(() => toBreakpointQueries(toValue(scale)));\n\n  // Fixed-arity fan-out — see this file's header. Do NOT collapse into a loop or a `.map`: the constant call\n  // count is what keeps a caller-supplied scale from leaking subscriptions as it shrinks.\n  const match0 = useMediaQuery(() => queryAt(queries.value, 0));\n  const match1 = useMediaQuery(() => queryAt(queries.value, 1));\n  const match2 = useMediaQuery(() => queryAt(queries.value, 2));\n  const match3 = useMediaQuery(() => queryAt(queries.value, 3));\n  const match4 = useMediaQuery(() => queryAt(queries.value, 4));\n  const match5 = useMediaQuery(() => queryAt(queries.value, 5));\n  const match6 = useMediaQuery(() => queryAt(queries.value, 6));\n  const match7 = useMediaQuery(() => queryAt(queries.value, 7));\n\n  return computed(() => {\n    // Exactly `MAX_BREAKPOINTS` entries — the invariant the header states. Positionally aligned with `queries`.\n    const matches: readonly boolean[] = [\n      match0.value,\n      match1.value,\n      match2.value,\n      match3.value,\n      match4.value,\n      match5.value,\n      match6.value,\n      match7.value,\n    ];\n\n    return resolveBreakpoint(queries.value, matches) as Extract<keyof TScale, string> | null;\n  });\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sources":["../../../src/foundation/device/enums/PointerType.ts","../../../src/foundation/device/hooks/UsePointer.ts","../../../src/foundation/device/hooks/UseOnlineStatus.ts","../../../src/foundation/device/enums/DisplayMode.ts","../../../src/foundation/device/hooks/UseDisplayMode.ts","../../../src/foundation/device/Platform.ts","../../../src/foundation/device/Breakpoints.ts","../../../src/foundation/device/hooks/UseBreakpoint.ts"],"sourcesContent":["// The pointer vocabulary, kept in its own file rather than inlined into the composable so a consumer can switch\n// on `PointerType.Coarse` without pulling Vue into a pure module — the same value/composable split\n// `foundation/shortcuts` uses for `Modifier` vs `UseHotkeys`.\n\n/** How precise the primary pointing device is, per the CSS `pointer` media feature. */\nexport const PointerType = {\n  /** Low-precision primary pointer — a finger on a touchscreen, a TV remote. Size hit targets generously. */\n  Coarse: 'coarse',\n  /** High-precision primary pointer — a mouse, trackpad, or stylus. Hover affordances are meaningful here. */\n  Fine: 'fine',\n  /** No pointing device at all — keyboard- or voice-driven. Also the SSR answer, where nothing is knowable yet. */\n  None: 'none',\n} as const;\n\n/** One of the {@link PointerType} values. */\nexport type PointerType = (typeof PointerType)[keyof typeof PointerType];\n","// Pointer precision and hover capability, read from the CSS `pointer` / `hover` media features through the shared\n// `useMediaQuery`.\n//\n// WHY NOT A USER-AGENT SNIFF: \"is this a touch device\" is not a device question, it is an INPUT question, and the\n// two diverge constantly. A Windows laptop with a touchscreen has both a fine mouse and a coarse finger; an iPad\n// with a Magic Keyboard reports a FINE pointer; a phone in desktop-site mode still has only a finger. A UA string\n// describes none of that, is trivially spoofed, and is frozen or deprecated on every Chromium browser. The media\n// features track the pointer the user is ACTUALLY holding and re-evaluate when it changes.\n//\n// WHY NOT `'ontouchstart' in window` AS THE PRIMARY SIGNAL: it proves the touch EVENT API is implemented, not that\n// a touchscreen is attached — every desktop Chromium build ships the API, so the check reads true on a mouse-only\n// machine and the UI grows finger-sized hit targets nobody needs. It is also a one-shot boolean with no change\n// event, so it can never react to a tablet being docked to a keyboard mid-session. `(pointer: coarse)` answers the\n// question that was actually being asked, and answers it reactively.\n\nimport { computed, type ComputedRef } from 'vue';\n\nimport { useMediaQuery } from './UseMediaQuery';\n\nimport { PointerType } from '../enums/PointerType';\n\n// `pointer` / `hover` describe the PRIMARY pointing device. The `any-pointer` / `any-hover` variants report every\n// attached device instead, which is the wrong question for layout: a touchscreen laptop matches `any-pointer:\n// coarse` while the user drives it entirely by mouse, and sizing every target for the finger they are not using\n// wastes the screen. Primary is what layout should follow.\nconst FinePointerQuery = '(pointer: fine)';\nconst CoarsePointerQuery = '(pointer: coarse)';\nconst HoverQuery = '(hover: hover)';\n\n/**\n * Reports the precision of the primary pointing device — `'fine'` (mouse, trackpad, stylus), `'coarse'` (finger),\n * or `'none'`.\n *\n * Reactive: a tablet gaining a mouse flips `'coarse'` → `'fine'` without a reload.\n *\n * Under SSR this reads `'none'` (there are no media features to read) and corrects on hydration. Treat `'none'`\n * as \"no pointer known\", not as a fact — never hide an essential affordance behind it.\n *\n * @returns The active {@link PointerType}.\n */\nexport function usePointerType(): ComputedRef<PointerType> {\n  const fine = useMediaQuery(FinePointerQuery);\n  const coarse = useMediaQuery(CoarsePointerQuery);\n\n  // `pointer` names one primary device, so at most one of these matches in practice. `fine` is tested first so\n  // that a browser reporting both resolves to the more capable pointer rather than to a coincidence of ordering.\n  return computed(() => {\n    if (fine.value) return PointerType.Fine;\n    if (coarse.value) return PointerType.Coarse;\n    return PointerType.None;\n  });\n}\n\n/**\n * Whether the primary pointing device can hover — the `(hover: hover)` media feature.\n *\n * Gate hover-only affordances on this: a tooltip that opens on mouseover, a table row's hover-revealed actions. On\n * a touchscreen a hover-only control is simply unreachable and needs a tap target or an always-visible equivalent.\n *\n * Reads `false` under SSR, so hover-revealed content must never be the only path to an action.\n *\n * @returns `true` when the primary pointer can hover.\n */\nexport function useHoverCapability(): ComputedRef<boolean> {\n  const hover = useMediaQuery(HoverQuery);\n  return computed(() => hover.value);\n}\n","// Network reachability — or as much of it as the browser is willing to admit to.\n//\n// WHAT `navigator.onLine` ACTUALLY MEANS: it is `false` only when the browser is certain there is NO network link\n// — airplane mode, Wi-Fi off, cable unplugged. It is `true` the moment a link exists and says NOTHING beyond that.\n// A captive portal nobody has logged into, hotel Wi-Fi that has not been paid for, a dropped VPN, a DNS failure,\n// or an API that is simply down all report `true`. So `false` is trustworthy and `true` is a hint.\n//\n// USE ACCORDINGLY: explain a failure that already happened (\"you appear to be offline\"), defer a retry, pause a\n// poll. Never treat `true` as a precondition — \"we are online, so this request will succeed\" is exactly the\n// inference this value cannot support. Proving the server that matters is reachable takes a request to it, which\n// is `foundation/http`'s job and not this slice's.\n//\n// The `online` / `offline` events bind through `foundation/dom`' `useEventListener` rather than a hand-rolled\n// `addEventListener`, so handler identity, attach options, and teardown follow the same rules as every other\n// listener in the library. The target is a GETTER, not a module constant: resolving `window` at module scope\n// would evaluate during a server render, and the lazy getter is the same shape `useEventListener` uses for its\n// own default.\n\nimport { onMounted, shallowRef, type ShallowRef } from 'vue';\n\nimport { useEventListener } from '../../dom';\n\n/** Resolved lazily so importing this module in an SSR pass never touches `window`. */\nconst globalTarget = (): Window | null => (typeof window === 'undefined' ? null : window);\n\n/**\n * Reads `navigator.onLine`, defaulting to online when there is no `navigator` (SSR), when the property is missing\n * (a partial polyfill), or when the read throws. Optimistic by design — see the note on the composable.\n */\nfunction readOnlineStatus(): boolean {\n  try {\n    if (typeof navigator === 'undefined') return true;\n    return navigator.onLine !== false;\n  } catch {\n    return true;\n  }\n}\n\n/**\n * Tracks whether the browser believes it has a network link — seeded optimistically, synced from\n * `navigator.onLine` on mount, then kept current by the window `online` / `offline` events.\n *\n * Reads `true` under SSR and whenever the status cannot be read: an offline banner rendered by a server that has\n * never met the client is worse than a missing one, and the value corrects on mount either way. Read this file's\n * header before acting on it — `false` is reliable, `true` only means a link exists.\n *\n * @returns `true` while the browser reports a network link.\n */\nexport function useOnlineStatus(): Readonly<ShallowRef<boolean>> {\n  // Seeded `true` rather than read at setup: `readOnlineStatus` answers `true` under SSR anyway, and seeding a\n  // constant keeps `navigator` out of the setup pass entirely.\n  const online = shallowRef(true);\n\n  // Re-read once on mount. Two gaps the events alone can never close: the seed was unconditional, and the link\n  // can flip between setup and the listeners attaching.\n  onMounted(() => {\n    online.value = readOnlineStatus();\n  });\n\n  useEventListener(\n    'online',\n    () => {\n      online.value = true;\n    },\n    globalTarget,\n  );\n  useEventListener(\n    'offline',\n    () => {\n      online.value = false;\n    },\n    globalTarget,\n  );\n\n  return online;\n}\n","// The display-mode vocabulary. Split from its composable for the same reason as `PointerType` — a consumer\n// comparing against `DisplayMode.Standalone` should not have to import Vue to do it.\n\n/** How the document is being presented — the values of the CSS `display-mode` media feature. */\nexport const DisplayMode = {\n  /** Installed and running in its own window with no browser chrome. The usual \"is this a PWA\" answer. */\n  Standalone: 'standalone',\n  /** Filling the screen with no OS chrome either — kiosk displays, the Fullscreen API. */\n  Fullscreen: 'fullscreen',\n  /** Own window with a minimal navigation strip (back / reload). Installed, but not chrome-free. */\n  MinimalUi: 'minimal-ui',\n  /** An ordinary browser tab. Also the SSR answer. */\n  Browser: 'browser',\n} as const;\n\n/** One of the {@link DisplayMode} values. */\nexport type DisplayMode = (typeof DisplayMode)[keyof typeof DisplayMode];\n","// Display mode — how the document is presented, and by extension whether the app was installed.\n//\n// Read entirely through `display-mode` media queries on the shared `useMediaQuery`, which makes the answer\n// reactive: a window entering or leaving fullscreen updates live, where the one-shot check at startup that most\n// codebases write would be stale for the rest of the session.\n//\n// QUERY ORDER IS LOAD-BEARING, and is not alphabetical. Browsers do not reliably report exactly one match — a\n// standalone window driven into fullscreen can satisfy both `(display-mode: fullscreen)` and\n// `(display-mode: standalone)` — so the most specific presentation is tested first and wins.\n//\n// KNOWN GAP — iOS Safari only supports `display-mode` from 16.4. On older iOS an installed home-screen app reports\n// `'browser'` here. Its legacy signal is the non-standard `navigator.standalone`, deliberately NOT read: this\n// slice keeps a single detection mechanism, and adding a second, non-reactive sniffer for one stale OS version\n// buys a narrow tail at the cost of two code paths that can disagree. A consumer that needs that tail can read\n// `navigator.standalone` itself and OR it in.\n\nimport { computed, type ComputedRef } from 'vue';\n\nimport { useMediaQuery } from './UseMediaQuery';\n\nimport { DisplayMode } from '../enums/DisplayMode';\n\nconst FullscreenQuery = '(display-mode: fullscreen)';\nconst StandaloneQuery = '(display-mode: standalone)';\nconst MinimalUiQuery = '(display-mode: minimal-ui)';\n\n/**\n * Reports how the document is being presented — its {@link DisplayMode}.\n *\n * Falls back to `'browser'` when no mode query matches, which is also what SSR and any browser without\n * `display-mode` support produce. `'browser'` therefore means \"an ordinary tab, as far as can be told\", not a\n * proof that the app is uninstalled.\n *\n * @returns The active {@link DisplayMode}.\n */\nexport function useDisplayMode(): ComputedRef<DisplayMode> {\n  const fullscreen = useMediaQuery(FullscreenQuery);\n  const standalone = useMediaQuery(StandaloneQuery);\n  const minimalUi = useMediaQuery(MinimalUiQuery);\n\n  return computed(() => {\n    if (fullscreen.value) return DisplayMode.Fullscreen;\n    if (standalone.value) return DisplayMode.Standalone;\n    if (minimalUi.value) return DisplayMode.MinimalUi;\n    return DisplayMode.Browser;\n  });\n}\n\n/**\n * Whether the app is running as an installed app rather than in a browser tab — any display mode other than\n * `'browser'`.\n *\n * Reads `false` under SSR and on iOS < 16.4 (see this file's header). Use it to ADD an installed-only affordance\n * — suppressing an \"Install app\" prompt, showing a custom title bar — never to withhold functionality, because a\n * `false` here can mean \"installed, but undetectable\".\n *\n * @returns `true` when the app is presented outside an ordinary browser tab.\n */\nexport function useIsInstalled(): ComputedRef<boolean> {\n  const mode = useDisplayMode();\n  return computed(() => mode.value !== DisplayMode.Browser);\n}\n","// Platform identification — the LAST-RESORT signal in this slice, and the only one here that asks what the\n// environment IS rather than what it can DO.\n//\n// USE IT ONLY FOR COSMETICS: rendering `⌘K` vs `Ctrl+K` in a shortcut hint, naming a modifier in help text,\n// labelling a button \"Show in Finder\" vs \"Show in Explorer\". NEVER gate a feature on it. A user agent is freely\n// spoofed, `navigator.platform` is deprecated, Chromium freezes its UA, and every question worth gating on\n// (pointer precision, hover, display mode, viewport) has a real capability query in this slice that answers it\n// truthfully. Platform sniffing gates on a guess; a media feature gates on the fact.\n//\n// The Apple branch delegates to `foundation/shortcuts`' `isApplePlatform` rather than re-sniffing: that predicate\n// already backs `mod` → ⌘ resolution, and two sniffers that drift apart would render a ⌘ hint on a Ctrl machine.\n// This file adds the other three families around it and reuses its exact source-precedence rules.\n//\n// Ordering is load-bearing. Android is tested before Linux because Android's UA names the Linux kernel; the\n// Windows pattern is anchored on real tokens (`Windows` / `Win32` / `Win64` / `WOW64`) rather than a bare `win`,\n// which would misread `Darwin` — a substring collision that silently turns a Mac into a PC.\n\nimport { isApplePlatform } from '../shortcuts';\n\n/** The coarse OS families this slice distinguishes. */\nexport const Platform = {\n  /** macOS, iOS, or iPadOS. */\n  Apple: 'apple',\n  /** Any Windows desktop. */\n  Windows: 'windows',\n  /** Android phones and tablets. */\n  Android: 'android',\n  /** Desktop Linux, X11, and ChromeOS — all Ctrl-keyed, all Linux-idiomatic in their affordances. */\n  Linux: 'linux',\n  /** Nothing recognisable — SSR, a stripped user agent, or a platform outside the four above. */\n  Unknown: 'unknown',\n} as const;\n\n/** One of the {@link Platform} families. */\nexport type Platform = (typeof Platform)[keyof typeof Platform];\n\n/**\n * Reads the best available platform string, preferring the modern `userAgentData.platform` over the deprecated\n * `navigator.platform` and falling back to the full user agent. Mirrors `isApplePlatform`'s precedence exactly so\n * both predicates always judge the same text. Returns `''` under SSR or if any read throws.\n */\nfunction readPlatformSource(): string {\n  try {\n    if (typeof navigator === 'undefined') return '';\n    const nav = navigator as Navigator & { userAgentData?: { platform?: string } };\n    return nav.userAgentData?.platform || nav.platform || nav.userAgent || '';\n  } catch {\n    // A throwing `navigator` getter (polyfill, hardened environment) reads as \"no information\", never as a crash.\n    return '';\n  }\n}\n\n/**\n * Identifies the OS family. Read this file's header before using it: the answer is for cosmetic, platform-idiomatic\n * decisions only, never for feature gating.\n *\n * Never throws. Returns `'unknown'` under SSR, for an unrecognised platform, and for an empty hint.\n *\n * @param hint Forces the string that is matched, instead of reading the environment — makes tests deterministic and\n * lets a server render for a client whose platform it already knows. Accepts a full user agent, a\n * `userAgentData.platform` value, or a bare token such as `'Windows'`.\n * @returns The detected {@link Platform}.\n */\nexport function getPlatform(hint?: string): Platform {\n  const source = hint ?? readPlatformSource();\n\n  if (isApplePlatform(source)) return Platform.Apple;\n  if (/android/i.test(source)) return Platform.Android;\n  if (/windows|win32|win64|wow64/i.test(source)) return Platform.Windows;\n  if (/linux|x11|cros|chrome ?os/i.test(source)) return Platform.Linux;\n  return Platform.Unknown;\n}\n","// The breakpoint model — pure, DOM-free, and deliberately WITHOUT a built-in scale.\n//\n// WHY NO DEFAULT SCALE: this library is Tailwind-v4 token-driven, so the app owns its breakpoints in its `@theme`\n// block. A scale hardcoded here would be a second source of truth that silently disagrees with the CSS the same\n// app ships — a layout that switches at 768px in JS and 720px in CSS is a bug no test in this repo could see.\n// `TailwindBreakpoints` is offered as a constant the caller may opt into, never a fallback a composable reaches for.\n//\n// Queries are plain `(min-width: …)` sorted WIDEST FIRST, so \"the first query that matches\" is the active\n// breakpoint. Mutually-exclusive bands (`min` and `max` together) are the alternative and were rejected: bands\n// need a sentinel max for the widest entry and a sub-pixel gap between neighbours (`max-width: 767.98px`), and\n// both are places for an off-by-one to hide. Independent min-width queries have neither, and match how the\n// mobile-first CSS beside them already cascades.\n\n/** A breakpoint scale — each key (`sm`, `md`, …) mapped to its minimum viewport width in CSS pixels. */\nexport type BreakpointScale = Readonly<Record<string, number>>;\n\n/**\n * Tailwind v4's default breakpoint scale, in CSS pixels. Opt-in: pass it to `useBreakpoint` explicitly. An app\n * that customised its `@theme` breakpoints must pass its own map instead, or JS and CSS will disagree.\n */\nexport const TailwindBreakpoints = {\n  /** ≥ 640px. */\n  sm: 640,\n  /** ≥ 768px. */\n  md: 768,\n  /** ≥ 1024px. */\n  lg: 1024,\n  /** ≥ 1280px. */\n  xl: 1280,\n  /** ≥ 1536px. */\n  '2xl': 1536,\n} as const;\n\n/** One breakpoint compiled to the media query that detects it. */\nexport interface BreakpointQuery<TKey extends string = string> {\n  /** The scale key this query stands for. */\n  readonly key: TKey;\n  /** The minimum viewport width, in CSS pixels. */\n  readonly minWidth: number;\n  /** The `(min-width: …px)` string to hand to `matchMedia`. */\n  readonly query: string;\n}\n\n/**\n * Compiles a scale into widest-first `(min-width: …)` queries.\n *\n * Entries whose width is not a finite number `>= 0` are dropped: a malformed scale must not emit\n * `(min-width: NaNpx)`, which `matchMedia` accepts and then never matches, quietly skewing the resolved\n * breakpoint instead of failing.\n *\n * @param scale The caller's breakpoint map.\n * @returns The scale's valid entries as queries, widest first.\n */\nexport function toBreakpointQueries<TScale extends BreakpointScale>(\n  scale: TScale,\n): ReadonlyArray<BreakpointQuery<Extract<keyof TScale, string>>> {\n  return Object.entries(scale)\n    .filter(([, minWidth]) => Number.isFinite(minWidth) && minWidth >= 0)\n    .sort(([, left], [, right]) => right - left)\n    .map(([key, minWidth]) => ({\n      // `Object.entries` widens the key to `string`; by construction it is a key of `scale`.\n      key: key as Extract<keyof TScale, string>,\n      minWidth,\n      query: `(min-width: ${minWidth}px)`,\n    }));\n}\n\n/**\n * Picks the active breakpoint from a widest-first query list and the match results for it.\n *\n * @param queries Compiled queries, widest first, as returned by {@link toBreakpointQueries}.\n * @param matches Match results positionally aligned with `queries`. A shorter array reads as \"did not match\" for\n * the missing tail.\n * @returns The key of the widest matching breakpoint, or `null` when the viewport is narrower than every entry —\n * the implicit mobile-first base band, which by definition has no key of its own.\n */\nexport function resolveBreakpoint<TKey extends string>(\n  queries: ReadonlyArray<BreakpointQuery<TKey>>,\n  matches: ReadonlyArray<boolean>,\n): TKey | null {\n  for (const [index, entry] of queries.entries()) {\n    if (matches[index] === true) return entry.key;\n  }\n  return null;\n}\n","import {\n  computed,\n  onMounted,\n  onScopeDispose,\n  shallowRef,\n  toValue,\n  watch,\n  type ComputedRef,\n  type MaybeRefOrGetter,\n} from 'vue';\nimport { subscribeMediaQuery } from './UseMediaQuery';\nimport { resolveBreakpoint, toBreakpointQueries, type BreakpointScale } from '../Breakpoints';\n\n/** Tracks every valid breakpoint in the caller's scale and releases replaced subscriptions. */\nexport function useBreakpoint<TScale extends BreakpointScale>(\n  scale: MaybeRefOrGetter<TScale>,\n): ComputedRef<Extract<keyof TScale, string> | null> {\n  const queries = computed(() => toBreakpointQueries(toValue(scale)));\n  const active = shallowRef<Extract<keyof TScale, string> | null>(null);\n  let mounted = false;\n  let dispose: (() => void) | undefined;\n  function subscribe(): void {\n    dispose?.();\n    dispose = undefined;\n    if (!mounted) return;\n    const current = queries.value;\n    const matches: boolean[] = current.map(() => false);\n    active.value = null;\n    const disposers = current.map((entry, index) =>\n      subscribeMediaQuery(entry.query, (value) => {\n        matches[index] = value;\n        active.value = resolveBreakpoint(current, matches);\n      }),\n    );\n    dispose = () => {\n      for (const unsubscribe of disposers) unsubscribe();\n    };\n  }\n  onMounted(() => {\n    mounted = true;\n    subscribe();\n  });\n  watch(queries, subscribe);\n  onScopeDispose(() => {\n    mounted = false;\n    dispose?.();\n  });\n  return computed(() => active.value);\n}\n"],"names":[],"mappings":"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"}

package/dist/foundation/dom/DomOrderExtensions.d.ts

@@ -0,0 +1,4 @@
+/** Orders registered controls by their current DOM positions without mutating their registry. */
+export declare const DomOrderExtensions: {
+    readonly inDocumentOrder: <T>(items: ReadonlyArray<T>, getNode: (item: T) => Node | null | undefined) => Array<T>;
+};

package/dist/foundation/dom/Polymorphic.d.ts

@@ -0,0 +1,29 @@
+import { Component, ComponentPublicInstance, IntrinsicElementAttributes } from 'vue';
+/**
+ * The value set accepted by an `as` prop — an intrinsic tag name or any Vue
+ * component. Rendered through `<component :is="as">`.
+ */
+export type ElementType = keyof IntrinsicElementAttributes | Component;
+/** Resolves the attribute bag for `C` — intrinsic tags map to their DOM attributes, components to an open bag. */
+type AttributesOf<C extends ElementType> = C extends keyof IntrinsicElementAttributes ? IntrinsicElementAttributes[C] : Record<string, unknown>;
+/**
+ * Props for a polymorphic component (`as` prop). Use only when a component
+ * meaningfully changes its DOM element — most components should use `Slot`/`asChild`
+ * instead.
+ */
+export type PolymorphicProps<C extends ElementType, P = object> = P & Omit<AttributesOf<C>, keyof P | 'as'> & {
+    as?: C;
+};
+/**
+ * Vue props never carry a `ref` — template refs are bound by the parent, not
+ * passed down. Kept as an alias of `PolymorphicProps` so consumers porting
+ * from the React package keep compiling.
+ */
+export type PolymorphicPropsWithoutRef<C extends ElementType, P = object> = PolymorphicProps<C, P>;
+/**
+ * The value a template ref receives when bound to a polymorphic element —
+ * a DOM element for intrinsic tags, a component instance otherwise. Pair with
+ * `useTemplateRef<PolymorphicRef<C>>(...)`.
+ */
+export type PolymorphicRef<C extends ElementType> = C extends keyof IntrinsicElementAttributes ? Element : ComponentPublicInstance;
+export {};

package/dist/foundation/dom/UrlExtensions.d.ts

@@ -0,0 +1,5 @@
+/** Selects a URL only when its parsed scheme is allowed at the corresponding DOM boundary. */
+export declare const UrlExtensions: {
+    readonly safeNavigation: (value: unknown) => string | undefined;
+    readonly safeResource: (value: unknown) => string | undefined;
+};

package/dist/foundation/dom/enums/AriaAttribute.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Defines an ARIA attribute name.
+ *
+ * Values are the DOM spelling, kebab-case, because that is what `getAttribute` / `setAttribute` and a
+ * `$attrs` key literally are — the house camelCase value rule does not apply to a wire format. The
+ * constant exists so the spelling is written once: a typo'd `'aria-lable'` is silently inert in the
+ * accessibility tree, and no test that renders the component will fail on it.
+ */
+export declare const AriaAttribute: {
+    /** Refers to the accessible name carried on the element itself. */
+    readonly Label: "aria-label";
+    /** Refers to the id list of elements naming this one. */
+    readonly LabelledBy: "aria-labelledby";
+    /** Refers to the id list of elements describing this one. */
+    readonly DescribedBy: "aria-describedby";
+    /** Refers to the flag hiding an element from the accessibility tree. */
+    readonly Hidden: "aria-hidden";
+    /** Refers to the disabled state announced without removing focusability. */
+    readonly Disabled: "aria-disabled";
+    /** Refers to the selected state of an option or tab. */
+    readonly Selected: "aria-selected";
+    /** Refers to the expanded state of a disclosure or combobox. */
+    readonly Expanded: "aria-expanded";
+    /** Refers to the required state of a form control. */
+    readonly Required: "aria-required";
+    /** Refers to the busy state of a region loading its content. */
+    readonly Busy: "aria-busy";
+    /** Refers to the announcement priority of a live region. */
+    readonly Live: "aria-live";
+    /** Refers to the direction of a composite widget. */
+    readonly Orientation: "aria-orientation";
+    /** Refers to the validation state of a control. */
+    readonly Invalid: "aria-invalid";
+    /** Refers to the pressed state of a toggle button. */
+    readonly Pressed: "aria-pressed";
+    /** Refers to the type of popup opened by an element. */
+    readonly HasPopup: "aria-haspopup";
+    /** Refers to a localized description of an element's role. */
+    readonly RoleDescription: "aria-roledescription";
+    /** Refers to the minimum value of a range widget. */
+    readonly ValueMin: "aria-valuemin";
+    /** Refers to the maximum value of a range widget. */
+    readonly ValueMax: "aria-valuemax";
+    /** Refers to the current value of a range widget. */
+    readonly ValueNow: "aria-valuenow";
+};
+/** Defines an ARIA attribute name. */
+export type AriaAttribute = (typeof AriaAttribute)[keyof typeof AriaAttribute];

package/dist/foundation/dom/enums/AttributeValue.d.ts

@@ -0,0 +1,9 @@
+/** Defines the value a boolean DOM or ARIA attribute is set to. */
+export declare const AttributeValue: {
+    /** Refers to the affirmative state — `aria-expanded="true"`, `data-copied="true"`. */
+    readonly True: "true";
+    /** Refers to the explicit negative state, for attributes where absence is not the same as false. */
+    readonly False: "false";
+};
+/** Defines the value a boolean DOM or ARIA attribute is set to. */
+export type AttributeValue = (typeof AttributeValue)[keyof typeof AttributeValue];

package/dist/foundation/dom/enums/DomEvent.d.ts

@@ -0,0 +1,25 @@
+/** Defines a DOM event name. */
+export declare const DomEvent: {
+    /** Refers to a pointer or keyboard activation. */
+    readonly Click: "click";
+    /** Refers to a committed value change — fires on blur for a native input. */
+    readonly Change: "change";
+    /** Refers to a failed operation surfaced as an event. */
+    readonly Error: "error";
+    /** Refers to a key press. */
+    readonly KeyDown: "keydown";
+    /** Refers to a key release. */
+    readonly KeyUp: "keyup";
+    /** Refers to a pointer contacting the element. */
+    readonly PointerDown: "pointerdown";
+    /** Refers to a pointer releasing over the element. */
+    readonly PointerUp: "pointerup";
+    /** Refers to a pointer leaving the element. */
+    readonly PointerLeave: "pointerleave";
+    /** Refers to a pointer interaction the browser cancelled. */
+    readonly PointerCancel: "pointercancel";
+};
+/** Defines a DOM event name. */
+export type DomEvent = (typeof DomEvent)[keyof typeof DomEvent];
+/** Defines the Vue handler-prop name carrying a DOM event — `'error'` becomes `'onError'`. */
+export type HandlerProp<TEvent extends string> = `on${Capitalize<TEvent>}`;

package/dist/foundation/dom/index.d.ts

@@ -0,0 +1,16 @@
+export { composeEventHandlers } from './ComposeEventHandlers';
+export { dataAttr } from './DataAttr';
+export type { ElementType, PolymorphicProps, PolymorphicPropsWithoutRef, PolymorphicRef } from './Polymorphic';
+export { PressExtensions, type PressEvent } from './PressExtensions';
+export { HtmlElement, ButtonType } from './enums/HtmlValues';
+export { Key } from './enums/Key';
+export { ElementTag } from './enums/ElementTag';
+export { AriaAttribute } from './enums/AriaAttribute';
+export { AttributeValue } from './enums/AttributeValue';
+export { DomEvent, type HandlerProp } from './enums/DomEvent';
+export { UrlExtensions } from './UrlExtensions';
+export * from './hooks/UseEventListener';
+export * from './hooks/UseOutsideClick';
+export * from './hooks/UseFocusTrap';
+export * from './hooks/UseScrollLock';
+export { DomOrderExtensions } from './DomOrderExtensions';

package/dist/foundation/dom/index.js

@@ -0,0 +1,31 @@
+import { c } from "../../chunks/ComposeEventHandlers-rgxao5aD.js";
+import { d } from "../../chunks/DataAttr-7BR67dTj.js";
+import { P } from "../../chunks/PressExtensions-DXqhjlR2.js";
+import { B, H } from "../../chunks/HtmlValues-jlKY5f9C.js";
+import { K } from "../../chunks/Key-CQlkK53D.js";
+import { E, u } from "../../chunks/index-DAbvXWP_.js";
+import { A } from "../../chunks/AriaAttribute-CmUjjXjp.js";
+import { A as A2, D, u as u2 } from "../../chunks/UseOutsideClick-8TTSb9x6.js";
+import { U } from "../../chunks/UrlExtensions-DqgLm0KY.js";
+import { u as u3 } from "../../chunks/UseEventListener-C1WgWGoT.js";
+import { u as u4 } from "../../chunks/UseScrollLock-DSk4L9xF.js";
+import { D as D2 } from "../../chunks/DomOrderExtensions-Czsyvn6e.js";
+export {
+  A as AriaAttribute,
+  A2 as AttributeValue,
+  B as ButtonType,
+  D as DomEvent,
+  D2 as DomOrderExtensions,
+  E as ElementTag,
+  H as HtmlElement,
+  K as Key,
+  P as PressExtensions,
+  U as UrlExtensions,
+  c as composeEventHandlers,
+  d as dataAttr,
+  u3 as useEventListener,
+  u as useFocusTrap,
+  u2 as useOutsideClick,
+  u4 as useScrollLock
+};
+//# sourceMappingURL=index.js.map

package/dist/foundation/dom/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;"}

package/dist/foundation/errors/ErrorLike.d.ts

@@ -31,5 +31,5 @@ export declare function readMember(source: object, key: string): unknown;
  * which a `Proxy` trap can throw from. Internal; not barrelled.
  */
 export declare function isError(value: unknown): value is Error;
-/** Checks whether a value is structurally an {@link ErrorLike} — an object (or function) whose `message` reads as a string. */
+/** Checks whether a value is structurally an {@link ErrorLike} — an object or function with a string `message`. */
 export declare function isErrorLike(value: unknown): value is ErrorLike;

package/dist/foundation/errors/ErrorMessage.d.ts

@@ -1,4 +1,4 @@
-/** Provides the message shown when a caught value carries nothing a person could read. Also the floor when a caller's own fallback is blank. */
+/** Provides the message shown when a caught value carries nothing readable. Also the floor for a blank fallback. */
 export declare const DefaultErrorMessage = "Something went wrong";
 /**
  * Extracts the message a UI can show for a caught value — the string itself, or its `message` member.

package/dist/foundation/errors/SerializeError.d.ts

@@ -1,14 +1,23 @@
-/** Defines the JSON-safe projection of an error produced by {@link serializeError}. Every member is a plain value — no getters, no prototype, no cycles. */
+/**
+ * Defines the JSON-safe projection of an error produced by {@link serializeError}. Every member is a plain
+ * value — no getters, no prototype, no cycles.
+ */
 export interface SerializedError {
     /** The error kind — the source's `name`, or `'Error'` when it had none. */
     readonly name: string;
-    /** The failure description — the source's `message`, or `''` when it had none (this is a log record, not UI copy). */
+    /** The failure description — the source's `message`, or `''` when it had none (a log record, not UI copy). */
     readonly message: string;
     /** The captured stack trace. Omitted when the source had none. */
     readonly stack?: string;
-    /** The machine-readable code. Omitted unless the source carried a string or number `code` — other types are dropped to keep the payload JSON-safe. */
+    /**
+     * The machine-readable code. Omitted unless the source carried a string or number `code` — other types are
+     * dropped to keep the payload JSON-safe.
+     */
     readonly code?: string | number;
-    /** The serialized underlying failure. Omitted at the root of the chain, and wherever the depth cap or a cycle stopped the walk. */
+    /**
+     * The serialized underlying failure. Omitted at the root of the chain, and wherever the depth cap or a cycle
+     * stopped the walk.
+     */
     readonly cause?: SerializedError;
 }
 /**

package/dist/foundation/errors/ToError.d.ts

@@ -1,4 +1,7 @@
-/** Provides the last-resort message used when normalization itself fails — the final rung of the never-throw contract. Internal; not barrelled. */
+/**
+ * Provides the last-resort message used when normalization itself fails — the final rung of the never-throw
+ * contract. Internal; not barrelled.
+ */
 export declare const UnknownErrorMessage = "Unknown error";
 /**
  * Normalizes any caught value into an `Error` — the first call every `catch` block makes, so that

package/dist/foundation/errors/index.js

@@ -1,17 +1,37 @@
-import { i } from "../../chunks/ErrorLike-Cfj0lZW3.js";
-import { t } from "../../chunks/ToError-CyTBsmLO.js";
-import { D, g } from "../../chunks/ErrorMessage-Cqt7WaFn.js";
-import { D as D2, f, g as g2, s } from "../../chunks/SerializeError-CclP2jCW.js";
-import { i as i2, a } from "../../chunks/ErrorRecognizers-oTklha6D.js";
+import { i as isObjectLike, r as readMember } from "../../chunks/ErrorLike-CRnbeEM0.js";
+import { a } from "../../chunks/ErrorLike-CRnbeEM0.js";
+import { t } from "../../chunks/ToError-vXncXe19.js";
+import { D, f, g, s } from "../../chunks/SerializeError-BzTdy-3I.js";
+import { i, a as a2 } from "../../chunks/ErrorRecognizers-DO2SHD6N.js";
+const DefaultErrorMessage = "Something went wrong";
+function usableMessage(candidate) {
+  if (typeof candidate !== "string") return void 0;
+  const trimmed = candidate.trim();
+  if (trimmed === "" || trimmed === "[object Object]") return void 0;
+  return trimmed;
+}
+function getErrorMessage(value, fallback = DefaultErrorMessage) {
+  try {
+    const direct = usableMessage(value);
+    if (direct !== void 0) return direct;
+    if (isObjectLike(value)) {
+      const message = usableMessage(readMember(value, "message"));
+      if (message !== void 0) return message;
+    }
+    return usableMessage(fallback) ?? DefaultErrorMessage;
+  } catch {
+    return DefaultErrorMessage;
+  }
+}
 export {
-  D as DefaultErrorMessage,
-  D2 as DefaultMaxCauseDepth,
+  DefaultErrorMessage,
+  D as DefaultMaxCauseDepth,
   f as flattenErrorChain,
-  g2 as getErrorCause,
-  g as getErrorMessage,
-  i2 as isAbortError,
-  i as isErrorLike,
-  a as isTimeoutError,
+  g as getErrorCause,
+  getErrorMessage,
+  i as isAbortError,
+  a as isErrorLike,
+  a2 as isTimeoutError,
   s as serializeError,
   t as toError
 };

package/dist/foundation/errors/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;"}
+{"version":3,"file":"index.js","sources":["../../../src/foundation/errors/ErrorMessage.ts"],"sourcesContent":["import { isObjectLike, readMember } from './ErrorLike';\n\n/** Provides the message shown when a caught value carries nothing readable. Also the floor for a blank fallback. */\nexport const DefaultErrorMessage = 'Something went wrong';\n\n/**\n * Accepts a candidate only if it is text worth showing — trimmed, non-blank, and not the\n * `'[object Object]'` tag an upstream `String(object)` may already have baked into a message.\n */\nfunction usableMessage(candidate: unknown): string | undefined {\n  if (typeof candidate !== 'string') return undefined;\n  const trimmed = candidate.trim();\n  if (trimmed === '' || trimmed === '[object Object]') return undefined;\n  return trimmed;\n}\n\n/**\n * Extracts the message a UI can show for a caught value — the string itself, or its `message` member.\n *\n * Narrower than `toError` on purpose. `toError` is total and must produce *some* `Error`, so it\n * stringifies whatever it gets; this returns UI copy, so a value with no message (a bare number, `{}`,\n * a JSON blob, `null`) yields `fallback` rather than rendering machine noise into a toast. Guaranteed\n * never to return `''` or `'[object Object]'` — a blank `fallback` degrades to {@link DefaultErrorMessage}.\n *\n * Never throws: a `message` getter that throws reads as absent.\n */\nexport function getErrorMessage(value: unknown, fallback: string = DefaultErrorMessage): string {\n  try {\n    const direct = usableMessage(value);\n    if (direct !== undefined) return direct;\n\n    if (isObjectLike(value)) {\n      const message = usableMessage(readMember(value, 'message'));\n      if (message !== undefined) return message;\n    }\n\n    return usableMessage(fallback) ?? DefaultErrorMessage;\n  } catch {\n    return DefaultErrorMessage;\n  }\n}\n"],"names":[],"mappings":";;;;;AAGO,MAAM,sBAAsB;AAMnC,SAAS,cAAc,WAAwC;AAC7D,MAAI,OAAO,cAAc,SAAU,QAAO;AAC1C,QAAM,UAAU,UAAU,KAAA;AAC1B,MAAI,YAAY,MAAM,YAAY,kBAAmB,QAAO;AAC5D,SAAO;AACT;AAYO,SAAS,gBAAgB,OAAgB,WAAmB,qBAA6B;AAC9F,MAAI;AACF,UAAM,SAAS,cAAc,KAAK;AAClC,QAAI,WAAW,OAAW,QAAO;AAEjC,QAAI,aAAa,KAAK,GAAG;AACvB,YAAM,UAAU,cAAc,WAAW,OAAO,SAAS,CAAC;AAC1D,UAAI,YAAY,OAAW,QAAO;AAAA,IACpC;AAEA,WAAO,cAAc,QAAQ,KAAK;AAAA,EACpC,QAAQ;AACN,WAAO;AAAA,EACT;AACF;"}

package/dist/foundation/files/index.d.ts

@@ -1,4 +1,4 @@
 export { type FileLike, type MatchesAcceptTypeOptions, parseAcceptTokens, matchesAccept, matchesAcceptType, } from './Accept';
-export { type SafeFileNameOptions, fileExtension, fileBaseName, safeFileName, } from './FileName';
+export { type SafeFileNameOptions, fileExtension, fileBaseName, safeFileName } from './FileName';
 export { readFileAsText, readFileAsDataUrl, readFileAsArrayBuffer } from './ReadFile';
 export { downloadBlob, downloadText, downloadJson } from './DownloadFile';

package/dist/foundation/files/index.js

@@ -1,6 +1,6 @@
 import { m, a, p } from "../../chunks/Accept-BWpCXDmS.js";
-import { s as safeFileName } from "../../chunks/FileName-CmNjFV7t.js";
-import { f, a as a2 } from "../../chunks/FileName-CmNjFV7t.js";
+import { s as safeFileName } from "../../chunks/FileName-DUtj4I5A.js";
+import { f, a as a2 } from "../../chunks/FileName-DUtj4I5A.js";
 function readWith(blob, start) {
   return new Promise((resolve, reject) => {
     const reader = new FileReader();