@godxjp/ui 30.4.1 → 30.5.2

package/agent/patterns/brand-theme-block.json

@@ -0,0 +1,33 @@
+{
+  "aliases": [
+    "rebrand",
+    "design-handoff",
+    "brand-motion",
+    "motion-tokens",
+    "whitelabel",
+    "white-label-theme",
+    "theme-block",
+    "external-brand"
+  ],
+  "code": "// ─────────────────────────────────────────────────────────────────────────\n// A WHOLE BRAND AS A THEME BLOCK.\n//\n// tenantTheme(hex) is for ONE customer colour arriving as data. This is the\n// other job: a design system handed to you (brand book, Figma, an HTML\n// prototype) that has its own palette, radii, shadows, type ramp AND motion\n// timing. All of it is token configuration. If you find yourself forking a\n// component or overriding a .ui-* selector from a page stylesheet, stop —\n// that is the signal to file an issue for the missing knob instead.\n//\n// Worked screens, three different brands: /showcase/acme-website (light/gold),\n// /showcase/futurelastic-web (dark/gold), /showcase/tcgm-website (light,\n// Japanese, and the one with a MOTION spec).\n\n<div data-tenant=\"acme\">              {/* a REGION, never <html> */}\n  <style>{THEME}</style>              {/* in an app this is your theme.css */}\n  <Navbar /> <Hero /> <Footer />\n</div>\n\nconst THEME = `\n[data-tenant=\"acme\"] {\n  /* 1 ── COLOUR. Map the brand's hexes onto the ROLES, as HSL triplets. */\n  --primary: 192 72% 21%; --primary-foreground: 0 0% 100%;\n  --ring: 199 89% 29%;          /* DECLARE IT. --ring is bound at :root and FREEZES;\n                                   many brands ring in a different blue than they fill with. */\n  --background: 210 40% 98%; --foreground: 195 57% 16%;\n  --card: 0 0% 100%; --muted-foreground: 196 17% 39%;\n  /* --border is decorative chrome. --input is the CONTROL BOUNDARY and is held to\n     3:1 (WCAG 2.2 SC 1.4.11) — brands usually ship a second, darker \"border-strong\"\n     for exactly this; use THAT one here, not the hairline. */\n  --border: 196 27% 89%; --input: 197 13% 51%;\n\n  /* 2 ── SHAPE + ELEVATION. Card hover is a TOKEN PAIR, not a hand-written rule:\n     \"lift 2px, shadow sm→md\" == --card-shadow + --card-hover-shadow. */\n  --radius-md: 12px; --radius-xl: 20px;\n  --card-radius: var(--radius-xl); --control-radius: var(--radius-md);\n  --card-shadow: 0 1px 2px rgb(15 76 92 / .06);\n  --card-hover-shadow: 0 12px 32px -14px rgb(15 76 92 / .20);\n\n  /* 3 ── TYPE. --font-size-display is the BASE KNOB of the display ramp: 3xl/4xl/5xl\n     all derive from it, so never restate --font-size-5xl. Use clamp() or the hero\n     paints its desktop size on a phone (measured: 56px at 390 where the brand scale\n     said 34px). */\n  --font-family-body: \"Noto Sans JP\", system-ui, sans-serif;\n  --font-family-sans: var(--font-family-body);\n  --font-family-display: var(--font-family-body);\n  --font-size-display: clamp(2.125rem, 4vw, 3.5rem);\n  /* ❌ --font-family-display: \"Montserrat\", \"Noto Sans JP\", …\n     A Latin-only face FIRST in a CJK product looks fine (the browser falls through\n     per glyph) while silently setting the Latin inside a Japanese headline in a\n     different face than the headline. Keep the CJK face as the display family and\n     opt into the Latin face per element instead: */\n  --brand-latin: \"Montserrat\", system-ui, sans-serif;\n}\n[data-tenant=\"acme\"] .brand-eyebrow,\n[data-tenant=\"acme\"] .brand-price { font-family: var(--brand-latin); }\n\n/* 4 ── MOTION. THIS IS THE PART PEOPLE FORK OVER, AND THEY DO NOT NEED TO.\n   A brand motion table — press 90ms · hover 140 · state 200 · enter 260 ·\n   hero-once 480ms at y8→0 · cubic-bezier(.2,.8,.2,1) — is EIGHT declarations.\n   <Reveal>, Card hoverable, Dialog/Sheet enter and every token-driven transition\n   retime themselves off these. Zero new @keyframes. */\n[data-tenant=\"acme\"] {\n  --duration-fast: 140ms;      /* hover / focus  */\n  --duration-base: 200ms;      /* state change   */\n  --duration-slow: 480ms;      /* hero once      */\n  --ease-standard: cubic-bezier(.2,.8,.2,1);\n  --ease-emphasized: cubic-bezier(.2,.8,.2,1);\n  --ease-decelerate: cubic-bezier(.2,.8,.2,1);\n  --reveal-distance: 8px;      /* the spec's \"y8→0\" */\n  --reveal-stagger-step: 70ms;\n  /* a11y numbers are tokens too — this brand's standard is a 44px target, above\n     the WCAG 2.2 SC 2.5.8 floor of 24px (gh#931): */\n  --carousel-arrow-size: 2.75rem;\n}\n`;\n\n// 5 ── SPEND THE MOTION, THEN STOP. Most brand books cap decorative motion\n// (\"one decorative region per viewport; no parallax, no count-up, no infinite\n// float\"). Read the spec before adding effects — adding more is not proving the\n// framework, it is breaking the brand.\n\n<Reveal on=\"mount\">                 {/* hero: illustration only, if the spec says\n                                       \"text appears immediately\" — then DON'T wrap\n                                       the headline, so it paints on frame 1 */}\n  <img src={heroArt} alt=\"…\" />\n</Reveal>\n\n<Reveal on=\"view\">                  {/* one observer per SECTION */}\n  <SectionHeading />\n</Reveal>\n<ResponsiveGrid columns={{ base: 2, sm: 3, lg: 4 }}>\n  {items.map((it, i) => (\n    <Reveal key={it.id} on=\"view\" delay={Math.min(i, 5) + 1}>   {/* delay caps at 6 */}\n      <Card hoverable>…</Card>\n    </Reveal>\n  ))}\n</ResponsiveGrid>\n\n// ❌ THE ONE THAT BITES: never put on=\"view\" on something a scroller CLIPS.\n//    <Carousel><CarouselItem><Reveal on=\"view\">…  ← 3 of 4 slides stayed at\n//    opacity 0 FOREVER: the observer's root is the viewport and a clipped box has\n//    an empty intersection rect, so a slide parked outside the rail never enters.\n// ✅ Reveal the RAIL:\n<Reveal on=\"view\">\n  <Carousel>\n    <CarouselContent>\n      {news.map((n) => (\n        <CarouselItem key={n.id} className=\"basis-4/5 sm:basis-1/2 lg:basis-1/3\">\n          <Card hoverable>…</Card>          {/* fractional basis, never basis-[82%] */}\n        </CarouselItem>\n      ))}\n    </CarouselContent>\n  </Carousel>\n</Reveal>\n\n// 6 ── VERIFY BY MEASURING, NOT BY SCREENSHOT. A full-page screenshot does not\n// fire viewport observers, so every scroll reveal photographs as invisible and\n// tells you nothing. Scroll the document, then count:\n//   [...document.querySelectorAll('.ui-reveal')]\n//     .filter(e => e.getAttribute('data-reveal-state') === 'out').length   // must be 0\n//   document.documentElement.scrollWidth - document.documentElement.clientWidth // must be 0\n// Check the hero's computed font-size at 390, and remember ResponsiveGrid steps\n// are CONTAINER widths: inside a 1280 shell with 32px gutters, a 768 tablet hands\n// the grid 704px, so `md` (48rem) never fires there — key that column to `sm`.\n",
+  "name": "brand-theme-block",
+  "tagline": "Wear a WHOLE external brand — its palette, shape, type AND its motion spec — as one scoped theme block of token declarations. No forked components, no page-local overrides of library selectors. Use when you are handed a design system (Figma/HTML prototype/brand book), not a single customer hex.",
+  "tags": [
+    "theme",
+    "brand",
+    "rebrand",
+    "handoff",
+    "motion",
+    "animation",
+    "reveal",
+    "typography",
+    "font",
+    "cjk",
+    "japanese",
+    "tokens",
+    "design-system",
+    "white-label",
+    "marketing",
+    "landing"
+  ]
+}

