@wow-two-beta/ui-vue 0.0.2

package/dist/foundation/share/ShareOrCopy.d.ts

@@ -0,0 +1,27 @@
+import { ShareOptions, ShareResult } from './Share';
+import { ShareData } from './ShareData';
+/** A {@link ShareResult} widened with the clipboard-fallback outcome. */
+export type ShareOrCopyResult = ShareResult | {
+    readonly status: 'copied';
+};
+/** The `status` discriminant of a {@link ShareOrCopyResult}. */
+export type ShareOrCopyStatus = ShareOrCopyResult['status'];
+/** Tunes a share-with-fallback attempt. */
+export interface ShareOrCopyOptions extends ShareOptions {
+    /**
+     * Whether an `unsupported` share degrades to a clipboard copy. Defaults to `true`; pass `false` to keep the
+     * `unsupported` result and render your own affordance instead (an explicit copy button, a mailto link).
+     */
+    readonly fallbackToCopy?: boolean;
+}
+/**
+ * Shares `data` natively, falling back to a clipboard copy of its `shareFallbackText` when there is no Web Share
+ * API. Resolves to `copied` when the fallback ran.
+ *
+ * Falls back on `unsupported` only — `shared` / `dismissed` / `failed` pass straight through. Stays
+ * `unsupported` when `fallbackToCopy` is `false`, when the payload has no copyable text (files only), or when
+ * the clipboard is unavailable too.
+ *
+ * Never throws, never rejects.
+ */
+export declare function shareOrCopy(data: ShareData, options?: ShareOrCopyOptions): Promise<ShareOrCopyResult>;

package/dist/foundation/share/UseShare.d.ts

@@ -0,0 +1,30 @@
+import { ComputedRef, MaybeRefOrGetter, ShallowRef } from 'vue';
+import { ShareResult } from './Share';
+import { ShareData } from './ShareData';
+import { ShareOrCopyOptions, ShareOrCopyResult } from './ShareOrCopy';
+/** Where a `useShare` instance sits in its cycle: idle, or awaiting the native sheet / clipboard write. */
+export type ShareState = 'idle' | 'sharing';
+/** What {@link useShare} returns. */
+export interface ShareControls {
+    /** `sharing` while an attempt is in flight, `idle` otherwise. */
+    readonly state: Readonly<ShallowRef<ShareState>>;
+    /** Convenience for `state === 'sharing'` — the flag a button's `disabled` / spinner wants. */
+    readonly sharing: ComputedRef<boolean>;
+    /** The most recent outcome, or `null` before the first attempt and after {@link ShareControls.reset}. */
+    readonly result: Readonly<ShallowRef<ShareOrCopyResult | null>>;
+    /** Whether the last attempt ended in a clipboard copy — the cue for a "Link copied" confirmation. */
+    readonly copied: ComputedRef<boolean>;
+    /** Opens the native sheet with no fallback. Resolves to the result; never throws. */
+    readonly share: (data: ShareData) => Promise<ShareResult>;
+    /** Opens the native sheet, degrading to a clipboard copy when unsupported. Resolves to the result; never throws. */
+    readonly shareOrCopy: (data: ShareData) => Promise<ShareOrCopyResult>;
+    /** Clears `result` and returns `state` to `idle`. */
+    readonly reset: () => void;
+}
+/**
+ * Wraps the share vector in an `idle` / `sharing` + last-result state machine. Inherits the module's
+ * never-throws contract — a rejected promise is not one of the outcomes.
+ *
+ * @param options Forwarded to `share` / `shareOrCopy`. A ref or getter is read at call time.
+ */
+export declare function useShare(options?: MaybeRefOrGetter<ShareOrCopyOptions | undefined>): ShareControls;

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

@@ -0,0 +1,5 @@
+export { type ShareData, shareFallbackText } from './ShareData';
+export { canShare } from './CanShare';
+export { share, type ShareResult, type ShareStatus, type ShareOptions } from './Share';
+export { shareOrCopy, type ShareOrCopyResult, type ShareOrCopyStatus, type ShareOrCopyOptions, } from './ShareOrCopy';
+export { useShare, type ShareControls, type ShareState } from './UseShare';

package/dist/foundation/share/index.js

