@stapel/forms-react 0.1.0

package/dist/widgets/validate.js

@@ -0,0 +1,173 @@
+/** The `error.400.feature_*` keys this mirror can raise — a subset of
+ * `stapel_attributes.errors.ATTRIBUTES_ERRORS`, listed so the i18n bundle can
+ * be checked against it. */
+export const FEATURE_ERROR_CODES = [
+    "error.400.feature_below_minimum",
+    "error.400.feature_above_maximum",
+    "error.400.feature_not_in_options",
+    "error.400.feature_invalid_type",
+    "error.400.feature_invalid_format",
+    "error.400.feature_mandatory_missing",
+];
+function featureError(field, code, extra = {}) {
+    return {
+        code,
+        // `field` is what the fleet's `useFieldError` routes on; `slug` and
+        // `feature` are what the attributes catalogue's message templates
+        // interpolate. The adapter keeps all three server-side (delta note 1), so
+        // the mirror does too.
+        params: {
+            field: field.slug,
+            slug: field.slug,
+            feature: field.name ?? field.slug,
+            ...extra,
+        },
+        status: 400,
+        message: undefined,
+        language: undefined,
+    };
+}
+function num(config, key) {
+    const raw = config[key];
+    return typeof raw === "number" && Number.isFinite(raw) ? raw : undefined;
+}
+/** The declared choice values of an options-bearing config, or `undefined`
+ * when the kind has none. Accepts both the bare-scalar and the
+ * `{value, label}` option shapes the attributes types allow. */
+export function optionValues(field) {
+    const raw = (field.config ?? {})["options"];
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    return raw.map((option) => option !== null && typeof option === "object" && "value" in option
+        ? option.value
+        : option);
+}
+/** True when the answer is "nothing was entered" — the one shape the
+ * mandatory rule fires on. An explicit `false` is an ANSWER for a `bool`, not
+ * an absence, which is why this is not a falsiness check. */
+export function isBlank(value) {
+    if (value === undefined || value === null)
+        return true;
+    if (typeof value === "string")
+        return value.trim().length === 0;
+    if (Array.isArray(value))
+        return value.length === 0;
+    return false;
+}
+/**
+ * Validate one answer against its field's config. Returns the mirrored
+ * refusal, or `undefined` when this side of the wire is satisfied.
+ *
+ * `header` fields are skipped outright: the engine regenerates a header's DAO
+ * from its config and REJECTS an answer to one (backend delta note 1), so a
+ * header has nothing to validate and must never be given a value.
+ */
+export function validateFieldValue(field, value) {
+    if (field.kind === "header")
+        return undefined;
+    const config = field.config ?? {};
+    if (isBlank(value)) {
+        return field.mandatory === true
+            ? featureError(field, "error.400.feature_mandatory_missing")
+            : // An optional field left blank is complete, and no later rule may
+                // fire on an absent value — a `minLength` must not turn "did not
+                // answer" into "answered too short".
+                undefined;
+    }
+    // ── choices ────────────────────────────────────────────────────────────
+    const options = optionValues(field);
+    if (options !== undefined && config["allowCustom"] !== true) {
+        const answers = Array.isArray(value) ? value : [value];
+        const stray = answers.find((answer) => !options.some((option) => option === answer));
+        if (stray !== undefined) {
+            return featureError(field, "error.400.feature_not_in_options", {
+                ref_value: stray,
+            });
+        }
+    }
+    // ── multi-select cardinality ───────────────────────────────────────────
+    if (field.kind === "select") {
+        const count = Array.isArray(value) ? value.length : 1;
+        const minSelected = num(config, "minSelected");
+        const maxSelected = num(config, "maxSelected");
+        if (minSelected !== undefined && count < minSelected) {
+            return featureError(field, "error.400.feature_below_minimum", {
+                min: minSelected,
+            });
+        }
+        if (maxSelected !== undefined && count > maxSelected) {
+            return featureError(field, "error.400.feature_above_maximum", {
+                max: maxSelected,
+            });
+        }
+        return undefined;
+    }
+    // ── numeric range ──────────────────────────────────────────────────────
+    if (field.kind === "int" || field.kind === "float") {
+        const asNumber = typeof value === "number" ? value : Number(value);
+        if (!Number.isFinite(asNumber)) {
+            return featureError(field, "error.400.feature_invalid_type");
+        }
+        if (field.kind === "int" && !Number.isInteger(asNumber)) {
+            return featureError(field, "error.400.feature_invalid_type");
+        }
+        const min = num(config, "min");
+        const max = num(config, "max");
+        if (min !== undefined && asNumber < min) {
+            return featureError(field, "error.400.feature_below_minimum", { min });
+        }
+        if (max !== undefined && asNumber > max) {
+            return featureError(field, "error.400.feature_above_maximum", { max });
+        }
+        return undefined;
+    }
+    // ── string length + pattern ────────────────────────────────────────────
+    if (field.kind === "string") {
+        const text = String(value);
+        const minLength = num(config, "minLength");
+        const maxLength = num(config, "maxLength");
+        if (minLength !== undefined && text.length < minLength) {
+            return featureError(field, "error.400.feature_below_minimum", {
+                min_length: minLength,
+            });
+        }
+        if (maxLength !== undefined && text.length > maxLength) {
+            return featureError(field, "error.400.feature_above_maximum", {
+                max_length: maxLength,
+            });
+        }
+        const pattern = config["pattern"];
+        if (typeof pattern === "string" && pattern.length > 0) {
+            let re;
+            try {
+                re = new RegExp(pattern);
+            }
+            catch {
+                // An admin-authored pattern that JS cannot compile (a Python-only
+                // construct) is NOT the respondent's problem: skip the mirror and
+                // let the server, which compiled it, be the one to refuse.
+                re = undefined;
+            }
+            if (re !== undefined && !re.test(text)) {
+                return featureError(field, "error.400.feature_invalid_format");
+            }
+        }
+        return undefined;
+    }
+    return undefined;
+}
+/**
+ * Validate a whole answer set. Returns `{slug: FlowError}` for the fields that
+ * failed — the exact shape `FormFillBag.fieldErrors` carries, so a server
+ * response can be merged into it without a translation step.
+ */
+export function validateAnswers(fields, values) {
+    const errors = {};
+    for (const field of fields) {
+        const error = validateFieldValue(field, values[field.slug]);
+        if (error !== undefined)
+            errors[field.slug] = error;
+    }
+    return errors;
+}
+//# sourceMappingURL=validate.js.map

