@marktiderman/genesis-core 1.4.0 → 1.5.1

package/dist/chunk-HUNGCTRA.js

@@ -0,0 +1,33 @@
+// src/schema/read-outcome.ts
+var DataReadError = class extends Error {
+  outcome;
+  /** The store's own error code, when it gave one. */
+  code;
+  constructor(outcome, message, options = {}) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "DataReadError";
+    this.outcome = outcome;
+    if (options.code !== void 0) this.code = options.code;
+  }
+};
+function isDataReadError(error) {
+  return error instanceof Error && error.name === "DataReadError" && typeof error.outcome === "string";
+}
+function readFailureMessage(outcome, noun, one, plural = `${noun}s`) {
+  switch (outcome) {
+    case "unauthenticated":
+      return "Your session has ended. Sign in again to continue.";
+    case "forbidden":
+      return one ? `You don't have access to this ${noun}.` : `You don't have access to these ${plural}.`;
+    case "gone":
+      return `This ${noun} doesn't exist, or you can't see it.`;
+    case "invalid":
+      return one ? `This ${noun} couldn't be loaded.` : `These ${plural} couldn't be loaded.`;
+    default:
+      return one ? `This ${noun} couldn't be loaded. Try again.` : `These ${plural} couldn't be loaded. Try again.`;
+  }
+}
+
+export { DataReadError, isDataReadError, readFailureMessage };
+//# sourceMappingURL=chunk-HUNGCTRA.js.map
+//# sourceMappingURL=chunk-HUNGCTRA.js.map

package/dist/chunk-HUNGCTRA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema/read-outcome.ts"],"names":[],"mappings":";AAyBO,IAAM,aAAA,GAAN,cAA4B,KAAA,CAAM;AAAA,EAC9B,OAAA;AAAA;AAAA,EAEA,IAAA;AAAA,EAET,WAAA,CAAY,OAAA,EAAsB,OAAA,EAAiB,OAAA,GAAgC,EAAC,EAAG;AACrF,IAAA,KAAA,CAAM,OAAA,EAAS,QAAQ,KAAA,KAAU,MAAA,GAAY,SAAY,EAAE,KAAA,EAAO,OAAA,CAAQ,KAAA,EAAO,CAAA;AACjF,IAAA,IAAA,CAAK,IAAA,GAAO,eAAA;AACZ,IAAA,IAAA,CAAK,OAAA,GAAU,OAAA;AACf,IAAA,IAAI,OAAA,CAAQ,IAAA,KAAS,MAAA,EAAW,IAAA,CAAK,OAAO,OAAA,CAAQ,IAAA;AAAA,EACtD;AACF;AAMO,SAAS,gBAAgB,KAAA,EAAwC;AACtE,EAAA,OACE,iBAAiB,KAAA,IACjB,KAAA,CAAM,SAAS,eAAA,IACf,OAAQ,MAAgC,OAAA,KAAY,QAAA;AAExD;AAGO,SAAS,mBAAmB,OAAA,EAAsB,IAAA,EAAc,KAAc,MAAA,GAAS,CAAA,EAAG,IAAI,CAAA,CAAA,CAAA,EAAa;AAChH,EAAA,QAAQ,OAAA;AAAS,IACf,KAAK,iBAAA;AACH,MAAA,OAAO,oDAAA;AAAA,IACT,KAAK,WAAA;AACH,MAAA,OAAO,GAAA,GAAM,CAAA,8BAAA,EAAiC,IAAI,CAAA,CAAA,CAAA,GAAM,kCAAkC,MAAM,CAAA,CAAA,CAAA;AAAA,IAClG,KAAK,MAAA;AACH,MAAA,OAAO,QAAQ,IAAI,CAAA,oCAAA,CAAA;AAAA,IACrB,KAAK,SAAA;AACH,MAAA,OAAO,GAAA,GAAM,CAAA,KAAA,EAAQ,IAAI,CAAA,oBAAA,CAAA,GAAyB,SAAS,MAAM,CAAA,oBAAA,CAAA;AAAA,IACnE;AACE,MAAA,OAAO,GAAA,GAAM,CAAA,KAAA,EAAQ,IAAI,CAAA,+BAAA,CAAA,GAAoC,SAAS,MAAM,CAAA,+BAAA,CAAA;AAAA;AAElF","file":"chunk-HUNGCTRA.js","sourcesContent":["// ---------------------------------------------------------------------------\n// Why a read failed, in words a user can be shown\n//\n// A store's own error text (\"relation \\\"tasks\\\" does not exist\", \"JWT\n// expired\", a constraint name) is for developers. A read error carries a\n// plain message for the screen and keeps the store's error as its `cause`.\n// ---------------------------------------------------------------------------\n\n/**\n * - `unauthenticated`: no signed-in user, or the session expired.\n * - `forbidden`: this user may not read these records.\n * - `gone`: the one record asked for doesn't exist, or isn't visible.\n * - `invalid`: the request itself was wrong (an unknown column, a bad value).\n * - `error`: anything else.\n */\nexport type ReadOutcome = \"unauthenticated\" | \"forbidden\" | \"gone\" | \"invalid\" | \"error\";\n\nexport interface DataReadErrorOptions {\n  /** The store's own error code (a Postgres SQLSTATE or PostgREST code). */\n  code?: string;\n  /** The underlying error, with its raw text, kept for logging. */\n  cause?: unknown;\n}\n\n/** Thrown by a provider when a read failed. Its `message` is safe to show. */\nexport class DataReadError extends Error {\n  readonly outcome: ReadOutcome;\n  /** The store's own error code, when it gave one. */\n  readonly code?: string;\n\n  constructor(outcome: ReadOutcome, message: string, options: DataReadErrorOptions = {}) {\n    super(message, options.cause === undefined ? undefined : { cause: options.cause });\n    this.name = \"DataReadError\";\n    this.outcome = outcome;\n    if (options.code !== undefined) this.code = options.code;\n  }\n}\n\n/**\n * `instanceof` fails when two copies of this package are installed, so check\n * the shape instead.\n */\nexport function isDataReadError(error: unknown): error is DataReadError {\n  return (\n    error instanceof Error &&\n    error.name === \"DataReadError\" &&\n    typeof (error as { outcome?: unknown }).outcome === \"string\"\n  );\n}\n\n/** The plain sentence for a failed read of `noun` records (one, or a list). */\nexport function readFailureMessage(outcome: ReadOutcome, noun: string, one: boolean, plural = `${noun}s`): string {\n  switch (outcome) {\n    case \"unauthenticated\":\n      return \"Your session has ended. Sign in again to continue.\";\n    case \"forbidden\":\n      return one ? `You don't have access to this ${noun}.` : `You don't have access to these ${plural}.`;\n    case \"gone\":\n      return `This ${noun} doesn't exist, or you can't see it.`;\n    case \"invalid\":\n      return one ? `This ${noun} couldn't be loaded.` : `These ${plural} couldn't be loaded.`;\n    default:\n      return one ? `This ${noun} couldn't be loaded. Try again.` : `These ${plural} couldn't be loaded. Try again.`;\n  }\n}\n"]}

