@corbits/react-ui 0.1.0

package/dist/lib/csv.js

@@ -0,0 +1,108 @@
+/**
+ * A CSV parser sized for previewing a file in a browser tab, not for ingesting
+ * one.
+ *
+ * The distinction matters and drives every decision here. A preview has a
+ * hostile input (a user's arbitrary file), a hard latency budget (the tab must
+ * stay responsive), and a low cost of being approximate (the user can always
+ * download the original). So this refuses oversized input up front instead of
+ * streaming it, caps what it hands back instead of virtualising, and reports
+ * "not tabular" instead of guessing — a ragged file rendered as a grid puts
+ * cells under the wrong headers, which is a worse failure than showing raw text.
+ */ /** Rows past this are dropped; the caller must say so in the UI. */ export const CSV_ROW_CAP = 500;
+/** Columns past this are dropped; the caller must say so in the UI. */ export const CSV_COLUMN_CAP = 40;
+/**
+ * Refuse to parse beyond this. 2 MiB of CSV is roughly 20k rows — already far
+ * past what anyone reads on screen, and enough DOM to lock the tab.
+ */ export const CSV_MAX_PREVIEW_BYTES = 2 * 1024 * 1024;
+/**
+ * True UTF-8 length, not `string.length`.
+ *
+ * `"é".length` is 1 but it costs 2 bytes, and a file of CJK text is three times
+ * its character count — sizing the guard by character count would let a file
+ * three times over budget through.
+ */ export function utf8ByteLength(text) {
+    return new TextEncoder().encode(text).length;
+}
+/**
+ * Splits one CSV line, honouring RFC 4180 quoting: `"a,b"` is one field, and a
+ * doubled `""` inside quotes is a literal quote.
+ *
+ * Line-at-a-time, so a quoted field containing a newline will split across two
+ * records. That is a deliberate limit rather than an oversight: handling it
+ * needs a character-level state machine over the whole document, and embedded
+ * newlines show up as an extra ragged row here — which `isTabular` catches and
+ * degrades to raw text, the honest outcome.
+ */ function splitLine(line) {
+    const fields = [];
+    let field = "";
+    let quoted = false;
+    for(let i = 0; i < line.length; i += 1){
+        const char = line[i];
+        if (quoted) {
+            if (char === '"') {
+                if (line[i + 1] === '"') {
+                    field += '"';
+                    i += 1;
+                } else {
+                    quoted = false;
+                }
+            } else {
+                field += char;
+            }
+        } else if (char === '"') {
+            quoted = true;
+        } else if (char === ",") {
+            fields.push(field);
+            field = "";
+        } else {
+            field += char;
+        }
+    }
+    fields.push(field);
+    return fields;
+}
+/**
+ * Parses CSV text, or returns `null` when it is too large to parse safely.
+ *
+ * `null` rather than a throw: "too big to preview" is an expected outcome of
+ * showing a user their own file, not an exceptional one, and the caller's
+ * response is to render a different surface rather than to catch.
+ */ export function parseCsv(text) {
+    if (utf8ByteLength(text) > CSV_MAX_PREVIEW_BYTES) return null;
+    const lines = text.split(/\r\n|\n|\r/).filter((line)=>line.trim() !== "");
+    if (lines.length === 0) return {
+        headers: [],
+        rows: []
+    };
+    const [headerLine, ...bodyLines] = lines;
+    return {
+        headers: splitLine(headerLine ?? ""),
+        rows: bodyLines.map(splitLine)
+    };
+}
+/**
+ * Whether the parse is rectangular enough to render as a grid.
+ *
+ * Requires at least two columns and every row to match the header width. A
+ * single-column "CSV" is prose that happens to have no commas, and a ragged one
+ * has no reliable column alignment — in both cases raw text tells the truth and
+ * a table does not.
+ */ export function isTabular(parsed) {
+    if (parsed.headers.length < 2) return false;
+    return parsed.rows.every((row)=>row.length === parsed.headers.length);
+}
+/** Trims a parse to the caps, keeping the original totals so the UI can say so. */ export function capCsv(parsed) {
+    const totalRows = parsed.rows.length;
+    const totalColumns = parsed.headers.length;
+    const columnsTruncated = totalColumns > CSV_COLUMN_CAP;
+    const rowsTruncated = totalRows > CSV_ROW_CAP;
+    return {
+        headers: columnsTruncated ? parsed.headers.slice(0, CSV_COLUMN_CAP) : parsed.headers,
+        rows: (rowsTruncated ? parsed.rows.slice(0, CSV_ROW_CAP) : parsed.rows).map((row)=>columnsTruncated ? row.slice(0, CSV_COLUMN_CAP) : row),
+        totalRows,
+        totalColumns,
+        rowsTruncated,
+        columnsTruncated
+    };
+}

