@timeax/form-palette 0.0.22 → 0.0.24

package/Readme.md

@@ -0,0 +1,428 @@
+### Form Palette: Developer Documentation (Core, Adapters, Variants)
+
+This guide documents how to use and extend the `packages/form-palette` package from a developer’s perspective. It covers the core runtime, the adapter system, and the variant layer (including the built-in Shadcn-based preset).
+
+Key source locations:
+- Core runtime and hooks: `src/core/*`
+- Adapters schema and registry: `src/schema/adapter.ts`, `src/core/adapter-registry.ts`, `src/adapters/*`
+- Field and input composition: `src/schema/field.ts`, `src/input/input-field.tsx`
+- Variant typing and registry: `src/schema/variant.ts`, `src/variants/*`, `src/presets/shadcn-variants/*`
+
+---
+
+### 1) Core
+
+#### 1.1 What the Core Provides
+The core coordinates form state, validation, submission, and UI control state. It exposes a `CoreContext` you access through hooks, and it manages fields and buttons that register into the form lifecycle.
+
+Primary entry points:
+- `CoreProvider` — wraps a form subtree with a live core instance.
+- `useCore()` / `useCoreContext()` — access the `CoreContext` API.
+- `useField()` — register a field with the core and get a typed, ergonomic API for value, errors, disabled/readOnly, and validation.
+- `input/input-field.tsx` — high-level field UI composition that binds a variant (visual control) to core state with field layout.
+
+Important types:
+- `CoreContext` in `src/schema/core.ts` — defines the public form API.
+- `Field` in `src/schema/field.ts` — runtime representation of a single form field.
+
+
+#### 1.2 Core Provider and Context
+- React context is declared in `src/core/context.ts` as `CoreContextReact`.
+- You must wrap your form with `CoreProvider` (see `src/core/core-provider.tsx`). Consumers then call `useCore()` or `useCoreContext()`.
+
+Minimal setup:
+```tsx
+import { CoreProvider } from "@/core/core-provider";
+import { useCore } from "@/core";
+
+export function MyForm() {
+  return (
+    <CoreProvider>
+      <Inner />
+    </CoreProvider>
+  );
+}
+
+function Inner() {
+  const core = useCore();
+  // core.values(), core.submit(), etc.
+  return null;
+}
+```
+
+
+#### 1.3 CoreContext API highlights (from `src/schema/core.ts`)
+Commonly used members:
+- `values(): ValuesResult<V>` — take a snapshot of values (respects `shared`, `alias`, and ignore rules).
+- `submit()` / `forceSubmit()` — trigger submit flow.
+- `validate(report?: boolean)` — run validation across registered fields.
+- `addField(field: Field)` — internal hook integration (handled by `useField`).
+- `error(name, message | bag)` — set error(s) at runtime.
+- `controlButton()` — core adjusts active submit button’s loading/disabled state during async flows.
+- `prepare(type?, route?, extra?, ignoreForm?, autoErr?)` / `go(data, ignoreForm?)` — lower-level orchestration used by adapters and submission.
+- `setValue(name, value)` / `reset(inputs?)` — programmatic state control.
+
+There is also a typed submit event (`SubmitEvent`) and callback props on providers (`BaseProps`, `CoreProps`) that let hosts hook into lifecycle events such as `onChange`, `onFinish`, `onSubmitted<K extends AdapterKey>(form, payload, resolve)` etc.
+
+
+#### 1.4 Fields and `useField`
+`useField` in `src/core/hooks/use-field.ts` is the main way a visual control binds to the core. It:
+- Registers a `Field` with the core and returns a live object with:
+  - `value`, `setValue(next, variant?)`
+  - `error`, `setError(message)`
+  - `required`, `disabled`, `readOnly` and their setters
+  - `loading`, `setLoading(loading)`
+  - identity and binding metadata (`name`, `bindId`, `bind`, `shared`, `alias`, `groupId`, `main`, `ignore`)
+  - `validate(report?)` delegating to field-level validation when provided
+- Coordinates with core-level `onChange` and per-field `onChange` based on core props such as `changeBefore` (see around lines 431–452 of `use-field.ts`).
+- Ensures the core can toggle the active submit button’s disabled state (`form.controlButton()`).
+
+Validation at field-level:
+- `UseFieldOptions<T>['validate']` returns `true | false | string` (or array in some higher-level paths).
+- Any returned message(s) are normalized for display.
+
+Identity and binding (`UseFieldOptions`):
+- `name?: string` — primary key in values and error bags.
+- `bindId?: string` / `bind?: string` — internal/external binding identifiers; used for advanced grouping and data flows.
+- `shared?: string` — nest values under a shared namespace (e.g., `profile.first_name`).
+- `groupId?: string`, `main?: boolean` — group controls (e.g., radios) and indicate a primary member.
+- `alias?: string` — map errors/names to a different label when desired.
+- `ignore?: boolean` — participate in registry without contributing to snapshots/validation when ignored.
+
+
+#### 1.5 Input composition: `input/input-field.tsx`
+`InputField` is a rich compositor that:
+- Looks up a variant by `variant` key (via `getVariant` from `src/variants`).
+- Builds the field layout using `FieldLayoutConfig` and optional variant-level `resolveLayout`.
+- Wires helper slots (label, sublabel, description, error placement) via primitives from `src/presets/ui/field`.
+- Normalizes validation results (`normalizeValidateResult`).
+
+Typical usage:
+```tsx
+import { InputField } from "@/input/input-field";
+
+<InputField
+  name="email"
+  variant="text"
+  label="Email"
+  description="We’ll never share your email"
+  required
+  // variant-specific props are forwarded
+/>
+```
+
+
+#### 1.6 Buttons
+Submit buttons can be registered with the core via imperatives that conform to `ButtonRef` (`src/schema/field.ts`):
+- `name: string`
+- Optional `loading`, `disabled` and setters `setLoading(v)`, `setDisabled(v)`
+
+The core toggles the active button during submit flows (success/error/finish) via `controlButton()`.
+
+
+#### 1.7 Errors and Validation
+- Field-level validation is provided via `useField` and variant-level validation can also be built in.
+- Form-level validation (`core.validate(report?)`) runs all participating fields and aggregates into an error bag.
+- Error rendering within `InputField` uses `FieldError` and layout slots.
+
+
+---
+
+### 2) Adapters
+
+Adapters abstract how submissions are executed (local resolve, Axios, Inertia, etc.). They are fully typed and pluggable at runtime.
+
+Key files:
+- Types: `src/schema/adapter.ts`
+- Registry: `src/core/adapter-registry.ts`
+- Built-ins: `src/adapters/axios.ts`, `src/adapters/inertia.ts`, index helpers in `src/adapters/index.ts`
+
+
+#### 2.1 Adapter Types (`src/schema/adapter.ts`)
+Core type concepts:
+- `AdapterCallbacks` — lifecycle hooks the adapter can invoke:
+  - `onSuccess(response)`
+  - `onError(error, updateRef)` (may ‘edit’ error/response context)
+  - `onFinish()`
+- `AdapterResult<Body>` — the runtime object an adapter factory returns with three operations:
+  - `submit(options?)` — trigger a submission side-effect
+  - `send(options?)` — return a promise resolved with an `ok`-typed payload
+  - `run(options?)` — a flexible operation; many adapters map it to `submit` or a hybrid
+- `AdapterFactory<Body>` / `NamedAdapterFactory<K>` — functions producing an `AdapterResult`
+- `Adapters` interface — the type-level registry that hosts/presets can augment with declaration merging to add their own keys and ok/error/payload shapes.
+
+Convenience type utilities:
+- `AdapterKey` — union of all adapter keys (e.g., `'local' | 'axios' | 'inertia' | ...'`).
+- `AdapterOk<K>`, `AdapterError<K>` — map adapter key to success/error payload types.
+- `AdapterSubmit<K>` — the type of what `onSubmitted(form, payload, resolve)` receives for a given adapter key.
+
+
+#### 2.2 Adapter Registry (`src/core/adapter-registry.ts`)
+- Maintains a simple in-memory registry of adapter factories keyed by `AdapterKey`.
+- Ships with a built-in `'local'` adapter (`localAdapter`) that:
+  - `send()` resolves `{ data: config.data }`
+  - `submit()`/`run()` are no-ops (core decides how to flow).
+- Public functions:
+  - `registerAdapter(key, factory)` — register/override an adapter.
+  - `getAdapter(key)` — retrieve a factory (or `undefined`).
+  - `hasAdapter(key)` — check presence.
+
+
+#### 2.3 Built-in Adapters and Helpers (`src/adapters/*`)
+- `axios` adapter factory: `createAxiosAdapter` (see `src/adapters/axios.ts`).
+- `inertia` adapter factory: `createInertiaAdapter` (see `src/adapters/inertia.ts`).
+- Helpers in `src/adapters/index.ts`:
+  - `registerAxiosAdapter()` — runtime check for `axios` and registers under key `'axios'`.
+  - `registerInertiaAdapter()` — dynamic import of `@inertiajs/react`, checks router `.visit`, registers under key `'inertia'`.
+  - `registerKnownAdapter(key: AdapterKey)` — switch over known keys.
+  - `registerAllAdapters()` — registers both axios and inertia.
+
+Registering at app bootstrap:
+```ts
+import { registerAxiosAdapter, registerInertiaAdapter } from "@/adapters";
+
+registerAxiosAdapter();
+await registerInertiaAdapter();
+```
+
+Using adapters in submit flow (high level):
+- The core’s submit logic (via `CoreProvider`) prepares a submission, locates the configured adapter by key, builds the adapter result with callbacks, and then calls `submit` or `send` depending on scenario.
+- On successful `send()`, the core will call your `onSubmitted<K>()` with the typed payload `AdapterSubmit<K>` (see `CoreProps` in `schema/core.ts`).
+
+Typing benefits:
+- If you extend `Adapters` via declaration merging, downstream code using `AdapterSubmit<'myAdapter'>` becomes strongly typed.
+
+
+---
+
+### 3) Variants
+
+Variants define the interactive control and its public props/value shape. The system separates:
+- Type-level registry describing value/props per variant key: `src/schema/variant.ts`
+- Runtime variant modules and preset implementations:
+  - `src/variants/core/*` — variant modules composing presets with defaults.
+  - `src/presets/shadcn-variants/*` — concrete Shadcn-based components for each variant.
+
+
+#### 3.1 Variant Types (`src/schema/variant.ts`)
+- `interface Variants` maps variant keys to `{ value, props }` pairs. This registry is used by:
+  - `InputFieldProps<K>` — to infer the correct `value` and `props` for a given variant key.
+  - `VariantModule<K>` — to type the runtime module providing a `Variant` component and optional layout resolution.
+- Built-in keys include: `text`, `number`, `phone`, `color`, `password`, `date`, `chips`, `textarea`, `toggle`, `toggle-group`, `radio`, `checkbox`, `select`, `multi-select`, `slider`, `keyvalue`, `custom`, `treeselect`, `file`.
+- All Shadcn prop types are re-exported by their files in `src/presets/shadcn-variants/*` and then aggregated into the `Variants` interface.
+
+
+#### 3.2 Variant Modules and Presets
+- A variant module is declared per key in `src/variants/core/*`. Example: `checkbox.tsx` wires the Shadcn checkbox preset and supplies defaults/layout:
+```ts
+export const checkboxModule: VariantModuleFor<"checkbox"> = {
+  variant: "checkbox",
+  Variant: ShadcnCheckboxVariant as unknown as React.ComponentType<
+    VariantBaseProps<CheckboxVariantPublicValue> & ShadcnCheckboxVariantPublicProps
+  >,
+  resolveLayout({ props }) {
+    if (props.single) return toggleLayoutDefaults;
+    return {};
+  },
+  meta: { label: "Checkbox", description: "...", tags: ["checkbox", "group", "boolean", "tri-state"] },
+};
+```
+- The `Variant` in a module is a React component receiving `VariantBaseProps<TValue>` plus the variant’s public props. The base props include:
+  - `field` (result of `useField`) with `value`, `setValue`, etc.
+  - `onChange(detail: ChangeDetail<TValue>)`
+  - `disabled`, `readOnly`, `required`, error, etc. (according to `VariantBaseProps` in `src/variants/shared`)
+- Presets implement the actual control UX (e.g., Shadcn Checkbox, Radio, Multiselect, File, TreeSelect, etc.) and are placed under `src/presets/shadcn-variants/*`.
+
+
+#### 3.3 Using Variants via InputField
+`InputField` takes `variant={key}` and forwards the key’s public props to the preset, wires `useField`, and renders a consistent Shadcn-based field chrome.
+
+Example — toggle and select:
+```tsx
+<InputField name="tos" variant="toggle" label="Accept Terms" required />
+
+<InputField
+  name="country"
+  variant="select"
+  label="Country"
+  options={[{ label: "USA", value: "US" }, { label: "Canada", value: "CA" }]}
+  placeholder="Select a country"
+/>
+```
+
+
+#### 3.4 Building a Custom Variant
+1) Extend the `Variants` interface if you’re adding a brand new key (optional if replacing internals only):
+```ts
+declare module "@/schema/variant" {
+  interface Variants {
+    mycontrol: VariantEntry<MyValue | undefined, MyControlPublicProps>;
+  }
+}
+```
+2) Create a preset component (e.g., in your own folder or mimic Shadcn preset style):
+```tsx
+function MyControlVariant(props: VariantBaseProps<MyValue> & MyControlPublicProps) {
+  const { field } = props; // field.value, field.setValue
+  // render your control
+  return <input value={field.value ?? ""} onChange={e => field.setValue(e.target.value)} />;
+}
+```
+3) Provide a variant module under `src/variants/core/mycontrol.tsx`:
+```ts
+export const mycontrolModule: VariantModuleFor<"mycontrol"> = {
+  variant: "mycontrol",
+  Variant: MyControlVariant,
+  resolveLayout({ defaults, overrides, props }) {
+    return { ...defaults, ...overrides };
+  },
+  meta: { label: "My Control", description: "Custom control.", tags: ["custom"] },
+};
+```
+4) Register the module with the variant registry (see how existing modules are exported/aggregated in `src/variants`). After registration, you can use `<InputField variant="mycontrol" ... />`.
+
+
+---
+
+### 4) Submission Lifecycle (Core × Adapters)
+A typical submit flow involves these steps:
+1. User triggers submit via a registered button or programmatically (`core.submit()`).
+2. Core collects values via `core.values()` and runs validation (`core.validate(true)`).
+3. Core prepares an adapter instance (key `local` by default or your configured key) using `getAdapter(key)`.
+4. Core calls `adapter.submit()` or `adapter.send()`. Adapters notify the core through `AdapterCallbacks`:
+  - `onSuccess(ok)` — core then calls your `onSubmitted<K>(form, payload, resolve)` from `CoreProps` with typed `AdapterSubmit<K>`.
+  - `onError(err, update)` — transform/record error; the core can populate error bags via `core.error(...)`.
+  - `onFinish()` — always runs; core toggles button states via `controlButton()`.
+
+Hosts can implement `onSubmitted<K extends AdapterKey>(form, payload, resolve)` to centralize success handling. The `resolve()` callback is provided to let you complete any external flows before the core finalizes.
+
+
+---
+
+### 5) Recipes
+
+#### 5.1 Basic form with a couple of fields
+```tsx
+import { CoreProvider } from "@/core/core-provider";
+import { InputField } from "@/input/input-field";
+import { useCore } from "@/core";
+
+export function SimpleForm() {
+  return (
+    <CoreProvider
+      // Optional: onSubmitted<K>(form, payload, resolve) {}
+      // Optional: onChange(form, values) {}
+    >
+      <Fields />
+    </CoreProvider>
+  );
+}
+
+function Fields() {
+  const core = useCore();
+
+  return (
+    <form onSubmit={(e) => { e.preventDefault(); core.submit(); }}>
+      <InputField name="email" variant="text" label="Email" required />
+      <InputField name="password" variant="password" label="Password" required />
+
+      <button type="submit">Sign in</button>
+    </form>
+  );
+}
+```
+
+#### 5.2 Register and use Axios adapter
+```ts
+// app bootstrap
+import { registerAxiosAdapter } from "@/adapters";
+registerAxiosAdapter();
+```
+```tsx
+<CoreProvider
+  onSubmitted={async (form, payload /* AdapterSubmit<'axios'> */, resolve) => {
+    console.log("Axios payload", payload);
+    resolve();
+  }}
+>
+  {/* fields */}
+</CoreProvider>
+```
+Adapter selection is typically part of the provider/config you pass when preparing a submit; see `CoreProps` and your submit orchestration where you choose the adapter key.
+
+#### 5.3 Custom field-level validation
+```tsx
+<InputField
+  name="username"
+  variant="text"
+  required
+  validate={(value, report) => {
+    if (!value) return report ? "Username is required" : false;
+    if (value.length < 3) return report ? "Minimum 3 characters" : false;
+    return true;
+  }}
+/>
+```
+
+#### 5.4 Programmatically set values and errors
+```ts
+const core = useCore();
+core.setValue("email", "demo@site.test");
+core.error("email", "Already taken");
+```
+
+
+---
+
+### 6) Gotchas and Best Practices
+- Always wrap consumers inside `<CoreProvider>`; `useCoreContext()` throws otherwise.
+- When integrating new adapters, register them at bootstrap (`registerAdapter(...)`).
+- Use `shared` to nest values under a parent key (e.g., `shared="profile"` with `name="first_name"` → `values.profile.first_name`).
+- Prefer `InputField` for consistent Shadcn layout and error rendering. If you build your own control, use `useField` directly and replicate the field chrome from `src/presets/ui/field`.
+- For grouped controls (radios, segmented toggles), use `groupId` and set `main` on the primary member when needed.
+- For adapter flows, handle `onSubmitted` in the provider to centralize success navigation or notifications.
+- The built-in `local` adapter is a no-op side-effect adapter that simply echoes `data`; useful for local validation or preview flows.
+
+
+---
+
+### 7) Extensibility Checklist
+- New adapter:
+  - Define `Adapters` augmentation with `ok/err/props` types.
+  - Implement `NamedAdapterFactory<K>` and return `{ submit, send, run }`.
+  - Call `registerAdapter<K>("key", factory)` at boot.
+- New variant:
+  - Optionally augment `Variants` with your key’s `value/props` types.
+  - Author a preset component with `VariantBaseProps<TValue>`.
+  - Create a variant module (with `meta`, optional `resolveLayout`).
+  - Export/register the module with the variant registry and use via `InputField`.
+
+
+---
+
+### 8) Where to Look in the Code
+- Core API and lifecycle:
+  - `src/schema/core.ts` — types for `CoreContext`, provider props, submit event.
+  - `src/core/core-provider.tsx` — the runtime engine orchestrating values/validation/submit.
+  - `src/core/hooks/use-field.ts` — field integration and state.
+  - `src/input/input-field.tsx` — UI composition and variant glue.
+- Adapters:
+  - `src/schema/adapter.ts` — adapter types and registry contracts.
+  - `src/core/adapter-registry.ts` — runtime registry + `localAdapter`.
+  - `src/adapters/index.ts` — axios/inertia registration helpers.
+  - `src/adapters/axios.ts`, `src/adapters/inertia.ts` — concrete factories.
+- Variants and presets:
+  - `src/schema/variant.ts` — variant key registry and types.
+  - `src/variants/core/*` — modules wiring preset → registry with defaults.
+  - `src/presets/shadcn-variants/*` — UI implementations.
+  - `src/presets/ui/*` — field chrome primitives (label, description, error, group, etc.).
+
+
+---
+
+### 9) Summary
+- Core manages field registry, validation, values, and submit orchestration; hooks provide a clean API to build inputs and drive UI.
+- Adapters encapsulate submission backends (local/axios/inertia/custom), offering typed payloads and lifecycle callbacks.
+- Variants define the shape and UI of controls. The Shadcn preset offers a full suite of ready-to-use components, while variant modules wire them into the registry and default layouts.
+
+With these pieces you can quickly build consistent forms, customize how data is submitted, and introduce new input types with a strongly-typed, extensible foundation.