package/dist/chunk-XQO4OH2N.js

@@ -0,0 +1,32 @@
+import { useRef, useEffect, useCallback } from 'react';
+
+// src/hooks/use-unsaved-changes-guard.ts
+var DEFAULT_UNSAVED_CHANGES_MESSAGE = "You have unsaved changes. Leave without saving?";
+function useUnsavedChangesGuard(options) {
+  const { when, message = DEFAULT_UNSAVED_CHANGES_MESSAGE, confirm } = options;
+  const whenRef = useRef(when);
+  whenRef.current = when;
+  const messageRef = useRef(message);
+  messageRef.current = message;
+  const confirmRef = useRef(confirm);
+  confirmRef.current = confirm;
+  useEffect(() => {
+    if (!when || typeof window === "undefined") return;
+    const onBeforeUnload = (event) => {
+      event.preventDefault();
+      event.returnValue = "";
+    };
+    window.addEventListener("beforeunload", onBeforeUnload);
+    return () => window.removeEventListener("beforeunload", onBeforeUnload);
+  }, [when]);
+  const confirmLeave = useCallback(() => {
+    if (!whenRef.current) return true;
+    const ask = confirmRef.current ?? (typeof window !== "undefined" && typeof window.confirm === "function" ? (text) => window.confirm(text) : () => true);
+    return ask(messageRef.current);
+  }, []);
+  return { isBlocking: when, confirmLeave };
+}
+
+export { DEFAULT_UNSAVED_CHANGES_MESSAGE, useUnsavedChangesGuard };
+//# sourceMappingURL=chunk-XQO4OH2N.js.map
+//# sourceMappingURL=chunk-XQO4OH2N.js.map