package/dist/lib/metrics.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Pure arithmetic behind the dashboard viz pieces: period-over-period deltas,
+ * sparkline and mosaic geometry, and zero-filling a sparse daily series. Plain
+ * numbers in, plain numbers out — no React, no SVG — so the part of a dashboard
+ * that can silently lie is the part you can check by hand.
+ */
+export { formatCompact } from "./chart-geometry.js";
+export type DeltaDirection = "up" | "down" | "flat";
+export type DeltaResult = {
+    readonly direction: DeltaDirection;
+    /** Percent change vs the previous window, or null when it cannot be computed. */
+    readonly pct: number | null;
+    readonly delta: number;
+    /**
+     * False when there is no previous window to compare against. Distinguishes
+     * "no change" (comparable, delta 0) from "no comparison available", so a UI
+     * never renders a flat indicator that reads as stability.
+     */
+    readonly comparable: boolean;
+};
+/**
+ * Period-over-period change. `comparable` is false when there is no previous
+ * window. `pct` is null when the previous value is absent or zero — there is no
+ * meaningful baseline to divide by, so callers render the absolute delta rather
+ * than a misleading "∞%".
+ */
+export declare function computeDelta(current: number, previous: number | null | undefined): DeltaResult;
+export type SparklineGeometry = {
+    /** SVG `<polyline>` `points` string. Empty for an empty series. */
+    readonly points: string;
+    readonly coords: readonly {
+        readonly x: number;
+        readonly y: number;
+    }[];
+};
+/**
+ * Maps a value series to polyline coordinates in a `width` × `height` viewBox.
+ * The minimum value sits on the bottom edge and the maximum on the top — the
+ * shape is the message, and a zero baseline would flatten every real series in
+ * a box this small. A flat series renders along the vertical centre and a
+ * single point is centred horizontally.
+ */
+export declare function buildSparkline(values: readonly number[], width: number, height: number): SparklineGeometry;
+export type MosaicSegment = {
+    readonly label: string;
+    readonly value: number;
+    /** Width as a percentage of the total, 0 when the total is 0. */
+    readonly pct: number;
+};
+/** Shares of a whole, as percentage widths for a stacked strip. */
+export declare function buildMosaic(parts: readonly {
+    label: string;
+    value: number;
+}[]): MosaicSegment[];
+export type FillDailySeriesOptions<T> = {
+    /** Reads the row's UTC calendar date, `YYYY-MM-DD`. */
+    readonly dateOf: (row: T) => string;
+    /** Builds the zero row for a date with no activity. */
+    readonly zero: (date: string) => T;
+};
+/** Runaway guard: the longest spine `fillDailySeries` will build. */
+export declare const FILL_DAILY_SERIES_MAX_DAYS = 400;
+/**
+ * Expands a sparse daily series (only days with activity) into a continuous,
+ * zero-filled spine from `startDate` to `endDate` inclusive (UTC). Without this
+ * a sparkline plots gapped days at equal spacing, drawing a false slope across
+ * dates where nothing happened. Returns the input unchanged for an unparseable
+ * or inverted range, and caps at `FILL_DAILY_SERIES_MAX_DAYS`.
+ */
+export declare function fillDailySeries<T>(series: readonly T[], startDate: string, endDate: string, options: FillDailySeriesOptions<T>): readonly T[];

