@wow-two-beta/ui-vue 0.0.2

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

@@ -0,0 +1,18 @@
+/**
+ * Checks whether a caught value is a cancellation — the `AbortError` every `fetch` / `AbortController`
+ * path produces. The one recognizer every request layer needs: an abort means the caller moved on, so
+ * it must be swallowed, never reported as a failure.
+ *
+ * Matched on `name`, deliberately not `instanceof DOMException`: the check has to hold for a
+ * `DOMException` from another realm (iframe · worker), for environments with no `DOMException` global,
+ * and for the plain `{ name: 'AbortError' }` that libraries and test doubles throw.
+ */
+export declare function isAbortError(value: unknown): boolean;
+/**
+ * Checks whether a caught value is a timeout — `AbortSignal.timeout()` rejects with a `TimeoutError`
+ * `DOMException`, and libraries copy that name.
+ *
+ * Name-only by design: no substring match on `message`. The word "timeout" appearing in prose is not a
+ * contract, and matching it would misclassify unrelated failures (and break under translation).
+ */
+export declare function isTimeoutError(value: unknown): boolean;

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

@@ -0,0 +1,25 @@
+/** Defines the JSON-safe projection of an error produced by {@link serializeError}. Every member is a plain value — no getters, no prototype, no cycles. */
+export interface SerializedError {
+    /** The error kind — the source's `name`, or `'Error'` when it had none. */
+    readonly name: string;
+    /** The failure description — the source's `message`, or `''` when it had none (this is a log record, not UI copy). */
+    readonly message: string;
+    /** The captured stack trace. Omitted when the source had none. */
+    readonly stack?: string;
+    /** The machine-readable code. Omitted unless the source carried a string or number `code` — other types are dropped to keep the payload JSON-safe. */
+    readonly code?: string | number;
+    /** The serialized underlying failure. Omitted at the root of the chain, and wherever the depth cap or a cycle stopped the walk. */
+    readonly cause?: SerializedError;
+}
+/**
+ * Projects any caught value into a plain object safe to hand a logger or a telemetry sink — an `Error`
+ * serializes to `{}` through `JSON.stringify`, because `name` / `message` / `stack` are all
+ * non-enumerable, so anything that ships errors off the device needs this first.
+ *
+ * The `cause` chain nests, inheriting the walk's cycle protection and depth cap, so a circular
+ * `cause` produces a finite tree rather than a `JSON.stringify` overflow. Non-JSON-safe members are
+ * dropped, not coerced: the result always survives `JSON.stringify`.
+ *
+ * Never throws.
+ */
+export declare function serializeError(error: unknown, maxDepth?: number): SerializedError;

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

@@ -0,0 +1,15 @@
+/** Provides the last-resort message used when normalization itself fails — the final rung of the never-throw contract. Internal; not barrelled. */
+export declare const UnknownErrorMessage = "Unknown error";
+/**
+ * Normalizes any caught value into an `Error` — the first call every `catch` block makes, so that
+ * downstream code has one type to reason about instead of `unknown`.
+ *
+ * An `Error` passes through by identity (no copy, no lost subclass — an `ApiError` stays an
+ * `ApiError`); an error-like object is adopted with its `name` / `stack` / `code` / `cause`; a string
+ * becomes its own message; anything else is stringified safely. Idempotent from the second call on,
+ * since the result is always an `Error`.
+ *
+ * Total and never-throwing, hostile inputs included: a throwing getter, a `Proxy` whose traps throw,
+ * and a circular structure all yield an `Error` rather than a second failure.
+ */
+export declare function toError(value: unknown): Error;

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

@@ -0,0 +1,6 @@
+export { isErrorLike, type ErrorLike } from './ErrorLike';
+export { toError } from './ToError';
+export { getErrorMessage, DefaultErrorMessage } from './ErrorMessage';
+export { getErrorCause, flattenErrorChain, DefaultMaxCauseDepth } from './ErrorChain';
+export { isAbortError, isTimeoutError } from './ErrorRecognizers';
+export { serializeError, type SerializedError } from './SerializeError';

