@godxjp/ui 16.10.0 → 17.0.0

package/README.md

@@ -139,9 +139,9 @@ bundled fonts). To ship only what you render, import the foundation plus the
 per-layer files you need (mirrors the JS subpaths — the CSS tree-shakes too):
 
 ```css
-@import "@godxjp/ui/styles/base";          /* required: tokens + tailwind + base layer */
-@import "@godxjp/ui/styles/control";       /* Button, Input, Select, Textarea, toggles */
-@import "@godxjp/ui/styles/form-layout";   /* FormField */
+@import "@godxjp/ui/styles/base"; /* required: tokens + tailwind + base layer */
+@import "@godxjp/ui/styles/control"; /* Button, Input, Select, Textarea, toggles */
+@import "@godxjp/ui/styles/form-layout"; /* FormField */
 @import "@godxjp/ui/styles/dialog-layout"; /* Dialog */
 /* …only the layers you use. Layer files need `base` first (they use @layer/@apply). */
 ```
@@ -158,8 +158,8 @@ one face everywhere, or per-language (no `[lang]` selectors to write):
 ```css
 :root {
   --font-sans-base: var(--my-latin), system-ui, sans-serif; /* default face */
-  --font-sans-ja: "Noto Sans JP", var(--font-sans-base);    /* lang="ja" */
-  --font-sans-vi: "Montserrat", var(--font-sans-base);      /* lang="vi" */
+  --font-sans-ja: "Noto Sans JP", var(--font-sans-base); /* lang="ja" */
+  --font-sans-vi: "Montserrat", var(--font-sans-base); /* lang="vi" */
   /* also: --font-sans-ko, --font-sans-zh-hans, --font-sans-zh-hant */
 }
 ```
