@keepkit/ui 0.4.0 → 0.6.0

package/README.md

@@ -4,76 +4,85 @@
 
 ## 日本語
 
-`@keepkit/core` の保存状態を、アプリ固有のCSSやUIライブラリに接続するための、低依存・スタイルレスなReact UIパーツです。Tailwind CSS、shadcn/ui、その他のデザインシステムには依存しません。
+Reactアプリケーション向けの標準利用パッケージです。`@keepkit/core`を内包し、Provider、保存ボタン、検索・ソート・ページング付きの一覧を少ないコードで構成できます。
 
 ```bash
-pnpm add @keepkit/core @keepkit/ui
+pnpm add @keepkit/ui
 ```
 
 ```tsx
-import { KeepList, KeepProvider, KeepTagFilter } from "@keepkit/ui";
+import { createBrowserStorageAdapter, createKeepKit } from "@keepkit/ui";
 
-function SavedItems() {
+type ArticleMeta = { title: string; url: string };
+const keep = createKeepKit<ArticleMeta>({
+  storage: createBrowserStorageAdapter({ key: "articles" }),
+  locale: "ja-JP",
+  labels: { save: "保存", remove: "削除" },
+});
+
+function SavedArticles() {
   return (
-    <KeepProvider>
-      <KeepTagFilter value={selectedTag} onValueChange={setSelectedTag} />
-      <KeepList options={{ tag: selectedTag }} />
-    </KeepProvider>
+    <keep.Provider>
+      <keep.Collection
+        query={{ targetType: "article" }}
+        renderItem={(item) => <keep.Button item={{ id: item.id, targetType: item.targetType, meta: item.meta }} />}
+      />
+    </keep.Provider>
   );
 }
 ```
 
-提供するコンポーネントは次のとおりです。
+`keep.Collection`は検索、ソート、ページング、loading / empty / error、ARIA live通知を標準で提供します。検索は既定で300msデバウンスされます。`features={{ tagFilter: true, bulkActions: true }}`でタグフィルターと一括操作も有効にできます。個別の`KeepList`、`KeepSearchInput`、`KeepSortSelect`、`KeepPagination`、`KeepItemCheckbox`、`KeepTagEditor`などは高度なレイアウト用に利用できます。`KeepBulkActions`はrender propsで操作UIを差し替えられます。
 
-- `KeepButton`: 保存済み状態、`aria-pressed`、ローディング・エラー状態、`asChild`、render props。`labels` または既存の `savedAriaLabel` / `unsavedAriaLabel` で翻訳できます。
-- `KeepList`: 保存一覧、読み込み中・空・エラー状態、標準カード、削除操作。`renderItem` で行単位を置き換えられます。
-- `KeepItemCard`: タイトル、画像、保存ボタン、削除ボタン。`getImageProps`、`imageComponent`、`renderImage` とrender propsで表示を差し替えられます。
-- `KeepTagFilter`: タグと件数を表示するキーボード操作可能なフィルター。`value` / `onValueChange` のcontrolled APIに対応します。
-- `KeepNoteEditor`: ノートの編集・保存フォーム。`render` で完全なカスタムUIにできます。
-- `KeepSearchInput` / `KeepSortSelect` / `KeepPagination`: `useKeepList` に渡す検索、ソート、offsetページング用のプリミティブ。
-- `KeepTagEditor` / `KeepBulkActions`: タグ編集、複数選択、一括削除、一括タグ更新。
-- `KeepUiProvider`: `labels`、`locale`、`labelResolver` をUI全体に適用するラベルコンテキスト。
-- `KeepAnnouncements`: 保存、削除、ノート保存の成功を `aria-live` で通知します。
-- `KeepEmptyState` / `KeepStatus`: 空、読み込み中、保存中、同期中、エラー状態の表示。
+一覧のqueryは次の形式に統一されています。
 
-すべてのルート要素で `className` を利用でき、対応コンポーネントでは `asChild` で既存要素をルートとして利用できます。コンポーネントの標準HTMLは意味的な要素、ネイティブボタン、フォーム、`aria-live` を利用します。
+```tsx
+const query = {
+  targetType: "article",
+  tags: ["read"],
+  search: { query: "react", mode: "and" as const },
+  sort: { by: "updatedAt" as const, direction: "desc" as const },
+  pagination: { page: 1, pageSize: 20 },
+};
+```
 
