@charcoal-ui/react 6.0.0-rc.1 → 6.0.0-rc.3

package/src/__tests__/token-v1-compat.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import postcss, { type Rule } from 'postcss'
+
+// Design Token 1.0互換モードの「見た目の非破壊」を検証する。
+//
+// 移行: 旧 `@charcoal-ui/react/dist/index.css` (v1, --charcoal-* を直接使用)
+//   →  新 コンポーネントCSS (v2, --charcoal-color-* を使用) + `_token_v1.css` remap
+//
+// 非破壊であるためには、各 (セレクタ, プロパティ) で新CSSが使う 1つの --charcoal-color-*
+// が、旧CSSで使われていた「単一の」--charcoal-* に対応していなければならない。同じ新トークンが
+// 箇所ごとに異なる旧トークンに対応するなら、v2 が複数の v1 トークンを統合したということで、
+// remap がどんな値を選んでも一部の箇所で色が変わる = 見た目が壊れる。
+// 例: --charcoal-color-container-neutral-default は Modal 背景 (旧 surface4 = 暗幕) と
+//     Switch (旧 text4) と Checkbox (旧 text3) に使われ、単一値では再現不可。
+//
+// 旧 index.css は charcoal の直前リリース (published v1) を fixtures に取り込んだもの。
+
+const legacyPath = path.resolve(
+  import.meta.dirname,
+  'fixtures/legacy-v1-index.css',
+)
+const componentsDir = path.resolve(import.meta.dirname, '../components')
+
+async function getCssFiles(dir: string): Promise<string[]> {
+  const entries = await fs.readdir(dir, { withFileTypes: true })
+  const results = await Promise.all(
+    entries.map(async (entry) => {
+      const entryPath = path.join(dir, entry.name)
+      if (entry.isDirectory()) return getCssFiles(entryPath)
+      if (entry.isFile() && entry.name.endsWith('.css')) return [entryPath]
+      return []
+    }),
+  )
+  return results.flat()
+}
+
+/** 親 Rule を辿ってネストしたセレクタパスを組み立てる。 */
+function selectorPath(rule: Rule): string {
+  const parts: string[] = []
+  let node: postcss.Container | postcss.Document | undefined = rule
+  while (node && node.type === 'rule') {
+    parts.unshift((node as Rule).selector.replace(/\s+/g, ' ').trim())
+    node = node.parent as postcss.Container | undefined
+  }
+  return parts.join(' >> ')
+}
+
+/** `${selectorPath} | ${prop}` -> 単一 var(--charcoal…) の参照トークン。 */
+function declarationTokens(css: string): Map<string, string> {
+  const root = postcss.parse(css)
+  const map = new Map<string, string>()
+  root.walkDecls((decl) => {
+    const m = decl.value.match(/^var\(\s*(--charcoal-[a-z0-9-]+)\s*\)$/)
+    if (!m || decl.parent?.type !== 'rule') return
+    map.set(`${selectorPath(decl.parent as Rule)} | ${decl.prop}`, m[1])
+  })
+  return map
+}
+
+const legacy = declarationTokens(await fs.readFile(legacyPath, 'utf-8'))
+const modern = new Map<string, string>()
+for (const file of await getCssFiles(componentsDir)) {
+  for (const [key, token] of declarationTokens(
+    await fs.readFile(file, 'utf-8'),
+  )) {
+    modern.set(key, token)
+  }
+}
+
+// 新旧で一致する (セレクタ, プロパティ) について 新トークン -> {旧トークン…}
+const correspondence = new Map<string, Map<string, string>>()
+for (const [key, newToken] of modern) {
+  if (!legacy.has(key)) continue
+  if (!newToken.startsWith('--charcoal-color-')) continue
+  if (!correspondence.has(newToken)) correspondence.set(newToken, new Map())
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  correspondence.get(newToken)!.set(key, legacy.get(key)!)
+}
+
+describe('Design Token 1.0互換: 旧 index.css の見た目を壊さない', () => {
+  it('新トークンは旧の単一 --charcoal-* に対応する (v2 でのトークン統合による破壊がない)', () => {
+    const breaking = [...correspondence]
+      .map(([newToken, byKey]) => ({
+        newToken,
+        oldTokens: [...new Set(byKey.values())].sort(),
+        usages: [...byKey.entries()].map(([k, v]) => `${k} → ${v}`),
+      }))
+      .filter(({ oldTokens }) => oldTokens.length > 1)
+      .map(
+        ({ newToken, oldTokens, usages }, index) =>
+          `${index + 1}) ${newToken} は旧の {${oldTokens.join(', ')}} を破壊的に統合:\n    - ${usages.join('\n    - ')}`,
+      )
+      .join('\n')
+
+    expect(breaking).toMatchInlineSnapshot(`
+      "1) --charcoal-color-text-default は旧の {--charcoal-text1, --charcoal-text2} を破壊的に統合:
+          - .charcoal-button | color → --charcoal-text2
+          - .charcoal-checkbox__label_div | color → --charcoal-text2
+          - .charcoal-ui-dropdown-selector-text | color → --charcoal-text2
+          - .charcoal-field-label | color → --charcoal-text1
+          - .charcoal-modal-header-title | color → --charcoal-text1
+          - .charcoal-multi-select-label | color → --charcoal-text2
+          - .charcoal-radio__label_div | color → --charcoal-text2
+          - .charcoal-switch__label_div | color → --charcoal-text2
+      2) --charcoal-color-border-default は旧の {--charcoal-text3, --charcoal-text4} を破壊的に統合:
+          - .charcoal-checkbox-input:not(:checked) | border-color → --charcoal-text4
+          - .charcoal-radio-input:not(:checked) | border-color → --charcoal-text3
+      3) --charcoal-color-icon-tertiary-default は旧の {--charcoal-text3, --charcoal-text4} を破壊的に統合:
+          - .charcoal-hint-text-icon | color → --charcoal-text3
+          - .charcoal-loading-spinner | color → --charcoal-text4
+      4) --charcoal-color-container-neutral-default は旧の {--charcoal-text3, --charcoal-text4} を破壊的に統合:
+          - .charcoal-multi-select-input[type='checkbox'] | background-color → --charcoal-text3
+          - .charcoal-switch-input | background-color → --charcoal-text4"
+    `)
+  })
+})