package/dist/lib/metrics.js

@@ -0,0 +1,101 @@
+/**
+ * Pure arithmetic behind the dashboard viz pieces: period-over-period deltas,
+ * sparkline and mosaic geometry, and zero-filling a sparse daily series. Plain
+ * numbers in, plain numbers out — no React, no SVG — so the part of a dashboard
+ * that can silently lie is the part you can check by hand.
+ */ export { formatCompact } from "./chart-geometry.js";
+/**
+ * Period-over-period change. `comparable` is false when there is no previous
+ * window. `pct` is null when the previous value is absent or zero — there is no
+ * meaningful baseline to divide by, so callers render the absolute delta rather
+ * than a misleading "∞%".
+ */ export function computeDelta(current, previous) {
+    if (previous === null || previous === undefined) {
+        return {
+            direction: "flat",
+            pct: null,
+            delta: 0,
+            comparable: false
+        };
+    }
+    const delta = current - previous;
+    const direction = delta > 0 ? "up" : delta < 0 ? "down" : "flat";
+    if (previous === 0) {
+        return {
+            direction,
+            pct: null,
+            delta,
+            comparable: true
+        };
+    }
+    return {
+        direction,
+        pct: delta / previous * 100,
+        delta,
+        comparable: true
+    };
+}
+/**
+ * Maps a value series to polyline coordinates in a `width` × `height` viewBox.
+ * The minimum value sits on the bottom edge and the maximum on the top — the
+ * shape is the message, and a zero baseline would flatten every real series in
+ * a box this small. A flat series renders along the vertical centre and a
+ * single point is centred horizontally.
+ */ export function buildSparkline(values, width, height) {
+    if (values.length === 0) {
+        return {
+            points: "",
+            coords: []
+        };
+    }
+    const max = Math.max(...values);
+    const min = Math.min(...values);
+    const span = max - min;
+    const stepX = values.length > 1 ? width / (values.length - 1) : 0;
+    const coords = values.map((value, index)=>({
+            x: values.length > 1 ? index * stepX : width / 2,
+            y: span === 0 ? height / 2 : height - (value - min) / span * height
+        }));
+    const points = coords.map((c)=>`${round(c.x)},${round(c.y)}`).join(" ");
+    return {
+        points,
+        coords
+    };
+}
+/** Shares of a whole, as percentage widths for a stacked strip. */ export function buildMosaic(parts) {
+    const total = parts.reduce((sum, part)=>sum + part.value, 0);
+    return parts.map((part)=>({
+            label: part.label,
+            value: part.value,
+            pct: total <= 0 ? 0 : part.value / total * 100
+        }));
+}
+/** Runaway guard: the longest spine `fillDailySeries` will build. */ export const FILL_DAILY_SERIES_MAX_DAYS = 400;
+/**
+ * Expands a sparse daily series (only days with activity) into a continuous,
+ * zero-filled spine from `startDate` to `endDate` inclusive (UTC). Without this
+ * a sparkline plots gapped days at equal spacing, drawing a false slope across
+ * dates where nothing happened. Returns the input unchanged for an unparseable
+ * or inverted range, and caps at `FILL_DAILY_SERIES_MAX_DAYS`.
+ */ export function fillDailySeries(series, startDate, endDate, options) {
+    const byDate = new Map(series.map((row)=>[
+            options.dateOf(row),
+            row
+        ]));
+    const msPerDay = 86_400_000;
+    let cursor = new Date(`${startDate}T00:00:00.000Z`).getTime();
+    const end = new Date(`${endDate}T00:00:00.000Z`).getTime();
+    if (Number.isNaN(cursor) || Number.isNaN(end) || end < cursor) {
+        return series;
+    }
+    const out = [];
+    while(cursor <= end && out.length < FILL_DAILY_SERIES_MAX_DAYS){
+        const date = new Date(cursor).toISOString().slice(0, 10);
+        out.push(byDate.get(date) ?? options.zero(date));
+        cursor += msPerDay;
+    }
+    return out;
+}
+function round(n) {
+    return Math.round(n * 100) / 100;
+}

