@geniee-inc/sfa-kit 1.12.0 → 1.13.0

package/GUIDE.md

@@ -303,9 +303,11 @@ that did land, and those are not recoverable anywhere else.
 - `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 tell the reader
-the operation is unavailable for this object instead of offering a retry. Read
-it from `SfaApiError.status`.
+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
@@ -332,6 +334,60 @@ 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,
@@ -544,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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geniee-inc/sfa-kit",
-  "version": "1.12.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';
@@ -33,6 +33,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 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';

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';
@@ -23,6 +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/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/provider/SfaClient.d.ts

@@ -14,8 +14,9 @@ import type { SfaApiMode, SfaBulkDeleteRow, SfaBulkRowResult, SfaBulkUpdateRow,
  * nothing about which rows had been written. It can go up only once a row
  * costs less, or those limits change.
  *
- * NOTE: public because a caller cannot batch without it, and kept next to the
- * check that enforces it so the two cannot disagree.
+ * NOTE: public because a caller cannot size its batches or its own warning
+ * without it, and kept next to the check that enforces it so the two cannot
+ * disagree.
  */
 export declare const SFA_BULK_MAX_ROWS = 25;
 /**
@@ -166,6 +167,47 @@ export declare class SfaConflictError extends SfaApiError {
     constructor(status: number, statusText: string, body: string, url: string, currentRecord: SfaRecord | null);
     static fromBody(status: number, statusText: string, body: string, url: string): SfaConflictError;
 }
+/**
+ * @description A bulk write refused before a request went out: nothing was
+ * selected, or more rows than the kit sends in one call.
+ *
+ * NOTE: `message` is for the log, like the rest of the kit's errors, and
+ * `userMessage` is what a page shows the reader — the same split the kit
+ * already makes between an error and the text in `FetchErrorState`. The page
+ * decides where to show it; the kit has no UI of its own.
+ *
+ * NOTE: a distinct class so a page recognises this without matching on the
+ * message. It is the one write failure a reader causes and can fix.
+ */
+export declare class SfaBulkRowCountError extends Error {
+    readonly submitted: number;
+    /** What a page shows the reader. `message` is the English text for the log. */
+    readonly userMessage: string;
+    /** The most rows one call sends, so a page can say it without importing it. */
+    readonly limit = 25;
+    /** @param submitted how many rows the caller tried to send */
+    constructor(submitted: number);
+}
+/**
+ * @description Thrown when the object offers no bulk writes at all: the
+ * endpoint answers 501.
+ *
+ * NOTE: told apart from other failures because waiting changes nothing. A
+ * page with no wording of its own says to try again later, which is the one
+ * thing that cannot work here — the operation is not implemented for this
+ * object, today or in an hour.
+ */
+export declare class SfaBulkUnsupportedError extends SfaApiError {
+    /** What a page shows the reader. `message` is the English text for the log. */
+    readonly userMessage: string;
+    /**
+     * NOTE: takes the response as it arrived, like every other error here, so
+     * the server's `detail` and `code` are read from the whole body. Building
+     * it from an `SfaApiError` instead would re-read a body already cut to
+     * `ERROR_BODY_MAX_LENGTH`, and a cut inside the JSON leaves nothing to read.
+     */
+    constructor(status: number, statusText: string, body: string, url: string);
+}
 /**
  * @description Thrown on 422 with code VALIDATION_FAILED. Exposes per-field
  * errors so the UI can highlight which fields need correction.

package/src/lib/provider/SfaClient.js

@@ -32,8 +32,9 @@ const BULK_REQUEST_TIMEOUT_MS = 60000;
  * nothing about which rows had been written. It can go up only once a row
  * costs less, or those limits change.
  *
- * NOTE: public because a caller cannot batch without it, and kept next to the
- * check that enforces it so the two cannot disagree.
+ * NOTE: public because a caller cannot size its batches or its own warning
+ * without it, and kept next to the check that enforces it so the two cannot
+ * disagree.
  */
 export const SFA_BULK_MAX_ROWS = 25;
 /**
@@ -310,6 +311,7 @@ export class SfaClient {
             const path = `/v1/objects/${enc(collection)}/records/${operation}`;
             const response = yield this.fetchWithBody('POST', path, { records }, {
                 timeoutMs: BULK_REQUEST_TIMEOUT_MS,
+                bulkUnsupportedOn501: true,
             });
             return normalizeBulkResults(yield response.json(), records.length);
         });
@@ -464,6 +466,11 @@ export class SfaClient {
                 if (response.status === 422) {
                     throw SfaValidationError.fromBody(response.status, response.statusText, text, url);
                 }
+                // NOTE: only the bulk endpoints answer 501, and only they can say what
+                // it means to the reader. A 501 elsewhere stays a plain SfaApiError
+                if (response.status === 501 && (options === null || options === void 0 ? void 0 : options.bulkUnsupportedOn501)) {
+                    throw new SfaBulkUnsupportedError(response.status, response.statusText, text, url);
+                }
                 throw new SfaApiError(response.status, response.statusText, text, url);
             }
             return response;
@@ -860,17 +867,14 @@ function parseConflictRecord(body) {
 /**
  * @description Guards the row count before a request goes out.
  *
- * NOTE: the API rejects the whole call with 422 when the array is empty or
- * longer than the limit, so a caller that over-sends loses every row. Saying
- * so here names the limit instead of surfacing a generic validation failure.
+ * NOTE: an empty array is rejected by the API with 422 for the whole call, and
+ * a selection over the kit's limit is refused before it can be sent at all.
+ * Either way the caller loses every row, so this names the limit and the count
+ * instead of leaving a generic validation failure to explain it.
  */
 function assertBulkRowCount(count) {
-    if (count === 0) {
-        throw new Error('A bulk write needs at least one row.');
-    }
-    if (count > SFA_BULK_MAX_ROWS) {
-        throw new Error(`A bulk write accepts at most ${SFA_BULK_MAX_ROWS} rows, got ${count}. ` +
-            'Split the selection into batches.');
+    if (count === 0 || count > SFA_BULK_MAX_ROWS) {
+        throw new SfaBulkRowCountError(count);
     }
 }
 /**
@@ -1112,6 +1116,65 @@ export class SfaConflictError extends SfaApiError {
         return new SfaConflictError(status, statusText, body, url, currentRecord);
     }
 }
+/**
+ * @description A bulk write refused before a request went out: nothing was
+ * selected, or more rows than the kit sends in one call.
+ *
+ * NOTE: `message` is for the log, like the rest of the kit's errors, and
+ * `userMessage` is what a page shows the reader — the same split the kit
+ * already makes between an error and the text in `FetchErrorState`. The page
+ * decides where to show it; the kit has no UI of its own.
+ *
+ * NOTE: a distinct class so a page recognises this without matching on the
+ * message. It is the one write failure a reader causes and can fix.
+ */
+export class SfaBulkRowCountError extends Error {
+    /** @param submitted how many rows the caller tried to send */
+    constructor(submitted) {
+        super(rowCountLogText(submitted));
+        this.submitted = submitted;
+        /** The most rows one call sends, so a page can say it without importing it. */
+        this.limit = SFA_BULK_MAX_ROWS;
+        this.name = 'SfaBulkRowCountError';
+        this.userMessage = rowCountReaderText(submitted);
+    }
+}
+/**
+ * @description Thrown when the object offers no bulk writes at all: the
+ * endpoint answers 501.
+ *
+ * NOTE: told apart from other failures because waiting changes nothing. A
+ * page with no wording of its own says to try again later, which is the one
+ * thing that cannot work here — the operation is not implemented for this
+ * object, today or in an hour.
+ */
+export class SfaBulkUnsupportedError extends SfaApiError {
+    /**
+     * NOTE: takes the response as it arrived, like every other error here, so
+     * the server's `detail` and `code` are read from the whole body. Building
+     * it from an `SfaApiError` instead would re-read a body already cut to
+     * `ERROR_BODY_MAX_LENGTH`, and a cut inside the JSON leaves nothing to read.
+     */
+    constructor(status, statusText, body, url) {
+        super(status, statusText, body, url);
+        /** What a page shows the reader. `message` is the English text for the log. */
+        this.userMessage = 'このオブジェクトでは一括操作を利用できません。';
+        this.name = 'SfaBulkUnsupportedError';
+    }
+}
+function rowCountLogText(submitted) {
+    if (submitted === 0)
+        return 'A bulk write needs at least one row.';
+    return (`A bulk write accepts at most ${SFA_BULK_MAX_ROWS} rows, ` +
+        `got ${submitted}. Split the selection into batches.`);
+}
+function rowCountReaderText(submitted) {
+    if (submitted === 0)
+        return '保存する行が選択されていません。';
+    return (`一度に保存できるのは ${SFA_BULK_MAX_ROWS} 件までです。` +
+        `選択されているのは ${submitted} 件です。` +
+        `選択を ${SFA_BULK_MAX_ROWS} 件以下に減らしてから保存してください。`);
+}
 /**
  * @description Thrown on 422 with code VALIDATION_FAILED. Exposes per-field
  * errors so the UI can highlight which fields need correction.

package/src/lib/version.d.ts

@@ -1 +1 @@
-export declare const SFA_KIT_VERSION = "1.12.0";
+export declare const SFA_KIT_VERSION = "1.13.0";

package/src/lib/version.js

@@ -1,3 +1,3 @@
 // このファイルは libs/sfa-kit/scripts/sync-version.cjs が生成する。
 // 手で編集しないこと。バージョンを上げるときは libs/sfa-kit/package.json を変更する。
-export const SFA_KIT_VERSION = '1.12.0';
+export const SFA_KIT_VERSION = '1.13.0';