package/dist/foundation/errors/index.js

@@ -0,0 +1,18 @@
+import { i } from "../../chunks/ErrorLike-Cfj0lZW3.js";
+import { t } from "../../chunks/ToError-CyTBsmLO.js";
+import { D, g } from "../../chunks/ErrorMessage-Cqt7WaFn.js";
+import { D as D2, f, g as g2, s } from "../../chunks/SerializeError-CclP2jCW.js";
+import { i as i2, a } from "../../chunks/ErrorRecognizers-oTklha6D.js";
+export {
+  D as DefaultErrorMessage,
+  D2 as DefaultMaxCauseDepth,
+  f as flattenErrorChain,
+  g2 as getErrorCause,
+  g as getErrorMessage,
+  i2 as isAbortError,
+  i as isErrorLike,
+  a as isTimeoutError,
+  s as serializeError,
+  t as toError
+};
+//# sourceMappingURL=index.js.map

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

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

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

@@ -0,0 +1,30 @@
+/** The subset of `File` accept-matching reads — lets a caller match a plain `{name, type}` without a real `File`. */
+export interface FileLike {
+    /** The file name, including extension. */
+    readonly name: string;
+    /** The MIME type, possibly empty (browsers leave it blank for unknown types). */
+    readonly type: string;
+}
+/** Splits an `accept` string into normalized, lower-cased tokens. Returns `[]` for an absent or blank list. */
+export declare function parseAcceptTokens(accept?: string): string[];
+/**
+ * Tests whether a file satisfies an `accept` list. An absent / blank / token-less list accepts everything.
+ * Matching is case-insensitive: extension tokens compare against the file name, `type/*` against the MIME
+ * prefix, and any other token against the exact MIME type.
+ */
+export declare function matchesAccept(file: FileLike, accept?: string): boolean;
+/** Tunes the advisory, type-only accept check. */
+export interface MatchesAcceptTypeOptions {
+    /**
+     * How to treat extension tokens (`.png`) when no file name is available (a `dragenter`, where only the MIME
+     * type is exposed). `allow` (default) keeps the drag optimistic and defers the real verdict to the drop;
+     * `reject` fails closed.
+     */
+    readonly extensionTokens?: 'allow' | 'reject';
+}
+/**
+ * Advisory accept check for the pre-drop phase, where only a MIME type is known (`DataTransferItem.type`).
+ * Wildcard and exact MIME tokens are judged normally; extension tokens are unverifiable without a file name and
+ * resolve per `extensionTokens` (default `allow`). Re-check with {@link matchesAccept} once the real `File` lands.
+ */
+export declare function matchesAcceptType(mimeType: string, accept?: string, options?: MatchesAcceptTypeOptions): boolean;

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

@@ -0,0 +1,10 @@
+/**
+ * Triggers a browser download of `blob` under `filename` (sanitized via {@link safeFileName}). Creates an object
+ * URL, clicks a detached anchor, then revokes the URL on the next tick so the blob is released. No-ops when
+ * there is no `document`. Returns whether the download was dispatched.
+ */
+export declare function downloadBlob(blob: Blob, filename: string): boolean;
+/** Downloads a string as a file. `mimeType` defaults to UTF-8 plain text. */
+export declare function downloadText(text: string, filename: string, mimeType?: string): boolean;
+/** Downloads a value as pretty-printed JSON (`space` defaults to 2). Throws on a value `JSON.stringify` rejects. */
+export declare function downloadJson(value: unknown, filename: string, space?: number): boolean;

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

