sparkle-design 1.0.2 → 1.0.3

package/README.en.md

@@ -39,8 +39,9 @@ This automatically:
 1. Detects your package manager (pnpm / npm / yarn / bun)
 2. Adds `sparkle-design` to dependencies and `tailwindcss` + `@tailwindcss/postcss` to devDependencies
 3. Generates `sparkle.config.json` / `postcss.config.mjs` / Tailwind entry CSS (Next.js: `globals.css`, Vite: `index.css`) if missing
-4. Adds a Sparkle Design guard block and `lint:sparkle` script to `CLAUDE.md`
-5. Generates `sparkle-design.css` and `SparkleHead.tsx`
+4. Writes the Sparkle Design guard block + `lint:sparkle` script to `CLAUDE.md` (and to `AGENTS.md` too when one already exists)
+5. Installs an assistant-specific Stop hook into `.claude/settings.json` / `.cursor/hooks.json` / `.codex/hooks.json` (`lint:sparkle --strict || exit 2`) so findings block the agent from finishing the turn
+6. Generates `sparkle-design.css` and `SparkleHead.tsx` (and for Vite projects, also injects a managed font `<link>` block into `index.html`'s `<head>`)
 
 `--assistant` accepts `claude` / `cursor` / `codex` / `generic`. Existing files are never overwritten.
 
@@ -73,21 +74,31 @@ Customize primary color, fonts, border radius, and more via `sparkle.config.json
 > @import "./sparkle-design.css";
 > ```
 >
-> From `sparkle-design-cli` v2.0.6 onward, `generate` / `setup` **auto-scans your `package.json`** (dependencies / devDependencies) and automatically inserts the matching `@source` directive when it detects `sparkle-design`. No manual config is required. If you want to include additional design system packages, add them to `extend.source-packages` in `sparkle.config.json`; the detected packages and your explicit list will be merged.
+> `sparkle-design-cli` **auto-scans your `package.json`** (dependencies / devDependencies) on `generate` / `setup` and automatically inserts the matching `@source` directive when it detects `sparkle-design`. No manual config is required. If you want to include additional design system packages, add them to `extend.source-packages` in `sparkle.config.json`; the detected packages and your explicit list will be merged. When an existing entry CSS lacks `@import "tailwindcss";` (e.g. straight from `create-vite`), the CLI auto-prepends the canonical import before continuing the patch, and the order of `@import` / `@source` is normalized to comply with the CSS spec, so both Vite and Next.js layouts reach a fully working state in a single setup run.
 
 #### Installing as an AI Agent Skill (optional)
 
-If you use an AI agent such as Claude Code, Codex, or Cursor, you can also install the Sparkle Design skills with [Vercel's skills CLI](https://github.com/vercel-labs/skills) to have the agent walk you through setup.
+If you use an AI agent such as Claude Code, GitHub Copilot, Cursor, Codex, Gemini CLI, or Antigravity, you can install the Sparkle Design skills through the [official `gh skill` command](https://github.blog/changelog/2026-04-16-manage-agent-skills-with-github-cli/) (requires gh CLI v2.90+), which lets the agent guide you through setup.
 
 ```bash
-# Install only the setup-sparkle-design skill
-npx skills add goodpatch/sparkle-design -s setup-sparkle-design
+# Install only the setup-sparkle-design skill (recommended)
+gh skill install goodpatch/sparkle-design setup-sparkle-design --agent claude-code
 
-# Install all skills (setup / add-component / accessibility-checker)
-npx skills add goodpatch/sparkle-design --all
+# Interactively pick multiple skills (setup / add-component / accessibility-checker / change-sparkle-config)
+gh skill install goodpatch/sparkle-design --agent claude-code
+
+# Inspect a skill before installing
+gh skill preview goodpatch/sparkle-design setup-sparkle-design
 ```
 
-After installation, asking the agent to "install Sparkle Design" triggers the `setup-sparkle-design` skill, which inspects the project and guides you through only the missing steps. Use `-a claude-code` / `-a codex` etc. to target a specific agent.
+After installation, asking the agent to "install Sparkle Design" triggers the `setup-sparkle-design` skill, which inspects the project and guides you through only the missing steps. Use `--agent claude-code` / `--agent github-copilot` / `--agent cursor` / `--agent codex` / `--agent gemini` / `--agent antigravity` to target a specific agent (the default for non-interactive runs is `github-copilot`).
+
+> **Fallback if gh CLI is not available**: The same skills are also published via [Vercel's skills CLI](https://github.com/vercel-labs/skills):
+>
+> ```bash
+> npx skills add goodpatch/sparkle-design -s setup-sparkle-design
+> npx skills add goodpatch/sparkle-design --all
+> ```
 
 ### 2. Use components
 
@@ -134,7 +145,7 @@ npx sparkle-design-cli check src
 
 ### Manual installation (advanced)
 
-If you prefer a step-by-step installation without CLI setup, see the [CLI documentation](https://github.com/goodpatch/sparkle-design-cli#readme).
+If you prefer a step-by-step installation without CLI setup, run `npx --yes sparkle-design-cli --help` / `npx --yes sparkle-design-cli generate --help` / `npx --yes sparkle-design-cli setup --help` to see the usage of each subcommand. See also the [sparkle-design-cli page on npm](https://www.npmjs.com/package/sparkle-design-cli).
 
 ## Install individual components
 

package/README.md

@@ -39,8 +39,9 @@ npx --yes sparkle-design-cli setup --assistant claude
 1. パッケージマネージャー（pnpm / npm / yarn / bun）を自動検出
 2. `sparkle-design` を dependencies、`tailwindcss` + `@tailwindcss/postcss` を devDependencies に追加
 3. `sparkle.config.json` / `postcss.config.mjs` / Tailwind エントリ CSS（Next.js: `globals.css`、Vite: `index.css`）を必要に応じて生成
-4. `CLAUDE.md` に Sparkle Design ガードブロックと `lint:sparkle` スクリプトを追加
-5. `sparkle-design.css` と `SparkleHead.tsx` を生成
+4. `CLAUDE.md` / `AGENTS.md`（既存があれば併用書き込み）に Sparkle Design ガードブロックと `lint:sparkle` スクリプトを追加
+5. `--assistant` に応じて `.claude/settings.json` / `.cursor/hooks.json` / `.codex/hooks.json` の Stop hook を自動設定（`lint:sparkle --strict || exit 2` で findings があれば応答終了をブロック）
+6. `sparkle-design.css` と `SparkleHead.tsx` を生成（Vite プロジェクトでは `index.html` の `<head>` 内に font `<link>` の managed block も自動注入）
 
 `--assistant` は `claude` / `cursor` / `codex` / `generic` から選択できます。既存ファイルは上書きされません。
 
@@ -73,21 +74,31 @@ export default function RootLayout({ children }) {
 > @import "./sparkle-design.css";
 > ```
 >
-> `sparkle-design-cli` v2.0.6 以降は、`generate` / `setup` 実行時に **`package.json` の dependencies / devDependencies を自動スキャン** し、`sparkle-design` が含まれていれば該当する `@source` を自動挿入します。`sparkle.config.json` 側で何も設定しなくても動きます。独自のデザインシステムパッケージを併用したい場合のみ `extend.source-packages` に追記すると、自動検出分と合算されます。
+> `sparkle-design-cli` は `generate` / `setup` 実行時に **`package.json` の dependencies / devDependencies を自動スキャン** し、`sparkle-design` が含まれていれば該当する `@source` を自動挿入します。`sparkle.config.json` 側で何も設定しなくても動きます。独自のデザインシステムパッケージを併用したい場合のみ `extend.source-packages` に追記すると、自動検出分と合算されます。`@import "tailwindcss";` が無い既存プロジェクト（`create-vite` 直後など）には canonical な `@import` を自動 prepend し、`@import` と `@source` の順序も CSS 仕様に従って整列するため、Vite / Next.js のどちらのレイアウトでもセットアップ 1 回で動く状態に到達できます。
 
 #### AI エージェントに Skill として導入する場合（任意）
 
-Claude Code / Codex / Cursor などの AI エージェントを使っている場合は、[Vercel の skills CLI](https://github.com/vercel-labs/skills) 経由で Sparkle Design のスキルセットを導入しておくと、会話から誘導してもらうこともできます。
+Claude Code / GitHub Copilot / Cursor / Codex / Gemini CLI / Antigravity などの AI エージェントを使っている場合は、[GitHub 公式の `gh skill` コマンド](https://github.blog/changelog/2026-04-16-manage-agent-skills-with-github-cli/)（gh CLI v2.90 以上）経由で Sparkle Design のスキルセットを導入しておくと、会話から誘導してもらえます。
 
 ```bash
-# setup-sparkle-design スキルだけを導入
-npx skills add goodpatch/sparkle-design -s setup-sparkle-design
+# setup-sparkle-design スキルだけを導入（推奨）
+gh skill install goodpatch/sparkle-design setup-sparkle-design --agent claude-code
 
-# 全スキル（setup / add-component / accessibility-checker）を導入
-npx skills add goodpatch/sparkle-design --all
+# 対話モードで複数スキルをまとめて選択（setup / add-component / accessibility-checker / change-sparkle-config）
+gh skill install goodpatch/sparkle-design --agent claude-code
+
+# インストール前に内容を検査したい場合
+gh skill preview goodpatch/sparkle-design setup-sparkle-design
 ```
 
-導入後に「Sparkle Design を導入して」と依頼すると `setup-sparkle-design` スキルが発動し、プロジェクト状態に合わせて不足ステップだけ案内してくれます。`-a claude-code` / `-a codex` などで対象エージェントを指定することもできます。
+導入後に「Sparkle Design を導入して」と依頼すると `setup-sparkle-design` スキルが発動し、プロジェクト状態に合わせて不足ステップだけ案内してくれます。`--agent` には `claude-code` / `github-copilot` / `cursor` / `codex` / `gemini` / `antigravity` などを指定できます（非対話実行のデフォルトは `github-copilot`）。
+
+> **gh CLI が手元に無い場合の fallback**: [Vercel の skills CLI](https://github.com/vercel-labs/skills) でも同じスキルを配布しています:
+>
+> ```bash
+> npx skills add goodpatch/sparkle-design -s setup-sparkle-design
+> npx skills add goodpatch/sparkle-design --all
+> ```
 
 ### 2. コンポーネントの使用
 
@@ -134,7 +145,7 @@ npx sparkle-design-cli check src
 
 ### 手動インストール（高度な利用）
 
-CLI setup を使わずに段階的に導入したい場合は、[CLI ドキュメント](https://github.com/goodpatch/sparkle-design-cli#readme) を参照してください。
+CLI setup を使わずに段階的に導入したい場合は、`npx --yes sparkle-design-cli --help` / `npx --yes sparkle-design-cli generate --help` / `npx --yes sparkle-design-cli setup --help` で各サブコマンドの使い方を確認できます。npm ページは [sparkle-design-cli on npm](https://www.npmjs.com/package/sparkle-design-cli) を参照してください。
 
 ## 個別コンポーネントの導入
 

package/dist/components/ui/input/index.d.ts

@@ -52,6 +52,27 @@ export interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElem
      * en: Callback function for icon button click
      */
     onIconButtonClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+    /**
+     * トリガーボタンへフォワードする HTML / ARIA 属性。`isTrigger` が true のときのみ有効。
+     * `aria-haspopup` / `aria-expanded` / `aria-controls` のように、Popover や Date Picker と
+     * 連携する際に必要な属性を宣言的に渡すために使用する。
+     *
+     * 以下の属性は Input が内部で制御するため、`triggerProps` で渡しても無視される:
+     * `ref` / `onFocus` / `onBlur` / `type` / `disabled` / `aria-label`（`triggerAriaLabel` が優先）
+     * / `onClick`（`onIconButtonClick` が指定された場合のみ優先。未指定なら `triggerProps.onClick`
+     * が使われる）。アイコンボタン自体の見た目（`icon` / `theme` / `variant` / `size`）も同様に
+     * Input 側で固定される。
+     *
+     * en: HTML / ARIA attributes forwarded to the trigger button. Only applied when
+     *     `isTrigger` is true. Use for attributes like `aria-haspopup`,
+     *     `aria-expanded`, `aria-controls` when integrating with Popover or Date Picker.
+     *     The following are controlled by Input and dropped if passed via
+     *     `triggerProps`: `ref`, `onFocus`, `onBlur`, `type`, `disabled`, `aria-label`
+     *     (the dedicated `triggerAriaLabel` wins), and the visual props
+     *     `icon` / `theme` / `variant` / `size`. `onClick` is overridden only when
+     *     `onIconButtonClick` is provided; otherwise `triggerProps.onClick` is used.
+     */
+    triggerProps?: React.ButtonHTMLAttributes<HTMLButtonElement>;
 }
 /**
  * **概要 / Overview**
@@ -110,6 +131,18 @@ export interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElem
  *   isTrigger
  *   triggerIcon="search"
  * />
+ *
+ * // Popover / Date Picker 連携時は triggerProps で ARIA を宣言的に渡す
+ * <Input
+ *   isTrigger
+ *   triggerIcon="calendar_today"
+ *   triggerAriaLabel="日付を選択"
+ *   triggerProps={{
+ *     "aria-haspopup": "dialog",
+ *     "aria-expanded": open,
+ *     "aria-controls": "date-picker-popover",
+ *   }}
+ * />
  * ```
  *
  * @param {InputProps} props

package/dist/components/ui/input/index.js

@@ -18,6 +18,8 @@ import * as React from "react";
 import { cva } from "class-variance-authority";
 import { cn } from "../../../lib/utils.js";
 import { IconButton } from "../../../components/ui/icon-button/index.js";
+import { useMergeRefs } from "../../../hooks/useMergeRefs.js";
+import { useInputContainerFocus } from "../../../hooks/useInputContainerFocus.js";
 // 入力フィールドのスタイル定義
 const inputVariants = cva("flex gap-0 items-center w-full rounded-action border bg-white transition-colors p-1", {
     variants: {
@@ -72,19 +74,6 @@ const inputVariants = cva("flex gap-0 items-center w-full rounded-action border
         isFocused: false,
     },
 });
-// 複数のrefをマージするユーティリティ関数
-function useMergeRefs(...refs) {
-    return React.useCallback((value) => {
-        refs.forEach(ref => {
-            if (typeof ref === "function") {
-                ref(value);
-            }
-            else if (ref != null) {
-                ref.current = value;
-            }
-        });
-    }, [refs]);
-}
 /**
  * **概要 / Overview**
  *
@@ -142,12 +131,24 @@ function useMergeRefs(...refs) {
  *   isTrigger
  *   triggerIcon="search"
  * />
+ *
+ * // Popover / Date Picker 連携時は triggerProps で ARIA を宣言的に渡す
+ * <Input
+ *   isTrigger
+ *   triggerIcon="calendar_today"
+ *   triggerAriaLabel="日付を選択"
+ *   triggerProps={{
+ *     "aria-haspopup": "dialog",
+ *     "aria-expanded": open,
+ *     "aria-controls": "date-picker-popover",
+ *   }}
+ * />
  * ```
  *
  * @param {InputProps} props
  */
 const Input = React.forwardRef((_a, ref) => {
-    var { className, size, isInvalid = false, isDisabled = false, isTrigger = false, triggerIcon = "edit", triggerAriaLabel, onIconButtonClick, disabled, defaultValue, value, onChange, onBlur, onFocus } = _a, props = __rest(_a, ["className", "size", "isInvalid", "isDisabled", "isTrigger", "triggerIcon", "triggerAriaLabel", "onIconButtonClick", "disabled", "defaultValue", "value", "onChange", "onBlur", "onFocus"]);
+    var { className, size, isInvalid = false, isDisabled = false, isTrigger = false, triggerIcon = "edit", triggerAriaLabel, onIconButtonClick, triggerProps, disabled, defaultValue, value, onChange, onBlur, onFocus } = _a, props = __rest(_a, ["className", "size", "isInvalid", "isDisabled", "isTrigger", "triggerIcon", "triggerAriaLabel", "onIconButtonClick", "triggerProps", "disabled", "defaultValue", "value", "onChange", "onBlur", "onFocus"]);
     // Refs
     const containerRef = React.useRef(null);
     const buttonRef = React.useRef(null);
@@ -191,21 +192,13 @@ const Input = React.forwardRef((_a, ref) => {
             setIsIconButtonFocused(false);
         }
     }, []);
-    // コンテナクリック時にインプットにフォーカスを当てる
-    const handleContainerClick = React.useCallback((e) => {
-        if (isInputDisabled)
-            return;
-        // アイコンボタン上でのクリックを除外
-        if (buttonRef.current &&
-            (buttonRef.current === e.target ||
-                buttonRef.current.contains(e.target))) {
-            return;
-        }
-        // 入力要素が無効でなければフォーカスを当てる
-        if (inputRef.current) {
-            inputRef.current.focus();
-        }
-    }, [isInputDisabled]);
+    // コンテナクリック時にインプットへフォーカスを移すハンドラ（ボタン上のクリックは除外）
+    const excludeRefs = React.useMemo(() => [buttonRef], []);
+    const handleContainerClick = useInputContainerFocus({
+        targetRef: inputRef,
+        isDisabled: isInputDisabled,
+        excludeRefs,
+    });
     // 外部クリックでフォーカスを解除するためのハンドラ
     React.useEffect(() => {
         // 無効状態の場合はイベントリスナーを追加しない
@@ -249,8 +242,13 @@ const Input = React.forwardRef((_a, ref) => {
         // aria-disabled={isInputDisabled}
         // aria-invalid={isInvalid === null ? undefined : isInvalid}
         onClick: handleContainerClick, role: "presentation", tabIndex: -1, children: [_jsx("input", Object.assign({ ref: mergedInputRef, disabled: isInputDisabled, "aria-invalid": isInvalid || undefined, className: cn("w-full h-full bg-transparent border-none outline-hidden focus:outline-hidden", "text-text-high placeholder:text-text-placeholder px-2", isInputDisabled &&
-                    "cursor-not-allowed text-neutral-400 placeholder:text-text-disabled"), onChange: handleChange, onFocus: handleInputFocus, onBlur: handleInputBlur, defaultValue: defaultValue, value: value, "aria-disabled": isInputDisabled }, props)), isTrigger && (_jsx(IconButton, { ref: buttonRef, icon: triggerIcon, theme: "neutral", variant: "ghost", size: iconButtonSize, onClick: onIconButtonClick, isDisabled: isInputDisabled, disabled: isInputDisabled, type: "button" // フォーム内でデフォルトのsubmit動作を防ぐ
-                , "aria-label": triggerAriaLabel, onFocus: handleIconButtonFocus, onBlur: handleIconButtonBlur }))] }));
+                    "cursor-not-allowed text-neutral-400 placeholder:text-text-disabled"), onChange: handleChange, onFocus: handleInputFocus, onBlur: handleInputBlur, defaultValue: defaultValue, value: value, "aria-disabled": isInputDisabled }, props)), isTrigger && (_jsx(IconButton
+            // triggerProps を先に展開し、専用 props (triggerAriaLabel / onIconButtonClick)
+            // と内部制御プロパティで上書きする
+            // en: Spread triggerProps first, then let dedicated props and internal
+            //     control props override them
+            , Object.assign({}, triggerProps, { ref: buttonRef, icon: triggerIcon, theme: "neutral", variant: "ghost", size: iconButtonSize, onClick: onIconButtonClick !== null && onIconButtonClick !== void 0 ? onIconButtonClick : triggerProps === null || triggerProps === void 0 ? void 0 : triggerProps.onClick, isDisabled: isInputDisabled, disabled: isInputDisabled, type: "button" // フォーム内でデフォルトのsubmit動作を防ぐ
+                , "aria-label": triggerAriaLabel !== null && triggerAriaLabel !== void 0 ? triggerAriaLabel : triggerProps === null || triggerProps === void 0 ? void 0 : triggerProps["aria-label"], onFocus: handleIconButtonFocus, onBlur: handleIconButtonBlur })))] }));
 });
 Input.displayName = "Input";
 export { Input, inputVariants };