package/dist/widgets/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/widgets/validate.ts"],"names":[],"mappings":"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"}

package/llms.txt

@@ -0,0 +1,124 @@
+# @stapel/forms-react 0.1.0
+
+Headless React flow pair for stapel-forms (contract >=0.2 <0.3) — business + state, zero visual opinion.
+Built on @stapel/core: typed client + StapelApiError envelope, auth token refresh,
+verification-403 interception, i18n engine, analytics facade, TanStack Query layer.
+
+## The one right way (do this, the rest is a review/lint smell)
+- No raw fetch/axios. The client is injected via <FormsProvider>/StapelConfigProvider;
+  every hook and flow already carries auth, refresh, and the error envelope.
+- Render errors, never try/catch them: a flow's state carries FlowError{code,params};
+  render `t(code, params)` and branch on `explainFormsError(code)` remediation.
+- Server state = the use* hooks (query layer); keys come only from formsQueryKeys.
+- User strings = i18n keys (registerFormsI18n); never string literals.
+- Sign-in UI = a headless flow component; copy it (shadcn-style) to restyle.
+
+## Layers
+api (typed client) · model (hooks, session) · flows (machines) · headless · i18n
+
+## Documented flows (flows.json — canonical id, steps, endpoints)
+
+## Operations (typed; use the named op, never a path string)
+Request/response schema names are in manifest.json + the generated types.
+Paths are relative to `/forms/api/v1/`.
+- forms_api_v1_field_kinds_retrieve: GET /field-kinds
+- forms_api_v1_forms_create: POST /forms
+- forms_api_v1_forms_destroy: DELETE /forms/{form_id}
+- forms_api_v1_forms_draft_update: PUT /forms/{form_id}/draft
+- forms_api_v1_forms_list: GET /forms
+- forms_api_v1_forms_partial_update: PATCH /forms/{form_id}
+- forms_api_v1_forms_publish_create: POST /forms/{form_id}/publish
+- forms_api_v1_forms_retrieve: GET /forms/{form_id}
+- forms_api_v1_forms_rotate_link_create: POST /forms/{form_id}/rotate-link
+- forms_api_v1_forms_state_create: POST /forms/{form_id}/state
+- forms_api_v1_forms_submissions_export_retrieve: GET /forms/{form_id}/submissions/export
+- forms_api_v1_forms_submissions_list: GET /forms/{form_id}/submissions
+- forms_api_v1_forms_versions_list: GET /forms/{form_id}/versions
+- forms_api_v1_public_retrieve: GET /public/{public_id}/
+- forms_api_v1_public_submissions_create: POST /public/{public_id}/submissions/
+- forms_api_v1_submissions_destroy: DELETE /submissions/{submission_id}
+- forms_api_v1_submissions_resend_create: POST /submissions/{submission_id}/resend
+- forms_api_v1_submissions_retrieve: GET /submissions/{submission_id}
+
+## Query hooks (server state; keys come only from the key factory)
+- useCreateForm (mutation) → createForm
+- useDeleteForm (mutation) → deleteForm
+- useDeleteSubmission (mutation) → deleteSubmission
+- useFieldKinds (query) → listFieldKinds
+- useForm (query) → getForm
+- useForms (query) → listForms
+- useFormVersions (query) → listVersions
+- usePublicForm (query) → getPublicForm
+- usePublishForm (mutation) → publish
+- useResendSubmission (mutation) → resendSubmission
+- useRotateLink (mutation) → rotateLink
+- useSaveDraft (mutation) → putDraft
+- useSetFormState (mutation) → setState
+- useSubmission (query) → getSubmission
+- useSubmissions (query) → listSubmissions
+- useSubmitForm (mutation) → submit
+- useUpdateForm (mutation) → patchForm
+
+## Errors (render t(code, params); UX from remediation)
+75 keys (full catalog: manifest.json §errors). By remediation: fix_input 41 · retry 14 · verify 7 · contact_support 6 · wait_and_retry 6 · reauthenticate 1.
+Param-bearing keys (interpolation slots matter):
+- error.400.description_too_long [400] → fix_input {max_length}
+- error.400.description_too_short [400] → fix_input {min_length}
+- error.400.feature_above_maximum [400] → fix_input {feature}
+- error.400.feature_below_minimum [400] → fix_input {feature}
+- error.400.feature_invalid_config [400] → fix_input {feature}
+- error.400.feature_invalid_format [400] → fix_input {feature}
+- error.400.feature_invalid_type [400] → fix_input {feature}
+- error.400.feature_mandatory_missing [400] → fix_input {feature}
+- error.400.feature_not_allowed [400] → fix_input {feature}
+- error.400.feature_not_in_options [400] → fix_input {feature}
+- error.400.feature_unknown [400] → fix_input {feature}
+- error.400.feature_unknown_type [400] → fix_input {feature}
+- error.400.field.blank [400] → fix_input {field}
+- error.400.field.does_not_exist [400] → fix_input {field}
+- error.400.field.invalid [400] → fix_input {field}
+- error.400.field.invalid_choice [400] → fix_input {field}
+- error.400.field.max_length [400] → fix_input {field,max_length}
+- error.400.field.max_value [400] → fix_input {field,max_value}
+- error.400.field.min_length [400] → fix_input {field,min_length}
+- error.400.field.min_value [400] → fix_input {field,min_value}
+- error.400.field.null [400] → fix_input {field}
+- error.400.field.required [400] → fix_input {field}
+- error.400.field.unique [400] → fix_input {field}
+- error.400.forms_duplicate_slug [400] → fix_input {slug}
+- error.400.forms_kind_not_allowed [400] → fix_input {kind}
+- error.429.rate_limit [429] → wait_and_retry {retry_after_minutes}
+
+## Analytics events (typed; defineEvent → events.json, drift-gated)
+- (no app defineEvent() in this pair — its analytic events are the
+  auto-instrumented flow funnels below)
+
+## Flow funnels (auto-instrumented: flow.<id>.<step> {phase})
+
+```tsx
+// Typed event + tracked() click (the one right way; §3.1).
+const planSelected = defineEvent({
+  name: "pricing.plan.selected",
+  description: "User picked a plan",
+  props: { plan: prop.oneOf(["free", "pro", "team"], "Plan code") },
+});
+const { tracked } = useTracked();
+<Button onClick={tracked(planSelected, { plan }, startCheckout)} />
+// A click that STEPS a flow machine is already instrumented — mark it
+// data-analytics="flow" instead; tracked() on top double-counts (§3.2).
+```
+
+## Demos (defineDemo → manifest.demos; compiled, linted, rendered examples)
+- forms.builder → <FormBuilder> [default]  demo/FormBuilder.demo.tsx
+- forms.fill → <FormFill> [default|closed|outage]  demo/FormFill.demo.tsx
+- forms.list → <FormList> [default]  demo/FormList.demo.tsx
+- forms.provider → <FormsProvider> [default]  demo/Forms.demo.tsx
+- forms.responses → <ResponsesTable> [default|empty]  demo/ResponsesTable.demo.tsx
+Each source file is the canonical usage snippet (open the default variant).
+
+## Snippets
+```tsx
+// Error rendering + remediation branch (one pattern for every pair).
+const r = explainFormsError(err.code); // 'wait_and_retry' | 'verify' | ...
+return <Alert action={r}>{t(err.code, err.params)}</Alert>;
+```