@@ -0,0 +1,21 @@
+/**
+ * Returns the lower-cased extension of a file name, without the leading dot. Yields `''` when there is no
+ * extension, when the name is a dotfile (`.gitignore` — the dot starts the name, it doesn't separate one), or
+ * when the dot is trailing.
+ */
+export declare function fileExtension(filename: string): string;
+/** Returns the file name without its extension (`report.final.pdf` → `report.final`). Dotfiles are returned whole. */
+export declare function fileBaseName(filename: string): string;
+/** Tunes download-name sanitizing. */
+export interface SafeFileNameOptions {
+    /** The character replacing each illegal run. Defaults to `-`. */
+    readonly replacement?: string;
+    /** Maximum length of the result (extension preserved when truncating). Defaults to `255`. */
+    readonly maxLength?: number;
+}
+/**
+ * Sanitizes a string into a file name safe across Windows / macOS / Linux: strips path separators, the reserved
+ * characters `< > : " | ? *`, and control characters; collapses whitespace; trims leading/trailing dots and
+ * spaces. Truncates to `maxLength` while preserving the extension. Returns `'file'` when nothing usable remains.
+ */
+export declare function safeFileName(name: string, options?: SafeFileNameOptions): string;

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

@@ -0,0 +1,6 @@
+/** Reads a blob/file as text. `encoding` defaults to the browser's UTF-8 (pass e.g. `windows-1251` for legacy data). */
+export declare function readFileAsText(blob: Blob, encoding?: string): Promise<string>;
+/** Reads a blob/file as a `data:` URL — the form an `<img src>` or a JSON payload can carry inline. */
+export declare function readFileAsDataUrl(blob: Blob): Promise<string>;
+/** Reads a blob/file as an `ArrayBuffer` — for binary inspection (magic bytes, hashing, parsing). */
+export declare function readFileAsArrayBuffer(blob: Blob): Promise<ArrayBuffer>;

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

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

package/dist/foundation/files/index.js

@@ -0,0 +1,62 @@
+import { m, a, p } from "../../chunks/Accept-BWpCXDmS.js";
+import { s as safeFileName } from "../../chunks/FileName-CmNjFV7t.js";
+import { f, a as a2 } from "../../chunks/FileName-CmNjFV7t.js";
+function readWith(blob, start) {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result);
+    reader.onerror = () => reject(reader.error ?? new Error("File read failed"));
+    reader.onabort = () => reject(new Error("File read aborted"));
+    try {
+      start(reader);
+    } catch (error) {
+      reject(error instanceof Error ? error : new Error(String(error)));
+    }
+  });
+}
+function readFileAsText(blob, encoding) {
+  return readWith(blob, (reader) => reader.readAsText(blob, encoding));
+}
+function readFileAsDataUrl(blob) {
+  return readWith(blob, (reader) => reader.readAsDataURL(blob));
+}
+function readFileAsArrayBuffer(blob) {
+  return readWith(blob, (reader) => reader.readAsArrayBuffer(blob));
+}
+function hasDocument() {
+  return typeof document !== "undefined";
+}
+function downloadBlob(blob, filename) {
+  if (!hasDocument()) return false;
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.download = safeFileName(filename);
+  anchor.style.display = "none";
+  document.body.appendChild(anchor);
+  anchor.click();
+  anchor.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+  return true;
+}
+function downloadText(text, filename, mimeType = "text/plain;charset=utf-8") {
+  return downloadBlob(new Blob([text], { type: mimeType }), filename);
+}
+function downloadJson(value, filename, space = 2) {
+  return downloadText(JSON.stringify(value, null, space), filename, "application/json;charset=utf-8");
+}
+export {
+  downloadBlob,
+  downloadJson,
+  downloadText,
+  f as fileBaseName,
+  a2 as fileExtension,
+  m as matchesAccept,
+  a as matchesAcceptType,
+  p as parseAcceptTokens,
+  readFileAsArrayBuffer,
+  readFileAsDataUrl,
+  readFileAsText,
+  safeFileName
+};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +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;"}

package/dist/foundation/format/Bytes.d.ts

