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

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/foundation/files/ReadFile.ts","../../../src/foundation/files/DownloadFile.ts"],"sourcesContent":["// Promise wrappers over `FileReader`. The browser API is event-based and easy to get subtly wrong (an `abort`\n// that never settles, an error surfaced as `null`); these settle exactly once and reject with a real `Error`.\n// `readFileAsText` takes an encoding, which is the one thing `Blob.text()` cannot express.\n\n/** Runs one `FileReader` operation as a promise that always settles — resolve on load, reject on error or abort. */\nfunction readWith<T extends string | ArrayBuffer>(\n  blob: Blob,\n  start: (reader: FileReader) => void,\n): Promise<T> {\n  return new Promise<T>((resolve, reject) => {\n    const reader = new FileReader();\n\n    reader.onload = () => resolve(reader.result as T);\n    reader.onerror = () => reject(reader.error ?? new Error('File read failed'));\n    reader.onabort = () => reject(new Error('File read aborted'));\n\n    try {\n      start(reader);\n    } catch (error) {\n      reject(error instanceof Error ? error : new Error(String(error)));\n    }\n  });\n}\n\n/** Reads a blob/file as text. `encoding` defaults to the browser's UTF-8 (pass e.g. `windows-1251` for legacy data). */\nexport function readFileAsText(blob: Blob, encoding?: string): Promise<string> {\n  return readWith<string>(blob, (reader) => reader.readAsText(blob, encoding));\n}\n\n/** Reads a blob/file as a `data:` URL — the form an `<img src>` or a JSON payload can carry inline. */\nexport function readFileAsDataUrl(blob: Blob): Promise<string> {\n  return readWith<string>(blob, (reader) => reader.readAsDataURL(blob));\n}\n\n/** Reads a blob/file as an `ArrayBuffer` — for binary inspection (magic bytes, hashing, parsing). */\nexport function readFileAsArrayBuffer(blob: Blob): Promise<ArrayBuffer> {\n  return readWith<ArrayBuffer>(blob, (reader) => reader.readAsArrayBuffer(blob));\n}\n","// Client-side \"save as\" — the object-URL + synthetic-anchor dance, done once and correctly. The easy leak here is\n// a forgotten `revokeObjectURL`, which pins the whole blob in memory for the page's lifetime; every helper below\n// revokes on the next tick (after the click has been dispatched). SSR-safe: with no `document`, each is a no-op,\n// since a download is only ever user-initiated.\n\nimport { safeFileName } from './FileName';\n\n/** Whether a DOM is present to drive the download (false during SSR / node). */\nfunction hasDocument(): boolean {\n  return typeof document !== 'undefined';\n}\n\n/**\n * Triggers a browser download of `blob` under `filename` (sanitized via {@link safeFileName}). Creates an object\n * URL, clicks a detached anchor, then revokes the URL on the next tick so the blob is released. No-ops when\n * there is no `document`. Returns whether the download was dispatched.\n */\nexport function downloadBlob(blob: Blob, filename: string): boolean {\n  if (!hasDocument()) return false;\n\n  const url = URL.createObjectURL(blob);\n  const anchor = document.createElement('a');\n  anchor.href = url;\n  anchor.download = safeFileName(filename);\n  // Firefox requires the anchor to be in the document for a programmatic click to register.\n  anchor.style.display = 'none';\n  document.body.appendChild(anchor);\n  anchor.click();\n  anchor.remove();\n\n  // Revoke after the click has been dispatched — revoking synchronously can cancel the download in some browsers.\n  setTimeout(() => URL.revokeObjectURL(url), 0);\n  return true;\n}\n\n/** Downloads a string as a file. `mimeType` defaults to UTF-8 plain text. */\nexport function downloadText(text: string, filename: string, mimeType = 'text/plain;charset=utf-8'): boolean {\n  return downloadBlob(new Blob([text], { type: mimeType }), filename);\n}\n\n/** Downloads a value as pretty-printed JSON (`space` defaults to 2). Throws on a value `JSON.stringify` rejects. */\nexport function downloadJson(value: unknown, filename: string, space: number = 2): boolean {\n  return downloadText(JSON.stringify(value, null, space), filename, 'application/json;charset=utf-8');\n}\n"],"names":[],"mappings":";;;AAKA,SAAS,SACP,MACA,OACY;AACZ,SAAO,IAAI,QAAW,CAAC,SAAS,WAAW;AACzC,UAAM,SAAS,IAAI,WAAA;AAEnB,WAAO,SAAS,MAAM,QAAQ,OAAO,MAAW;AAChD,WAAO,UAAU,MAAM,OAAO,OAAO,SAAS,IAAI,MAAM,kBAAkB,CAAC;AAC3E,WAAO,UAAU,MAAM,OAAO,IAAI,MAAM,mBAAmB,CAAC;AAE5D,QAAI;AACF,YAAM,MAAM;AAAA,IACd,SAAS,OAAO;AACd,aAAO,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC,CAAC;AAAA,IAClE;AAAA,EACF,CAAC;AACH;AAGO,SAAS,eAAe,MAAY,UAAoC;AAC7E,SAAO,SAAiB,MAAM,CAAC,WAAW,OAAO,WAAW,MAAM,QAAQ,CAAC;AAC7E;AAGO,SAAS,kBAAkB,MAA6B;AAC7D,SAAO,SAAiB,MAAM,CAAC,WAAW,OAAO,cAAc,IAAI,CAAC;AACtE;AAGO,SAAS,sBAAsB,MAAkC;AACtE,SAAO,SAAsB,MAAM,CAAC,WAAW,OAAO,kBAAkB,IAAI,CAAC;AAC/E;AC7BA,SAAS,cAAuB;AAC9B,SAAO,OAAO,aAAa;AAC7B;AAOO,SAAS,aAAa,MAAY,UAA2B;AAClE,MAAI,CAAC,YAAA,EAAe,QAAO;AAE3B,QAAM,MAAM,IAAI,gBAAgB,IAAI;AACpC,QAAM,SAAS,SAAS,cAAc,GAAG;AACzC,SAAO,OAAO;AACd,SAAO,WAAW,aAAa,QAAQ;AAEvC,SAAO,MAAM,UAAU;AACvB,WAAS,KAAK,YAAY,MAAM;AAChC,SAAO,MAAA;AACP,SAAO,OAAA;AAGP,aAAW,MAAM,IAAI,gBAAgB,GAAG,GAAG,CAAC;AAC5C,SAAO;AACT;AAGO,SAAS,aAAa,MAAc,UAAkB,WAAW,4BAAqC;AAC3G,SAAO,aAAa,IAAI,KAAK,CAAC,IAAI,GAAG,EAAE,MAAM,UAAU,GAAG,QAAQ;AACpE;AAGO,SAAS,aAAa,OAAgB,UAAkB,QAAgB,GAAY;AACzF,SAAO,aAAa,KAAK,UAAU,OAAO,MAAM,KAAK,GAAG,UAAU,gCAAgC;AACpG;"}
+{"version":3,"file":"index.js","sources":["../../../src/foundation/files/ReadFile.ts","../../../src/foundation/files/DownloadFile.ts"],"sourcesContent":["// Promise wrappers over `FileReader`. The browser API is event-based and easy to get subtly wrong (an `abort`\n// that never settles, an error surfaced as `null`); these settle exactly once and reject with a real `Error`.\n// `readFileAsText` takes an encoding, which is the one thing `Blob.text()` cannot express.\n\n/** Runs one `FileReader` operation as a promise that always settles — resolve on load, reject on error or abort. */\nfunction readWith<T extends string | ArrayBuffer>(blob: Blob, start: (reader: FileReader) => void): Promise<T> {\n  return new Promise<T>((resolve, reject) => {\n    const reader = new FileReader();\n\n    reader.onload = () => resolve(reader.result as T);\n    reader.onerror = () => reject(reader.error ?? new Error('File read failed'));\n    reader.onabort = () => reject(new Error('File read aborted'));\n\n    try {\n      start(reader);\n    } catch (error) {\n      reject(error instanceof Error ? error : new Error(String(error)));\n    }\n  });\n}\n\n/** Reads a blob/file as text. `encoding` defaults to the browser's UTF-8 (pass e.g. `windows-1251` for legacy data). */\nexport function readFileAsText(blob: Blob, encoding?: string): Promise<string> {\n  return readWith<string>(blob, (reader) => reader.readAsText(blob, encoding));\n}\n\n/** Reads a blob/file as a `data:` URL — the form an `<img src>` or a JSON payload can carry inline. */\nexport function readFileAsDataUrl(blob: Blob): Promise<string> {\n  return readWith<string>(blob, (reader) => reader.readAsDataURL(blob));\n}\n\n/** Reads a blob/file as an `ArrayBuffer` — for binary inspection (magic bytes, hashing, parsing). */\nexport function readFileAsArrayBuffer(blob: Blob): Promise<ArrayBuffer> {\n  return readWith<ArrayBuffer>(blob, (reader) => reader.readAsArrayBuffer(blob));\n}\n","// Client-side \"save as\" — the object-URL + synthetic-anchor dance, done once and correctly. The easy leak here is\n// a forgotten `revokeObjectURL`, which pins the whole blob in memory for the page's lifetime; every helper below\n// revokes on the next tick (after the click has been dispatched). SSR-safe: with no `document`, each is a no-op,\n// since a download is only ever user-initiated.\n\nimport { safeFileName } from './FileName';\n\n/** Whether a DOM is present to drive the download (false during SSR / node). */\nfunction hasDocument(): boolean {\n  return typeof document !== 'undefined';\n}\n\n/**\n * Triggers a browser download of `blob` under `filename` (sanitized via {@link safeFileName}). Creates an object\n * URL, clicks a detached anchor, then revokes the URL on the next tick so the blob is released. No-ops when\n * there is no `document`. Returns whether the download was dispatched.\n */\nexport function downloadBlob(blob: Blob, filename: string): boolean {\n  if (!hasDocument()) return false;\n\n  const url = URL.createObjectURL(blob);\n  const anchor = document.createElement('a');\n  anchor.href = url;\n  anchor.download = safeFileName(filename);\n  // Firefox requires the anchor to be in the document for a programmatic click to register.\n  anchor.style.display = 'none';\n  document.body.appendChild(anchor);\n  anchor.click();\n  anchor.remove();\n\n  // Revoke after the click has been dispatched — revoking synchronously can cancel the download in some browsers.\n  setTimeout(() => URL.revokeObjectURL(url), 0);\n  return true;\n}\n\n/** Downloads a string as a file. `mimeType` defaults to UTF-8 plain text. */\nexport function downloadText(text: string, filename: string, mimeType = 'text/plain;charset=utf-8'): boolean {\n  return downloadBlob(new Blob([text], { type: mimeType }), filename);\n}\n\n/** Downloads a value as pretty-printed JSON (`space` defaults to 2). Throws on a value `JSON.stringify` rejects. */\nexport function downloadJson(value: unknown, filename: string, space: number = 2): boolean {\n  return downloadText(JSON.stringify(value, null, space), filename, 'application/json;charset=utf-8');\n}\n"],"names":[],"mappings":";;;AAKA,SAAS,SAAyC,MAAY,OAAiD;AAC7G,SAAO,IAAI,QAAW,CAAC,SAAS,WAAW;AACzC,UAAM,SAAS,IAAI,WAAA;AAEnB,WAAO,SAAS,MAAM,QAAQ,OAAO,MAAW;AAChD,WAAO,UAAU,MAAM,OAAO,OAAO,SAAS,IAAI,MAAM,kBAAkB,CAAC;AAC3E,WAAO,UAAU,MAAM,OAAO,IAAI,MAAM,mBAAmB,CAAC;AAE5D,QAAI;AACF,YAAM,MAAM;AAAA,IACd,SAAS,OAAO;AACd,aAAO,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC,CAAC;AAAA,IAClE;AAAA,EACF,CAAC;AACH;AAGO,SAAS,eAAe,MAAY,UAAoC;AAC7E,SAAO,SAAiB,MAAM,CAAC,WAAW,OAAO,WAAW,MAAM,QAAQ,CAAC;AAC7E;AAGO,SAAS,kBAAkB,MAA6B;AAC7D,SAAO,SAAiB,MAAM,CAAC,WAAW,OAAO,cAAc,IAAI,CAAC;AACtE;AAGO,SAAS,sBAAsB,MAAkC;AACtE,SAAO,SAAsB,MAAM,CAAC,WAAW,OAAO,kBAAkB,IAAI,CAAC;AAC/E;AC1BA,SAAS,cAAuB;AAC9B,SAAO,OAAO,aAAa;AAC7B;AAOO,SAAS,aAAa,MAAY,UAA2B;AAClE,MAAI,CAAC,YAAA,EAAe,QAAO;AAE3B,QAAM,MAAM,IAAI,gBAAgB,IAAI;AACpC,QAAM,SAAS,SAAS,cAAc,GAAG;AACzC,SAAO,OAAO;AACd,SAAO,WAAW,aAAa,QAAQ;AAEvC,SAAO,MAAM,UAAU;AACvB,WAAS,KAAK,YAAY,MAAM;AAChC,SAAO,MAAA;AACP,SAAO,OAAA;AAGP,aAAW,MAAM,IAAI,gBAAgB,GAAG,GAAG,CAAC;AAC5C,SAAO;AACT;AAGO,SAAS,aAAa,MAAc,UAAkB,WAAW,4BAAqC;AAC3G,SAAO,aAAa,IAAI,KAAK,CAAC,IAAI,GAAG,EAAE,MAAM,UAAU,GAAG,QAAQ;AACpE;AAGO,SAAS,aAAa,OAAgB,UAAkB,QAAgB,GAAY;AACzF,SAAO,aAAa,KAAK,UAAU,OAAO,MAAM,KAAK,GAAG,UAAU,gCAAgC;AACpG;"}

