@godxjp/ui 27.1.0 → 27.4.1

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

@@ -1,10 +1,11 @@
 "use client";
-import { jsx } from "react/jsx-runtime";
+import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 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";
+import { mergeAriaIds, useFieldIdentity } from "../../lib/field-a11y.js";
+import { Label } from "./label.js";
 import { CheckboxGroup } from "./checkbox-group.js";
 import { withOwnHitTarget } from "./choice-hit-target.js";
 function CheckboxGlyph({ state }) {
@@ -39,9 +40,14 @@ const CheckboxRoot = React.forwardRef((props, ref) => {
     required,
     value,
     tabIndex,
+    children,
     "data-field": ownField,
     ...rest
   } = props;
+  const autoId = React.useId();
+  const hasInlineLabel = !(children === void 0 || children === null || children === false || children === "");
+  const inputId = props.id ?? (hasInlineLabel ? autoId : void 0);
+  const inlineLabelId = `${inputId}-inline-label`;
   const identity = useFieldIdentity({
     id: props.id,
     name: props.name,
@@ -63,7 +69,10 @@ const CheckboxRoot = React.forwardRef((props, ref) => {
   );
   const state = checked ?? uncontrolled;
   const invalid = props["aria-invalid"];
-  return /* @__PURE__ */ jsx(
+  const isInvalid = invalid !== void 0 && invalid !== false && invalid !== "false";
+  const describedBy = isInvalid ? mergeAriaIds(props["aria-describedby"], props["aria-errormessage"]) : props["aria-describedby"];
+  const labelledBy = hasInlineLabel && props["aria-labelledby"] !== void 0 ? mergeAriaIds(props["aria-labelledby"], inlineLabelId) : props["aria-labelledby"];
+  const box = /* @__PURE__ */ jsx(
     AriaCheckbox,
     {
       ...rest,
@@ -77,7 +86,10 @@ const CheckboxRoot = React.forwardRef((props, ref) => {
       isIndeterminate: state === "indeterminate",
       isDisabled: disabled,
       isRequired: required,
-      isInvalid: invalid !== void 0 && invalid !== false && invalid !== "false",
+      isInvalid,
+      id: inputId,
+      "aria-describedby": describedBy,
+      "aria-labelledby": labelledBy,
       excludeFromTabOrder: tabIndex !== void 0 && tabIndex < 0,
       className: cn(
         // `disabled:cursor-not-allowed disabled:opacity-50` and the checked fill are DELETED, not
@@ -95,7 +107,8 @@ const CheckboxRoot = React.forwardRef((props, ref) => {
         // 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",
-        className
+        // With an inline label the row is what a caller styles; the box keeps its own classes.
+        hasInlineLabel ? void 0 : className
       ),
       render: (domProps) => /* @__PURE__ */ jsx("label", { ...domProps, children: withOwnHitTarget(domProps.children) }),
       onChange: (next) => {
@@ -105,6 +118,11 @@ const CheckboxRoot = React.forwardRef((props, ref) => {
       children: /* @__PURE__ */ jsx("span", { "data-slot": "checkbox-indicator", className: "ui-choice-indicator", children: state ? /* @__PURE__ */ jsx(CheckboxGlyph, { state }) : null })
     }
   );
+  if (!hasInlineLabel) return box;
+  return /* @__PURE__ */ jsxs("div", { "data-slot": "checkbox-field", className: cn("ui-choice-field", className), children: [
+    /* @__PURE__ */ jsx("div", { className: "ui-choice-control", children: box }),
+    /* @__PURE__ */ jsx("div", { className: "ui-choice-content", children: /* @__PURE__ */ jsx(Label, { id: inlineLabelId, htmlFor: inputId, className: "ui-choice-label", children }) })
+  ] });
 });
 CheckboxRoot.displayName = "Checkbox";
 const Checkbox = Object.assign(CheckboxRoot, {

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

@@ -1,4 +1,6 @@
 import * as React from "react";
+import type { CommandProp } from "../../props/components/data-entry.prop.js";
+export type { CommandProp, CommandProp as CommandProps };
 export declare const Command: React.ForwardRefExoticComponent<Omit<{
     children?: React.ReactNode;
 } & Pick<Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof React.HTMLAttributes<HTMLDivElement>> & {
@@ -15,7 +17,7 @@ export declare const Command: React.ForwardRefExoticComponent<Omit<{
     loop?: boolean;
     disablePointerSelection?: boolean;
     vimBindings?: boolean;
-} & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+} & React.RefAttributes<HTMLDivElement>, "ref"> & CommandProp & React.RefAttributes<HTMLDivElement>>;
 export declare const CommandInput: React.ForwardRefExoticComponent<Omit<Omit<Pick<Pick<React.DetailedHTMLProps<React.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "key" | keyof React.InputHTMLAttributes<HTMLInputElement>> & {
     ref?: React.Ref<HTMLInputElement>;
 } & {

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

@@ -5,7 +5,7 @@ import { Command as CommandPrimitive } from "cmdk";
 import { Search } from "lucide-react";
 import { cn } from "../../lib/utils.js";
 import { controlIconLeadingClass } from "../../lib/control-styles.js";
-const Command = React.forwardRef(({ className, ...props }, ref) => {
+const Command = React.forwardRef(({ className, split = false, ...props }, ref) => {
   const rootRef = React.useRef(null);
   const setRefs = (node) => {
     rootRef.current = node;
@@ -22,7 +22,15 @@ const Command = React.forwardRef(({ className, ...props }, ref) => {
     if (input && expectedId && !input.id) input.id = expectedId;
     else if (!input || input.id !== expectedId) label.removeAttribute("for");
   });
-  return /* @__PURE__ */ jsx(CommandPrimitive, { ref: setRefs, className: cn("ui-command", className), ...props });
+  return /* @__PURE__ */ jsx(
+    CommandPrimitive,
+    {
+      ref: setRefs,
+      className: cn("ui-command", className),
+      "data-split": split ? "" : void 0,
+      ...props
+    }
+  );
 });
 Command.displayName = CommandPrimitive.displayName;
 const CommandInput = React.forwardRef(({ className, ...props }, ref) => (

package/dist/components/data-entry/form-field.js

@@ -47,6 +47,7 @@ function FormField({
   const autoId = React.useId();
   const resolvedId = id ?? autoId;
   const labelId = `${resolvedId}-label`;
+  const hasLabel = !(label === void 0 || label === null || label === false || label === "");
   const helperId = helper ? `${resolvedId}-helper` : void 0;
   const helperNode = helper ? /* @__PURE__ */ jsx("p", { id: helperId, className: "ui-form-field-note text-muted-foreground text-xs", children: helper }) : null;
   const validationStatus = error ? "error" : validateStatus;
@@ -62,8 +63,8 @@ function FormField({
     );
   }
   const fieldNameContext = React.useMemo(
-    () => ({ labelId, label: typeof label === "string" ? label : void 0 }),
-    [labelId, label]
+    () => hasLabel ? { labelId, label: typeof label === "string" ? label : void 0 } : null,
+    [hasLabel, labelId, label]
   );
   const fieldIdentityContext = React.useMemo(
     () => fieldKey === void 0 ? null : { emitName: emitFieldNames },
@@ -88,12 +89,12 @@ function FormField({
     // `"data-field": fieldKey` would erase a value the control set for itself.
     "data-field": childProps?.["data-field"] ?? fieldKey,
     ...emitFieldNames ? { name: childProps?.name ?? fieldKey } : void 0,
-    "aria-labelledby": childProps?.["aria-labelledby"] ?? labelId,
+    "aria-labelledby": childProps?.["aria-labelledby"] ?? (hasLabel ? labelId : void 0),
     // Redundant `aria-label` fallback (belt-and-suspenders): the accessible name is the
     // SAME string as the visible label, just reachable even if an aria-labelledby lookup
     // ever comes back empty (id-ref timing, AT quirks). Only when `label` is plain text and
     // the child hasn't already set its own aria-label.
-    "aria-label": childProps?.["aria-label"] ?? (typeof label === "string" ? label : void 0),
+    "aria-label": childProps?.["aria-label"] ?? (hasLabel && typeof label === "string" ? label : void 0),
     // Helper and error can coexist: helper stays on aria-describedby, the error on
     // aria-errormessage (surfaced when aria-invalid is true).
     "aria-describedby": mergeIds(
@@ -124,8 +125,8 @@ function FormField({
       style: Object.keys(style).length ? style : void 0,
       className: cn("ui-form-field", className),
       children: [
-        /* @__PURE__ */ jsxs("div", { "data-slot": "form-field-label", className: "ui-form-field-label", children: [
-          /* @__PURE__ */ jsx(
+        hasLabel || labelAddon != null ? /* @__PURE__ */ jsxs("div", { "data-slot": "form-field-label", className: "ui-form-field-label", children: [
+          hasLabel ? /* @__PURE__ */ jsx(
             Label,
             {
               asChild: true,
@@ -151,9 +152,9 @@ function FormField({
                 }
               )
             }
-          ),
+          ) : null,
           labelAddon
-        ] }),
+        ] }) : null,
         /* @__PURE__ */ jsxs("div", { "data-slot": "form-field-control", className: "ui-form-field-control", children: [
           helperPlacement === "before" ? helperNode : null,
           isStatic ? childWithA11y : /* @__PURE__ */ jsx(FieldNameContext.Provider, { value: fieldNameContext, children: /* @__PURE__ */ jsx(FieldIdentityContext.Provider, { value: fieldIdentityContext, children: /* @__PURE__ */ jsx(

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

@@ -49,6 +49,7 @@ export type { TreeSelectProps } from "./tree-select.js";
 export { Transfer } from "./transfer.js";
 export type { TransferProps, TransferItemProp } from "./transfer.js";
 export { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, } from "./command.js";
+export type { CommandProps } from "./command.js";
 export { CommandPalette } from "./command-palette.js";
 export type { CommandPaletteGroup, CommandPaletteItem, CommandPaletteLabels, CommandPaletteProps, } from "./command-palette.js";
 export { PasswordInput } from "./password-input.js";

package/dist/components/data-entry/search-select.js

@@ -511,144 +511,153 @@ function SearchSelect(props) {
               style: typeof popupMatchSelectWidth === "number" ? {
                 "--search-select-panel-inline-size": `${popupMatchSelectWidth}px`
               } : void 0,
-              children: /* @__PURE__ */ jsx(PopupRender, { render: popupRender, children: /* @__PURE__ */ jsxs(Command, { value, shouldFilter: false, className: "ui-search-select-command", children: [
-                /* @__PURE__ */ jsx("div", { className: "ui-search-select-search", children: /* @__PURE__ */ jsx(
-                  Input,
-                  {
-                    autoFocus: true,
-                    "aria-controls": listId,
-                    "aria-autocomplete": "list",
-                    "aria-activedescendant": activeOptionId,
-                    "aria-label": searchPlaceholder ?? t("dataEntry.searchSelect.search"),
-                    value: query,
-                    onChange: (event) => {
-                      const next = event.target.value;
-                      if (multiple && tokenSeparators?.length && tokenSeparators.some((separator) => next.includes(separator))) {
-                        selectTokens(next);
-                        setQuery("");
-                        return;
+              children: /* @__PURE__ */ jsx(PopupRender, { render: popupRender, children: /* @__PURE__ */ jsxs(
+                Command,
+                {
+                  value,
+                  shouldFilter: false,
+                  className: "ui-search-select-command",
+                  split: multiple,
+                  children: [
+                    /* @__PURE__ */ jsx("div", { className: "ui-search-select-search", children: /* @__PURE__ */ jsx(
+                      Input,
+                      {
+                        autoFocus: true,
+                        "aria-controls": listId,
+                        "aria-autocomplete": "list",
+                        "aria-activedescendant": activeOptionId,
+                        "aria-label": searchPlaceholder ?? t("dataEntry.searchSelect.search"),
+                        value: query,
+                        onChange: (event) => {
+                          const next = event.target.value;
+                          if (multiple && tokenSeparators?.length && tokenSeparators.some((separator) => next.includes(separator))) {
+                            selectTokens(next);
+                            setQuery("");
+                            return;
+                          }
+                          setQuery(next);
+                        },
+                        onPaste: (event) => {
+                          if (!multiple || !tokenSeparators?.length) return;
+                          const text = event.clipboardData.getData("text");
+                          if (!tokenSeparators.some((separator) => text.includes(separator))) return;
+                          event.preventDefault();
+                          selectTokens(text);
+                          setQuery("");
+                        },
+                        onKeyDown,
+                        placeholder: searchPlaceholder ?? t("dataEntry.searchSelect.search"),
+                        className: "ui-search-select-search-input"
                       }
-                      setQuery(next);
-                    },
-                    onPaste: (event) => {
-                      if (!multiple || !tokenSeparators?.length) return;
-                      const text = event.clipboardData.getData("text");
-                      if (!tokenSeparators.some((separator) => text.includes(separator))) return;
-                      event.preventDefault();
-                      selectTokens(text);
-                      setQuery("");
-                    },
-                    onKeyDown,
-                    placeholder: searchPlaceholder ?? t("dataEntry.searchSelect.search"),
-                    className: "ui-search-select-search-input"
-                  }
-                ) }),
-                /* @__PURE__ */ jsxs(
-                  "div",
-                  {
-                    id: listId,
-                    role: "listbox",
-                    "aria-multiselectable": multiple || void 0,
-                    "aria-busy": loading,
-                    className: "ui-search-select-list",
-                    style: listHeight === void 0 ? void 0 : {
-                      "--search-select-list-max-height": `${listHeight}px`
-                    },
-                    onScroll: (event) => {
-                      onPopupScroll?.(event);
-                      onScroll(event);
-                    },
-                    children: [
-                      grouped.map((group) => {
-                        const rows = group.items.map(({ option, index }) => /* @__PURE__ */ jsxs(
-                          "div",
-                          {
-                            id: optionDomId(option.value),
-                            role: "option",
-                            "data-testid": optionTestId(option.value),
-                            "aria-selected": isSelected(option.value),
-                            "aria-disabled": option.disabled || atMaxCount && !isSelected(option.value) || void 0,
-                            "data-disabled": option.disabled || atMaxCount && !isSelected(option.value) || void 0,
-                            className: cn(
-                              "ui-command-item",
-                              // Selected = persistent bg-accent + medium weight (NO check icon — saves width),
-                              // matching the plain SelectItem's `data-[state=checked]` convention; active =
-                              // hover/keyboard accent. Same bg so selection stays coherent across both Selects.
-                              isSelected(option.value) && "bg-accent text-foreground font-medium",
-                              activeIndex === index && "bg-accent text-accent-foreground"
-                            ),
-                            onMouseEnter: () => !option.disabled && setActiveIndex(index),
-                            onMouseDown: (event) => event.preventDefault(),
-                            onClick: () => select(option),
-                            children: [
-                              optionRender ? /* @__PURE__ */ jsx("div", { className: "ui-search-select-option-slot", children: optionRender(option, { index }) }) : renderOption ? /* @__PURE__ */ jsx("div", { className: "ui-search-select-option-slot", children: renderOption(option) }) : /* @__PURE__ */ jsxs("div", { className: "ui-search-select-option-body", children: [
-                                option.icon ? /* @__PURE__ */ jsx("span", { className: "flex shrink-0 items-center", "aria-hidden": "true", children: option.icon }) : null,
-                                /* @__PURE__ */ jsxs("div", { className: "ui-search-select-option-text", children: [
-                                  /* @__PURE__ */ jsx("span", { className: "ui-search-select-option-label", children: option.label }),
-                                  option.sublabel ? /* @__PURE__ */ jsx("span", { className: "ui-search-select-option-sublabel", children: option.sublabel }) : null
-                                ] })
-                              ] }),
-                              menuItemSelectedIcon && isSelected(option.value) ? /* @__PURE__ */ jsx(
-                                "span",
-                                {
-                                  "data-slot": "search-select-selected-icon",
-                                  className: "ui-search-select-selected-icon",
-                                  "aria-hidden": "true",
-                                  children: menuItemSelectedIcon
-                                }
-                              ) : null
-                            ]
-                          },
-                          option.value
-                        ));
-                        return group.heading ? /* @__PURE__ */ jsx(CommandGroup, { heading: group.heading, children: rows }, group.heading) : /* @__PURE__ */ jsx(React.Fragment, { children: rows }, "__ungrouped");
-                      }),
-                      loading ? /* @__PURE__ */ jsxs("div", { role: "status", className: "ui-search-select-status", children: [
-                        /* @__PURE__ */ jsx(Loader2, { className: "ui-search-select-spinner animate-spin", "aria-hidden": "true" }),
-                        loadingMessage ?? t("dataEntry.searchSelect.loading")
-                      ] }) : error ? renderError ? renderError({
-                        message: errorMessage ?? t("dataEntry.searchSelect.error"),
-                        // Retry always reloads from the first page (a defined, predictable recovery —
-                        // NOT a resume of a failed page-N append, which would need to re-derive state).
-                        retry: () => void fetchPage(1, debouncedQuery, false)
-                      }) : /* @__PURE__ */ jsx(
-                        "div",
-                        {
-                          role: "option",
-                          "aria-disabled": "true",
-                          "aria-selected": false,
-                          className: "ui-search-select-placeholder",
-                          "data-tone": "destructive",
-                          children: errorMessage ?? t("dataEntry.searchSelect.error")
-                        }
-                      ) : displayOptions.length === 0 ? /* @__PURE__ */ jsx(
-                        "div",
-                        {
-                          role: "option",
-                          "aria-disabled": "true",
-                          "aria-selected": false,
-                          className: "ui-search-select-placeholder",
-                          children: notFoundContent ?? emptyMessage ?? t("dataEntry.searchSelect.empty")
-                        }
-                      ) : null
-                    ]
-                  }
-                ),
-                renderLoadMore && hasMore ? /* @__PURE__ */ jsx(
-                  "div",
-                  {
-                    className: "ui-search-select-footer",
-                    onKeyDown: (event) => event.stopPropagation(),
-                    children: renderLoadMore({
-                      hasMore,
-                      loading,
-                      loadMore: () => {
-                        if (!loading) void fetchPage(page + 1, debouncedQuery, true);
+                    ) }),
+                    /* @__PURE__ */ jsxs(
+                      "div",
+                      {
+                        id: listId,
+                        role: "listbox",
+                        "aria-multiselectable": multiple || void 0,
+                        "aria-busy": loading,
+                        className: "ui-search-select-list",
+                        style: listHeight === void 0 ? void 0 : {
+                          "--search-select-list-max-height": `${listHeight}px`
+                        },
+                        onScroll: (event) => {
+                          onPopupScroll?.(event);
+                          onScroll(event);
+                        },
+                        children: [
+                          grouped.map((group) => {
+                            const rows = group.items.map(({ option, index }) => /* @__PURE__ */ jsxs(
+                              "div",
+                              {
+                                id: optionDomId(option.value),
+                                role: "option",
+                                "data-testid": optionTestId(option.value),
+                                "aria-selected": isSelected(option.value),
+                                "aria-disabled": option.disabled || atMaxCount && !isSelected(option.value) || void 0,
+                                "data-disabled": option.disabled || atMaxCount && !isSelected(option.value) || void 0,
+                                className: cn(
+                                  "ui-command-item",
+                                  // Selected = persistent bg-accent + medium weight (NO check icon — saves width),
+                                  // matching the plain SelectItem's `data-[state=checked]` convention; active =
+                                  // hover/keyboard accent. Same bg so selection stays coherent across both Selects.
+                                  isSelected(option.value) && "bg-accent text-foreground font-medium",
+                                  activeIndex === index && "bg-accent text-accent-foreground"
+                                ),
+                                onMouseEnter: () => !option.disabled && setActiveIndex(index),
+                                onMouseDown: (event) => event.preventDefault(),
+                                onClick: () => select(option),
+                                children: [
+                                  optionRender ? /* @__PURE__ */ jsx("div", { className: "ui-search-select-option-slot", children: optionRender(option, { index }) }) : renderOption ? /* @__PURE__ */ jsx("div", { className: "ui-search-select-option-slot", children: renderOption(option) }) : /* @__PURE__ */ jsxs("div", { className: "ui-search-select-option-body", children: [
+                                    option.icon ? /* @__PURE__ */ jsx("span", { className: "flex shrink-0 items-center", "aria-hidden": "true", children: option.icon }) : null,
+                                    /* @__PURE__ */ jsxs("div", { className: "ui-search-select-option-text", children: [
+                                      /* @__PURE__ */ jsx("span", { className: "ui-search-select-option-label", children: option.label }),
+                                      option.sublabel ? /* @__PURE__ */ jsx("span", { className: "ui-search-select-option-sublabel", children: option.sublabel }) : null
+                                    ] })
+                                  ] }),
+                                  menuItemSelectedIcon && isSelected(option.value) ? /* @__PURE__ */ jsx(
+                                    "span",
+                                    {
+                                      "data-slot": "search-select-selected-icon",
+                                      className: "ui-search-select-selected-icon",
+                                      "aria-hidden": "true",
+                                      children: menuItemSelectedIcon
+                                    }
+                                  ) : null
+                                ]
+                              },
+                              option.value
+                            ));
+                            return group.heading ? /* @__PURE__ */ jsx(CommandGroup, { heading: group.heading, children: rows }, group.heading) : /* @__PURE__ */ jsx(React.Fragment, { children: rows }, "__ungrouped");
+                          }),
+                          loading ? /* @__PURE__ */ jsxs("div", { role: "status", className: "ui-search-select-status", children: [
+                            /* @__PURE__ */ jsx(Loader2, { className: "ui-search-select-spinner animate-spin", "aria-hidden": "true" }),
+                            loadingMessage ?? t("dataEntry.searchSelect.loading")
+                          ] }) : error ? renderError ? renderError({
+                            message: errorMessage ?? t("dataEntry.searchSelect.error"),
+                            // Retry always reloads from the first page (a defined, predictable recovery —
+                            // NOT a resume of a failed page-N append, which would need to re-derive state).
+                            retry: () => void fetchPage(1, debouncedQuery, false)
+                          }) : /* @__PURE__ */ jsx(
+                            "div",
+                            {
+                              role: "option",
+                              "aria-disabled": "true",
+                              "aria-selected": false,
+                              className: "ui-search-select-placeholder",
+                              "data-tone": "destructive",
+                              children: errorMessage ?? t("dataEntry.searchSelect.error")
+                            }
+                          ) : displayOptions.length === 0 ? /* @__PURE__ */ jsx(
+                            "div",
+                            {
+                              role: "option",
+                              "aria-disabled": "true",
+                              "aria-selected": false,
+                              className: "ui-search-select-placeholder",
+                              children: notFoundContent ?? emptyMessage ?? t("dataEntry.searchSelect.empty")
+                            }
+                          ) : null
+                        ]
                       }
-                    })
-                  }
-                ) : null
-              ] }) })
+                    ),
+                    renderLoadMore && hasMore ? /* @__PURE__ */ jsx(
+                      "div",
+                      {
+                        className: "ui-search-select-footer",
+                        onKeyDown: (event) => event.stopPropagation(),
+                        children: renderLoadMore({
+                          hasMore,
+                          loading,
+                          loadMore: () => {
+                            if (!loading) void fetchPage(page + 1, debouncedQuery, true);
+                          }
+                        })
+                      }
+                    ) : null
+                  ]
+                }
+              ) })
             }
           )
         ]

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

@@ -55,6 +55,35 @@ function itemTextValue(node) {
   }
   return "";
 }
+function useSettledDefaultOpen(rootRef, defaultOpen, open) {
+  const [deferred] = React.useState(() => defaultOpen === true && open === void 0);
+  const [settledOpen, setSettledOpen] = React.useState(false);
+  React.useLayoutEffect(() => {
+    if (!deferred) return;
+    let cancelled = false;
+    const moving = [];
+    for (let node = rootRef.current?.parentElement; node; node = node.parentElement) {
+      if (typeof node.getAnimations !== "function") break;
+      for (const animation of node.getAnimations()) {
+        const end = animation.effect?.getComputedTiming().endTime;
+        if (animation.playState === "running" && Number.isFinite(Number(end))) {
+          moving.push(animation.finished);
+        }
+      }
+    }
+    if (moving.length === 0) {
+      setSettledOpen(true);
+      return;
+    }
+    void Promise.allSettled(moving).then(() => {
+      if (!cancelled) setSettledOpen(true);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [deferred, rootRef]);
+  return deferred ? { open: settledOpen, setOpen: setSettledOpen } : null;
+}
 function SelectRoot({
   id,
   value,
@@ -76,9 +105,12 @@ function SelectRoot({
   children
 }) {
   void dir;
+  const rootRef = React.useRef(null);
+  const settled = useSettledDefaultOpen(rootRef, defaultOpen, open);
   return /* @__PURE__ */ jsx(
     AriaSelect,
     {
+      ref: rootRef,
       "data-slot": "select",
       className: "ui-select-root",
       id,
@@ -87,9 +119,12 @@ function SelectRoot({
       onChange: (key) => {
         if (key != null) onValueChange?.(String(key));
       },
-      isOpen: open,
-      defaultOpen,
-      onOpenChange,
+      isOpen: open ?? settled?.open,
+      defaultOpen: settled ? void 0 : defaultOpen,
+      onOpenChange: (next) => {
+        settled?.setOpen(next);
+        onOpenChange?.(next);
+      },
       isDisabled: disabled || isDisabled,
       isRequired: required,
       name,

package/dist/components/general/icon.d.ts

@@ -0,0 +1,31 @@
+import * as React from "react";
+export type { IconGlyphProp, IconGlyphProp as IconProps, } from "../../props/components/general.prop.js";
+/**
+ * Icon — a glyph on the `--icon-size-*` scale, and the only supported way to draw a standalone one.
+ *
+ * WHY THIS EXISTS (gh#712). A lucide component ships `width="24" height="24"`, and exactly four
+ * rules in this library ever override that: `.ui-button svg`, `.ui-dropdown-menu-item > svg`,
+ * `.ui-topbar-item > svg` and `[data-slot="list-row-leading"] > svg`. Anywhere else — in a `Text`,
+ * in a table cell, in an `<a>` — the glyph draws at 24px beside 14px type, 1.71× the text it
+ * annotates. A consumer cannot fix that themselves: `size-4` and `w-[16px]` are what
+ * docs/CONSUMER-RULES.md §3/§8 forbid, and `size={16}` hard-codes a number the theme owns. One
+ * consumer measured 38 such glyphs in a single app.
+ *
+ * RENDERS ONTO THE GLYPH, NOT AROUND IT. `as={Lock}` is invoked with the class, the size and the
+ * a11y wiring, so the element that carries the metric IS the `<svg>`. A wrapper `<span>` would add
+ * a box to every flex row that holds an icon, and would break `Button`'s own `svg` rule by putting
+ * an element between the two.
+ *
+ * DECORATIVE BY DEFAULT. Without `label` the glyph is `aria-hidden` — a glyph beside a visible
+ * label is decoration, and announcing it twice is the usual defect (WCAG 2.2 SC 1.1.1). Pass
+ * `label` only when the glyph is the ONLY thing saying what it says; it then renders as
+ * `role="img"` + that name, which is how a graphic gets a name in WAI-ARIA 1.2. The string is the
+ * consumer's to localize — the library ships no copy for it.
+ */
+export declare const Icon: React.ForwardRefExoticComponent<Omit<React.SVGProps<SVGSVGElement>, "children" | "ref"> & {
+    as: React.ComponentType<React.SVGProps<SVGSVGElement> & React.RefAttributes<SVGSVGElement>>;
+    size?: import("../../props/index.js").IconSizeProp;
+    tone?: import("../../props/index.js").TextToneProp;
+    label?: string;
+    className?: import("../../props/index.js").ClassNameProp;
+} & React.RefAttributes<SVGSVGElement>>;

package/dist/components/general/icon.js

@@ -0,0 +1,23 @@
+import { jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../../lib/utils.js";
+const Icon = React.forwardRef(function Icon2({ as: Glyph, size = "md", tone, label, className, ...props }, ref) {
+  const named = label !== void 0 && label !== "";
+  return /* @__PURE__ */ jsx(
+    Glyph,
+    {
+      ref,
+      "data-slot": "icon",
+      "data-size": size,
+      "data-tone": tone,
+      className: cn("ui-icon", className),
+      role: named ? "img" : void 0,
+      "aria-label": named ? label : void 0,
+      "aria-hidden": named ? void 0 : true,
+      ...props
+    }
+  );
+});
+export {
+  Icon
+};

package/dist/components/general/index.d.ts

@@ -2,6 +2,8 @@ export { Button, buttonVariants } from "./button.js";
 export type { ButtonProps } from "./button.js";
 export { Text, Heading, Typography, Title, Paragraph, Link } from "./typography.js";
 export type { TextProps, HeadingProps, TextProp, HeadingProp, TypographyProp, TypographyProps, TypographyBlockProp, TypographyTitleProp, TitleProps, ParagraphProp, ParagraphProps, LinkProp, LinkProps, } from "./typography.js";
+export { Icon } from "./icon.js";
+export type { IconGlyphProp, IconProps } from "./icon.js";
 export { Logo } from "./logo.js";
 export type { LogoMark, LogoProps, LogoSize, LogoTone } from "./logo.js";
 export { Reveal } from "./reveal.js";

package/dist/components/general/index.js

@@ -1,5 +1,6 @@
 import { Button, buttonVariants } from "./button.js";
 import { Text, Heading, Typography, Title, Paragraph, Link } from "./typography.js";
+import { Icon } from "./icon.js";
 import { Logo } from "./logo.js";
 import { Reveal } from "./reveal.js";
 import { FloatButton } from "./float-button.js";
@@ -15,6 +16,7 @@ export {
   Button,
   FloatButton,
   Heading,
+  Icon,
   Link,
   Logo,
   Paragraph,