@dynamicforms/vue-forms 0.16.0 → 0.17.0

package/dist/index.d.ts

@@ -12,7 +12,7 @@ import { Ref } from 'vue';
 export declare class AbortEventHandlingException extends Error {
 }
 
-export declare class Action<T extends ActionValue = ActionValue, X extends object = {}> extends Field<T, X> {
+export declare class Action<T extends ActionValue = ActionValue, X extends object = Omit<Extras, keyof ActionValue>> extends Field<T, X> {
     get [Symbol.toStringTag](): string;
     protected init(params?: IFieldParams<T, X>): void;
     /**
@@ -22,9 +22,9 @@ export declare class Action<T extends ActionValue = ActionValue, X extends objec
      * against a baseline that never carried the key.
      */
     private valueWith;
-    get icon(): string | undefined;
-    set icon(newValue: string | undefined);
-    get label(): string | undefined;
+    get icon(): T['icon'];
+    set icon(newValue: T['icon']);
+    get label(): T['label'];
     /**
      * The two setters hand the value setter a new object rather than writing into the one the action holds, so each
      * is an ordinary value change: the handlers fire, isChanged answers over it, and a disabled action refuses it.
@@ -32,7 +32,7 @@ export declare class Action<T extends ActionValue = ActionValue, X extends objec
      * identity and every copy is a new object, so without the comparison here a write of the value already held
      * would announce a change and invalidate the value cache of every container above.
      */
-    set label(newValue: string | undefined);
+    set label(newValue: T['label']);
     /** the counter behind `busy`, allocated for this action the first time it is asked for */
     private get busyRuns();
     /** true from the moment execute() is called until the handler it ran has settled, however it settles */
@@ -117,9 +117,19 @@ export declare class ActionsMap {
     private walk;
 }
 
+/**
+ * The value an `Action` holds. Both members are `unknown` because `Action` states the concept and a UI library
+ * states what it renders: a subclass declares its value type with `label` and `icon` in whatever shape it renders
+ * them - `string | MdString`, a per-breakpoint object - and the accessors below answer at that type, because they
+ * read it off `T` rather than fixing one of their own.
+ *
+ * The consequence for an `Action` built without a type argument is that reading either member answers `unknown`
+ * and the reader states what it expects. That is the shape the class is for; an application that renders actions
+ * uses the subclass its UI library ships.
+ */
 export declare interface ActionValue {
-    label?: string;
-    icon?: string;
+    label?: unknown;
+    icon?: unknown;
 }
 
 /**
@@ -363,7 +373,31 @@ export declare class ExecuteAction extends FieldActionBase {
     execute(field: FieldBase, supr: FieldActionExecute, params: any): any;
 }
 
-export declare class Field<T = any, X extends object = {}> extends FieldBase<T, X> {
+/**
+ * The extended properties an element carries when nothing states otherwise. It is empty as declared and exists
+ * to be augmented: the layer that renders the elements declares what it renders them with, and every element in
+ * the application then carries those properties without a type argument at any construction site.
+ *
+ * ```ts
+ * declare module '@dynamicforms/vue-forms' {
+ *   interface Extras {
+ *     label?: string;
+ *     hint?: string;
+ *     cssClass?: string;
+ *   }
+ * }
+ * ```
+ *
+ * The interface is one per application, so two packages that both declare a property of the same name must give
+ * it the same type; declaration merging refuses a second declaration that differs.
+ *
+ * An element that states an X of its own replaces this rather than adding to it, so an element that carries both
+ * is `Field<string, Extras & Local>`.
+ */
+export declare interface Extras {
+}
+
+export declare class Field<T = any, X extends object = Extras> extends FieldBase<T, X> {
     get [Symbol.toStringTag](): string;
     protected get state(): FieldSlots<T>;
     protected get raw(): FieldSlots<T>;
@@ -431,7 +465,7 @@ export declare abstract class FieldActionBase {
 
 export declare type FieldActionExecute<T = any> = (field: FieldBase<T>, ...params: any[]) => any;
 
-export declare abstract class FieldBase<T = any, X extends object = {}> {
+export declare abstract class FieldBase<T = any, X extends object = Extras> {
     #private;
     /**
      * Vue's getTargetType answers INVALID for an object that carries __v_skip, so reactive() hands an element back
@@ -710,6 +744,25 @@ export declare abstract class FieldBase<T = any, X extends object = {}> {
      * different list whatever the items compare as - so the commit announces it without composing a comparison.
      */
     protected propagateValueChanged(force?: boolean): void;
+    /**
+     * The last step of a construction: it runs inside the transaction the construction is, with the parameters
+     * applied and the value in place, before the element records what it was built as.
+     *
+     * A subclass overrides it to complete what the element was built with. What it writes here is part of the
+     * construction rather than a change of it: the element announces no ValueChangedAction, and what the hook
+     * leaves is what its eager actions and its validators run over, once. An element whose parameters named no
+     * `originalValue` is baselined on the value the hook left and so starts unchanged; one that named a baseline is
+     * measured against it, as any element is. A `Field` writes
+     * `_value`, which reaches the slot on an element built `enabled: false` as well - the value setter, which a
+     * disabled field refuses, states a change, and this is not one.
+     *
+     * A container completes itself through its members, and a member carries a construction of its own: the write
+     * reaches it as any later one would, so the member announces it and reports itself changed. A member that is to
+     * start unchanged is baselined here as well - `this.fields.x.originalValue = this.fields.x.value`.
+     *
+     * `params` is the parameter object the constructor received, where it received one.
+     */
+    protected constructed(params?: object): void;
     /**
      * Re-reads the value that the next ValueChangedAction will report as the one it replaces. A leaf records what
      * it announced at every announcement, so its copy is always current and there is nothing to re-read; a
@@ -766,6 +819,22 @@ export declare abstract class FieldBase<T = any, X extends object = {}> {
     set visibility(newValue: DisplayMode);
     get enabled(): boolean;
     set enabled(newValue: boolean);
+    /**
+     * Whether this element and every container above it are enabled. A rendering layer binds one read instead of
+     * walking the parent chain: a disabled `Group` states that its section cannot be edited, and the inputs
+     * rendered from the members inside it read that here.
+     *
+     * It is a read and nothing else. `enabled` on each element stays exactly what was written to it, a write to a
+     * member of a disabled container is accepted the way it always was, and what a container serializes is decided
+     * by the members' own `enabled`. Where a whole subtree is to stop serializing, the members are disabled.
+     *
+     * `enabled` is the only member with a reading of this kind, and it is not a scheme the other members follow.
+     * `visibility` has none because `SUPPRESS` states that an element is absent from the value as well, so folding
+     * it down the tree would decide serialization rather than report it; `value` has none because a container
+     * composes its own from its members rather than passing one down. A rendering layer that needs a third thing
+     * folded down the tree has `provide`/`inject`, which is where the render tree's own context belongs.
+     */
+    get effectiveEnabled(): boolean;
     /**
      * True for an element whose value is composed of its members'. The commit builds such a value only where
      * something receives it, compares it by content rather than by identity, and runs the element's own validators
@@ -897,6 +966,7 @@ declare namespace Form {
         NullableField,
         IFieldConstructorActionsList,
         IFieldConstructorParams,
+        Extras,
         IFieldParams,
         IBindParams,
         AbortEventHandlingException,
@@ -952,7 +1022,7 @@ export declare type GenericFieldsInterface = Record<string, FieldBase>;
 /** The current configuration. The object is the module's own record, and reading it again reports later writes. */
 export declare function getConfig(): FormsConfig;
 
-export declare class Group<T extends GenericFieldsInterface = GenericFieldsInterface, X extends object = {}> extends FieldBase<GroupValue<T>, X> {
+export declare class Group<T extends GenericFieldsInterface = GenericFieldsInterface, X extends object = Extras> extends FieldBase<GroupValue<T>, X> {
     get [Symbol.toStringTag](): string;
     protected get state(): GroupSlots<GroupValue<T>>;
     protected get raw(): GroupSlots<GroupValue<T>>;
@@ -1086,7 +1156,7 @@ export declare type GroupValueInput<T extends GenericFieldsInterface> = Partial<
  * `validators` and `actions` are carried from the declaration rather than supplied, and `touched` and `errors`
  * are what the binding establishes for itself as it validates.
  */
-export declare type IBindParams<T = any, X extends object = {}> = Partial<Pick<IFieldConstructorParams<T>, 'originalValue' | 'enabled' | 'visibility'>> & Partial<NoInfer<X>>;
+export declare type IBindParams<T = any, X extends object = Extras> = Partial<Pick<IFieldConstructorParams<T>, 'originalValue' | 'enabled' | 'visibility'>> & Partial<NoInfer<X>>;
 
 export declare interface IFieldConstructorActionsList {
     actions?: FieldActionBase[];
@@ -1113,15 +1183,14 @@ export declare type IFieldConstructorParams<T = any> = {
  * What an element's constructor accepts: the parameters the element answers for itself, together with the
  * extended properties its X parameter declares.
  *
- * X is left out of inference, so an element built without a type argument carries no extended properties and a
- * parameter object naming one is rejected as an excess property. A caller that wants them states them:
- * `new Field<string, { label: string }>({ value: 'a', label: 'Name' })`.
+ * X is left out of inference, so an element carries what its X states - `Extras` where no type argument replaces
+ * it - and a parameter object naming anything else is rejected as an excess property.
  *
  * The two halves are made partial separately. `Partial<A & X>` is a mapped type over an intersection, which is
  * what T is inferred through, and inference through it answers with one constituent of a union rather than the
  * union: `new Field({ value: someStringOrNumber })` would be a Field<string>.
  */
-export declare type IFieldParams<T = any, X extends object = {}> = Partial<IFieldConstructorParams<T>> & Partial<NoInfer<X>>;
+export declare type IFieldParams<T = any, X extends object = Extras> = Partial<IFieldConstructorParams<T>> & Partial<NoInfer<X>>;
 
 declare class InAllowedValues<T = any> extends Validator {
     constructor(allowedValues: AllowedValues<T>, message?: RenderContentRef);
@@ -1140,7 +1209,7 @@ declare class LengthInRange extends Validator {
     constructor(minLength: number, maxLength: number, message?: RenderContentRef);
 }
 
-export declare class List<T extends GenericFieldsInterface = GenericFieldsInterface, X extends object = {}> extends FieldBase<ListValue, X> {
+export declare class List<T extends GenericFieldsInterface = GenericFieldsInterface, X extends object = Extras> extends FieldBase<ListValue, X> {
     get [Symbol.toStringTag](): string;
     protected get state(): ListSlots<T>;
     protected get raw(): ListSlots<T>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dynamicforms/vue-forms",
   "private": false,
-  "version": "0.16.0",
+  "version": "0.17.0",
   "type": "module",
   "description": "A lightweight Vue.js library for form state management with built-in validation, conditional logic, nested structures, and a rich event system. UI-agnostic and TypeScript-first.",
   "author": "Jure Erzno\u017enik",