package/agent/patterns-index.json

@@ -346,5 +346,37 @@
       "white-label",
       "launcher"
     ]
+  },
+  {
+    "aliases": [
+      "rebrand",
+      "design-handoff",
+      "brand-motion",
+      "motion-tokens",
+      "whitelabel",
+      "white-label-theme",
+      "theme-block",
+      "external-brand"
+    ],
+    "name": "brand-theme-block",
+    "tagline": "Wear a WHOLE external brand — its palette, shape, type AND its motion spec — as one scoped theme block of token declarations. No forked components, no page-local overrides of library selectors. Use when you are handed a design system (Figma/HTML prototype/brand book), not a single customer hex.",
+    "tags": [
+      "theme",
+      "brand",
+      "rebrand",
+      "handoff",
+      "motion",
+      "animation",
+      "reveal",
+      "typography",
+      "font",
+      "cjk",
+      "japanese",
+      "tokens",
+      "design-system",
+      "white-label",
+      "marketing",
+      "landing"
+    ]
   }
 ]

package/agent/patterns.json

@@ -366,5 +366,38 @@
       "white-label",
       "launcher"
     ]
+  },
+  {
+    "aliases": [
+      "rebrand",
+      "design-handoff",
+      "brand-motion",
+      "motion-tokens",
+      "whitelabel",
+      "white-label-theme",
+      "theme-block",
+      "external-brand"
+    ],
+    "code": "// ─────────────────────────────────────────────────────────────────────────\n// A WHOLE BRAND AS A THEME BLOCK.\n//\n// tenantTheme(hex) is for ONE customer colour arriving as data. This is the\n// other job: a design system handed to you (brand book, Figma, an HTML\n// prototype) that has its own palette, radii, shadows, type ramp AND motion\n// timing. All of it is token configuration. If you find yourself forking a\n// component or overriding a .ui-* selector from a page stylesheet, stop —\n// that is the signal to file an issue for the missing knob instead.\n//\n// Worked screens, three different brands: /showcase/acme-website (light/gold),\n// /showcase/futurelastic-web (dark/gold), /showcase/tcgm-website (light,\n// Japanese, and the one with a MOTION spec).\n\n<div data-tenant=\"acme\">              {/* a REGION, never <html> */}\n  <style>{THEME}</style>              {/* in an app this is your theme.css */}\n  <Navbar /> <Hero /> <Footer />\n</div>\n\nconst THEME = `\n[data-tenant=\"acme\"] {\n  /* 1 ── COLOUR. Map the brand's hexes onto the ROLES, as HSL triplets. */\n  --primary: 192 72% 21%; --primary-foreground: 0 0% 100%;\n  --ring: 199 89% 29%;          /* DECLARE IT. --ring is bound at :root and FREEZES;\n                                   many brands ring in a different blue than they fill with. */\n  --background: 210 40% 98%; --foreground: 195 57% 16%;\n  --card: 0 0% 100%; --muted-foreground: 196 17% 39%;\n  /* --border is decorative chrome. --input is the CONTROL BOUNDARY and is held to\n     3:1 (WCAG 2.2 SC 1.4.11) — brands usually ship a second, darker \"border-strong\"\n     for exactly this; use THAT one here, not the hairline. */\n  --border: 196 27% 89%; --input: 197 13% 51%;\n\n  /* 2 ── SHAPE + ELEVATION. Card hover is a TOKEN PAIR, not a hand-written rule:\n     \"lift 2px, shadow sm→md\" == --card-shadow + --card-hover-shadow. */\n  --radius-md: 12px; --radius-xl: 20px;\n  --card-radius: var(--radius-xl); --control-radius: var(--radius-md);\n  --card-shadow: 0 1px 2px rgb(15 76 92 / .06);\n  --card-hover-shadow: 0 12px 32px -14px rgb(15 76 92 / .20);\n\n  /* 3 ── TYPE. --font-size-display is the BASE KNOB of the display ramp: 3xl/4xl/5xl\n     all derive from it, so never restate --font-size-5xl. Use clamp() or the hero\n     paints its desktop size on a phone (measured: 56px at 390 where the brand scale\n     said 34px). */\n  --font-family-body: \"Noto Sans JP\", system-ui, sans-serif;\n  --font-family-sans: var(--font-family-body);\n  --font-family-display: var(--font-family-body);\n  --font-size-display: clamp(2.125rem, 4vw, 3.5rem);\n  /* ❌ --font-family-display: \"Montserrat\", \"Noto Sans JP\", …\n     A Latin-only face FIRST in a CJK product looks fine (the browser falls through\n     per glyph) while silently setting the Latin inside a Japanese headline in a\n     different face than the headline. Keep the CJK face as the display family and\n     opt into the Latin face per element instead: */\n  --brand-latin: \"Montserrat\", system-ui, sans-serif;\n}\n[data-tenant=\"acme\"] .brand-eyebrow,\n[data-tenant=\"acme\"] .brand-price { font-family: var(--brand-latin); }\n\n/* 4 ── MOTION. THIS IS THE PART PEOPLE FORK OVER, AND THEY DO NOT NEED TO.\n   A brand motion table — press 90ms · hover 140 · state 200 · enter 260 ·\n   hero-once 480ms at y8→0 · cubic-bezier(.2,.8,.2,1) — is EIGHT declarations.\n   <Reveal>, Card hoverable, Dialog/Sheet enter and every token-driven transition\n   retime themselves off these. Zero new @keyframes. */\n[data-tenant=\"acme\"] {\n  --duration-fast: 140ms;      /* hover / focus  */\n  --duration-base: 200ms;      /* state change   */\n  --duration-slow: 480ms;      /* hero once      */\n  --ease-standard: cubic-bezier(.2,.8,.2,1);\n  --ease-emphasized: cubic-bezier(.2,.8,.2,1);\n  --ease-decelerate: cubic-bezier(.2,.8,.2,1);\n  --reveal-distance: 8px;      /* the spec's \"y8→0\" */\n  --reveal-stagger-step: 70ms;\n  /* a11y numbers are tokens too — this brand's standard is a 44px target, above\n     the WCAG 2.2 SC 2.5.8 floor of 24px (gh#931): */\n  --carousel-arrow-size: 2.75rem;\n}\n`;\n\n// 5 ── SPEND THE MOTION, THEN STOP. Most brand books cap decorative motion\n// (\"one decorative region per viewport; no parallax, no count-up, no infinite\n// float\"). Read the spec before adding effects — adding more is not proving the\n// framework, it is breaking the brand.\n\n<Reveal on=\"mount\">                 {/* hero: illustration only, if the spec says\n                                       \"text appears immediately\" — then DON'T wrap\n                                       the headline, so it paints on frame 1 */}\n  <img src={heroArt} alt=\"…\" />\n</Reveal>\n\n<Reveal on=\"view\">                  {/* one observer per SECTION */}\n  <SectionHeading />\n</Reveal>\n<ResponsiveGrid columns={{ base: 2, sm: 3, lg: 4 }}>\n  {items.map((it, i) => (\n    <Reveal key={it.id} on=\"view\" delay={Math.min(i, 5) + 1}>   {/* delay caps at 6 */}\n      <Card hoverable>…</Card>\n    </Reveal>\n  ))}\n</ResponsiveGrid>\n\n// ❌ THE ONE THAT BITES: never put on=\"view\" on something a scroller CLIPS.\n//    <Carousel><CarouselItem><Reveal on=\"view\">…  ← 3 of 4 slides stayed at\n//    opacity 0 FOREVER: the observer's root is the viewport and a clipped box has\n//    an empty intersection rect, so a slide parked outside the rail never enters.\n// ✅ Reveal the RAIL:\n<Reveal on=\"view\">\n  <Carousel>\n    <CarouselContent>\n      {news.map((n) => (\n        <CarouselItem key={n.id} className=\"basis-4/5 sm:basis-1/2 lg:basis-1/3\">\n          <Card hoverable>…</Card>          {/* fractional basis, never basis-[82%] */}\n        </CarouselItem>\n      ))}\n    </CarouselContent>\n  </Carousel>\n</Reveal>\n\n// 6 ── VERIFY BY MEASURING, NOT BY SCREENSHOT. A full-page screenshot does not\n// fire viewport observers, so every scroll reveal photographs as invisible and\n// tells you nothing. Scroll the document, then count:\n//   [...document.querySelectorAll('.ui-reveal')]\n//     .filter(e => e.getAttribute('data-reveal-state') === 'out').length   // must be 0\n//   document.documentElement.scrollWidth - document.documentElement.clientWidth // must be 0\n// Check the hero's computed font-size at 390, and remember ResponsiveGrid steps\n// are CONTAINER widths: inside a 1280 shell with 32px gutters, a 768 tablet hands\n// the grid 704px, so `md` (48rem) never fires there — key that column to `sm`.\n",
+    "name": "brand-theme-block",
+    "tagline": "Wear a WHOLE external brand — its palette, shape, type AND its motion spec — as one scoped theme block of token declarations. No forked components, no page-local overrides of library selectors. Use when you are handed a design system (Figma/HTML prototype/brand book), not a single customer hex.",
+    "tags": [
+      "theme",
+      "brand",
+      "rebrand",
+      "handoff",
+      "motion",
+      "animation",
+      "reveal",
+      "typography",
+      "font",
+      "cjk",
+      "japanese",
+      "tokens",
+      "design-system",
+      "white-label",
+      "marketing",
+      "landing"
+    ]
   }
 ]

