@keepkit/ui 0.11.0 → 0.13.0

package/README.md

@@ -57,7 +57,41 @@ function SavedArticles() {
 `keep.Collection`は検索、ソート、ページング、loading / empty / error、ARIA live通知を標準で提供します。検索は既定で300msデバウンスされます。`features={{ tagFilter: true, bulkActions: true }}`でタグフィルターと一括操作も有効にできます。個別の`KeepList`、`KeepSearchInput`、`KeepSortSelect`、`KeepPagination`、`KeepItemCheckbox`、`KeepTagEditor`などは高度なレイアウト用に利用できます。`KeepBulkActions`はrender propsで操作UIを差し替えられ、`isAllSelected` / `toggleSelectAll`で表示中アイテムを一括操作できます。`KeepNoteEditor`は既定300msのデバウンス保存に対応し、`debounceMs={0}`でフォーム送信のみへ戻せます。通知領域だけを明示的に置く場合は`KeepAnnouncer`（`KeepAnnouncements`のalias）を使えます。
 `KeepItemCard`は`href`、`onOpen`、`linkTarget`、`linkComponent`に対応し、保存アイテムから詳細ページへ遷移できます。非公開・期限切れ等の`status`を持つアイテムは自動的にリンクを無効化します。`KeepBackup`はJSONのエクスポート、merge / replaceインポート、結果件数、容量エラー表示を提供します。
 
-v0.11.0では`KeepCollection urlSync layout="list" | "grid" | "compact"`、`KeepBulkActions selectionScope="page" | "query" | "all"`、`KeepUndo`を利用できます。`createNextPagesRouterAdapter`はNext.js Pages Router用の注入adapterです。`locale`は日本語・英語・韓国語・中国語に対応し、`labels`で上書きできます。
+v0.13.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テーマ
+
+```tsx
+import "@keepkit/ui/tailwind.css";
+import { KeepThemeProvider, KeepCollection } from "@keepkit/ui";
+
+<KeepThemeProvider theme="compact" 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等へ差し替えられます。
+
+Viewer向け保存カードとカスタムテーマは次のように構成できます。`savedAt`、タイトル、タグ、詳細リンク、保存解除ボタン、期限切れ表示は`KeepItemCard`の標準markupに含まれます。
+
+```tsx
+import "@keepkit/ui/theme.css";
+import { KeepItemCard, KeepThemeProvider } from "@keepkit/ui";
+
+<KeepThemeProvider
+  theme="rounded"
+  variables={{ "--keep-primary": "oklch(0.55 0.2 250)", "--keep-card-gap": "0.75rem" }}
+>
+  <KeepItemCard
+    item={item}
+    href={`/guide/${item.id}`}
+    getImageProps={(entry) => ({ src: entry.meta.image, alt: entry.meta.title })}
+  />
+</KeepThemeProvider>;
+```
+
+状態は色だけに依存せず、ラベルと属性でも利用できます。`[data-state="saved"]`、`[data-state="unsaved"]`、`[data-loading="true"]`、`[data-state="error"]`、`[data-state="empty"]`、`[data-state="stale"]`、`[data-status="expired"]`、`[data-status="removed"]`、`[data-state="selected"]`をホストCSSやTailwindのdata variantから参照できます。既存テーマから移行する場合は、`@keepkit/ui/theme.css`を残したまま`--keepkit-*`参照を`--keep-*`へ置き換えてください。Pages Routerでは`createNextPagesRouterAdapter(router)`を`urlAdapter`へ注入します。
 
 一覧のqueryは次の形式に統一されています。
 
@@ -109,7 +143,41 @@ 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.
 `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.
 
-In v0.11.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 Japanese, English, Korean, and Chinese dictionaries; `labels` overrides individual entries.
+In v0.13.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
+
+```tsx
+import "@keepkit/ui/tailwind.css";
+import { KeepThemeProvider, KeepCollection } from "@keepkit/ui";
+
+<KeepThemeProvider theme="compact" 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`.
+
+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:
+
+```tsx
+import "@keepkit/ui/theme.css";
+import { KeepItemCard, KeepThemeProvider } from "@keepkit/ui";
+
+<KeepThemeProvider
+  theme="rounded"
+  variables={{ "--keep-primary": "oklch(0.55 0.2 250)", "--keep-card-gap": "0.75rem" }}
+>
+  <KeepItemCard
+    item={item}
+    href={`/guide/${item.id}`}
+    getImageProps={(entry) => ({ src: entry.meta.image, alt: entry.meta.title })}
+  />
+</KeepThemeProvider>;
+```
+
+Use `[data-state="saved"]`, `[data-state="unsaved"]`, `[data-loading="true"]`, `[data-state="error"]`, `[data-state="empty"]`, `[data-state="stale"]`, `[data-status="expired"]`, `[data-status="removed"]`, and `[data-state="selected"]` from host CSS or Tailwind data variants. For migration, keep importing `@keepkit/ui/theme.css` while replacing direct `--keepkit-*` references with `--keep-*`. In the Pages Router, inject `createNextPagesRouterAdapter(router)` into `urlAdapter`.
 
 Collection queries use one canonical shape: `targetType`, `tags`, `search`, `sort`, `pagination`, `filter`, and `savedBetween`. Saved item inputs contain only `id`, `meta`, `targetType`, `note`, and `tags`; KeepKit owns persistence timestamps.
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
-import { HTMLAttributes, ReactNode, ImgHTMLAttributes, ComponentType, MouseEvent, HTMLAttributeAnchorTarget, InputHTMLAttributes, FormHTMLAttributes, SelectHTMLAttributes } from 'react';
-import { ImportItemsResult, KeepListQuery, KeepItem, KeepUrlSyncOptions, KeepItemInput } from '@keepkit/core/core';
-export { KeepItem, KeepItemInput, KeepListQuery, KeepScope, KeepSyncStatus, KeepUndoState, KeepUrlSyncOptions } from '@keepkit/core/core';
+import { HTMLAttributes, ReactNode, ComponentType, ImgHTMLAttributes, MouseEvent, HTMLAttributeAnchorTarget, InputHTMLAttributes, FormHTMLAttributes, ButtonHTMLAttributes, SelectHTMLAttributes, CSSProperties } from 'react';
+import { ImportItemsResult, KeepListQuery, KeepItem, KeepUrlSyncOptions, KeepItemStatus, KeepSyncConflict, KeepItemInput } from '@keepkit/core/core';
+export { AuthenticatedSyncAuthContext, AuthenticatedSyncKit, AuthenticatedSyncKitOptions, AuthenticatedSyncRequestContext, AuthenticatedSyncTransport, KeepItem, KeepItemInput, KeepListQuery, KeepScope, KeepSyncConflict, KeepSyncResolution, KeepSyncState, KeepSyncStatus, KeepUndoState, KeepUrlSyncOptions, createAuthenticatedSyncKit } from '@keepkit/core/core';
 import { KeepButtonProps as KeepButtonProps$1, UseKeepListResult, KeepErrorBoundaryProps, CreateKeepKitOptions as CreateKeepKitOptions$1, KeepProviderProps, useKeepContext, useKeepItem, useKeepList, KeepShortcutOptions } from '@keepkit/core/react';
 export { KeepButtonState, KeepContextValue, KeepErrorBoundary, KeepErrorBoundaryProps, KeepProvider, KeepProviderProps, KeepShortcutOptions, useKeepContext, useKeepItem, useKeepList, useKeepShortcut } from '@keepkit/core/react';
 export { FallbackStorageAdapter, IndexedDBAdapter, IndexedDBSyncQueueAdapter, LocalStorageAdapter, LocalStorageSyncQueueAdapter, SyncStorageAdapter, createBrowserStorageAdapter, createStorageAdapter } from '@keepkit/core/storage';
@@ -23,6 +23,18 @@ type KeepButtonLabels = {
     savedAriaLabel?: string;
     unsavedAriaLabel?: string;
 };
+type KeepButtonIconProps = {
+    "aria-hidden"?: boolean;
+    className?: string;
+};
+type KeepButtonIcon = ReactNode | ComponentType<KeepButtonIconProps>;
+type KeepButtonIcons = {
+    save?: KeepButtonIcon;
+    saved?: KeepButtonIcon;
+    remove?: KeepButtonIcon;
+    loading?: KeepButtonIcon;
+    error?: KeepButtonIcon;
+};
 
 type KeepBulkActionsState<TMeta = Record<string, unknown>> = {
     items: KeepItem<TMeta>[];
@@ -63,9 +75,13 @@ declare function KeepBulkActions<TMeta = Record<string, unknown>>({ query, selec
 
 type KeepButtonProps<TMeta = Record<string, unknown>> = KeepButtonProps$1<TMeta> & {
     labels?: KeepButtonLabels;
+    icons?: KeepButtonIcons;
+    iconOnly?: boolean;
+    showLabel?: boolean;
+    iconClassName?: string;
 };
 /** A style-free save toggle with localized labels and the core button's ARIA/asChild behavior. */
-declare function KeepButton<TMeta = Record<string, unknown>>({ labels, ...props }: KeepButtonProps<TMeta>): react.JSX.Element;
+declare function KeepButton<TMeta = Record<string, unknown>>({ labels, icons, iconOnly, showLabel, iconClassName, ...props }: KeepButtonProps<TMeta>): react.JSX.Element;
 
 type KeepItemCardState<TMeta = Record<string, unknown>> = {
     item: KeepItem<TMeta>;
@@ -95,12 +111,14 @@ type KeepItemCardProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HT
     renderImage?: (props: KeepImageProps, item: KeepItem<TMeta>) => ReactNode;
     renderTags?: (tags: string[], item: KeepItem<TMeta>) => ReactNode;
     showTags?: boolean;
+    showSavedAt?: boolean;
     imageAlt?: string;
     render?: RenderProp<KeepItemCardState<TMeta>>;
     children?: ReactNode | RenderProp<KeepItemCardState<TMeta>>;
     removeLabel?: string;
     onRemoveError?: (error: unknown) => void;
     onRemoved?: (item: KeepItem<TMeta>) => void;
+    onRetry?: (item: KeepItem<TMeta>) => void | Promise<void>;
     showSaveButton?: boolean;
     saveButtonLabels?: KeepButtonLabels;
     asChild?: boolean;
@@ -112,7 +130,7 @@ type KeepItemCardProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HT
     linkRel?: string;
 };
 /** A low-dependency item presentation primitive. The default markup can be replaced with render props. */
-declare function KeepItemCard<TMeta = Record<string, unknown>>({ item, title, getTitle, getImageProps, imageComponent: ImageComponent, renderImage, renderTags, showTags, imageAlt, render, children, removeLabel, onRemoveError, onRemoved, showSaveButton, saveButtonLabels, asChild, href: hrefOption, onOpen, linkTarget, linkComponent: LinkComponent, linkTargetAttribute, linkRel, className, ...rootProps }: KeepItemCardProps<TMeta>): react.ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+declare function KeepItemCard<TMeta = Record<string, unknown>>({ item, title, getTitle, getImageProps, imageComponent: ImageComponent, renderImage, renderTags, showTags, showSavedAt, imageAlt, render, children, removeLabel, onRemoveError, onRemoved, onRetry, showSaveButton, saveButtonLabels, asChild, href: hrefOption, onOpen, linkTarget, linkComponent: LinkComponent, linkTargetAttribute, linkRel, className, ...rootProps }: KeepItemCardProps<TMeta>): react.ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
 type KeepListState<TMeta = Record<string, unknown>> = UseKeepListResult<TMeta>;
 type KeepListProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLElement>, "children"> & {
@@ -192,6 +210,13 @@ type KeepItemCheckboxProps<TMeta = Record<string, unknown>> = Omit<InputHTMLAttr
 /** A reusable accessible selection checkbox for a saved item. */
 declare function KeepItemCheckbox<TMeta = Record<string, unknown>>({ item, checked, label, onCheckedChange, "aria-label": ariaLabel, ...props }: KeepItemCheckboxProps<TMeta>): react.JSX.Element;
 
+type KeepItemStatusBadgeProps = Omit<HTMLAttributes<HTMLSpanElement>, "children"> & {
+    status?: KeepItemStatus;
+    label?: ReactNode;
+};
+/** Displays the normalized availability state of a saved item. */
+declare function KeepItemStatusBadge({ status, label, className, ...props }: KeepItemStatusBadgeProps): react.JSX.Element;
+
 type KeepLayoutProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
     layout?: KeepLayoutPreset;
     children?: ReactNode;
@@ -224,6 +249,46 @@ type KeepNoteEditorProps<TMeta = Record<string, unknown>> = Omit<FormHTMLAttribu
 /** A controlled-by-default note editor that persists through useKeepItem. */
 declare function KeepNoteEditor<TMeta = Record<string, unknown>>({ item, label, saveLabel, placeholder, debounceMs, onSaved, onSaveError, render, children, asChild, className, ...formProps }: KeepNoteEditorProps<TMeta>): react.JSX.Element;
 
+type KeepStaleNoticeProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLElement>, "children"> & {
+    item: KeepItem<TMeta>;
+    onRetry?: (item: KeepItem<TMeta>) => void | Promise<void>;
+    onRemoved?: (item: KeepItem<TMeta>) => void;
+    retryLabel?: ReactNode;
+    removeLabel?: ReactNode;
+    children?: ReactNode;
+};
+/** Provides retry and remove actions for an item whose source is no longer available. */
+declare function KeepStaleNotice<TMeta = Record<string, unknown>>({ item, onRetry, onRemoved, retryLabel, removeLabel, children, className, ...props }: KeepStaleNoticeProps<TMeta>): react.JSX.Element;
+type KeepPruneStaleButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children"> & {
+    statuses?: KeepItemStatus[];
+    label?: ReactNode;
+    onPruned?: (ids: string[]) => void;
+    children?: ReactNode;
+};
+/** Removes all unavailable items through the provider's undo-capable batch action. */
+declare function KeepPruneStaleButton<TMeta = Record<string, unknown>>({ statuses, label, onPruned, children, disabled, ...props }: KeepPruneStaleButtonProps): react.JSX.Element;
+
+type KeepSyncRecoveryDialogProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLElement>, "children" | "title"> & {
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    conflicts?: KeepSyncConflict<TMeta>[];
+    onManualMerge?: (conflict: KeepSyncConflict<TMeta>) => KeepItem<TMeta> | Promise<KeepItem<TMeta>>;
+    backup?: ReactNode;
+    showBackupControls?: boolean;
+    title?: ReactNode;
+    children?: ReactNode;
+};
+/** Resolves queued sync conflicts and guides users to restore a backup after data corruption. */
+declare function KeepSyncRecoveryDialog<TMeta = Record<string, unknown>>({ open, onOpenChange, conflicts, onManualMerge, backup, showBackupControls, title, children, className, ...props }: KeepSyncRecoveryDialogProps<TMeta>): react.JSX.Element | null;
+
+type KeepSyncStatusBannerProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
+    onRetry?: () => void | Promise<void>;
+    onResolveConflicts?: () => void;
+    children?: ReactNode;
+};
+/** Announces synchronization failures and exposes retry or conflict-recovery entry points. */
+declare function KeepSyncStatusBanner({ onRetry, onResolveConflicts, children, className, ...props }: KeepSyncStatusBannerProps): react.JSX.Element | null;
+
 type KeepTagEditorState = {
     tags: string[];
     setTags: (tags: string[]) => void;
@@ -336,8 +401,45 @@ declare function KeepAnnouncements<TMeta = Record<string, unknown>>({ messages,
 /** Singular alias for applications that mount one announcer explicitly. */
 declare const KeepAnnouncer: typeof KeepAnnouncements;
 
-type KeepUiLabelKey = "save" | "saved" | "remove" | "loading" | "saving" | "syncing" | "error" | "allTags" | "tags" | "filterTags" | "note" | "saveNote" | "noItems" | "loadingItems" | "errorItems" | "search" | "sort" | "newest" | "oldest" | "savedNewest" | "savedOldest" | "updatedNewest" | "updatedOldest" | "previousPage" | "nextPage" | "pagination" | "page" | "selectItems" | "selectedCount" | "deleteSelected" | "tagsToApply" | "applyTags" | "savedMessage" | "removedMessage" | "undo" | "undoAvailable" | "selectionScope" | "currentPage" | "searchResults" | "allItems" | "statusAvailable" | "noteSavedMessage" | "exportData" | "importData" | "importMode" | "merge" | "replace" | "importedCount" | "failedCount" | "storageQuotaError" | "statusExpired" | "statusRemoved" | "statusDeleted" | "statusPrivate" | "statusUnknown";
+type KeepThemeName = "default" | "compact" | "minimal" | "rounded" | "high-contrast" | "dark";
+type KeepThemeMode = "light" | "dark" | "system";
+type KeepThemeDensity = "compact" | "comfortable" | "spacious";
+type KeepThemeRadius = "none" | "small" | "medium" | "large" | "full";
+type KeepThemeVariables = Record<`--keep-${string}`, string | number>;
+type KeepThemeProviderProps = {
+    children?: ReactNode;
+    className?: string;
+    id?: string;
+    title?: string;
+    role?: string;
+    tabIndex?: number;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    "data-testid"?: string;
+    [key: `data-${string}`]: string | undefined;
+    theme?: KeepThemeName;
+    mode?: KeepThemeMode;
+    density?: KeepThemeDensity;
+    radius?: KeepThemeRadius;
+    accentColor?: "blue" | "green" | "violet" | "orange" | "rose" | (string & {});
+    highContrast?: boolean;
+    reducedMotion?: boolean;
+    variables?: KeepThemeVariables;
+    style?: CSSProperties & KeepThemeVariables;
+    asChild?: boolean;
+};
+/** Scopes KeepKit tokens and opt-in component styles to one subtree. */
+declare function KeepThemeProvider({ children, theme, mode, density, radius, accentColor, highContrast, reducedMotion, variables, style, className, asChild, ...props }: KeepThemeProviderProps): react.JSX.Element;
+
+type KeepUiLabelKey = "save" | "saved" | "remove" | "loading" | "saving" | "syncing" | "error" | "allTags" | "tags" | "filterTags" | "note" | "saveNote" | "noItems" | "loadingItems" | "errorItems" | "search" | "sort" | "newest" | "oldest" | "savedNewest" | "savedOldest" | "updatedNewest" | "updatedOldest" | "previousPage" | "nextPage" | "pagination" | "page" | "selectItems" | "selectedCount" | "deleteSelected" | "tagsToApply" | "applyTags" | "savedMessage" | "removedMessage" | "undo" | "undoAvailable" | "selectionScope" | "currentPage" | "searchResults" | "allItems" | "statusAvailable" | "noteSavedMessage" | "exportData" | "importData" | "importMode" | "merge" | "replace" | "importedCount" | "failedCount" | "storageQuotaError" | "statusExpired" | "statusRemoved" | "statusDeleted" | "statusPrivate" | "statusUnknown" | "retry" | "removeFromList" | "pruneStale" | "retrySync" | "resolveSync" | "keepLocal" | "useServer" | "manualMerge" | "close" | "backupRecovery" | "backupRecoveryDescription" | "syncPending" | "syncSynced" | "syncConflict";
 type KeepUiLabels = Partial<Record<KeepUiLabelKey, string>>;
+type KeepUiLocaleLabels = Record<KeepUiLabelKey, string>;
+
+declare const KEEP_BUILT_IN_LOCALES: readonly ["en", "ja", "ko", "zh-Hans", "zh-Hant", "th", "fr", "es", "pt-BR", "it", "de", "ru", "fil", "vi", "id", "ms"];
+type KeepUiLocale = (typeof KEEP_BUILT_IN_LOCALES)[number];
+declare function getKeepLocaleLabels(locale?: string): KeepUiLocaleLabels;
+
 type KeepUiLabelContext = {
     locale?: string;
     labels: Readonly<Record<KeepUiLabelKey, string>>;
@@ -352,18 +454,27 @@ type KeepUiProviderProps = {
     labelResolver?: KeepUiLabelContext["labelResolver"];
     children?: ReactNode;
 };
-/** Provides one locale-aware label source to every UI primitive. */
+/** Provides one complete locale-aware label source to every UI primitive. */
 declare function KeepUiProvider({ labels, locale, labelResolver, children }: KeepUiProviderProps): react.JSX.Element;
 declare function useKeepUiLabels(): KeepUiLabelContext;
-declare function getKeepLocaleLabels(locale?: string): KeepUiLabels;
 
-type KeepKitProviderProps<TMeta = Record<string, unknown>> = Omit<KeepProviderProps<TMeta>, "children"> & Omit<KeepUiProviderProps, "children"> & {
+type KeepKitProviderProps<TMeta = Record<string, unknown>> = Omit<KeepProviderProps<TMeta>, "children"> & Omit<KeepUiProviderProps, "children"> & Omit<KeepThemeProviderProps, "children"> & {
     children?: ReactNode;
 };
 /** Combines the core store, UI labels, and the global live announcer. */
-declare function KeepKitProvider<TMeta = Record<string, unknown>>({ labels, locale, labelResolver, children, ...providerProps }: KeepKitProviderProps<TMeta>): react.JSX.Element;
+declare function KeepKitProvider<TMeta = Record<string, unknown>>({ labels, locale, labelResolver, theme, mode, density, radius, accentColor, highContrast, reducedMotion, variables, className: themeClassName, style: themeStyle, asChild: themeAsChild, children, ...providerProps }: KeepKitProviderProps<TMeta>): react.JSX.Element;
 
 type CreateKeepKitOptions<TMeta = Record<string, unknown>> = CreateKeepKitOptions$1<TMeta> & Omit<KeepUiProviderProps, "children"> & {
+    theme?: KeepThemeName;
+    mode?: KeepThemeMode;
+    density?: KeepThemeDensity;
+    radius?: KeepThemeRadius;
+    accentColor?: KeepThemeProviderProps["accentColor"];
+    highContrast?: boolean;
+    reducedMotion?: boolean;
+    variables?: KeepThemeVariables;
+    themeClassName?: string;
+    themeStyle?: KeepThemeProviderProps["style"];
     getTitle?: (item: KeepItem<TMeta>) => ReactNode;
     getImageProps?: (item: KeepItem<TMeta>, title: ReactNode) => KeepImageProps | undefined;
 };
@@ -380,4 +491,4 @@ type KeepKit<TMeta = Record<string, unknown>> = {
 /** Create one typed application API for the core and standard UI layer. */
 declare function createKeepKit<TMeta = Record<string, unknown>>(options?: CreateKeepKitOptions<TMeta>): KeepKit<TMeta>;
 
-export { type CreateKeepKitOptions, KeepAnnouncements, type KeepAnnouncementsProps, KeepAnnouncer, KeepBackup, type KeepBackupProps, KeepBulkActions, type KeepBulkActionsProps, type KeepBulkActionsState, KeepButton, type KeepButtonLabels, type KeepButtonProps, KeepCollection, type KeepCollectionFeature, type KeepCollectionProps, KeepEmptyState, type KeepEmptyStateProps, type KeepImageProps, KeepItemCard, type KeepItemCardLinkProps, type KeepItemCardProps, type KeepItemCardState, KeepItemCheckbox, type KeepItemCheckboxProps, type KeepKit, KeepKitProvider, type KeepKitProviderProps, KeepLayout, type KeepLayoutPreset, type KeepLayoutProps, KeepList, type KeepListProps, type KeepListState, KeepNoteEditor, type KeepNoteEditorProps, type KeepNoteEditorState, type KeepPagesRouterLike, KeepPagination, type KeepPaginationProps, type KeepPaginationState, KeepSearchInput, type KeepSearchInputProps, type KeepSelectionScope, KeepSortSelect, type KeepSortSelectProps, type KeepSortValue, KeepStatus, type KeepStatusLabels, type KeepStatusProps, type KeepStatusState, type KeepStatusValue, KeepTagEditor, type KeepTagEditorProps, type KeepTagEditorState, KeepTagFilter, type KeepTagFilterProps, type KeepTagFilterState, type KeepUiLabelContext, type KeepUiLabelKey, type KeepUiLabels, KeepUiProvider, type KeepUiProviderProps, KeepUndo, type KeepUndoProps, type KeepUrlAdapter, type RenderProp, createKeepKit, createNextPagesRouterAdapter, getKeepLocaleLabels, isAllSelected, toggleSelectAll, useKeepUiLabels, useKeepUrlSync };
+export { type CreateKeepKitOptions, KeepAnnouncements, type KeepAnnouncementsProps, KeepAnnouncer, KeepBackup, type KeepBackupProps, KeepBulkActions, type KeepBulkActionsProps, type KeepBulkActionsState, KeepButton, type KeepButtonIcon, type KeepButtonIconProps, type KeepButtonIcons, type KeepButtonLabels, type KeepButtonProps, KeepCollection, type KeepCollectionFeature, type KeepCollectionProps, KeepEmptyState, type KeepEmptyStateProps, type KeepImageProps, KeepItemCard, type KeepItemCardLinkProps, type KeepItemCardProps, type KeepItemCardState, KeepItemCheckbox, type KeepItemCheckboxProps, KeepItemStatusBadge, type KeepItemStatusBadgeProps, type KeepKit, KeepKitProvider, type KeepKitProviderProps, KeepLayout, type KeepLayoutPreset, type KeepLayoutProps, KeepList, type KeepListProps, type KeepListState, KeepNoteEditor, type KeepNoteEditorProps, type KeepNoteEditorState, type KeepPagesRouterLike, KeepPagination, type KeepPaginationProps, type KeepPaginationState, KeepPruneStaleButton, type KeepPruneStaleButtonProps, KeepSearchInput, type KeepSearchInputProps, type KeepSelectionScope, KeepSortSelect, type KeepSortSelectProps, type KeepSortValue, KeepStaleNotice, type KeepStaleNoticeProps, KeepStatus, type KeepStatusLabels, type KeepStatusProps, type KeepStatusState, type KeepStatusValue, KeepSyncRecoveryDialog, type KeepSyncRecoveryDialogProps, KeepSyncStatusBanner, type KeepSyncStatusBannerProps, KeepTagEditor, type KeepTagEditorProps, type KeepTagEditorState, KeepTagFilter, type KeepTagFilterProps, type KeepTagFilterState, type KeepThemeDensity, type KeepThemeMode, type KeepThemeName, KeepThemeProvider, type KeepThemeProviderProps, type KeepThemeRadius, type KeepThemeVariables, type KeepUiLabelContext, type KeepUiLabelKey, type KeepUiLabels, type KeepUiLocale, type KeepUiLocaleLabels, KeepUiProvider, type KeepUiProviderProps, KeepUndo, type KeepUndoProps, type KeepUrlAdapter, type RenderProp, createKeepKit, createNextPagesRouterAdapter, getKeepLocaleLabels, isAllSelected, toggleSelectAll, useKeepUiLabels, useKeepUrlSync };