package/dist/foundation/formatters/Text.d.ts

@@ -0,0 +1,52 @@
+/** Tunes truncation. */
+export interface TruncateOptions {
+    /** The overflow indicator appended when the text is cut. Defaults to `…`. */
+    readonly ellipsis?: string;
+    /** Cut back to the last word boundary so a word is never split mid-way. Defaults to `false`. */
+    readonly wordBoundary?: boolean;
+}
+/**
+ * Truncates `text` to at most `maxLength` characters *including* the ellipsis. Returns the text unchanged when it
+ * already fits. With `wordBoundary`, trims back to the last space before the cut so no word is split.
+ */
+export declare function truncate(text: string, maxLength: number, options?: TruncateOptions): string;
+/** Upper-cases the first character, leaving the rest untouched (`"hi there"` → `"Hi there"`). */
+export declare function capitalize(text: string): string;
+/** Upper-cases the first letter of each whitespace-separated word (rest of each word lowercased). */
+export declare function titleCase(text: string): string;
+/** Tunes slug generation. */
+export interface SlugifyOptions {
+    /** The literal word separator; empty joins words without a separator. Defaults to `-`. */
+    readonly separator?: string;
+}
+/**
+ * Builds a URL-safe slug: strips diacritics (NFKD normalize + drop combining marks), lower-cases, replaces every
+ * interior run of non-alphanumeric characters with the literal separator, and removes edge punctuation.
+ * `"Héllo, World!"` → `"hello-world"`.
+ */
+export declare function slugify(text: string, options?: SlugifyOptions): string;
+/** Tunes initials extraction. */
+export interface InitialsOptions {
+    /** Maximum number of initials to take. Defaults to `2`. */
+    readonly max?: number;
+}
+/**
+ * Extracts up-to-`max` upper-cased initials from a name — the first letter of the first and last significant
+ * words. `"John Ronald Reuel Tolkien"` → `"JT"`. Returns `""` for a blank name.
+ */
+export declare function initials(name: string, options?: InitialsOptions): string;
+/** Tunes masking. */
+export interface MaskOptions {
+    /** Number of characters left visible. Defaults to `4`; invalid counts mask every character. */
+    readonly visible?: number;
+    /** The mask character. Defaults to `•`. */
+    readonly mask?: string;
+    /** Which end stays visible — `end` shows the suffix, `start` the prefix. Defaults to `end`. */
+    readonly side?: 'start' | 'end';
+}
+/**
+ * Masks all but the last (or first) `visible` characters — for rendering partial secrets / PII (`"4242…4242"` →
+ * `"••••••••••••4242"`). When the text is no longer than `visible`, every character is masked.
+ * Nonfinite, fractional and negative visibility counts also mask every character.
+ */
+export declare function maskString(text: string, options?: MaskOptions): string;

