@keepkit/ui 0.17.0 → 0.19.0

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, ReactElement, 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;
@@ -101,6 +72,12 @@ type KeepButtonIcons = {
     loading?: KeepButtonIcon;
     error?: KeepButtonIcon;
 };
+type MergeableProps = Record<string, unknown>;
+/** Chains child and component event handlers while preserving both handlers' event order. */
+declare function chainedFunction<T extends (...args: never[]) => unknown>(childHandler: T | undefined, parentHandler: T | undefined): T | undefined;
+/** Merges slot props without dropping child classes, styles, ARIA attributes, or events. */
+declare function mergeProps<T extends MergeableProps>(childProps: T, parentProps: Partial<T> & MergeableProps): T;
+declare function createSlot(child: ReactElement<MergeableProps>, props: MergeableProps, body?: ReactNode): ReactElement<MergeableProps>;
 
 /** Returns whether every visible item is selected. Empty lists are never all selected. */
 declare function isAllSelected<TMeta>(items: readonly Pick<KeepItem<TMeta>, "id">[], selectedIds: readonly string[]): boolean;
@@ -150,6 +127,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 +209,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;
@@ -518,6 +512,7 @@ type KeepListProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLEl
     loadingCount?: number;
     empty?: ReactNode | RenderProp<KeepListState<TMeta>>;
     error?: ReactNode | RenderProp<KeepListState<TMeta>>;
+    onClearFilters?: () => void;
     itemCardProps?: Omit<KeepItemCardProps<TMeta>, "item" | "children" | "render">;
     layout?: KeepLayoutPreset;
     asChild?: boolean;
@@ -528,36 +523,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"> & {
@@ -573,6 +538,7 @@ type KeepCollectionProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<
     /** Alias for `loading`. When neither is provided, KeepList renders skeleton cards. */
     renderLoading?: ReactNode | RenderProp<KeepListState<TMeta>>;
     loadingCount?: number;
+    activeFilters?: ReactNode | RenderProp<KeepListState<TMeta>>;
     empty?: ReactNode | RenderProp<KeepListState<TMeta>>;
     error?: ReactNode | RenderProp<KeepListState<TMeta>>;
     fallback?: KeepErrorBoundaryProps["fallback"];