@@ -0,0 +1,111 @@
+import { t as toError } from "../../chunks/ToError-CyTBsmLO.js";
+import { i as isAbortError } from "../../chunks/ErrorRecognizers-oTklha6D.js";
+import { shallowRef, computed, toValue } from "vue";
+function toNativeSharePayload(data) {
+  const payload = {};
+  if (data.title !== void 0) payload.title = data.title;
+  if (data.text !== void 0) payload.text = data.text;
+  if (data.url !== void 0) payload.url = data.url;
+  if (data.files !== void 0) payload.files = [...data.files];
+  return payload;
+}
+function shareFallbackText(data) {
+  for (const candidate of [data.url, data.text, data.title]) {
+    if (candidate !== void 0 && candidate.trim() !== "") return candidate;
+  }
+  return void 0;
+}
+function hasNativeShare() {
+  try {
+    return typeof navigator !== "undefined" && typeof navigator.share === "function";
+  } catch {
+    return false;
+  }
+}
+function canShare(data) {
+  if (!hasNativeShare()) return false;
+  if (data?.files === void 0) return true;
+  try {
+    if (typeof navigator.canShare !== "function") return false;
+    return navigator.canShare(toNativeSharePayload(data)) === true;
+  } catch {
+    return false;
+  }
+}
+function reportShareError(onError, error) {
+  if (onError === void 0) return;
+  try {
+    onError(error);
+  } catch {
+  }
+}
+async function share(data, options) {
+  if (!canShare(data)) return { status: "unsupported" };
+  try {
+    await navigator.share(toNativeSharePayload(data));
+    return { status: "shared" };
+  } catch (error) {
+    if (isAbortError(error)) return { status: "dismissed" };
+    const failure = toError(error);
+    reportShareError(options?.onError, failure);
+    return { status: "failed", error: failure };
+  }
+}
+async function copyToClipboard(text, options) {
+  try {
+    if (typeof navigator === "undefined" || typeof navigator.clipboard?.writeText !== "function") {
+      return { status: "unsupported" };
+    }
+    await navigator.clipboard.writeText(text);
+    return { status: "copied" };
+  } catch (error) {
+    const failure = toError(error);
+    reportShareError(options?.onError, failure);
+    return { status: "failed", error: failure };
+  }
+}
+async function shareOrCopy(data, options) {
+  const result = await share(data, options);
+  if (result.status !== "unsupported") return result;
+  if (options?.fallbackToCopy === false) return result;
+  const text = shareFallbackText(data);
+  if (text === void 0) return result;
+  return copyToClipboard(text, options);
+}
+function useShare(options) {
+  const state = shallowRef("idle");
+  const result = shallowRef(null);
+  async function run(attempt) {
+    state.value = "sharing";
+    try {
+      const outcome = await attempt();
+      result.value = outcome;
+      return outcome;
+    } finally {
+      state.value = "idle";
+    }
+  }
+  const runShare = (data) => run(() => share(data, toValue(options)));
+  const runShareOrCopy = (data) => run(() => shareOrCopy(data, toValue(options)));
+  const reset = () => {
+    state.value = "idle";
+    result.value = null;
+  };
+  return {
+    state,
+    sharing: computed(() => state.value === "sharing"),
+    result,
+    copied: computed(() => result.value?.status === "copied"),
+    share: runShare,
+    shareOrCopy: runShareOrCopy,
+    reset
+  };
+}
+export {
+  canShare,
+  share,
+  shareFallbackText,
+  shareOrCopy,
+  useShare
+};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/foundation/share/ShareData.ts","../../../src/foundation/share/CanShare.ts","../../../src/foundation/share/Share.ts","../../../src/foundation/share/ShareOrCopy.ts","../../../src/foundation/share/UseShare.ts"],"sourcesContent":["// The payload half of the share vector — what a caller hands in, the shape the native API actually accepts, and\n// the text a share degrades to once it becomes a clipboard copy.\n//\n// Why a hand-rolled `ShareData` rather than the DOM lib's: ours is `readonly` end-to-end (a payload is a value,\n// not a buffer the platform may edit) and carries `readonly File[]`. Neither is assignable to the DOM dictionary,\n// so every native call goes through `toNativeSharePayload` to copy into the mutable shape the API demands.\n//\n// That copy is built key-by-key rather than spread, so the payload carries only members the caller actually set.\n// `canShare` and `share` then judge the exact same object, and a member the caller left off never reaches the\n// platform as a present-but-`undefined` key.\n\n/**\n * A Web Share payload — a structural mirror of the browser's `ShareData` dictionary. Every member is optional,\n * but the platform rejects a payload with none of them set.\n */\nexport interface ShareData {\n  /** Title of the shared content. Targets may ignore it — many render `text` / `url` only. */\n  readonly title?: string;\n\n  /** Body text of the share. */\n  readonly text?: string;\n\n  /** URL of the shared content — the member most targets render, and the one the clipboard fallback prefers. */\n  readonly url?: string;\n\n  /** Files to share. Support is far narrower than the rest of the payload — always gate on `canShare`. */\n  readonly files?: readonly File[];\n}\n\n/**\n * The mutable, defined-keys-only object handed to `navigator.share` / `navigator.canShare`. Exported for the\n * sibling modules (and for declaration emit) but deliberately absent from the barrel — callers pass\n * {@link ShareData}.\n */\nexport interface NativeSharePayload {\n  /** See {@link ShareData.title}. */\n  title?: string;\n\n  /** See {@link ShareData.text}. */\n  text?: string;\n\n  /** See {@link ShareData.url}. */\n  url?: string;\n\n  /** See {@link ShareData.files} — copied into a mutable array, which is what the DOM dictionary requires. */\n  files?: File[];\n}\n\n/**\n * Copies a {@link ShareData} into the mutable payload the native API accepts, omitting members the caller left\n * unset. Pure; never throws.\n */\nexport function toNativeSharePayload(data: ShareData): NativeSharePayload {\n  const payload: NativeSharePayload = {};\n  if (data.title !== undefined) payload.title = data.title;\n  if (data.text !== undefined) payload.text = data.text;\n  if (data.url !== undefined) payload.url = data.url;\n  if (data.files !== undefined) payload.files = [...data.files];\n  return payload;\n}\n\n/**\n * Picks the one string that best represents a payload as plain text — `url`, else `text`, else `title` — for the\n * clipboard fallback.\n *\n * Blank / whitespace-only members are skipped: copying `''` would report a successful share while putting\n * nothing on the user's clipboard (and clobbering what was there). Returns `undefined` when nothing is copyable,\n * which is the files-only payload. Pure; never throws.\n */\nexport function shareFallbackText(data: ShareData): string | undefined {\n  for (const candidate of [data.url, data.text, data.title]) {\n    if (candidate !== undefined && candidate.trim() !== '') return candidate;\n  }\n  return undefined;\n}\n","// Feature detection for the share vector. Two conditions, kept deliberately separate: `navigator.share` must\n// exist at all, and — only when the payload carries files — `navigator.canShare` must accept it. File sharing is\n// supported far more narrowly than text / url sharing, and is the one case the platform itself can veto.\n//\n// Every read is guarded. `navigator` is absent under SSR, the members are absent on most desktop browsers, and a\n// property read can in principle throw (a polyfill's getter). A detector that throws defeats its own purpose, so\n// the answer is always a boolean.\n\nimport { toNativeSharePayload, type ShareData } from './ShareData';\n\n/** Whether the environment exposes `navigator.share`. False under SSR (no `navigator`) and on non-supporting browsers. */\nfunction hasNativeShare(): boolean {\n  try {\n    return typeof navigator !== 'undefined' && typeof navigator.share === 'function';\n  } catch {\n    // A throwing `navigator` / `share` getter reads as absent — same posture as `foundation/errors`' guarded reads.\n    return false;\n  }\n}\n\n/**\n * Reports whether `share` can hand `data` to a native share sheet.\n *\n * With no argument — or a file-free payload — this is pure availability: does `navigator.share` exist. When\n * `data.files` is present the platform is asked directly via `navigator.canShare`, and a missing `canShare` is\n * treated as a no: a browser that cannot answer the file question is not one to hand files to.\n *\n * Never throws. Returns `false` under SSR.\n */\nexport function canShare(data?: ShareData): boolean {\n  if (!hasNativeShare()) return false;\n  if (data?.files === undefined) return true;\n\n  try {\n    if (typeof navigator.canShare !== 'function') return false;\n    return navigator.canShare(toNativeSharePayload(data)) === true;\n  } catch {\n    // `canShare` is specified not to throw, but a partial implementation may. Unverifiable reads as unsupported.\n    return false;\n  }\n}\n","// The native half of the share vector: one call, four outcomes, no throw.\n//\n// DEFINING CONTRACT: NOTHING HERE THROWS. This is called straight from a click handler, where a rejection is an\n// unhandled error in the consumer's app and the user sees nothing at all. Every path — missing API, user\n// dismissal, platform failure, even an `onError` callback that itself throws — resolves to a `ShareResult` the\n// caller switches on.\n//\n// The dismissal case is the reason the result is a union rather than a boolean. Closing the share sheet rejects\n// the very same promise a genuine failure does, distinguished only by an `AbortError` name; reported as a\n// failure it raises a toast for something the user deliberately did. So it gets its own status and never reaches\n// `onError`. The recognizer is `foundation/errors`' `isAbortError`, which matches on `name` — so it holds for a\n// `DOMException` from another realm and for the plain `{ name: 'AbortError' }` a test double throws.\n\nimport { isAbortError, toError } from '../errors';\n\nimport { canShare } from './CanShare';\nimport { toNativeSharePayload, type ShareData } from './ShareData';\n\n/**\n * The outcome of a share attempt.\n *\n * - `shared` — the native sheet completed. The platform does not report *which* target was picked, nor whether\n *   the receiving app did anything with the payload, so this is \"handed off\", not \"delivered\".\n * - `dismissed` — the user closed the sheet. A decision, not an error.\n * - `unsupported` — no Web Share here: desktop browser, SSR, or a files payload the platform refused.\n * - `failed` — anything else, carrying the normalized `Error`.\n */\nexport type ShareResult =\n  | { readonly status: 'shared' }\n  | { readonly status: 'dismissed' }\n  | { readonly status: 'unsupported' }\n  | { readonly status: 'failed'; readonly error: Error };\n\n/** The `status` discriminant of a {@link ShareResult} — for a consumer's own switch or status→copy map. */\nexport type ShareStatus = ShareResult['status'];\n\n/** Tunes a share attempt. */\nexport interface ShareOptions {\n  /**\n   * Called with the normalized error on a `failed` result — the seam for a toast or telemetry hook. Never called\n   * for `dismissed` or `unsupported`, neither of which is a failure. A throw from this callback is swallowed.\n   */\n  readonly onError?: (error: Error) => void;\n}\n\n/**\n * Hands a consumer's callback the failure, absorbing a throw from the callback itself. A reporter that throws\n * must not convert a typed result into an unhandled rejection. Exported for the sibling fallback module; absent\n * from the barrel.\n */\nexport function reportShareError(onError: ShareOptions['onError'], error: Error): void {\n  if (onError === undefined) return;\n  try {\n    onError(error);\n  } catch {\n    // The consumer's own reporter failed. There is nothing useful left to do with that — the result still\n    // reaches the caller, which is the guarantee that matters.\n  }\n}\n\n/**\n * Opens the native share sheet for `data` and resolves to a {@link ShareResult}.\n *\n * Call it from a user gesture: browsers require transient activation for the sheet, and without one the platform\n * rejects — which surfaces as `failed`, not `unsupported`, since the API was in fact present.\n *\n * Never throws, never rejects.\n */\nexport async function share(data: ShareData, options?: ShareOptions): Promise<ShareResult> {\n  if (!canShare(data)) return { status: 'unsupported' };\n\n  try {\n    await navigator.share(toNativeSharePayload(data));\n    return { status: 'shared' };\n  } catch (error) {\n    // The user's own decision ends the flow quietly — no `onError`, no fallback downstream.\n    if (isAbortError(error)) return { status: 'dismissed' };\n\n    const failure = toError(error);\n    reportShareError(options?.onError, failure);\n    return { status: 'failed', error: failure };\n  }\n}\n","// The graceful-degradation half of the share vector. Web Share is mobile-first — most desktop browsers have no\n// sheet at all — so a share button wired only to `share` is dead UI for a large share of traffic. The fallback\n// puts the payload's text on the clipboard instead, which is what the user reaches for next anyway.\n//\n// Only `unsupported` falls back, and the exclusions are the whole point:\n//   - `dismissed` must NOT copy. The user opened the sheet and closed it; that is a decision not to share.\n//     Writing to their clipboard anyway overrides that decision and clobbers whatever they had on it.\n//   - `failed` must NOT copy either — the platform tried and broke, and a copy would report success for a\n//     share that did not happen.\n//\n// Clipboard writing: `foundation/hooks`' `useClipboard` owns the Vue-side copy (transient `copied` flag,\n// auto-reset), but it is a composable and cannot be called from this async, setup-free path — and its `copy`\n// resolves either way, folding failure into reactive state that a framework-free caller cannot read. So the\n// write here goes\n// straight to `navigator.clipboard.writeText`, guarded exactly as the rest of the slice guards `navigator`.\n// Consumers wanting the transient flag compose `useClipboard` themselves, or read `useShare().copied`.\n\nimport { toError } from '../errors';\n\nimport { reportShareError, share, type ShareOptions, type ShareResult } from './Share';\nimport { shareFallbackText, type ShareData } from './ShareData';\n\n/** A {@link ShareResult} widened with the clipboard-fallback outcome. */\nexport type ShareOrCopyResult = ShareResult | { readonly status: 'copied' };\n\n/** The `status` discriminant of a {@link ShareOrCopyResult}. */\nexport type ShareOrCopyStatus = ShareOrCopyResult['status'];\n\n/** Tunes a share-with-fallback attempt. */\nexport interface ShareOrCopyOptions extends ShareOptions {\n  /**\n   * Whether an `unsupported` share degrades to a clipboard copy. Defaults to `true`; pass `false` to keep the\n   * `unsupported` result and render your own affordance instead (an explicit copy button, a mailto link).\n   */\n  readonly fallbackToCopy?: boolean;\n}\n\n/** Writes `text` to the system clipboard, mapping the outcome onto the share result vocabulary. Never throws. */\nasync function copyToClipboard(text: string, options?: ShareOptions): Promise<ShareOrCopyResult> {\n  try {\n    if (typeof navigator === 'undefined' || typeof navigator.clipboard?.writeText !== 'function') {\n      return { status: 'unsupported' };\n    }\n\n    await navigator.clipboard.writeText(text);\n    return { status: 'copied' };\n  } catch (error) {\n    // A rejected write is a real failure (denied permission, insecure context): the user asked to share and\n    // nothing reached them. Reported rather than quietly downgraded to `unsupported`.\n    const failure = toError(error);\n    reportShareError(options?.onError, failure);\n    return { status: 'failed', error: failure };\n  }\n}\n\n/**\n * Shares `data` natively, falling back to a clipboard copy of its `shareFallbackText` when there is no Web Share\n * API. Resolves to `copied` when the fallback ran.\n *\n * Falls back on `unsupported` only — `shared` / `dismissed` / `failed` pass straight through. Stays\n * `unsupported` when `fallbackToCopy` is `false`, when the payload has no copyable text (files only), or when\n * the clipboard is unavailable too.\n *\n * Never throws, never rejects.\n */\nexport async function shareOrCopy(data: ShareData, options?: ShareOrCopyOptions): Promise<ShareOrCopyResult> {\n  const result = await share(data, options);\n  if (result.status !== 'unsupported') return result;\n  if (options?.fallbackToCopy === false) return result;\n\n  const text = shareFallbackText(data);\n  if (text === undefined) return result;\n\n  return copyToClipboard(text, options);\n}\n","// The Vue binding of the share vector — a thin state machine over `share` / `shareOrCopy`, so a share button\n// can render a pending state and a post-action confirmation without every consumer re-declaring the same two\n// refs. No behaviour of its own: both callbacks delegate, so the never-throws contract holds unchanged and\n// every outcome arrives as a `ShareOrCopyResult` on `result`.\n//\n// Options are read through `toValue` at call time, so a reactive `onError` stays live — the same shape\n// `foundation/shortcuts`' `useHotkeys` uses.\n//\n// Nothing here touches a platform global at setup: `share` and `shareOrCopy` are only reached from a user\n// gesture, which is also what the Web Share API requires.\n//\n// The pending flag is cleared in a `finally`. The delegates are contractually throw-free, but a state machine\n// that can strand itself at `sharing` would disable the button forever, so the reset does not depend on that\n// contract holding.\n\nimport { computed, shallowRef, toValue, type ComputedRef, type MaybeRefOrGetter, type ShallowRef } from 'vue';\n\nimport { share, type ShareResult } from './Share';\nimport type { ShareData } from './ShareData';\nimport { shareOrCopy, type ShareOrCopyOptions, type ShareOrCopyResult } from './ShareOrCopy';\n\n/** Where a `useShare` instance sits in its cycle: idle, or awaiting the native sheet / clipboard write. */\nexport type ShareState = 'idle' | 'sharing';\n\n/** What {@link useShare} returns. */\nexport interface ShareControls {\n  /** `sharing` while an attempt is in flight, `idle` otherwise. */\n  readonly state: Readonly<ShallowRef<ShareState>>;\n\n  /** Convenience for `state === 'sharing'` — the flag a button's `disabled` / spinner wants. */\n  readonly sharing: ComputedRef<boolean>;\n\n  /** The most recent outcome, or `null` before the first attempt and after {@link ShareControls.reset}. */\n  readonly result: Readonly<ShallowRef<ShareOrCopyResult | null>>;\n\n  /** Whether the last attempt ended in a clipboard copy — the cue for a \"Link copied\" confirmation. */\n  readonly copied: ComputedRef<boolean>;\n\n  /** Opens the native sheet with no fallback. Resolves to the result; never throws. */\n  readonly share: (data: ShareData) => Promise<ShareResult>;\n\n  /** Opens the native sheet, degrading to a clipboard copy when unsupported. Resolves to the result; never throws. */\n  readonly shareOrCopy: (data: ShareData) => Promise<ShareOrCopyResult>;\n\n  /** Clears `result` and returns `state` to `idle`. */\n  readonly reset: () => void;\n}\n\n/**\n * Wraps the share vector in an `idle` / `sharing` + last-result state machine. Inherits the module's\n * never-throws contract — a rejected promise is not one of the outcomes.\n *\n * @param options Forwarded to `share` / `shareOrCopy`. A ref or getter is read at call time.\n */\nexport function useShare(options?: MaybeRefOrGetter<ShareOrCopyOptions | undefined>): ShareControls {\n  const state = shallowRef<ShareState>('idle');\n  const result = shallowRef<ShareOrCopyResult | null>(null);\n\n  /** Runs one attempt, bracketing it with the pending flag and recording the outcome. */\n  async function run<TResult extends ShareOrCopyResult>(attempt: () => Promise<TResult>): Promise<TResult> {\n    state.value = 'sharing';\n    try {\n      const outcome = await attempt();\n      result.value = outcome;\n      return outcome;\n    } finally {\n      state.value = 'idle';\n    }\n  }\n\n  const runShare = (data: ShareData): Promise<ShareResult> => run(() => share(data, toValue(options)));\n\n  const runShareOrCopy = (data: ShareData): Promise<ShareOrCopyResult> =>\n    run(() => shareOrCopy(data, toValue(options)));\n\n  const reset = (): void => {\n    state.value = 'idle';\n    result.value = null;\n  };\n\n  return {\n    state,\n    sharing: computed(() => state.value === 'sharing'),\n    result,\n    copied: computed(() => result.value?.status === 'copied'),\n    share: runShare,\n    shareOrCopy: runShareOrCopy,\n    reset,\n  };\n}\n"],"names":[],"mappings":"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"}