package/dist/foundation/formatters/index.js

@@ -0,0 +1,102 @@
+import { f } from "../../chunks/Bytes-CzQrdbN4.js";
+const MsPer = { d: 864e5, h: 36e5, m: 6e4, s: 1e3 };
+function formatDuration(milliseconds, options) {
+  if (!Number.isFinite(milliseconds)) {
+    throw new RangeError(`formatDuration: expected a finite number, got ${milliseconds}`);
+  }
+  const maxUnits = Math.max(1, options?.units ?? 2);
+  const sign = milliseconds < 0 ? "-" : "";
+  let remaining = Math.abs(milliseconds);
+  const segments = [];
+  for (const [unit, size] of Object.entries(MsPer)) {
+    const amount = Math.floor(remaining / size);
+    if (amount > 0) {
+      segments.push(`${amount}${unit}`);
+      remaining -= amount * size;
+    }
+  }
+  const millis = Math.floor(remaining);
+  if ((segments.length === 0 || options?.ms === true) && millis > 0) segments.push(`${millis}ms`);
+  if (segments.length === 0) return "0s";
+  return `${sign}${segments.slice(0, maxUnits).join(" ")}`;
+}
+function truncate(text, maxLength, options) {
+  if (maxLength < 0) throw new RangeError(`truncate: maxLength must be ≥ 0, got ${maxLength}`);
+  if (text.length <= maxLength) return text;
+  const ellipsis = options?.ellipsis ?? "…";
+  if (maxLength <= ellipsis.length) return ellipsis.slice(0, maxLength);
+  let end = maxLength - ellipsis.length;
+  let head = text.slice(0, end);
+  if (options?.wordBoundary === true) {
+    const lastSpace = head.lastIndexOf(" ");
+    if (lastSpace > 0) {
+      end = lastSpace;
+      head = text.slice(0, end);
+    }
+  }
+  return head.trimEnd() + ellipsis;
+}
+function capitalize(text) {
+  return text.length === 0 ? text : text.charAt(0).toUpperCase() + text.slice(1);
+}
+function titleCase(text) {
+  return text.split(/(\s+)/).map(
+    (part) => /\s/.test(part) || part.length === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()
+  ).join("");
+}
+function slugify(text, options) {
+  const separator = options?.separator ?? "-";
+  return text.normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, "").replace(/[^a-z0-9]+/g, () => separator);
+}
+function initials(name, options) {
+  const max = Math.max(1, options?.max ?? 2);
+  const words = name.trim().split(/\s+/).filter((word) => word.length > 0);
+  if (words.length === 0) return "";
+  const last = words[words.length - 1];
+  const picked = words.length <= max ? words : [...words.slice(0, max - 1), last];
+  return picked.slice(0, max).map((word) => word.charAt(0).toUpperCase()).join("");
+}
+function maskString(text, options) {
+  const requestedVisible = options?.visible ?? 4;
+  const visible = Number.isInteger(requestedVisible) && requestedVisible >= 0 ? requestedVisible : 0;
+  const maskChar = options?.mask ?? "•";
+  const side = options?.side ?? "end";
+  if (text.length <= visible) return maskChar.repeat(text.length);
+  const masked = maskChar.repeat(text.length - visible);
+  return side === "start" ? text.slice(0, visible) + masked : masked + text.slice(text.length - visible);
+}
+function pluralize(count, singular, plural) {
+  return Math.abs(count) === 1 ? singular : plural ?? `${singular}s`;
+}
+function ordinalSuffix(value) {
+  const abs = Math.abs(Math.trunc(value));
+  const lastTwo = abs % 100;
+  if (lastTwo >= 11 && lastTwo <= 13) return "th";
+  switch (abs % 10) {
+    case 1:
+      return "st";
+    case 2:
+      return "nd";
+    case 3:
+      return "rd";
+    default:
+      return "th";
+  }
+}
+function ordinal(value) {
+  return `${Math.trunc(value)}${ordinalSuffix(value)}`;
+}
+export {
+  capitalize,
+  f as formatBytes,
+  formatDuration,
+  initials,
+  maskString,
+  ordinal,
+  ordinalSuffix,
+  pluralize,
+  slugify,
+  titleCase,
+  truncate
+};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/foundation/formatters/Duration.ts","../../../src/foundation/formatters/Text.ts","../../../src/foundation/formatters/Count.ts"],"sourcesContent":["// Duration humanizing — compact elapsed-time rendering `Intl` doesn't cover. `formatDuration(200_000)` → `3m 20s`.\n// Shows the N most-significant non-zero segments (default 2) across d/h/m/s(/ms), sign-preserving. Locale-free:\n// for a localized \"3 minutes ago\" phrasing use the i18n `relativeTime` formatter instead — this is the terse form.\n\n/** Tunes duration formatting. */\nexport interface FormatDurationOptions {\n  /** Maximum number of unit segments to show, most-significant first. Defaults to `2` (`1h 3m`). */\n  readonly units?: number;\n\n  /** Include a millisecond segment even for durations ≥ 1s. Defaults to `false` (ms only shows sub-second). */\n  readonly ms?: boolean;\n}\n\nconst MsPer = { d: 86_400_000, h: 3_600_000, m: 60_000, s: 1000 } as const;\n\n/**\n * Formats a millisecond duration as a compact string (`1d 2h`, `3m 20s`, `500ms`, `0s`). Emits at most `units`\n * non-zero segments in descending order; a sub-second duration renders as `ms`. Sign is preserved. Throws a\n * `RangeError` on a non-finite input.\n */\nexport function formatDuration(milliseconds: number, options?: FormatDurationOptions): string {\n  if (!Number.isFinite(milliseconds)) {\n    throw new RangeError(`formatDuration: expected a finite number, got ${milliseconds}`);\n  }\n\n  const maxUnits = Math.max(1, options?.units ?? 2);\n  const sign = milliseconds < 0 ? '-' : '';\n  let remaining = Math.abs(milliseconds);\n\n  const segments: string[] = [];\n  for (const [unit, size] of Object.entries(MsPer) as [keyof typeof MsPer, number][]) {\n    const amount = Math.floor(remaining / size);\n    if (amount > 0) {\n      segments.push(`${amount}${unit}`);\n      remaining -= amount * size;\n    }\n  }\n\n  const millis = Math.floor(remaining);\n  // Sub-second total (no d/h/m/s segments) always shows ms; `ms: true` appends it to longer durations too.\n  if ((segments.length === 0 || options?.ms === true) && millis > 0) segments.push(`${millis}ms`);\n\n  if (segments.length === 0) return '0s';\n  return `${sign}${segments.slice(0, maxUnits).join(' ')}`;\n}\n","// String humanizers — truncation, casing, slugs, initials, and masking. All pure and locale-light (casing uses\n// the default locale's `toUpperCase`/`toLowerCase`); no `Intl` dependency.\n\n/** Tunes truncation. */\nexport interface TruncateOptions {\n  /** The overflow indicator appended when the text is cut. Defaults to `…`. */\n  readonly ellipsis?: string;\n\n  /** Cut back to the last word boundary so a word is never split mid-way. Defaults to `false`. */\n  readonly wordBoundary?: boolean;\n}\n\n/**\n * Truncates `text` to at most `maxLength` characters *including* the ellipsis. Returns the text unchanged when it\n * already fits. With `wordBoundary`, trims back to the last space before the cut so no word is split.\n */\nexport function truncate(text: string, maxLength: number, options?: TruncateOptions): string {\n  if (maxLength < 0) throw new RangeError(`truncate: maxLength must be ≥ 0, got ${maxLength}`);\n  if (text.length <= maxLength) return text;\n\n  const ellipsis = options?.ellipsis ?? '…';\n  if (maxLength <= ellipsis.length) return ellipsis.slice(0, maxLength);\n\n  let end = maxLength - ellipsis.length;\n  let head = text.slice(0, end);\n  if (options?.wordBoundary === true) {\n    const lastSpace = head.lastIndexOf(' ');\n    if (lastSpace > 0) {\n      end = lastSpace;\n      head = text.slice(0, end);\n    }\n  }\n  return head.trimEnd() + ellipsis;\n}\n\n/** Upper-cases the first character, leaving the rest untouched (`\"hi there\"` → `\"Hi there\"`). */\nexport function capitalize(text: string): string {\n  return text.length === 0 ? text : text.charAt(0).toUpperCase() + text.slice(1);\n}\n\n/** Upper-cases the first letter of each whitespace-separated word (rest of each word lowercased). */\nexport function titleCase(text: string): string {\n  return text\n    .split(/(\\s+)/)\n    .map((part) =>\n      /\\s/.test(part) || part.length === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1).toLowerCase(),\n    )\n    .join('');\n}\n\n/** Tunes slug generation. */\nexport interface SlugifyOptions {\n  /** The literal word separator; empty joins words without a separator. Defaults to `-`. */\n  readonly separator?: string;\n}\n\n/**\n * Builds a URL-safe slug: strips diacritics (NFKD normalize + drop combining marks), lower-cases, replaces every\n * interior run of non-alphanumeric characters with the literal separator, and removes edge punctuation.\n * `\"Héllo, World!\"` → `\"hello-world\"`.\n */\nexport function slugify(text: string, options?: SlugifyOptions): string {\n  const separator = options?.separator ?? '-';\n  return text\n    .normalize('NFKD')\n    .replace(/[̀-ͯ]/g, '') // combining diacritical marks split off by NFKD\n    .toLowerCase()\n    .replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, '')\n    .replace(/[^a-z0-9]+/g, () => separator);\n}\n\n/** Tunes initials extraction. */\nexport interface InitialsOptions {\n  /** Maximum number of initials to take. Defaults to `2`. */\n  readonly max?: number;\n}\n\n/**\n * Extracts up-to-`max` upper-cased initials from a name — the first letter of the first and last significant\n * words. `\"John Ronald Reuel Tolkien\"` → `\"JT\"`. Returns `\"\"` for a blank name.\n */\nexport function initials(name: string, options?: InitialsOptions): string {\n  const max = Math.max(1, options?.max ?? 2);\n  const words = name\n    .trim()\n    .split(/\\s+/)\n    .filter((word) => word.length > 0);\n  if (words.length === 0) return '';\n\n  // First `max-1` words plus the last word — so a long name yields \"first…last\" initials, not the first N.\n  // `words` is non-empty here, so the last element is present (the cast satisfies `noUncheckedIndexedAccess`).\n  const last = words[words.length - 1] as string;\n  const picked = words.length <= max ? words : [...words.slice(0, max - 1), last];\n  return picked\n    .slice(0, max)\n    .map((word) => word.charAt(0).toUpperCase())\n    .join('');\n}\n\n/** Tunes masking. */\nexport interface MaskOptions {\n  /** Number of characters left visible. Defaults to `4`; invalid counts mask every character. */\n  readonly visible?: number;\n\n  /** The mask character. Defaults to `•`. */\n  readonly mask?: string;\n\n  /** Which end stays visible — `end` shows the suffix, `start` the prefix. Defaults to `end`. */\n  readonly side?: 'start' | 'end';\n}\n\n/**\n * Masks all but the last (or first) `visible` characters — for rendering partial secrets / PII (`\"4242…4242\"` →\n * `\"••••••••••••4242\"`). When the text is no longer than `visible`, every character is masked.\n * Nonfinite, fractional and negative visibility counts also mask every character.\n */\nexport function maskString(text: string, options?: MaskOptions): string {\n  const requestedVisible = options?.visible ?? 4;\n  const visible = Number.isInteger(requestedVisible) && requestedVisible >= 0 ? requestedVisible : 0;\n  const maskChar = options?.mask ?? '•';\n  const side = options?.side ?? 'end';\n\n  if (text.length <= visible) return maskChar.repeat(text.length);\n\n  const masked = maskChar.repeat(text.length - visible);\n  return side === 'start' ? text.slice(0, visible) + masked : masked + text.slice(text.length - visible);\n}\n","// Count humanizers — English pluralization and ordinals. Deliberately English-only helpers, distinct from the\n// i18n `plural` formatter (which returns the locale's LDML plural *category*, not a word). Compose these with the\n// i18n number formatter for the count itself: `` `${fmt.number(n)} ${pluralize(n, 'item')}` ``.\n\n/**\n * Returns the correct English word form for `count` — `singular` when the count is exactly 1 (or -1), else\n * `plural` (defaulting to `singular + 's'`). Word only, so it composes with any number rendering.\n * `pluralize(2, 'item')` → `\"items\"`; `pluralize(1, 'child', 'children')` → `\"child\"`.\n */\nexport function pluralize(count: number, singular: string, plural?: string): string {\n  return Math.abs(count) === 1 ? singular : (plural ?? `${singular}s`);\n}\n\n/** Returns the English ordinal suffix for an integer — `\"st\"`, `\"nd\"`, `\"rd\"`, or `\"th\"` (11–13 are always `\"th\"`). */\nexport function ordinalSuffix(value: number): string {\n  const abs = Math.abs(Math.trunc(value));\n  const lastTwo = abs % 100;\n  if (lastTwo >= 11 && lastTwo <= 13) return 'th';\n  switch (abs % 10) {\n    case 1:\n      return 'st';\n    case 2:\n      return 'nd';\n    case 3:\n      return 'rd';\n    default:\n      return 'th';\n  }\n}\n\n/** Renders an integer with its English ordinal suffix — `ordinal(1)` → `\"1st\"`, `ordinal(22)` → `\"22nd\"`. */\nexport function ordinal(value: number): string {\n  return `${Math.trunc(value)}${ordinalSuffix(value)}`;\n}\n"],"names":[],"mappings":"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"}

