@danxbot/ui 7.4.2 → 7.5.0

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

@@ -25,6 +25,77 @@ 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>;
+    /** 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>;
+    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.
+ */
+export declare function trimOptimisticLayers(key: string, beforeLayerId: number, fields: readonly 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;
+/** 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 +125,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/dist/types/lib/values/email.d.ts

@@ -2,5 +2,11 @@
  * Whether `value` reads as a plausible email address. An empty (or
  * whitespace-only) value is treated as VALID — clearing the field is not a
  * typo, and a required-field rule belongs to the caller, not this check.
+ *
+ * SG-909 review fix: the previous regex (`/^[^\s@]+@[^\s@]+\.[^\s@]+$/`)
+ * matched the domain half non-specifically, so `"a@b..com"` (an empty label
+ * between two dots) passed, and it never looked at trailing punctuation at
+ * all, so `"jane@example.com."` and `"jane@example.com,"` — the shape a typo
+ * or a sentence's own full stop produces — both passed too.
  */
 export declare function isValidEmail(value: string): boolean;

package/dist/types/lib/values/phone.d.ts

@@ -6,6 +6,12 @@
  * rule `formatDate` documents. A stored value should already be `parsePhone`'s
  * output; if it is not, that is a data problem worth seeing in the row, not
  * a blank field that looks like nobody ever entered a number.
+ *
+ * Reuses `formatPhonePartial` for the ten-digit case (SG-909 review) rather
+ * than repeating the same three-slice punctuation a second time — passing it
+ * exactly ten digits always produces the identical `"(XXX) XXX-XXXX"` string,
+ * since `formatPhonePartial` only ever appends a raw, unformatted tail past
+ * the tenth digit and there is no tail here.
  */
 export declare function formatPhone(value: string | null | undefined): string;
 /**
@@ -19,22 +25,44 @@ export declare function formatPhone(value: string | null | undefined): string;
  * too many, or an 11-digit number NOT starting with `1` (a foreign number
  * mis-typed into a US field, not a US number with an extra digit) — returns
  * `null` rather than truncating or padding a guess into place.
+ *
+ * THIS is the one place in the file the 11-digit-leading-`1` rule is written
+ * (SG-909 review — it used to also live in `digitsOfPhoneInProgress`, which
+ * no longer transforms digits at all; see that function's own doc for why).
  */
 export declare function parsePhone(input: string): string | null;
 /**
- * Every non-digit stripped, an 11-digit leading US country code dropped (the
- * same rule `parsePhone` applies), and the rest capped at ten digits — the
- * normalised digit sequence `PhoneField` (SG-909) keeps as ITS state while a
- * person is still typing, before there are enough digits for `parsePhone` to
- * accept.
+ * Every non-digit stripped — nothing else. `PhoneField` (SG-909) keeps this
+ * as ITS state while a person is still typing.
+ *
+ * Deliberately NOT capped at ten and NOT country-code-aware, unlike an
+ * earlier revision of this function. That revision silently dropped every
+ * digit past the tenth and stripped a leading `"1"` off an 11-digit run —
+ * which meant pasting `"555-123-4567 x12"` or `"44 20 7946 0958"` (a UK
+ * number) landed at commit as `parsePhone` accepting whatever ten-or-eleven
+ * digits happened to survive the cap, saving a DIFFERENT phone number than
+ * the one actually typed, with no error and no visible sign anything had
+ * been thrown away. `PhoneField` now keeps the full digit sequence — see its
+ * own module comment for how it is FORMATTED (first ten punctuated, any rest
+ * appended raw) and how `parsePhone` alone decides, at commit, whether the
+ * full sequence resolves to a real ten-digit number.
  */
 export declare function digitsOfPhoneInProgress(input: string): string;
 /**
- * `digitsOfPhoneInProgress`'s output → what the box shows WHILE TYPING —
- * progressively punctuated as each digit lands, not only once ten are
- * present. `formatPhone` above is the too-late-to-use-here sibling: it takes
- * the STORED ten-digit form and either renders it or hands back a non-ten-
- * digit value unchanged, which would show a partial number completely
- * unpunctuated until the last digit arrived.
+ * A digit sequence of any length → what the box shows WHILE TYPING —
+ * progressively punctuated as each of the first ten digits lands, with any
+ * digit past the tenth appended after a space, UNFORMATTED, rather than
+ * silently dropped (SG-909 review). `formatPhone` above is the too-late-to-
+ * use-here sibling: it takes the STORED ten-digit form and either renders it
+ * or hands back a non-ten-digit value unchanged, which would show a partial
+ * number completely unpunctuated until the last digit arrived, and would
+ * have nowhere to put an eleventh digit at all.
+ *
+ * The trailing digits past ten are shown, not hidden, specifically so a
+ * too-long paste or a stray extra keystroke stays visible for the person to
+ * see and correct — `parsePhone` will refuse anything that is not exactly
+ * ten digits (or eleven with a leading `1`) at commit, and a refusal against
+ * a box that visibly still has extra digits in it is legible; a refusal
+ * against a box that silently ate them is not.
  */
 export declare function formatPhonePartial(digits: string): string;

package/package.json

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