@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/lib/color.js

@@ -0,0 +1,177 @@
+/**
+ * Colour helpers for Color picker (and anything that shows user-defined colours):
+ * parse hex / rgb() / oklch() strings, convert hex ↔ OKLCH, and compute WCAG contrast.
+ * React-free (works in server components).
+ *
+ * Values in the kit's public APIs are always hex: `"#rrggbb"` or `"#rrggbbaa"`.
+ */
+const clamp = (n, min, max) => Math.min(max, Math.max(min, n));
+const round = (n, digits = 0) => {
+    const f = 10 ** digits;
+    return Math.round(n * f) / f;
+};
+/** Parses `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa` (the `#` is optional). */
+export function hexToRgba(input) {
+    const hex = input.trim().replace(/^#/, "");
+    if (!/^[0-9a-f]+$/i.test(hex))
+        return null;
+    let full;
+    if (hex.length === 3 || hex.length === 4)
+        full = [...hex].map((c) => c + c).join("");
+    else if (hex.length === 6 || hex.length === 8)
+        full = hex;
+    else
+        return null;
+    const n = (i) => parseInt(full.slice(i, i + 2), 16);
+    return { r: n(0), g: n(2), b: n(4), a: full.length === 8 ? round(n(6) / 255, 3) : 1 };
+}
+const toHexByte = (n) => clamp(Math.round(n), 0, 255).toString(16).padStart(2, "0");
+/** `"#rrggbb"`, or `"#rrggbbaa"` when `withAlpha` (default: only when alpha < 1). Lowercase. */
+export function rgbaToHex(c, withAlpha = c.a < 1) {
+    return `#${toHexByte(c.r)}${toHexByte(c.g)}${toHexByte(c.b)}${withAlpha ? toHexByte(c.a * 255) : ""}`;
+}
+const channel = (s, max) => (s.endsWith("%") ? (parseFloat(s) / 100) * max : parseFloat(s));
+const alphaOf = (s) => (s === undefined ? 1 : clamp(channel(s, 1), 0, 1));
+/**
+ * Parses any colour string the picker accepts: hex (with or without `#`), `rgb()`/`rgba()`
+ * (comma or space syntax) and `oklch()`. Returns `null` for anything else.
+ *
+ * ```ts
+ * parseColor("c6f432");                   // { r: 198, g: 244, b: 50, a: 1 }
+ * parseColor("oklch(89% 0.21 122 / 50%)"); // …a: 0.5
+ * ```
+ */
+export function parseColor(input) {
+    const s = input.trim().toLowerCase();
+    if (!s)
+        return null;
+    const fn = /^(rgba?|oklch)\(\s*([^)]*)\)$/.exec(s);
+    if (!fn)
+        return hexToRgba(s);
+    const [, name, body] = fn;
+    const [main, slashAlpha] = body.split("/").map((p) => p.trim());
+    const parts = main.split(/[\s,]+/).filter(Boolean);
+    const alpha = slashAlpha ?? (parts.length === 4 ? parts[3] : undefined);
+    if (parts.length < 3 || parts.slice(0, 3).some((p) => Number.isNaN(parseFloat(p))))
+        return null;
+    if (name === "oklch") {
+        const l = channel(parts[0], 1);
+        const c = parts[1].endsWith("%") ? (parseFloat(parts[1]) / 100) * 0.4 : parseFloat(parts[1]);
+        const h = parseFloat(parts[2]);
+        return oklchToRgba({ l, c, h, a: alphaOf(alpha) });
+    }
+    return {
+        r: clamp(channel(parts[0], 255), 0, 255),
+        g: clamp(channel(parts[1], 255), 0, 255),
+        b: clamp(channel(parts[2], 255), 0, 255),
+        a: round(alphaOf(alpha), 3),
+    };
+}
+/** Normalises any accepted colour string to lowercase hex, or `null` if it can't be parsed. */
+export function toHex(input, withAlpha) {
+    const c = parseColor(input);
+    return c ? rgbaToHex(c, withAlpha ?? c.a < 1) : null;
+}
+/* ---------------------------------------------------------------- OKLab */
+const toLinear = (v) => {
+    const c = v / 255;
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+};
+const fromLinear = (v) => 255 * (v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055);
+/** sRGB → OKLCH. */
+export function rgbaToOklch({ r, g, b, a }) {
+    const lr = toLinear(r);
+    const lg = toLinear(g);
+    const lb = toLinear(b);
+    const l_ = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+    const m_ = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+    const s_ = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+    const L = 0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_;
+    const A = 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_;
+    const B = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_;
+    const c = Math.sqrt(A * A + B * B);
+    let h = (Math.atan2(B, A) * 180) / Math.PI;
+    if (h < 0)
+        h += 360;
+    return { l: L, c, h: c < 1e-4 ? 0 : h, a };
+}
+/** OKLCH → sRGB, clipped to the sRGB gamut. */
+export function oklchToRgba({ l, c, h, a }) {
+    const hr = (h * Math.PI) / 180;
+    const A = c * Math.cos(hr);
+    const B = c * Math.sin(hr);
+    const l_ = l + 0.3963377774 * A + 0.2158037573 * B;
+    const m_ = l - 0.1055613458 * A - 0.0638541728 * B;
+    const s_ = l - 0.0894841775 * A - 1.291485548 * B;
+    const L = l_ ** 3;
+    const M = m_ ** 3;
+    const S = s_ ** 3;
+    return {
+        r: clamp(fromLinear(4.0767416621 * L - 3.3077115913 * M + 0.2309699292 * S), 0, 255),
+        g: clamp(fromLinear(-1.2684380046 * L + 2.6097574011 * M - 0.3413193965 * S), 0, 255),
+        b: clamp(fromLinear(-0.0041960863 * L - 0.7034186147 * M + 1.707614701 * S), 0, 255),
+        a: clamp(a, 0, 1),
+    };
+}
+/**
+ * Formats a hex value for display / editing.
+ *
+ * ```ts
+ * formatColor("#c6f432", "rgb");   // "rgb(198 244 50)"
+ * formatColor("#c6f432", "oklch"); // "oklch(91.5% 0.205 125.3)"
+ * ```
+ */
+export function formatColor(hex, format = "hex") {
+    const c = parseColor(hex);
+    if (!c)
+        return hex;
+    const alpha = c.a < 1 ? ` / ${round(c.a * 100)}%` : "";
+    if (format === "rgb")
+        return `rgb(${Math.round(c.r)} ${Math.round(c.g)} ${Math.round(c.b)}${alpha})`;
+    if (format === "oklch") {
+        const o = rgbaToOklch(c);
+        return `oklch(${round(o.l * 100, 1)}% ${round(o.c, 3)} ${round(o.h, 1)}${alpha})`;
+    }
+    return rgbaToHex(c);
+}
+/* ---------------------------------------------------------------- Contrast */
+/** WCAG 2 relative luminance (0 = black, 1 = white). Alpha is ignored. */
+export function relativeLuminance({ r, g, b }) {
+    return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+}
+/** Composites a translucent colour over an opaque background. */
+export function blend(fg, bg) {
+    const a = fg.a;
+    return { r: fg.r * a + bg.r * (1 - a), g: fg.g * a + bg.g * (1 - a), b: fg.b * a + bg.b * (1 - a), a: 1 };
+}
+/**
+ * WCAG 2 contrast ratio between two colours (1–21), or `null` if either can't be parsed.
+ * A translucent colour is composited over the other one first.
+ */
+export function contrastRatio(a, b) {
+    const ca = parseColor(a);
+    const cb = parseColor(b);
+    if (!ca || !cb)
+        return null;
+    const bgOpaque = { ...cb, a: 1 };
+    const la = relativeLuminance(ca.a < 1 ? blend(ca, bgOpaque) : ca);
+    const lb = relativeLuminance(bgOpaque);
+    const [hi, lo] = la > lb ? [la, lb] : [lb, la];
+    return (hi + 0.05) / (lo + 0.05);
+}
+/** WCAG 2 rating for a contrast ratio: AAA ≥ 7, AA ≥ 4.5, AA large text ≥ 3. */
+export function contrastLevel(ratio) {
+    if (ratio >= 7)
+        return "AAA";
+    if (ratio >= 4.5)
+        return "AA";
+    if (ratio >= 3)
+        return "AA-large";
+    return "fail";
+}
+/** Black or white — whichever reads better on `background`. */
+export function readableOn(background) {
+    const white = contrastRatio("#ffffff", background) ?? 21;
+    const black = contrastRatio("#000000", background) ?? 21;
+    return black >= white ? "#000000" : "#ffffff";
+}