package/dist/foundation/geolocation/DistanceBetween.d.ts

@@ -1,4 +1,4 @@
-import { LatLng } from './Coordinates';
+import { LatLng } from './models/Coordinates';
 /** IUGG mean Earth radius (R₁), in metres. The sphere the haversine result is measured on. */
 export declare const EarthRadiusMetres = 6371008.8;
 /**

package/dist/foundation/geolocation/GetCurrentPosition.d.ts

@@ -1,4 +1,4 @@
-import { PositionRequestOptions, PositionResult } from './PositionResult';
+import { PositionRequestOptions, PositionReadResult } from './PositionMapping';
 /**
  * Reads the device's current position once.
  *
@@ -6,9 +6,9 @@ import { PositionRequestOptions, PositionResult } from './PositionResult';
  * prompt with no visible cause is the one users reflexively dismiss, and a dismissal is a `denied` that sticks.
  *
  * Never throws, never rejects — every outcome, including the absence of the API, arrives as a
- * {@link PositionResult}.
+ * {@link PositionReadResult}.
  *
  * @param options Accuracy / timeout / cache-age tuning. See {@link PositionRequestOptions}.
  * @returns The outcome: a fix, a typed refusal (`denied` / `unavailable` / `timeout`), `unsupported`, or `failed`.
  */