package/dist/lib/now-item.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The model behind the "Now" surface: the things asking for the user's
+ * attention, whatever produced them.
+ *
+ * Two variants, because they behave differently and not because they look
+ * different: a `gate` is blocked work that cannot proceed without a decision,
+ * and a `mail` is something delivered to be read. A gate is never "read"; a
+ * mail has no decision to make. A single optional-field shape would let a
+ * caller build a read gate, which is not a thing.
+ *
+ * `classification` is a free string, not an enum: what counts as a category
+ * differs per app, and the label is shown verbatim. Ranking is driven by
+ * `priority`, which is fixed, so a new classification never changes ordering.
+ */
+export type NowPriority = "now" | "next" | "later";
+export type NowStatus = "needs-action" | "done";
+type NowItemBase = {
+    readonly id: string;
+    readonly title: string;
+    readonly summary?: string;
+    /** Category shown as a badge, e.g. "Approval", "Brief", "Failure". */
+    readonly classification: string;
+    readonly priority: NowPriority;
+    /**
+     * Whether the item is still asking for something. On the base and not only on
+     * mail: a gate is resolved once decided, exactly as a message is once handled,
+     * and a row that had to check `type` before it could show "done" would be
+     * wrong the first time a third variant appeared.
+     */
+    readonly status: NowStatus;
+    /** ISO timestamp. Ties in priority are broken by this, newest first. */
+    readonly when: string;
+    /** Where the item opens. Without it the card renders as static text. */
+    readonly href?: string;
+};
+export type NowItem = (NowItemBase & {
+    readonly type: "gate";
+    /** The decision being asked for, e.g. "Approve send". */
+    readonly action: string;
+}) | (NowItemBase & {
+    readonly type: "mail";
+    readonly from: string;
+    readonly read: boolean;
+});
+/** Short band label for the queue's priority column. */
+export declare const PRIORITY_LABEL: Record<NowPriority, string>;
+/** Human label for the status marker. */
+export declare const STATUS_LABEL: Record<NowStatus, string>;
+/**
+ * Priority first, then newest. Sorts a copy — a component handed a frozen or
+ * host-owned array must not reorder it in place.
+ */
+export declare function sortNowItems(items: readonly NowItem[]): readonly NowItem[];
+export type NowGroup = {
+    readonly priority: NowPriority;
+    readonly items: readonly NowItem[];
+};
+/**
+ * Sorted items split into priority bands. Empty bands are dropped rather than
+ * returned empty, so a caller can map straight to headings without checking.
+ */
+export declare function groupNowItemsByPriority(items: readonly NowItem[]): readonly NowGroup[];
+/** The classifications present, in first-appearance order — for a filter row. */
+export declare function nowItemClassifications(items: readonly NowItem[]): readonly string[];
+export {};

package/dist/lib/now-item.js

