@keepkit/ui 0.8.0 → 0.10.0

package/README.md

@@ -10,6 +10,28 @@ Reactアプリケーション向けの標準利用パッケージです。`@keep
 pnpm add @keepkit/ui
 ```
 
+## Minimal Starter Recipe
+
+```tsx
+import { createBrowserStorageAdapter, createKeepKit } from "@keepkit/ui";
+
+type Meta = { title: string; url: string };
+const keep = createKeepKit<Meta>({
+  storage: createBrowserStorageAdapter({ key: "demo:keeps" }),
+});
+
+export function SavedArticle({ article }: { article: Meta & { id: string } }) {
+  return (
+    <keep.Provider fallback={<p>Saved items are temporarily unavailable.</p>}>
+      <keep.Button item={{ id: article.id, targetType: "article", meta: article }} />
+      <keep.Collection query={{ targetType: "article" }} />
+    </keep.Provider>
+  );
+}
+```
+
+Every primitive exposes `data-state`; pending operations expose `data-loading="true"`, and disabled controls expose `data-disabled="true"`. Use these attributes from host CSS or Tailwind data variants. `KeepCollection` and `KeepList` accept `fallback`, `onBoundaryError`, and `boundaryResetKey` for local render-error isolation.
+
 ```tsx
 import { createBrowserStorageAdapter, createKeepKit } from "@keepkit/ui";
 
@@ -33,6 +55,7 @@ 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インポート、結果件数、容量エラー表示を提供します。
 
 一覧のqueryは次の形式に統一されています。
 
@@ -82,6 +105,7 @@ function SavedArticles() {
 ```
 
 `keep.Collection` includes search, sorting, pagination, loading/empty/error states, and polite live announcements. Search is debounced by 300ms by default. Enable `features={{ tagFilter: true, bulkActions: true }}` for tag filtering and bulk operations. Use the individual `KeepList`, `KeepSearchInput`, `KeepSortSelect`, `KeepPagination`, `KeepItemCheckbox`, and `KeepTagEditor` primitives when you need a custom layout. `KeepBulkActions` supports render props and exposes `isAllSelected` / `toggleSelectAll` for visible-item selection. `KeepNoteEditor` auto-saves dirty notes after 300ms by default; set `debounceMs={0}` to use form submission only. Mount `KeepAnnouncer` (`KeepAnnouncements` alias) when you need the live region explicitly.
+`KeepItemCard` accepts `href`, `onOpen`, `linkTarget`, and `linkComponent` for detail-page navigation. Links are disabled for unavailable `status` values such as private or expired. `KeepBackup` provides JSON export, merge/replace import, result counts, and quota-error messaging.
 
 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,11 +1,19 @@
 import * as react from 'react';
-import { ReactNode, HTMLAttributes, ImgHTMLAttributes, ComponentType, InputHTMLAttributes, FormHTMLAttributes, SelectHTMLAttributes } from 'react';
-import { KeepListQuery, KeepItem, KeepItemInput } from '@keepkit/core/core';
+import { HTMLAttributes, ReactNode, ImgHTMLAttributes, ComponentType, MouseEvent, HTMLAttributeAnchorTarget, InputHTMLAttributes, FormHTMLAttributes, SelectHTMLAttributes } from 'react';
+import { ImportItemsResult, KeepListQuery, KeepItem, KeepItemInput } from '@keepkit/core/core';
 export { KeepItem, KeepItemInput, KeepListQuery, KeepSyncStatus } from '@keepkit/core/core';
