@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/components/input.js

@@ -0,0 +1,187 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { Label as LabelPrimitive } from "radix-ui";
+import { CircleAlert, X } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useComposedRefs, mergeIds } from "../lib/compose-refs.js";
+import { FieldContext, useFieldControl } from "../lib/field-context.js";
+import { useLabels } from "../lib/labels.js";
+import { controlVariants } from "../lib/variants.js";
+/**
+ * The classic field look for a bare `<input>` / `<textarea>`. Kept for compatibility —
+ * new controls should use `controlVariants` from `lib/variants`.
+ */
+export const fieldBase = "w-full min-w-0 rounded-ui border border-field-border bg-field text-sm text-fg placeholder:text-fg-subtle transition-[border-color,box-shadow] duration-150 hover:border-field-border-hover focus-visible:border-ring focus-visible:shadow-[0_0_0_3px_var(--accent-soft)] focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-danger aria-invalid:focus-visible:shadow-[0_0_0_3px_color-mix(in_srgb,var(--danger)_18%,transparent)]";
+/* ------------------------------------------------------------------ */
+/* Input                                                               */
+/* ------------------------------------------------------------------ */
+const inputLabels = {
+    clear: "Clear",
+    count: "{count} / {max}",
+    remaining: "{count, plural, =0 {No characters left} one {# character left} other {# characters left}}",
+};
+const setNativeValue = (el, value) => {
+    const proto = el instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+    Object.getOwnPropertyDescriptor(proto, "value")?.set?.call(el, value);
+    el.dispatchEvent(new Event("input", { bubbles: true }));
+};
+/**
+ * Single-line text entry. Native contract (`value` / `defaultValue` / `onChange(event)`); the
+ * `ref` always reaches the `<input>`, so `react-hook-form`'s `register` works. Inside a `Field`
+ * the id, description and invalid/required/disabled state are wired automatically.
+ *
+ * ```tsx
+ * <Field label="Title" hint="Under 60 characters for search results.">
+ *   <Input maxLength={60} showCount />
+ * </Field>
+ * <Input leading={<Search />} placeholder="Search contacts" clearable />
+ * <Input addonStart="https://" addonEnd=".vamos.ist" defaultValue="acme" />
+ * ```
+ */
+export const Input = React.forwardRef(function Input(rawProps, forwardedRef) {
+    const { className, inputClassName, size = "md", variant = "default", leading, trailing, addonStart, addonEnd, clearable, onClear, showCount, invalid, labels, style, ...rest } = rawProps;
+    const props = useFieldControl({ ...rest, "aria-invalid": invalid ? true : rest["aria-invalid"] });
+    const t = useLabels("input", inputLabels, labels);
+    const inputRef = React.useRef(null);
+    const ref = useComposedRefs(forwardedRef, inputRef);
+    const countId = React.useId();
+    const controlled = props.value !== undefined;
+    const [uncontrolledLength, setLength] = React.useState(() => String(props.defaultValue ?? "").length);
+    const length = controlled ? String(props.value ?? "").length : uncontrolledLength;
+    const hasValue = length > 0;
+    const inert = props.disabled || props.readOnly;
+    const max = props.maxLength !== undefined && props.maxLength >= 0 ? props.maxLength : undefined;
+    const remaining = max !== undefined ? max - length : undefined;
+    const clear = () => {
+        const el = inputRef.current;
+        if (!el)
+            return;
+        setNativeValue(el, "");
+        if (!controlled)
+            setLength(0);
+        onClear?.();
+        el.focus();
+    };
+    const showClear = clearable && hasValue && !inert;
+    const adornment = "pointer-events-none flex shrink-0 items-center text-fg-subtle [&_svg]:size-[1em]";
+    const addon = "flex shrink-0 items-center self-stretch bg-surface-2 text-fg-muted whitespace-nowrap";
+    return (_jsxs("div", { "data-slot": "input", "data-size": size, "data-readonly": props.readOnly ? "" : undefined, className: cn(controlVariants({ size, variant }), "cursor-text gap-0 overflow-visible px-0", className), style: style, onPointerDown: (e) => {
+            // Clicking padding or an adornment focuses the input (not addons/buttons).
+            if (e.target === e.currentTarget) {
+                e.preventDefault();
+                inputRef.current?.focus();
+            }
+        }, children: [addonStart ? _jsx("span", { className: cn(addon, "rounded-s-[inherit] border-e border-field-border px-3"), children: addonStart }) : null, leading ? _jsx("span", { className: cn(adornment, "ps-3"), children: leading }) : null, _jsx("input", { ref: ref, ...props, "aria-describedby": mergeIds(props["aria-describedby"], showCount ? countId : undefined), className: cn("h-full min-w-0 flex-1 bg-transparent px-3 text-[length:inherit] text-fg outline-none placeholder:text-fg-subtle disabled:cursor-not-allowed", leading && "ps-2", (trailing || showClear || showCount) && "pe-1.5", inputClassName), onChange: (e) => {
+                    if (!controlled)
+                        setLength(e.currentTarget.value.length);
+                    props.onChange?.(e);
+                }, onKeyDown: (e) => {
+                    props.onKeyDown?.(e);
+                    if (!e.defaultPrevented && clearable && e.key === "Escape" && hasValue && !inert) {
+                        e.preventDefault();
+                        e.stopPropagation();
+                        clear();
+                    }
+                } }), showClear ? (_jsx("button", { type: "button", tabIndex: -1, "aria-label": t("clear"), onClick: clear, className: "me-1.5 inline-flex size-6 shrink-0 items-center justify-center rounded-ui-sm text-fg-subtle transition-colors hover:bg-hover hover:text-fg [&_svg]:size-3.5", children: _jsx(X, { "aria-hidden": true }) })) : null, showCount ? (_jsxs("span", { className: cn("pointer-events-none shrink-0 pe-3 font-mono text-[11px] tabular text-fg-subtle", remaining !== undefined && remaining <= 0 && "text-danger", remaining !== undefined && remaining > 0 && remaining <= 10 && "text-warning"), children: [_jsx("span", { "aria-hidden": true, children: max !== undefined ? t("count", { count: length, max }) : length }), _jsx("span", { id: countId, className: "sr-only", "aria-live": "polite", children: remaining !== undefined && remaining <= 10 ? t("remaining", { count: Math.max(remaining, 0) }) : "" })] })) : null, trailing ? _jsx("span", { className: cn("flex shrink-0 items-center text-fg-subtle [&_svg]:size-[1em]", !addonEnd && "pe-1.5", "[&>svg]:me-1.5"), children: trailing }) : null, addonEnd ? _jsx("span", { className: cn(addon, "rounded-e-[inherit] border-s border-field-border px-3"), children: addonEnd }) : null] }));
+});
+/**
+ * Multi-line text. Grows with its content (`field-sizing: content`) and reads Field context.
+ *
+ * ```tsx
+ * <Field label="Anything we should know first?"><Textarea maxLength={400} showCount /></Field>
+ * ```
+ */
+export const Textarea = React.forwardRef(function Textarea({ className, rows = 4, invalid, showCount, labels, ...rest }, ref) {
+    const props = useFieldControl({ ...rest, "aria-invalid": invalid ? true : rest["aria-invalid"] });
+    const t = useLabels("input", inputLabels, labels);
+    const countId = React.useId();
+    const controlled = props.value !== undefined;
+    const [uncontrolledLength, setLength] = React.useState(() => String(props.defaultValue ?? "").length);
+    const length = controlled ? String(props.value ?? "").length : uncontrolledLength;
+    const max = props.maxLength !== undefined && props.maxLength >= 0 ? props.maxLength : undefined;
+    const remaining = max !== undefined ? max - length : undefined;
+    const area = (_jsx("textarea", { ref: ref, rows: rows, "data-slot": "textarea", className: cn(fieldBase, "field-sizing-content min-h-20 px-3 py-2.5 leading-relaxed read-only:border-dashed read-only:bg-transparent", className), ...props, "aria-describedby": showCount ? mergeIds(props["aria-describedby"], countId) : props["aria-describedby"], onChange: (e) => {
+            if (!controlled)
+                setLength(e.currentTarget.value.length);
+            props.onChange?.(e);
+        } }));
+    if (!showCount)
+        return area;
+    return (_jsxs("div", { "data-slot": "textarea-root", className: "flex w-full flex-col gap-1", children: [area, _jsxs("span", { className: cn("self-end font-mono text-[11px] tabular text-fg-muted", remaining !== undefined && remaining <= 0 && "text-danger", remaining !== undefined && remaining > 0 && remaining <= 20 && "text-warning"), children: [_jsx("span", { "aria-hidden": true, children: max !== undefined ? t("count", { count: length, max }) : length }), _jsx("span", { id: countId, className: "sr-only", "aria-live": "polite", children: remaining !== undefined && remaining <= 20 ? t("remaining", { count: Math.max(remaining, 0) }) : "" })] })] }));
+});
+/* ------------------------------------------------------------------ */
+/* Label                                                               */
+/* ------------------------------------------------------------------ */
+/** Form label (Radix Label: no text selection on double-click). */
+export const Label = React.forwardRef(function Label({ className, ...props }, ref) {
+    return (_jsx(LabelPrimitive.Root, { ref: ref, "data-slot": "label", className: cn("text-[13px] font-medium text-fg", className), ...props }));
+});
+/* ------------------------------------------------------------------ */
+/* Field                                                               */
+/* ------------------------------------------------------------------ */
+const fieldLabels = { optional: "(optional)", required: "(required)" };
+const NATIVE = new Set(["input", "select", "textarea"]);
+/**
+ * Label + control + hint/error, with the accessibility wiring done for you:
+ * `<label for>`, `aria-describedby` (merged with the control's own), `aria-invalid`, `required`,
+ * `disabled`. Works with any kit control through context — Select, Combobox, Date picker —
+ * not only a single direct child.
+ *
+ * ```tsx
+ * <Field label="Work email" hint="We send the invoice here." required>
+ *   <Input type="email" />
+ * </Field>
+ * <Field label="Status" error={errors.status}><Select … /></Field>
+ * ```
+ */
+export function Field({ label, hint, error, id, name, required = false, optional = false, disabled = false, readOnly = false, orientation = "vertical", layout = "stack", labelAction, className, labels, children, }) {
+    const t = useLabels("field", fieldLabels, labels);
+    const autoId = React.useId();
+    const only = React.Children.count(children) === 1 && React.isValidElement(children) ? children : null;
+    const controlId = id ?? only?.props.id ?? `field${autoId.replace(/:/g, "")}`;
+    const firstError = Array.isArray(error) ? error.find((e) => e != null && e !== false && e !== "") : error;
+    const hasError = firstError != null && firstError !== false && firstError !== "";
+    const labelId = label ? `${controlId}-label` : undefined;
+    const hintId = !hasError && hint ? `${controlId}-hint` : undefined;
+    const errorId = hasError ? `${controlId}-error` : undefined;
+    const ctx = React.useMemo(() => ({ id: controlId, labelId, describedBy: mergeIds(hintId, errorId), errorId, invalid: hasError, required, disabled, readOnly, name }), [controlId, labelId, hintId, errorId, hasError, required, disabled, readOnly, name]);
+    // A plain DOM control can't read context: wire it by cloning.
+    let control = children;
+    if (only && typeof only.type === "string" && NATIVE.has(only.type)) {
+        const p = only.props;
+        control = React.cloneElement(only, {
+            id: controlId,
+            name: p.name ?? name,
+            "aria-describedby": mergeIds(ctx.describedBy, p["aria-describedby"]),
+            "aria-invalid": p["aria-invalid"] ?? (hasError || undefined),
+            required: p.required ?? (required || undefined),
+            disabled: p.disabled ?? (disabled || undefined),
+            readOnly: p.readOnly ?? (readOnly || undefined),
+        });
+    }
+    const labelEl = label ? (_jsxs("div", { className: cn("flex min-w-0 items-baseline justify-between gap-3", orientation === "horizontal" && "col-start-2 row-start-1"), children: [_jsxs(Label, { id: labelId, htmlFor: controlId, className: cn(disabled && "opacity-60", orientation === "horizontal" && "font-normal"), children: [label, required ? (_jsx("span", { "aria-hidden": true, className: "ms-0.5 text-danger", children: "*" })) : null, optional && !required ? _jsx("span", { className: "ms-1 font-normal text-fg-subtle", children: t("optional") }) : null] }), labelAction ? _jsx("div", { className: "shrink-0 text-xs", children: labelAction }) : null] })) : null;
+    const message = hasError ? (_jsxs("p", { id: errorId, "data-slot": "field-error", className: "flex items-start gap-1.5 text-xs text-danger", children: [_jsx(CircleAlert, { "aria-hidden": true, className: "mt-px size-3.5 shrink-0" }), _jsx("span", { children: firstError })] })) : hint ? (_jsx("p", { id: hintId, "data-slot": "field-hint", className: "text-xs text-pretty text-fg-subtle", children: hint })) : null;
+    const body = orientation === "horizontal" ? (_jsxs("div", { className: "grid grid-cols-[auto_minmax(0,1fr)] items-start gap-x-2.5 gap-y-0.5", children: [_jsx("div", { className: "col-start-1 row-span-2 row-start-1 flex min-h-5 items-center", children: control }), labelEl, message ? _jsx("div", { className: "col-start-2 row-start-2", children: message }) : null] })) : layout === "inline" ? (_jsxs("div", { className: "grid gap-1.5 sm:grid-cols-[minmax(10rem,14rem)_minmax(0,1fr)] sm:gap-x-6", children: [_jsx("div", { className: "sm:pt-[calc((var(--control-h)-1.25rem)/2)]", children: labelEl }), _jsxs("div", { className: "grid min-w-0 gap-1.5", children: [control, message] })] })) : (_jsxs(_Fragment, { children: [labelEl, control, message] }));
+    return (_jsx(FieldContext.Provider, { value: ctx, children: _jsx("div", { "data-slot": "field", "data-invalid": hasError ? "" : undefined, "data-disabled": disabled ? "" : undefined, className: cn("group/field grid min-w-0 content-start gap-1.5", className), children: body }) }));
+}
+/**
+ * Groups related controls with a real `<fieldset>` + `<legend>` — radio and checkbox groups,
+ * an address block. `disabled` disables every native control inside.
+ *
+ * ```tsx
+ * <Fieldset legend="Notifications" hint="Choose where we reach you.">
+ *   <Field label="Email" orientation="horizontal"><Checkbox /></Field>
+ * </Fieldset>
+ * ```
+ */
+export const Fieldset = React.forwardRef(function Fieldset({ legend, hint, error, className, children, "aria-describedby": describedBy, ...props }, ref) {
+    const id = React.useId();
+    const hintId = hint && !error ? `${id}-hint` : undefined;
+    const errorId = error ? `${id}-error` : undefined;
+    return (_jsxs("fieldset", { ref: ref, "data-slot": "fieldset", "aria-describedby": mergeIds(hintId, errorId, describedBy), "data-invalid": error ? "" : undefined, className: cn("grid min-w-0 gap-3 border-0 p-0 disabled:opacity-60", className), ...props, children: [legend ? _jsx(Legend, { className: "float-left w-full", children: legend }) : null, hint && !error ? (_jsx("p", { id: hintId, className: "-mt-2 text-xs text-fg-subtle", children: hint })) : null, error ? (_jsxs("p", { id: errorId, className: "-mt-2 flex items-start gap-1.5 text-xs text-danger", children: [_jsx(CircleAlert, { "aria-hidden": true, className: "mt-px size-3.5 shrink-0" }), _jsx("span", { children: error })] })) : null, children] }));
+});
+/** Title of a Fieldset. */
+export const Legend = React.forwardRef(function Legend({ className, ...props }, ref) {
+    return _jsx("legend", { ref: ref, "data-slot": "legend", className: cn("mb-0 p-0 text-sm font-semibold tracking-[-0.005em] text-fg", className), ...props });
+});

