@keepkit/ui 0.5.0 → 0.6.0

package/README.md

@@ -32,7 +32,7 @@ function SavedArticles() {
 }
 ```
 
-`keep.Collection`は検索、ソート、ページング、loading / empty / error、ARIA live通知を標準で提供します。`features={{ tagFilter: true, bulkActions: true }}`でタグフィルターと一括操作も有効にできます。個別の`KeepList`、`KeepSearchInput`、`KeepSortSelect`、`KeepPagination`などは高度なレイアウト用に利用できます。
+`keep.Collection`は検索、ソート、ページング、loading / empty / error、ARIA live通知を標準で提供します。検索は既定で300msデバウンスされます。`features={{ tagFilter: true, bulkActions: true }}`でタグフィルターと一括操作も有効にできます。個別の`KeepList`、`KeepSearchInput`、`KeepSortSelect`、`KeepPagination`、`KeepItemCheckbox`、`KeepTagEditor`などは高度なレイアウト用に利用できます。`KeepBulkActions`はrender propsで操作UIを差し替えられます。
 
 一覧のqueryは次の形式に統一されています。
 
@@ -81,7 +81,7 @@ function SavedArticles() {
 }
 ```
 
-`keep.Collection` includes search, sorting, pagination, loading/empty/error states, and polite live announcements. Enable `features={{ tagFilter: true, bulkActions: true }}` for tag filtering and bulk operations. Use the individual `KeepList`, `KeepSearchInput`, `KeepSortSelect`, and `KeepPagination` primitives when you need a custom layout.
+`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 for replacing its operation UI.
 
 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,12 +1,54 @@
 import * as react from 'react';
-import { ReactNode, ImgHTMLAttributes, HTMLAttributes, ComponentType, ReactElement, FormHTMLAttributes, InputHTMLAttributes, SelectHTMLAttributes } from 'react';
+import { InputHTMLAttributes, ReactNode, SelectHTMLAttributes, ImgHTMLAttributes, HTMLAttributes, ComponentType, ReactElement, FormHTMLAttributes } from 'react';
 import { KeepItem, KeepListQuery, KeepItemInput } from '@keepkit/core/core';
 export { KeepItem, KeepItemInput, KeepListQuery, KeepSyncStatus } from '@keepkit/core/core';
 import { CreateKeepKitOptions as CreateKeepKitOptions$1, KeepButtonProps as KeepButtonProps$1, UseKeepListResult, KeepProviderProps, useKeepContext, useKeepItem, KeepShortcutOptions } from '@keepkit/core/react';
 export { KeepContextValue, KeepProvider, KeepProviderProps, KeepShortcutOptions, useKeepContext, useKeepItem, useKeepList, 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" | "filterTags" | "note" | "saveNote" | "noItems" | "loadingItems" | "errorItems" | "search" | "sort" | "newest" | "oldest" | "previousPage" | "nextPage" | "pagination" | "page" | "selectItems" | "selectedCount" | "deleteSelected" | "tagsToApply" | "applyTags" | "savedMessage" | "removedMessage" | "noteSavedMessage";
+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 KeepSearchInputProps = Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "defaultValue" | "onChange"> & {
+    value?: string;
+    defaultValue?: string;
+    /** Delay before notifying consumers; set to 0 to disable debouncing. */
+    debounceMs?: number;
+    onValueChange?: (value: string) => void;
+};
+/** A controlled/uncontrolled search field with a small built-in debounce. */
+declare function KeepSearchInput({ value: controlledValue, defaultValue, debounceMs, onValueChange, "aria-label": ariaLabel, placeholder, ...props }: KeepSearchInputProps): react.JSX.Element;
+type KeepSortValue = "savedAt:desc" | "savedAt:asc" | "updatedAt:desc" | "updatedAt:asc";
+type KeepSortSelectProps = Omit<SelectHTMLAttributes<HTMLSelectElement>, "value" | "defaultValue" | "onChange"> & {
+    value?: KeepSortValue;
+    defaultValue?: KeepSortValue;
+    onValueChange?: (value: KeepSortValue, sort: NonNullable<KeepListQuery["sort"]>) => void;
+};
+/** Emits a normalized sort descriptor that can be passed directly to useKeepList. */
+declare function KeepSortSelect({ value: controlledValue, defaultValue, onValueChange, "aria-label": ariaLabel, children, ...props }: KeepSortSelectProps): react.JSX.Element;
+type KeepPaginationState = {
+    page: number;
+    pageCount: number;
+    goToPage: (page: number) => void;
+};
+type KeepPaginationProps = Omit<React.HTMLAttributes<HTMLElement>, "children"> & {
+    totalCount: number;
+    pageSize: number;
+    page?: number;
+    maxPageButtons?: number;
+    onPageChange?: (page: number, offset: number) => void;
+    render?: (state: KeepPaginationState) => ReactNode;
+};
+/** 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 KeepUiLabelKey = "save" | "saved" | "remove" | "loading" | "saving" | "syncing" | "error" | "allTags" | "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" | "noteSavedMessage";
 type KeepUiLabels = Partial<Record<KeepUiLabelKey, string>>;
 type KeepUiLabelContext = {
     locale?: string;
@@ -23,12 +65,13 @@ type KeepUiProviderProps = {
 };
 /** Provides one locale-aware label source to every UI primitive. */
 declare function KeepUiProvider({ labels, locale, labelResolver, children }: KeepUiProviderProps): react.JSX.Element;
+declare function useKeepUiLabels(): KeepUiLabelContext;
+
 type KeepKitProviderProps<TMeta = Record<string, unknown>> = Omit<KeepProviderProps<TMeta>, "children"> & Omit<KeepUiProviderProps, "children"> & {
     children?: ReactNode;
 };
 /** Combines the core store and UI labels into the default application provider. */
 declare function KeepKitProvider<TMeta = Record<string, unknown>>({ labels, locale, labelResolver, children, ...providerProps }: KeepKitProviderProps<TMeta>): react.JSX.Element;
-declare function useKeepUiLabels(): KeepUiLabelContext;
 
 type CreateKeepKitOptions<TMeta = Record<string, unknown>> = CreateKeepKitOptions$1<TMeta> & Omit<KeepUiProviderProps, "children"> & {
     getTitle?: (item: KeepItem<TMeta>) => ReactNode;
@@ -158,34 +201,6 @@ 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, onSaved, onSaveError, render, children, asChild, className, ...formProps }: KeepNoteEditorProps<TMeta>): react.JSX.Element;
-type KeepSearchInputProps = Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "defaultValue" | "onChange"> & {
-    value?: string;
-    defaultValue?: string;
-    onValueChange?: (value: string) => void;
-};
-/** A controlled/uncontrolled search field for wiring into KeepListQuery.search. */
-declare function KeepSearchInput({ value: controlledValue, defaultValue, onValueChange, "aria-label": ariaLabel, placeholder, ...props }: KeepSearchInputProps): react.JSX.Element;
-type KeepSortValue = "savedAt:desc" | "savedAt:asc" | "updatedAt:desc" | "updatedAt:asc";
-type KeepSortSelectProps = Omit<SelectHTMLAttributes<HTMLSelectElement>, "value" | "defaultValue" | "onChange"> & {
-    value?: KeepSortValue;
-    defaultValue?: KeepSortValue;
-    onValueChange?: (value: KeepSortValue, sort: NonNullable<KeepListQuery["sort"]>) => void;
-};
-/** Emits a normalized sort descriptor that can be passed directly to useKeepList. */
-declare function KeepSortSelect({ value: controlledValue, defaultValue, onValueChange, "aria-label": ariaLabel, children, ...props }: KeepSortSelectProps): react.JSX.Element;
-type KeepPaginationProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
-    totalCount: number;
-    pageSize: number;
-    page?: number;
-    onPageChange?: (page: number, offset: number) => void;
-    render?: RenderProp<{
-        page: number;
-        pageCount: number;
-        goToPage: (page: number) => void;
-    }>;
-};
-/** A small accessible pagination control using one-based pages and zero-based offsets. */
-declare function KeepPagination({ totalCount, pageSize, page, onPageChange, render, ...props }: KeepPaginationProps): react.JSX.Element;
 type KeepTagEditorProps<TMeta = Record<string, unknown>> = Omit<FormHTMLAttributes<HTMLFormElement>, "children" | "onSubmit"> & {
     item: KeepItem<TMeta>;
     availableTags?: string[];
@@ -200,6 +215,19 @@ type KeepTagEditorProps<TMeta = Record<string, unknown>> = Omit<FormHTMLAttribut
 };
 /** Edits one item's normalized tag set and exposes a render-prop escape hatch. */
 declare function KeepTagEditor<TMeta = Record<string, unknown>>({ item, availableTags, onSaved, onSaveError, render, ...props }: KeepTagEditorProps<TMeta>): react.JSX.Element;
+type KeepBulkActionsState<TMeta = Record<string, unknown>> = {
+    items: KeepItem<TMeta>[];
+    selectedIds: string[];
+    selectedCount: number;
+    allSelected: boolean;
+    tagsInput: string;
+    setTagsInput: (value: string) => void;
+    toggle: (id: string) => void;
+    toggleAll: () => void;
+    remove: () => Promise<void>;
+    updateTags: () => Promise<void>;
+    isMutating: boolean;
+};
 type KeepBulkActionsProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLElement>, "children"> & {
     query?: KeepListQuery<TMeta>;
     selectedIds?: string[];
@@ -207,9 +235,11 @@ type KeepBulkActionsProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes
     onSelectedIdsChange?: (ids: string[]) => void;
     renderItem?: (item: KeepItem<TMeta>, selected: boolean) => ReactNode;
     onCompleted?: (action: "remove" | "tags", ids: string[]) => void;
+    render?: RenderProp<KeepBulkActionsState<TMeta>>;
+    children?: ReactNode | RenderProp<KeepBulkActionsState<TMeta>>;
 };
 /** Selects visible items and performs one storage operation for the whole selection. */
-declare function KeepBulkActions<TMeta = Record<string, unknown>>({ query, selectedIds: controlledSelectedIds, defaultSelectedIds, onSelectedIdsChange, renderItem, onCompleted, ...props }: KeepBulkActionsProps<TMeta>): react.JSX.Element;
+declare function KeepBulkActions<TMeta = Record<string, unknown>>({ query, selectedIds: controlledSelectedIds, defaultSelectedIds, onSelectedIdsChange, renderItem, onCompleted, render, children, ...props }: KeepBulkActionsProps<TMeta>): react.JSX.Element;
 type KeepEmptyStateProps = Omit<HTMLAttributes<HTMLElement>, "children" | "title"> & {
     title?: ReactNode;
     description?: ReactNode;
@@ -242,4 +272,4 @@ type KeepAnnouncementsProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
 /** Announces successful save, remove, and note operations in a polite live region. */
 declare function KeepAnnouncements<TMeta = Record<string, unknown>>({ messages, ...props }: KeepAnnouncementsProps): react.JSX.Element;
 
-export { type CreateKeepKitOptions, KeepAnnouncements, type KeepAnnouncementsProps, KeepBulkActions, type KeepBulkActionsProps, KeepButton, type KeepButtonLabels, type KeepButtonProps, KeepCollection, type KeepCollectionFeature, type KeepCollectionProps, KeepEmptyState, type KeepEmptyStateProps, type KeepImageProps, KeepItemCard, type KeepItemCardProps, type KeepItemCardState, type KeepKit, KeepKitProvider, type KeepKitProviderProps, KeepList, type KeepListProps, type KeepListState, KeepNoteEditor, type KeepNoteEditorProps, type KeepNoteEditorState, KeepPagination, type KeepPaginationProps, KeepSearchInput, type KeepSearchInputProps, KeepSortSelect, type KeepSortSelectProps, type KeepSortValue, KeepStatus, type KeepStatusLabels, type KeepStatusProps, type KeepStatusState, type KeepStatusValue, KeepTagEditor, type KeepTagEditorProps, KeepTagFilter, type KeepTagFilterProps, type KeepTagFilterState, type KeepUiLabelContext, type KeepUiLabelKey, type KeepUiLabels, KeepUiProvider, type KeepUiProviderProps, type RenderProp, createKeepKit, useKeepUiLabels };
+export { type CreateKeepKitOptions, KeepAnnouncements, type KeepAnnouncementsProps, KeepBulkActions, type KeepBulkActionsProps, type KeepBulkActionsState, KeepButton, type KeepButtonLabels, type KeepButtonProps, KeepCollection, type KeepCollectionFeature, type KeepCollectionProps, KeepEmptyState, type KeepEmptyStateProps, type KeepImageProps, KeepItemCard, type KeepItemCardProps, type KeepItemCardState, KeepItemCheckbox, type KeepItemCheckboxProps, type KeepKit, KeepKitProvider, type KeepKitProviderProps, KeepList, type KeepListProps, type KeepListState, KeepNoteEditor, type KeepNoteEditorProps, type KeepNoteEditorState, KeepPagination, type KeepPaginationProps, type KeepPaginationState, KeepSearchInput, type KeepSearchInputProps, KeepSortSelect, type KeepSortSelectProps, type KeepSortValue, KeepStatus, type KeepStatusLabels, type KeepStatusProps, type KeepStatusState, type KeepStatusValue, KeepTagEditor, type KeepTagEditorProps, KeepTagFilter, type KeepTagFilterProps, type KeepTagFilterState, type KeepUiLabelContext, type KeepUiLabelKey, type KeepUiLabels, KeepUiProvider, type KeepUiProviderProps, type RenderProp, createKeepKit, useKeepUiLabels };