@godxjp/ui 19.5.0 → 20.0.0

package/docs/WHAT-BELONGS-HERE.md

@@ -0,0 +1,179 @@
+# Cái gì đáng đưa vào @godxjp/ui
+
+Một design system hỏng theo hai hướng ngược nhau, và cả hai đều hỏng thật:
+
+- **Quá hẹp** — thiếu prop, nên consumer buộc phải lách bằng class hoặc mã màu
+  gõ tay. Đây là hướng đang hỏng: một lượt kiểm trên godx-chat (08/09/2026) ra
+  **51 lỗi, 42 trong đó đến từ ĐÚNG MỘT prop còn thiếu** (đệm trên primitive bố
+  cục).
+- **Quá rộng** — nhận mọi yêu cầu, thành một đống prop không ai nhớ, và mỗi
+  prop là một mảnh DOM nội bộ bị đóng băng thành API công khai.
+
+Tài liệu này là bộ lọc giữa hai hướng đó. Nó cố tình viết thành câu hỏi **trả
+lời được bằng có/không**, không phải nguyên tắc để cảm nhận.
+
+---
+
+## Ba câu hỏi — phải ĐỦ CẢ BA
+
+### 1. Có phải consumer KHÔNG CÓ nước đi hợp lệ nào không?
+
+Không phải "bất tiện". Là **bất khả**: mọi prop và token đang có đều không nói
+được điều cần nói, và mọi đường còn lại đều bị `ui-audit` chặn.
+
+- ✅ Thiết kế cần 12px giữa hai phần tử trên một HÀNG. Thang bậc tên đọc trục
+  dọc nên `md` = 16px; làm tròn thì lệch bố cục; viết `gap: 12px` thì
+  `no-arbitrary-spacing` chặn. **Không có nước đi.** → gh#401, đã vá.
+- ❌ "Viết `<Flex gap={3}>` dài hơn `gap-3`." Có nước đi, chỉ là dài hơn.
+
+Cách kiểm: viết ra đoạn mã bạn _muốn_ viết, chạy `ui-audit` lên nó. Nếu nó
+xanh, bạn đã có nước đi.
+
+### 2. Nó thuộc về HÌNH DẠNG của component, hay thuộc về NỘI DUNG của một màn?
+
+Design system sở hữu hình dạng. Màn hình sở hữu nội dung.
+
+- ✅ `Flex` không có đệm. Mọi hàng/cột trong mọi ứng dụng đều có thể cần đệm.
+- ✅ `TableHead` không có trục căn lề. Mọi bảng có cột số đều cần.
+- ❌ "Bảng quản trị thành viên cần cột vai trò rộng 8rem." Đó là màn hình ấy.
+- ❌ "Dashboard cần bốn thẻ chỉ số xếp ngang." Đó là bố cục của một trang.
+
+Câu hỏi phụ khi phân vân: **consumer thứ hai có gặp không?** Nếu câu trả lời là
+"chắc là không" thì gần như luôn là nội dung, không phải hình dạng.
+
+### 3. Diễn đạt được thành một TRỤC CÓ TÊN không?
+
+Một prop phải gọi được **ý định**, không chỉ mở một lỗ.
+
+- ✅ `pad={{ blockStart: 3 }}` — trục logic, bậc thang, đọc ra nghĩa.
+- ❌ `styles={{ body: {...}, header: {...} }}` — không phải một trục; nó là một
+  lỗ tự do, và nó đóng băng tên khe DOM nội bộ thành API công khai. Xem mục
+  "Không đáng" bên dưới.
+
+---
+
+## Bốn dấu hiệu MẠNH — một cái là đủ để ưu tiên làm ngay
+
+Ba câu trên quyết định _có thuộc về đây không_. Bốn dấu hiệu này quyết định
+_làm trước hay sau_.
+
+### a. Nó chặn một yêu cầu TIẾP CẬN
+
+Không thương lượng, làm trước.
+Ví dụ đã gặp: vòng tiêu điểm của Input là 1px (hạ xuống có chủ ý), không
+đạt WCAG 2.4.11 vốn đòi vùng chỉ báo tương đương đường 2px. Và `FormRoot` không
+có móc `onInvalid`, nên không đưa được tiêu điểm về trường lỗi đầu tiên — WCAG
+3.3.1 / 2.4.3.
+
+### b. Nó hỏng IM LẶNG
+
+Không lỗi biên dịch, không test đỏ, không cảnh báo — chỉ sai.
+Ví dụ đã gặp: `AppShell` nhận cả `logo` lẫn `topbar` nhưng `resolvedTopbar` trả
+thẳng `topbar`, nên `logo` **không bao giờ được vẽ**. godx-chat truyền cả hai
+suốt nhiều tháng và không ai phát hiện.
+
+Lớp lỗi này đắt gấp nhiều lần lớp lỗi ồn ào, vì nó không có ai báo.
+
+### c. Đếm được
+
+Một khoảng trống đẻ ra N lỗi audit là một khoảng trống có số đo, không phải một
+ý kiến. 42 lỗi từ một prop thiếu là một ưu tiên; một lỗi từ một prop thiếu thì
+chưa chắc.
+
+### d. Nó BẤT ĐỐI XỨNG với thứ đã có
+
+Nếu trục dọc có `xl` mà trục ngang không có, khoảng trống ấy gần như luôn là
+**quên**, không phải quyết định. Sửa cho cân là rẻ và không tranh cãi.
+
+---
+
+## Cái KHÔNG đáng vào — và vì sao
+
+**Bố cục của một màn hình cụ thể.** Nó thuộc về màn hình đó. Nếu ba màn cùng
+cần, lúc ấy nó đã thành hình dạng và quay lại câu hỏi 2.
+
+**Một giá trị dùng đúng một lần.** Đừng đẻ prop cho nó — dùng cửa thoát
+(`gapRaw`, `padRaw`). Cửa thoát để lại `data-*-raw` trên DOM nên đếm được; khi
+số đếm ấy lớn lên, ĐÓ mới là lúc nó thành một trục đáng có tên.
+
+**Lỗ kiểu dáng tự do** (`styles={{ slot }}`, `classNames={{ slot }}`). Nó đóng
+băng cấu trúc DOM nội bộ thành API công khai, và audit **không đếm được** nó
+(một object style dựng ở đâu cũng được rồi spread vào). Nó cũng ngược hẳn với
+`style: 0/289` — lập trường nhất quán hiện nay là cho prop ý định, không cho lỗ
+kiểu dáng.
+
+**Gu thẩm mỹ.** "Dùng nhiều khoảng trắng", "hai màu nhấn là đủ", "tránh lưới
+bento". Không kiểm chứng được, không cổng nào canh, và khi nó tới tay agent
+TRƯỚC luật cứng thì kết quả là mã đẹp mà sai hợp đồng.
+
+**Thứ chỉ tiết kiệm vài dòng ở call site.** Nếu đường hiện tại đã hợp lệ và
+đọc được, việc rút ngắn nó không phải việc của design system.
+
+---
+
+## Thêm rồi thì NỢ gì
+
+Một prop mới chưa xong khi nó biên dịch được. Ba việc bắt buộc, và cả ba đều đã
+có cổng CI:
+
+1. **Vào catalog.** Chạy `node scripts/gen-component-api-manifest.mjs`.
+   `check:component-api-manifest` canh việc này. **Không vào catalog thì agent
+   không biết nó tồn tại** — và đó không phải giả thuyết: `pad`/`padRaw` được
+   thêm vào gói nhưng catalog phát hành chưa có, nên một agent tra MCP đúng quy
+   trình vẫn kết luận "Flex chỉ có gap" và bỏ cuộc trước 21 lỗi mà nó có thể
+   sửa.
+
+2. **Có bằng chứng phủ từng nhánh giá trị.** `component-case-evidence.json` +
+   `check:frame-coverage-ledger`. Bằng chứng phải trỏ vào test THẬT SỰ chạy qua
+   nhánh ấy, không phải một tệp cho có.
+
+3. **Có ví dụ BIÊN DỊCH ĐƯỢC.** Hậu quả đo được khi không kiểm: pattern
+   `confirm-destructive` truyền cho `Dialog` một prop `mode` không tồn tại,
+   hướng dẫn DataTable dùng `variant="success"` (chính thứ luật
+   `status-tone-not-variant` cấm), và ví dụ `Input` gọi một prop
+   `onValueChange` không có thật. Agent chép chúng và viết ra mã hỏng.
+
+   Ba chỗ ấy đã sửa, và `check:doc-prop-existence` nay bắt được lớp lỗi đó.
+   Lưu ý khi viết tài liệu: cổng ấy đọc mọi đoạn JSX trong `docs/**` như mã
+   THẬT, nên **trích dẫn một API sai để làm ví dụ cũng bị bắt**. Mô tả bằng lời
+   như đoạn trên, đừng dán một thẻ JSX hoàn chỉnh vào.
+
+---
+
+## Một lợi ích ẩn của việc rời Radix, đo được
+
+`check:doc-prop-existence` canh chiều "mọi prop dùng trong ví dụ đều phải tồn
+tại" — chính lớp lỗi khiến agent chép ví dụ rồi viết ra mã hỏng (prop `mode`
+trên `Dialog`, prop `onValueChange` trên `Input`). Nhưng nó **bỏ qua mọi
+component bọc primitive bên thứ ba**, vì với chúng manifest chỉ là cận dưới:
+prop thật nằm trong types của Radix, generator không mở ra được.
+
+Số đo (08/09/2026):
+
+|                                               | component KHÔNG kiểm được |
+| --------------------------------------------- | ------------------------- |
+| `main`                                        | **139 / 289**             |
+| `feat/v20-react-aria` (6 primitive đã chuyển) | **126 / 289**             |
+
+Mỗi primitive rời Radix là `declaredIn` chuyển từ `node_modules` vào `src/`, và
+component đó **bước vào vùng kiểm được**. Sáu primitive đầu đã gỡ rào cho 13
+component.
+
+Nên đợt đổi nền không chỉ là thay thư viện. Nó là cách duy nhất làm cho 126
+component còn lại có thể được canh — và trong số đó có `Dialog`, `Input`,
+`Badge`, tức đúng những component mà ví dụ sai đã lọt qua.
+
+## Khi câu trả lời là "không thuộc về đây"
+
+Nói ra ở chỗ gặp nó, bằng mã:
+
+```tsx
+/*
+ * KHÔNG thuộc về design system: bề rộng này là số đo của riêng màn hình
+ * quản trị thành viên, không phải một trục của Table. Nếu màn thứ hai cần
+ * cùng thứ, lúc đó mở issue.
+ */
+```
+
+Một dòng như thế đáng giá hơn một issue mở rồi bỏ đấy — nó nói cho người sau
+biết ai đã cân nhắc, và cân nhắc ra sao.

