@keepkit/core 0.8.0 → 0.10.0

package/dist/react.d.ts

@@ -1,8 +1,9 @@
 import * as react from 'react';
-import { ReactNode, ButtonHTMLAttributes, MouseEvent, HTMLAttributes, ReactElement, PropsWithChildren, ComponentType } from 'react';
-import { K as KeepItemMetadataRefresher, d as KeepItemRevalidator, R as RevalidateKeepItemsOptions, c as KeepItemRevalidationSummary, f as KeepListQuery, g as KeepStore, h as KeepStoreActions } from './store-CqNh-2DS.js';
-export { b as KeepItemRevalidationResult, e as KeepItemStatus, k as isKeepItemMetadataStale } from './store-CqNh-2DS.js';
-import { m as KeepItemInput, a as KeepItem, l as KeepEventHandlers, S as StorageAdapter, d as KeepPlugin, K as KeepSchema, b as KeepInvalidItemPolicy, f as KeepChangeContext, t as KeepSyncState } from './types-BCziYE6E.js';
+import { ReactNode, ButtonHTMLAttributes, MouseEvent, HTMLAttributes, ReactElement, ErrorInfo, Component, PropsWithChildren, ComponentType } from 'react';
+import { f as KeepItemMetadataRefresher, k as KeepItemRevalidator, R as RevalidateKeepItemsOptions, j as KeepItemRevalidationSummary, l as KeepListQuery, g as KeepItemResolver, I as ImportItemsOptions, a as ImportItemsResult, m as KeepStore, n as KeepStoreActions } from './store-Cgqx7_xd.js';
+export { i as KeepItemRevalidationResult, s as isKeepItemMetadataStale } from './store-Cgqx7_xd.js';
+import { m as KeepItemInput, a as KeepItem, k as KeepEventHandlers, S as StorageAdapter, c as KeepPlugin, K as KeepSchema, l as KeepInvalidItemPolicy, e as KeepChangeContext, u as KeepSyncState } from './types--YahIoEB.js';
+export { n as KeepItemStatus } from './types--YahIoEB.js';
 
 type UseKeepItemResult<TMeta = Record<string, unknown>> = {
     item: KeepItem<TMeta> | undefined;
@@ -40,7 +41,7 @@ type UseKeepListResult<TMeta = Record<string, unknown>> = {
     removeTagsBatch: (ids: string[], tags: string[]) => Promise<void>;
     clear: () => Promise<void>;
     refresh: () => Promise<void>;
-    revalidate: (revalidator: KeepItemRevalidator<TMeta>, options?: RevalidateKeepItemsOptions) => Promise<KeepItemRevalidationSummary<TMeta>>;
+    revalidate: (revalidator: KeepItemRevalidator<TMeta>, options?: RevalidateKeepItemsOptions<TMeta>) => Promise<KeepItemRevalidationSummary<TMeta>>;
 };
 declare function useKeepList<TMeta = Record<string, unknown>>(query?: KeepListQuery<TMeta>): UseKeepListResult<TMeta>;
 
@@ -94,6 +95,25 @@ type KeepButtonState<TMeta = Record<string, unknown>> = {
 /** A style-free accessible save toggle. Consumers provide all visual styling. */
 declare function KeepButton<TMeta = Record<string, unknown>>({ item, children, savedLabel, unsavedLabel, savedAriaLabel, unsavedAriaLabel, getAriaLabel, asChild, onToggleError, onClick, disabled, ...buttonProps }: KeepButtonProps<TMeta>): react.JSX.Element;
 
+type KeepErrorBoundaryProps = {
+    children?: ReactNode;
+    fallback?: ReactNode | ((error: unknown) => ReactNode);
+    onError?: (error: unknown, info: ErrorInfo) => void;
+    /** Change this value to retry rendering after an error has been handled. */
+    resetKey?: unknown;
+};
+type KeepErrorBoundaryState = {
+    error: unknown | null;
+};
+/** Prevents an unexpected render error from taking down the host application. */
+declare class KeepErrorBoundary extends Component<KeepErrorBoundaryProps, KeepErrorBoundaryState> {
+    state: KeepErrorBoundaryState;
+    static getDerivedStateFromError(error: unknown): KeepErrorBoundaryState;
+    componentDidCatch(error: unknown, info: ErrorInfo): void;
+    componentDidUpdate(previousProps: KeepErrorBoundaryProps): void;
+    render(): ReactNode;
+}
+
 type KeepContextValue<TMeta = Record<string, unknown>> = {
     items: KeepItem<TMeta>[];
     isLoading: boolean;
@@ -114,7 +134,9 @@ type KeepContextValue<TMeta = Record<string, unknown>> = {
     refresh: () => Promise<void>;
     flushSync: () => Promise<void>;
     refreshItemMetadata: (id: string, refresh: KeepItemMetadataRefresher<TMeta>) => Promise<void>;
-    revalidateItems: (revalidator: KeepItemRevalidator<TMeta>, options?: RevalidateKeepItemsOptions) => Promise<KeepItemRevalidationSummary<TMeta>>;
+    revalidateItems: (revalidator?: KeepItemRevalidator<TMeta>, options?: RevalidateKeepItemsOptions<TMeta>) => Promise<KeepItemRevalidationSummary<TMeta>>;
+    exportBackup: () => Promise<string>;
+    importBackup: (data: string, options?: Pick<ImportItemsOptions<TMeta>, "mode" | "invalidItemPolicy" | "onInvalidItem">) => Promise<ImportItemsResult<TMeta>>;
 };
 type KeepProviderProps<TMeta = Record<string, unknown>> = PropsWithChildren<KeepEventHandlers<TMeta> & {
     storage?: StorageAdapter<TMeta>;
@@ -130,12 +152,18 @@ type KeepProviderProps<TMeta = Record<string, unknown>> = PropsWithChildren<Keep
     invalidItemPolicy?: KeepInvalidItemPolicy;
     onInvalidItem?: (error: unknown, item: KeepItem<unknown>) => void;
     migrateMeta?: (meta: unknown, fromVersion: number, toVersion: number, item: KeepItem<TMeta>) => TMeta | Promise<TMeta>;
+    /** Render this content when a descendant or provider render unexpectedly throws. */
+    fallback?: KeepErrorBoundaryProps["fallback"];
+    onBoundaryError?: KeepErrorBoundaryProps["onError"];
+    boundaryResetKey?: unknown;
+    validateItem?: KeepItemRevalidator<TMeta>;
+    resolveItem?: KeepItemResolver<TMeta>;
 }>;
 type KeepStoreAccess<TMeta> = {
     store: KeepStore<TMeta>;
     actions: KeepStoreActions<TMeta>;
 };
-declare function KeepProvider<TMeta = Record<string, unknown>>({ storage, initialItems, onSave, onRemove, onNoteUpdate, onTagsUpdate, onChange, onError, plugins, schemaVersion, schema, invalidItemPolicy, onInvalidItem, migrateMeta, children, }: KeepProviderProps<TMeta>): react.JSX.Element;
+declare function KeepProvider<TMeta = Record<string, unknown>>({ storage, initialItems, onSave, onRemove, onNoteUpdate, onTagsUpdate, onChange, onError, plugins, schemaVersion, schema, invalidItemPolicy, onInvalidItem, migrateMeta, fallback, onBoundaryError, boundaryResetKey, validateItem, resolveItem, children, }: KeepProviderProps<TMeta>): react.JSX.Element;
 declare function useKeepContext<TMeta = Record<string, unknown>>(): KeepContextValue<TMeta>;
 declare function useKeepStore<TMeta = Record<string, unknown>>(): KeepStoreAccess<TMeta>;
 
@@ -151,4 +179,4 @@ type KeepKit<TMeta> = {
 /** Create an app-specific, fully typed set of KeepKit components and hooks. */
 declare function createKeepKit<TMeta = Record<string, unknown>>(options?: CreateKeepKitOptions<TMeta>): KeepKit<TMeta>;
 
-export { type CreateKeepKitOptions, KeepButton, type KeepButtonItem, type KeepButtonProps, type KeepButtonState, type KeepContextValue, KeepItemMetadataRefresher, KeepItemRevalidationSummary, KeepItemRevalidator, type KeepKit, KeepListQuery, KeepProvider, type KeepProviderProps, type KeepShortcutModifier, type KeepShortcutOptions, RevalidateKeepItemsOptions, type UseKeepItemResult, type UseKeepListResult, createKeepKit, useKeepContext, useKeepItem, useKeepList, useKeepShortcut, useKeepStore };
+export { type CreateKeepKitOptions, KeepButton, type KeepButtonItem, type KeepButtonProps, type KeepButtonState, type KeepContextValue, KeepErrorBoundary, type KeepErrorBoundaryProps, KeepItemMetadataRefresher, KeepItemResolver, KeepItemRevalidationSummary, KeepItemRevalidator, type KeepKit, KeepListQuery, KeepProvider, type KeepProviderProps, type KeepShortcutModifier, type KeepShortcutOptions, RevalidateKeepItemsOptions, type UseKeepItemResult, type UseKeepListResult, createKeepKit, useKeepContext, useKeepItem, useKeepList, useKeepShortcut, useKeepStore };

package/dist/react.js

@@ -1,10 +1,12 @@
 "use client";
 import {
   KeepStore,
+  exportItems,
+  importItems,
   isKeepItemMetadataStale,
   queryKeepItems,
   revalidateKeepItems
-} from "./chunk-AWQWKK4V.js";
+} from "./chunk-XF5VI6O5.js";
 import {
   parseKeepMeta
 } from "./chunk-THZ3ACR2.js";
@@ -12,7 +14,7 @@ import "./chunk-5QSZP6MT.js";
 import {
   createBrowserStorageAdapter,
   normalizeKeepTags
-} from "./chunk-DBRHZ6XU.js";
+} from "./chunk-EXE4E3GA.js";
 
 // src/hooks/useKeepItem.ts
 import { useCallback as useCallback3 } from "react";
@@ -27,6 +29,34 @@ import {
   useRef,
   useSyncExternalStore
 } from "react";
+
+// src/KeepErrorBoundary.tsx
+import { Component } from "react";
+var KeepErrorBoundary = class extends Component {
+  constructor() {
+    super(...arguments);
+    this.state = { error: null };
+  }
+  static getDerivedStateFromError(error) {
+    return { error };
+  }
+  componentDidCatch(error, info) {
+    this.props.onError?.(error, info);
+  }
+  componentDidUpdate(previousProps) {
+    if (this.state.error !== null && previousProps.resetKey !== this.props.resetKey) {
+      this.setState({ error: null });
+    }
+  }
+  render() {
+    if (this.state.error !== null) {
+      return typeof this.props.fallback === "function" ? this.props.fallback(this.state.error) : this.props.fallback ?? null;
+    }
+    return this.props.children;
+  }
+};
+
+// src/KeepProvider.tsx
 import { jsx } from "react/jsx-runtime";
 var defaultStorage = createBrowserStorageAdapter();
 var KeepContext = createContext(null);
@@ -46,6 +76,55 @@ function KeepProvider({
   invalidItemPolicy = "error",
   onInvalidItem,
   migrateMeta,
+  fallback,
+  onBoundaryError,
+  boundaryResetKey,
+  validateItem,
+  resolveItem,
+  children
+}) {
+  const content = /* @__PURE__ */ jsx(
+    KeepProviderContent,
+    {
+      storage,
+      initialItems,
+      onSave,
+      onRemove,
+      onNoteUpdate,
+      onTagsUpdate,
+      onChange,
+      onError,
+      plugins,
+      schemaVersion,
+      schema,
+      invalidItemPolicy,
+      onInvalidItem,
+      migrateMeta,
+      validateItem,
+      resolveItem,
+      children
+    }
+  );
+  if (fallback === void 0 && onBoundaryError === void 0) return content;
+  return /* @__PURE__ */ jsx(KeepErrorBoundary, { fallback, onError: onBoundaryError, resetKey: boundaryResetKey, children: content });
+}
+function KeepProviderContent({
+  storage = defaultStorage,
+  initialItems,
+  onSave,
+  onRemove,
+  onNoteUpdate,
+  onTagsUpdate,
+  onChange,
+  onError,
+  plugins = [],
+  schemaVersion,
+  schema,
+  invalidItemPolicy = "error",
+  onInvalidItem,
+  migrateMeta,
+  validateItem,
+  resolveItem,
   children
 }) {
   const storeRef = useRef(null);
@@ -411,7 +490,13 @@ function KeepProvider({
         const previous = itemsRef.current;
         let persistenceStarted = false;
         try {
-          const summary = await revalidateKeepItems(previous, revalidator, options);
+          const activeRevalidator = revalidator ?? validateItem;
+          if (!activeRevalidator)
+            throw new Error("KeepProvider.revalidateItems requires a revalidator or validateItem.");
+          const summary = await revalidateKeepItems(previous, activeRevalidator, {
+            ...options,
+            resolveItem: options.resolveItem ?? resolveItem
+          });
           const pluginContext = { action: "revalidate", items: summary.updatedItems };
           await runBeforePlugins(pluginContext);
           if (summary.updatedItems.length > 0) {
@@ -447,7 +532,17 @@ function KeepProvider({
         if (pendingMutationsRef.current === 0) store.setState({ isMutating: false });
       });
     },
-    [enqueueOperation, reportError, runAfterPlugins, runBeforePlugins, setItems, storage, store]
+    [
+      enqueueOperation,
+      reportError,
+      resolveItem,
+      runAfterPlugins,
+      runBeforePlugins,
+      setItems,
+      storage,
+      store,
+      validateItem
+    ]
   );
   const refreshItemMetadata = useCallback(
     async (id, refresh2) => {
@@ -462,6 +557,34 @@ function KeepProvider({
     [revalidateItems]
   );
   const flushSync = useCallback(() => syncStorage ? syncStorage.flushSync() : Promise.resolve(), [syncStorage]);
+  const exportBackup = useCallback(() => exportItems(storage), [storage]);
+  const importBackup = useCallback(
+    async (data, options = {}) => {
+      pendingMutationsRef.current += 1;
+      store.setState({ isMutating: true });
+      const run = enqueueOperation(async () => {
+        try {
+          const result = await importItems(storage, data, {
+            ...options,
+            schema: migrationRef.current.schema,
+            invalidItemPolicy: options.invalidItemPolicy ?? migrationRef.current.invalidItemPolicy,
+            onInvalidItem: options.onInvalidItem ?? migrationRef.current.onInvalidItem
+          });
+          setItems(result.items);
+          store.setState({ error: null });
+          return result;
+        } catch (cause) {
+          reportError(cause, { action: "import" });
+          throw cause;
+        }
+      });
+      return run.finally(() => {
+        pendingMutationsRef.current -= 1;
+        if (pendingMutationsRef.current === 0) store.setState({ isMutating: false });
+      });
+    },
+    [enqueueOperation, reportError, setItems, storage, store]
+  );
   const value = useMemo(
     () => ({
       items,
@@ -483,7 +606,9 @@ function KeepProvider({
       refresh,
       flushSync,
       refreshItemMetadata,
-      revalidateItems
+      revalidateItems,
+      exportBackup,
+      importBackup
     }),
     [
       clear,
@@ -505,7 +630,9 @@ function KeepProvider({
       removeTagsBatch,
       removeItems,
       refreshItemMetadata,
-      revalidateItems
+      revalidateItems,
+      exportBackup,
+      importBackup
     ]
   );
   const actions = useMemo(
@@ -855,6 +982,9 @@ function KeepButton({
   const commonProps = {
     ...buttonProps,
     "aria-pressed": isSaved,
+    "data-state": isSaved ? "saved" : "unsaved",
+    "data-loading": state.isLoading || state.isMutating ? "true" : void 0,
+    "data-disabled": isDisabled ? "true" : void 0,
     "aria-label": ("aria-label" in buttonProps ? buttonProps["aria-label"] : void 0) ?? getAriaLabel?.(state) ?? (isSaved ? savedAriaLabel : unsavedAriaLabel) ?? getAccessibleLabel(isSaved, item, asChild),
     ...asChild ? {
       "aria-disabled": isDisabled,
@@ -895,6 +1025,7 @@ function createKeepKit(options = {}) {
 }
 export {
   KeepButton,
+  KeepErrorBoundary,
   KeepProvider,
   createKeepKit,
   isKeepItemMetadataStale,