-import { KeepButtonProps as KeepButtonProps$1, UseKeepListResult, CreateKeepKitOptions as CreateKeepKitOptions$1, KeepProviderProps, useKeepContext, useKeepItem, useKeepList, KeepShortcutOptions } from '@keepkit/core/react';
-export { KeepButtonState, KeepContextValue, KeepProvider, KeepProviderProps, KeepShortcutOptions, useKeepContext, useKeepItem, useKeepList, useKeepShortcut } from '@keepkit/core/react';
+import { KeepButtonProps as KeepButtonProps$1, UseKeepListResult, KeepErrorBoundaryProps, CreateKeepKitOptions as CreateKeepKitOptions$1, KeepProviderProps, useKeepContext, useKeepItem, useKeepList, KeepShortcutOptions } from '@keepkit/core/react';
+export { KeepButtonState, KeepContextValue, KeepErrorBoundary, KeepErrorBoundaryProps, KeepProvider, KeepProviderProps, KeepShortcutOptions, useKeepContext, useKeepItem, useKeepList, useKeepShortcut } from '@keepkit/core/react';
 export { FallbackStorageAdapter, IndexedDBAdapter, IndexedDBSyncQueueAdapter, LocalStorageAdapter, LocalStorageSyncQueueAdapter, SyncStorageAdapter, createBrowserStorageAdapter, createStorageAdapter } from '@keepkit/core/storage';
 
