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

package/dist/foundation/selection/models/Selection.d.ts

@@ -0,0 +1,116 @@
+/** Represents the identity of a selectable item — the value a surface keys its rows/options by. */
+export type SelectionKey = string | number;
+/** Defines how many items a surface allows to be selected at once. */
+export declare const SelectionMode: {
+    /** Refers to a non-selectable surface — every mutating op is inert. */
+    readonly None: "none";
+    /** Refers to at most one selected item — selecting replaces rather than accumulates. */
+    readonly Single: "single";
+    /** Refers to any number of selected items, including ranges. */
+    readonly Multiple: "multiple";
+};
+export type SelectionMode = (typeof SelectionMode)[keyof typeof SelectionMode];
+/** Defines the tri-state a header checkbox renders for a key set. */
+export declare const SelectionStatus: {
+    /** Refers to none of the given keys being selected — an unchecked box. */
+    readonly None: "none";
+    /** Refers to a partial selection — an indeterminate box. */
+    readonly Some: "some";
+    /** Refers to every given key being selected — a checked box. */
+    readonly All: "all";
+};
+export type SelectionStatus = (typeof SelectionStatus)[keyof typeof SelectionStatus];
+/** Represents an immutable selection snapshot. Build with {@link createSelection}; never construct by hand. */
+export interface SelectionState<TKey extends SelectionKey> {
+    /** The mode enforced by every op on this state. */
+    readonly mode: SelectionMode;
+    /** The selected keys, in the order they were added. */
+    readonly keys: ReadonlySet<TKey>;
+    /** The last plainly-interacted key — the fixed end of a subsequent range extension, or `null`. */
+    readonly anchor: TKey | null;
+}
+/** Options accepted by the range ops. */
+export interface SelectRangeOptions {
+    /**
+     * The union behaviour. `true` (default) merges the range into the existing selection — the checkbox-list
+     * shift-click every data grid in this SDK wants. `false` replaces the selection with the range alone,
+     * matching a file-manager style list.
+     */
+    isAdditive?: boolean;
+}
+/**
+ * Creates a selection state, normalising the seed to the mode: `none` drops every key, `single` keeps only
+ * the first. Also the way to re-mode an existing state — `createSelection('single', state.keys)`.
+ *
+ * @param mode The selection mode to enforce. Defaults to `'multiple'`.
+ * @param keys The initially selected keys, in priority order.
+ * @param anchor The initial range anchor. Defaults to `null`.
+ */
+export declare function createSelection<TKey extends SelectionKey>(mode?: SelectionMode, keys?: Iterable<TKey>, anchor?: TKey | null): SelectionState<TKey>;
+/** Reports whether a key is currently selected. */
+export declare function isSelected<TKey extends SelectionKey>(state: SelectionState<TKey>, key: TKey): boolean;
+/** The number of selected keys. */
+export declare function selectionCount<TKey extends SelectionKey>(state: SelectionState<TKey>): number;
+/** The selected keys as an array, in insertion order — the shape a controlled `onSelectionChange` emits. */
+export declare function selectedKeys<TKey extends SelectionKey>(state: SelectionState<TKey>): ReadonlyArray<TKey>;
+/**
+ * Selects a key and moves the anchor to it. In `single` mode this REPLACES the selection rather than
+ * accumulating; in `none` mode it is inert.
+ */
+export declare function select<TKey extends SelectionKey>(state: SelectionState<TKey>, key: TKey): SelectionState<TKey>;
+/**
+ * Deselects a key and moves the anchor to it. Inert in `none` mode, and inert when the key was not
+ * selected — an unselected key carries no interaction to anchor on.
+ */
+export declare function deselect<TKey extends SelectionKey>(state: SelectionState<TKey>, key: TKey): SelectionState<TKey>;
+/**
+ * Flips one key's membership and moves the anchor to it — the plain click. In `single` mode, toggling the
+ * selected key clears the selection and toggling any other key replaces it.
+ */
+export declare function toggle<TKey extends SelectionKey>(state: SelectionState<TKey>, key: TKey): SelectionState<TKey>;
+/**
+ * Adds every given key to the selection, leaving the anchor and any selection OUTSIDE the given keys
+ * untouched — so "select all" on a filtered table keeps rows selected under other filters.
+ *
+ * Inert in `none` and `single` modes: "all" has no meaning on a surface that holds at most one key.
+ */
+export declare function selectAll<TKey extends SelectionKey>(state: SelectionState<TKey>, keys: Iterable<TKey>): SelectionState<TKey>;
+/** Empties the selection and drops the anchor — with nothing selected there is no range to extend from. */
+export declare function clear<TKey extends SelectionKey>(state: SelectionState<TKey>): SelectionState<TKey>;
+/**
+ * Flips the membership of every given key. Keys selected OUTSIDE the given set are left alone, so
+ * inverting a filtered page inverts exactly that page.
+ *
+ * Inert in `none` and `single` modes.
+ */
+export declare function invert<TKey extends SelectionKey>(state: SelectionState<TKey>, keys: Iterable<TKey>): SelectionState<TKey>;
+/**
+ * The header-checkbox click: selects every given key unless all of them are already selected, in which
+ * case it deselects them. Selections outside the given keys survive either way.
+ *
+ * Inert in `none` and `single` modes, and on an empty key list.
+ */
+export declare function toggleAll<TKey extends SelectionKey>(state: SelectionState<TKey>, keys: Iterable<TKey>): SelectionState<TKey>;
+/**
+ * The tri-state a header checkbox renders for the given keys: `'all'` when every one is selected,
+ * `'none'` when none is, `'some'` otherwise. An empty key list is `'none'` — there is nothing to check.
+ */
+export declare function selectionStatus<TKey extends SelectionKey>(state: SelectionState<TKey>, keys: Iterable<TKey>): SelectionStatus;
+/**
+ * Selects the contiguous run between two keys — the shift-click. `orderedKeys` is the surface's CURRENT
+ * visual order (already sorted and filtered), which is what makes the range mean what the user sees.
+ *
+ * The anchor is left AT `anchor`, not moved to `target`: successive shift-clicks must all measure from the
+ * same fixed end, so dragging a range back and forth grows and shrinks it instead of walking it away.
+ *
+ * Degenerate cases, all documented rather than thrown: `none` mode is inert; `single` mode collapses to
+ * {@link select} on `target`; a `target` missing from `orderedKeys` is inert; an `anchor` missing from
+ * `orderedKeys` falls back to selecting `target` alone.
+ */
+export declare function selectRange<TKey extends SelectionKey>(state: SelectionState<TKey>, anchor: TKey, target: TKey, orderedKeys: ReadonlyArray<TKey>, options?: SelectRangeOptions): SelectionState<TKey>;
+/**
+ * The shift-click as a surface actually calls it: extends from the state's own anchor to `target`. With no
+ * anchor yet (nothing has been plainly clicked), the target itself becomes the anchor and the range is the
+ * single row — which is exactly what a shift-click on a fresh list should do.
+ */
+export declare function extendSelection<TKey extends SelectionKey>(state: SelectionState<TKey>, target: TKey, orderedKeys: ReadonlyArray<TKey>, options?: SelectRangeOptions): SelectionState<TKey>;