package/agent/tokens.json

@@ -4961,6 +4961,12 @@
     "tier": "component",
     "value": "var(--icon-size-md)"
   },
+  {
+    "description": "THE ARROW'S BOX, WHICH IS NOT THE SAME KNOB AS ITS GLYPH (gh#931). `--carousel-arrow-icon-size` sizes the mark INSIDE the button; the button itself was a pair of bare `2rem` literals in data-display-layout.css, so the TARGET had no tier-2 route at all. 32px clears WCAG 2.2 SC 2.5.8 (24px), which is why this is a missing knob and not a defect — but a brand whose own foundations ask for a 44px target could not reach it from a theme, and had no option left except a page-local override of a library selector. Reported from a real re-theme whose spec reads \"arrows44px\". The default is the same 2rem the literals painted, so no existing carousel moves. A theme that wants the larger target writes one line: `--carousel-arrow-size: 2.75rem`.",
+    "name": "--carousel-arrow-size",
+    "tier": "component",
+    "value": "2rem"
+  },
   {
     "description": "WHERE THE ARROWS SIT, AND THE DEFAULT IS THE MIDDLE OF THE CONTENT — NOT OF THE COMPONENT. `.ui-carousel` is the positioning context and it is as tall as the slides PLUS the dots, so a plain `50%` centres the arrows on that sum. Measured on a 98px carousel: slides 58px (middle at -3415), dots 40px, arrows landing at -3395 — exactly half the dots row too low, which is what \"tại sao lại là middle của cả khung thế\" is pointing at. The reserve below subtracts it back. default = the content's middle, at the call site",
     "name": "--carousel-arrow-inset-block-start",
@@ -5879,6 +5885,12 @@
     "tier": "component",
     "value": "var(--space-4)"
   },