+type KeepBackupProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLElement>, "children"> & {
+    filename?: string;
+    onExport?: (data: string) => void;
+    onImported?: (result: ImportItemsResult<TMeta>) => void;
+};
+/** Accessible JSON backup controls backed by the current KeepProvider storage. */
+declare function KeepBackup<TMeta = Record<string, unknown>>({ filename, onExport, onImported, ...props }: KeepBackupProps<TMeta>): react.JSX.Element;
+
 type RenderProp<TState> = (state: TState) => ReactNode;
 type KeepButtonLabels = {
     saved?: ReactNode;
@@ -60,6 +68,14 @@ type KeepItemCardState<TMeta = Record<string, unknown>> = {
     isMutating: boolean;
     error: unknown | null;
     remove: () => Promise<void>;
+    status: KeepItem["status"];
+};
+type KeepItemCardLinkProps = {
+    href: string;
+    children?: ReactNode;
+    target?: HTMLAttributeAnchorTarget;
+    rel?: string;
+    onClick?: (event: MouseEvent<HTMLElement>) => void;
 };
 type KeepImageProps = ImgHTMLAttributes<HTMLImageElement> & {
     src: string;
@@ -81,9 +97,15 @@ type KeepItemCardProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HT
     showSaveButton?: boolean;
     saveButtonLabels?: KeepButtonLabels;
     asChild?: boolean;
+    href?: string | ((item: KeepItem<TMeta>) => string | undefined);
+    onOpen?: (item: KeepItem<TMeta>, event: MouseEvent<HTMLElement>) => void;
+    linkTarget?: "title" | "card";
+    linkComponent?: ComponentType<KeepItemCardLinkProps>;
+    linkTargetAttribute?: HTMLAttributeAnchorTarget;
+    linkRel?: string;
 };
 /** A low-dependency item presentation primitive. The default markup can be replaced with render props. */
-declare function KeepItemCard<TMeta = Record<string, unknown>>({ item, title, getTitle, getImageProps, imageComponent: ImageComponent, renderImage, imageAlt, render, children, removeLabel, onRemoveError, onRemoved, showSaveButton, saveButtonLabels, asChild, className, ...rootProps }: KeepItemCardProps<TMeta>): react.ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+declare function KeepItemCard<TMeta = Record<string, unknown>>({ item, title, getTitle, getImageProps, imageComponent: ImageComponent, renderImage, imageAlt, render, children, removeLabel, onRemoveError, onRemoved, showSaveButton, saveButtonLabels, asChild, href: hrefOption, onOpen, linkTarget, linkComponent: LinkComponent, linkTargetAttribute, linkRel, className, ...rootProps }: KeepItemCardProps<TMeta>): react.ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
 type KeepListState<TMeta = Record<string, unknown>> = UseKeepListResult<TMeta>;
 type KeepListProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLElement>, "children"> & {
@@ -95,9 +117,12 @@ type KeepListProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLEl
     error?: ReactNode | RenderProp<KeepListState<TMeta>>;
     itemCardProps?: Omit<KeepItemCardProps<TMeta>, "item" | "children" | "render">;
     asChild?: boolean;
+    fallback?: KeepErrorBoundaryProps["fallback"];
+    onBoundaryError?: KeepErrorBoundaryProps["onError"];
+    boundaryResetKey?: unknown;
 };
 /** A list primitive with built-in loading, empty, error, and removal states. */
-declare function KeepList<TMeta = Record<string, unknown>>({ query, children, renderItem, loading, empty, error: errorContent, itemCardProps, asChild, className, ...rootProps }: KeepListProps<TMeta>): react.ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+declare function KeepList<TMeta = Record<string, unknown>>(props: KeepListProps<TMeta>): react.JSX.Element;
 
 type KeepCollectionFeature = "search" | "sort" | "pagination" | "tagFilter" | "bulkActions";
 type KeepCollectionProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<HTMLElement>, "children"> & {
@@ -109,9 +134,12 @@ type KeepCollectionProps<TMeta = Record<string, unknown>> = Omit<HTMLAttributes<
     loading?: ReactNode | RenderProp<KeepListState<TMeta>>;
     empty?: ReactNode | RenderProp<KeepListState<TMeta>>;
     error?: ReactNode | RenderProp<KeepListState<TMeta>>;
+    fallback?: KeepErrorBoundaryProps["fallback"];
+    onBoundaryError?: KeepErrorBoundaryProps["onError"];
+    boundaryResetKey?: unknown;
 };
 /** 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;
+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>;
@@ -252,7 +280,7 @@ declare function KeepAnnouncements<TMeta = Record<string, unknown>>({ messages,
 /** Singular alias for applications that mount one announcer explicitly. */
 declare const KeepAnnouncer: typeof KeepAnnouncements;
 
-type KeepUiLabelKey = "save" | "saved" | "remove" | "loading" | "saving" | "syncing" | "error" | "allTags" | "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 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" | "exportData" | "importData" | "importMode" | "merge" | "replace" | "importedCount" | "failedCount" | "storageQuotaError" | "statusExpired" | "statusRemoved" | "statusDeleted" | "statusPrivate" | "statusUnknown";
 type KeepUiLabels = Partial<Record<KeepUiLabelKey, string>>;
 type KeepUiLabelContext = {
     locale?: string;
@@ -284,6 +312,7 @@ type CreateKeepKitOptions<TMeta = Record<string, unknown>> = CreateKeepKitOption
 type KeepKit<TMeta = Record<string, unknown>> = {
     Provider: ComponentType<KeepKitProviderProps<TMeta>>;
     Button: ComponentType<KeepButtonProps<TMeta>>;
+    Backup: ComponentType<KeepBackupProps<TMeta>>;
     Collection: ComponentType<KeepCollectionProps<TMeta>>;
     useContext: () => ReturnType<typeof useKeepContext<TMeta>>;
     useItem: (item?: KeepItemInput<TMeta>) => ReturnType<typeof useKeepItem<TMeta>>;
@@ -293,4 +322,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, 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, type KeepTagEditorState, KeepTagFilter, type KeepTagFilterProps, type KeepTagFilterState, type KeepUiLabelContext, type KeepUiLabelKey, type KeepUiLabels, KeepUiProvider, type KeepUiProviderProps, type RenderProp, createKeepKit, isAllSelected, toggleSelectAll, useKeepUiLabels };
+export { type CreateKeepKitOptions, KeepAnnouncements, type KeepAnnouncementsProps, KeepAnnouncer, KeepBackup, type KeepBackupProps, KeepBulkActions, type KeepBulkActionsProps, type KeepBulkActionsState, KeepButton, type KeepButtonLabels, type KeepButtonProps, KeepCollection, type KeepCollectionFeature, type KeepCollectionProps, KeepEmptyState, type KeepEmptyStateProps, type KeepImageProps, KeepItemCard, type KeepItemCardLinkProps, type KeepItemCardProps, type KeepItemCardState, KeepItemCheckbox, type KeepItemCheckboxProps, type KeepKit, KeepKitProvider, type KeepKitProviderProps, 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, type KeepTagEditorState, KeepTagFilter, type KeepTagFilterProps, type KeepTagFilterState, type KeepUiLabelContext, type KeepUiLabelKey, type KeepUiLabels, KeepUiProvider, type KeepUiProviderProps, type RenderProp, createKeepKit, isAllSelected, toggleSelectAll, useKeepUiLabels };