package/dist/lib/compose-refs.d.ts

@@ -0,0 +1,24 @@
+import * as React from "react";
+type PossibleRef<T> = React.Ref<T> | undefined | null;
+/** Assigns `value` to a callback ref or an object ref. */
+export declare function setRef<T>(ref: PossibleRef<T>, value: T | null): void;
+/**
+ * Combines several refs into one callback ref.
+ *
+ * ```tsx
+ * <input ref={composeRefs(forwardedRef, localRef)} />
+ * ```
+ */
+export declare function composeRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T>;
+/** Memoised `composeRefs` — keeps the same callback while the refs don't change. */
+export declare function useComposedRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T>;
+/**
+ * Joins id lists (e.g. `aria-describedby`) without duplicates or empty entries.
+ * Returns `undefined` when nothing is left, so the attribute is omitted.
+ *
+ * ```ts
+ * mergeIds("title-hint", props["aria-describedby"], error && "title-error"); // "title-hint own-id title-error"
+ * ```
+ */
+export declare function mergeIds(...ids: (string | false | null | undefined)[]): string | undefined;
+export {};

package/dist/lib/compose-refs.js

@@ -0,0 +1,45 @@
+import * as React from "react";
+/** Assigns `value` to a callback ref or an object ref. */
+export function setRef(ref, value) {
+    if (typeof ref === "function")
+        ref(value);
+    else if (ref)
+        ref.current = value;
+}
+/**
+ * Combines several refs into one callback ref.
+ *
+ * ```tsx
+ * <input ref={composeRefs(forwardedRef, localRef)} />
+ * ```
+ */
+export function composeRefs(...refs) {
+    return (node) => {
+        for (const ref of refs)
+            setRef(ref, node);
+    };
+}
+/** Memoised `composeRefs` — keeps the same callback while the refs don't change. */
+export function useComposedRefs(...refs) {
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    return React.useCallback(composeRefs(...refs), refs);
+}
+/**
+ * Joins id lists (e.g. `aria-describedby`) without duplicates or empty entries.
+ * Returns `undefined` when nothing is left, so the attribute is omitted.
+ *
+ * ```ts
+ * mergeIds("title-hint", props["aria-describedby"], error && "title-error"); // "title-hint own-id title-error"
+ * ```
+ */
+export function mergeIds(...ids) {
+    const out = [];
+    for (const group of ids) {
+        if (!group)
+            continue;
+        for (const id of group.split(/\s+/))
+            if (id && !out.includes(id))
+                out.push(id);
+    }
+    return out.length ? out.join(" ") : undefined;
+}

