@geniee-inc/sfa-kit 1.18.0 → 1.19.2

package/src/lib/bundle/request-signature.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Whether `value` has the shape Keystone gives `content_hash` and `signature`.
+ *
+ * NOTE: shared with the builder's previous-build check, so the shape the
+ * signer accepts and the shape a rebuild recognises cannot drift apart.
+ */
+export declare function isHexDigest(value: unknown): value is string;
 /**
  * @description Asks Keystone to sign a bundle, returning the signature.
  *
@@ -6,6 +13,11 @@
  * per project while the key must be identical across all of them (SFAJAI-186).
  * The caller computes `contentHash` locally and Keystone signs it.
  *
+ * Without `studioVersion`, Keystone signs `contentHash` alone. With it, Keystone
+ * returns the legacy signature over `"{studio_version}:{content_hash}"`, and the
+ * caller must write the same `studio_version` into the manifest for it to
+ * verify.
+ *
  * NOTE: every failure throws. An unsigned bundle uploads successfully while
  * Keystone's verifier runs in `disabled` mode, so returning "no signature" here
  * would produce an artifact that looks fine and starts being rejected the day
@@ -17,6 +29,6 @@
 export declare function requestSignature({ apiBase, accessToken, studioVersion, contentHash, }: {
     readonly apiBase: string;
     readonly accessToken: string;
-    readonly studioVersion: string;
+    readonly studioVersion?: string;
     readonly contentHash: string;
 }): Promise<string>;

package/src/lib/bundle/request-signature.js

@@ -6,6 +6,15 @@ import { __awaiter } from "tslib";
 const HEX_DIGEST_PATTERN = /^[0-9a-f]{64}$/;
 /** Matches the timeout the documented Python flow uses for the same call. */
 const SIGN_TIMEOUT_MS = 30000;
