@godxjp/ui 19.6.0 → 20.1.0

package/dist/components/data-entry/cascader.js

@@ -1,11 +1,17 @@
 "use client";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
-import { Check, ChevronRight, ChevronsUpDown, Minus, X } from "lucide-react";
+import { Check, ChevronRight, ChevronsUpDown, Loader2, Minus, X } from "lucide-react";
 import { useTranslation } from "../../i18n/use-translation.js";
 import { cn } from "../../lib/utils.js";
 import { pickFieldA11y, useFieldIdentity } from "../../lib/field-a11y.js";
-import { controlTriggerClass } from "../../lib/control-styles.js";
+import { controlSurfaceTriggerClass } from "../../lib/control-styles.js";
+import {
+  applyMaxTagCount,
+  controlSurfaceAttrs,
+  resolveAllowClear,
+  resolveAriaInvalid
+} from "./control-surface.js";
 import { Popover, PopoverContent, PopoverTrigger } from "../data-display/popover.js";
 import { ScrollArea, ScrollBar } from "../data-display/scroll-area.js";
 import { Command, CommandInput } from "./command.js";
@@ -15,7 +21,8 @@ import {
   getNodeByPath,
   normalizeTreeOptions,
   pathKey,
-  pathsEqual
+  pathsEqual,
+  reactNodeText
 } from "./tree-utils.js";
 function pathInValues(path, values) {
   return values.some((v) => pathsEqual(v, path));
@@ -66,6 +73,41 @@ function aggregateCheckState(node, path, values) {
   if (total === 0 || selected === 0) return "none";
   return selected === total ? "checked" : "indeterminate";
 }
+function leafPathsUnder(node, path) {
+  const out = [];
+  const walk = (current, prefix) => {
+    const isLeaf = (current.children?.length ?? 0) === 0 || current.isLeaf === true;
+    if (isLeaf) {
+      out.push(prefix);
+      return;
+    }
+    for (const child of current.children) walk(child, [...prefix, child.value]);
+  };
+  walk(node, path);
+  return out;
+}
+function collapseToParents(values, options) {
+  const representative = /* @__PURE__ */ new Map();
+  const walk = (nodes, prefix) => {
+    for (const node of nodes) {
+      const path = [...prefix, node.value];
+      const hasChildren = (node.children?.length ?? 0) > 0 && node.isLeaf !== true;
+      if (!hasChildren) continue;
+      if (aggregateCheckState(node, path, values) === "checked") {
+        for (const leaf of leafPathsUnder(node, path)) representative.set(pathKey(leaf), path);
+        continue;
+      }
+      walk(node.children, path);
+    }
+  };
+  walk(options, []);
+  const out = [];
+  for (const value of values) {
+    const shown = representative.get(pathKey(value)) ?? value;
+    if (!out.some((existing) => pathsEqual(existing, shown))) out.push(shown);
+  }
+  return out;
+}
 function Cascader({
   options: optionsProp,
   value,
@@ -76,25 +118,76 @@ function Cascader({
   showSearch,
   placeholder,
   disabled,
+  readOnly,
+  name,
   className,
   id,
   expandTrigger = "click",
   fieldNames,
-  allowClear = true,
+  allowClear,
+  size,
+  status,
+  variant,
+  loading = false,
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  showCheckedStrategy = "SHOW_CHILD",
+  loadData,
+  displayRender,
+  optionRender,
+  maxTagCount,
+  maxTagPlaceholder,
+  notFoundContent,
+  autoClearSearchValue = true,
+  search: searchProp,
+  onSearchChange,
   ...ariaProps
 }) {
   const { t } = useTranslation();
   const fieldA11y = pickFieldA11y(ariaProps);
-  const identity = useFieldIdentity({ id, "data-field": fieldA11y["data-field"] });
+  const identity = useFieldIdentity({ id, name, "data-field": fieldA11y["data-field"] });
+  const resolvedName = name ?? identity.name;
   const reactId = React.useId();
   const panelId = `${id ?? reactId}-panel`;
   const options = React.useMemo(
     () => normalizeTreeOptions(optionsProp, fieldNames),
     [optionsProp, fieldNames]
   );
-  const [open, setOpen] = React.useState(false);
+  const [internalOpen, setInternalOpen] = React.useState(defaultOpen);
+  const isOpenControlled = openProp !== void 0;
+  const open = isOpenControlled ? openProp : internalOpen;
+  const setOpen = React.useCallback(
+    (next) => {
+      if (!isOpenControlled) setInternalOpen(next);
+      onOpenChange?.(next);
+    },
+    [isOpenControlled, onOpenChange]
+  );
   const [activePath, setActivePath] = React.useState([]);
-  const [search, setSearch] = React.useState("");
+  const [internalSearch, setInternalSearch] = React.useState("");
+  const isSearchControlled = searchProp !== void 0;
+  const search = isSearchControlled ? searchProp : internalSearch;
+  const setSearch = React.useCallback(
+    (next) => {
+      if (!isSearchControlled) setInternalSearch(next);
+      onSearchChange?.(next);
+    },
+    [isSearchControlled, onSearchChange]
+  );
+  const requestedLoads = React.useRef(/* @__PURE__ */ new Set());
+  const requestLoad = React.useCallback(
+    (path, chain) => {
+      if (!loadData) return;
+      const node = chain.at(-1);
+      if (!node || node.isLeaf === true || (node.children?.length ?? 0) > 0) return;
+      const key = pathKey(path);
+      if (requestedLoads.current.has(key)) return;
+      requestedLoads.current.add(key);
+      void loadData(chain);
+    },
+    [loadData]
+  );
   const isControlledSingle = !multiple && value !== void 0;
   const isControlledMulti = multiple && value !== void 0;
   const [internalSingle, setInternalSingle] = React.useState(
@@ -106,14 +199,52 @@ function Cascader({
   const singleValue = isControlledSingle ? value : internalSingle;
   const multiValue = isControlledMulti ? value : internalMulti;
   const resolvedPlaceholder = placeholder ?? t("dataEntry.cascader.placeholder");
+  const hasValue = multiple ? multiValue.length > 0 : singleValue.length > 0;
   const displayLabel = React.useMemo(() => {
     if (multiple) {
       if (!multiValue.length) return null;
-      return multiValue.map((path) => formatPathLabels(getNodeByPath(options, path))).join(", ");
+      const shown = showCheckedStrategy === "SHOW_PARENT" ? collapseToParents(multiValue, options) : multiValue;
+      const items = shown.map((path) => {
+        const chain2 = getNodeByPath(options, path);
+        const labels = chain2.map((node) => reactNodeText(node.label));
+        return {
+          value: pathKey(path),
+          label: displayRender ? displayRender(labels, chain2) : formatPathLabels(chain2)
+        };
+      });
+      const { visible, omitted, overflow } = applyMaxTagCount(
+        items,
+        maxTagCount,
+        maxTagPlaceholder
+      );
+      const body = visible.map((item, index) => /* @__PURE__ */ jsxs(React.Fragment, { children: [
+        index > 0 ? ", " : null,
+        item.label
+      ] }, item.value));
+      if (omitted.length === 0) return body;
+      return /* @__PURE__ */ jsxs(Fragment, { children: [
+        body,
+        ", ",
+        /* @__PURE__ */ jsx("span", { "data-slot": "cascader-overflow", children: overflow ?? t("dataEntry.selection.overflow", { count: omitted.length }) })
+      ] });
     }
     if (!singleValue.length) return null;
-    return formatPathLabels(getNodeByPath(options, singleValue));
-  }, [multiple, multiValue, singleValue, options]);
+    const chain = getNodeByPath(options, singleValue);
+    return displayRender ? displayRender(
+      chain.map((node) => reactNodeText(node.label)),
+      chain
+    ) : formatPathLabels(chain);
+  }, [
+    multiple,
+    multiValue,
+    singleValue,
+    options,
+    showCheckedStrategy,
+    displayRender,
+    maxTagCount,
+    maxTagPlaceholder,
+    t
+  ]);
   const setSingleValue = (path) => {
     if (!isControlledSingle) setInternalSingle(path);
     onValueChange?.(path, getNodeByPath(options, path));
@@ -122,7 +253,7 @@ function Cascader({
     setSingleValue(path);
     setOpen(false);
     setActivePath([]);
-    setSearch("");
+    if (autoClearSearchValue) setSearch("");
   };
   const commitMulti = (paths) => {
     if (!isControlledMulti) setInternalMulti(paths);
@@ -143,6 +274,11 @@ function Cascader({
   }, [options, activePath]);
   const handleSelectNode = (node, path) => {
     const hasChildren = (node.children?.length ?? 0) > 0 && node.isLeaf !== true;
+    requestLoad(path, getNodeByPath(options, path));
+    if (loadData && node.isLeaf === false && !(node.children?.length ?? 0)) {
+      setActivePath(path);
+      return;
+    }
     if (multiple) {
       if (hasChildren && !changeOnSelect) setActivePath(path);
       else if (!node.disableCheckbox) commitMulti(togglePath(multiValue, path));
@@ -161,11 +297,12 @@ function Cascader({
     [options, search, isSearching]
   );
   const handleOpenChange = (next) => {
+    if (readOnly && next) return;
     setOpen(next);
     if (next) {
       setActivePath(multiple ? [] : singleValue);
     } else {
-      setSearch("");
+      if (autoClearSearchValue) setSearch("");
       setActivePath([]);
     }
   };
@@ -208,7 +345,11 @@ function Cascader({
                 // deeper column but keeps its own. Never collapse on the column's mouseleave
                 // — moving the pointer toward the next column would strand the deeper levels
                 // and make a depth-3 leaf unreachable.
-                expandTrigger === "hover" && !node.disabled ? () => setActivePath(hasChildren ? path : path.slice(0, -1)) : void 0
+                expandTrigger === "hover" && !node.disabled ? () => {
+                  const loadable = node.isLeaf === false && !(node.children?.length ?? 0);
+                  requestLoad(path, getNodeByPath(options, path));
+                  setActivePath(hasChildren || loadable ? path : path.slice(0, -1));
+                } : void 0
               ),
               onClick: () => !node.disabled && handleSelectNode(node, path),
               children: [
@@ -222,8 +363,8 @@ function Cascader({
                   }
                 ),
                 !multiple && selected && /* @__PURE__ */ jsx(Check, { className: "ui-cascader-option-icon", "aria-hidden": "true" }),
-                /* @__PURE__ */ jsx("span", { className: "flex-1 truncate text-start", children: node.label }),
-                hasChildren && /* @__PURE__ */ jsx(ChevronRight, { className: "ui-cascader-option-chevron", "aria-hidden": "true" })
+                /* @__PURE__ */ jsx("span", { className: "flex-1 truncate text-start", children: optionRender ? optionRender(node) : node.label }),
+                (hasChildren || loadData && node.isLeaf === false) && /* @__PURE__ */ jsx(ChevronRight, { className: "ui-cascader-option-chevron", "aria-hidden": "true" })
               ]
             }
           ) }, node.value);
@@ -233,7 +374,9 @@ function Cascader({
     )) }),
     /* @__PURE__ */ jsx(ScrollBar, { orientation: "horizontal" })
   ] });
-  const showClear = allowClear && displayLabel && !disabled;
+  const clearControl = resolveAllowClear(allowClear, true, t("dataEntry.cascader.clear"));
+  const showClear = clearControl.enabled && hasValue && !disabled && !readOnly && !loading;
+  const surface = controlSurfaceAttrs({ variant, status, size });
   return /* @__PURE__ */ jsxs("div", { className: cn("relative", className), children: [
     /* @__PURE__ */ jsxs(Popover, { open, onOpenChange: handleOpenChange, children: [
       /* @__PURE__ */ jsx(PopoverTrigger, { asChild: true, children: /* @__PURE__ */ jsx(
@@ -247,17 +390,31 @@ function Cascader({
           "aria-haspopup": "listbox",
           "aria-controls": open ? panelId : void 0,
           ...fieldA11y,
+          ...surface,
+          "aria-invalid": resolveAriaInvalid(fieldA11y["aria-invalid"], status),
+          "aria-busy": loading || void 0,
+          "aria-readonly": readOnly || void 0,
           disabled,
           className: cn(
-            controlTriggerClass,
+            controlSurfaceTriggerClass,
             "w-full justify-start",
             // Reserve trailing room for the single clear-or-chevron overlay rendered below.
             "ui-control-trigger-affixed",
-            !displayLabel && "text-muted-foreground"
+            !hasValue && "text-muted-foreground"
           ),
-          children: /* @__PURE__ */ jsx("span", { className: "truncate", children: displayLabel ?? resolvedPlaceholder })
+          children: /* @__PURE__ */ jsx("span", { className: "truncate", children: hasValue ? displayLabel : resolvedPlaceholder })
         }
       ) }),
+      resolvedName ? (multiple ? multiValue : singleValue.length ? [singleValue] : []).map((path, index) => /* @__PURE__ */ jsx(
+        "input",
+        {
+          type: "hidden",
+          name: resolvedName,
+          value: path.join("/"),
+          readOnly: true
+        },
+        `${pathKey(path)}-${index}`
+      )) : null,
       /* @__PURE__ */ jsxs(PopoverContent, { id: panelId, className: "ui-cascader-popover", align: "start", children: [
         showSearch && /* @__PURE__ */ jsx(Command, { shouldFilter: false, children: /* @__PURE__ */ jsx(
           CommandInput,
@@ -273,7 +430,7 @@ function Cascader({
             className: "ui-cascader-panel",
             role: "listbox",
             "aria-multiselectable": multiple ? true : void 0,
-            children: searchResults.length === 0 ? /* @__PURE__ */ jsx("p", { className: "ui-cascader-empty", children: t("dataEntry.cascader.empty") }) : searchResults.map(({ path, labels }) => {
+            children: searchResults.length === 0 ? /* @__PURE__ */ jsx("p", { className: "ui-cascader-empty", children: notFoundContent ?? t("dataEntry.cascader.empty") }) : searchResults.map(({ path, labels }) => {
               const label = labels.join(" / ");
               const selected = multiple ? pathInValues(path, multiValue) : pathsEqual(path, singleValue);
               return /* @__PURE__ */ jsxs(
@@ -307,14 +464,21 @@ function Cascader({
         ) }) : renderCascadeColumns()
       ] })
     ] }),
-    /* @__PURE__ */ jsx("div", { className: "ui-control-affix ui-cascader-affix", children: showClear ? /* @__PURE__ */ jsx(
+    /* @__PURE__ */ jsx("div", { className: "ui-control-affix ui-cascader-affix", children: loading ? /* @__PURE__ */ jsx(
+      Loader2,
+      {
+        "data-slot": "cascader-loading",
+        className: "ui-control-affix-icon ui-control-affix-indicator animate-spin",
+        "aria-hidden": "true"
+      }
+    ) : showClear ? /* @__PURE__ */ jsx(
       "button",
       {
         type: "button",
-        "aria-label": t("dataEntry.cascader.clear"),
+        "aria-label": clearControl.label,
         className: "ui-control-affix-action",
         onClick: clearValue,
-        children: /* @__PURE__ */ jsx(X, { className: "ui-control-affix-icon", "aria-hidden": "true" })
+        children: clearControl.clearIcon ?? /* @__PURE__ */ jsx(X, { className: "ui-control-affix-icon", "aria-hidden": "true" })
       }
     ) : /* @__PURE__ */ jsx(
       ChevronsUpDown,

package/dist/components/data-entry/checkbox.d.ts

@@ -1,11 +1,10 @@
 import * as React from "react";
-import * as CheckboxPrimitive from "@radix-ui/react-checkbox";
 import { CheckboxGroup } from "./checkbox-group.js";
 /**
  * Decorative checkbox glyph — a non-interactive `<span>`, NOT the real {@link Checkbox} (which is a
- * `<button>`). Used where the row itself is the interactive element and a nested `<button>` would
- * be invalid HTML (Cascader's option rows). Shares {@link CheckboxGlyph} so "partial" can never
- * drift apart from the real control's rendering again.
+ * real `<input>` wrapped by react-aria-components). Used where the row itself is the interactive
+ * element and a nested control would be invalid HTML (Cascader's option rows). Shares
+ * {@link CheckboxGlyph} so "partial" can never drift apart from the real control's rendering again.
  */
 export declare function CheckboxVisual({ checked, indeterminate, disabled, className, }: {
     checked: boolean;
@@ -13,7 +12,21 @@ export declare function CheckboxVisual({ checked, indeterminate, disabled, class
     disabled?: boolean;
     className?: string;
 }): React.JSX.Element;
-/** Checkbox — dùng standalone hoặc `Checkbox.Group` với `options` (Ant Design style). */
-export declare const Checkbox: React.ForwardRefExoticComponent<Omit<CheckboxPrimitive.CheckboxProps & React.RefAttributes<HTMLButtonElement>, "ref"> & React.RefAttributes<HTMLButtonElement>> & {
+/**
+ * The PUBLIC prop shape, unchanged from the @radix-ui/react-checkbox era: `checked` /
+ * `defaultChecked` accept the tri-state `"indeterminate"`, `onCheckedChange` reports it back, and
+ * `disabled` / `required` keep their HTML spelling. react-aria-components spells the same four
+ * `isSelected` + `isIndeterminate` / `defaultSelected` / `onChange` / `isDisabled` / `isRequired`;
+ * that translation happens INSIDE this component and none of those names reach a consumer.
+ */
+interface CheckboxRootProps extends Omit<React.ComponentPropsWithoutRef<"button">, "checked" | "defaultChecked" | "onChange"> {
+    checked?: boolean | "indeterminate";
+    defaultChecked?: boolean | "indeterminate";
+    onCheckedChange?: (checked: boolean | "indeterminate") => void;
+    required?: boolean;
+}
+/** Checkbox — dùng standalone hoặc `Checkbox.Group` với `options` (theo quy ước phổ biến). */
+export declare const Checkbox: React.ForwardRefExoticComponent<CheckboxRootProps & React.RefAttributes<HTMLLabelElement>> & {
     Group: typeof CheckboxGroup;
 };
+export {};

package/dist/components/data-entry/checkbox.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx } from "react/jsx-runtime";
 import * as React from "react";
-import * as CheckboxPrimitive from "@radix-ui/react-checkbox";
+import { Checkbox as AriaCheckbox } from "react-aria-components";
 import { Check, Minus } from "lucide-react";
 import { cn } from "../../lib/utils.js";
 import { useFieldIdentity } from "../../lib/field-a11y.js";
@@ -28,44 +28,83 @@ function CheckboxVisual({
     }
   );
 }
-const CheckboxRoot = React.forwardRef(({ className, ...props }, ref) => {
+const CheckboxRoot = React.forwardRef((props, ref) => {
+  const {
+    className,
+    checked,
+    defaultChecked,
+    onCheckedChange,
+    disabled,
+    required,
+    value,
+    tabIndex,
+    "data-field": ownField,
+    ...rest
+  } = props;
   const identity = useFieldIdentity({
     id: props.id,
     name: props.name,
-    "data-field": props["data-field"]
+    "data-field": ownField
   });
+  const fieldKey = ownField ?? identity["data-field"];
+  const inputRef = React.useRef(null);
+  React.useLayoutEffect(() => {
+    const input = inputRef.current;
+    if (!input) return;
+    if (fieldKey === void 0) {
+      input.removeAttribute("data-field");
+    } else {
+      input.setAttribute("data-field", fieldKey);
+    }
+  }, [fieldKey]);
   const [uncontrolled, setUncontrolled] = React.useState(
-    props.defaultChecked ?? false
+    defaultChecked ?? false
   );
-  const state = props.checked ?? uncontrolled;
+  const state = checked ?? uncontrolled;
+  const invalid = props["aria-invalid"];
   return /* @__PURE__ */ jsx(
-    CheckboxPrimitive.Root,
+    AriaCheckbox,
     {
+      ...rest,
       ref,
+      inputRef,
       "data-slot": "checkbox",
+      "data-state": state === "indeterminate" ? "indeterminate" : state ? "checked" : "unchecked",
+      name: identity.name ?? props.name,
+      value,
+      isSelected: state === true,
+      isIndeterminate: state === "indeterminate",
+      isDisabled: disabled,
+      isRequired: required,
+      isInvalid: invalid !== void 0 && invalid !== false && invalid !== "false",
+      excludeFromTabOrder: tabIndex !== void 0 && tabIndex < 0,
       className: cn(
         // `disabled:cursor-not-allowed disabled:opacity-50` and the checked fill are DELETED, not
         // moved: `.ui-checkbox:disabled, .ui-checkbox[data-disabled]` and
         // `.ui-checkbox[data-state="checked"]` in styles/control.css already declare both, reading
         // --disabled-opacity and --checkbox-checked-background. Utilities are layered AFTER
         // components in Tailwind v4, so these literals were silently OUTRANKING those knobs — a
-        // service overriding --checkbox-checked-background got no fill change at all. Radix sets
-        // `data-state`/`data-disabled` on the root, so the CSS rules match. Rendering is unchanged:
-        // both knobs default to exactly the values these utilities hard-coded.
-        "peer ui-checkbox aria-invalid:border-destructive data-[state=checked]:border-primary data-[state=checked]:text-primary-foreground shrink-0 shadow-xs transition-shadow outline-none",
+        // service overriding --checkbox-checked-background got no fill change at all. `data-state`
+        // above and react-aria's own `data-disabled` keep those CSS rules matching. Rendering is
+        // unchanged: both knobs default to exactly the values these utilities hard-coded.
+        //
+        // `inline-flex items-center justify-center` is NEW and load-bearing: the root used to be a
+        // `<button>` (inline-block, so `.ui-checkbox`'s width/height applied and the glyph centred
+        // itself). react-aria's root is a `<label>`, which is `display:inline` — without this the
+        // 16px box collapses to nothing. CheckboxVisual already carries the same three for the
+        // same reason.
+        "peer ui-checkbox data-[invalid]:border-destructive data-[state=checked]:border-primary data-[state=checked]:text-primary-foreground inline-flex shrink-0 items-center justify-center shadow-xs transition-shadow outline-none",
         className
       ),
-      ...props,
-      ...identity,
-      onCheckedChange: (next) => {
+      onChange: (next) => {
         setUncontrolled(next);
-        props.onCheckedChange?.(next);
+        onCheckedChange?.(next);
       },
-      children: /* @__PURE__ */ jsx(CheckboxPrimitive.Indicator, { "data-slot": "checkbox-indicator", className: "ui-choice-indicator", children: /* @__PURE__ */ jsx(CheckboxGlyph, { state }) })
+      children: /* @__PURE__ */ jsx("span", { "data-slot": "checkbox-indicator", className: "ui-choice-indicator", children: state ? /* @__PURE__ */ jsx(CheckboxGlyph, { state }) : null })
     }
   );
 });
-CheckboxRoot.displayName = CheckboxPrimitive.Root.displayName;
+CheckboxRoot.displayName = "Checkbox";
 const Checkbox = Object.assign(CheckboxRoot, {
   Group: CheckboxGroup
 });

package/dist/components/data-entry/choice-option.d.ts

@@ -1,5 +1,5 @@
 import type * as React from "react";
-/** Shared option shape — Ant Design `CheckboxOptionType` / `Radio` options. */
+/** Shared option shape — the conventional `CheckboxOptionType` / `Radio` options entry. */
 export type ChoiceOption = {
     label: React.ReactNode;
     value: string;

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

@@ -1,4 +1,4 @@
 import * as React from "react";
 import type { ColorPickerProp } from "../../props/components/data-entry.prop.js";
 export type { ColorPickerProp, ColorPickerProp as ColorPickerProps, } from "../../props/components/data-entry.prop.js";
-export declare function ColorPicker({ value, onValueChange, disabled, className, id, showHexInput, ...ariaProps }: ColorPickerProp): React.JSX.Element;
+export declare function ColorPicker({ value: valueProp, defaultValue, onValueChange, disabled, name, className, id, showHexInput, ...ariaProps }: ColorPickerProp): React.JSX.Element;

package/dist/components/data-entry/color-picker.js

@@ -3,26 +3,35 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { useTranslation } from "../../i18n/use-translation.js";
 import { cn } from "../../lib/utils.js";
-import { resolveFieldA11y } from "../../lib/field-a11y.js";
+import { resolveFieldA11y, useFieldIdentity } from "../../lib/field-a11y.js";
 import { controlIconClass } from "../../lib/control-styles.js";
 import { Input } from "./input.js";
 const HEX_PATTERN = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+const NATIVE_COLOR_FALLBACK = "#000000";
 function normalizeHex(value) {
   if (!value.startsWith("#")) return `#${value}`;
   return value;
 }
 function ColorPicker({
-  value = "#2563eb",
+  value: valueProp,
+  defaultValue,
   onValueChange,
   disabled,
+  name,
   className,
   id,
   showHexInput = true,
   ...ariaProps
 }) {
   const { t } = useTranslation();
+  const isControlled = valueProp !== void 0;
+  const [internalValue, setInternalValue] = React.useState(defaultValue ?? "");
+  const value = isControlled ? valueProp : internalValue;
   const [draft, setDraft] = React.useState(null);
   const display = draft ?? value;
+  const swatchValue = HEX_PATTERN.test(display) ? display : HEX_PATTERN.test(value) ? value : NATIVE_COLOR_FALLBACK;
+  const identity = useFieldIdentity({ id, name, "data-field": ariaProps["data-field"] });
+  const resolvedName = name ?? identity.name;
   const swatchA11y = resolveFieldA11y(ariaProps, t("dataEntry.colorPicker.ariaLabel"));
   const commit = (next) => {
     const normalized = normalizeHex(next);
@@ -31,6 +40,7 @@ function ColorPicker({
       return;
     }
     setDraft(null);
+    if (!isControlled) setInternalValue(normalized);
     onValueChange?.(normalized);
   };
   return /* @__PURE__ */ jsxs("div", { className: cn("ui-color-picker", className), children: [
@@ -39,7 +49,7 @@ function ColorPicker({
         "div",
         {
           className: "ui-color-picker-preview",
-          style: { backgroundColor: HEX_PATTERN.test(display) ? display : value },
+          style: { backgroundColor: swatchValue },
           "aria-hidden": "true"
         }
       ),
@@ -48,10 +58,11 @@ function ColorPicker({
         {
           id,
           type: "color",
-          value: HEX_PATTERN.test(display) ? display : value,
+          value: swatchValue,
           disabled,
           onChange: (event) => commit(event.target.value),
           className: "ui-color-picker-input",
+          "data-field": ariaProps["data-field"] ?? identity["data-field"],
           ...swatchA11y
         }
       )
@@ -71,7 +82,8 @@ function ColorPicker({
         className: "ui-color-picker-hex",
         spellCheck: false
       }
-    )
+    ),
+    resolvedName ? /* @__PURE__ */ jsx("input", { type: "hidden", name: resolvedName, value, readOnly: true }) : null
   ] });
 }
 export {

package/dist/components/data-entry/control-appearance.d.ts

@@ -0,0 +1,64 @@
+import type * as React from "react";
+import type { ControlStatusProp, ControlVariantProp } from "../../props/vocabulary/index.js";
+import type { ControlCountProp } from "../../props/components/data-entry.prop.js";
+/**
+ * The two appearance axes Ant Design puts on every text field — `status` and `variant` — resolved
+ * once, here, so Input / Textarea / NumberInput / PasswordInput / SearchInput cannot drift into
+ * three different spellings of "this field is wrong".
+ *
+ * WHY A HELPER AND NOT A CLASS PER COMPONENT. `status` has a SECOND half that is not paint:
+ * `error` must also report `aria-invalid`, or the red boundary is a lie to a screen reader. That
+ * pairing is the thing worth keeping in one place; the CSS is the easy half.
+ */
+export type ControlAppearanceInput = {
+    status?: ControlStatusProp;
+    variant?: ControlVariantProp;
+    "aria-invalid"?: React.AriaAttributes["aria-invalid"];
+};
+export type ControlAppearanceAttributes = {
+    "data-status"?: ControlStatusProp;
+    "data-variant"?: ControlVariantProp;
+    "aria-invalid"?: React.AriaAttributes["aria-invalid"];
+};
+/**
+ * `status="error"` REPORTS `aria-invalid` — unless the caller (or FormField, which injects it)
+ * already said something, in which case the explicit value wins and nothing is overwritten.
+ * `status="warning"` deliberately reports nothing: a warning is not a validity failure, and
+ * antd does not announce one either (es/_util/statusUtils.js only reaches for the class name).
+ */
+export declare function controlAppearanceAttributes({ status, variant, "aria-invalid": ariaInvalid, }: ControlAppearanceInput): ControlAppearanceAttributes;
+/**
+ * The chrome utilities a variant carries, kept in the COMPONENT rather than in `control.css`.
+ *
+ * A Tailwind utility lives in `@layer utilities`, which outranks `@layer components` no matter
+ * how specific the component rule is — so `bg-background` baked unconditionally into the class
+ * list would silently defeat `filled` and `borderless` and no gate would notice. The outlined
+ * field therefore keeps exactly the utilities it always had, and the other two simply do not
+ * receive them; their surface comes from `.ui-control--filled` / `.ui-control--borderless`.
+ */
+export declare const CONTROL_VARIANT_CHROME_CLASS: Record<ControlVariantProp, string>;
+/**
+ * The status BOUNDARY, for the same cascade-layer reason — and this one was measured the hard way.
+ *
+ * `.ui-control[data-status="warning"] { border-color: … }` in `@layer components` renders exactly
+ * nothing: `border-input` is a utility, utilities are a later layer, and a later layer wins over
+ * any specificity. In Chromium the warned field measured `rgb(144 135 127)` — the resting border —
+ * with the component rule in place and no error anywhere. Painting it from a utility instead puts
+ * the two declarations in the SAME layer, where `data-[status=…]` (0,2,0) genuinely outranks
+ * `border-input` (0,1,0). It is also the mechanism the library already used for the invalid state
+ * (`aria-invalid:border-destructive`), so the two states now paint the same way.
+ *
+ * The `--focus-*` reassignments stay in `control.css`: those are custom properties, and no utility
+ * competes for them.
+ */
+export declare const CONTROL_STATUS_CHROME_CLASS = "data-[status=error]:border-destructive data-[status=warning]:border-warning";
+/** Default `count.strategy` — code points, so a surrogate pair counts once. */
+export declare function countCodePoints(value: string): number;
+export type ResolvedControlCount = {
+    count: number;
+    max?: number;
+    exceeded: boolean;
+    content: React.ReactNode;
+};
+/** `null` when the counter is switched off (no `count`, or `count.show === false`). */
+export declare function resolveControlCount(config: ControlCountProp | undefined, value: string): ResolvedControlCount | null;