@codapet/design-system 0.8.6 → 0.8.7

package/AGENTS.md

@@ -369,6 +369,8 @@ There are no other public exports, and no subpath imports: only
 - **Wrong default Button look** → you forgot `variant="primary"`/`size="md"` are not the same as shadcn's defaults; passing nothing gives you `primary` + `lg`.
 - **Toast looks generic** → you imported `toast` from `'sonner'` instead of from `@codapet/design-system`.
 - **Modal doesn't bottom-sheet on mobile** → you used `Dialog` instead of `SmartDialog`.
+- **`AsyncAutocomplete` keeps stale results while refetching** → `loading` only replaces the list when there is nothing else to show. Once results are visible, a further keystroke leaves them in place and marks the listbox `aria-busy` plus `data-busy`, so the panel does not flash back to the spinner on every character. Style the refresh with `classNames={{ listbox: 'data-[busy=true]:opacity-60' }}` if you want visible feedback.
+- **`AsyncAutocomplete` warns about a missing accessible name** → a combobox must be named, and a `placeholder` does not name one (ARIA practices are explicit about this). Pass `label` for a visible label — it renders a real `<label htmlFor>`, unlike `SearchInput`/`MultiSelectFreeText`, whose `label` prop is a styled `<div>` and is *not* programmatically associated — or pass `inputProps={{ 'aria-label': '…' }}` when the design has no visible label. `mandatory` sets `aria-required` and hides the asterisk from assistive tech.
 - **`AsyncAutocomplete` fires a request per keystroke** → it deliberately does not debounce. Debounce in your fetch layer (`usePlacesService({ debounce: 300 })`, your own hook) so cancellation and out-of-order responses stay with the code that owns them.
 - **`AsyncAutocomplete` shows results that don't match what you typed** → it renders `options` verbatim by design, because the server already filtered. If your list is static, use `SearchableSelect`/`DropdownSelect`, which filter client-side.
 - **Styling `AsyncAutocomplete`** → it does **not** follow the flat `*ClassName` convention that `DateInput`/`TimeInput` use, because it has twenty-odd stylable slots. `className` is the root wrapper; everything else lives in one `classNames` object: `field`, `input`, `leftIcon`, `clearButton`, `content`, `listbox`, `option`, `optionHighlighted`, `optionDisabled`, `optionIcon`, `optionLabel`, `optionDescription`, `loading`, `loadingSpinner`, `empty`, plus `sheetOverlay`, `sheetContent`, `sheetHeader`, `sheetCloseButton`, `sheetInput`, `sheetList`. All merge through `cn`, so `{ content: 'max-h-[420px]' }` replaces the built-in max-height rather than stacking with it. A single row can also carry its own `className` via the option object, and rows expose `data-highlighted` / `data-disabled` for parent-level selectors. Use `renderOption` to change row *structure*, `classNames` to change its *look*.

package/dist/index.d.mts