@@ -0,0 +1,59 @@
+/**
+ * The model behind the "Now" surface: the things asking for the user's
+ * attention, whatever produced them.
+ *
+ * Two variants, because they behave differently and not because they look
+ * different: a `gate` is blocked work that cannot proceed without a decision,
+ * and a `mail` is something delivered to be read. A gate is never "read"; a
+ * mail has no decision to make. A single optional-field shape would let a
+ * caller build a read gate, which is not a thing.
+ *
+ * `classification` is a free string, not an enum: what counts as a category
+ * differs per app, and the label is shown verbatim. Ranking is driven by
+ * `priority`, which is fixed, so a new classification never changes ordering.
+ */ const PRIORITY_RANK = {
+    now: 0,
+    next: 1,
+    later: 2
+};
+/** Short band label for the queue's priority column. */ export const PRIORITY_LABEL = {
+    now: "HIGH",
+    next: "MED",
+    later: "LOW"
+};
+/** Human label for the status marker. */ export const STATUS_LABEL = {
+    "needs-action": "Needs action",
+    done: "Done"
+};
+/**
+ * Priority first, then newest. Sorts a copy — a component handed a frozen or
+ * host-owned array must not reorder it in place.
+ */ export function sortNowItems(items) {
+    return [
+        ...items
+    ].sort((a, b)=>{
+        const byPriority = PRIORITY_RANK[a.priority] - PRIORITY_RANK[b.priority];
+        if (byPriority !== 0) return byPriority;
+        return Date.parse(b.when) - Date.parse(a.when);
+    });
+}
+/**
+ * Sorted items split into priority bands. Empty bands are dropped rather than
+ * returned empty, so a caller can map straight to headings without checking.
+ */ export function groupNowItemsByPriority(items) {
+    const sorted = sortNowItems(items);
+    const order = [
+        "now",
+        "next",
+        "later"
+    ];
+    return order.map((priority)=>({
+            priority,
+            items: sorted.filter((item)=>item.priority === priority)
+        })).filter((group)=>group.items.length > 0);
+}
+/** The classifications present, in first-appearance order — for a filter row. */ export function nowItemClassifications(items) {
+    return [
+        ...new Set(sortNowItems(items).map((item)=>item.classification))
+    ];
+}

package/dist/lib/relative-time.d.ts

@@ -0,0 +1,9 @@
+/**
+ * "3 min ago" / "in 2 days", localised, from an ISO timestamp.
+ *
+ * `now` is a parameter rather than a `Date.now()` call inside so the output is
+ * a pure function of its inputs — otherwise every list that renders a timestamp
+ * is untestable and re-renders to a different string than the server produced.
+ * Pass the server's render time when hydrating.
+ */
+export declare function formatRelativeTime(iso: string, now?: number): string;

package/dist/lib/relative-time.js

@@ -0,0 +1,47 @@
+const UNITS = [
+    [
+        "year",
+        365 * 24 * 60 * 60 * 1000
+    ],
+    [
+        "month",
+        30 * 24 * 60 * 60 * 1000
+    ],
+    [
+        "week",
+        7 * 24 * 60 * 60 * 1000
+    ],
+    [
+        "day",
+        24 * 60 * 60 * 1000
+    ],
+    [
+        "hour",
+        60 * 60 * 1000
+    ],
+    [
+        "minute",
+        60 * 1000
+    ]
+];
+/**
+ * "3 min ago" / "in 2 days", localised, from an ISO timestamp.
+ *
+ * `now` is a parameter rather than a `Date.now()` call inside so the output is
+ * a pure function of its inputs — otherwise every list that renders a timestamp
+ * is untestable and re-renders to a different string than the server produced.
+ * Pass the server's render time when hydrating.
+ */ export function formatRelativeTime(iso, now = Date.now()) {
+    const then = Date.parse(iso);
+    if (Number.isNaN(then)) return "";
+    const delta = then - now;
+    const magnitude = Math.abs(delta);
+    const format = new Intl.RelativeTimeFormat(undefined, {
+        numeric: "auto",
+        style: "narrow"
+    });
+    for (const [unit, ms] of UNITS){
+        if (magnitude >= ms) return format.format(Math.round(delta / ms), unit);
+    }
+    return format.format(Math.round(delta / 1000), "second");
+}

package/dist/lib/theme.d.ts

