@stapel/forms-react 0.1.0

package/src/i18n/keys.ts

@@ -0,0 +1,264 @@
+import type { I18nDictionary, I18nEngine } from "@stapel/core";
+import { FORMS_ERROR_CODES, formsErrorBundleEn } from "./generated/errors.gen.js";
+
+/**
+ * forms-react's own translation KEYS (frontend-standard §4.2): headless
+ * components never render literal strings — hosts resolve these via core's
+ * i18n engine (`useT`). Backend error codes flow through the SAME contour: a
+ * `StapelApiError.code` is already a key, so the default bundle below ships
+ * English fallbacks for the backend error codes (generated — all 75 of them
+ * since stapel-forms 0.2.0, including the stapel_attributes family) and the
+ * pair's own UI keys. All UI keys live under the `forms.` namespace.
+ *
+ * ── What is NOT an i18n key here ───────────────────────────────────────────
+ *
+ * A form's FIELD LABELS are admin-authored content carried in the schema
+ * (`FeatureDef.name`), not keys. They render verbatim in whatever language
+ * the admin typed them. Multi-language form CONTENT is a v2 fork (spec §10) —
+ * translating a customer's question text is a different problem from
+ * translating the pair's chrome, and pretending otherwise would put
+ * user-generated strings through a bundle that can never contain them.
+ */
+export const FORMS_I18N_KEYS = {
+  unknownError: "forms.error.unknown",
+
+  // ── fill: load + refusal states ──────────────────────────────────────────
+  fillLoading: "forms.fill.loading",
+  fillRetry: "forms.fill.retry",
+  fillLoadFailed: "forms.fill.load_failed",
+  fillNotFound: "forms.fill.not_found",
+  fillClosed: "forms.fill.closed",
+  fillSuperseded: "forms.fill.superseded",
+  fillUnsupportedField: "forms.fill.unsupported_field",
+  fillRequired: "forms.fill.required",
+  fillSubmit: "forms.fill.submit",
+  fillSubmitting: "forms.fill.submitting",
+  fillThanks: "forms.fill.thanks",
+  fillOptionalHint: "forms.fill.optional_hint",
+  fillBoolYes: "forms.fill.bool_yes",
+  fillBoolNo: "forms.fill.bool_no",
+  fillSelectPlaceholder: "forms.fill.select_placeholder",
+  fillUnlimited: "forms.fill.unlimited",
+
+  // ── fill: why the submit button is off ───────────────────────────────────
+  submitBlockedDone: "forms.submit.blocked.done",
+  submitBlockedInFlight: "forms.submit.blocked.in_flight",
+  submitBlockedUnsupported: "forms.submit.blocked.unsupported_kind",
+
+  // ── builder ──────────────────────────────────────────────────────────────
+  builderTitle: "forms.builder.title",
+  builderAddField: "forms.builder.add_field",
+  builderRemoveField: "forms.builder.remove_field",
+  builderMoveUp: "forms.builder.move_up",
+  builderMoveDown: "forms.builder.move_down",
+  builderFieldSlug: "forms.builder.field_slug",
+  builderFieldLabel: "forms.builder.field_label",
+  builderFieldRequired: "forms.builder.field_required",
+  builderFieldKind: "forms.builder.field_kind",
+  builderSave: "forms.builder.save",
+  builderPublish: "forms.builder.publish",
+  builderSaving: "forms.builder.blocked.saving",
+  builderPublishing: "forms.builder.blocked.publishing",
+  builderNoChanges: "forms.builder.blocked.no_changes",
+  builderEmptySchema: "forms.builder.blocked.empty_schema",
+  builderUnsavedDraft: "forms.builder.blocked.unsaved_draft",
+  builderBuilderLess: "forms.builder.builder_less",
+  builderKindUnregistered: "forms.builder.kind_unregistered",
+  builderKindsFailed: "forms.builder.kinds_failed",
+  builderNoKinds: "forms.builder.no_kinds",
+  builderUnsupportedConfig: "forms.builder.unsupported_config",
+  builderEmpty: "forms.builder.empty",
+  builderMetaTitle: "forms.builder.meta_title",
+  builderMetaDescription: "forms.builder.meta_description",
+  builderMetaSubmitLabel: "forms.builder.meta_submit_label",
+  builderMetaConfirmation: "forms.builder.meta_confirmation",
+  builderStateOpen: "forms.builder.state_open",
+  builderStateClosed: "forms.builder.state_closed",
+  builderStateDraft: "forms.builder.state_draft",
+  builderRotateLink: "forms.builder.rotate_link",
+  builderPublicLink: "forms.builder.public_link",
+
+  // ── responses ────────────────────────────────────────────────────────────
+  responsesTitle: "forms.responses.title",
+  responsesEmpty: "forms.responses.empty",
+  responsesLoadFailed: "forms.responses.load_failed",
+  responsesSubmittedAt: "forms.responses.submitted_at",
+  responsesRespondent: "forms.responses.respondent",
+  responsesAnonymous: "forms.responses.anonymous",
+  responsesVersion: "forms.responses.version",
+  responsesAllVersions: "forms.responses.all_versions",
+  responsesNext: "forms.responses.next",
+  responsesPrev: "forms.responses.prev",
+  responsesAtEnd: "forms.responses.blocked.at_end",
+  responsesAtStart: "forms.responses.blocked.at_start",
+  responsesDelete: "forms.responses.delete",
+  responsesDeleteConfirm: "forms.responses.delete_confirm",
+  responsesResend: "forms.responses.resend",
+  responsesResendSent: "forms.responses.resend_sent",
+  responsesResendOverride: "forms.responses.resend_override",
+  responsesResendOverrideHint: "forms.responses.resend_override_hint",
+  responsesExport: "forms.responses.export",
+  responsesExporting: "forms.responses.exporting",
+  responsesErased: "forms.responses.erased",
+  responsesDetail: "forms.responses.detail",
+  responsesClose: "forms.responses.close",
+
+  // ── form list ────────────────────────────────────────────────────────────
+  listTitle: "forms.list.title",
+  listEmpty: "forms.list.empty",
+  listLoadFailed: "forms.list.load_failed",
+  listCreate: "forms.list.create",
+  listNewTitle: "forms.list.new_title",
+  listSubmissionCount: "forms.list.submission_count",
+} as const;
+
+export type FormsI18nKey =
+  (typeof FORMS_I18N_KEYS)[keyof typeof FORMS_I18N_KEYS];
+
+/**
+ * The `error.400.feature_*` codes, read off the generated registry.
+ *
+ * stapel-forms 0.2.0 put the stapel_attributes family INTO its published
+ * contract (75 keys, 12 of them owned by `stapel_attributes`), so the English
+ * the pair used to hand-carry now arrives through `gen:errors` like every other
+ * backend code and has been deleted. This list stays only so the locale bundles
+ * can be checked against it — derived, never typed out, so it cannot fall
+ * behind the registry.
+ *
+ * The ru/es strings ARE still authored by the pair: attributes ships English
+ * only (it has no `translations/` directory), so those 12 keys can appear in no
+ * locale catalog until upstream localizes them — logged as stapel-forms
+ * MODULE.md §12.6. `gen:errors` runs for this module with
+ * `ERRORS_LOCALE_EXEMPT_OWNERS=stapel_attributes`, which is why the generated
+ * ru/es bundles are `Partial` and the authored strings below them are load-bearing.
+ */
+export const FEATURE_ERROR_KEYS: readonly string[] = FORMS_ERROR_CODES.filter(
+  (code) => code.startsWith("error.400.feature_")
+);
+
+/**
+ * English fallback bundle for forms-react UI keys + backend error codes.
+ * The generated `formsErrorBundleEn` (from stapel-forms's error registry,
+ * `pnpm gen:errors`) is spread FIRST so every backend `error.*` key has a
+ * fallback — a `StapelApiError.code` never renders as a raw key. The
+ * attributes family follows, then the pair's own copy.
+ */
+export const formsI18nBundleEn: I18nDictionary = {
+  // Backend error codes — generated en fallbacks (coverage by construction,
+  // and since stapel-forms 0.2.0 that includes the error.400.feature_* family
+  // the pair used to hand-carry).
+  ...formsErrorBundleEn,
+
+  // forms-react UI
+  "forms.error.unknown": "Something went wrong. Please try again.",
+
+  "forms.fill.loading": "Loading the form…",
+  "forms.fill.retry": "Try again",
+  "forms.fill.load_failed":
+    "We could not load this form. This is a problem on our side, not with your link.",
+  "forms.fill.not_found": "This form link is not valid.",
+  "forms.fill.closed": "This form is closed and is no longer accepting responses.",
+  "forms.fill.superseded":
+    "The form changed while you were filling it in. Please review your answers and submit again.",
+  "forms.fill.unsupported_field":
+    "This field type ({kind}) cannot be shown in this version of the app.",
+  "forms.fill.required": "Required",
+  "forms.fill.submit": "Submit",
+  "forms.fill.submitting": "Submitting…",
+  "forms.fill.thanks": "Thank you — your response has been recorded.",
+  "forms.fill.optional_hint": "Optional",
+  "forms.fill.bool_yes": "Yes",
+  "forms.fill.bool_no": "No",
+  "forms.fill.select_placeholder": "Choose…",
+  "forms.fill.unlimited": "Unlimited",
+
+  "forms.submit.blocked.done": "You have already submitted this form.",
+  "forms.submit.blocked.in_flight": "Submitting your response…",
+  "forms.submit.blocked.unsupported_kind":
+    "This form uses a field type this app cannot show ({kinds}), so it cannot be submitted safely.",
+
+  "forms.builder.title": "Form builder",
+  "forms.builder.add_field": "Add field",
+  "forms.builder.remove_field": "Remove field",
+  "forms.builder.move_up": "Move up",
+  "forms.builder.move_down": "Move down",
+  "forms.builder.field_slug": "Key",
+  "forms.builder.field_label": "Label",
+  "forms.builder.field_required": "Required",
+  "forms.builder.field_kind": "Type",
+  "forms.builder.save": "Save draft",
+  "forms.builder.publish": "Publish",
+  "forms.builder.blocked.saving": "Saving the draft…",
+  "forms.builder.blocked.publishing": "Publishing…",
+  "forms.builder.blocked.no_changes": "Nothing has changed since the last save.",
+  "forms.builder.blocked.empty_schema": "Add at least one field before publishing.",
+  "forms.builder.blocked.unsaved_draft":
+    "Save the draft first — publishing would release the previously saved version.",
+  "forms.builder.builder_less":
+    "This field type has no editable options here. Its configuration is authored through the draft API.",
+  "forms.builder.kind_unregistered":
+    "This deployment does not recognise this field type, so it cannot be configured or rendered here. The field is kept so it is not silently dropped from the schema.",
+  "forms.builder.kinds_failed":
+    "We could not load the list of field types, so no fields can be added right now.",
+  "forms.builder.no_kinds":
+    "This deployment has no configurable field types available.",
+  "forms.builder.unsupported_config":
+    "Some options of this field ({keys}) cannot be edited here yet.",
+  "forms.builder.empty": "This form has no fields yet.",
+  "forms.builder.meta_title": "Form title",
+  "forms.builder.meta_description": "Description",
+  "forms.builder.meta_submit_label": "Submit button text",
+  "forms.builder.meta_confirmation": "Confirmation message",
+  "forms.builder.state_open": "Open",
+  "forms.builder.state_closed": "Closed",
+  "forms.builder.state_draft": "Draft",
+  "forms.builder.rotate_link": "Rotate public link",
+  "forms.builder.public_link": "Public link",
+
+  "forms.responses.title": "Responses",
+  "forms.responses.empty": "No responses yet.",
+  "forms.responses.load_failed": "We could not load the responses.",
+  "forms.responses.submitted_at": "Submitted",
+  "forms.responses.respondent": "Respondent",
+  "forms.responses.anonymous": "Anonymous",
+  "forms.responses.version": "Version",
+  "forms.responses.all_versions": "All versions",
+  "forms.responses.next": "Next",
+  "forms.responses.prev": "Previous",
+  "forms.responses.blocked.at_end": "This is the last page.",
+  "forms.responses.blocked.at_start": "This is the first page.",
+  "forms.responses.delete": "Delete",
+  "forms.responses.delete_confirm": "Delete this response permanently?",
+  "forms.responses.resend": "Resend",
+  "forms.responses.resend_sent": "Sent to {count} destination(s).",
+  "forms.responses.resend_override": "Send to specific addresses instead",
+  "forms.responses.resend_override_hint":
+    "These replace the form's configured recipients for this one send.",
+  "forms.responses.export": "Export CSV",
+  "forms.responses.exporting": "Exporting… ({pages} page(s))",
+  "forms.responses.erased": "Erased",
+  "forms.responses.detail": "Response detail",
+  "forms.responses.close": "Close",
+
+  "forms.list.title": "Forms",
+  "forms.list.empty": "No forms in this workspace yet.",
+  "forms.list.load_failed": "We could not load the forms.",
+  "forms.list.create": "New form",
+  "forms.list.new_title": "Untitled form",
+  "forms.list.submission_count": "{count} response(s)",
+};
+
+/**
+ * Register forms-react's key bundle into a core i18n engine (call once at
+ * startup). Registers under the given locale (default `"en"`); a later
+ * `loadLocale` from stapel-translate can layer localized overrides on top.
+ *
+ * MERGE-PRIORITY CONVENTION (i18n-shipping.md §3): registration order is
+ * override priority — later wins per key. A HOST bundle registered AFTER this
+ * call overrides any pair text without a fork. The `ru`/`es` locales ship as
+ * the `./i18n/ru` and `./i18n/es` subpaths so a host that does not need them
+ * never carries the strings.
+ */
+export function registerFormsI18n(engine: I18nEngine, locale = "en"): void {
+  engine.registerBundle(locale, formsI18nBundleEn);
+}