package/dist/foundation/shortcuts/Chord.d.ts

@@ -0,0 +1,51 @@
+/** The modifier tokens a chord string accepts. `Mod` is platform-adaptive (⌘ on Apple, Ctrl elsewhere). */
+export declare const Modifier: {
+    /** Platform-adaptive primary modifier — ⌘ (Command) on Apple, Ctrl elsewhere. */
+    readonly Mod: "mod";
+    /** The Control key. */
+    readonly Ctrl: "ctrl";
+    /** The Meta key — ⌘ (Command) on Apple, ⊞ (Windows) elsewhere. */
+    readonly Meta: "meta";
+    /** The Shift key. */
+    readonly Shift: "shift";
+    /** The Alt / Option key. */
+    readonly Alt: "alt";
+};
+export type Modifier = (typeof Modifier)[keyof typeof Modifier];
+/** A parsed keystroke combination — a canonical main key plus the four modifier flags. */
+export interface Chord {
+    /** The canonical `KeyboardEvent.key` for the main key (letters lowercased, named keys canonical, e.g. `Enter`). */
+    readonly key: string;
+    /** Whether Control must be held. */
+    readonly ctrl: boolean;
+    /** Whether Meta (⌘ / ⊞) must be held. */
+    readonly meta: boolean;
+    /** Whether Shift must be held. */
+    readonly shift: boolean;
+    /** Whether Alt / Option must be held. */
+    readonly alt: boolean;
+}
+/** The `KeyboardEvent` fields a chord match reads — a structural subset satisfied by native DOM events. */
+export type KeyboardEventLike = Pick<KeyboardEvent, 'key' | 'ctrlKey' | 'metaKey' | 'shiftKey' | 'altKey'>;
+/** Detects an Apple platform (for `mod` → ⌘ and symbol formatting). SSR-safe; pass `platformHint` to force it in tests. */
+export declare function isApplePlatform(platformHint?: string): boolean;
+/** Options shared by the platform-sensitive chord helpers. */
+export interface ChordPlatformOptions {
+    /** Forces Apple vs non-Apple resolution (for `mod` and formatting); defaults to runtime detection. */
+    readonly applePlatform?: boolean;
+}
+/**
+ * Parses a chord string (`mod+shift+k`, `ctrl+/`, `esc`) into a {@link Chord}. Tokens split on `+`, are
+ * case-insensitive, and may appear in any order; `mod` resolves per platform. Throws when no non-modifier key
+ * is present. To bind the literal `+` key, write `plus` (or `mod+plus`).
+ */
+export declare function parseChord(input: string, options?: ChordPlatformOptions): Chord;
+/** Tests whether a keyboard event satisfies a chord — all four modifiers exact, main key case-insensitive. */
+export declare function matchesChord(event: KeyboardEventLike, chord: Chord): boolean;
+/**
+ * Renders a chord as a human label for a `<kbd>` hint. Apple builds the compact symbol form (`⌃⌥⇧⌘K`); other
+ * platforms build the `Ctrl+Alt+Shift+Win+K` form. Modifier order follows each platform's convention.
+ */
+export declare function formatChord(chord: Chord, options?: ChordPlatformOptions): string;
+/** Convenience: parse then format a chord string in one step (`formatChordString('mod+k')` → `⌘K` / `Ctrl+K`). */
+export declare function formatChordString(input: string, options?: ChordPlatformOptions): string;

