@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/components/checkbox.js

@@ -0,0 +1,138 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Checkbox as CheckboxPrimitive } from "radix-ui";
+import { cva } from "class-variance-authority";
+import { cn } from "../lib/cn.js";
+import { mergeIds } from "../lib/compose-refs.js";
+import { FieldContextReset, useFieldContext, useFieldControl } from "../lib/field-context.js";
+import { useControllableState } from "../lib/use-controllable-state.js";
+export const checkboxVariants = cva([
+    "peer relative inline-flex shrink-0 items-center justify-center border bg-field text-accent-fg outline-none",
+    // 16–18px boxes need the stronger edge in every material, or they vanish on dark solid
+    "border-field-border-hover",
+    "transition-[background-color,border-color,box-shadow] duration-150",
+    "hover:border-fg-subtle",
+    "focus-visible:border-ring focus-visible:shadow-[0_0_0_3px_var(--accent-soft)]",
+    "data-[state=checked]:border-transparent data-[state=checked]:bg-accent data-[state=indeterminate]:border-transparent data-[state=indeterminate]:bg-accent",
+    "data-[state=checked]:shadow-[inset_0_1px_0_rgb(255_255_255/0.3),0_0_0_1px_color-mix(in_srgb,var(--fg)_10%,transparent)]",
+    "data-[state=indeterminate]:shadow-[inset_0_1px_0_rgb(255_255_255/0.3),0_0_0_1px_color-mix(in_srgb,var(--fg)_10%,transparent)]",
+    "aria-invalid:border-danger aria-invalid:data-[state=unchecked]:shadow-[0_0_0_3px_color-mix(in_srgb,var(--danger)_14%,transparent)]",
+    "disabled:cursor-not-allowed disabled:opacity-45",
+    "aria-readonly:cursor-default aria-readonly:data-[state=checked]:bg-fg-subtle aria-readonly:data-[state=indeterminate]:bg-fg-subtle aria-readonly:text-scene",
+], {
+    variants: {
+        size: {
+            sm: "size-4 rounded-[5px] [&_svg]:size-3",
+            md: "size-[18px] rounded-[5px] [&_svg]:size-[13px]",
+        },
+    },
+    defaultVariants: { size: "md" },
+});
+const CheckboxGroupContext = React.createContext(null);
+function CheckIcon() {
+    return (_jsx("svg", { viewBox: "0 0 14 14", fill: "none", "aria-hidden": true, focusable: "false", children: _jsx("path", { className: "ui-check-path", d: "M3 7.4 5.8 10 11 4.2", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round" }) }));
+}
+function DashIcon() {
+    return (_jsx("svg", { viewBox: "0 0 14 14", fill: "none", "aria-hidden": true, focusable: "false", children: _jsx("path", { d: "M3.5 7h7", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round" }) }));
+}
+/**
+ * Yes/no and multi-select: "Allow comments", row selection, permissions, consent.
+ * Built on Radix Checkbox (tri-state, hidden input with `name`). Reads Field context.
+ *
+ * ```tsx
+ * <Checkbox label="Allow comments" description="Readers can reply below the post." defaultChecked />
+ * <Checkbox checked={some ? "indeterminate" : all} onCheckedChange={toggleAll} aria-label="Select all rows" />
+ * <Field label="I accept the terms" orientation="horizontal" error={err}><Checkbox name="terms" /></Field>
+ * ```
+ */
+export const Checkbox = React.forwardRef(function Checkbox(rawProps, ref) {
+    const group = React.useContext(CheckboxGroupContext);
+    const { checked: checkedProp, defaultChecked, onCheckedChange, label, description, size = group?.size ?? "md", variant = group?.variant ?? "default", icon, invalid, readOnly: readOnlyProp, className, controlClassName, value, style, ...rest } = rawProps;
+    const groupValue = value === undefined ? undefined : String(value);
+    const inGroup = Boolean(group && groupValue !== undefined);
+    const control = useFieldControl({
+        ...rest,
+        name: rest.name ?? (inGroup ? group.name : undefined),
+        disabled: rest.disabled ?? (group?.disabled || undefined),
+        readOnly: readOnlyProp ?? (group?.readOnly || undefined),
+        "aria-invalid": invalid || group?.invalid ? true : rest["aria-invalid"],
+    });
+    const { readOnly, required, ...controlProps } = control;
+    const [state, setState] = useControllableState({
+        value: inGroup ? group.value.includes(groupValue) : checkedProp,
+        defaultValue: defaultChecked ?? false,
+        onChange: (next) => {
+            if (inGroup)
+                group.toggle(groupValue, next === true);
+            onCheckedChange?.(next);
+        },
+        name: "Checkbox",
+    });
+    const autoId = React.useId();
+    const id = controlProps.id ?? (label ? `cb${autoId.replace(/:/g, "")}` : undefined);
+    const descId = description ? `${id ?? autoId}-desc` : undefined;
+    const labelId = label ? `${id ?? autoId}-label` : undefined;
+    const labelledBy = controlProps["aria-labelledby"] ?? (label && !controlProps["aria-label"] ? labelId : undefined);
+    const box = (_jsx(CheckboxPrimitive.Root, { ref: ref, "data-slot": "checkbox", "data-size": size, ...controlProps, id: id, value: groupValue, required: required, "aria-required": required || undefined, "aria-readonly": readOnly || undefined, "aria-labelledby": labelledBy, "aria-describedby": mergeIds(controlProps["aria-describedby"], descId), checked: state, onCheckedChange: (next) => {
+            if (readOnly)
+                return;
+            setState(next);
+        }, onKeyDown: (e) => {
+            // Radix ignores Enter on purpose (WAI-ARIA); read-only also swallows Space.
+            if (readOnly && e.key === " ")
+                e.preventDefault();
+            controlProps.onKeyDown?.(e);
+        }, className: cn(checkboxVariants({ size }), label ? controlClassName : cn(controlClassName, className)), style: label ? undefined : style, children: _jsx(CheckboxPrimitive.Indicator, { "data-slot": "checkbox-indicator", forceMount: true, className: "flex items-center justify-center data-[state=unchecked]:hidden", children: state === "indeterminate" ? _jsx(DashIcon, {}) : _jsx(CheckIcon, {}) }) }));
+    if (!label)
+        return box;
+    const disabled = controlProps.disabled;
+    const text = (_jsxs("span", { className: "grid min-w-0 gap-0.5", children: [_jsx("span", { id: labelId, className: cn("text-fg", size === "sm" ? "text-[13px]" : "text-sm", variant === "card" ? "font-medium" : "leading-5"), children: label }), description ? (_jsx("span", { id: descId, className: cn("text-fg-muted text-pretty", size === "sm" ? "text-[11.5px]" : "text-xs", "leading-[1.45]"), children: description })) : null] }));
+    if (variant === "card") {
+        return (_jsxs("label", { htmlFor: id, "data-slot": "checkbox-card", "data-state": state === true ? "checked" : state === "indeterminate" ? "indeterminate" : "unchecked", "data-disabled": disabled ? "" : undefined, className: cn("group/cb relative flex cursor-pointer items-start gap-3 rounded-ui border border-field-border bg-field p-3.5 transition-[background-color,border-color,box-shadow] duration-150", "hover:border-field-border-hover glass:border-field-border-hover", "has-[:focus-visible]:border-ring has-[:focus-visible]:shadow-[0_0_0_3px_var(--accent-soft)]", "data-[state=checked]:border-accent-ink data-[state=checked]:bg-[color-mix(in_oklch,var(--accent-base)_11%,transparent)] data-[state=checked]:shadow-[inset_0_0_0_1px_var(--accent-ink)]", "has-[[aria-invalid=true]]:border-danger", "data-disabled:cursor-not-allowed data-disabled:opacity-50", className), style: style, children: [icon ? _jsx("span", { className: "mt-px flex size-8 shrink-0 items-center justify-center rounded-ui-sm bg-surface-2 text-fg-muted [&_svg]:size-4", children: icon }) : null, _jsx("span", { className: "min-w-0 flex-1", children: text }), _jsx("span", { className: "mt-px", children: box })] }));
+    }
+    return (_jsxs("div", { "data-slot": "checkbox-row", "data-disabled": disabled ? "" : undefined, className: cn("flex items-start gap-2.5", className), style: style, children: [_jsx("span", { className: cn("flex shrink-0 items-center", size === "sm" ? "h-[19.5px]" : "h-5"), children: box }), _jsx("label", { htmlFor: id, className: cn("min-w-0 select-none", disabled ? "cursor-not-allowed opacity-60" : "cursor-pointer"), children: text })] }));
+});
+/**
+ * Several checkboxes that share one array value: notification channels, modules, permissions.
+ * `role="group"`, labelled by the surrounding Field / Fieldset.
+ *
+ * ```tsx
+ * <Field label="Notify me by">
+ *   <CheckboxGroup name="channels" defaultValue={["email"]} items={[{ value: "email", label: "Email" }, { value: "sms", label: "SMS" }]} />
+ * </Field>
+ * ```
+ */
+export const CheckboxGroup = React.forwardRef(function CheckboxGroup({ value, defaultValue, onValueChange, name, items, orientation = "vertical", variant = "default", size, disabled, readOnly, invalid, required, className, children, id, "aria-labelledby": labelledBy, "aria-describedby": describedBy, ...props }, ref) {
+    const field = useFieldContext();
+    const [current, setCurrent] = useControllableState({ value, defaultValue: defaultValue ?? [], onChange: onValueChange, name: "CheckboxGroup" });
+    const order = React.useRef([]);
+    order.current = items?.map((i) => i.value) ?? [];
+    const toggle = React.useCallback((v, checked) => setCurrent((prev) => {
+        if (checked === prev.includes(v))
+            return prev;
+        const next = checked ? [...prev, v] : prev.filter((x) => x !== v);
+        // Keep the order of the items list, so the value is stable regardless of click order.
+        return order.current.length ? next.sort((a, b) => order.current.indexOf(a) - order.current.indexOf(b)) : next;
+    }), [setCurrent]);
+    const ctx = React.useMemo(() => ({
+        value: current,
+        toggle,
+        name: name ?? field?.name,
+        disabled: disabled ?? field?.disabled,
+        readOnly: readOnly ?? field?.readOnly,
+        invalid: invalid ?? field?.invalid,
+        size,
+        variant,
+    }), [current, toggle, name, field?.name, disabled, field?.disabled, readOnly, field?.readOnly, invalid, field?.invalid, size, variant]);
+    const isRequired = required ?? field?.required;
+    return (_jsx("div", { ...props, ref: ref, role: "group", "data-slot": "checkbox-group", "data-orientation": orientation, "aria-labelledby": labelledBy ?? (props["aria-label"] ? undefined : field?.labelId), "aria-describedby": mergeIds(field?.describedBy, describedBy), "aria-invalid": ctx.invalid || undefined, "aria-required": isRequired || undefined, id: id ?? field?.id, className: cn(variant === "card"
+            ? "grid gap-2.5 sm:grid-cols-[repeat(auto-fill,minmax(14rem,1fr))]"
+            : orientation === "horizontal"
+                ? "flex flex-wrap items-start gap-x-6 gap-y-2.5"
+                : "grid gap-2.5", className), children: _jsx(FieldContextReset, { children: _jsxs(CheckboxGroupContext.Provider, { value: ctx, children: [items?.map((item) => (_jsx(CheckboxGroupItem, { value: item.value, label: item.label, description: item.description, icon: item.icon, disabled: item.disabled }, item.value))), children] }) }) }));
+});
+/** One option inside a `CheckboxGroup`. */
+export const CheckboxGroupItem = React.forwardRef(function CheckboxGroupItem(props, ref) {
+    return _jsx(Checkbox, { ref: ref, ...props });
+});

package/dist/components/color-picker.d.ts

@@ -0,0 +1,112 @@
+import * as React from "react";
+import { type ColorFormat } from "../lib/color.js";
+declare const colorLabels: {
+    dialog: string;
+    area: string;
+    hue: string;
+    alpha: string;
+    input: string;
+    format: string;
+    swatches: string;
+    swatch: string;
+    eyeDropper: string;
+    invalid: string;
+    contrast: string;
+    ratio: string;
+    aaa: string;
+    aa: string;
+    aaLarge: string;
+    fail: string;
+    transparent: string;
+};
+export type ColorPickerLabels = typeof colorLabels;
+/** One preset colour. `name` is what screen readers hear ("Lime, #c6f432"). */
+export interface ColorSwatch {
+    value: string;
+    name?: string;
+}
+export interface ColorSwatchPickerProps {
+    swatches: ColorSwatch[] | "tokens";
+    value?: string | null;
+    defaultValue?: string | null;
+    onValueChange?: (hex: string) => void;
+    size?: "sm" | "md";
+    name?: string;
+    disabled?: boolean;
+    id?: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    className?: string;
+    labels?: Partial<ColorPickerLabels>;
+}
+/**
+ * A row of preset colours as a radio group (one tab stop, arrow keys move and select). For label
+ * colours, calendar categories and campaign colours where a free picker is too much.
+ */
+export declare const ColorSwatchPicker: React.ForwardRefExoticComponent<ColorSwatchPickerProps & React.RefAttributes<HTMLDivElement>>;
+export interface ColorPickerPanelProps {
+    value: string;
+    onValueChange: (hex: string) => void;
+    alpha?: boolean;
+    swatches?: ColorSwatch[] | "tokens";
+    eyeDropper?: boolean;
+    format?: ColorFormat;
+    onFormatChange?: (format: ColorFormat) => void;
+    /** Show a format switch (HEX / RGB / OKLCH) above the input. Default `true`. */
+    showFormats?: boolean;
+    contrastAgainst?: string;
+    disabled?: boolean;
+    className?: string;
+    labels?: Partial<ColorPickerLabels>;
+}
+/** The picker body: saturation/brightness area, hue (and opacity) strip, value input, swatches, contrast. */
+export declare function ColorPickerPanel({ value, onValueChange, alpha, swatches, eyeDropper, format: formatProp, onFormatChange, showFormats, contrastAgainst, disabled, className, labels, }: ColorPickerPanelProps): React.JSX.Element;
+export interface ColorPickerProps {
+    /** `"#rrggbb"`, or `"#rrggbbaa"` with `alpha`. */
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (hex: string) => void;
+    /** Add an opacity strip; values become `#rrggbbaa` when not fully opaque. */
+    alpha?: boolean;
+    /** Preset colours under the picker, or `"tokens"` for the theme palette. */
+    swatches?: ColorSwatch[] | "tokens";
+    /** Screen colour picker button (only where the EyeDropper API exists). Default `true`. */
+    eyeDropper?: boolean;
+    /** Display / input format; the value is always hex. Default `"hex"`. */
+    format?: ColorFormat;
+    defaultFormat?: ColorFormat;
+    onFormatChange?: (format: ColorFormat) => void;
+    /** Show the HEX / RGB / OKLCH switch. Default `true`. */
+    showFormats?: boolean;
+    /** Show the WCAG contrast ratio of the colour against this one (e.g. `"#ffffff"` for button text). */
+    contrastAgainst?: string;
+    /** `"popover"` (default): swatch button + floating panel. `"inline"`: the panel in place. */
+    variant?: "popover" | "inline";
+    name?: string;
+    size?: "sm" | "md" | "lg";
+    disabled?: boolean;
+    invalid?: boolean;
+    readOnly?: boolean;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    id?: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    className?: string;
+    labels?: Partial<ColorPickerLabels>;
+}
+/**
+ * Choose a colour: website brand colour, label colours, campaign or chart series colour.
+ * Saturation/brightness area and hue strip are keyboard sliders; the value field accepts hex,
+ * `rgb()` and `oklch()`; swatches are a radio group; an optional WCAG contrast hint shows whether
+ * text on the colour stays readable. The value is always hex.
+ *
+ * ```tsx
+ * <Field label="Brand color"><ColorPicker name="brand" defaultValue="#c6f432" contrastAgainst="#12150f" /></Field>
+ * <ColorPicker alpha swatches="tokens" variant="inline" />
+ * ```
+ */
+export declare const ColorPicker: React.ForwardRefExoticComponent<ColorPickerProps & React.RefAttributes<HTMLButtonElement>>;
+export {};

package/dist/components/color-picker.js

@@ -0,0 +1,235 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { HexAlphaColorPicker, HexColorPicker } from "react-colorful";
+import { RadioGroup as RadioGroupPrimitive } from "radix-ui";
+import { Check, ChevronDown, Pipette } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { mergeIds } from "../lib/compose-refs.js";
+import { FieldContextReset, useFieldContext, useFieldControl } from "../lib/field-context.js";
+import { useLabels } from "../lib/labels.js";
+import { useFormat } from "../lib/locale.js";
+import { contrastLevel, contrastRatio, formatColor, parseColor, readableOn, rgbaToHex } from "../lib/color.js";
+import { useControllableState } from "../lib/use-controllable-state.js";
+import { controlVariants } from "../lib/variants.js";
+import { Popover, PopoverContent, PopoverTrigger } from "./popover.js";
+import { RadioGroup } from "./radio-group.js";
+const colorLabels = {
+    dialog: "Pick a color",
+    area: "Saturation and brightness",
+    hue: "Hue",
+    alpha: "Opacity",
+    input: "Color value",
+    format: "Color format",
+    swatches: "Swatches",
+    swatch: "{name}, {value}",
+    eyeDropper: "Pick a color from the screen",
+    invalid: "Enter a hex, rgb() or oklch() color",
+    contrast: "Contrast with {against}",
+    ratio: "{ratio}:1",
+    aaa: "AAA",
+    aa: "AA",
+    aaLarge: "AA large text",
+    fail: "Fails",
+    transparent: "Transparent",
+};
+/** Theme tokens offered by `swatches="tokens"` (resolved to hex in the browser). */
+const TOKEN_SWATCHES = [
+    { token: "--accent", name: "Accent" },
+    { token: "--chart-2", name: "Blue" },
+    { token: "--chart-5", name: "Teal" },
+    { token: "--success", name: "Green" },
+    { token: "--chart-3", name: "Orange" },
+    { token: "--warning", name: "Amber" },
+    { token: "--danger", name: "Red" },
+    { token: "--chart-6", name: "Rose" },
+    { token: "--chart-4", name: "Violet" },
+    { token: "--fg-muted", name: "Gray" },
+];
+/** Resolves `"tokens"` to concrete hex swatches from the current theme. */
+function useSwatches(swatches, probe) {
+    const [resolved, setResolved] = React.useState([]);
+    React.useEffect(() => {
+        if (swatches !== "tokens" || !probe.current)
+            return;
+        const el = document.createElement("span");
+        probe.current.appendChild(el);
+        const out = [];
+        for (const { token, name } of TOKEN_SWATCHES) {
+            el.style.color = `var(${token})`;
+            const c = parseColor(getComputedStyle(el).color);
+            if (c)
+                out.push({ value: rgbaToHex({ ...c, a: 1 }), name });
+        }
+        el.remove();
+        setResolved(out);
+    }, [swatches, probe]);
+    if (swatches === "tokens")
+        return resolved;
+    return swatches ?? [];
+}
+/**
+ * A row of preset colours as a radio group (one tab stop, arrow keys move and select). For label
+ * colours, calendar categories and campaign colours where a free picker is too much.
+ */
+export const ColorSwatchPicker = React.forwardRef(function ColorSwatchPicker({ swatches: swatchesProp, value: valueProp, defaultValue, onValueChange, size = "md", name: nameProp, disabled, id, className, labels, ...aria }, ref) {
+    const t = useLabels("colorPicker", colorLabels, labels);
+    const field = useFieldContext();
+    const probe = React.useRef(null);
+    const swatches = useSwatches(swatchesProp, probe);
+    const [value, setValue] = useControllableState({
+        value: valueProp === undefined ? undefined : (valueProp?.toLowerCase() ?? null),
+        defaultValue: defaultValue?.toLowerCase() ?? null,
+        onChange: (v) => v && onValueChange?.(v),
+        name: "ColorSwatchPicker",
+    });
+    const isDisabled = disabled ?? field?.disabled;
+    return (_jsx(RadioGroupPrimitive.Root, { ref: (node) => {
+            probe.current = node;
+            if (typeof ref === "function")
+                ref(node);
+            else if (ref)
+                ref.current = node;
+        }, "data-slot": "color-swatch-picker", id: id ?? field?.id, name: nameProp ?? field?.name, disabled: isDisabled, value: value ?? "", onValueChange: (v) => setValue(v), orientation: "horizontal", loop: true, "aria-label": aria["aria-label"] ?? (aria["aria-labelledby"] || field?.labelId ? undefined : t("swatches")), "aria-labelledby": aria["aria-labelledby"] ?? (aria["aria-label"] ? undefined : field?.labelId), "aria-describedby": field?.describedBy, className: cn("flex flex-wrap items-center", size === "sm" ? "gap-1.5" : "gap-2", className), children: _jsx(FieldContextReset, { children: swatches.map((s) => {
+                const hex = s.value.toLowerCase();
+                return (_jsxs(RadioGroupPrimitive.Item, { value: hex, "aria-label": s.name ? t("swatch", { name: s.name, value: hex }) : hex, "data-slot": "color-swatch", className: cn("ui-checker group/swatch relative inline-flex shrink-0 items-center justify-center overflow-hidden rounded-full outline-none", "shadow-[inset_0_0_0_1px_color-mix(in_srgb,var(--fg)_14%,transparent)] transition-transform duration-100", "hover:scale-110 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-(--surface-solid)", "data-[state=checked]:ring-2 data-[state=checked]:ring-fg data-[state=checked]:ring-offset-2 data-[state=checked]:ring-offset-(--surface-solid)", "disabled:cursor-not-allowed disabled:opacity-50 disabled:hover:scale-100 motion-reduce:transition-none motion-reduce:hover:scale-100", size === "sm" ? "size-5" : "size-7"), children: [_jsx("span", { "aria-hidden": true, className: "absolute inset-0", style: { background: hex } }), _jsx(RadioGroupPrimitive.Indicator, { className: "relative", style: { color: readableOn(hex) }, children: _jsx(Check, { "aria-hidden": true, strokeWidth: 3, className: size === "sm" ? "size-3" : "size-3.5" }) })] }, hex));
+            }) }) }));
+});
+/* ------------------------------------------------------------------ */
+/* Contrast hint                                                       */
+/* ------------------------------------------------------------------ */
+function ContrastHint({ color, against, t }) {
+    const f = useFormat();
+    const ratio = contrastRatio(color, against);
+    if (ratio === null)
+        return null;
+    const level = contrastLevel(ratio);
+    const levelText = level === "AAA" ? t("aaa") : level === "AA" ? t("aa") : level === "AA-large" ? t("aaLarge") : t("fail");
+    const ok = level === "AAA" || level === "AA";
+    return (_jsxs("div", { "data-slot": "color-contrast", className: "flex items-center gap-2.5 rounded-ui-sm border border-line bg-surface-2 p-1.5 pe-2.5", children: [_jsxs("span", { "aria-hidden": true, className: "ui-checker relative flex h-7 w-10 shrink-0 items-center justify-center overflow-hidden rounded-[6px] text-[13px] font-semibold", children: [_jsx("span", { className: "absolute inset-0", style: { background: color } }), _jsx("span", { className: "relative", style: { color: against }, children: "Aa" })] }), _jsxs("span", { className: "min-w-0 flex-1 text-xs leading-tight text-fg-muted", children: [t("contrast", { against: formatColor(against) }), _jsx("span", { className: "block font-medium text-fg tabular", children: t("ratio", { ratio: f.number(Math.floor(ratio * 10) / 10, { minimumFractionDigits: 1, maximumFractionDigits: 1 }) }) })] }), _jsx("span", { className: cn("inline-flex h-5 shrink-0 items-center rounded-full px-2 text-[11px] font-medium", ok ? "tone-success tone-soft" : level === "AA-large" ? "tone-warning tone-soft" : "tone-danger tone-soft"), children: levelText })] }));
+}
+/** The picker body: saturation/brightness area, hue (and opacity) strip, value input, swatches, contrast. */
+export function ColorPickerPanel({ value, onValueChange, alpha = false, swatches, eyeDropper = true, format: formatProp, onFormatChange, showFormats = true, contrastAgainst, disabled, className, labels, }) {
+    const t = useLabels("colorPicker", colorLabels, labels);
+    const [format, setFormat] = useControllableState({ value: formatProp, defaultValue: "hex", onChange: onFormatChange, name: "ColorPicker" });
+    const areaRef = React.useRef(null);
+    const [draft, setDraft] = React.useState(null);
+    const [draftInvalid, setDraftInvalid] = React.useState(false);
+    const [canDrop, setCanDrop] = React.useState(false);
+    const inputId = React.useId();
+    const errorId = React.useId();
+    const hasAlpha = alpha;
+    const hex = value.toLowerCase();
+    React.useEffect(() => setCanDrop(typeof window !== "undefined" && "EyeDropper" in window), []);
+    // react-colorful names its sliders in English ("Color", "Hue", "Alpha"): use the dictionary.
+    React.useEffect(() => {
+        const sliders = areaRef.current?.querySelectorAll('[role="slider"]');
+        if (!sliders)
+            return;
+        const names = [t("area"), t("hue"), t("alpha")];
+        sliders.forEach((s, i) => {
+            s.setAttribute("aria-label", names[i] ?? "");
+            if (disabled)
+                s.setAttribute("tabindex", "-1");
+            else
+                s.setAttribute("tabindex", "0");
+            s.setAttribute("aria-disabled", disabled ? "true" : "false");
+        });
+    }, [t, disabled, hasAlpha]);
+    const commitText = (text, final) => {
+        const c = parseColor(text);
+        if (!c) {
+            if (final)
+                setDraftInvalid(true);
+            return;
+        }
+        const raw = text.trim().replace(/^#/, "");
+        // While typing hex, wait for a complete value (6 or 8 digits) before applying.
+        if (!final && /^[0-9a-f]*$/i.test(raw) && raw.length !== 6 && raw.length !== 8)
+            return;
+        setDraftInvalid(false);
+        onValueChange(rgbaToHex(hasAlpha ? c : { ...c, a: 1 }, hasAlpha && c.a < 1));
+        if (final)
+            setDraft(null);
+    };
+    const shown = draft ?? (format === "hex" ? formatColor(hex, "hex").slice(1) : formatColor(hex, format));
+    const Picker = hasAlpha ? HexAlphaColorPicker : HexColorPicker;
+    const resolvedSwatches = swatches;
+    return (_jsxs("div", { "data-slot": "color-picker-panel", className: cn("grid min-w-0 grid-cols-[minmax(0,1fr)] gap-3", disabled && "pointer-events-none opacity-60", className), children: [_jsx("div", { ref: areaRef, "data-slot": "color-picker-area", className: "ui-color-area", children: _jsx(Picker, { color: hex, onChange: (v) => onValueChange(hasAlpha ? (v.length === 9 && v.endsWith("ff") ? v.slice(0, 7) : v) : v) }) }), _jsxs("div", { className: "grid grid-cols-[minmax(0,1fr)] gap-2", children: [showFormats ? (_jsx(RadioGroup, { variant: "segmented", size: "sm", "aria-label": t("format"), value: format, onValueChange: (v) => {
+                            setFormat(v);
+                            setDraft(null);
+                            setDraftInvalid(false);
+                        }, className: "w-full [&>*]:flex-1", items: [
+                            { value: "hex", label: "HEX" },
+                            { value: "rgb", label: "RGB" },
+                            { value: "oklch", label: "OKLCH" },
+                        ] })) : null, _jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { "aria-hidden": true, className: "ui-checker relative size-(--control-h) shrink-0 overflow-hidden rounded-ui border border-field-border", children: _jsx("span", { className: "absolute inset-0", style: { background: hex } }) }), _jsx("label", { htmlFor: inputId, className: "sr-only", children: t("input") }), _jsxs("div", { className: cn(controlVariants({ size: "md" }), "min-w-0 flex-1 gap-0 px-0"), "data-slot": "color-picker-input", children: [format === "hex" ? (_jsx("span", { "aria-hidden": true, className: "ps-3 font-mono text-[13px] text-fg-subtle", children: "#" })) : null, _jsx("input", { id: inputId, value: shown, spellCheck: false, autoComplete: "off", disabled: disabled, "aria-invalid": draftInvalid || undefined, "aria-describedby": draftInvalid ? errorId : undefined, onChange: (e) => {
+                                            setDraft(e.target.value);
+                                            setDraftInvalid(false);
+                                            commitText(e.target.value, false);
+                                        }, onBlur: () => {
+                                            if (draft !== null)
+                                                commitText(draft, true);
+                                        }, onKeyDown: (e) => {
+                                            if (e.key === "Enter" && draft !== null) {
+                                                e.preventDefault();
+                                                commitText(draft, true);
+                                            }
+                                            if (e.key === "Escape" && draft !== null) {
+                                                e.stopPropagation();
+                                                setDraft(null);
+                                                setDraftInvalid(false);
+                                            }
+                                        }, className: cn("h-full min-w-0 flex-1 bg-transparent font-mono text-[13px] text-fg outline-none tabular", format === "hex" ? "ps-1 pe-3" : "px-3") })] }), eyeDropper && canDrop ? (_jsx("button", { type: "button", "aria-label": t("eyeDropper"), disabled: disabled, onClick: async () => {
+                                    try {
+                                        const Dropper = window.EyeDropper;
+                                        const res = await new Dropper().open();
+                                        const picked = parseColor(res.sRGBHex);
+                                        if (picked)
+                                            onValueChange(rgbaToHex({ ...picked, a: 1 }));
+                                    }
+                                    catch {
+                                        /* cancelled */
+                                    }
+                                }, className: "inline-flex size-(--control-h) shrink-0 items-center justify-center rounded-ui border border-field-border bg-field text-fg-muted transition-colors hover:border-field-border-hover hover:text-fg focus-ring [&_svg]:size-4", children: _jsx(Pipette, { "aria-hidden": true }) })) : null] }), draftInvalid ? (_jsx("p", { id: errorId, role: "alert", className: "text-xs text-danger", children: t("invalid") })) : null] }), resolvedSwatches && (resolvedSwatches === "tokens" || resolvedSwatches.length > 0) ? (_jsx(ColorSwatchPicker, { swatches: resolvedSwatches, size: "sm", value: hex.slice(0, 7), onValueChange: (v) => onValueChange(v), disabled: disabled, labels: labels, className: "border-t border-line pt-3" })) : null, contrastAgainst ? _jsx(ContrastHint, { color: hex, against: contrastAgainst, t: t }) : null] }));
+}
+/**
+ * Choose a colour: website brand colour, label colours, campaign or chart series colour.
+ * Saturation/brightness area and hue strip are keyboard sliders; the value field accepts hex,
+ * `rgb()` and `oklch()`; swatches are a radio group; an optional WCAG contrast hint shows whether
+ * text on the colour stays readable. The value is always hex.
+ *
+ * ```tsx
+ * <Field label="Brand color"><ColorPicker name="brand" defaultValue="#c6f432" contrastAgainst="#12150f" /></Field>
+ * <ColorPicker alpha swatches="tokens" variant="inline" />
+ * ```
+ */
+export const ColorPicker = React.forwardRef(function ColorPicker(props, ref) {
+    const { value: valueProp, defaultValue, onValueChange, alpha, swatches, eyeDropper, format: formatProp, defaultFormat, onFormatChange, showFormats, contrastAgainst, variant = "popover", name: nameProp, size = "md", invalid, open: openProp, defaultOpen, onOpenChange, className, labels, } = props;
+    const t = useLabels("colorPicker", colorLabels, labels);
+    const field = useFieldContext();
+    const control = useFieldControl({
+        id: props.id,
+        name: nameProp,
+        disabled: props.disabled,
+        readOnly: props.readOnly,
+        "aria-invalid": invalid ? true : undefined,
+        "aria-label": props["aria-label"],
+        "aria-labelledby": props["aria-labelledby"],
+        "aria-describedby": props["aria-describedby"],
+    });
+    const [value, setValue] = useControllableState({ value: valueProp, defaultValue: defaultValue ?? "#000000", onChange: onValueChange, name: "ColorPicker" });
+    const [format, setFormat] = useControllableState({ value: formatProp, defaultValue: defaultFormat ?? "hex", onChange: onFormatChange, name: "ColorPicker" });
+    const [open, setOpen] = useControllableState({ value: openProp, defaultValue: defaultOpen ?? false, onChange: onOpenChange, name: "ColorPicker" });
+    const valueId = React.useId();
+    const disabled = Boolean(control.disabled);
+    const readOnly = Boolean(control.readOnly);
+    const hex = (parseColor(value) ? value : "#000000").toLowerCase();
+    const transparent = parseColor(hex)?.a === 0;
+    const panel = (_jsx(ColorPickerPanel, { value: hex, onValueChange: setValue, alpha: alpha, swatches: swatches, eyeDropper: eyeDropper, format: format, onFormatChange: setFormat, showFormats: showFormats, contrastAgainst: contrastAgainst, disabled: disabled || readOnly, labels: labels }));
+    const hidden = control.name ? _jsx("input", { type: "hidden", name: control.name, value: hex }) : null;
+    if (variant === "inline") {
+        return (_jsxs("div", { "data-slot": "color-picker", "data-variant": "inline", role: "group", "aria-label": control["aria-label"] ?? (control["aria-labelledby"] || field?.labelId ? undefined : t("dialog")), "aria-labelledby": control["aria-labelledby"] ?? (control["aria-label"] ? undefined : field?.labelId), "aria-describedby": control["aria-describedby"], className: cn("w-72 max-w-full rounded-ui-lg border border-line bg-surface p-3", className), children: [_jsx(FieldContextReset, { children: panel }), hidden] }));
+    }
+    return (_jsxs(Popover, { open: readOnly || disabled ? false : open, onOpenChange: (o) => !readOnly && !disabled && setOpen(o), children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs("button", { ref: ref, type: "button", "data-slot": "color-picker", "data-readonly": readOnly ? "" : undefined, id: control.id, disabled: disabled, "aria-label": control["aria-label"], "aria-labelledby": control["aria-labelledby"], "aria-describedby": mergeIds(control["aria-describedby"], valueId), "aria-invalid": control["aria-invalid"] || undefined, className: cn(controlVariants({ size }), "justify-start text-start font-mono tabular", size === "sm" ? "ps-1" : "ps-1.5", className), children: [_jsx("span", { "aria-hidden": true, className: cn("ui-checker relative shrink-0 overflow-hidden rounded-[calc(var(--radius)-5px)] shadow-[inset_0_0_0_1px_color-mix(in_srgb,var(--fg)_14%,transparent)]", size === "sm" ? "size-5" : size === "lg" ? "size-8" : "size-6.5"), children: _jsx("span", { className: "absolute inset-0", style: { background: hex } }) }), _jsx("span", { id: valueId, className: "min-w-0 flex-1 truncate text-[0.95em]", children: transparent ? t("transparent") : formatColor(hex, format) }), readOnly ? null : _jsx(ChevronDown, { "aria-hidden": true, className: "shrink-0 text-fg-subtle" })] }) }), hidden, _jsx(PopoverContent, { size: "auto", align: "start", "aria-label": t("dialog"), className: "w-72", children: _jsx(FieldContextReset, { children: panel }) })] }));
+});

package/dist/components/combobox.d.ts

@@ -0,0 +1,136 @@
+import * as React from "react";
+import { type AsyncLoader } from "../lib/use-async-list.js";
+declare const comboboxLabels: {
+    placeholder: string;
+    placeholderMultiple: string;
+    search: string;
+    empty: string;
+    create: string;
+    results: string;
+    error: string;
+    retry: string;
+    loading: string;
+    loadMore: string;
+    clear: string;
+    selected: string;
+    selectedCount: string;
+    remove: string;
+    more: string;
+    moreLabel: string;
+};
+export type ComboboxLabels = typeof comboboxLabels;
+/** The default item shape. Any other shape works with `getValue` / `getLabel`. */
+export interface ComboboxOption {
+    value: string;
+    label: string;
+    description?: string;
+    icon?: React.ReactNode;
+    disabled?: boolean;
+    /** Extra searchable text (email, code, former name). */
+    keywords?: string[];
+    /** Items with the same group render under one heading. */
+    group?: string;
+}
+export interface ComboboxItemState {
+    selected: boolean;
+    /** The current search text (for your own highlighting). */
+    query: string;
+    /** The label split into matched / unmatched parts (locale-folded). */
+    highlight: React.ReactNode;
+}
+interface ComboboxCommonProps<T> {
+    /** Static items (filtered client-side with locale folding: "istanbul" finds "İstanbul"). */
+    items?: T[];
+    /**
+     * Server search. Called (debounced, abortable) with the query; return an array or
+     * `{ items, cursor }` for paging. Called with `cursor` for the next page.
+     */
+    loadItems?: AsyncLoader<T>;
+    /** Debounce for `loadItems` in ms. Default 200. */
+    debounce?: number;
+    getValue?: (item: T) => string;
+    getLabel?: (item: T) => string;
+    /** Extra searchable text per item. Default: `item.keywords`. */
+    getKeywords?: (item: T) => string[] | undefined;
+    getDisabled?: (item: T) => boolean;
+    getGroup?: (item: T) => string | undefined;
+    /** Custom row content (avatar + email…). The check indicator is added for you. */
+    renderItem?: (item: T, state: ComboboxItemState) => React.ReactNode;
+    /**
+     * Shows a "Create “…”" row for unknown text. Return the new item to select it
+     * (or a promise of it); return nothing to handle selection yourself.
+     */
+    onCreate?: (query: string) => T | void | Promise<T | void>;
+    /** Labels for values that aren't in the current list (async initial values). */
+    selectedItems?: T[];
+    /** Trigger text with no selection. */
+    placeholder?: string;
+    /** Placeholder of the search box. */
+    searchPlaceholder?: string;
+    /** Shown when nothing matches. */
+    emptyMessage?: React.ReactNode;
+    size?: "sm" | "md" | "lg";
+    variant?: "default" | "ghost" | "pill";
+    /** `"popover"` (default): trigger + floating list. `"inline"`: the search and list in place. */
+    mode?: "popover" | "inline";
+    /** Static items are still loading. */
+    loading?: boolean;
+    name?: string;
+    disabled?: boolean;
+    invalid?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Close after picking. Default: `true` for single, `false` for multiple. */
+    closeOnSelect?: boolean;
+    id?: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    /** Classes for the root (trigger box or inline panel). */
+    className?: string;
+    /** Classes for the popover panel. */
+    contentClassName?: string;
+    /** Max height of the list. Default 18rem. */
+    listClassName?: string;
+    /** Built-in string overrides (`combobox` namespace). */
+    labels?: Partial<ComboboxLabels>;
+}
+export interface ComboboxSingleProps<T> extends ComboboxCommonProps<T> {
+    multiple?: false;
+    value?: string | null;
+    defaultValue?: string | null;
+    onValueChange?: (value: string | null, item: T | null) => void;
+    /** Show a clear (×) button while there is a value. */
+    clearable?: boolean;
+    maxVisibleChips?: never;
+}
+export interface ComboboxMultipleProps<T> extends ComboboxCommonProps<T> {
+    multiple: true;
+    value?: string[];
+    defaultValue?: string[];
+    onValueChange?: (value: string[], items: T[]) => void;
+    /** Collapse chips beyond this count into "+N". */
+    maxVisibleChips?: number;
+    clearable?: boolean;
+}
+export type ComboboxProps<T = ComboboxOption> = ComboboxSingleProps<T> | ComboboxMultipleProps<T>;
+/**
+ * Searchable selection — single or multiple, static or server-backed, optionally creatable:
+ * city, assignee, category, country, tags. WAI-ARIA combobox + listbox in a popover (or inline).
+ * Search folds locale characters, so "istanbul" finds "İstanbul" and "cagri" finds "Çağrı";
+ * matches are highlighted by weight, not colour (readable on glass).
+ *
+ * ```tsx
+ * <Field label="City"><Combobox name="city" items={cities} /></Field>
+ * <Combobox multiple items={labels} defaultValue={["urgent"]} maxVisibleChips={3} />
+ * <Combobox loadItems={(q, signal) => fetch(`/api/people?q=${q}`, { signal }).then((r) => r.json())} />
+ * <Combobox items={categories} onCreate={async (name) => api.createCategory(name)} />
+ * ```
+ */
+export declare const Combobox: <T = ComboboxOption>(props: ComboboxProps<T> & {
+    ref?: React.Ref<HTMLButtonElement>;
+}) => React.ReactElement;
+export {};