@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/components/sla-timer.js

@@ -0,0 +1,142 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cva } from "class-variance-authority";
+import { AlarmClock, CircleCheck, CircleX, Pause, Timer } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { useFormat } from "../lib/locale.js";
+export const slaTimerLabels = {
+    dueIn: "Due in {time}",
+    overdue: "Overdue by {time}",
+    met: "Met with {time} to spare",
+    missed: "Missed by {time}",
+    paused: "Paused with {time} left",
+    pausedOverdue: "Paused, {time} over",
+    stateOnTrack: "On track",
+    stateAtRisk: "At risk",
+    stateBreached: "Breached",
+    stateMet: "Met",
+    stateMissed: "Missed",
+    statePaused: "Paused",
+};
+const ms = (v) => (v instanceof Date ? v.getTime() : typeof v === "number" ? v : Date.parse(v));
+/**
+ * Pure SLA state: `on-track`, `at-risk` (less than `warnAt` of the window or `warnMinutes`
+ * left), `breached`, and the final `met` / `missed` once `completedAt` is set.
+ */
+export function slaState({ due, start, completedAt, pausedAt, now, warnAt = 0.25, warnMinutes }) {
+    const dueMs = ms(due);
+    const startMs = start != null ? ms(start) : null;
+    const end = completedAt != null ? ms(completedAt) : pausedAt != null ? ms(pausedAt) : now;
+    const remaining = dueMs - end;
+    const used = startMs != null && dueMs > startMs ? (end - startMs) / (dueMs - startMs) : null;
+    if (completedAt != null)
+        return { state: remaining >= 0 ? "met" : "missed", remaining, used };
+    if (pausedAt != null)
+        return { state: "paused", remaining, used };
+    if (remaining < 0)
+        return { state: "breached", remaining, used };
+    const threshold = warnMinutes != null ? warnMinutes * 60_000 : startMs != null ? (dueMs - startMs) * warnAt : 30 * 60_000;
+    return { state: remaining <= threshold ? "at-risk" : "on-track", remaining, used };
+}
+const slaTimerVariants = cva("inline-flex items-center gap-1.5 whitespace-nowrap font-medium tabular", {
+    variants: {
+        variant: {
+            /** Tinted pill — list rows, inbox items. */
+            badge: "h-6 rounded-full px-2 text-xs [&_svg]:size-3.5",
+            /** Text with an icon — headers, side panels. */
+            inline: "text-[13px] [&_svg]:size-4",
+        },
+        state: {
+            "on-track": "",
+            "at-risk": "",
+            breached: "",
+            met: "",
+            missed: "",
+            paused: "",
+        },
+    },
+    compoundVariants: [
+        { variant: "badge", state: "on-track", class: "bg-selected text-fg-muted" },
+        { variant: "badge", state: "at-risk", class: "tone-warning tone-soft" },
+        { variant: "badge", state: "breached", class: "tone-danger tone-soft" },
+        { variant: "badge", state: "met", class: "tone-success tone-soft" },
+        { variant: "badge", state: "missed", class: "tone-danger tone-soft" },
+        { variant: "badge", state: "paused", class: "border border-dashed border-field-border text-fg-muted" },
+        { variant: "inline", state: "on-track", class: "text-fg" },
+        { variant: "inline", state: "at-risk", class: "tone-warning [color:color-mix(in_srgb,var(--tone)_var(--tone-ink-mix,100%),var(--fg))]" },
+        { variant: "inline", state: "breached", class: "tone-danger [color:color-mix(in_srgb,var(--tone)_var(--tone-ink-mix,100%),var(--fg))]" },
+        { variant: "inline", state: "met", class: "tone-success [color:color-mix(in_srgb,var(--tone)_var(--tone-ink-mix,100%),var(--fg))]" },
+        { variant: "inline", state: "missed", class: "tone-danger [color:color-mix(in_srgb,var(--tone)_var(--tone-ink-mix,100%),var(--fg))]" },
+        { variant: "inline", state: "paused", class: "text-fg-muted" },
+    ],
+    defaultVariants: { variant: "badge", state: "on-track" },
+});
+const icons = {
+    "on-track": Timer,
+    "at-risk": AlarmClock,
+    breached: AlarmClock,
+    met: CircleCheck,
+    missed: CircleX,
+    paused: Pause,
+};
+const barColor = {
+    "on-track": "bg-accent",
+    "at-risk": "bg-warning",
+    breached: "bg-danger",
+    met: "bg-success",
+    missed: "bg-danger",
+    paused: "bg-fg-subtle",
+};
+/** Ticks once per second near the deadline, every 15 s otherwise; static when `now` is passed. */
+function useNow(fixed, remaining, live) {
+    const [now, setNow] = React.useState(() => fixed ?? Date.now());
+    React.useEffect(() => {
+        if (fixed != null || !live)
+            return;
+        let id = 0;
+        const tick = () => {
+            setNow(Date.now());
+            const left = Math.abs(remaining());
+            id = window.setTimeout(tick, left < 3_600_000 ? 1000 - (Date.now() % 1000) : 15_000);
+        };
+        tick();
+        return () => window.clearTimeout(id);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [fixed, live]);
+    return fixed ?? now;
+}
+/**
+ * Countdown to a service-level deadline — first response, resolution, delivery window.
+ * Colour follows the state (on track → at risk → breached), and it freezes as met/missed
+ * once `completedAt` is set. `role="timer"` with a full sentence for screen readers.
+ *
+ * ```tsx
+ * <SlaTimer label="First response" start={ticket.createdAt} due={ticket.firstResponseDue} />
+ * <SlaTimer variant="bar" label="Resolution" start={t.createdAt} due={t.resolveDue} completedAt={t.solvedAt} />
+ * ```
+ */
+export const SlaTimer = React.forwardRef(function SlaTimer({ due, start, completedAt, pausedAt, now: fixedNow, warnAt, warnMinutes, variant = "badge", label, seconds = true, hideIcon, labels, className, ...props }, ref) {
+    const t = useLabels("slaTimer", slaTimerLabels, labels);
+    const f = useFormat();
+    const frozen = completedAt != null || pausedAt != null;
+    const now = useNow(fixedNow, () => ms(due) - Date.now(), !frozen);
+    const m = slaState({ due, start, completedAt, pausedAt, now, warnAt, warnMinutes });
+    const abs = Math.abs(m.remaining);
+    const time = f.duration(Math.floor(abs / 1000), { smallest: seconds && abs < 3_600_000 ? "s" : "min", maxParts: 2 });
+    const sentence = m.state === "met" ? t("met", { time })
+        : m.state === "missed" ? t("missed", { time })
+            : m.state === "paused" ? t(m.remaining >= 0 ? "paused" : "pausedOverdue", { time })
+                : m.state === "breached" ? t("overdue", { time })
+                    : t("dueIn", { time });
+    const stateName = t({ "on-track": "stateOnTrack", "at-risk": "stateAtRisk", breached: "stateBreached", met: "stateMet", missed: "stateMissed", paused: "statePaused" }[m.state]);
+    const spoken = `${label ? `${label}: ` : ""}${sentence}`;
+    const Icon = icons[m.state];
+    const visible = m.state === "breached" || m.state === "missed" ? `−${time}` : m.state === "met" ? stateName : time;
+    if (variant === "bar") {
+        const fill = m.used == null ? (m.remaining < 0 ? 1 : 0) : Math.max(0, Math.min(1, m.used));
+        return (_jsxs("span", { ref: ref, role: "timer", "aria-label": spoken, suppressHydrationWarning: true, "data-slot": "sla-timer", "data-state": m.state, className: cn("grid w-full min-w-40 gap-1.5", className), ...props, children: [_jsxs("span", { "aria-hidden": "true", className: "flex items-baseline justify-between gap-3 text-[13px]", children: [_jsx("span", { className: "truncate text-fg-muted", children: label ?? stateName }), _jsx("span", { suppressHydrationWarning: true, className: cn("font-medium tabular", slaTimerVariants({ variant: "inline", state: m.state })), children: visible })] }), _jsx("span", { "aria-hidden": "true", className: "relative h-1 overflow-hidden rounded-full bg-track", children: _jsx("span", { suppressHydrationWarning: true, className: cn("absolute inset-0 origin-left rounded-full transition-transform duration-500 motion-reduce:transition-none rtl:origin-right", barColor[m.state]), style: { transform: `scaleX(${fill})` } }) })] }));
+    }
+    return (_jsxs("span", { ref: ref, role: "timer", "aria-label": spoken, title: spoken, suppressHydrationWarning: true, "data-slot": "sla-timer", "data-state": m.state, className: cn(slaTimerVariants({ variant, state: m.state }), className), ...props, children: [hideIcon ? null : _jsx(Icon, { "aria-hidden": true }), _jsx("span", { "aria-hidden": "true", suppressHydrationWarning: true, children: visible })] }));
+});

package/dist/components/slider.d.ts

@@ -0,0 +1,57 @@
+import * as React from "react";
+import { Slider as SliderPrimitive } from "radix-ui";
+declare const sliderLabels: {
+    min: string;
+    max: string;
+    value: string;
+};
+export type SliderLabels = typeof sliderLabels;
+export type SliderMark = number | {
+    value: number;
+    label: React.ReactNode;
+};
+export interface SliderProps extends Omit<React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root>, "value" | "defaultValue" | "onValueChange" | "onValueCommit" | "name" | "children"> {
+    /** One number = single slider, two = range. */
+    value?: number[];
+    defaultValue?: number[];
+    /** Fires continuously while dragging. */
+    onValueChange?: (value: number[]) => void;
+    /** Fires on release / key up — wire filters and server requests here. */
+    onValueCommit?: (value: number[]) => void;
+    /** Ticks under the track; objects get a text label. */
+    marks?: SliderMark[];
+    /** Custom formatter for the value bubble, `aria-valuetext` and marks. Wins over `formatOptions`. */
+    formatValue?: (value: number) => string;
+    /** `Intl.NumberFormat` options applied with the provider locale, e.g. `{ style: "currency", currency: "USD" }`. */
+    formatOptions?: Intl.NumberFormatOptions;
+    /** Value bubble above the thumb: on hover/focus/drag, always, or never. Default `"hover"`. */
+    showValue?: "never" | "hover" | "always";
+    /** Number inputs under the track, synced with the thumbs (commit on blur / Enter). */
+    withInputs?: boolean;
+    size?: "sm" | "md";
+    /** Accessible name per thumb. Range default: "Minimum" / "Maximum" (dictionary `slider`). */
+    thumbLabels?: string[];
+    /** Form name. Range values submit as repeated entries (`formData.getAll(name)`). */
+    name?: string;
+    /** Separate form names per thumb, e.g. `["priceMin", "priceMax"]`. */
+    names?: string[];
+    invalid?: boolean;
+    /** Focusable, but the value can't change (`aria-readonly`). */
+    readOnly?: boolean;
+    required?: boolean;
+    labels?: Partial<SliderLabels>;
+}
+/**
+ * Pick a number or a range by dragging: price filter, salary band, deal probability, opacity.
+ * Radix Slider (WAI-ARIA: arrows ± step, PageUp/PageDown ± 10 steps, Home/End). Values are
+ * formatted with the provider locale (`aria-valuetext` included).
+ *
+ * ```tsx
+ * <Field label="Price per night">
+ *   <Slider defaultValue={[80, 240]} min={0} max={500} step={10} formatOptions={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }} withInputs />
+ * </Field>
+ * <Slider defaultValue={[60]} marks={[0, 25, 50, 75, 100]} aria-label="Deal probability" />
+ * ```
+ */
+export declare const Slider: React.ForwardRefExoticComponent<SliderProps & React.RefAttributes<HTMLSpanElement>>;
+export {};

package/dist/components/slider.js

@@ -0,0 +1,133 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Slider as SliderPrimitive } from "radix-ui";
+import { cn } from "../lib/cn.js";
+import { mergeIds } from "../lib/compose-refs.js";
+import { FieldContextReset, useFieldContext } from "../lib/field-context.js";
+import { useLabels } from "../lib/labels.js";
+import { useFormat } from "../lib/locale.js";
+import { useControllableState } from "../lib/use-controllable-state.js";
+import { Input } from "./input.js";
+const sliderLabels = {
+    min: "Minimum",
+    max: "Maximum",
+    value: "Value {index} of {total}",
+};
+const clamp = (n, min, max) => Math.min(max, Math.max(min, n));
+const decimalsOf = (n) => {
+    const s = String(n);
+    const i = s.indexOf(".");
+    return i === -1 ? 0 : s.length - i - 1;
+};
+const snap = (n, min, step) => {
+    const d = decimalsOf(step);
+    return Number((Math.round((n - min) / step) * step + min).toFixed(d));
+};
+/**
+ * Pick a number or a range by dragging: price filter, salary band, deal probability, opacity.
+ * Radix Slider (WAI-ARIA: arrows ± step, PageUp/PageDown ± 10 steps, Home/End). Values are
+ * formatted with the provider locale (`aria-valuetext` included).
+ *
+ * ```tsx
+ * <Field label="Price per night">
+ *   <Slider defaultValue={[80, 240]} min={0} max={500} step={10} formatOptions={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }} withInputs />
+ * </Field>
+ * <Slider defaultValue={[60]} marks={[0, 25, 50, 75, 100]} aria-label="Deal probability" />
+ * ```
+ */
+export const Slider = React.forwardRef(function Slider({ value: valueProp, defaultValue, onValueChange, onValueCommit, min = 0, max = 100, step = 1, marks, formatValue, formatOptions, showValue = "hover", withInputs, size = "md", thumbLabels, name, names, invalid, readOnly, required, disabled, labels, id, className, orientation = "horizontal", "aria-label": ariaLabel, "aria-labelledby": labelledBy, "aria-describedby": describedBy, ...props }, ref) {
+    const field = useFieldContext();
+    const t = useLabels("slider", sliderLabels, labels);
+    const f = useFormat();
+    const [value, setValue] = useControllableState({
+        value: valueProp,
+        defaultValue: defaultValue ?? [min],
+        onChange: onValueChange,
+        name: "Slider",
+    });
+    const [dragging, setDragging] = React.useState(false);
+    const fmt = React.useCallback((n) => (formatValue ? formatValue(n) : f.number(n, formatOptions)), [formatValue, f, formatOptions]);
+    const isDisabled = disabled ?? field?.disabled;
+    const isReadOnly = readOnly ?? field?.readOnly;
+    const isInvalid = invalid ?? field?.invalid;
+    const isRequired = required ?? field?.required;
+    const formName = name ?? field?.name;
+    const autoId = React.useId().replace(/:/g, "");
+    const rootId = id ?? field?.id;
+    const groupLabel = labelledBy ?? field?.labelId;
+    const count = value.length;
+    const thumbName = (i) => {
+        const own = thumbLabels?.[i];
+        if (own)
+            return own;
+        if (count === 2)
+            return i === 0 ? t("min") : t("max");
+        if (count > 2)
+            return t("value", { index: i + 1, total: count });
+        return undefined;
+    };
+    const commit = (next) => {
+        if (isReadOnly)
+            return;
+        setValue(next);
+        onValueCommit?.(next);
+    };
+    const markList = (marks ?? []).map((m) => (typeof m === "number" ? { value: m, label: undefined } : m));
+    const pct = (n) => ((clamp(n, min, max) - min) / (max - min || 1)) * 100;
+    const vertical = orientation === "vertical";
+    // Radix keeps thumbs inside the track (half a thumb in at the ends); marks follow the same curve.
+    const half = size === "sm" ? 7 : 9;
+    const atThumb = (n) => {
+        const p = pct(n);
+        return `calc(${p}% + ${(half * (1 - p / 50)).toFixed(2)}px)`;
+    };
+    return (_jsxs("div", { "data-slot": "slider-field", "data-size": size, className: cn("grid gap-3", vertical && "h-full w-fit", className), "data-disabled": isDisabled ? "" : undefined, children: [_jsxs(SliderPrimitive.Root, { ...props, ref: ref, id: rootId, "data-slot": "slider", "data-readonly": isReadOnly ? "" : undefined, "data-dragging": dragging ? "" : undefined, "aria-invalid": isInvalid || undefined, min: min, max: max, step: step, orientation: orientation, disabled: isDisabled, value: value, onValueChange: (next) => {
+                    if (isReadOnly)
+                        return;
+                    setDragging(true);
+                    setValue(next);
+                }, onValueCommit: (next) => {
+                    setDragging(false);
+                    if (!isReadOnly)
+                        onValueCommit?.(next);
+                }, onPointerUp: (e) => {
+                    setDragging(false);
+                    props.onPointerUp?.(e);
+                }, className: cn("group/slider relative flex touch-none select-none items-center data-disabled:opacity-45", vertical ? "h-full min-h-32 w-5 flex-col" : "h-5 w-full", isReadOnly && "cursor-default", 
+                // room for the value bubble
+                showValue === "always" && !vertical && "mt-7", markList.length > 0 && !vertical && (markList.some((m) => m.label != null) ? "mb-7" : "mb-2")), children: [_jsx(SliderPrimitive.Track, { "data-slot": "slider-track", className: cn("relative grow overflow-hidden rounded-full bg-track", vertical ? (size === "sm" ? "w-1" : "w-1.5") : size === "sm" ? "h-1" : "h-1.5", "group-aria-invalid/slider:bg-[color-mix(in_srgb,var(--danger)_25%,transparent)]"), children: _jsx(SliderPrimitive.Range, { "data-slot": "slider-range", className: cn("absolute rounded-full bg-accent-ink", vertical ? "w-full" : "h-full", "group-aria-invalid/slider:bg-danger group-data-readonly/slider:bg-fg-subtle") }) }), markList.length ? (_jsx("div", { "aria-hidden": true, className: cn("pointer-events-none absolute", vertical ? "inset-y-0 start-full ms-1.5" : "inset-x-0 top-full mt-1"), children: markList.map((m) => {
+                            const active = count === 1 ? m.value <= value[0] : m.value >= Math.min(...value) && m.value <= Math.max(...value);
+                            return (_jsxs("span", { "data-active": active ? "" : undefined, className: cn("absolute flex items-center gap-1", vertical ? "-translate-y-1/2 flex-row" : "-translate-x-1/2 flex-col rtl:translate-x-1/2"), style: vertical ? { bottom: atThumb(m.value) } : { insetInlineStart: atThumb(m.value) }, children: [_jsx("span", { className: cn("rounded-full", vertical ? "h-px w-1.5" : "h-1.5 w-px", active ? "bg-accent-ink" : "bg-field-border-hover") }), m.label != null ? _jsx("span", { className: "whitespace-nowrap font-mono text-[11px] tabular text-fg-subtle", children: m.label }) : null] }, m.value));
+                        }) })) : null, value.map((v, i) => {
+                        const own = thumbName(i);
+                        const labelSpanId = own && groupLabel ? `${autoId}-thumb-${i}` : undefined;
+                        return (_jsxs(SliderPrimitive.Thumb, { "data-slot": "slider-thumb", name: names?.[i] ?? formName, "aria-label": labelSpanId ? undefined : (own ?? ariaLabel), "aria-labelledby": labelSpanId ? `${groupLabel} ${labelSpanId}` : own ? undefined : groupLabel, "aria-describedby": mergeIds(field?.describedBy, describedBy), "aria-valuetext": fmt(v), "aria-invalid": isInvalid || undefined, "aria-readonly": isReadOnly || undefined, "aria-required": isRequired || undefined, className: cn("group/thumb relative block rounded-full border-2 border-accent-ink bg-popover-nested outline-none", "shadow-[0_1px_3px_rgb(0_0_0/0.18)] transition-[transform,box-shadow] duration-150", "hover:shadow-[0_0_0_5px_var(--accent-soft),0_1px_3px_rgb(0_0_0/0.18)]", "focus-visible:shadow-[0_0_0_2px_var(--scene),0_0_0_4px_var(--ring)]", "motion-safe:active:scale-110 group-data-dragging/slider:cursor-grabbing", "group-aria-invalid/slider:border-danger group-data-readonly/slider:border-fg-subtle group-data-disabled/slider:cursor-not-allowed", size === "sm" ? "size-3.5" : "size-[18px]", isReadOnly ? "cursor-default" : "cursor-grab"), children: [labelSpanId ? (_jsx("span", { id: labelSpanId, hidden: true, children: own })) : null, showValue !== "never" ? (_jsx("span", { "aria-hidden": true, "data-slot": "slider-value", className: cn("pointer-events-none absolute whitespace-nowrap rounded-[6px] bg-fg px-1.5 py-0.5 font-mono text-[11px] font-medium tabular text-scene", "transition-[opacity,transform] duration-150", vertical ? "start-full top-1/2 ms-3 -translate-y-1/2" : "bottom-full left-1/2 mb-2.5 -translate-x-1/2", showValue === "hover" &&
+                                        "opacity-0 scale-95 group-hover/thumb:opacity-100 group-hover/thumb:scale-100 group-focus-visible/thumb:opacity-100 group-focus-visible/thumb:scale-100 group-data-dragging/slider:opacity-100 group-data-dragging/slider:scale-100"), children: fmt(v) })) : null] }, i));
+                    })] }), withInputs && !vertical ? (_jsx(FieldContextReset, { children: _jsx(SliderInputs, { value: value, min: min, max: max, step: step, size: size, disabled: isDisabled, readOnly: isReadOnly, names: value.map((_, i) => thumbName(i) ?? ariaLabel ?? t("value", { index: i + 1, total: count })), groupLabel: groupLabel, idBase: autoId, onCommit: commit }) })) : null] }));
+});
+function SliderInputs({ value, min, max, step, size, disabled, readOnly, names, groupLabel, idBase, onCommit, }) {
+    const [drafts, setDrafts] = React.useState(null);
+    const shown = drafts ?? value.map(String);
+    const apply = (i, raw) => {
+        setDrafts(null);
+        const n = Number(raw.replace(",", "."));
+        if (raw.trim() === "" || Number.isNaN(n))
+            return;
+        const next = [...value];
+        const lo = i > 0 ? next[i - 1] : min;
+        const hi = i < next.length - 1 ? next[i + 1] : max;
+        next[i] = clamp(snap(n, min, step), lo, hi);
+        onCommit(next);
+    };
+    return (_jsx("div", { "data-slot": "slider-inputs", className: "flex items-center gap-2", children: value.map((_, i) => (_jsxs(React.Fragment, { children: [i > 0 ? (_jsx("span", { "aria-hidden": true, className: "h-px w-3 shrink-0 bg-field-border" })) : null, _jsx("span", { id: `${idBase}-input-${i}`, hidden: true, children: names[i] }), _jsx(Input, { type: "number", inputMode: "decimal", size: size === "sm" ? "sm" : "md", min: min, max: max, step: step, disabled: disabled, readOnly: readOnly, "aria-labelledby": mergeIds(groupLabel, `${idBase}-input-${i}`), value: shown[i] ?? "", onChange: (e) => {
+                        const next = [...shown];
+                        next[i] = e.currentTarget.value;
+                        setDrafts(next);
+                    }, onBlur: (e) => apply(i, e.currentTarget.value), onKeyDown: (e) => {
+                        if (e.key === "Enter") {
+                            e.preventDefault();
+                            apply(i, e.currentTarget.value);
+                        }
+                    }, className: "w-28 min-w-0 flex-1 sm:flex-none", inputClassName: "tabular font-mono text-[13px]" })] }, i))) }));
+}