package/dist/foundation/shortcuts/UseHotkeys.d.ts

@@ -0,0 +1,34 @@
+import { MaybeRefOrGetter } from 'vue';
+import { ChordPlatformOptions } from './Chord';
+/** Tunes how a hotkey binding listens. */
+export interface HotkeyOptions extends ChordPlatformOptions {
+    /** Whether the binding is active. Defaults to `true`. */
+    readonly enabled?: MaybeRefOrGetter<boolean>;
+    /** Whether a match calls `event.preventDefault()`. Defaults to `true`. */
+    readonly preventDefault?: MaybeRefOrGetter<boolean>;
+    /**
+     * Whether to ignore keystrokes while a text input / textarea / select / `contenteditable` has focus.
+     * Defaults to `true` — but a chord carrying Ctrl or Meta still fires (so `mod+k` works inside a field).
+     */
+    readonly ignoreInputs?: MaybeRefOrGetter<boolean>;
+    /** The element to bind to; defaults to `window`. Pass a template ref to scope the shortcut to a subtree. */
+    readonly target?: MaybeRefOrGetter<HTMLElement | null | undefined>;
+    /** Which key phase to listen on. Defaults to `keydown`. */
+    readonly eventType?: 'keydown' | 'keyup';
+}
+/**
+ * Binds one or more chord strings to a single handler. Multiple chords act as an OR (`['mod+k', 'ctrl+k']`).
+ * The chords are parsed in a `computed`, so an inline array literal costs one parse; the handler and the
+ * behavioural options are read at event time, so passing fresh closures is fine — the listener is attached
+ * once per `target`/`eventType`/platform and reused.
+ */
+export declare function useHotkeys(chords: MaybeRefOrGetter<string | readonly string[]>, handler: (event: KeyboardEvent) => void, options?: HotkeyOptions): void;
+/** The per-chord handler a keymap holds; a falsy entry is a row the caller has disabled. */
+type HotkeyMapHandler = ((event: KeyboardEvent) => void) | false | null | undefined;
+/**
+ * Binds a map of `chord → handler` — the ergonomic shape for a command palette or editor keymap. Each entry is
+ * an independent binding sharing the same `options`. A `false`/`null`/`undefined` handler entry is skipped, so a
+ * caller can conditionally disable one row without restructuring the map.
+ */
+export declare function useHotkeyMap(map: MaybeRefOrGetter<Readonly<Record<string, HotkeyMapHandler>>>, options?: HotkeyOptions): void;
+export {};

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

