@godxjp/ui 28.5.0 → 28.6.0

package/docs/data-display/descriptions.tsx

@@ -6,176 +6,255 @@ import {
   CardHeader,
   CardTitle,
   Descriptions,
+  Progress,
+  Thumbnail,
 } from "@godxjp/ui/data-display";
-import type { CSSProperties } from "react";
-import { Text } from "@godxjp/ui/general";
+import { Button, Text } from "@godxjp/ui/general";
 import { Flex, PageContainer } from "@godxjp/ui/layout";
+import { Download, ExternalLink, FileText } from "lucide-react";
 
 /**
- * Descriptions — responsive label/value grid for detail-page metadata. COMPOUND:
- * the value goes in Descriptions.Item children. Never hand-roll a dl/dt/dd grid.
- * Composed only from real @godxjp/ui components.
+ * Descriptions — the label/value grid every detail page is made of.
+ *
+ * WHY THIS PAGE IS LONG. It was five tidy cards of short strings, and the owner's verdict was that
+ * it shows nothing about whether the component holds up. That is right: a label/value grid is
+ * trivial when every label is four characters and every value is one line.
+ *
+ * A real detail screen is not that. It has a label that runs to three lines beside one that is two
+ * characters; a value that is an image, a file to download, a link, a status, a progress bar, a
+ * 40-character machine ID, or nothing at all; and it has to survive all of them in the same grid,
+ * at every breakpoint, bordered and not.
+ *
+ * So every section below is a case a real detail page hits. Where a section looks bad, the
+ * component owes an answer — the sample data is not there to flatter it.
  */
