@geniee-inc/sfa-kit 1.11.0 → 1.13.0

package/GUIDE.md

@@ -263,6 +263,219 @@ Check `status` for **every** hook on the page, not just the first one. Each rela
 
 Returns `{ items, totalCount, hasMore, pageIndex, status, goToPage, isLoading, error, refetch, relationship }`.
 
+### Bulk writes
+
+`useBulkCreateRecords`, `useBulkUpdateRecords` and `useBulkDeleteRecords` write
+many records of one object in a single call — for grid edits and other
+multi-row saves, instead of looping the single-record hooks. They share the
+contract below; the three sections after it cover only what differs.
+
+**A bulk call is best-effort per row.** The API answers `200` and reports every
+row's outcome — there is no all-or-nothing mode, so a batch can be partly
+successful and nothing is rolled back. That is why per-row failures come back
+as data rather than thrown errors: throwing would discard the ids of the rows
+that did land, and those are not recoverable anywhere else.
+
+- `results` — one entry per submitted row, carrying `index` (its position in
+  the request), `status`, `record` and `error`. Each entry is placed by its
+  `index`, never by the order it arrived in, so `results[n]` is the outcome of
+  the row that was sent at position `n`. A response that cannot be paired with
+  the request — fewer entries than rows, an index missing, not a whole
+  position, repeated, or past the end — is refused rather than returned: some
+  submitted row would have no reported outcome, and showing the rest as the
+  whole picture leaves it looking neither written nor retryable. Re-read the
+  records to find out what landed
+- `failed` — the rows that did not land **and can be sent again**: `conflict`,
+  `invalid` and `not_attempted`. Retry exactly these. What makes that safe is
+  that they did not apply; there is no server-side de-duplication to fall back
+  on
+- `unresolved` — the rows that may already be written but cannot be reported
+  either way. They keep whatever `id` arrived. **Re-read these; never retry
+  them**: a create that already landed would be written twice
+- `isLoading` — a call is in flight. Starting a second call supersedes the
+  first: whichever was started last owns the state, so a slower earlier batch
+  cannot publish outcomes for rows the caller has moved on from
+- `error` — set only when the whole call was rejected: row count out of range,
+  a response that does not answer for every row, auth, a 4xx/5xx. Individual
+  row failures are never reported here. The call **also rejects**, the same as
+  the single-record write hooks, so catch it to keep the rejection out of the
+  console; what to show the reader comes from `error`
+- `reset` — clears results and error
+
+A `501` inside that error is not a hiccup: the object does not offer bulk
+writes at all. Waiting or retrying will never make it work, so it arrives as
+`SfaBulkUnsupportedError` — a `SfaApiError` carrying `status` 501 and a
+`userMessage` that says the operation is unavailable rather than asking for
+another try. `ErrorSnackbar` shows that text as it stands; a page writing its
+own wording can tell the case apart with `instanceof` or `status`.
+
+Everything the hook reports describes the object it was written for, on the
+visit it was written on. Pass a different collection, or let the provider
+rebuild its client — a token refresh or an org switch does — and results,
+loading and error read empty again rather than carrying the previous object's
+rows over. Coming back to that object does not bring them back either: they
+belong to the visit that ended. A batch that was already in flight answers into
+nothing, then and later.
+
+Read-only mode is not reported through `error`: the call throws instead,
+because it is a provider setting rather than an outcome of the request.
+
+A call takes 1..`SFA_BULK_MAX_ROWS` (25) rows. The API itself accepts up to
+100; 25 is the kit's own limit, set by how long a call takes — the server
+writes one row at a time, under a budget of its own, and a larger batch would
+outlast it and then the load balancer. A larger selection is refused before a
+request goes out rather than being cut off mid-write. Split bigger selections
+into batches; each batch is its own call.
+
+A bulk write is also given a longer fetch timeout than other calls, so the
+browser waits for the server to finish rather than dropping an answer that
+names the rows already written. Should a call time out anyway, treat the whole
+batch the way you treat `unresolved`: the server may have written some of it
+and the answer is gone, so re-read the records rather than sending them
+again.
+
+An oversized selection is refused with `SfaBulkRowCountError`, which carries
+`limit`, `submitted` and a ready `userMessage` in Japanese. Show that message
+rather than writing the sentence again in the page, where it would drift from
+the limit the kit enforces. It lands in the hook's `error` like any whole-call
+failure, so showing it takes no state of your own — hand `error` to
+`ErrorSnackbar` and clear it with `reset`:
+
+```tsx
+import { ErrorSnackbar, useBulkUpdateRecords } from '@geniee-inc/sfa-kit';
+
+const { bulkUpdate, error, reset } = useBulkUpdateRecords('opportunity');
+
+// the call rejects as well as setting `error`, so catch it to keep the
+// rejection from reaching the console
+const save = () => void bulkUpdate(edited).catch(() => undefined);
+
+<ErrorSnackbar error={error} onClose={reset} />;
+```
+
+`ErrorSnackbar` shows the error's `userMessage` when there is one and a general
+line otherwise; an error's `message` is never shown, being English wording
+written for the log. Pass `message` to say something more specific.
+
+The same bar reports how a partly successful batch ended — the counts, and the
+action left to take:
+
+```tsx
+return (
+  <>
+    <OpportunityGrid results={results} />
+    {/* `error` is null here: the call worked, some rows did not. The bar
+        appears because there is a message to show.
+
+        Not while the retry runs: `results` are kept during a call, so the bar
+        and its action would stay on screen, and a second press would send the
+        rows again. Nothing de-duplicates them — a repeated create writes
+        twice. */}
+    {!isLoading && (
+      <ErrorSnackbar
+        error={null}
+        message={`${results.length} 件中 ${updated.length} 件を保存しました。${failed.length} 件は保存されていません。`}
+        onRetry={() => void bulkUpdate(rowsFor(failed)).catch(() => undefined)}
+        onClose={reset}
+      />
+    )}
+  </>
+);
+```
+
+Counts only: which row failed and why belongs in the grid, where the reader
+acts on it — `results` carries each row's `index` and its per-field errors.
+Offer `onRetry` for `failed` rows; `unresolved` rows are re-read instead, so
+label the action accordingly (`retryLabel`).
+
+A row counts as written only when it carries what a write produces: the record
+for a create or an update, the id for a delete. Anything short of that is
+`failed` or `unresolved`, and which one is decided by what the answer says,
+not by elimination. Three statuses mean the row did not apply, and only those
+may be sent again: `conflict`, `invalid`, and `not_attempted` — the last for a
+row the call ran out of budget before starting, which is resent exactly as it
+was. A `conflict` carries the server's current record: retry with the
+`version` it reports, or re-read first if none arrived.
+
+Everything else is `unresolved`: `indeterminate`, the server saying it cannot
+tell whether the row applied; a claimed success missing what it should carry —
+no record, an unreadable one, no `version`, an empty id; and any answer the kit
+cannot place, such as a status outside the contract.
+
+Every submitted row is therefore in exactly one of the success list
+(`created` / `updated` / `deletedIds`), `failed`, or `unresolved`.
+
+### useBulkCreateRecords
+
+```tsx
+import { useBulkCreateRecords, SFA_BULK_MAX_ROWS } from '@geniee-inc/sfa-kit';
+
+const { bulkCreate, created, failed, isLoading, error } =
+  useBulkCreateRecords('opportunity');
+
+try {
+  await bulkCreate([
+    { company_id: 'cmp_88', stage: '3', amount: 5300000 },
+    { company_id: 'cmp_90', stage: '1', amount: 120000 },
+  ]);
+} catch {
+  // the whole call was rejected; `error` holds it for rendering
+}
+```
+
+Each row is a field map, like a single create.
+
+- `created` — the records that were written, in submission order
+
+Returns `{ bulkCreate, results, created, failed, unresolved, isLoading, error, reset }`.
+
+### useBulkUpdateRecords
+
+The save action of a grid edit: each row carries its own version.
+
+```tsx
+const { bulkUpdate, updated, conflicts, failed } =
+  useBulkUpdateRecords('opportunity');
+
+await bulkUpdate([
+  { id: 'opp_1', version: 'v1', fields: { stage: '4' } },
+  { id: 'opp_2', version: 'v7', fields: { amount: 90000 } },
+]);
+```
+
+A row whose `version` is stale comes back as `conflict` and is **left
+unchanged**, while the rest of the batch applies. Its result carries the
+server's current `record`, which is what the reader reconciles against — retry
+with the version that record reports, never by re-sending the stale one.
+
+- `updated` — the records as they now stand on the server, in submission order
+- `conflicts` — the rows a concurrent write got to first, each with the current
+  `record`. Also present in `failed`
+
+Returns the same shape, with `updated` and `conflicts` in place of `created`.
+
+### useBulkDeleteRecords
+
+```tsx
+const { bulkDelete, deletedIds, conflicts, failed } =
+  useBulkDeleteRecords('opportunity');
+
+await bulkDelete([
+  { id: 'opp_1', version: 'v1' },
+  { id: 'opp_2', version: 'v7' },
+]);
+```
+
+The same optimistic concurrency: a stale row is reported as `conflict` and
+stays in place. A partly failed batch has already removed records, so reconcile
+from `deletedIds` rather than assume the whole selection is gone.
+
+- `deletedIds` — what was actually removed, in submission order. A delete
+  answers with no record, so the id comes from the row itself
+
+Returns the same shape, with `deletedIds` and `conflicts` in place of
+`created`.
+
 ### useDescribe
 
 Discovers object schema — fields, types, relationships, permissions. Use this to build dynamic UIs that adapt to any object.