package/dist/chunk-XQO4OH2N.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hooks/use-unsaved-changes-guard.ts"],"names":[],"mappings":";;;AAEO,IAAM,+BAAA,GACX;AAiCK,SAAS,uBACd,OAAA,EAC8B;AAC9B,EAAA,MAAM,EAAE,IAAA,EAAM,OAAA,GAAU,+BAAA,EAAiC,SAAQ,GAAI,OAAA;AACrE,EAAA,MAAM,OAAA,GAAU,OAAO,IAAI,CAAA;AAC3B,EAAA,OAAA,CAAQ,OAAA,GAAU,IAAA;AAClB,EAAA,MAAM,UAAA,GAAa,OAAO,OAAO,CAAA;AACjC,EAAA,UAAA,CAAW,OAAA,GAAU,OAAA;AACrB,EAAA,MAAM,UAAA,GAAa,OAAO,OAAO,CAAA;AACjC,EAAA,UAAA,CAAW,OAAA,GAAU,OAAA;AAErB,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,IAAI,CAAC,IAAA,IAAQ,OAAO,MAAA,KAAW,WAAA,EAAa;AAC5C,IAAA,MAAM,cAAA,GAAiB,CAAC,KAAA,KAA6B;AACnD,MAAA,KAAA,CAAM,cAAA,EAAe;AAErB,MAAA,KAAA,CAAM,WAAA,GAAc,EAAA;AAAA,IACtB,CAAA;AACA,IAAA,MAAA,CAAO,gBAAA,CAAiB,gBAAgB,cAAc,CAAA;AACtD,IAAA,OAAO,MAAM,MAAA,CAAO,mBAAA,CAAoB,cAAA,EAAgB,cAAc,CAAA;AAAA,EACxE,CAAA,EAAG,CAAC,IAAI,CAAC,CAAA;AAET,EAAA,MAAM,YAAA,GAAe,YAAY,MAAe;AAC9C,IAAA,IAAI,CAAC,OAAA,CAAQ,OAAA,EAAS,OAAO,IAAA;AAC7B,IAAA,MAAM,MACJ,UAAA,CAAW,OAAA,KACV,OAAO,MAAA,KAAW,eAAe,OAAO,MAAA,CAAO,OAAA,KAAY,UAAA,GACxD,CAAC,IAAA,KAAiB,MAAA,CAAO,OAAA,CAAQ,IAAI,IACrC,MAAM,IAAA,CAAA;AACZ,IAAA,OAAO,GAAA,CAAI,WAAW,OAAO,CAAA;AAAA,EAC/B,CAAA,EAAG,EAAE,CAAA;AAEL,EAAA,OAAO,EAAE,UAAA,EAAY,IAAA,EAAM,YAAA,EAAa;AAC1C","file":"chunk-XQO4OH2N.js","sourcesContent":["import { useCallback, useEffect, useRef } from \"react\";\n\nexport const DEFAULT_UNSAVED_CHANGES_MESSAGE =\n  \"You have unsaved changes. Leave without saving?\";\n\nexport interface UseUnsavedChangesGuardOptions {\n  /** Guard while this is true (e.g. a form is dirty). */\n  when: boolean;\n  /** The question `confirmLeave` asks. */\n  message?: string;\n  /**\n   * How to ask. Default `window.confirm`. Must answer synchronously, since\n   * router blockers and `beforeunload` cannot wait.\n   */\n  confirm?: (message: string) => boolean;\n}\n\nexport interface UseUnsavedChangesGuardReturn {\n  /** True while leaving would lose changes. */\n  isBlocking: boolean;\n  /**\n   * Call before leaving in-app (closing a dialog, a router blocker). Returns\n   * true when it is fine to leave: nothing to lose, or the user said so.\n   */\n  confirmLeave: () => boolean;\n}\n\n/**\n * Warns before unsaved changes are lost, without depending on a router.\n *\n * - While `when` is true, closing or reloading the tab shows the browser's\n *   own \"Leave site?\" prompt (`beforeunload`).\n * - `confirmLeave()` is for in-app navigation: wire it to your router's\n *   blocker (React Router `useBlocker`, TanStack Router `useBlocker`), or call\n *   it before closing a dialog. See SKILL.md \"Unsaved changes\".\n */\nexport function useUnsavedChangesGuard(\n  options: UseUnsavedChangesGuardOptions,\n): UseUnsavedChangesGuardReturn {\n  const { when, message = DEFAULT_UNSAVED_CHANGES_MESSAGE, confirm } = options;\n  const whenRef = useRef(when);\n  whenRef.current = when;\n  const messageRef = useRef(message);\n  messageRef.current = message;\n  const confirmRef = useRef(confirm);\n  confirmRef.current = confirm;\n\n  useEffect(() => {\n    if (!when || typeof window === \"undefined\") return;\n    const onBeforeUnload = (event: BeforeUnloadEvent) => {\n      event.preventDefault();\n      // Older browsers need returnValue set to show the prompt.\n      event.returnValue = \"\";\n    };\n    window.addEventListener(\"beforeunload\", onBeforeUnload);\n    return () => window.removeEventListener(\"beforeunload\", onBeforeUnload);\n  }, [when]);\n\n  const confirmLeave = useCallback((): boolean => {\n    if (!whenRef.current) return true;\n    const ask =\n      confirmRef.current ??\n      (typeof window !== \"undefined\" && typeof window.confirm === \"function\"\n        ? (text: string) => window.confirm(text)\n        : () => true);\n    return ask(messageRef.current);\n  }, []);\n\n  return { isBlocking: when, confirmLeave };\n}\n"]}

package/dist/hooks/index.d.ts

@@ -1,8 +1,12 @@
 export { UseResourceOptions, UseResourceReturn, useResource } from './use-resource.js';
 export { UseOneOptions, useOne } from './use-one.js';
+export { useCapabilities } from './use-capabilities.js';
 export { UseResourceFormOptions, UseResourceFormReturn, buildArrayItemDefaults, useResourceForm } from './use-resource-form.js';
 export { UseWizardReturn, WizardStep, useWizard } from './use-wizard.js';
+export { DEFAULT_UNDO_DELAY_MS, MutationMode, MutationModeOptions, UndoableWrite, pendingWriteCount } from './mutation-mode.js';
+export { DEFAULT_UNSAVED_CHANGES_MESSAGE, UseUnsavedChangesGuardOptions, UseUnsavedChangesGuardReturn, useUnsavedChangesGuard } from './use-unsaved-changes-guard.js';
 import '@tanstack/react-query';
-import '../types-zILrlHuV.js';
+import '../types-DDOmG9hj.js';
+import '../types-5cuflvha.js';
 import '../form-types.js';
 import 'react-hook-form';

package/dist/hooks/index.js

@@ -1,10 +1,14 @@
-import '../chunk-EL7YGOTY.js';
+import '../chunk-HT43MPKW.js';
+export { buildArrayItemDefaults, useResourceForm } from '../chunk-3JSFTLDV.js';
+export { useResource } from '../chunk-6Q477CHB.js';
+export { DEFAULT_UNSAVED_CHANGES_MESSAGE, useUnsavedChangesGuard } from '../chunk-XQO4OH2N.js';
 export { useWizard } from '../chunk-7KOLYF27.js';