@@ -0,0 +1,30 @@
+/** Theme mode and preset resolution for ThemeProvider.
+
+ * Dark mode is a `.dark` class on an ancestor, with an OS-following fallback
+ * when neither `.dark` nor `.light` is set (see theme.css — `@custom-variant
+ * dark` plus the `prefers-color-scheme` block). `.light` is the explicit
+ * opt-out and only works on `documentElement`. This module owns the pure
+ * resolution rules; ThemeProvider applies them to the document and persists
+ * the choice.
+ */
+export type ThemeMode = "system" | "light" | "dark";
+export type ResolvedThemeMode = "light" | "dark";
+/** Named token overlays shipped as `data-theme` values on the root. */
+export type ThemePreset = "default" | "warm" | "cool";
+export declare const THEME_MODES: readonly ThemeMode[];
+export declare const THEME_PRESETS: readonly ThemePreset[];
+export declare const DEFAULT_THEME_STORAGE_KEY = "corbits-theme";
+export type ThemePreference = {
+    readonly mode: ThemeMode;
+    readonly preset: ThemePreset;
+};
+export declare function isThemeMode(value: unknown): value is ThemeMode;
+export declare function isThemePreset(value: unknown): value is ThemePreset;
+/** Resolve light/dark after consulting the system preference when mode is system. */
+export declare function resolveThemeMode(mode: ThemeMode, systemPrefersDark: boolean): ResolvedThemeMode;
+export declare function parseThemePreference(raw: string | null, fallback: ThemePreference): ThemePreference;
+export declare function serializeThemePreference(preference: ThemePreference): string;
+/** Cycle system → light → dark → system for a one-control toggle. */
+export declare function nextThemeMode(mode: ThemeMode): ThemeMode;
+/** Apply resolved mode + preset to a root element (usually documentElement). */
+export declare function applyThemeToRoot(root: Element, resolved: ResolvedThemeMode, preset: ThemePreset): void;

package/dist/lib/theme.js

@@ -0,0 +1,77 @@
+/** Theme mode and preset resolution for ThemeProvider.
+
+ * Dark mode is a `.dark` class on an ancestor, with an OS-following fallback
+ * when neither `.dark` nor `.light` is set (see theme.css — `@custom-variant
+ * dark` plus the `prefers-color-scheme` block). `.light` is the explicit
+ * opt-out and only works on `documentElement`. This module owns the pure
+ * resolution rules; ThemeProvider applies them to the document and persists
+ * the choice.
+ */ export const THEME_MODES = [
+    "system",
+    "light",
+    "dark"
+];
+export const THEME_PRESETS = [
+    "default",
+    "warm",
+    "cool"
+];
+export const DEFAULT_THEME_STORAGE_KEY = "corbits-theme";
+export function isThemeMode(value) {
+    return value === "system" || value === "light" || value === "dark";
+}
+export function isThemePreset(value) {
+    return value === "default" || value === "warm" || value === "cool";
+}
+/** Resolve light/dark after consulting the system preference when mode is system. */ export function resolveThemeMode(mode, systemPrefersDark) {
+    if (mode === "light") return "light";
+    if (mode === "dark") return "dark";
+    return systemPrefersDark ? "dark" : "light";
+}
+export function parseThemePreference(raw, fallback) {
+    if (raw === null || raw.length === 0) return fallback;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null) return fallback;
+        const record = parsed;
+        const mode = isThemeMode(record.mode) ? record.mode : fallback.mode;
+        const preset = isThemePreset(record.preset) ? record.preset : fallback.preset;
+        return {
+            mode,
+            preset
+        };
+    } catch  {
+        // Legacy: a bare mode string from an earlier client.
+        if (isThemeMode(raw)) return {
+            mode: raw,
+            preset: fallback.preset
+        };
+        return fallback;
+    }
+}
+export function serializeThemePreference(preference) {
+    return JSON.stringify({
+        mode: preference.mode,
+        preset: preference.preset
+    });
+}
+/** Cycle system → light → dark → system for a one-control toggle. */ export function nextThemeMode(mode) {
+    if (mode === "system") return "light";
+    if (mode === "light") return "dark";
+    return "system";
+}
+/** Apply resolved mode + preset to a root element (usually documentElement). */ export function applyThemeToRoot(root, resolved, preset) {
+    root.classList.toggle("dark", resolved === "dark");
+    // `.light` is the explicit-light escape hatch from the `prefers-color-scheme`
+    // media query in theme.css — without it, "light" mode chosen on a dark-OS
+    // host would be overridden back to dark tokens by the media query.
+    root.classList.toggle("light", resolved === "light");
+    if (preset === "default") {
+        root.removeAttribute("data-theme");
+    } else {
+        root.setAttribute("data-theme", preset);
+    }
+    if (root instanceof HTMLElement) {
+        root.style.colorScheme = resolved;
+    }
+}