@@ -0,0 +1,15 @@
+/** Tunes byte formatting. */
+export interface FormatBytesOptions {
+    /** Use 1024-based IEC units (`KiB`/`MiB`) instead of 1000-based SI units (`KB`/`MB`). Defaults to `false`. */
+    readonly binary?: boolean;
+    /** Maximum fraction digits for units above bytes (trailing zeros are trimmed). Defaults to `1`. */
+    readonly decimals?: number;
+    /** Insert a space between the number and the unit. Defaults to `true`. */
+    readonly space?: boolean;
+}
+/**
+ * Formats a byte count as a human-readable size. Chooses the largest unit whose value is ≥ 1, rounds to
+ * `decimals` fraction digits (trailing zeros trimmed; whole bytes never show decimals), and preserves sign.
+ * Throws a `RangeError` on a non-finite input — formatting `NaN`/`Infinity` bytes is a caller bug.
+ */
+export declare function formatBytes(bytes: number, options?: FormatBytesOptions): string;

package/dist/foundation/format/Count.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Returns the correct English word form for `count` — `singular` when the count is exactly 1 (or -1), else
+ * `plural` (defaulting to `singular + 's'`). Word only, so it composes with any number rendering.
+ * `pluralize(2, 'item')` → `"items"`; `pluralize(1, 'child', 'children')` → `"child"`.
+ */
+export declare function pluralize(count: number, singular: string, plural?: string): string;
+/** Returns the English ordinal suffix for an integer — `"st"`, `"nd"`, `"rd"`, or `"th"` (11–13 are always `"th"`). */
+export declare function ordinalSuffix(value: number): string;
+/** Renders an integer with its English ordinal suffix — `ordinal(1)` → `"1st"`, `ordinal(22)` → `"22nd"`. */
+export declare function ordinal(value: number): string;

package/dist/foundation/format/Duration.d.ts

@@ -0,0 +1,13 @@
+/** Tunes duration formatting. */
+export interface FormatDurationOptions {
+    /** Maximum number of unit segments to show, most-significant first. Defaults to `2` (`1h 3m`). */
+    readonly units?: number;
+    /** Include a millisecond segment even for durations ≥ 1s. Defaults to `false` (ms only shows sub-second). */
+    readonly ms?: boolean;
+}
+/**
+ * Formats a millisecond duration as a compact string (`1d 2h`, `3m 20s`, `500ms`, `0s`). Emits at most `units`
+ * non-zero segments in descending order; a sub-second duration renders as `ms`. Sign is preserved. Throws a
+ * `RangeError` on a non-finite input.
+ */
+export declare function formatDuration(milliseconds: number, options?: FormatDurationOptions): string;

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

@@ -0,0 +1,51 @@
+/** 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 word separator. Defaults to `-`. */
+    readonly separator?: string;
+}
+/**
+ * Builds a URL-safe slug: strips diacritics (NFKD normalize + drop combining marks), lower-cases, replaces every
+ * run of non-alphanumeric characters with the separator, and trims leading/trailing separators.
+ * `"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`. */
+    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.
+ */
+export declare function maskString(text: string, options?: MaskOptions): string;

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

@@ -0,0 +1,4 @@
+export { formatBytes, type FormatBytesOptions } from './Bytes';
+export { formatDuration, type FormatDurationOptions } from './Duration';
+export { truncate, capitalize, titleCase, slugify, initials, maskString, type TruncateOptions, type SlugifyOptions, type InitialsOptions, type MaskOptions, } from './Text';
+export { pluralize, ordinal, ordinalSuffix } from './Count';

package/dist/foundation/format/index.js

