@keepkit/ui 0.14.0 → 0.16.0

package/README.md

@@ -13,6 +13,7 @@ pnpm add @keepkit/ui
 ## Minimal Starter Recipe
 
 ```tsx
+import "@keepkit/ui/theme.css";
 import { createBrowserStorageAdapter, createKeepKit } from "@keepkit/ui";
 
 type Meta = { title: string; url: string };
@@ -30,9 +31,10 @@ export function SavedArticle({ article }: { article: Meta & { id: string } }) {
 }
 ```
 
-Every primitive exposes `data-state`; pending operations expose `data-loading="true"`, and disabled controls expose `data-disabled="true"`. Use these attributes from host CSS or Tailwind data variants. `KeepCollection` and `KeepList` accept `fallback`, `onBoundaryError`, and `boundaryResetKey` for local render-error isolation.
+すべてのプリミティブは`data-state`を公開し、処理中は`data-loading="true"`、無効時は`data-disabled="true"`になります。`@keepkit/ui/theme.css`を読み込むと、標準の枠、面色、影、フォーカス表示と装飾アイコンが有効になります。個別の操作は`data-keep-action`で選択でき、`--keep-icon-size`、`--keep-control-gap`、`--keep-shadow`、`--keep-success`、`--keep-warning`で調整できます。CSSを読み込まないheadless利用と`KeepButton icons`による差し替えは維持されます。
 
 ```tsx
+import "@keepkit/ui/theme.css";
 import { createBrowserStorageAdapter, createKeepKit } from "@keepkit/ui";
 
 type ArticleMeta = { title: string; url: string };
@@ -58,7 +60,29 @@ function SavedArticles() {
 `KeepItemCard`は`href`、`onOpen`、`linkTarget`、`linkComponent`に対応し、保存アイテムから詳細ページへ遷移できます。非公開・期限切れ等の`status`を持つアイテムは自動的にリンクを無効化します。`KeepBackup`はJSONのエクスポート、merge / replaceインポート、結果件数、容量エラー表示を提供します。
 外部URLの詳細リンクには`target="_blank"`と`rel="noreferrer"`が既定で補完され、利用できないカードには`aria-disabled="true"`と`data-item-status`が付与されます。同期競合ダイアログではローカルとリモートの更新日時・メモを並べて確認できます。
 
-v0.14.0では`KeepCollection urlSync layout="list" | "grid" | "compact"`、`KeepBulkActions selectionScope="page" | "query" | "all"`、`KeepUndo`を利用できます。`createNextPagesRouterAdapter`はNext.js Pages Router用の注入adapterです。`locale`は英語、日本語、韓国語、中国語簡体字・繁体字、タイ語、フランス語、スペイン語、ポルトガル語、イタリア語、ドイツ語、ロシア語、フィリピン語、ベトナム語、インドネシア語、マレー語の16言語に対応し、`labels`で上書きできます。認証付き同期は`createAuthenticatedSyncKit`から利用できます。
+`KeepList`は初回ロード中、`layout`に合う`KeepItemCardSkeleton`を既定で6枚表示します。`loadingCount`で枚数を変更でき、従来の`loading`または`renderLoading`で完全に差し替えられます。`layout="auto"`は画面幅ではなく配置コンテナ幅に追従し、サイドバーやモーダルでも1列から複数列へ切り替わります。スケルトンのパルスは`prefers-reduced-motion`で静止表示になります。
+
+カードの一部だけを配置し直す場合はCompound APIを利用できます。画像alt、タイトルリンク、タグ一覧のARIAラベル、保存操作の状態は各パーツでも維持されます。
+
+```tsx
+<KeepItemCard item={item} href={`/items/${item.id}`} getImageProps={getImageProps}>
+  <KeepItemCard.Media fallback="No image" />
+  <KeepItemCard.Content>
+    <KeepItemCard.Title />
+    <KeepItemCard.Tags />
+  </KeepItemCard.Content>
+  <KeepItemCard.Actions />
+</KeepItemCard>
+```
+
+`KeepKitProvider` / `KeepUiProvider`の`onFeedback`は`item-saved`、`item-removed`、`item-restored`、`sync-completed`、`sync-failed`、`stale-pruned`を通知します。削除系イベントには`undo`と現在ロケールの`undoLabel`が含まれます。Sonner互換の関数なら次の1行で接続できます（ライブラリ依存は追加されません）。
+
+```tsx
+const onFeedback = useKeepToastFeedback(toast);
+<KeepKitProvider storage={storage} onFeedback={onFeedback}>{children}</KeepKitProvider>;
+```
+
+v0.16.0では`KeepCollection urlSync layout="list" | "grid" | "compact"`、`KeepBulkActions selectionScope="page" | "query" | "all"`、`KeepUndo`を利用できます。`createNextPagesRouterAdapter`はNext.js Pages Router用の注入adapterです。`locale`は英語、日本語、韓国語、中国語簡体字・繁体字、タイ語、フランス語、スペイン語、ポルトガル語、イタリア語、ドイツ語、ロシア語、フィリピン語、ベトナム語、インドネシア語、マレー語の16言語に対応し、`labels`で上書きできます。認証付き同期は`createAuthenticatedSyncKit`から利用できます。
 Phase 4の状態UIとして`KeepItemStatusBadge`、`KeepStaleNotice`、`KeepPruneStaleButton`、`KeepSyncStatusBanner`、`KeepSyncRecoveryDialog`を利用できます。`import "@keepkit/ui/theme.css"`でテーマCSSを有効にできます。
 
 ### Tailwind／shadcnテーマ
@@ -67,12 +91,14 @@ Phase 4の状態UIとして`KeepItemStatusBadge`、`KeepStaleNotice`、`KeepPrun
 import "@keepkit/ui/tailwind.css";
 import { KeepThemeProvider, KeepCollection } from "@keepkit/ui";
 
