@charcoal-ui/react 6.0.0-rc.0 → 6.0.0-rc.2

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>

package/src/components/Carousel/__snapshots__/index.css.snap

@@ -0,0 +1,274 @@
+.charcoal-carousel {
+  position: relative;
+  display: block;
+}
+
+.charcoal-carousel[data-full-width='true'] {
+  width: 100vw;
+  margin-inline: calc(50% - 50vw);
+}
+
+.charcoal-carousel__viewport {
+  position: relative;
+}
+
+.charcoal-carousel__scroller {
+  position: relative;
+  display: flex;
+  gap: 24px;
+  overflow-x: auto;
+  overflow-y: hidden;
+  overscroll-behavior-x: contain;
+  scroll-behavior: smooth;
+  scrollbar-width: none;
+  outline: none;
+}
+
+.charcoal-carousel__scroller::-webkit-scrollbar {
+  display: none;
+}
+
+.charcoal-carousel__scroller[data-focus-visible] {
+  box-shadow: 0 0 0 4px rgba(0, 150, 250, 0.32);
+}
+
+.charcoal-carousel[data-size='S'] .charcoal-carousel__scroller {
+  gap: 0;
+}
+
+/* スクロールスナップ type は prop（scrollSnap.type）で scroller に出し分ける。
+   align は基底 .charcoal-carousel__item の後（後述）に置く（no-descending-specificity 回避）。
+   未指定時の既定（M=none / S=mandatory / align=center）は JS 側で data 属性に解決する。 */
+
+.charcoal-carousel[data-scroll-snap-type='none'] .charcoal-carousel__scroller {
+  scroll-snap-type: none;
+}
+
+.charcoal-carousel[data-scroll-snap-type='proximity'] .charcoal-carousel__scroller {
+  scroll-snap-type: x proximity;
+}
+
+.charcoal-carousel[data-scroll-snap-type='mandatory'] .charcoal-carousel__scroller {
+  scroll-snap-type: x mandatory;
+}
+
+/* グラデーション: はみ出してスクロール可能な側のみ、端のアイテムを背景色（白）へ
+   フェードさせる。mask による透過ではなく、72px の「背景色→透明」オーバーレイを
+   ビューポートに重ねて白で覆う。スクロール可能な側だけ data-can-prev/next で出し分ける。 */
+
+.charcoal-carousel[data-has-gradient='true'] .charcoal-carousel__viewport::before, .charcoal-carousel[data-has-gradient='true'] .charcoal-carousel__viewport::after {
+  content: '';
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 72px;
+  pointer-events: none;
+  opacity: 0;
+  transition: 0.2s opacity;
+  z-index: 1;
+}
+
+.charcoal-carousel[data-has-gradient='true'] .charcoal-carousel__viewport::before {
+  left: 0;
+  background: linear-gradient(to right, #fff, transparent);
+}
+
+.charcoal-carousel[data-has-gradient='true'] .charcoal-carousel__viewport::after {
+  right: 0;
+  background: linear-gradient(to left, #fff, transparent);
+}
+
+.charcoal-carousel[data-has-gradient='true'][data-can-prev='true'] .charcoal-carousel__viewport::before {
+  opacity: 1;
+}
+
+.charcoal-carousel[data-has-gradient='true'][data-can-next='true'] .charcoal-carousel__viewport::after {
+  opacity: 1;
+}
+
+.charcoal-carousel__item {
+  flex: 0 0 auto;
+  min-width: 0;
+}
+
+.charcoal-carousel[data-size='S'] .charcoal-carousel__item {
+  flex: 0 0 100%;
+}
+
+/* scroll-snap-align は prop（scrollSnap.align）で出し分ける。基底 .charcoal-carousel__item
+   より後に置くことで no-descending-specificity を回避する。 */
+
+.charcoal-carousel[data-scroll-snap-align='center'] .charcoal-carousel__item {
+  scroll-snap-align: center;
+}
+
+.charcoal-carousel[data-scroll-snap-align='start'] .charcoal-carousel__item {
+  scroll-snap-align: start;
+}
+
+/* ── Navigation Buttons (charcoal IconButton, variant=Overlay size=S) ── */
+
+/* マスクと同じ 72px 1fr 72px グリッド。各ボタンは 72px ゾーンの中央に置く。 */
+
+.charcoal-carousel__navigation {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  display: grid;
+  grid-template-columns: 72px 1fr 72px;
+  align-items: center;
+  /* 白フェード（z-index: 1）より上にボタンを表示する */
+  z-index: 2;
+  /* sandbox 同様、通常は隠してカルーセル hover 時にフェードイン表示する。 */
+  opacity: 0;
+  transition: 0.4s opacity;
+}
+
+.charcoal-carousel__navigation[data-visible='false'] {
+  display: none;
+}
+
+/* hover で表示。キーボード操作でも到達できるよう focus-within でも表示する。 */
+
+.charcoal-carousel:hover .charcoal-carousel__navigation, .charcoal-carousel:focus-within .charcoal-carousel__navigation {
+  opacity: 1;
+}
+
+.charcoal-carousel__navigation__item {
+  pointer-events: auto;
+}
+
+.charcoal-carousel__navigation__item[data-direction='prev'] {
+  grid-column: 1;
+  justify-self: center;
+}
+
+.charcoal-carousel__navigation__item[data-direction='next'] {
+  grid-column: 3;
+  justify-self: center;
+}
+
+/* スクロール端では非表示。IconButton の disabled スタイル(opacity:0.32)より
+   高い詳細度で打ち消すため、ルートを前置する。 */
+
+.charcoal-carousel .charcoal-carousel__navigation__item[data-hidden='true'] {
+  opacity: 0;
+  pointer-events: none;
+}
+
+/* タッチデバイスではナビゲーションボタンを出さず、スワイプ操作に委ねる。 */
+
+@media (hover: none) and (pointer: coarse) {
+
+.charcoal-carousel__navigation {
+  display: none;
+}
+}
+
+/* ── Indicator: JS Fallback ── */
+
+.charcoal-carousel__indicator {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  height: 40px;
+  gap: 8px;
+}
+
+.charcoal-carousel__indicator[data-visible='false'] {
+  display: none;
+}
+
+.charcoal-carousel__indicator__item {
+  appearance: none;
+  box-sizing: border-box;
+  width: 8px;
+  height: 8px;
+  padding: 0;
+  border: 0;
+  border-radius: 50%;
+  background-color: var(--charcoal-color-text-tertiary-default);
+  cursor: pointer;
+  transition: 0.2s background-color;
+}
+
+.charcoal-carousel__indicator__item:hover {
+  background-color: var(--charcoal-color-text-secondary-default);
+}
+
+.charcoal-carousel__indicator__item:focus-visible {
+  outline: 2px solid rgba(0, 150, 250, 0.56);
+  outline-offset: 2px;
+}
+
+.charcoal-carousel__indicator__item[data-active='true'] {
+  background-color: var(--charcoal-color-text-default);
+}
+
+/* ── CSS Scroll Markers (progressive enhancement) ── */
+
+/* CSS Scroll Markers / Anchor Positioning は新しい仕様で、stylelint がプロパティ・
+   擬似要素・擬似クラスを未知と判定するため、この @supports ブロックでは該当ルールを無効化する。 */
+/* stylelint-disable property-no-unknown, selector-pseudo-element-no-unknown, selector-pseudo-class-no-unknown */
+
+@supports (scroll-marker-group: after) {
+
+.charcoal-carousel[data-indicator='true'] {
+  padding-bottom: 40px;
+}
+
+.charcoal-carousel__scroller {
+  anchor-name: --charcoal-carousel;
+  scroll-marker-group: after;
+}
+
+.charcoal-carousel__scroller::scroll-button(*) {
+  content: none;
+}
+
+.charcoal-carousel__scroller::scroll-marker-group {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  height: 40px;
+  gap: 8px;
+  position: absolute;
+  position-anchor: --charcoal-carousel;
+  top: anchor(bottom);
+  justify-self: anchor-center;
+}
+
+.charcoal-carousel[data-indicator='false'] .charcoal-carousel__scroller {
+  scroll-marker-group: none;
+}
+
+.charcoal-carousel__item::scroll-marker {
+  content: '';
+  width: 8px;
+  height: 8px;
+  border: 0;
+  border-radius: 50%;
+  background-color: var(--charcoal-color-text-tertiary-default);
+  cursor: pointer;
+  transition: 0.2s background-color;
+}
+
+.charcoal-carousel__item::scroll-marker:hover {
+  background-color: var(--charcoal-color-text-secondary-default);
+}
+
+.charcoal-carousel__item::scroll-marker:focus {
+  outline: 2px solid rgba(0, 150, 250, 0.56);
+  outline-offset: 2px;
+}
+
+.charcoal-carousel__item::scroll-marker:target-current {
+  background-color: var(--charcoal-color-text-default);
+}
+
+.charcoal-carousel__indicator {
+  display: none;
+}
+}
+/* stylelint-enable property-no-unknown, selector-pseudo-element-no-unknown, selector-pseudo-class-no-unknown */
+

package/src/components/Carousel/carouselStore.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from 'vitest'
+import { createCarouselStore } from './carouselStore'
+
+describe('createCarouselStore', () => {
+  it('初期値', () => {
+    expect(createCarouselStore().getSnapshot()).toEqual({
+      activeIndex: 0,
+      canPrev: false,
+      canNext: false,
+      scroll: null,
+    })
+  })
+
+  it('setActive: 変化なしなら同一参照', () => {
+    const s = createCarouselStore()
+    const a = s.getSnapshot()
+    s.dispatch({ type: 'setActive', index: 0 })
+    expect(s.getSnapshot()).toBe(a)
+    s.dispatch({ type: 'setActive', index: 2 })
+    expect(s.getSnapshot().activeIndex).toBe(2)
+  })
+
+  it('setScrollState: 変化なしなら同一参照', () => {
+    const s = createCarouselStore()
+    s.dispatch({ type: 'setScrollState', canPrev: true, canNext: true })
+    const a = s.getSnapshot()
+    s.dispatch({ type: 'setScrollState', canPrev: true, canNext: true })
+    expect(s.getSnapshot()).toBe(a)
+  })
+
+  it('requestScroll: index と単調増加 nonce', () => {
+    const s = createCarouselStore()
+    s.dispatch({ type: 'requestScroll', index: 3 })
+    expect(s.getSnapshot().scroll).toEqual({ index: 3, nonce: 1 })
+    s.dispatch({ type: 'requestScroll', index: 3 })
+    expect(s.getSnapshot().scroll).toEqual({ index: 3, nonce: 2 })
+  })
+})

package/src/components/Carousel/carouselStore.ts

@@ -0,0 +1,48 @@
+import { createStore, type Store } from './store'
+
+export type CarouselState = Readonly<{
+  activeIndex: number
+  canPrev: boolean
+  canNext: boolean
+  scroll: { index: number; nonce: number } | null
+}>
+
+export type CarouselAction =
+  | { type: 'setActive'; index: number }
+  | { type: 'setScrollState'; canPrev: boolean; canNext: boolean }
+  | { type: 'requestScroll'; index: number }
+
+export type CarouselStore = Store<CarouselState, CarouselAction>
+
+export const INITIAL_CAROUSEL_STATE: CarouselState = {
+  activeIndex: 0,
+  canPrev: false,
+  canNext: false,
+  scroll: null,
+}
+
+const reducer = (
+  state: CarouselState,
+  action: CarouselAction,
+): CarouselState => {
+  switch (action.type) {
+    case 'setActive':
+      return state.activeIndex === action.index
+        ? state
+        : { ...state, activeIndex: action.index }
+    case 'setScrollState':
+      return state.canPrev === action.canPrev &&
+        state.canNext === action.canNext
+        ? state
+        : { ...state, canPrev: action.canPrev, canNext: action.canNext }
+    case 'requestScroll':
+      return {
+        ...state,
+        scroll: { index: action.index, nonce: (state.scroll?.nonce ?? 0) + 1 },
+      }
+  }
+}
+
+export function createCarouselStore(): CarouselStore {
+  return createStore(reducer, INITIAL_CAROUSEL_STATE)
+}