@@ -0,0 +1,100 @@
+import { f } from "../../chunks/Bytes-7Jxs6Bq6.js";
+const MS_PER = { 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(MS_PER)) {
+    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 ?? "-";
+  const escaped = separator.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return text.normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, separator).replace(new RegExp(`^${escaped}+|${escaped}+$`, "g"), "");
+}
+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 visible = Math.max(0, options?.visible ?? 4);
+  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/format/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/foundation/format/Duration.ts","../../../src/foundation/format/Text.ts","../../../src/foundation/format/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 MS_PER = { 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(MS_PER) as [keyof typeof MS_PER, 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) => (/\\s/.test(part) || part.length === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()))\n    .join('');\n}\n\n/** Tunes slug generation. */\nexport interface SlugifyOptions {\n  /** The word 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 * run of non-alphanumeric characters with the separator, and trims leading/trailing separators.\n * `\"Héllo, World!\"` → `\"hello-world\"`.\n */\nexport function slugify(text: string, options?: SlugifyOptions): string {\n  const separator = options?.separator ?? '-';\n  const escaped = separator.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n  return text\n    .normalize('NFKD')\n    .replace(/[̀-ͯ]/g, '') // combining diacritical marks split off by NFKD\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, separator)\n    .replace(new RegExp(`^${escaped}+|${escaped}+$`, 'g'), '');\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.trim().split(/\\s+/).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`. */\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 */\nexport function maskString(text: string, options?: MaskOptions): string {\n  const visible = Math.max(0, options?.visible ?? 4);\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/CanLocate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Returns `navigator.geolocation` when it is present and callable, `undefined` otherwise. Exported for the
+ * sibling modules, which need the object itself; absent from the barrel, where {@link canLocate} is the boolean
+ * a consumer wants.
+ *
+ * Never throws.
+ */
+export declare function geolocationApi(): Geolocation | undefined;
+/**
+ * Whether this environment exposes a usable Geolocation API.
+ *
+ * Use it to decide whether to render a "Use my location" affordance at all. It does NOT predict success: the
+ * API can be present and still answer `denied` (user or policy) or `unavailable` (no fix). Treat a `false` as
+ * "hide the feature" and the call's own result as "what happened".
+ *
+ * Never throws. Returns `false` under SSR.
+ */
+export declare function canLocate(): boolean;

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

@@ -0,0 +1,41 @@
+/** The minimum a point needs to be positioned on a sphere — the input {@link distanceBetween} accepts. */
+export interface LatLng {
+    /** Degrees north of the equator, negative for south. */
+    readonly latitude: number;
+    /** Degrees east of the prime meridian, negative for west. */
+    readonly longitude: number;
+}
+/** One fix's spatial data, flattened out of the platform's `GeolocationCoordinates`. */
+export interface Coordinates extends LatLng {
+    /** Radius of the 95%-confidence circle around the position, in metres. Always present; never negative. */
+    readonly accuracy: number;
+    /** Metres above the WGS-84 ellipsoid, or `null` where the device cannot measure altitude. */
+    readonly altitude: number | null;
+    /** Confidence interval on {@link Coordinates.altitude}, in metres, or `null` when altitude is `null`. */
+    readonly altitudeAccuracy: number | null;
+    /** Direction of travel in degrees clockwise from true north, or `null` when stationary or unmeasurable. */
+    readonly heading: number | null;
+    /** Ground speed in metres per second, or `null` where the device cannot measure it. */
+    readonly speed: number | null;
+}
+/** A complete fix: where the device was, and when. The value every entry point in this slice hands back. */
+export interface Position extends Coordinates {
+    /** Milliseconds since the epoch at which the fix was taken — same base as `Date.now()`. */
+    readonly timestamp: number;
+}
+/**
+ * Converts the platform's position object into a plain {@link Position}, or `null` when it carries no usable
+ * fix. Exported for the sibling modules that own the platform callbacks; absent from the barrel, where a
+ * consumer only ever meets the converted form.
+ *
+ * `latitude`, `longitude` and `accuracy` are load-bearing: without all three there is no position to report, so
+ * an unreadable one collapses the whole reading to `null`. The optional channels degrade individually to
+ * `null`. A missing or unreadable `timestamp` falls back to `Date.now()` — the read is happening now, and a fix
+ * without a time is harder to use than one with an approximate one.
+ *
+ * Never throws.
+ *
+ * @param raw The value handed to a `getCurrentPosition` / `watchPosition` success callback.
+ * @returns The plain snapshot, or `null` if no fix could be read out of it.
+ */
+export declare function toPosition(raw: unknown): Position | null;

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

@@ -0,0 +1,21 @@
+import { LatLng } from './Coordinates';
+/** IUGG mean Earth radius (R₁), in metres. The sphere the haversine result is measured on. */
+export declare const EarthRadiusMetres = 6371008.8;
+/**
+ * Great-circle ("as the crow flies") distance between two points, in metres.
+ *
+ * Pure and symmetric — `distanceBetween(a, b) === distanceBetween(b, a)` — and exactly `0` for identical
+ * points. Correct across the antimeridian and the poles without any special-casing by the caller. Accepts
+ * anything with `latitude` / `longitude`, so a {@link Position} from this slice can be passed directly.
+ *
+ * Not road distance and not ellipsoidal: ~0.5% worst case against a geodesic solution, dominated by the
+ * spherical-Earth assumption rather than by the formula. Fine for proximity, sorting, and radius filters; not
+ * for surveying.
+ *
+ * Never throws. Returns `NaN` if any component is `NaN`, `Infinity`, or otherwise not a finite number.
+ *
+ * @param a One endpoint.
+ * @param b The other endpoint.
+ * @returns Metres along the great circle, or `NaN` for unmeasurable input.
+ */
+export declare function distanceBetween(a: LatLng, b: LatLng): number;

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

@@ -0,0 +1,13 @@
+import { PermissionQueryState } from '../notifications';
+export type { PermissionQueryState };
+/**
+ * Reads the current geolocation grant without prompting for it.
+ *
+ * A snapshot — the returned promise fires no event on a later change. Use `usePermissionState('geolocation')`
+ * from `foundation/notifications` to follow changes (a revoke from site settings, a grant given in another tab).
+ *
+ * Never throws, never rejects.
+ *
+ * @returns `granted` / `denied` / `prompt`, or `unsupported` where the Permissions API cannot answer.
+ */
+export declare function getGeolocationPermission(): Promise<PermissionQueryState>;

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

@@ -0,0 +1,30 @@
+import { Position } from './Coordinates';
+import { PositionResult, PositionStatus } from './PositionResult';
+/**
+ * Where a geolocation consumer sits in its lifecycle: the platform's outcomes, plus the two states that exist
+ * only in the UI — `idle` (nothing requested yet) and `locating` (a request is in flight).
+ */
+export type GeolocationState = 'idle' | 'locating' | PositionStatus;
+/** The state both {@link useGeolocation} and {@link useWatchPosition} expose. */
+export interface GeolocationReading {
+    /** The lifecycle state — drive the whole UI off this one switch. */
+    readonly status: GeolocationState;
+    /**
+     * The most recent successful fix, or `null` before the first one. Deliberately NOT cleared by a later
+     * failure — check `status === 'ok'` when only a currently-valid reading will do.
+     */
+    readonly position: Position | null;
+    /** The error behind a `failed` status, or `null` for every other status. Never stale. */
+    readonly error: Error | null;
+}
+/** The starting state: nothing requested, nothing known. */
+export declare const IdleGeolocationReading: GeolocationReading;
+/**
+ * Folds one {@link PositionResult} into the current reading. Pure; exported for the two composables and for tests,
+ * absent from the barrel.
+ *
+ * @param previous The reading being updated — its `position` is what carries a past fix forward.
+ * @param result The outcome to apply.
+ * @returns The next reading.
+ */
+export declare function applyPositionResult(previous: GeolocationReading, result: PositionResult): GeolocationReading;

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

@@ -0,0 +1,14 @@
+import { PositionRequestOptions, PositionResult } from './PositionResult';
+/**
+ * Reads the device's current position once.
+ *
+ * The first call from an origin triggers the browser's permission prompt, so call it from a user gesture: a
+ * 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}.
+ *
+ * @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>;