@keepkit/core 0.1.0 → 0.3.0

package/dist/react.d.ts

@@ -0,0 +1,159 @@
+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 KeepListOptions, g as KeepStore, h as KeepStoreActions } from './store-DyjKY0s4.js';
+export { b as KeepItemRevalidationResult, e as KeepItemStatus, k as isKeepItemMetadataStale } from './store-DyjKY0s4.js';
+import { m as KeepItemInput, a as KeepItem, l as KeepEventHandlers, S as StorageAdapter, d as KeepPlugin, K as KeepSchema, b as KeepInvalidItemPolicy, t as KeepSyncState } from './types-BRfvVnCA.js';
+
+type UseKeepItemResult<TMeta = Record<string, unknown>> = {
+    item: KeepItem<TMeta> | undefined;
+    isSaved: boolean;
+    isLoading: boolean;
+    isMutating: boolean;
+    error: unknown | null;
+    save: () => Promise<void>;
+    remove: () => Promise<void>;
+    toggle: () => Promise<void>;
+    updateNote: (note?: string) => Promise<void>;
+    updateTags: (tags?: string[]) => Promise<void>;
+    refreshMetadata: (refresh: KeepItemMetadataRefresher<TMeta>) => Promise<void>;
+};
+declare function useKeepItem<TMeta = Record<string, unknown>>(id: string, itemPayload?: KeepItemInput<TMeta>): UseKeepItemResult<TMeta>;
+
+type UseKeepListResult<TMeta = Record<string, unknown>> = {
+    items: KeepItem<TMeta>[];
+    totalCount: number;
+    tags: string[];
+    tagCounts: Record<string, number>;
+    isLoading: boolean;
+    isHydrated: boolean;
+    isMutating: boolean;
+    error: unknown | null;
+    remove: (id: string) => Promise<void>;
+    removeBatch: (ids: string[]) => Promise<void>;
+    updateTagsBatch: (ids: string[], tags?: string[]) => Promise<void>;
+    addTagsBatch: (ids: string[], tags: string[]) => Promise<void>;
+    removeTagsBatch: (ids: string[], tags: string[]) => Promise<void>;
+    clear: () => Promise<void>;
+    refresh: () => Promise<void>;
+    revalidate: (revalidator: KeepItemRevalidator<TMeta>, options?: RevalidateKeepItemsOptions) => Promise<KeepItemRevalidationSummary<TMeta>>;
+};
+declare function useKeepList<TMeta = Record<string, unknown>>(options?: KeepListOptions<TMeta>): UseKeepListResult<TMeta>;
+
+type KeepShortcutModifier = "meta" | "ctrl" | "alt" | "shift";
+type KeepShortcutOptions<TMeta = Record<string, unknown>> = {
+    key: string;
+    modifier?: KeepShortcutModifier;
+    id?: string;
+    itemPayload?: KeepItemInput<TMeta>;
+    action?: "toggle" | "save" | "remove";
+    enabled?: boolean;
+    preventDefault?: boolean;
+    allowInEditable?: boolean;
+    onTrigger?: (event: KeyboardEvent) => void | Promise<void>;
+    onError?: (error: unknown) => void;
+};
+/** Bind a keyboard shortcut to a Keep action or an arbitrary command. */
+declare function useKeepShortcut<TMeta = Record<string, unknown>>(options: KeepShortcutOptions<TMeta>): void;
+
+type KeepButtonItem<TMeta = Record<string, unknown>> = KeepItemInput<TMeta> & {
+    id: string;
+};
+type KeepButtonSharedProps<TMeta> = {
+    item: KeepButtonItem<TMeta>;
+    children?: ReactNode | ((state: KeepButtonState<TMeta>) => ReactNode);
+    savedLabel?: ReactNode;
+    unsavedLabel?: ReactNode;
+    savedAriaLabel?: string;
+    unsavedAriaLabel?: string;
+    getAriaLabel?: (state: KeepButtonState<TMeta>) => string;
+    disabled?: boolean;
+    onToggleError?: (error: unknown) => void;
+};
+type KeepButtonProps<TMeta = Record<string, unknown>> = KeepButtonSharedProps<TMeta> & ((Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "onClick" | "aria-pressed"> & {
+    asChild?: false;
+    onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+}) | (Omit<HTMLAttributes<HTMLElement>, "children" | "onClick" | "aria-pressed"> & {
+    asChild: true;
+    children: ReactElement | ((state: KeepButtonState<TMeta>) => ReactElement);
+    onClick?: (event: MouseEvent<HTMLElement>) => void;
+}));
+type KeepButtonState<TMeta = Record<string, unknown>> = {
+    item: ReturnType<typeof useKeepItem<TMeta>>["item"];
+    isSaved: boolean;
+    isLoading: boolean;
+    isMutating: boolean;
+    error: unknown | null;
+    save: () => Promise<void>;
+    remove: () => Promise<void>;
+    toggle: () => Promise<void>;
+    updateNote: (note?: string) => Promise<void>;
+    updateTags: (tags?: string[]) => Promise<void>;
+};
+/** 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 KeepContextValue<TMeta = Record<string, unknown>> = {
+    items: KeepItem<TMeta>[];
+    isLoading: boolean;
+    isHydrated: boolean;
+    isMutating: boolean;
+    error: unknown | null;
+    syncState: KeepSyncState;
+    saveItem: (item: KeepItem<TMeta>) => Promise<void>;
+    updateNote: (id: string, note?: string) => Promise<void>;
+    updateTags: (id: string, tags?: string[]) => Promise<void>;
+    updateTagsBatch: (ids: string[], tags?: string[]) => Promise<void>;
+    addTagsBatch: (ids: string[], tags: string[]) => Promise<void>;
+    removeTagsBatch: (ids: string[], tags: string[]) => Promise<void>;
+    removeItem: (id: string) => Promise<void>;
+    removeItems: (ids: string[]) => Promise<void>;
+    clear: () => Promise<void>;
+    refresh: () => Promise<void>;
+    flushSync: () => Promise<void>;
+    refreshItemMetadata: (id: string, refresh: KeepItemMetadataRefresher<TMeta>) => Promise<void>;
+    revalidateItems: (revalidator: KeepItemRevalidator<TMeta>, options?: RevalidateKeepItemsOptions) => Promise<KeepItemRevalidationSummary<TMeta>>;
+};
+type KeepProviderProps<TMeta = Record<string, unknown>> = PropsWithChildren<KeepEventHandlers<TMeta> & {
+    storage?: StorageAdapter<TMeta>;
+    /**
+     * Optional server-provided snapshot rendered before the client adapter
+     * finishes hydrating. The adapter remains the source of truth after the
+     * first refresh.
+     */
+    initialItems?: KeepItem<TMeta>[];
+    plugins?: KeepPlugin<TMeta>[];
+    schemaVersion?: number;
+    schema?: KeepSchema<TMeta>;
+    invalidItemPolicy?: KeepInvalidItemPolicy;
+    onInvalidItem?: (error: unknown, item: KeepItem<unknown>) => void;
+    migrateMeta?: (meta: unknown, fromVersion: number, toVersion: number, item: KeepItem<TMeta>) => TMeta | Promise<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 useKeepContext<TMeta = Record<string, unknown>>(): KeepContextValue<TMeta>;
+declare function useKeepStore<TMeta = Record<string, unknown>>(): KeepStoreAccess<TMeta>;
+
+type CreateKeepKitOptions<TMeta = Record<string, unknown>> = {
+    initialItems?: KeepProviderProps<TMeta>["initialItems"];
+    plugins?: KeepPlugin<TMeta>[];
+    schemaVersion?: number;
+    schema?: KeepSchema<TMeta>;
+    invalidItemPolicy?: KeepInvalidItemPolicy;
+    onInvalidItem?: KeepProviderProps<TMeta>["onInvalidItem"];
+    migrateMeta?: KeepProviderProps<TMeta>["migrateMeta"];
+};
+type KeepKit<TMeta> = {
+    KeepProvider: ComponentType<KeepProviderProps<TMeta>>;
+    KeepButton: ComponentType<KeepButtonProps<TMeta>>;
+    useKeepContext: () => ReturnType<typeof useKeepContext<TMeta>>;
+    useKeepItem: (id: string, itemPayload?: KeepItemInput<TMeta>) => UseKeepItemResult<TMeta>;
+    useKeepList: (options?: KeepListOptions<TMeta>) => UseKeepListResult<TMeta>;
+    useKeepShortcut: (options: KeepShortcutOptions<TMeta>) => void;
+};
+/** 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, KeepListOptions, KeepProvider, type KeepProviderProps, type KeepShortcutModifier, type KeepShortcutOptions, RevalidateKeepItemsOptions, type UseKeepItemResult, type UseKeepListResult, createKeepKit, useKeepContext, useKeepItem, useKeepList, useKeepShortcut, useKeepStore };