@@ -221,6 +221,31 @@ pnpm release --ui <patch|minor|major> --mcp <…|skip>   # publish lib + MCP in
 | `check:mcp-orphans`     | every public component HAS a catalog entry (catalog can't rot)       |
 | `check:core-isolation`  | the root export pulls no foreign runtime (adapters stay on subpaths) |
 
+### Runtime visual audit (Playwright + axe-core)
+
+`scripts/visual-audit.mjs` drives a **real browser** over a running app and runs axe-core plus
+computed-style heuristics (target size, OKLCH accent chroma, rendered emoji, mis-laid-out alerts) —
+catching what the static `pnpm audit` (source regexes) can't see. Playwright + `@axe-core/playwright`
+are **optional peers**, installed only by apps that run the audit.
+
+```bash
+# from a consumer, against its running dev/preview server:
+node node_modules/@godxjp/ui/scripts/visual-audit.mjs http://localhost:5173 /invoices /settings
+node node_modules/@godxjp/ui/scripts/visual-audit.mjs http://localhost:5173 --format json  # machine-readable
+node node_modules/@godxjp/ui/scripts/visual-audit.mjs --strict http://localhost:5173       # CI gate
+```
+
+**Tested peer range** (pin one of these): `playwright >=1.55 <2` (tested 1.61.1) ·
+`@axe-core/playwright >=4.10 <5` (tested 4.12.1) · `axe-core >=4.10 <5` (tested 4.12.1). Playwright
+1.55+ is required for the `browser.newContext()` → `context.newPage()` flow axe expects; older
+`browser.newPage()` throws _"Please use browser.newContext()"_.
+
+`--format json` **always** emits valid JSON — even on bootstrap failure — with a `status`
+(`ok` · `partial` · `error`) that separates **infrastructure errors** (missing peers, page won't
+load, axe won't inject → `errors[]`, `summary: null`/flagged) from **product findings** (`findings[]`).
+A tool failure can therefore never be misread as "zero violations". `pnpm check:visual-audit` is the
+CI smoke test: it serves a fixture page tripping all five rule families and asserts each one fires.
+
 This repo ships two packages — `@godxjp/ui` (this dir) and `@godxjp/ui-mcp` (`mcp/`). They keep
 separate version lines but release together via `pnpm release`; see DEVELOPMENT.md §6.
 The **preview app auto-deploys to [GitHub Pages](https://godx-jp.github.io/godxjp-ui/)** on every push to `main`

package/dist/components/charts/chart-cartesian.js

@@ -17,12 +17,7 @@ import {
 } from "recharts";
 import { EmptyState } from "../data-display/empty-state.js";
 import { useTranslation } from "../../i18n/use-translation.js";
-import {
-  ChartFrame,
-  chartColor,
-  chartHeight,
-  useChartNumberFormat
-} from "./chart-frame.js";
+import { ChartFrame, chartColor, chartHeight, useChartNumberFormat } from "./chart-frame.js";
 import { buildCartesianSummary } from "./chart-summary.js";
 function CartesianChart({
   kind,

package/dist/components/charts/pie-chart.js

@@ -1,13 +1,6 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
-import {
-  Cell,
-  Legend,
-  Pie,
-  PieChart as RPieChart,
-  ResponsiveContainer,
-  Tooltip
-} from "recharts";
+import { Cell, Legend, Pie, PieChart as RPieChart, ResponsiveContainer, Tooltip } from "recharts";
 import { EmptyState } from "../data-display/empty-state.js";
 import { useTranslation } from "../../i18n/use-translation.js";
 import { ChartFrame, chartColor, chartHeight, useChartNumberFormat } from "./chart-frame.js";

package/dist/components/data-display/empty-state.d.ts

@@ -1,3 +1,3 @@
 import type { EmptyStateProp } from "../../props/components/data-display.prop.js";
 export type { EmptyStateProp, EmptyStateProp as EmptyStateProps, } from "../../props/components/data-display.prop.js";
-export declare function EmptyState({ icon: Icon, title, description, action, className }: EmptyStateProp): import("react/jsx-runtime").JSX.Element;
+export declare function EmptyState({ icon: Icon, title, description, action, variant, tone, className, }: EmptyStateProp): import("react/jsx-runtime").JSX.Element;

package/dist/components/data-display/empty-state.js

@@ -1,12 +1,30 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { cn } from "../../lib/utils.js";
-function EmptyState({ icon: Icon, title, description, action, className }) {
-  return /* @__PURE__ */ jsxs("div", { "data-slot": "empty-state", role: "status", className: cn("ui-empty-state", className), children: [
-    Icon && /* @__PURE__ */ jsx("div", { className: "ui-empty-state-icon", children: /* @__PURE__ */ jsx(Icon, { className: "text-muted-foreground size-6", "aria-hidden": "true" }) }),
-    /* @__PURE__ */ jsx("h3", { className: "ui-empty-state-title", children: title }),
-    description && /* @__PURE__ */ jsx("p", { className: "ui-empty-state-description", children: description }),
-    action && /* @__PURE__ */ jsx("div", { children: action })
-  ] });
+function EmptyState({
+  icon: Icon,
+  title,
+  description,
+  action,
+  variant = "page",
+  tone = "muted",
+  className
+}) {
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      "data-slot": "empty-state",
+      "data-variant": variant,
+      "data-tone": tone,
+      role: "status",
+      className: cn("ui-empty-state", className),
+      children: [
+        Icon && variant !== "compact" && /* @__PURE__ */ jsx("div", { className: "ui-empty-state-icon", children: /* @__PURE__ */ jsx(Icon, { className: "text-muted-foreground size-6", "aria-hidden": "true" }) }),
+        /* @__PURE__ */ jsx("h3", { className: "ui-empty-state-title", children: title }),
+        description && /* @__PURE__ */ jsx("p", { className: "ui-empty-state-description", children: description }),
+        action && /* @__PURE__ */ jsx("div", { children: action })
+      ]
+    }
+  );
 }
 export {
   EmptyState

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

@@ -37,6 +37,9 @@ function FormField({
     );
   }
   const childProps = React.isValidElement(children) ? children.props : void 0;
+  const mergeIds = (...values) => Array.from(new Set(values.flatMap((value) => value?.split(/\s+/).filter(Boolean) ?? []))).join(
+    " "
+  ) || void 0;
   const childWithA11y = React.isValidElement(children) ? React.cloneElement(children, {
     // The label is associated via aria-labelledby (not <label for>): composite
     // controls (Radio.Group, checkbox lists, range pairs) have no labelable root,
@@ -45,10 +48,16 @@ function FormField({
     "aria-labelledby": childProps?.["aria-labelledby"] ?? labelId,
     // Helper and error can coexist: helper stays on aria-describedby, the error on
     // aria-errormessage (surfaced when aria-invalid is true).
-    "aria-describedby": helperId,
-    "aria-errormessage": errorId,
-    "aria-required": required ? true : void 0,
-    "aria-invalid": !!error || void 0
+    "aria-describedby": mergeIds(
+      childProps?.["aria-describedby"],
+      helperId
+    ),
+    "aria-errormessage": mergeIds(
+      childProps?.["aria-errormessage"],
+      errorId
+    ),
+    "aria-required": required ? true : childProps?.["aria-required"],
+    "aria-invalid": error ? true : childProps?.["aria-invalid"]
   }) : children;
   const style = {};
   if (labelWidth != null)

package/dist/components/data-entry/search-select.d.ts

@@ -8,4 +8,4 @@ export type { SearchSelectProp, SearchSelectProp as SearchSelectProps, SearchSel
  * Custom per-option rendering via `renderOption` (Ant-Design style). Form-submittable via
  * `name`; e2e-testable by the trigger's `data-testid` + each option's `${data-testid}-option-${value}`.
  */
-export declare function SearchSelect({ value: valueProp, defaultValue, onValueChange, options: staticOptions, loadOptions, renderOption, labelRender, selectedLabel, selectedIcon, placeholder, searchPlaceholder, emptyMessage, loadingMessage, clearLabel, clearable, disabled, name, id, className, "data-testid": dataTestId, }: SearchSelectProp): import("react/jsx-runtime").JSX.Element;
+export declare function SearchSelect({ value: valueProp, defaultValue, onValueChange, options: staticOptions, loadOptions, renderOption, labelRender, selectedLabel, selectedIcon, placeholder, searchPlaceholder, emptyMessage, loadingMessage, errorMessage, clearLabel, clearable, disabled, name, id, className, "data-testid": dataTestId, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledby, "aria-describedby": ariaDescribedby, "aria-errormessage": ariaErrorMessage, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, }: SearchSelectProp): import("react/jsx-runtime").JSX.Element;

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

@@ -7,7 +7,7 @@ import { cn } from "../../lib/utils.js";
 import { controlOpenRingClass } from "../../lib/control-styles.js";
 import { Button } from "../general/button.js";
 import { Popover, PopoverContent, PopoverTrigger } from "../data-display/popover.js";
-import { Command, CommandGroup, CommandItem, CommandList } from "./command.js";
+import { Command, CommandGroup } from "./command.js";
 import { Input } from "./input.js";
 const DEBOUNCE_MS = 250;
 function SearchSelect({
@@ -24,13 +24,20 @@ function SearchSelect({
   searchPlaceholder,
   emptyMessage,
   loadingMessage,
+  errorMessage,
   clearLabel,
   clearable = true,
   disabled = false,
   name,
   id,
   className,
-  "data-testid": dataTestId
+  "data-testid": dataTestId,
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledby,
+  "aria-describedby": ariaDescribedby,
+  "aria-errormessage": ariaErrorMessage,
+  "aria-invalid": ariaInvalid,
+  "aria-required": ariaRequired
 }) {
   const { t } = useTranslation();
   const reactId = React.useId();
@@ -43,6 +50,7 @@ function SearchSelect({
   const [page, setPage] = React.useState(1);
   const [hasMore, setHasMore] = React.useState(false);
   const [loading, setLoading] = React.useState(false);
+  const [error, setError] = React.useState(false);
   const [activeIndex, setActiveIndex] = React.useState(0);
   const [picked, setPicked] = React.useState(null);
   const [internalValue, setInternalValue] = React.useState(defaultValue ?? "");
@@ -70,12 +78,22 @@ function SearchSelect({
     async (nextPage, search, append) => {
       const ticket = ++reqId.current;
       setLoading(true);
+      if (!append) setError(false);
       try {
         const result = await resolvedLoad({ query: search, page: nextPage });
         if (ticket !== reqId.current) return;
         setLoaded((prev) => append ? [...prev, ...result.options] : result.options);
+        if (!append) {
+          const firstEnabled = result.options.findIndex((option) => !option.disabled);
+          setActiveIndex(firstEnabled >= 0 ? firstEnabled : 0);
+        }
         setHasMore(Boolean(result.hasMore));
         setPage(nextPage);
+      } catch {
+        if (ticket !== reqId.current) return;
+        if (!append) setLoaded([]);
+        setHasMore(false);
+        setError(true);
       } finally {
         if (ticket === reqId.current) setLoading(false);
       }
@@ -131,13 +149,36 @@ function SearchSelect({
       void fetchPage(page + 1, debouncedQuery, true);
     }
   };
+  const moveActive = (direction) => {
+    if (flatOrdered.length === 0) return;
+    let next = activeIndex;
+    for (let checked = 0; checked < flatOrdered.length; checked += 1) {
+      next = (next + direction + flatOrdered.length) % flatOrdered.length;
+      if (!flatOrdered[next]?.disabled) {
+        setActiveIndex(next);
+        return;
+      }
+    }
+  };
+  const moveToEdge = (edge) => {
+    const indices = flatOrdered.map((_, index) => index);
+    if (edge === "end") indices.reverse();
+    const next = indices.find((index) => !flatOrdered[index]?.disabled);
+    if (next !== void 0) setActiveIndex(next);
+  };
   const onKeyDown = (event) => {
     if (event.key === "ArrowDown") {
       event.preventDefault();
-      setActiveIndex((i) => Math.min(i + 1, Math.max(flatOrdered.length - 1, 0)));
+      moveActive(1);
     } else if (event.key === "ArrowUp") {
       event.preventDefault();
-      setActiveIndex((i) => Math.max(i - 1, 0));
+      moveActive(-1);
+    } else if (event.key === "Home") {
+      event.preventDefault();
+      moveToEdge("start");
+    } else if (event.key === "End") {
+      event.preventDefault();
+      moveToEdge("end");
     } else if (event.key === "Enter" && flatOrdered[activeIndex]) {
       event.preventDefault();
       select(flatOrdered[activeIndex]);
@@ -168,6 +209,13 @@ function SearchSelect({
               variant: "outline",
               role: "combobox",
               "aria-expanded": open,
+              "aria-controls": open ? listId : void 0,
+              "aria-label": ariaLabel,
+              "aria-labelledby": ariaLabelledby,
+              "aria-describedby": ariaDescribedby,
+              "aria-errormessage": ariaErrorMessage,
+              "aria-invalid": ariaInvalid,
+              "aria-required": ariaRequired,
               disabled,
               "data-testid": dataTestId,
               className: cn(
@@ -195,11 +243,13 @@ function SearchSelect({
           /* @__PURE__ */ jsx(
             PopoverContent,
             {
+              "aria-label": ariaLabelledby ? void 0 : ariaLabel ?? resolvedPlaceholder,
+              "aria-labelledby": ariaLabelledby,
               align: "start",
               sideOffset: 4,
               collisionPadding: 12,
               className: "flex max-h-[var(--radix-popover-content-available-height)] w-max max-w-[min(32rem,calc(100vw-1.5rem))] min-w-[var(--radix-popover-trigger-width)] flex-col p-0",
-              children: /* @__PURE__ */ jsxs(Command, { shouldFilter: false, className: "flex min-h-0 flex-col", children: [
+              children: /* @__PURE__ */ jsxs(Command, { value, shouldFilter: false, className: "flex min-h-0 flex-col", children: [
                 /* @__PURE__ */ jsx("div", { className: "border-border shrink-0 border-b", children: /* @__PURE__ */ jsx(
                   Input,
                   {
@@ -207,6 +257,7 @@ function SearchSelect({
                     "aria-controls": listId,
                     "aria-autocomplete": "list",
                     "aria-activedescendant": activeOptionId,
+                    "aria-label": searchPlaceholder ?? t("dataEntry.searchSelect.search"),
                     value: query,
                     onChange: (event) => setQuery(event.target.value),
                     onKeyDown,
@@ -215,32 +266,35 @@ function SearchSelect({
                   }
                 ) }),
                 /* @__PURE__ */ jsxs(
-                  CommandList,
+                  "div",
                   {
                     id: listId,
                     role: "listbox",
+                    "aria-busy": loading,
                     className: "max-h-none min-h-0 flex-1 overflow-y-auto p-1",
                     onScroll,
                     children: [
                       grouped.map((group) => {
                         const rows = group.items.map(({ option, index }) => /* @__PURE__ */ jsx(
-                          CommandItem,
+                          "div",
                           {
                             id: optionDomId(option.value),
                             role: "option",
-                            value: option.value,
                             "data-testid": optionTestId(option.value),
-                            "aria-selected": activeIndex === index,
-                            disabled: option.disabled,
+                            "aria-selected": value === option.value,
+                            "aria-disabled": option.disabled || void 0,
+                            "data-disabled": option.disabled || 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.
                               value === option.value && "bg-accent text-foreground font-medium",
                               activeIndex === index && "bg-accent text-accent-foreground"
                             ),
-                            onMouseEnter: () => setActiveIndex(index),
-                            onSelect: () => select(option),
+                            onMouseEnter: () => !option.disabled && setActiveIndex(index),
+                            onMouseDown: (event) => event.preventDefault(),
+                            onClick: () => select(option),
                             children: renderOption ? /* @__PURE__ */ jsx("div", { className: "min-w-0 flex-1", children: renderOption(option) }) : /* @__PURE__ */ jsxs("div", { className: "flex min-w-0 flex-1 items-center gap-2", children: [
                               option.icon ? /* @__PURE__ */ jsx("span", { className: "flex shrink-0 items-center", "aria-hidden": "true", children: option.icon }) : null,
                               /* @__PURE__ */ jsxs("div", { className: "flex min-w-0 flex-col", children: [
@@ -253,11 +307,35 @@ function SearchSelect({
                         ));
                         return group.heading ? /* @__PURE__ */ jsx(CommandGroup, { heading: group.heading, children: rows }, group.heading) : /* @__PURE__ */ jsx(React.Fragment, { children: rows }, "__ungrouped");
                       }),
-                      loading ? /* @__PURE__ */ jsxs("div", { className: "text-muted-foreground flex items-center gap-2 px-2 py-3 text-sm", children: [
-                        /* @__PURE__ */ jsx(Loader2, { className: "size-4 animate-spin", "aria-hidden": "true" }),
-                        loadingMessage ?? t("dataEntry.searchSelect.loading")
-                      ] }) : null,
-                      !loading && loaded.length === 0 ? /* @__PURE__ */ jsx("div", { className: "text-muted-foreground px-2 py-6 text-center text-sm", children: emptyMessage ?? t("dataEntry.searchSelect.empty") }) : null
+                      loading ? /* @__PURE__ */ jsxs(
+                        "div",
+                        {
+                          role: "status",
+                          className: "text-muted-foreground flex items-center gap-2 px-2 py-3 text-sm",
+                          children: [
+                            /* @__PURE__ */ jsx(Loader2, { className: "size-4 animate-spin", "aria-hidden": "true" }),
+                            loadingMessage ?? t("dataEntry.searchSelect.loading")
+                          ]
+                        }
+                      ) : error ? /* @__PURE__ */ jsx(
+                        "div",
+                        {
+                          role: "option",
+                          "aria-disabled": "true",
+                          "aria-selected": false,
+                          className: "text-destructive px-2 py-6 text-center text-sm",
+                          children: errorMessage ?? t("dataEntry.searchSelect.error")
+                        }
+                      ) : loaded.length === 0 ? /* @__PURE__ */ jsx(
+                        "div",
+                        {
+                          role: "option",
+                          "aria-disabled": "true",
+                          "aria-selected": false,
+                          className: "text-muted-foreground px-2 py-6 text-center text-sm",
+                          children: emptyMessage ?? t("dataEntry.searchSelect.empty")
+                        }
+                      ) : null
                     ]
                   }
                 )
@@ -267,13 +345,13 @@ function SearchSelect({
         ]
       }
     ),
-    /* @__PURE__ */ jsx("div", { className: "pointer-events-none absolute inset-y-0 end-3 flex items-center", children: showClear ? /* @__PURE__ */ jsx(
+    /* @__PURE__ */ jsx("div", { className: "pointer-events-none absolute inset-y-0 end-2 flex items-center", children: showClear ? /* @__PURE__ */ jsx(
       "button",
       {
         type: "button",
         "aria-label": clearLabel ?? t("dataEntry.searchSelect.clear"),
         "data-testid": optionTestId("clear"),
-        className: "pointer-events-auto flex size-4 items-center justify-center rounded-sm opacity-50 hover:opacity-100 focus-visible:opacity-100",
+        className: "pointer-events-auto flex size-6 items-center justify-center rounded-sm opacity-50 hover:opacity-100 focus-visible:opacity-100",
         onClick: clear,
         children: /* @__PURE__ */ jsx(X, { className: "size-4", "aria-hidden": "true" })
       }

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

@@ -35,7 +35,14 @@ const SelectTrigger = React.forwardRef(({ className, children, size = "md", ...p
     ...props,
     children: [
       children,
-      /* @__PURE__ */ jsx(SelectPrimitive.Icon, { asChild: true, children: /* @__PURE__ */ jsx(ChevronDown, { className: "size-4 shrink-0 opacity-50", "aria-hidden": "true" }) })
+      /* @__PURE__ */ jsx(SelectPrimitive.Icon, { asChild: true, children: /* @__PURE__ */ jsx(
+        ChevronDown,
+        {
+          "data-slot": "select-chevron",
+          className: "size-4 shrink-0 opacity-50",
+          "aria-hidden": "true"
+        }
+      ) })
     ]
   }
 ));
@@ -154,6 +161,7 @@ function DataSelect({
   searchPlaceholder,
   emptyMessage,
   loadingMessage,
+  errorMessage,
   clearLabel,
   clearable,
   disabled,
@@ -167,6 +175,7 @@ function DataSelect({
     Object.entries(rest).filter(([key]) => key.startsWith("aria-"))
   );
   const searchable = showSearch ?? Boolean(loadOptions);
+  const hasOptions = options.length > 0;
   if (searchable) {
     return /* @__PURE__ */ jsx(
       SearchSelect,
@@ -184,13 +193,15 @@ function DataSelect({
         searchPlaceholder,
         emptyMessage,
         loadingMessage,
+        errorMessage,
         clearLabel,
         clearable,
-        disabled,
+        disabled: disabled || !loadOptions && !hasOptions,
         name,
         id,
         className,
-        "data-testid": dataTestId
+        "data-testid": dataTestId,
+        ...ariaProps
       }
     );
   }
@@ -216,7 +227,7 @@ function DataSelect({
         next,
         options.find((option) => option.value === next)
       ),
-      disabled,
+      disabled: disabled || !hasOptions,
       name,
       children: [
         /* @__PURE__ */ jsx(SelectTrigger, { id, "data-testid": dataTestId, className, ...ariaProps, children: /* @__PURE__ */ jsx(SelectValue, { placeholder }) }),

package/dist/components/feedback/alert.d.ts

@@ -26,8 +26,17 @@ export declare const AlertActions: React.ForwardRefExoticComponent<React.HTMLAtt
     className?: import("../../props/index.js").ClassNameProp;
     children?: import("../../props/index.js").ChildrenProp;
 } & React.RefAttributes<HTMLDivElement>>;
-/** TanStack Query / API failure preset — same visual as `Alert tone="destructive"`. Used by `DataState` (@godxjp/ui/query). */
-export declare function AlertQueryError({ error, onRetry, className }: AlertQueryErrorProp): import("react/jsx-runtime").JSX.Element;
+/**
+ * TanStack Query / API failure preset used by `DataState` (@godxjp/ui/query).
+ *
+ * - **Cause-aware mode** (pass `category`, as `DataState` does): presents a safe, localized message
+ *   — never the raw backend/token/stack text — with a cause-appropriate action. `auth`
+ *   (401/expired) offers session renewal (`onAuthAction`) instead of Retry; transient/network/5xx
+ *   offer Retry (`onRetry`); permission/not-found/validation offer neither by default.
+ * - **Legacy mode** (no `category`, e.g. mutation/infinite feedback): shows the cleaned domain
+ *   message (`humanError`) + optional Retry — form-submit corrective guidance stays visible.
+ */
+export declare function AlertQueryError({ error, category, onRetry, onAuthAction, className, }: AlertQueryErrorProp): import("react/jsx-runtime").JSX.Element;
 export declare const Alert: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
     variant?: import("../../props/index.js").AlertVariantProp;
     tone?: ToneProp;

package/dist/components/feedback/alert.js

@@ -5,6 +5,7 @@ import {
   AlertCircle,
   CheckCircle2,
   Info,
+  LogIn,
   RefreshCw,
   TriangleAlert,
   X
@@ -89,25 +90,66 @@ const AlertActions = React.forwardRef(
   ({ className, ...props }, ref) => /* @__PURE__ */ jsx("div", { ref, "data-slot": "alert-actions", className, ...props })
 );
 AlertActions.displayName = "AlertActions";
-function AlertQueryError({ error, onRetry, className }) {
+const WARNING_CATEGORIES = /* @__PURE__ */ new Set([
+  "forbidden",
+  "notFound",
+  "validation"
+]);
+const RETRYABLE_CATEGORIES = /* @__PURE__ */ new Set([
+  "transient",
+  "unknown"
+]);
+function RetryButton({ onRetry }) {
   const { t } = useTranslation();
-  return /* @__PURE__ */ jsxs(Alert, { tone: "destructive", className, children: [
-    /* @__PURE__ */ jsx(AlertTitle, { children: t("common.error") }),
-    /* @__PURE__ */ jsx(AlertDescription, { children: humanError(error) }),
-    onRetry && /* @__PURE__ */ jsx(AlertActions, { children: /* @__PURE__ */ jsx(
+  return /* @__PURE__ */ jsx(AlertActions, { children: /* @__PURE__ */ jsx(
+    Button,
+    {
+      variant: "outline",
+      size: "sm",
+      onClick: () => {
+        void onRetry();
+      },
+      children: /* @__PURE__ */ jsxs(Flex, { direction: "row", wrap: true, align: "center", gap: "xs", children: [
+        /* @__PURE__ */ jsx(RefreshCw, { className: "size-4", "aria-hidden": "true" }),
+        t("common.retry")
+      ] })
+    }
+  ) });
+}
+function AlertQueryError({
+  error,
+  category,
+  onRetry,
+  onAuthAction,
+  className
+}) {
+  const { t } = useTranslation();
+  if (!category) {
+    return /* @__PURE__ */ jsxs(Alert, { tone: "destructive", className, children: [
+      /* @__PURE__ */ jsx(AlertTitle, { children: t("common.error") }),
+      /* @__PURE__ */ jsx(AlertDescription, { children: humanError(error) }),
+      onRetry && /* @__PURE__ */ jsx(RetryButton, { onRetry })
+    ] });
+  }
+  const tone = WARNING_CATEGORIES.has(category) ? "warning" : "destructive";
+  return /* @__PURE__ */ jsxs(Alert, { tone, className, children: [
+    /* @__PURE__ */ jsx(AlertTitle, { children: t(`query.error.title.${category}`) }),
+    /* @__PURE__ */ jsx(AlertDescription, { children: t(`query.error.description.${category}`) }),
+    category === "auth" && onAuthAction && /* @__PURE__ */ jsx(AlertActions, { children: /* @__PURE__ */ jsx(
       Button,
       {
         variant: "outline",
         size: "sm",
         onClick: () => {
-          void onRetry();
+          void onAuthAction();
         },
         children: /* @__PURE__ */ jsxs(Flex, { direction: "row", wrap: true, align: "center", gap: "xs", children: [
-          /* @__PURE__ */ jsx(RefreshCw, { className: "size-4", "aria-hidden": "true" }),
-          t("common.retry")
+          /* @__PURE__ */ jsx(LogIn, { className: "size-4", "aria-hidden": "true" }),
+          t("query.error.action.signIn")
         ] })
       }
-    ) })
+    ) }),
+    RETRYABLE_CATEGORIES.has(category) && onRetry && /* @__PURE__ */ jsx(RetryButton, { onRetry })
   ] });
 }
 const Alert = Object.assign(AlertBase, {

package/dist/components/general/button.js

@@ -62,6 +62,7 @@ const Button = React.forwardRef(
     overflowCount = 99,
     showZero = true,
     disabled,
+    type,
     children,
     ...props
   }, ref) => {
@@ -96,6 +97,7 @@ const Button = React.forwardRef(
         "data-loading": isLoading ? "" : void 0,
         "aria-busy": isLoading || void 0,
         disabled: isLoading || disabled,
+        type: asChild ? void 0 : type ?? "button",
         className: cn(
           "inline-flex shrink-0 items-center justify-center gap-2 text-sm font-medium whitespace-nowrap transition-all outline-none",
           fullWidth && "w-full",

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

@@ -4,3 +4,5 @@ export { Text, Heading } from "./typography.js";
 export type { TextProps, HeadingProps, TextProp, HeadingProp } from "./typography.js";
 export { Logo } from "./logo.js";
 export type { LogoProps, LogoSize } from "./logo.js";
+export { Reveal } from "./reveal.js";
+export type { RevealProp, RevealProps } from "./reveal.js";

package/dist/components/general/index.js

@@ -1,10 +1,12 @@
 import { Button, buttonVariants } from "./button.js";
 import { Text, Heading } from "./typography.js";
 import { Logo } from "./logo.js";
+import { Reveal } from "./reveal.js";
 export {
   Button,
   Heading,
   Logo,
+  Reveal,
   Text,
   buttonVariants
 };

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

@@ -0,0 +1,14 @@
+import type { RevealProp } from "../../props/components/general.prop.js";
+export type { RevealProp, RevealProp as RevealProps } from "../../props/components/general.prop.js";
+/**
+ * Reveal — the official entrance-motion primitive (staggered fade-up). Content animates in on mount
+ * reading the DS motion tokens (`--duration-slow`, `--ease-emphasized`, `--reveal-distance`), so a
+ * consumer never hand-rolls `@keyframes` + `.app-reveal`/`.d1..d6`. `delay` is a stagger ordinal
+ * (`0..6`) — an index into the `--reveal-stagger-step` ladder, never a raw ms — so a column of rows
+ * cascades in. Under `prefers-reduced-motion` the animation is dropped entirely: content renders in
+ * its final position, fully visible, with no layout shift (CSS `@media` guard in motion.css).
+ *
+ * Pure/server-safe: no hooks, no effects. Pass `asChild` to merge the reveal onto the single child
+ * element (no wrapper `<div>`) when an extra box would break a grid/flex layout.
+ */
+export declare function Reveal({ children, delay, asChild, className, ...props }: RevealProp): import("react/jsx-runtime").JSX.Element;

package/dist/components/general/reveal.js

@@ -0,0 +1,21 @@
+import { jsx } from "react/jsx-runtime";
+import { cloneElement, isValidElement } from "react";
+import { cn } from "../../lib/utils.js";
+function Reveal({ children, delay = 0, asChild = false, className, ...props }) {
+  const shared = {
+    "data-slot": "reveal",
+    "data-reveal-delay": delay > 0 ? String(delay) : void 0
+  };
+  if (asChild && isValidElement(children)) {
+    const child = children;
+    return cloneElement(child, {
+      ...shared,
+      ...props,
+      className: cn("ui-reveal", child.props.className, className)
+    });
+  }
+  return /* @__PURE__ */ jsx("div", { ...shared, ...props, className: cn("ui-reveal", className), children });
+}
+export {
+  Reveal
+};