vue-formless 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -1,123 +1,88 @@
-import { AllowedComponentProps } from 'vue';
 import { Component } from 'vue';
-import { ComponentCustomProps } from 'vue';
-import { ComponentOptionsBase } from 'vue';
 import { ComponentOptionsMixin } from 'vue';
 import { ComponentProvideOptions } from 'vue';
-import { CreateComponentPublicInstanceWithMixins } from 'vue';
 import { DefineComponent } from 'vue';
 import { ExtractPropTypes } from 'vue';
-import { GlobalComponents } from 'vue';
-import { GlobalDirectives } from 'vue';
-import { InjectionKey } from 'vue';
 import { PropType } from 'vue';
 import { PublicProps } from 'vue';
-import { Slot } from 'vue';
 import { VNodeChild } from 'vue';
-import { VNodeProps } from 'vue';
 
-export declare function applyControlBinding(formModel: unknown, binding: ResolvedControlBinding, update: (prop: string, value: unknown) => void): Record<string, unknown>;
-
-/** Slice a multi-port binding to one v-model port (ADR-013 `useFormItem('start')`). */
-export declare function bindingForPort(binding: ResolvedControlBinding, port: string): ResolvedControlBinding;
-
-export declare type CamelToPascal<S extends string> = S extends `${infer F}${infer R}` ? `${Uppercase<F>}${R}` : S;
-
-/** `name` → `Name`, `idCard` → `IdCard` */
-export declare function camelToPascal(key: string): string;
-
-export declare type ColPlace = 'auto' | 'start' | 'end';
-
-/** Author-facing Col width: omit / `'Nx'` / `'max'` / absolute 1–24. */
-export declare type ColSpanSpec = string | number;
+declare type ColSpan = IntRange<1, typeof GRID_TOTAL>;
 
 /**
  * Public `$props` of a Vue constructor, functional component, or SFC.
- * `never` / omitted widgets yield `{}` (`never extends Constructor` is true in TS).
+ * `never` / omitted controls yield `{}` (`never extends Constructor` is true in TS).
  */