-### カスタマイズ契約
+保存操作にはID付きの最小入力を渡します。保存・更新時刻はKeepKitが管理します。
 
-- `render` / render props はstateを受け取り、標準内部マークアップを置き換えます。`KeepList.renderItem` は各アイテムだけを置き換えます。
-- `KeepItemCard` の画像は `getImageProps` で `src`、`alt`、`width`、`height`、`srcSet` を作り、`imageComponent` または `renderImage` で描画します。
-- `asChild` は単一のReact要素を必要とし、ルート要素だけを置き換えます。内部のアクセシビリティ属性とイベントは保持してください。
-- 標準構造は `KeepList` が `div > ul > li`、`KeepTagFilter` が `fieldset`、`KeepNoteEditor` が `form`、一括操作が `section > fieldset` です。
-- CSSはルートと渡された標準要素の `className` に適用します。コンポーネントはstyleを持ちません。
-- `onClick`、`onSubmit`、`onChange` は利用者のハンドラーを先に実行し、`preventDefault()` された場合は既定操作を実行しません。
+```tsx
+const article = { id: "article-123", targetType: "article", meta: { title, url } };
+const item = keep.useItem(article);
+```
 
-ラベルと画像の拡張ポイントは `KeepUiProvider` と `getImageProps`/`imageComponent`/`renderImage` に集約しています。既存の個別label propsも明示的な上書き用途として利用できます。
+高度なフレームワーク中立APIは`@keepkit/core/core`、低レベルのReact APIは`@keepkit/core/react`、ストレージ実装は`@keepkit/core/storage`から利用できます。
 
 ## English
 
-`@keepkit/ui` provides low-dependency, style-free React UI primitives that connect `@keepkit/core` state to an app's own CSS or design system. It has no direct dependency on Tailwind CSS, shadcn/ui, or another component library.
+The standard React package for KeepKit. It includes `@keepkit/core` and provides a single typed provider, save button, and searchable/sortable/paginated collection workflow.
 
 ```bash
-pnpm add @keepkit/core @keepkit/ui
+pnpm add @keepkit/ui
 ```
 
 ```tsx
-import { KeepList, KeepProvider, KeepTagFilter } from "@keepkit/ui";
+import { createBrowserStorageAdapter, createKeepKit } from "@keepkit/ui";
+
+type ArticleMeta = { title: string; url: string };
+const keep = createKeepKit<ArticleMeta>({
+  storage: createBrowserStorageAdapter({ key: "articles" }),
+  labels: { save: "Save", remove: "Remove" },
+});
 
-function SavedItems() {
+function SavedArticles() {
   return (
-    <KeepProvider>
-      <KeepTagFilter value={selectedTag} onValueChange={setSelectedTag} />
-      <KeepList options={{ tag: selectedTag }} />
-    </KeepProvider>
+    <keep.Provider>
+      <keep.Collection query={{ targetType: "article" }} />
+    </keep.Provider>
   );
 }
 ```
 
