@godxjp/ui 28.7.0 → 28.8.0

package/docs/layout/affix.tsx

@@ -0,0 +1,209 @@
+import { useRef, useState } from "react";
+
+import {
+  Badge,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Descriptions,
+  ScrollArea,
+} from "@godxjp/ui/data-display";
+import { Button, Heading, Paragraph, Text } from "@godxjp/ui/general";
+import { Affix, Flex, PageContainer } from "@godxjp/ui/layout";
+import { Check, Filter } from "lucide-react";
+
+/**
+ * Affix — Ant Design `Affix` (6.6.5). Pin an element to its scrollport, and REPORT that it is
+ * pinned — which is the whole difference from `position: sticky`, and the reason both website
+ * showcases in docs/showcase/ wrote `position: sticky` and got nothing usable out of it.
+ *
+ * The cases on this page are the ones that break a hand-rolled sticky header:
+ *
+ * — the PAGE JUMP. Taking a bar out of flow removes its height, so everything below it moves up by
+ *   exactly that height. Card 1 prints the measured number it is holding open;
+ * — the CONDENSE. The bar is a different bar once pinned — a smaller control, a shorter title, a
+ *   monogram instead of a wordmark — and nothing but the reported boolean can drive that;
+ * — a SCROLLING CONTAINER that is not the page, which is `target`;
+ * — the BLOCK-END pin, which is the sticky form footer and not the sticky header;
+ * — a bar of CJK beside Latin and a 71-character unbreakable token, because the measured height is
+ *   only right if it is measured at the width it is actually laid out at;
+ * — and the narrow case, where the same bar wraps to two lines and the placeholder has to follow.
+ *
+ * Composed only from real @godxjp/ui components.
+ */
+
+/** A real filename in a real toolbar: 71 characters with nowhere to break. */
+const UNBREAKABLE = "RegionalDeploymentConfigurationParameterNamespaceIdentifierOverrides123";
+
+function Filler({ id, title, lines }: { id: string; title: string; lines: number }) {
+  return (
+    <section id={id} aria-labelledby={`${id}-heading`}>
+      <Heading level={3} id={`${id}-heading`}>
+        {title}
+      </Heading>
+      {Array.from({ length: lines }, (_, line) => (
+        <Paragraph key={line}>
+          スクロールしてください。Scroll on, and keep scrolling: the bar above only becomes
+          interesting once the page has gone far enough past it for the pin to fire.
+        </Paragraph>
+      ))}
+    </section>
+  );
+}
+
+export default function Demo() {
+  const paneRef = useRef<HTMLDivElement>(null);
+  const [pinned, setPinned] = useState(false);
+  const [paneP, setPanePinned] = useState(false);
+  const [footerPinned, setFooterPinned] = useState(false);
+
+  return (
+    <PageContainer
+      title="Affix"
+      subtitle="antd Affix · the measured placeholder, the reported boolean, the scrolling target"
+    >
+      <Flex direction="col" gap="lg">
+        <Card>
+          <CardHeader>
+            <CardTitle>1 · The condensing bar, against the page</CardTitle>
+            <CardDescription>
+              Everything that changes below is driven by `onChange` alone: the title loses its
+              qualifier, the primary action drops a size tier, and the state badge flips. Nothing
+              here is a second measurement, and `position: sticky` can drive none of it.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Affix offsetBlockStart={8} onChange={setPinned}>
+              <Card>
+                <CardContent>
+                  <Flex align="center" justify="between" gap="sm" wrap>
+                    <Text weight="medium">
+                      {pinned ? "請求書 · Invoices" : "請求書 · Invoices, 2026 年度 (all regions)"}
+                    </Text>
+                    <Flex align="center" gap="sm">
+                      <Badge variant={pinned ? "default" : "secondary"}>
+                        {pinned ? "affixed" : "in flow"}
+                      </Badge>
+                      <Button size={pinned ? "sm" : "md"}>
+                        <Check aria-hidden="true" />
+                        承認 · Approve
+                      </Button>
+                    </Flex>
+                  </Flex>
+                </CardContent>
+              </Card>
+            </Affix>
+            <Filler id="affix-page-body" title="A long page to scroll" lines={14} />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle>2 · Inside a scrolling target, not the page</CardTitle>
+            <CardDescription>
+              `target` is Ant Design&apos;s, and it is the answer to a page whose scroll belongs to
+              a pane: the bar pins against the pane&apos;s edge and stops there, not at the top of
+              the window. The label carries a 71-character unbreakable token beside CJK, so the
+              measured height is taken at the width the bar is really laid out at.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <ScrollArea viewportRef={paneRef} className="h-80" label="Filter pane">
+              <Affix target={() => paneRef.current} onChange={setPanePinned}>
+                <Card>
+                  <CardContent>
+                    <Flex align="center" gap="sm" wrap>
+                      <Filter aria-hidden="true" />
+                      {/* `truncate`, not a wrap: a 71-character identifier with nowhere to break
+                          would otherwise spill 255px past its box at 375px (measured by
+                          check:frame-overflow, which is what caught it). A toolbar label is one
+                          line; the full string stays in the DOM and in the accessible name. */}
+                      <Text weight="medium" truncate className="min-w-0">
+                        絞り込み · {UNBREAKABLE}
+                      </Text>
+                      <Badge variant={paneP ? "default" : "secondary"}>
+                        {paneP ? "affixed" : "in flow"}
+                      </Badge>
+                    </Flex>
+                  </CardContent>
+                </Card>
+              </Affix>
+              <Filler id="affix-pane-body" title="Pane content" lines={12} />
+            </ScrollArea>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle>3 · offsetBlockEnd · the sticky form footer</CardTitle>
+            <CardDescription>
+              Passing the block-END offset (and no block-start one) is what selects bottom pinning,
+              exactly as in Ant Design. It releases the moment the real end of the form reaches it,
+              which is the behaviour a `position: sticky` footer cannot express without a second
+              element.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Filler id="affix-form-body" title="Form fields" lines={10} />
+            <Affix offsetBlockEnd={8} onChange={setFooterPinned}>
+              <Card>
+                <CardContent>
+                  <Flex align="center" justify="between" gap="sm" wrap>
+                    <Text tone="muted">
+                      {footerPinned ? "未保存の変更があります" : "すべて保存済み"}
+                    </Text>
+                    <Flex align="center" gap="sm">
+                      <Badge variant={footerPinned ? "default" : "secondary"}>
+                        {footerPinned ? "affixed" : "in flow"}
+                      </Badge>
+                      <Button variant="outline">キャンセル</Button>
+                      <Button>保存</Button>
+                    </Flex>
+                  </Flex>
+                </CardContent>
+              </Card>
+            </Affix>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle>4 · What the component is actually reporting</CardTitle>
+            <CardDescription>
+              Three independent Affixes, three independent booleans. Each one fires on its own pin
+              transition and on nothing else, never once per scroll frame.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Descriptions
+              items={[
+                {
+                  label: "1 · page bar",
+                  children: (
+                    <Badge variant={pinned ? "default" : "secondary"}>{String(pinned)}</Badge>
+                  ),
+                },
+                {
+                  label: "2 · pane bar",
+                  children: (
+                    <Badge variant={paneP ? "default" : "secondary"}>{String(paneP)}</Badge>
+                  ),
+                },
+                {
+                  label: "3 · form footer",
+                  children: (
+                    <Badge variant={footerPinned ? "default" : "secondary"}>
+                      {String(footerPinned)}
+                    </Badge>
+                  ),
+                },
+              ]}
+            />
+          </CardContent>
+        </Card>
+      </Flex>
+    </PageContainer>
+  );
+}