-export declare function getCurrentPosition(options?: PositionRequestOptions): Promise<PositionResult>;
+export declare function getCurrentPosition(options?: PositionRequestOptions): Promise<PositionReadResult>;

package/dist/foundation/geolocation/PositionFailureCode.d.ts

@@ -0,0 +1,9 @@
+/** Closed failure vocabulary for PositionFailure. */
+export declare const PositionFailureCode: {
+    readonly Denied: "denied";
+    readonly Unavailable: "unavailable";
+    readonly Timeout: "timeout";
+    readonly Unsupported: "unsupported";
+    readonly Failed: "failed";
+};
+export type PositionFailureCode = (typeof PositionFailureCode)[keyof typeof PositionFailureCode];

package/dist/foundation/geolocation/PositionMapping.d.ts

@@ -0,0 +1,50 @@
+import { PositionReadResult } from './models/PositionReadResult';
+import { PositionFailure } from './models/PositionFailure';
+/** The message on the `Error` reported when the platform hands back a position nothing can be read out of. */
+export declare const UnreadablePositionMessage = "Geolocation reported a position with no readable coordinates.";
+export type { PositionFailure } from './models/PositionFailure';
+export type { PositionReadResult } from './models/PositionReadResult';
+export type PositionStatus = 'ok' | PositionFailure['status'];
+/**
+ * Tunes a position request. Mirrors the platform's `PositionOptions`, restated here so the public API of this
+ * slice owns its own input type and can document what each field actually costs.
+ */
+export interface PositionRequestOptions {
+    /**
+     * Asks for the most accurate fix the device can give — GPS rather than wifi/cell triangulation. Slower to
+     * acquire and materially more battery-hungry; leave it off unless the accuracy genuinely changes the UI.
+     */
+    readonly enableHighAccuracy?: boolean;
+    /**
+     * Milliseconds to wait for a fix before answering `timeout`. Unset means wait indefinitely — which is why a
+     * request with no timeout can leave a UI spinning forever indoors. A cold GPS fix can need 10–30s.
+     */
+    readonly timeout?: number;
+    /**
+     * Milliseconds a cached fix may be old and still be handed back instantly. `0` (the platform default) forces
+     * a fresh acquisition every time; a few seconds is usually a better trade for a UI that asks repeatedly.
+     */
+    readonly maximumAge?: number;
+}
+/**
+ * Translates a value from a geolocation error callback into its {@link PositionReadResult}. Exported for the two
+ * sibling entry points; absent from the barrel.
+ *
+ * Never throws — a hostile error object degrades to `failed`, never to an exception thrown inside a platform
+ * callback.
+ *
+ * @param raw The value handed to a `getCurrentPosition` / `watchPosition` error callback.
+ */
+export declare function toPositionResult(raw: unknown): PositionReadResult;
+/**
+ * Translates a value from a geolocation success callback into its {@link PositionReadResult}, converting the host
+ * object into a plain snapshot on the way. Exported for the two sibling entry points; absent from the barrel.
+ *
+ * A success callback that carries nothing readable becomes `failed` rather than `ok` with a hollow position —
+ * a consumer must never receive a `status: 'ok'` it cannot plot.
+ *
+ * Never throws.
+ *
+ * @param raw The value handed to a `getCurrentPosition` / `watchPosition` success callback.
+ */
+export declare function toPositionSuccess(raw: unknown): PositionReadResult;