-<KeepThemeProvider theme="compact" mode="system" density="comfortable" radius="medium">
+<KeepThemeProvider theme="ocean" mode="system" density="comfortable" radius="medium">
   <KeepCollection layout="grid" />
 </KeepThemeProvider>;
 ```
 
-`default`、`compact`、`minimal`、`rounded`、`high-contrast`、`dark`のプリセット、`.dark`／`prefers-color-scheme`、モバイル対応、`prefers-reduced-motion`を提供します。shadcn/uiの`--background`、`--foreground`、`--card`、`--muted`、`--border`、`--primary`、`--destructive`、`--ring`を継承し、KeepKit固有の値は`--keep-*`に分離されます。`KeepKitProvider theme="compact"`、`variables`、`highContrast`、`reducedMotion`も利用できます。`keepKitTheme`は`@keepkit/ui/tailwind`から、分割CSSは`@keepkit/ui/styles/base.css`、`button.css`、`collection.css`、`sync.css`から読み込めます。`KeepButton icons={{ save, saved, remove }}`と`iconOnly`でLucide等へ差し替えられます。
+色テーマは`default`、`ocean`、`forest`、`sunset`、`lavender`から選べます。既存の`compact`、`minimal`、`rounded`、`high-contrast`、`dark`も引き続き利用できます。`theme`は`mode`、`density`、`radius`と独立しており、`KeepKitProvider theme="forest" mode="dark"`のように組み合わせられます。選択肢をUIへ表示する場合は`keepThemeNames`を利用できます。
+
+shadcn/uiの`--background`、`--foreground`、`--card`、`--muted`、`--border`、`--primary`、`--destructive`、`--ring`を継承し、KeepKit固有の値は`--keep-*`に分離されます。`variables`、`accentColor`、`highContrast`、`reducedMotion`による上書きも維持されます。`keepKitTheme`は`@keepkit/ui/tailwind`から、分割CSSは`@keepkit/ui/styles/base.css`、`button.css`、`collection.css`、`sync.css`から読み込めます。`KeepButton icons={{ save, saved, remove }}`と`iconOnly`でLucide等へ差し替えられます。
 
 Viewer向け保存カードとカスタムテーマは次のように構成できます。`savedAt`、タイトル、タグ、詳細リンク、保存解除ボタン、期限切れ表示は`KeepItemCard`の標準markupに含まれます。
 
@@ -142,10 +168,34 @@ function SavedArticles() {
 ```
 
 `keep.Collection` includes search, sorting, pagination, loading/empty/error states, and polite live announcements. Search is debounced by 300ms by default. Enable `features={{ tagFilter: true, bulkActions: true }}` for tag filtering and bulk operations. Use the individual `KeepList`, `KeepSearchInput`, `KeepSortSelect`, `KeepPagination`, `KeepItemCheckbox`, and `KeepTagEditor` primitives when you need a custom layout. `KeepBulkActions` supports render props and exposes `isAllSelected` / `toggleSelectAll` for visible-item selection. `KeepNoteEditor` auto-saves dirty notes after 300ms by default; set `debounceMs={0}` to use form submission only. Mount `KeepAnnouncer` (`KeepAnnouncements` alias) when you need the live region explicitly.
+
+The opt-in theme adds neutral borders, surfaces, shadows, focus treatment, and decorative action icons without changing accessible names. Target individual controls with `data-keep-action`, or override `--keep-icon-size`, `--keep-control-gap`, `--keep-shadow`, `--keep-success`, and `--keep-warning`. Consumers that omit the CSS keep the headless markup, and `KeepButton icons` continues to take precedence over the built-in icon.
 `KeepItemCard` accepts `href`, `onOpen`, `linkTarget`, and `linkComponent` for detail-page navigation. Links are disabled for unavailable `status` values such as private or expired. `KeepBackup` provides JSON export, merge/replace import, result counts, and quota-error messaging.
 External detail URLs receive `target="_blank"` and `rel="noreferrer"` defaults. Unavailable cards expose `aria-disabled="true"` and normalized `data-item-status` values, and the sync recovery dialog compares local and remote updated dates and notes side by side.
 