package/dist/foundation/selection/models/Sort.d.ts

@@ -0,0 +1,69 @@
+import { FieldAccessors, LocaleOptions } from './Field';
+/** Defines the ordering applied to a sorted field. */
+export declare const SortDirection: {
+    /** Refers to ascending order — smallest/earliest/`false` first. */
+    readonly Asc: "asc";
+    /** Refers to descending order — largest/latest/`true` first. */
+    readonly Desc: "desc";
+};
+export type SortDirection = (typeof SortDirection)[keyof typeof SortDirection];
+/** Represents one field of an ordering. A list of these is the whole sort state; array order is precedence. */
+export interface SortDescriptor<TField extends string = string> {
+    /** The field name, resolved through the accessor registry or read as a plain property. */
+    readonly field: TField;
+    /** The direction applied to this field. */
+    readonly direction: SortDirection;
+}
+/** Options accepted by {@link toggleSort}. */
+export interface ToggleSortOptions {
+    /**
+     * The multi-field behaviour. `false` (default) keeps at most one sorted field — a click on a new field
+     * replaces the ordering. `true` appends the new field after the existing ones, so precedence follows
+     * click order (the shift-click-a-second-header behaviour).
+     */
+    isMulti?: boolean;
+}
+/**
+ * Compares two non-nullish values with the SDK's default ordering, direction-agnostic (callers negate).
+ * Handles, in order: numbers, bigints, booleans (`false` before `true`), the `Temporal` types, native
+ * `Date`, strings, and finally anything else via its text form.
+ *
+ * Nullish handling is deliberately NOT here — {@link applySort} applies it outside the direction flip so
+ * absent values sort last in both directions. Calling this with a nullish value falls through to the text
+ * comparison, which is not the documented ordering.
+ */
+export declare function compareValues(a: unknown, b: unknown, options?: LocaleOptions): number;
+/** The direction currently applied to a field, or `null` when the field is unsorted. */
+export declare function sortDirectionFor<TField extends string>(descriptors: ReadonlyArray<SortDescriptor<TField>>, field: TField): SortDirection | null;
+/**
+ * The 0-based precedence of a field in the ordering, or `-1` when unsorted — the number a multi-sort header
+ * renders as its "1 / 2 / 3" badge (add one for display).
+ */
+export declare function sortIndexFor<TField extends string>(descriptors: ReadonlyArray<SortDescriptor<TField>>, field: TField): number;
+/**
+ * Advances one field through the `asc → desc → none` cycle and returns the next descriptor list.
+ *
+ * Single-field (default): the result is `[{ field, 'asc' }]`, `[{ field, 'desc' }]`, or `[]`. Clicking a
+ * different field restarts that field's cycle at `asc` and drops the previous one.
+ *
+ * Multi-field (`{ isMulti: true }`): the field keeps its position while cycling `asc → desc`, and the third
+ * click removes it, leaving the other fields' precedence intact. A field not yet in the list is appended.
+ */
+export declare function toggleSort<TField extends string>(descriptors: ReadonlyArray<SortDescriptor<TField>>, field: TField, options?: ToggleSortOptions): ReadonlyArray<SortDescriptor<TField>>;
+/**
+ * Builds the comparator an ordering describes — exported so a virtualised or server-side surface can feed
+ * it to its own machinery instead of materialising a sorted array.
+ *
+ * Fields are consulted in array order and the first non-zero result wins. Within each field: absent values
+ * (`null` / `undefined` / `NaN`) sort last regardless of direction, then {@link compareValues} decides and
+ * the direction is applied to that result only.
+ */
+export declare function sortComparator<T, TField extends string = string>(descriptors: ReadonlyArray<SortDescriptor<TField>>, accessors?: FieldAccessors<T, TField>, options?: LocaleOptions): (a: T, b: T) => number;
+/**
+ * Sorts a list by an ordering, without mutating the input. Returns the input array itself when there is
+ * nothing to order, so an unsorted render costs no copy.
+ *
+ * The sort is stable (`Array.prototype.sort` has been stable since ES2019), which is what makes multi-field
+ * ordering composable: equal rows keep the order the previous field — or the server — put them in.
+ */
+export declare function applySort<T, TField extends string = string>(items: ReadonlyArray<T>, descriptors: ReadonlyArray<SortDescriptor<TField>>, accessors?: FieldAccessors<T, TField>, options?: LocaleOptions): ReadonlyArray<T>;

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