package/src/i18n/ru.ts

@@ -0,0 +1,150 @@
+import type { I18nDictionary, I18nEngine } from "@stapel/core";
+import { formsErrorBundleRu } from "./generated/errors.ru.gen.js";
+
+export { formsErrorBundleRu } from "./generated/errors.ru.gen.js";
+
+/**
+ * Russian bundle for forms-react — the pair's `ru` locale, shipped as the
+ * `@stapel/forms-react/i18n/ru` subpath (i18n-shipping.md §2) so the locale is
+ * opt-in: hosts that don't register it never carry these strings (the main
+ * entry does not import this module — gated by size-limit + the bundle-purity
+ * test).
+ *
+ * Composition mirrors `formsI18nBundleEn`: the GENERATED backend error texts
+ * (from stapel-forms's `translations/errors.ru.json`, merged under
+ * stapel-core's cross-cutting catalogue — `pnpm gen:errors`) are spread first
+ * for coverage by construction; the 12 `stapel_attributes`-owned keys the generated
+ * bundle cannot carry follow (attributes ships English only — no
+ * `translations/` directory — so `gen:errors` runs with
+ * `ERRORS_LOCALE_EXEMPT_OWNERS=stapel_attributes` and emits a `Partial`
+ * bundle; upstream localization is stapel-forms MODULE.md §12.6); then the ru UI copy.
+ *
+ * PROVENANCE, stated rather than implied: stapel-forms' ru/es catalogues ship
+ * `origin=seed:authored` and are UNREVIEWED (backend delta note 10) — authored
+ * rather than machine-translated, but approved by nobody. The pair-authored
+ * strings below are the same grade. Neither is a claim of review.
+ */
+const ATTRIBUTES_ERRORS_RU: Readonly<Record<string, string>> = {
+  "error.400.feature_below_minimum": "Значение меньше минимального для «{feature}»",
+  "error.400.feature_above_maximum": "Значение больше максимального для «{feature}»",
+  "error.400.feature_not_in_options":
+    "Значение отсутствует среди допустимых вариантов для «{feature}»",
+  "error.400.feature_invalid_type": "Неверный тип значения для «{feature}»",
+  "error.400.feature_invalid_format": "Неверный формат значения для «{feature}»",
+  "error.400.feature_mandatory_missing": "Поле «{feature}» обязательно для заполнения",
+  "error.400.feature_unknown_type": "Неизвестный тип поля «{feature}»",
+  "error.400.feature_not_allowed": "Поле «{feature}» здесь недопустимо",
+  "error.400.feature_unknown": "Неизвестное поле «{feature}»",
+  "error.400.feature_invalid_config": "Неверная конфигурация поля «{feature}»",
+  "error.400.description_too_short": "Описание должно содержать не менее {min_length} символов",
+  "error.400.description_too_long": "Описание должно содержать не более {max_length} символов",
+};
+
+export const formsI18nBundleRu: I18nDictionary = {
+  ...formsErrorBundleRu,
+  ...ATTRIBUTES_ERRORS_RU,
+
+  "forms.error.unknown": "Что-то пошло не так. Попробуйте ещё раз.",
+
+  "forms.fill.loading": "Загрузка формы…",
+  "forms.fill.retry": "Повторить",
+  "forms.fill.load_failed":
+    "Не удалось загрузить форму. Проблема на нашей стороне, а не в вашей ссылке.",
+  "forms.fill.not_found": "Ссылка на форму недействительна.",
+  "forms.fill.closed": "Форма закрыта и больше не принимает ответы.",
+  "forms.fill.superseded":
+    "Форма изменилась, пока вы её заполняли. Проверьте ответы и отправьте ещё раз.",
+  "forms.fill.unsupported_field":
+    "Поле типа «{kind}» не может быть показано в этой версии приложения.",
+  "forms.fill.required": "Обязательно",
+  "forms.fill.submit": "Отправить",
+  "forms.fill.submitting": "Отправка…",
+  "forms.fill.thanks": "Спасибо — ваш ответ записан.",
+  "forms.fill.optional_hint": "Необязательно",
+  "forms.fill.bool_yes": "Да",
+  "forms.fill.bool_no": "Нет",
+  "forms.fill.select_placeholder": "Выберите…",
+  "forms.fill.unlimited": "Без ограничения",
+
+  "forms.submit.blocked.done": "Вы уже отправили эту форму.",
+  "forms.submit.blocked.in_flight": "Отправляем ваш ответ…",
+  "forms.submit.blocked.unsupported_kind":
+    "В форме есть поле типа, который приложение не умеет показывать ({kinds}), поэтому отправить её безопасно нельзя.",
+
+  "forms.builder.title": "Конструктор формы",
+  "forms.builder.add_field": "Добавить поле",
+  "forms.builder.remove_field": "Удалить поле",
+  "forms.builder.move_up": "Выше",
+  "forms.builder.move_down": "Ниже",
+  "forms.builder.field_slug": "Ключ",
+  "forms.builder.field_label": "Название",
+  "forms.builder.field_required": "Обязательное",
+  "forms.builder.field_kind": "Тип",
+  "forms.builder.save": "Сохранить черновик",
+  "forms.builder.publish": "Опубликовать",
+  "forms.builder.blocked.saving": "Сохраняем черновик…",
+  "forms.builder.blocked.publishing": "Публикуем…",
+  "forms.builder.blocked.no_changes": "С последнего сохранения ничего не изменилось.",
+  "forms.builder.blocked.empty_schema":
+    "Добавьте хотя бы одно поле перед публикацией.",
+  "forms.builder.blocked.unsaved_draft":
+    "Сначала сохраните черновик — иначе будет опубликована предыдущая сохранённая версия.",
+  "forms.builder.builder_less":
+    "У этого типа поля здесь нет редактируемых настроек. Его конфигурация задаётся через API черновика.",
+  "forms.builder.kind_unregistered":
+    "Эта установка не знает такой тип поля — его нельзя ни настроить, ни отобразить здесь. Поле сохранено, чтобы оно не исчезло из схемы незаметно.",
+  "forms.builder.kinds_failed":
+    "Не удалось загрузить список типов полей, поэтому сейчас нельзя добавить поле.",
+  "forms.builder.no_kinds":
+    "В этой установке нет доступных настраиваемых типов полей.",
+  "forms.builder.unsupported_config":
+    "Некоторые настройки этого поля ({keys}) пока нельзя изменить здесь.",
+  "forms.builder.empty": "В этой форме пока нет полей.",
+  "forms.builder.meta_title": "Название формы",
+  "forms.builder.meta_description": "Описание",
+  "forms.builder.meta_submit_label": "Текст кнопки отправки",
+  "forms.builder.meta_confirmation": "Сообщение после отправки",
+  "forms.builder.state_open": "Открыта",
+  "forms.builder.state_closed": "Закрыта",
+  "forms.builder.state_draft": "Черновик",
+  "forms.builder.rotate_link": "Обновить публичную ссылку",
+  "forms.builder.public_link": "Публичная ссылка",
+
+  "forms.responses.title": "Ответы",
+  "forms.responses.empty": "Ответов пока нет.",
+  "forms.responses.load_failed": "Не удалось загрузить ответы.",
+  "forms.responses.submitted_at": "Отправлен",
+  "forms.responses.respondent": "Респондент",
+  "forms.responses.anonymous": "Аноним",
+  "forms.responses.version": "Версия",
+  "forms.responses.all_versions": "Все версии",
+  "forms.responses.next": "Дальше",
+  "forms.responses.prev": "Назад",
+  "forms.responses.blocked.at_end": "Это последняя страница.",
+  "forms.responses.blocked.at_start": "Это первая страница.",
+  "forms.responses.delete": "Удалить",
+  "forms.responses.delete_confirm": "Удалить этот ответ безвозвратно?",
+  "forms.responses.resend": "Отправить повторно",
+  "forms.responses.resend_sent": "Отправлено получателям: {count}.",
+  "forms.responses.resend_override": "Отправить на другие адреса",
+  "forms.responses.resend_override_hint":
+    "Они заменяют настроенных получателей формы для этой отправки.",
+  "forms.responses.export": "Экспорт в CSV",
+  "forms.responses.exporting": "Экспорт… (страниц: {pages})",
+  "forms.responses.erased": "Стёрт",
+  "forms.responses.detail": "Ответ целиком",
+  "forms.responses.close": "Закрыть",
+
+  "forms.list.title": "Формы",
+  "forms.list.empty": "В этом рабочем пространстве пока нет форм.",
+  "forms.list.load_failed": "Не удалось загрузить формы.",
+  "forms.list.create": "Новая форма",
+  "forms.list.new_title": "Форма без названия",
+  "forms.list.submission_count": "Ответов: {count}",
+};
+
+/** Register the ru bundle. Call AFTER `registerFormsI18n` so it layers over
+ * the en floor (merge priority = registration order). */
+export function registerFormsI18nRu(engine: I18nEngine): void {
+  engine.registerBundle("ru", formsI18nBundleRu);
+}