@@ -0,0 +1,3 @@
+export { type Chord, type KeyboardEventLike, type ChordPlatformOptions, Modifier, isApplePlatform, parseChord, matchesChord, formatChord, formatChordString, } from './Chord';
+export { Key } from '../utils/KeyboardExtensions';
+export { useHotkeys, useHotkeyMap, type HotkeyOptions } from './UseHotkeys';

package/dist/foundation/shortcuts/index.js

@@ -0,0 +1,15 @@
+import { M, f, a, i, m, p } from "../../chunks/Chord-D9Z-j3O0.js";
+import { u, a as a2 } from "../../chunks/UseHotkeys-CKIYK5Mq.js";
+import { K } from "../../chunks/KeyboardExtensions-CQlkK53D.js";
+export {
+  K as Key,
+  M as Modifier,
+  f as formatChord,
+  a as formatChordString,
+  i as isApplePlatform,
+  m as matchesChord,
+  p as parseChord,
+  u as useHotkeyMap,
+  a2 as useHotkeys
+};
+//# sourceMappingURL=index.js.map

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

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

package/dist/foundation/speech/CreateSpeechRecognizer.d.ts

@@ -0,0 +1,79 @@
+import { SpeechRecognitionFailure, SpeechTranscript } from './SpeechRecognitionResult';
+/**
+ * The outcome of a {@link SpeechRecognizer.start} call.
+ *
+ * - `started` — the engine accepted the request. Listening begins later, at the `onStart` callback.
+ * - `already-started` — a session is running or starting. The native call would have thrown here.
+ * - `unsupported` — no recognition API (SSR, Firefox).
+ * - `failed` — the engine refused, carrying the normalized `Error`.
+ */
+export type RecognizerStartResult = {
+    readonly status: 'started';
+} | {
+    readonly status: 'already-started';
+} | {
+    readonly status: 'unsupported';
+} | {
+    readonly status: 'failed';
+    readonly error: Error;
+};
+/** Configuration and callbacks for a recognizer. Applied once, at creation — see {@link createSpeechRecognizer}. */
+export interface SpeechRecognizerOptions {
+    /** BCP-47 tag to transcribe (`en-US`, `uz`). Same vocabulary as `foundation/i18n`'s locale. Defaults to the engine's. */
+    readonly lang?: string;
+    /** Keep listening past the first phrase. Defaults to `false`. Chrome still ends the session on long silence. */
+    readonly continuous?: boolean;
+    /** Emit revisable partial results while the user is still speaking. Defaults to `false`. */
+    readonly interimResults?: boolean;
+    /** How many alternatives each result carries. Defaults to the engine's (`1`). */
+    readonly maxAlternatives?: number;
+    /** Every update, interim and final — the one callback that sees the whole stream. A throw from it is swallowed. */
+    readonly onResult?: (result: SpeechTranscript) => void;
+    /** Committed phrases only. The callback most consumers want. A throw from it is swallowed. */
+    readonly onFinal?: (transcript: string) => void;
+    /** The current uncommitted text, joined across pending results. Requires `interimResults`. */
+    readonly onInterim?: (transcript: string) => void;
+    /** A classified failure. `no-speech` and `aborted` arrive here too — neither is worth a toast. */
+    readonly onError?: (failure: SpeechRecognitionFailure) => void;
+    /** The engine is now listening — later than the `start()` that asked for it, and after any permission prompt. */
+    readonly onStart?: () => void;
+    /** The session ended, for ANY reason: `stop`, `abort`, an error, or the engine's own silence timeout. */
+    readonly onEnd?: () => void;
+}
+/** A wrapped recognition session. Every method is total — nothing throws, nothing needs a `try`. */
+export interface SpeechRecognizer {
+    /** Whether a real engine is behind this recognizer. `false` under SSR, in Firefox, and if construction failed. */
+    readonly supported: boolean;
+    /** Whether the engine is listening right now — `false` during the gap between `start()` and the `start` event. */
+    readonly listening: boolean;
+    /** Begins a session. Safe to call twice: the second call answers `already-started` instead of throwing. */
+    readonly start: () => RecognizerStartResult;
+    /** Ends the session, keeping results the engine has already recognized. A no-op when idle. */
+    readonly stop: () => void;
+    /** Ends the session immediately, discarding pending results. A no-op when idle. Use this on unmount. */
+    readonly abort: () => void;
+}
+/**
+ * Creates a wrapped speech recognizer.
+ *
+ * ```ts
+ * const recognizer = createSpeechRecognizer({
+ *   lang: 'en-US',
+ *   interimResults: true,
+ *   onFinal: (text) => append(text),
+ *   onError: (failure) => { if (failure.status === 'denied') showMicrophoneHelp(); },
+ * });
+ *
+ * if (recognizer.supported) recognizer.start();
+ * ```
+ *
+ * Options are applied ONCE, at creation: the platform reads `lang` / `continuous` / `interimResults` when a
+ * session starts and offers no way to reconfigure a running one, so changing them means creating a new
+ * recognizer. `useSpeechRecognition` does exactly that when its `lang` changes.
+ *
+ * Never throws. Always returns a usable object — check `supported`, or read the `start()` result.
+ *
+ * @param options Language, session shape, and callbacks.
+ * @returns The recognizer. `supported: false` under SSR, in Firefox, and where the constructor exists but refuses.
+ */
+export declare function createSpeechRecognizer(options?: SpeechRecognizerOptions): SpeechRecognizer;