package/docs/data-display/legend.tsx

@@ -0,0 +1,145 @@
+import {
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Legend,
+  Progress,
+} from "@godxjp/ui/data-display";
+import { Text } from "@godxjp/ui/general";
+import { Flex, PageContainer } from "@godxjp/ui/layout";
+
+const COMPLIANCE = [
+  { name: "株式会社山田製作所", over: 2, near: 3, done: 12 },
+  { name: "佐藤食品株式会社", over: 1, near: 2, done: 9 },
+  { name: "東海精密工業株式会社", over: 0, near: 3, done: 21 },
+];
+
+const STATUS_KEYS = [
+  { tone: "destructive", label: "期限超過" },
+  { tone: "warning", label: "期限間近" },
+  { tone: "success", label: "対応済" },
+] as const;
+
+/**
+ * Legend — the KEY for a colour-coded surface: which tone means what, in words, once.
+ * Composed only from real @godxjp/ui components.
+ */
+export default function Demo() {
+  return (
+    <PageContainer title="Legend" subtitle="tone → 意味 のキー · 凡例">
+      <Flex direction="col" gap="lg">
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Progress の breakdown と組む</CardTitle>
+            <CardDescription>
+              CardAction に置くと、カード見出しと同じ行に凡例が並びます。色の意味をカードで
+              一度だけ言い、各行では繰り返しません。
+            </CardDescription>
+            <CardAction>
+              <Legend items={[...STATUS_KEYS]} />
+            </CardAction>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gapRaw={11}>
+              {COMPLIANCE.map((row) => (
+                <Flex key={row.name} align="center" gapRaw={14}>
+                  <Flex width={180}>
+                    <Text weight="medium" truncate>
+                      {row.name}
+                    </Text>
+                  </Flex>
+                  <Flex fill direction="col">
+                    <Progress
+                      segments={[
+                        { value: row.over, tone: "destructive", label: "期限超過" },
+                        { value: row.near, tone: "warning", label: "期限間近" },
+                        { value: row.done, tone: "success", label: "対応済" },
+                      ]}
+                      aria-label={row.name}
+                    />
+                  </Flex>
+                  <Flex width={150} justify="end" align="center" gapRaw={12}>
+                    <Text tone="destructive" weight="semibold" tabular>
+                      {row.over}
+                    </Text>
+                    <Text tone="warning" weight="semibold" tabular>
+                      {row.near}
+                    </Text>
+                    <Text tone="success" weight="semibold" tabular>
+                      {row.done}
+                    </Text>
+                    <Text tone="muted" tabular>
+                      計 {row.over + row.near + row.done}
+                    </Text>
+                  </Flex>
+                </Flex>
+              ))}
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Tones</CardTitle>
+            <CardDescription>
+              vocabulary の 7 tone すべてに塗りがあります。色だけで意味を運ばないため label
+              は必須です（WCAG 1.4.1）。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Legend
+              items={[
+                { tone: "default", label: "既定（primary）" },
+                { tone: "success", label: "成功" },
+                { tone: "warning", label: "注意" },
+                { tone: "destructive", label: "危険" },
+                { tone: "info", label: "情報" },
+                { tone: "muted", label: "控えめ" },
+                { tone: "neutral", label: "中立" },
+              ]}
+            />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Named legend</CardTitle>
+            <CardDescription>
+              aria-label を渡すと、その凡例が「何のキーか」を読み上げます。項目は list /
+              listitem として並びます。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Legend items={[...STATUS_KEYS]} aria-label="コンプライアンス状況の凡例" />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Wrapping</CardTitle>
+            <CardDescription>
+              狭い幅では折り返します（横スクロールしません）。凡例が視界の外に出ると、色の意味
+              そのものが失われるためです。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex width={240}>
+              <Legend
+                items={[
+                  { tone: "destructive", label: "期限超過" },
+                  { tone: "warning", label: "期限間近" },
+                  { tone: "success", label: "対応済" },
+                  { tone: "info", label: "確認中" },
+                  { tone: "muted", label: "対象外" },
+                ]}
+              />
+            </Flex>
+          </CardContent>
+        </Card>
+      </Flex>
+    </PageContainer>
+  );
+}

