@formality-ui/core 0.3.1 → 0.4.0

package/dist/index.d.cts

@@ -306,7 +306,16 @@ type SelectFunction<TReturn = unknown> = (formState: FormState, methods: unknown
 interface InputConfig<TValue = unknown> {
     /** The component to render (typed `unknown` for framework agnosticism; React consumers see `ComponentType<any>` via `ReactInputConfig`) */
     component: unknown;
-    /** Default value for this input type (e.g., '' for text, false for switch) */
+    /**
+     * Default value for this input type (e.g., `''` for text, `false` for switch).
+     *
+     * Per-field override via `FieldConfig.defaultValue` (§6.4.1); the
+     * field-level value wins when `!== undefined` (resolved via
+     * `resolveFieldOverType`, §6.4.0 — so null/false/0/"" are meaningful
+     * defaults). A field-level default is a new priority tier *below*
+     * `record`/`defaultValues` and *above* this type default (§6.4.1,
+     * §13.1) — not a bare `??` of this value.
+     */
     defaultValue: TValue;
     /**
      * Auto-save debounce for fields of this input type.
@@ -319,19 +328,55 @@ interface InputConfig<TValue = unknown> {
      *   debounces fire on their own cadence. When unset, the field falls back
      *   to the Form-level `debounce` prop (default 1000ms).
      *
+     * Three-tier precedence (§6.4.2): a field-level `FieldConfig.debounce`
+     * wins when set; otherwise this type-level value; otherwise the
+     * Form-level `debounce` prop (default 1000). All three share the single
+     * field-over-type rule from §6.4.0 (resolved via `resolveFieldOverType`,
+     * so a field-level `false`/`number` is honored when `!== undefined`).
+     *
      * This governs *auto-save timing only*. The field value is still committed
      * to the form state on every change (it does not throttle re-renders).
      */
     debounce?: number | false;
     /** Prop name for passing value to component (default: 'value') */
     inputFieldProp?: string;
-    /** For complex values (objects), which property contains the actual value */
+    /**
+     * For complex values (objects), which property contains the actual value to submit.
+     *
+     * Per-field override via `FieldConfig.valueField` (§6.4.4); the field-level
+     * value wins when `!== undefined`, otherwise this type-level value applies.
+     * Resolved via `resolveFieldOverType` (§6.4.0), restoring read/write symmetry
+     * with `recordKey`.
+     */
     valueField?: string;
-    /** Transform field name for submission (e.g., 'client' → 'clientId') */
+    /**
+     * Transform the field name for submission (e.g. `'client' → 'clientId'`).
+     *
+     * Per-field override via `FieldConfig.getSubmitField` (§6.4.4); the
+     * field-level value wins when `!== undefined`, otherwise this type-level
+     * value applies. Resolved via `resolveFieldOverType` (§6.4.0), restoring
+     * read/write symmetry with `recordKey`.
+     */
     getSubmitField?: (fieldName: string) => string;
-    /** Transform user input to form value. String = named parser, function = inline */
+    /**
+     * Transform user input to form value. String = named parser, function = inline.
+     *
+     * Three-tier precedence (§6.4.3): field → type → none. Per-field override
+     * via `FieldConfig.parser`; the field-level value wins when `!== undefined`
+     * (resolved via `resolveFieldOverType`, §6.4.0 — so null/false/0/"" are
+     * meaningful overrides). Named (string) specs resolve against the
+     * provider's global `parsers` registry.
+     */
     parser?: string | ((value: unknown) => TValue);
-    /** Transform form value to display value. String = named formatter, function = inline */
+    /**
+     * Transform form value to display value. String = named formatter, function = inline.
+     *
+     * Three-tier precedence (§6.4.3): field → type → none. Per-field override
+     * via `FieldConfig.formatter`; the field-level value wins when `!== undefined`
+     * (resolved via `resolveFieldOverType`, §6.4.0 — so null/false/0/"" are
+     * meaningful overrides). Named (string) specs resolve against the
+     * provider's global `formatters` registry.
+     */
     formatter?: string | ((value: TValue) => unknown);
     /** Type-level validation (runs after field-level validator) */
     validator?: ValidatorSpec;
@@ -367,6 +412,38 @@ interface FieldConfig {
     order?: number;
     /** Key to use when reading initial value from record (defaults to field name) */
     recordKey?: string;
+    /**
+     * Per-instance default value. Overrides the input type's defaultValue;
+     * superseded by record/defaultValues prop. Honored when !== undefined, so
+     * null/false/0/"" are meaningful. See §6.4.1, §13.1.
+     */
+    defaultValue?: unknown;
+    /**
+     * Per-instance auto-save debounce. Overrides the input type's debounce;
+     * falls back to Form-level debounce prop (default 1000). false = submit
+     * immediately. See §6.4.2.
+     */
+    debounce?: number | false;
+    /**
+     * Per-instance value transform (input→form). Overrides the input type's
+     * parser. String = named parser; function = inline. See §6.4.3.
+     */
+    parser?: string | ((value: unknown) => unknown);
+    /**
+     * Per-instance value transform (form→display). Overrides the input type's
+     * formatter. String = named formatter; function = inline. See §6.4.3.
+     */
+    formatter?: string | ((value: unknown) => unknown);
+    /**
+     * Submit-side value extraction from complex objects. Overrides the input
+     * type's valueField. See §6.4.4.
+     */
+    valueField?: string;
+    /**
+     * Submit-side field name transformation. Overrides the input type's
+     * getSubmitField. See §6.4.4.
+     */
+    getSubmitField?: (fieldName: string) => string;
     /** Register options forwarded to the framework's field register call (typed loose for framework agnosticism; React consumers see react-hook-form's `RegisterOptions` via `ReactFieldConfig`) */
     rules?: Record<string, unknown>;
     /** Field-level validation (runs before type-level validator) */
@@ -1191,26 +1268,53 @@ declare function mergeConfigs(provider: FormalityProviderConfig, form?: FormConf
     fieldConfig: FieldConfig;
 };
 
+/**
+ * Resolve a field-level override against its type-level default. Returns the
+ * field value when it is not undefined (so null/false/0/"" are meaningful
+ * overrides); otherwise the type value. This is the single precedence rule
+ * shared by defaultValue, debounce, parser, formatter, getSubmitField, and
+ * valueField (§6.4.0). Every adapter MUST call this helper at each
+ * field-vs-type resolution site.
+ *
+ * @param fieldVal - The field-level (instance) value; `undefined` means "not specified".
+ * @param typeVal  - The type-level (InputConfig) default; `undefined` means "not specified".
+ * @returns `fieldVal` when it is not `undefined`, else `typeVal`.
+ *
+ * @example
+ * // Field override wins (even when falsy):
+ * resolveFieldOverType(false, true);   // → false
+ * resolveFieldOverType(null, "x");     // → null
+ * resolveFieldOverType(0, 100);        // → 0
+ * resolveFieldOverType("", "fallback");// → ""
+ *
+ * // Field unset → type default:
+ * resolveFieldOverType(undefined, "type"); // → "type"
+ * resolveFieldOverType(undefined, undefined); // → undefined
+ */
+declare function resolveFieldOverType<T>(fieldVal: T | undefined, typeVal: T | undefined): T | undefined;
 /**
  * Resolve the initial value for a field
  *
  * Priority order (highest to lowest):
  * 1. defaultValues[fieldName] (from Form props)
  * 2. record[recordKey] (using recordKey if specified, else fieldName)
- * 3. inputConfig.defaultValue (from input type definition)
+ * 3. fieldConfig.defaultValue (per-instance default; §6.4.1, §13.1)
+ * 4. inputConfig.defaultValue (from input type definition)
  *
  * **PRD deviation note (accepted, gap_analysis G5).** PRD §1.3.2's table
  * summarizes this export as `resolveInitialValue(record, config, inputConfig)`.
  * The implemented signature is a richer superset —
  * `(fieldName, fieldConfig?, inputConfig?, record?, defaultValues?)` — because
  * it drives the full priority chain above (defaultValues → record[recordKey] →
- * inputConfig.defaultValue) from a single call. This is an internal API
- * consumed by the framework adapters and by {@link resolveAllInitialValues},
- * not a simplified end-user entry point; the PRD literal form is a condensed
- * representation. No code change is planned.
+ * fieldConfig.defaultValue → inputConfig.defaultValue) from a single call. This
+ * is an internal API consumed by the framework adapters and by
+ * {@link resolveAllInitialValues}, not a simplified end-user entry point; the
+ * PRD literal form is a condensed representation. No code change is planned.
  *
  * @param fieldName - Field name
- * @param fieldConfig - Field configuration
+ * @param fieldConfig - Field configuration; `defaultValue` (when set) is the
+ *   Priority-3 per-instance default (§6.4.1), honored for any value
+ *   `!== undefined` (so null/false/0/"" are meaningful).
  * @param inputConfig - Input type configuration
  * @param record - Record data passed to form
  * @param defaultValues - Default values passed to form
@@ -1236,6 +1340,16 @@ declare function mergeConfigs(provider: FormalityProviderConfig, form?: FormConf
  *   { status: 'active' }
  * )
  * // → 'active' (defaultValues takes precedence)
+ *
+ * // Field-level default wins over the type default (§6.4.1)
+ * resolveInitialValue(
+ *   'active',
+ *   { type: 'switch', defaultValue: true }, // field default: true
+ *   { defaultValue: false }, // type default: false
+ *   undefined,
+ *   undefined,
+ * )
+ * // → true (field-level default honored; null/false/0/"" would also win)
  */
 declare function resolveInitialValue(fieldName: string, fieldConfig?: FieldConfig, inputConfig?: InputConfig, record?: Record<string, unknown>, defaultValues?: Record<string, unknown>): unknown;
 /**
@@ -1329,30 +1443,46 @@ declare function humanizeLabel(fieldName: string): string;
  * Priority order (highest to lowest):
  * 1. Component prop (label from JSX props)
  * 2. Field config props.label
- * 3. Evaluated selectProps.label
+ * 3. Evaluated selectProps.label (field-level selectProps)
  * 4. Field config label
  * 5. Field config title (legacy alias)
- * 6. Auto-generated from field name
+ * 6. Evaluated form-level selectDefaultFieldProps.label
+ * 7. Evaluated provider-level selectDefaultFieldProps.label
+ * 8. Auto-generated from field name
+ *
+ * The provider/form `selectDefaultFieldProps` layers are documented as label
+ * sources in PRD §16.1 (`providerConfig.selectDefaultFieldProps: { label:
+ * "props.name" }` works; same for `formConfig`). They sit below the field-level
+ * sources (matching their lower precedence in the 8-layer `mergeFieldProps`
+ * pipeline — layers 5 and 7 vs. the field-level layers 2/3) but above the
+ * humanized fallback, so a global label convention applies unless the field
+ * itself overrides it.
  *
  * **PRD deviation note (accepted, gap_analysis G5).** PRD §1.3.2's table
  * summarizes this export as `resolveLabel(config, fieldName)`. The implemented
  * signature is a richer superset —
- * `(fieldName, fieldConfig?, evaluatedSelectProps?, componentProps?)` — because
- * it resolves the full 6-source priority chain above in one call, which
- * requires the pre-evaluated `selectProps` and the JSX `componentProps`. This
+ * `(fieldName, fieldConfig?, evaluatedSelectProps?, componentProps?,
+ * providerSelectProps?, formSelectProps?)` — because it resolves the full
+ * priority chain above in one call, which requires the pre-evaluated
+ * `selectProps`/`selectDefaultFieldProps` and the JSX `componentProps`. This
  * is an internal API consumed by the framework adapters (e.g.
  * `@formality-ui/react`'s `Field` calls
- * `resolveLabel(name, fieldConfig, fieldSelectProps, restProps)`), not a
- * simplified end-user entry point; the PRD literal form is a condensed
- * representation. No code change is planned.
+ * `resolveLabel(name, fieldConfig, fieldSelectProps, restProps,
+ * providerSelectProps, formSelectProps)`), not a simplified end-user entry
+ * point; the PRD literal form is a condensed representation. No code change is
+ * planned.
  *
  * @param fieldName - Field name
  * @param fieldConfig - Field configuration
- * @param evaluatedSelectProps - Pre-evaluated selectProps
+ * @param evaluatedSelectProps - Pre-evaluated field-level selectProps
  * @param componentProps - Props from JSX
+ * @param providerSelectProps - Pre-evaluated provider-level
+ *   selectDefaultFieldProps (PRD §16.1)
+ * @param formSelectProps - Pre-evaluated form-level selectDefaultFieldProps
+ *   (PRD §16.1)
  * @returns Resolved label string
  */
-declare function resolveLabel(fieldName: string, fieldConfig?: FieldConfig, evaluatedSelectProps?: Record<string, unknown>, componentProps?: Record<string, unknown>): string;
+declare function resolveLabel(fieldName: string, fieldConfig?: FieldConfig, evaluatedSelectProps?: Record<string, unknown>, componentProps?: Record<string, unknown>, providerSelectProps?: Record<string, unknown>, formSelectProps?: Record<string, unknown>): string;
 /**
  * Resolve the title for a form
  *
@@ -1396,4 +1526,4 @@ declare function parseLabelWithUnit(label: string): {
     unit?: string;
 };
 
-export { type ConditionDescriptor, type ConditionResult, type ErrorMessagesConfig, type EvaluateConditionsInput, type EvaluationContext, FIELD_PROXY_MARKER, FIELD_PROXY_VALUE, type FieldConfig, type FieldError, type FieldState, type FieldStateInput, type FormConfig, type FormFieldsConfig, type FormState, type FormalityProviderConfig, type FormatterFunction, type FormatterSpec, type FormattersConfig, type GroupConfig, type InputConfig, type InputTemplateProps, KEYWORDS, type ParserFunction, type ParserSpec, type ParsersConfig, QUALIFIED_PREFIXES, type SelectFunction, type SelectValue, type ValidationResult, type ValidatorEntry, type ValidatorFactory, type ValidatorFunction, type ValidatorSpec, type ValidatorsConfig, buildEvaluationContext, buildFieldContext, buildFormContext, clearExpressionCache, composeValidators, conditionMatches, createConfigContext, createDefaultFormatters, createDefaultParsers, createErrorMessages, createFieldStateProxy, createFloatFormatter, createFloatParser, createIntParser, createLabelWithUnit, createTrimParser, createValidationError, deepMerge, evaluate, evaluateConditions, evaluateDescriptor, extractValueField, format, formatTypeAsMessage, getErrorType, getInputDefaultValue, getOrderedUnusedFields, getUnusedFields, humanizeLabel, inferFieldsFromConditions, inferFieldsFromDescriptor, inferFieldsFromExpression, isAutoGeneratedLabel, isEmptyValue, isFieldProxy, isValid, maxLength, mergeConditionResults, mergeConfigs, mergeFieldProps, mergeInputConfigs, mergeRecordWithDefaults, mergeStaticProps, minLength, parse, parseLabelWithUnit, pattern, required, resolveAllInitialValues, resolveErrorMessage, resolveFieldType, resolveFormTitle, resolveInitialValue, resolveInputConfig, resolveLabel, runValidator, runValidatorSync, sortFieldsByOrder, transformFieldName, unwrapFieldProxy, validate };
+export { type ConditionDescriptor, type ConditionResult, type ErrorMessagesConfig, type EvaluateConditionsInput, type EvaluationContext, FIELD_PROXY_MARKER, FIELD_PROXY_VALUE, type FieldConfig, type FieldError, type FieldState, type FieldStateInput, type FormConfig, type FormFieldsConfig, type FormState, type FormalityProviderConfig, type FormatterFunction, type FormatterSpec, type FormattersConfig, type GroupConfig, type InputConfig, type InputTemplateProps, KEYWORDS, type ParserFunction, type ParserSpec, type ParsersConfig, QUALIFIED_PREFIXES, type SelectFunction, type SelectValue, type ValidationResult, type ValidatorEntry, type ValidatorFactory, type ValidatorFunction, type ValidatorSpec, type ValidatorsConfig, buildEvaluationContext, buildFieldContext, buildFormContext, clearExpressionCache, composeValidators, conditionMatches, createConfigContext, createDefaultFormatters, createDefaultParsers, createErrorMessages, createFieldStateProxy, createFloatFormatter, createFloatParser, createIntParser, createLabelWithUnit, createTrimParser, createValidationError, deepMerge, evaluate, evaluateConditions, evaluateDescriptor, extractValueField, format, formatTypeAsMessage, getErrorType, getInputDefaultValue, getOrderedUnusedFields, getUnusedFields, humanizeLabel, inferFieldsFromConditions, inferFieldsFromDescriptor, inferFieldsFromExpression, isAutoGeneratedLabel, isEmptyValue, isFieldProxy, isValid, maxLength, mergeConditionResults, mergeConfigs, mergeFieldProps, mergeInputConfigs, mergeRecordWithDefaults, mergeStaticProps, minLength, parse, parseLabelWithUnit, pattern, required, resolveAllInitialValues, resolveErrorMessage, resolveFieldOverType, resolveFieldType, resolveFormTitle, resolveInitialValue, resolveInputConfig, resolveLabel, runValidator, runValidatorSync, sortFieldsByOrder, transformFieldName, unwrapFieldProxy, validate };

package/dist/index.d.ts

@@ -306,7 +306,16 @@ type SelectFunction<TReturn = unknown> = (formState: FormState, methods: unknown
 interface InputConfig<TValue = unknown> {
     /** The component to render (typed `unknown` for framework agnosticism; React consumers see `ComponentType<any>` via `ReactInputConfig`) */
     component: unknown;
-    /** Default value for this input type (e.g., '' for text, false for switch) */
+    /**
+     * Default value for this input type (e.g., `''` for text, `false` for switch).
+     *
+     * Per-field override via `FieldConfig.defaultValue` (§6.4.1); the
+     * field-level value wins when `!== undefined` (resolved via
+     * `resolveFieldOverType`, §6.4.0 — so null/false/0/"" are meaningful
+     * defaults). A field-level default is a new priority tier *below*
+     * `record`/`defaultValues` and *above* this type default (§6.4.1,
+     * §13.1) — not a bare `??` of this value.
+     */
     defaultValue: TValue;
     /**
      * Auto-save debounce for fields of this input type.
@@ -319,19 +328,55 @@ interface InputConfig<TValue = unknown> {
      *   debounces fire on their own cadence. When unset, the field falls back
      *   to the Form-level `debounce` prop (default 1000ms).
      *
+     * Three-tier precedence (§6.4.2): a field-level `FieldConfig.debounce`
+     * wins when set; otherwise this type-level value; otherwise the
+     * Form-level `debounce` prop (default 1000). All three share the single
+     * field-over-type rule from §6.4.0 (resolved via `resolveFieldOverType`,
+     * so a field-level `false`/`number` is honored when `!== undefined`).
+     *
      * This governs *auto-save timing only*. The field value is still committed
      * to the form state on every change (it does not throttle re-renders).
      */
     debounce?: number | false;
     /** Prop name for passing value to component (default: 'value') */
     inputFieldProp?: string;
-    /** For complex values (objects), which property contains the actual value */
+    /**
+     * For complex values (objects), which property contains the actual value to submit.
+     *
+     * Per-field override via `FieldConfig.valueField` (§6.4.4); the field-level
+     * value wins when `!== undefined`, otherwise this type-level value applies.
+     * Resolved via `resolveFieldOverType` (§6.4.0), restoring read/write symmetry
+     * with `recordKey`.
+     */
     valueField?: string;
-    /** Transform field name for submission (e.g., 'client' → 'clientId') */
+    /**
+     * Transform the field name for submission (e.g. `'client' → 'clientId'`).
+     *
+     * Per-field override via `FieldConfig.getSubmitField` (§6.4.4); the
+     * field-level value wins when `!== undefined`, otherwise this type-level
+     * value applies. Resolved via `resolveFieldOverType` (§6.4.0), restoring
+     * read/write symmetry with `recordKey`.
+     */
     getSubmitField?: (fieldName: string) => string;
-    /** Transform user input to form value. String = named parser, function = inline */
+    /**
+     * Transform user input to form value. String = named parser, function = inline.
+     *
+     * Three-tier precedence (§6.4.3): field → type → none. Per-field override
+     * via `FieldConfig.parser`; the field-level value wins when `!== undefined`
+     * (resolved via `resolveFieldOverType`, §6.4.0 — so null/false/0/"" are
+     * meaningful overrides). Named (string) specs resolve against the
+     * provider's global `parsers` registry.
+     */
     parser?: string | ((value: unknown) => TValue);
-    /** Transform form value to display value. String = named formatter, function = inline */
+    /**
+     * Transform form value to display value. String = named formatter, function = inline.
+     *
+     * Three-tier precedence (§6.4.3): field → type → none. Per-field override
+     * via `FieldConfig.formatter`; the field-level value wins when `!== undefined`
+     * (resolved via `resolveFieldOverType`, §6.4.0 — so null/false/0/"" are
+     * meaningful overrides). Named (string) specs resolve against the
+     * provider's global `formatters` registry.
+     */
     formatter?: string | ((value: TValue) => unknown);
     /** Type-level validation (runs after field-level validator) */
     validator?: ValidatorSpec;
@@ -367,6 +412,38 @@ interface FieldConfig {
     order?: number;
     /** Key to use when reading initial value from record (defaults to field name) */
     recordKey?: string;
+    /**
+     * Per-instance default value. Overrides the input type's defaultValue;
+     * superseded by record/defaultValues prop. Honored when !== undefined, so
+     * null/false/0/"" are meaningful. See §6.4.1, §13.1.
+     */
+    defaultValue?: unknown;
+    /**
+     * Per-instance auto-save debounce. Overrides the input type's debounce;
+     * falls back to Form-level debounce prop (default 1000). false = submit
+     * immediately. See §6.4.2.
+     */
+    debounce?: number | false;
+    /**
+     * Per-instance value transform (input→form). Overrides the input type's
+     * parser. String = named parser; function = inline. See §6.4.3.
+     */
+    parser?: string | ((value: unknown) => unknown);
+    /**
+     * Per-instance value transform (form→display). Overrides the input type's
+     * formatter. String = named formatter; function = inline. See §6.4.3.
+     */
+    formatter?: string | ((value: unknown) => unknown);
+    /**
+     * Submit-side value extraction from complex objects. Overrides the input
+     * type's valueField. See §6.4.4.
+     */
+    valueField?: string;
+    /**
+     * Submit-side field name transformation. Overrides the input type's
+     * getSubmitField. See §6.4.4.
+     */
+    getSubmitField?: (fieldName: string) => string;
     /** Register options forwarded to the framework's field register call (typed loose for framework agnosticism; React consumers see react-hook-form's `RegisterOptions` via `ReactFieldConfig`) */
     rules?: Record<string, unknown>;
     /** Field-level validation (runs before type-level validator) */
@@ -1191,26 +1268,53 @@ declare function mergeConfigs(provider: FormalityProviderConfig, form?: FormConf
     fieldConfig: FieldConfig;
 };
 
+/**
+ * Resolve a field-level override against its type-level default. Returns the
+ * field value when it is not undefined (so null/false/0/"" are meaningful
+ * overrides); otherwise the type value. This is the single precedence rule
+ * shared by defaultValue, debounce, parser, formatter, getSubmitField, and
+ * valueField (§6.4.0). Every adapter MUST call this helper at each
+ * field-vs-type resolution site.
+ *
+ * @param fieldVal - The field-level (instance) value; `undefined` means "not specified".
+ * @param typeVal  - The type-level (InputConfig) default; `undefined` means "not specified".
+ * @returns `fieldVal` when it is not `undefined`, else `typeVal`.
+ *
+ * @example
+ * // Field override wins (even when falsy):
+ * resolveFieldOverType(false, true);   // → false
+ * resolveFieldOverType(null, "x");     // → null
+ * resolveFieldOverType(0, 100);        // → 0
+ * resolveFieldOverType("", "fallback");// → ""
+ *
+ * // Field unset → type default:
+ * resolveFieldOverType(undefined, "type"); // → "type"
+ * resolveFieldOverType(undefined, undefined); // → undefined
+ */
+declare function resolveFieldOverType<T>(fieldVal: T | undefined, typeVal: T | undefined): T | undefined;
 /**
  * Resolve the initial value for a field
  *
  * Priority order (highest to lowest):
  * 1. defaultValues[fieldName] (from Form props)
  * 2. record[recordKey] (using recordKey if specified, else fieldName)
- * 3. inputConfig.defaultValue (from input type definition)
+ * 3. fieldConfig.defaultValue (per-instance default; §6.4.1, §13.1)
+ * 4. inputConfig.defaultValue (from input type definition)
  *
  * **PRD deviation note (accepted, gap_analysis G5).** PRD §1.3.2's table
  * summarizes this export as `resolveInitialValue(record, config, inputConfig)`.
  * The implemented signature is a richer superset —
  * `(fieldName, fieldConfig?, inputConfig?, record?, defaultValues?)` — because
  * it drives the full priority chain above (defaultValues → record[recordKey] →
- * inputConfig.defaultValue) from a single call. This is an internal API
- * consumed by the framework adapters and by {@link resolveAllInitialValues},
- * not a simplified end-user entry point; the PRD literal form is a condensed
- * representation. No code change is planned.
+ * fieldConfig.defaultValue → inputConfig.defaultValue) from a single call. This
+ * is an internal API consumed by the framework adapters and by
+ * {@link resolveAllInitialValues}, not a simplified end-user entry point; the
+ * PRD literal form is a condensed representation. No code change is planned.
  *
  * @param fieldName - Field name
- * @param fieldConfig - Field configuration
+ * @param fieldConfig - Field configuration; `defaultValue` (when set) is the
+ *   Priority-3 per-instance default (§6.4.1), honored for any value
+ *   `!== undefined` (so null/false/0/"" are meaningful).
  * @param inputConfig - Input type configuration
  * @param record - Record data passed to form
  * @param defaultValues - Default values passed to form
@@ -1236,6 +1340,16 @@ declare function mergeConfigs(provider: FormalityProviderConfig, form?: FormConf
  *   { status: 'active' }
  * )
  * // → 'active' (defaultValues takes precedence)
+ *
+ * // Field-level default wins over the type default (§6.4.1)
+ * resolveInitialValue(
+ *   'active',
+ *   { type: 'switch', defaultValue: true }, // field default: true
+ *   { defaultValue: false }, // type default: false
+ *   undefined,
+ *   undefined,
+ * )
+ * // → true (field-level default honored; null/false/0/"" would also win)
  */
 declare function resolveInitialValue(fieldName: string, fieldConfig?: FieldConfig, inputConfig?: InputConfig, record?: Record<string, unknown>, defaultValues?: Record<string, unknown>): unknown;
 /**
@@ -1329,30 +1443,46 @@ declare function humanizeLabel(fieldName: string): string;
  * Priority order (highest to lowest):
  * 1. Component prop (label from JSX props)
  * 2. Field config props.label
- * 3. Evaluated selectProps.label
+ * 3. Evaluated selectProps.label (field-level selectProps)
  * 4. Field config label
  * 5. Field config title (legacy alias)
- * 6. Auto-generated from field name
+ * 6. Evaluated form-level selectDefaultFieldProps.label
+ * 7. Evaluated provider-level selectDefaultFieldProps.label
+ * 8. Auto-generated from field name
+ *
+ * The provider/form `selectDefaultFieldProps` layers are documented as label
+ * sources in PRD §16.1 (`providerConfig.selectDefaultFieldProps: { label:
+ * "props.name" }` works; same for `formConfig`). They sit below the field-level
+ * sources (matching their lower precedence in the 8-layer `mergeFieldProps`
+ * pipeline — layers 5 and 7 vs. the field-level layers 2/3) but above the
+ * humanized fallback, so a global label convention applies unless the field
+ * itself overrides it.
  *
  * **PRD deviation note (accepted, gap_analysis G5).** PRD §1.3.2's table
  * summarizes this export as `resolveLabel(config, fieldName)`. The implemented
  * signature is a richer superset —
- * `(fieldName, fieldConfig?, evaluatedSelectProps?, componentProps?)` — because
- * it resolves the full 6-source priority chain above in one call, which
- * requires the pre-evaluated `selectProps` and the JSX `componentProps`. This
+ * `(fieldName, fieldConfig?, evaluatedSelectProps?, componentProps?,
+ * providerSelectProps?, formSelectProps?)` — because it resolves the full
+ * priority chain above in one call, which requires the pre-evaluated
+ * `selectProps`/`selectDefaultFieldProps` and the JSX `componentProps`. This
  * is an internal API consumed by the framework adapters (e.g.
  * `@formality-ui/react`'s `Field` calls
- * `resolveLabel(name, fieldConfig, fieldSelectProps, restProps)`), not a
- * simplified end-user entry point; the PRD literal form is a condensed
- * representation. No code change is planned.
+ * `resolveLabel(name, fieldConfig, fieldSelectProps, restProps,
+ * providerSelectProps, formSelectProps)`), not a simplified end-user entry
+ * point; the PRD literal form is a condensed representation. No code change is
+ * planned.
  *
  * @param fieldName - Field name
  * @param fieldConfig - Field configuration
- * @param evaluatedSelectProps - Pre-evaluated selectProps
+ * @param evaluatedSelectProps - Pre-evaluated field-level selectProps
  * @param componentProps - Props from JSX
+ * @param providerSelectProps - Pre-evaluated provider-level
+ *   selectDefaultFieldProps (PRD §16.1)
+ * @param formSelectProps - Pre-evaluated form-level selectDefaultFieldProps
+ *   (PRD §16.1)
  * @returns Resolved label string
  */
-declare function resolveLabel(fieldName: string, fieldConfig?: FieldConfig, evaluatedSelectProps?: Record<string, unknown>, componentProps?: Record<string, unknown>): string;
+declare function resolveLabel(fieldName: string, fieldConfig?: FieldConfig, evaluatedSelectProps?: Record<string, unknown>, componentProps?: Record<string, unknown>, providerSelectProps?: Record<string, unknown>, formSelectProps?: Record<string, unknown>): string;
 /**
  * Resolve the title for a form
  *
@@ -1396,4 +1526,4 @@ declare function parseLabelWithUnit(label: string): {
     unit?: string;
 };
 
-export { type ConditionDescriptor, type ConditionResult, type ErrorMessagesConfig, type EvaluateConditionsInput, type EvaluationContext, FIELD_PROXY_MARKER, FIELD_PROXY_VALUE, type FieldConfig, type FieldError, type FieldState, type FieldStateInput, type FormConfig, type FormFieldsConfig, type FormState, type FormalityProviderConfig, type FormatterFunction, type FormatterSpec, type FormattersConfig, type GroupConfig, type InputConfig, type InputTemplateProps, KEYWORDS, type ParserFunction, type ParserSpec, type ParsersConfig, QUALIFIED_PREFIXES, type SelectFunction, type SelectValue, type ValidationResult, type ValidatorEntry, type ValidatorFactory, type ValidatorFunction, type ValidatorSpec, type ValidatorsConfig, buildEvaluationContext, buildFieldContext, buildFormContext, clearExpressionCache, composeValidators, conditionMatches, createConfigContext, createDefaultFormatters, createDefaultParsers, createErrorMessages, createFieldStateProxy, createFloatFormatter, createFloatParser, createIntParser, createLabelWithUnit, createTrimParser, createValidationError, deepMerge, evaluate, evaluateConditions, evaluateDescriptor, extractValueField, format, formatTypeAsMessage, getErrorType, getInputDefaultValue, getOrderedUnusedFields, getUnusedFields, humanizeLabel, inferFieldsFromConditions, inferFieldsFromDescriptor, inferFieldsFromExpression, isAutoGeneratedLabel, isEmptyValue, isFieldProxy, isValid, maxLength, mergeConditionResults, mergeConfigs, mergeFieldProps, mergeInputConfigs, mergeRecordWithDefaults, mergeStaticProps, minLength, parse, parseLabelWithUnit, pattern, required, resolveAllInitialValues, resolveErrorMessage, resolveFieldType, resolveFormTitle, resolveInitialValue, resolveInputConfig, resolveLabel, runValidator, runValidatorSync, sortFieldsByOrder, transformFieldName, unwrapFieldProxy, validate };
+export { type ConditionDescriptor, type ConditionResult, type ErrorMessagesConfig, type EvaluateConditionsInput, type EvaluationContext, FIELD_PROXY_MARKER, FIELD_PROXY_VALUE, type FieldConfig, type FieldError, type FieldState, type FieldStateInput, type FormConfig, type FormFieldsConfig, type FormState, type FormalityProviderConfig, type FormatterFunction, type FormatterSpec, type FormattersConfig, type GroupConfig, type InputConfig, type InputTemplateProps, KEYWORDS, type ParserFunction, type ParserSpec, type ParsersConfig, QUALIFIED_PREFIXES, type SelectFunction, type SelectValue, type ValidationResult, type ValidatorEntry, type ValidatorFactory, type ValidatorFunction, type ValidatorSpec, type ValidatorsConfig, buildEvaluationContext, buildFieldContext, buildFormContext, clearExpressionCache, composeValidators, conditionMatches, createConfigContext, createDefaultFormatters, createDefaultParsers, createErrorMessages, createFieldStateProxy, createFloatFormatter, createFloatParser, createIntParser, createLabelWithUnit, createTrimParser, createValidationError, deepMerge, evaluate, evaluateConditions, evaluateDescriptor, extractValueField, format, formatTypeAsMessage, getErrorType, getInputDefaultValue, getOrderedUnusedFields, getUnusedFields, humanizeLabel, inferFieldsFromConditions, inferFieldsFromDescriptor, inferFieldsFromExpression, isAutoGeneratedLabel, isEmptyValue, isFieldProxy, isValid, maxLength, mergeConditionResults, mergeConfigs, mergeFieldProps, mergeInputConfigs, mergeRecordWithDefaults, mergeStaticProps, minLength, parse, parseLabelWithUnit, pattern, required, resolveAllInitialValues, resolveErrorMessage, resolveFieldOverType, resolveFieldType, resolveFormTitle, resolveInitialValue, resolveInputConfig, resolveLabel, runValidator, runValidatorSync, sortFieldsByOrder, transformFieldName, unwrapFieldProxy, validate };

package/dist/index.js

@@ -1220,6 +1220,9 @@ function mergeConfigs(provider, form, field) {
 }
 
 // src/config/defaults.ts
+function resolveFieldOverType(fieldVal, typeVal) {
+  return fieldVal !== void 0 ? fieldVal : typeVal;
+}
 function resolveInitialValue(fieldName, fieldConfig, inputConfig, record, defaultValues) {
   if (defaultValues && fieldName in defaultValues) {
     return defaultValues[fieldName];
@@ -1228,8 +1231,12 @@ function resolveInitialValue(fieldName, fieldConfig, inputConfig, record, defaul
   if (record && recordKey in record) {
     return record[recordKey];
   }
-  if (inputConfig?.defaultValue !== void 0) {
-    return inputConfig.defaultValue;
+  const resolvedDefault = resolveFieldOverType(
+    fieldConfig?.defaultValue,
+    inputConfig?.defaultValue
+  );
+  if (resolvedDefault !== void 0) {
+    return resolvedDefault;
   }
   return void 0;
 }
@@ -1340,7 +1347,7 @@ function humanizeLabel(fieldName) {
   const words = fieldName.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").split(" ");
   return words.map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join(" ");
 }
-function resolveLabel(fieldName, fieldConfig, evaluatedSelectProps, componentProps) {
+function resolveLabel(fieldName, fieldConfig, evaluatedSelectProps, componentProps, providerSelectProps, formSelectProps) {
   if (componentProps?.label !== void 0) {
     return String(componentProps.label);
   }
@@ -1356,6 +1363,12 @@ function resolveLabel(fieldName, fieldConfig, evaluatedSelectProps, componentPro
   if (fieldConfig?.title !== void 0) {
     return fieldConfig.title;
   }
+  if (formSelectProps?.label !== void 0) {
+    return String(formSelectProps.label);
+  }
+  if (providerSelectProps?.label !== void 0) {
+    return String(providerSelectProps.label);
+  }
   return humanizeLabel(fieldName);
 }
 function resolveFormTitle(formTitle, evaluatedSelectTitle) {
@@ -1381,6 +1394,6 @@ function parseLabelWithUnit(label) {
   return { base: label };
 }
 
-export { FIELD_PROXY_MARKER, FIELD_PROXY_VALUE, KEYWORDS, QUALIFIED_PREFIXES, buildEvaluationContext, buildFieldContext, buildFormContext, clearExpressionCache, composeValidators, conditionMatches, createConfigContext, createDefaultFormatters, createDefaultParsers, createErrorMessages, createFieldStateProxy, createFloatFormatter, createFloatParser, createIntParser, createLabelWithUnit, createTrimParser, createValidationError, deepMerge, evaluate, evaluateConditions, evaluateDescriptor, extractValueField, format, formatTypeAsMessage, getErrorType, getInputDefaultValue, getOrderedUnusedFields, getUnusedFields, humanizeLabel, inferFieldsFromConditions, inferFieldsFromDescriptor, inferFieldsFromExpression, isAutoGeneratedLabel, isEmptyValue, isFieldProxy, isValid, maxLength, mergeConditionResults, mergeConfigs, mergeFieldProps, mergeInputConfigs, mergeRecordWithDefaults, mergeStaticProps, minLength, parse, parseLabelWithUnit, pattern, required, resolveAllInitialValues, resolveErrorMessage, resolveFieldType, resolveFormTitle, resolveInitialValue, resolveInputConfig, resolveLabel, runValidator, runValidatorSync, sortFieldsByOrder, transformFieldName, unwrapFieldProxy, validate };
+export { FIELD_PROXY_MARKER, FIELD_PROXY_VALUE, KEYWORDS, QUALIFIED_PREFIXES, buildEvaluationContext, buildFieldContext, buildFormContext, clearExpressionCache, composeValidators, conditionMatches, createConfigContext, createDefaultFormatters, createDefaultParsers, createErrorMessages, createFieldStateProxy, createFloatFormatter, createFloatParser, createIntParser, createLabelWithUnit, createTrimParser, createValidationError, deepMerge, evaluate, evaluateConditions, evaluateDescriptor, extractValueField, format, formatTypeAsMessage, getErrorType, getInputDefaultValue, getOrderedUnusedFields, getUnusedFields, humanizeLabel, inferFieldsFromConditions, inferFieldsFromDescriptor, inferFieldsFromExpression, isAutoGeneratedLabel, isEmptyValue, isFieldProxy, isValid, maxLength, mergeConditionResults, mergeConfigs, mergeFieldProps, mergeInputConfigs, mergeRecordWithDefaults, mergeStaticProps, minLength, parse, parseLabelWithUnit, pattern, required, resolveAllInitialValues, resolveErrorMessage, resolveFieldOverType, resolveFieldType, resolveFormTitle, resolveInitialValue, resolveInputConfig, resolveLabel, runValidator, runValidatorSync, sortFieldsByOrder, transformFieldName, unwrapFieldProxy, validate };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map