package/dist/foundation/speech/ListVoices.d.ts

@@ -0,0 +1,78 @@
+/** How long {@link listVoices} waits for a populated list before answering with whatever exists. */
+export declare const DefaultVoicesTimeoutMs = 1000;
+/** Tunes the wait for an asynchronously-populated voice list. */
+export interface ListVoicesOptions {
+    /** How long to wait for `voiceschanged` before resolving with whatever exists. Defaults to `1000`. */
+    readonly timeoutMs?: number;
+}
+/**
+ * The synchronous snapshot of the installed voices.
+ *
+ * OFTEN EMPTY on first paint — that is the platform behaviour this module exists to absorb, not a failure. Use it
+ * only where an empty answer is acceptable (a re-render triggered by something else); prefer {@link listVoices}
+ * anywhere the answer drives UI.
+ *
+ * Never throws. `[]` under SSR.
+ *
+ * @returns The voices the engine has registered so far.
+ */
+export declare function listVoicesSync(): readonly SpeechSynthesisVoice[];
+/**
+ * Subscribes to `voiceschanged`.
+ *
+ * Exported for the sibling composable, which re-reads the list when the engine revises it (Chrome does, after remote
+ * voices load). Absent from the barrel — a consumer wants `useSpeechSynthesis`'s `voices`, not an event.
+ *
+ * Never throws. A no-op under SSR, where the returned unsubscribe is still safe to call.
+ *
+ * @param listener Called whenever the engine reports a change. Receives no arguments; re-read the list.
+ * @returns The unsubscribe function.
+ */
+export declare function onVoicesChanged(listener: () => void): () => void;
+/**
+ * Lists the installed voices, WAITING for the asynchronously-populated list rather than returning the empty array
+ * a first `getVoices()` hands back.
+ *
+ * Resolves immediately when the list is already populated — the common case on every call after the first.
+ *
+ * ```ts
+ * const voices = await listVoices();
+ * const german = voices.filter((voice) => voice.lang.startsWith('de'));
+ * ```
+ *
+ * Never throws, never rejects. Resolves to `[]` under SSR, and to `[]` on a device that genuinely has no voices
+ * (after the timeout).
+ *
+ * @param options The wait bound. Defaults to {@link DefaultVoicesTimeoutMs}.
+ * @returns The voices, or `[]`.
+ */
+export declare function listVoices(options?: ListVoicesOptions): Promise<readonly SpeechSynthesisVoice[]>;
+/**
+ * Filters voices to a language tag, exact matches first, then same-primary-subtag ones.
+ *
+ * Pure — takes the list rather than fetching it, so it is trivially testable and reusable on a list a consumer
+ * already holds. Tag comparison is case-insensitive and tolerates the `en_US` separator some engines report.
+ *
+ * The two tiers are kept in order rather than collapsed because they are not equivalent: `en-GB` text read by an
+ * `en-US` voice is understandable, so it belongs in the list — but never ahead of an actual `en-GB` voice.
+ *
+ * @param voices The list to filter, typically from {@link listVoices}.
+ * @param lang A BCP-47 tag (`de`, `en-GB`). Same vocabulary as `foundation/i18n`'s locale.
+ * @returns The matching voices, best match first. Empty when nothing matches.
+ */
+export declare function voicesForLang(voices: readonly SpeechSynthesisVoice[], lang: string): readonly SpeechSynthesisVoice[];
+/**
+ * Picks the best voice for a language tag, waiting for the voice list the same way {@link listVoices} does.
+ *
+ * ```ts
+ * const voice = await findVoice('de-DE');
+ * await speak('Guten Tag', { voice, lang: 'de-DE' });
+ * ```
+ *
+ * Never throws, never rejects.
+ *
+ * @param lang A BCP-47 tag.
+ * @param options The wait bound, forwarded to {@link listVoices}.
+ * @returns The best match, or `undefined` when the language has no voice installed (SSR included).
+ */
+export declare function findVoice(lang: string, options?: ListVoicesOptions): Promise<SpeechSynthesisVoice | undefined>;