package/docs/data-display/progress.tsx

@@ -33,6 +33,38 @@ export default function Demo() {
           </CardContent>
         </Card>
 
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Breakdown（segments）</CardTitle>
+            <CardDescription>
+              1 つの合計を状態ごとに分割します。割合ではなく実数を渡すと、各スライスの比率は
+              コンポーネントが計算します。メーターより背の高いトラックになるのは、0.5rem の pill
+              上に 3 色を並べると比率が読めなくなるためです。role=&quot;img&quot;
+              として、全スライスを 1 つの名前で読み上げます。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <Progress
+                segments={[
+                  { value: 2, tone: "destructive", label: "期限超過" },
+                  { value: 3, tone: "warning", label: "期限間近" },
+                  { value: 12, tone: "success", label: "対応済" },
+                ]}
+                label="株式会社山田製作所"
+              />
+              <Progress
+                segments={[
+                  { value: 0, tone: "destructive", label: "期限超過" },
+                  { value: 1, tone: "warning", label: "期限間近" },
+                  { value: 6, tone: "success", label: "対応済" },
+                ]}
+                label="みどり農産株式会社（0 件のスライスは幅 0）"
+              />
+            </Flex>
+          </CardContent>
+        </Card>
+
         <Card>
           <CardHeader>
             <CardTitle level={2}>Over capacity</CardTitle>

package/docs/data-entry/segmented.tsx

@@ -7,7 +7,7 @@ import { Flex, PageContainer } from "@godxjp/ui/layout";
 import { CalendarDays, Columns3, LayoutList, Monitor, Moon, Sun } from "lucide-react";
 
 /**
- * Segmented — one-of-N from a small, closed, always-visible set. antd's Segmented drawn on Radix
+ * Segmented — one-of-N from a small, closed, always-visible set. The enterprise Segmented drawn on Radix
  * RadioGroup: a recessed track with the chosen item as a lifted slab, radiogroup semantics, arrow
  * keys between members. The track measures exactly --control-height, so it sits level with an
  * Input or a Button on the same row.

package/docs/data-entry/select.tsx

@@ -286,8 +286,8 @@ export default function Demo() {
           <CardHeader>
             <CardTitle level={2}>labelRender · custom selected display</CardTitle>
             <CardDescription>
-              `labelRender` (Ant Design) customizes the SELECTED value shown on the trigger: here an
-              avatar + name + a role badge. The placeholder still shows when nothing is selected.
+              `labelRender` customizes the SELECTED value shown on the trigger: here an avatar +
+              name + a role badge. The placeholder still shows when nothing is selected.
             </CardDescription>
           </CardHeader>
           <CardContent>

package/docs/feedback/sheet.tsx

@@ -47,7 +47,7 @@ const headerTones = [
  * Sheet > SheetTrigger (asChild) > SheetContent(side) > SheetHeader >
  * SheetTitle (a11y required) > scrollable body > SheetFooter.
  *
- * SheetFooter is an Ant-Design-style PINNED action bar: it sticks to the bottom
+ * SheetFooter is a PINNED action bar: it sticks to the bottom
  * via mt-auto, draws a full-bleed top border, and right-aligns its actions with
  * the PRIMARY button rightmost. A destructive / clear / reset action goes
  * far-LEFT · give THAT button className="me-auto". Never stack footer buttons

package/docs/general/typography.tsx

@@ -1,5 +1,17 @@
 import { Button, Heading, Text } from "@godxjp/ui/general";
-import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "@godxjp/ui/data-display";
 import { Flex, PageContainer } from "@godxjp/ui/layout";
 
 /**
@@ -146,6 +158,77 @@ export default function Demo() {
             </Flex>
           </CardContent>
         </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Links in running content</CardTitle>
+            <CardDescription>
+              link は色ではなく「これはリンクである」という手がかりです。ホバーだけでなく
+              キーボードフォーカスでも下線が出るため、hover: だけのユーティリティでは
+              届かない利用者にも伝わります。色は tone のままなので、tone=&quot;destructive&quot;
+              のリンクは destructive のまま下線を引きます。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <Flex direction="row" gap="md" wrap align="center">
+                <Text as="a" href="#typography" link>
+                  既定 · tone は primary
+                </Text>
+                <Text as="a" href="#typography" link tone="destructive">
+                  取り消す
+                </Text>
+                <Text as="a" href="#typography" link size="xs" tone="muted">
+                  すべての通知を見る
+                </Text>
+              </Flex>
+
+              {/* The case Button variant="link" cannot serve. `.ui-button` is a control box —
+               * white-space: nowrap, flex-shrink: 0, a --control-height tier and inline padding —
+               * so in a cell it neither wraps to a second line nor shares the row's line box.
+               * `<Text link>` is text, so it does both. */}
+              <Table>
+                <TableHeader>
+                  <TableRow>
+                    <TableHead>キー</TableHead>
+                    <TableHead>件名</TableHead>
+                  </TableRow>
+                </TableHeader>
+                <TableBody>
+                  <TableRow>
+                    <TableCell>
+                      <Text size="xs" mono tone="muted">
+                        PKG-128
+                      </Text>
+                    </TableCell>
+                    <TableCell>
+                      <Text as="a" href="#typography" link>
+                        ログイン画面の余白が狭く、パスワード再設定リンクが本文と重なって見える
+                      </Text>
+                    </TableCell>
+                  </TableRow>
+                  <TableRow>
+                    <TableCell>
+                      <Text size="xs" mono tone="muted">
+                        PKG-129
+                      </Text>
+                    </TableCell>
+                    <TableCell>
+                      <Text as="a" href="#typography" link>
+                        請求書PDFの明細行
+                      </Text>
+                    </TableCell>
+                  </TableRow>
+                </TableBody>
+              </Table>
+
+              <Text size="xs" tone="muted">
+                アクション（送信・展開）にはリンク風の Button variant=&quot;link&quot;
+                を使います。本文の中のリンクは Text link です。
+              </Text>
+            </Flex>
+          </CardContent>
+        </Card>
       </Flex>
     </PageContainer>
   );