-In v0.14.0, use `KeepCollection urlSync` with `layout="list" | "grid" | "compact"`, `KeepBulkActions selectionScope="page" | "query" | "all"`, and `KeepUndo`. `createNextPagesRouterAdapter` is the injected adapter for Next.js Pages Router. `locale` includes complete dictionaries for 16 built-in locales; `labels` overrides individual entries. Authenticated sync is available through `createAuthenticatedSyncKit`.
+During initial loading, `KeepList` renders six layout-matched `KeepItemCardSkeleton` placeholders by default. Change the count with `loadingCount`, or replace them with the existing `loading` prop or its `renderLoading` alias. `layout="auto"` responds to the available container width rather than viewport width, so embedded sidebars and dialogs collapse to one column. Skeleton pulses become static under `prefers-reduced-motion`.
+
+Use the compound parts to rearrange only the card regions you own while preserving image alt text, linked headings, the labelled tag list, and action state:
+
+```tsx
+<KeepItemCard item={item} href={`/items/${item.id}`} getImageProps={getImageProps}>
+  <KeepItemCard.Media fallback="No image" />
+  <KeepItemCard.Content>
+    <KeepItemCard.Title />
+    <KeepItemCard.Tags />
+  </KeepItemCard.Content>
+  <KeepItemCard.Actions />
+</KeepItemCard>
+```
+
+`onFeedback` on `KeepKitProvider` / `KeepUiProvider` receives `item-saved`, `item-removed`, `item-restored`, `sync-completed`, `sync-failed`, and `stale-pruned`. Removal events include an `undo` function and locale-aware `undoLabel`. Connect a Sonner-compatible function without adding a package dependency:
+
+```tsx
+const onFeedback = useKeepToastFeedback(toast);
+<KeepKitProvider storage={storage} onFeedback={onFeedback}>{children}</KeepKitProvider>;
+```
+
+In v0.16.0, use `KeepCollection urlSync` with `layout="list" | "grid" | "compact"`, `KeepBulkActions selectionScope="page" | "query" | "all"`, and `KeepUndo`. `createNextPagesRouterAdapter` is the injected adapter for Next.js Pages Router. `locale` includes complete dictionaries for 16 built-in locales; `labels` overrides individual entries. Authenticated sync is available through `createAuthenticatedSyncKit`.
 Phase 4 adds `KeepItemStatusBadge`, `KeepStaleNotice`, `KeepPruneStaleButton`, `KeepSyncStatusBanner`, and `KeepSyncRecoveryDialog` for unavailable items, sync failures, conflict resolution, and backup recovery. Import `@keepkit/ui/theme.css` or `@keepkit/ui/tailwind.css` for the opt-in theme layer.
 
 ### Tailwind and shadcn theme
@@ -154,12 +204,14 @@ Phase 4 adds `KeepItemStatusBadge`, `KeepStaleNotice`, `KeepPruneStaleButton`, `
 import "@keepkit/ui/tailwind.css";
 import { KeepThemeProvider, KeepCollection } from "@keepkit/ui";
 
-<KeepThemeProvider theme="compact" mode="system" density="comfortable" radius="medium">
+<KeepThemeProvider theme="ocean" mode="system" density="comfortable" radius="medium">
   <KeepCollection layout="grid" />
 </KeepThemeProvider>;
 ```
 
-Presets include `default`, `compact`, `minimal`, `rounded`, `high-contrast`, and `dark`. The scoped `--keep-*` tokens inherit shadcn/ui variables, and the provider supports `.dark`, system preference, `variables`, `highContrast`, and `reducedMotion`. Use `keepKitTheme` from `@keepkit/ui/tailwind`, feature CSS from `@keepkit/ui/styles/*`, and `icons={{ save, saved, remove }}` / `iconOnly` on `KeepButton` for Lucide or shadcn replacements. The existing Next.js Pages Router recipe remains unchanged: inject `createNextPagesRouterAdapter(router)` into `urlAdapter`.
+Color themes include `default`, `ocean`, `forest`, `sunset`, and `lavender`. Existing `compact`, `minimal`, `rounded`, `high-contrast`, and `dark` presets remain available. `theme` composes independently with `mode`, `density`, and `radius`, so `theme="forest" mode="dark"` is supported. Use the exported `keepThemeNames` list when building a selector.
+
+The scoped `--keep-*` tokens inherit shadcn/ui variables, and the provider supports `.dark`, system preference, `variables`, `accentColor`, `highContrast`, and `reducedMotion`. Use `keepKitTheme` from `@keepkit/ui/tailwind`, feature CSS from `@keepkit/ui/styles/*`, and `icons={{ save, saved, remove }}` / `iconOnly` on `KeepButton` for Lucide or shadcn replacements. The existing Next.js Pages Router recipe remains unchanged: inject `createNextPagesRouterAdapter(router)` into `urlAdapter`.
 
 For a Viewer card, the default `KeepItemCard` markup includes the title, tags, saved date, detail link, remove action, thumbnail, and expired-item notice. Override tokens without replacing the markup, or use render props for a complete replacement: