@danxbot/ui 3.6.1 → 3.8.0

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

@@ -0,0 +1,188 @@
+/**
+ * A payload as it arrives off the wire — from a fetch response, from a
+ * mutation's returned item, or from a broadcast.
+ *
+ * DELIBERATELY LOOSE. The store requires exactly two things of it (`__type`
+ * and `id`) and interprets five more (`__timestamp`, `__deleted_at`,
+ * `deleted_at`, `__stale`, `__model`). Everything else is data it carries
+ * without understanding — which is the whole of this module's claim to being
+ * domain-agnostic.
+ */
+export interface RecordPayload {
+    readonly [field: string]: unknown;
+}
+/**
+ * How a payload arrived. NOT telemetry — each value changes real behaviour:
+ *
+ * - `"fetch"` may SATISFY a field-set tag and CLEARS staleness on every field
+ *   it carries. A broadcast can never do either, because a broadcast is
+ *   partial by whitelist and can never complete a record.
+ * - `"broadcast"` is the only source that MARKS a field stale, using the
+ *   `staleFields` its type declared. Saying so out loud prevents the obvious
+ *   wrong reading, in which a fetch that omits a stale-declared field re-marks
+ *   it and the refetch loop never settles.
+ *
+ * A mutation's returned item is a `"fetch"`: it is a full server answer to a
+ * request this client made, so it may satisfy a tag.
+ */
+export type WriteSource = "fetch" | "broadcast";
+/** Options every write carries. */
+export interface WriteOptions {
+    readonly source: WriteSource;
+    /**
+     * The tenant the REQUEST was issued under — stamped by the caller at request
+     * time, never read from module state inside `write`.
+     *
+     * Reading it inside `write` would read the tenant as it is NOW, which is
+     * precisely the bug this parameter exists to prevent: a team-A response that
+     * resolves after a switch to team B would write team A's records into a
+     * store now being read as team B's. A broadcast is stamped with the tenant
+     * whose channel delivered it, which the subscription already knows. So both
+     * sources carry it and neither infers it.
+     */
+    readonly tenant?: string | number;
+    /**
+     * An OPAQUE field-set name — `"card"`, `"detail"`, whatever the caller's own
+     * api layer already calls the selector it asked for. The store never
+     * interprets it; it records which tags a key has satisfied and compares them
+     * for equality, so the library still knows nothing about any type's fields.
+     *
+     * Only a `"fetch"` may satisfy a tag. It is what makes `useRecord(…,
+     * {needs:"card"})` report `unknown` for a record seeded only by a broadcast,
+     * rather than handing a projection function a record with no `files` and no
+     * `workflow_runs` — which renders a confident "0 documents" card for a
+     * 434-page demand.
+     */
+    readonly tag?: string;
+}
+/**
+ * What a write did. Every value is observable so a refusal leaves a trace: the
+ * prior art in this codebase records nothing at all on rejection, which is why
+ * its out-of-order guard was inert for years without anyone noticing.
+ *
+ * - `applied` — accepted, and something a reader can observe changed.
+ * - `unchanged` — accepted, and nothing changed. NOBODY IS NOTIFIED. A
+ *   redelivered duplicate must not invalidate every hydration memo that
+ *   touched the key and re-render every subscriber.
+ * - `dropped-older` — strictly older than the record's own stored timestamp.
+ * - `dropped-tenant` — stamped for a tenant this store is no longer serving.
+ * - `rejected-shape` — not a record at all: no `__type`, no `id`, or a
+ *   `{__stale:true}` ping, which carries neither.
+ */
+export type WriteVerdict = "applied" | "unchanged" | "dropped-older" | "dropped-tenant" | "rejected-shape";
+/** The result of one `write`. */
+export interface WriteResult {
+    readonly verdict: WriteVerdict;
+    /**
+     * Every key this write touched, INCLUDING nested ones — a demand payload
+     * carrying 434 files returns 435 keys.
+     *
+     * The caller that issued a refetch to clear a staleness signal needs this to
+     * decide whether the write it just made actually satisfied what it was
+     * issued for. Empty for every dropped or rejected verdict.
+     */
+    readonly keys: readonly string[];
+    /** Why, for the verdicts that are refusals. Present only when it helps. */
+    readonly reason?: string;
+}
+/** The result of one `writeAll`. */
+export interface WriteAllResult {
+    /** One entry per payload, in the order they were given. */
+    readonly results: readonly WriteResult[];
+    /** The union of every payload's touched keys, de-duplicated. */
+    readonly keys: readonly string[];
+}
+/**
+ * What a reader is told about one key.
+ *
+ * FOUR ABSENCES, NOT ONE. Never-fetched, deleted and broadcast-partial are
+ * different answers and a screen renders each of them differently. The fourth —
+ * a 404 — is deliberately NOT a member: a refusal carries a message and a
+ * remedy that the store has no way to build, so it belongs to whatever layer
+ * performed the request.
+ *
+ * `stale` is part of the state rather than a side channel because a write that
+ * changes no value but marks a field stale must still notify — and notifying
+ * for something no reader can observe is worse than not notifying at all.
+ */
+export type RecordState<T> = {
+    readonly status: "unknown";
+} | {
+    readonly status: "present";
+    readonly record: T;
+    /** Bumps on every accepted write that changed something observable. */
+    readonly version: number;
+    /**
+     * Fields the last broadcast could not carry. Sorted, so two structurally
+     * equal stale sets compare equal.
+     *
+     * A held stale value can only be stale-LOW for a monotonic high-water
+     * mark, never stale-high, so holding the last number on screen while the
+     * refetch lands is honest. Dimming it is available, not mandatory.
+     */
+    readonly stale: readonly string[];
+} | {
+    readonly status: "deleted";
+    readonly at: string;
+};
+/** What `useRecord`/`useRecords` require of their caller. */
+export interface ReadOptions {
+    /**
+     * REQUIRED, not optional. The tag a `"fetch"` must have satisfied before
+     * this key reports `present`.
+     *
+     * The tag mechanism existed once as an optional parameter and nothing forced
+     * a caller to use it, which reopened the exact hole it was introduced to
+     * close. One word in the signature is the whole fix.
+     */
+    readonly needs: string;
+}
+/**
+ * A registered record type: the runtime string and the compile-time type, so
+ * the two can never drift.
+ *
+ * `_record` is a phantom — it carries `T` through inference and holds no value
+ * at runtime.
+ */
+export interface RecordTypeToken<T> {
+    /** The NORMALIZED model name. Never carries a `Resource` suffix. */
+    readonly type: string;
+    /** @see RecordTypeOptions.staleFields */
+    readonly staleFields: readonly string[] | "*";
+    /** Phantom. Never read. */
+    readonly _record?: T;
+}
+/** What a type may declare at registration. */
+export interface RecordTypeOptions {
+    /**
+     * The fields this type's BROADCAST cannot carry — because they are computed,
+     * or deliberately withheld from the whitelist. Everything else in a
+     * broadcast merges normally.
+     *
+     * Staleness is PER FIELD and never a whole-type on/off switch. A per-type
+     * binary discards the twelve real fields a broadcast does carry in order to
+     * signal the two it does not.
+     *
+     * `"*"` means every data field — the case where a type's broadcast carries
+     * identity and nothing else, and where the field set is not knowable at
+     * registration because it is a bag of dynamic attributes. It resolves at
+     * write time against the keys the record actually holds; see
+     * `resolveStaleFields` in `store.ts` for what that buys and what it costs.
+     */
+    readonly staleFields?: readonly string[] | "*";
+}
+/**
+ * One root affected by a staleness mark, and the fields under it that are now
+ * suspect.
+ *
+ * `key` is a ROOT, not the key that went stale. For a queue, the key that goes
+ * stale is a run while the list holds demands; naming the raw key would match
+ * no list slot and nothing would ever refetch. Roots are resolved through the
+ * hydration memo's deps map, which is safe in a way a maintained reverse index
+ * is not: it is rebuilt by the same walk that reads it, so there is no separate
+ * maintenance step to get wrong.
+ */
+export interface StalenessEntry {
+    readonly key: string;
+    readonly fields: readonly string[];
+}

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

