Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
// Extension form fields — let host-app code and plugins add fields to a
// built-in resource form (product, category, …) that hydrate from the fetched
// resource and persist through the form's own Save. The host form spreads its
// values into the update payload, so a registered field's value reaches the
// API without any save code on the extension side; the backend only needs to
// permit the attribute.
//
// The registry solves the hydration half: built-in forms reset their values
// from a mapper over the fetched resource (which knows nothing about
// extension fields), so each form merges `extensionFormValues(formKey,
// resource)` into every defaultValues/reset object. The rendering half is a
// slot widget binding an input via `useHostForm()`.
/** One extension field on a built-in resource form. */
export interface FormFieldRegistration<TResource = unknown> {
/**
* The form value key — also the API attribute name submitted on save
* (read/write symmetry: whatever the serializer exposes is what the
* controller permits).
*/
name: string
/**
* Seed the field's form value from the fetched resource. Receives `null`
* on create forms (no resource yet) — return the field's blank value.
*/
from: (resource: TResource | null) => unknown
}
const registrations = new Map<string, FormFieldRegistration[]>()
/**
* Registry of extension fields per built-in form. Form keys match the form's
* slot prefix — `'product'` for the product detail form, `'product.media'` and
* `'product.variant'` for the rows of its media and variant lists. Registered names
* must be unique per form; duplicates throw so two plugins can't silently
* fight over one attribute.
*/
export const formFields = {
register<TResource = unknown>(
formKey: string,
registration: FormFieldRegistration<TResource>,
): void {
const list = registrations.get(formKey) ?? []
if (list.some((r) => r.name === registration.name)) {
throw new Error(
`Form field "${registration.name}" is already registered on the "${formKey}" form.`,
)
}
registrations.set(formKey, [...list, registration as FormFieldRegistration])
},
/** Remove a registered field. No-op when absent. */
remove(formKey: string, name: string): void {
const list = registrations.get(formKey)
if (!list) return
registrations.set(
formKey,
list.filter((r) => r.name !== name),
)
},
}
/**
* Values for every extension field registered on `formKey`, seeded from
* `resource` (or blanks when `null`). Built-in forms merge this into their
* defaultValues and every hydration `reset(...)` so extension fields survive
* refetch-driven resets.
*/
export function extensionFormValues(
formKey: string,
resource: unknown | null,
): Record<string, unknown> {
const out: Record<string, unknown> = {}
for (const registration of registrations.get(formKey) ?? []) {
out[registration.name] = registration.from(resource)
}
return out
}
/**
* Current values of every extension field registered on `formKey`, read from
* live form state. Host forms spread this into their submit payload: the
* form's Zod schema only knows first-party fields (its parse strips unknown
* keys from the submitted values), so extension values are collected from
* `form.getValues(...)` instead — which also keeps them out of client-side
* schema validation. Their validation is the server's; a 422 maps back onto
* the field via `mapSpreeErrorsToForm`.
*/
export function extensionSubmitValues(
formKey: string,
form: { getValues: (name: string) => unknown },
): Record<string, unknown> {
const out: Record<string, unknown> = {}
for (const registration of registrations.get(formKey) ?? []) {
out[registration.name] = form.getValues(registration.name)
}
return out
}
/** Names of every extension field registered on `formKey`. */
export function extensionFieldNames(formKey: string): string[] {
return (registrations.get(formKey) ?? []).map((registration) => registration.name)
}
/**
* Extension field values carried by one row of a nested list — a media or
* variant row of the product form, registered under `'product.media'` /
* `'product.variant'`. Only keys the row actually holds are returned, so a
* row added after hydration (a fresh upload) sends nothing it never had.
*/
export function extensionRowValues(formKey: string, row: unknown): Record<string, unknown> {
if (!row || typeof row !== 'object') return {}
const out: Record<string, unknown> = {}
for (const name of extensionFieldNames(formKey)) {
if (name in row) out[name] = (row as Record<string, unknown>)[name]
}
return out
}
/** Test-only: clear the registry. Not exported from the package index. */
export function __resetFormFieldsRegistry(): void {
registrations.clear()
}