@godxjp/ui 28.12.0 → 29.0.0

package/docs/showcase/case4-login.tsx

@@ -129,8 +129,8 @@ export default function LoginShowcase() {
       /* Page-level controls, pinned to the banner's inline end. */
       actions={
         <>
-          <Select value={locale} onValueChange={setLocale}>
-            <SelectTrigger size="sm" className="w-32" aria-label="言語を選択">
+          <Select aria-label="言語を選択" value={locale} onValueChange={setLocale}>
+            <SelectTrigger size="sm" className="w-32">
               <Languages aria-hidden="true" className="text-muted-foreground" />
               <SelectValue />
             </SelectTrigger>

package/docs/showcase/marketing-page.tsx

@@ -112,8 +112,9 @@
  * elements cross the inline edge. The two boxes that do scroll are the `Marquee` viewport and the
  * `Carousel` viewport, which is what both components are.
  *
- * Every string and every `aria-label` comes from `t()` (`src/i18n/messages/{en,ja,vi}.json`,
- * namespace `marketingShowcase`), and the locale picker in the bar switches all three live. Money
+ * Every string and every `aria-label` comes from `t()` (`docs/i18n/messages/{en,ja,vi}.json`,
+ * namespace `marketingShowcase` — demo copy the preview registers at startup, never shipped to a
+ * consumer; gh#858), and the locale picker in the bar switches all three live. Money
  * is `Intl.NumberFormat` with the ACTIVE locale and an ISO 4217 code that lives in data, never a
  * symbol in the copy. The year is `Intl.DateTimeFormat`. Domains are RFC 2606 reserved
  * (`*.example.jp`), the company is fictional, and every wordmark in the logo wall is invented.

package/docs/showcase/permission-matrix.tsx

@@ -137,7 +137,10 @@ function GrantCell({ granted }: { granted: boolean }) {
 }
 
 // 固定列（先頭 = 権限）— スクロールする本体が下を通るので不透明背景 + トークン端。
-const PIN_START = "sticky start-0 z-20 bg-inherit border-e border-border";
+// `.ui-permission-matrix-pin` is the packaged component's own class (gh#874 fixed its opaque
+// base + tone/hover/selected compositing in `data-display-layout.css`) — reused here rather than
+// hand-rolled so this showcase gets the identical answer instead of drifting from it again.
+const PIN_START = "ui-permission-matrix-pin";
 
 export default function Demo() {
   const [compareA, setCompareA] = React.useState("editor");
@@ -225,11 +228,11 @@ export default function Demo() {
             </CardAction>
           </CardHeader>
           <CardContent flush>
-            <div className="overflow-x-auto">
+            <div className="ui-permission-matrix overflow-x-auto">
               <Table className="min-w-[760px]">
                 <TableHeader className="bg-secondary [&_tr]:bg-secondary">
                   <TableRow className="bg-secondary hover:bg-secondary">
-                    <TableHead className={cn(PIN_START, "w-64 min-w-64")}>権限</TableHead>
+                    <TableHead className={PIN_START}>権限</TableHead>
                     {ROLES.map((role) => {
                       const isCompared = !sameRole && compared.has(role.id);
                       return (
@@ -263,10 +266,15 @@ export default function Demo() {
                     return (
                       <TableRow
                         key={perm.id}
-                        className={cn(isDiffRow && "bg-warning/[0.07] hover:bg-warning/10")}
+                        // Same hand-off the PermissionMatrix component uses (gh#872): the wash,
+                        // the leading rail and the hover step belong to `styles/table-layout.css`,
+                        // which reads `--surface-warning` first — so this hand-composed table is
+                        // re-groundable by a tenant theme exactly like the packaged one. A local
+                        // `bg-warning/[0.07]` here would be a second, private warning surface.
+                        data-tone={isDiffRow ? "warning" : undefined}
                         aria-label={isDiffRow ? `${perm.name} · 比較ロール間で差分あり` : undefined}
                       >
-                        <TableCell className={cn(PIN_START, "w-64 min-w-64 align-middle")}>
+                        <TableCell className={cn(PIN_START, "align-middle")}>
                           <Flex direction="col" className="leading-tight">
                             <Flex align="center" gap="xs">
                               <Text weight="medium">{perm.name}</Text>

package/docs/showcase/table-pagination.tsx

@@ -312,13 +312,14 @@ function CursorPeriodCard() {
         <CardTitle level={2}>カーソル / 期間ジャンプ</CardTitle>
         <CardAction>
           <Select
+            aria-label="期間を選択"
             value={period}
             onValueChange={(v: string) => {
               setPeriod(v);
               setCursor(undefined); // jumping period resets the cursor to the first page
             }}
           >
-            <SelectTrigger size="sm" aria-label="期間を選択" className="w-36">
+            <SelectTrigger size="sm" className="w-36">
               <SelectValue />
             </SelectTrigger>
             <SelectContent>

package/docs/showcase/tenant-brand-color.tsx

@@ -0,0 +1,338 @@
+/**
+ * Showcase · tenant-brand-color — "Màu thương hiệu của KHÁCH, ở một vùng, lúc chạy" (gh#861, gh#868).
+ *
+ * ── Gate 0 verdict: COMPOSITION PATTERN ──────────────────────────────────────────────────────
+ * Hai kho tiêu thụ xin một `<TenantTheme primary={hex}>`. Chạy Framework-Component Test
+ * (docs/COMPOSITION-VS-COMPONENT.md §3.2) thì nó TRƯỢT: bọc `<div>` không giữ state, không bàn
+ * phím, không focus, không ARIA (C2); nó đúng là "token override theo scope" mà chính doctrine
+ * chỉ định làm composition (C3); API `primary`/`secondary`/`tenant` không map vào
+ * `value`/`onValueChange`/`size` nào (C4); và nó không render chữ nào để `t()` hay APG nói về
+ * (C6). Thứ hai consumer thật sự chép tay là PHÉP TÍNH — hex → triplet HSL, và quy tắc tương phản
+ * chọn màu chữ. Phép tính ấy ship trong gói (`tenantTheme`, `@godxjp/ui/app`); cái `<div>` ở lại
+ * trang này. Không component mới, không token mới.
+ *
+ * ── Trang này chứng minh bốn thứ, mỗi thứ đo được trên màn hình ──────────────────────────────
+ *   1. PHẠM VI. Cùng một hàng component, một bản TRONG vùng `[data-tenant]` và một bản NGOÀI.
+ *      Chỉ bản trong đổi màu. Không đụng `<html>`, không stylesheet thứ hai.
+ *   2. CẶP MÀU. `--primary` không đi một mình: `--primary-foreground` đi kèm, chọn bằng tương
+ *      phản WCAG 2.2 SC 1.4.3 (4.5:1), và tỷ số đạt được HIỆN trên màn hình chứ không giấu.
+ *   3. HOVER / ACTIVE KHÔNG IM LẶNG. `tenantTheme` phát hai bước ấy thành TRIPLET THẬT, không
+ *      phải `initial` + relative colour, nên màu khách áp ở mọi trạng thái trên mọi engine —
+ *      không cần `CSS.supports("color", "hsl(from red h s l)")` như bản tự chế của một kho tiêu thụ.
+ *   4. CA ĐÃ CHẠY, KHÔNG PHẢI HAPPY PATH. Bốn hàng cuối là hex không hợp lệ (vùng trở về theme
+ *      của app, trang không vỡ), một cặp do máy chủ cấp KHÔNG đạt AA (API nói KHÔNG, kèm số), và
+ *      hai màu khách hay chọn nhất mà quy tắc ngây thơ "luôn chữ trắng" sẽ hỏng.
+ *
+ * ── Điều trang này CỐ TÌNH không làm ─────────────────────────────────────────────────────────
+ * Không đụng `--text-link` / `--text-brand` / `--text-primary`. Đó là MỰC trên nền trang, không
+ * phải nhãn trên nền nút: độ đọc của nó phụ thuộc `--background` — thứ màu của khách không quyết
+ * định — và hướng bước là theo THEME chứ không theo nhãn. Một seed nhạt (#FFD400) cho link 1.4:1
+ * trên nền trắng. Xem hàng "mực thương hiệu" trong bảng.
+ */
+import * as React from "react";
+
+import { AA_NORMAL_TEXT, tenantTheme } from "@godxjp/ui/app";
+import { Button, Text } from "@godxjp/ui/general";
+import { Flex, PageContainer, ResponsiveGrid } from "@godxjp/ui/layout";
+import {
+  Badge,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  CodeBlock,
+  DataTable,
+  Progress,
+  Swatch,
+  type ColumnDef,
+} from "@godxjp/ui/data-display";
+import { ColorPicker, FormField, Input, Switch } from "@godxjp/ui/data-entry";
+import { Callout } from "@godxjp/ui/feedback";
+
+/** Màu thật của khách — hai đầu mút là chỗ quy tắc "luôn chữ trắng" hỏng. */
+const CUSTOMERS = [
+  { hex: "#0071bd", name: "Biển Đông Logistics" },
+  { hex: "#FFD400", name: "Vàng Mặt Trời" },
+  { hex: "#0A1F44", name: "Hàng hải Bắc Hà" },
+  { hex: "#00A86B", name: "Ngọc Bích Foods" },
+  { hex: "#E30613", name: "Đỏ Sao Vàng" },
+  { hex: "#767676", name: "Xám Trung Tính" },
+] as const;
+
+type Row = {
+  hex: string;
+  name: string;
+  foreground: string;
+  ratio: string;
+  meetsAA: boolean;
+};
+
+const columns: ColumnDef<Row>[] = [
+  {
+    key: "hex",
+    header: "Màu khách",
+    render: (r) => (
+      <Flex align="center" gap="sm">
+        <Swatch color={r.hex} aria-label={`Màu chính của ${r.name}: ${r.hex}`} />
+        <Text as="span" size="xs" mono>
+          {r.hex}
+        </Text>
+      </Flex>
+    ),
+  },
+  { key: "name", header: "Khách", hiddenOnMobile: true },
+  {
+    key: "foreground",
+    header: "Màu chữ đã chọn",
+    render: (r) => (
+      <Flex align="center" gap="sm">
+        <Swatch color={r.foreground} aria-label={`Màu chữ an toàn: ${r.foreground}`} />
+        <Text as="span" size="xs" mono>
+          {r.foreground}
+        </Text>
+      </Flex>
+    ),
+  },
+  {
+    key: "ratio",
+    header: "Tương phản",
+    align: "right",
+    render: (r) => <Text tabular>{r.ratio}:1</Text>,
+  },
+  {
+    key: "meetsAA",
+    header: "WCAG 2.2 AA",
+    align: "center",
+    render: (r) => (
+      <Badge tone={r.meetsAA ? "success" : "destructive"}>{r.meetsAA ? "Đạt" : "Không đạt"}</Badge>
+    ),
+  },
+];
+
+/**
+ * Một hàng component THẬT đọc `--primary`. Dùng hai lần trên trang: một lần trong vùng khách,
+ * một lần ngoài — cùng markup, khác đúng một `style` của thẻ cha.
+ */
+function BrandedRow({ idPrefix }: { idPrefix: string }) {
+  return (
+    <Flex direction="col" gap="md">
+      <Flex direction="row" gap="sm" wrap align="center">
+        <Button type="button">Mở ứng dụng</Button>
+        <Button type="button" variant="outline">
+          Chi tiết
+        </Button>
+        <Badge tone="info">12 dịch vụ</Badge>
+        <Switch id={`${idPrefix}-switch`} defaultChecked aria-label="Bật thông báo" />
+      </Flex>
+      <FormField id={`${idPrefix}-input`} label="Mã tra cứu" helper="Bấm vào ô để thấy vòng focus">
+        <Input id={`${idPrefix}-input`} defaultValue="GDX-1042" />
+      </FormField>
+      <Progress value={62} label="Hạn mức đã dùng" />
+    </Flex>
+  );
+}
+
+export default function Demo() {
+  const [hex, setHex] = React.useState("#0071bd");
+  const [serverForeground, setServerForeground] = React.useState(false);
+
+  // Cặp do máy chủ cấp — Platform lưu sẵn ở `brands.theme_tokens`. #3b82f6 trên #0071bd chỉ đạt
+  // 2.02:1: một cặp THẬT có thể sai, và API phải nói ra chứ không lặng lẽ trả về trắng.
+  const seed = tenantTheme(hex, { foreground: serverForeground ? "#3b82f6" : null });
+  const invalid = tenantTheme("#nope00");
+
+  const rows: Row[] = CUSTOMERS.map((customer) => {
+    const computed = tenantTheme(customer.hex);
+    return {
+      hex: customer.hex,
+      name: customer.name,
+      foreground: computed.foreground ?? "—",
+      ratio: computed.contrast.toFixed(2),
+      meetsAA: computed.meetsAA,
+    };
+  });
+
+  const declarations = Object.entries(seed.vars)
+    .map(([name, value]) => `  ${name}: ${value};`)
+    .join("\n");
+
+  return (
+    <PageContainer
+      title="Màu thương hiệu của khách · một vùng, lúc chạy"
+      subtitle="tenantTheme(hex) → khai báo token cho MỘT vùng. Cặp màu chữ chọn bằng WCAG 2.2 SC 1.4.3; hover/pressed là triplet thật nên không im lặng trên engine thiếu relative colour."
+    >
+      <Flex direction="col" gap="lg">
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Màu khách chọn</CardTitle>
+            <CardDescription>
+              Hex — đúng thứ `ColorPicker` trả về và đúng thứ mọi kho tiêu thụ lưu. Ba hoặc sáu chữ
+              số; giá trị hỏng bị bỏ qua chứ không làm vỡ trang.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <FormField id="tenant-hex" label="Màu chính của khách">
+                <ColorPicker id="tenant-hex" value={hex} onValueChange={setHex} />
+              </FormField>
+              <Flex direction="row" gap="sm" wrap>
+                {CUSTOMERS.map((customer) => (
+                  <Button
+                    key={customer.hex}
+                    type="button"
+                    variant="outline"
+                    size="sm"
+                    onClick={() => setHex(customer.hex)}
+                  >
+                    {customer.name}
+                  </Button>
+                ))}
+              </Flex>
+              <Flex direction="row" gap="md" align="center" wrap>
+                <Swatch color={seed.primary ?? "#ffffff"} aria-label={`Màu nền: ${seed.primary}`} />
+                <Swatch
+                  color={seed.foreground ?? "#000000"}
+                  aria-label={`Màu chữ: ${seed.foreground}`}
+                />
+                <Text as="span" size="sm">
+                  Tương phản đo được{" "}
+                  <Text as="strong" weight="medium" tabular>
+                    {seed.contrast.toFixed(2)}:1
+                  </Text>{" "}
+                  (ngưỡng AA {AA_NORMAL_TEXT}:1)
+                </Text>
+                <Badge tone={seed.meetsAA ? "success" : "destructive"}>
+                  {seed.meetsAA ? "Đạt WCAG 2.2 AA" : "KHÔNG đạt WCAG 2.2 AA"}
+                </Badge>
+              </Flex>
+              <Flex direction="row" gap="sm" align="center">
+                <Switch
+                  id="server-foreground"
+                  checked={serverForeground}
+                  onCheckedChange={setServerForeground}
+                />
+                <Text as="label" size="sm" htmlFor="server-foreground">
+                  Dùng cặp do máy chủ cấp (#3b82f6) — một cặp THẬT nhưng dưới ngưỡng
+                </Text>
+              </Flex>
+              {!seed.meetsAA ? (
+                <Callout kind="warning">
+                  <Callout.Title>API nói KHÔNG, kèm số</Callout.Title>
+                  <Callout.Description>
+                    Cặp được cấp đo {seed.contrast.toFixed(2)}:1 trên {seed.primary} — dưới 4.5:1
+                    của WCAG 2.2 SC 1.4.3. Gói KHÔNG lặng lẽ đổi sang trắng: nó giữ đúng cặp bạn
+                    cấp, trả `meetsAA: false`, và cảnh báo ở bản dev. Bỏ trống `foreground` để gói
+                    tự chọn màu chữ an toàn.
+                  </Callout.Description>
+                </Callout>
+              ) : null}
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <ResponsiveGrid columns={2}>
+          {/* TRONG vùng — đúng một thẻ cha mang data-tenant + style */}
+          <Card data-tenant="customer" style={seed.vars}>
+            <CardHeader>
+              <CardTitle level={2}>Trong vùng của khách</CardTitle>
+              <CardDescription>
+                `&lt;div data-tenant="…" style=&#123;tenantTheme(hex).vars&#125;&gt;`. Rê chuột và
+                giữ chuột trên nút. Hover và pressed đi theo màu khách, không phải xanh mặc định.
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <BrandedRow idPrefix="inside" />
+            </CardContent>
+          </Card>
+
+          {/* NGOÀI vùng — cùng markup, không style */}
+          <Card>
+            <CardHeader>
+              <CardTitle level={2}>Ngoài vùng</CardTitle>
+              <CardDescription>
+                Cùng một hàng component, không thẻ cha nào mang khai báo. Vẫn là theme của ứng dụng
+                — đây là bằng chứng phạm vi, không phải ảnh chụp thứ hai.
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <BrandedRow idPrefix="outside" />
+            </CardContent>
+          </Card>
+        </ResponsiveGrid>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Khai báo mà vùng đang mang</CardTitle>
+            <CardDescription>
+              Năm dòng, không hơn. `--ring` có mặt vì `derived.css` khai `--ring: var(--primary)` ở
+              `:root`, nơi var() thay thế MỘT LẦN. Một scope dưới `&lt;html&gt;` thừa kế vòng focus
+              của root nếu không khai lại (docs/TOKENS.md · freeze rule).
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <CodeBlock language="css" wrap={false}>
+              {`[data-tenant="customer"] {\n${declarations}\n}`}
+            </CodeBlock>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Bảng tương phản · màu khách thật</CardTitle>
+            <CardDescription>
+              Màu chữ được chọn bằng độ chói tương đối của WCAG, không phải hằng số. Hai hàng đáng
+              nhìn nhất: #FFD400 nhận chữ ĐEN (quy tắc "luôn trắng" chỉ đạt 1.29:1) và #0A1F44 nhận
+              chữ TRẮNG (quy tắc "luôn đen" chỉ đạt 1.29:1).
+            </CardDescription>
+          </CardHeader>
+          <CardContent flush>
+            <DataTable
+              columns={columns}
+              data={rows}
+              getRowId={(row) => row.hex}
+              label="Bảng tương phản màu khách"
+            />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Ca đã chạy: hex không hợp lệ</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <Text as="p" size="sm" tone="muted">
+                `tenantTheme("#nope00")` trả `vars` RỖNG ({Object.keys(invalid.vars).length} khai
+                báo), nên vùng dưới đây giữ nguyên theme của ứng dụng thay vì vỡ. Cùng hợp đồng
+                `ColorPicker` đã có: hex hỏng bị bỏ qua, không ném lỗi.
+              </Text>
+              <div data-tenant="broken" style={invalid.vars}>
+                <BrandedRow idPrefix="broken" />
+              </div>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Mực thương hiệu · thứ gói KHÔNG tự động đổi</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <Callout kind="important">
+              <Callout.Title>
+                `--text-link` / `--text-brand` / `--text-primary` là việc của bạn
+              </Callout.Title>
+              <Callout.Description>
+                Chúng là mực trên NỀN TRANG, không phải nhãn trên nền nút, nên độ đọc phụ thuộc
+                `--background` — thứ màu của khách không quyết định. Một seed nhạt như #FFD400 cho
+                link ~1.4:1 trên nền trắng. `tenantTheme` để yên ba vai đó; nếu bạn muốn link mang
+                màu thương hiệu, hãy tự đặt chúng SAU KHI đo bằng `contrastRatio()`.
+              </Callout.Description>
+            </Callout>
+          </CardContent>
+        </Card>
+      </Flex>
+    </PageContainer>
+  );
+}

package/docs/showcase/theme-customization.tsx

@@ -68,7 +68,8 @@
  *
  * ── i18n / a11y / RTL ────────────────────────────────────────────────────────────────────────
  * Every string and every `aria-label` comes from `t()` (`themeShowcase.*` in
- * src/i18n/messages/{en,ja,vi}.json); the locale picker drives the SAME `AppProvider` locale the
+ * docs/i18n/messages/{en,ja,vi}.json — demo copy the preview registers at startup rather than
+ * ship to consumers; gh#858); the locale picker drives the SAME `AppProvider` locale the
  * library's own chrome reads, so the page and its components switch together. Numbers, currency,
  * dates, lists, regions and plurals go through `Intl` with that locale — no hand-built formats, no
  * emoji flags. Logical CSS only; no Tailwind spacing or layout utilities on this page's own