@dynamicforms/vue-forms 0.16.1 → 0.17.1

package/dist/index.d.ts

@@ -7,12 +7,13 @@ import { Ref } from 'vue';
 /**
  * Thrown from a handler to end the run it is in. What the trigger answers with is the exception itself rather than
  * `null`, so a caller can tell a run a handler ended from one that reached no handler at all - and the setters
- * that ask a `*Changing*` handler read it as a refusal and write nothing.
+ * that ask a `*Changing*` handler read it as a refusal and write nothing. The answer carries it directly where the
+ * chain ran synchronously, and as what the answered promise resolves to where a handler in it was asynchronous.
  */
 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 +23,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 +33,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 */
@@ -45,7 +46,8 @@ export declare class Action<T extends ActionValue = ActionValue, X extends objec
      *
      * The answer is a promise whatever the handler returns, so a handler that throws rejects it rather than throwing
      * out of this call: a caller that does not await the answer and does not attach a catch handler leaves that
-     * rejection unhandled.
+     * rejection unhandled. An `AbortEventHandlingException` is the one exception that does not reject: the answer
+     * resolves with it, in a synchronous chain as in an asynchronous one.
      */
     execute(params?: any): Promise<any>;
 }
@@ -103,10 +105,24 @@ export declare class ActionsMap {
     bindTo(owner: FieldBase): void;
     /** True where no eager action of `identifier` stands after `index`, which makes `index` the group's entry. */
     private static outermostEager;
+    /**
+     * True where `value` is a promise, which is what a walk through an asynchronous handler answers with. The test is
+     * the type rather than a `then` member: a handler may answer with a value object that carries one, and calling
+     * `then` on such an object replaces the answer with whatever that call returns.
+     */
+    private static isPromise;
+    /**
+     * Answers an abort with itself on the asynchronous path as well. Where a handler in the chain is asynchronous, the
+     * walk answers with a promise and the abort raised under it arrives as that promise's rejection; this turns it back
+     * into the value the caller receives, so a promise the trigger answers with resolves to the exception instead of
+     * rejecting with it. Anything else keeps rejecting.
+     */
+    private static answerAbort;
     /**
      * Enters a group at its outermost action. An abort ends the run and is answered with rather than raised: the
-     * exception is what the caller receives, so a run a handler ended is told apart from one that reached no handler
-     * and from one whose handler answered null.
+     * exception is what the caller receives - directly where the chain ran synchronously, as what the answered promise
+     * resolves to where it did not - so a run a handler ended is told apart from one that reached no handler and from
+     * one whose handler answered null.
      */
     private run;
     /**
@@ -117,9 +133,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 +389,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 +481,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
@@ -785,6 +835,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
@@ -916,6 +982,7 @@ declare namespace Form {
         NullableField,
         IFieldConstructorActionsList,
         IFieldConstructorParams,
+        Extras,
         IFieldParams,
         IBindParams,
         AbortEventHandlingException,
@@ -971,7 +1038,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>>;
@@ -1105,7 +1172,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[];
@@ -1132,15 +1199,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);
@@ -1159,7 +1225,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.1",
+  "version": "0.17.1",
   "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",