@@ -302,6 +515,8 @@ const record = await client.get('companies', 'abc123');
 const list = await client.list('companies', { limit: 10 });
 ```
 
+`SfaClientInterface` describes the shape of the client the provider hands out — it is not an extension point. Methods are added to it as the API grows, so implementing it yourself would break on any release that covers a new endpoint. Take the client from `useSfaClient()`; to stand one in for a test, mock the hook rather than the interface.
+
 ## Record shape
 
 All hooks return records in a normalized shape:
@@ -385,7 +600,34 @@ The server's error text is deliberately not shown: it is wording the reader cann
 
 `refetch` retries whichever step failed. On `useRelatedRecords` that includes a failed describe: retrying only the list would do nothing, because without relationship metadata the list never ran.
 
-Two baseline components for resilient pages:
+Three baseline components for resilient pages:
+
+### ErrorSnackbar
+
+A bar at the bottom of the page saying why a write did not happen, and how a
+partly successful one ended. Renders nothing until there is something to say —
+an error or a `message` — so a page can hand it the state it keeps the failure
+in.
+
+```tsx
+<ErrorSnackbar error={failure} onClose={reset} />
+```
+
+- `error` — the error as caught. Its `userMessage` is shown when it has one
+  (the row count refusal and the 501 do), a general line otherwise — and that
+  line says to try again later, which is why the failures where waiting cannot
+  help carry their own text. An error's `message` is never shown: it is
+  English wording written for the log
+- `message` — overrides both, for when the page can be more specific. A bulk
+  write passes its counts here
+- `onRetry`, `retryLabel` — an optional action beside the text, for the rows
+  in `failed`. Name it for what it does: `unresolved` rows are re-read, not
+  retried. Take the bar down while the retry runs: a second press sends the
+  same rows again, and nothing de-duplicates them
+- `onClose` — clears it. The bar stays until dismissed: a reader told to
+  reduce a selection has to read a number before acting on it
+
+Use `FetchErrorState` for a failed read and this for a failed write.
 
 ### ErrorBoundary
 
@@ -728,6 +970,7 @@ Returns `null` for unsupported collections (e.g. `schedules`).
 - Do NOT hardcode `defaultOrganizationId` as a number literal in JSX. Use `Number(process.env.NEXT_PUBLIC_DEFAULT_ORG_ID)` and set the value in `.env`.
 - Do NOT embed service account credentials in generated page source. Discovery credentials (used to query the schema at build time) must never appear in deployed code.
 - Do NOT call the API directly with fetch. Use the provided hooks or `useSfaClient()`.
+- Do NOT loop single writes to save many rows. Use the bulk hooks: a loop sends one request per row, and a failure part-way through leaves the caller with no report of what landed.
 - Do NOT add Route Handlers (app/api/) for SFA data. The kit calls the API from the browser.
 - Do NOT hardcode API base URLs, API keys, or credentials anywhere.
 - Do NOT add record detail links automatically. They are opt-in: generate them only when the user asks (e.g. "make the names clickable", "add links to records"), or ask the user for confirmation before adding them. In standalone preview mode, links are unavailable (`useRecordDetailUrl` returns `null`). The `schedules` collection does not have a standard record detail page; if asked, tell the user that schedule links are not yet supported.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geniee-inc/sfa-kit",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "React hooks and components for building pages that connect to GENIEE SFA/CRM data.",
   "type": "module",
   "main": "./src/index.js",

package/src/index.d.ts

@@ -1,4 +1,4 @@
-export { SfaApiError, SfaConflictError, SfaValidationError, } from './lib/provider/SfaClient';
+export { SfaApiError, SfaBulkRowCountError, SfaBulkUnsupportedError, SfaConflictError, SfaValidationError, } from './lib/provider/SfaClient';
 export { SfaProvider } from './lib/provider/SfaProvider';
 export { useSfaClient } from './lib/provider/useSfaClient';
 export { SfaLoginGate } from './lib/auth/SfaLoginGate';
@@ -15,6 +15,12 @@ export { useObjectCatalog } from './lib/hooks/useObjectCatalog';
 export { useFieldTypes } from './lib/hooks/useFieldTypes';
 export { useCreateRecord } from './lib/hooks/useCreateRecord';
 export type { UseCreateRecordResult } from './lib/hooks/useCreateRecord';
+export { useBulkCreateRecords } from './lib/hooks/useBulkCreateRecords';
+export type { UseBulkCreateRecordsResult } from './lib/hooks/useBulkCreateRecords';
+export { useBulkUpdateRecords } from './lib/hooks/useBulkUpdateRecords';
+export type { UseBulkUpdateRecordsResult } from './lib/hooks/useBulkUpdateRecords';
+export { useBulkDeleteRecords } from './lib/hooks/useBulkDeleteRecords';
+export type { UseBulkDeleteRecordsResult } from './lib/hooks/useBulkDeleteRecords';
 export { useUpdateRecord } from './lib/hooks/useUpdateRecord';
 export type { UseUpdateRecordResult, SfaConflictDetail, } from './lib/hooks/useUpdateRecord';
 export { useDeleteRecord } from './lib/hooks/useDeleteRecord';
@@ -27,7 +33,9 @@ export { RecordList } from './lib/components/RecordList';
 export { ErrorBoundary } from './lib/components/ErrorBoundary';
 export { EmptyState } from './lib/components/EmptyState';
 export { FetchErrorState } from './lib/components/FetchErrorState';
-export type { SfaAuth, SfaApiMode, SfaClientConfig, SfaRecord, SfaListResponse, SfaListParams, SfaFieldValue, SfaFieldKind, SfaFieldValueMapping, FieldGroupSpec, FieldGroupLayout, SfaFieldDescriptor, SfaFieldOption, SfaRelationDescriptor, SfaObjectDetail, SfaObjectSummary, SfaObjectCatalog, SfaObjectPermissions, SfaObjectOrigin, SfaRelationshipKind, SfaCardinality, SfaDescribeResult, SfaFieldTypeDescriptor, SfaFieldTypeCatalog, SfaFilterOperator, SfaCreateOptions, SfaFieldError, } from './lib/provider/types';
+export { ErrorSnackbar } from './lib/components/ErrorSnackbar';
+export type { SfaAuth, SfaApiMode, SfaClientConfig, SfaRecord, SfaListResponse, SfaListParams, SfaFieldValue, SfaFieldKind, SfaFieldValueMapping, FieldGroupSpec, FieldGroupLayout, SfaFieldDescriptor, SfaFieldOption, SfaRelationDescriptor, SfaObjectDetail, SfaObjectSummary, SfaObjectCatalog, SfaObjectPermissions, SfaObjectOrigin, SfaRelationshipKind, SfaCardinality, SfaDescribeResult, SfaFieldTypeDescriptor, SfaFieldTypeCatalog, SfaFilterOperator, SfaCreateOptions, SfaFieldError, SfaBulkRowStatus, SfaBulkRowResult, SfaBulkRowError, SfaBulkUpdateRow, SfaBulkDeleteRow, } from './lib/provider/types';
+export { SFA_BULK_MAX_ROWS } from './lib/provider/SfaClient';
 export type { SfaSession, AuthResult, OrganizationChoice, } from './lib/auth/types';
 export { buildRecordDetailUrl, resolveHostOrigin, } from './lib/navigation/record-detail-url';
 export type { RecordDetailUrlParams, RecordDetailLink, } from './lib/navigation/record-detail-url';

package/src/index.js

@@ -1,4 +1,4 @@
-export { SfaApiError, SfaConflictError, SfaValidationError, } from './lib/provider/SfaClient';
+export { SfaApiError, SfaBulkRowCountError, SfaBulkUnsupportedError, SfaConflictError, SfaValidationError, } from './lib/provider/SfaClient';
 export { SfaProvider } from './lib/provider/SfaProvider';
 export { useSfaClient } from './lib/provider/useSfaClient';
 export { SfaLoginGate } from './lib/auth/SfaLoginGate';
@@ -11,6 +11,9 @@ export { useDescribe } from './lib/hooks/useDescribe';
 export { useObjectCatalog } from './lib/hooks/useObjectCatalog';
 export { useFieldTypes } from './lib/hooks/useFieldTypes';
 export { useCreateRecord } from './lib/hooks/useCreateRecord';
+export { useBulkCreateRecords } from './lib/hooks/useBulkCreateRecords';
+export { useBulkUpdateRecords } from './lib/hooks/useBulkUpdateRecords';
+export { useBulkDeleteRecords } from './lib/hooks/useBulkDeleteRecords';
 export { useUpdateRecord } from './lib/hooks/useUpdateRecord';
 export { useDeleteRecord } from './lib/hooks/useDeleteRecord';
 export { useRelatedRecords, RelationNotFoundError, resolveRelation, buildRelationFilter, } from './lib/hooks/useRelatedRecords';
@@ -20,5 +23,7 @@ export { RecordList } from './lib/components/RecordList';
 export { ErrorBoundary } from './lib/components/ErrorBoundary';
 export { EmptyState } from './lib/components/EmptyState';
 export { FetchErrorState } from './lib/components/FetchErrorState';
+export { ErrorSnackbar } from './lib/components/ErrorSnackbar';
+export { SFA_BULK_MAX_ROWS } from './lib/provider/SfaClient';
 export { buildRecordDetailUrl, resolveHostOrigin, } from './lib/navigation/record-detail-url';
 export { useRecordDetailUrl } from './lib/hooks/useRecordDetailUrl';

package/src/lib/auth/StandalonePreviewContext.d.ts

@@ -5,6 +5,7 @@
 export interface StandalonePreviewState {
     readonly object_key: string;
     readonly record_id?: string;
+    readonly list_id?: string;
 }
 export interface StandalonePreviewControls {
     readonly state: StandalonePreviewState | null;

package/src/lib/auth/embed-protocol.d.ts

@@ -15,6 +15,7 @@ export interface EmbedReadyMessage {
 export interface EmbedContext {
     readonly object_key: string;
     readonly record_id?: string;
+    readonly list_id?: string;
 }
 /** Sent by the host to deliver a single-use exchange code. */
 export interface EmbedCodeMessage {

package/src/lib/auth/embed-protocol.js

@@ -33,7 +33,8 @@ export function parseInboundMessage(event, trustedOrigin) {
             const ctx = rawContext;
             if (typeof ctx['object_key'] === 'string' &&
                 ctx['object_key'].length > 0) {
-                const context = { object_key: ctx['object_key'] };
+                const context = Object.assign({ object_key: ctx['object_key'] }, (typeof ctx['list_id'] === 'string' &&
+                    ctx['list_id'].length > 0 && { list_id: ctx['list_id'] }));
                 if (typeof ctx['record_id'] === 'string' &&
                     ctx['record_id'].length > 0) {
                     return Object.assign(Object.assign({}, result), { context: Object.assign(Object.assign({}, context), { record_id: ctx['record_id'] }) });

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

@@ -0,0 +1,53 @@
+interface ErrorSnackbarProps {
+    /**
+     * The error to announce, as caught. A page can hand this the same state it
+     * stores the failure in; pass null when there is none and say what happened
+     * through `message` instead, as a partly successful batch does.
+     */
+    readonly error: unknown;
+    /** Dismisses it. Clear the error the page is holding. */
+    readonly onClose: () => void;
+    /**
+     * Overrides the text. Use when the page can say something more specific
+     * than the kit can — which object was being saved, or how a bulk write
+     * ended: `8 件中 5 件を保存しました。2 件は保存されていません。` An empty
+     * string counts as nothing said, and the error is used instead.
+     */
+    readonly message?: string;
+    /**
+     * Adds an action next to the text. A bulk write hands this the retry of
+     * its `failed` rows; omit it when there is nothing to offer.
+     */
+    readonly onRetry?: () => void;
+    /** Label for that action. */
+    readonly retryLabel?: string;
+}
+/**
+ * @description A bar that tells the reader why a write did not happen.
+ *
+ * The text comes from the error's `userMessage` when it has one — the row
+ * count refusal and the 501 that says an object has no bulk write do, since
+ * the general line asks for another try and neither is worth retrying — and
+ * falls back to that general line otherwise. An error's
+ * `message` is never shown: it is written for the log, in English, and names
+ * things the reader cannot act on.
+ *
+ * ```tsx
+ * const [failure, setFailure] = useState<unknown>(null);
+ *
+ * const save = async () => {
+ *   try {
+ *     await bulkUpdate(edited);
+ *   } catch (error) {
+ *     setFailure(error);
+ *   }
+ * };
+ *
+ * <ErrorSnackbar error={failure} onClose={() => setFailure(null)} />;
+ * ```
+ *
+ * NOTE: it stays until dismissed. A reader told to reduce a selection has to
+ * read a number and then act on it, which a bar that times out takes away.
+ */
+export declare function ErrorSnackbar({ error, onClose, message, onRetry, retryLabel, }: ErrorSnackbarProps): JSX.Element | null;
+export {};

package/src/lib/components/ErrorSnackbar.js

@@ -0,0 +1,112 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { color, font, radius, space } from '../theme';
+/** Shown when the error carries nothing a reader can act on. */
+const FALLBACK_MESSAGE = '保存できませんでした。時間をおいて再度お試しください。';
+/**
+ * @description A bar that tells the reader why a write did not happen.
+ *
+ * The text comes from the error's `userMessage` when it has one — the row
+ * count refusal and the 501 that says an object has no bulk write do, since
+ * the general line asks for another try and neither is worth retrying — and
+ * falls back to that general line otherwise. An error's
+ * `message` is never shown: it is written for the log, in English, and names
+ * things the reader cannot act on.
+ *
+ * ```tsx
+ * const [failure, setFailure] = useState<unknown>(null);
+ *
+ * const save = async () => {
+ *   try {
+ *     await bulkUpdate(edited);
+ *   } catch (error) {
+ *     setFailure(error);
+ *   }
+ * };
+ *
+ * <ErrorSnackbar error={failure} onClose={() => setFailure(null)} />;
+ * ```
+ *
+ * NOTE: it stays until dismissed. A reader told to reduce a selection has to
+ * read a number and then act on it, which a bar that times out takes away.
+ */
+export function ErrorSnackbar({ error, onClose, message, onRetry, retryLabel = '再試行', }) {
+    // NOTE: a partly successful batch has no error at all — the call worked,
+    // some rows did not. The bar still has something to say, so what decides
+    // whether it appears is the text, not the error.
+    //
+    // NOTE: an empty string is a page with nothing to say — a summary built from
+    // a list that turned out empty. Taken as given it would draw a bar carrying
+    // a warning sign and no words, and announce nothing to a screen reader
+    const pageText = message != null && message.trim() !== '' ? message : null;
+    const text = pageText !== null && pageText !== void 0 ? pageText : (error == null ? null : readUserMessage(error));
+    if (text == null)
+        return null;
+    return (_jsxs("div", { style: styles.bar, children: [_jsxs("span", { style: styles.text, role: "alert", children: [_jsx("span", { "aria-hidden": "true", children: "\u26A0" }), " ", text] }), onRetry && (_jsx("button", { type: "button", style: styles.retry, onClick: onRetry, children: retryLabel })), _jsx("button", { type: "button", style: styles.close, onClick: onClose, "aria-label": "\u9589\u3058\u308B", children: _jsx("span", { "aria-hidden": "true", children: "\u00D7" }) })] }));
+}
+/**
+ * @description The reader-facing text of an error, if it has one.
+ *
+ * NOTE: reads the field rather than testing for a class, so an error type
+ * added later carries its own wording here without changing this component —
+ * and this stays a presentational component with nothing to know about the
+ * provider layer.
+ */
+function readUserMessage(error) {
+    if (error != null && typeof error === 'object' && 'userMessage' in error) {
+        const carried = error.userMessage;
+        if (typeof carried === 'string' && carried !== '')
+            return carried;
+    }
+    return FALLBACK_MESSAGE;
+}
+const styles = {
+    bar: {
+        position: 'fixed',
+        left: '50%',
+        bottom: space.lg,
+        transform: 'translateX(-50%)',
+        zIndex: 1000,
+        display: 'flex',
+        alignItems: 'center',
+        gap: space.md,
+        maxWidth: 'calc(100vw - 32px)',
+        padding: `${space.sm}px ${space.md}px`,
+        fontFamily: font.family,
+        fontSize: font.sizeMd,
+        color: color.textPrimary,
+        backgroundColor: color.errorLight,
+        border: `1px solid ${color.error}`,
+        borderRadius: radius.sm,
+    },
+    text: {
+        fontWeight: font.weightMedium,
+    },
+    retry: {
+        flexShrink: 0,
+        padding: 0,
+        fontFamily: font.family,
+        fontSize: font.sizeMd,
+        color: color.primary,
+        backgroundColor: 'transparent',
+        border: 'none',
+        textDecoration: 'underline',
+        cursor: 'pointer',
+    },
+    close: {
+        flexShrink: 0,
+        // NOTE: 記号は小さいので、押せる範囲は文字サイズではなく箱で確保する
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        width: space.lg,
+        height: space.lg,
+        padding: 0,
+        fontFamily: font.family,
+        fontSize: font.sizeXl,
+        lineHeight: 1,
+        color: color.textSecondary,
+        backgroundColor: 'transparent',
+        border: 'none',
+        cursor: 'pointer',
+    },
+};

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

@@ -0,0 +1,30 @@
+import type { SfaBulkRowResult, SfaBulkRowStatus } from '../provider/types';
+export interface BulkRowSplit<T> {
+    /** What each row that landed produced, in submission order. */
+    readonly landed: readonly T[];
+    /** May already be applied. Re-read; retrying is what writes a duplicate. */
+    readonly unresolved: readonly SfaBulkRowResult[];
+    /** The rows a concurrent write got to first. Also present in `failed`. */
+    readonly conflicts: readonly SfaBulkRowResult[];
+    /**
+     * The rows that did not land and can be sent again. A `conflict` is one of
+     * them, and also appears in `conflicts`.
+     */
+    readonly failed: readonly SfaBulkRowResult[];
+}
+/**
+ * @description Splits per-row outcomes by what the caller may do with them.
+ *
+ * NOTE: `failed` is decided by what the answer says, never by exclusion.
+ * `conflict`, `invalid` and `not_attempted` all mean the row did not apply, so
+ * those are the ones safe to send again — a row the call never started is as
+ * unwritten as one the server rejected. Anything else the kit cannot place —
+ * `indeterminate`, no record, no version, a status outside the contract or
+ * belonging to another operation — may already be written, and a retry would
+ * write it twice.
+ *
+ * NOTE: one pass, so a row that claims success without carrying it falls into
+ * `unresolved` rather than out of every list. Order follows `results`, which
+ * the client has already aligned with the request.
+ */
+export declare function splitBulkRows<T>(results: readonly SfaBulkRowResult[], landedStatus: SfaBulkRowStatus, read: (row: SfaBulkRowResult) => T | null): BulkRowSplit<T>;

package/src/lib/hooks/splitBulkRows.js

@@ -0,0 +1,42 @@
+/** The outcomes that mean the row did not apply, so sending it again is safe. */
+const RETRYABLE_STATUSES = new Set([
+    'conflict',
+    'invalid',
+    'not_attempted',
+]);
+/**
+ * @description Splits per-row outcomes by what the caller may do with them.
+ *
+ * NOTE: `failed` is decided by what the answer says, never by exclusion.
+ * `conflict`, `invalid` and `not_attempted` all mean the row did not apply, so
+ * those are the ones safe to send again — a row the call never started is as
+ * unwritten as one the server rejected. Anything else the kit cannot place —
+ * `indeterminate`, no record, no version, a status outside the contract or
+ * belonging to another operation — may already be written, and a retry would
+ * write it twice.
+ *
+ * NOTE: one pass, so a row that claims success without carrying it falls into
+ * `unresolved` rather than out of every list. Order follows `results`, which
+ * the client has already aligned with the request.
+ */
+export function splitBulkRows(results, landedStatus, read) {
+    const landed = [];
+    const unresolved = [];
+    const conflicts = [];
+    const failed = [];
+    for (const row of results) {
+        const value = row.status === landedStatus ? read(row) : null;
+        if (value != null) {
+            landed.push(value);
+            continue;
+        }
+        if (RETRYABLE_STATUSES.has(row.status)) {
+            failed.push(row);
+            if (row.status === 'conflict')
+                conflicts.push(row);
+            continue;
+        }
+        unresolved.push(row);
+    }
+    return { landed, unresolved, conflicts, failed };
+}

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

@@ -0,0 +1,56 @@
+import type { SfaBulkRowResult, SfaRecord } from '../provider/types';
+export interface UseBulkCreateRecordsResult {
+    /**
+     * Call to create many records at once. Each entry is a field map, like a
+     * single create. Resolves with one result per submitted row.
+     */
+    readonly bulkCreate: (rows: readonly Record<string, unknown>[]) => Promise<readonly SfaBulkRowResult[]>;
+    /**
+     * Every row's outcome from the last call, aligned to the submitted rows by
+     * `index`. Empty before the first call, and empty again once `collection`
+     * or the provider's client changes — and it stays that way if they change
+     * back: these outcomes describe the object they were written for, on the
+     * visit they were written on.
+     */
+    readonly results: readonly SfaBulkRowResult[];
+    /** The records that were created, in submission order. */
+    readonly created: readonly SfaRecord[];
+    /**
+     * The rows that did not land and can be sent again, with their `index` and
+     * `error`. A batch can be partly successful, so this being non-empty does
+     * not mean nothing was written — retry exactly these rows.
+     */
+    readonly failed: readonly SfaBulkRowResult[];
+    /**
+     * The rows that may already be created but cannot be reported either way.
+     * They keep whatever `id` arrived. Re-read these; retrying one that landed
+     * writes a second record.
+     */
+    readonly unresolved: readonly SfaBulkRowResult[];
+    readonly isLoading: boolean;
+    /**
+     * Set when the whole call was rejected — row count out of range, a response
+     * that does not answer for every row, auth, or a 4xx/5xx from the API. Rows
+     * that failed individually are reported in `failed`, not here, and read-only
+     * mode throws synchronously instead: it is a provider setting, not an
+     * outcome of this call.
+     */
+    readonly error: Error | null;
+    /** Reset results and error state to initial values. */
+    readonly reset: () => void;
+}
+/**
+ * @description Imperative hook for creating many records of one object in a
+ * single call. Like the single-record hooks it does not fetch on mount.
+ *
+ * A bulk call is best-effort per row: the API answers 200 and reports each
+ * row's outcome, with no all-or-nothing mode. So a partly failed batch still
+ * created records, and their ids are only available here — which is why
+ * per-row failures are returned as data rather than thrown. `error` is for
+ * the call as a whole.
+ *
+ * Retry only the rows in `failed`: those did not apply, which is what makes
+ * resending them safe. Re-read the rows in `unresolved` instead — nothing
+ * protects against writing them twice.
+ */
+export declare function useBulkCreateRecords(collection: string): UseBulkCreateRecordsResult;