@timeax/form-palette 0.0.28 → 0.0.30

package/dist/variant-BPDyK780.d.mts

@@ -0,0 +1,4337 @@
+import * as React from 'react';
+import React__default, { RefObject, ComponentType } from 'react';
+import { z } from 'zod';
+import { M as Method, b as AdapterResult, A as AdapterKey, f as AdapterProps, i as AdapterSubmit } from './adapter-CvjXO9Gi.mjs';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { DayPicker } from 'react-day-picker';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import { VariantProps } from 'class-variance-authority';
+import * as SwitchPrimitive from '@radix-ui/react-switch';
+
+/**
+ * Imperative handle for a submit button registered with the core.
+ *
+ * This mirrors the legacy `ButtonRef` interface, but is aligned with the
+ * current CoreProvider implementation:
+ *
+ * - The core will try `setLoading(v)` / `setDisabled(v)` if available.
+ * - Otherwise, it will fall back to setting `loading` / `disabled` props.
+ */
+interface ButtonRef {
+    /**
+     * Logical name of the button.
+     *
+     * Used by the core runtime to track the "active" button
+     * and to map behaviours to a specific action.
+     */
+    name: string;
+    /**
+     * Loading flag. The core may read or assign this directly if
+     * no setter is provided.
+     */
+    loading?: boolean;
+    /**
+     * Disabled flag. The core may read or assign this directly if
+     * no setter is provided.
+     */
+    disabled?: boolean;
+    /**
+     * Optional setter used by the core to toggle loading.
+     */
+    setLoading?(v: boolean): void;
+    /**
+     * Optional setter used by the core to toggle disabled state.
+     */
+    setDisabled?(v: boolean): void;
+}
+/**
+ * Runtime representation of a single field registered with the core.
+ *
+ * This is a direct, type-safe evolution of the legacy `Field` interface
+ * from the old `types.ts`, updated to match the new core + binder flow.
+ */
+interface Field {
+    /**
+     * Primary field name, used in values, error bags, and schema mapping.
+     *
+     * May be omitted for purely bound/virtual fields that participate in
+     * binder flows but are not directly part of the value bag.
+     */
+    name?: string;
+    /**
+     * Internal binding identifier.
+     *
+     * Used by "bound" helpers (observe-bound-field, wait-for-bound-field)
+     * to locate shared/aliased fields without going through the name.
+     */
+    bindId?: string;
+    /**
+     * Optional explicit binding identifier.
+     * Use to bind to a specific field in a nested object that has bindId
+     */
+    bind?: string;
+    /**
+     * Ref to the underlying DOM element used for focus/scroll operations.
+     *
+     * Implementations typically point this at the outer wrapper of the field.
+     */
+    ref?: RefObject<HTMLElement> | null;
+    /**
+     * Whether this field is required.
+     *
+     * Variant-level and schema-level validation may use this.
+     */
+    required?: boolean;
+    /**
+     * Current error message for the field.
+     *
+     * Undefined or empty string means "no error".
+     */
+    error?: string;
+    /**
+     * Current value of the field, as seen by the core runtime.
+     *
+     * For formatted inputs, this may be the formatted representation.
+     */
+    value?: unknown;
+    /**
+     * Initial/default value for the field.
+     *
+     * This is typically the "un-touched" value coming from props or
+     * from a persisted value bag.
+     */
+    defaultValue?: unknown;
+    /**
+     * Original, unformatted value as first seen by the core.
+     *
+     * This allows callers to compare "what changed" relative to the
+     * original snapshot, independent of any display formatting.
+     */
+    originalValue?: unknown;
+    /**
+     * Whether this field is currently performing an async operation
+     * (e.g. remote validation).
+     */
+    loading?: boolean;
+    /**
+     * Optional group identifier used to group related fields together
+     * (e.g. radio groups, segmented inputs).
+     */
+    groupId?: string;
+    /**
+     * Optional alias for this field.
+     *
+     * Aliases allow mapping server error bags or schema keys that do
+     * not strictly match the `name` property.
+     */
+    alias?: string;
+    /**
+     * Marks this field as the "main" one in a group.
+     *
+     * Used by some variants/layouts to determine which field drives
+     * overall group state.
+     */
+    main?: boolean;
+    /**
+     * If true, this field will be ignored when building values or
+     * running certain validation flows.
+     */
+    ignore?: boolean;
+    /**
+     * Stable unique key (distinct from `name` and `bindId`).
+     *
+     * Used internally by registries and React lists.
+     */
+    key?: string;
+    /**
+     * Shared key for fields that share their value (e.g. custom views
+     * over the same underlying data).
+     *
+     * This is used by the core when building nested objects, e.g.:
+     *   shared = "profile", name = "first_name"
+     *   ⇒ values.profile.first_name
+     */
+    shared?: string;
+    /**
+     * Run validation for this field.
+     *
+     * @param report If true, the field should update its own error state;
+     *               if false, it may simply return whether it is valid.
+     * @returns `true` if the field is currently valid, `false` otherwise.
+     */
+    validate?(report?: boolean): boolean;
+    /**
+     * Optional hook used by the core or higher-level utilities to retrieve
+     * the current value of the field.
+     *
+     * If omitted, the core will fall back to the `value` property.
+     */
+    getValue?(): unknown;
+    /**
+     * Optional hook used by the core or higher-level utilities to update
+     * the current value of the field.
+     *
+     * If omitted, the core will fall back to mutating the `value` property.
+     */
+    setValue?(value: unknown): void;
+    /**
+     * Optional hook used by the core to reset the field back to its
+     * default/original value.
+     */
+    reset?(): void;
+    /**
+     * Optional hook used by the core to set or clear the field error.
+     *
+     * If omitted, the core will fall back to assigning the `error` property.
+     */
+    setError?(message?: string): void;
+    /**
+     * Optional hook called whenever the field value changes.
+     *
+     * Used by binder utilities to propagate changes across bound fields.
+     *
+     * @param value   New value.
+     * @param old     Previous value.
+     * @param source  Source tag responsible for the change
+     *                (e.g. "variant", "util", "paste", "programmatic").
+     */
+    onChange?(value: unknown, old: unknown, source: string): void;
+}
+
+/**
+ * Minimal surface needed for bound helpers.
+ *
+ * CoreContext already satisfies this, and FieldRegistry can be made to
+ * satisfy it as well (via getBind).
+ */
+interface BindHost<V extends Dict = Dict> {
+    getBind(id: string): Field | undefined;
+    controlButton?(): void;
+}
+
+/**
+ * BinderRegistry: bound-field utilities for a given host (CoreContext or FieldRegistry).
+ *
+ * - Hosts must satisfy BindHost (getBind + optional controlButton).
+ * - FieldRegistry already does (via getBind() we added).
+ * - CoreContext also does.
+ *
+ * You typically access this via:
+ *   form.inputs.binding  // where inputs is a FieldRegistry
+ */
+declare class BinderRegistry<V extends Dict = Dict> {
+    private readonly host;
+    constructor(host: BindHost<V>);
+    /** Raw field access. */
+    get(bindId: string): Field | undefined;
+    has(bindId: string): boolean;
+    /** Read current value. */
+    value<T = unknown>(bindId: string): T | undefined;
+    /** Set value (and trigger controlButton / onChange). */
+    set<T = unknown>(bindId: string, value: T, variant?: string): boolean;
+    /** Set error message on the bound field. */
+    error(bindId: string, msg: string): boolean;
+    /** Run the field’s own validate(). */
+    validate(bindId: string, report?: boolean): boolean;
+    /** Observe a bound field’s value/error and liveness. */
+    observe<T = unknown>(bindId: string, handler: (evt: {
+        exists: boolean;
+        field?: Field;
+        value?: T;
+        error?: string;
+    }) => void, pollMs?: number): () => void;
+    /** Wait for a bound field to appear. */
+    wait(bindId: string, timeoutMs?: number): Promise<Field>;
+}
+
+/**
+ * Central store for all fields registered with the core runtime.
+ *
+ * Goals:
+ * - Keep stable Field references (no cloning).
+ * - Prefer mounted fields for all “get” operations.
+ * - Prune stale/detached fields opportunistically.
+ */
+declare class FieldRegistry {
+    #private;
+    private list;
+    private getEl;
+    /** Mounted = has an element and that element is currently in the DOM. */
+    private isMounted;
+    /**
+     * Detached = has an element but it is NOT currently in the DOM.
+     * Note: if ref.current is null, we treat it as “unknown” (do NOT prune).
+     */
+    private isDetached;
+    /** Mounted-first stable ordering (does not mutate input). */
+    private sortMountedFirst;
+    /** Prefer the first mounted candidate; else fall back to first candidate. */
+    private pickPreferred;
+    /**
+     * Remove detached fields.
+     *
+     * IMPORTANT: We only remove entries that have a non-null ref.current AND are
+     * not in the DOM. We do not remove “unknown” (null-ref) fields because they
+     * may be in the process of mounting.
+     */
+    private pruneDetached;
+    /**
+     * Remove detached fields that conflict with an incoming field by identifier.
+     * This prevents stale “same-name / same-bindId / same-groupId” entries from
+     * hijacking lookups.
+     */
+    private pruneDetachedConflicts;
+    /**
+     * Whether this field should be tracked at all.
+     *
+     * We require at least one of: name, bindId, groupId.
+     */
+    hasIdentifier(field: Field): boolean;
+    /**
+     * Add a field to the registry if it has an identifier.
+     *
+     * Rules:
+     * - Opportunistically prune detached fields.
+     * - Prune detached conflicts (same name/bindId/groupId) before adding.
+     * - If the same field instance is already tracked, ignore.
+     * - If the same key already exists (rare), prefer mounted; otherwise replace.
+     */
+    add(field: Field): void;
+    /**
+     * Remove a field from the registry.
+     */
+    remove(field: Field): void;
+    /**
+     * Clear all tracked fields.
+     */
+    clear(): void;
+    /**
+     * All fields tracked by this registry (mounted-first).
+     */
+    all(): Field[];
+    /** All fields that have a non-empty name (mounted-first). */
+    getAllNamed(): Field[];
+    /** All fields that have a bindId (mounted-first). */
+    getAllBound(): Field[];
+    /** All fields that have a groupId (mounted-first). */
+    getAllGrouped(): Field[];
+    /**
+     * First field with a given name (exact, trimmed match).
+     *
+     * Behaviour:
+     * - Prefer a field whose ref is currently in the DOM.
+     * - If none are mounted, fall back to the first matching field.
+     */
+    getByName(name: string): Field | undefined;
+    /**
+     * All fields with a given name (exact, trimmed match), mounted-first.
+     */
+    getAllByName(name: string): Field[];
+    /** First field with the given groupId (prefer mounted). */
+    getByGroupId(id: string): Field | undefined;
+    /** All fields with the given groupId (mounted-first). */
+    getAllByGroupId(id: string): Field[];
+    /**
+     * All fields that share the given bindId (mounted-first).
+     */
+    getAllByBind(id: string): Field[];
+    /**
+     * First field with the given bindId (prefer mounted).
+     */
+    getByBind(id: string): Field | undefined;
+    getBind(id: string): Field | undefined;
+    get binding(): BinderRegistry;
+}
+
+/**
+ * Generic dictionary type used throughout the core.
+ *
+ * This matches the legacy Dict<T> from the old types.ts.
+ */
+type Dict<T = unknown> = Record<string, T>;
+/**
+ * If a Zod schema is present, infer the values from that schema;
+ * otherwise use the fallback V type. Ensured to be a Dict so it
+ * can safely be used as CoreContext's generic argument.
+ */
+type InferFromSchema<S, V extends Dict> = S extends z.ZodType ? z.infer<S> & Dict : V;
+/**
+ * Event object passed to onSubmit, matching the legacy SubmitEvent
+ * but kept transport-agnostic. The host decides how route/method/xhr
+ * are interpreted and which adapter is used.
+ *
+ * @template TValues Shape of the outbound data for this submit event.
+ */
+type SubmitEvent<TValues extends Dict, K extends AdapterKey> = {
+    /**
+     * Prevent the default submit behavior.
+     *
+     * In practice this prevents the core from continuing with its
+     * normal submit/prepare flow.
+     */
+    preventDefault(): void;
+    /**
+     * Mutate the outbound data just before it is used.
+     *
+     * The callback may return a new data object or mutate in-place.
+     */
+    editData(cb: (data: TValues) => TValues | void): void;
+    /**
+     * Override the config for this adapter submission only.
+     *
+     * The core itself does not enforce any semantics here; the host
+     * is expected to interpret this when wiring submissions.
+     */
+    setConfig(props: Partial<AdapterProps<K>>): void;
+    setConfig(key: keyof AdapterProps<K>, value: any): void;
+    /**
+     * The button that triggered this submit, if any.
+     */
+    button?: ButtonRef;
+    /**
+     * The current outbound data snapshot (after any internal merges).
+     */
+    readonly formData: TValues;
+    /**
+     * The core context associated with this submit event.
+     */
+    form: CoreContext<TValues>;
+    /**
+     * If set to false, the core will abort the submit flow after
+     * this handler returns.
+     */
+    continue: boolean;
+};
+/**
+ * Shared base props for the core runtime, matching the spirit of
+ * the legacy BaseProps, but transport-agnostic.
+ *
+ * @template V Shape of the underlying value map (pre-schema).
+ * @template S Optional Zod schema type.
+ */
+type BaseProps$7<V extends Dict, S extends z.ZodType | undefined, K extends AdapterKey> = {
+    /**
+     * Field names that should be ignored when building diffs or snapshots.
+     * Useful for excluding secrets like passwords from logs.
+     */
+    exceptions?: string[];
+    /**
+     * Whether the core should persist values to the provided valueBag.
+     */
+    persist?: boolean;
+    /**
+     * Optional logical name for the core instance.
+     */
+    name?: string;
+    /**
+     * If true, a button may be automatically marked as "active" when
+     * certain changes occur.
+     */
+    activateButtonOnChange?: boolean;
+    /**
+     * Called whenever a field changes.
+     *
+     * current is the field that changed; options carries any
+     * variant-specific metadata.
+     */
+    onChange?(form: CoreContext<InferFromSchema<S, V>>, current: Field, options: Dict): void;
+    /**
+     * Called when the overall values snapshot is considered "updated".
+     */
+    onUpdate?(values: InferFromSchema<S, V>): void;
+    /**
+     * If true, onChange may run before certain internal updates.
+     */
+    changeBefore?: boolean;
+    /**
+     * Optional ref to the core context instance, for imperative access.
+     */
+    formRef?: React__default.MutableRefObject<CoreContext<InferFromSchema<S, V>> | null>;
+    /**
+     * Initial value bag for hydration / persistence.
+     */
+    valueBag?: InferFromSchema<S, V>;
+    /**
+     * Optional hook used to transform a single value as it is being
+     * persisted or fed into the core.
+     */
+    valueFeed?: <K extends keyof InferFromSchema<S, V>>(name: K, value: InferFromSchema<S, V>[K], form: CoreContext<InferFromSchema<S, V>>) => InferFromSchema<S, V>[K] | undefined;
+    /**
+     * Called at the end of certain flows (legacy "finish" hook).
+     *
+     * Receives the core context so you can read values, errors, etc.
+     */
+    onFinish?(form: CoreContext<InferFromSchema<S, V>>): void;
+    /**
+     * Called after the core initializes.
+     */
+    init?(form: CoreContext<InferFromSchema<S, V>>): void;
+    /**
+     * Intercepts the submit event before the core proceeds.
+     *
+     * You can:
+     * - mutate data,
+     * - change route/method/xhr flags,
+     * - abort by setting e.continue = false.
+     */
+    onSubmit?<T extends Dict = InferFromSchema<S, V>>(e: SubmitEvent<T, K>): Promise<void> | void;
+    /**
+     * Optional Zod schema used for validation and value inference.
+     */
+    schema?: S;
+};
+/**
+ * Public core props, adapter-centric.
+ *
+ * - The library defines a built-in 'local' adapter flavour.
+ *   AdapterSubmit<'local'> is `{ data: unknown }`.
+ * - Hosts can extend the Adapters interface (schema/adapter.ts) to add
+ *   their own adapter flavours (axios, inertia, etc.) and then use
+ *   those keys here.
+ *
+ * @template V Shape of the underlying value map (pre-schema).
+ * @template S Optional Zod schema type.
+ * @template K Adapter key; defaults to 'local'.
+ */
+type CoreProps<V extends Dict, S extends z.ZodType | undefined, K extends AdapterKey = "local"> = BaseProps$7<V, S, K> & AdapterProps<K> & {
+    /**
+     * Which adapter flavour this core instance should use.
+     *
+     * - 'local' (default) → library-defined local submission (no URL/method semantics).
+     * - extended keys      → host-defined adapters via Adapters augmentation.
+     */
+    adapter?: K;
+    /**
+     * Called after a submission completes. The payload type is derived from
+     * the selected adapter key via the adapter registry:
+     *
+     *   AdapterSubmit<'local'> → { data: unknown }
+     *   AdapterSubmit<'axios'> → host-defined type, etc.
+     */
+    onSubmitted?(form: CoreContext<InferFromSchema<S, V>>, payload: AdapterSubmit<K>, resolve?: () => void): void | Promise<void>;
+};
+/**
+ * Backwards-compatible alias for legacy naming, if you want it.
+ */
+type FormProps<V extends Dict, S extends z.ZodType | undefined, K extends AdapterKey = "local"> = CoreProps<V, S, K>;
+/**
+ * Result of a submit operation: values + validity flag.
+ */
+type ValuesResult<V extends Dict> = {
+    values: V;
+    valid: boolean;
+};
+/**
+ * Query API for fields, similar to DOM helpers but scoped
+ * to the current form instance.
+ *
+ * "id" here refers to the field's groupId.
+ */
+interface InputStore {
+    /** All registered inputs (with at least one identifier). */
+    all(): Field[];
+    /** All inputs that have a non-empty name. */
+    getAllNamed(): Field[];
+    /** All inputs that have a bindId. */
+    getAllBound(): Field[];
+    /** All inputs that have a groupId. */
+    getAllGrouped(): Field[];
+    /** First field matching an exact name. */
+    getByName(name: string): Field | undefined;
+    /** All fields matching an exact name. */
+    getAllByName(name: string): Field[];
+    /** First field with this groupId. */
+    getById(id: string): Field | undefined;
+    /** All fields with this groupId. */
+    getAllById(id: string): Field[];
+    /** First bound field with this bindId (prefers mounted fields). */
+    getByBind(id: string): Field | undefined;
+    /** All fields that share this bindId. */
+    getAllByBind(id: string): Field[];
+}
+/**
+ * Core runtime context, renamed from the legacy FormContext.
+ *
+ * @template V Shape of the values object produced by this core instance.
+ */
+interface CoreContext<V extends Dict> {
+    /**
+     * Compute the current values snapshot from registered fields.
+     */
+    values(): V;
+    /**
+     * Run validation and return the values + validity flag.
+     */
+    submit(): ValuesResult<V>;
+    /**
+     * Lookup a field by its binding id.
+     */
+    getBind(id: string): Field | undefined;
+    /**
+     * Run validation across fields.
+     *
+     * @param report If true, fields should update their own error states.
+     * @returns true if all fields are valid, false otherwise.
+     */
+    validate(report?: boolean): boolean;
+    /**
+     * Register a new field with the core.
+     */
+    addField(field: Field): void;
+    /**
+     * Generic internal bucket for arbitrary metadata.
+     */
+    bucket: Dict;
+    /**
+     * Set a single field error or map an error bag.
+     */
+    error(name: string, msg: string): void;
+    error(bag: Record<string, string>): void;
+    /**
+     * Re-run button control logic (which button is active/disabled etc.).
+     */
+    controlButton(): void;
+    /**
+     * Prepare an adapter-backed request.
+     *
+     * This mirrors the legacy prepare method:
+     * - Builds a payload from values + extra.
+     * - May run validation / beforeSubmit hooks.
+     * - Returns an adapter result or undefined if aborted.
+     *
+     * The concrete adapter wiring is the host's responsibility.
+     */
+    prepare(type: Method, route: string, extra?: Partial<V>, ignoreForm?: boolean, autoErr?: boolean): Promise<AdapterResult<any> | undefined>;
+    /**
+     * Persist values to a provided data object, optionally transforming
+     * values via the feed function.
+     */
+    persist(data: Partial<V>, feed?: (name: string, value: unknown, original: unknown) => unknown): void;
+    /**
+     * Imperatively set a single value by field name.
+     */
+    setValue(name: string, value: unknown): void;
+    /**
+     * Kick off a submit flow using optional extra data.
+     */
+    go(data?: Partial<V>, ignoreForm?: boolean): void;
+    /**
+     * Reset specific inputs by name.
+     */
+    reset(inputs: string[]): void;
+    /**
+     * Register the current active button.
+     */
+    set button(v: ButtonRef);
+    /**
+     * Force a submit regardless of validation state.
+     */
+    forceSubmit(): Promise<void>;
+    /**
+     * All registered fields.
+     */
+    readonly fields: Field[];
+    /**
+     * Effective core props at runtime, excluding internal-only fields.
+     *
+     * Note: the adapter key parameter is erased here (set to any) because
+     * the runtime does not need the specific key for structural typing;
+     * hosts can still use more precise generics at the component level.
+     */
+    readonly props: Omit<CoreProps<V, z.ZodType | undefined, any>, "formRef" | "valueBag">;
+    /**
+     * Mark a button as active by name.
+     */
+    setActiveButton(name: string): void;
+    /**
+     * Return uncaught messages (errors that could not be mapped to a field).
+     *
+     * Typically used by an error strip component.
+     */
+    getUncaught(): readonly string[];
+    /**
+     * Field-query "DOM" for this form.
+     *
+     * Example:
+     *   const email = form.inputs.getByName("email");
+     *   const phoneFields = form.inputs.getAllById("phone-group");
+     *   const bound = form.inputs.getByBind("shipping");
+     */
+    inputs: Omit<FieldRegistry, "add" | "remove">;
+    /**
+     * Checks if the form values have changed
+     */
+    isDirty(): boolean;
+}
+
+/**
+ * Size hint for field variants.
+ *
+ * Presets can interpret these however they like (font size, padding, etc.).
+ */
+type FieldSize = "sm" | "md" | "lg";
+/**
+ * Density hint for field variants.
+ *
+ * - "compact"     → tight vertical spacing
+ * - "comfortable" → default spacing
+ * - "loose"       → extra breathing room
+ */
+type FieldDensity = "compact" | "comfortable" | "loose";
+/**
+ * Logical source of a change event.
+ *
+ * Variants and utilities can tag changes to help the host reason
+ * about where a value came from.
+ */
+type ChangeSource = "variant" | "paste" | "programmatic" | "util" | (string & {});
+/**
+ * Additional context passed along with value changes.
+ */
+interface ChangeDetail<TMeta = unknown, TRaw = unknown> {
+    /**
+     * Logical source for this change.
+     */
+    source: ChangeSource;
+    /**
+     * Optional raw input that produced this value.
+     *
+     * Example: original keyboard input or pasted string.
+     */
+    raw?: TRaw;
+    nativeEvent?: React__default.SyntheticEvent;
+    /**
+     * Variant-specific metadata (e.g. cursor position).
+     */
+    meta?: TMeta;
+}
+/**
+ * Base props shared by all variant components.
+ *
+ * Each variant module will extend this with its own props type.
+ */
+interface VariantBaseProps<TValue> {
+    /**
+     * Current logical value for this field.
+     */
+    value?: TValue | undefined;
+    /**
+     * Called whenever the variant wants to update the value.
+     *
+     * The detail payload describes where the change came from.
+     */
+    onValue?(value: TValue | undefined, detail?: ChangeDetail): void;
+    /**
+     * State flags.
+     */
+    disabled?: boolean;
+    defaultValue?: any;
+    readOnly?: boolean;
+    required?: boolean;
+    alias?: string;
+    main?: boolean;
+    /**
+     * Current error message for this field, if any.
+     */
+    error?: string;
+    /**
+     * Size & density hints.
+     *
+     * Variants are free to ignore these, but presets (e.g. Shadcn)
+     * will typically honour them.
+     */
+    size?: FieldSize;
+    density?: FieldDensity;
+}
+interface Extras {
+    trailingIcons?: React__default.ReactNode[];
+    leadingIcons?: React__default.ReactNode[];
+    icon?: React__default.ReactNode;
+    iconGap?: number;
+    trailingIconSpacing?: number;
+    leadingIconSpacing?: number;
+    trailingControl?: React__default.ReactNode;
+    leadingControl?: React__default.ReactNode;
+    /**
+     * Optional className applied to the container that wraps the leading control.
+     * This does not affect the control node itself, only the wrapper div.
+     */
+    leadingControlClassName?: string;
+    /**
+     * Optional className applied to the container that wraps the trailing control.
+     * This does not affect the control node itself, only the wrapper div.
+     */
+    trailingControlClassName?: string;
+    px?: number;
+    py?: number;
+    pb?: number;
+    pe?: number;
+    ps?: number;
+}
+type ExtraFieldProps<Props> = Extras & Props;
+
+/**
+ * Result type for validation hooks.
+ *
+ * Used by:
+ * - variant modules (`validate`)
+ * - per-field `onValidate` (InputField)
+ */
+type ValidateResult = boolean | string | string[] | null | void;
+/**
+ * Placement of the main label relative to the field control.
+ *
+ * This is a macro layout decision: where the label block lives
+ * compared to the input/control block.
+ */
+type LabelPlacement = "top" | "left" | "right" | "hidden";
+/**
+ * Shared placement for helper slots relative to their *root*.
+ *
+ * Example:
+ *  - "above" → above the label root or input root
+ *  - "below" → below the label root or input root
+ *  - "left"  → left of the label root or input root
+ *  - "right" → right of the label root or input root
+ *  - "hidden" → not rendered
+ */
+type SlotPlacement = "left" | "right" | "above" | "below" | "hidden";
+/**
+ * Placement of the sublabel relative to its root block.
+ */
+type SublabelPlacement = SlotPlacement;
+/**
+ * Placement for the longer description block.
+ */
+type DescriptionPlacement = SlotPlacement;
+/**
+ * Placement for helper text (typically small, subtle text).
+ */
+type HelpTextPlacement = SlotPlacement;
+/**
+ * Placement for explicit error text (visual error copy).
+ */
+type ErrorTextPlacement = SlotPlacement;
+/**
+ * Registry of all logical "slots" a field can render.
+ *
+ * Hosts can extend this via declaration merging, e.g.:
+ *
+ *   declare module "@/schema/input-field" {
+ *     interface FieldSlots {
+ *       charCounter: true;
+ *     }
+ *   }
+ */
+interface FieldSlots {
+    /** The main label text. */
+    label: true;
+    /** Optional smaller label text. */
+    sublabel: true;
+    /** Longer, usually multi-line description. */
+    description: true;
+    /** Small helper text, usually subtle. */
+    helpText: true;
+    /** Error text (validation message) when present. */
+    errorText: true;
+    /** The actual control/input element. */
+    input: true;
+    /**tags */
+    tags: true;
+}
+/**
+ * Registry of logical "roots" / anchor blocks.
+ *
+ * Other slots are positioned relative to one of these.
+ */
+interface FieldRoots {
+    /** Label root block. */
+    label: true;
+    /** Input/control root block. */
+    input: true;
+}
+type FieldSlotId = keyof FieldSlots;
+type FieldRootId = keyof FieldRoots;
+/**
+ * Map of which root each *non-root* slot belongs to.
+ *
+ * Example:
+ *   relativeRoots: {
+ *     sublabel: "label",
+ *     description: "input",
+ *     helpText: "input",
+ *     errorText: "input",
+ *   }
+ */
+type RelativeRootsMap = Partial<Record<Exclude<FieldSlotId, FieldRootId>, // non-root slots only
+FieldRootId>>;
+/**
+ * Relative ordering of *non-root* slots per root.
+ *
+ * This is *not* about placement; it only decides "who comes first"
+ * when multiple slots share the same:
+ *   - root (label/input), and
+ *   - placement (above/below/left/right)
+ *
+ * Example:
+ *   ordering: {
+ *     input: ["errorText", "description", "helpText"],
+ *   }
+ *
+ * If description and helpText are both "below" the input, then the
+ * above config means:
+ *   - errorText (below input) first,
+ *   - then description (below input),
+ *   - then helpText (below input).
+ */
+type FieldOrdering = Partial<Record<FieldRootId, Exclude<FieldSlotId, FieldRootId>[]>>;
+/**
+ * Layout defaults for a field/variant.
+ *
+ * Variants can provide these as defaults; InputField merges them
+ * with per-field overrides.
+ *
+ * The high-level placement props remain the main public API.
+ * `relativeRoots` and `ordering` provide a lower-level layout graph
+ * that InputField can use to render slots relative to "label" or
+ * "input" in a predictable order.
+ */
+interface FieldLayoutConfig {
+    /**
+     * Where to render the main label relative to the control.
+     */
+    labelPlacement?: LabelPlacement;
+    /**
+     * Where to render the sublabel relative to its root.
+     */
+    sublabelPlacement?: SublabelPlacement;
+    /**
+     * Where to render the description block relative to its root.
+     */
+    descriptionPlacement?: DescriptionPlacement;
+    /**
+     * Where to render helper text relative to its root.
+     */
+    helpTextPlacement?: HelpTextPlacement;
+    /**
+     * Where to render error text (if any) relative to its root.
+     */
+    errorTextPlacement?: ErrorTextPlacement;
+    /**Where to render the tags (if any) relative to ites root */
+    tagPlacement?: SlotPlacement;
+    /**
+     * Hint that the field should render inline with other controls.
+     */
+    inline?: boolean;
+    /**
+     * Hint that the field should stretch to the full available width.
+     */
+    fullWidth?: boolean;
+    /**
+     * Optional default size/density hints.
+     *
+     * These are advisory; variants/presets may override them.
+     */
+    defaultSize?: FieldSize;
+    defaultDensity?: FieldDensity;
+    /**
+     * Which root each non-root slot is attached to.
+     *
+     * If omitted, InputField can infer reasonable defaults, e.g.:
+     * - sublabel     → "label"
+     * - description  → "input"
+     * - helpText     → "input"
+     * - errorText    → "input"
+     */
+    relativeRoots?: RelativeRootsMap;
+    /**
+     * Relative ordering of non-root slots per root.
+     *
+     * Used only when multiple slots share the same
+     * root + placement combination.
+     */
+    ordering?: FieldOrdering;
+}
+/**
+ * Effective layout for a field after merging:
+ * - variant defaults, and
+ * - per-field overrides.
+ */
+interface EffectiveFieldLayout extends FieldLayoutConfig {
+    /**
+     * Concrete size/density after merging defaults + overrides.
+     */
+    size?: FieldSize;
+    density?: FieldDensity;
+}
+/**
+ * Context passed to a variant's layout resolver.
+ *
+ * - `defaults`: layout defaults defined by the variant module.
+ * - `overrides`: only the layout keys explicitly set on <InputField />.
+ * - `props`: the raw <InputField /> props for this field.
+ *
+ * The resolver MUST respect host overrides: if a key is present in
+ * `overrides`, it should not change it.
+ */
+interface LayoutResolveContext<T = unknown> {
+    defaults: FieldLayoutConfig;
+    overrides: Partial<FieldLayoutConfig>;
+    props: T;
+}
+/**
+ * Variant-level layout resolver.
+ *
+ * This allows variants to implement mapping rules such as:
+ * - "if labelPlacement is left ⇒ inline=true, error below, etc."
+ * while still allowing host overrides to win.
+ *
+ * Variants may also fill in `relativeRoots` and `ordering` to define
+ * how slots are attached to "label" vs "input" and in what relative
+ * order they should render.
+ */
+type LayoutResolver<T = unknown> = (ctx: LayoutResolveContext<T>) => FieldLayoutConfig;
+
+type MaskMode = "raw" | "masked";
+/**
+ * Mask-related props for the Shadcn text variant.
+ *
+ * These are forwarded to the underlying <Input>, which in turn wires
+ * them into the InputMask implementation.
+ */
+interface ShadcnTextMaskProps {
+    /**
+     * Mask pattern – Primereact style.
+     * Example: "99/99/9999", "(999) 999-9999"
+     */
+    mask?: string;
+    /**
+     * Per-symbol definitions for slots.
+     * Kept for future custom engine; not used by the current
+     * react-input-mask implementation.
+     */
+    maskDefinitions?: Record<string, RegExp>;
+    /**
+     * Character used to visually represent an empty slot.
+     * Default: "_".
+     */
+    slotChar?: string;
+    /**
+     * If true, when the value is effectively "empty" (no unmasked chars),
+     * we emit an empty string "" instead of a fully-masked placeholder.
+     *
+     * NOTE: This behaviour is implemented in the variant, not Input,
+     * so we preserve your existing semantics.
+     */
+    autoClear?: boolean;
+    /**
+     * Whether the *model* value is raw or masked.
+     *
+     * - "raw" or true   → onValue receives unmasked value
+     * - "masked" or false/undefined → onValue receives full masked string
+     *
+     * NOTE: detail.raw is **always** the masked string.
+     */
+    unmask?: MaskMode | boolean;
+    /**
+     * Placeholder for future caret-mode logic when we go back
+     * to a custom engine. Currently unused, kept for API compatibility.
+     */
+    maskInsertMode?: "stream" | "caret";
+}
+/**
+ * Extra UI props for the Shadcn text input (pure HTML-level).
+ *
+ * These are forwarded straight to the underlying <Input />.
+ */
+type ShadcnTextUiProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "value" | "defaultValue" | "onChange" | "size"> & {
+    /**
+     * Extra classes applied only to the *inner* input element
+     * (the actual <input>, not the wrapper box).
+     */
+    inputClassName?: string;
+    /**
+     * Fixed prefix rendered as part of the input value, NOT as an icon.
+     * E.g. "₦", "ID: ".
+     *
+     * The underlying <Input> will:
+     *  - take the model value (without prefix),
+     *  - render prefix + value,
+     *  - expose the full visible string in event.target.value.
+     */
+    prefix?: string;
+    /**
+     * Fixed suffix rendered as part of the input value, NOT as an icon.
+     * E.g. "%", "kg".
+     */
+    suffix?: string;
+    /**
+     * If true (default), we strip the prefix from the value
+     * before emitting it via `onValue`.
+     */
+    stripPrefix?: boolean;
+    /**
+     * If true (default), we strip the suffix from the value
+     * before emitting it via `onValue`.
+     */
+    stripSuffix?: boolean;
+} & ShadcnTextMaskProps;
+/**
+ * Props for the Shadcn-based text variant.
+ *
+ * This is a *form* wrapper around the base <Input />:
+ *  - Handles value ↔ ChangeDetail mapping.
+ *  - Delegates all visual concerns (masking, affixes, icons, controls,
+ *    size, density) to the Input component.
+ */
+type ShadcnTextVariantProps = ExtraFieldProps<VariantBaseProps<string | undefined>> & {
+    /**
+     * If true and there are controls, the input + controls share one box
+     * (borders, radius, focus states).
+     *
+     * Delegated to the underlying <Input />.
+     */
+    joinControls?: boolean;
+    /**
+     * When joinControls is true, whether the box styling extends over controls
+     * (true) or controls are visually separate (false).
+     */
+    extendBoxToControls?: boolean;
+} & ShadcnTextUiProps;
+
+type InputRef = HTMLInputElement;
+interface InputNumberValueChangeEvent {
+    originalEvent: React.SyntheticEvent<any> | null;
+    value: number | null;
+    stopPropagation(): void;
+    preventDefault(): void;
+    target: {
+        name?: string | null;
+        id?: string | null;
+        value: number | null;
+    };
+}
+interface InputNumberProps extends Omit<ShadcnTextVariantProps, 'min' | 'max' | 'value'>, Omit<React.InputHTMLAttributes<HTMLInputElement>, "value" | "defaultValue" | "onChange" | "onInput" | "onKeyDown" | "onKeyUp" | "size" | 'max' | 'min'> {
+    onKeyUp?(event: React.KeyboardEvent<HTMLInputElement>): unknown;
+    onKeyDown?(event: React.KeyboardEvent<HTMLInputElement>): unknown;
+    value?: number | null;
+    /**
+     * Emitted when the numeric value changes (Prime-style).
+     */
+    onValueChange?: (e: InputNumberValueChangeEvent) => void;
+    /**
+     * Optional simple change handler (numeric value).
+     */
+    onChange?: (e: {
+        originalEvent: React.SyntheticEvent<any>;
+        value: number | null;
+    }) => void;
+    locale?: string;
+    localeMatcher?: Intl.NumberFormatOptions["localeMatcher"];
+    mode?: "decimal" | "currency";
+    currency?: string;
+    currencyDisplay?: Intl.NumberFormatOptions["currencyDisplay"];
+    useGrouping?: boolean;
+    minFractionDigits?: number;
+    maxFractionDigits?: number;
+    roundingMode?: Intl.NumberFormatOptions["roundingMode"];
+    min?: number | null;
+    max?: number | null;
+    step?: number;
+    allowEmpty?: boolean;
+    format?: boolean;
+    inputId?: string;
+    inputClassName?: string;
+    inputStyle?: React.CSSProperties;
+    inputRef?: React.Ref<InputRef> | null;
+    /**
+     * String prefix/suffix (like Prime). They are part of formatting logic.
+     * You can ALSO forward them to your text variant as visual adornments.
+     */
+    prefix?: string;
+    suffix?: string;
+    size?: FieldSize;
+    invalid?: boolean;
+}
+declare const InputNumber: React.MemoExoticComponent<React.ForwardRefExoticComponent<InputNumberProps & React.RefAttributes<HTMLInputElement>>>;
+
+type ShadcnNumberVariantProps = Omit<InputNumberProps, "onValueChange" | "onChange" | "leadingControl" | "trailingControl"> & {
+    /**
+     * Show +/- buttons around the numeric field.
+     * Defaults to false.
+     */
+    showButtons?: boolean;
+    /**
+     * How the step buttons are laid out when showButtons is true.
+     *
+     * - 'inline': "-" on the left, "+" on the right
+     * - 'stacked': vertical +/- stack on the right
+     */
+    buttonLayout?: "inline" | "stacked";
+};
+
+type BaseProps$6 = VariantBaseProps<string | undefined>;
+/**
+ * Single-country phone config.
+ *
+ * - code: ISO 3166-1 alpha-2 ("NG", "US", "GB", ...)
+ * - dial: dial code without "+" ("234", "1", "44", ...)
+ * - mask: NATIONAL portion mask only (no dial), e.g. "999 999 9999"
+ */
+interface PhoneCountry {
+    code: string;
+    label: string;
+    dial: string;
+    mask: string;
+    flag?: React.ReactNode;
+}
+/**
+ * How the variant emits the form value.
+ *
+ * - "masked"  → "+234 801 234 5678"
+ * - "e164"    → "2348012345678"   (dial + national digits, no "+")
+ * - "national"→ "8012345678"
+ */
+type PhoneValueMode = "masked" | "e164" | "national";
+interface PhoneSpecificProps {
+    countries?: PhoneCountry[];
+    defaultCountry?: string;
+    onCountryChange?: (country: PhoneCountry) => void;
+    showCountry?: boolean;
+    countryPlaceholder?: string;
+    showFlag?: boolean;
+    showSelectedLabel?: boolean;
+    showSelectedDial?: boolean;
+    showDialInList?: boolean;
+    /**
+     * Controls how the emitted value is shaped.
+     *
+     * Default mirrors legacy autoUnmask=true + emitE164=true → "e164".
+     */
+    valueMode?: PhoneValueMode;
+    /**
+     * When true, the national mask keeps placeholder characters
+     * for not-yet-filled positions. When false, trailing mask
+     * fragments are omitted.
+     */
+    keepCharPositions?: boolean;
+    /**
+     * Style hooks for the internal country selector.
+     */
+    countrySelectClassName?: string;
+    countryTriggerClassName?: string;
+    countryValueClassName?: string;
+    countryContentClassName?: string;
+    countryItemClassName?: string;
+}
+type TextUiProps$4 = Omit<ShadcnTextVariantProps, "type" | "inputMode" | "leadingControl" | "value" | "onValue">;
+/**
+ * Full props for the phone variant as seen by the form runtime.
+ *
+ * - Keeps the same `value`/`onValue` contract as other variants.
+ * - Inherits visual/behavioural text props (size, density, className, etc.).
+ * - Adds phone-specific configuration (countries, valueMode, etc.).
+ */
+type ShadcnPhoneVariantProps = TextUiProps$4 & PhoneSpecificProps & Pick<BaseProps$6, "value" | "onValue">;
+
+type BaseProps$5 = VariantBaseProps<string | undefined>;
+/**
+ * Extra options specific to the color variant.
+ */
+interface ColorSpecificProps {
+    /**
+     * If false, we hide the colour preview box.
+     * Default: true
+     */
+    showPreview?: boolean;
+    /**
+     * If false, we hide the picker toggle control/icon.
+     * Default: true
+     */
+    showPickerToggle?: boolean;
+    /**
+     * Size of the colour swatch in pixels.
+     * Default: 18
+     */
+    previewSize?: number;
+    /**
+     * Optional className for the outer wrapper that hosts
+     * the Input + hidden color input.
+     */
+    wrapperClassName?: string;
+    /**
+     * Optional className for the preview button itself (around the swatch).
+     */
+    previewButtonClassName?: string;
+    /**
+     * Optional className for the swatch box inside the preview button.
+     */
+    previewSwatchClassName?: string;
+    /**
+     * Optional className for the hidden `<input type="color">`.
+     *
+     * By default this input is visually hidden and only used
+     * to invoke the browser/OS colour picker, but you can override
+     * this class to make it visible and style it.
+     */
+    pickerInputClassName?: string;
+    /**
+     * Custom icon shown in the trailing control as the picker toggle.
+     * If omitted, a tiny ▾ triangle is used.
+     */
+    pickerToggleIcon?: React.ReactNode;
+    className?: string;
+}
+/**
+ * We inherit the *visual/behavioural* props from ShadcnTextVariant,
+ * but control value / onValue / type / inputMode / leadingControl / trailingControl ourselves.
+ */
+type TextUiProps$3 = Omit<ShadcnTextVariantProps, "type" | "inputMode" | "leadingControl" | "trailingControl" | "value" | "onValue">;
+/**
+ * Full props for the color variant as seen by the form runtime.
+ */
+type ShadcnColorVariantProps = TextUiProps$3 & ColorSpecificProps & Pick<BaseProps$5, "value" | "onValue">;
+
+type BaseProps$4 = VariantBaseProps<string | undefined>;
+/**
+ * Options for the built-in password strength meter.
+ *
+ * NOTE: Score is always in the range 0–4 (inclusive).
+ */
+interface StrengthOptions {
+    /**
+     * Custom scoring function.
+     * Return a number in the range 0–4 (inclusive) where 0 = weakest, 4 = strongest.
+     */
+    calc?: (value: string) => number;
+    /**
+     * Labels for each score bucket (index 0..4).
+     * Defaults to: ["Very weak", "Weak", "Okay", "Good", "Strong"]
+     */
+    labels?: [string, string, string, string, string];
+    /**
+     * Thresholds for score steps using a 0–100 bar.
+     * Defaults to [0, 25, 50, 75, 100] mapping to scores 0..4 respectively.
+     */
+    thresholds?: [number, number, number, number, number];
+    /**
+     * Minimum score required to consider the password acceptable (0–4).
+     * This is purely visual unless you enforce it in validate/onChange.
+     * Default: 2
+     */
+    minScore?: number | 2;
+    /**
+     * Whether to show the textual label next to/under the bar.
+     * Default: true
+     */
+    showLabel?: boolean;
+    /**
+     * Where to render the meter.
+     * - "inline" → compact row under the input
+     * - "block" → stacked with more spacing
+     * Default: "inline"
+     */
+    display?: "inline" | "block";
+}
+interface PasswordRuleConfig {
+    /**
+     * Pattern used to decide if the rule passes.
+     */
+    pattern: RegExp;
+    /**
+     * If true, the rule is considered optional (recommendation).
+     * Default: false unless the rule name is not prefixed with "!".
+     */
+    optional?: boolean;
+    /**
+     * Weight in the scoring (relative importance).
+     * Default: 1, doubled if the use key is prefixed with "!".
+     */
+    weight?: number;
+    /**
+     * Short label for the rule (e.g. "At least 8 characters").
+     * Defaults to the map key if omitted.
+     */
+    label?: string;
+    /**
+     * Longer description, used in detailed rule view.
+     */
+    description?: string;
+}
+/**
+ * A definition entry can be:
+ * - string     → treated as a regex source
+ * - RegExp     → used directly
+ * - full config
+ */
+type PasswordRuleDefinition = string | RegExp | PasswordRuleConfig;
+/**
+ * Map of alias/keys → definition entries.
+ */
+type PasswordDefinitionMap = Record<string, PasswordRuleDefinition>;
+/**
+ * Internal normalized state for a single rule.
+ */
+interface NormalizedRuleState {
+    key: string;
+    label: string;
+    description?: string;
+    optional: boolean;
+    required: boolean;
+    weight: number;
+    passed: boolean;
+}
+/**
+ * Props passed to custom meter renderers.
+ */
+interface PasswordMeterRenderProps {
+    /** Raw password value. */
+    value: string;
+    /** Bucket score 0..4 based on percent + thresholds. */
+    score: number;
+    /** 0–100 progress used for the bar. */
+    percent: number;
+    /** Human label for the current score. */
+    label: string;
+    /** Whether score >= minScore. */
+    passed: boolean;
+    /** Effective minScore after normalization. */
+    minScore: number;
+    /** Effective thresholds used for bucketing. */
+    thresholds: [number, number, number, number, number];
+    /** Effective labels used. */
+    labels: [string, string, string, string, string];
+    /** Rule-level details when using a definition map. */
+    rules: NormalizedRuleState[];
+}
+/**
+ * Password-only props (on top of Shadcn text UI props & VariantBaseProps).
+ *
+ * This is what the form runtime sees as VariantPropsFor<"password">.
+ */
+interface PasswordVariantProps {
+    /** Maximum number of characters permitted. */
+    maxLength?: number;
+    /** Browser autocomplete hint (e.g., "current-password", "new-password"). */
+    autoComplete?: string;
+    /** Show an eye button to toggle between obscured/plain text. (default: true) */
+    revealToggle?: boolean;
+    /** Start in the revealed (plain text) state. */
+    defaultRevealed?: boolean;
+    /** Called whenever the reveal state changes. */
+    onRevealChange?(revealed: boolean): void;
+    /** Override the icons used for hide/show. */
+    renderToggleIcon?(revealed: boolean): React.ReactNode;
+    /** Accessible label for the toggle button. */
+    toggleAriaLabel?(revealed: boolean): string;
+    /**
+     * Extra className for the reveal toggle button.
+     */
+    toggleButtonClassName?: string;
+    /**
+     * Enable the built-in strength meter (boolean or options).
+     *
+     * - false / undefined → no built-in meter is shown
+     * - true              → use defaults
+     * - object            → merge with defaults
+     */
+    strengthMeter?: boolean | StrengthOptions;
+    /**
+     * Optional rule definition map.
+     */
+    ruleDefinitions?: PasswordDefinitionMap;
+    /**
+     * Selection of rule aliases to apply.
+     *
+     * - "length"  → use ruleDefinitions["length"] with default importance
+     * - "!length" → same rule but treated as more important
+     */
+    ruleUses?: string[];
+    /**
+     * Built-in meter style:
+     * - "simple" → single bar + label
+     * - "rules"  → bar + per-rule checklist
+     * Default: "simple"
+     */
+    meterStyle?: "simple" | "rules";
+    /**
+     * Optional custom meter renderer.
+     */
+    renderMeter?(props: PasswordMeterRenderProps): React.ReactNode;
+    /**
+     * ClassNames for the meter and rules UI.
+     */
+    meterWrapperClassName?: string;
+    meterContainerClassName?: string;
+    meterBarClassName?: string;
+    meterLabelClassName?: string;
+    rulesWrapperClassName?: string;
+    rulesHeadingClassName?: string;
+    rulesListClassName?: string;
+    ruleItemClassName?: string;
+    ruleIconClassName?: string;
+    ruleLabelClassName?: string;
+    /**
+     * Extra className for the outer field wrapper.
+     */
+    className?: string;
+}
+type TextUiProps$2 = Omit<ShadcnTextVariantProps, "type" | "inputMode" | "leadingControl" | "trailingControl" | "value" | "onValue">;
+/**
+ * Full props for the Shadcn-based password variant.
+ */
+type ShadcnPasswordVariantProps = TextUiProps$2 & PasswordVariantProps & Pick<BaseProps$4, "value" | "onValue" | "error">;
+
+declare const buttonVariants: (props?: ({
+    variant?: "default" | "link" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
+    size?: "default" | "sm" | "lg" | "icon" | "icon-sm" | "icon-lg" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+declare function Button({ className, variant, size, asChild, ...props }: React.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & {
+    asChild?: boolean;
+}): react_jsx_runtime.JSX.Element;
+
+declare function Calendar({ className, classNames, showOutsideDays, captionLayout, buttonVariant, formatters, components, ...props }: React.ComponentProps<typeof DayPicker> & {
+    buttonVariant?: React.ComponentProps<typeof Button>["variant"];
+}): react_jsx_runtime.JSX.Element;
+
+type DateMode = "single" | "range";
+interface DateRange {
+    from?: Date;
+    to?: Date;
+}
+type DateValue = Date | DateRange | undefined;
+type BaseProps$3 = VariantBaseProps<DateValue>;
+type DisabledDays = React.ComponentProps<typeof Calendar>["disabled"];
+/**
+ * Logical temporal "kind" for the field.
+ *
+ * This controls the default mask + formatting/parsing.
+ *
+ * - "date"      → yyyy-MM-dd (default)
+ * - "datetime"  → yyyy-MM-dd HH:mm
+ * - "time"      → HH:mm
+ * - "hour"      → HH
+ * - "monthYear" → MM/yyyy
+ * - "year"      → yyyy
+ */
+type DateKind = "date" | "datetime" | "time" | "hour" | "monthYear" | "year" | (string & {});
+/**
+ * Public props for the date variant (legacy + mask extensions).
+ */
+interface DateVariantProps {
+    mode?: DateMode;
+    placeholder?: React.ReactNode;
+    clearable?: boolean;
+    minDate?: Date;
+    maxDate?: Date;
+    disabledDays?: DisabledDays;
+    /**
+     * Pattern for single dates.
+     *
+     * Tokens:
+     * - yyyy → full year
+     * - MM   → month (01–12)
+     * - dd   → day (01–31)
+     * - HH   → hours (00–23)
+     * - mm   → minutes (00–59)
+     *
+     * Default depends on `kind`:
+     * - date      → "yyyy-MM-dd"
+     * - datetime  → "yyyy-MM-dd HH:mm"
+     * - time      → "HH:mm"
+     * - hour      → "HH"
+     * - monthYear → "MM/yyyy"
+     * - year      → "yyyy"
+     */
+    formatSingle?: string;
+    /**
+     * String pattern or custom formatter for ranges.
+     *
+     * - string → same token rules as formatSingle, applied to both ends
+     * - function → full control over display text
+     */
+    formatRange?: string | ((range: DateRange | undefined) => string);
+    /**
+     * Separator when formatRange is a string pattern.
+     * Default: " – "
+     */
+    rangeSeparator?: string;
+    /**
+     * When true, keep the calendar open after a selection.
+     *
+     * For range mode, the picker also stays open until both
+     * `from` and `to` are chosen.
+     */
+    stayOpenOnSelect?: boolean;
+    /**
+     * Controlled open state for the popover.
+     */
+    open?: boolean;
+    onOpenChange?(o: boolean): void;
+    /**
+     * Temporal kind (controls default mask + formatting/parsing).
+     *
+     * Default: "date".
+     */
+    kind?: DateKind;
+    /**
+     * Optional explicit input mask pattern for the text input.
+     *
+     * If omitted, a sensible default based on `kind` is used.
+     *
+     * Mask tokens follow the same rules as the underlying Input mask:
+     *   9 = digit, a = letter, * = alphanumeric.
+     */
+    inputMask?: string;
+    /**
+     * Whether to render the calendar popover.
+     *
+     * Defaults:
+     * - true  for `kind` = "date" | "datetime"
+     * - false for time-only kinds ("time", "hour", "monthYear", "year")
+     */
+    showCalendar?: boolean;
+}
+/**
+ * We still reuse the Shadcn text UI props (size, density, icons, etc.),
+ * but we take over type/value/onValue and the controls.
+ */
+type TextUiProps$1 = Omit<ShadcnTextVariantProps, "type" | "inputMode" | "leadingControl" | "trailingControl" | "value" | "onValue">;
+/**
+ * Full props for the Shadcn-based date variant.
+ */
+type ShadcnDateVariantProps = TextUiProps$1 & DateVariantProps & Pick<BaseProps$3, "value" | "onValue" | "error">;
+
+type ChipsValue = string[] | undefined;
+type BaseProps$2 = VariantBaseProps<ChipsValue>;
+/**
+ * How we split text into chips when committing.
+ */
+type ChipsSeparator = string | RegExp | (string | RegExp)[];
+/**
+ * Placement of chips relative to the entry control.
+ *
+ * - "inline" → inside the same visual box (Input) or in the textarea toolbox.
+ * - "below"  → chips rendered as a block underneath the field.
+ */
+type ChipsPlacement = "inline" | "below";
+/**
+ * Chips-only props, on top of the injected ones.
+ */
+interface ChipsVariantProps {
+    /**
+     * Placeholder shown when there are no chips and input is empty.
+     */
+    placeholder?: string;
+    /**
+     * Separators used to split raw input into chips.
+     *
+     * - string  → split on that string
+     * - RegExp  → split with regex
+     * - array   → try each in order
+     *
+     * Default: [",", ";"]
+     */
+    separators?: ChipsSeparator;
+    /**
+     * When true, pressing Enter commits the current input as chips.
+     * Default: true
+     */
+    addOnEnter?: boolean;
+    /**
+     * When true, pressing Tab commits the current input as chips.
+     * Default: true
+     */
+    addOnTab?: boolean;
+    /**
+     * When true, blurring the field commits any remaining input as chips.
+     * Default: true
+     */
+    addOnBlur?: boolean;
+    /**
+     * When false, duplicate chips are ignored.
+     * Default: false
+     */
+    allowDuplicates?: boolean;
+    /**
+     * Maximum number of chips allowed.
+     * Undefined → unlimited.
+     */
+    maxChips?: number;
+    /**
+     * When true, Backspace on empty input removes the last chip.
+     * Default: true
+     */
+    backspaceRemovesLast?: boolean;
+    /**
+     * Show a small clear-all button.
+     * Default: false
+     */
+    clearable?: boolean;
+    /**
+     * Called when chips are added.
+     */
+    onAddChips?(added: string[], next: string[]): void;
+    /**
+     * Called when chips are removed.
+     */
+    onRemoveChips?(removed: string[], next: string[]): void;
+    /**
+     * Optional custom chip renderer.
+     *
+     * If provided, you are responsible for calling onRemove(index)
+     * from your UI when you want to remove a chip.
+     */
+    renderChip?(chip: string, index: number, ctx: {
+        remove(): void;
+        chips: string[];
+    }): React.ReactNode;
+    /**
+     * Optional custom overflow chip renderer.
+     *
+     * Receives the hidden count and the full chip list.
+     */
+    renderOverflowChip?(hiddenCount: number, chips: string[]): React.ReactNode;
+    /**
+     * Max number of chips to *render*.
+     * Extra chips are summarized as "+N more".
+     */
+    maxVisibleChips?: number;
+    /**
+     * Max number of characters to *display* per chip.
+     * The underlying value is not truncated.
+     */
+    maxChipChars?: number;
+    /**
+     * CSS max-width for chip labels (e.g. 160 or "12rem").
+     */
+    maxChipWidth?: number | string;
+    /**
+     * When true, the entry control is a Textarea instead of Input.
+     * Good for comment-style chip entry.
+     */
+    textareaMode?: boolean;
+    /**
+     * Where chips are rendered relative to the entry.
+     *
+     * Default:
+     * - Input mode → "inline"
+     * - Textarea mode → "inline"
+     */
+    placement?: ChipsPlacement;
+    className?: string;
+    chipsClassName?: string;
+    chipClassName?: string;
+    chipLabelClassName?: string;
+    chipRemoveClassName?: string;
+    inputClassName?: string;
+}
+/**
+ * We still type against ShadcnTextVariantProps so chips can reuse
+ * size/density/icon props etc. We take control of:
+ * - type / value / onValue
+ * - leadingControl / trailingControl
+ */
+type TextUiProps = Omit<ShadcnTextVariantProps, "type" | "inputMode" | "leadingControl" | "trailingControl" | "value" | "onValue">;
+/**
+ * Full props for the Shadcn-based chips variant.
+ */
+type ShadcnChipsVariantProps = TextUiProps & ChipsVariantProps & Pick<BaseProps$2, "value" | "onValue" | "error">;
+
+interface TextareaIconControlProps {
+    leadingIcons?: React.ReactNode[];
+    trailingIcons?: React.ReactNode[];
+    icon?: React.ReactNode;
+    iconGap?: number;
+    leadingIconSpacing?: number;
+    trailingIconSpacing?: number;
+    leadingControl?: React.ReactNode;
+    trailingControl?: React.ReactNode;
+    leadingControlClassName?: string;
+    trailingControlClassName?: string;
+    /**
+     * If true, move the visual box (border, bg, radius, focus) from
+     * `textarea-field` to `textarea-inner` so the side controls are
+     * inside the same frame.
+     *
+     * Default: false (controls sit outside the border).
+     */
+    extendBoxToControls?: boolean;
+    /**
+     * If true, move the visual box all the way up to `textarea-box`,
+     * so the upper toolbox and the inner row share a single frame.
+     *
+     * When this is true, it overrides `extendBoxToControls`.
+     *
+     * Default: false.
+     */
+    extendBoxToToolbox?: boolean;
+    /**
+     * Extra padding knobs (same semantics as Input).
+     *
+     * px → symmetric horizontal padding
+     * py → symmetric vertical padding
+     * ps/pe → logical start/end padding adjustments
+     * pb → extra bottom padding (stacked with py)
+     */
+    px?: number;
+    py?: number;
+    ps?: number;
+    pe?: number;
+    pb?: number;
+    /**
+     * Extra classes merged into the raw <textarea>.
+     * (The box padding/border live on the wrappers.)
+     */
+    inputClassName?: string;
+}
+interface TextareaSizeProps {
+    size?: "sm" | "md" | "lg" | (string & {});
+    density?: "compact" | "normal" | "relaxed" | "dense" | "loose" | (string & {});
+}
+interface TextareaProps extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, "size">, TextareaIconControlProps, TextareaSizeProps {
+    /**
+     * Auto-resize based on content.
+     * Default: true.
+     */
+    autoResize?: boolean;
+    /**
+     * Minimum number of visual rows.
+     * Default: 1.
+     */
+    rows?: number;
+    /**
+     * Maximum number of visual rows.
+     * Undefined → unlimited.
+     */
+    maxRows?: number;
+    /**
+     * Optional upper toolbox area.
+     */
+    upperControl?: React.ReactNode;
+    upperControlClassName?: string;
+}
+declare const Textarea: React.ForwardRefExoticComponent<TextareaProps & React.RefAttributes<HTMLTextAreaElement>>;
+
+type TextareaValue = string | undefined;
+type BaseProps$1 = VariantBaseProps<TextareaValue>;
+/**
+ * Full props for the Shadcn-based textarea variant.
+ *
+ * - Reuses all UI-level behaviour from `Textarea` (autoResize, upperControl,
+ *   leading/trailing controls, icons, size/density, padding knobs, etc.).
+ * - Takes over `value` / `onChange` so it can emit through `onValue` with
+ *   a `ChangeDetail`.
+ */
+interface ShadcnTextareaVariantProps extends Omit<TextareaProps, "value" | "defaultValue" | "onChange">, Pick<BaseProps$1, "value" | "onValue" | "error"> {
+}
+
+declare function Switch({ className, thumbClassName, ...props }: React.ComponentProps<typeof SwitchPrimitive.Root> & {
+    thumbClassName?: string;
+}): react_jsx_runtime.JSX.Element;
+
+type ToggleValue = boolean | undefined;
+type BaseProps = VariantBaseProps<ToggleValue>;
+type Size = "sm" | "md" | "lg";
+type Density = "default" | "dense";
+/**
+ * UI props specific to the Shadcn-based toggle.
+ *
+ * This uses Switch as the underlying control, but we keep
+ * the API surface small and focused.
+ */
+interface ShadcnToggleUiProps extends Omit<React.ComponentProps<typeof Switch>, "checked" | "onCheckedChange" | "className"> {
+    /**
+     * Visual size of the switch / text.
+     * Default: "md".
+     */
+    size?: Size;
+    /**
+     * Row density (vertical padding & gap).
+     * Default: "default".
+     */
+    density?: Density;
+    /**
+     * Place the switch on the left or right of the state text.
+     * Default: "left".
+     */
+    controlPlacement?: "left" | "right";
+    /**
+     * Optional state text shown next to the control when ON.
+     */
+    onText?: React.ReactNode;
+    /**
+     * Optional state text shown next to the control when OFF.
+     */
+    offText?: React.ReactNode;
+    /**
+     * Wrapper class for the whole toggle row.
+     */
+    className?: string;
+    /**
+     * Extra classes for the Switch root.
+     */
+    switchClassName?: string;
+    /**
+     * Extra classes for the Switch thumb.
+     * (Your patched Switch should support thumbClassName.)
+     */
+    switchThumbClassName?: string;
+}
+/**
+ * Full props for the Shadcn-based toggle variant.
+ *
+ * We only pick value/onValue/error from the variant base props;
+ * everything else (id, disabled, aria-*) flows via Switch props.
+ */
+type ShadcnToggleVariantProps$1 = ShadcnToggleUiProps & Pick<BaseProps, "value" | "onValue" | "error">;
+
+/**
+ * Visual size of the radio UI.
+ */
+type RadioSize = "sm" | "md" | "lg";
+/**
+ * Vertical density of each radio row.
+ *
+ * Names aligned with your FieldDensity, but local to this variant.
+ */
+type RadioDensity = "compact" | "comfortable" | "loose";
+/**
+ * Layout mode for the group.
+ *
+ * - "list" → stacked rows
+ * - "grid" → CSS grid with `columns`
+ */
+type RadioLayoutMode = "list" | "grid";
+/**
+ * Base radio item shape.
+ */
+interface RadioItem<TValue> {
+    value: TValue;
+    label: React.ReactNode;
+    description?: React.ReactNode;
+    disabled?: boolean;
+    key?: React.Key;
+    /**
+     * Option-level renderer (provided by the normaliser).
+     * If present, it overrides the variant-level `renderOption` for this item.
+     */
+    render?: (ctx: RadioRenderOptionContext<TValue>) => React.ReactNode;
+}
+/**
+ * Mapping functions used when TItem is not `RadioItem<TValue>`.
+ */
+interface RadioMappers<TItem, TValue> {
+    getValue: (item: TItem, index: number) => TValue;
+    getLabel: (item: TItem, index: number) => React.ReactNode;
+    getDescription?: (item: TItem, index: number) => React.ReactNode;
+    isDisabled?: (item: TItem, index: number) => boolean;
+    getKey?: (item: TItem, index: number) => React.Key;
+}
+/**
+ * Context passed to a custom renderOption callback.
+ */
+interface RadioRenderOptionContext<TValue> {
+    item: RadioItem<TValue>;
+    index: number;
+    selected: boolean;
+    disabled: boolean;
+    size: RadioSize;
+    density: RadioDensity;
+    click(): void;
+    /**
+     * DOM id of this option (tied to the underlying RadioGroupItem).
+     */
+    optionId?: string;
+    /**
+     * Prebuilt radio control for convenience.
+     * You can ignore this and render your own if you want.
+     */
+    radio: React.ReactNode;
+}
+/**
+ * UI-specific radio props (independent of VariantBaseProps).
+ */
+interface ShadcnRadioUiProps<TItem, TValue> {
+    /**
+     * Items to render as choices.
+     *
+     * Can be:
+     * - `RadioItem<TValue>[]`, or
+     * - any custom TItem[] when used with mapping functions
+     *   or optionValue/optionLabel keys.
+     * - primitive arrays such as `string[]` or `number[]` (fallback).
+     */
+    items: readonly TItem[];
+    /**
+     * Mapping functions for TItem → value/label/etc.
+     *
+     * Takes precedence over optionValue/optionLabel if provided.
+     */
+    mappers?: RadioMappers<TItem, TValue>;
+    /**
+     * Property name on TItem that holds the **value**.
+     *
+     * Example:
+     *   items = [{ id: "free", title: "Free" }]
+     *   optionValue = "id"
+     */
+    optionValue?: keyof TItem | string;
+    /**
+     * Property name on TItem that holds the **label**.
+     *
+     * Example:
+     *   items = [{ id: "free", title: "Free" }]
+     *   optionLabel = "title"
+     */
+    optionLabel?: keyof TItem | string;
+    /**
+     * Optional custom renderer for each option.
+     *
+     * If provided, the default label/description layout is skipped and
+     * this function is responsible for rendering the row.
+     */
+    renderOption?: (ctx: RadioRenderOptionContext<TValue>) => React.ReactNode;
+    /**
+     * Layout mode for the group.
+     * Default: "list".
+     */
+    layout?: RadioLayoutMode;
+    /**
+     * Number of columns in grid mode.
+     * Default: 2.
+     */
+    columns?: number;
+    /**
+     * Gap between items (list rows or grid cells) in px.
+     * If omitted, Tailwind gaps/classes can handle spacing.
+     */
+    itemGapPx?: number;
+    /**
+     * Visual size of the radios.
+     * Default: "md".
+     */
+    size?: RadioSize;
+    /**
+     * Vertical density (padding) of each row.
+     * Default: "comfortable".
+     */
+    density?: RadioDensity;
+    /**
+     * When true, capitalizes the **first letter** of the label
+     * (only applied when the label is a string).
+     */
+    autoCap?: boolean;
+    /**
+     * ARIA overrides for the group.
+     */
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    /**
+     * Wrapper class for the whole radio group.
+     */
+    groupClassName?: string;
+    /**
+     * Extra classes for each radio option row.
+     */
+    optionClassName?: string;
+    /**
+     * Extra classes for the option label node.
+     */
+    labelClassName?: string;
+    /**
+     * Extra classes for the description text under the label.
+     */
+    descriptionClassName?: string;
+}
+/**
+ * Full props for the Shadcn-based radio variant.
+ */
+type ShadcnRadioVariantProps<TValue, TItem = RadioItem<TValue>> = ShadcnRadioUiProps<TItem, TValue> & Pick<VariantBaseProps<TValue | undefined>, "value" | "onValue" | "error" | "disabled" | "required"> & {
+    id?: string;
+    name?: string;
+    className?: string;
+    "aria-describedby"?: string;
+};
+
+type CheckboxSize = "sm" | "md" | "lg";
+type CheckboxDensity = "compact" | "comfortable" | "loose";
+type CheckboxLayoutMode = "list" | "grid";
+/**
+ * Internal state we store in the value list.
+ * "none" never goes into the external value.
+ */
+type CheckboxTriStateValue = true | false;
+/**
+ * Internal state we pass to the Shadcn checkbox.
+ * "none" is used to represent "no stance yet".
+ */
+type CheckboxInternalState = true | false | "none";
+interface CheckboxGroupEntry<TValue> {
+    value: TValue;
+    state: CheckboxTriStateValue;
+}
+type CheckboxGroupValue<TValue> = readonly CheckboxGroupEntry<TValue>[] | undefined;
+/**
+ * Single checkbox value.
+ * undefined → "none"
+ */
+type CheckboxSingleValue = boolean | undefined;
+/**
+ * Public union type for the variant's value.
+ *
+ * - In single mode: we expect CheckboxSingleValue
+ * - In group mode: we expect CheckboxGroupValue<TValue>
+ *
+ * At the type level this is a union; at runtime we branch using `single`.
+ */
+type CheckboxVariantValue<TValue> = CheckboxSingleValue | CheckboxGroupValue<TValue>;
+interface CheckboxItem<TValue> {
+    value: TValue;
+    label: React.ReactNode;
+    description?: React.ReactNode;
+    disabled?: boolean;
+    key?: React.Key;
+    /**
+     * Option-level renderer (provided by the normaliser).
+     * If present, it should override the variant-level `renderOption` for this item.
+     */
+    render?: (ctx: CheckboxRenderOptionContext<TValue>) => React.ReactNode;
+    /**
+     * Override tri-state behaviour for this item.
+     * If undefined, variant-level `tristate` is used.
+     */
+    tristate?: boolean;
+}
+interface CheckboxMappers<TItem, TValue> {
+    getValue: (item: TItem, index: number) => TValue;
+    getLabel: (item: TItem, index: number) => React.ReactNode;
+    getDescription?: (item: TItem, index: number) => React.ReactNode;
+    isDisabled?: (item: TItem, index: number) => boolean;
+    getKey?: (item: TItem, index: number) => React.Key;
+    getTristate?: (item: TItem, index: number) => boolean | undefined;
+}
+interface CheckboxRenderOptionContext<TValue> {
+    item: CheckboxItem<TValue>;
+    index: number;
+    state: CheckboxInternalState;
+    effectiveTristate: boolean;
+    disabled: boolean;
+    size: CheckboxSize;
+    density: CheckboxDensity;
+    checkboxId?: string;
+    click(): void;
+    /**
+     * Prebuilt Shadcn checkbox node.
+     */
+    checkbox: React.ReactNode;
+}
+/**
+ * UI props for both single and group modes.
+ */
+interface ShadcnCheckboxUiProps<TItem, TValue> {
+    /**
+     * Group mode:
+     *  - Required when `single` is not true.
+     *
+     * Single mode:
+     *  - Optional; if provided, `items[0]` can supply label/description.
+     */
+    items?: readonly TItem[];
+    /**
+     * Mapping functions for arbitrary item shapes.
+     * Takes precedence over optionValue/optionLabel.
+     */
+    mappers?: CheckboxMappers<TItem, TValue>;
+    /**
+     * Property name that holds the value on each item.
+     *
+     * Example:
+     *   items = [{ id: "read", label: "Read" }]
+     *   optionValue = "id"
+     */
+    optionValue?: keyof TItem;
+    /**
+     * Property name that holds the label on each item.
+     *
+     * Example:
+     *   items = [{ id: "read", title: "Read" }]
+     *   optionLabel = "title"
+     */
+    optionLabel?: keyof TItem;
+    /**
+     * Custom renderer for each option row.
+     */
+    renderOption?: (ctx: CheckboxRenderOptionContext<TValue>) => React.ReactNode;
+    /**
+     * If true, treat this variant as a single checkbox instead of a group.
+     *
+     * Value is then CheckboxSingleValue (boolean | undefined).
+     */
+    single?: boolean;
+    /**
+     * Variant-level default tri-state behaviour.
+     *
+     * - In single mode: directly controls tri-state for the single checkbox.
+     * - In group mode: default for all items, unless item.tristate overrides.
+     */
+    tristate?: boolean;
+    /**
+     * Layout mode in group mode: vertical list or CSS grid.
+     */
+    layout?: CheckboxLayoutMode;
+    /**
+     * Number of columns in grid mode.
+     * Default: 2.
+     */
+    columns?: number;
+    /**
+     * Gap between items in px.
+     */
+    itemGapPx?: number;
+    /**
+     * Visual size of the checkbox / text.
+     * Default: "md".
+     */
+    size?: CheckboxSize;
+    /**
+     * Vertical density of each row.
+     * Default: "comfortable".
+     */
+    density?: CheckboxDensity;
+    /**
+     * When true, capitalizes the first letter of the label
+     * (only applied when the label is a string).
+     */
+    autoCap?: boolean;
+    /**
+     * ARIA attributes for the group wrapper.
+     */
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    /**
+     * Wrapper class for the entire group (or single field).
+     */
+    groupClassName?: string;
+    /**
+     * Extra classes for each option row (group mode).
+     */
+    optionClassName?: string;
+    /**
+     * Extra classes for the option label text.
+     */
+    labelClassName?: string;
+    /**
+     * Extra classes for the option label text in group mode only.
+     * This allows styling group item labels without affecting single mode labels.
+     */
+    optionLabelClassName?: string;
+    /**
+     * Extra classes for the option description text.
+     */
+    descriptionClassName?: string;
+    /**
+     * Single-mode inline label (if you want variant-level text).
+     * Usually you'll rely on InputField's label instead.
+     */
+    singleLabel?: React.ReactNode;
+    /**
+     * Single-mode description text under the label.
+     */
+    singleDescription?: React.ReactNode;
+}
+/**
+ * Full props for the Shadcn-based checkbox variant.
+ *
+ * TValue: primitive or object key
+ * TItem: item shape used to build checkbox items
+ */
+type ShadcnCheckboxVariantProps<TValue, TItem = CheckboxItem<TValue>> = ShadcnCheckboxUiProps<TItem, TValue> & Pick<VariantBaseProps<CheckboxVariantValue<TValue>>, "value" | "onValue" | "error" | "disabled" | "required"> & {
+    id?: string;
+    className?: string;
+    name?: string;
+    "aria-describedby"?: string;
+};
+/**
+ * Default item value type for the checkbox variant.
+ *
+ * You can still use the generic ShadcnCheckboxVariantProps<TValue, TItem>
+ * directly if you need a different TValue; the registry uses this alias.
+ */
+type DefaultCheckboxItemValue = string | number;
+/**
+ * Public "value" type for the checkbox variant used by the registry:
+ *
+ * - Single mode: boolean | undefined
+ * - Group mode: CheckboxGroupEntry<DefaultCheckboxItemValue>[] | undefined
+ *
+ * In tri-state group mode, both `true` and `false` entries are present;
+ * `"none"` never appears in this type.
+ */
+type CheckboxVariantPublicValue = CheckboxVariantValue<DefaultCheckboxItemValue>;
+/**
+ * Public props type for the checkbox variant used by the registry.
+ *
+ * This is ShadcnCheckboxVariantProps with TValue fixed to DefaultCheckboxItemValue.
+ */
+type ShadcnCheckboxVariantPublicProps = ShadcnCheckboxVariantProps<DefaultCheckboxItemValue>;
+
+type SelectPrimitive$1 = string | number;
+type MultiSelectOption = SelectPrimitive$1 | {
+    label?: React.ReactNode;
+    value?: SelectPrimitive$1;
+    description?: React.ReactNode;
+    disabled?: boolean;
+    icon?: React.ReactNode;
+    [key: string]: any;
+};
+type NormalizedMultiItem = {
+    key: string;
+    value: SelectPrimitive$1;
+    labelNode: React.ReactNode;
+    labelText: string;
+    description?: React.ReactNode;
+    disabled?: boolean;
+    icon?: React.ReactNode;
+    /** Option-level renderer (falls back to global renderOption) */
+    render?: (...args: any[]) => React.ReactNode;
+    raw: MultiSelectOption;
+};
+type MultiSelectBaseProps = Pick<VariantBaseProps<SelectPrimitive$1[] | undefined>, "value" | "onValue" | "error" | "disabled" | "readOnly" | "size" | "density"> & {
+    /**
+     * Options for the multi-select.
+     *
+     * You can pass:
+     * - primitives: ["ng", "gh", "ke"]
+     * - objects:    [{ label, value, ...extra }]
+     */
+    options?: MultiSelectOption[];
+    /**
+     * Automatically capitalise the first letter of the label
+     * (when the resolved label is a string).
+     */
+    autoCap?: boolean;
+    /**
+     * How to read the label from each option.
+     *
+     * - string → key on the option object
+     * - function → custom mapper
+     * - omitted → tries `label`, else String(value)
+     */
+    optionLabel?: string | ((item: MultiSelectOption) => React.ReactNode);
+    /**
+     * How to read the value from each option.
+     *
+     * - string → key on the option object
+     * - function → custom mapper
+     * - omitted → uses `value`, or `id`, or `key`, or index
+     */
+    optionValue?: string | ((item: MultiSelectOption) => SelectPrimitive$1);
+    /**
+     * Optional description line under the label.
+     */
+    optionDescription?: string | ((item: MultiSelectOption) => React.ReactNode);
+    /**
+     * How to determine if an option is disabled.
+     */
+    optionDisabled?: string | ((item: MultiSelectOption) => boolean);
+    /**
+     * How to extract an icon for each option.
+     *
+     * - string → key on the option object (default "icon")
+     * - function → custom mapper
+     */
+    optionIcon?: string | ((item: MultiSelectOption) => React.ReactNode);
+    /**
+     * How to compute the React key for each option.
+     */
+    optionKey?: string | ((item: MultiSelectOption, index: number) => React.Key);
+    /**
+     * Enable inline search inside the dropdown.
+     */
+    searchable?: boolean;
+    /**
+     * Placeholder for the search input.
+     */
+    searchPlaceholder?: string;
+    /**
+     * Text to show when search yields no results.
+     */
+    emptySearchText?: React.ReactNode;
+    /**
+     * Placeholder when nothing is selected.
+     */
+    placeholder?: React.ReactNode;
+    /**
+     * Show a small clear button in the trigger when any value is selected.
+     */
+    clearable?: boolean;
+    /**
+     * Whether to show a "Select all" row.
+     */
+    showSelectAll?: boolean;
+    /**
+     * Label for the "Select all" row.
+     * Default: "Select all".
+     */
+    selectAllLabel?: React.ReactNode;
+    /**
+     * Where to place the "Select all" row.
+     * Default: "top".
+     */
+    selectAllPosition?: "top" | "bottom";
+    /**
+     * Custom renderer for each option row (checkbox + label).
+     */
+    renderOption?: (ctx: {
+        item: NormalizedMultiItem;
+        selected: boolean;
+        index: number;
+        option: React.ReactNode;
+        click(): void;
+    }) => React.ReactNode;
+    /**
+     * Custom renderer for the trigger summary.
+     */
+    renderValue?: (ctx: {
+        selectedItems: NormalizedMultiItem[];
+        placeholder?: React.ReactNode;
+    }) => React.ReactNode;
+    /**
+     * Custom renderer for the checkbox.
+     *
+     * - item: the option item (or null for "select all")
+     * - selected: whether this row is currently fully selected
+     * - indeterminate: partially selected (used for "select all")
+     * - isSelectAll: true for the "select all" row
+     */
+    renderCheckbox?: (ctx: {
+        item: NormalizedMultiItem | null;
+        selected: boolean;
+        indeterminate: boolean;
+        isSelectAll: boolean;
+    }) => React.ReactNode;
+    /**
+     * Max height (in px) for the dropdown list before scrolling.
+     * Default: 260.
+     */
+    maxListHeight?: number;
+    /**
+     * Wrapper class for the whole variant.
+     */
+    className?: string;
+    /**
+     * Extra classes for the trigger button.
+     */
+    triggerClassName?: string;
+    /**
+     * Extra classes for the popover content.
+     */
+    contentClassName?: string;
+};
+type MultiSelectDefaultModeProps = {
+    mode?: "default";
+    leadingIcons?: React.ReactNode[];
+    trailingIcons?: React.ReactNode[];
+    icon?: React.ReactNode;
+    iconGap?: number;
+    leadingIconSpacing?: number;
+    trailingIconSpacing?: number;
+    leadingControl?: React.ReactNode;
+    trailingControl?: React.ReactNode;
+    leadingControlClassName?: string;
+    trailingControlClassName?: string;
+    joinControls?: boolean;
+    extendBoxToControls?: boolean;
+    button?: never;
+    children?: never;
+    selectedBadge?: never;
+    selectedBadgeHiddenWhenZero?: never;
+    selectedBadgeClassName?: never;
+    selectedBadgePlacement?: never;
+};
+type MultiSelectButtonModeButton = React.ReactNode | ((ctx: {
+    open: boolean;
+    selectedItems: NormalizedMultiItem[];
+    selectedCount: number;
+}) => React.ReactNode);
+type MultiSelectButtonModeProps = {
+    mode: "button";
+    /**
+     * Used when mode="button". If provided, this is the trigger.
+     * If not provided, `children` is used.
+     */
+    button?: MultiSelectButtonModeButton;
+    children?: MultiSelectButtonModeButton;
+    /**
+     * Selected-count badge (mode="button" only)
+     */
+    selectedBadge?: boolean;
+    selectedBadgeHiddenWhenZero?: boolean;
+    selectedBadgeClassName?: string;
+    selectedBadgePlacement?: "end" | "corner";
+    leadingIcons?: never;
+    trailingIcons?: never;
+    icon?: never;
+    iconGap?: never;
+    leadingIconSpacing?: never;
+    trailingIconSpacing?: never;
+    leadingControl?: never;
+    trailingControl?: never;
+    leadingControlClassName?: never;
+    trailingControlClassName?: never;
+    joinControls?: never;
+    extendBoxToControls?: never;
+};
+type ShadcnMultiSelectVariantProps = MultiSelectBaseProps & (MultiSelectDefaultModeProps | MultiSelectButtonModeProps);
+
+type SliderValue$1 = number | undefined;
+interface ShadcnSliderVariantProps extends Pick<VariantBaseProps<SliderValue$1>, "value" | "onValue" | "error" | "disabled" | "readOnly" | "size" | "density"> {
+    /**
+     * Minimum value for the slider.
+     * Default: 0
+     */
+    min?: number;
+    /**
+     * Maximum value for the slider.
+     * Default: 100
+     */
+    max?: number;
+    /**
+     * Step between values.
+     * Default: 1
+     */
+    step?: number;
+    /**
+     * Show the current value as text next to the slider.
+     * Default: true
+     */
+    showValue?: boolean;
+    /**
+     * Where to place the value label, relative to the slider.
+     * - "end"   → right of the slider (horizontal)
+     * - "start" → left of the slider
+     *
+     * Default: "end"
+     */
+    valuePlacement?: "start" | "end";
+    /**
+     * Custom formatter for the numeric value.
+     * If omitted, uses the raw number.
+     */
+    formatValue?: (value: SliderValue$1) => React.ReactNode;
+    /**
+     * Wrapper class for the entire slider field.
+     */
+    className?: string;
+    /**
+     * Extra classes for the Slider root.
+     */
+    sliderClassName?: string;
+    /**
+     * Extra classes for the value label.
+     */
+    valueClassName?: string;
+    /**
+     * One or more icons displayed inside the slider region, on the left.
+     *
+     * If not provided and `icon` is set, that single icon
+     * is treated as `leadingIcons[0]`.
+     */
+    leadingIcons?: React.ReactNode[];
+    /**
+     * Icons displayed on the right side of the slider region
+     * (before/after the value label depending on placement).
+     */
+    trailingIcons?: React.ReactNode[];
+    /**
+     * Convenience single-icon prop for the left side.
+     */
+    icon?: React.ReactNode;
+    /**
+     * Base gap between icons and slider/value.
+     * Defaults to 4px-ish via `gap-1`.
+     */
+    iconGap?: number;
+    /**
+     * Extra spacing to apply between leading icons and the slider track.
+     */
+    leadingIconSpacing?: number;
+    /**
+     * Extra spacing to apply between trailing icons and the value label.
+     */
+    trailingIconSpacing?: number;
+    /**
+     * Arbitrary React node rendered before the slider (e.g. a button).
+     */
+    leadingControl?: React.ReactNode;
+    /**
+     * Arbitrary React node rendered after the slider (e.g. a button).
+     */
+    trailingControl?: React.ReactNode;
+    /**
+     * Extra classes for the leading control wrapper.
+     */
+    leadingControlClassName?: string;
+    /**
+     * Extra classes for the trailing control wrapper.
+     */
+    trailingControlClassName?: string;
+    /**
+     * If true and there are controls, the slider + controls share
+     * a single visual box (borders, radius, focus states).
+     * Default: true (to match text/select behaviour).
+     */
+    joinControls?: boolean;
+    /**
+     * When joinControls is true, whether the box styling extends over controls
+     * (true) or controls are visually separate (false).
+     * Default: true.
+     */
+    extendBoxToControls?: boolean;
+    /**
+     * Built-in +/- controls around the slider.
+     *
+     * - "none"  → no built-in step buttons (default)
+     * - "boxed" → +/- inside the same frame as the slider
+     * - "edge"  → loose layout: "- [ slider ] +"
+     */
+    controlVariant?: "none" | "boxed" | "edge";
+    /**
+     * Step used when clicking the +/- controls.
+     * Defaults to `step`.
+     */
+    controlStep?: number;
+    /**
+     * Custom node for the decrement control. Default: "−".
+     */
+    controlDecrementIcon?: React.ReactNode;
+    /**
+     * Custom node for the increment control. Default: "+".
+     */
+    controlIncrementIcon?: React.ReactNode;
+}
+
+/**
+ * Slider value type:
+ * - `number | undefined` for now (single-value slider).
+ *   If/when you add range support, this can be widened to [number, number].
+ */
+type SliderValue = number | undefined;
+
+type KeyValueMap = Record<string, string>;
+interface KV {
+    key: string;
+    value: string;
+}
+interface ShadcnKeyValueVariantProps extends Pick<VariantBaseProps<KeyValueMap | undefined>, "value" | "onValue" | "error" | "disabled" | "readOnly" | "size" | "density"> {
+    min?: number;
+    max?: number;
+    minVisible?: number;
+    maxVisible?: number;
+    showAddButton?: boolean;
+    showMenuButton?: boolean;
+    placeholder?: React.ReactNode;
+    dialogTitle?: React.ReactNode;
+    keyLabel?: React.ReactNode;
+    valueLabel?: React.ReactNode;
+    submitLabel?: React.ReactNode;
+    moreLabel?: (count: number) => React.ReactNode;
+    emptyLabel?: React.ReactNode;
+    className?: string;
+    chipsClassName?: string;
+    chipClassName?: string;
+    renderChip?: (ctx: {
+        pair: KV;
+        index: number;
+        onEdit: () => void;
+        onRemove: () => void;
+        defaultChip: React.ReactNode;
+    }) => React.ReactNode;
+}
+
+/**
+ * Props for the generic "custom" variant.
+ *
+ * - The only special props we define are:
+ *   - component: the React component to render
+ *   - valueProp / changeProp / disabledProp / readOnlyProp / errorProp
+ *   - idProp / nameProp / placeholderProp
+ *   - mapValue / mapDetail (optional hooks)
+ *
+ * - All other props are treated as "component props" and forwarded
+ *   directly to the underlying component.
+ *
+ * The underlying component is expected to:
+ *   - accept the mapped `valueProp`
+ *   - call the mapped `changeProp` with the next value (first argument)
+ *   - optionally use disabled/readOnly/error/id/name/placeholder via the mapped names
+ */
+interface ShadcnCustomVariantProps<TValue = unknown> extends VariantBaseProps<TValue> {
+    /**
+     * The actual React component to render.
+     *
+     * Example:
+     *   component={MyToggle}
+     */
+    component: React.ComponentType<any>;
+    /**
+     * Prop name that carries the current value for the component.
+     * Default: "value".
+     */
+    valueProp?: string;
+    /**
+     * Prop name for the change handler that the component will call.
+     * Default: "onChange".
+     *
+     * The component is expected to call:
+     *   props[changeProp](nextValue, ...otherArgs?)
+     *
+     * The first argument is taken as the new value.
+     */
+    changeProp?: string;
+    /**
+     * Prop name for disabled state.
+     * Default: "disabled".
+     */
+    disabledProp?: string;
+    /**
+     * Prop name for read-only state.
+     * Default: "readOnly".
+     */
+    readOnlyProp?: string;
+    /**
+     * Prop name for passing error to the component (if it cares).
+     * If provided, we pass the `error` field as-is.
+     * Example values: "error", "isInvalid", "status".
+     */
+    errorProp?: string;
+    /**
+     * Prop name for the id attribute.
+     * Default: "id".
+     */
+    idProp?: string;
+    /**
+     * Prop name for the name attribute.
+     * Default: "name".
+     */
+    nameProp?: string;
+    /**
+     * Prop name for the placeholder attribute.
+     * Default: "placeholder".
+     */
+    placeholderProp?: string;
+    /**
+     * Optional transform for the raw next value before it hits the field.
+     *
+     * Receives the first argument that the component passes to the change
+     * handler, plus the full argument list for flexibility.
+     */
+    mapValue?: (raw: any, ...args: any[]) => TValue;
+    /**
+     * Optional builder for ChangeDetail, given the raw next value.
+     *
+     * If omitted, a default { source: "variant", raw } detail is used.
+     */
+    mapDetail?: (raw: any, ...args: any[]) => ChangeDetail;
+    /**
+     * Any other props are assumed to belong to the custom component.
+     */
+    [key: string]: unknown;
+}
+
+type TreeKey = string | number;
+type TreeValue = TreeKey | TreeKey[] | undefined;
+type TreeSelectOption = TreeKey | {
+    label?: React__default.ReactNode;
+    value?: TreeKey;
+    description?: React__default.ReactNode;
+    disabled?: boolean;
+    icon?: React__default.ReactNode;
+    children?: TreeSelectOption[];
+    [key: string]: any;
+};
+type NormalizedTreeItem = {
+    key: string;
+    value: TreeKey;
+    labelNode: React__default.ReactNode;
+    labelText: string;
+    description?: React__default.ReactNode;
+    disabled?: boolean;
+    icon?: React__default.ReactNode;
+    level: number;
+    parentValue?: TreeKey;
+    path: TreeKey[];
+    hasChildren: boolean;
+    children: NormalizedTreeItem[];
+    raw: TreeSelectOption;
+};
+
+type BadgeVariant$1 = "default" | "secondary" | "destructive" | "outline";
+type TreeSelectBaseProps = Pick<VariantBaseProps<TreeValue>, "value" | "onValue" | "error" | "disabled" | "readOnly" | "size" | "density"> & {
+    options?: TreeSelectOption[];
+    /**
+     * If true, allows multiple selection (checkboxes).
+     * If false, allows single selection (no checkboxes, closes on select).
+     * Default: true
+     */
+    multiple?: boolean;
+    autoCap?: boolean;
+    optionLabel?: string | ((item: TreeSelectOption) => React.ReactNode);
+    optionValue?: string | ((item: TreeSelectOption) => TreeKey);
+    optionDescription?: string | ((item: TreeSelectOption) => React.ReactNode);
+    optionDisabled?: string | ((item: TreeSelectOption) => boolean);
+    optionIcon?: string | ((item: TreeSelectOption) => React.ReactNode);
+    optionKey?: string | ((item: TreeSelectOption, index: number) => React.Key);
+    searchable?: boolean;
+    searchPlaceholder?: string;
+    emptyLabel?: React.ReactNode;
+    emptySearchText?: React.ReactNode;
+    clearable?: boolean;
+    placeholder?: React.ReactNode;
+    className?: string;
+    triggerClassName?: string;
+    contentClassName?: string;
+    renderOption?: (ctx: {
+        item: NormalizedTreeItem;
+        selected: boolean;
+        index: number;
+        option: React.ReactNode;
+        click(): void;
+    }) => React.ReactNode;
+    renderValue?: (ctx: {
+        selectedItems: NormalizedTreeItem[];
+        placeholder?: React.ReactNode;
+    }) => React.ReactNode;
+    expandAll?: boolean;
+    defaultExpandedValues?: TreeKey[];
+    leafOnly?: boolean;
+};
+type TreeSelectDefaultModeProps = {
+    mode?: "default";
+    leadingIcons?: React.ReactNode[];
+    trailingIcons?: React.ReactNode[];
+    icon?: React.ReactNode;
+    iconGap?: number;
+    leadingIconSpacing?: number;
+    trailingIconSpacing?: number;
+    leadingControl?: React.ReactNode;
+    trailingControl?: React.ReactNode;
+    leadingControlClassName?: string;
+    trailingControlClassName?: string;
+    joinControls?: boolean;
+    extendBoxToControls?: boolean;
+    button?: never;
+    children?: never;
+    selectedBadge?: never;
+    selectedBadgeHiddenWhenZero?: never;
+    selectedBadgeVariant?: never;
+    selectedBadgeClassName?: never;
+    selectedBadgePlacement?: never;
+};
+type TreeSelectButtonModeButton = React.ReactNode | ((ctx: {
+    open: boolean;
+    selectedItems: NormalizedTreeItem[];
+    selectedCount: number;
+}) => React.ReactNode);
+type TreeSelectButtonModeProps = {
+    mode: "button";
+    /**
+     * Used when mode="button". If provided, this is the trigger.
+     * If not provided, `children` is used.
+     */
+    button?: TreeSelectButtonModeButton;
+    children?: TreeSelectButtonModeButton;
+    /**
+     * Selected-count badge (mode="button" only)
+     */
+    selectedBadge?: boolean;
+    selectedBadgeHiddenWhenZero?: boolean;
+    selectedBadgeVariant?: BadgeVariant$1;
+    selectedBadgeClassName?: string;
+    selectedBadgePlacement?: "end" | "corner";
+    leadingIcons?: never;
+    trailingIcons?: never;
+    icon?: never;
+    iconGap?: never;
+    leadingIconSpacing?: never;
+    trailingIconSpacing?: never;
+    leadingControl?: never;
+    trailingControl?: never;
+    leadingControlClassName?: never;
+    trailingControlClassName?: never;
+    joinControls?: never;
+    extendBoxToControls?: never;
+};
+type ShadcnTreeSelectVariantProps = TreeSelectBaseProps & (TreeSelectDefaultModeProps | TreeSelectButtonModeProps);
+
+declare const badgeVariants: (props?: ({
+    variant?: "default" | "destructive" | "outline" | "secondary" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+declare function Badge({ className, variant, asChild, ...props }: React.ComponentProps<"span"> & VariantProps<typeof badgeVariants> & {
+    asChild?: boolean;
+}): react_jsx_runtime.JSX.Element;
+
+type FileSourceKind = "native" | "path" | "url" | "custom";
+interface FileItem {
+    id: string;
+    kind: FileSourceKind;
+    file?: File;
+    path?: string;
+    url?: string;
+    name: string;
+    size?: number;
+    type?: string;
+    status?: "idle" | "loading" | "done" | "failed";
+    error?: string | null;
+    meta?: any;
+}
+type FileLike = File | string | {
+    id?: string;
+    file?: File;
+    path?: string;
+    url?: string;
+    name?: string;
+    size?: number;
+    type?: string;
+    status?: FileItem["status"];
+    error?: string | null;
+    meta?: any;
+    [key: string]: unknown;
+};
+type CustomFileLoaderResult = FileLike | FileLike[] | null | undefined;
+type CustomFileLoader = (ctx: {
+    multiple: boolean;
+    current: FileItem[];
+}) => Promise<CustomFileLoaderResult> | CustomFileLoaderResult;
+type BadgeVariant = React.ComponentProps<typeof Badge>["variant"];
+type FileVariantBaseProps = Pick<VariantBaseProps<FileItem[]>, "value" | "onValue" | "error" | "disabled" | "readOnly" | "size" | "density"> & {
+    multiple?: boolean;
+    accept?: string | string[];
+    maxFiles?: number;
+    maxTotalSize?: number;
+    showDropArea?: boolean;
+    dropIcon?: React.ReactNode;
+    dropTitle?: React.ReactNode;
+    dropDescription?: React.ReactNode;
+    renderDropArea?: (ctx: {
+        openPicker: () => void;
+        isDragging: boolean;
+    }) => React.ReactNode;
+    renderFileItem?: (ctx: {
+        item: FileItem;
+        index: number;
+        selected: boolean;
+        toggleSelected: () => void;
+        remove: () => void;
+    }) => React.ReactNode;
+    showCheckboxes?: boolean;
+    onFilesAdded?: (added: FileItem[], detail: ChangeDetail<{
+        from: "input" | "drop" | "custom-loader";
+    }>) => void;
+    customLoader?: CustomFileLoader;
+    mergeMode?: "append" | "replace";
+    formatFileName?: (item: FileItem) => React.ReactNode;
+    formatFileSize?: (size?: number) => React.ReactNode;
+    placeholder?: string;
+    className?: string;
+    dropAreaClassName?: string;
+    listClassName?: string;
+    triggerClassName?: string;
+};
+type FileDefaultModeProps = {
+    mode?: "default";
+    leadingIcons?: React.ReactNode[];
+    trailingIcons?: React.ReactNode[];
+    icon?: React.ReactNode;
+    leadingControl?: React.ReactNode;
+    trailingControl?: React.ReactNode;
+    leadingControlClassName?: string;
+    trailingControlClassName?: string;
+    joinControls?: boolean;
+    extendBoxToControls?: boolean;
+    button?: never;
+    children?: never;
+    selectedBadge?: never;
+    selectedBadgeHiddenWhenZero?: never;
+    selectedBadgeVariant?: never;
+    selectedBadgeClassName?: never;
+    selectedBadgePlacement?: never;
+};
+type FileButtonTrigger = React.ReactNode | ((ctx: {
+    open: boolean;
+    items: FileItem[];
+    selectedCount: number;
+    disabled: boolean;
+}) => React.ReactNode);
+type FileButtonModeProps = {
+    mode: "button";
+    /** Used when mode="button". If provided, this is the trigger. If not, `children` is used. */
+    button?: FileButtonTrigger;
+    children?: FileButtonTrigger;
+    /** Selected-count badge (mode="button" only) */
+    selectedBadge?: boolean;
+    selectedBadgeHiddenWhenZero?: boolean;
+    selectedBadgeVariant?: BadgeVariant;
+    selectedBadgeClassName?: string;
+    selectedBadgePlacement?: "end" | "corner";
+    leadingIcons?: never;
+    trailingIcons?: never;
+    icon?: never;
+    leadingControl?: never;
+    trailingControl?: never;
+    leadingControlClassName?: never;
+    trailingControlClassName?: never;
+    joinControls?: never;
+    extendBoxToControls?: never;
+};
+type ShadcnFileVariantProps = FileVariantBaseProps & (FileDefaultModeProps | FileButtonModeProps);
+
+type SelectPrimitive = string | number;
+type SelectOption = SelectPrimitive | {
+    label?: React.ReactNode;
+    value?: SelectPrimitive;
+    description?: React.ReactNode;
+    disabled?: boolean;
+    [key: string]: any;
+};
+type NormalizedSelectItem = {
+    key: string;
+    value: SelectPrimitive;
+    labelNode: React.ReactNode;
+    labelText: string;
+    description?: React.ReactNode;
+    disabled?: boolean;
+    icon?: React.ReactNode;
+    /** Option-level renderer (falls back to global renderOption) */
+    render?: (...args: any[]) => React.ReactNode;
+    raw: SelectOption;
+};
+/**
+ * Shadcn-based Select variant.
+ */
+interface SelectBaseProps extends Pick<VariantBaseProps<SelectPrimitive | undefined>, "value" | "onValue" | "error" | "disabled" | "readOnly" | "size" | "density"> {
+    /**
+     * Options for the select.
+     *
+     * You can pass:
+     * - primitives: ["ng", "gh", "ke"]
+     * - objects:    [{ label, value, ...extra }]
+     */
+    options?: SelectOption[];
+    /**
+     * Automatically capitalise the first letter of the label
+     * (when the resolved label is a string).
+     */
+    autoCap?: boolean;
+    /**
+     * How to read the label from each option.
+     *
+     * - string → key on the option object
+     * - function → custom mapper
+     * - omitted → tries `label`, else String(value)
+     */
+    optionLabel?: string | ((item: SelectOption) => React.ReactNode);
+    /**
+     * How to read the value from each option.
+     *
+     * - string → key on the option object
+     * - function → custom mapper
+     * - omitted → uses `value`, or `id`, or `key`, or index
+     */
+    optionValue?: string | ((item: SelectOption) => SelectPrimitive);
+    /**
+     * Optional description line under the label.
+     */
+    optionDescription?: string | ((item: SelectOption) => React.ReactNode);
+    /**
+     * How to determine if an option is disabled.
+     */
+    optionDisabled?: string | ((item: SelectOption) => boolean);
+    /**
+     * How to extract an icon for each option.
+     *
+     * - string → key on the option object (default "icon")
+     * - function → custom mapper
+     */
+    optionIcon?: string | ((item: SelectOption) => React.ReactNode);
+    /**
+     * How to compute the React key for each option.
+     */
+    optionKey?: string | ((item: SelectOption, index: number) => React.Key);
+    /**
+     * Enable inline search inside the dropdown.
+     */
+    searchable?: boolean;
+    /**
+     * Placeholder for the search input.
+     */
+    searchPlaceholder?: string;
+    /**
+     * Label shown when there are no options available at all.
+     *
+     * If omitted, falls back to `emptySearchText` or a default message.
+     */
+    emptyLabel?: React.ReactNode;
+    /**
+     * Text to show when search yields no results
+     * (but there *are* options in general).
+     */
+    emptySearchText?: React.ReactNode;
+    /**
+     * Show a small clear button in the trigger when a value is selected.
+     */
+    clearable?: boolean;
+    /**
+     * Placeholder when nothing is selected.
+     */
+    placeholder?: React.ReactNode;
+    /**
+     * Wrapper class for the whole variant.
+     */
+    className?: string;
+    /**
+     * Extra classes for the SelectTrigger.
+     */
+    triggerClassName?: string;
+    /**
+     * Extra classes for the SelectContent popover.
+     */
+    contentClassName?: string;
+    /**
+     * Custom renderer for each option row.
+     */
+    renderOption?: (ctx: {
+        item: NormalizedSelectItem;
+        selected: boolean;
+        index: number;
+        option: React.ReactNode;
+        click(): void;
+    }) => React.ReactNode;
+    /**
+     * Custom renderer for the trigger value.
+     */
+    renderValue?: (ctx: {
+        selectedItem: NormalizedSelectItem | null;
+        placeholder?: React.ReactNode;
+    }) => React.ReactNode;
+    /**
+     * Icons displayed on the right side of the trigger,
+     * near the clear button / chevron area.
+     */
+    trailingIcons?: React.ReactNode[];
+    /**
+     * Convenience single-icon prop for the left side.
+     */
+    icon?: React.ReactNode;
+    /**
+     * Base gap between icons and text.
+     * Defaults to 4px-ish via `gap-1`.
+     */
+    iconGap?: number;
+    /**
+     * Extra spacing to apply between leading icons and the text.
+     */
+    leadingIconSpacing?: number;
+    /**
+     * Extra spacing to apply between trailing icons and the clear button.
+     */
+    trailingIconSpacing?: number;
+    /**
+     * Arbitrary React node rendered before the select (e.g. a button).
+     */
+    leadingControl?: React.ReactNode;
+    /**
+     * Arbitrary React node rendered after the select (e.g. a button).
+     */
+    trailingControl?: React.ReactNode;
+    /**
+     * Extra classes for the leading control wrapper.
+     */
+    leadingControlClassName?: string;
+    /**
+     * Extra classes for the trailing control wrapper.
+     */
+    trailingControlClassName?: string;
+    /**
+     * If true and there are controls, the select trigger + controls share
+     * a single visual box (borders, radius, focus states).
+     */
+    joinControls?: boolean;
+    /**
+     * When joinControls is true, whether the box styling extends over controls
+     * (true) or controls are visually separate (false).
+     */
+    extendBoxToControls?: boolean;
+    /**
+     * Enable incremental rendering for large option lists.
+     *
+     * When true, only a page of options is rendered initially,
+     * and more are revealed as the user scrolls down.
+     */
+    virtualScroll?: boolean;
+    /**
+     * Number of options to render per "page" when virtualScroll is enabled.
+     * Default: 50.
+     */
+    virtualScrollPageSize?: number;
+    /**
+     * Distance from the bottom (in px) at which the next page loads.
+     * Default: 48px.
+     */
+    virtualScrollThreshold?: number;
+}
+type SelectDefaultModeProps = {
+    mode?: "default";
+    leadingIcons?: React.ReactNode[];
+    trailingIcons?: React.ReactNode[];
+    icon?: React.ReactNode;
+    iconGap?: number;
+    leadingIconSpacing?: number;
+    trailingIconSpacing?: number;
+    leadingControl?: React.ReactNode;
+    trailingControl?: React.ReactNode;
+    leadingControlClassName?: string;
+    trailingControlClassName?: string;
+    joinControls?: boolean;
+    extendBoxToControls?: boolean;
+    button?: never;
+    children?: never;
+};
+type SelectButtonModeButton = React.ReactNode | ((ctx: {
+    open: boolean;
+    selectedItem: NormalizedSelectItem | null;
+    selectedValue: SelectPrimitive | undefined;
+    placeholder?: React.ReactNode;
+}) => React.ReactNode);
+type SelectButtonModeProps = {
+    mode: "button";
+    /**
+     * Used when mode="button". If provided, this is the trigger.
+     * If not provided, `children` is used.
+     */
+    button?: SelectButtonModeButton;
+    children?: SelectButtonModeButton;
+    leadingIcons?: never;
+    trailingIcons?: never;
+    icon?: never;
+    iconGap?: never;
+    leadingIconSpacing?: never;
+    trailingIconSpacing?: never;
+    leadingControl?: never;
+    trailingControl?: never;
+    leadingControlClassName?: never;
+    trailingControlClassName?: never;
+    joinControls?: never;
+    extendBoxToControls?: never;
+};
+type ShadcnSelectVariantProps = SelectBaseProps & (SelectDefaultModeProps | SelectButtonModeProps);
+
+type SelectVariantProps = ShadcnSelectVariantProps;
+
+interface ToggleOption {
+    label: React.ReactNode;
+    value: string;
+    icon?: React.ReactNode;
+    disabled?: boolean;
+    tooltip?: React.ReactNode;
+    meta?: any;
+}
+/**
+ * Allow primitive options as shorthand:
+ * - "free" → { value: "free", label: "free" }
+ */
+type ToggleOptionInput = ToggleOption | string | number | boolean;
+interface ShadcnToggleVariantProps extends Pick<VariantBaseProps<string | string[]>, "value" | "onValue" | "error" | "disabled" | "readOnly" | "size" | "density"> {
+    /**
+     * Options for the toggle group.
+     *
+     * Can be:
+     * - ToggleOption objects
+     * - Primitive strings/numbers/booleans (shorthand)
+     * - Objects using option* keys (optionValue, optionLabel, etc.)
+     */
+    options: ToggleOptionInput[];
+    multiple?: boolean;
+    variant?: "default" | "outline";
+    layout?: "horizontal" | "vertical" | "grid";
+    gridCols?: number;
+    fillWidth?: boolean;
+    /**
+     * Property name to read the option value from, when using
+     * custom option objects.
+     *
+     * If omitted, falls back to:
+     *   - obj.value
+     *   - or the primitive itself (for primitive options)
+     */
+    optionValue?: string;
+    /**
+     * Property name to read the option label from, when using
+     * custom option objects.
+     *
+     * If omitted, falls back to:
+     *   - obj.label
+     *   - or String(value)
+     */
+    optionLabel?: string;
+    /**
+     * Property name to read an icon node from, when using
+     * custom option objects.
+     *
+     * If omitted, falls back to obj.icon.
+     */
+    optionIcon?: string;
+    /**
+     * Property name to read disabled flag from, when using
+     * custom option objects.
+     *
+     * If omitted, falls back to obj.disabled.
+     */
+    optionDisabled?: string;
+    /**
+     * Property name to read tooltip content from, when using
+     * custom option objects.
+     *
+     * If omitted, falls back to obj.tooltip.
+     */
+    optionTooltip?: string;
+    /**
+     * Property name to read meta from, when using custom option objects.
+     *
+     * If omitted, falls back to obj.meta.
+     */
+    optionMeta?: string;
+    /**
+     * Optional custom renderer for each option.
+     * Receives the normalized ToggleOption and selected state.
+     */
+    renderOption?: (option: ToggleOption, isSelected: boolean) => React.ReactNode;
+    className?: string;
+    /** Base class for all items */
+    itemClassName?: string;
+    /** Class applied ONLY to selected items (overrides/merges with default active styles) */
+    activeClassName?: string;
+    /**
+     * When true, capitalizes the first letter of the label
+     * (only applied when the label is a string).
+     */
+    autoCap?: boolean;
+    /**
+     * Gap between buttons in pixels.
+     *
+     * - Applies to both flex (horizontal/vertical) and grid layouts.
+     * - If omitted, falls back to Tailwind gap classes.
+     */
+    gap?: number;
+}
+
+/**
+ * Host app MUST import Toast UI Editor CSS:
+ *   import "@toast-ui/editor/dist/toastui-editor.css";
+ */
+type ToastToolbarItem = "heading" | "bold" | "italic" | "strike" | "hr" | "quote" | "ul" | "ol" | "task" | "indent" | "outdent" | "table" | "image" | "link" | "code" | "codeblock";
+type EditorFormat = "html" | "markdown";
+type EditorToolbar = "default" | "none" | ToastToolbarItem[][];
+interface ShadcnEditorVariantProps extends Pick<VariantBaseProps<string | undefined>, "value" | "onValue" | "error" | "disabled" | "readOnly" | "required" | "size" | "density"> {
+    placeholder?: string;
+    height?: string;
+    previewStyle?: "vertical" | "tab";
+    editType?: "wysiwyg" | "markdown";
+    useCommandShortcut?: boolean;
+    /** Which format to store in the form value */
+    format?: EditorFormat;
+    /**
+     * Toolbar config:
+     * - "default" uses Toast UI defaults
+     * - "none" hides tools + mode switch
+     * - array provides toolbarItems
+     */
+    toolbar?: EditorToolbar;
+    /** If true, paste is intercepted and inserted as plain text only */
+    pastePlainText?: boolean;
+    className?: string;
+}
+
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+type JsonObject = Record<string, JsonValue>;
+type JsonPath = string;
+type JsonWildcard = string;
+
+/**
+ * A "variant spec" can be:
+ * - a plain VariantKey ("text", "number", "toggle", ...)
+ * - a variant key + props to pass into that variant
+ */
+type JsonEditorVariantSpec = VariantKey | {
+    variant: VariantKey;
+    props?: VariantPropsFor<any>;
+};
+/**
+ * Map a key-path (or wildcard) to a variant spec.
+ *
+ * Keys are matched against:
+ * - full path:  "config.apiEndpoint"
+ * - leaf key:   "apiEndpoint"
+ *
+ * Wild examples:
+ * - "*api*"             (segment contains "api")
+ * - "config.*"          (direct children)
+ * - "config.**"         (subtree)
+ * - "**.*token*"        (any route/leaf)
+ */
+type JsonEditorFieldMap = Record<JsonWildcard, JsonEditorVariantSpec>;
+/**
+ * Layout is scoped to a "page" (object route path).
+ *
+ * Each entry is a "row":
+ * - string: render a single field row
+ * - string[]: render these fields side-by-side (grid row)
+ *
+ * Example:
+ * layout: {
+ *   "": [["projectName","version"], "description"],
+ *   "config": [["maxEntries","apiEndpoint"], "retry"]
+ * }
+ */
+type JsonEditorLayoutRow = string | string[];
+type JsonEditorLayoutMap = Record<JsonWildcard, JsonEditorLayoutRow[]>;
+interface JsonEditorFilters {
+    /** Hide entire object routes/pages (navigation + rendering) */
+    excludeRoutes?: JsonWildcard[];
+    includeRoutes?: JsonWildcard[];
+    /** Hide specific fields (by full path or leaf/wild patterns) */
+    excludeFields?: JsonWildcard[];
+    includeFields?: JsonWildcard[];
+    /**
+     * If true, excluding "config" also excludes "config.**".
+     * Default: true
+     */
+    excludeRouteSubtree?: boolean;
+}
+/**
+ * Default value for a newly created key (or a new array item).
+ * Can be a constant JsonValue, or a function.
+ */
+type JsonEditorDefaultValueSpec = JsonValue | ((ctx: {
+    parentPath: JsonPath;
+    key: string;
+    current: JsonValue | undefined;
+}) => JsonValue);
+interface JsonEditorDefaults {
+    /**
+     * When adding a new array item, you can pick from allowed variants.
+     * You can pass VariantKey or a {variant, props} spec.
+     */
+    array?: JsonEditorVariantSpec[];
+    /**
+     * Optional default values for new keys.
+     * Keyed by wildcard path (full path / leaf / patterns).
+     */
+    values?: Record<JsonWildcard, JsonEditorDefaultValueSpec>;
+}
+type JsonEditorNavMode = "sidebar" | "tabs" | "drawer";
+interface JsonEditorNavOptions {
+    mode?: JsonEditorNavMode;
+    /** Show root "" as a page in navigation. Default: true */
+    showRoot?: boolean;
+    /** Initial active route/page. Default: "" */
+    defaultRoute?: JsonPath;
+    /** Optional label overrides for route nodes */
+    routeLabels?: Record<JsonWildcard, React.ReactNode>;
+    /** Max object nesting to generate routes for. Optional safety */
+    maxDepth?: number;
+    /**
+     * Whether arrays containing objects can contribute routes.
+     * - "none": arrays never create routes (default)
+     * - "objects": array items that are objects become routes like "config.items.0"
+     */
+    arrayRoutes?: "none" | "objects";
+}
+interface JsonRouteNode {
+    path: JsonPath;
+    key: string;
+    label: React.ReactNode;
+    children: JsonRouteNode[];
+}
+type JsonEditorViewMode = "split" | "visual" | "raw";
+interface JsonEditorPermissions {
+    canAdd?: boolean;
+    canDelete?: boolean;
+    canViewRaw?: boolean;
+    canEditRaw?: boolean;
+    /**
+     * Keys/paths in this shape cannot be deleted even if canDelete is true.
+     * (treated as "locked")
+     */
+    defaultShape?: JsonObject;
+    /**
+     * Optional finer-grain locks by wildcard.
+     * If true, this key/path cannot be added/deleted/edited.
+     */
+    lockPaths?: JsonWildcard[];
+}
+type JsonEditorEditAction = "add" | "delete" | "edit" | "edit-raw";
+interface JsonEditorEditMeta {
+    action: JsonEditorEditAction;
+    /** the page (object route) currently being edited */
+    route: JsonPath;
+    /** the exact key path being changed (field path) */
+    path: JsonPath;
+    /** parent object path of the key */
+    parent: JsonPath;
+    /** leaf key (segment) */
+    key: string;
+}
+interface JsonEditorCallbacks {
+    onAdd?: (nextRoot: JsonObject, meta: JsonEditorEditMeta) => void;
+    onDelete?: (nextRoot: JsonObject, meta: JsonEditorEditMeta) => void;
+    onEdit?: (nextRoot: JsonObject, meta: JsonEditorEditMeta) => void;
+}
+interface JsonEditorResolvedField {
+    path: JsonPath;
+    key: string;
+    value: JsonValue;
+    valueType: "string" | "number" | "boolean" | "null" | "object" | "array";
+    variant?: JsonEditorVariantSpec;
+    hidden?: boolean;
+}
+/**
+ * This is the "shared" props contract for the JSON editor variant UI.
+ *
+ * NOTE:
+ * - `title` is purely UI (header text)
+ * - `schema` is NOT a title — it’s a schema id/key for validation (later use)
+ */
+interface ShadcnJsonEditorVariantProps extends Pick<VariantBaseProps<JsonObject | undefined>, "value" | "onValue" | "error" | "disabled" | "readOnly"> {
+    /** Header title (UI only) */
+    title?: React.ReactNode;
+    /** Optional schema id/key or raw JSON Schema object for validation */
+    schema?: string | JsonObject;
+    /** Primary config */
+    fieldMap?: JsonEditorFieldMap;
+    layout?: JsonEditorLayoutMap;
+    defaults?: JsonEditorDefaults;
+    /** Navigation derived from JSON structure */
+    nav?: JsonEditorNavOptions;
+    /** include/exclude for routes + fields */
+    filters?: JsonEditorFilters;
+    /** permissions + locks */
+    permissions?: JsonEditorPermissions;
+    /** callbacks */
+    callbacks?: JsonEditorCallbacks;
+    /**
+     * Page rendering mode:
+     * - "accordion": page sections expand/collapse in main panel
+     * - "popover": nested objects open as overlays (optional UX)
+     */
+    mode?: "accordion" | "popover";
+    /**
+     * Routing:
+     * - route: controlled current page
+     * - defaultRoute: uncontrolled initial page (overrides nav.defaultRoute)
+     * - onRouteChange: called whenever the editor navigates
+     */
+    route?: JsonPath;
+    defaultRoute?: JsonPath;
+    onRouteChange?: (route: JsonPath) => void;
+    /**
+     * View mode (top toggle):
+     * - "split": raw sidebar + visual editor (default)
+     * - "visual": visual editor only
+     * - "raw": raw editor only
+     *
+     * If viewMode is provided, it is controlled.
+     * Otherwise, the defaultViewMode seeds the internal state.
+     */
+    viewMode?: JsonEditorViewMode;
+    defaultViewMode?: JsonEditorViewMode;
+    onViewModeChange?: (mode: JsonEditorViewMode) => void;
+    /** Close button intent (optional). Actual close UI is controlled by the wrapper (index.tsx). */
+    onClose?: () => void;
+    /** Visual (editor-level styling) */
+    className?: string;
+    contentClassName?: string;
+    navClassName?: string;
+    /**
+     * Optional hooks to customize nav + page rendering.
+     */
+    renderRouteLabel?: (ctx: {
+        node: JsonRouteNode;
+        active: boolean;
+    }) => React.ReactNode;
+    renderField?: (ctx: {
+        field: JsonEditorResolvedField;
+        route: JsonPath;
+    }) => React.ReactNode;
+    leadingIcons?: React.ReactNode[];
+    trailingIcons?: React.ReactNode[];
+    icon?: React.ReactNode;
+    iconGap?: number;
+    leadingIconSpacing?: number;
+    trailingIconSpacing?: number;
+    leadingControl?: React.ReactNode;
+    trailingControl?: React.ReactNode;
+    leadingControlClassName?: string;
+    trailingControlClassName?: string;
+    joinControls?: boolean;
+    extendBoxToControls?: boolean;
+    triggerClassName?: string;
+}
+/**
+ * Wrapper mode:
+ * - "popover": show trigger + popover
+ * - "accordion": inline panel that can expand/collapse
+ */
+type JsonEditorMode = "popover" | "accordion";
+/**
+ * Typed to match your shadcn button variants/sizes.
+ * If your project differs, change these unions here once.
+ */
+type JsonEditorTriggerVariant = "default" | "destructive" | "outline" | "secondary" | "ghost" | "link";
+type JsonEditorTriggerSize = "default" | "sm" | "lg" | "icon";
+/**
+ * Exposed ref handle from index.tsx wrapper (not the inner editor).
+ * The wrapper controls popover open/close; it can also expose the inner editor ref.
+ */
+interface JsonEditorIndexHandle {
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    editor: React.RefObject<any>;
+}
+/**
+ * Standalone wiring:
+ * - caller provides root/onRoot directly
+ */
+type JsonEditorStandaloneWiring = {
+    root: JsonObject;
+    onRoot: (nextRoot: JsonObject, detail?: any) => void;
+    value?: never;
+    onValue?: never;
+};
+/**
+ * Variant wiring:
+ * - InputField variant uses value/onValue
+ */
+type JsonEditorVariantWiring = Pick<VariantBaseProps<JsonObject | undefined>, "value" | "onValue" | "disabled" | "readOnly" | "error" | "size" | "density"> & {
+    root?: never;
+    onRoot?: never;
+};
+/**
+ * Props for the exported component (index.tsx):
+ * - accepts standalone OR variant wiring
+ * - wrapper owns mode/open/trigger UI
+ * - editor-specific props are passed through, without redefining a second type list
+ *
+ * IMPORTANT:
+ * - wrapper uses `wrapperClassName` (outer container)
+ * - editor uses `className` (inner editor surface)
+ */
+interface JsonEditorWrapperProps {
+    /** Wrapper mode (popover vs accordion). */
+    mode?: JsonEditorMode;
+    /** Trigger UI (popover mode) */
+    triggerLabel?: React.ReactNode;
+    triggerVariant?: JsonEditorTriggerVariant;
+    triggerSize?: JsonEditorTriggerSize;
+    /** Popover sizing/skin */
+    popoverClassName?: string;
+    /** Inline/accordion container class */
+    panelClassName?: string;
+    /** Outer wrapper class */
+    wrapperClassName?: string;
+    /** Optional: controlled popover open state */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Accessibility (useful when rendered as an InputField variant) */
+    id?: string;
+    describedBy?: string;
+    /** Called when the wrapper closes (popover close / accordion hide). */
+    onClose?: () => void;
+}
+/**
+ * Single source of truth for what index.tsx accepts:
+ * - (standalone OR variant wiring)
+ * - wrapper props
+ * - editor props (minus a few keys owned by wrapper)
+ */
+type ShadcnJsonEditorProps = (JsonEditorStandaloneWiring | JsonEditorVariantWiring) & JsonEditorWrapperProps & Omit<ShadcnJsonEditorVariantProps, "onValue" | "value" | "disabled" | "readOnly" | "error" | "size" | "density" | "onClose">;
+
+type ListerId = string | number;
+type ListerMode = "single" | "multiple";
+type ListerSearchMode = "local" | "remote" | "hybrid";
+type ListerOpenReason = "apply" | "cancel" | "close" | "denied" | "error";
+type ListerSessionId = string;
+/** Extraction selector:
+ * - string form is runtime-only (dot-path); not type-checked
+ * - function form is typed and must return an array
+ */
+type Selector<TRaw> = string | ((body: any) => TRaw[]);
+/** Resolver:
+ * - string form is runtime-only (dot-path relative to raw item)
+ * - function form is fully typed
+ */
+type Resolver<TOut, TRaw, TCtx = any> = string | ((raw: TRaw, ctx: TCtx) => TOut);
+type OpenAnchor = {
+    x: number;
+    y: number;
+} | {
+    clientX: number;
+    clientY: number;
+} | any;
+type ListerChangeEvent = {
+    preventDefault(): void;
+    defaultPrevented: boolean;
+};
+type ListerLogLevel = "info" | "success" | "warning" | "error";
+type ListerLogCode = "lister.access_denied" | "lister.fetch_failed" | "lister.extract_not_array" | "lister.mapping_failed" | "lister.unknown_error";
+type ListerLogEntry = {
+    level: ListerLogLevel;
+    code: ListerLogCode;
+    message: string;
+    details?: Record<string, unknown>;
+    ui?: {
+        mode?: "toast" | "banner" | "dialog";
+        group?: string;
+        autoCloseMs?: number | null;
+    };
+};
+type ListerPermissionCtx = {
+    kind?: string;
+    endpoint?: string;
+    filters?: any;
+    sessionId?: ListerSessionId;
+};
+interface ListerProviderHost {
+    /** Host decides permission logic. Mandatory permissions end with '!' */
+    can: (permissions: string[], ctx: ListerPermissionCtx) => boolean;
+    /** Host decides notification/diagnostic surface */
+    log: (entry: ListerLogEntry) => void;
+}
+type ListerOption<TRaw, TValue extends ListerId, TMeta = unknown> = {
+    value: TValue;
+    label: any;
+    icon?: any;
+    description?: any;
+    disabled?: boolean;
+    group?: string;
+    meta?: TMeta;
+    /** optional raw passthrough (implementation choice) */
+    raw?: TRaw;
+};
+type ListerMapping<TRaw, TValue extends ListerId, TMeta = unknown, TCtx = any> = {
+    optionValue: Resolver<TValue, TRaw, TCtx>;
+    /** default: raw.label ?? String(value) */
+    optionLabel?: Resolver<any, TRaw, TCtx>;
+    optionIcon?: Resolver<any, TRaw, TCtx>;
+    optionDescription?: Resolver<any, TRaw, TCtx>;
+    optionDisabled?: Resolver<boolean, TRaw, TCtx>;
+    optionGroup?: Resolver<string, TRaw, TCtx>;
+    optionMeta?: Resolver<TMeta, TRaw, TCtx>;
+};
+type ListerSource<TFilters = unknown> = {
+    endpoint: string;
+    method?: "GET" | "POST";
+    /** Optional custom mapping of filters/query/cursor into request params/body/headers */
+    buildRequest?: (args: {
+        filters?: TFilters;
+        query?: string;
+        cursor?: string | null;
+    }) => {
+        params?: any;
+        body?: any;
+        headers?: any;
+    };
+};
+type ListerSearchSpec<TColumn extends string = string> = {
+    /**
+     * Columns the UI can offer as "Subject" (search in one column).
+     * Example: ["name", "email", "status"]
+     */
+    subjects?: readonly TColumn[];
+    /**
+     * Columns the UI can offer as "Search only" (search across multiple columns).
+     * Example: ["name", "email"]
+     */
+    only?: readonly TColumn[];
+    /**
+     * Allow user to type a column name that isn't in `subjects`.
+     * (Your backend still decides whether to accept/reject it.)
+     */
+    allowCustomSubject?: boolean;
+    /**
+     * Allow user to add custom column names to the multi-field "only" list.
+     * Useful if you want advanced users to target niche columns.
+     */
+    allowCustomOnly?: boolean;
+    /**
+     * Whether the UI can show a "Search all" option.
+     * (Semantics depend on your backend: usually "all text columns".)
+     */
+    allowAll?: boolean;
+    /**
+     * Optional UI hints (totally optional, but nice for button labels/placeholders).
+     */
+    ui?: {
+        placeholder?: string;
+        subjectLabel?: string;
+        allLabel?: string;
+        onlyLabel?: string;
+        customSubjectLabel?: string;
+    };
+    default?: string;
+};
+type ListerDefinition<TRaw, TValue extends ListerId, TFilters = unknown, TMeta = unknown, TCtx = any, TSearchColumn extends string = string> = {
+    /** optional stable id used by presets */
+    id?: string;
+    source: ListerSource<TFilters>;
+    /** If missing: default extraction uses body.data (runtime). Must produce an array. */
+    selector?: Selector<TRaw>;
+    /** How raw item maps into selectable option */
+    mapping: ListerMapping<TRaw, TValue, TMeta, TCtx>;
+    /**
+     * Search configuration:
+     * - defines which columns are searchable (subject + multi-field)
+     * - optionally allows custom column names (advanced mode)
+     */
+    search?: ListerSearchSpec<TSearchColumn>;
+};
+type ListerFilterApplyMode = "replace" | "merge" | "unset";
+type ListerFilterApply<TFilters, K extends keyof TFilters & string> = {
+    key: K;
+    mode?: ListerFilterApplyMode;
+    value?: TFilters[K];
+    toggleable?: boolean;
+    /** optional: clicking cycles through these states */
+    cycle?: Array<{
+        mode: "unset";
+    } | {
+        mode: "replace";
+        value: TFilters[K];
+    } | {
+        mode: "merge";
+        value: Partial<TFilters>;
+    }>;
+};
+type ListerFilterCtx<TFilters> = {
+    /** base filters passed to open() */
+    base: TFilters | undefined;
+    /** only what filter controls changed */
+    patch: Partial<TFilters>;
+    /** base + patch (merged) */
+    effective: TFilters | undefined;
+    set<K extends keyof TFilters & string>(key: K, value: TFilters[K]): void;
+    merge(patch: Partial<TFilters>): void;
+    unset<K extends keyof TFilters & string>(key: K): void;
+    clear(): void;
+    /** triggers refetch using current effective filters */
+    refresh(): void;
+    /** reads from effective (base overridden by patch) */
+    get<K extends keyof TFilters & string>(key: K): TFilters[K] | undefined;
+};
+type ListerFilterBindKey<TFilters> = keyof TFilters & string;
+/**
+ * OPTIONAL inline input filter config
+ * (value comes from the input; not from option.value)
+ */
+type ListerFilterInput<TFilters> = {
+    /** If omitted, falls back to option.bindKey (or parent bindKey). */
+    bindKey?: ListerFilterBindKey<TFilters>;
+    variant: VariantKey;
+    props?: VariantPropsFor<any>;
+    mode?: "replace" | "merge";
+    unsetOnEmpty?: boolean;
+};
+type FilterNodeBase<TFilters> = {
+    /**
+     * UI identity (must be unique in the tree)
+     * Example: "status", "status.active", "pricing.minMax"
+     */
+    id: string | number;
+    label?: any;
+    icon?: any;
+    description?: any;
+    disabled?: boolean;
+    /**
+     * Column/reference key (DB filter key).
+     * Example: "status"
+     *
+     * Typically set on a group node and inherited by children.
+     */
+    bindKey?: ListerFilterBindKey<TFilters>;
+    /**
+     * Optional custom render (advanced).
+     * (Still works, but now you can also use kind="input" for most cases.)
+     */
+    render?: (args: {
+        option: ListerFilterOption<TFilters>;
+        ctx: ListerFilterCtx<TFilters>;
+        state: {
+            open: boolean;
+            selected: boolean;
+        };
+        actions: {
+            close(): void;
+        };
+    }) => any;
+};
+type ListerFilterGroupOption<TFilters> = FilterNodeBase<TFilters> & {
+    kind: "group";
+    children: Array<ListerFilterOption<TFilters>>;
+    apply?: never;
+    input?: never;
+    value?: never;
+};
+type ListerFilterValueOption<TFilters, TValue = string | number> = FilterNodeBase<TFilters> & {
+    kind: "value";
+    /**
+     * Actual DB value. Example: "active"
+     * (NOT "status.active")
+     */
+    value: TValue;
+    /**
+     * Optional: clicking this item applies/unapplies it.
+     * If apply.value is omitted => defaults to option.value
+     */
+    apply?: ListerFilterApply<TFilters, any>;
+    children?: never;
+    input?: never;
+};
+type ListerFilterInputOption<TFilters> = FilterNodeBase<TFilters> & {
+    kind: "input";
+    /**
+     * Value comes from the input; binds to bindKey (option.bindKey or input.bindKey).
+     */
+    input: ListerFilterInput<TFilters>;
+    children?: never;
+    apply?: never;
+    value?: never;
+};
+type ListerFilterOption<TFilters> = ListerFilterGroupOption<TFilters> | ListerFilterValueOption<TFilters> | ListerFilterInputOption<TFilters>;
+type ListerFilterSpec<TFilters> = {
+    /** TreeSelect options */
+    options: Array<ListerFilterOption<TFilters>>;
+    /** Merge base + patch into effective */
+    merge?: (base: TFilters | undefined, patch: Partial<TFilters>) => TFilters;
+    /** Default: true. If true, any ctx.set/merge/unset triggers a fetch */
+    autoFetch?: boolean;
+};
+type ListerValueForMode<TValue extends ListerId, TMode extends ListerMode> = TMode extends "multiple" ? TValue[] : TValue | null;
+type ListerRawForMode<TRaw, TMode extends ListerMode> = TMode extends "multiple" ? TRaw[] : TRaw | null;
+type ListerOptionsForMode<TRaw, TValue extends ListerId, TMeta, TMode extends ListerMode> = TMode extends "multiple" ? Array<ListerOption<TRaw, TValue, TMeta>> : ListerOption<TRaw, TValue, TMeta> | null;
+type ListerDetails<TRaw, TValue extends ListerId, TMeta, TMode extends ListerMode> = {
+    /** Selected mapped options (array in multiple, single option/null in single) */
+    options: ListerOptionsForMode<TRaw, TValue, TMeta, TMode>;
+    /** Selected raw backend item(s) (array only in multiple mode) */
+    raw: ListerRawForMode<TRaw, TMode>;
+    /** Live change semantic while open */
+    action: "select" | "deselect" | "clear" | "init";
+};
+type ListerOpenOptions<TRaw, TValue extends ListerId, TFilters, TMeta, TMode extends ListerMode = "single"> = {
+    /** Mode defaults to "single" */
+    mode?: TMode;
+    /** Single-mode only: if true => Apply/Cancel UI, draft selection until Apply */
+    confirm?: TMode extends "single" ? boolean : never;
+    /** Initial selection when opened (draft seed) */
+    defaultValue?: ListerValueForMode<TValue, TMode>;
+    /** Permission entries; mandatory end with '!' */
+    permissions?: string[];
+    /** Search behaviour */
+    searchMode?: ListerSearchMode;
+    initialQuery?: string;
+    /** UI */
+    title?: string;
+    draggable?: boolean;
+    anchor?: OpenAnchor;
+    /** Refresh */
+    showRefresh?: boolean;
+    refreshMode?: "preserve-selection" | "clear-missing" | "clear-all";
+    /** Filters control (TreeSelect-native options; render supported) */
+    filtersSpec?: ListerFilterSpec<TFilters>;
+    /** Custom row renderer */
+    renderOption?: (args: {
+        option: ListerOption<TRaw, TValue, TMeta>;
+        state: {
+            selected: boolean;
+            active: boolean;
+            mode: TMode;
+        };
+        actions: {
+            toggle(): void;
+            select(): void;
+            deselect(): void;
+        };
+        ctx: {
+            query?: string;
+            filters?: TFilters;
+        };
+    }) => any;
+    /** Live change hook (sync + veto) */
+    onChange?: (value: ListerValueForMode<TValue, TMode>, details: ListerDetails<TRaw, TValue, TMeta, TMode>, e: ListerChangeEvent) => void;
+};
+type ListerOpenResult<TRaw, TValue extends ListerId, TMeta, TMode extends ListerMode> = {
+    reason: ListerOpenReason;
+    value: ListerValueForMode<TValue, TMode>;
+    details: {
+        options: ListerOptionsForMode<TRaw, TValue, TMeta, TMode>;
+        raw: ListerRawForMode<TRaw, TMode>;
+        action: "apply" | "cancel" | "close" | "denied" | "error";
+        errorCode?: string;
+        /** Useful in multi-session UI: which popover resolved */
+        sessionId?: ListerSessionId;
+    };
+};
+type PresetMap = Record<string, ListerDefinition<any, any, any, any, any>>;
+type PresetRaw<P extends PresetMap, K extends keyof P> = P[K] extends ListerDefinition<infer R, any, any, any, any> ? R : never;
+type PresetValue<P extends PresetMap, K extends keyof P> = P[K] extends ListerDefinition<any, infer V, any, any, any> ? V : never;
+type PresetFilters<P extends PresetMap, K extends keyof P> = P[K] extends ListerDefinition<any, any, infer F, any, any> ? F : never;
+type PresetMeta<P extends PresetMap, K extends keyof P> = P[K] extends ListerDefinition<any, any, any, infer M, any> ? M : never;
+interface ListerApi<P extends PresetMap> {
+    /** Fetch data without opening session */
+    fetch<K extends keyof P>(kind: K, filters?: PresetFilters<P, K>, opts?: {
+        query?: string;
+    }): Promise<{
+        raw: PresetRaw<P, K>[];
+        options: Array<ListerOption<PresetRaw<P, K>, PresetValue<P, K>, PresetMeta<P, K>>>;
+    }>;
+    /** Fetch data without opening session (custom definition) */
+    fetch<TRaw, TValue extends ListerId, TFilters = unknown, TMeta = unknown>(def: ListerDefinition<TRaw, TValue, TFilters, TMeta>, filters?: TFilters, opts?: {
+        query?: string;
+    }): Promise<{
+        raw: TRaw[];
+        options: Array<ListerOption<TRaw, TValue, TMeta>>;
+    }>;
+    /** Open via preset kind */
+    open<K extends keyof P, TMode extends ListerMode = "single">(kind: K, filters?: PresetFilters<P, K>, opts?: ListerOpenOptions<PresetRaw<P, K>, PresetValue<P, K>, PresetFilters<P, K>, PresetMeta<P, K>, TMode> & {
+        mode?: TMode;
+    }): Promise<ListerOpenResult<PresetRaw<P, K>, PresetValue<P, K>, PresetMeta<P, K>, TMode>>;
+    /** Open via custom definition */
+    open<TRaw, TValue extends ListerId, TFilters = unknown, TMeta = unknown, TMode extends ListerMode = "single">(def: ListerDefinition<TRaw, TValue, TFilters, TMeta>, filters?: TFilters, opts?: ListerOpenOptions<TRaw, TValue, TFilters, TMeta, TMode> & {
+        mode?: TMode;
+    }): Promise<ListerOpenResult<TRaw, TValue, TMeta, TMode>>;
+    /** Optional preset registry helpers */
+    registerPreset?: (kind: string, def: ListerDefinition<any, any, any, any, any>) => void;
+    getPreset?: (kind: string) => ListerDefinition<any, any, any, any, any> | undefined;
+}
+type ListerSessionState<TRaw, TValue extends ListerId, TFilters, TMeta, TMode extends ListerMode> = {
+    sessionId: ListerSessionId;
+    createdAt: number;
+    isOpen: boolean;
+    kind?: string;
+    definition?: ListerDefinition<TRaw, TValue, TFilters, TMeta>;
+    filters?: TFilters;
+    permissions?: string[];
+    mode: TMode;
+    confirm: TMode extends "single" ? boolean : true;
+    title?: string;
+    draggable: boolean;
+    position: {
+        x: number;
+        y: number;
+    } | null;
+    hasMoved: boolean;
+    searchMode: ListerSearchMode;
+    query: string;
+    loading: boolean;
+    refreshing: boolean;
+    errorCode?: ListerLogCode | string;
+    rawList: TRaw[];
+    optionsList: Array<ListerOption<TRaw, TValue, TMeta>>;
+    draftValue: ListerValueForMode<TValue, TMode>;
+    refreshMode: "preserve-selection" | "clear-missing" | "clear-all";
+    _resolve?: (result: ListerOpenResult<TRaw, TValue, TMeta, TMode>) => void;
+};
+type ListerRuntimeState<TRaw, TValue extends ListerId, TFilters, TMeta, TMode extends ListerMode> = ListerSessionState<TRaw, TValue, TFilters, TMeta, TMode> & {
+    /** Used to revert on cancel/close (recommended behaviour) */
+    initialDraftValue: ListerValueForMode<TValue, TMode>;
+    /** Stored from open() opts for later UI + provider logic */
+    onChange?: (value: ListerValueForMode<TValue, TMode>, details: ListerDetails<TRaw, TValue, TMeta, TMode>, e: ListerChangeEvent) => void;
+    /** UI hook for later */
+    renderOption?: ListerOpenOptions<TRaw, TValue, TFilters, TMeta, TMode>["renderOption"];
+    /** UI flag for later */
+    showRefresh?: boolean;
+    /** Filters config + runtime patch/effective (provider-owned) */
+    filtersSpec?: ListerFilterSpec<TFilters>;
+    filtersPatch?: Partial<TFilters>;
+    effectiveFilters?: TFilters;
+    /** Optional UI convenience */
+    selectedFilterValues?: Array<string | number>;
+    /** Derived from def.search (used for UI to render subjects/only/all rules) */
+    searchSpec?: ListerSearchSpec<string>;
+    /** Persisted user selection (subject/all/only) */
+    searchTarget?: ListerSearchTarget;
+};
+type ListerStoreState = {
+    /** rendering order (last = topmost) */
+    order: ListerSessionId[];
+    /** active/focused session */
+    activeId?: ListerSessionId;
+    /** sessions registry */
+    sessions: Record<ListerSessionId, ListerRuntimeState<any, any, any, any, any>>;
+};
+type ListerSearchTarget = {
+    /**
+     * "all"    => backend receives `searchAll=true`
+     * "subject"=> backend receives `subject=<col>`
+     * "only"   => backend receives `searchOnly=[...]`
+     */
+    mode: "all" | "subject" | "only";
+    subject?: string | null;
+    only?: Array<string | number> | null;
+};
+type ListerSearchPayload = {
+    subject?: string;
+    searchAll?: boolean;
+    searchOnly?: Array<string | number>;
+};
+
+type ListerFieldBaseProps<TValue> = {
+    value: TValue;
+    onValue: (next: TValue, detail?: any) => void;
+    disabled?: boolean;
+    readOnly?: boolean;
+    className?: string;
+    placeholder?: string;
+};
+/**
+ * Key or function mapping.
+ * IMPORTANT: ctx-aware because your engine mapping functions receive (raw, ctx).
+ */
+type KeyOrFn<TRaw, TOut, TCtx = any> = (keyof TRaw & string) | ((raw: TRaw, ctx: TCtx) => TOut);
+type ListerSize = "sm" | "md" | "lg";
+type ListerDensity = "compact" | "comfortable" | "loose";
+type ListerTriggerRenderCtx<TRaw extends Record<string, any>, TValue extends ListerId, TMeta, TMode extends ListerMode> = {
+    mode: TMode;
+    value: any;
+    selectedOptions: any[] | null;
+    placeholder: string;
+    maxDisplayItems: number;
+    display: React.ReactNode;
+    disabled?: boolean;
+    readOnly?: boolean;
+    isOpen: boolean;
+    /** convenience */
+    disabledTrigger: boolean;
+    hasValue: boolean;
+    /** convenience actions */
+    clear(): void;
+    open(): void;
+};
+type ListerVariantProps<P extends PresetMap = PresetMap, TRaw extends Record<string, any> = any, TValue extends ListerId = any, TFilters extends Record<string, any> = Record<string, any>, TMeta = any, TMode extends ListerMode = "single", TCtx = any, TSearchColumn extends string = string> = ListerFieldBaseProps<ListerValueForMode<TValue, TMode>> & {
+    host?: ListerProviderHost;
+    presets?: P;
+    remoteDebounceMs?: number;
+    /** Final/base definition */
+    def?: ListerDefinition<TRaw, TValue, TFilters, TMeta, TCtx, TSearchColumn>;
+    /** Inline overrides (any one can exist => inline exists) */
+    endpoint?: string;
+    method?: "GET" | "POST";
+    buildRequest?: ListerSource<TFilters>["buildRequest"];
+    selector?: Selector<TRaw>;
+    /** ✅ Search spec override (feeds session.searchSpec) */
+    search?: ListerDefinition<TRaw, TValue, TFilters, TMeta, TCtx, TSearchColumn>["search"];
+    /**
+     * ✅ Initial/seed search target (feeds session.searchTarget)
+     * If omitted, provider will derive it from `search.default` (if present) or fallback.
+     */
+    searchTarget?: ListerSearchTarget;
+    /** Inline mapping overrides (ctx-aware) */
+    optionValue?: KeyOrFn<TRaw, TValue, TCtx>;
+    optionLabel?: KeyOrFn<TRaw, string, TCtx>;
+    optionIcon?: KeyOrFn<TRaw, any, TCtx>;
+    optionDescription?: KeyOrFn<TRaw, string, TCtx>;
+    optionDisabled?: KeyOrFn<TRaw, boolean, TCtx>;
+    optionGroup?: KeyOrFn<TRaw, string, TCtx>;
+    optionMeta?: KeyOrFn<TRaw, TMeta, TCtx>;
+    filters?: TFilters;
+    mode?: TMode;
+    confirm?: TMode extends "single" ? boolean : never;
+    permissions?: string[];
+    title?: string;
+    searchMode?: ListerOpenOptions<TRaw, TValue, TFilters, TMeta, TMode>["searchMode"];
+    initialQuery?: string;
+    showRefresh?: boolean;
+    refreshMode?: ListerOpenOptions<TRaw, TValue, TFilters, TMeta, TMode>["refreshMode"];
+    /** Filters */
+    filtersSpec?: ListerFilterSpec<TFilters>;
+    renderOption?: ListerOpenOptions<TRaw, TValue, TFilters, TMeta, TMode>["renderOption"];
+    maxDisplayItems?: number;
+    renderTrigger?: (ctx: ListerTriggerRenderCtx<TRaw, TValue, TMeta, TMode>) => React.ReactElement;
+    size?: ListerSize;
+    density?: ListerDensity;
+    clearable?: boolean;
+    leadingIcons?: React.ReactNode[];
+    trailingIcons?: React.ReactNode[];
+    icon?: React.ReactNode;
+    iconGap?: number;
+    leadingIconSpacing?: number;
+    trailingIconSpacing?: number;
+    leadingControl?: React.ReactNode;
+    trailingControl?: React.ReactNode;
+    leadingControlClassName?: string;
+    trailingControlClassName?: string;
+    joinControls?: boolean;
+    extendBoxToControls?: boolean;
+    panelClassName?: string;
+    contentClassName?: string;
+};
+
+/**
+ * Helper type for a single variant registry entry.
+ *
+ * Keeps the shape consistent and easy to extend via declaration merging.
+ */
+interface VariantEntry<TValue, TProps> {
+    value: TValue;
+    props: TProps;
+}
+/**
+ * Base type-level variant registry.
+ *
+ * This is the **canonical mapping** used by:
+ * - InputFieldProps<K>
+ * - VariantModule<K>
+ *
+ * Hosts & presets extend it via declaration merging:
+ *
+ *   declare module "@/schema/variant" {
+ *     interface Variants {
+ *       select: VariantEntry<SelectValuePublic, SelectPropsPublic>;
+ *     }
+ *   }
+ */
+interface Variants<H = unknown> {
+    /**
+     * Built-in "text" variant.
+     *
+     * Shadcn-based implementation lives in presets/shadcn-variants/text.tsx
+     */
+    text: VariantEntry<string | undefined, ShadcnTextVariantProps>;
+    /**
+     * Example scalar variant.
+     *
+     * You can repurpose this for "custom" or drop it later.
+     */
+    number: VariantEntry<number | undefined, ShadcnNumberVariantProps>;
+    phone: VariantEntry<string | number | undefined, ShadcnPhoneVariantProps>;
+    color: VariantEntry<string | undefined, ShadcnColorVariantProps>;
+    password: VariantEntry<string | undefined, ShadcnPasswordVariantProps>;
+    date: VariantEntry<string | undefined, ShadcnDateVariantProps>;
+    chips: VariantEntry<string[] | undefined, ShadcnChipsVariantProps>;
+    textarea: VariantEntry<string | undefined, ShadcnTextareaVariantProps>;
+    toggle: VariantEntry<boolean | undefined, ShadcnToggleVariantProps$1>;
+    'toggle-group': VariantEntry<any | undefined, ShadcnToggleVariantProps>;
+    radio: VariantEntry<unknown | undefined, ShadcnRadioVariantProps<unknown, H>>;
+    checkbox: VariantEntry<CheckboxVariantPublicValue, ShadcnCheckboxVariantPublicProps>;
+    select: VariantEntry<string | number | undefined, SelectVariantProps>;
+    'multi-select': VariantEntry<Array<string | number> | undefined, ShadcnMultiSelectVariantProps>;
+    slider: VariantEntry<SliderValue, ShadcnSliderVariantProps>;
+    keyvalue: VariantEntry<KeyValueMap | undefined, ShadcnKeyValueVariantProps>;
+    custom: VariantEntry<unknown | undefined, ShadcnCustomVariantProps>;
+    treeselect: VariantEntry<string | number | undefined, ShadcnTreeSelectVariantProps>;
+    file: VariantEntry<FileLike, ShadcnFileVariantProps>;
+    editor: VariantEntry<string | undefined, ShadcnEditorVariantProps>;
+    'json-editor': VariantEntry<JsonObject | undefined, ShadcnJsonEditorProps>;
+    lister: VariantEntry<any | undefined, ListerVariantProps>;
+}
+/**
+ * Union of all variant keys.
+ */
+type VariantKey = keyof Variants;
+/**
+ * Value type for a given variant key.
+ *
+ * Strongly drives autocomplete:
+ * - InputFieldProps<"text"> → TValue = string | undefined
+ */
+type VariantValueFor<K extends VariantKey, H = unknown> = Variants<H>[K]["value"];
+/**
+ * Props type for a given variant key.
+ *
+ * Strongly drives autocomplete:
+ * - InputFieldProps<"text"> → props = TextVariantProps
+ */
+type VariantPropsFor<K extends VariantKey, H = unknown> = Variants<H>[K]["props"];
+/**
+ * Signature for variant-level validation functions.
+ */
+type VariantValidateFn<TValue, TProps> = (value: TValue | undefined, ctx: {
+    required?: boolean;
+    props: TProps;
+    field: Field;
+    form: CoreContext<Dict>;
+}) => ValidateResult;
+/**
+ * Layout defaults for a variant.
+ *
+ * This extends FieldLayoutConfig, so it automatically includes:
+ * - placement props (labelPlacement, descriptionPlacement, etc.)
+ * - layout hints (inline, fullWidth, defaultSize/density)
+ * - layout graph (relativeRoots, ordering)
+ */
+interface VariantLayoutDefaults extends FieldLayoutConfig {
+}
+/**
+ * Runtime module definition for a variant.
+ *
+ * IMPORTANT:
+ * - This is **tied directly** to the registry:
+ *     TValue = VariantValueFor<K>
+ *     TProps = VariantPropsFor<K>
+ *
+ *   So if you change the entry in `Variants`, both:
+ *     - <InputField variant="..." /> props
+ *     - The Variant component in the module
+ *   will see the updated types and IntelliSense matches everywhere.
+ *
+ * - For complex variants (select/multiselect):
+ *   you model the relationship via unions in `Variants["select"]`.
+ */
+interface VariantModule<K extends VariantKey = VariantKey> {
+    /**
+     * Unique key for this variant, e.g. "text", "number", "select".
+     */
+    variant: K;
+    /**
+     * React component that renders the control.
+     *
+     * It receives:
+     * - VariantBaseProps<VariantValueFor<K>>
+     * - VariantPropsFor<K>
+     */
+    Variant: ComponentType<VariantBaseProps<VariantValueFor<K>> & VariantPropsFor<K>>;
+    /**
+     * Optional validation logic specific to this variant.
+     */
+    validate?: VariantValidateFn<VariantValueFor<K>, VariantPropsFor<K>>;
+    /**
+     * Optional default layout hints for this variant.
+     */
+    defaults?: {
+        layout?: VariantLayoutDefaults;
+    };
+    /**
+     * Optional smart layout resolver.
+     *
+     * Must respect host overrides.
+     */
+    resolveLayout?: LayoutResolver<VariantPropsFor<K>>;
+    /**
+     * Optional metadata, useful for docs/inspectors.
+     */
+    meta?: {
+        label?: string;
+        description?: string;
+        tags?: string[];
+    };
+}
+/**
+ * Convenience alias when you want to be explicit:
+ *
+ *   const textModule: VariantModuleFor<"text"> = { ... }
+ */
+type VariantModuleFor<K extends VariantKey> = VariantModule<K>;
+
+export { type ListerDefinition as $, type Variants as A, type BaseProps$7 as B, type CoreProps as C, type Dict as D, type ErrorTextPlacement as E, type Field as F, type VariantValidateFn as G, type HelpTextPlacement as H, InputNumber as I, type VariantLayoutDefaults as J, type VariantModuleFor as K, type LabelPlacement as L, type ListerProviderHost as M, type ListerApi as N, type ListerStoreState as O, type PresetMap as P, type ListerRuntimeState as Q, type RelativeRootsMap as R, type SublabelPlacement as S, Textarea as T, type ListerSessionId as U, type VariantKey as V, type ListerId as W, type ListerSearchMode as X, type ListerSearchTarget as Y, type ListerSearchPayload as Z, type ListerFilterCtx as _, type CoreContext as a, type ListerMode as a0, type ShadcnJsonEditorProps as a1, type JsonEditorIndexHandle as a2, type ListerOpenReason as a3, type Selector as a4, type Resolver as a5, type OpenAnchor as a6, type ListerChangeEvent as a7, type ListerLogLevel as a8, type ListerLogCode as a9, type ListerLogEntry as aa, type ListerPermissionCtx as ab, type ListerOption as ac, type ListerMapping as ad, type ListerSource as ae, type ListerSearchSpec as af, type ListerFilterApplyMode as ag, type ListerFilterApply as ah, type ListerFilterBindKey as ai, type ListerFilterInput as aj, type ListerFilterGroupOption as ak, type ListerFilterValueOption as al, type ListerFilterInputOption as am, type ListerFilterOption as an, type ListerFilterSpec as ao, type ListerValueForMode as ap, type ListerRawForMode as aq, type ListerOptionsForMode as ar, type ListerDetails as as, type ListerOpenOptions as at, type ListerOpenResult as au, type PresetRaw as av, type PresetValue as aw, type PresetFilters as ax, type PresetMeta as ay, type ListerSessionState as az, type DescriptionPlacement as b, type SlotPlacement as c, type FieldSize as d, type FieldDensity as e, type ValidateResult as f, type ChangeDetail as g, type VariantValueFor as h, type VariantPropsFor as i, type VariantModule as j, type InferFromSchema as k, type SubmitEvent as l, type FormProps as m, type ValuesResult as n, type InputStore as o, type ButtonRef as p, type FieldSlots as q, type FieldRoots as r, type FieldSlotId as s, type FieldRootId as t, type FieldOrdering as u, type FieldLayoutConfig as v, type EffectiveFieldLayout as w, type LayoutResolveContext as x, type LayoutResolver as y, type VariantEntry as z };