package/dist/foundation/geolocation/WatchPosition.d.ts

@@ -1,6 +1,6 @@
-import { PositionRequestOptions, PositionResult } from './PositionResult';
+import { PositionRequestOptions, PositionReadResult } from './PositionMapping';
 /** Receives every emission of a watch — a new fix, or a failure. Called with the same union as a one-shot read. */
-export type PositionHandler = (result: PositionResult) => void;
+export type PositionHandler = (result: PositionReadResult) => void;
 /**
  * Subscribes to the device's position and calls `handler` on every fix and every failure.
  *
@@ -12,7 +12,7 @@ export type PositionHandler = (result: PositionResult) => void;
  *
  * Never throws — neither this call nor any emission.
  *
- * @param handler Called with each {@link PositionResult}. A throw from it is swallowed.
+ * @param handler Called with each {@link PositionReadResult}. A throw from it is swallowed.
  * @param options Accuracy / timeout / cache-age tuning. See {@link PositionRequestOptions}.
  * @returns The disposer. Idempotent; safe to call more than once and after emissions have stopped.
  */

package/dist/foundation/geolocation/hooks/UseGeolocation.d.ts

@@ -0,0 +1,38 @@
+import { ComputedRef, MaybeRefOrGetter } from 'vue';
+import { Position } from '../models/Coordinates';
+import { GeolocationState } from '../models/GeolocationReading';
+import { PositionRequestOptions, PositionReadResult } from '../PositionMapping';
+/**
+ * What {@link useGeolocation} returns — the reactive form of a {@link GeolocationReading} plus the action that
+ * refreshes it.
+ */
+export interface GeolocationControls {
+    /** The lifecycle state — drive the whole UI off this one switch. */
+    readonly status: ComputedRef<GeolocationState>;
+    /**
+     * The most recent successful fix, or `null` before the first one. Deliberately NOT cleared by a later
+     * failure — check `status.value === 'ok'` when only a currently-valid reading will do.
+     */
+    readonly position: ComputedRef<Position | null>;
+    /** The error behind a `failed` status, or `null` for every other status. Never stale. */
+    readonly error: ComputedRef<Error | null>;
+    /** Convenience for `status === 'locating'` — the flag a button's `disabled` / spinner wants. */
+    readonly locating: ComputedRef<boolean>;
+    /**
+     * Requests a fix, writing the outcome to this composable's state and also resolving to it. Never throws,
+     * never rejects. Call it from a user gesture — it is what raises the permission prompt.
+     *
+     * @param overrides Options for this call only, replacing the composable-level ones. Omit to use those.
+     */
+    readonly request: (overrides?: PositionRequestOptions) => Promise<PositionReadResult>;
+}
+/**
+ * Exposes the device's position as reactive state, with a `request()` that fetches it on demand.
+ *
+ * Requests nothing on mount — see the header for why that is deliberate. Inherits the slice's never-throws
+ * contract: `request` resolves to a {@link PositionReadResult}, never rejects.
+ *
+ * @param options Default tuning for every `request()` call. A ref or getter is read at call time, so the value
+ *   in effect is always the current one.
+ */
+export declare function useGeolocation(options?: MaybeRefOrGetter<PositionRequestOptions | undefined>): GeolocationControls;

