@keepkit/ui 0.17.0 → 0.18.0

package/README.md

@@ -58,8 +58,9 @@ 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インポート、結果件数、容量エラー表示を提供します。
-`KeepTourBar`（alias: `KeepNavigator`）は進行度、前へ・次へ、一覧へ戻る操作をURLまたはコールバックで提供します。`keyboardShortcuts`を指定するとJ/Kまたは]/[で巡回でき、`useKeepTourShortcuts`ではキーと動作を個別に差し替えられます。`KeepReorderableList`はドラッグ操作と矢印キーによる並び替えを提供します。
+`KeepTourBar`（alias: `KeepNavigator`）は進行度、前へ・次へ、一覧へ戻る操作をURLまたはコールバックで提供します。前後ボタンには隣接アイテム名のプレビューが付き、`getItemTitle`で表示名を差し替えられます。`keyboardShortcuts`を指定するとJ/Kまたは]/[で巡回でき、`useKeepTourShortcuts`ではキーと動作を個別に差し替えられます。`KeepReorderableList`はドラッグ操作と矢印キーによる並び替えを提供し、ドラッグ中の挿入位置を表示します。
 `KeepList`や`KeepCollection`のカードは検索語を大文字小文字を区別せず`<mark class="keep-highlight" data-highlight="true">`で表示します。単体の`KeepItemCard`では`highlightQuery`、任意のテキストでは`KeepHighlight`を使えます。`KeepItemCard.Media`は読み込み状態を`data-media-status`で公開し、失敗時は`fallback`または標準SVGへ切り替わります。
+テーマCSSではハイライト用の`--keep-highlight-bg` / `--keep-highlight-fg`（ライト／ダーク対応）、タイトル2行・メモプレビュー3行の制限、メディアの固定アスペクト比を適用します。`KeepItemStatusBadge`は状態ラベルに加えてチェック・時計・進入禁止・鍵のSVGアイコンを表示し、状態ごとの形状とトーンを組み合わせます。個別の状態スタイルは`@keepkit/ui/styles/status.css`からも読み込めます。
 外部URLの詳細リンクには`target="_blank"`と`rel="noreferrer"`が既定で補完され、利用できないカードには`aria-disabled="true"`と`data-item-status`が付与されます。同期競合ダイアログではローカルとリモートの更新日時・メモを並べて確認できます。
 
 `KeepList`は初回ロード中、`layout`に合う`KeepItemCardSkeleton`を既定で6枚表示します。`loadingCount`で枚数を変更でき、従来の`loading`または`renderLoading`で完全に差し替えられます。`layout="auto"`は画面幅ではなく配置コンテナ幅に追従し、サイドバーやモーダルでも1列から複数列へ切り替わります。スケルトンのパルスは`prefers-reduced-motion`で静止表示になります。
@@ -85,7 +86,7 @@ const onFeedback = useKeepToastFeedback(toast);
 <KeepKitProvider storage={storage} onFeedback={onFeedback}>{children}</KeepKitProvider>;
 ```
 
-v0.17.0では`KeepTourBar` / `KeepNavigator`、`KeepReorderableList`、`useKeepTourShortcuts`を利用できます。`KeepCollection urlSync layout="list" | "grid" | "compact"`、`KeepBulkActions selectionScope="page" | "query" | "all"`、`KeepUndo`も利用できます。`createNextPagesRouterAdapter`はNext.js Pages Router用の注入adapterです。`locale`は16言語に対応し、`labels`で上書きできます。認証付き同期は`createAuthenticatedSyncKit`から利用できます。
+v0.18.0では`KeepTourBar` / `KeepNavigator`、`KeepReorderableList`、`useKeepTourShortcuts`を利用できます。`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テーマ
@@ -174,8 +175,9 @@ function SavedArticles() {
 
 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.
-`KeepTourBar` (aliased as `KeepNavigator`) provides progress, previous/next, and return-to-list actions through URLs or callbacks. Set `keyboardShortcuts` for J/K or ]/[ tour navigation, or use `useKeepTourShortcuts` for custom bindings. `KeepReorderableList` supports drag and keyboard reordering.
+`KeepTourBar` (aliased as `KeepNavigator`) provides progress, previous/next, and return-to-list actions through URLs or callbacks. Adjacent item titles are previewed below the navigation labels; customize them with `getItemTitle`. Set `keyboardShortcuts` for J/K or ]/[ tour navigation, or use `useKeepTourShortcuts` for custom bindings. `KeepReorderableList` supports drag and keyboard reordering and shows the active insertion position.
 Cards rendered by `KeepList` and `KeepCollection` highlight case-insensitive search matches with `<mark class="keep-highlight" data-highlight="true">`. Use `highlightQuery` on a standalone `KeepItemCard` or `KeepHighlight` for arbitrary text. `KeepItemCard.Media` exposes its loading state through `data-media-status` and replaces failed images with `fallback` or the built-in SVG placeholder.
+The theme defines WCAG-oriented `--keep-highlight-bg` / `--keep-highlight-fg` pairs for light and dark modes, clamps titles to two lines and memo previews to three, and reserves a stable media aspect ratio. `KeepItemStatusBadge` combines visible status text with check, clock, ban, or lock SVG icons; import `@keepkit/ui/styles/status.css` when using the status styles independently.
 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.
 
 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`.
@@ -201,7 +203,7 @@ const onFeedback = useKeepToastFeedback(toast);
 <KeepKitProvider storage={storage} onFeedback={onFeedback}>{children}</KeepKitProvider>;
 ```
 
-In v0.17.0, use `KeepTourBar` / `KeepNavigator`, `KeepReorderableList`, and `useKeepTourShortcuts` for continuous saved-item tours. `KeepCollection urlSync` with `layout="list" | "grid" | "compact"`, `KeepBulkActions selectionScope="page" | "query" | "all"`, and `KeepUndo` remain available. `createNextPagesRouterAdapter` is the injected adapter for Next.js Pages Router. `locale` includes 16 built-in dictionaries, and `labels` overrides individual entries. Authenticated sync is available through `createAuthenticatedSyncKit`.
+In v0.18.0, use `KeepTourBar` / `KeepNavigator`, `KeepReorderableList`, and `useKeepTourShortcuts` for continuous saved-item tours. `KeepCollection urlSync` with `layout="list" | "grid" | "compact"`, `KeepBulkActions selectionScope="page" | "query" | "all"`, and `KeepUndo` remain available. `createNextPagesRouterAdapter` is the injected adapter for Next.js Pages Router. `locale` includes 16 built-in dictionaries, and `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

package/dist/index.d.ts

@@ -1,69 +1,40 @@
 import * as react from 'react';
-import { ReactNode, HTMLAttributes, ComponentType, ImgHTMLAttributes, MouseEvent, HTMLAttributeAnchorTarget, InputHTMLAttributes, FormHTMLAttributes, KeyboardEvent, ButtonHTMLAttributes, SelectHTMLAttributes, CSSProperties } from 'react';
-import { KeepItem, ImportItemsResult, KeepListQuery, KeepUrlSyncOptions, KeepItemStatus, KeepSyncConflict, KeepItemInput } from '@keepkit/core/core';
+import { HTMLAttributes, ReactNode, ComponentType, InputHTMLAttributes, ImgHTMLAttributes, MouseEvent, HTMLAttributeAnchorTarget, KeyboardEvent, FormHTMLAttributes, SelectHTMLAttributes, ButtonHTMLAttributes, CSSProperties } from 'react';
+import { KeepListQuery, KeepUrlSyncOptions, ImportItemsResult, KeepItem, 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, UseKeepNavigatorResult, CreateKeepKitOptions as CreateKeepKitOptions$1, KeepProviderProps, useKeepContext, useKeepItem, useKeepList, UseKeepNavigatorOptions, KeepShortcutOptions } from '@keepkit/core/react';
 export { KeepButtonState, KeepContextValue, KeepErrorBoundary, KeepErrorBoundaryProps, KeepProvider, KeepProviderProps, KeepShortcutOptions, useKeepContext, useKeepItem, useKeepList, useKeepNavigator, useKeepShortcut } from '@keepkit/core/react';
 export { FallbackStorageAdapter, IndexedDBAdapter, IndexedDBSyncQueueAdapter, LocalStorageAdapter, LocalStorageSyncQueueAdapter, SyncStorageAdapter, createBrowserStorageAdapter, createStorageAdapter } from '@keepkit/core/storage';
 
-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" | "restoredMessage" | "syncFailedMessage" | "stalePrunedMessage" | "undo" | "undoAvailable" | "selectionScope" | "currentPage" | "searchResults" | "allItems" | "localVersion" | "remoteVersion" | "updatedAt" | "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>>;
-    customLabels?: KeepUiLabels;
-    labelResolver?: (key: KeepUiLabelKey, context: {
-        locale?: string;
-    }) => string | undefined;
-    emitFeedback: <TMeta>(event: KeepUiFeedbackEvent<TMeta>) => void;
-};
-type KeepUiFeedbackBase<TType extends string> = {
-    type: TType;
-    message: string;
-};
-type KeepUiFeedbackEvent<TMeta = Record<string, unknown>> = (KeepUiFeedbackBase<"item-saved"> & {
-    item: KeepItem<TMeta>;
-}) | (KeepUiFeedbackBase<"item-removed"> & {
-    item: KeepItem<TMeta>;
-    undo: () => void | Promise<void>;
-    undoLabel: string;
-}) | (KeepUiFeedbackBase<"item-restored"> & {
-    item?: KeepItem<TMeta>;
-    items: KeepItem<TMeta>[];
-}) | KeepUiFeedbackBase<"sync-completed"> | (KeepUiFeedbackBase<"sync-failed"> & {
-    error: unknown;
-}) | (KeepUiFeedbackBase<"stale-pruned"> & {
-    item?: KeepItem<TMeta>;
-    items: KeepItem<TMeta>[];
-    undo: () => void | Promise<void>;
-    undoLabel: string;
-});
-type KeepUiProviderProps<TMeta = Record<string, unknown>> = {
-    labels?: KeepUiLabels;
-    locale?: string;
-    labelResolver?: KeepUiLabelContext["labelResolver"];
-    onFeedback?: (event: KeepUiFeedbackEvent<TMeta>) => void;
-    children?: ReactNode;
+type KeepUrlAdapter = {
+    getUrl: () => string;
+    subscribe?: (listener: () => void) => () => void;
+    navigate: (url: string, mode: "replace" | "push") => void;
 };
-/** Provides one complete locale-aware label source to every UI primitive. */
-declare function KeepUiProvider<TMeta = Record<string, unknown>>({ labels, locale, labelResolver, onFeedback, children, }: KeepUiProviderProps<TMeta>): react.JSX.Element;
-declare function useKeepUiLabels(): KeepUiLabelContext;
-
-type KeepToastFeedbackOptions = {
-    action?: {
-        label: string;
-        onClick: () => void;
+type KeepPagesRouterLike = {
+    asPath?: string;
+    push: (url: string, as?: string, options?: {
+        shallow?: boolean;
+    }) => Promise<boolean> | boolean;
+    replace: (url: string, as?: string, options?: {
+        shallow?: boolean;
+    }) => Promise<boolean> | boolean;
+    events?: {
+        on: (event: string, listener: () => void) => void;
+        off: (event: string, listener: () => void) => void;
     };
 };
-type KeepToastHandler = (message: string, options?: KeepToastFeedbackOptions) => unknown;
-/** Adapts KeepKit feedback to Sonner-like toast functions without adding a toast dependency. */
-declare function useKeepToastFeedback<TMeta = Record<string, unknown>>(showToast: KeepToastHandler): (event: KeepUiFeedbackEvent<TMeta>) => void;
+type KeepUrlSyncProps<TMeta = Record<string, unknown>> = {
+    enabled?: boolean;
+    query: KeepListQuery<TMeta>;
+    onQueryChange: (query: KeepListQuery<TMeta> | ((previous: KeepListQuery<TMeta>) => KeepListQuery<TMeta>)) => void;
+    options?: KeepUrlSyncOptions;
+    adapter?: KeepUrlAdapter;
+};
+/** Adapter for Next.js Pages Router. It intentionally uses structural typing and has no Next dependency. */
+declare function createNextPagesRouterAdapter(router: KeepPagesRouterLike): KeepUrlAdapter;
+/** Synchronizes collection filters with browser history and supports back/forward restoration. */
+declare function useKeepUrlSync<TMeta = Record<string, unknown>>({ enabled, query, onQueryChange, options, adapter: providedAdapter, }: KeepUrlSyncProps<TMeta>): void;
 
 type KeepBackupProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLElement>, "children"> & {
     filename?: string;
@@ -150,6 +121,22 @@ type KeepButtonProps<TMeta = Record<string, unknown>> = KeepButtonProps$1<TMeta>
 /** A style-free save toggle with localized labels and the core button's ARIA/asChild behavior. */
 declare function KeepButton<TMeta = Record<string, unknown>>({ labels, icons, iconOnly, showLabel, iconClassName, onClick, onToggleError, ...props }: KeepButtonProps<TMeta>): react.JSX.Element;
 
+type KeepItemCheckboxProps<TMeta = Record<string, unknown>> = Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "checked" | "defaultChecked" | "onChange"> & {
+    item: KeepItem<TMeta>;
+    checked?: boolean;
+    label?: ReactNode;
+    onCheckedChange?: (checked: boolean) => void;
+};
+/** 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 KeepUndoProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
+    children?: ReactNode;
+    label?: ReactNode;
+};
+/** Presents the short-lived undo action created by removeWithUndo/removeBatchWithUndo. */
+declare function KeepUndo({ children, label, ...props }: KeepUndoProps): react.JSX.Element | null;
+
 type KeepItemCardState<TMeta = Record<string, unknown>> = {
     item: KeepItem<TMeta>;
     isSaved: boolean;
@@ -216,6 +203,7 @@ declare function KeepItemCardMedia({ children, fallback, ...props }: KeepItemCar
 declare function KeepItemCardContent({ children, ...props }: KeepItemCardContentProps): react.JSX.Element;
 declare function KeepItemCardTitle({ as, children, ...props }: KeepItemCardTitleProps): react.DetailedReactHTMLElement<{
     "data-keep-card-part": string;
+    "data-line-clamp": string;
     onChange?: react.ChangeEventHandler<HTMLHeadingElement, Element> | undefined;
     onError?: react.ReactEventHandler<HTMLHeadingElement> | undefined;
     className?: string | undefined | undefined;
@@ -528,36 +516,6 @@ type KeepListProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLEl
 /** A list primitive with built-in loading, empty, error, and removal states. */
 declare function KeepList<TMeta = Record<string, unknown>>(props: KeepListProps<TMeta>): react.JSX.Element;
 
-type KeepUrlAdapter = {
-    getUrl: () => string;
-    subscribe?: (listener: () => void) => () => void;
-    navigate: (url: string, mode: "replace" | "push") => void;
-};
-type KeepPagesRouterLike = {
-    asPath?: string;
-    push: (url: string, as?: string, options?: {
-        shallow?: boolean;
-    }) => Promise<boolean> | boolean;
-    replace: (url: string, as?: string, options?: {
-        shallow?: boolean;
-    }) => Promise<boolean> | boolean;
-    events?: {
-        on: (event: string, listener: () => void) => void;
-        off: (event: string, listener: () => void) => void;
-    };
-};
-type KeepUrlSyncProps<TMeta = Record<string, unknown>> = {
-    enabled?: boolean;
-    query: KeepListQuery<TMeta>;
-    onQueryChange: (query: KeepListQuery<TMeta> | ((previous: KeepListQuery<TMeta>) => KeepListQuery<TMeta>)) => void;
-    options?: KeepUrlSyncOptions;
-    adapter?: KeepUrlAdapter;
-};
-/** Adapter for Next.js Pages Router. It intentionally uses structural typing and has no Next dependency. */
-declare function createNextPagesRouterAdapter(router: KeepPagesRouterLike): KeepUrlAdapter;
-/** Synchronizes collection filters with browser history and supports back/forward restoration. */
-declare function useKeepUrlSync<TMeta = Record<string, unknown>>({ enabled, query, onQueryChange, options, adapter: providedAdapter, }: KeepUrlSyncProps<TMeta>): void;
-
 type KeepCollectionFeature = "search" | "sort" | "pagination" | "tagFilter" | "bulkActions";
 type KeepLayoutPreset = "list" | "grid" | "compact" | "auto";
 type KeepCollectionProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLElement>, "children"> & {
@@ -582,23 +540,6 @@ type KeepCollectionProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<
 /** A batteries-included collection with query controls and accessible status feedback. */
 declare function KeepCollection<TMeta = Record<string, unknown>>(props: KeepCollectionProps<TMeta>): react.JSX.Element;
 
-type KeepItemCheckboxProps<TMeta = Record<string, unknown>> = Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "checked" | "defaultChecked" | "onChange"> & {
-    item: KeepItem<TMeta>;
-    checked?: boolean;
-    label?: ReactNode;
-    onCheckedChange?: (checked: boolean) => void;
-};
-/** 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 | "restricted";
-    label?: ReactNode;
-};
-type KeepDisplayStatus = "available" | "expired" | "removed" | "restricted";
-/** 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;
@@ -606,31 +547,6 @@ type KeepLayoutProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
 /** A container-aware layout wrapper with a stable preset attribute for host or theme CSS. */
 declare function KeepLayout({ layout, children, onKeyDown, onFocusCapture, ...props }: KeepLayoutProps): react.JSX.Element;
 
-type KeepNoteEditorState<TMeta = Record<string, unknown>> = {
-    item: KeepItem<TMeta>;
-    note: string;
-    setNote: (note: string) => void;
-    isDirty: boolean;
-    isSaving: boolean;
-    error: unknown | null;
-    save: () => Promise<void>;
-};
-type KeepNoteEditorProps<TMeta = Record<string, unknown>> = Omit<FormHTMLAttributes<HTMLFormElement>, "children" | "onSubmit"> & {
-    item: KeepItem<TMeta>;
-    label?: ReactNode;
-    saveLabel?: ReactNode;
-    placeholder?: string;
-    /** Automatically save dirty notes after this delay; set to 0 to disable auto-save. */
-    debounceMs?: number;
-    onSaved?: (note?: string) => void;
-    onSaveError?: (error: unknown) => void;
-    render?: RenderProp<KeepNoteEditorState<TMeta>>;
-    children?: ReactNode | RenderProp<KeepNoteEditorState<TMeta>>;
-    asChild?: boolean;
-};
-/** 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 KeepReorderableItemState = {
     index: number;
     isDragging: boolean;
@@ -638,6 +554,7 @@ type KeepReorderableItemState = {
         role: "button";
         tabIndex: 0;
         draggable: true;
+        "data-drag-handle": "true";
         "aria-label": string;
         "aria-grabbed": boolean;
         onDragStart: () => void;
@@ -660,45 +577,30 @@ declare function KeepReorderableList<TItem extends {
     id: string;
 } = KeepItem>({ items, onReorder, renderItem, itemLabel, ...props }: KeepReorderableListProps<TItem>): react.JSX.Element;
 
-type KeepStaleNoticeProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLElement>, "children"> & {
+type KeepNoteEditorState<TMeta = Record<string, unknown>> = {
     item: KeepItem<TMeta>;
-    onRetry?: (item: KeepItem<TMeta>) => void | Promise<void>;
-    onRemoved?: (item: KeepItem<TMeta>) => void;
-    retryLabel?: ReactNode;
-    removeLabel?: ReactNode;
-    children?: ReactNode;
+    note: string;
+    setNote: (note: string) => void;
+    isDirty: boolean;
+    isSaving: boolean;
+    error: unknown | null;
+    save: () => Promise<void>;
 };
-/** 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[];
+type KeepNoteEditorProps<TMeta = Record<string, unknown>> = Omit<FormHTMLAttributes<HTMLFormElement>, "children" | "onSubmit"> & {
+    item: KeepItem<TMeta>;
     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;
+    saveLabel?: ReactNode;
+    placeholder?: string;
+    /** Automatically save dirty notes after this delay; set to 0 to disable auto-save. */
+    debounceMs?: number;
+    onSaved?: (note?: string) => void;
+    onSaveError?: (error: unknown) => void;
+    render?: RenderProp<KeepNoteEditorState<TMeta>>;
+    children?: ReactNode | RenderProp<KeepNoteEditorState<TMeta>>;
+    asChild?: boolean;
 };
-/** Announces synchronization failures and exposes retry or conflict-recovery entry points. */
-declare function KeepSyncStatusBanner({ onRetry, onResolveConflicts, children, className, ...props }: KeepSyncStatusBannerProps): react.JSX.Element | null;
+/** 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 KeepTagEditorState = {
     tags: string[];
@@ -716,27 +618,72 @@ type KeepTagEditorProps<TMeta = Record<string, unknown>> = Omit<FormHTMLAttribut
 /** Edits one item's normalized tag set; Enter adds and Backspace removes the last tag. */
 declare function KeepTagEditor<TMeta = Record<string, unknown>>({ item, availableTags, onSaved, onSaveError, render, ...props }: KeepTagEditorProps<TMeta>): react.JSX.Element;
 
-type KeepTagFilterState = {
-    tags: string[];
-    tagCounts: Record<string, number>;
-    value?: string;
-    select: (tag?: string) => void;
+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" | "restoredMessage" | "syncFailedMessage" | "stalePrunedMessage" | "undo" | "undoAvailable" | "selectionScope" | "currentPage" | "searchResults" | "allItems" | "localVersion" | "remoteVersion" | "updatedAt" | "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>>;
+    customLabels?: KeepUiLabels;
+    labelResolver?: (key: KeepUiLabelKey, context: {
+        locale?: string;
+    }) => string | undefined;
+    emitFeedback: <TMeta>(event: KeepUiFeedbackEvent<TMeta>) => void;
 };
-type KeepTagFilterProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLElement>, "children" | "onChange"> & {
-    query?: KeepListQuery<TMeta>;
-    value?: string;
-    defaultValue?: string;
-    onChange?: (tag?: string) => void;
-    onValueChange?: (tag?: string) => void;
-    allLabel?: ReactNode;
-    ariaLabel?: string;
-    renderTag?: (tag: string, count: number, selected: boolean) => ReactNode;
-    render?: RenderProp<KeepTagFilterState>;
-    children?: ReactNode | RenderProp<KeepTagFilterState>;
-    asChild?: boolean;
+type KeepUiFeedbackBase<TType extends string> = {
+    type: TType;
+    message: string;
 };
-/** An ARIA button group for tag filtering; consumers can connect value to a collection query. */
-declare function KeepTagFilter<TMeta = Record<string, unknown>>({ query, value: controlledValue, defaultValue, onChange, onValueChange, allLabel, ariaLabel, renderTag, render, children, asChild, className, ...rootProps }: KeepTagFilterProps<TMeta>): react.ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+type KeepUiFeedbackEvent<TMeta = Record<string, unknown>> = (KeepUiFeedbackBase<"item-saved"> & {
+    item: KeepItem<TMeta>;
+}) | (KeepUiFeedbackBase<"item-removed"> & {
+    item: KeepItem<TMeta>;
+    undo: () => void | Promise<void>;
+    undoLabel: string;
+}) | (KeepUiFeedbackBase<"item-restored"> & {
+    item?: KeepItem<TMeta>;
+    items: KeepItem<TMeta>[];
+}) | KeepUiFeedbackBase<"sync-completed"> | (KeepUiFeedbackBase<"sync-failed"> & {
+    error: unknown;
+}) | (KeepUiFeedbackBase<"stale-pruned"> & {
+    item?: KeepItem<TMeta>;
+    items: KeepItem<TMeta>[];
+    undo: () => void | Promise<void>;
+    undoLabel: string;
+});
+type KeepUiProviderProps<TMeta = Record<string, unknown>> = {
+    labels?: KeepUiLabels;
+    locale?: string;
+    labelResolver?: KeepUiLabelContext["labelResolver"];
+    onFeedback?: (event: KeepUiFeedbackEvent<TMeta>) => void;
+    children?: ReactNode;
+};
+/** Provides one complete locale-aware label source to every UI primitive. */
+declare function KeepUiProvider<TMeta = Record<string, unknown>>({ labels, locale, labelResolver, onFeedback, children, }: KeepUiProviderProps<TMeta>): react.JSX.Element;
+declare function useKeepUiLabels(): KeepUiLabelContext;
+
+type KeepToastFeedbackOptions = {
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
+};
+type KeepToastHandler = (message: string, options?: KeepToastFeedbackOptions) => unknown;
+/** Adapts KeepKit feedback to Sonner-like toast functions without adding a toast dependency. */
+declare function useKeepToastFeedback<TMeta = Record<string, unknown>>(showToast: KeepToastHandler): (event: KeepUiFeedbackEvent<TMeta>) => void;
+
+type KeepItemStatusBadgeProps = Omit<HTMLAttributes<HTMLSpanElement>, "children"> & {
+    status?: KeepItemStatus | "restricted";
+    label?: ReactNode;
+};
+type KeepDisplayStatus = "available" | "expired" | "removed" | "restricted";
+/** Displays the normalized availability state of a saved item. */
+declare function KeepItemStatusBadge({ status, label, className, ...props }: KeepItemStatusBadgeProps): react.JSX.Element;
 
 type KeepTourShortcutsOptions = {
     onNext: () => void | Promise<void>;
@@ -768,17 +715,33 @@ type KeepTourBarProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTM
     keyboardShortcuts?: boolean;
     shortcutOptions?: Omit<KeepTourShortcutsOptions, "onNext" | "onPrev">;
     progress?: ReactNode;
+    getItemTitle?: (item: KeepItem<TMeta>) => ReactNode;
 };
 /** Headless previous/current/next navigation with optional URL links and keyboard shortcuts. */
-declare function KeepTourBar<TMeta = Record<string, unknown>>({ navigation: providedNavigation, currentId, initialIndex, showProgress, prevHref, nextHref, backHref, onPrev, onNext, onBack, prevLabel, nextLabel, backLabel, keyboardShortcuts, shortcutOptions, progress, ...props }: KeepTourBarProps<TMeta>): react.JSX.Element;
+declare function KeepTourBar<TMeta = Record<string, unknown>>({ navigation: providedNavigation, currentId, initialIndex, showProgress, prevHref, nextHref, backHref, onPrev, onNext, onBack, prevLabel, nextLabel, backLabel, keyboardShortcuts, shortcutOptions, progress, getItemTitle, ...props }: KeepTourBarProps<TMeta>): react.JSX.Element;
 declare const KeepNavigator: typeof KeepTourBar;
 
-type KeepUndoProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
-    children?: ReactNode;
-    label?: ReactNode;
+type KeepTagFilterState = {
+    tags: string[];
+    tagCounts: Record<string, number>;
+    value?: string;
+    select: (tag?: string) => void;
 };
-/** Presents the short-lived undo action created by removeWithUndo/removeBatchWithUndo. */
-declare function KeepUndo({ children, label, ...props }: KeepUndoProps): react.JSX.Element | null;
+type KeepTagFilterProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLElement>, "children" | "onChange"> & {
+    query?: KeepListQuery<TMeta>;
+    value?: string;
+    defaultValue?: string;
+    onChange?: (tag?: string) => void;
+    onValueChange?: (tag?: string) => void;
+    allLabel?: ReactNode;
+    ariaLabel?: string;
+    renderTag?: (tag: string, count: number, selected: boolean) => ReactNode;
+    render?: RenderProp<KeepTagFilterState>;
+    children?: ReactNode | RenderProp<KeepTagFilterState>;
+    asChild?: boolean;
+};
+/** An ARIA button group for tag filtering; consumers can connect value to a collection query. */
+declare function KeepTagFilter<TMeta = Record<string, unknown>>({ query, value: controlledValue, defaultValue, onChange, onValueChange, allLabel, ariaLabel, renderTag, render, children, asChild, className, ...rootProps }: KeepTagFilterProps<TMeta>): react.ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
 type KeepSearchInputProps = Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "defaultValue" | "onChange"> & {
     value?: string;
@@ -813,6 +776,25 @@ type KeepPaginationProps = Omit<React.HTMLAttributes<HTMLElement>, "children"> &
 /** Accessible pagination with previous/next controls and numbered page buttons. */
 declare function KeepPagination({ totalCount, pageSize, page, maxPageButtons, onPageChange, render, ...props }: KeepPaginationProps): 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 KeepEmptyStateProps = Omit<HTMLAttributes<HTMLElement>, "children" | "title"> & {
     title?: ReactNode;
     description?: ReactNode;
@@ -847,6 +829,27 @@ declare function KeepAnnouncements<TMeta = Record<string, unknown>>({ messages,
 /** Singular alias for applications that mount one announcer explicitly. */
 declare const KeepAnnouncer: typeof KeepAnnouncements;
 
+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;
+
 declare const keepThemeNames: readonly ["default", "ocean", "forest", "sunset", "lavender", "compact", "minimal", "rounded", "high-contrast", "dark"];
 type KeepThemeName = (typeof keepThemeNames)[number];
 type KeepThemeMode = "light" | "dark" | "system";