-Components include `KeepButton`, `KeepList`, `KeepItemCard`, `KeepTagFilter`, `KeepNoteEditor`, `KeepEmptyState`, and `KeepStatus`. They support `className`, render props, localized labels, and `asChild` where a root element can be replaced. The defaults use semantic HTML, native keyboard behavior, `aria-pressed`, and live-region status announcements. `KeepList` includes loading, empty, error, and removal states, while `KeepTagFilter` exposes controlled `value` / `onValueChange` state.
-
-The package also exports `KeepSearchInput`, `KeepSortSelect`, `KeepPagination`, `KeepTagEditor`, `KeepBulkActions`, `KeepUiProvider`, and `KeepAnnouncements`. Configure labels once with `KeepUiProvider`, replace card images with `getImageProps` plus `imageComponent` or `renderImage`, and use `KeepAnnouncements` for success messages in a polite live region.
+`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.
 
-Customization is explicit: render props replace component markup, `KeepList.renderItem` replaces one item, `asChild` replaces only a single root element, and standard HTML structure is stable (`div > ul > li`, `fieldset`, `form`, and `section > fieldset`). User handlers run before default behavior and `preventDefault()` cancels it. The old URL-only image entry point is replaced by the structured image API; app-wide labels belong in `KeepUiProvider`.
+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.
 
-The package re-exports `KeepProvider` and the core React hooks for convenient composition. The state and storage implementation remains in `@keepkit/core`; this package only adds the UI layer. Existing component label props remain available as explicit overrides, while app-wide defaults belong in `KeepUiProvider`.
+Framework-neutral APIs remain available from `@keepkit/core/core`, low-level React bindings from `@keepkit/core/react`, and storage adapters from `@keepkit/core/storage`.

package/dist/index.d.ts

@@ -1,11 +1,54 @@
 import * as react from 'react';
-import { HTMLAttributes, ReactNode, ReactElement, ImgHTMLAttributes, ComponentType, FormHTMLAttributes, InputHTMLAttributes, SelectHTMLAttributes } from 'react';
-import { KeepListOptions, KeepItem } from '@keepkit/core/core';
-export { KeepItem, KeepItemInput, KeepListOptions, KeepSyncStatus } from '@keepkit/core/core';
-import { KeepButtonProps as KeepButtonProps$1, UseKeepListResult } from '@keepkit/core/react';
-export { KeepContextValue, KeepProvider, KeepProviderProps, useKeepContext, useKeepItem, useKeepList } from '@keepkit/core/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;
@@ -24,6 +67,27 @@ type KeepUiProviderProps = {
 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;
+
+type CreateKeepKitOptions<TMeta = Record<string, unknown>> = CreateKeepKitOptions$1<TMeta> & Omit<KeepUiProviderProps, "children"> & {
+    getTitle?: (item: KeepItem<TMeta>) => ReactNode;
+    getImageProps?: (item: KeepItem<TMeta>, title: ReactNode) => KeepImageProps | undefined;
+};
+type KeepKit<TMeta = Record<string, unknown>> = {
+    Provider: ComponentType<KeepKitProviderProps<TMeta>>;
+    Button: ComponentType<KeepButtonProps<TMeta>>;
+    Collection: ComponentType<KeepCollectionProps<TMeta>>;
+    useContext: () => ReturnType<typeof useKeepContext<TMeta>>;
+    useItem: (item?: KeepItemInput<TMeta>) => ReturnType<typeof useKeepItem<TMeta>>;
+    useList: (query?: KeepListQuery<TMeta>) => UseKeepListResult<TMeta>;
+    useShortcut: (options: KeepShortcutOptions<TMeta>) => void;
+};
+/** Create one typed application API for the core and the standard UI layer. */
+declare function createKeepKit<TMeta = Record<string, unknown>>(options?: CreateKeepKitOptions<TMeta>): KeepKit<TMeta>;
 type RenderProp<TState> = (state: TState) => ReactNode;
 type KeepButtonLabels = {
     saved?: ReactNode;
@@ -52,6 +116,7 @@ type KeepImageProps = ImgHTMLAttributes<HTMLImageElement> & {
 type KeepItemCardProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLElement>, "children" | "title"> & {
     item: KeepItem<TMeta>;
     title?: ReactNode | ((item: KeepItem<TMeta>) => ReactNode);
+    getTitle?: (item: KeepItem<TMeta>) => ReactNode;
     getImageProps?: (item: KeepItem<TMeta>, title: ReactNode) => KeepImageProps | undefined;
     imageComponent?: ComponentType<KeepImageProps>;
     renderImage?: (props: KeepImageProps, item: KeepItem<TMeta>) => ReactNode;
@@ -66,10 +131,10 @@ type KeepItemCardProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HT
     asChild?: boolean;
 };
 /** A low-dependency item presentation primitive. The default markup can be replaced with render props. */
-declare function KeepItemCard<TMeta = Record<string, unknown>>({ item, title, getImageProps, imageComponent: ImageComponent, renderImage, imageAlt, render, children, removeLabel, onRemoveError, onRemoved, showSaveButton, saveButtonLabels, asChild, className, ...rootProps }: KeepItemCardProps<TMeta>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+declare function KeepItemCard<TMeta = Record<string, unknown>>({ item, title, getTitle, getImageProps, imageComponent: ImageComponent, renderImage, imageAlt, render, children, removeLabel, onRemoveError, onRemoved, showSaveButton, saveButtonLabels, asChild, className, ...rootProps }: KeepItemCardProps<TMeta>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 type KeepListState<TMeta = Record<string, unknown>> = UseKeepListResult<TMeta>;
 type KeepListProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLElement>, "children"> & {
-    options?: KeepListOptions<TMeta>;
+    query?: KeepListQuery<TMeta>;
     children?: ReactNode | RenderProp<KeepListState<TMeta>>;
     renderItem?: (item: KeepItem<TMeta>, state: KeepListState<TMeta>) => ReactNode;
     loading?: ReactNode | RenderProp<KeepListState<TMeta>>;
@@ -79,7 +144,20 @@ type KeepListProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLEl
     asChild?: boolean;
 };
 /** A list primitive with built-in loading, empty, error, and removal states. */
-declare function KeepList<TMeta = Record<string, unknown>>({ options, children, renderItem, loading, empty, error: errorContent, itemCardProps, asChild, className, ...rootProps }: KeepListProps<TMeta>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+declare function KeepList<TMeta = Record<string, unknown>>({ query, children, renderItem, loading, empty, error: errorContent, itemCardProps, asChild, className, ...rootProps }: KeepListProps<TMeta>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+type KeepCollectionFeature = "search" | "sort" | "pagination" | "tagFilter" | "bulkActions";
+type KeepCollectionProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLElement>, "children"> & {
+    query?: KeepListQuery<TMeta>;
+    pageSize?: number;
+    features?: Partial<Record<KeepCollectionFeature, boolean>>;
+    renderItem?: (item: KeepItem<TMeta>, state: KeepListState<TMeta>) => ReactNode;
+    itemCardProps?: Omit<KeepItemCardProps<TMeta>, "item" | "children" | "render">;
+    loading?: ReactNode | RenderProp<KeepListState<TMeta>>;
+    empty?: ReactNode | RenderProp<KeepListState<TMeta>>;
+    error?: ReactNode | RenderProp<KeepListState<TMeta>>;
+};
+/** A batteries-included collection with query controls and accessible status feedback. */
+declare function KeepCollection<TMeta = Record<string, unknown>>({ query, pageSize, features, renderItem, itemCardProps, loading, empty, error, className, ...rootProps }: KeepCollectionProps<TMeta>): react.JSX.Element;
 type KeepTagFilterState = {
     tags: string[];
     tagCounts: Record<string, number>;
@@ -87,7 +165,7 @@ type KeepTagFilterState = {
     select: (tag?: string) => void;
 };
 type KeepTagFilterProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLElement>, "children" | "onChange"> & {
-    listOptions?: KeepListOptions<TMeta>;
+    query?: KeepListQuery<TMeta>;
     value?: string;
     defaultValue?: string;
     onChange?: (tag?: string) => void;
@@ -99,8 +177,8 @@ type KeepTagFilterProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<H
     children?: ReactNode | RenderProp<KeepTagFilterState>;
     asChild?: boolean;
 };
-/** An ARIA button group for tag filtering; consumers can connect value to KeepList options. */
-declare function KeepTagFilter<TMeta = Record<string, unknown>>({ listOptions, value: controlledValue, defaultValue, onChange, onValueChange, allLabel, ariaLabel, renderTag, render, children, asChild, className, ...rootProps }: KeepTagFilterProps<TMeta>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+/** 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>): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 type KeepNoteEditorState<TMeta = Record<string, unknown>> = {
     item: KeepItem<TMeta>;
     note: string;
@@ -123,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 useKeepList.searchQuery. */
-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<KeepListOptions["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[];
@@ -165,16 +215,31 @@ 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"> & {
-    listOptions?: KeepListOptions<TMeta>;
+    query?: KeepListQuery<TMeta>;
     selectedIds?: string[];
     defaultSelectedIds?: string[];
     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>>({ listOptions, 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;
@@ -207,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 { KeepAnnouncements, type KeepAnnouncementsProps, KeepBulkActions, type KeepBulkActionsProps, KeepButton, type KeepButtonLabels, type KeepButtonProps, KeepEmptyState, type KeepEmptyStateProps, type KeepImageProps, KeepItemCard, type KeepItemCardProps, type KeepItemCardState, 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, 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 };