+  {
+    "description": "RecordPicker — chiều cao TỐI ĐA của danh sách trong Dialog (gh#932). Một hằng số ở đây là thứ không theme nào với tới: một service dùng hàng dày hơn, hoặc một Dialog cao hơn, cần đổi được con số này mà không phải đè selector của thư viện.",
+    "name": "--record-picker-list-max-block-size",
+    "tier": "component",
+    "value": "22rem"
+  },
   {
     "description": "Data-entry component tokens — small-by-design text knobs (rule #45/#46).",
     "name": "--password-strength-score-font-size",

package/dist/components/data-display/table.d.ts

@@ -166,7 +166,36 @@ export declare const TableBody: React.ForwardRefExoticComponent<React.HTMLAttrib
 type TableRowTone = {
     tone?: TableRowToneProp;
 };
-export declare const TableRow: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLTableRowElement> & TableRowTone & React.RefAttributes<HTMLTableRowElement>>;
+/**
+ * `interactive` — THE ROW IS THE TARGET (gh#929).
+ *
+ * `ListRow` already gives a clickable row all four of the things that make one usable: the whole
+ * row as the hit area, a pointer cursor, a row-level hover, and the design system's focus ring —
+ * because it wraps the `<a>` itself. A `<tr>` cannot be wrapped in an `<a>` and stay a table row,
+ * so every consumer building "a list with COLUMNS whose rows are selectable" fell into the same
+ * hole and patched it with page CSS, which `CONSUMER-RULES` forbids.
+ *
+ * Measured on a consumer (godx-jp/id, `/organization/roles`): the link occupied 160x66 of a
+ * 318x83 row, so the right half of every row was dead; `cursor` computed `auto` on every `<tr>`,
+ * so the hit area that did exist never advertised itself; and a bare `<Link>` in a `TableCell`
+ * fell back to Chromium's default ring (`rgb(0, 95, 204) auto 1px`) instead of the system's
+ * (`1px solid rgb(122, 0, 255)`), because `focus-ring.css` only names a fixed list of classes.
+ *
+ * This prop writes `data-interactive` and the package answers all three in CSS. It does NOT bind a
+ * handler and does NOT make the row focusable: a row is not a control, and the thing a keyboard
+ * user tabs to must still be a real `<a>`/`<button>` inside it — which is exactly what now gets
+ * the system's ring. Pair it with your own `onClick` on the row for the pointer affordance, and
+ * keep the real control in the first cell for the keyboard.
+ */
+type TableRowInteractive = {
+    /**
+     * The whole row acts as one target: pointer cursor, a row-level hover that means "clickable"
+     * rather than merely "hovered", and the design-system focus ring for the real control inside it.
+     * Presentation only — bind the handler yourself and keep a genuine `<a>`/`<button>` in the row.
+     */
+    interactive?: boolean;
+};
+export declare const TableRow: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLTableRowElement> & TableRowTone & TableRowInteractive & React.RefAttributes<HTMLTableRowElement>>;
 /**
  * Column priority carried by BOTH the header cell and the body cells of a column. Read only by
  * `Table preset="action-collection"` below its collapse step, where it selects the column's

package/dist/components/data-display/table.js

@@ -78,11 +78,12 @@ const TableBody = React.forwardRef(({ className, ...props }, ref) => (
   /* @__PURE__ */ jsx("tbody", { ref, "data-slot": "table-body", className: cn(className), ...props })
 ));
 TableBody.displayName = "TableBody";