package/src/index.ts

@@ -0,0 +1,184 @@
+/**
+ * `@stapel/forms-react` — the headless React pair for stapel-forms
+ * (frontend-standard §2). Business + state only, zero visual opinion; the
+ * antd skin lives behind the `./default` subpath so a host that renders its
+ * own visuals never carries it.
+ *
+ * ── The one-liner the owner asked for ──────────────────────────────────────
+ *
+ * ```tsx
+ * const runtime = createFormsRuntime({ baseUrl: "/forms/api/v1/" });
+ * <FormsProvider runtime={runtime}>
+ *   <StapelForm publicId="k3J…x9" />   // from @stapel/forms-react/default
+ * </FormsProvider>
+ * ```
+ *
+ * No session, no workspace id, no auth client: the two public routes are
+ * anonymous, so a marketing page can embed a form and nothing else.
+ *
+ * Layers: api → model → flows → headless → i18n. Generated surfaces (the
+ * typed schema, the error map, the manifest, llms.txt) are produced by the
+ * monorepo `gen:*` drivers from stapel-forms's own `docs/` artifacts and
+ * stand under drift gates.
+ */
+
+// ── api ──────────────────────────────────────────────────────────────────────
+export { createFormsApi } from "./api/formsApi.js";
+export type { FormsApi, FormsApiOptions } from "./api/formsApi.js";
+export type { Schemas } from "./api/types.js";
+export type {
+  BuiltinFieldKind,
+  ConfigFieldSpec,
+  FieldKind,
+  FieldKindCatalogue,
+  FormCreateRequest,
+  FormFieldDef,
+  FormPatchRequest,
+  FormRow,
+  FormSchema,
+  FormSchemaMeta,
+  FormSettings,
+  FormState,
+  FormVersion,
+  PublicForm,
+  PublishResult,
+  ResendRequest,
+  ResendResult,
+  Submission,
+  SubmissionListParams,
+  SubmitRequest,
+  SubmitResult,
+} from "./api/types.js";
+export { BUILTIN_FIELD_KINDS as ALLOWED_FIELD_KINDS } from "./api/types.js";
+
+/** The CSV export's raw transport — a header cursor and a file body are two
+ * things core's JSON client cannot carry (see `api/export.ts`). */
+export {
+  concatCsvPages,
+  exportSubmissionsCsv,
+  FORMS_NEXT_BEFORE_HEADER,
+} from "./api/export.js";
+export type { CsvExportPage, FormsRawTransport } from "./api/export.js";
+
+// ── flows ────────────────────────────────────────────────────────────────────
+// The flow-machine primitive lives in `@stapel/core` (one reviewed copy for
+// every pair — frontend-core-architecture §4b). Re-exported for ergonomics.
+export { createFlowMachine, useFlow, isErrorCode } from "@stapel/core";
+export type {
+  FlowMachine,
+  FlowMachineOptions,
+  FlowStateBase,
+  FlowError,
+} from "@stapel/core";
+export { toFlowError } from "./flows/errors.js";
+export { FORMS_FLOWS, flowEndpoints } from "./flows/registry.js";
+export type {
+  FormsFlowId,
+  FormsFlowSpec,
+  FlowEndpoint,
+} from "./flows/registry.js";
+
+// ── model (runtime wiring, query keys, context, hooks) ───────────────────────
+export { createFormsRuntime } from "./model/runtime.js";
+export type {
+  FormsRuntime,
+  CreateFormsRuntimeOptions,
+} from "./model/runtime.js";
+export {
+  FormsRuntimeContext,
+  useFormsRuntime,
+  useFormsApi,
+  useFormsAnalytics,
+} from "./model/context.js";
+export { formsQueryKeys } from "./model/queryKeys.js";
+
+export {
+  useFieldKinds,
+  useForm,
+  useForms,
+  useFormVersions,
+  usePublicForm,
+  useSubmission,
+  useSubmissions,
+} from "./model/queries.js";
+
+export {
+  useCreateForm,
+  useCsvExport,
+  useDeleteForm,
+  useDeleteSubmission,
+  usePublishForm,
+  useResendSubmission,
+  useRotateLink,
+  useSaveDraft,
+  useSetFormState,
+  useSubmitForm,
+  useUpdateForm,
+} from "./model/mutations.js";
+export type {
+  CsvExportBag,
+  FormRef,
+  ResendVariables,
+  SaveDraftVariables,
+  SetFormStateVariables,
+  SubmissionRef,
+  SubmitVariables,
+  UpdateFormVariables,
+} from "./model/mutations.js";
+
+// ── widgets (the open seam) ──────────────────────────────────────────────────
+export {
+  registerFormFieldWidget,
+  unregisterFormFieldWidget,
+  resolveFormFieldWidget,
+  registeredFormFieldKinds,
+} from "./widgets/registry.js";
+export type {
+  FormFieldWidget,
+  FormFieldWidgetProps,
+} from "./widgets/registry.js";
+
+export {
+  FEATURE_ERROR_CODES,
+  isBlank,
+  optionValues,
+  validateAnswers,
+  validateFieldValue,
+} from "./widgets/validate.js";
+
+// ── headless (renderless components) ─────────────────────────────────────────
+export { FormsProvider } from "./headless/FormsProvider.js";
+export { FormFill } from "./headless/FormFill.js";
+export type { FormFillBag } from "./headless/FormFill.js";
+export { FormBuilder } from "./headless/FormBuilder.js";
+export type { BuilderField, FormBuilderBag } from "./headless/FormBuilder.js";
+export { ResponsesTable } from "./headless/ResponsesTable.js";
+export type {
+  ResponseColumn,
+  ResponsesTableBag,
+  ResponsesView,
+} from "./headless/ResponsesTable.js";
+export { FormList } from "./headless/FormList.js";
+export type { FormListBag } from "./headless/FormList.js";
+
+// ── i18n ─────────────────────────────────────────────────────────────────────
+export {
+  FEATURE_ERROR_KEYS,
+  FORMS_I18N_KEYS,
+  formsI18nBundleEn,
+  registerFormsI18n,
+} from "./i18n/keys.js";
+export type { FormsI18nKey } from "./i18n/keys.js";
+
+// ── errors map (code → status/params/remediation/en; generated) ──────────────
+export {
+  FORMS_ERRORS,
+  FORMS_ERROR_CODES,
+  formsErrorBundleEn,
+  explainFormsError,
+} from "./i18n/errorsMap.js";
+export type {
+  FormsErrorCode,
+  FormsErrorSpec,
+  Remediation,
+} from "./i18n/errorsMap.js";