+const ID = "01JBQ9X7M4K2R8VT3NZ6YHF0PA";
+
 export default function Demo() {
   return (
-    <PageContainer title="Descriptions" subtitle="Label / value metadata grid for detail pages">
+    <PageContainer
+      title="Descriptions"
+      subtitle="label/value grid — every shape a detail page asks for"
+    >
       <Flex direction="col" gap="lg">
-        {/* Default columns=2 — the canonical 2-column metadata grid.
-            mono for the ID; span=2 + a long URL value shows full-row + break-all overflow. */}
         <Card>
           <CardHeader>
-            <CardTitle level={2}>請求書の詳細</CardTitle>
+            <CardTitle level={2}>1 · columns × bordered × layout — the three axes</CardTitle>
             <CardDescription>
-              既定は
-              columns=2。値は任意のノード（テキスト・Badge・金額）。狭い画面では1列に折り返します。
+              Every combination changes where the label sits and how the grid divides. These are the
+              four a project actually picks between.
             </CardDescription>
           </CardHeader>
           <CardContent>
-            <Descriptions>
-              <Descriptions.Item label="請求書番号" mono>
-                INV-2024-0312
-              </Descriptions.Item>
-              <Descriptions.Item label="取引先">株式会社ベトヤ</Descriptions.Item>
-              <Descriptions.Item label="状態">
-                <Badge status="active" />
-              </Descriptions.Item>
-              <Descriptions.Item label="発行日">2024-04-12</Descriptions.Item>
-              <Descriptions.Item label="小計">
-                <Text tabular>¥438,182</Text>
-              </Descriptions.Item>
-              <Descriptions.Item label="消費税 (10%)">
-                <Text tabular>¥43,818</Text>
-              </Descriptions.Item>
-              <Descriptions.Item label="合計">
-                <Text weight="medium" tabular>
-                  ¥482,000
+            <Flex direction="col" gap="lg">
+              <Flex direction="col" gap="xs">
+                <Text size="sm" tone="muted">
+                  columns=3 · bordered · horizontal — the dense admin default
                 </Text>
+                <Descriptions columns={3} bordered layout="horizontal">
+                  <Descriptions.Item label="取引先">株式会社山田製作所</Descriptions.Item>
+                  <Descriptions.Item label="担当">佐藤 玲</Descriptions.Item>
+                  <Descriptions.Item label="状態">
+                    <Badge tone="success">有効</Badge>
+                  </Descriptions.Item>
+                  <Descriptions.Item label="登録日">2024-04-01</Descriptions.Item>
+                  <Descriptions.Item label="与信枠">¥12,000,000</Descriptions.Item>
+                  <Descriptions.Item label="支払条件">月末締め翌月末払い</Descriptions.Item>
+                </Descriptions>
+              </Flex>
+
+              <Flex direction="col" gap="xs">
+                <Text size="sm" tone="muted">
+                  columns=2 · no border · vertical — the reading layout, label above value
+                </Text>
+                <Descriptions columns={2} layout="vertical">
+                  <Descriptions.Item label="取引先">株式会社山田製作所</Descriptions.Item>
+                  <Descriptions.Item label="担当">佐藤 玲</Descriptions.Item>
+                  <Descriptions.Item label="与信枠">¥12,000,000</Descriptions.Item>
+                  <Descriptions.Item label="支払条件">月末締め翌月末払い</Descriptions.Item>
+                </Descriptions>
+              </Flex>
+
+              <Flex direction="col" gap="xs">
+                <Text size="sm" tone="muted">
+                  columns=1 · bordered — a narrow column or a phone
+                </Text>
+                <Descriptions columns={1} bordered>
+                  <Descriptions.Item label="取引先">株式会社山田製作所</Descriptions.Item>
+                  <Descriptions.Item label="状態">
+                    <Badge tone="success">有効</Badge>
+                  </Descriptions.Item>
+                </Descriptions>
+              </Flex>
+
+              <Flex direction="col" gap="xs">
+                <Text size="sm" tone="muted">
+                  labelAlign=end — right-aligned labels, so the values start on one line
+                </Text>
+                <Descriptions columns={2} bordered labelAlign="end">
+                  <Descriptions.Item label="ID">{ID}</Descriptions.Item>
+                  <Descriptions.Item label="状態">
+                    <Badge tone="success">有効</Badge>
+                  </Descriptions.Item>
+                </Descriptions>
+              </Flex>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>2 · responsive columns</CardTitle>
+            <CardDescription>
+              `columns` takes a breakpoint object. Narrow this frame with the Dimensions control: 1
+              column on a phone, 2 on a tablet, 3 on a desktop — the same markup throughout.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Descriptions columns={{ sm: 1, md: 2, lg: 3 }} bordered>
+              <Descriptions.Item label="会社名">株式会社山田製作所</Descriptions.Item>
+              <Descriptions.Item label="法人番号" mono>
+                7010001071491
               </Descriptions.Item>
-              <Descriptions.Item label="PDF リンク" mono span={2}>
-                https://invoices.vetoya.example.co.jp/2024/04/INV-2024-0312-rev2.pdf
-              </Descriptions.Item>
+              <Descriptions.Item label="業種">精密機器製造</Descriptions.Item>
+              <Descriptions.Item label="代表">山田 太郎</Descriptions.Item>
+              <Descriptions.Item label="従業員数">248 名</Descriptions.Item>
+              <Descriptions.Item label="設立">1974-06-12</Descriptions.Item>
             </Descriptions>
           </CardContent>
         </Card>
 
-        {/* layout="horizontal" — label BESIDE value (token-aligned label column), like <Form layout>.
-            Default layout is "vertical" (label over value, the cards above). */}
         <Card>
           <CardHeader>
-            <CardTitle level={2}>横並び (layout=&quot;horizontal&quot;)</CardTitle>
+            <CardTitle level={2}>3 · the value is not a string</CardTitle>
             <CardDescription>
-              ラベルを値の左に揃える。`--descriptions-label-width` でラベル列幅を調整。既定は
-              layout=&quot;vertical&quot;（ラベルを上に積む、上のカード）。
+              The value slot takes any node. These are the ones a detail page actually puts there —
+              an image, a file, a link, a status, a proportion, a secret, money, a long memo.
             </CardDescription>
           </CardHeader>
           <CardContent>
-            <Descriptions columns={1} layout="horizontal">
-              <Descriptions.Item label="請求書番号" mono>
-                INV-2024-0312
+            <Descriptions columns={{ sm: 1, md: 2 }} bordered>
+              <Descriptions.Item label="製品画像">
+                <Thumbnail src="/godxjp-ui/favicon.svg" alt="製品サムネイル" size="md" />
               </Descriptions.Item>
-              <Descriptions.Item label="取引先">株式会社ベトヤ</Descriptions.Item>
               <Descriptions.Item label="状態">
-                <Badge status="active" />
+                <Flex direction="row" gap="xs" wrap>
+                  <Badge tone="success">出荷可</Badge>
+                  <Badge tone="warning" variant="outline">
+                    在庫僅少
+                  </Badge>
+                </Flex>
               </Descriptions.Item>
-              <Descriptions.Item label="合計">
-                <Text weight="medium" tabular>
-                  ¥482,000
-                </Text>
+              <Descriptions.Item label="仕様書">
+                <Button variant="outline" size="sm">
+                  <FileText className="size-4" />
+                  仕様書_v4.2.pdf
+                </Button>
+              </Descriptions.Item>
+              <Descriptions.Item label="検査成績書">
+                <Button variant="ghost" size="sm">
+                  <Download className="size-4" />
+                  ダウンロード（2.4 MB）
+                </Button>
+              </Descriptions.Item>
+              <Descriptions.Item label="外部リンク">
+                <Button variant="link" size="sm">
+                  <ExternalLink className="size-4" />
+                  サプライヤーポータル
+                </Button>
+              </Descriptions.Item>
+              <Descriptions.Item label="検収進捗">
+                <Progress value={72} tone="success" label="検収進捗 72%" />
+              </Descriptions.Item>
+              <Descriptions.Item label="単価">¥128,400</Descriptions.Item>
+              <Descriptions.Item label="ロットID" mono>
+                {ID}
               </Descriptions.Item>
             </Descriptions>
           </CardContent>
         </Card>
 
-        {/* columns=1 — stacked detail panel: every item on its own row. */}
         <Card>
           <CardHeader>
-            <CardTitle level={2}>取引先の詳細</CardTitle>
-            <CardDescription>columns=1。各項目を縦積みにする詳細パネル向けの構成。</CardDescription>
+            <CardTitle level={2}>4 · span — a value that needs the whole row</CardTitle>
+            <CardDescription>
+              An address, a memo or a JSON blob does not belong in a one-third cell. `span` widens
+              the item; `span=&quot;filled&quot;` takes whatever is left on the row, so the grid
+              stays aligned instead of leaving a hole.
+            </CardDescription>
           </CardHeader>
           <CardContent>
-            <Descriptions columns={1}>
-              <Descriptions.Item label="会社名">株式会社ベトヤ</Descriptions.Item>
-              <Descriptions.Item label="法人番号" mono>
-                1180001052731
+            <Descriptions columns={3} bordered>
+              <Descriptions.Item label="取引先">株式会社山田製作所</Descriptions.Item>
+              <Descriptions.Item label="担当">佐藤 玲</Descriptions.Item>
+              <Descriptions.Item label="電話">03-5555-0198</Descriptions.Item>
+              <Descriptions.Item label="本社所在地" span={3}>
+                〒105-0011 東京都港区芝公園四丁目2番8号 東京タワー内 グローバルビジネスセンター 23F
+                株式会社山田製作所 東日本統括本部
               </Descriptions.Item>
-              <Descriptions.Item label="住所">
-                東京都渋谷区神宮前5-52-2 青山オーバルビル7F
+              <Descriptions.Item label="備考" span="filled">
+                検収は毎月第2・第4火曜のみ。祝日と重なる場合は翌営業日に振替。先方の受入窓口は
+                資材部・資材管理課（内線
+                4821）。2026年4月以降は電子取引のみとなるため、紙の納品書は不可。
               </Descriptions.Item>
-              <Descriptions.Item label="担当者">山田 太郎（経理部）</Descriptions.Item>
+              <Descriptions.Item label="与信枠">¥12,000,000</Descriptions.Item>
+              <Descriptions.Item label="使用中">¥8,214,930</Descriptions.Item>
             </Descriptions>
           </CardContent>
         </Card>
 
-        {/* columns=3 — dense metadata grid; span=3 makes the JSON value occupy the full width. */}
         <Card>
           <CardHeader>
-            <CardTitle level={2}>システムメタデータ</CardTitle>
+            <CardTitle level={2}>5 · the cases that break a label/value grid</CardTitle>
             <CardDescription>
-              columns=3。識別子の多い密なメタデータ向け。mono と span でIDやJSONを整列。
+              This is the only section on the page that can tell you whether Descriptions is any
+              good. If a row here looks wrong, the component owes an answer — not the data.
             </CardDescription>
           </CardHeader>
           <CardContent>
-            <Descriptions columns={3}>
-              <Descriptions.Item label="リソースID" mono>
-                inv_8f3a21c0
+            <Descriptions columns={{ sm: 1, md: 2, lg: 3 }} bordered>
+              <Descriptions.Item label="グローバル人事情報基盤・従業員セルフサービスポータル（アジア太平洋地域）連携ステータス">
+                <Badge tone="success">連携済</Badge>
               </Descriptions.Item>
-              <Descriptions.Item label="リビジョン" mono>
-                v3
+              <Descriptions.Item label="率">96.8%</Descriptions.Item>
+              <Descriptions.Item label="ID" mono>
+                urn:godx:entitlement:ap-northeast-1:7010001071491:workforce/identity/administration/v4
               </Descriptions.Item>
-              <Descriptions.Item label="状態">
-                <Badge status="active" />
-              </Descriptions.Item>
-              <Descriptions.Item label="作成日時" mono>
-                2024-04-12T09:31:00+09:00
-              </Descriptions.Item>
-              <Descriptions.Item label="更新日時" mono>
-                2024-04-12T14:07:55+09:00
+              <Descriptions.Item label="未設定">
+                <Text tone="muted">—</Text>
               </Descriptions.Item>
-              <Descriptions.Item label="作成者">山田 太郎</Descriptions.Item>
-              <Descriptions.Item label="メタデータ" mono span={3}>
-                {'{ "channel": "web", "tax_rate": 0.1, "currency": "JPY" }'}
+              <Descriptions.Item label="空文字">{""}</Descriptions.Item>
+              <Descriptions.Item label="ゼロ">0</Descriptions.Item>
+              <Descriptions.Item label="累計取扱高">¥128,400,932,517</Descriptions.Item>
+              <Descriptions.Item label="差引">−¥412,880</Descriptions.Item>
+              <Descriptions.Item label="長い英数字" mono>
+                AKIAIOSFODNN7EXAMPLEWJALRXUTNFEMIK7MDENGBPXRFICYEXAMPLEKEY
               </Descriptions.Item>
             </Descriptions>
           </CardContent>
         </Card>
 
-        {/* ── The RULED property panel (gh#414) ─────────────────────────────
-            Two token knobs, both OFF by default, turn a horizontal Descriptions into the ruled
-            panel a detail page usually wants. They exist so a service stops hand-rolling a
-            `<Flex className="min-h-10 border-b">` row: the label column, the gaps and the value
-            type step were already Descriptions'; only the rule and the band height were missing.
-            The row gap goes to 0 in the same declaration — the gap is the space BETWEEN rules, so
-            leaving it would draw detached hairlines instead of a ruled list. */}
         <Card>
           <CardHeader>
-            <CardTitle level={2}>案件の詳細 · ruled rows</CardTitle>
-            <CardDescription>
-              一行ごとに罫線を引いた属性パネル。--descriptions-row-border と
-              --descriptions-row-min-height をテーマで一度設定するだけで、コンポーネントは同じです。
-            </CardDescription>
+            <CardTitle level={2}>使い方の要点</CardTitle>
+            <CardDescription>この3点で、上のほとんどが決まります。</CardDescription>
           </CardHeader>
-          {/* The knobs are declared on the CARD BODY, not on the grid: custom properties inherit,
-              so one scope re-tunes every Descriptions inside it — which is how a service theme
-              would set them (once, globally), not per call site. */}
-          <CardContent
-            style={
-              {
-                "--descriptions-row-border": "1px solid hsl(var(--border))",
-                "--descriptions-row-min-height": "var(--band-height-lg)",
-                "--descriptions-row-gap": "0px",
-              } as CSSProperties
-            }
-          >
-            <Descriptions columns={1} layout="horizontal">
-              <Descriptions.Item label="案件名">2026年度 基幹システム更改</Descriptions.Item>
-              <Descriptions.Item label="担当">山田 太郎</Descriptions.Item>
-              <Descriptions.Item label="状態">
-                <Badge status="active" />
-              </Descriptions.Item>
-              <Descriptions.Item label="契約ID" mono>
-                CT-2026-0088
-              </Descriptions.Item>
-            </Descriptions>
+          <CardContent>
+            <Flex direction="col" gap="sm">
+              <Text as="div" size="sm">
+                直下の子は <code>Descriptions.Item</code> だけです。生の <code>&lt;div&gt;</code> や
+                <code>&lt;dt&gt;/&lt;dd&gt;</code> を混ぜるとグリッドが崩れます。
+              </Text>
+              <Text as="div" size="sm">
+                機械可読な値（ID・パス・鍵・通貨コード）には <code>mono</code> を付けてください。
+                等幅になるだけでなく <code>break-all</code> が効き、上の 57
+                文字の鍵がセルを突き破らずに折り返します。
+              </Text>
+              <Text as="div" size="sm">
+                住所・備考・JSON のような長い値には <code>span</code> を。 1/3
+                セルに押し込むと、その行だけ高さが跳ねて表全体が読みにくくなります。
+              </Text>
+            </Flex>
           </CardContent>
         </Card>
       </Flex>

package/docs/data-display/legend.tsx

@@ -61,7 +61,20 @@ export default function Demo() {
                       aria-label={row.name}
                     />
                   </Flex>
-                  <Flex width={150} justify="end" align="center" gapRaw={12}>
+                  {/* A COLUMN OF NUMBERS NEEDS COLUMNS, not a row of shrink-to-fit boxes.
+                      `tabular` makes DIGITS equal-width inside one Text; it cannot align two Texts
+                      with different digit COUNTS. Laid out as a flex row and right-aligned as a
+                      group, a row ending in "9" sat 8px right of one ending in "21" — measured on
+                      the published site, and the reason this readout looked crooked. Fixed tracks
+                      give each value its own cell, so every row lines up whatever the digits. */}
+                  <div
+                    className="grid items-center"
+                    style={{
+                      gridTemplateColumns: "2.5rem 2.5rem 2.5rem 4.5rem",
+                      justifyItems: "end",
+                      columnGap: "var(--space-2)",
+                    }}
+                  >
                     <Text tone="destructive" weight="semibold" tabular>
                       {row.over}
                     </Text>
@@ -74,7 +87,7 @@ export default function Demo() {
                     <Text tone="muted" tabular>
                       計 {row.over + row.near + row.done}
                     </Text>
-                  </Flex>
+                  </div>
                 </Flex>
               ))}
             </Flex>
@@ -108,8 +121,8 @@ export default function Demo() {
           <CardHeader>
             <CardTitle level={2}>Named legend</CardTitle>
             <CardDescription>
-              aria-label を渡すと、その凡例が「何のキーか」を読み上げます。項目は list /
-              listitem として並びます。
+              aria-label を渡すと、その凡例が「何のキーか」を読み上げます。項目は list / listitem
+              として並びます。
             </CardDescription>
           </CardHeader>
           <CardContent>

package/docs/data-display/scroll-area.tsx

@@ -116,6 +116,7 @@ export default function Demo() {
             <Card variant="outline" className="h-64 w-full">
               <CardContent flush>
                 <ScrollArea
+                  className="h-72"
                   anchor="bottom"
                   viewportRef={streamViewport}
                   onAnchoredChange={setAnchored}
@@ -176,7 +177,7 @@ export default function Demo() {
           <CardContent>
             <Card variant="outline" className="h-40 w-full">
               <CardContent flush>
-                <ScrollArea anchor="bottom" anchorOffset={0}>
+                <ScrollArea className="h-40" anchor="bottom" anchorOffset={0}>
                   <CardContent>
                     <Flex direction="col" gap="xs">
                       {entries.map((e) => (
@@ -192,6 +193,67 @@ export default function Demo() {
           </CardContent>
         </Card>
 
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>
+              scrollbar=&quot;always&quot; — 「スクロールバーが見えない」の答え
+            </CardTitle>
+            <CardDescription>
+              既定の <code>auto</code> はプラットフォームに任せます。macOS / iPadOS
+              のシステム既定「スクロール中にのみ表示」では、それは
+              <strong>オーバーレイのバー</strong>
+              です。つまり、すでにスクロールしている間しか存在しません。止まっている状態では、
+              この面がスクロールできることが一切わかりません（gh#798）。
+              下の2つは中身も高さも同一で、違うのは <code>scrollbar</code> だけです。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <ResponsiveGrid columns={{ sm: 1, md: 2 }}>
+              <Flex direction="col" gap="xs">
+                <Text size="sm" tone="muted">
+                  scrollbar=&quot;auto&quot;（既定）— macOS では静止時にバーが出ない
+                </Text>
+                <Card variant="outline" className="w-full">
+                  <CardContent flush>
+                    <ScrollArea className="h-40">
+                      <CardContent>
+                        <Flex direction="col" gap="xs">
+                          {entries.map((e) => (
+                            <div key={`auto-${e}`} className="text-sm tabular-nums">
+                              {e}
+                            </div>
+                          ))}
+                        </Flex>
+                      </CardContent>
+                    </ScrollArea>
+                  </CardContent>
+                </Card>
+              </Flex>
+
+              <Flex direction="col" gap="xs">
+                <Text size="sm" tone="muted">
+                  scrollbar=&quot;always&quot; — レイアウトを占める古典的なバー
+                </Text>
+                <Card variant="outline" className="w-full">
+                  <CardContent flush>
+                    <ScrollArea className="h-40" scrollbar="always">
+                      <CardContent>
+                        <Flex direction="col" gap="xs">
+                          {entries.map((e) => (
+                            <div key={`always-${e}`} className="text-sm tabular-nums">
+                              {e}
+                            </div>
+                          ))}
+                        </Flex>
+                      </CardContent>
+                    </ScrollArea>
+                  </CardContent>
+                </Card>
+              </Flex>
+            </ResponsiveGrid>
+          </CardContent>
+        </Card>
+
         <Card>
           <CardHeader>
             <CardTitle level={2}>固定高さのリスト（縦スクロール）</CardTitle>
@@ -200,9 +262,14 @@ export default function Demo() {
             </CardDescription>
           </CardHeader>
           <CardContent>
-            <Card variant="outline" className="h-56 w-full">
+            {/* THE HEIGHT GOES ON THE SCROLLAREA, not on an ancestor. It was on the outer Card,
+                and neither CardContent nor ScrollArea inherits a height from it — so the
+                ScrollArea grew to its content, `scrollHeight === clientHeight`, and the demo for
+                a scrolling component did not scroll. Measured on the published site before this
+                change. The page header says this rule outright; the example broke it. */}
+            <Card variant="outline" className="w-full">
               <CardContent flush>
-                <ScrollArea>
+                <ScrollArea className="h-56">
                   <CardContent>
                     <Flex direction="col" gap="xs">
                       {entries.map((e) => (
@@ -296,9 +363,12 @@ export default function Demo() {
             </CardDescription>
           </CardHeader>
           <CardContent>
-            <Card variant="outline" className="h-56 w-full">
+            {/* Same h-56 as above, DELIBERATELY not overflowing: `shortEntries` fits, so no bar
+                appears. This is the control case — it is only meaningful next to one that does
+                overflow, which is why the demo above had to be fixed first. */}
+            <Card variant="outline" className="w-full">
               <CardContent flush>
-                <ScrollArea>
+                <ScrollArea className="h-56">
                   <CardContent>
                     <Flex direction="col" gap="xs">
                       {shortEntries.map((e) => (