package/dist/hooks/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright 2026 Goodpatch Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export { useMergeRefs } from "./useMergeRefs";
+export { useInputContainerFocus, type UseInputContainerFocusOptions, } from "./useInputContainerFocus";

package/dist/hooks/index.js

@@ -0,0 +1,6 @@
+/**
+ * Copyright 2026 Goodpatch Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export { useMergeRefs } from "./useMergeRefs.js";
+export { useInputContainerFocus, } from "./useInputContainerFocus.js";

package/dist/hooks/useInputContainerFocus.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Copyright 2026 Goodpatch Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as React from "react";
+/**
+ * `useInputContainerFocus` のオプション
+ * en: Options for `useInputContainerFocus`
+ */
+export interface UseInputContainerFocusOptions<TTarget extends HTMLElement> {
+    /**
+     * クリック時にフォーカスさせるターゲット要素の ref
+     * en: Ref to the target element that should receive focus on container click
+     */
+    targetRef: React.RefObject<TTarget | null>;
+    /**
+     * 無効状態（true のときは何もしない）
+     * en: When true, the handler does nothing
+     */
+    isDisabled?: boolean;
+    /**
+     * クリックがこの ref の要素内で発生したときはフォーカスを移さない
+     * en: When the click originates inside any of these refs, focus is not moved
+     */
+    excludeRefs?: ReadonlyArray<React.RefObject<HTMLElement | null>>;
+}
+/**
+ * コンテナ要素クリック時に、内側のターゲット要素（典型的には `<input>`）へ
+ * フォーカスを移すクリックハンドラを返す hook。
+ *
+ * en: Returns a click handler that forwards focus to a target element (typically
+ *     the inner `<input>`) when the surrounding container element is clicked.
+ *     Clicks that originate within `excludeRefs` are ignored so embedded controls
+ *     (icon buttons, clear buttons, etc.) keep their own click semantics.
+ *
+ * @example
+ * ```tsx
+ * const containerRef = React.useRef<HTMLDivElement>(null);
+ * const inputRef = React.useRef<HTMLInputElement>(null);
+ * const buttonRef = React.useRef<HTMLButtonElement>(null);
+ *
+ * const handleContainerClick = useInputContainerFocus({
+ *   targetRef: inputRef,
+ *   isDisabled,
+ *   excludeRefs: [buttonRef],
+ * });
+ *
+ * return (
+ *   <div ref={containerRef} onClick={handleContainerClick}>
+ *     <input ref={inputRef} />
+ *     <button ref={buttonRef}>...</button>
+ *   </div>
+ * );
+ * ```
+ */
+export declare function useInputContainerFocus<TTarget extends HTMLElement>(options: UseInputContainerFocusOptions<TTarget>): (e: React.MouseEvent) => void;