package/src/model/context.tsx

@@ -0,0 +1,28 @@
+import type { Context } from "react";
+import { createModuleContext } from "@stapel/core";
+import type { Analytics, ModuleContextKit } from "@stapel/core";
+import type { FormsApi } from "../api/formsApi.js";
+import type { FormsRuntime } from "./runtime.js";
+
+/**
+ * The wired FormsRuntime shared through React context by
+ * `<FormsProvider>`. Hooks in `model/` and `headless/` read the singletons
+ * from here. One reviewed copy of this plumbing lives in `@stapel/core`
+ * (`createModuleContext`, slim wave §21/S2); this module binds it under the
+ * pair's public names.
+ */
+const kit: ModuleContextKit<FormsRuntime> =
+  createModuleContext<FormsRuntime>("Forms");
+
+export const FormsRuntimeContext: Context<FormsRuntime | null> =
+  kit.RuntimeContext;
+
+export const useFormsRuntime: () => FormsRuntime = kit.useRuntime;
+
+export const useFormsApi: () => FormsApi = kit.useApi;
+
+export const useFormsAnalytics: () => Analytics | null = kit.useAnalytics;
+
+/** @internal Re-exported as `<FormsProvider>` from `headless/`. */
+export const ModuleProvider: ModuleContextKit<FormsRuntime>["Provider"] =
+  kit.Provider;