package/src/__tests__/token-v1-remap.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from 'vitest'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import postcss from 'postcss'
+
+// Design Token 1.0互換モード (`@charcoal-ui/theme/css/_token_v1.css`) の remap を検証する。
+//
+// アプリは 1.0互換 (`_token_v1.css`) か 2.0 (`_variables_*.css`) のいずれかで --charcoal-color-*
+// を供給し、コンポーネント実装CSS (`@charcoal-ui/react`) がそれを消費する。remap が
+// 「壊さない・冗長でない・正しい」ことを次で担保する:
+//   1. 非破壊: コンポーネントが使う --charcoal-color-* は全て remap 経由で解決できる。
+//   2. 正しさ: --charcoal-color-* 同士の参照は全て定義済みで循環しない。重複定義がない。
+//   3. 冗長でない: 2.0 API にも無く・内部参照も無く・コンポーネントも使わないトークンを持たない。
+
+const cssDir = path.resolve(import.meta.dirname, '../../../theme/src/css')
+const tokenV1Path = path.join(cssDir, '_token_v1.css')
+const variables2Path = path.join(cssDir, '_variables_light.css')
+const componentsDir = path.resolve(import.meta.dirname, '../components')
+
+const COLOR_PREFIX = '--charcoal-color-'
+const colorVarsIn = (value: string): string[] =>
+  [...value.matchAll(/var\(\s*(--charcoal-color-[a-z0-9-]+)/g)].map((m) => m[1])
+
+async function getCssFiles(dir: string): Promise<string[]> {
+  const entries = await fs.readdir(dir, { withFileTypes: true })
+  const results = await Promise.all(
+    entries.map(async (entry) => {
+      const entryPath = path.join(dir, entry.name)
+      if (entry.isDirectory()) return getCssFiles(entryPath)
+      if (entry.isFile() && entry.name.endsWith('.css')) return [entryPath]
+      return []
+    }),
+  )
+  return results.flat()
+}
+
+/** --charcoal-color-* の定義 (prop -> value) を収集。重複も検出。 */
+function parseColorDefinitions(css: string): {
+  defs: Map<string, string>
+  duplicates: string[]
+} {
+  const defs = new Map<string, string>()
+  const duplicates: string[] = []
+  postcss.parse(css).walkDecls((decl) => {
+    if (!decl.prop.startsWith(COLOR_PREFIX)) return
+    if (defs.has(decl.prop)) duplicates.push(decl.prop)
+    defs.set(decl.prop, decl.value)
+  })
+  return { defs, duplicates }
+}
+
+/** 宣言値から使用中の --charcoal-color-* を収集。 */
+function usedColorVars(css: string): Set<string> {
+  const used = new Set<string>()
+  postcss.parse(css).walkDecls((decl) => {
+    for (const v of colorVarsIn(decl.value)) used.add(v)
+  })
+  return used
+}
+
+/** --charcoal-color-* の var() チェインを解決。未定義参照・循環があれば失敗。 */
+function resolve(
+  token: string,
+  defs: Map<string, string>,
+  seen = new Set<string>(),
+): { ok: true } | { ok: false; reason: string } {
+  if (!defs.has(token)) return { ok: false, reason: `undefined ${token}` }
+  if (seen.has(token)) return { ok: false, reason: `cycle at ${token}` }
+  seen.add(token)
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  for (const ref of colorVarsIn(defs.get(token)!)) {
+    const r = resolve(ref, defs, seen)
+    if (!r.ok) return r
+  }
+  return { ok: true } // --charcoal-color-* を含まない = 終端 (--charcoal-* かリテラル)
+}
+
+const { defs: tokenDefs, duplicates } = parseColorDefinitions(
+  await fs.readFile(tokenV1Path, 'utf-8'),
+)
+const variables2Defs = parseColorDefinitions(
+  await fs.readFile(variables2Path, 'utf-8'),
+).defs
+
+const componentCssFiles = await getCssFiles(componentsDir)
+const componentUsed = new Set<string>()
+for (const file of componentCssFiles) {
+  for (const v of usedColorVars(await fs.readFile(file, 'utf-8')))
+    componentUsed.add(v)
+}
+
+describe('Design Token 1.0互換 (_token_v1.css) remap', () => {
+  it('重複定義がない', () => {
+    expect(duplicates).toEqual([])
+  })
+
+  it('全ての --charcoal-color-* が解決する (dangling / 循環がない)', () => {
+    const broken = [...tokenDefs.keys()]
+      .map((token) => ({ token, r: resolve(token, tokenDefs) }))
+      .filter(({ r }) => !r.ok)
+      .map(({ token, r }) => `${token}: ${(r as { reason: string }).reason}`)
+
+    expect(broken).toEqual([])
+  })
+
+  it('冗長トークンがない (2.0 API にも無く・内部参照も無く・コンポーネント未使用)', () => {
+    const internallyReferenced = new Set<string>()
+    for (const value of tokenDefs.values()) {
+      for (const ref of colorVarsIn(value)) internallyReferenced.add(ref)
+    }
+    const redundant = [...tokenDefs.keys()].filter(
+      (t) =>
+        !variables2Defs.has(t) &&
+        !internallyReferenced.has(t) &&
+        !componentUsed.has(t),
+    )
+
+    expect(redundant).toEqual([])
+  })
+
+  it.each(componentCssFiles)(
+    '%s: 使用する --charcoal-color-* は全て _token_v1.css 経由で解決する (非破壊)',
+    async (file) => {
+      const css = await fs.readFile(file, 'utf-8')
+      const unresolved = [...usedColorVars(css)]
+        .map((token) => ({ token, r: resolve(token, tokenDefs) }))
+        .filter(({ r }) => !r.ok)
+        .map(({ token }) => token)
+
+      expect(unresolved).toEqual([])
+    },
+  )
+})

package/src/components/Carousel/CarouselItem.tsx

@@ -0,0 +1,56 @@
+import { useEffect, useRef, type ReactNode } from 'react'
+import type { CarouselStore } from './carouselStore'
+import { observeCenter } from './intersectionObserver'
+import { observeResize } from './resizeObserver'
+
+export type CarouselItemProps = Readonly<{
+  index: number
+  store: CarouselStore
+  onResize: () => void
+  children: ReactNode
+}>
+
+export const CarouselItem = ({
+  index,
+  store,
+  onResize,
+  children,
+}: CarouselItemProps) => {
+  const ref = useRef<HTMLDivElement>(null)
+
+  // activeIndex: 自分が中央に来たら store に報告する（root は親=scroller から導出）。
+  useEffect(() => {
+    const el = ref.current
+    if (!el) return
+    return observeCenter(el, () => store.dispatch({ type: 'setActive', index }))
+  }, [index, store])
+
+  // scrollToItem: 自分宛ての命令でだけ自己スクロールする（再レンダーしない）。
+  useEffect(() => {
+    let lastNonce = store.getSnapshot().scroll?.nonce ?? 0
+    return store.subscribe(() => {
+      const scroll = store.getSnapshot().scroll
+      if (!scroll || scroll.index !== index || scroll.nonce === lastNonce)
+        return
+      lastNonce = scroll.nonce
+      ref.current?.scrollIntoView({
+        behavior: 'smooth',
+        inline: 'center',
+        block: 'nearest',
+      })
+    })
+  }, [index, store])
+
+  // 遅延コンテンツ: 自分のサイズ変化を onResize で通知する。
+  useEffect(() => {
+    const el = ref.current
+    if (!el) return
+    return observeResize(el, onResize)
+  }, [onResize])
+
+  return (
+    <div ref={ref} className="charcoal-carousel__item">
+      {children}
+    </div>
+  )
+}

package/src/components/Carousel/MIGRATION.md

@@ -0,0 +1,117 @@
+# Carousel 移行ガイド（`@charcoal-ui/react-sandbox` → `@charcoal-ui/react`）
+
+`@charcoal-ui/react-sandbox` の `Carousel`（react-spring + styled-components 実装）から、
+`@charcoal-ui/react` の `Carousel`（CSS scroll-snap + store ベース実装）への移行手順をまとめる。
+
+## 移行の要点
+
+- **import 差し替え + `children` → `items` がほぼ唯一の必須変更**。
+- `onScroll` / `onResize` / `onScrollStateChange` / `ref`（`resetScroll()`）/ `defaultScroll` /
+  `hasGradient` は **sandbox と同じシグネチャ**で利用できる（drop-in 互換）。
+- `scrollAmountCoef` は `scrollStep`（関数も可）に名称変更。`fadeInGradient` / `buttonOffset` 系 /
+  `centerItems` は廃止。
+- `size` / `indicator` / `scrollSnap` / `fullWidth` は新規（任意・後方互換）。
+
+## 概要
+
+|                | sandbox (`@charcoal-ui/react-sandbox`) | react (`@charcoal-ui/react`)                    |
+| -------------- | -------------------------------------- | ----------------------------------------------- |
+| スクロール     | react-spring による JS アニメーション  | ネイティブ overflow + CSS `scroll-snap`         |
+| 子要素         | `children`（任意のノード）             | `items: { id; children }[]`                     |
+| インジケーター | なし                                   | CSS `::scroll-marker` / JS フォールバックの dot |
+| スタイル       | styled-components                      | プレーン CSS（`index.css`）                     |
+
+## import
+
+```diff
+- import { Carousel } from '@charcoal-ui/react-sandbox'
++ import { Carousel } from '@charcoal-ui/react'
+```
+
+公開型: `CarouselProps` / `CarouselItem` / `CarouselHandlerRef` / `ScrollAlign` / `ScrollStep` /
+`ScrollStepContext` / `ScrollSnap` / `ScrollSnapType` / `ScrollSnapAlign`。
+
+## 子要素: `children` → `items`
+
+最大の変更点。子ノードを直接渡す形から、`id` 付きの配列に変える。
+sandbox では自前で `flex` ラッパーや `gap` を組んでいたが、新版はレイアウト（`gap: 24px`、S は `0`）を
+コンポーネント側 CSS が持つので、**ラッパーで囲まず 1 スライド 1 要素**で渡す。
+
+```diff
+- <Carousel hasGradient defaultScroll={{ align: 'center' }} scrollAmountCoef={0.75}>
+-   <div style={{ display: 'flex', gap: 8 }}>
+-     {items.map((i) => (
+-       <Slide key={i} />
+-     ))}
+-   </div>
+- </Carousel>
++ <Carousel
++   size="M"
++   hasGradient
++   defaultScroll={{ align: 'center' }}
++   scrollStep={0.75}
++   items={items.map((i) => ({ id: String(i), children: <Slide /> }))}
++ />
+```
+
+`id` はキー安定化（再レンダー・スクロール命令の宛先識別）に使うので、配列内で一意かつ安定した値にする。
+
+## props 対応表
+
+| sandbox                                           | react                                          | 備考                                                                                                      |
+| ------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `children`                                        | `items: { id: string; children: ReactNode }[]` | 上記参照                                                                                                  |
+| `scrollAmountCoef`（既定 `0.75`）                 | `scrollStep`（既定 `0.75`）                    | `number`（表示幅比）に加え `(ctx) => px` の関数も渡せる                                                   |
+| `defaultScroll: { align, offset }`                | `defaultScroll: { align, offset }`             | `align` は `'left' \| 'center' \| 'right'`。ほぼ同等                                                      |
+| `hasGradient`                                     | `hasGradient`（既定 `false`）                  | 実装が mask → 背景色オーバーレイに変更                                                                    |
+| `fadeInGradient`                                  | （廃止）                                       | 常にオーバーレイ式フェード                                                                                |
+| `buttonOffset` / `buttonPadding` / `bottomOffset` | （廃止）                                       | ボタン配置は CSS グリッド（左右 72px ゾーン）に固定                                                       |
+| `centerItems`                                     | （廃止）                                       | レイアウトは `flex` + `gap` 固定                                                                          |
+| `onScroll(left)`                                  | `onScroll(left)`                               | ✅ そのまま対応（scroll で発火）                                                                          |
+| `onResize(width)`                                 | `onResize(width)`                              | ✅ scroller 幅の変化で発火                                                                                |
+| `onScrollStateChange(canScroll)`                  | `onScrollStateChange(canScroll)`               | ✅ `canPrev \|\| canNext` の変化で発火                                                                    |
+| `ref`（`CarouselHandlerRef.resetScroll()`）       | `ref`（`CarouselHandlerRef.resetScroll()`）    | ✅ `forwardRef` で対応。`defaultScroll` の初期位置へ戻す                                                  |
+| —                                                 | `size: 'S' \| 'M'`（既定 `'M'`）               | 新規。`S` は 1 枚全幅 + `mandatory` スナップ                                                              |
+| —                                                 | `navigationButtons?: boolean`                  | 既定は `size === 'M'`                                                                                     |
+| —                                                 | `indicator?: boolean`                          | 既定は `size === 'S'`                                                                                     |
+| —                                                 | `fullWidth?: boolean`（既定 `false`）          | `100vw` 表示                                                                                              |
+| —                                                 | `className?: string`                           | ルートに付与                                                                                              |
+| —                                                 | `scrollSnap?: { type?; align? }`               | `type`: `none`/`proximity`/`mandatory`、`align`: `center`/`start`。未指定で M=none / S=mandatory / center |
+
+## 挙動の変更（移行時に確認すること）
+
+- **ナビゲーションボタンの hover 表示を廃止**: sandbox はカルーセルに hover した時だけボタンが現れ、
+  マウスが離れるとフェードアウトしていた。新版は**常時表示**で、スクロール端でのみ非表示
+  （`canPrev`/`canNext`）。hover-reveal に依存した UI だった場合は要確認。
+- **タッチ端末**: 両実装ともナビゲーションボタンを非表示（`@media (hover: none) and (pointer: coarse)`）。
+- **スナップ**: JS アニメーションから CSS `scroll-snap`（`scroll-snap-align: center`）へ。
+  既定は `M` が `none`（スナップなし。`scrollStep`＝0.75×表示幅ちょうど進む。sandbox の進み量と一致）、
+  `S` が `mandatory`（1 枚全幅で必ずスナップ）。`scrollSnap` prop で `proximity`/`mandatory` も選べる。
+  ※アニメーションは native smooth scroll で、sandbox（react-spring）とイージング/連打時の積算挙動は異なる。
+- **インジケーター**: 新規。`indicator` 有効時に dot を表示（CSS Scroll Markers 対応環境では `::scroll-marker`、
+  非対応環境では JS フォールバック）。
+- **キーボード操作**: スクローラーが `tabIndex={0}` でフォーカス可能になり、`←` / `→` で 1 ステップスクロール。
+  フォーカスリングは charcoal 標準（`box-shadow: 0 0 0 4px rgba(0, 150, 250, 0.32)`）。
+- **グラデーション**: `mask` による透過から、背景色（`#fff`）オーバーレイ方式に変更。
+  ダークモードは現状未対応（背景色固定）。
+
+## スクロール量を細かく制御したい場合
+
+`scrollStep` に関数を渡すと、1 操作あたりの進む量（px）を自前で計算できる。
+
+```tsx
+// 表示幅の比率（sandbox の scrollAmountCoef 相当）
+<Carousel items={items} scrollStep={0.5} />
+
+// 進む px を直接返す（端は残り全部、など）
+<Carousel
+  items={items}
+  scrollStep={({ clientWidth, scrollWidth, scrollLeft, direction }) =>
+    direction === 'next'
+      ? Math.min(clientWidth * 0.8, scrollWidth - clientWidth - scrollLeft)
+      : Math.min(clientWidth * 0.8, scrollLeft)
+  }
+/>
+```
+
+戻り値は「進む量の絶対値（px）」。符号（prev / next）はコンポーネント側で付与する。

package/src/components/Carousel/Migration.mdx

@@ -0,0 +1,8 @@
+import { Meta, Markdown } from '@storybook/addon-docs/blocks'
+import migration from './MIGRATION.md?raw'
+
+{/* 本文は MIGRATION.md を単一ソースとして ?raw で読み込み、ここで描画する */}
+
+<Meta title="react/Carousel/Migration Guide" />
+
+<Markdown>{migration}</Markdown>