@@ -140,6 +140,8 @@ type AsyncAutocompleteInputProps = Omit<React$1.ComponentPropsWithoutRef<'input'
 interface AsyncAutocompleteClassNames {
     /** Wrapper around the input — also the popover's anchor. */
     field?: string;
+    /** The visible label element. */
+    label?: string;
     /** The text input itself. */
     input?: string;
     /** Left icon wrapper inside the input. */
@@ -202,7 +204,14 @@ interface AsyncAutocompleteProps<TData = unknown> {
      * `formatted_address`) or clear the field. Drive `value` yourself.
      */
     onSelect: (option: AsyncAutocompleteOption<TData>) => void;
-    /** In-flight request. Replaces the rows with a spinner. */
+    /**
+     * A request is in flight.
+     *
+     * The spinner row only replaces the list when there is nothing else to show.
+     * If results are already on screen they stay put and the listbox is marked
+     * `aria-busy` / `data-busy` instead — so typing another character does not
+     * flash the panel back to "Searching…".
+     */
     loading?: boolean;
     /** Controlled input text. */
     value?: string;
@@ -217,6 +226,17 @@ interface AsyncAutocompleteProps<TData = unknown> {
      */
     onClear?: () => void;
     placeholder?: string;
+    /**
+     * Visible label, rendered above the field and wired to it with `htmlFor`.
+     *
+     * A combobox **must** have an accessible name — the ARIA practices are
+     * explicit that a placeholder is not one. Provide either this, or an
+     * `aria-label`/`aria-labelledby` through `inputProps`. In development the
+     * component warns when neither is present.
+     */
+    label?: string;
+    /** Appends a red asterisk to `label`. */
+    mandatory?: boolean;
     /** Decorative leading icon — `<MapPin />`, `<Stethoscope />`, … */
     leftIcon?: React$1.ReactNode;
     /** Fixed height: `sm` 40px · `md` 48px (default) · `lg` 56px. */
@@ -241,6 +261,10 @@ interface AsyncAutocompleteProps<TData = unknown> {
      * for stacked two-line rows, avatars, or bold match highlighting — the
      * wrapper, `role="option"`, ids, highlight background and click/keyboard
      * wiring stay with the component.
+     *
+     * Keep the content non-interactive: it renders inside `role="option"`, and a
+     * nested button or link there is both invalid and unreachable by keyboard,
+     * since the row is driven by `aria-activedescendant` rather than focus.
      */
     renderOption?: (option: AsyncAutocompleteOption<TData>, state: AsyncAutocompleteOptionState) => React$1.ReactNode;
     /** Default leading icon for rows without their own `option.icon`. */
@@ -280,7 +304,7 @@ interface AsyncAutocompleteProps<TData = unknown> {
     /** Per-slot class overrides. See `AsyncAutocompleteClassNames`. */
     classNames?: AsyncAutocompleteClassNames;
 }
-declare function AsyncAutocomplete<TData = unknown>({ options, onSearch, onSelect, loading, value: valueProp, defaultValue, onValueChange, onClear, placeholder, leftIcon, size, error, disabled, inputRef, inputProps, mobileVariant, renderOption, optionIcon, emptyMessage, emptyState, loadingMessage, clearIcon, clearLabel, sheetTitle, sheetCloseIcon, sheetCloseLabel, open: openProp, defaultOpen, onOpenChange, idPrefix, className, classNames }: AsyncAutocompleteProps<TData>): react_jsx_runtime.JSX.Element;
+declare function AsyncAutocomplete<TData = unknown>({ options, onSearch, onSelect, loading, value: valueProp, defaultValue, onValueChange, onClear, placeholder, label, mandatory, leftIcon, size, error, disabled, inputRef, inputProps, mobileVariant, renderOption, optionIcon, emptyMessage, emptyState, loadingMessage, clearIcon, clearLabel, sheetTitle, sheetCloseIcon, sheetCloseLabel, open: openProp, defaultOpen, onOpenChange, idPrefix, className, classNames }: AsyncAutocompleteProps<TData>): react_jsx_runtime.JSX.Element;
 
 interface TextareaProps extends Omit<React$1.ComponentProps<'textarea'>, 'size'> {
     error?: boolean;

package/dist/index.mjs

@@ -664,6 +664,8 @@ function AsyncAutocomplete({
   onValueChange,
   onClear,
   placeholder,
+  label,
+  mandatory = false,
   leftIcon,
   size = "md",
   error = false,
@@ -702,6 +704,13 @@ function AsyncAutocomplete({
   const sheetInputRef = React8.useRef(null);
   const optionRefs = React8.useRef([]);
   const isMobile = useIsMobile();
+  const hasAccessibleName = !!label || !!inputProps?.["aria-label"] || !!inputProps?.["aria-labelledby"];
+  React8.useEffect(() => {
+    if (process.env.NODE_ENV === "production" || hasAccessibleName) return;
+    console.warn(
+      "[AsyncAutocomplete] No accessible name. Pass `label`, or an `aria-label`/`aria-labelledby` via `inputProps`. A `placeholder` does not name a combobox."
+    );
+  }, [hasAccessibleName]);
   const isControlledValue = valueProp !== void 0;
   const isControlledOpen = openProp !== void 0;
   const query = isControlledValue ? valueProp : internalValue;
@@ -796,13 +805,13 @@ function AsyncAutocomplete({
     if (highlightedIndex < 0) return;
     optionRefs.current[highlightedIndex]?.scrollIntoView({ block: "nearest" });
   }, [highlightedIndex]);
-  const showEmpty = !loading && options.length === 0 && query.trim() !== "";
-  const hasBody = loading || options.length > 0 || showEmpty;
+  const hasOptions = options.length > 0;
+  const showLoadingRow = loading && !hasOptions;
+  const showEmpty = !loading && !hasOptions && query.trim() !== "";
+  const isRefreshing = loading && hasOptions;
+  const hasBody = showLoadingRow || hasOptions || showEmpty;
   const popoverOpen = isOpen && !useSheet && hasBody;
-  const dismissIgnoreRefs = React8.useMemo(
-    () => [contentRef, fieldRef],
-    []
-  );
+  const dismissIgnoreRefs = React8.useMemo(() => [contentRef, fieldRef], []);
   useDismissOnScroll(popoverOpen, closePanel, dismissIgnoreRefs);
   const handleKeyDown = (event) => {
     if (useSheet && !isOpen && (event.key === "Enter" || event.key === " " || event.key === "ArrowDown")) {
@@ -890,7 +899,16 @@ function AsyncAutocomplete({
               ),
               children: [
                 option.label,
-                option.description && /* @__PURE__ */ jsx8("span", { className: cn("text-gray-subtle", classNames?.optionDescription), children: `, ${option.description}` })
+                option.description && /* @__PURE__ */ jsx8(
+                  "span",
+                  {
+                    className: cn(
+                      "text-gray-subtle",
+                      classNames?.optionDescription
+                    ),
+                    children: `, ${option.description}`
+                  }
+                )
               ]
             }
           )
@@ -904,22 +922,71 @@ function AsyncAutocomplete({
     {
       role: "listbox",
       id: listboxId,
+      "aria-busy": loading || void 0,
+      "data-busy": isRefreshing || void 0,
       className: cn("flex flex-col", classNames?.listbox),
-      children: loading ? /* @__PURE__ */ jsxs5("div", { className: cn(messageClassName, classNames?.loading), children: [
-        /* @__PURE__ */ jsx8(
-          Loader2,
+      children: showLoadingRow ? (
+        // `role="listbox"` may only own `option` and `group` children, so the
+        // status rows are disabled options: still announced, never selectable,
+        // and skipped by keyboard nav since they are not in `options`.
+        /* @__PURE__ */ jsxs5(
+          "div",
           {
-            className: cn(
-              "size-[16px] animate-spin text-gray-icon-light",
-              classNames?.loadingSpinner
-            )
+            role: "option",
+            "aria-disabled": "true",
+            "aria-selected": "false",
+            className: cn(messageClassName, classNames?.loading),
+            children: [
+              /* @__PURE__ */ jsx8(
+                Loader2,
+                {
+                  className: cn(
+                    "size-[16px] animate-spin text-gray-icon-light",
+                    classNames?.loadingSpinner
+                  )
+                }
+              ),
+              loadingMessage
+            ]
           }
-        ),
-        loadingMessage
-      ] }) : showEmpty ? emptyState ?? /* @__PURE__ */ jsx8("div", { className: cn(messageClassName, classNames?.empty), children: emptyMessage }) : options.map(renderRow)
+        )
+      ) : showEmpty ? /* @__PURE__ */ jsx8(
+        "div",
+        {
+          role: "option",
+          "aria-disabled": "true",
+          "aria-selected": "false",
+          className: cn(!emptyState && messageClassName, classNames?.empty),
+          children: emptyState ?? emptyMessage
+        }
+      ) : options.map(renderRow)
     }
   );
   const activeDescendant = highlightedIndex >= 0 ? optionDomId(highlightedIndex) : void 0;
+  const labelNode = label ? /* @__PURE__ */ jsxs5(
+    "label",
+    {
+      htmlFor: `${prefix}-input`,
+      "data-slot": "async-autocomplete-label",
+      className: cn(
+        "flex items-center font-sans font-medium text-[14px] leading-[20px] text-vibrant-text-details",
+        classNames?.label
+      ),
+      children: [
+        label,
+        mandatory && // Decorative: the requirement is conveyed by aria-required on the
+        // input, so screen readers say "City, required" rather than "City star".
+        /* @__PURE__ */ jsx8(
+          "span",
+          {
+            "aria-hidden": "true",
+            className: "ml-0.5 text-[14px] leading-[20px] text-error-surface-default",
+            children: "*"
+          }
+        )
+      ]
+    }
+  ) : null;
   const field = /* @__PURE__ */ jsx8("div", { ref: fieldRef, className: cn("relative w-full", classNames?.field), children: /* @__PURE__ */ jsx8(
     Input,
     {
@@ -933,6 +1000,7 @@ function AsyncAutocomplete({
       "aria-expanded": useSheet ? sheetIsOpen : popoverOpen,
       "aria-controls": popoverOpen ? listboxId : void 0,
       "aria-autocomplete": useSheet ? void 0 : "list",
+      "aria-required": mandatory || void 0,
       "aria-activedescendant": popoverOpen ? activeDescendant : void 0,
       size,
       error,
@@ -971,8 +1039,13 @@ function AsyncAutocomplete({
           "div",
           {
             "data-slot": "async-autocomplete",
-            className: cn("w-full", className),
+            className: cn(
+              "flex w-full flex-col",
+              labelNode && "gap-[8px]",
+              className
+            ),
             children: [
+              labelNode,
               /* @__PURE__ */ jsx8(PopoverPrimitive.Anchor, { asChild: true, children: field }),
               /* @__PURE__ */ jsx8(PopoverPrimitive.Portal, { children: /* @__PURE__ */ jsx8(
                 PopoverPrimitive.Content,
@@ -1076,7 +1149,7 @@ function AsyncAutocomplete({
                               "aria-controls": listboxId,
                               "aria-autocomplete": "list",
                               "aria-activedescendant": activeDescendant,
-                              "aria-label": sheetTitle,
+                              "aria-label": label ?? sheetTitle,
                               size,
                               placeholder,
                               leftIcon,