package/dist/hooks/useInputContainerFocus.js

@@ -0,0 +1,51 @@
+/**
+ * Copyright 2026 Goodpatch Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as React from "react";
+/**
+ * コンテナ要素クリック時に、内側のターゲット要素（典型的には `<input>`）へ
+ * フォーカスを移すクリックハンドラを返す hook。
+ *
+ * en: Returns a click handler that forwards focus to a target element (typically
+ *     the inner `<input>`) when the surrounding container element is clicked.
+ *     Clicks that originate within `excludeRefs` are ignored so embedded controls
+ *     (icon buttons, clear buttons, etc.) keep their own click semantics.
+ *
+ * @example
+ * ```tsx
+ * const containerRef = React.useRef<HTMLDivElement>(null);
+ * const inputRef = React.useRef<HTMLInputElement>(null);
+ * const buttonRef = React.useRef<HTMLButtonElement>(null);
+ *
+ * const handleContainerClick = useInputContainerFocus({
+ *   targetRef: inputRef,
+ *   isDisabled,
+ *   excludeRefs: [buttonRef],
+ * });
+ *
+ * return (
+ *   <div ref={containerRef} onClick={handleContainerClick}>
+ *     <input ref={inputRef} />
+ *     <button ref={buttonRef}>...</button>
+ *   </div>
+ * );
+ * ```
+ */
+export function useInputContainerFocus(options) {
+    const { targetRef, isDisabled = false, excludeRefs } = options;
+    return React.useCallback((e) => {
+        var _a;
+        if (isDisabled)
+            return;
+        if (excludeRefs) {
+            for (const ref of excludeRefs) {
+                const node = ref.current;
+                if (node && (node === e.target || node.contains(e.target))) {
+                    return;
+                }
+            }
+        }
+        (_a = targetRef.current) === null || _a === void 0 ? void 0 : _a.focus();
+    }, [isDisabled, targetRef, excludeRefs]);
+}