-export { buildArrayItemDefaults, useResourceForm } from '../chunk-IHWWJUEN.js';
+import '../chunk-5NHR6ZXS.js';
 import '../chunk-RYEXWQFD.js';
-export { useOne } from '../chunk-ZK5C3OOT.js';
-export { useResource } from '../chunk-P4OIIRQS.js';
+export { DEFAULT_UNDO_DELAY_MS, pendingWriteCount } from '../chunk-F3BE7NGM.js';
 import '../chunk-7NUL32W7.js';
+export { useCapabilities } from '../chunk-BQOJX67X.js';
+export { useOne } from '../chunk-ZK5C3OOT.js';
 import '../chunk-GGSXSI6Z.js';
 import '../chunk-ZYJUEJ4Z.js';
 //# sourceMappingURL=index.js.map

package/dist/hooks/mutation-mode.d.ts

@@ -0,0 +1,119 @@
+import { QueryClient } from '@tanstack/react-query';
+import { I as Identifier, B as BaseRecord, D as DataProvider } from '../types-DDOmG9hj.js';
+import { A as AuditEntry } from '../types-5cuflvha.js';
+import '../form-types.js';
+
+type MutationMode = "pessimistic" | "optimistic" | "undoable";
+/** How long an `undoable` write waits for an undo before it is sent. */
+declare const DEFAULT_UNDO_DELAY_MS = 5000;
+/** An undoable write, as handed to `onUndoable` so a UI can offer the undo. */
+interface UndoableWrite {
+    resource: string;
+    kind: "create" | "update" | "delete";
+    /** The record's id; absent for a create (it has none until it is sent). */
+    id?: Identifier;
+    /**
+     * - `delay`: the write has not been sent. `undo()` discards it; `commit()`
+     *   sends it now instead of waiting.
+     * - `provider`: the write was sent at once, because the provider serves
+     *   `undo`. `undo()` asks the provider to reverse it; `commit()` does
+     *   nothing.
+     */
+    strategy: "delay" | "provider";
+    /** How long the undo is offered, in ms (the toast's duration). */
+    delayMs: number;
+    /**
+     * Take the write back. Resolves true when it was undone (or will never be
+     * sent), false when it could not be: already sent under `delay` (the
+     * window closed, it was committed, a later write on the same record sent
+     * it first, or the page unloaded), already undone, or the provider's undo
+     * failed (reported through `onError`). Works after the hook that made the
+     * write has unmounted. Safe to call more than once.
+     */
+    undo: () => Promise<boolean>;
+    /** Send a `delay` write now. */
+    commit: () => void;
+}
+interface MutationModeOptions {
+    /** Default `"pessimistic"`. */
+    mutationMode?: MutationMode;
+    /** How long an `undoable` write waits, in ms. Default 5000. */
+    undoDelayMs?: number;
+    /** Called with every `undoable` write, to show an undo control. */
+    onUndoable?: (write: UndoableWrite) => void;
+}
+/** Structural equality for row values (JSON-like data, Dates). */
+declare function sameValue(a: unknown, b: unknown): boolean;
+/** The record as the cache has it now, from a detail entry or any list. */
+declare function cachedRecord(queryClient: QueryClient, resource: string, id: Identifier): BaseRecord | undefined;
+/** Optimistic or undoable writes on `resource` not yet settled. */
+declare function pendingWriteCount(queryClient: QueryClient, resource: string): number;
+/**
+ * Invalidate `[resource]`. Safe while optimistic/undoable writes on it are
+ * pending: their patches are re-applied to whatever the refetch brings.
+ */
+declare function invalidateResource(queryClient: QueryClient, resource: string): Promise<void>;
+/** What `send` is given when the write goes out. */
+interface SendContext {
+    /**
+     * The row-shaped values to send, when `data` was given. They can differ
+     * from `data`: an earlier write on the record that this one built on was
+     * taken back, and its values were put back. Send these.
+     */
+    data?: Record<string, unknown>;
+    /** The page is unloading: pass `keepalive: true` to the provider. */
+    keepalive: boolean;
+}
+interface ExecuteWriteArgs<R extends BaseRecord | void> {
+    queryClient: QueryClient;
+    provider: DataProvider;
+    resource: string;
+    kind: "create" | "update" | "delete";
+    id?: Identifier;
+    /**
+     * The values to merge into the cached row (update). Leave out to patch
+     * nothing, e.g. when the values are form-shaped and the row is not.
+     */
+    data?: Record<string, unknown>;
+    mode: MutationMode;
+    undoDelayMs?: number;
+    onUndoable?: (write: UndoableWrite) => void;
+    /** Sends the write. */
+    send: (context: SendContext) => Promise<{
+        record: R;
+        audit?: AuditEntry;
+    }>;
+    /** After the write committed. Invalidates and calls success callbacks. */
+    committed: (record: R) => Promise<void> | void;
+    /** A write that failed (or was dropped) after the caller was told it went through. */
+    failedLater: (error: Error) => void;
+}
+type ExecuteWriteResult<R> = {
+    status: "committed";
+    record: R;
+} | {
+    status: "applied";
+};
+/**
+ * Whether `provider` serves `undo` for `resource`, from its capabilities
+ * (useCapabilities' key, so the answer is shared, and scoped to this
+ * provider: a swapped-out provider's capabilities never offer undo).
+ * @internal Exported for tests.
+ */
+declare function providerServesUndo(queryClient: QueryClient, provider: DataProvider, resource: string): Promise<boolean>;
+/** A later write that built on one that was taken back. */
+declare const DROPPED_WRITE_MESSAGE = "This change was not saved: it was made on top of an earlier change that was undone or failed. Please make it again.";
+/**
+ * Runs one write in the given mode.
+ *
+ * - `pessimistic`: sends it and waits; a failure rejects.
+ * - `optimistic` / `undoable`: resolves `{ status: "applied" }` as soon as
+ *   the cache is patched. A later failure rolls the patch back and goes to
+ *   `failedLater`, never to the returned promise.
+ *
+ * Writes on the same record are sent one after another, in the order they
+ * were made; sending one first sends the earlier ones still waiting.
+ */
+declare function executeWrite<R extends BaseRecord | void>(args: ExecuteWriteArgs<R>): Promise<ExecuteWriteResult<R>>;
+
+export { DEFAULT_UNDO_DELAY_MS, DROPPED_WRITE_MESSAGE, type ExecuteWriteArgs, type ExecuteWriteResult, type MutationMode, type MutationModeOptions, type SendContext, type UndoableWrite, cachedRecord, executeWrite, invalidateResource, pendingWriteCount, providerServesUndo, sameValue };