-const TableRow = React.forwardRef(({ className, tone, ...props }, ref) => /* @__PURE__ */ jsx(
+const TableRow = React.forwardRef(({ className, tone, interactive, ...props }, ref) => /* @__PURE__ */ jsx(
   "tr",
   {
     ref,
     "data-tone": tone,
+    "data-interactive": interactive ? "" : void 0,
     className: cn(
       // The row rule itself is `.ui-table-row` in table-layout.css (--table-row-border-width),
       // NOT a `border-b` utility — a utility sits in `@layer utilities` and would outrank the

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

@@ -22,6 +22,8 @@ export type { FormErrorsProp, FormErrorsProps, FormErrorsProviderProp, FormError
 export { Field } from "./field.js";
 export type { FieldProps } from "./field.js";
 export { SearchInput } from "./search-input.js";
+export { RecordPicker } from "./record-picker.js";
+export type { RecordPickerProp, RecordPickerProps } from "./record-picker.js";
 export { Switch } from "./switch.js";
 export type { SwitchProps } from "./switch.js";
 export { Toggle } from "./toggle.js";

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

@@ -24,6 +24,7 @@ import { FormField } from "./form-field.js";
 import { FormErrors, FormErrorsProvider } from "./form-errors.js";
 import { Field } from "./field.js";
 import { SearchInput } from "./search-input.js";
+import { RecordPicker } from "./record-picker.js";
 import { Switch } from "./switch.js";
 import { Toggle } from "./toggle.js";
 import { ToggleGroup, ToggleGroupItem } from "./toggle-group.js";
@@ -100,6 +101,7 @@ export {
   RadioGroupRoot,
   RadioItem,
   Rating,
+  RecordPicker,
   SHOW_ALL,
   SHOW_CHILD,
   SHOW_PARENT,

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

@@ -0,0 +1,62 @@
+import * as React from "react";
+import type { RecordPickerProp, SearchSelectOptionProp, SelectOptionGroupProp } from "../../props/components/data-entry.prop.js";
+export type { RecordPickerProp, RecordPickerProp as RecordPickerProps };
+/**
+ * RecordPicker — ONE control whose SHAPE follows the size of the set behind it (gh#932).
+ *
+ * The report, from a `/human-tester` session on a consumer: "các select mà có khả năng nhiều dữ
+ * liệu mà hiển thị kiểu dropdown có cả nghìn cái thì làm sao chọn được… dưới X người là dropdown,
+ * trên X người là cho cấu hình search condition trong modal". A dropdown is the right control for
+ * eight people and the wrong one for eight hundred, and today the consumer has to decide that by
+ * hand, per screen — which is why the same concept ("pick a person") shipped three different ways
+ * in one app, including a bare text field where a mistyped key failed with a 422 after save.
+ *
+ * ## Why this is a component and not a composition
+ *
+ * By the Framework-Component Test it passes on every count: three unrelated screens need it, the
+ * behaviour is stateful and keyboard/ARIA-bearing rather than arrangement, and the knob that
+ * matters (`threshold`) is a design decision a service sets once. What it does NOT do is invent
+ * anything: under the threshold it renders `Select` — the same component, same props, same panel —
+ * and over it, the dialog body is `Command` with its own filtering off, which is exactly how
+ * `Select` already drives a server-backed list.
+ *
+ * ## The threshold is counted, not guessed
+ *
+ * `count` is the size of the WHOLE set, which a server knows and a page of results does not. With
+ * `options` it defaults to their length. The default 10 is the owner's own number ("dưới 10 thì
+ * dropdown, trên 10 thì mở modal search"), and a service overrides it once.
+ *
+ * ## Selected values survive a page they are not on
+ *
+ * A picker over ten thousand records will routinely hold a value whose row is not in the current
+ * result page — on first render, there IS no result page. `selectedOptions` is how the consumer
+ * hands over the labels it already has, and it is merged ahead of whatever loads later, so a chip
+ * never renders as a raw id and never disappears when the query changes.
+ */
+export declare const RecordPicker: React.ForwardRefExoticComponent<Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "defaultValue" | "onChange" | "value"> & {
+    mode?: "single" | "multiple";
+    value?: string | string[] | null;
+    defaultValue?: string | string[] | null;
+    onValueChange?: (value: string | string[] | null) => void;
+    options?: (SearchSelectOptionProp | SelectOptionGroupProp)[];
+    loadOptions?: (params: {
+        query: string;
+        filters: Record<string, string>;
+        cursor?: string;
+    }) => Promise<{
+        options: SearchSelectOptionProp[];
+        count?: number;
+        nextCursor?: string;
+    }>;
+    count?: number;
+    threshold?: number;
+    filters?: import("../../props/components/data-entry.prop.js").RecordPickerFilterProp[];
+    selectedOptions?: SearchSelectOptionProp[];
+    emptyOption?: {
+        value: string;
+        label: string;
+    };
+    placeholder?: string;
+    dialogTitle?: string;
+    size?: "xs" | "sm" | "md" | "lg";
+} & React.RefAttributes<HTMLButtonElement>>;

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

@@ -0,0 +1,296 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Check, ChevronDown, X } from "lucide-react";
+import * as React from "react";
+import { useTranslation } from "../../i18n/use-translation.js";
+import { cn } from "../../lib/utils.js";
+import { normalizeSelectOptions } from "../../lib/select-options.js";
+import { Badge } from "../data-display/badge.js";
+import { EmptyState } from "../data-display/empty-state.js";
+import { Button } from "../general/button.js";
+import { Text } from "../general/typography.js";
+import { Flex } from "../layout/flex.js";
+import {
+  Dialog,
+  DialogBody,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle
+} from "../feedback/dialog.js";
+import { Command, CommandGroup } from "./command.js";
+import { Input } from "./input.js";
+import { Select } from "./select.js";
+const RecordPicker = React.forwardRef(
+  function RecordPicker2({
+    mode = "single",
+    value,
+    defaultValue,
+    onValueChange,
+    options,
+    loadOptions,
+    count,
+    threshold = 10,
+    filters,
+    selectedOptions,
+    emptyOption,
+    placeholder,
+    dialogTitle,
+    disabled = false,
+    size,
+    className,
+    ...props
+  }, ref) {
+    const { t } = useTranslation();
+    const isMultiple = mode === "multiple";
+    const controlled = value !== void 0;
+    const [internal, setInternal] = React.useState(
+      () => toArray(defaultValue ?? (isMultiple ? [] : null))
+    );
+    const selected = controlled ? toArray(value) : internal;
+    const commit = React.useCallback(
+      (next) => {
+        if (!controlled) setInternal(next);
+        onValueChange?.(isMultiple ? next : next[0] ?? null);
+      },
+      [controlled, isMultiple, onValueChange]
+    );
+    const staticOptions = React.useMemo(
+      () => options ? normalizeSelectOptions(options) : [],
+      [options]
+    );
+    const total = count ?? (options ? staticOptions.length : void 0);
+    const asDialog = total === void 0 ? Boolean(loadOptions) : total > threshold;
+    if (!asDialog) {
+      return /* @__PURE__ */ jsx(
+        Select,
+        {
+          mode: isMultiple ? "multiple" : void 0,
+          labelInValue: false,
+          showSearch: true,
+          options: withEmptyOption(options, emptyOption),
+          value: isMultiple ? selected : selected[0] ?? void 0,
+          onValueChange: ((next) => commit(toArray(next))),
+          placeholder: placeholder ?? t("dataEntry.recordPicker.placeholder"),
+          disabled,
+          size,
+          className
+        }
+      );
+    }
+    return /* @__PURE__ */ jsx(
+      DialogPicker,
+      {
+        ref,
+        isMultiple,
+        selected,
+        commit,
+        staticOptions,
+        loadOptions,
+        filters,
+        selectedOptions,
+        emptyOption,
+        placeholder,
+        dialogTitle,
+        disabled,
+        size,
+        className,
+        ...props
+      }
+    );
+  }
+);
+function toArray(v) {
+  if (v === null || v === void 0) return [];
+  return Array.isArray(v) ? v : [v];
+}
+function withEmptyOption(options, emptyOption) {
+  if (!emptyOption) return options;
+  return [{ value: emptyOption.value, label: emptyOption.label }, ...options ?? []];
+}
+const DialogPicker = React.forwardRef(function DialogPicker2({
+  isMultiple,
+  selected,
+  commit,
+  staticOptions,
+  loadOptions,
+  filters,
+  selectedOptions,
+  emptyOption,
+  placeholder,
+  dialogTitle,
+  disabled,
+  size,
+  className,
+  ...props
+}, ref) {
+  const { t } = useTranslation();
+  const [open, setOpen] = React.useState(false);
+  const [query, setQuery] = React.useState("");
+  const [filterValues, setFilterValues] = React.useState({});
+  const [rows, setRows] = React.useState(staticOptions);
+  const [status, setStatus] = React.useState("idle");
+  const [draft, setDraft] = React.useState(selected);
+  React.useEffect(() => {
+    if (open) setDraft(selected);
+  }, [open, selected]);
+  const labels = React.useMemo(() => {
+    const map = /* @__PURE__ */ new Map();
+    for (const o of [...selectedOptions ?? [], ...staticOptions, ...rows]) map.set(o.value, o);
+    if (emptyOption) map.set(emptyOption.value, { value: emptyOption.value, label: emptyOption.label });
+    return map;
+  }, [selectedOptions, staticOptions, rows, emptyOption]);
+  const load = React.useCallback(
+    async (q, f) => {
+      if (!loadOptions) return;
+      setStatus("loading");
+      try {
+        const result = await loadOptions({ query: q, filters: f });
+        setRows(result.options);
+        setStatus("idle");
+      } catch {
+        setStatus("error");
+      }
+    },
+    [loadOptions]
+  );
+  React.useEffect(() => {
+    if (!open || !loadOptions) return;
+    const id = setTimeout(() => void load(query, filterValues), 250);
+    return () => clearTimeout(id);
+  }, [open, query, filterValues, load, loadOptions]);
+  const visible = React.useMemo(() => {
+    const base = loadOptions ? rows : staticOptions.filter((o) => o.label.toLowerCase().includes(query.trim().toLowerCase()));
+    return emptyOption && !query.trim() ? [{ value: emptyOption.value, label: emptyOption.label }, ...base] : base;
+  }, [loadOptions, rows, staticOptions, query, emptyOption]);
+  const groups = React.useMemo(() => {
+    const out = /* @__PURE__ */ new Map();
+    for (const o of visible) {
+      const key = o.group ?? "";
+      out.set(key, [...out.get(key) ?? [], o]);
+    }
+    return [...out.entries()];
+  }, [visible]);
+  const toggle = (optionValue) => {
+    if (!isMultiple) {
+      commit([optionValue]);
+      setOpen(false);
+      return;
+    }
+    setDraft(
+      (prev) => prev.includes(optionValue) ? prev.filter((v) => v !== optionValue) : [...prev, optionValue]
+    );
+  };
+  const chips = selected.map((v) => labels.get(v) ?? { value: v, label: v });
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsxs(
+      Button,
+      {
+        ref,
+        type: "button",
+        variant: "outline",
+        size,
+        disabled,
+        "aria-haspopup": "dialog",
+        onClick: () => setOpen(true),
+        className: cn("ui-record-picker-trigger", className),
+        ...props,
+        children: [
+          /* @__PURE__ */ jsx("span", { className: "ui-record-picker-trigger-label", children: chips.length === 0 ? /* @__PURE__ */ jsx(Text, { as: "span", size: "sm", tone: "muted", children: placeholder ?? t("dataEntry.recordPicker.placeholder") }) : /* @__PURE__ */ jsx(Flex, { direction: "row", gap: "xs", wrap: true, align: "center", children: chips.map((c) => /* @__PURE__ */ jsxs(Badge, { variant: "secondary", as: "span", children: [
+            c.icon,
+            c.label
+          ] }, c.value)) }) }),
+          /* @__PURE__ */ jsx(ChevronDown, { "aria-hidden": "true" })
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsx(Dialog, { open, onOpenChange: setOpen, children: /* @__PURE__ */ jsxs(DialogContent, { className: "ui-record-picker-dialog", children: [
+      /* @__PURE__ */ jsx(DialogHeader, { children: /* @__PURE__ */ jsx(DialogTitle, { children: dialogTitle ?? t("dataEntry.recordPicker.dialogTitle") }) }),
+      /* @__PURE__ */ jsx(DialogBody, { children: /* @__PURE__ */ jsxs(Flex, { direction: "col", gap: "md", children: [
+        /* @__PURE__ */ jsx(
+          Input,
+          {
+            autoFocus: true,
+            type: "search",
+            value: query,
+            onChange: (e) => setQuery(e.target.value),
+            "aria-label": t("dataEntry.recordPicker.search"),
+            placeholder: t("dataEntry.recordPicker.searchPlaceholder")
+          }
+        ),
+        filters?.length ? /* @__PURE__ */ jsx(Flex, { direction: "row", gap: "sm", wrap: true, role: "group", "aria-label": t("dataEntry.recordPicker.filters"), children: filters.map((f) => /* @__PURE__ */ jsx(
+          Select,
+          {
+            size: "sm",
+            "aria-label": f.label,
+            placeholder: f.label,
+            value: filterValues[f.name] ?? "",
+            onValueChange: (next) => setFilterValues((prev) => ({ ...prev, [f.name]: next })),
+            options: [
+              { value: "", label: t("dataEntry.recordPicker.allFilter") },
+              ...f.options
+            ]
+          },
+          f.name
+        )) }) : null,
+        /* @__PURE__ */ jsx(Command, { shouldFilter: false, split: isMultiple, className: "ui-record-picker-list", children: status === "error" ? /* @__PURE__ */ jsx(
+          EmptyState,
+          {
+            variant: "compact",
+            tone: "destructive",
+            title: t("dataEntry.recordPicker.error"),
+            action: /* @__PURE__ */ jsx(Button, { variant: "outline", size: "sm", onClick: () => void load(query, filterValues), children: t("dataEntry.recordPicker.more") })
+          }
+        ) : status === "loading" ? /* @__PURE__ */ jsx("div", { role: "status", className: "ui-record-picker-status", children: t("dataEntry.recordPicker.loading") }) : visible.length === 0 ? /* @__PURE__ */ jsx(EmptyState, { variant: "compact", title: t("dataEntry.recordPicker.empty") }) : groups.map(([heading, items]) => {
+          const rendered = items.map((o) => {
+            const picked = (isMultiple ? draft : selected).includes(o.value);
+            return /* @__PURE__ */ jsxs(
+              "button",
+              {
+                type: "button",
+                role: "option",
+                "aria-selected": picked,
+                "data-picked": picked ? "" : void 0,
+                disabled: o.disabled,
+                className: "ui-record-picker-option",
+                onClick: () => toggle(o.value),
+                children: [
+                  /* @__PURE__ */ jsx("span", { className: "ui-record-picker-tick", "aria-hidden": "true", children: picked ? /* @__PURE__ */ jsx(Check, {}) : null }),
+                  o.icon,
+                  /* @__PURE__ */ jsxs("span", { className: "ui-record-picker-option-label", children: [
+                    o.label,
+                    o.sublabel ? /* @__PURE__ */ jsx(Text, { as: "span", size: "2xs", tone: "muted", children: o.sublabel }) : null
+                  ] })
+                ]
+              },
+              o.value
+            );
+          });
+          return heading ? /* @__PURE__ */ jsx(CommandGroup, { heading, children: rendered }, heading) : /* @__PURE__ */ jsx(React.Fragment, { children: rendered }, "__ungrouped");
+        }) })
+      ] }) }),
+      isMultiple ? /* @__PURE__ */ jsxs(DialogFooter, { children: [
+        /* @__PURE__ */ jsx(Text, { as: "span", size: "xs", tone: "muted", className: "me-auto", children: t("dataEntry.recordPicker.selected", { count: draft.length }) }),
+        /* @__PURE__ */ jsxs(Button, { variant: "ghost", size: "sm", onClick: () => setDraft([]), children: [
+          /* @__PURE__ */ jsx(X, { "aria-hidden": "true" }),
+          t("dataEntry.recordPicker.clear")
+        ] }),
+        /* @__PURE__ */ jsx(Button, { variant: "outline", size: "sm", onClick: () => setOpen(false), children: t("dataEntry.recordPicker.cancel") }),
+        /* @__PURE__ */ jsx(
+          Button,
+          {
+            size: "sm",
+            onClick: () => {
+              commit(draft);
+              setOpen(false);
+            },
+            children: t("dataEntry.recordPicker.confirm")
+          }
+        )
+      ] }) : null
+    ] }) })
+  ] });
+});
+export {
+  RecordPicker
+};

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

@@ -20,6 +20,7 @@ export declare const Text: React.ForwardRefExoticComponent<Omit<React.HTMLAttrib
     clamp?: number;
     ellipsis?: boolean | Omit<TypographyEllipsisConfigProp, "rows" | "expandable" | "onExpand">;
     whitespace?: import("../../props/index.js").TextWhitespaceProp;
+    break?: import("../../props/index.js").TextBreakProp;
     tabular?: boolean;
     decoration?: "none" | "underline" | "line-through";
     chip?: boolean;

package/dist/components/general/typography.js

@@ -380,6 +380,8 @@ const TextBase = React.forwardRef((props, ref) => {
     truncate,
     clamp,
     whitespace,
+    // `break` is a reserved word, so it cannot be a binding name.
+    break: breakMode,
     tabular,
     decoration,
     chip,
@@ -424,6 +426,11 @@ const TextBase = React.forwardRef((props, ref) => {
         'Text: `truncate` and `whitespace="pre-wrap"` are mutually exclusive \u2014 `truncate` takes precedence (one line, one ellipsis); use `clamp` to keep preserved line breaks and still bound the height.'
       );
     }
+    if (breakMode === "anywhere" && truncating) {
+      console.warn(
+        'Text: `truncate` and `break="anywhere"` are mutually exclusive \u2014 `truncate` takes precedence (one line has nowhere to break to); use `clamp` to split the token and still bound the height.'
+      );
+    }
     if (ellipsis && (truncate || clamp !== void 0)) {
       console.warn(
         "Text: `ellipsis` (antd) and `truncate`/`clamp` are the same axis \u2014 `ellipsis` takes precedence; drop the other."
@@ -452,6 +459,9 @@ const TextBase = React.forwardRef((props, ref) => {
     // Inert default: `normal` is CSS's own behaviour, so it emits no attribute and there is no
     // `[data-whitespace="normal"]` rule to lose a specificity argument with anything.
     "data-whitespace": whitespace === "pre-wrap" && !truncating ? "pre-wrap" : void 0,
+    // Same shape and the same precedence as `whitespace`: `normal` is inert, and one line has
+    // nowhere to break to, so `truncate` simply does not emit it (gh#927).
+    "data-break": breakMode === "anywhere" && !truncating ? "anywhere" : void 0,
     style: clampStyle,
     "data-tabular": tabular ? "" : void 0,
     "data-decoration": decoration,

package/dist/contracts/measurement.json

@@ -1,6 +1,6 @@
 {
   "$comment": "AUTO-GENERATED by scripts/gen-measurement-contract.mjs — do not edit. Read this instead of guessing: docs/MEASUREMENT-CONTRACT.md.",
-  "version": "30.4.1",
+  "version": "30.5.2",
   "targetSize": {
     "standard": "WCAG 2.2 SC 2.5.8 Target Size (Minimum), level AA — 24×24 CSS px",
     "min": 24,