package/dist/components/item.d.ts

@@ -0,0 +1,96 @@
+import * as React from "react";
+export interface ItemListProps extends Omit<React.HTMLAttributes<HTMLElement>, "defaultValue" | "onChange" | "value"> {
+    /** Hairlines between rows. Default `true`. */
+    divided?: boolean;
+    /**
+     * Rows with small side padding and rounded hover — for a list inside a padded CardBody.
+     * Without it rows use the card padding, so a list placed straight in a Card lines up with the header.
+     */
+    inset?: boolean;
+    /** Turns the list into a listbox (↑ ↓ Home End, Space toggles). Children need a `value`. */
+    selectable?: "single" | "multiple";
+    /** Selected values (controlled). */
+    value?: string[];
+    defaultValue?: string[];
+    onValueChange?: (value: string[]) => void;
+    /** Element. Default `"ul"` (`"div"` for a list of plain blocks). */
+    as?: "ul" | "ol" | "div";
+    /** Shown instead of the rows when there are none. */
+    empty?: React.ReactNode;
+}
+/**
+ * The container of Item rows. A plain `<ul>` by default; with `selectable` it becomes a listbox
+ * (single or multiple) with arrow-key navigation. Server-component compatible unless selectable.
+ *
+ * ```tsx
+ * <ItemList>
+ *   <Item><ItemContent><ItemTitle>Local SEO checklist for 2026</ItemTitle><ItemDescription>Samet · Edited yesterday</ItemDescription></ItemContent></Item>
+ * </ItemList>
+ * ```
+ */
+export declare const ItemList: React.ForwardRefExoticComponent<ItemListProps & React.RefAttributes<HTMLElement>>;
+export declare const itemRowVariants: (props?: ({
+    size?: "sm" | "md" | "lg" | null | undefined;
+    align?: "start" | "center" | null | undefined;
+    interactive?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface ItemProps extends Omit<React.HTMLAttributes<HTMLElement>, "value"> {
+    /** Option value — required for rows of a selectable ItemList. */
+    value?: string;
+    /** Merge the row styles onto the child (a link: `<Item asChild><a href>…</a></Item>`). */
+    asChild?: boolean;
+    /** Hover tint + pointer. On by default for `asChild` rows and options. */
+    interactive?: boolean;
+    disabled?: boolean;
+    /** Row height from `--row-h`: sm −0.5rem, md, lg +1rem. Default `"md"`. */
+    size?: "sm" | "md" | "lg";
+    /** Vertical alignment of the parts. Default `"center"`. */
+    align?: "center" | "start";
+    /** Element of the row wrapper. Default `"li"` (use `"div"` inside `ItemList as="div"`). */
+    as?: "li" | "div";
+}
+/**
+ * The generic row of a non-tabular list: leading visual, title + description, meta and actions.
+ *
+ * ```tsx
+ * <Item>
+ *   <ItemLeading><Avatar … /></ItemLeading>
+ *   <ItemContent><ItemTitle>Ayşe Kaya</ItemTitle><ItemDescription>Head of Sales · Northwind</ItemDescription></ItemContent>
+ *   <ItemMeta>2h</ItemMeta>
+ *   <ItemActions reveal="hover"><IconButton label="Call Ayşe Kaya" size="xs"><Phone /></IconButton></ItemActions>
+ * </Item>
+ * ```
+ */
+export declare const Item: React.ForwardRefExoticComponent<ItemProps & React.RefAttributes<HTMLElement>>;
+/** Leading visual: avatar, icon tile, thumbnail or checkbox. */
+export declare function ItemLeading({ className, variant, ...props }: React.HTMLAttributes<HTMLDivElement> & {
+    variant?: "plain" | "icon" | "thumbnail";
+}): React.JSX.Element;
+/** Title + description column; takes the remaining width and truncates. */
+export declare function ItemContent({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+export interface ItemTitleProps extends React.HTMLAttributes<HTMLElement> {
+    /** Render as the child (a link or heading). */
+    asChild?: boolean;
+    /** Cut to one line (with the full text as `title` when it is a string). Default `true`. */
+    truncate?: boolean;
+}
+export declare function ItemTitle({ className, asChild, truncate, title, children, ...props }: ItemTitleProps): React.JSX.Element;
+export declare function ItemDescription({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+/** Trailing information: time, count, badge. */
+export declare function ItemMeta({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+export interface ItemActionsProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * `"always"` (default) or `"hover"`: hidden until the row is hovered — but still visible when
+     * anything in the row has focus, and always visible on touch screens.
+     */
+    reveal?: "always" | "hover";
+}
+export declare function ItemActions({ className, reveal, ...props }: ItemActionsProps): React.JSX.Element;
+export interface ItemSkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Number of placeholder rows. Default 3. */
+    count?: number;
+    /** Include a leading circle. Default `true`. */
+    leading?: boolean;
+}
+/** Placeholder rows while a list loads (one `aria-busy` region). */
+export declare function ItemSkeleton({ count, leading, className, ...props }: ItemSkeletonProps): React.JSX.Element;

package/dist/components/item.js

@@ -0,0 +1,113 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Slot } from "radix-ui";
+import { Check } from "lucide-react";
+import { cva } from "class-variance-authority";
+import { cn } from "../lib/cn.js";
+import { ItemListbox } from "../lib/data-islands.js";
+import { Skeleton } from "./skeleton.js";
+/**
+ * The container of Item rows. A plain `<ul>` by default; with `selectable` it becomes a listbox
+ * (single or multiple) with arrow-key navigation. Server-component compatible unless selectable.
+ *
+ * ```tsx
+ * <ItemList>
+ *   <Item><ItemContent><ItemTitle>Local SEO checklist for 2026</ItemTitle><ItemDescription>Samet · Edited yesterday</ItemDescription></ItemContent></Item>
+ * </ItemList>
+ * ```
+ */
+export const ItemList = React.forwardRef(function ItemList({ divided = true, inset, selectable, value, defaultValue, onValueChange, as = "ul", empty, className, children, ...props }, ref) {
+    const count = React.Children.toArray(children).length;
+    const classes = cn("group/list m-0 grid list-none p-0", inset && "-mx-2 gap-0.5", 
+    // hairline at the bottom of every row but the last (also through an asChild wrapper)
+    divided && !inset && "[&>[data-slot=item]:not(:last-child)]:shadow-[inset_0_-1px_0_var(--line)] [&>[data-slot=item-wrapper]:not(:last-child)>*]:shadow-[inset_0_-1px_0_var(--line)]", className);
+    const data = { "data-slot": "item-list", "data-divided": divided ? "" : undefined, "data-inset": inset ? "" : undefined };
+    if (count === 0 && empty !== undefined) {
+        return (_jsx("div", { ref: ref, ...data, className: cn("px-(--card-p,1.25rem) py-8 text-center text-[13px] text-fg-muted", className), children: empty }));
+    }
+    if (selectable) {
+        return (_jsx(ItemListbox, { ref: ref, selectable: selectable, value: value, defaultValue: defaultValue, onValueChange: onValueChange, ...data, className: classes, ...props, children: children }));
+    }
+    const Comp = as;
+    return (_jsx(Comp, { ref: ref, ...data, className: classes, ...props, children: children }));
+});
+/* ------------------------------------------------------------------ */
+/* Item                                                                 */
+/* ------------------------------------------------------------------ */
+export const itemRowVariants = cva([
+    "group/item relative flex w-full min-w-0 gap-3 text-start text-[13px] text-fg outline-none",
+    "px-(--card-p,1.25rem) group-data-inset/list:rounded-ui-sm group-data-inset/list:px-2",
+    // states (also driven by the listbox island via aria-selected / aria-disabled)
+    "aria-selected:bg-selected data-[state=selected]:bg-selected",
+    "aria-disabled:pointer-events-none aria-disabled:opacity-50 data-disabled:pointer-events-none data-disabled:opacity-50",
+    "focus-visible:z-[1] focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-ring",
+], {
+    variants: {
+        size: {
+            sm: "min-h-[calc(var(--row-h)-0.5rem)] py-1.5",
+            md: "min-h-(--row-h) py-2.5",
+            lg: "min-h-[calc(var(--row-h)+1rem)] py-3.5",
+        },
+        align: { center: "items-center", start: "items-start" },
+        interactive: {
+            true: "cursor-pointer transition-colors duration-100 hover:bg-hover",
+        },
+    },
+    defaultVariants: { size: "md", align: "center" },
+});
+/**
+ * The generic row of a non-tabular list: leading visual, title + description, meta and actions.
+ *
+ * ```tsx
+ * <Item>
+ *   <ItemLeading><Avatar … /></ItemLeading>
+ *   <ItemContent><ItemTitle>Ayşe Kaya</ItemTitle><ItemDescription>Head of Sales · Northwind</ItemDescription></ItemContent>
+ *   <ItemMeta>2h</ItemMeta>
+ *   <ItemActions reveal="hover"><IconButton label="Call Ayşe Kaya" size="xs"><Phone /></IconButton></ItemActions>
+ * </Item>
+ * ```
+ */
+export const Item = React.forwardRef(function Item({ value, asChild, interactive, disabled, size, align, as = "li", className, children, ...props }, ref) {
+    const option = value !== undefined;
+    const rowClass = cn(itemRowVariants({ size, align, interactive: interactive ?? (asChild || option) }), className);
+    const state = {
+        "data-slot": "item",
+        "data-value": value,
+        "data-disabled": disabled ? "" : undefined,
+        "aria-disabled": disabled || undefined,
+    };
+    const check = option ? (_jsx("span", { "aria-hidden": true, "data-slot": "item-check", className: "ms-1 grid size-4 shrink-0 place-items-center self-center text-accent-ink opacity-0 transition-opacity group-aria-selected/item:opacity-100 [&_svg]:size-3.5", children: _jsx(Check, { strokeWidth: 2.5 }) })) : null;
+    if (asChild) {
+        const Wrapper = as;
+        return (_jsx(Wrapper, { className: "contents", "data-slot": "item-wrapper", children: _jsx(Slot.Root, { ref: ref, ...state, className: rowClass, ...props, children: children }) }));
+    }
+    const Comp = as;
+    return (_jsxs(Comp, { ref: ref, ...state, className: rowClass, ...props, children: [children, check] }));
+});
+/** Leading visual: avatar, icon tile, thumbnail or checkbox. */
+export function ItemLeading({ className, variant, ...props }) {
+    return (_jsx("div", { "data-slot": "item-leading", className: cn("flex shrink-0 items-center", variant === "icon" && "grid size-8 place-items-center rounded-ui-sm border border-line bg-surface-2 text-fg-muted [&_svg]:size-4", variant === "thumbnail" && "h-10 w-14 overflow-hidden rounded-ui-sm border border-line bg-surface-2 [&_img]:size-full [&_img]:object-cover", className), ...props }));
+}
+/** Title + description column; takes the remaining width and truncates. */
+export function ItemContent({ className, ...props }) {
+    return _jsx("div", { "data-slot": "item-content", className: cn("grid min-w-0 flex-1 gap-0.5", className), ...props });
+}
+export function ItemTitle({ className, asChild, truncate = true, title, children, ...props }) {
+    const Comp = asChild ? Slot.Root : "div";
+    return (_jsx(Comp, { "data-slot": "item-title", title: title ?? (truncate && typeof children === "string" ? children : undefined), className: cn("font-medium text-fg", truncate && "truncate", className), ...props, children: children }));
+}
+export function ItemDescription({ className, ...props }) {
+    return _jsx("div", { "data-slot": "item-description", className: cn("min-w-0 truncate text-xs text-fg-subtle", className), ...props });
+}
+/** Trailing information: time, count, badge. */
+export function ItemMeta({ className, ...props }) {
+    return _jsx("div", { "data-slot": "item-meta", className: cn("flex shrink-0 items-center gap-2 text-xs text-fg-subtle tabular", className), ...props });
+}
+export function ItemActions({ className, reveal = "always", ...props }) {
+    return (_jsx("div", { "data-slot": "item-actions", "data-reveal": reveal, className: cn("flex shrink-0 items-center gap-1", reveal === "hover" &&
+            "opacity-0 transition-opacity duration-100 group-hover/item:opacity-100 group-focus-within/item:opacity-100 has-[[data-state=open]]:opacity-100 [@media(hover:none)]:opacity-100", className), ...props }));
+}
+/** Placeholder rows while a list loads (one `aria-busy` region). */
+export function ItemSkeleton({ count = 3, leading = true, className, ...props }) {
+    return (_jsx("div", { "data-slot": "item-skeleton", "aria-busy": "true", className: cn("grid", className), ...props, children: Array.from({ length: count }, (_, i) => (_jsxs("div", { className: "flex min-h-(--row-h) items-center gap-3 px-(--card-p,1.25rem) py-2.5", children: [leading ? _jsx(Skeleton, { shape: "circle", className: "size-8" }) : null, _jsxs("div", { className: "grid flex-1 gap-2", children: [_jsx(Skeleton, { shape: "text", className: "h-3", style: { width: `${68 - ((i * 17) % 30)}%` } }), _jsx(Skeleton, { shape: "text", className: "h-2.5", style: { width: `${38 - ((i * 11) % 14)}%` } })] }), _jsx(Skeleton, { shape: "text", className: "h-2.5 w-10" })] }, i))) }));
+}

package/dist/components/kbd.d.ts

@@ -0,0 +1,64 @@
+import * as React from "react";
+import { type VariantProps } from "class-variance-authority";
+export declare const kbdVariants: (props?: ({
+    size?: "sm" | "md" | null | undefined;
+    variant?: "nav" | "default" | "ghost" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/** Key names Kbd understands. Anything else is shown as typed (single letters are uppercased). */
+export type KeyName = "mod" | "ctrl" | "meta" | "alt" | "shift" | "enter" | "esc" | "escape" | "tab" | "space" | "backspace" | "delete" | "up" | "down" | "left" | "right" | (string & {});
+declare const kbdLabels: {
+    command: string;
+    control: string;
+    option: string;
+    alt: string;
+    shift: string;
+    windows: string;
+    enter: string;
+    escape: string;
+    backspace: string;
+    delete: string;
+    tab: string;
+    space: string;
+    up: string;
+    down: string;
+    left: string;
+    right: string;
+};
+export type KbdLabels = typeof kbdLabels;
+export interface KbdProps extends React.HTMLAttributes<HTMLElement>, VariantProps<typeof kbdVariants> {
+    /**
+     * A key token to render platform-aware (`"mod"` → ⌘ / Ctrl, `"shift"` → ⇧ / Shift, `"enter"` → ↩ / Enter).
+     * Without it, `children` are shown as-is.
+     */
+    keyName?: KeyName;
+    /** Overrides for the spoken key names (`kbd` namespace). */
+    labels?: Partial<KbdLabels>;
+}
+/**
+ * One keyboard key, rendered as `<kbd>`.
+ *
+ * ```tsx
+ * <Kbd>Esc</Kbd>
+ * <Kbd keyName="mod" />   // ⌘ on macOS, Ctrl elsewhere
+ * ```
+ */
+export declare const Kbd: React.ForwardRefExoticComponent<KbdProps & React.RefAttributes<HTMLElement>>;
+export interface KbdGroupProps extends Omit<React.HTMLAttributes<HTMLElement>, "children">, VariantProps<typeof kbdVariants> {
+    /** A shortcut string (`"mod+shift+k"`) or key tokens (`["mod", "k"]`). */
+    keys: string | KeyName[];
+    /** Visible text between keycaps (e.g. "+" or "then"). Default: none (keycaps sit side by side). */
+    separator?: React.ReactNode;
+    labels?: Partial<KbdLabels>;
+}
+/**
+ * A key combination: one `<kbd>` per key nested in an outer `<kbd>` (per the HTML spec).
+ * Platform-aware and always left-to-right; key order follows platform convention
+ * (⌃ ⌥ ⇧ ⌘ on Apple, Ctrl Alt Shift elsewhere). SSR renders the non-Apple form.
+ *
+ * ```tsx
+ * <KbdGroup keys="mod+k" />          // ⌘ K  /  Ctrl K
+ * <KbdGroup keys={["g", "p"]} separator="then" />
+ * ```
+ */
+export declare const KbdGroup: React.ForwardRefExoticComponent<KbdGroupProps & React.RefAttributes<HTMLElement>>;
+export {};

package/dist/components/kbd.js

@@ -0,0 +1,119 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cva } from "class-variance-authority";
+import { cn } from "../lib/cn.js";
+import { formatKey, parseShortcut, shortcutKeys, useIsMac } from "../lib/use-hotkeys.js";
+import { useLabels } from "../lib/labels.js";
+export const kbdVariants = cva("ui-keycap inline-flex shrink-0 select-none items-center justify-center whitespace-nowrap rounded-[calc(var(--radius)*0.42)] font-mono font-medium leading-none tabular", {
+    variants: {
+        size: {
+            sm: "h-[1.125rem] min-w-[1.125rem] px-1 text-[10.5px]",
+            md: "h-6 min-w-6 px-1.5 text-[11.5px]",
+        },
+        variant: {
+            /** Inset keycap on surfaces. */
+            default: "border border-line bg-surface-2 text-fg-muted",
+            /** Border only — inside inputs and dense menus. */
+            ghost: "border border-field-border bg-transparent text-fg-subtle shadow-none",
+            /** Inside the dark sidebar or nav popovers. */
+            nav: "border border-nav-line bg-nav-hover text-nav-fg [--kbd-edge:var(--nav-line)]",
+        },
+    },
+    defaultVariants: { size: "md", variant: "default" },
+});
+const kbdLabels = {
+    command: "Command",
+    control: "Control",
+    option: "Option",
+    alt: "Alt",
+    shift: "Shift",
+    windows: "Windows",
+    enter: "Enter",
+    escape: "Escape",
+    backspace: "Backspace",
+    delete: "Delete",
+    tab: "Tab",
+    space: "Space",
+    up: "Up arrow",
+    down: "Down arrow",
+    left: "Left arrow",
+    right: "Right arrow",
+};
+/** Accessible name key for a canonical key token, when the visible glyph is a symbol or abbreviation. */
+function spokenKey(token, isMac) {
+    switch (token) {
+        case "mod":
+            return isMac ? "command" : "control";
+        case "meta":
+            return isMac ? "command" : "windows";
+        case "ctrl":
+            return "control";
+        case "alt":
+            return isMac ? "option" : "alt";
+        case "shift":
+            return "shift";
+        case "enter":
+            return "enter";
+        case "escape":
+            return "escape";
+        case "backspace":
+            return "backspace";
+        case "delete":
+            return "delete";
+        case "tab":
+            return "tab";
+        case " ":
+            return "space";
+        case "arrowup":
+            return "up";
+        case "arrowdown":
+            return "down";
+        case "arrowleft":
+            return "left";
+        case "arrowright":
+            return "right";
+        default:
+            return undefined;
+    }
+}
+/**
+ * One keyboard key, rendered as `<kbd>`.
+ *
+ * ```tsx
+ * <Kbd>Esc</Kbd>
+ * <Kbd keyName="mod" />   // ⌘ on macOS, Ctrl elsewhere
+ * ```
+ */
+export const Kbd = React.forwardRef(function Kbd({ keyName, size, variant, labels, className, children, ...props }, ref) {
+    const isMac = useIsMac();
+    const t = useLabels("kbd", kbdLabels, labels);
+    let content = children;
+    if (keyName !== undefined && children === undefined) {
+        const token = parseShortcut(keyName === "+" ? "plus" : keyName);
+        const canonical = token.key || (token.mod ? "mod" : token.meta ? "meta" : token.ctrl ? "ctrl" : token.alt ? "alt" : token.shift ? "shift" : keyName);
+        const glyph = formatKey(canonical, isMac);
+        const spoken = spokenKey(canonical, isMac);
+        const name = spoken ? t(spoken) : undefined;
+        // Symbol glyphs (⌘ ⇧ ⌥ ↩) fall back to a system font that draws them small next to letters.
+        const symbol = /^[^\x00-\x7f]$/.test(glyph);
+        content =
+            name && name !== glyph ? (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": true, className: symbol ? "text-[1.2em] leading-none" : undefined, children: glyph }), _jsx("span", { className: "sr-only", children: name })] })) : (glyph);
+    }
+    return (_jsx("kbd", { ref: ref, "data-slot": "kbd", className: cn(kbdVariants({ size, variant }), className), ...props, children: content }));
+});
+/**
+ * A key combination: one `<kbd>` per key nested in an outer `<kbd>` (per the HTML spec).
+ * Platform-aware and always left-to-right; key order follows platform convention
+ * (⌃ ⌥ ⇧ ⌘ on Apple, Ctrl Alt Shift elsewhere). SSR renders the non-Apple form.
+ *
+ * ```tsx
+ * <KbdGroup keys="mod+k" />          // ⌘ K  /  Ctrl K
+ * <KbdGroup keys={["g", "p"]} separator="then" />
+ * ```
+ */
+export const KbdGroup = React.forwardRef(function KbdGroup({ keys, separator, size, variant, labels, className, ...props }, ref) {
+    const isMac = useIsMac();
+    const tokens = typeof keys === "string" ? shortcutKeys(keys, isMac) : keys;
+    return (_jsx("kbd", { ref: ref, dir: "ltr", "data-slot": "kbd-group", className: cn("inline-flex items-center gap-1 font-sans", className), ...props, children: tokens.map((k, i) => (_jsxs(React.Fragment, { children: [i > 0 && separator != null ? (_jsx("span", { "aria-hidden": typeof separator === "string" && /^[+\-–]$/.test(separator) ? true : undefined, className: "text-[11px] text-fg-subtle", children: separator })) : null, _jsx(Kbd, { keyName: k, size: size, variant: variant, labels: labels })] }, `${k}-${i}`))) }));
+});