@k8ordo/ui 1.0.0 → 2.0.0

package/docs/references/hooks.md

@@ -1,16 +1,22 @@
 # Hooks
 
-k8ordo UI が提供するカスタムフック。
+The custom hooks `@k8ordo/ui` provides.
 
 ```tsx
 import { useDisclosure, useDeferredDebounce } from '@k8ordo/ui';
 ```
 
-## 状態管理
+These hooks cover UI mechanics: disclosure, timing, DOM observation, and the
+like. State that lives in a place — the URL, a history entry, localStorage,
+memory — is `@k8ordo/state`'s job (`defineLocalState` and friends). There is
+deliberately no `useLocalStorage`, `useSessionStorage`, or `useHash` here: a
+package that owned that state twice would give an app two answers.
+
+## State
 
 ### useDisclosure
 
-開閉状態のトグル管理。
+Toggles open/closed state.
 
 ```tsx
 const { isOpen, open, close, toggle } = useDisclosure();
@@ -18,7 +24,7 @@ const { isOpen, open, close, toggle } = useDisclosure();
 
 ### useControllableState
 
-Controlled / Uncontrolled を透過的に扱うパターン。
+Handles controlled and uncontrolled use transparently.
 
 ```tsx
 const [value, setValue] = useControllableState({
@@ -30,7 +36,7 @@ const [value, setValue] = useControllableState({
 
 ### useStep
 
-ステップカウンター。進む/戻るの制御。
+A step counter with forward/back control.
 
 ```tsx
 const { count, next, back, isDisabledBack, isDisabledNext } = useStep({
@@ -39,86 +45,65 @@ const { count, next, back, isDisabledBack, isDisabledNext } = useStep({
 });
 ```
 
-### useHash
-
-URL ハッシュの読み取り（読み取り専用）。
-
-```tsx
-const hash = useHash(); // string | null
-```
-
-## ストレージ
-
-### useLocalStorage
-
-LocalStorage と同期した状態。`remove` で削除も可能。
-
-```tsx
-const [value, setValue, remove] = useLocalStorage<string>('key', 'default');
-```
-
-### useSessionStorage
-
-SessionStorage と同期した状態。`remove` で削除も可能。
-
-```tsx
-const [value, setValue, remove] = useSessionStorage<string>('key', 'default');
-```
-
-## イベント
+## Events
 
 ### useClickAway
 
-要素外クリックの検知。ref と callback を引数に取る。
+Detects a click outside an element. Takes a ref and a callback.
 
 ```tsx
 const ref = useRef<HTMLDivElement>(null);
 
 useClickAway(ref, (e) => {
-  console.log('外側をクリック');
+  console.log('clicked outside');
 });
 ```
 
-引数:
+Arguments:
 
 - `ref`: `RefObject<T | null>`
 - `callback`: `(e: Event) => void`
-- `enabled`: boolean（デフォルト: `true`）
+- `enabled`: boolean (default: `true`)
 
 ### useHover
 
-ホバー状態の検知。`hoverProps` を要素に spread する。
+Detects the hover state. Spread `hoverProps` onto the element.
 
 ```tsx
 const { isHovered, hoverProps } = useHover();
 
-<div {...hoverProps}>{isHovered ? 'ホバー中' : '通常'}</div>;
+<div {...hoverProps}>{isHovered ? 'hovered' : 'idle'}</div>;
 ```
 
-`hoverProps` は `{ onPointerEnter, onPointerLeave }` を含む。
+`hoverProps` contains `{ onPointerEnter, onPointerLeave }`.
 
-## タイミング
+## Timing
 
-> `useDeferredDebounce` と `useDebouncedTransition` は役割が異なります。
+> `useDeferredDebounce` and `useDebouncedTransition` do different jobs.
 >
-> - **`useDeferredDebounce`**: **描画の遅延**（render defer）。React スケジューラが重い再レンダーを後回しにするだけで、遅延時間の保証はない。副作用（fetch / 外部 API）を間引く用途には使えない。
-> - **`useDebouncedTransition`**: **副作用の間引き**（rate limiting）。指定した `delay` を待ってからアクションを実行し、再呼び出し時には前回の `AbortSignal` を abort する。fetch など「軽々しく連射したくない処理」に使う。
+> - **`useDeferredDebounce`**: **defers rendering**. The React scheduler simply postpones an expensive re-render; there is no guarantee about how long it waits. It cannot be used to throttle side effects (fetch, external APIs).
+> - **`useDebouncedTransition`**: **rate-limits side effects**. It waits for the given `delay` before running the action, and aborts the previous `AbortSignal` when called again. Use it for work you do not want fired in rapid succession, such as fetch.
 
 ### useDeferredDebounce
 
-`useDeferredValue` をラップし、値と「追いついていない」ペンディング状態を返す。入力に応じてリストを絞り込むような **純 UI 用途のみ** 向け。
+Wraps `useDeferredValue` and returns the value plus a pending flag for when it
+has not caught up. **For pure UI purposes only**, such as filtering a list as
+the user types.
 
 ```tsx
 const [deferredValue, isPending] = useDeferredDebounce(inputValue);
 ```
 
-戻り値:
+Returns:
 
 - `[T, boolean]` — `[deferredValue, isPending]`
 
 ### useDebouncedTransition
 
-`startTransition(async)` と `AbortController` を組み合わせ、delay 経過後にアクションを実行する。再呼び出し時は前回のアクションに渡した signal を abort し、action 内が `fetch({ signal })` 等で AbortError を投げても未処理 rejection にはならない。
+Combines `startTransition(async)` with an `AbortController` and runs the action
+once the delay has elapsed. On a repeat call it aborts the signal passed to the
+previous action, so an `AbortError` thrown inside the action by, say,
+`fetch({ signal })` does not become an unhandled rejection.
 
 ```tsx
 const [isPending, run] = useDebouncedTransition(300);
@@ -133,13 +118,13 @@ const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
 };
 ```
 
-戻り値:
+Returns:
 
 - `[boolean, (action: (signal: AbortSignal) => void | Promise<void>) => void]`
 
 ### useInterval
 
-定期実行。
+Runs something on an interval.
 
 ```tsx
 useInterval(() => {
@@ -149,7 +134,7 @@ useInterval(() => {
 
 ### useTimeout
 
-遅延実行。
+Runs something after a delay.
 
 ```tsx
 useTimeout(() => {
@@ -157,11 +142,11 @@ useTimeout(() => {
 }, 3000);
 ```
 
-## DOM・ブラウザ
+## DOM and browser
 
 ### useWindowSize
 
-ウィンドウサイズの取得。
+Reads the window size.
 
 ```tsx
 const { width, height } = useWindowSize();
@@ -169,7 +154,7 @@ const { width, height } = useWindowSize();
 
 ### useWindowResize
 
-ウィンドウリサイズのリスナー。コールバックに `{ width, height }` が渡される。
+Listens for window resizes. The callback receives `{ width, height }`.
 
 ```tsx
 useWindowResize(
@@ -180,14 +165,14 @@ useWindowResize(
 );
 ```
 
-引数:
+Arguments:
 
 - `callback`: `(size: { width: number; height: number }) => void`
 - `options`: `{ enabled?: boolean }`
 
 ### useResize
 
-要素のリサイズ監視（ResizeObserver）。ref を引数に取る。
+Observes an element's size (ResizeObserver). Takes a ref.
 
 ```tsx
 const ref = useRef<HTMLDivElement>(null);
@@ -201,7 +186,7 @@ useResize(
 );
 ```
 
-引数:
+Arguments:
 
 - `ref`: `RefObject<T | null>`
 - `callback`: `(entry: ResizeObserverEntry) => void`
@@ -209,7 +194,7 @@ useResize(
 
 ### useIntersectionObserver
 
-交差オブザーバー。ref を引数に取る。
+An intersection observer. Takes a ref.
 
 ```tsx
 const ref = useRef<HTMLDivElement>(null);
@@ -223,29 +208,29 @@ useIntersectionObserver(
 );
 ```
 
-引数:
+Arguments:
 
 - `ref`: `RefObject<T | null>`
 - `callback`: `(entry: IntersectionObserverEntry) => void`
-- `options`: IntersectionObserver のオプション
+- `options`: IntersectionObserver options
 
 ### useInView
 
-要素の表示状態。ref を引数に取り、boolean を返す。
+Whether an element is in view. Takes a ref and returns a boolean.
 
 ```tsx
 const ref = useRef<HTMLDivElement>(null);
 const isInView = useInView(ref, { threshold: 0.1 });
 ```
 
-引数:
+Arguments:
 
 - `ref`: `RefObject<T | null>`
-- `options`: IntersectionObserver のオプション
+- `options`: IntersectionObserver options
 
 ### useScrollDirection
 
-スクロール方向の検知。X 軸と Y 軸の両方を返す。
+Detects scroll direction, on both axes.
 
 ```tsx
 const { x, y } = useScrollDirection();
@@ -255,48 +240,50 @@ const { x, y } = useScrollDirection();
 
 ### useScrollLock
 
-body のスクロールロック。lock / unlock 関数を返す。
+Locks scrolling on the body. Returns lock and unlock functions.
 
 ```tsx
 const { lock, unlock } = useScrollLock();
 
-// モーダルを開くとき
+// when opening a modal
 lock();
 
-// モーダルを閉じるとき
+// when closing it
 unlock();
 ```
 
 ### useWritingMode
 
-要素の `writing-mode` を検知し、`'horizontal'` または `'vertical'` を返す。`vertical-*` / `sideways-*` はすべて `'vertical'` として正規化される。ResizeObserver で監視し、SSR では `'horizontal'` を返す。
+Detects an element's `writing-mode` and returns `'horizontal'` or `'vertical'`.
+Every `vertical-*` and `sideways-*` value normalizes to `'vertical'`. It
+observes through a ResizeObserver, and returns `'horizontal'` during SSR.
 
 ```tsx
 const ref = useRef<HTMLDivElement>(null);
 const writingMode = useWritingMode(ref); // 'horizontal' | 'vertical'
 ```
 
-引数:
+Arguments:
 
 - `ref`: `RefObject<Element | null>`
 
-戻り値:
+Returns:
 
 - `'horizontal' | 'vertical'`
 
 ### useBreakpoint
 
-Tailwind ブレークポイントの判定。
+Tests a Tailwind breakpoint.
 
 ```tsx
-const isMd = useBreakpoint('md'); // 768px 以上かどうか
+const isMd = useBreakpoint('md'); // whether the viewport is 768px or wider
 ```
 
-## ユーティリティ
+## Utilities
 
 ### useClient
 
-クライアントサイドかどうか。
+Whether we are on the client.
 
 ```tsx
 const isClient = useClient();
@@ -304,11 +291,11 @@ const isClient = useClient();
 
 ### useClipboard
 
-クリップボードの読み書き。
+Reads from and writes to the clipboard.
 
 ```tsx
 const { writeClipboard, readClipboard } = useClipboard();
 
-await writeClipboard('コピーするテキスト');
+await writeClipboard('the text to copy');
 const text = await readClipboard();
 ```

package/docs/references/interaction-design.md

@@ -1,77 +1,77 @@
-# インタラクションデザイン
+# Interaction design
 
-k8ordo UI のインタラクションは「静かな変化」を原則とする。
+Interaction in `@k8ordo/ui` follows one principle: quiet change.
 
-## インタラクティブ状態
+## Interactive states
 
-8つの状態を意識して設計する。
+Design with these eight states in mind.
 
-| 状態     | スタイル                                              |
+| State    | Style                                                 |
 | -------- | ----------------------------------------------------- |
-| Default  | 基本スタイル                                          |
-| Hover    | `hover:bg-bg-mute` — 穏やかな色変化                   |
+| Default  | The base style                                        |
+| Hover    | `hover:bg-bg-mute` — a gentle color shift             |
 | Focus    | `focus-visible:ring-2 focus-visible:ring-border-info` |
 | Active   | `active:bg-bg-emphasize`                              |
 | Disabled | `opacity-50 cursor-not-allowed`                       |
-| Loading  | スピナーまたはスケルトン                              |
+| Loading  | A spinner or a skeleton                               |
 | Selected | `bg-primary-bg-subtle`                                |
 | Error    | `border-border-error` + `text-fg-error`               |
 
-## トランジション
+## Transitions
 
-控えめで自然な動き。
+Restrained, natural motion.
 
-| 用途                 | 推奨設定                                   |
-| -------------------- | ------------------------------------------ |
-| ホバー色変化         | `transition-colors duration-150 ease-out`  |
-| 透過度変化           | `transition-opacity duration-200 ease-out` |
-| サイズ変化を伴う場合 | `transition-all duration-150 ease-out`     |
+| Purpose                        | Recommended setting                        |
+| ------------------------------ | ------------------------------------------ |
+| Hover color change             | `transition-colors duration-150 ease-out`  |
+| Opacity change                 | `transition-opacity duration-200 ease-out` |
+| When size changes are involved | `transition-all duration-150 ease-out`     |
 
-### タイミングの原則
+### Timing principles
 
-- **100ms**: 即時フィードバック（ボタンプレス）
-- **150–200ms**: 標準トランジション（ホバー、フォーカス）
-- **300ms**: 開閉アニメーション（Accordion, Drawer の限度）
-- **300ms を超えない** — 重く感じる
+- **100ms**: immediate feedback (a button press)
+- **150–200ms**: the standard transition (hover, focus)
+- **300ms**: open/close animation (the limit for Accordion, Drawer)
+- **Never exceed 300ms** — it starts to feel heavy
 
-### アニメーションの選択
+### Choosing an animation
 
 ```tsx
-// Good: transition-colors（色だけ変わる）
+// Good: transition-colors (only the color changes)
 className = 'transition-colors hover:bg-bg-mute';
 
-// OK: transition-all（複数のプロパティが変わる場合のみ）
+// OK: transition-all (only when several properties change)
 className = 'transition-all hover:bg-bg-mute hover:scale-[1.02]';
 
-// Bad: bounce, spring 系のイージング
+// Bad: bounce or spring easing
 className = 'animate-bounce';
 ```
 
-## フォーカス管理
+## Focus management
 
-- `focus-visible` を使う（`focus` ではなく）— マウスクリック時にリングが出ない
-- フォーカスリングは `ring-border-info` で統一
-- `outline-hidden` でデフォルトのアウトラインを消してから ring を適用
+- Use `focus-visible`, not `focus` — no ring appears on a mouse click
+- Keep the focus ring consistent with `ring-border-info`
+- Clear the default outline with `outline-hidden` before applying the ring
 
 ```tsx
 className =
   'focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-border-info';
 ```
 
-## フォームデザイン
+## Form design
 
-- ラベルは入力の上に配置（左配置は日本語で読みにくい）
-- エラーメッセージは入力の直下に `text-fg-error text-sm`
-- 必須マークは `*` でラベルの後ろに
-- バリデーションは送信時に行う（リアルタイムは控えめに）
-- `FormControl` コンポーネントでラベル・エラー表示を統一
+- Put the label above the input (a left-aligned label reads badly in Japanese)
+- Put the error message directly under the input, as `text-fg-error text-sm`
+- Mark required fields with `*` after the label
+- Validate on submit; keep real-time validation to a minimum
+- Use the `FormControl` component so labels and errors stay consistent
 
 ```tsx
 import { FormControl, TextField } from '@k8ordo/ui';
 
 <FormControl
-  label="メールアドレス"
-  errorText="入力してください"
+  label="Email address"
+  errorText="This field is required"
   required
   renderInput={(props) => (
     <TextField {...props} placeholder="example@mail.com" />
@@ -79,17 +79,17 @@ import { FormControl, TextField } from '@k8ordo/ui';
 />;
 ```
 
-## アクセシビリティ
+## Accessibility
 
-- `aria-label` / `aria-describedby` を適切に設定
-- キーボードナビゲーションを確保（Tab, Enter, Escape, 矢印キー）
-- `prefers-reduced-motion` を考慮 — motion ライブラリが自動対応
-- カラーだけに頼らない状態表現（アイコンやテキストを併用）
+- Set `aria-label` / `aria-describedby` where they belong
+- Guarantee keyboard navigation (Tab, Enter, Escape, arrow keys)
+- Respect `prefers-reduced-motion` — the motion library handles it for you
+- Never signal state with color alone; pair it with an icon or text
 
-## やってはいけないこと
+## What not to do
 
-- bounce / spring 系のイージング
-- 300ms を超えるアニメーション
-- ホバーに強い原色（`bg-primary-bg`）を使う
-- `cursor-pointer` をボタン以外に付ける（リンクにも不要）
-- ダブルクリック防止なしの送信ボタン
+- Bounce or spring easing
+- Animation longer than 300ms
+- A strong primary color (`bg-primary-bg`) on hover
+- `cursor-pointer` on anything that is not a button (links do not need it either)
+- A submit button with no double-click guard