package/dist/foundation/speech/Speak.d.ts

@@ -0,0 +1,52 @@
+import { SpeakResult } from './SpeechResult';
+/** Tunes one utterance. Every field is optional; an omitted one leaves the engine's own default in place. */
+export interface SpeakOptions {
+    /** The voice to speak with — an entry from `listVoices()`. Omitted means the engine's default for `lang`. */
+    readonly voice?: SpeechSynthesisVoice;
+    /** BCP-47 language tag (`en-US`, `de`). Same vocabulary as `foundation/i18n`'s locale, which `useSpeechSynthesis` defaults it to. */
+    readonly lang?: string;
+    /** Speed, `0.1`–`10`, default `1`. Clamped to that range; a non-finite value is ignored. */
+    readonly rate?: number;
+    /** Pitch, `0`–`2`, default `1`. Clamped to that range; a non-finite value is ignored. */
+    readonly pitch?: number;
+    /** Volume, `0`–`1`, default `1`. Clamped to that range; a non-finite value is ignored. */
+    readonly volume?: number;
+}
+/**
+ * The return of {@link speak}: awaitable for the outcome, and callable for control while it runs.
+ *
+ * All three controls are GLOBAL — the platform exposes no per-utterance cancel or pause, so they act on the
+ * document's whole utterance queue.
+ */
+export interface SpeechHandle extends PromiseLike<SpeakResult> {
+    /** The underlying promise, for a caller that wants to store or pass it. Never rejects. */
+    readonly spoken: Promise<SpeakResult>;
+    /** Stops this utterance — and every other queued one. Settles the handle as `cancelled`. */
+    readonly cancel: () => void;
+    /** Pauses the engine. See `SpeechControls` for Chrome-on-Android's pause-is-cancel behaviour. */
+    readonly pause: () => void;
+    /** Resumes a paused engine. */
+    readonly resume: () => void;
+}
+/**
+ * Speaks `text` aloud, settling when the utterance ends.
+ *
+ * ```ts
+ * const result = await speak('Order confirmed', { lang: 'en-GB', rate: 1.1 });
+ * if (result.status === 'unsupported') showTextInstead();
+ *
+ * const handle = speak(longArticle);
+ * stopButton.onclick = () => handle.cancel(); // settles as `cancelled`
+ * ```
+ *
+ * Call it from a user gesture where possible: some engines refuse synthesis without one (arriving as `failed`
+ * with a `not-allowed` code, since the API was present).
+ *
+ * Never throws, never rejects.
+ *
+ * @param text The text to speak. Empty text is handed to the engine unchanged — engines differ on whether they
+ *   fire `end` for it, which is exactly the kind of thing a caller should not have to guess about mid-sentence.
+ * @param options Voice, language, and prosody. Out-of-range prosody is clamped; see {@link SpeakOptions}.
+ * @returns The awaitable handle — `spoken` / `cancelled` / `unsupported` / `failed`, plus the live controls.
+ */
+export declare function speak(text: string, options?: SpeakOptions): SpeechHandle;