package/dist/foundation/geolocation/hooks/UseWatchPosition.d.ts

@@ -0,0 +1,16 @@
+import { MaybeRefOrGetter, ShallowRef } from 'vue';
+import { GeolocationReading } from '../models/GeolocationReading';
+import { PositionRequestOptions } from '../PositionMapping';
+/**
+ * Tracks the device's position for as long as the scope lives, clearing the watch when it is disposed.
+ *
+ * Starts on mount — see the header. Every fix and every failure arrives through the same
+ * {@link GeolocationReading} shape `useGeolocation` exposes, minus the manual `request`; the last successful
+ * fix survives a later failure, so a map keeps its pin when the signal drops.
+ *
+ * Inherits the slice's never-throws contract.
+ *
+ * @param options Accuracy / timeout / cache-age tuning. Changing any of the three values restarts the watch.
+ * @returns The current reading. Holds {@link IdleGeolocationReading} during SSR and until mount.
+ */
+export declare function useWatchPosition(options?: MaybeRefOrGetter<PositionRequestOptions | undefined>): Readonly<ShallowRef<GeolocationReading>>;

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

@@ -1,10 +1,11 @@
-export { type LatLng, type Coordinates, type Position } from './Coordinates';
+export { type LatLng, type Coordinates, type Position } from './models/Coordinates';
 export { canLocate } from './CanLocate';
-export { type PositionResult, type PositionStatus, type PositionRequestOptions, UnreadablePositionMessage, } from './PositionResult';
+export { type PositionFailure, type PositionReadResult, type PositionStatus, type PositionRequestOptions, UnreadablePositionMessage, } from './PositionMapping';
 export { getCurrentPosition } from './GetCurrentPosition';
 export { watchPosition, type PositionHandler } from './WatchPosition';
 export { getGeolocationPermission, type PermissionQueryState } from './GeolocationPermission';
 export { distanceBetween, EarthRadiusMetres } from './DistanceBetween';
-export { type GeolocationState, type GeolocationReading } from './GeolocationReading';
-export { useGeolocation, type GeolocationControls } from './UseGeolocation';
-export { useWatchPosition } from './UseWatchPosition';
+export { type GeolocationState, type GeolocationReading } from './models/GeolocationReading';
+export { useGeolocation, type GeolocationControls } from './hooks/UseGeolocation';
+export { useWatchPosition } from './hooks/UseWatchPosition';
+export { PositionFailureCode } from './PositionFailureCode';

