@timeax/form-palette 0.0.24 → 0.0.26

package/Readme.md

@@ -1,428 +1,435 @@
-### Form Palette: Developer Documentation (Core, Adapters, Variants)
+### Form Palette: Build Forms with InputField (Consumer Guide)
 
-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).
+This guide shows how to build forms with @timeax/form-palette. It focuses on InputField usage, variants, and practical recipes taken from the playground’s App.tsx.
 
-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/*`
+If you just want to build forms, start here. Internals and source file locations are intentionally de‑emphasized.
 
 ---
 
-### 1) Core
+### Quick start
 
-#### 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.
+Install (from npm):
 
+```bash
+npm install @timeax/form-palette
+```
 
-#### 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 form:
 
-Minimal setup:
 ```tsx
-import { CoreProvider } from "@/core/core-provider";
-import { useCore } from "@/core";
+import { Form, InputField } from "@timeax/form-palette";
+
+export default function Example() {
+  function onSubmit(e: any) {
+    // e.form gives you programmatic access
+    // e.formData is the values snapshot
+    console.log("Submitted", e.formData);
+  }
 
-export function MyForm() {
   return (
-    <CoreProvider>
-      <Inner />
-    </CoreProvider>
+    <Form wrapped gap={12} onSubmit={onSubmit}>
+      <InputField name="email" label="Email" variant="text" required />
+      <InputField name="password" label="Password" variant="password" required />
+      <button type="submit">Submit</button>
+    </Form>
   );
 }
-
-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 basics
+
+Use one component for all input types by switching the variant key. InputField wires the value, validation, and a consistent label/description/error layout for you.
+
+Common props (apply to most variants):
+- name: unique field key
+- variant: which control to render (see Variant reference below)
+- label, sublabel: title and a small inline hint
+- description/helpText: helper copy under the control
+- errorText: force an error message (or rely on validation)
+- required, disabled, readOnly
+- icon, prefix, suffix, leadingControl, trailingControl: decorate the input content
+- contain: force the input and label to share a tile-like container
+- validate(value, report): return true | false | string for simple inline validation
+- onChange(detail): detail.value holds the new value; prevent default if you need to override
+
+Example with decorations and validation:
 
+```tsx
 <InputField
-  name="email"
+  name="username"
   variant="text"
-  label="Email"
-  description="We’ll never share your email"
-  required
-  // variant-specific props are forwarded
+  label="Username"
+  sublabel="public handle"
+  prefix="@"
+  validate={(value, report) => {
+    if (!value) return report ? "Required" : false;
+    if (value.length < 3) return report ? "Min 3 characters" : false;
+    return true;
+  }}
+  onChange={(e) => console.log("username:", e.value)}
 />
 ```
 
+Programmatic control during submit:
 
-#### 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()`.
+```tsx
+function onSubmit(e: any) {
+  // Programmatically set a value
+  e.form.inputs.getByName("email").setValue("demo@example.com");
+  console.log(e.formData);
+}
+```
 
+---
 
-#### 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.
+### Variant reference (what value they hold and unique props)
 
+Below are the built‑in variants with the props you’ll use most often. Examples mirror the playground App.tsx.
 
----
+Note on options: selection controls accept options as primitives ("US") or objects ({ label, value, ...extra }).
 
-### 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();
+1) text
+- Value: string | undefined
+- Nice extras: mask, slotChar, unmask, autoClear (phone-like masking); icon/prefix/suffix; searchable isn’t applicable here
+- Example:
+```tsx
+<InputField name="email" label="Email" variant="text" />
 ```
 
-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`).
+2) number
+- Value: number | undefined
+- Props: min, max, step, showButtons
+- Example:
+```tsx
+<InputField name="age" label="Age" variant="number" min={0} max={120} step={1} showButtons />
+```
 
-Typing benefits:
-- If you extend `Adapters` via declaration merging, downstream code using `AdapterSubmit<'myAdapter'>` becomes strongly typed.
+3) password
+- Value: string | undefined
+- Props: showToggle; strengthMeter; meterStyle="rules" | "bar" (depending on preset)
+- Example:
+```tsx
+<InputField name="pwd" label="Password" variant="password" showToggle strengthMeter meterStyle="rules" />
+```
 
+4) color
+- Value: string | undefined (hex or css color)
+- Props: showPreview, previewButtonClassName
+- Example:
+```tsx
+<InputField name="color" label="Favorite colour" variant="color" showPreview />
+```
 
----
+5) phone
+- Value: string | undefined
+- Typical usage uses masking controls the same way as text: mask, slotChar, unmask, autoClear
+- Example (from playground labeled "Phone"):
+```tsx
+<InputField
+  name="phone"
+  label="Phone"
+  variant="text" // or a dedicated phone variant if enabled in your build
+  mask="+99 99 999 999? x999"
+  slotChar="_"
+  autoClear
+/>
+```
 
-### 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"] },
-};
+6) textarea
+- Value: string | undefined
+- Usual textarea props like placeholder, rows, etc.
+- Example:
+```tsx
+<InputField name="bio" label="Bio" variant="textarea" description="Tell us about you" />
 ```
-- 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/*`.
 
+7) toggle
+- Value: boolean | undefined
+- Example:
+```tsx
+<InputField name="tos" variant="toggle" label="Accept Terms" required />
+```
 
-#### 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.
+8) toggle-group
+- Value: string | number | undefined (selected item)
+- Props: options (primitives or objects), layout/density sizing depending on preset
+
+9) radio
+- Value: string | number | undefined
+- Props:
+  - options: primitives or objects with { value, label, description?, disabled? }
+  - layout?: "list" | "grid" (default "list"); columns?: number (when layout="grid")
+  - size?: "sm" | "md" | "lg"; density?: "compact" | "comfortable" | "loose"
+  - You can also map custom item shapes via optionValue/optionLabel style mappers depending on preset
+- Example:
+```tsx
+<InputField
+  name="role"
+  label="Role"
+  variant="radio"
+  options={[
+    { value: "reader", label: "Reader" },
+    { value: "editor", label: "Editor" },
+  ]}
+/> 
+```
 
-Example — toggle and select:
+10) checkbox
+- Value: boolean | string[] | number[] depending on single vs group usage
+- Single boolean checkbox:
 ```tsx
-<InputField name="tos" variant="toggle" label="Accept Terms" required />
+<InputField variant="checkbox" label="Remember me" />
+```
+- Group example:
+```tsx
+<InputField
+  name="perms"
+  variant="checkbox"
+  label="Permissions"
+  options={[
+    { value: "read", label: "Read content" },
+    { value: "write", label: "Write content" },
+    { value: "delete", label: "Delete content" },
+  ]}
+/> 
+```
 
+- Extras:
+  - single?: boolean switches to single‑checkbox mode (value becomes boolean | undefined)
+  - tristate?: boolean enables an indeterminate state for single or per‑item
+  - layout?: "list" | "grid"; columns?: number (grid mode)
+  - size?: "sm" | "md" | "lg"; density?: "compact" | "comfortable" | "loose"
+
+11) select
+- Value: string | number | undefined
+- Props (high‑use):
+  - options: (string|number)[] | { label?, value?, description?, disabled?, icon?, ... }[]
+  - searchable?: boolean (inline search box)
+  - searchPlaceholder?: string (placeholder inside the search box)
+  - clearable?: boolean (show clear button)
+  - placeholder?: string
+  - autoCap?: boolean (capitalise label text)
+  - emptyLabel?: React.ReactNode (shown when there are no options)
+  - emptySearchText?: React.ReactNode (shown when search returns no results)
+  - optionLabel, optionValue, optionDescription, optionDisabled, optionIcon, optionKey: map/compute option pieces
+  - renderOption?: (ctx) => ReactNode (custom row rendering; per‑option render overrides this)
+- Example:
+```tsx
 <InputField
   name="country"
   variant="select"
   label="Country"
   options={[{ label: "USA", value: "US" }, { label: "Canada", value: "CA" }]}
   placeholder="Select a country"
+  searchable
+  clearable
 />
 ```
 
-
-#### 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):
+12) multi-select
+- Value: (string|number)[] | undefined
+- Props: same mapping props as select (optionLabel, optionValue, optionDescription, optionDisabled, optionIcon, optionKey)
+  - searchable?: boolean; searchPlaceholder?: string
+  - clearable?: boolean; placeholder?: React.ReactNode
+  - autoCap?: boolean
+  - emptyLabel?: React.ReactNode; emptySearchText?: React.ReactNode
+  - renderOption?: (ctx) => ReactNode (custom row rendering; per‑option render overrides this)
+- Example:
 ```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"] },
-};
+<InputField
+  name="tags"
+  label="Tags"
+  variant="multi-select"
+  options={["red", "green", "blue"]}
+/>
 ```
-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" ... />`.
 
+13) chips
+- Value: string[] | number[] | undefined
+- Free‑form or from options; often used to add/remove tokens
 
----
-
-### 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.
+14) treeselect
+- Value: (string|number)[] | string | number | undefined (single or multiple tree selection)
+- Option type: TreeSelectOption = { label, value, icon?, description?, children?: TreeSelectOption[] }
+- Example:
+```tsx
+import { TreeSelectOption } from "@timeax/form-palette/presets/shadcn-variants/tree-select-types";
 
+const regionOptions: TreeSelectOption[] = [
+  { label: "Africa", value: "africa", children: [{ label: "Nigeria", value: "ng" }] },
+  { label: "Europe", value: "europe" },
+];
 
----
+<InputField
+  name="regions"
+  label="Regions"
+  variant="treeselect"
+  options={regionOptions}
+/> 
+```
 
-### 5) Recipes
+- Props (high‑use):
+  - multiple?: boolean (default true). If false, single‑select behaviour.
+  - searchable?: boolean; searchPlaceholder?: string
+  - clearable?: boolean; placeholder?: React.ReactNode
+  - autoCap?: boolean
+  - optionLabel, optionValue, optionDescription, optionDisabled, optionIcon, optionKey
+  - emptyLabel?: React.ReactNode; emptySearchText?: React.ReactNode
+  - renderOption?: ({ item, selected, option, click }) => ReactNode
+  - renderValue?: ({ selectedItems, placeholder }) => ReactNode (custom trigger content)
+  - expandAll?: boolean; defaultExpandedValues?: (string|number)[]
+  - leafOnly?: boolean (only leaf nodes are selectable)
+  - mode?: "default" | "button"; when "button", you can provide a custom trigger and show a selected‑count badge
+
+15) slider
+- Value: number | [number, number] depending on range mode
+- Props: min, max, step; possibly range/multiple depending on preset
+
+16) file
+- Value: File | File[] | Custom file shape depending on configuration
+- Types: FileItem, CustomFileLoader, FileLike are exported from the preset if you need advanced control
+- Example (simple):
+```tsx
+<InputField name="avatar" label="Avatar" variant="file" />
+```
 
-#### 5.1 Basic form with a couple of fields
+17) keyvalue
+- Value: Record<string, string> | undefined
+- Use to capture arbitrary key/value pairs
+
+18) editor
+- Value: string | undefined (HTML or Markdown)
+- Requires host CSS import once in your app:
+  - import "@toast-ui/editor/dist/toastui-editor.css";
+- Props (high‑use):
+  - format?: "html" | "markdown" (stored value format; default "html")
+  - toolbar?: "default" | "none" | ToastToolbarItem[][]
+  - height?: string (e.g., "400px"), placeholder?: string
+  - editType?: "wysiwyg" | "markdown"; previewStyle?: "vertical" | "tab"
+  - pastePlainText?: boolean (force plain text on paste)
+- Example:
 ```tsx
-import { CoreProvider } from "@/core/core-provider";
-import { InputField } from "@/input/input-field";
-import { useCore } from "@/core";
+<InputField
+  name="content"
+  label="Content"
+  variant="editor"
+  format="markdown"
+  toolbar="default"
+  height="400px"
+/>
+```
 
-export function SimpleForm() {
-  return (
-    <CoreProvider
-      // Optional: onSubmitted<K>(form, payload, resolve) {}
-      // Optional: onChange(form, values) {}
-    >
-      <Fields />
-    </CoreProvider>
-  );
-}
+19) custom
+- Bring your own control but still benefit from InputField’s layout and validation chrome
 
-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 />
+### Recipes from the playground
 
-      <button type="submit">Sign in</button>
-    </form>
-  );
-}
+Masking a phone‑like input:
+```tsx
+<InputField
+  name="phone"
+  label="Phone"
+  variant="text"
+  mask="+99 99 999 999? x999"
+  slotChar="_"
+  autoClear
+  leadingControl={<span>Leading control</span>}
+  prefix="number: "
+/>
 ```
 
-#### 5.2 Register and use Axios adapter
-```ts
-// app bootstrap
-import { registerAxiosAdapter } from "@/adapters";
-registerAxiosAdapter();
-```
+Password with strength meter:
 ```tsx
-<CoreProvider
-  onSubmitted={async (form, payload /* AdapterSubmit<'axios'> */, resolve) => {
-    console.log("Axios payload", payload);
-    resolve();
-  }}
->
-  {/* fields */}
-</CoreProvider>
+<InputField
+  name="password"
+  label="Password"
+  variant="password"
+  placeholder="Enter your password"
+  strengthMeter
+  meterStyle="rules"
+/>
 ```
-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
+Selects and multi‑selects:
 ```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;