package/dist/foundation/speech/SpeechControls.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The current cancel generation.
+ *
+ * Internal to the slice — `Speak` samples it before speaking and compares on settle. Absent from the barrel: the
+ * number means nothing on its own, and a consumer comparing two samples is reimplementing `speak`.
+ *
+ * @returns A monotonically increasing count of cancels that reached the engine.
+ */
+export declare function cancelGeneration(): number;
+/**
+ * Stops all speech and empties the utterance queue.
+ *
+ * GLOBAL: this silences every utterance in the document, not just the caller's. Any in-flight `speak` settles as
+ * `cancelled` rather than `spoken` or `failed`.
+ *
+ * Never throws. A no-op under SSR.
+ *
+ * @returns `true` when a real engine was reached; `false` under SSR or when the call itself failed.
+ */
+export declare function cancelSpeech(): boolean;
+/**
+ * Pauses the current utterance, leaving the queue intact.
+ *
+ * Never throws. A no-op under SSR, and on engines that expose no `pause` (some mobile webviews). See the module
+ * header for Chrome-on-Android's pause-is-cancel behaviour.
+ *
+ * @returns `true` when the call reached a real engine.
+ */
+export declare function pauseSpeech(): boolean;
+/**
+ * Resumes speech paused by {@link pauseSpeech}.
+ *
+ * Never throws. A no-op under SSR.
+ *
+ * @returns `true` when the call reached a real engine.
+ */
+export declare function resumeSpeech(): boolean;
+/**
+ * Whether the engine is speaking right now.
+ *
+ * Reads the platform's own flag rather than a locally tracked one, so it stays true for speech this module did
+ * not start. Note it stays `true` while PAUSED — that is the spec's definition, not a bug; pair it with
+ * {@link isSpeechPaused}.
+ *
+ * Never throws. `false` under SSR.
+ *
+ * @returns The engine's `speaking` flag.
+ */
+export declare function isSpeaking(): boolean;
+/**
+ * Whether the engine is in a paused state.
+ *
+ * Never throws. `false` under SSR.
+ *
+ * @returns The engine's `paused` flag.
+ */
+export declare function isSpeechPaused(): boolean;