@godxjp/ui 28.7.0 → 28.8.0

package/docs/data-display/marquee.tsx

@@ -0,0 +1,254 @@
+import { useState } from "react";
+
+import {
+  Badge,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Marquee,
+} from "@godxjp/ui/data-display";
+import { Switch } from "@godxjp/ui/data-entry";
+import { Heading, Link, Text } from "@godxjp/ui/general";
+import { Flex, PageContainer, Separator } from "@godxjp/ui/layout";
+
+/**
+ * Marquee · a track of content that travels continuously, and the WCAG 2.2.2 pause control that
+ * makes that legal.
+ *
+ * Every card on this page is an EDGE, because the tidy demo is the one that hides the defects this
+ * component actually has:
+ * · ONE item in a full-width track, which is the case that needs the most clones;
+ * · FORTY items, which is the case that proves the pace is measured and not per-cycle;
+ * · a 71-character unbreakable string, wider than a phone;
+ * · a track NARROWER than one item, where there is nothing to clone into;
+ * · CJK beside Latin beside Vietnamese, at three different optical widths;
+ * · the paused state, which is where the content has to stay readable;
+ * · a controlled "stop all motion" switch driving two tracks at once.
+ *
+ * Composed only from real @godxjp/ui components. All copy is consumer-owned and localized.
+ */
+
+const PARTNERS = [
+  "フジワラ運輸",
+  "Meridian Foods",
+  "Công ty Đại Việt",
+  "北陸電機",
+  "Halden Systems",
+  "三和商会",
+  "Vinh Phat Logistics",
+  "東海システム",
+];
+
+/** Forty items · the case a per-cycle duration would send across the screen forty times too fast. */
+const FORTY = Array.from({ length: 40 }, (_, index) => `SKU-${String(index + 1).padStart(4, "0")}`);
+
+/** 71 characters, no break opportunity anywhere in it. */
+const UNBREAKABLE = "SUPPLYCHAINRECONCILIATIONBATCHIDENTIFIER2026Q3NOBREAKOPPORTUNITY0000001";
+
+export default function MarqueeDoc() {
+  const [motion, setMotion] = useState(true);
+
+  return (
+    <PageContainer title="Marquee" subtitle="連続して流れるトラックと、それを止める操作">
+      <Flex direction="col" gap="lg">
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>ロゴウォール · 既定のかたち</CardTitle>
+            <CardDescription>
+              `fade` で両端をマスクし、`pauseOnHover` を足した 8 件。コピー数は測って決まる（内容幅
+              ÷ 表示幅 + 1）ので、ウィンドウを横に伸ばせばクローンが増える。停止ボタンは常にあり、
+              Tab で到達できる。各社名はリンクなので、トラック内にフォーカスが入ると自動で止まる
+              （動いているリンクは押せないため）。クローン側のリンクは Tab の順路に出てこない。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Marquee fade pauseOnHover label="取引先ロゴ">
+              {PARTNERS.map((name) => (
+                <Link key={name} href={`#partner-${encodeURIComponent(name)}`}>
+                  {name}
+                </Link>
+              ))}
+            </Marquee>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>1 件 と 40 件 · 速度は件数で変わらない</CardTitle>
+            <CardDescription>
+              1 周の所要時間ではなく「1 画面ぶんを流れる時間」が `--marquee-interval` なので、1
+              件でも 40 件でも見た目の速さは同じ。1 件のトラックはクローンが最も多く、 40
+              件のトラックはクローンが 1 枚で足りる。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <Heading level={3}>1 件</Heading>
+              <Marquee label="在庫同期の状態">
+                <Badge tone="info">在庫同期 · 実行中</Badge>
+              </Marquee>
+              <Separator />
+              <Heading level={3}>40 件</Heading>
+              <Marquee label="処理中の SKU">
+                {FORTY.map((sku) => (
+                  <Text key={sku} size="xs" tone="muted">
+                    {sku}
+                  </Text>
+                ))}
+              </Marquee>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>折り返せない 71 文字と、1 件より狭いトラック</CardTitle>
+            <CardDescription>
+              分割点のない 71 文字は電話の画面より広い。狭い枠に入れると「表示幅 ÷ 内容幅」は 1
+              を下回るので、クローンは最小の 1 枚になり、それでも継ぎ目なく回る。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <Heading level={3}>全幅</Heading>
+              <Marquee label="照合バッチ識別子">
+                <Text size="sm">{UNBREAKABLE}</Text>
+              </Marquee>
+              <Separator />
+              <Heading level={3}>幅 14rem · 1 件より狭い枠</Heading>
+              <div style={{ inlineSize: "14rem", maxInlineSize: "100%" }}>
+                <Marquee label="照合バッチ識別子・狭い枠">
+                  <Text size="sm">{UNBREAKABLE}</Text>
+                </Marquee>
+              </div>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>日本語 · Latin · Tiếng Việt が同じ行に並ぶ</CardTitle>
+            <CardDescription>
+              全角の仮名漢字、欧文、そしてダイアクリティカルの付いたベトナム語は 1 文字あたりの幅も
+              行の高さも違う。同じトラックに置いたときの継ぎ目とベースラインはここで見る。
+              `direction="end"` は読み方向の逆に流れる版で、`dir="rtl"` では両方が反転する。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <Marquee gap={6} speed="slow" label="多言語の見出し">
+                <Text size="sm">品質保証部 · 月次レビュー</Text>
+                <Text size="sm">Quality Assurance · Monthly review</Text>
+                <Text size="sm">Đảm bảo chất lượng · Đánh giá hàng tháng</Text>
+              </Marquee>
+              <Separator />
+              <Marquee gap={6} speed="fast" direction="end" label="多言語の見出し・逆方向">
+                <Text size="sm">品質保証部 · 月次レビュー</Text>
+                <Text size="sm">Quality Assurance · Monthly review</Text>
+                <Text size="sm">Đảm bảo chất lượng · Đánh giá hàng tháng</Text>
+              </Marquee>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>止まった状態 · WebAIM の推奨する既定</CardTitle>
+            <CardDescription>
+              `defaultPlay={false}` で始めると、内容は止まったまま読める。停止中もリンクは Tab
+              で辿れて、押せる。動いている最中にトラック内へフォーカスが入った場合も自動で止まる
+              （動いているリンクは押せないため）。ボタンの名前は「次に起きること」を言う。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Marquee defaultPlay={false} fade label="社内のお知らせ">
+              <Text size="sm">2026-10-01 · 社内システム定期メンテナンス</Text>
+              <Link href="#maintenance">詳細</Link>
+              <Text size="sm">2026-10-14 · 新しい経費申請フォームに切替</Text>
+              <Link href="#expense">申請の手順</Link>
+            </Marquee>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>`play` で外から止める</CardTitle>
+            <CardDescription>
+              制御された `play` / `onPlayChange` は、画面全体の「動きを止める」1
+              つのスイッチから複数のトラックを同時に止めるためにある。各トラックの停止ボタンは
+              そのまま残る（2.2.2 の要件は個々の操作で満たす）。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <Flex align="center" gap="sm">
+                <Switch
+                  id="stop-all-motion"
+                  checked={motion}
+                  onCheckedChange={setMotion}
+                  aria-label="このページの動きを有効にする"
+                />
+                <Text size="sm">
+                  {motion ? "このページの動きは有効" : "このページの動きは停止中"}
+                </Text>
+              </Flex>
+              <Marquee play={motion} onPlayChange={setMotion} label="取引先ロゴ・上段">
+                {PARTNERS.slice(0, 4).map((name) => (
+                  <Text key={name} size="sm" tone="muted">
+                    {name}
+                  </Text>
+                ))}
+              </Marquee>
+              <Marquee
+                play={motion}
+                onPlayChange={setMotion}
+                direction="end"
+                label="取引先ロゴ・下段"
+              >
+                {PARTNERS.slice(4).map((name) => (
+                  <Text key={name} size="sm" tone="muted">
+                    {name}
+                  </Text>
+                ))}
+              </Marquee>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>使う前に読むこと</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="sm">
+              <Heading level={3}>止められる動きでも、止まっている方が良いことは多い</Heading>
+              <Text tone="muted">
+                自動で流れる内容は Nielsen Norman Group も WebAIM も勧めていない。NN/g
+                は「ユーザーが操作していないのに画面が動くのは不快で、読み終える前に消える」と書き、
+                WebAIM は「アニメーションは既定で止めておくことを勧める」と書いている。この
+                コンポーネントはその判断を奪わない。止める操作は必ず付いてくるし、`defaultPlay=
+                {"{false}"}` は 1 つのプロパティで済む。動かす理由が言えないなら、静止した `Flex
+                wrap` や `ResponsiveGrid` のロゴウォールの方が良い。
+              </Text>
+              <Heading level={3}>OS のモーション低減設定では一切動かない</Heading>
+              <Text tone="muted">
+                `prefers-reduced-motion: reduce` のとき、クローンも停止ボタンも作らず、1
+                件ぶんの内容を横スクロールできる領域として出す。横方向の平行移動は前庭系の
+                トリガーそのもので、控えめにする版というものが無いため（WCAG 2.2 SC 2.2.2 / SC
+                2.3.3）。
+              </Text>
+              <Heading level={3}>テーマ側のつまみ</Heading>
+              <Text tone="muted">
+                --marquee-interval · --marquee-interval-slow · --marquee-interval-fast ·
+                --marquee-gap-inline · --marquee-mask-width。時間はモーション層
+                （foundation.css）に、幾何はコンポーネント層（tokens/components/marquee.css）にある。
+              </Text>
+            </Flex>
+          </CardContent>
+        </Card>
+      </Flex>
+    </PageContainer>
+  );
+}