package/dist/lib/url.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Is `url` safe to hand to a live sink — `href`, `src`, `window.open` — as-is?
+ *
+ * Agent- and artifact-supplied strings are untrusted input: a `javascript:`
+ * or `data:` value handed straight to `href` becomes a live script the
+ * moment someone clicks it. Checking `.protocol` after `new URL()` parses the
+ * string, rather than matching a prefix, is what defeats tricks like embedded
+ * tabs/newlines (`java\tscript:`) or mixed case (`JavaScript:`) — the URL
+ * parser strips and normalizes both away before the comparison ever runs.
+ *
+ * Relative and protocol-relative URLs (`/path`, `//host/path`) fail to parse
+ * without a base and are rejected rather than resolved against one: every
+ * sink this guards links to a third-party resource — a citation, a download,
+ * an embed — so there is no in-app page a bare path could sensibly mean, and
+ * inventing a base to resolve against would only guess wrong.
+ */
+export declare function isSafeUrl(url: string, allowedProtocols?: readonly string[]): boolean;
+/**
+ * `url` back, unchanged, if `isSafeUrl` accepts it — otherwise `undefined`.
+ *
+ * The shape callers want at a render site: a value they can put straight
+ * into `href`/`src` when present, and a clean signal to fall back to plain
+ * text when not. Never returns a placeholder like `"#"` — a disabled-looking
+ * link that is secretly still a link is its own trap.
+ */
+export declare function toSafeHref(url: string | undefined, allowedProtocols?: readonly string[]): string | undefined;

package/dist/lib/url.js

@@ -0,0 +1,37 @@
+const DEFAULT_ALLOWED_PROTOCOLS = [
+    "http:",
+    "https:"
+];
+/**
+ * Is `url` safe to hand to a live sink — `href`, `src`, `window.open` — as-is?
+ *
+ * Agent- and artifact-supplied strings are untrusted input: a `javascript:`
+ * or `data:` value handed straight to `href` becomes a live script the
+ * moment someone clicks it. Checking `.protocol` after `new URL()` parses the
+ * string, rather than matching a prefix, is what defeats tricks like embedded
+ * tabs/newlines (`java\tscript:`) or mixed case (`JavaScript:`) — the URL
+ * parser strips and normalizes both away before the comparison ever runs.
+ *
+ * Relative and protocol-relative URLs (`/path`, `//host/path`) fail to parse
+ * without a base and are rejected rather than resolved against one: every
+ * sink this guards links to a third-party resource — a citation, a download,
+ * an embed — so there is no in-app page a bare path could sensibly mean, and
+ * inventing a base to resolve against would only guess wrong.
+ */ export function isSafeUrl(url, allowedProtocols = DEFAULT_ALLOWED_PROTOCOLS) {
+    try {
+        return allowedProtocols.includes(new URL(url).protocol);
+    } catch  {
+        return false;
+    }
+}
+/**
+ * `url` back, unchanged, if `isSafeUrl` accepts it — otherwise `undefined`.
+ *
+ * The shape callers want at a render site: a value they can put straight
+ * into `href`/`src` when present, and a clean signal to fall back to plain
+ * text when not. Never returns a placeholder like `"#"` — a disabled-looking
+ * link that is secretly still a link is its own trap.
+ */ export function toSafeHref(url, allowedProtocols = DEFAULT_ALLOWED_PROTOCOLS) {
+    if (url === undefined) return undefined;
+    return isSafeUrl(url, allowedProtocols) ? url : undefined;
+}

package/dist/lib/utils.d.ts

@@ -0,0 +1,2 @@
+import { type ClassValue } from "clsx";
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/lib/utils.js

@@ -0,0 +1,5 @@
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+export function cn(...inputs) {
+    return twMerge(clsx(inputs));
+}