package/dist/components/slug-input.d.ts

@@ -0,0 +1,69 @@
+import * as React from "react";
+declare const slugLabels: {
+    edit: string;
+    editSlug: string;
+    done: string;
+    cancel: string;
+    auto: string;
+    autoHint: string;
+    regenerate: string;
+    checking: string;
+    available: string;
+    taken: string;
+    useSuggestion: string;
+    empty: string;
+    slug: string;
+};
+export type SlugInputLabels = typeof slugLabels;
+export interface SlugInputProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "defaultValue" | "onChange"> {
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (slug: string) => void;
+    /** Text the slug is derived from (the title) until the user edits the slug. */
+    source?: string;
+    /** `true` = manual: stops following `source`. Saved content should start locked. */
+    locked?: boolean;
+    /** Default: `true` when there is an initial slug, else `false` (auto). */
+    defaultLocked?: boolean;
+    onLockedChange?: (locked: boolean) => void;
+    /** Shown before the slug: `"vamos.ist/blog/"`. */
+    prefix?: string;
+    /** Default 80. Cut at a word boundary when possible. */
+    maxLength?: number;
+    /** Transliteration rules. Default: the LocaleProvider's locale. */
+    locale?: string;
+    /**
+     * Async uniqueness check, debounced. Resolve `true` when free, or a message ("Used by
+     * “Spring menu”") when not. The signal aborts when the slug changes again.
+     */
+    validate?: (slug: string, signal: AbortSignal) => Promise<string | true>;
+    /** Offer a free alternative after a failed check ("spring-menu-2"). */
+    suggestUnique?: (slug: string) => Promise<string>;
+    /** Debounce for `validate`, ms. Default 350. */
+    validateDelay?: number;
+    /** `"field"`: always an input (default). `"permalink"`: a link with "Edit" that opens the input inline. */
+    variant?: "field" | "permalink";
+    /** Link target for the permalink view. Default: `prefix + slug` when the prefix looks like a URL. */
+    href?: string;
+    size?: "sm" | "md" | "lg";
+    name?: string;
+    id?: string;
+    disabled?: boolean;
+    invalid?: boolean;
+    placeholder?: string;
+    labels?: Partial<SlugInputLabels>;
+    "aria-label"?: string;
+    "aria-describedby"?: string;
+}
+/**
+ * URL slug derived from a title, with locale transliteration ("İşe Alım & Oryantasyon" →
+ * `ise-alim-ve-oryantasyon` in Turkish), a lock once edited by hand, and an optional async
+ * uniqueness check with a suggested alternative.
+ *
+ * ```tsx
+ * <Field label="URL"><SlugInput source={title} prefix="vamos.ist/blog/" validate={checkSlug} /></Field>
+ * <SlugInput variant="permalink" source={title} prefix="https://vamos.ist/blog/" />
+ * ```
+ */
+export declare const SlugInput: React.ForwardRefExoticComponent<SlugInputProps & React.RefAttributes<HTMLInputElement>>;
+export {};