-  }}
+  name="country"
+  variant="select"
+  label="Country"
+  options={[{ label: "USA", value: "US" }, { label: "Canada", value: "CA" }]}
+  placeholder="Select a country"
+  searchable
+/>
+
+<InputField
+  name="languages"
+  variant="multi-select"
+  label="Languages"
+  options={["English", "French", "German"]}
 />
 ```
 
-#### 5.4 Programmatically set values and errors
-```ts
-const core = useCore();
-core.setValue("email", "demo@site.test");
-core.error("email", "Already taken");
+Tree select with icons and descriptions:
+```tsx
+<InputField name="regions" label="Regions" variant="treeselect" options={regionOptions} />
+```
+
+Single checkbox:
+```tsx
+<InputField variant="checkbox" label="Remember me" />
 ```
 
+Number with buttons:
+```tsx
+<InputField name="age" label="Age" variant="number" min={0} max={120} step={1} showButtons />
+```
 
 ---
 
-### 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.
+### Submitting the form
 
+Form wraps your fields and provides a submit event that carries both the values and utilities.
 
----
-
-### 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`.
+```tsx
+import { Form, InputField } from "@timeax/form-palette";
+
+function Example() {
+  function handleSubmit(e: any) {
+    // values snapshot
+    console.log(e.formData);
+    // programmatic API
+    e.form.inputs.getByName("email").setValue("this is nice");
+  }
 
+  return (
+    <Form wrapped onSubmit={handleSubmit}>
+      <InputField name="email" label="Email" variant="text" />
+      <button type="submit">Submit</button>
+    </Form>
+  );
+}
+```
 
 ---
 
-### 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.).
-
+### Tips and best practices
+- Prefer InputField over wiring controls by hand; it gives you consistent labels, descriptions, and error placement.
+- Use options as primitives for quick setups, or objects when you need description/disabled/icon per item.
+- Use validate for quick client checks; you can also set errorText manually.
+- For grouped controls (radios/checkbox groups), pass options; for a single boolean, omit options.
+- Keep labels short and place longer helper copy into description/helpText.
 
 ---
 
-### 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.
+### FAQ
+- Can I access values without submitting? Yes, via the programmatic API exposed in events like onChange at the form level, or by reading e.form.values() from handlers inside the form.
+- Can I bring my own input component? Yes. Use the "custom" variant or build a dedicated preset and still place it inside InputField to reuse layout and validation.
+- Do I need to register adapters? Not for basic local use. Adapters matter when you integrate with external routers or clients; see the package’s adapters folder if needed.
+
+---
 
-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.
+This document intentionally centers on how to use the package to build forms. For deeper internals and extension points, browse the source or the developer docs in the repository.