package/dist/lib/data-islands.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Client islands for the server-compatible data-display components (Stat, Delta, Table,
+ * Description list, Item, Activity timeline). Each one is small and only exists because it
+ * needs the locale context, the clock, the clipboard or keyboard state.
+ */
+import * as React from "react";
+import { type ValueFormat } from "./value-format.js";
+export declare const statLabels: {
+    up: string;
+    down: string;
+    flat: string;
+    noData: string;
+    trendUp: string;
+    trendDown: string;
+    trendFlat: string;
+    goal: string;
+    goalReached: string;
+    ofGoal: string;
+};
+export declare const timelineLabels: {
+    today: string;
+    yesterday: string;
+    empty: string;
+    loadMore: string;
+    loading: string;
+    newItems: string;
+    done: string;
+    current: string;
+    upcoming: string;
+    failed: string;
+};
+export declare const descriptionListLabels: {
+    copy: string;
+    copied: string;
+    edit: string;
+    save: string;
+    cancel: string;
+    saving: string;
+    error: string;
+    empty: string;
+};
+export declare const tableLabels: {
+    empty: string;
+};
+declare const DATA_LABELS: {
+    readonly table: {
+        empty: string;
+    };
+    readonly stat: {
+        up: string;
+        down: string;
+        flat: string;
+        noData: string;
+        trendUp: string;
+        trendDown: string;
+        trendFlat: string;
+        goal: string;
+        goalReached: string;
+        ofGoal: string;
+    };
+    readonly timeline: {
+        today: string;
+        yesterday: string;
+        empty: string;
+        loadMore: string;
+        loading: string;
+        newItems: string;
+        done: string;
+        current: string;
+        upcoming: string;
+        failed: string;
+    };
+    readonly descriptionList: {
+        copy: string;
+        copied: string;
+        edit: string;
+        save: string;
+        cancel: string;
+        saving: string;
+        error: string;
+        empty: string;
+    };
+};
+type DataNamespace = keyof typeof DATA_LABELS;
+/** One built-in data-display string, translated through LocaleProvider: `<DataLabel ns="timeline" id="today" />`. */
+export declare function DataLabel<N extends DataNamespace>({ ns, id, vars, override, }: {
+    ns: N;
+    id: keyof (typeof DATA_LABELS)[N] & string;
+    vars?: Record<string, unknown>;
+    override?: Partial<Record<string, string>>;
+}): React.JSX.Element;
+/** A locale-formatted value: `<ValueText value={28412} format="compact" />` → "28.4K". */
+export declare function ValueText({ value, format, options }: {
+    value: number | string;
+    format?: ValueFormat;
+    options?: Intl.NumberFormatOptions;
+}): React.JSX.Element;
+export interface DeltaTextProps {
+    value: number;
+    kind?: "percent" | "number" | "currency";
+    currency?: string;
+    /** Max fraction digits. Default 1 (percent) / 0 (number) / currency default. */
+    precision?: number;
+    /** Full screen-reader text, e.g. "Up 12.4% vs last month". */
+    srLabel?: string;
+    /** Appended to the screen-reader text ("vs previous 30 days"). */
+    srSuffix?: string;
+    labels?: Partial<typeof statLabels>;
+}
+/** Signed delta text ("+12.4%", "+%12,4" in tr-TR) with a spoken sentence for screen readers. */
+export declare function DeltaText({ value, kind, currency, precision, srLabel, srSuffix, labels }: DeltaTextProps): React.JSX.Element;
+/** Progress-to-goal caption: "Goal $46,800" + "27%". */
+export declare function StatGoalText({ value, target, format, labels }: {
+    value: number;
+    target: number;
+    format?: ValueFormat;
+    labels?: Partial<typeof statLabels>;
+}): React.JSX.Element;
+/**
+ * The current time, refreshed by a shared ticker. `null` during SSR and hydration, so the
+ * server and the first client render agree; `fixed` pins the clock (docs, tests).
+ */
+export declare function useNow(fixed?: Date | string | number): number | null;
+export interface RelativeTimeProps extends Omit<React.TimeHTMLAttributes<HTMLElement>, "children"> {
+    value: Date | string | number;
+    /** Fix the reference time (docs, tests, server-rendered snapshots). */
+    now?: Date | string | number;
+    /** `"long"` "4 minutes ago" · `"short"` "4 min. ago" · `"narrow"`. Default `"long"`. */
+    styleType?: Intl.RelativeTimeFormatStyle;
+    /** `"relative"` (default) · `"time"` time of day ("9:30 AM") · `"datetime"` full date and time. */
+    display?: "relative" | "time" | "datetime";
+}
+/**
+ * `<time>` with a relative label ("4 minutes ago", "yesterday") and the full date as `title`.
+ * Server render shows the absolute time; the client upgrades it and keeps it fresh.
+ */
+export declare function RelativeTime({ value, now, styleType, display, className, ...props }: RelativeTimeProps): React.JSX.Element;
+/** Day heading of a grouped timeline: "Today", "Yesterday", "Monday, Nov 8". */
+export declare function TimelineDayLabel({ date, now, labels }: {
+    date: string;
+    now?: Date | string | number;
+    labels?: Partial<typeof timelineLabels>;
+}): React.JSX.Element;
+export interface CopyValueButtonProps {
+    /** Text written to the clipboard. */
+    text: string;
+    /** What is copied, for the accessible name ("Copy IBAN"). */
+    label: string;
+    labels?: Partial<typeof descriptionListLabels>;
+    className?: string;
+    onCopied?: (text: string) => void;
+}
+/** Small copy-to-clipboard button with a "Copied" confirmation (visible + announced). */
+export declare function CopyValueButton({ text, label, labels, className, onCopied }: CopyValueButtonProps): React.JSX.Element;
+export interface DescriptionEditableProps {
+    /** Current value (the editor starts from it). */
+    value: string;
+    /** Called with the new value. Return a promise to show "Saving…"; reject to show the error. */
+    onSave: (value: string) => void | Promise<void>;
+    /** Field name for the accessible names ("Edit Phone"). */
+    label: string;
+    /** What to show when not editing. Default: the value, or "Not set". */
+    display?: React.ReactNode;
+    inputType?: "text" | "email" | "tel" | "url" | "number";
+    placeholder?: string;
+    /** Disable editing (read-only look). */
+    disabled?: boolean;
+    labels?: Partial<typeof descriptionListLabels>;
+    className?: string;
+}
+/**
+ * Click-to-edit value for Description list rows. The value is a button ("Edit Phone");
+ * Enter saves, Escape cancels, focus returns to the value afterwards.
+ */
+export declare function DescriptionEditable({ value, onSave, label, display, inputType, placeholder, disabled, labels, className }: DescriptionEditableProps): React.JSX.Element;
+export interface ItemListboxProps extends Omit<React.HTMLAttributes<HTMLUListElement>, "defaultValue" | "onChange"> {
+    selectable: "single" | "multiple";
+    value?: string[];
+    defaultValue?: string[];
+    onValueChange?: (value: string[]) => void;
+}
+/**
+ * Listbox behaviour for `ItemList selectable`: roving focus, ↑ ↓ Home End, Space/Enter toggles,
+ * click selects. Direct `Item` children with a `value` become options.
+ */
+export declare const ItemListbox: React.ForwardRefExoticComponent<ItemListboxProps & React.RefAttributes<HTMLUListElement>>;
+/** "Load older activity" button with a busy state while `onLoadMore` resolves. */
+export declare function LoadMoreButton({ onLoadMore, label, className, labels }: {
+    onLoadMore: () => void | Promise<void>;
+    label?: string;
+    className?: string;
+    labels?: Partial<typeof timelineLabels>;
+}): React.JSX.Element;
+export {};