@danxbot/ui 7.4.3 → 7.6.0

package/dist/types/index.d.ts

@@ -125,4 +125,4 @@ export { createSimStore, resetSimStores, useSimSettings, setSimSettings, getNetw
 export { NodeCanvas, LAYOUT_DEFAULTS, layoutTree, pathToNode, type NodeCanvasProps, type CanvasEdge, type CanvasLayout, type CanvasNode, type CanvasOrientation, type LayoutOptions, type NodeRenderContext, type NodeRenderer, type PlacedNode, } from "./components/node-canvas";
 export { defineRecordType, resetRecordTypes, useRecord, useRecords, useStaleness, write, writeAll, peekRecord, readState, readStaleness, subscribeToKey, subscribeToStaleness, retainKeys, sweepRecords, setRecordStoreTenant, getRecordStoreTenant, flushRecordNotifications, resetRecordStore, recordStoreStats, UNKNOWN_STATE, normalizeTypeName, normalizeTimestamp, recordKey, isRecordRef, type RecordRef, type ReadOptions, type RecordPayload, type RecordState, type RecordTypeOptions, type RecordTypeToken, type StalenessEntry, type WriteAllResult, type WriteOptions, type WriteResult, type WriteSource, type WriteVerdict, } from "./lib/records";
 export { RealtimeProvider, useRealtime, useRealtimeEpoch, useRealtimeHealth, useRealtimeRegistry, SubscriptionRegistry, normalizeScope, scopeKey, subscriptionKey, readRealtimeEpoch, subscribeToRealtimeEpoch, subscribeToRealtimeEvents, resetRealtimeSignals, type RealtimeChannel, type RealtimeConnectionState, type RealtimeDiagnostic, type RealtimeEvent, type RealtimeHealth, type RealtimeProviderProps, type RealtimeScope, type RealtimeScopeInput, type RealtimeStatus, type RealtimeTransport, type RegistryOptions, type SubscriptionHealth, type SubscriptionLease, type SubscriptionRequest, } from "./lib/realtime";
-export { useRecordRead, useRecordListRead, useRecordStoreSweep, applyMutationResult, acquireSlot, appendCreated, emptySlotSnapshot, readSlot, resetSlots, slotKeys, subscribeToSlot, writeSlot, RefetchRunner, registerActiveRead, resetActiveReads, type ActiveRead, type ListFetch, type ListFetchResult, type ListReadOptions, type ListReadResult, type ReadError, type RecordFetch, type RecordReadOptions, type RecordReadResult, type RunnerOptions, type SlotSnapshot, } from "./lib/reads";
+export { useRecordRead, useRecordListRead, useRecordStoreSweep, applyMutationResult, optimisticWrite, beginOptimisticWrite, resetOptimisticWrites, type OptimisticHandle, type OptimisticWriteOptions, type OptimisticWriteSpec, type SlotDescriptor, acquireSlot, appendCreated, emptySlotSnapshot, readSlot, resetSlots, slotKeys, subscribeToSlot, writeSlot, RefetchRunner, registerActiveRead, resetActiveReads, type ActiveRead, type ListFetch, type ListFetchResult, type ListReadOptions, type ListReadResult, type ReadError, type RecordFetch, type RecordReadOptions, type RecordReadResult, type RunnerOptions, type SlotSnapshot, } from "./lib/reads";

package/dist/types/lib/reads/index.d.ts

@@ -1,4 +1,5 @@
 export { useRecordRead, useRecordListRead, applyMutationResult, useRecordStoreSweep } from "./hooks";
-export { acquireSlot, appendCreated, emptySlotSnapshot, readSlot, resetSlots, slotKeys, subscribeToSlot, writeSlot, type SlotSnapshot, } from "./slots";
+export { acquireSlot, appendCreated, emptySlotSnapshot, readSlot, resetSlots, slotKeys, subscribeToSlot, writeSlot, type SlotDescriptor, type SlotSnapshot, } from "./slots";
+export { optimisticWrite, beginOptimisticWrite, resetOptimisticWrites, type OptimisticHandle, type OptimisticWriteOptions, type OptimisticWriteSpec, } from "./optimistic";
 export { RefetchRunner, registerActiveRead, resetActiveReads, type ActiveRead, type RunnerOptions } from "./refetch";
 export type { ListFetch, ListFetchResult, ListReadOptions, ListReadResult, ReadError, RecordFetch, RecordReadOptions, RecordReadResult, } from "./types";

package/dist/types/lib/reads/optimistic.d.ts

@@ -0,0 +1,87 @@
+import { type RecordTypeToken } from "../records";
+import { type SlotDescriptor } from "./slots";
+/** Which records to change, and how. */
+export type OptimisticWriteSpec<T> = {
+    readonly kind: "update";
+    readonly type: RecordTypeToken<T>;
+    readonly id: string | number;
+    /** Only the fields that change. A present `null` clears; an `undefined` value is ignored. */
+    readonly patch: Partial<T>;
+    readonly at?: undefined;
+} | {
+    readonly kind: "update";
+    readonly type: RecordTypeToken<T>;
+    readonly id: string | number;
+    /**
+     * A field holding a keyed map (`data_points`, `attributes`): `patch` then names KEYS OF
+     * THAT MAP, merged over whatever it holds. Use it whenever a write changes one entry of a
+     * map — patching the whole field instead would pin every other entry at its value as of
+     * the click, and undoing one of two concurrent writes would undo both.
+     */
+    readonly at: Extract<keyof T, string>;
+    readonly patch: Readonly<Record<string, unknown>>;
+} | {
+    readonly kind: "create";
+    readonly type: RecordTypeToken<T>;
+    /** The record as the reader will see it until the server answers. Its `id` is assigned. */
+    readonly fields: Partial<T>;
+    /**
+     * Which live list reads show the pending row. Default: every list of this record type —
+     * the library cannot evaluate a server-side filter, so narrow it when a list is filtered.
+     */
+    readonly lists?: (slot: SlotDescriptor) => boolean;
+    /** Above the fetched page (default) or below it. */
+    readonly position?: "start" | "end";
+} | {
+    readonly kind: "delete";
+    readonly type: RecordTypeToken<T>;
+    readonly id: string | number;
+};
+export interface OptimisticWriteOptions<A = unknown> {
+    /**
+     * The field-set tag the server's answer satisfies, as `applyMutationResult` takes it. A
+     * create's answer ALSO satisfies the tag of every list it was shown in, or the real row would
+     * be held but not rendered the moment it replaced the pending one.
+     */
+    readonly tag?: string;
+    /** The tenant the request is issued under. Captured now, never when the answer lands. */
+    readonly tenant?: string | number;
+    /**
+     * Pick the record out of the request's result, when the result is an envelope rather than the
+     * record itself. Default: the result, if it carries `__type` and `id`.
+     */
+    readonly answer?: (result: A) => unknown;
+    /**
+     * The request stores its own answer — an API layer that writes every response into the store,
+     * or a caller that normalizes the answer before storing it. Commit then only retires the belief:
+     * nothing is written, so the stored answer is exactly what shows.
+     */
+    readonly answerStored?: boolean;
+}
+/** An applied write whose request the caller runs itself — `beginOptimisticWrite`'s handle. */
+export interface OptimisticHandle {
+    /** The record's id — for a create, the temporary one the pending row carries. */
+    readonly id: string | number;
+    /** `Type:id`, as the store keys it. */
+    readonly key: string;
+    /** The request succeeded. `answer` is the server's record, if it sent one. Idempotent. */
+    commit(answer?: unknown): void;
+    /** The request failed: put back exactly what was there before. Idempotent. */
+    rollback(): void;
+}
+/**
+ * Apply an optimistic write and run its request.
+ *
+ * Applies synchronously — before `request` is even called — so the reader sees the change in
+ * the same tick as their click, hidden page or not. On success the server's answer replaces the
+ * belief and the request's own result is returned untouched. On failure the belief is removed
+ * and the error is rethrown for the caller's refusal handling.
+ */
+export declare function optimisticWrite<T, A>(spec: OptimisticWriteSpec<T>, request: () => Promise<A>, options?: OptimisticWriteOptions<A>): Promise<A>;
+/**
+ * The same write, for a caller that owns its request lifecycle — apply now, and call `commit`
+ * or `rollback` on the handle when the request settles.
+ */
+export declare function beginOptimisticWrite<T>(spec: OptimisticWriteSpec<T>, options?: Pick<OptimisticWriteOptions, "tag" | "tenant" | "answerStored">): OptimisticHandle;
+/** Test seam. Nothing in the library calls this. */
+export declare function resetOptimisticWrites(): void;

package/dist/types/lib/reads/slots.d.ts

@@ -46,6 +46,36 @@ export declare function slotPendingKeys(id: string): readonly string[];
  * AND ONLY WHERE IT BELONGS — see `belongsTo`.
  */
 export declare function appendCreated(event: RealtimeEvent): void;
+/** What a create's `lists` predicate is shown about each live slot. */
+export interface SlotDescriptor {
+    /** The list read's own `key`. */
+    readonly id: string;
+    readonly type: string;
+    readonly tag: string;
+}
+/**
+ * Show an optimistic create in every slot that should list it, before the server has answered.
+ *
+ * AN OPTIMISTIC CREATE IS NOT A `created` EVENT, and it does not go into `pending`. `pending` is
+ * the server telling a list "this entered your set, position unknown" and a screen may render it
+ * as a "1 new" affordance; a create is the reader's OWN action, shown inline as a row the moment
+ * it is made. It sits beside the fetched page — above it by default, where a new row is looked
+ * for — in its own list, so a fetch landing while the create is in flight rewrites the page and
+ * leaves the pending row standing.
+ *
+ * WHICH SLOTS is the caller's to say when it can: the library cannot evaluate a server-side
+ * filter, so the default is every live slot of the record's type, and `lists` narrows it.
+ *
+ * @returns the slots the key joined — their tags are what the server's answer must satisfy for
+ *   the real row to render in them.
+ */
+export declare function addOptimisticMember(key: string, type: string, lists: ((slot: SlotDescriptor) => boolean) | undefined, position: "start" | "end"): SlotDescriptor[];
+/**
+ * An optimistic create has settled. With `realKey` (the server answered), the real row takes
+ * the pending row's place — in the fetched page, so it stays put until the server next orders
+ * the list. With `null` (the create failed), the pending row simply goes.
+ */
+export declare function settleOptimisticMember(tempKey: string, realKey: string | null): void;
 export declare function subscribeToSlot(id: string, listener: () => void): () => void;
 /** The keys a slot holds right now — the roots a targeted refetch matches on. */
 export declare function slotKeys(id: string): readonly string[];

package/dist/types/lib/records/store.d.ts

@@ -25,6 +25,95 @@ export declare function write(payload: RecordPayload, options: WriteOptions): Wr
  * in one call coalesces into a single notification.
  */
 export declare function writeAll(payloads: readonly RecordPayload[], options: WriteOptions): WriteAllResult;
+/**
+ * One optimistic write, held ON TOP of a record's base rather than merged into it.
+ *
+ * ==== WHY A LAYER AND NOT A WRITE ====
+ *
+ * The first optimistic writes built on this store merged the belief into the base with a
+ * client-invented `__timestamp`, and each one then had to work around what that did:
+ *
+ *   - the rollback had to be stamped NEWER than the belief, or the out-of-order guard dropped
+ *     it — and a same-millisecond apply-then-revert is not newer, so a local monotonic clock
+ *     was needed to get it through;
+ *   - once a client timestamp was stored, the SERVER's own later answer could lose to it, since
+ *     a browser clock and a database column are not the same clock;
+ *   - the rollback snapshot came from a read, which strips the envelope, so `__type` had to be
+ *     patched back in before the store would take it.
+ *
+ * A layer has none of those problems by construction. The base — the only thing the ordering
+ * guard adjudicates — is never touched by the belief, so the belief can never outrank a server
+ * answer and removing it is a removal, not a write that has to win anything.
+ *
+ * ==== ORDER ====
+ *
+ * Layers apply oldest first, so the newest belief about a field is the one a reader sees — a
+ * set, clear, set, clear on one field shows the last clear the moment it is made, whatever
+ * order the four answers come back in. Removing a layer from the middle leaves every later one
+ * standing: undoing write 2 of 4 does not undo 3 and 4.
+ */
+export interface OptimisticLayer {
+    /** Global and strictly increasing — also the issue order of the writes that made them. */
+    readonly id: number;
+    /** Data fields, stored as given — never normalized, so a patch cannot mint records. */
+    fields: Record<string, unknown>;
+    /**
+     * When set, `fields` are KEYS OF THE MAP held in this one field (a record's `data_points`,
+     * say), merged over whatever that map holds beneath — never a replacement of the whole field.
+     * Two beliefs about two different keys of one map then stay independent: undoing one leaves the
+     * other standing, and a read that rewrites the map underneath still shows through every key no
+     * belief is about.
+     */
+    readonly at: string | undefined;
+    /** An ISO time when this layer is a delete. */
+    readonly tombstone: string | undefined;
+    /** True when this layer IS the record — an optimistic create with no server row yet. */
+    readonly created: boolean;
+}
+/**
+ * Put an optimistic layer on top of `Type:id`, creating a base-less record for a create.
+ *
+ * Notification is QUEUED here, like every other store change; the optimistic-write primitive
+ * flushes synchronously afterwards, because a user-initiated write must never wait on an
+ * animation frame (a hidden page never gets one).
+ *
+ * @returns the layer id, for `removeOptimisticLayer` / `trimOptimisticLayers`
+ */
+export declare function pushOptimisticLayer(type: string, id: string | number, layer: {
+    fields?: Record<string, unknown>;
+    at?: string;
+    tombstone?: string;
+    created?: boolean;
+}): number;
+/**
+ * Take one layer off. A record that only ever existed as an optimistic create disappears with
+ * its last layer — it reads `unknown` again, exactly as before the create.
+ */
+export declare function removeOptimisticLayer(key: string, layerId: number): void;
+/**
+ * A later write's answer has landed: every OLDER layer's belief about the same fields is
+ * superseded, whether or not that older request has answered yet. A layer left with nothing to
+ * say is dropped. Without this, a set whose answer is still out would keep overlaying a field
+ * the server has already confirmed was cleared after it.
+ *
+ * `at` scopes the trim to beliefs about keys of that one map field — the same granularity the
+ * committing write had.
+ */
+export declare function trimOptimisticLayers(key: string, beforeLayerId: number, fields: readonly string[], at?: string): void;
+/**
+ * Whether the BASE is tombstoned — what a list slot prunes on. An optimistic delete hides the
+ * row from every read but must not cost the slot its key, or a rollback would bring the record
+ * back with no list left holding it.
+ */
+export declare function isBaseTombstoned(key: string): boolean;
+/**
+ * One field of the BASE, as stored (normalized: a nested record is a `{__ref}`). What a keyed
+ * belief is folded into when its write succeeds without an answer to replace it — writing it back
+ * through `write()` round-trips the refs untouched.
+ */
+export declare function readBaseField(key: string, field: string): unknown;
+/** Does `key` carry any optimistic layer right now? */
+export declare function hasOptimisticLayers(key: string): boolean;
 /**
  * The `unknown` state, as ONE module-level frozen constant.
  *
@@ -54,7 +143,9 @@ export declare function peekRecord(type: string, id: string | number, needs: str
  *
  * Exported so a caller that must observe the effect of a write synchronously —
  * a test, or a measurement taken immediately after a write — can flush rather
- * than wait for a frame.
+ * than wait for a frame. The optimistic write (`reads/optimistic.ts`) flushes
+ * after every step: a reader's own action is one change, not a burst, and it
+ * must reach the screen in the same tick even on a page that gets no frames.
  */
 export declare function flushRecordNotifications(): void;
 export declare function subscribeToKey(key: string, listener: () => void): () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danxbot/ui",
-  "version": "7.4.3",
+  "version": "7.6.0",
   "type": "module",
   "description": "Danxbot — a domain-agnostic React design system with motion as a first-class primitive.",
   "license": "MIT",