@@ -0,0 +1,96 @@
+import type { RecordPayload } from "./types";
+/** A relation, once normalized: a pointer to another record's key. */
+export interface RecordRef {
+    readonly __ref: string;
+}
+export declare function isRecordRef(value: unknown): value is RecordRef;
+/**
+ * Strip a trailing `Resource` so a delete and the record it deletes land on
+ * the same key.
+ *
+ * CREATED AND DELETED PAYLOADS DISAGREE ABOUT `__type`, verified in the
+ * backend twice: created/updated take it from a resource class name that no
+ * resource overrides, so it keeps the suffix (`"WorkflowRunResource"`), while
+ * deletes take it from a helper that strips the suffix (`"WorkflowRun"`).
+ *
+ * A store keyed on the raw string files a delete under a different key than
+ * the record it is deleting, so the tombstone never lands and the row stays on
+ * screen forever. One line, and without it a whole class of update silently
+ * does nothing.
+ */
+export declare function normalizeTypeName(raw: string): string;
+/**
+ * `Type:id`, with the id COERCED TO A STRING.
+ *
+ * Ids are not uniformly numeric — a file's id is a UUID while a run's is an
+ * integer — and a Map keyed on the raw value would file `7` and `"7"`
+ * separately. There is deliberately NO `id || name` fallback: that is a quirk
+ * of one prior implementation, not part of any contract, and a record keyed on
+ * a name silently merges two different rows the day two of them share one.
+ */
+export declare function recordKey(type: string, id: string | number): string;
+/** The identity a payload carries, or `undefined` if it is not a record. */
+export interface PayloadIdentity {
+    readonly key: string;
+    readonly type: string;
+    readonly id: string;
+}
+export declare function payloadIdentity(payload: RecordPayload): PayloadIdentity | undefined;
+/**
+ * A `{__stale:true, id, __model}` ping: an invalidation the backend sends
+ * under the normal event name with NO `__type` at all.
+ *
+ * Recognised by name and dropped, because keying it would need a type it does
+ * not have — and guessing one from `__model` (a PHP class name) is exactly the
+ * sort of inference that produces a store full of records nothing reads.
+ */
+export declare function isStalePing(payload: RecordPayload): boolean;
+/**
+ * The tombstone marker, or `undefined`.
+ *
+ * BOTH SPELLINGS, deliberately. A `deleted` event carries `deleted_at`; a
+ * soft-delete arriving as an `updated` event carries `__deleted_at`. The prior
+ * art in this codebase checks only the second, so its delete handling has never
+ * run once — the payload says `deleted_at` and the store asks for
+ * `__deleted_at`.
+ */
+export declare function tombstoneAt(payload: RecordPayload): string | undefined;
+/**
+ * True when the payload says, in so many words, that the record is NOT
+ * deleted — which is what un-deletes a tombstoned record.
+ *
+ * Needed because absent keeps the previous value: without this, a record that
+ * was tombstoned could never come back, even when the server says it has.
+ */
+export declare function explicitlyUndeleted(payload: RecordPayload): boolean;
+/**
+ * Normalize `__timestamp` to milliseconds.
+ *
+ * IT ARRIVES IN TWO UNITS, 1000x APART, and this is verified rather than
+ * theoretical: the backend reads the model's `updated_at` in MILLISECONDS when
+ * the model has that column, and falls back to a SECONDS-resolution wall clock
+ * when it does not. At least one real model has no `updated_at` column at all.
+ *
+ * A comparison across the two units is not merely wrong, it is CONSISTENTLY
+ * wrong in one direction: a seconds value is ~1000x smaller, so it always
+ * loses to a milliseconds value and such a record would never update again.
+ *
+ * An implausible magnitude — below either window — is a contract violation,
+ * and it is surfaced rather than coerced. It returns `undefined`, which means
+ * "cannot adjudicate": the write is still ACCEPTED (a bogus tiny number must
+ * not be allowed to make a record permanently un-writable), it just cannot
+ * refuse anything.
+ */
+export declare function normalizeTimestamp(raw: unknown): number | undefined;
+/**
+ * Keys the store INTERPRETS rather than stores.
+ *
+ * Everything `__`-prefixed is envelope by this wire format's own convention,
+ * and two of them would actively break the store if kept as data:
+ * `__broadcasted_at` moves on every delivery, so storing it would make an
+ * identical redelivered payload look like a change and re-render the world —
+ * which is the exact cost the notify-only-if-changed rule exists to avoid.
+ *
+ * `deleted_at` is here because it is the tombstone marker, not a field.
+ */
+export declare function isEnvelopeKey(key: string): boolean;

