@start9labs/start-sdk 0.4.0-beta.5 → 0.4.0-beta.51

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 { Pattern, RandomString, ValueSpec, ValueSpecDatetime, ValueSpecText } from "../inputSpecTypes";
-import { DefaultString } from "../inputSpecTypes";
-import { Parser } from "ts-matches";
-import { DeepPartial } from "../../../types";
-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>);
+import { InputSpec, LazyBuild } from './inputSpec';
+import { List } from './list';
+import { UnionRes, UnionResStaticValidatedAs, Variants } from './variants';
+import { Pattern, RandomString, ValueSpec, ValueSpecDatetime, ValueSpecText } from '../inputSpecTypes';
+import { DefaultString } from '../inputSpecTypes';
+import { z } from 'zod';
+import { DeepPartial } from '../../../types';
+export declare const fileInfoParser: z.ZodObject<{
+    path: z.ZodString;
+    commitment: z.ZodObject<{
+        hash: z.ZodString;
+        size: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type FileInfo = z.infer<typeof fileInfoParser>;
+export type AsRequired<T, Required extends boolean> = Required extends true ? T : T | null;
+export declare class Value<Type extends StaticValidatedAs, StaticValidatedAs = Type, OuterType = unknown> {
+    build: LazyBuild<{
+        spec: ValueSpec;
+        validator: z.ZodType<Type>;
+    }, OuterType>;
+    readonly validator: z.ZodType<StaticValidatedAs>;
+    protected constructor(build: LazyBuild<{
+        spec: ValueSpec;
+        validator: z.ZodType<Type>;
+    }, OuterType>, validator: z.ZodType<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, unknown>;
+    static dynamicToggle<OuterType = unknown>(a: LazyBuild<{
         name: string;
         description?: string | null;
         warning?: string | null;
         default: boolean;
         disabled?: false | string;
-    }>): Value<boolean, Store>;
+    }, OuterType>): Value<boolean, boolean, OuterType>;
+    /**
+     * @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;
@@ -71,7 +125,7 @@ export declare class Value<Type, Store> {
          * @description Informs the browser how to behave and which keyboard to display on mobile
          * @default "text"
          */
-        inputmode?: ValueSpecText["inputmode"];
+        inputmode?: ValueSpecText['inputmode'];
         /**
          * @description Once set, the value can never be changed.
          * @default false
@@ -81,22 +135,44 @@ 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>, unknown>;
+    static dynamicText<Required extends boolean, OuterType = unknown>(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;
         maxLength?: number | null;
         patterns?: Pattern[];
-        inputmode?: ValueSpecText["inputmode"];
+        inputmode?: ValueSpecText['inputmode'];
         disabled?: string | false;
         generate?: null | RandomString;
-    }>): Value<string | null, Store>;
+    }, OuterType>): Value<AsRequired<string, Required>, string | null, OuterType>;
+    /**
+     * @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,
+        minRows: 3
+        maxRows: 6
+        immutable: false,
+      }),
+      * ```
+      */
     static textarea<Required extends boolean>(a: {
         name: string;
         description?: string | null;
@@ -106,24 +182,68 @@ export declare class Value<Type, Store> {
         required: Required;
         minLength?: number | null;
         maxLength?: number | null;
+        /**
+         * @description A list of regular expressions to which the text must conform to pass validation. A human readable description is provided in case the validation fails.
+         * @default []
+         * @example
+         * ```
+          [
+            {
+              regex: "[a-z]",
+              description: "May only contain lower case letters from the English alphabet."
+            }
+          ]
+         * ```
+         */
+        patterns?: Pattern[];
+        /** Defaults to 3 */
+        minRows?: number;
+        /** Maximum number of rows before scroll appears. Defaults to 6 */
+        maxRows?: number;
         placeholder?: string | null;
         /**
          * @description Once set, the value can never be changed.
          * @default false
          */
         immutable?: boolean;
-    }): Value<AsRequired<string, Required>, never>;
-    static dynamicTextarea<Store = never>(getA: LazyBuild<Store, {
+    }): Value<AsRequired<string, Required>, AsRequired<string, Required>, unknown>;
+    static dynamicTextarea<Required extends boolean, OuterType = unknown>(getA: LazyBuild<{
         name: string;
         description?: string | null;
         warning?: string | null;
         default: string | null;
-        required: boolean;
+        required: Required;
         minLength?: number | null;
         maxLength?: number | null;
+        patterns?: Pattern[];
+        minRows?: number;
+        maxRows?: number;
         placeholder?: string | null;
         disabled?: false | string;
-    }>): Value<string | null, Store>;
+    }, OuterType>): Value<AsRequired<string, Required>, string | null, OuterType>;
+    /**
+     * @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 +278,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>, unknown>;
+    static dynamicNumber<Required extends boolean, OuterType = unknown>(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 +292,24 @@ export declare class Value<Type, Store> {
         units?: string | null;
         placeholder?: string | null;
         disabled?: false | string;
-    }>): Value<number | null, Store>;
+    }, OuterType>): Value<AsRequired<number, Required>, number | null, OuterType>;
+    /**
+     * @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 +328,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>, unknown>;
+    static dynamicColor<Required extends boolean, OuterType = unknown>(getA: LazyBuild<{
         name: string;
         description?: string | null;
         warning?: string | null;
         default: string | null;
-        required: boolean;
+        required: Required;
         disabled?: false | string;
-    }>): Value<string | null, Store>;
+    }, OuterType>): Value<AsRequired<string, Required>, string | null, OuterType>;
+    /**
+     * @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;
@@ -217,7 +374,7 @@ export declare class Value<Type, Store> {
          * @description Informs the browser how to behave and which date/time component to display.
          * @default "datetime-local"
          */
-        inputmode?: ValueSpecDatetime["inputmode"];
+        inputmode?: ValueSpecDatetime['inputmode'];
         min?: string | null;
         max?: string | null;
         /**
@@ -225,18 +382,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>, unknown>;
+    static dynamicDatetime<Required extends boolean, OuterType = unknown>(getA: LazyBuild<{
         name: string;
         description?: string | null;
         warning?: string | null;
         default: string | null;
-        required: boolean;
-        inputmode?: ValueSpecDatetime["inputmode"];
+        required: Required;
+        inputmode?: ValueSpecDatetime['inputmode'];
         min?: string | null;
         max?: string | null;
         disabled?: false | string;
-    }>): Value<string | null, Store>;
+    }, OuterType>): Value<AsRequired<string, Required>, string | null, OuterType>;
+    /**
+     * @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 +444,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, unknown>;
+    static dynamicSelect<Values extends Record<string, string>, OuterType = unknown>(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>;
+    }, OuterType>): Value<keyof Values & string, keyof Values & string, OuterType>;
+    /**
+     * @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 +504,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)[], unknown>;
+    static dynamicMultiselect<Values extends Record<string, string>, OuterType = unknown>(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: {
+    }, OuterType>): Value<(keyof Values & string)[], (keyof Values & string)[], OuterType>;
+    /**
+     * @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, unknown>;
+    static file<Required extends boolean>(a: {
         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>, AsRequired<{
+        path: string;
+        commitment: {
+            hash: string;
+            size: number;
+        };
+    }, Required>, unknown>;
+    static dynamicFile<Required extends boolean, OuterType = unknown>(a: LazyBuild<{
+        name: string;
+        description?: string | null;
+        warning?: string | null;
+        extensions: string[];
+        required: Required;
+    }, OuterType>): Value<AsRequired<{
+        path: string;
+        commitment: {
+            hash: string;
+            size: number;
+        };
+    }, Required>, {
+        path: string;
+        commitment: {
+            hash: string;
+            size: number;
+        };
+    } | null, OuterType>;
+    /**
+     * @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 +625,113 @@ 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>, unknown>;
+    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: {
+    }, OuterType = unknown>(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;
+    }, OuterType>): Value<UnionRes<VariantValues>, UnionRes<VariantValues>, OuterType>;
+    static dynamicUnion<StaticVariantValues extends {
         [K in string]: {
             name: string;
-            spec: InputSpec<any, Store> | InputSpec<any, never>;
+            spec: InputSpec<any, any>;
         };
-    }, Store>(getA: LazyBuild<Store, {
+    }, VariantValues extends StaticVariantValues, OuterType = unknown>(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>;
+    }, OuterType>, validator: z.ZodType<UnionResStaticValidatedAs<StaticVariantValues>>): Value<UnionRes<VariantValues>, UnionResStaticValidatedAs<StaticVariantValues>, OuterType>;
     /**
-     * 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: [],
+  
+            // 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({}),
   
-    return InputSpec.of<Store>()({
-      myValue: a.withStore(),
-    })
-    ```
+            // optional
+            displayAs: null,
+            uniqueBy: null,
+          },
+        ),
+      ),
+     * ```
+     */
+    static list<Type>(a: List<Type>): Value<Type, Type, unknown>;
+    /**
+     * @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>;
+    static hidden<T>(parser: z.ZodType<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, OuterType = unknown>(getParser: LazyBuild<z.ZodType<T>, OuterType>): Value<T, T, OuterType>;
+    map<U>(fn: (value: StaticValidatedAs) => U): Value<U, U, OuterType>;
 }
-export {};