@@ -582,23 +548,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 +555,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 +562,7 @@ type KeepReorderableItemState = {
         role: "button";
         tabIndex: 0;
         draggable: true;
+        "data-drag-handle": "true";
         "aria-label": string;
         "aria-grabbed": boolean;
         onDragStart: () => void;
@@ -660,45 +585,31 @@ 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;
+    showShortcutHint?: boolean;
+    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, showShortcutHint, onSaved, onSaveError, render, children, asChild, className, ...formProps }: KeepNoteEditorProps<TMeta>): react.JSX.Element;
 
 type KeepTagEditorState = {
     tags: string[];
@@ -716,27 +627,79 @@ 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" | "activeFilters" | "clearFilters" | "clearAllFilters" | "removeFilter" | "noFilteredItems" | "noFilteredItemsDescription" | "emptyStorageDescription" | "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 KeepShortcutHintProps = Omit<HTMLAttributes<HTMLSpanElement>, "children"> & {
+    shortcut: string | readonly string[];
+    separator?: ReactNode;
+};
+/** Displays a keyboard shortcut using semantic kbd elements. */
+declare function KeepShortcutHint({ shortcut, separator, ...props }: KeepShortcutHintProps): react.JSX.Element;
 
 type KeepTourShortcutsOptions = {
     onNext: () => void | Promise<void>;
@@ -766,19 +729,59 @@ type KeepTourBarProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTM
     nextLabel?: string;
     backLabel?: string;
     keyboardShortcuts?: boolean;
+    showShortcutHint?: boolean;
     shortcutOptions?: Omit<KeepTourShortcutsOptions, "onNext" | "onPrev">;
     progress?: ReactNode;
+    getItemTitle?: (item: KeepItem<TMeta>) => ReactNode;
+    children?: ReactNode;
+    asChild?: boolean;
 };
 /** 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, showShortcutHint, shortcutOptions, progress, getItemTitle, children, asChild, ...props }: KeepTourBarProps<TMeta>): react.ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 declare const KeepNavigator: typeof KeepTourBar;
 
-type KeepUndoProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
-    children?: ReactNode;
-    label?: ReactNode;
+type KeepActiveFiltersSummaryProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLElement>, "children"> & {
+    query?: KeepListQuery<TMeta>;
+    search?: string;
+    tags?: readonly string[];
+    onSearchChange?: (value: string) => void;
+    onTagChange?: (tag: string) => void;
+    onClear?: () => void;
+    children?: ReactNode | RenderProp<KeepActiveFiltersSummaryState>;
+    asChild?: boolean;
 };
-/** Presents the short-lived undo action created by removeWithUndo/removeBatchWithUndo. */
-declare function KeepUndo({ children, label, ...props }: KeepUndoProps): react.JSX.Element | null;
+type KeepActiveFiltersSummaryState = {
+    search: string;
+    tags: string[];
+    hasFilters: boolean;
+    clear: () => void;
+    removeSearch: () => void;
+    removeTag: (tag: string) => void;
+};
+/** Lists active search and tag filters with one-tap recovery actions. */
+declare function KeepActiveFiltersSummary<TMeta = Record<string, unknown>>({ query, search: providedSearch, tags: providedTags, onSearchChange, onTagChange, onClear, children, asChild, className, ...rootProps }: KeepActiveFiltersSummaryProps<TMeta>): ReactElement<unknown, string | react.JSXElementConstructor<any>> | null;
+
+type KeepTagFilterState = {
+    tags: string[];
+    tagCounts: Record<string, number>;
+    value?: string;
+    select: (tag?: string) => 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;
+};
+/** 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,15 +816,38 @@ 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 KeepEmptyStateVariant = "empty-storage" | "empty-filtered";
 type KeepEmptyStateProps = Omit<HTMLAttributes<HTMLElement>, "children" | "title"> & {
     title?: ReactNode;
     description?: ReactNode;
     action?: ReactNode;
     children?: ReactNode;
+    variant?: KeepEmptyStateVariant;
+    onClearFilters?: () => void;
     asChild?: boolean;
 };
-/** A style-free, reusable empty collection state. */
-declare function KeepEmptyState({ title, description, action, children, asChild, className, ...rootProps }: KeepEmptyStateProps): react.ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+/** An accessible empty state that distinguishes an empty store from an empty filter result. */
+declare function KeepEmptyState({ title, description, action, children, variant, onClearFilters, asChild, className, ...rootProps }: KeepEmptyStateProps): react.ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
 type KeepStatusValue = "idle" | "empty" | "loading" | "saving" | "syncing" | "error";
 type KeepStatusLabels = Partial<Record<KeepStatusValue, ReactNode>>;
 type KeepStatusState<TMeta = Record<string, unknown>> = {
@@ -847,6 +873,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";
@@ -913,4 +960,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 KeepButtonIcon, type KeepButtonIconProps, type KeepButtonIcons, type KeepButtonLabels, type KeepButtonProps, KeepCollection, type KeepCollectionFeature, type KeepCollectionProps, type KeepDisplayStatus, KeepEmptyState, type KeepEmptyStateProps, KeepHighlight, type KeepHighlightProps, type KeepImageProps, KeepItemCard, type KeepItemCardActionsProps, type KeepItemCardContentProps, type KeepItemCardLinkProps, type KeepItemCardMediaProps, type KeepItemCardProps, KeepItemCardSkeleton, type KeepItemCardSkeletonProps, type KeepItemCardState, type KeepItemCardTagsProps, type KeepItemCardTitleProps, KeepItemCheckbox, type KeepItemCheckboxProps, KeepItemStatusBadge, type KeepItemStatusBadgeProps, type KeepKit, KeepKitProvider, type KeepKitProviderProps, KeepLayout, type KeepLayoutPreset, type KeepLayoutProps, KeepList, type KeepListProps, type KeepListState, KeepNavigator, KeepNoteEditor, type KeepNoteEditorProps, type KeepNoteEditorState, type KeepPagesRouterLike, KeepPagination, type KeepPaginationProps, type KeepPaginationState, KeepPruneStaleButton, type KeepPruneStaleButtonProps, type KeepReorderableItemState, KeepReorderableList, type KeepReorderableListProps, 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 KeepToastFeedbackOptions, type KeepToastHandler, KeepTourBar, type KeepTourBarProps, type KeepTourShortcutsOptions, type KeepUiFeedbackEvent, type KeepUiLabelContext, type KeepUiLabelKey, type KeepUiLabels, type KeepUiLocale, type KeepUiLocaleLabels, KeepUiProvider, type KeepUiProviderProps, KeepUndo, type KeepUndoProps, type KeepUrlAdapter, type RenderProp, createKeepKit, createNextPagesRouterAdapter, getKeepLocaleLabels, highlightText, isAllSelected, keepThemeNames, toggleSelectAll, useKeepToastFeedback, useKeepTourShortcuts, useKeepUiLabels, useKeepUrlSync };
+export { type CreateKeepKitOptions, KeepActiveFiltersSummary, type KeepActiveFiltersSummaryProps, type KeepActiveFiltersSummaryState, 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, type KeepDisplayStatus, KeepEmptyState, type KeepEmptyStateProps, type KeepEmptyStateVariant, KeepHighlight, type KeepHighlightProps, type KeepImageProps, KeepItemCard, type KeepItemCardActionsProps, type KeepItemCardContentProps, type KeepItemCardLinkProps, type KeepItemCardMediaProps, type KeepItemCardProps, KeepItemCardSkeleton, type KeepItemCardSkeletonProps, type KeepItemCardState, type KeepItemCardTagsProps, type KeepItemCardTitleProps, KeepItemCheckbox, type KeepItemCheckboxProps, KeepItemStatusBadge, type KeepItemStatusBadgeProps, type KeepKit, KeepKitProvider, type KeepKitProviderProps, KeepLayout, type KeepLayoutPreset, type KeepLayoutProps, KeepList, type KeepListProps, type KeepListState, KeepNavigator, KeepNoteEditor, type KeepNoteEditorProps, type KeepNoteEditorState, type KeepPagesRouterLike, KeepPagination, type KeepPaginationProps, type KeepPaginationState, KeepPruneStaleButton, type KeepPruneStaleButtonProps, type KeepReorderableItemState, KeepReorderableList, type KeepReorderableListProps, KeepSearchInput, type KeepSearchInputProps, type KeepSelectionScope, KeepShortcutHint, type KeepShortcutHintProps, 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 KeepToastFeedbackOptions, type KeepToastHandler, KeepTourBar, type KeepTourBarProps, type KeepTourShortcutsOptions, type KeepUiFeedbackEvent, type KeepUiLabelContext, type KeepUiLabelKey, type KeepUiLabels, type KeepUiLocale, type KeepUiLocaleLabels, KeepUiProvider, type KeepUiProviderProps, KeepUndo, type KeepUndoProps, type KeepUrlAdapter, type RenderProp, chainedFunction, createKeepKit, createNextPagesRouterAdapter, createSlot, getKeepLocaleLabels, highlightText, isAllSelected, keepThemeNames, mergeProps, toggleSelectAll, useKeepToastFeedback, useKeepTourShortcuts, useKeepUiLabels, useKeepUrlSync };