package/dist/hooks/mutation-mode.js

@@ -0,0 +1,6 @@
+export { DEFAULT_UNDO_DELAY_MS, DROPPED_WRITE_MESSAGE, cachedRecord, executeWrite, invalidateResource, pendingWriteCount, providerServesUndo, sameValue } from '../chunk-F3BE7NGM.js';
+import '../chunk-BQOJX67X.js';
+import '../chunk-GGSXSI6Z.js';
+import '../chunk-ZYJUEJ4Z.js';
+//# sourceMappingURL=mutation-mode.js.map
+//# sourceMappingURL=mutation-mode.js.map

package/dist/hooks/mutation-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"mutation-mode.js"}

package/dist/hooks/related-keys.d.ts

@@ -1,4 +1,5 @@
-import { D as DataProvider, W as WriteEvent, p as InvalidationKey } from '../types-zILrlHuV.js';
+import { D as DataProvider, W as WriteEvent, j as InvalidationKey } from '../types-DDOmG9hj.js';
+import '../types-5cuflvha.js';
 import '../form-types.js';
 
 /**

package/dist/hooks/use-capabilities.d.ts

@@ -0,0 +1,21 @@
+import { UseQueryResult } from '@tanstack/react-query';
+import { P as ProviderCapabilities } from '../types-5cuflvha.js';
+import '../form-types.js';
+
+/**
+ * The query key for `provider`'s capabilities for `resource`. It includes
+ * the provider's identity: swapping the provider (another tenant, a
+ * different store) asks the new one instead of reusing the old answer.
+ * @internal
+ */
+declare function capabilitiesQueryKey(provider: object, resource: string | undefined): readonly unknown[];
+/**
+ * What the data provider can do for `resource` (`provider.capabilities`),
+ * cached per provider and resource. `data` stays undefined for a provider
+ * that doesn't report capabilities, so a UI keeps its defaults.
+ */
+declare function useCapabilities(resource: string | undefined, options?: {
+    enabled?: boolean;
+}): UseQueryResult<ProviderCapabilities>;
+
+export { capabilitiesQueryKey, useCapabilities };

package/dist/hooks/use-capabilities.js

@@ -0,0 +1,5 @@
+export { capabilitiesQueryKey, useCapabilities } from '../chunk-BQOJX67X.js';
+import '../chunk-GGSXSI6Z.js';
+import '../chunk-ZYJUEJ4Z.js';
+//# sourceMappingURL=use-capabilities.js.map
+//# sourceMappingURL=use-capabilities.js.map

package/dist/hooks/use-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"use-capabilities.js"}

package/dist/hooks/use-one.d.ts

@@ -1,5 +1,6 @@
 import { UseQueryResult } from '@tanstack/react-query';