@@ -1,25 +1,9 @@
+import { ShareSendResult } from './models/ShareSendResult';
+import { ShareFailure } from './models/ShareFailure';
 import { ShareData } from './ShareData';
-/**
- * The outcome of a share attempt.
- *
- * - `shared` — the native sheet completed. The platform does not report *which* target was picked, nor whether
- *   the receiving app did anything with the payload, so this is "handed off", not "delivered".
- * - `dismissed` — the user closed the sheet. A decision, not an error.
- * - `unsupported` — no Web Share here: desktop browser, SSR, or a files payload the platform refused.
- * - `failed` — anything else, carrying the normalized `Error`.
- */
-export type ShareResult = {
-    readonly status: 'shared';
-} | {
-    readonly status: 'dismissed';
-} | {
-    readonly status: 'unsupported';
-} | {
-    readonly status: 'failed';
-    readonly error: Error;
-};
-/** The `status` discriminant of a {@link ShareResult} — for a consumer's own switch or status→copy map. */
-export type ShareStatus = ShareResult['status'];
+export type { ShareFailure } from './models/ShareFailure';
+export type { ShareSendResult } from './models/ShareSendResult';
+export type ShareStatus = 'shared' | ShareFailure['status'];
 /** Tunes a share attempt. */
 export interface ShareOptions {
     /**
@@ -35,11 +19,11 @@ export interface ShareOptions {
  */
 export declare function reportShareError(onError: ShareOptions['onError'], error: Error): void;
 /**
- * Opens the native share sheet for `data` and resolves to a {@link ShareResult}.
+ * Opens the native share sheet for `data` and resolves to a {@link ShareSendResult}.
  *
  * Call it from a user gesture: browsers require transient activation for the sheet, and without one the platform
  * rejects — which surfaces as `failed`, not `unsupported`, since the API was in fact present.
  *
  * Never throws, never rejects.
  */
-export declare function share(data: ShareData, options?: ShareOptions): Promise<ShareResult>;
+export declare function share(data: ShareData, options?: ShareOptions): Promise<ShareSendResult>;

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

@@ -10,7 +10,7 @@ export interface ShareData {
     /** URL of the shared content — the member most targets render, and the one the clipboard fallback prefers. */
     readonly url?: string;
     /** Files to share. Support is far narrower than the rest of the payload — always gate on `canShare`. */
-    readonly files?: readonly File[];
+    readonly files?: ReadonlyArray<File>;
 }
 /**
  * The mutable, defined-keys-only object handed to `navigator.share` / `navigator.canShare`. Exported for the

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

@@ -0,0 +1,7 @@
+/** Closed failure vocabulary for ShareFailure. */
+export declare const ShareFailureCode: {
+    readonly Dismissed: "dismissed";
+    readonly Unsupported: "unsupported";
+    readonly Failed: "failed";
+};
+export type ShareFailureCode = (typeof ShareFailureCode)[keyof typeof ShareFailureCode];

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

@@ -1,11 +1,9 @@
-import { ShareOptions, ShareResult } from './Share';
+import { ShareSendOrCopyResult } from './models/ShareSendOrCopyResult';
+import { ShareOptions, ShareFailure } 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'];
+export type { ShareSendOrCopyResult } from './models/ShareSendOrCopyResult';
+/** The `status` discriminant of a {@link ShareSendOrCopyResult}. */
+export type ShareOrCopyStatus = 'shared' | 'copied' | ShareFailure['status'];
 /** Tunes a share-with-fallback attempt. */
 export interface ShareOrCopyOptions extends ShareOptions {
     /**
@@ -24,4 +22,4 @@ export interface ShareOrCopyOptions extends ShareOptions {
  *
  * Never throws, never rejects.
  */
-export declare function shareOrCopy(data: ShareData, options?: ShareOrCopyOptions): Promise<ShareOrCopyResult>;
+export declare function shareOrCopy(data: ShareData, options?: ShareOrCopyOptions): Promise<ShareSendOrCopyResult>;

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

@@ -1,23 +1,30 @@
 import { ComputedRef, MaybeRefOrGetter, ShallowRef } from 'vue';
-import { ShareResult } from './Share';
+import { ShareSendResult } from './Share';
 import { ShareData } from './ShareData';
-import { ShareOrCopyOptions, ShareOrCopyResult } from './ShareOrCopy';
+import { ShareOrCopyOptions, ShareSendOrCopyResult } from './ShareOrCopy';
 /** Where a `useShare` instance sits in its cycle: idle, or awaiting the native sheet / clipboard write. */
-export type ShareState = 'idle' | 'sharing';
+export declare const ShareState: {
+    /** Nothing in flight — the resting state, and the one every attempt returns to. */
+    readonly Idle: "idle";
+    /** The native sheet is open, or the clipboard fallback is mid-write. */
+    readonly Sharing: "sharing";
+};
+/** Where a `useShare` instance sits in its cycle: idle, or awaiting the native sheet / clipboard write. */
+export type ShareState = (typeof ShareState)[keyof typeof ShareState];
 /** 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. */
+    /** Convenience for `state === ShareState.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>>;
+    readonly result: Readonly<ShallowRef<ShareSendResult | ShareSendOrCopyResult | 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>;
+    readonly share: (data: ShareData) => Promise<ShareSendResult>;
     /** Opens the native sheet, degrading to a clipboard copy when unsupported. Resolves to the result; never throws. */
-    readonly shareOrCopy: (data: ShareData) => Promise<ShareOrCopyResult>;
+    readonly shareOrCopy: (data: ShareData) => Promise<ShareSendOrCopyResult>;
     /** Clears `result` and returns `state` to `idle`. */
     readonly reset: () => void;
 }

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

@@ -1,5 +1,6 @@
 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 { share, type ShareFailure, type ShareSendResult, type ShareStatus, type ShareOptions } from './Share';
+export { shareOrCopy, type ShareSendOrCopyResult, type ShareOrCopyStatus, type ShareOrCopyOptions, } from './ShareOrCopy';
 export { useShare, type ShareControls, type ShareState } from './UseShare';
+export { ShareFailureCode } from './ShareFailureCode';

package/dist/foundation/share/index.js

@@ -1,6 +1,6 @@
-import { t as toError } from "../../chunks/ToError-CyTBsmLO.js";
-import { i as isAbortError } from "../../chunks/ErrorRecognizers-oTklha6D.js";
-import { shallowRef, computed, toValue } from "vue";
+import { t as toError } from "../../chunks/ToError-vXncXe19.js";
+import { i as isAbortError } from "../../chunks/ErrorRecognizers-DO2SHD6N.js";
+import { shallowRef, onScopeDispose, computed, toValue } from "vue";
 function toNativeSharePayload(data) {
   const payload = {};
   if (data.title !== void 0) payload.title = data.title;
@@ -40,68 +40,93 @@ function reportShareError(onError, error) {
   }
 }
 async function share(data, options) {
-  if (!canShare(data)) return { status: "unsupported" };
+  if (!canShare(data)) return { ok: false, failure: { status: "unsupported" } };
   try {
     await navigator.share(toNativeSharePayload(data));
-    return { status: "shared" };
+    return { ok: true, value: void 0 };
   } catch (error) {
-    if (isAbortError(error)) return { status: "dismissed" };
+    if (isAbortError(error)) return { ok: false, failure: { status: "dismissed" } };
     const failure = toError(error);
     reportShareError(options?.onError, failure);
-    return { status: "failed", error: failure };
+    return { ok: false, failure: { status: "failed", error: failure } };
   }
 }
 async function copyToClipboard(text, options) {
   try {
     if (typeof navigator === "undefined" || typeof navigator.clipboard?.writeText !== "function") {
-      return { status: "unsupported" };
+      return { ok: false, failure: { status: "unsupported" } };
     }
     await navigator.clipboard.writeText(text);
-    return { status: "copied" };
+    return { ok: true, value: "copied" };
   } catch (error) {
     const failure = toError(error);
     reportShareError(options?.onError, failure);
-    return { status: "failed", error: failure };
+    return { ok: false, failure: { status: "failed", error: failure } };
   }
 }
 async function shareOrCopy(data, options) {
   const result = await share(data, options);
-  if (result.status !== "unsupported") return result;
+  if (result.ok) return { ok: true, value: "shared" };
+  if (result.failure.status !== "unsupported") return result;
   if (options?.fallbackToCopy === false) return result;
   const text = shareFallbackText(data);
   if (text === void 0) return result;
   return copyToClipboard(text, options);
 }
+const ShareState = {
+  /** Nothing in flight — the resting state, and the one every attempt returns to. */
+  Idle: "idle",
+  /** The native sheet is open, or the clipboard fallback is mid-write. */
+  Sharing: "sharing"
+};
 function useShare(options) {
-  const state = shallowRef("idle");
+  const state = shallowRef(ShareState.Idle);
   const result = shallowRef(null);
+  let latest = 0;
+  let disposed = false;
+  const pending = /* @__PURE__ */ new Set();
+  onScopeDispose(() => {
+    disposed = true;
+    pending.clear();
+  });
   async function run(attempt) {
-    state.value = "sharing";
+    const operation = ++latest;
+    pending.add(operation);
+    if (!disposed) state.value = ShareState.Sharing;
     try {
       const outcome = await attempt();
-      result.value = outcome;
+      if (!disposed && operation === latest) result.value = outcome;
       return outcome;
     } finally {
-      state.value = "idle";
+      pending.delete(operation);
+      if (!disposed) state.value = pending.size > 0 ? ShareState.Sharing : ShareState.Idle;
     }
   }
   const runShare = (data) => run(() => share(data, toValue(options)));
   const runShareOrCopy = (data) => run(() => shareOrCopy(data, toValue(options)));
   const reset = () => {
-    state.value = "idle";
+    latest++;
+    pending.clear();
+    state.value = ShareState.Idle;
     result.value = null;
   };
   return {
     state,
-    sharing: computed(() => state.value === "sharing"),
+    sharing: computed(() => state.value === ShareState.Sharing),
     result,
-    copied: computed(() => result.value?.status === "copied"),
+    copied: computed(() => result.value?.ok === true && result.value.value === "copied"),
     share: runShare,
     shareOrCopy: runShareOrCopy,
     reset
   };
 }
+const ShareFailureCode = {
+  Dismissed: "dismissed",
+  Unsupported: "unsupported",
+  Failed: "failed"
+};
 export {
+  ShareFailureCode,
   canShare,
   share,
   shareFallbackText,

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

@@ -1 +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":";;;AAoDO,SAAS,qBAAqB,MAAqC;AACxE,QAAM,UAA8B,CAAA;AACpC,MAAI,KAAK,UAAU,OAAW,SAAQ,QAAQ,KAAK;AACnD,MAAI,KAAK,SAAS,OAAW,SAAQ,OAAO,KAAK;AACjD,MAAI,KAAK,QAAQ,OAAW,SAAQ,MAAM,KAAK;AAC/C,MAAI,KAAK,UAAU,OAAW,SAAQ,QAAQ,CAAC,GAAG,KAAK,KAAK;AAC5D,SAAO;AACT;AAUO,SAAS,kBAAkB,MAAqC;AACrE,aAAW,aAAa,CAAC,KAAK,KAAK,KAAK,MAAM,KAAK,KAAK,GAAG;AACzD,QAAI,cAAc,UAAa,UAAU,KAAA,MAAW,GAAI,QAAO;AAAA,EACjE;AACA,SAAO;AACT;AC/DA,SAAS,iBAA0B;AACjC,MAAI;AACF,WAAO,OAAO,cAAc,eAAe,OAAO,UAAU,UAAU;AAAA,EACxE,QAAQ;AAEN,WAAO;AAAA,EACT;AACF;AAWO,SAAS,SAAS,MAA2B;AAClD,MAAI,CAAC,eAAA,EAAkB,QAAO;AAC9B,MAAI,MAAM,UAAU,OAAW,QAAO;AAEtC,MAAI;AACF,QAAI,OAAO,UAAU,aAAa,WAAY,QAAO;AACrD,WAAO,UAAU,SAAS,qBAAqB,IAAI,CAAC,MAAM;AAAA,EAC5D,QAAQ;AAEN,WAAO;AAAA,EACT;AACF;ACUO,SAAS,iBAAiB,SAAkC,OAAoB;AACrF,MAAI,YAAY,OAAW;AAC3B,MAAI;AACF,YAAQ,KAAK;AAAA,EACf,QAAQ;AAAA,EAGR;AACF;AAUA,eAAsB,MAAM,MAAiB,SAA8C;AACzF,MAAI,CAAC,SAAS,IAAI,EAAG,QAAO,EAAE,QAAQ,cAAA;AAEtC,MAAI;AACF,UAAM,UAAU,MAAM,qBAAqB,IAAI,CAAC;AAChD,WAAO,EAAE,QAAQ,SAAA;AAAA,EACnB,SAAS,OAAO;AAEd,QAAI,aAAa,KAAK,EAAG,QAAO,EAAE,QAAQ,YAAA;AAE1C,UAAM,UAAU,QAAQ,KAAK;AAC7B,qBAAiB,SAAS,SAAS,OAAO;AAC1C,WAAO,EAAE,QAAQ,UAAU,OAAO,QAAA;AAAA,EACpC;AACF;AC5CA,eAAe,gBAAgB,MAAc,SAAoD;AAC/F,MAAI;AACF,QAAI,OAAO,cAAc,eAAe,OAAO,UAAU,WAAW,cAAc,YAAY;AAC5F,aAAO,EAAE,QAAQ,cAAA;AAAA,IACnB;AAEA,UAAM,UAAU,UAAU,UAAU,IAAI;AACxC,WAAO,EAAE,QAAQ,SAAA;AAAA,EACnB,SAAS,OAAO;AAGd,UAAM,UAAU,QAAQ,KAAK;AAC7B,qBAAiB,SAAS,SAAS,OAAO;AAC1C,WAAO,EAAE,QAAQ,UAAU,OAAO,QAAA;AAAA,EACpC;AACF;AAYA,eAAsB,YAAY,MAAiB,SAA0D;AAC3G,QAAM,SAAS,MAAM,MAAM,MAAM,OAAO;AACxC,MAAI,OAAO,WAAW,cAAe,QAAO;AAC5C,MAAI,SAAS,mBAAmB,MAAO,QAAO;AAE9C,QAAM,OAAO,kBAAkB,IAAI;AACnC,MAAI,SAAS,OAAW,QAAO;AAE/B,SAAO,gBAAgB,MAAM,OAAO;AACtC;ACpBO,SAAS,SAAS,SAA2E;AAClG,QAAM,QAAQ,WAAuB,MAAM;AAC3C,QAAM,SAAS,WAAqC,IAAI;AAGxD,iBAAe,IAAuC,SAAmD;AACvG,UAAM,QAAQ;AACd,QAAI;AACF,YAAM,UAAU,MAAM,QAAA;AACtB,aAAO,QAAQ;AACf,aAAO;AAAA,IACT,UAAA;AACE,YAAM,QAAQ;AAAA,IAChB;AAAA,EACF;AAEA,QAAM,WAAW,CAAC,SAA0C,IAAI,MAAM,MAAM,MAAM,QAAQ,OAAO,CAAC,CAAC;AAEnG,QAAM,iBAAiB,CAAC,SACtB,IAAI,MAAM,YAAY,MAAM,QAAQ,OAAO,CAAC,CAAC;AAE/C,QAAM,QAAQ,MAAY;AACxB,UAAM,QAAQ;AACd,WAAO,QAAQ;AAAA,EACjB;AAEA,SAAO;AAAA,IACL;AAAA,IACA,SAAS,SAAS,MAAM,MAAM,UAAU,SAAS;AAAA,IACjD;AAAA,IACA,QAAQ,SAAS,MAAM,OAAO,OAAO,WAAW,QAAQ;AAAA,IACxD,OAAO;AAAA,IACP,aAAa;AAAA,IACb;AAAA,EAAA;AAEJ;"}
+{"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","../../../src/foundation/share/ShareFailureCode.ts"],"sourcesContent":["/**\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?: ReadonlyArray<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","import { toNativeSharePayload, type ShareData } from './ShareData';\n\n/** Whether `navigator.share` exists. 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","import type { ShareSendResult } from './models/ShareSendResult';\nimport type { ShareFailure } from './models/ShareFailure';\n\nimport { isAbortError, toError } from '../errors';\n\nimport { canShare } from './CanShare';\nimport { toNativeSharePayload, type ShareData } from './ShareData';\nexport type { ShareFailure } from './models/ShareFailure';\nexport type { ShareSendResult } from './models/ShareSendResult';\nexport type ShareStatus = 'shared' | ShareFailure['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 ShareSendResult}.\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<ShareSendResult> {\n  if (!canShare(data)) return { ok: false, failure: { status: 'unsupported' } };\n\n  try {\n    await navigator.share(toNativeSharePayload(data));\n    return { ok: true, value: undefined };\n  } catch (error) {\n    // The user's own decision ends the flow quietly — no `onError`, no fallback downstream.\n    if (isAbortError(error)) return { ok: false, failure: { status: 'dismissed' } };\n\n    const failure = toError(error);\n    reportShareError(options?.onError, failure);\n    return { ok: false, failure: { status: 'failed', error: failure } };\n  }\n}\n","import type { ShareSendOrCopyResult } from './models/ShareSendOrCopyResult';\n\nimport { toError } from '../errors';\n\nimport { reportShareError, share, type ShareOptions, type ShareFailure } from './Share';\nimport { shareFallbackText, type ShareData } from './ShareData';\nexport type { ShareSendOrCopyResult } from './models/ShareSendOrCopyResult';\n\n/** The `status` discriminant of a {@link ShareSendOrCopyResult}. */\nexport type ShareOrCopyStatus = 'shared' | 'copied' | ShareFailure['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<ShareSendOrCopyResult> {\n  try {\n    if (typeof navigator === 'undefined' || typeof navigator.clipboard?.writeText !== 'function') {\n      return { ok: false, failure: { status: 'unsupported' } };\n    }\n\n    await navigator.clipboard.writeText(text);\n    return { ok: true, value: '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 { ok: false, failure: { 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<ShareSendOrCopyResult> {\n  const result = await share(data, options);\n  if (result.ok) return { ok: true, value: 'shared' };\n  if (result.failure.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","import {\n  computed,\n  onScopeDispose,\n  shallowRef,\n  toValue,\n  type ComputedRef,\n  type MaybeRefOrGetter,\n  type ShallowRef,\n} from 'vue';\n\nimport { share, type ShareSendResult } from './Share';\nimport type { ShareData } from './ShareData';\nimport { shareOrCopy, type ShareOrCopyOptions, type ShareSendOrCopyResult } from './ShareOrCopy';\n\n/** Where a `useShare` instance sits in its cycle: idle, or awaiting the native sheet / clipboard write. */\nexport const ShareState = {\n  /** Nothing in flight — the resting state, and the one every attempt returns to. */\n  Idle: 'idle',\n\n  /** The native sheet is open, or the clipboard fallback is mid-write. */\n  Sharing: 'sharing',\n} as const;\n\n/** Where a `useShare` instance sits in its cycle: idle, or awaiting the native sheet / clipboard write. */\nexport type ShareState = (typeof ShareState)[keyof typeof ShareState];\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 === ShareState.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<ShareSendResult | ShareSendOrCopyResult | 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<ShareSendResult>;\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<ShareSendOrCopyResult>;\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>(ShareState.Idle);\n  const result = shallowRef<ShareSendResult | ShareSendOrCopyResult | null>(null);\n  let latest = 0;\n  let disposed = false;\n  const pending = new Set<number>();\n  onScopeDispose(() => {\n    disposed = true;\n    pending.clear();\n  });\n\n  /** Runs one attempt, bracketing it with the pending flag and recording the outcome. */\n  async function run<TResult extends ShareSendResult | ShareSendOrCopyResult>(\n    attempt: () => Promise<TResult>,\n  ): Promise<TResult> {\n    const operation = ++latest;\n    pending.add(operation);\n    if (!disposed) state.value = ShareState.Sharing;\n    try {\n      const outcome = await attempt();\n      if (!disposed && operation === latest) result.value = outcome;\n      return outcome;\n    } finally {\n      pending.delete(operation);\n      if (!disposed) state.value = pending.size > 0 ? ShareState.Sharing : ShareState.Idle;\n    }\n  }\n\n  const runShare = (data: ShareData): Promise<ShareSendResult> => run(() => share(data, toValue(options)));\n\n  const runShareOrCopy = (data: ShareData): Promise<ShareSendOrCopyResult> =>\n    run(() => shareOrCopy(data, toValue(options)));\n\n  const reset = (): void => {\n    latest++;\n    pending.clear();\n    state.value = ShareState.Idle;\n    result.value = null;\n  };\n\n  return {\n    state,\n    sharing: computed(() => state.value === ShareState.Sharing),\n    result,\n    copied: computed(() => result.value?.ok === true && result.value.value === 'copied'),\n    share: runShare,\n    shareOrCopy: runShareOrCopy,\n    reset,\n  };\n}\n","/** Closed failure vocabulary for ShareFailure. */\nexport const ShareFailureCode = {\n  Dismissed: 'dismissed',\n  Unsupported: 'unsupported',\n  Failed: 'failed',\n} as const;\n\nexport type ShareFailureCode = (typeof ShareFailureCode)[keyof typeof ShareFailureCode];\n"],"names":[],"mappings":"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"}

package/dist/foundation/share/models/ShareFailure.d.ts

@@ -0,0 +1,10 @@
+import { ShareFailureCode } from '../ShareFailureCode';
+/** Expected reasons the operation could not produce its requested value. */
+export type ShareFailure = {
+    readonly status: typeof ShareFailureCode.Dismissed;
+} | {
+    readonly status: typeof ShareFailureCode.Unsupported;
+} | {
+    readonly status: typeof ShareFailureCode.Failed;
+    readonly error: Error;
+};

package/dist/foundation/share/models/ShareSendOrCopyResult.d.ts

@@ -0,0 +1,4 @@
+import { Result } from '../../results';
+import { ShareFailure } from '../Share';
+/** The completed operation, carrying either its value or its typed failure. */
+export type ShareSendOrCopyResult = Result<'shared' | 'copied', ShareFailure>;

package/dist/foundation/share/models/ShareSendResult.d.ts

@@ -0,0 +1,4 @@
+import { Result } from '../../results';
+import { ShareFailure } from './ShareFailure';
+/** The completed operation, carrying either its value or its typed failure. */
+export type ShareSendResult = Result<void, ShareFailure>;

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

@@ -27,7 +27,7 @@ export interface Chord {
 }
 /** 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. */
+/** Detects an Apple platform (for `mod` → ⌘ and symbol formatting). SSR-safe; `platformHint` forces it in tests. */
 export declare function isApplePlatform(platformHint?: string): boolean;
 /** Options shared by the platform-sensitive chord helpers. */
 export interface ChordPlatformOptions {

package/dist/foundation/shortcuts/hooks/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 | ReadonlyArray<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

@@ -1,3 +1,4 @@
 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';
+export { Key } from '../dom/enums/Key';
+export { useHotkeys, useHotkeyMap, type HotkeyOptions } from './hooks/UseHotkeys';
+export * from './hooks/UseEscape';