package/dist/components/slug-input.js

@@ -0,0 +1,201 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { Check, CircleAlert, Link2, Pencil, RefreshCw } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { mergeIds, useComposedRefs } from "../lib/compose-refs.js";
+import { useFieldContext } from "../lib/field-context.js";
+import { useLabels } from "../lib/labels.js";
+import { useLocale } from "../lib/locale.js";
+import { slugify } from "../lib/text.js";
+import { useControllableState, useLatest } from "../lib/use-controllable-state.js";
+import { useFormattedInput } from "../lib/use-formatted-input.js";
+import { Button } from "./button.js";
+import { Input } from "./input.js";
+import { Spinner } from "./spinner.js";
+import { WithoutFieldName } from "./formatted-input.js";
+const slugLabels = {
+    edit: "Edit",
+    editSlug: "Edit URL",
+    done: "Done",
+    cancel: "Cancel",
+    auto: "Auto",
+    autoHint: "Follows the title until you edit it",
+    regenerate: "Regenerate from title",
+    checking: "Checking availability…",
+    available: "Available",
+    taken: "This URL is already in use",
+    useSuggestion: "Use {slug}",
+    empty: "Add a title to create the URL",
+    slug: "URL slug",
+};
+/**
+ * URL slug derived from a title, with locale transliteration ("İşe Alım & Oryantasyon" →
+ * `ise-alim-ve-oryantasyon` in Turkish), a lock once edited by hand, and an optional async
+ * uniqueness check with a suggested alternative.
+ *
+ * ```tsx
+ * <Field label="URL"><SlugInput source={title} prefix="vamos.ist/blog/" validate={checkSlug} /></Field>
+ * <SlugInput variant="permalink" source={title} prefix="https://vamos.ist/blog/" />
+ * ```
+ */
+export const SlugInput = React.forwardRef(function SlugInput(props, forwardedRef) {
+    const { value, defaultValue, onValueChange, source, locked: lockedProp, defaultLocked, onLockedChange, prefix, maxLength = 80, locale: localeProp, validate, suggestUnique, validateDelay = 350, variant = "field", href, size, name, id, disabled, invalid, placeholder, labels, className, "aria-label": ariaLabel, "aria-describedby": describedByProp, ...rest } = props;
+    const { locale: providerLocale } = useLocale();
+    const locale = localeProp ?? providerLocale;
+    const t = useLabels("slug", slugLabels, labels);
+    const field = useFieldContext();
+    const submitName = name ?? field?.name;
+    const messageId = React.useId();
+    const initial = value ?? defaultValue ?? "";
+    const [slug, setSlug] = useControllableState({ value, defaultValue: defaultValue ?? "", onChange: onValueChange, name: "SlugInput" });
+    const [locked, setLocked] = useControllableState({ value: lockedProp, defaultValue: defaultLocked ?? initial !== "", onChange: onLockedChange, name: "SlugInput" });
+    const derive = React.useCallback((s) => slugify(s, { locale, maxLength }), [locale, maxLength]);
+    // Follow the source while unlocked.
+    React.useEffect(() => {
+        if (locked || source === undefined)
+            return;
+        const next = derive(source);
+        if (next !== slug)
+            setSlug(next);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [source, locked, derive]);
+    /* ---------------- typing (sanitised live, caret kept) ---------------- */
+    const accept = (ch) => /^[\p{L}\p{N}\s_-]$/u.test(ch);
+    const sanitize = (typed) => {
+        const trailing = /[\s_-]$/.test(typed);
+        let s = slugify(typed, { locale, maxLength });
+        if (trailing && s && s.length < maxLength)
+            s += "-";
+        return s;
+    };
+    const engine = useFormattedInput({
+        value: slug,
+        accept,
+        format: sanitize,
+        parse: (d) => d.replace(/-+$/, ""),
+        toDisplay: (raw) => raw ?? "",
+        formatOnBlur: (d) => d.replace(/-+$/, ""),
+        onValueChange: (raw) => {
+            setSlug(raw ?? "");
+            if (!locked)
+                setLocked(true);
+        },
+    });
+    const ref = useComposedRefs(forwardedRef, engine.ref);
+    /* ---------------- uniqueness ---------------- */
+    const [check, setCheck] = React.useState({ state: "idle" });
+    const validateRef = useLatest(validate);
+    const suggestRef = useLatest(suggestUnique);
+    React.useEffect(() => {
+        const fn = validateRef.current;
+        if (!fn || !slug) {
+            setCheck({ state: "idle" });
+            return;
+        }
+        const ac = new AbortController();
+        setCheck({ state: "checking" });
+        const timer = setTimeout(async () => {
+            try {
+                const res = await fn(slug, ac.signal);
+                if (ac.signal.aborted)
+                    return;
+                if (res === true) {
+                    setCheck({ state: "ok" });
+                    return;
+                }
+                const message = typeof res === "string" && res ? res : t("taken");
+                setCheck({ state: "error", message });
+                const sug = suggestRef.current;
+                if (sug) {
+                    const suggestion = await sug(slug);
+                    if (!ac.signal.aborted && suggestion && suggestion !== slug)
+                        setCheck({ state: "error", message, suggestion });
+                }
+            }
+            catch {
+                if (!ac.signal.aborted)
+                    setCheck({ state: "idle" });
+            }
+        }, validateDelay);
+        return () => {
+            ac.abort();
+            clearTimeout(timer);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [slug, validateDelay]);
+    const regenerate = () => {
+        setLocked(false);
+        if (source !== undefined)
+            setSlug(derive(source));
+    };
+    const applySuggestion = (s) => {
+        setSlug(s);
+        setLocked(true);
+        engine.ref.current?.focus();
+    };
+    const isInvalid = invalid || check.state === "error";
+    const canRegenerate = locked && source !== undefined && derive(source) !== slug && !!derive(source);
+    const status = check.state === "checking" ? (_jsx(Spinner, { size: "xs", className: "text-fg-subtle" })) : check.state === "ok" ? (_jsx(Check, { "aria-hidden": true, className: "size-3.5 text-success" })) : check.state === "error" ? (_jsx(CircleAlert, { "aria-hidden": true, className: "size-3.5 text-danger" })) : null;
+    const lockControl = !locked && source !== undefined ? (_jsx("span", { "data-slot": "slug-input-auto", title: t("autoHint"), className: "me-1.5 inline-flex h-5 items-center rounded-full bg-accent-soft px-2 text-[11px] font-medium text-accent-ink", children: t("auto") })) : canRegenerate && !disabled ? (_jsx("button", { type: "button", "data-slot": "slug-input-regenerate", onClick: regenerate, "aria-label": t("regenerate"), title: t("regenerate"), className: "me-1 inline-flex size-7 items-center justify-center rounded-ui-sm text-fg-subtle transition-colors hover:bg-hover hover:text-fg focus-ring [&_svg]:size-3.5", children: _jsx(RefreshCw, { "aria-hidden": true, className: "rtl:-scale-x-100" }) })) : null;
+    const message = check.state === "error" ? (_jsxs("p", { id: messageId, "data-slot": "slug-input-message", className: "flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-danger", children: [_jsx("span", { children: check.message }), check.suggestion ? (_jsx("button", { type: "button", onClick: () => applySuggestion(check.suggestion), className: "rounded-ui-sm font-mono text-[11.5px] font-medium text-fg underline decoration-line underline-offset-[3px] transition-colors hover:decoration-fg focus-ring", children: t("useSuggestion", { slug: check.suggestion }) })) : null] })) : null;
+    const live = (_jsx("span", { className: "sr-only", "aria-live": "polite", children: check.state === "checking" ? t("checking") : check.state === "ok" ? t("available") : check.state === "error" ? check.message : "" }));
+    const input = (extra) => (_jsx(WithoutFieldName, { children: _jsx(Input, { ref: ref, ...engine.inputProps, id: id, size: size, disabled: disabled, invalid: isInvalid, dir: "ltr", spellCheck: false, autoCapitalize: "off", autoComplete: "off", placeholder: placeholder ?? (source !== undefined && !source ? t("empty") : undefined), "aria-label": ariaLabel ?? (field ? undefined : t("slug")), "aria-describedby": mergeIds(describedByProp, message ? messageId : undefined), addonStart: prefix ? _jsx("span", { className: "max-w-[16rem] truncate font-mono text-[12px] text-fg-subtle max-sm:max-w-[9rem]", title: prefix, children: prefix }) : undefined, inputClassName: "font-mono text-[13px]", "data-slot": "slug-input-control", trailing: status || lockControl || extra?.trailingExtra ? (_jsxs("span", { className: "flex items-center gap-1", children: [status ? _jsx("span", { className: "flex size-5 items-center justify-center", children: status }) : null, lockControl, extra?.trailingExtra] })) : undefined, onKeyDown: (e) => {
+                extra?.onKeyDown?.(e);
+                if (!e.defaultPrevented)
+                    engine.inputProps.onKeyDown(e);
+            } }) }));
+    const hidden = submitName ? _jsx("input", { type: "hidden", name: submitName, value: slug, disabled: disabled }) : null;
+    if (variant === "permalink") {
+        return (_jsx(Permalink, { ...rest, className: className, slug: slug, prefix: prefix, href: href, disabled: disabled, t: t, input: input, message: message, live: live, hiddenInput: hidden, status: status, onCancel: (previous) => setSlug(previous), onConfirm: () => {
+                const el = engine.ref.current;
+                if (el)
+                    engine.inputProps.onBlur({ currentTarget: el });
+            } }));
+    }
+    return (_jsxs("div", { ...rest, "data-slot": "slug-input", "data-locked": locked ? "" : undefined, className: cn("grid min-w-0 gap-1.5", className), children: [input(), message, live, hidden] }));
+});
+/* ------------------------------------------------------------------ */
+/* Permalink view                                                      */
+/* ------------------------------------------------------------------ */
+function Permalink({ slug, prefix, href, disabled, t, input, message, live, hiddenInput, status, onCancel, onConfirm, className, ...rest }) {
+    const [editing, setEditing] = React.useState(false);
+    const previous = React.useRef(slug);
+    const editRef = React.useRef(null);
+    const wrapRef = React.useRef(null);
+    const returnFocus = React.useRef(false);
+    React.useEffect(() => {
+        if (editing)
+            wrapRef.current?.querySelector("input:not([type=hidden])")?.focus();
+        else if (returnFocus.current) {
+            returnFocus.current = false;
+            editRef.current?.focus();
+        }
+    }, [editing]);
+    const open = () => {
+        previous.current = slug;
+        setEditing(true);
+    };
+    const close = (keep) => {
+        if (keep)
+            onConfirm();
+        else
+            onCancel(previous.current);
+        returnFocus.current = true;
+        setEditing(false);
+    };
+    const link = href ?? (prefix && /^(https?:)?\/\//.test(prefix) ? prefix + slug : undefined);
+    return (_jsxs("div", { ...rest, ref: wrapRef, "data-slot": "slug-input", "data-variant": "permalink", className: cn("grid min-w-0 gap-1.5", className), children: [editing ? (_jsxs("div", { className: "flex min-w-0 items-center gap-2", children: [_jsx("div", { className: "min-w-0 flex-1", children: input({
+                            onKeyDown: (e) => {
+                                if (e.key === "Enter") {
+                                    e.preventDefault();
+                                    close(true);
+                                }
+                                else if (e.key === "Escape") {
+                                    e.preventDefault();
+                                    e.stopPropagation();
+                                    close(false);
+                                }
+                            },
+                        }) }), _jsx(Button, { size: "sm", variant: "primary", onClick: () => close(true), children: t("done") }), _jsx(Button, { size: "sm", variant: "ghost", onClick: () => close(false), children: t("cancel") })] })) : (_jsxs("div", { className: "flex min-w-0 items-center gap-2 text-[13px]", children: [_jsx(Link2, { "aria-hidden": true, className: "size-3.5 shrink-0 text-fg-subtle rtl:-scale-x-100" }), _jsx("span", { dir: "ltr", className: "min-w-0 truncate font-mono text-[12.5px]", children: link ? (_jsxs("a", { href: link, target: "_blank", rel: "noreferrer", className: "rounded-ui-sm text-fg-muted underline decoration-line underline-offset-[3px] transition-colors hover:text-fg hover:decoration-fg-subtle focus-ring", children: [_jsx("span", { className: "text-fg-subtle", children: prefix }), _jsx("span", { className: "text-fg", children: slug || "…" })] })) : (_jsxs(_Fragment, { children: [_jsx("span", { className: "text-fg-subtle", children: prefix }), _jsx("span", { className: "text-fg", children: slug || "…" })] })) }), status ? _jsx("span", { className: "flex size-4 shrink-0 items-center justify-center", children: status }) : null, _jsxs(Button, { ref: editRef, size: "xs", variant: "ghost", className: "shrink-0", disabled: disabled, onClick: open, "aria-label": t("editSlug"), children: [_jsx(Pencil, { "aria-hidden": true }), " ", t("edit")] })] })), message, live, hiddenInput] }));
+}