package/dist/hooks/useMergeRefs.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright 2026 Goodpatch Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as React from "react";
+/**
+ * 複数の ref を 1 つにまとめる ref コールバックを返す hook
+ * en: Returns a single ref callback that forwards to multiple refs
+ *
+ * @example
+ * ```tsx
+ * const Foo = React.forwardRef<HTMLInputElement, Props>((props, ref) => {
+ *   const innerRef = React.useRef<HTMLInputElement>(null);
+ *   const mergedRef = useMergeRefs(innerRef, ref);
+ *   return <input ref={mergedRef} {...props} />;
+ * });
+ * ```
+ *
+ * @param refs マージ対象の ref。`React.Ref<T>` 互換のもの（callback ref / ref object）。
+ */
+export declare function useMergeRefs<T>(...refs: Array<React.Ref<T> | undefined>): React.RefCallback<T>;

package/dist/hooks/useMergeRefs.js

@@ -0,0 +1,34 @@
+/**
+ * Copyright 2026 Goodpatch Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as React from "react";
+/**
+ * 複数の ref を 1 つにまとめる ref コールバックを返す hook
+ * en: Returns a single ref callback that forwards to multiple refs
+ *
+ * @example
+ * ```tsx
+ * const Foo = React.forwardRef<HTMLInputElement, Props>((props, ref) => {
+ *   const innerRef = React.useRef<HTMLInputElement>(null);
+ *   const mergedRef = useMergeRefs(innerRef, ref);
+ *   return <input ref={mergedRef} {...props} />;
+ * });
+ * ```
+ *
+ * @param refs マージ対象の ref。`React.Ref<T>` 互換のもの（callback ref / ref object）。
+ */
+export function useMergeRefs(...refs) {
+    return React.useCallback((value) => {
+        refs.forEach(ref => {
+            if (typeof ref === "function") {
+                ref(value);
+            }
+            else if (ref != null) {
+                ref.current = value;
+            }
+        });
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    refs);
+}

package/dist/index.d.ts

@@ -25,3 +25,4 @@ export * from "./components/ui/tag";
 export * from "./components/ui/textarea";
 export * from "./components/ui/toast";
 export * from "./components/ui/tooltip";
+export * from "./hooks";

package/dist/index.js

@@ -25,3 +25,4 @@ export * from "./components/ui/tag/index.js";
 export * from "./components/ui/textarea/index.js";
 export * from "./components/ui/toast/index.js";
 export * from "./components/ui/tooltip/index.js";
+export * from "./hooks/index.js";

package/dist/test/helpers.js

@@ -15,9 +15,10 @@ export class TestContainer {
         this.root = ReactDOM.createRoot(this.container);
     }
     cleanup() {
-        if (this.root) {
+        const root = this.root;
+        if (root) {
             act(() => {
-                this.root.unmount();
+                root.unmount();
             });
             this.root = null;
         }
@@ -27,11 +28,12 @@ export class TestContainer {
         }
     }
     render(element) {
-        if (!this.root) {
+        const root = this.root;
+        if (!root) {
             throw new Error("Container not set up. Call setup() first.");
         }
         act(() => {
-            this.root.render(element);
+            root.render(element);
         });
     }
     getContainer() {
@@ -156,6 +158,9 @@ export const AsyncHelpers = {
     waitFor(callback, timeout = 1000, interval = 50) {
         return new Promise((resolve, reject) => {
             const startTime = Date.now();
+            // タイムアウト時に最後に起きたエラーを含めて reject するため保持する
+            // en: Keep the last thrown error so we can surface it on timeout.
+            let lastError;
             const check = () => {
                 try {
                     const result = callback();
@@ -165,10 +170,13 @@ export const AsyncHelpers = {
                     }
                 }
                 catch (error) {
-                    // Continue checking
+                    lastError = error;
                 }
                 if (Date.now() - startTime >= timeout) {
-                    reject(new Error(`Timeout after ${timeout}ms`));
+                    const message = lastError
+                        ? `Timeout after ${timeout}ms (last error: ${lastError instanceof Error ? lastError.message : String(lastError)})`
+                        : `Timeout after ${timeout}ms`;
+                    reject(new Error(message));
                     return;
                 }
                 setTimeout(check, interval);

package/dist/test/setup.js

@@ -33,6 +33,6 @@ Object.defineProperty(window, "matchMedia", {
         removeListener: () => { },
         addEventListener: () => { },
         removeEventListener: () => { },
-        dispatchEvent: () => { },
+        dispatchEvent: () => true,
     }),
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkle-design",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
@@ -91,7 +91,7 @@
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-jsx-a11y": "^6.10.2",
     "eslint-plugin-storybook": "^10.3.5",
-    "next": "15.5.15",
+    "next": "15.5.18",
     "playwright": "^1.51.1",
     "prettier": "^3.6.2",
     "storybook": "^10.3.5",
@@ -125,7 +125,7 @@
       "js-yaml@>=4.0.0 <4.1.1": "^4.1.1",
       "playwright": "^1.59.1",
       "form-data": "^4.0.4",
-      "hono": "^4.12.14",
+      "hono": "^4.12.18",
       "yaml@>=2.0.0 <2.8.3": "^2.8.3",
       "@eslint/plugin-kit": "^0.3.4",
       "brace-expansion@<1.1.13": "^1.1.13"
@@ -273,6 +273,11 @@
       "types": "./dist/components/ui/tooltip/index.d.ts",
       "import": "./dist/components/ui/tooltip/index.js",
       "require": "./dist/components/ui/tooltip/index.js"
+    },
+    "./hooks": {
+      "types": "./dist/hooks/index.d.ts",
+      "import": "./dist/hooks/index.js",
+      "require": "./dist/hooks/index.js"
     }
   },
   "files": [