package/dist/foundation/geolocation/index.js

@@ -1,6 +1,6 @@
-import { t as toError } from "../../chunks/ToError-CyTBsmLO.js";
-import { q as queryPermission } from "../../chunks/QueryPermission--OKfvS9c.js";
-import { shallowRef, computed, toValue, onMounted, watch, onScopeDispose } from "vue";
+import { t as toError } from "../../chunks/ToError-vXncXe19.js";
+import { q as queryPermission } from "../../chunks/QueryPermission-BsLR2WRk.js";
+import { shallowRef, onScopeDispose, computed, toValue, onMounted, watch } from "vue";
 function readFiniteNumber(source, key) {
   try {
     const value = source[key];
@@ -66,23 +66,24 @@ function readErrorCode(raw) {
 function toPositionResult(raw) {
   switch (readErrorCode(raw)) {
     case PermissionDeniedCode:
-      return { status: "denied" };
+      return { ok: false, failure: { status: "denied" } };
     case PositionUnavailableCode:
-      return { status: "unavailable" };
+      return { ok: false, failure: { status: "unavailable" } };
     case TimeoutCode:
-      return { status: "timeout" };
+      return { ok: false, failure: { status: "timeout" } };
     default:
-      return { status: "failed", error: toError(raw) };
+      return { ok: false, failure: { status: "failed", error: toError(raw) } };
   }
 }
 function toPositionSuccess(raw) {
   const position = toPosition(raw);
-  if (position === null) return { status: "failed", error: new Error(UnreadablePositionMessage) };
-  return { status: "ok", position };
+  if (position === null)
+    return { ok: false, failure: { status: "failed", error: new Error(UnreadablePositionMessage) } };
+  return { ok: true, value: position };
 }
 function getCurrentPosition(options) {
   const api = geolocationApi();
-  if (api === void 0) return Promise.resolve({ status: "unsupported" });
+  if (api === void 0) return Promise.resolve({ ok: false, failure: { status: "unsupported" } });
   return new Promise((resolve) => {
     let settled = false;
     const settle = (result) => {
@@ -97,7 +98,7 @@ function getCurrentPosition(options) {
         options
       );
     } catch (error) {
-      settle({ status: "failed", error: toError(error) });
+      settle({ ok: false, failure: { status: "failed", error: toError(error) } });
     }
   });
 }
@@ -113,7 +114,7 @@ function watchPosition(handler, options) {
   };
   const api = geolocationApi();
   if (api === void 0 || typeof api.watchPosition !== "function") {
-    emit({ status: "unsupported" });
+    emit({ ok: false, failure: { status: "unsupported" } });
     return () => {
       disposed = true;
     };
@@ -126,7 +127,7 @@ function watchPosition(handler, options) {
     );
     if (typeof id === "number") watchId = id;
   } catch (error) {
-    emit({ status: "failed", error: toError(error) });
+    emit({ ok: false, failure: { status: "failed", error: toError(error) } });
   }
   return () => {
     if (disposed) return;
@@ -155,24 +156,35 @@ function distanceBetween(a, b) {
   const halfLatitudeDelta = (b.latitude - a.latitude) * DegreesToRadians / 2;
   const halfLongitudeDelta = (b.longitude - a.longitude) * DegreesToRadians / 2;
   const chord = Math.sin(halfLatitudeDelta) ** 2 + Math.cos(latitudeA) * Math.cos(latitudeB) * Math.sin(halfLongitudeDelta) ** 2;
-  return 2 * EarthRadiusMetres * Math.atan2(Math.sqrt(chord), Math.sqrt(1 - chord));
+  const clamped = Math.min(1, Math.max(0, chord));
+  return 2 * EarthRadiusMetres * Math.atan2(Math.sqrt(clamped), Math.sqrt(1 - clamped));
 }
+const GeolocationState = {
+  /** Nothing has been requested yet — the state before the first read and the one a reset returns to. */
+  Idle: "idle"
+};
 const IdleGeolocationReading = {
-  status: "idle",
+  status: GeolocationState.Idle,
   position: null,
   error: null
 };
 function applyPositionResult(previous, result) {
   return {
-    status: result.status,
-    position: result.status === "ok" ? result.position : previous.position,
-    error: result.status === "failed" ? result.error : null
+    status: result.ok ? "ok" : result.failure.status,
+    position: result.ok ? result.value : previous.position,
+    error: !result.ok && result.failure.status === "failed" ? result.failure.error : null
   };
 }
 function useGeolocation(options) {
   const reading = shallowRef(IdleGeolocationReading);
   let latestRequest = 0;
+  let disposed = false;
+  onScopeDispose(() => {
+    disposed = true;
+    latestRequest++;
+  });
   const request = async (overrides) => {
+    if (disposed) return { ok: false, failure: { status: "unsupported" } };
     latestRequest += 1;
     const token = latestRequest;
     reading.value = { ...reading.value, status: "locating" };
@@ -212,18 +224,22 @@ function useWatchPosition(options) {
   }
   onMounted(start);
   watch(
-    [
-      () => toValue(options)?.enableHighAccuracy,
-      () => toValue(options)?.timeout,
-      () => toValue(options)?.maximumAge
-    ],
+    [() => toValue(options)?.enableHighAccuracy, () => toValue(options)?.timeout, () => toValue(options)?.maximumAge],
     start
   );
   onScopeDispose(stop);
   return reading;
 }
+const PositionFailureCode = {
+  Denied: "denied",
+  Unavailable: "unavailable",
+  Timeout: "timeout",
+  Unsupported: "unsupported",
+  Failed: "failed"
+};
 export {
   EarthRadiusMetres,
+  PositionFailureCode,
   UnreadablePositionMessage,
   canLocate,
   distanceBetween,