package/docs/foundation/_theme-editor-scope.ts

@@ -0,0 +1,222 @@
+/**
+ * What the Theme Editor page needs that is NOT React: the repo's own brand derivation, the two
+ * stylesheet facts it takes as arguments, and the ONE style object that makes a previewed seed
+ * actually reach the components under it.
+ *
+ * `deriveBrand` is `scripts/gen-brand.mjs`'s body (src/tokens/__tests__/brand-derivation.ts).
+ * Importing it — rather than porting it — is why the page's export and `pnpm gen:brand` emit the
+ * same bytes for the same hex. `wcag-contrast.ts`'s own opening line says why there is one copy of
+ * the luminance formula; this is the same argument one level up.
+ */
+import type { CSSProperties } from "react";
+
+import {
+  asTriplet,
+  deriveBrand,
+  triplet,
+  type BrandChannels,
+  type BrandTheme,
+  type Hsl,
+} from "../../src/tokens/__tests__/brand-derivation";
+
+export {
+  AA_TEXT,
+  NON_TEXT,
+  asTriplet,
+  contrast,
+  deriveBrand,
+  hslToRgb,
+  parseHex,
+  toHex,
+  toHsl,
+  round,
+} from "../../src/tokens/__tests__/brand-derivation";
+export type {
+  Brand,
+  BrandChannels,
+  BrandTheme,
+  ContrastRow,
+  Hsl,
+} from "../../src/tokens/__tests__/brand-derivation";
+
+/* ── what the stylesheet says, asked of the browser rather than copied here ─────────────────── */
+
+/**
+ * `gen:brand` reads `--background` and the three `-channels` expressions out of `foundation.css`
+ * and `derived.css` with `node:fs`. A page has no filesystem, and a literal copied into this file
+ * would be a third place the canvas colour lives — stale the first time someone retunes the spine.
+ * So the page asks the DOCUMENT, which is the same declarations after the same cascade.
+ *
+ * The CANVASES come from the CSSOM rather than `getComputedStyle`, because the page needs BOTH at
+ * once and an element can only be in one theme at a time: read live, a page rendered under
+ * `data-theme="dark"` would report the dark canvas as the light one and the whole dark-seed search
+ * would target the wrong number, silently. The CSSOM carries both declarations side by side no
+ * matter which theme is on screen.
+ *
+ * The CHANNELS are the opposite case: `--primary-hover-darken-channels` and its three siblings are
+ * declared once at `:root` and never re-scoped (`.dark` only repoints `--primary-hover-channels`
+ * AT one of them), so a computed read is correct under any theme and is one line instead of a walk.
+ */
+export type ThemeSpine = { lightCanvas: Hsl; darkCanvas: Hsl; channels: BrandChannels };
+
+/** Every style rule in the document, walking into `@layer` / `@media` / `@supports` and nesting. */
+function* styleRules(rules: CSSRuleList): Generator<CSSStyleRule> {
+  for (const rule of Array.from(rules)) {
+    if ("selectorText" in rule) yield rule as CSSStyleRule;
+    const nested = (rule as CSSGroupingRule).cssRules;
+    if (nested) yield* styleRules(nested);
+  }
+}
+
+/** The LAST `--background` declared by a rule this selector test accepts — cascade order. */
+function canvasFrom(accepts: (selector: string) => boolean): Hsl | null {
+  let found: Hsl | null = null;
+  for (const sheet of Array.from(document.styleSheets)) {
+    let rules: CSSRuleList;
+    try {
+      rules = sheet.cssRules;
+    } catch {
+      /* A cross-origin sheet refuses `cssRules`. Ours are same-origin; skip anything else. */
+      continue;
+    }
+    for (const rule of styleRules(rules)) {
+      if (!accepts(rule.selectorText)) continue;
+      const value = rule.style.getPropertyValue("--background").trim();
+      if (!value) continue;
+      try {
+        found = triplet(value);
+      } catch {
+        /* Not a plain `H S% L%` triple — not a canvas this derivation can use. */
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * The probe fallback, for the one case the CSSOM cannot answer: a sheet the document can paint from
+ * but not read. It costs a layout, so it only runs when the walk came back empty.
+ */
+function canvasByProbe(dark: boolean): Hsl | null {
+  const probe = document.createElement("div");
+  if (dark) probe.className = "dark";
+  document.body.append(probe);
+  try {
+    const value = getComputedStyle(probe).getPropertyValue("--background").trim();
+    return value ? triplet(value) : null;
+  } catch {
+    return null;
+  } finally {
+    probe.remove();
+  }
+}
+
+const channel = (name: string) =>
+  getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+
+/** The spine this document is actually painting, or `null` when it cannot be read at all. */
+export function readThemeSpine(): ThemeSpine | null {
+  const lightCanvas = canvasFrom((s) => s.trim() === ":root") ?? canvasByProbe(false);
+  const darkCanvas = canvasFrom((s) => /\[data-theme=["']?dark/.test(s)) ?? canvasByProbe(true);
+  const channels: BrandChannels = {
+    hoverDarken: channel("--primary-hover-darken-channels"),
+    activeDarken: channel("--primary-active-darken-channels"),
+    hoverLighten: channel("--primary-hover-lighten-channels"),
+  };
+  if (!lightCanvas || !darkCanvas) return null;
+  if (!channels.hoverDarken || !channels.activeDarken || !channels.hoverLighten) return null;
+  return { lightCanvas, darkCanvas, channels };
+}
+
+/* ── the scope a preview pane declares ──────────────────────────────────────────────────────── */
+
+/**
+ * THE THREE TOKENS `gen:brand` EMITS ARE THE THREE A SCOPE MUST DECLARE, and that is not a
+ * coincidence — it is the freeze rule (docs/TOKENS.md) read from the other end.
+ *
+ * `--primary` and `--primary-foreground` are ordinary roles: declare them on the pane and every
+ * descendant paints from them, including `--primary-hover` and `--text-link`, which are `initial`
+ * knobs whose defaults re-resolve at the element that paints (gh#678, gh#664). Writing THOSE here
+ * is the drift `gen:brand` refuses to emit, so this does not write them either.
+ *
+ * `--ring` is the one that bites. `derived.css` declares `--ring: var(--primary)` — and a `var()`
+ * substitutes where it is DECLARED, so at `:root` it computed against the package's own seed and
+ * inherits that frozen answer into every subtree. The dark pane escapes by accident (it carries
+ * `.dark`, and `derived.css` re-declares `--ring: var(--primary)` in that block too, which
+ * re-substitutes on the pane); the LIGHT pane does not, and a focus ring in the old brand colour
+ * on a re-themed button is exactly the defect. `derived.css` says so in as many words: "a
+ * `--primary` scoped BELOW `<html>` does not reach `--ring` … a nested scope sets `--ring`
+ * itself". So both panes set it, which is also what a consumer's `:root` gets from `gen:brand`.
+ *
+ * The `-channels` PAIR is written only when the seed's label runs against the theme's default,
+ * because that is the one thing CSS cannot infer: the label decides which way a state steps, and
+ * only the author knows the label. It is a role-mirror, so it is written as `var(--…-channels)`
+ * and never as a resolved literal.
+ */
+export function previewScope(theme: BrandTheme): CSSProperties {
+  const scope: Record<string, string> = {
+    "--primary": asTriplet(theme.seed),
+    "--primary-foreground": asTriplet(theme.label),
+    "--ring": asTriplet(theme.seed),
+  };
+  if (theme.repointsChannels) {
+    scope["--primary-hover-channels"] = `var(--primary-hover-${theme.polarity}-channels)`;
+    scope["--primary-active-channels"] = `var(--primary-active-${theme.polarity}-channels)`;
+  }
+  return scope as CSSProperties;
+}
+
+/* ── the seeds a demo must not avoid ────────────────────────────────────────────────────────── */
+
+/**
+ * AN EDITOR THAT ONLY DEMOS A NICE BLUE PROVES NOTHING. Each of these is here because it produces
+ * an answer the happy path hides; `hex` is the only input, everything else is measured.
+ */
+export type SeedPreset = {
+  id: "godx" | "blue" | "very-light" | "very-dark" | "sunflower";
+  hex: string;
+};
+
+export const SEED_PRESETS: SeedPreset[] = [
+  /* The package's own `--primary`: the export must reproduce foundation.css's light block. */
+  { id: "godx", hex: "#7A00FF" },
+  /* An ordinary, well-behaved brand — every row clears, so a passing readout is visible too. */
+  { id: "blue", hex: "#2563EB" },
+  /* Near-white: the label flips to black and the fill cannot clear 3:1 on a near-white canvas. */
+  { id: "very-light", hex: "#FFF9C4" },
+  /* Near-black: the dark-seed search runs all the way to pure white to hold parity. */
+  { id: "very-dark", hex: "#0B0B14" },
+  /* A dark label in light and a light label in dark — the seed that repoints the `-channels`
+   * pair in BOTH theme blocks, which nothing else here exercises. */
+  { id: "sunflower", hex: "#F5D60A" },
+];
+
+/** One place that knows how a hex becomes a brand, so the page never calls `deriveBrand` twice. */
+export function brandFor(
+  spine: ThemeSpine,
+  hex: string,
+  name: string,
+  foreground: string | null,
+  darkLightness: number | null,
+) {
+  return deriveBrand({ hex, name, foreground, darkLightness, ...spine });
+}
+
+/**
+ * THE COMMAND THAT REPRODUCES THIS EXPORT, or `null` when nothing does.
+ *
+ * The seed and the forced label are both `gen:brand` flags, so those exports are byte-identical to
+ * what the CLI writes and the page can say which command to run. An AUTHORED dark lightness is
+ * not: the generator searches for parity and has no flag to override it, so the page has to stop
+ * claiming agreement rather than print a command that emits something else.
+ */
+export function genBrandCommand(
+  hex: string,
+  name: string,
+  foreground: string | null,
+  darkLightnessOverridden: boolean,
+): string | null {
+  if (darkLightnessOverridden) return null;
+  const flags = foreground ? ` --foreground '${foreground}'` : "";
+  return `pnpm gen:brand '${hex}' --name ${name}${flags}`;
+}

package/docs/foundation/density.tsx

@@ -123,7 +123,12 @@ export default function Demo() {
             </CardDescription>
           </CardHeader>
           <CardContent>
-            <Flex direction="row" gap="lg" align="start" wrap>
+            {/* A STACK ON A PHONE, said with `direction` rather than left to `wrap`.
+                `wrap` never fired here: each column carries `min-w-0 flex-1`, and an item that
+                may shrink to nothing never reaches the wrap threshold — so at 375px this was
+                three 92px columns, and the unbreakable `density="comfortable"` label painted
+                36px over its neighbour with no scrollport to reach it. */}
+            <Flex direction={{ base: "col", md: "row" }} gap="lg" align="start" wrap>
               {density.map((d) => (
                 <Flex key={d.cls} direction="col" gap="sm" className="min-w-0 flex-1 sm:min-w-72">
                   <Flex direction="row" align="center" justify="between" gap="sm">
@@ -154,7 +159,12 @@ export default function Demo() {
             </CardDescription>
           </CardHeader>
           <CardContent>
-            <Flex direction="row" gap="lg" align="start" wrap>
+            {/* A STACK ON A PHONE, said with `direction` rather than left to `wrap`.
+                `wrap` never fired here: each column carries `min-w-0 flex-1`, and an item that
+                may shrink to nothing never reaches the wrap threshold — so at 375px this was
+                three 92px columns, and the unbreakable `density="comfortable"` label painted
+                36px over its neighbour with no scrollport to reach it. */}
+            <Flex direction={{ base: "col", md: "row" }} gap="lg" align="start" wrap>
               <Flex direction="col" gap="sm" className="min-w-0 flex-1 sm:min-w-72">
                 <Text size="xs" mono>
                   density=&quot;compact&quot;

package/docs/foundation/spacing.tsx

@@ -22,6 +22,9 @@ const rawScale = [
   "--space-8",
   "--space-10",
   "--space-12",
+  // The DISPLAY end of the grid (gh#831) — Carbon $spacing-11 / $spacing-12, for marketing bands.
+  "--space-20",
+  "--space-24",
 ];
 
 const phiScale = [
@@ -36,6 +39,8 @@ const layoutScale = [
   { token: "--space-page-x", role: "page gutter X (PageContainer)" },
   { token: "--space-page-y", role: "page gutter Y (PageContainer)" },
   { token: "--space-section", role: "section gap (= --phi-0)" },
+  { token: "--space-section-band", role: "marketing band padding-block (= --space-20)" },
+  { token: "--space-section-hero", role: "hero band padding-block (= --space-24)" },
   { token: "--space-stack-xs", role: "Flex gap='xs'" },
   { token: "--space-stack-sm", role: "Flex gap='sm'" },
   { token: "--space-stack-md", role: "Flex gap='md' (default · = --phi-0)" },