@start9labs/start-sdk 0.4.0-beta.4 → 0.4.0-beta.40

package/base/lib/actions/input/builder/value.d.ts

@@ -1,17 +1,47 @@
 import { InputSpec, LazyBuild } from "./inputSpec";
 import { List } from "./list";
-import { Variants } from "./variants";
+import { UnionRes, UnionResStaticValidatedAs, Variants } from "./variants";
 import { Pattern, RandomString, ValueSpec, ValueSpecDatetime, ValueSpecText } from "../inputSpecTypes";
 import { DefaultString } from "../inputSpecTypes";
 import { Parser } from "ts-matches";
 import { DeepPartial } from "../../../types";
+export declare const fileInfoParser: Parser<unknown, {
+    path: string;
+    commitment: {
+        hash: string;
+        size: number;
+    };
+}>;
+export type FileInfo = typeof fileInfoParser._TYPE;
 type AsRequired<T, Required extends boolean> = Required extends true ? T : T | null;
-export declare class Value<Type, Store> {
-    build: LazyBuild<Store, ValueSpec>;
-    validator: Parser<unknown, Type>;
-    protected constructor(build: LazyBuild<Store, ValueSpec>, validator: Parser<unknown, Type>);
+export declare class Value<Type extends StaticValidatedAs, StaticValidatedAs = Type> {
+    build: LazyBuild<{
+        spec: ValueSpec;
+        validator: Parser<unknown, Type>;
+    }>;
+    readonly validator: Parser<unknown, StaticValidatedAs>;
+    protected constructor(build: LazyBuild<{
+        spec: ValueSpec;
+        validator: Parser<unknown, Type>;
+    }>, validator: Parser<unknown, StaticValidatedAs>);
     _TYPE: Type;
     _PARTIAL: DeepPartial<Type>;
+    /**
+     * @description Displays a boolean toggle to enable/disable
+     * @example
+     * ```
+      toggleExample: Value.toggle({
+        // required
+        name: 'Toggle Example',
+        default: true,
+      
+        // optional
+        description: null,
+        warning: null,
+        immutable: false,
+      }),
+      * ```
+     */
     static toggle(a: {
         name: string;
         description?: string | null;
@@ -23,14 +53,38 @@ export declare class Value<Type, Store> {
          * @default false
          */
         immutable?: boolean;
-    }): Value<boolean, never>;
-    static dynamicToggle<Store = never>(a: LazyBuild<Store, {
+    }): Value<boolean, boolean>;
+    static dynamicToggle(a: LazyBuild<{
         name: string;
         description?: string | null;
         warning?: string | null;
         default: boolean;
         disabled?: false | string;
-    }>): Value<boolean, Store>;
+    }>): Value<boolean, boolean>;
+    /**
+     * @description Displays a text input field
+     * @example
+     * ```
+      textExample: Value.text({
+        // required
+        name: 'Text Example',
+        required: false,
+        default: null,
+      
+        // optional
+        description: null,
+        placeholder: null,
+        warning: null,
+        generate: null,
+        inputmode: 'text',
+        masked: false,
+        minLength: null,
+        maxLength: null,
+        patterns: [],
+        immutable: false,
+      }),
+      * ```
+      */
     static text<Required extends boolean>(a: {
         name: string;
         description?: string | null;
@@ -81,13 +135,13 @@ export declare class Value<Type, Store> {
          * @description Displays a button that will generate a random string according to the provided charset and len attributes.
          */
         generate?: RandomString | null;
-    }): Value<AsRequired<string, Required>, never>;
-    static dynamicText<Store = never>(getA: LazyBuild<Store, {
+    }): Value<AsRequired<string, Required>, AsRequired<string, Required>>;
+    static dynamicText<Required extends boolean>(getA: LazyBuild<{
         name: string;
         description?: string | null;
         warning?: string | null;
         default: DefaultString | null;
-        required: boolean;
+        required: Required;
         masked?: boolean;
         placeholder?: string | null;
         minLength?: number | null;
@@ -96,7 +150,27 @@ export declare class Value<Type, Store> {
         inputmode?: ValueSpecText["inputmode"];
         disabled?: string | false;
         generate?: null | RandomString;
-    }>): Value<string | null, Store>;
+    }>): Value<AsRequired<string, Required>, string | null>;
+    /**
+     * @description Displays a large textarea field for long form entry.
+     * @example
+     * ```
+      textareaExample: Value.textarea({
+        // required
+        name: 'Textarea Example',
+        required: false,
+        default: null,
+      
+        // optional
+        description: null,
+        placeholder: null,
+        warning: null,
+        minLength: null,
+        maxLength: null,
+        immutable: false,
+      }),
+      * ```
+      */
     static textarea<Required extends boolean>(a: {
         name: string;
         description?: string | null;
@@ -112,18 +186,41 @@ export declare class Value<Type, Store> {
          * @default false
          */
         immutable?: boolean;
-    }): Value<AsRequired<string, Required>, never>;
-    static dynamicTextarea<Store = never>(getA: LazyBuild<Store, {
+    }): Value<AsRequired<string, Required>, AsRequired<string, Required>>;
+    static dynamicTextarea<Required extends boolean>(getA: LazyBuild<{
         name: string;
         description?: string | null;
         warning?: string | null;
         default: string | null;
-        required: boolean;
+        required: Required;
         minLength?: number | null;
         maxLength?: number | null;
         placeholder?: string | null;
         disabled?: false | string;
-    }>): Value<string | null, Store>;
+    }>): Value<AsRequired<string, Required>, string | null>;
+    /**
+     * @description Displays a number input field
+     * @example
+     * ```
+      numberExample: Value.number({
+        // required
+        name: 'Number Example',
+        required: false,
+        default: null,
+        integer: true,
+      
+        // optional
+        description: null,
+        placeholder: null,
+        warning: null,
+        min: null,
+        max: null,
+        immutable: false,
+        step: null,
+        units: null,
+      }),
+      * ```
+      */
     static number<Required extends boolean>(a: {
         name: string;
         description?: string | null;
@@ -158,13 +255,13 @@ export declare class Value<Type, Store> {
          * @default false
          */
         immutable?: boolean;
-    }): Value<AsRequired<number, Required>, never>;
-    static dynamicNumber<Store = never>(getA: LazyBuild<Store, {
+    }): Value<AsRequired<number, Required>, AsRequired<number, Required>>;
+    static dynamicNumber<Required extends boolean>(getA: LazyBuild<{
         name: string;
         description?: string | null;
         warning?: string | null;
         default: number | null;
-        required: boolean;
+        required: Required;
         min?: number | null;
         max?: number | null;
         step?: number | null;
@@ -172,7 +269,24 @@ export declare class Value<Type, Store> {
         units?: string | null;
         placeholder?: string | null;
         disabled?: false | string;
-    }>): Value<number | null, Store>;
+    }>): Value<AsRequired<number, Required>, number | null>;
+    /**
+     * @description Displays a browser-native color selector.
+     * @example
+     * ```
+      colorExample: Value.color({
+        // required
+        name: 'Color Example',
+        required: false,
+        default: null,
+      
+        // optional
+        description: null,
+        warning: null,
+        immutable: false,
+      }),
+      * ```
+      */
     static color<Required extends boolean>(a: {
         name: string;
         description?: string | null;
@@ -191,15 +305,35 @@ export declare class Value<Type, Store> {
          * @default false
          */
         immutable?: boolean;
-    }): Value<AsRequired<string, Required>, never>;
-    static dynamicColor<Store = never>(getA: LazyBuild<Store, {
+    }): Value<AsRequired<string, Required>, AsRequired<string, Required>>;
+    static dynamicColor<Required extends boolean>(getA: LazyBuild<{
         name: string;
         description?: string | null;
         warning?: string | null;
         default: string | null;
-        required: boolean;
+        required: Required;
         disabled?: false | string;
-    }>): Value<string | null, Store>;
+    }>): Value<AsRequired<string, Required>, string | null>;
+    /**
+     * @description Displays a browser-native date/time selector.
+     * @example
+     * ```
+      datetimeExample: Value.datetime({
+        // required
+        name: 'Datetime Example',
+        required: false,
+        default: null,
+      
+        // optional
+        description: null,
+        warning: null,
+        immutable: false,
+        inputmode: 'datetime-local',
+        min: null,
+        max: null,
+      }),
+      * ```
+      */
     static datetime<Required extends boolean>(a: {
         name: string;
         description?: string | null;
@@ -225,18 +359,39 @@ export declare class Value<Type, Store> {
          * @default false
          */
         immutable?: boolean;
-    }): Value<AsRequired<string, Required>, never>;
-    static dynamicDatetime<Store = never>(getA: LazyBuild<Store, {
+    }): Value<AsRequired<string, Required>, AsRequired<string, Required>>;
+    static dynamicDatetime<Required extends boolean>(getA: LazyBuild<{
         name: string;
         description?: string | null;
         warning?: string | null;
         default: string | null;
-        required: boolean;
+        required: Required;
         inputmode?: ValueSpecDatetime["inputmode"];
         min?: string | null;
         max?: string | null;
         disabled?: false | string;
-    }>): Value<string | null, Store>;
+    }>): Value<AsRequired<string, Required>, string | null>;
+    /**
+     * @description Displays a select modal with radio buttons, allowing for a single selection.
+     * @example
+     * ```
+      selectExample: Value.select({
+        // required
+        name: 'Select Example',
+        default: 'radio1',
+        values: {
+          radio1: 'Radio 1',
+          radio2: 'Radio 2',
+        },
+      
+        // optional
+        description: null,
+        warning: null,
+        immutable: false,
+        disabled: false,
+      }),
+      * ```
+      */
     static select<Values extends Record<string, string>>(a: {
         name: string;
         description?: string | null;
@@ -266,15 +421,38 @@ export declare class Value<Type, Store> {
          * @default false
          */
         immutable?: boolean;
-    }): Value<keyof Values & string, never>;
-    static dynamicSelect<Store = never>(getA: LazyBuild<Store, {
+    }): Value<keyof Values & string, keyof Values & string>;
+    static dynamicSelect<Values extends Record<string, string>>(getA: LazyBuild<{
         name: string;
         description?: string | null;
         warning?: string | null;
         default: string;
-        values: Record<string, string>;
+        values: Values;
         disabled?: false | string | string[];
-    }>): Value<string, Store>;
+    }>): Value<keyof Values & string, string>;
+    /**
+     * @description Displays a select modal with checkboxes, allowing for multiple selections.
+     * @example
+     * ```
+      multiselectExample: Value.multiselect({
+        // required
+        name: 'Multiselect Example',
+        values: {
+          option1: 'Option 1',
+          option2: 'Option 2',
+        },
+        default: [],
+      
+        // optional
+        description: null,
+        warning: null,
+        immutable: false,
+        disabled: false,
+        minlength: null,
+        maxLength: null,
+      }),
+      * ```
+      */
     static multiselect<Values extends Record<string, string>>(a: {
         name: string;
         description?: string | null;
@@ -303,31 +481,116 @@ export declare class Value<Type, Store> {
          * @default false
          */
         immutable?: boolean;
-    }): Value<(keyof Values)[], never>;
-    static dynamicMultiselect<Store = never>(getA: LazyBuild<Store, {
+    }): Value<(keyof Values & string)[], (keyof Values & string)[]>;
+    static dynamicMultiselect<Values extends Record<string, string>>(getA: LazyBuild<{
         name: string;
         description?: string | null;
         warning?: string | null;
         default: string[];
-        values: Record<string, string>;
+        values: Values;
         minLength?: number | null;
         maxLength?: number | null;
         disabled?: false | string | string[];
-    }>): Value<string[], Store>;
-    static object<Type extends Record<string, any>, Store>(a: {
+    }>): Value<(keyof Values & string)[], string[]>;
+    /**
+     * @description Display a collapsable grouping of additional fields, a "sub form". The second value is the inputSpec spec for the sub form.
+     * @example
+     * ```
+      objectExample: Value.object(
+        {
+          // required
+          name: 'Object Example',
+      
+          // optional
+          description: null,
+          warning: null,
+        },
+        InputSpec.of({}),
+      ),
+      * ```
+      */
+    static object<Type extends StaticValidatedAs, StaticValidatedAs extends Record<string, any>>(a: {
+        name: string;
+        description?: string | null;
+    }, spec: InputSpec<Type, StaticValidatedAs>): Value<Type, StaticValidatedAs>;
+    static file<Required extends boolean>(a: {
+        name: string;
+        description?: string | null;
+        warning?: string | null;
+        extensions: string[];
+        required: Required;
+    }): Value<AsRequired<{
+        path: string;
+        commitment: {
+            hash: string;
+            size: number;
+        };
+    }, Required>, AsRequired<{
+        path: string;
+        commitment: {
+            hash: string;
+            size: number;
+        };
+    }, Required>>;
+    static dynamicFile<Required extends boolean>(a: LazyBuild<{
         name: string;
         description?: string | null;
-    }, spec: InputSpec<Type, Store>): Value<Type, Store>;
+        warning?: string | null;
+        extensions: string[];
+        required: Required;
+    }>): Value<AsRequired<{
+        path: string;
+        commitment: {
+            hash: string;
+            size: number;
+        };
+    }, Required>, {
+        path: string;
+        commitment: {
+            hash: string;
+            size: number;
+        };
+    } | null>;
+    /**
+     * @description Displays a dropdown, allowing for a single selection. Depending on the selection, a different object ("sub form") is presented.
+     * @example
+     * ```
+      unionExample: Value.union(
+        {
+          // required
+          name: 'Union Example',
+          default: 'option1',
+      
+          // optional
+          description: null,
+          warning: null,
+          disabled: false,
+          immutable: false,
+        },
+        Variants.of({
+          option1: {
+            name: 'Option 1',
+            spec: InputSpec.of({}),
+          },
+          option2: {
+            name: 'Option 2',
+            spec: InputSpec.of({}),
+          },
+        }),
+      ),
+      * ```
+      */
     static union<VariantValues extends {
         [K in string]: {
             name: string;
-            spec: InputSpec<any, Store> | InputSpec<any, never>;
+            spec: InputSpec<any>;
         };
-    }, Store>(a: {
+    }>(a: {
         name: string;
         description?: string | null;
         /** Presents a warning prompt before permitting the value to change. */
         warning?: string | null;
+        variants: Variants<VariantValues>;
         /**
          * @description Provide a default value from the list of variants.
          * @type { string }
@@ -339,47 +602,114 @@ export declare class Value<Type, Store> {
          * @default false
          */
         immutable?: boolean;
-    }, aVariants: Variants<VariantValues, Store>): Value<import("./variants").UnionRes<Store, VariantValues, keyof VariantValues & string>, Store>;
-    static filteredUnion<VariantValues extends {
+    }): Value<UnionRes<VariantValues, keyof VariantValues & string>, UnionResStaticValidatedAs<VariantValues, keyof VariantValues & string>>;
+    static dynamicUnion<VariantValues extends {
         [K in string]: {
             name: string;
-            spec: InputSpec<any, Store> | InputSpec<any, never>;
+            spec: InputSpec<any>;
         };
-    }, Store>(getDisabledFn: LazyBuild<Store, string[] | false | string>, a: {
+    }>(getA: LazyBuild<{
         name: string;
         description?: string | null;
         warning?: string | null;
+        variants: Variants<VariantValues>;
         default: keyof VariantValues & string;
-    }, aVariants: Variants<VariantValues, Store> | Variants<VariantValues, never>): Value<import("./variants").UnionRes<Store, VariantValues, keyof VariantValues & string> | import("./variants").UnionRes<never, VariantValues, keyof VariantValues & string>, Store>;
-    static dynamicUnion<VariantValues extends {
+        disabled: string[] | false | string;
+    }>): Value<UnionRes<VariantValues>, unknown>;
+    static dynamicUnion<VariantValues extends StaticVariantValues, StaticVariantValues extends {
         [K in string]: {
             name: string;
-            spec: InputSpec<any, Store> | InputSpec<any, never>;
+            spec: InputSpec<any, any>;
         };
-    }, Store>(getA: LazyBuild<Store, {
+    }>(getA: LazyBuild<{
         name: string;
         description?: string | null;
         warning?: string | null;
+        variants: Variants<VariantValues>;
         default: keyof VariantValues & string;
         disabled: string[] | false | string;
-    }>, aVariants: Variants<VariantValues, Store> | Variants<VariantValues, never>): Value<import("./variants").UnionRes<Store, VariantValues, keyof VariantValues & string> | import("./variants").UnionRes<never, VariantValues, keyof VariantValues & string>, Store>;
-    static list<Type, Store>(a: List<Type, Store>): Value<Type, Store>;
-    static hidden<T>(parser?: Parser<unknown, T>): Value<T, never>;
-    map<U>(fn: (value: Type) => U): Value<U, Store>;
+    }>, validator: Parser<unknown, UnionResStaticValidatedAs<StaticVariantValues>>): Value<UnionRes<VariantValues>, UnionResStaticValidatedAs<StaticVariantValues>>;
     /**
-     * Use this during the times that the input needs a more specific type.
-     * Used in types that the value/ variant/ list/ inputSpec is constructed somewhere else.
-    ```ts
-    const a = InputSpec.text({
-      name: "a",
-      required: false,
-    })
+     * @description Presents an interface to add/remove/edit items in a list.
+     * @example
+     * In this example, we create a list of text inputs.
+     *
+     * ```
+      listExampleText: Value.list(
+        List.text(
+          {
+            // required
+            name: 'Text List',
+  
+            // optional
+            description: null,
+            warning: null,
+            default: [],
+            minLength: null,
+            maxLength: null,
+          },
+          {
+            // required
+            patterns: [],
   
-    return InputSpec.of<Store>()({
-      myValue: a.withStore(),
-    })
-    ```
+            // optional
+            placeholder: null,
+            generate: null,
+            inputmode: 'url',
+            masked: false,
+            minLength: null,
+            maxLength: null,
+          },
+        ),
+      ),
+     * ```
+     * @example
+     * In this example, we create a list of objects.
+     *
+     * ```
+      listExampleObject: Value.list(
+        List.obj(
+          {
+            // required
+            name: 'Object List',
+  
+            // optional
+            description: null,
+            warning: null,
+            default: [],
+            minLength: null,
+            maxLength: null,
+          },
+          {
+            // required
+            spec: InputSpec.of({}),
+  
+            // optional
+            displayAs: null,
+            uniqueBy: null,
+          },
+        ),
+      ),
+     * ```
+     */
+    static list<Type>(a: List<Type>): Value<Type, Type>;
+    /**
+     * @description Provides a way to define a hidden field with a static value. Useful for tracking
+     * @example
+     * ```
+      hiddenExample: Value.hidden(),
+     * ```
+     */
+    static hidden<T>(): Value<T, unknown>;
+    static hidden<T>(parser: Parser<unknown, T>): Value<T>;
+    /**
+     * @description Provides a way to define a hidden field with a static value. Useful for tracking
+     * @example
+     * ```
+      hiddenExample: Value.hidden(),
+     * ```
      */
-    withStore<NewStore extends Store extends never ? any : Store>(): Value<Type, NewStore>;
+    static dynamicHidden<T>(getParser: LazyBuild<Parser<unknown, T>>): Value<T, unknown>;
+    map<U>(fn: (value: StaticValidatedAs) => U): Value<U>;
 }
 export {};