+/**
+ * Whether `value` has the shape Keystone gives `content_hash` and `signature`.
+ *
+ * NOTE: shared with the builder's previous-build check, so the shape the
+ * signer accepts and the shape a rebuild recognises cannot drift apart.
+ */
+export function isHexDigest(value) {
+    return typeof value === 'string' && HEX_DIGEST_PATTERN.test(value);
+}
 /**
  * @description Asks Keystone to sign a bundle, returning the signature.
  *
@@ -14,6 +23,11 @@ const SIGN_TIMEOUT_MS = 30000;
  * per project while the key must be identical across all of them (SFAJAI-186).
  * The caller computes `contentHash` locally and Keystone signs it.
  *
+ * Without `studioVersion`, Keystone signs `contentHash` alone. With it, Keystone
+ * returns the legacy signature over `"{studio_version}:{content_hash}"`, and the
+ * caller must write the same `studio_version` into the manifest for it to
+ * verify.
+ *
  * NOTE: every failure throws. An unsigned bundle uploads successfully while
  * Keystone's verifier runs in `disabled` mode, so returning "no signature" here
  * would produce an artifact that looks fine and starts being rejected the day
@@ -24,7 +38,7 @@ const SIGN_TIMEOUT_MS = 30000;
  */
 export function requestSignature(_a) {
     return __awaiter(this, arguments, void 0, function* ({ apiBase, accessToken, studioVersion, contentHash, }) {
-        if (!HEX_DIGEST_PATTERN.test(contentHash)) {
+        if (!isHexDigest(contentHash)) {
             throw new Error(`content_hash must be a 64-character hex digest, got ${JSON.stringify(contentHash)}`);
         }
         // 末尾のスラッシュを落とす。付いたままだと //v1/pages/sign になり、多くの
@@ -44,10 +58,11 @@ export function requestSignature(_a) {
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${accessToken}`,
             },
-            body: JSON.stringify({
-                studio_version: studioVersion,
-                content_hash: contentHash,
-            }),
+            // NOTE: the field is left out, not sent empty. Keystone picks the format
+            // by whether studio_version is present, as it does for the manifest.
+            body: JSON.stringify(studioVersion == null
+                ? { content_hash: contentHash }
+                : { studio_version: studioVersion, content_hash: contentHash }),
         })
             .catch((thrown) => {
             throw new Error(`POST ${url} could not be reached ` +
@@ -72,7 +87,7 @@ export function requestSignature(_a) {
         // error page echoed into this field would otherwise be written into
         // manifest.json, upload fine while the verifier is `disabled`, and fail only
         // once it is switched to `enforced`.
-        if (!HEX_DIGEST_PATTERN.test(payload.signature)) {
+        if (!isHexDigest(payload.signature)) {
             throw new Error(`POST ${url} returned ${JSON.stringify(payload.signature)}, which is ` +
                 'not an HMAC-SHA-256 hex digest. The bundle was not signed.');
         }

package/src/lib/components/FieldRenderer.d.ts

@@ -5,7 +5,8 @@ interface FieldRendererProps {
 }
 /**
  * @description Renders a single field value based on its normalized kind.
- * Uses `label` for display (pre-formatted by the API), falls back to `value`.
+ * Uses `label` for display (pre-formatted by the API), falls back to a plain
+ * readable `value` — never a code or an id.
  */
 export declare function FieldRenderer({ fieldValue, fieldName }: FieldRendererProps): JSX.Element;
 export {};

package/src/lib/components/FieldRenderer.js

@@ -1,36 +1,28 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { toFieldDisplayText } from './fieldDisplayText';
 /**
  * @description Renders a single field value based on its normalized kind.
- * Uses `label` for display (pre-formatted by the API), falls back to `value`.
+ * Uses `label` for display (pre-formatted by the API), falls back to a plain
+ * readable `value` — never a code or an id.
  */
 export function FieldRenderer({ fieldValue, fieldName }) {
-    var _a;
-    const display = (_a = fieldValue.label) !== null && _a !== void 0 ? _a : formatFallback(fieldValue);
+    const display = toFieldDisplayText(fieldValue);
+    // NOTE: every branch carries `data-field`, so a page can find a field by name
+    // whatever its value looks like — empty, multi-line or a link
     if (display == null || display === '') {
-        return _jsx("span", { style: styles.empty, children: "\u2014" });
+        return (_jsx("span", { "data-field": fieldName, style: styles.empty, children: "\u2014" }));
     }
     if (fieldValue.kind === 'text' && typeof fieldValue.value === 'string') {
         if (isMultiline(fieldValue.value)) {
-            return _jsx("span", { style: styles.preWrap, children: display });
+            return (_jsx("span", { "data-field": fieldName, style: styles.preWrap, children: display }));
         }
         const link = detectLink(fieldValue.value);
         if (link) {
-            return (_jsx("a", { href: link.href, style: styles.link, target: "_blank", rel: "noopener noreferrer", children: display }));
+            return (_jsx("a", { "data-field": fieldName, href: link.href, style: styles.link, target: "_blank", rel: "noopener noreferrer", children: display }));
         }
     }
     return _jsx("span", { "data-field": fieldName, children: display });
 }
-function formatFallback(field) {
-    if (field.value == null)
-        return null;
-    if (typeof field.value === 'number')
-        return field.value.toLocaleString('ja-JP');
-    if (typeof field.value === 'string')
-        return field.value;
-    if (Array.isArray(field.value))
-        return field.value.join(', ');
-    return String(field.value);
-}
 function isMultiline(value) {
     return value.includes('\n');
 }
@@ -39,10 +31,31 @@ function detectLink(value) {
         return { href: value };
     if (/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value))
         return { href: `mailto:${value}` };
-    if (/^[\d+][\d\-().+\s]{7,}$/.test(value))
-        return { href: `tel:${value.replace(/[\s()-]/g, '')}` };
+    const phoneNumber = toPhoneNumber(value);
+    if (phoneNumber)
+        return { href: `tel:${phoneNumber}` };
     return null;
 }
+/**
+ * The number to dial when `value` reads as a phone number, or null.
+ *
+ * NOTE: digits and dashes alone also make up postal codes (100-0001) and dates
+ * (2026-09-28). A Japanese number starts with a single 0 and has 10 or 11
+ * digits; an international one starts with + and has 8 to 15 (E.164 caps it at
+ * 15). A leading 00 is a zero-padded code, not a number to dial
+ */
+function toPhoneNumber(value) {
+    if (!/^(?:\+|\(?0)[\d\s().-]+$/.test(value))
+        return null;
+    const digits = value.replace(/\D/g, '');
+    if (value.startsWith('+')) {
+        return digits.length >= 8 && digits.length <= 15 ? `+${digits}` : null;
+    }
+    // NOTE: checked on the digits, so separators cannot hide the second 0
+    if (digits.startsWith('00'))
+        return null;
+    return digits.length === 10 || digits.length === 11 ? digits : null;
+}
 const styles = {
     empty: {
         color: '#94a3b8',

package/src/lib/components/RecordList.js

@@ -3,6 +3,7 @@ import { useEffect, useMemo, useRef } from 'react';
 import { useRecordList } from '../hooks/useRecordList';
 import { color, font, radius, space, baseContainerStyle, baseButtonStyle, } from '../theme';
 import { SFA_KIT_VERSION } from '../version';
+import { EmptyState } from './EmptyState';
 import { FetchErrorState } from './FetchErrorState';
 import { FieldRenderer } from './FieldRenderer';
 const MAX_AUTO_COLUMNS = 8;
@@ -26,11 +27,38 @@ export function RecordList({ collection, columns, params, pageSize = 20, showPag
     if (status === 'error') {
         return (_jsxs("div", { style: styles.container, children: [_jsx(FetchErrorState, { message: errorMessage, onRetry: refetch }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
     }
+    // NOTE: on 'idle' nothing was asked — this component never disables the hook,
+    // so it only happens while `collection` is empty. "0 records" and "No records
+    // found" would state something the server never answered, and an empty table
+    // would look broken. Say what is missing instead — the input, not the data —
+    // as RecordView does for a missing record. From here on the status is
+    // 'loading' or 'success', so `!isLoading` means the items came from the server
+    if (status === 'idle') {
+        return (_jsxs("div", { style: styles.container, children: [_jsx(EmptyState, { message: "\u30AA\u30D6\u30B8\u30A7\u30AF\u30C8\u304C\u6307\u5B9A\u3055\u308C\u3066\u3044\u307E\u305B\u3093" }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
+    }
     const resolvedColumns = columns !== null && columns !== void 0 ? columns : autoDetectColumns(items);
-    const totalPages = Math.max(1, Math.ceil(totalCount / pageSize));
+    // NOTE: totalCount is null when it is not known — the backend reports no
+    // total (Keystone), or the count is not in yet. Then show the page number and
+    // the range on screen without a total
     const rangeStart = pageIndex * pageSize + 1;
-    const rangeEnd = Math.min((pageIndex + 1) * pageSize, totalCount);
-    return (_jsxs("div", { style: styles.container, children: [_jsxs("div", { style: styles.header, children: [_jsx("span", { style: styles.collectionName, children: collection }), !isLoading && _jsxs("span", { style: styles.count, children: [totalCount, " records"] })] }), _jsx("div", { style: styles.tableWrapper, children: _jsxs("table", { style: styles.table, children: [_jsx("thead", { children: _jsx("tr", { children: resolvedColumns.map(col => {
+    const rangeEnd = totalCount == null
+        ? pageIndex * pageSize + items.length
+        : Math.min((pageIndex + 1) * pageSize, totalCount);
+    const pageLabel = totalCount == null
+        ? `Page ${pageIndex + 1}`
+        : `Page ${pageIndex + 1} of ${Math.max(1, Math.ceil(totalCount / pageSize))}`;
+    const rangeLabel = totalCount == null
+        ? `Showing ${rangeStart}-${rangeEnd}`
+        : `Showing ${rangeStart}-${rangeEnd} of ${totalCount}`;
+    // NOTE: a later page that came back empty (records removed between page
+    // turns) keeps the pager so Prev can lead back, also while that page turn
+    // loads. No page position is stated there — see hasRecordsOnScreen
+    const hasPages = (totalCount !== null && totalCount !== void 0 ? totalCount : items.length) > 0 || pageIndex > 0;
+    // NOTE: with no records on screen there is no range or page position to state.
+    // While loading the table shows the loading row instead of the items, and
+    // pageIndex already names the page being fetched
+    const hasRecordsOnScreen = !isLoading && items.length > 0;
+    return (_jsxs("div", { style: styles.container, children: [_jsxs("div", { style: styles.header, children: [_jsx("span", { style: styles.collectionName, children: collection }), !isLoading && totalCount != null && (_jsxs("span", { style: styles.count, children: [totalCount, " records"] }))] }), _jsx("div", { style: styles.tableWrapper, children: _jsxs("table", { style: styles.table, children: [_jsx("thead", { children: _jsx("tr", { children: resolvedColumns.map(col => {
                                     var _a;
                                     return (_jsx("th", { style: Object.assign(Object.assign({}, styles.th), { width: col.width }), children: (_a = col.header) !== null && _a !== void 0 ? _a : col.fieldName }, col.fieldName));
                                 }) }) }), _jsxs("tbody", { children: [isLoading && (_jsx("tr", { children: _jsx("td", { colSpan: resolvedColumns.length, style: styles.loadingCell, children: "Loading..." }) })), !isLoading && items.length === 0 && (_jsx("tr", { children: _jsx("td", { colSpan: resolvedColumns.length, style: styles.emptyCell, children: "No records found" }) })), !isLoading &&
@@ -38,7 +66,7 @@ export function RecordList({ collection, columns, params, pageSize = 20, showPag
                                     items.map(record => (_jsx("tr", { style: onRowClick ? styles.clickableRow : styles.row, onClick: onRowClick ? () => onRowClick(record) : undefined, children: resolvedColumns.map(col => {
                                             const fieldValue = record.fields[col.fieldName];
                                             return (_jsx("td", { style: styles.td, children: fieldValue ? (_jsx(FieldRenderer, { fieldValue: fieldValue, fieldName: col.fieldName })) : (_jsx("span", { style: styles.emptyValue, children: "\u2014" })) }, col.fieldName));
-                                        }) }, record.record_id)))] })] }) }), showPagination && totalCount > 0 && (_jsxs("div", { style: styles.pagination, children: [_jsx("button", { style: styles.pageButton, disabled: pageIndex === 0 || isLoading, onClick: () => goToPage(pageIndex - 1), type: "button", children: "Prev" }), _jsxs("span", { style: styles.pageInfo, children: ["Page ", pageIndex + 1, " of ", totalPages] }), _jsx("button", { style: styles.pageButton, disabled: !hasMore || isLoading, onClick: () => goToPage(pageIndex + 1), type: "button", children: "Next" }), _jsxs("span", { style: styles.rangeInfo, children: ["Showing ", rangeStart, "-", rangeEnd, " of ", totalCount] })] })), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
+                                        }) }, record.record_id)))] })] }) }), showPagination && hasPages && (_jsxs("div", { style: styles.pagination, children: [_jsx("button", { style: styles.pageButton, disabled: pageIndex === 0 || isLoading, onClick: () => goToPage(pageIndex - 1), type: "button", children: "Prev" }), hasRecordsOnScreen && (_jsx("span", { style: styles.pageInfo, children: pageLabel })), _jsx("button", { style: styles.pageButton, disabled: !hasMore || isLoading, onClick: () => goToPage(pageIndex + 1), type: "button", children: "Next" }), hasRecordsOnScreen && (_jsx("span", { style: styles.rangeInfo, children: rangeLabel }))] })), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
 }
 function autoDetectColumns(items) {
     const first = items[0];

package/src/lib/components/RecordView.js

@@ -3,7 +3,9 @@ import { useEffect, useRef } from 'react';
 import { useRecord } from '../hooks/useRecord';
 import { color, font, radius, space, baseContainerStyle } from '../theme';
 import { SFA_KIT_VERSION } from '../version';
+import { EmptyState } from './EmptyState';
 import { FetchErrorState } from './FetchErrorState';
+import { toFieldDisplayText } from './fieldDisplayText';
 import { FieldRenderer } from './FieldRenderer';
 /**
  * @description Fetches and displays a single SFA/CRM record in a label-value grid.
@@ -11,26 +13,41 @@ import { FieldRenderer } from './FieldRenderer';
 export function RecordView({ collection, recordId, title, fields, fieldGroups, onError, errorMessage, }) {
     var _a;
     const { record, isLoading, error, refetch } = useRecord(collection, recordId);
+    // NOTE: useRecord reports an empty record id as an error so a page using the
+    // hook alone can say so, but to this component it is "no record specified",
+    // not a failed fetch: nothing was sent, and a retry would only repeat it.
+    // The screen and onError both read this, so a page never toasts a failure
+    // next to the "not specified" state
+    const fetchError = recordId === '' ? null : error;
     // Use a ref so inline onError callbacks don't re-fire the effect on
     // every parent render when error is present.
     const onErrorRef = useRef(onError);
     onErrorRef.current = onError;
     useEffect(() => {
         var _a;
-        if (error)
-            (_a = onErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onErrorRef, error);
-    }, [error]);
-    if (error) {
+        if (fetchError)
+            (_a = onErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onErrorRef, fetchError);
+    }, [fetchError]);
+    if (fetchError) {
         // NOTE: `title` is the label the page already shows as the heading, so it
         // names the record without exposing `collection` — the object key the API
         // is addressed with. The derived heading is unavailable here: it reads the
         // record, and on a failure there is none.
         return (_jsxs("div", { style: styles.container, children: [_jsx(FetchErrorState, { message: errorMessage !== null && errorMessage !== void 0 ? errorMessage : (title ? `${title}の取得に失敗` : undefined), onRetry: refetch }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
     }
-    if (isLoading || !record) {
+    if (isLoading) {
         return (_jsxs("div", { style: styles.container, children: [_jsx("div", { style: styles.loading, children: "Loading..." }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
     }
-    const displayTitle = (_a = title !== null && title !== void 0 ? title : record.title) !== null && _a !== void 0 ? _a : buildTitle(record.fields, record.titleFields);
+    // NOTE: nothing is loading and no fetch failed, yet there is no record. A
+    // fetch that finds none throws, so this means no record was specified — no
+    // collection or no record id yet. "Loading..." would never go away
+    if (!record) {
+        return (_jsxs("div", { style: styles.container, children: [_jsx(EmptyState, { message: "\u30EC\u30B3\u30FC\u30C9\u304C\u6307\u5B9A\u3055\u308C\u3066\u3044\u307E\u305B\u3093" }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
+    }
+    // NOTE: an empty title from the API names nothing, so build one from
+    // `titleFields` as if it were missing
+    const recordTitle = record.title === '' ? null : record.title;
+    const displayTitle = (_a = title !== null && title !== void 0 ? title : recordTitle) !== null && _a !== void 0 ? _a : buildTitle(record.fields, record.titleFields);
     const hasGroups = fieldGroups && fieldGroups.length > 0;
     return (_jsxs("div", { style: styles.container, children: [displayTitle && _jsx("h2", { style: styles.title, children: displayTitle }), _jsxs("div", { style: styles.meta, children: [collection, " / ", record.record_id] }), hasGroups
                 ? renderFieldGroups(record.fields, fieldGroups)
@@ -65,7 +82,10 @@ function renderFieldGroups(mapping, groups) {
 }
 function buildTitle(mapping, titleFields) {
     return titleFields
-        .map(name => { var _a; return (_a = mapping[name]) === null || _a === void 0 ? void 0 : _a.label; })
+        .map(name => {
+        const field = mapping[name];
+        return field ? toFieldDisplayText(field) : null;
+    })
         .filter(Boolean)
         .join(' ');
 }

package/src/lib/components/fieldDisplayText.d.ts

@@ -0,0 +1,11 @@
+import type { SfaFieldValue } from '../provider/types';
+/**
+ * @description The text a field shows to a reader — its label, or a plain
+ * readable value when the label is empty or missing — or null.
+ *
+ * NOTE: never a code or an id. FieldRenderer and the heading RecordView builds
+ * from `titleFields` both use this, so a field shows the same thing in its row
+ * and in the heading, and a reference whose label is missing puts its raw id
+ * in neither
+ */
+export declare function toFieldDisplayText(field: SfaFieldValue): string | null;

package/src/lib/components/fieldDisplayText.js

@@ -0,0 +1,51 @@
+/**
+ * Kinds whose `value` reads as it is. The others hold a code or an id, and
+ * only `label` names it
+ */
+const READABLE_VALUE_KINDS = new Set([
+    'text',
+    'number',
+    'date',
+    'datetime',
+    'computed',
+]);
+/**
+ * Whether `value` can be shown to a reader as it is: a number, a boolean, or a
+ * string that is not markup
+ *
+ * NOTE: Chikyu also sends kinds it has no mapping for as 'text' — an image
+ * field holds HTML, others may hold an object — so the kind alone does not
+ * promise readable text
+ */
+function isPlainValue(value) {
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return true;
+    return typeof value === 'string' && !/<[a-z!/][^>]*>/i.test(value);
+}
+/**
+ * @description The text a field shows to a reader — its label, or a plain
+ * readable value when the label is empty or missing — or null.
+ *
+ * NOTE: never a code or an id. FieldRenderer and the heading RecordView builds
+ * from `titleFields` both use this, so a field shows the same thing in its row
+ * and in the heading, and a reference whose label is missing puts its raw id
+ * in neither
+ */
+export function toFieldDisplayText(field) {
+    if (field.label != null && field.label !== '')
+        return field.label;
+    // NOTE: an empty or missing label carries no formatting, so a plain readable
+    // value shows instead. Anything else stays empty: a choice or a reference
+    // holds a code or an id (Chikyu leaves the caption out of fields it does not
+    // display, and a master-backed select holds an id), and markup or an object
+    // means nothing to a reader
+    return READABLE_VALUE_KINDS.has(field.kind) && isPlainValue(field.value)
+        ? formatPlainValue(field.value)
+        : null;
+}
+/** A plain value as text: a number formatted for ja-JP, the rest as it is */
+function formatPlainValue(value) {
+    return typeof value === 'number'
+        ? value.toLocaleString('ja-JP')
+        : String(value);
+}

package/src/lib/hooks/useFieldTypes.d.ts

@@ -10,6 +10,11 @@ interface UseFieldTypesResult {
 }
 /**
  * @description Fetches the static field-type catalog from Keystone.
+ *
+ * NOTE: a failed refetch keeps the field types already shown and sets `error`
+ * beside them. The catalog almost never changes, so a transient failure must
+ * not empty the pickers built from it. useRecord drops its record instead: a
+ * record does change, and a stale one would pass for the current one.
  */
 export declare function useFieldTypes(options?: UseFieldTypesOptions): UseFieldTypesResult;
 export {};

package/src/lib/hooks/useFieldTypes.js

@@ -2,6 +2,11 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { useSfaClient } from '../provider/useSfaClient';
 /**
  * @description Fetches the static field-type catalog from Keystone.
+ *
+ * NOTE: a failed refetch keeps the field types already shown and sets `error`
+ * beside them. The catalog almost never changes, so a transient failure must
+ * not empty the pickers built from it. useRecord drops its record instead: a
+ * record does change, and a stale one would pass for the current one.
  */
 export function useFieldTypes(options) {
     var _a;

package/src/lib/hooks/useObjectCatalog.d.ts

@@ -10,6 +10,12 @@ interface UseObjectCatalogResult {
 }
 /**
  * @description Fetches the list of all objects available in the org.
+ *
+ * NOTE: a failed refetch keeps the objects already shown and sets `error`
+ * beside them. The catalog almost never changes, so a transient failure must
+ * not empty the object picker built from it. useRecord drops its record
+ * instead: a record does change, and a stale one would pass for the current
+ * one.
  */
 export declare function useObjectCatalog(options?: UseObjectCatalogOptions): UseObjectCatalogResult;
 export {};

package/src/lib/hooks/useObjectCatalog.js

@@ -2,6 +2,12 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { useSfaClient } from '../provider/useSfaClient';
 /**
  * @description Fetches the list of all objects available in the org.
+ *
+ * NOTE: a failed refetch keeps the objects already shown and sets `error`
+ * beside them. The catalog almost never changes, so a transient failure must
+ * not empty the object picker built from it. useRecord drops its record
+ * instead: a record does change, and a stale one would pass for the current
+ * one.
  */
 export function useObjectCatalog(options) {
     var _a;

package/src/lib/hooks/useRecord.d.ts

@@ -10,6 +10,26 @@ interface UseRecordResult {
 }
 /**
  * @description Fetches a single record from the SFA/CRM API.
+ *
+ * NOTE: a failed refetch drops the record already shown. A record changes, so
+ * an earlier copy next to the error would pass for the current one and could
+ * be edited from. The catalog hooks keep their data on a failure instead,
+ * because what they hold almost never changes.
+ *
+ * NOTE: an empty `collection` means there is nothing to ask yet — the embed
+ * context has not arrived, say — and is treated like `enabled: false`: no
+ * request and no error. An error would flash on every page that is still
+ * waiting, and useRecordList and useDescribe stay idle the same way. An empty
+ * `recordId` with a collection given is different, and does set `error`: the
+ * object is known but no record is picked, which the message asks the reader to
+ * fix, and an empty id that reached the API was answered with a 503.
+ *
+ * NOTE: the result always describes the `collection` / `recordId` / client
+ * passed right now. When they change, the state still answers the old ones
+ * until the fetch for the new ones starts, so it reports no record and no
+ * error — with `isLoading` when a fetch is due — instead of the old answer,
+ * the way useRecordList reports 'loading' before its fetch settles. Disabling
+ * without changing them keeps the record already fetched.
  */
 export declare function useRecord(collection: string, recordId: string, options?: UseRecordOptions): UseRecordResult;
 export {};

package/src/lib/hooks/useRecord.js

@@ -4,6 +4,26 @@ import { ERR_EMPTY_RECORD_ID } from '../errors';
 import { useSfaClient } from '../provider/useSfaClient';
 /**
  * @description Fetches a single record from the SFA/CRM API.
+ *
+ * NOTE: a failed refetch drops the record already shown. A record changes, so
+ * an earlier copy next to the error would pass for the current one and could
+ * be edited from. The catalog hooks keep their data on a failure instead,
+ * because what they hold almost never changes.
+ *
+ * NOTE: an empty `collection` means there is nothing to ask yet — the embed
+ * context has not arrived, say — and is treated like `enabled: false`: no
+ * request and no error. An error would flash on every page that is still
+ * waiting, and useRecordList and useDescribe stay idle the same way. An empty
+ * `recordId` with a collection given is different, and does set `error`: the
+ * object is known but no record is picked, which the message asks the reader to
+ * fix, and an empty id that reached the API was answered with a 503.
+ *
+ * NOTE: the result always describes the `collection` / `recordId` / client
+ * passed right now. When they change, the state still answers the old ones
+ * until the fetch for the new ones starts, so it reports no record and no
+ * error — with `isLoading` when a fetch is due — instead of the old answer,
+ * the way useRecordList reports 'loading' before its fetch settles. Disabling
+ * without changing them keeps the record already fetched.
  */
 export function useRecord(collection, recordId, options) {
     var _a;
@@ -13,9 +33,19 @@ export function useRecord(collection, recordId, options) {
     const [isLoading, setIsLoading] = useState(enabled && !!collection && !!recordId);
     const [error, setError] = useState(null);
     const fetchId = useRef(0);
+    // NOTE: which inputs the state above answers. Set whenever doFetch starts
+    // answering a new question, so a render can tell the state is about inputs
+    // that are no longer passed
+    const answeredRef = useRef(null);
     const doFetch = useCallback(() => __awaiter(this, void 0, void 0, function* () {
         if (!enabled || !collection)
             return;
+        const answered = answeredRef.current;
+        const isNewQuestion = answered == null ||
+            answered.client !== client ||
+            answered.collection !== collection ||
+            answered.recordId !== recordId;
+        answeredRef.current = { client, collection, recordId };
         if (!recordId) {
             fetchId.current += 1;
             setRecord(null);
@@ -25,6 +55,10 @@ export function useRecord(collection, recordId, options) {
         }
         fetchId.current += 1;
         const currentFetchId = fetchId.current;
+        // NOTE: a refetch of the same record keeps it on screen while it loads; a
+        // record answering other inputs must not stand in for the new one
+        if (isNewQuestion)
+            setRecord(null);
         setIsLoading(true);
         setError(null);
         try {
@@ -45,5 +79,24 @@ export function useRecord(collection, recordId, options) {
     useEffect(() => {
         doFetch();
     }, [doFetch]);
+    const answered = answeredRef.current;
+    const answersCurrentInputs = answered != null &&
+        answered.client === client &&
+        answered.collection === collection &&
+        answered.recordId === recordId;
+    // NOTE: the state answers other inputs — the fetch for these has not started
+    // yet, or nothing will be asked (no collection, or disabled after the inputs
+    // changed). Either way the old record and error answer something else. It
+    // is loading only when a fetch is due; an empty record id gets its error from
+    // the effect. Disabling without changing the inputs keeps what was fetched,
+    // as useRecordList does
+    if (!answersCurrentInputs) {
+        return {
+            record: null,
+            isLoading: enabled && !!collection && !!recordId,
+            error: null,
+            refetch: doFetch,
+        };
+    }
     return { record, isLoading, error, refetch: doFetch };
 }

package/src/lib/hooks/useRecordList.d.ts

@@ -26,7 +26,13 @@ interface UseRecordListResult {
      * it without checking `status` turns a failed fetch into a confident zero.
      */
     readonly items: readonly SfaRecord[];
-    readonly totalCount: number;
+    /**
+     * @description Records across all pages, or null when not known: the backend
+     * does not report it (Keystone), or no fetch has succeeded since the query
+     * last changed — an earlier answer to the same query does not count. Like
+     * `items`, read it together with `status`
+     */
+    readonly totalCount: number | null;
     readonly hasMore: boolean;
     readonly pageIndex: number;
     readonly status: SfaListStatus;

package/src/lib/hooks/useRecordList.js

@@ -14,7 +14,7 @@ export function useRecordList(collection, params, options) {
     const listId = (_a = params === null || params === void 0 ? void 0 : params.listId) !== null && _a !== void 0 ? _a : embedCtx === null || embedCtx === void 0 ? void 0 : embedCtx.list_id;
     const limit = (_b = params === null || params === void 0 ? void 0 : params.limit) !== null && _b !== void 0 ? _b : 20;
     const [items, setItems] = useState([]);
-    const [totalCount, setTotalCount] = useState(0);
+    const [totalCount, setTotalCount] = useState(null);
     const [hasMore, setHasMore] = useState(false);
     /**
      * Where the caller asked the listing to start.
@@ -161,7 +161,7 @@ export function useRecordList(collection, params, options) {
                     // would show one record's children — or one organization's data —
                     // under another, so drop them and let status report them unknown.
                     setItems([]);
-                    setTotalCount(0);
+                    setTotalCount(null);
                     setHasMore(false);
                     loadedRef.current = null;
                 }
@@ -245,7 +245,7 @@ export function useRecordList(collection, params, options) {
         ? { items, totalCount, hasMore, status, error }
         : {
             items: NO_ITEMS,
-            totalCount: 0,
+            totalCount: null,
             hasMore: false,
             status: willFetch ? 'loading' : 'idle',
             error: null,

package/src/lib/hooks/useRelatedRecords.d.ts

@@ -22,7 +22,11 @@ export interface UseRelatedRecordsResult {
      * only meaningful when `status` is `'success'` — see useRecordList.
      */
     readonly items: readonly SfaRecord[];
-    readonly totalCount: number;
+    /**
+     * @description Records across all pages, or null when not known — see
+     * useRecordList
+     */
+    readonly totalCount: number | null;
     readonly hasMore: boolean;
     readonly pageIndex: number;
     /**