-export declare type ComponentPublicProps<C> = [C] extends [never] ? {} : [C] extends [undefined] ? {} : C extends abstract new (...args: any) => {
+declare type ComponentPublicProps<C> = [C] extends [never] ? {} : [C] extends [undefined] ? {} : C extends abstract new (...args: any) => {
     $props: infer P;
 } ? P : C extends (props: infer P, ...args: any) => unknown ? P : C extends {
     $props: infer P;
 } ? P : {};
 
-export declare interface ControlBindingOverrides {
-    prop?: ControlProp;
-}
-
-export declare type ControlItemSetting = boolean | 'self';
-
-export declare type ControlProp = string | readonly string[];
-
 /**
- * Control identity. Adapter extras (e.g. `label`) via `declare module 'vue-formless'`.
- * Extra keys become `ItemFl` fields and optional `fl:*` tag props.
+ * One field's declaration: the input of `createFormField` / each entry of
+ * `createFormFields` (design.md §11). It extends the augmentable
+ * `FormFieldCustomOptions`, so a consumer's `label` / `validation` joins the
+ * same shape and flows into the `FormFieldFormless` snapshot and the `fl:*` tag
+ * props.
+ *
+ * `component` stays `unknown` on purpose: a field table can pass any control
+ * and let the tag infer that control's public props.
  */
-export declare interface ControlSchema {
+export declare interface CreateFormFieldOptions extends FormFieldCustomOptions {
     /**
-     * Input widget only (no FormItem). Receives v-model bindings from formless.
-     * Widget may also declare static `formless: { model, item }`.
+     * The control only (no host Item). Receives v-model bindings from formless.
+     * A control may also declare static `formless: { model, item, field }`.
      */
-    component?: Component;
-    /** Input defaults: static object, or derived from the cell snapshot. */
-    props?: HostProps<ItemFl>;
+    component?: unknown;
+    /** Control defaults: static object, or derived from the field snapshot. */
+    props?: HostProps<FormFieldFormless>;
     /**
-     * v-model names on the widget (ADR-011). Default `'modelValue'`.
-     * Locked with the component; tag cannot override. Prefer widget `formless.model`.
+     * v-model names on the control (design.md §7.1). Default `'modelValue'`.
+     * Locked with the component; tag cannot override. Prefer control `formless.model`.
      */
-    model?: ControlVModel;
+    model?: FormFieldVModelRaw;
     /**
-     * Location(s) from FormView root (ADR-011). Default: control key.
+     * Location(s) from FormView root (design.md §7.1). Default: field key.
      * Overridable via `:fl:prop`. Empty string is illegal.
      * Nested: `buyers[0].name`, `` `buyers[${$index}].name` ``.
      */
-    prop?: ControlProp;
+    prop?: FormFieldPropRaw;
+    /**
+     * Host Item shell for this field: FormView default, then this, then tag `:fl:item`.
+     * Boolean only (design.md §9). Not “skip FormField”.
+     */
+    item?: boolean;
     /**
-     * Outer wrap: FormView default, then this, then tag `:fl:item`.
-     * `'self'`: widget lays out cells via `useFormItem(port)` (ADR-017).
+     * Assembly placement (design.md §8). Omit = `'auto'`.
+     * Schema and tag merge by nearest-wins; the control is **not** a merge layer —
+     * its static `formless.field` is read at render and folded in (`auto`).
      */
-    item?: boolean | 'self';
+    field?: FormFieldFormlessFieldRaw;
+    /** Debug-only component name; `createFormFields` injects the table key. */
+    name?: string;
 }
 
-/** Adapter fields on ControlSchema (everything except kernel keys). */
-declare type ControlSchemaExtras = Omit<ControlSchema, ControlSchemaKernelKey>;
-
-/**
- * Constraint for `createFormControls` only. `component` stays `unknown` so object
- * literals keep `typeof ElInput` instead of widening to Vue's `Component`.
- */
-declare type ControlSchemaInput = Omit<ControlSchema, 'component'> & {
-    component?: unknown;
-};
-
-/** Kernel-owned ControlSchema keys. Not extras; tags already have matching `fl:*` where allowed. */
-declare type ControlSchemaKernelKey = 'component' | 'props' | 'model' | 'prop' | 'item';
-
-export declare type ControlVModel = string | readonly string[];
-
 /**
- * Build a static namespaced control table (ADR-009).
- * Schema keys are camelCase control names → `<User.TimeRange />`.
+ * Build a static namespaced field table (design.md §11).
+ * Schema keys are camelCase (`timeRange`) or kebab-case (`time-range`) field
+ * names; only the **tag name** is normalized (`<User.TimeRange />`). The key as
+ * written still supplies the default `prop`.
  */
-export declare function createFormControls<const S extends {
-    [K in keyof S]: ControlSchemaInput;
-}>(schema: S, options?: CreateFormControlsOptions): NamespacedControls<S>;
-
-export declare interface CreateFormControlsOptions {
-    /** Defaults for every control in this cluster (static or from the cell snapshot). */
-    props?: HostProps<ItemFl>;
-}
+export declare function createFormFields<const S extends {
+    [K in keyof S]: CreateFormFieldOptions;
+}>(options: S): FormFields<S>;
 
 /**
- * Bind host layout / form / item once; returns a FormView (ADR-008 / ADR-016).
+ * Bind host layout / form / item once; returns a FormView (design.md §10).
  *
- * Host shells stay in this closure. Cells go through `useFormItem` / `FormView.Item`.
+ * Host shells stay in this closure. Ad-hoc fields use `FormField`.
  *
  * @example
  * ```ts
  * export const FormView = createFormView({
- *   layout: { Row: ElRow, Col: ElCol, column: 2, gutter: 16 },
- *   form: { component: ElForm, props: (fl) => ({ model: fl.modelValue }) },
+ *   layout: { Row: ElRow, Col: ElCol, props: { column: 2 } },
+ *   form: { component: MyForm }, // MyForm declares `modelValue` → ElForm `model`
  *   item: { component: ElFormItem, props: toEpItemProps },
  * })
  * ```
@@ -125,381 +90,296 @@ export declare interface CreateFormControlsOptions {
 export declare function createFormView(options?: CreateFormViewOptions): FormViewComponent;
 
 export declare interface CreateFormViewOptions {
-    /** Row + Col for hosted grid, plus optional project density. */
+    /** Row + Col for the hosted grid, plus optional LayoutView props (density etc.). */
     layout?: FormViewLayoutBind;
     /** Host form shell. Omit or `:fl:form="false"` skips wrapping. */
-    form?: FormViewHostBind<FormFl>;
-    /** Host item shell. `props` are defaults (static or from the cell snapshot). */
-    item?: FormViewHostBind<ItemFl>;
+    form?: FormViewFormBind;
+    /** Host item shell. `props` are defaults (static or from the field snapshot). */
+    item?: FormViewItemBind;
 }
 
-/**
- * Bind host Row/Col once. Returns LayoutView.
- * LayoutItem is not exported; cells call `useLayoutItem()`.
- */
+/** Bind host Row/Col once. Returns LayoutView; items are `LayoutItem`. */
 export declare function createLayoutView(options?: CreateLayoutViewOptions): Component;
 
-export declare interface CreateLayoutViewOptions {
+declare interface CreateLayoutViewOptions {
     Row?: Component;
     Col?: Component;
     column?: number;
 }
 
-/** Kernel column when factory and the LayoutView `column` prop are omitted. */
-export declare const DEFAULT_LAYOUT: {
-    readonly column: 1;
-};
-
-/** Tag attrs: `label?: string` → `'fl:label'?: string`. Always optional (override, not required). */
-declare type FlExtraProps<T> = {
-    [K in keyof T as K extends string ? `fl:${K}` : never]+?: T[K];
-};
+declare type _Enumerate<N extends number, Acc extends number[] = []> = Acc['length'] extends N ? Acc[number] : _Enumerate<N, [...Acc, Acc['length']]>;
 
-export declare interface FormContext {
-    /** Current FormView `modelValue` (parent snapshot; do not mutate). */
-    model: unknown;
-    /** Report a field write; FormView patches and emits `update:modelValue`. */
-    update: (prop: string, value: unknown) => void;
+/** Static `formless` bag a control may declare on `ComponentCustomOptions`. */
+export declare interface FormControlFormless {
+    /** v-model ports on the control (design.md §7.1). */
+    model?: FormFieldVModelRaw;
     /**
-     * FormView-owned Item shell.
-     * Used by `useFormItem` / `FormView.Item`, not by widget authors.
+     * Composite marker (design.md §8): "my inner `<FormField>`s need an inner
+     * LayoutView whenever this field is boxed". Only `'embed'` is meaningful —
+     * it is the control's **nature**, not a placement, so it is read at render
+     * (`FormFieldCore`) and folded into `fl:field`, never merged as a preset layer.
      */
-    wrap: WrapControl;
-    /** This FormView layer's Item switch. */
-    isItemEnabled: () => boolean;
-    /** This FormView's `:fl:layout` switch (page, not nearest LayoutView). */
-    isLayoutEnabled: () => boolean;
-    /** Factory `createLayoutView` result; reused for gear-4 inner host. */
-    LayoutView: Component;
-    /** `createFormView({ layout })` density; inner extra rows use this, not the page `:row:*`. */
-    factoryColumn: number;
-    factoryGutter: number;
+    field?: 'embed';
 }
 
-export declare const formContextKey: InjectionKey<FormContext>;
+/** Control props that may appear on `<User.Xxx />` (v-model ports stripped). */
+declare type FormControlProps<Def> = Def extends {
+    component?: infer C;
+} ? [Exclude<C, undefined>] extends [never] ? {} : Omit<ComponentPublicProps<Exclude<C, undefined>>, LockedKeysForDef<Def>> : {};
 
-export declare type FormControlComponent<P = {}> = DefineComponent<FormControlProps & P>;
+export declare const FormField: FormFieldComponent<{}>;
 
-/** Kernel `fl:` / `col:` / `row:` keys on `<User.Xxx />`. Schema extras are prefixed automatically. */
-export declare type FormControlProps = {
-    'fl:prop'?: string | string[];
-    'fl:item'?: boolean;
-    'col:span'?: string | number;
-    'col:place'?: 'auto' | 'start' | 'end';
-    'row:column'?: number;
-    'row:gutter'?: number;
-} & FlExtraProps<ControlSchemaExtras>;
-
-/** Loose schema bag. Prefer inferring `S` from an object literal via `createFormControls`. */
-export declare type FormControlsSchema = Record<string, ControlSchema>;
-
-export declare interface FormFl {
-    layout: boolean;
-    form: boolean;
+export declare type FormFieldComponent<P = {}> = DefineComponent<FormFieldProps & P>;
+
+/**
+ * The single module-augmentation anchor for field extras (design.md §18), and
+ * the extras domain itself: `CreateFormFieldOptions` extends it, and both the
+ * `FormFieldFormless` snapshot and the `fl:*` tag props take their extras
+ * straight from it. Mirrors Vue's `ComponentCustomOptions`: declare `label` /
+ * `validation` here, and they land on the factory input, the snapshot, and the
+ * tag props. There is no separate `Omit`-derived "extras" alias — kernel keys
+ * live on `CreateFormFieldOptions` only.
+ */
+export declare interface FormFieldCustomOptions {
+}
+
+/**
+ * The **normalized** per-field snapshot (design.md §10.1 / §16.3): what
+ * `item.props` / field `props` functions receive, and what `FormField` hands
+ * down to its host `FormItem`. Not passed as a host component prop.
+ *
+ * Adapters declare their extras once, on `FormFieldCustomOptions` (module
+ * augmentation, design.md §18); `extends FormFieldCustomOptions` pulls them in,
+ * so a declared `label` is `fl.label` in the snapshot **and** `:fl:label` on the
+ * tag.
+ *
+ * `model` / `prop` are this field's **normalized** binding arrays — index-aligned
+ * (`model[i] ↔ prop[i]`), never empty and `prop` no longer than `model`. The
+ * kernel sends no identity **name**: a host Item `prop` is the adapter's own
+ * encoding, so an adapter that cannot encode the field simply leaves it unbound.
+ *
+ * **Only the keys the kernel resolves are declared here** — `model` / `prop` /
+ * `field` / `item` — plus the consumer's declared extras, pulled in by
+ * `extends FormFieldCustomOptions`. The raw bag's other keys (a raw `component`,
+ * an unread `props`) still ride through at runtime, but they are **not** part of
+ * this type: the snapshot is a closed shape, so reading an undeclared key is a
+ * compile error rather than a silent `unknown`.
+ */
+export declare interface FormFieldFormless extends FormFieldCustomOptions {
+    /** This field's v-model ports, index-aligned with `prop`. */
+    model: FormFieldVModel;
+    /** This field's locations, index-aligned with `model`; `undefined` when nothing bound them. */
+    prop: FormFieldProp | undefined;
+    /** Assembled placement (design.md §8). `'auto'` is resolved away, never sent. */
+    field: FormFieldFormlessField;
+    /**
+     * Host Item shell switch (design.md §9): the nearest FormView's page `fl:item`
+     * default ← this cell's `fl:item`, near wins; a bare attr (`''`) counts as
+     * `true`. Resolved in one place (`FormFieldCore`), so it is **always a boolean**
+     * and every consumer — the adapter `item.props` and the control `props`
+     * alike — sees the same value.
+     */
     item: boolean;
-    /** FormView write-model; map to the host via `form.props` (e.g. `{ model: fl.modelValue }`). */
-    modelValue: unknown;
 }
 
-export declare type FormFormProp = boolean | 'auto';
+/** The **assembled** placement. `'auto'` is resolved away, never sent. */
+declare type FormFieldFormlessField = 'wrap' | 'embed' | 'wrap-embed';
 
-/** Dot-notation path for ElFormItem `prop` (e.g. `buyers.0.name`). */
-export declare function formItemProp(prop: string): string;
+/**
+ * The **written** placement — the three writable values. Omit = `'auto'`: defer
+ * to the control's static `formless.field`. A leaf resolves to `'wrap'`, but
+ * that value is never writable.
+ */
+declare type FormFieldFormlessFieldRaw = 'auto' | 'embed' | 'wrap-embed';
 
-/** Factory `layout.column` overlay; gutter lives on `FormViewLayoutBind`. */
-export declare type FormLayoutOptions = Pick<FormViewLayoutBind, 'column'>;
+declare type FormFieldProp = (string | undefined)[];
 
-/** FormView `:fl:layout` is a boolean switch. Density is factory / `:row:*`. */
-export declare type FormLayoutProp = boolean;
+declare type FormFieldPropRaw = string | readonly string[];
 
 /**
- * Context-only FormView (no Row/Col/Form/Item). Prefer `createFormView({ layout: { Row, Col } })`.
+ * Public props of `<FormField>` / `<User.Xxx />`. Kernel `fl:` / `item:` /
+ * `layout:` / `layout-item:` keys on `<FormField>` / `<User.Xxx />`.
+ * Schema extras are prefixed automatically.
+ * `fl:model` declares the v-model ports at the identity root and selects one declared port inside it.
+ * `layout:column` is formless density; other `layout:*` (e.g. gutter) stay attrs and fall through to LayoutView → Row.
+ *
+ * The declaration's own keys are **mapped**, not retyped: every core key has a
+ * matching `fl:` tag key (design.md §6), so the tag cannot drift from
+ * `CreateFormFieldOptions`. Two keys stay off the tag — `props` (it may be a
+ * snapshot function, which cannot ride in an attr: it enters as the first
+ * `control` layer instead, §16.3) and `name` (factory-private). `component` is
+ * the one key whose *type* changes: the declaration keeps `unknown` so a field
+ * table can pass any control, while the tag supplies a real `Component`
+ * (ad-hoc field / factory preset, §7.4). Extras need no separate term — they
+ * are part of the declaration, so the same mapper prefixes them.
+ *
+ * The `layout:` / `layout-item:` keys are not retyped either: they are mapped
+ * from `@vue-formless/layout`'s own prop bags by the same `ToFormlessProps` —
+ * `LayoutViewProps` under `'layout:'` and `LayoutItemProps` under
+ * `'layout-item:'` — so density and placement have a single source and cannot
+ * drift from the layout package. Nothing is `Omit`-ed: the kernel overrides
+ * `layout:disabled` at the page it forwards the bag to (spread first, then
+ * `disabled={!fl:layout}`), not by dropping it from the channel.
  */
-export declare const FormView: {
-    new (...args: any[]): CreateComponentPublicInstanceWithMixins<Readonly<ExtractPropTypes<    {
-    modelValue: {
-    type: PropType<unknown>;
-    default: undefined;
-    };
-    'fl:layout': {
-    type: PropType<FormLayoutProp>;
-    default: boolean;
-    };
-    'row:column': {
-    type: NumberConstructor;
-    default: undefined;
-    };
-    'row:gutter': {
-    type: NumberConstructor;
-    default: undefined;
-    };
-    'fl:form': {
-    type: PropType<FormFormProp>;
-    default: string;
-    };
-    'fl:item': {
-    type: BooleanConstructor;
-    default: boolean;
-    };
-    }>> & Readonly<{
-    "onUpdate:modelValue"?: ((_value: unknown) => any) | undefined;
-    }>, () => VNodeChild, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
-    'update:modelValue': (_value: unknown) => boolean;
-    }, PublicProps, {
-    modelValue: undefined;
-    'fl:layout': boolean;
-    'row:column': number;
-    'row:gutter': number;
-    'fl:form': FormFormProp;
-    'fl:item': boolean;
-    }, true, {}, {}, GlobalComponents, GlobalDirectives, string, {}, any, ComponentProvideOptions, {
-    P: {};
-    B: {};
-    D: {};
-    C: {};
-    M: {};
-    Defaults: {};
-    }, Readonly<ExtractPropTypes<    {
-    modelValue: {
-    type: PropType<unknown>;
-    default: undefined;
-    };
-    'fl:layout': {
-    type: PropType<FormLayoutProp>;
-    default: boolean;
-    };
-    'row:column': {
-    type: NumberConstructor;
-    default: undefined;
-    };
-    'row:gutter': {
-    type: NumberConstructor;
-    default: undefined;
-    };
-    'fl:form': {
-    type: PropType<FormFormProp>;
-    default: string;
-    };
-    'fl:item': {
-    type: BooleanConstructor;
-    default: boolean;
-    };
-    }>> & Readonly<{
-    "onUpdate:modelValue"?: ((_value: unknown) => any) | undefined;
-    }>, () => VNodeChild, {}, {}, {}, {
-    modelValue: undefined;
-    'fl:layout': boolean;
-    'row:column': number;
-    'row:gutter': number;
-    'fl:form': FormFormProp;
-    'fl:item': boolean;
-    }>;
-    __isFragment?: never;
-    __isTeleport?: never;
-    __isSuspense?: never;
-} & ComponentOptionsBase<Readonly<ExtractPropTypes<    {
-modelValue: {
-type: PropType<unknown>;
-default: undefined;
-};
-'fl:layout': {
-type: PropType<FormLayoutProp>;
-default: boolean;
-};
-'row:column': {
-type: NumberConstructor;
-default: undefined;
-};
-'row:gutter': {
-type: NumberConstructor;
-default: undefined;
-};
-'fl:form': {
-type: PropType<FormFormProp>;
-default: string;
-};
-'fl:item': {
-type: BooleanConstructor;
-default: boolean;
-};
-}>> & Readonly<{
-"onUpdate:modelValue"?: ((_value: unknown) => any) | undefined;
-}>, () => VNodeChild, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
-'update:modelValue': (_value: unknown) => boolean;
-}, string, {
-modelValue: undefined;
-'fl:layout': boolean;
-'row:column': number;
-'row:gutter': number;
-'fl:form': FormFormProp;
-'fl:item': boolean;
-}, {}, string, {}, GlobalComponents, GlobalDirectives, string, ComponentProvideOptions> & VNodeProps & AllowedComponentProps & ComponentCustomProps & {
-    Item: typeof FormViewItem;
-};
+export declare type FormFieldProps = ToFormlessProps<Omit<CreateFormFieldOptions, 'props' | 'name' | 'component'> & {
+    component?: Component;
+}> & ToFormlessProps<LayoutViewProps, 'layout:'> & ToFormlessProps<LayoutItemProps, 'layout-item:'>;
 
-export declare type FormViewComponent = Component & {
-    Item: typeof FormViewItem;
+/**
+ * PascalCase field tags. `S` must not be `Record<string, _>` or `keyof` collapses
+ * to `string` and Volar/TS lose `User.Name` / `User.IdCard` as named keys.
+ * Tag props are `fl:*` plus the control's public props (v-model ports locked).
+ *
+ * Keys may be camelCase (`timeRange`) or kebab-case (`time-range`); both land on
+ * the same tag (`<User.TimeRange />`). The runtime normalizes via
+ * `upperFirst(toCamel(key))`, so the type must mirror it exactly. Normalizing
+ * the tag is all this mapping does — `prop` is not derived from the tag name.
+ */
+export declare type FormFields<S> = {
+    [K in keyof S & string as UpperFirst<ToCamel<K>>]: FormFieldComponent<FormControlProps<S[K]>>;
 };
 
-export declare interface FormViewHostBind<TFl> {
-    component: Component;
-    props?: HostProps<TFl>;
+export declare interface FormFieldSlotProps {
+    $bindings: Record<string, unknown>;
 }
 
-/** Page-level anonymous cell. Same wrap as `useFormItem()`. */
-export declare const FormViewItem: FormViewItemComponent;
+/**
+ * The **normalized** binding arrays. A port that is not a string stays as an
+ * `undefined` placeholder so the `model[i] ↔ prop[i]` alignment survives.
+ */
+declare type FormFieldVModel = (string | undefined)[];
 
-declare type FormViewItemComponent = DefineComponent<FormViewItemProps>;
+/**
+ * Field binding (design.md §7.1):
+ * - `model` — v-model names on the control (identity). Default `'modelValue'`.
+ * - `prop`  — location(s) from FormView root (`name`, `buyers[0].name`).
+ *
+ * `prop` array pairs with `model` (prefix-aligned). Extra model ports are unbound.
+ */
+declare type FormFieldVModelRaw = string | readonly string[];
 
-/** Kernel keys on `FormView.Item` / `useFormItem()`. Schema extras are prefixed automatically. */
-export declare type FormViewItemProps = {
-    'fl:prop'?: string | string[];
-    'col:span'?: string | number;
-    'col:place'?: 'auto' | 'start' | 'end';
-} & FlExtraProps<ControlSchemaExtras>;
+export declare type FormViewComponent = DefineComponent<FormViewProps>;
 
-export declare interface FormViewItemSlotProps {
-    /** `applyControlBinding` result (`modelValue` + `onUpdate:modelValue` for a single leaf). */
-    field: Record<string, unknown>;
+/**
+ * Host Form shell. `props` are **static** defaults: formless has no form-level
+ * snapshot to project from — the write model reaches the host as the bare
+ * `modelValue` attr (no-prefix rule, design.md §10.1). A library whose model
+ * port is named differently (`ElForm` → `model`) wraps the host in its own
+ * component that declares `modelValue` and forwards it (`MyForm`).
+ */
+declare interface FormViewFormBind {
+    component: Component;
+    props?: Record<string, unknown>;
 }
 
-export declare interface FormViewLayoutBind {
+declare type FormViewFormProp = boolean | 'auto';
+
+/**
+ * Host item shell. `props` are defaults, static or mapped from the field
+ * snapshot (`HostProps<FormFieldFormless>`); `createFormItem` does the
+ * projection.
+ */
+declare interface FormViewItemBind {
+    component: Component;
+    props?: HostProps<FormFieldFormless>;
+}
+
+declare interface FormViewLayoutBind {
     Row: Component;
     Col: Component;
-    column?: number;
-    gutter?: number;
+    /**
+     * Default LayoutView props (density etc.): a static object. Tag `:layout:*`
+     * overlays them (near wins). `disabled` stays kernel-owned: always the
+     * `fl:layout` polarity flip.
+     */
+    props?: Record<string, unknown>;
 }
 
+/** FormView `:fl:layout` is a boolean switch. Density is factory `layout.props` / `:layout:*`. */
+declare type FormViewLayoutProp = boolean;
+
 export declare interface FormViewProps {
+    /**
+     * FormView write model (the DTO). It is **not** a declared prop: the bare key
+     * stays in `attrs` and, per the no-prefix rule, also reaches the host Form — a
+     * host that wants it declares `modelValue` itself (wrap ElForm in a `MyForm`;
+     * design.md §10.1). The `onUpdate:modelValue` listener is read here
+     * (`useFormViewValue`) and also rides through to the host Form.
+     */
     modelValue?: unknown;
     /**
      * Grid hosting switch. Default `false`.
-     * Density: this FormView's factory `layout.column/gutter` plus `:row:column` / `:row:gutter`.
-     * Nested FormView / extra rows do not inherit this instance overlay.
+     * Density: factory `layout.props` plus `:layout:*` for **this** page LayoutView only.
+     * wrap-embed inner LayoutView inherits neither. Other `:layout:*` fall through to the host Row.
      */
-    'fl:layout'?: FormLayoutProp;
-    'row:column'?: number;
-    'row:gutter'?: number;
+    'fl:layout'?: FormViewLayoutProp;
+    'layout:column'?: LayoutViewProps['column'];
     /**
      * Wrap the factory `form`. Default `'auto'`: on at the root, off when nested.
      * Explicit `true` / `false` win.
      */
-    'fl:form'?: FormFormProp;
-    /** Wrap the factory `item` per cell (default `true` when `item.component` is bound). */
+    'fl:form'?: FormViewFormProp;
+    /** Wrap the factory `item` per field (default `true` when `item.component` is bound). */
     'fl:item'?: boolean;
 }
 
-export declare function getIn(root: unknown, prop: string): unknown;
-
 /** Host Col span modulus (Element / Ant Design 24-grid). */
-export declare const GRID_TOTAL = 24;
+declare const GRID_TOTAL = 24;
 
 /** Static host props, or derived from that layer's snapshot. */
-export declare type HostProps<TFl> = Record<string, unknown> | ((fl: TFl) => Record<string, unknown> | undefined);
+declare type HostProps<TFl> = Record<string, unknown> | ((fl: TFl) => Record<string, unknown> | undefined);
 
 /**
- * Snapshot for `item.props` / control `props` functions.
- * Kernel wiring + ControlSchema extras. Not passed as a host component prop.
+ * 通用整数范围类型工具
+ * @example IntRange<1, 24> 会生成 1 到 24 的联合类型
  */
-export declare type ItemFl = {
-    controlKey: string;
-    binding: ResolvedControlBinding;
-    getValues: () => unknown[];
-    [extra: string]: unknown;
-} & ControlSchemaExtras;
-
-export declare interface LayoutItemProps {
-    span?: ColSpanSpec;
-    place?: ColPlace;
-}
-
-export declare interface LayoutViewProps {
-    disabled?: boolean;
-    column?: number;
-}
-
-declare type LockedKeysForDef<Def> = LockedVModelKeys<SchemaModel<Def> extends ControlVModel | undefined ? SchemaModel<Def> : undefined>;
-
-export declare type LockedVModelKeys<M extends ControlVModel | undefined> = ModelPortNames<M> | `onUpdate:${ModelPortNames<M>}`;
-
-/** Widget `formless.item` vs schema `item`. `'self'` vs `false` is illegal. */
-export declare function mergeInternalItem(widget?: ControlItemSetting, schema?: ControlItemSetting): ControlItemSetting | undefined;
+declare type IntRange<F extends number, T extends number> = Exclude<_Enumerate<T>, _Enumerate<F>> | T;
 
-declare type ModelPortNames<M> = [M] extends [undefined] ? 'modelValue' : M extends string ? M : M extends readonly [infer F extends string, ...infer R] ? F | ModelPortNames<R> : 'modelValue';
-
-/**
- * PascalCase control tags. `S` must not be `Record<string, _>` or `keyof` collapses
- * to `string` and Volar/TS lose `User.Name` / `User.IdCard` as named keys.
- * Tag props are `fl:*` plus the widget's public props (v-model ports locked).
- */
-export declare type NamespacedControls<S> = {
-    [K in keyof S & string as CamelToPascal<K>]: FormControlComponent<WidgetTagProps<S[K]>>;
+export declare const LayoutItem: DefineComponent<ExtractPropTypes<    {
+span: {
+type: PropType<LayoutItemSpan>;
+default: undefined;
 };
-
-/** Later layers win. `undefined` does not override. Empty string is a value. */
-export declare function overlayProps(...layers: Array<Record<string, unknown> | undefined>): Record<string, unknown>;
-
-export declare function parsePath(prop: string): PathSegment[];
-
-/** `Name` → `name`, `IdCard` → `idCard` */
-export declare function pascalToCamel(key: string): string;
-
-/**
- * Parse `prop` location strings: object keys and `[index]` segments.
- * Examples: `name`, `buyers[0].name`, `[2].title`
- */
-export declare type PathSegment = {
-    type: 'key';
-    key: string;
-} | {
-    type: 'index';
-    index: number;
+place: {
+type: PropType<LayoutItemPlace>;
+default: undefined;
+};
+}>, () => VNodeChild, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<ExtractPropTypes<    {
+span: {
+type: PropType<LayoutItemSpan>;
+default: undefined;
+};
+place: {
+type: PropType<LayoutItemPlace>;
+default: undefined;
 };
+}>> & Readonly<{}>, {
+place: LayoutItemPlace;
+span: LayoutItemSpan;
+}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
 
-export declare function resolveControlBinding(controlKey: string, options?: {
-    model?: ControlVModel;
-    prop?: ControlProp;
-}, overrides?: ControlBindingOverrides): ResolvedControlBinding;
+declare type LayoutItemPlace = 'auto' | 'start' | 'end';
 
-/**
- * FormView < internal < tag (ADR-017).
- * Pure `'self'` skips outer Item+Col. `'self'` + explicit tag item true
- * wraps outer Item (and Col when page layout is on) and asks for an inner Row.
- * Col follows the Row host only; no control/cell layout switch.
- */
-export declare function resolveControlShell(input: ResolveControlShellInput): ResolvedControlShell;
-
-declare interface ResolveControlShellInput {
-    pageItem: boolean;
-    pageLayoutOn: boolean;
-    internalItem?: ControlItemSetting;
-    /** Tag `:fl:item`. Omitted ≠ `true`. */
-    tagItem?: boolean;
+declare interface LayoutItemProps {
+    span?: LayoutItemSpan;
+    place?: LayoutItemPlace;
 }
 
-export declare interface ResolvedControlBinding {
-    models: string[];
-    props: string[];
-}
+declare type LayoutItemSpan = ColSpan | `${ColSpan}` | `${ColSpan}x` | 'max';
 
-export declare interface ResolvedControlShell {
-    wrapItem: boolean;
-    wrapCol: boolean;
-    extraRow: boolean;
-    self: boolean;
+declare interface LayoutViewProps {
+    disabled?: boolean;
+    column?: number;
 }
 
-/**
- * Optional Element-style encoding: one location → dotted path; several →
- * control key. Kernel does not put this on Item `fl` — the adapter Item
- * calls this (or encodes another way) when mapping to host `prop`.
- */
-export declare function resolveFormItemProp(binding: ResolvedControlBinding, controlKey: string): string;
+declare type LockedKeysForDef<Def> = LockedVModelKeys<SchemaModel<Def> extends FormFieldVModelRaw | undefined ? SchemaModel<Def> : undefined>;
 
-export declare function resolveProps<TFl>(spec: HostProps<TFl> | undefined, fl: TFl): Record<string, unknown>;
+declare type LockedVModelKeys<M extends FormFieldVModelRaw | undefined> = ModelPortNames<M> | `onUpdate:${ModelPortNames<M>}`;
+
+declare type ModelPortNames<M> = [M] extends [undefined] ? 'modelValue' : M extends string ? M : M extends readonly [infer F extends string, ...infer R] ? F | ModelPortNames<R> : 'modelValue';
 
 /**
- * v-model ports locked on the tag (ADR-011). Schema `model` wins;
+ * v-model ports locked on the tag (design.md §7.2 / §17). Schema `model` wins;
  * omitted `model` locks the default `'modelValue'`.
  * Widened `string[]` is not treated as port names (would Omit every string key).
  */
@@ -507,55 +387,31 @@ declare type SchemaModel<Def> = Def extends {
     model: infer M;
 } ? M : undefined;
 
-/** Immutable write at a full `prop` location (`buyers[0].name`). Arrays are cloned. */
-export declare function setIn(root: unknown, prop: string, value: unknown): unknown;
-
-export declare function toBindingList(value: ControlVModel | ControlProp): string[];
-
-export declare function useFormContext(): FormContext;
+/** Type-level `toCamel` (built-in `Capitalize`): `'layout-item'` → `'layoutItem'`. */
+declare type ToCamel<S extends string> = S extends `${infer Head}-${infer Tail}` ? `${Head}${Capitalize<ToCamel<Tail>>}` : S;
 
 /**
- * One cell: LayoutItem? → Item? → (inner LayoutView?) → default slot.
- * No arg: this control's full binding (factory outer wrap).
- * Port: slice one v-model mouth.
- * Outer wrap follows the merged shell (ADR-017); binding stays on the frame.
+ * Any declaration bag → its optional tag props under `Prefix` (`label` →
+ * `'fl:label'` under the default prefix). Always optional (override, not
+ * required).
+ *
+ * The prefix is the kernel channel the keys land on: `fl:` for the field
+ * declaration, `layout:` / `layout-item:` for the layout package's prop bags.
+ * One mapper therefore produces every prefixed tag key space instead of each
+ * one being retyped.
  */
-export declare function useFormItem(port?: string): FormViewItemComponent;
-
-/** Nearest LayoutView's cell component; identity when no LayoutView. */
-export declare function useLayoutItem(): Component;
-
-export declare interface WidgetFormless {
-    model?: string | string[];
-    item?: boolean | 'self';
-}
-
-/** Widget props that may appear on `<User.Xxx />` (v-model ports stripped). */
-export declare type WidgetTagProps<Def> = Def extends {
-    component?: infer C;
-} ? [Exclude<C, undefined>] extends [never] ? {} : Omit<ComponentPublicProps<Exclude<C, undefined>>, LockedKeysForDef<Def>> : {};
-
-/** FormView-owned Item shell. Col is owned by LayoutView / useLayoutItem. */
-export declare type WrapControl = (body: VNodeChild, meta: WrapControlMeta) => VNodeChild;
+declare type ToFormlessProps<T, Prefix extends string = 'fl:'> = {
+    [K in keyof T as K extends string ? `${Prefix}${K}` : never]+?: T[K];
+};
 
-/** Input Control hands to FormView's wrap: Item snapshot + host fallthrough. */
-export declare interface WrapControlMeta {
-    /**
-     * This wrap only. `false` skips Item even when FormView `item` is on.
-     * `true` forces Item even when FormView `item` is off. Omit = follow FormView.
-     */
-    item?: boolean;
-    fl: ItemFl;
-    itemAttrs: Record<string, unknown>;
-    itemOn: Record<string, unknown>;
-    itemSlots: Record<string, Slot>;
-}
+/** Type-level `upperFirst`: `'name'` → `'Name'` (design.md §11). */
+declare type UpperFirst<S extends string> = S extends `${infer F}${infer R}` ? `${Uppercase<F>}${R}` : S;
 
 export { }
 
 
 declare module 'vue' {
     interface ComponentCustomOptions {
-        formless?: WidgetFormless;
+        formless?: FormControlFormless;
     }
 }