package/dist/types/lib/use-fill-height.d.ts

@@ -0,0 +1,26 @@
+import { type RefCallback } from "react";
+/**
+ * Size an element to the space between its own top and the bottom of the box
+ * that scrolls it, and keep it sized as the page changes around it.
+ *
+ * Returns a ref callback for the element. The height is written as inline style
+ * rather than returned as state on purpose — a returned number would re-render
+ * the subtree on every resize frame, and the value is only ever consumed by one
+ * property on one element.
+ *
+ * ```tsx
+ * const fillRef = useFillHeight(fill);
+ * <div ref={fillRef} className="max-h-full …" />
+ * ```
+ *
+ * WHAT IT WATCHES, and why that list rather than a global observer. The number
+ * changes when a box ABOVE the element changes size: the scrollport itself, an
+ * ancestor between the two, or a sibling laid out before it. All three are
+ * observed. The element itself is deliberately NOT observed — it is the thing
+ * being written, and observing it is the loop.
+ *
+ * A sibling ADDED after mount is the known gap: the observer set is built once
+ * per attach. In practice the content above a filling element is a page header,
+ * not a live list, and a `key`ed remount covers the rest.
+ */
+export declare function useFillHeight(enabled?: boolean): RefCallback<HTMLElement>;

package/package.json

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