package/docs/layout/masonry.tsx

@@ -0,0 +1,291 @@
+import { useState } from "react";
+
+import {
+  Badge,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Thumbnail,
+} from "@godxjp/ui/data-display";
+import { Button, Text } from "@godxjp/ui/general";
+import {
+  AppShell,
+  Flex,
+  Masonry,
+  PageContainer,
+  Sidebar,
+  type SidebarSectionProp,
+  Topbar,
+  type MasonryItemProp,
+} from "@godxjp/ui/layout";
+import { Bot, Images, Inbox, MessageSquare, Settings } from "lucide-react";
+
+import coverTerrain from "../assets/cover-terrain.svg";
+import shotPortrait from "../assets/shot-portrait.svg";
+
+/**
+ * Masonry — Ant Design `Masonry` (6.0.0). A real inbox of mixed-height notes, not a tidy row of
+ * equal cards: the tidy demo is the one that hides every defect this layout actually has.
+ *
+ * Every card on this page is an EDGE:
+ * — a one-line note beside a twelve-line one, in the same run;
+ * — an IMAGE tile whose height is declared so the columns do not jump when it decodes;
+ * — a CJK tile of real Japanese prose at --line-height-body 1.7, which is taller per character
+ *   than the Latin beside it;
+ * — the single-column case, which is what every narrow viewport collapses to;
+ * — a tile PINNED to the first column, which is where reading order and visual order part company;
+ * — a responsive `columns` map, driven live by the viewport.
+ *
+ * Composed only from real @godxjp/ui components.
+ */
+const sections: SidebarSectionProp[] = [
+  {
+    label: "受信",
+    items: [
+      { id: "inbox", label: "メモ", icon: Inbox },
+      { id: "gallery", label: "素材", icon: Images },
+      { id: "chat", label: "やりとり", icon: MessageSquare },
+      { id: "agents", label: "エージェント", icon: Bot },
+    ],
+  },
+  { label: "管理", items: [{ id: "settings", label: "設定", icon: Settings }] },
+];
+
+/** A one-line note. The shortest thing this layout ever has to place. */
+function ShortNote({ title, body }: { title: string; body: string }) {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>{title}</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <Text size="sm">{body}</Text>
+      </CardContent>
+    </Card>
+  );
+}
+
+const LONG_BODY = [
+  "The rule the team keeps re-deriving: a masonry has two orders and they do not agree.",
+  "DOM order is the order of `items`, always, because every tile is absolutely positioned and",
+  "nothing reorders the markup. Visual order is the packing: tile four lands under whichever of",
+  "the first three columns is shortest, so it can paint ABOVE a tile that precedes it in the",
+  "source. That is the form, and the consequence is one line long: order the items by importance,",
+  "never by height.",
+  "",
+  "It matters most for the keyboard. Tab visits this card before the short one beside it even",
+  "when this card's top edge sits lower on the screen, and a screen reader reads them in the same",
+  "sequence. The alternative implementation, CSS `column-count`, is worse on exactly that axis:",
+  "it fills the first column to the bottom before starting the second, so in a thirty-tile feed",
+  "the second tile in the DOM paints at the bottom-left corner of the viewport.",
+].join(" ");
+
+const JA_BODY =
+  "日本語の本文は 1 文字あたりの高さが欧文より大きい。全角の仮名と漢字が em ボックスを埋めるので、" +
+  "--line-height-body の 1.7 がそのまま行の高さに効く。同じ文字数でも、欧文の隣に置くと列の高さが" +
+  "先に伸びるのはそのためで、段組みの詰め方はこの差をそのまま受け取る。短い注記と長い注記を同じ列に" +
+  "並べたときに、どちらが先に読まれるかは見た目ではなく items の順序が決める。ここを取り違えると、" +
+  "画面では上にあるカードが、読み上げでは最後に来る。";
+
+export default function MasonryDoc() {
+  const [columns, setColumns] = useState(3);
+  const [placed, setPlaced] = useState<number[]>([]);
+
+  const feed: MasonryItemProp[] = [
+    {
+      key: "one-line",
+      children: <ShortNote title="請求書 #4821" body="承認済み。" />,
+    },
+    {
+      key: "image",
+      // The declared height is what keeps the columns still while the image decodes: without it
+      // every tile below this one jumps the moment the bytes land.
+      height: 268,
+      children: (
+        <Card>
+          <CardContent>
+            <Thumbnail src={coverTerrain} width={480} height={270} alt="" />
+            <Text size="xs" tone="muted">
+              cover-terrain.svg · 480×270
+            </Text>
+          </CardContent>
+        </Card>
+      ),
+    },
+    {
+      key: "long",
+      children: (
+        <Card>
+          <CardHeader>
+            <CardTitle>Reading order vs visual order</CardTitle>
+            <CardDescription>Twelve lines, beside a one-line card.</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Text size="sm">{LONG_BODY}</Text>
+          </CardContent>
+        </Card>
+      ),
+    },
+    {
+      key: "ja",
+      children: (
+        <Card>
+          <CardHeader>
+            <CardTitle>行の高さは言語で変わる</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <Text size="sm">{JA_BODY}</Text>
+          </CardContent>
+        </Card>
+      ),
+    },
+    {
+      key: "badge",
+      children: (
+        <Card>
+          <CardContent>
+            <Flex gap="sm" wrap>
+              <Badge>下書き</Badge>
+              <Badge variant="secondary">保留</Badge>
+              <Badge variant="outline">期限切れ</Badge>
+            </Flex>
+          </CardContent>
+        </Card>
+      ),
+    },
+    {
+      key: "pinned",
+      // PINNED. It stays fifth in the reading order whatever the packing does with it.
+      column: 0,
+      children: (
+        <Card>
+          <CardHeader>
+            <CardTitle>column: 0</CardTitle>
+            <CardDescription>
+              最初の列に固定。読み上げの順番は五番目のまま動かない。
+            </CardDescription>
+          </CardHeader>
+        </Card>
+      ),
+    },
+    {
+      key: "portrait",
+      height: 232,
+      children: (
+        <Card>
+          <CardContent>
+            <Thumbnail src={shotPortrait} width={360} height={640} alt="モバイル版の一覧画面" />
+          </CardContent>
+        </Card>
+      ),
+    },
+    {
+      key: "two-line",
+      children: (
+        <ShortNote
+          title="経費精算"
+          body="領収書が二枚不足しています。差し戻し前に担当者へ確認してください。"
+        />
+      ),
+    },
+    {
+      key: "shortest",
+      children: <ShortNote title="勤怠" body="—" />,
+    },
+  ];
+
+  return (
+    <AppShell
+      sidebar={
+        <Sidebar
+          activeId="inbox"
+          sections={sections}
+          onSelect={() => {}}
+          product={{ name: "CoreDesk", role: "メモ", color: "hsl(var(--primary))" }}
+        />
+      }
+      topbar={<Topbar />}
+    >
+      <PageContainer
+        title="段組みメモ"
+        subtitle="Masonry · 高さの揃わないカードを、そのつど一番低い列へ落としていく"
+      >
+        {/* THE REAL SCREEN. Responsive columns, a mixed feed, and the layout report. */}
+        <Flex direction="col" gap="sm">
+          <Flex gap="sm" align="center" wrap>
+            <Text size="sm" weight="medium">
+              columns · {columns} · fresh
+            </Text>
+            {[1, 2, 3, 4].map((count) => (
+              <Button
+                key={count}
+                size="sm"
+                variant={count === columns ? "default" : "outline"}
+                onClick={() => setColumns(count)}
+              >
+                {count}
+              </Button>
+            ))}
+            <Text size="xs" tone="muted">
+              {placed.length === 0
+                ? "onLayoutChange 待ち"
+                : `onLayoutChange · 列ごとの枚数 ${placed.join(" / ")}`}
+            </Text>
+          </Flex>
+          {/* `fresh` is ON here, and the reason is a measurement, not a preference: at 390px the
+              long English card re-wraps by one line AFTER the pass that measured it, and with the
+              container observer alone (antd's default) nothing notices — the container reported
+              2472.2px while its own content ended at 2489.7px. `fresh` observes each tile, so the
+              two agree. A feed with images and a live column count is exactly what it is for. */}
+          <Masonry
+            fresh
+            columns={columns}
+            gap="md"
+            items={feed}
+            onLayoutChange={(layout) => {
+              const perColumn = new Array<number>(columns).fill(0);
+              for (const entry of layout) perColumn[entry.column] += 1;
+              setPlaced(perColumn);
+            }}
+          />
+        </Flex>
+
+        {/* THE NARROW CASE, on purpose and at full width: one column is what every phone gets,
+            and it is the arrangement a three-column demo never shows. */}
+        <Flex direction="col" gap="sm">
+          <Text size="sm" weight="medium">
+            単一列 · columns={1}
+          </Text>
+          <Text size="xs" tone="muted">
+            狭い画面はここに収束する。段組みが消えても読み上げの順番は同じ。DOM の順序は items
+            の順序のまま。
+          </Text>
+          <Masonry columns={1} gap="sm" items={feed.slice(0, 4)} />
+        </Flex>
+
+        {/* THE VIEWPORT MAP. `columns` takes the same step names Flex direction does. */}
+        <Flex direction="col" gap="sm">
+          <Text size="sm" weight="medium">
+            columns={"{ base: 1, sm: 2, md: 3, xl: 4 }"}
+          </Text>
+          <Text size="xs" tone="muted">
+            sm 40rem · md 48rem · lg 64rem · xl 80rem。Ant Design の `xs` はここでは `base`、`xxl`
+            はない。
+          </Text>
+          <Masonry columns={{ base: 1, sm: 2, md: 3, xl: 4 }} gap="md" items={feed.slice(2)} />
+        </Flex>
+
+        {/* NO GAP AT ALL — Ant Design's own default, which is what a token-less masonry looks
+            like. Worth seeing once so the `gap` step is a decision rather than a habit. */}
+        <Flex direction="col" gap="sm">
+          <Text size="sm" weight="medium">
+            gap 省略 · Ant Design の既定は 0
+          </Text>
+          <Masonry columns={3} items={feed.slice(0, 5)} />
+        </Flex>
+      </PageContainer>
+    </AppShell>
+  );
+}