-import { B as BaseRecord, I as Identifier } from '../types-zILrlHuV.js';
+import { B as BaseRecord, I as Identifier } from '../types-DDOmG9hj.js';
+import '../types-5cuflvha.js';
 import '../form-types.js';
 
 interface UseOneOptions {

package/dist/hooks/use-resource-form.d.ts

@@ -1,8 +1,11 @@
 import { UseFormReturn } from 'react-hook-form';
 import { ResourceFormFieldDef } from '../form-types.js';
-import { p as InvalidationKey } from '../types-zILrlHuV.js';
+import { j as InvalidationKey } from '../types-DDOmG9hj.js';
+import { MutationModeOptions } from './mutation-mode.js';
+import '../types-5cuflvha.js';
+import '@tanstack/react-query';
 
-interface UseResourceFormOptions {
+interface UseResourceFormOptions extends MutationModeOptions {
     resource: string;
     action: "create" | "edit";
     id?: string;
@@ -10,8 +13,35 @@ interface UseResourceFormOptions {
     fields?: ResourceFormFieldDef[];
     /** Full dataset used to auto-detect select fields from unique values. */
     listData?: Record<string, unknown>[];
+    /**
+     * The form is done. After the save in `pessimistic` mode (with the stored
+     * row); at once in `optimistic` and `undoable` modes (with the submitted
+     * values over the record, and no `id` for a create).
+     */
     onSuccess?: (data: Record<string, unknown>) => void;
+    /**
+     * The save failed. In `optimistic` and `undoable` modes the form may be
+     * gone by then, so show the error from here (genesis-ui's ResourceForm
+     * toasts it when no `onError` is given).
+     */
     onError?: (error: Error) => void;
+    /**
+     * Warn before unsaved changes are lost. Default false. While the form is
+     * dirty, closing or reloading the tab shows the browser's prompt, and
+     * `confirmLeave()` asks before in-app navigation (wire it to a router
+     * blocker; see SKILL.md "Unsaved changes").
+     */
+    warnWhenUnsaved?: boolean | {
+        message?: string;
+    };
+    /**
+     * Whether the form is on screen. Default true. Pass false while it is
+     * hidden but still mounted (a closed dialog). An optimistic or undoable
+     * save that fails later is put back on the form (field errors, unsaved
+     * again) only while the form is mounted, visible and still holds the
+     * values it saved; otherwise the failure only reaches `onError`.
+     */
+    visible?: boolean;
     /**
      * Pre-fill create form defaults from URL query params: a param named like a
      * field (`?status=draft`) becomes that field's starting value. Default true.
@@ -48,6 +78,17 @@ interface UseResourceFormReturn {
     handleSave: (data: Record<string, unknown>) => Promise<void>;
     isSaving: boolean;
     isLoading: boolean;
+    /**
+     * The form has changes that have not been saved. False again once a save
+     * succeeds (or, in optimistic / undoable modes, is handed off).
+     */
+    isDirty: boolean;
+    /**
+     * For in-app navigation: true when it is fine to leave (nothing unsaved,
+     * `warnWhenUnsaved` off, or the user confirmed). Asks with
+     * `window.confirm` otherwise.
+     */
+    confirmLeave: () => boolean;
 }
 /** Build default values for a single array item from its sub-field definitions */
 declare function buildArrayItemDefaults(arrayFields: ResourceFormFieldDef[]): Record<string, unknown>;

package/dist/hooks/use-resource-form.js

@@ -1,7 +1,11 @@
-export { buildArrayItemDefaults, useResourceForm } from '../chunk-IHWWJUEN.js';
+export { buildArrayItemDefaults, useResourceForm } from '../chunk-3JSFTLDV.js';
+import '../chunk-XQO4OH2N.js';
+import '../chunk-5NHR6ZXS.js';
 import '../chunk-RYEXWQFD.js';
-import '../chunk-ZK5C3OOT.js';
+import '../chunk-F3BE7NGM.js';
 import '../chunk-7NUL32W7.js';
+import '../chunk-BQOJX67X.js';
+import '../chunk-ZK5C3OOT.js';
 import '../chunk-GGSXSI6Z.js';
 import '../chunk-ZYJUEJ4Z.js';
 //# sourceMappingURL=use-resource-form.js.map

package/dist/hooks/use-resource.d.ts

@@ -1,8 +1,10 @@
 import { UseQueryResult, UseMutationResult } from '@tanstack/react-query';
-import { E as SortParam, k as FilterParam, p as InvalidationKey, q as ListResult, L as ListParams, I as Identifier, B as BaseRecord } from '../types-zILrlHuV.js';
+import { m as SortParam, F as FilterParam, j as InvalidationKey, k as ListResult, L as ListParams, I as Identifier, B as BaseRecord } from '../types-DDOmG9hj.js';
+import { MutationModeOptions } from './mutation-mode.js';
+import '../types-5cuflvha.js';
 import '../form-types.js';
 
-interface UseResourceOptions<T> {
+interface UseResourceOptions<T> extends MutationModeOptions {
     defaultSort?: SortParam;
     /**
      * Re-synced whenever its value changes (deep-equal, order-independent),
@@ -15,6 +17,10 @@ interface UseResourceOptions<T> {
      */
     defaultFilters?: FilterParam[];
     defaultPerPage?: number;
+    /** The page to start on (from 1), e.g. restored from the URL. Default 1. */
+    defaultPage?: number;
+    /** The search to start with, e.g. restored from the URL. Default "". */
+    defaultSearch?: string;
     /** Supabase select/join syntax, e.g. "*, author:profiles(name)". */
     select?: string;
     /** Fields to search across when setSearch is called. Required for server-side search. */
@@ -34,9 +40,19 @@ interface UseResourceOptions<T> {
      * rather than flashing a skeleton. Default false.
      */
     keepPreviousData?: boolean;
+    /**
+     * After the write commits, with the provider's row. In `optimistic` and
+     * `undoable` modes that is after `create` / `update` / `remove` have
+     * already resolved.
+     */
     onCreateSuccess?: (data: T) => void;
     onUpdateSuccess?: (data: T) => void;
     onDeleteSuccess?: () => void;
+    /**
+     * A write failed. In `optimistic` and `undoable` modes this is the only
+     * place a failure is reported (the cache has already been put back), so
+     * show it to the user here.
+     */
     onError?: (error: Error) => void;
 }
 interface UseResourceReturn<T> {
@@ -49,11 +65,19 @@ interface UseResourceReturn<T> {
     setPage: (page: number) => void;
     setPerPage: (perPage: number) => void;
     setSearch: (query: string) => void;
-    /** Create a new record. Returns the created item. */
+    /**
+     * Create a new record. Returns the created item. In `optimistic` and
+     * `undoable` modes it resolves at once with the values given (no `id` yet;
+     * `onCreateSuccess` gets the stored row).
+     */
     create: (data: Partial<T>) => Promise<T>;
-    /** Update an existing record by id. Returns the updated item. */
+    /**
+     * Update an existing record by id. Returns the updated item. In
+     * `optimistic` and `undoable` modes it resolves at once with the cached
+     * row merged with `data`.
+     */
     update: (id: Identifier, data: Partial<T>) => Promise<T>;
-    /** Delete a record by id. */
+    /** Delete a record by id. Resolves at once in `optimistic` / `undoable` modes. */
     remove: (id: Identifier) => Promise<void>;
     /** True when any mutation is in-flight. */
     isMutating: boolean;

package/dist/hooks/use-resource.js

@@ -1,5 +1,7 @@
-export { useResource } from '../chunk-P4OIIRQS.js';
+export { useResource } from '../chunk-6Q477CHB.js';
+import '../chunk-F3BE7NGM.js';
 import '../chunk-7NUL32W7.js';
+import '../chunk-BQOJX67X.js';
 import '../chunk-GGSXSI6Z.js';
 import '../chunk-ZYJUEJ4Z.js';
 //# sourceMappingURL=use-resource.js.map

package/dist/hooks/use-unsaved-changes-guard.d.ts

@@ -0,0 +1,33 @@
+declare const DEFAULT_UNSAVED_CHANGES_MESSAGE = "You have unsaved changes. Leave without saving?";
+interface UseUnsavedChangesGuardOptions {
+    /** Guard while this is true (e.g. a form is dirty). */
+    when: boolean;
+    /** The question `confirmLeave` asks. */
+    message?: string;
+    /**
+     * How to ask. Default `window.confirm`. Must answer synchronously, since
+     * router blockers and `beforeunload` cannot wait.
+     */
+    confirm?: (message: string) => boolean;
+}
+interface UseUnsavedChangesGuardReturn {
+    /** True while leaving would lose changes. */
+    isBlocking: boolean;
+    /**
+     * Call before leaving in-app (closing a dialog, a router blocker). Returns
+     * true when it is fine to leave: nothing to lose, or the user said so.
+     */
+    confirmLeave: () => boolean;
+}
+/**
+ * Warns before unsaved changes are lost, without depending on a router.
+ *
+ * - While `when` is true, closing or reloading the tab shows the browser's
+ *   own "Leave site?" prompt (`beforeunload`).
+ * - `confirmLeave()` is for in-app navigation: wire it to your router's
+ *   blocker (React Router `useBlocker`, TanStack Router `useBlocker`), or call
+ *   it before closing a dialog. See SKILL.md "Unsaved changes".
+ */
+declare function useUnsavedChangesGuard(options: UseUnsavedChangesGuardOptions): UseUnsavedChangesGuardReturn;
+
+export { DEFAULT_UNSAVED_CHANGES_MESSAGE, type UseUnsavedChangesGuardOptions, type UseUnsavedChangesGuardReturn, useUnsavedChangesGuard };

package/dist/hooks/use-unsaved-changes-guard.js

@@ -0,0 +1,3 @@
+export { DEFAULT_UNSAVED_CHANGES_MESSAGE, useUnsavedChangesGuard } from '../chunk-XQO4OH2N.js';
+//# sourceMappingURL=use-unsaved-changes-guard.js.map
+//# sourceMappingURL=use-unsaved-changes-guard.js.map

package/dist/hooks/use-unsaved-changes-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"use-unsaved-changes-guard.js"}

package/dist/index.d.ts

@@ -1,13 +1,17 @@
-export { A as ArrayFilter, a as AuditEntry, B as BaseRecord, b as BulkChange, c as BulkResult, C as CreateParams, d as CreateResult, D as DataProvider, e as DataRow, f as DeleteParams, g as DeleteResult, F as FieldPermissions, h as FieldReference, i as FieldSchema, j as FilterOperator, k as FilterParam, G as GetManyParams, l as GetManyResult, m as GetOneParams, n as GetOneResult, H as HistoryParams, I as Identifier, o as ImportParams, p as InvalidationKey, L as ListParams, q as ListResult, N as NullFilter, P as PaginationParam, r as ProviderCapabilities, R as RangeFilter, s as RecordComment, t as ResourceAccess, u as ResourceContract, v as ResourceRelation, w as ResourceSchema, x as ResourceSummary, y as RowAction, z as RowFailure, S as ScalarFilter, E as SortParam, J as StorageType, U as UpdateParams, K as UpdateResult, V as VersionField, W as WriteEvent } from './types-zILrlHuV.js';
-export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from './write-outcome-BE3Tk6bA.js';
-export { DataProviderRoot, DataProviderRootProps, GenesisProvider, GenesisProviderProps, MockProviderOptions, SupabaseClient, SupabaseClientInput, SupabaseProviderOptions, SupabaseResourceConfig, SupabaseWriteContext, createMockProvider, createSupabaseProvider, toDataWriteError, useDataProvider, useStorage, writeOutcomeFromCode } from './provider/index.js';
+export { A as ArrayFilter, B as BaseRecord, a as BulkChange, b as BulkResult, C as CreateParams, c as CreateResult, D as DataProvider, d as DeleteParams, e as DeleteResult, F as FilterParam, G as GetManyParams, f as GetManyResult, g as GetOneParams, h as GetOneResult, H as HistoryParams, I as Identifier, i as ImportParams, j as InvalidationKey, L as ListParams, k as ListResult, N as NullFilter, P as PaginationParam, R as RangeFilter, l as RowFailure, S as ScalarFilter, m as SortParam, U as UpdateParams, n as UpdateResult, W as WriteEvent } from './types-DDOmG9hj.js';
+export { D as DataReadError, a as DataReadErrorOptions, b as DataWriteError, c as DataWriteErrorOptions, R as ReadOutcome, W as WriteOutcome, i as isDataReadError, d as isDataWriteError, r as readFailureMessage } from './read-outcome-kgNhfuST.js';
+export { DataProviderRoot, DataProviderRootProps, GenesisProvider, GenesisProviderProps, MockProviderOptions, PostgrestFieldErrors, SupabaseClient, SupabaseClientInput, SupabaseProviderOptions, SupabaseResourceConfig, SupabaseWriteContext, createMockProvider, createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, useDataProvider, useStorage, writeOutcomeFromCode } from './provider/index.js';
 export { S as StorageAdapter } from './types-DKcxHXxq.js';
 export { createLocalStorageAdapter, createMemoryStorageAdapter, createNoopStorageAdapter } from './storage/index.js';
 export { UseResourceOptions, UseResourceReturn, useResource } from './hooks/use-resource.js';
 export { UseOneOptions, useOne } from './hooks/use-one.js';
+export { useCapabilities } from './hooks/use-capabilities.js';
 export { UseResourceFormOptions, UseResourceFormReturn, buildArrayItemDefaults, useResourceForm } from './hooks/use-resource-form.js';
 export { UseWizardReturn, WizardStep, useWizard } from './hooks/use-wizard.js';
+export { DEFAULT_UNDO_DELAY_MS, MutationMode, MutationModeOptions, UndoableWrite, pendingWriteCount } from './hooks/mutation-mode.js';
+export { DEFAULT_UNSAVED_CHANGES_MESSAGE, UseUnsavedChangesGuardOptions, UseUnsavedChangesGuardReturn, useUnsavedChangesGuard } from './hooks/use-unsaved-changes-guard.js';
 export { FieldType, ResourceFormFieldDef, SelectOption, FieldType as WidgetHint } from './form-types.js';
+export { A as AuditEntry, D as DataRow, F as FieldPermissions, a as FieldReference, b as FieldSchema, c as FilterOperator, P as ProviderCapabilities, R as RecordComment, d as ResourceAccess, e as ResourceContract, f as ResourceRelation, g as ResourceSchema, h as ResourceSummary, i as RowAction, S as StorageType, V as VersionField } from './types-5cuflvha.js';
 export { decodeRecordKey, encodeRecordKey, keyFields } from './schema/index.js';
 export { titleCase } from './utils.js';
 import 'react';

package/dist/index.js

@@ -1,15 +1,19 @@
-export { createSupabaseProvider, toDataWriteError, writeOutcomeFromCode } from './chunk-NW26Z3LZ.js';
+export { createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, writeOutcomeFromCode } from './chunk-E5VYFAQO.js';
 export { decodeRecordKey, encodeRecordKey, keyFields } from './chunk-KV2HW4G4.js';
-export { DataWriteError, isDataWriteError } from './chunk-6MBACQYA.js';
+export { DataReadError, isDataReadError, readFailureMessage } from './chunk-HUNGCTRA.js';
 import './chunk-XCX2TRBL.js';
 import './chunk-65SXNHWE.js';
-import './chunk-EL7YGOTY.js';
+import './chunk-HT43MPKW.js';
+export { buildArrayItemDefaults, useResourceForm } from './chunk-3JSFTLDV.js';
+export { useResource } from './chunk-6Q477CHB.js';
+export { DEFAULT_UNSAVED_CHANGES_MESSAGE, useUnsavedChangesGuard } from './chunk-XQO4OH2N.js';
 export { useWizard } from './chunk-7KOLYF27.js';
-export { buildArrayItemDefaults, useResourceForm } from './chunk-IHWWJUEN.js';
+export { DataWriteError, isDataWriteError } from './chunk-5NHR6ZXS.js';
 export { titleCase } from './chunk-RYEXWQFD.js';
-export { useOne } from './chunk-ZK5C3OOT.js';
-export { useResource } from './chunk-P4OIIRQS.js';
+export { DEFAULT_UNDO_DELAY_MS, pendingWriteCount } from './chunk-F3BE7NGM.js';
 import './chunk-7NUL32W7.js';
+export { useCapabilities } from './chunk-BQOJX67X.js';
+export { useOne } from './chunk-ZK5C3OOT.js';
 export { DataProviderRoot, GenesisProvider, createMockProvider, useDataProvider, useStorage } from './chunk-GGSXSI6Z.js';
 export { createLocalStorageAdapter, createMemoryStorageAdapter, createNoopStorageAdapter } from './chunk-ZYJUEJ4Z.js';
 //# sourceMappingURL=index.js.map