@godxjp/ui 20.0.0 → 20.2.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/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;

package/dist/components/data-entry/control-appearance.js

@@ -0,0 +1,39 @@
+function controlAppearanceAttributes({
+  status,
+  variant,
+  "aria-invalid": ariaInvalid
+}) {
+  return {
+    "data-status": status,
+    "data-variant": variant,
+    "aria-invalid": ariaInvalid ?? (status === "error" ? true : void 0)
+  };
+}
+const CONTROL_VARIANT_CHROME_CLASS = {
+  outlined: "border-input bg-background",
+  filled: "ui-control--filled",
+  borderless: "ui-control--borderless"
+};
+const CONTROL_STATUS_CHROME_CLASS = "data-[status=error]:border-destructive data-[status=warning]:border-warning";
+function countCodePoints(value) {
+  return [...value].length;
+}
+function resolveControlCount(config, value) {
+  if (!config || config.show === false) return null;
+  const strategy = config.strategy ?? countCodePoints;
+  const count = strategy(value);
+  const max = config.max;
+  return {
+    count,
+    max,
+    exceeded: max != null && count > max,
+    content: config.formatter ? config.formatter({ value, count, max }) : max == null ? String(count) : `${count} / ${max}`
+  };
+}
+export {
+  CONTROL_STATUS_CHROME_CLASS,
+  CONTROL_VARIANT_CHROME_CLASS,
+  controlAppearanceAttributes,
+  countCodePoints,
+  resolveControlCount
+};

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

@@ -0,0 +1,61 @@
+import type * as React from "react";
+import type { AllowClearProp, ControlStatusProp, ControlVariantProp, MaxTagPlaceholderProp, SizeProp } from "../../props/vocabulary/index.js";
+/**
+ * The DOM attributes that put a control on the `variant` × `status` × `size` matrix owned by
+ * `.ui-control-surface` in `src/styles/control.css`.
+ *
+ * Written once, here, rather than five times: every member of the select family (Select,
+ * SearchSelect, Cascader, TreeSelect, TagInput) states the antd surface contract the same way, and
+ * a per-component copy is how the five drift apart. Each default (`outlined`, `md`) emits NO
+ * attribute at all, so a control that says nothing keeps the exact DOM it had.
+ */
+export declare function controlSurfaceAttrs(props: {
+    variant?: ControlVariantProp;
+    status?: ControlStatusProp;
+    size?: SizeProp;
+}): {
+    "data-variant"?: ControlVariantProp;
+    "data-status"?: ControlStatusProp;
+    "data-size"?: SizeProp;
+};
+/**
+ * `status="error"` must also reach assistive tech, so it folds into `aria-invalid`.
+ *
+ * antd's own `status="error"` is a pure recolour — a state announced by hue alone, which WCAG 2.2
+ * SC 1.4.1 does not accept. An `aria-invalid` arriving from `FormField` always wins: the field's
+ * validation state is the authority, and a `status` prop must never be able to talk it down.
+ */
+export declare function resolveAriaInvalid<T extends React.AriaAttributes["aria-invalid"]>(ariaInvalid: T, status: ControlStatusProp | undefined): T | true | undefined;
+/** The normalised clear affordance: whether to offer it, with what icon, under what label. */
+export type ResolvedAllowClear = {
+    enabled: boolean;
+    clearIcon?: React.ReactNode;
+    label?: string;
+};
+/**
+ * Reconcile antd's `allowClear` with this library's own `clearable`.
+ *
+ * `allowClear` wins when present because it is the more specific statement — the object form
+ * carries an icon and a label that `clearable` has no way to express. `clearable` remains the
+ * name every existing call site uses, and keeps its `true` default.
+ */
+export declare function resolveAllowClear(allowClear: AllowClearProp | undefined, clearable: boolean | undefined, fallbackLabel?: string): ResolvedAllowClear;
+/**
+ * Apply antd's `maxTagCount` / `maxTagPlaceholder` to a list of selected values.
+ *
+ * Returns the values that stay visible plus the overflow node, so the three call sites (Cascader,
+ * TreeSelect, TagInput) agree on what "+2" means. `maxTagCount` is only honoured when it is a
+ * non-negative number — `undefined` shows everything, which is the antd default.
+ *
+ * `overflow` is `undefined` when the consumer supplied no `maxTagPlaceholder`: the fallback wording
+ * is a COUNT, and a count has to go through `t()` + `Intl.PluralRules` at the call site rather than
+ * be concatenated here.
+ */
+export declare function applyMaxTagCount<T extends {
+    value: string;
+    label: React.ReactNode;
+}>(items: T[], maxTagCount: number | undefined, maxTagPlaceholder: MaxTagPlaceholderProp | undefined): {
+    visible: T[];
+    omitted: T[];
+    overflow: React.ReactNode | undefined;
+};

package/dist/components/data-entry/control-surface.js

@@ -0,0 +1,39 @@
+function controlSurfaceAttrs(props) {
+  return {
+    "data-variant": props.variant && props.variant !== "outlined" ? props.variant : void 0,
+    "data-status": props.status,
+    "data-size": props.size && props.size !== "md" ? props.size : void 0
+  };
+}
+function resolveAriaInvalid(ariaInvalid, status) {
+  if (ariaInvalid !== void 0) return ariaInvalid;
+  return status === "error" ? true : void 0;
+}
+function resolveAllowClear(allowClear, clearable, fallbackLabel) {
+  if (allowClear !== void 0) {
+    if (typeof allowClear === "boolean") {
+      return { enabled: allowClear, label: fallbackLabel };
+    }
+    return {
+      enabled: true,
+      clearIcon: allowClear.clearIcon,
+      label: allowClear.label ?? fallbackLabel
+    };
+  }
+  return { enabled: clearable !== false, label: fallbackLabel };
+}
+function applyMaxTagCount(items, maxTagCount, maxTagPlaceholder) {
+  if (maxTagCount === void 0 || maxTagCount < 0 || items.length <= maxTagCount) {
+    return { visible: items, omitted: [], overflow: void 0 };
+  }
+  const visible = items.slice(0, maxTagCount);
+  const omitted = items.slice(maxTagCount);
+  const overflow = typeof maxTagPlaceholder === "function" ? maxTagPlaceholder(omitted.map(({ value, label }) => ({ value, label }))) : maxTagPlaceholder;
+  return { visible, omitted, overflow };
+}
+export {
+  applyMaxTagCount,
+  controlSurfaceAttrs,
+  resolveAllowClear,
+  resolveAriaInvalid
+};

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

@@ -6,4 +6,4 @@ export type { DatePickerProp, DatePickerProp as DatePickerProps, } from "../../p
  * `yyyy-MM-dd` string (the international standard): it is form-submittable (give it a `name`),
  * screen-reader friendly, and e2e-testable by simply filling the input.
  */
-export declare function DatePicker({ value: valueProp, defaultValue, onValueChange, placeholder, disabled, className, id, name, locale: localeProp, showToday, showClose, fromDate, toDate, allowClear, ...ariaProps }: DatePickerProp): React.JSX.Element;
+export declare function DatePicker(props: DatePickerProp): React.JSX.Element;