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

package/base/lib/actions/input/builder/value.js

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Value = void 0;
+exports.Value = exports.fileInfoParser = void 0;
 const util_1 = require("../../../util");
 const ts_matches_1 = require("ts-matches");
+exports.fileInfoParser = (0, ts_matches_1.object)({
+    path: ts_matches_1.string,
+    commitment: (0, ts_matches_1.object)({ hash: ts_matches_1.string, size: ts_matches_1.number }),
+});
 const testForAsRequiredParser = (0, util_1.once)(() => (0, ts_matches_1.object)({ required: (0, ts_matches_1.literal)(true) }).test);
 function asRequiredParser(parser, input) {
     if (testForAsRequiredParser()(input))
@@ -16,47 +20,78 @@ class Value {
         this._TYPE = null;
         this._PARTIAL = null;
     }
+    /**
+     * @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) {
+        const validator = ts_matches_1.boolean;
         return new Value(async () => ({
-            description: null,
-            warning: null,
-            type: "toggle",
-            disabled: false,
-            immutable: a.immutable ?? false,
-            ...a,
-        }), ts_matches_1.boolean);
+            spec: {
+                description: null,
+                warning: null,
+                type: "toggle",
+                disabled: false,
+                immutable: a.immutable ?? false,
+                ...a,
+            },
+            validator,
+        }), validator);
     }
     static dynamicToggle(a) {
+        const validator = ts_matches_1.boolean;
         return new Value(async (options) => ({
-            description: null,
-            warning: null,
-            type: "toggle",
-            disabled: false,
-            immutable: false,
-            ...(await a(options)),
-        }), ts_matches_1.boolean);
+            spec: {
+                description: null,
+                warning: null,
+                type: "toggle",
+                disabled: false,
+                immutable: false,
+                ...(await a(options)),
+            },
+            validator,
+        }), validator);
     }
+    /**
+     * @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(a) {
+        const validator = asRequiredParser(ts_matches_1.string, a);
         return new Value(async () => ({
-            type: "text",
-            description: null,
-            warning: null,
-            masked: false,
-            placeholder: null,
-            minLength: null,
-            maxLength: null,
-            patterns: [],
-            inputmode: "text",
-            disabled: false,
-            immutable: a.immutable ?? false,
-            generate: a.generate ?? null,
-            ...a,
-        }), asRequiredParser(ts_matches_1.string, a));
-    }
-    static dynamicText(getA) {
-        return new Value(async (options) => {
-            const a = await getA(options);
-            return {
+            spec: {
                 type: "text",
                 description: null,
                 warning: null,
@@ -67,13 +102,58 @@ class Value {
                 patterns: [],
                 inputmode: "text",
                 disabled: false,
-                immutable: false,
+                immutable: a.immutable ?? false,
                 generate: a.generate ?? null,
                 ...a,
+            },
+            validator,
+        }), validator);
+    }
+    static dynamicText(getA) {
+        return new Value(async (options) => {
+            const a = await getA(options);
+            return {
+                spec: {
+                    type: "text",
+                    description: null,
+                    warning: null,
+                    masked: false,
+                    placeholder: null,
+                    minLength: null,
+                    maxLength: null,
+                    patterns: [],
+                    inputmode: "text",
+                    disabled: false,
+                    immutable: false,
+                    generate: a.generate ?? null,
+                    ...a,
+                },
+                validator: asRequiredParser(ts_matches_1.string, a),
             };
         }, ts_matches_1.string.nullable());
     }
+    /**
+     * @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(a) {
+        const validator = asRequiredParser(ts_matches_1.string, a);
         return new Value(async () => {
             const built = {
                 description: null,
@@ -86,44 +166,55 @@ class Value {
                 immutable: a.immutable ?? false,
                 ...a,
             };
-            return built;
-        }, asRequiredParser(ts_matches_1.string, a));
+            return { spec: built, validator };
+        }, validator);
     }
     static dynamicTextarea(getA) {
         return new Value(async (options) => {
             const a = await getA(options);
             return {
-                description: null,
-                warning: null,
-                minLength: null,
-                maxLength: null,
-                placeholder: null,
-                type: "textarea",
-                disabled: false,
-                immutable: false,
-                ...a,
+                spec: {
+                    description: null,
+                    warning: null,
+                    minLength: null,
+                    maxLength: null,
+                    placeholder: null,
+                    type: "textarea",
+                    disabled: false,
+                    immutable: false,
+                    ...a,
+                },
+                validator: asRequiredParser(ts_matches_1.string, a),
             };
         }, ts_matches_1.string.nullable());
     }
+    /**
+     * @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(a) {
+        const validator = asRequiredParser(ts_matches_1.number, a);
         return new Value(() => ({
-            type: "number",
-            description: null,
-            warning: null,
-            min: null,
-            max: null,
-            step: null,
-            units: null,
-            placeholder: null,
-            disabled: false,
-            immutable: a.immutable ?? false,
-            ...a,
-        }), asRequiredParser(ts_matches_1.number, a));
-    }
-    static dynamicNumber(getA) {
-        return new Value(async (options) => {
-            const a = await getA(options);
-            return {
+            spec: {
                 type: "number",
                 description: null,
                 warning: null,
@@ -133,232 +224,470 @@ class Value {
                 units: null,
                 placeholder: null,
                 disabled: false,
-                immutable: false,
+                immutable: a.immutable ?? false,
                 ...a,
+            },
+            validator,
+        }), validator);
+    }
+    static dynamicNumber(getA) {
+        return new Value(async (options) => {
+            const a = await getA(options);
+            return {
+                spec: {
+                    type: "number",
+                    description: null,
+                    warning: null,
+                    min: null,
+                    max: null,
+                    step: null,
+                    units: null,
+                    placeholder: null,
+                    disabled: false,
+                    immutable: false,
+                    ...a,
+                },
+                validator: asRequiredParser(ts_matches_1.number, a),
             };
         }, ts_matches_1.number.nullable());
     }
+    /**
+     * @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(a) {
+        const validator = asRequiredParser(ts_matches_1.string, a);
         return new Value(() => ({
-            type: "color",
-            description: null,
-            warning: null,
-            disabled: false,
-            immutable: a.immutable ?? false,
-            ...a,
-        }), asRequiredParser(ts_matches_1.string, a));
-    }
-    static dynamicColor(getA) {
-        return new Value(async (options) => {
-            const a = await getA(options);
-            return {
+            spec: {
                 type: "color",
                 description: null,
                 warning: null,
                 disabled: false,
-                immutable: false,
+                immutable: a.immutable ?? false,
                 ...a,
+            },
+            validator,
+        }), validator);
+    }
+    static dynamicColor(getA) {
+        return new Value(async (options) => {
+            const a = await getA(options);
+            return {
+                spec: {
+                    type: "color",
+                    description: null,
+                    warning: null,
+                    disabled: false,
+                    immutable: false,
+                    ...a,
+                },
+                validator: asRequiredParser(ts_matches_1.string, a),
             };
         }, ts_matches_1.string.nullable());
     }
+    /**
+     * @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(a) {
+        const validator = asRequiredParser(ts_matches_1.string, a);
         return new Value(() => ({
-            type: "datetime",
-            description: null,
-            warning: null,
-            inputmode: "datetime-local",
-            min: null,
-            max: null,
-            step: null,
-            disabled: false,
-            immutable: a.immutable ?? false,
-            ...a,
-        }), asRequiredParser(ts_matches_1.string, a));
-    }
-    static dynamicDatetime(getA) {
-        return new Value(async (options) => {
-            const a = await getA(options);
-            return {
+            spec: {
                 type: "datetime",
                 description: null,
                 warning: null,
                 inputmode: "datetime-local",
                 min: null,
                 max: null,
+                step: null,
                 disabled: false,
-                immutable: false,
+                immutable: a.immutable ?? false,
                 ...a,
+            },
+            validator,
+        }), validator);
+    }
+    static dynamicDatetime(getA) {
+        return new Value(async (options) => {
+            const a = await getA(options);
+            return {
+                spec: {
+                    type: "datetime",
+                    description: null,
+                    warning: null,
+                    inputmode: "datetime-local",
+                    min: null,
+                    max: null,
+                    disabled: false,
+                    immutable: false,
+                    ...a,
+                },
+                validator: asRequiredParser(ts_matches_1.string, a),
             };
         }, ts_matches_1.string.nullable());
     }
+    /**
+     * @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(a) {
+        const validator = (0, ts_matches_1.anyOf)(...Object.keys(a.values).map((x) => (0, ts_matches_1.literal)(x)));
         return new Value(() => ({
-            description: null,
-            warning: null,
-            type: "select",
-            disabled: false,
-            immutable: a.immutable ?? false,
-            ...a,
-        }), (0, ts_matches_1.anyOf)(...Object.keys(a.values).map((x) => (0, ts_matches_1.literal)(x))));
-    }
-    static dynamicSelect(getA) {
-        return new Value(async (options) => {
-            const a = await getA(options);
-            return {
+            spec: {
                 description: null,
                 warning: null,
                 type: "select",
                 disabled: false,
-                immutable: false,
+                immutable: a.immutable ?? false,
                 ...a,
+            },
+            validator,
+        }), validator);
+    }
+    static dynamicSelect(getA) {
+        return new Value(async (options) => {
+            const a = await getA(options);
+            return {
+                spec: {
+                    description: null,
+                    warning: null,
+                    type: "select",
+                    disabled: false,
+                    immutable: false,
+                    ...a,
+                },
+                validator: (0, ts_matches_1.anyOf)(...Object.keys(a.values).map((x) => (0, ts_matches_1.literal)(x))),
             };
         }, ts_matches_1.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(a) {
+        const validator = (0, ts_matches_1.arrayOf)((0, ts_matches_1.literals)(...Object.keys(a.values)));
         return new Value(() => ({
-            type: "multiselect",
-            minLength: null,
-            maxLength: null,
-            warning: null,
-            description: null,
-            disabled: false,
-            immutable: a.immutable ?? false,
-            ...a,
-        }), (0, ts_matches_1.arrayOf)((0, ts_matches_1.literals)(...Object.keys(a.values))));
-    }
-    static dynamicMultiselect(getA) {
-        return new Value(async (options) => {
-            const a = await getA(options);
-            return {
+            spec: {
                 type: "multiselect",
                 minLength: null,
                 maxLength: null,
                 warning: null,
                 description: null,
                 disabled: false,
-                immutable: false,
+                immutable: a.immutable ?? false,
                 ...a,
+            },
+            validator,
+        }), validator);
+    }
+    static dynamicMultiselect(getA) {
+        return new Value(async (options) => {
+            const a = await getA(options);
+            return {
+                spec: {
+                    type: "multiselect",
+                    minLength: null,
+                    maxLength: null,
+                    warning: null,
+                    description: null,
+                    disabled: false,
+                    immutable: false,
+                    ...a,
+                },
+                validator: (0, ts_matches_1.arrayOf)((0, ts_matches_1.literals)(...Object.keys(a.values))),
             };
         }, (0, ts_matches_1.arrayOf)(ts_matches_1.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(a, spec) {
         return new Value(async (options) => {
             const built = await spec.build(options);
             return {
-                type: "object",
-                description: null,
-                warning: null,
-                ...a,
-                spec: built,
+                spec: {
+                    type: "object",
+                    description: null,
+                    warning: null,
+                    ...a,
+                    spec: built.spec,
+                },
+                validator: built.validator,
             };
         }, spec.validator);
     }
-    // static file<Store, Required extends boolean>(a: {
-    //   name: string
-    //   description?: string | null
-    //   extensions: string[]
-    //   required: Required
-    // }) {
-    //   const buildValue = {
-    //     type: "file" as const,
-    //     description: null,
-    //     warning: null,
-    //     ...a,
-    //   }
-    //   return new Value<AsRequired<FilePath, Required>, Store>(
-    //     () => ({
-    //       ...buildValue,
-    //     }),
-    //     asRequiredParser(object({ filePath: string }), a),
-    //   )
-    // }
-    // static dynamicFile<Store>(
-    //   a: LazyBuild<
-    //     Store,
-    //     {
-    //       name: string
-    //       description?: string | null
-    //       warning?: string | null
-    //       extensions: string[]
-    //       required: boolean
-    //     }
-    //   >,
-    // ) {
-    //   return new Value<FilePath | null, Store>(
-    //     async (options) => ({
-    //       type: "file" as const,
-    //       description: null,
-    //       warning: null,
-    //       ...(await a(options)),
-    //     }),
-    //     object({ filePath: string }).nullable(),
-    //   )
-    // }
-    static union(a, aVariants) {
-        return new Value(async (options) => ({
-            type: "union",
+    static file(a) {
+        const buildValue = {
+            type: "file",
             description: null,
             warning: null,
-            disabled: false,
             ...a,
-            variants: await aVariants.build(options),
-            immutable: a.immutable ?? false,
-        }), aVariants.validator);
+        };
+        return new Value(() => ({
+            spec: {
+                ...buildValue,
+            },
+            validator: asRequiredParser(exports.fileInfoParser, a),
+        }), asRequiredParser(exports.fileInfoParser, a));
     }
-    static filteredUnion(getDisabledFn, a, aVariants) {
-        return new Value(async (options) => ({
-            type: "union",
-            description: null,
-            warning: null,
-            ...a,
-            variants: await aVariants.build(options),
-            disabled: (await getDisabledFn(options)) || false,
-            immutable: false,
-        }), aVariants.validator);
+    static dynamicFile(a) {
+        return new Value(async (options) => {
+            const spec = {
+                type: "file",
+                description: null,
+                warning: null,
+                ...(await a(options)),
+            };
+            return {
+                spec,
+                validator: asRequiredParser(exports.fileInfoParser, spec),
+            };
+        }, exports.fileInfoParser.nullable());
+    }
+    /**
+     * @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(a) {
+        return new Value(async (options) => {
+            const built = await a.variants.build(options);
+            return {
+                spec: {
+                    type: "union",
+                    description: null,
+                    warning: null,
+                    disabled: false,
+                    ...a,
+                    variants: built.spec,
+                    immutable: a.immutable ?? false,
+                },
+                validator: built.validator,
+            };
+        }, a.variants.validator);
     }
-    static dynamicUnion(getA, aVariants) {
+    static dynamicUnion(getA, validator = ts_matches_1.any) {
         return new Value(async (options) => {
             const newValues = await getA(options);
+            const built = await newValues.variants.build(options);
             return {
-                type: "union",
-                description: null,
-                warning: null,
-                ...newValues,
-                variants: await aVariants.build(options),
-                immutable: false,
+                spec: {
+                    type: "union",
+                    description: null,
+                    warning: null,
+                    ...newValues,
+                    variants: built.spec,
+                    immutable: false,
+                },
+                validator: built.validator,
             };
-        }, aVariants.validator);
+        }, validator);
     }
+    /**
+     * @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({}),
+  
+            // optional
+            displayAs: null,
+            uniqueBy: null,
+          },
+        ),
+      ),
+     * ```
+     */
     static list(a) {
         return new Value((options) => a.build(options), a.validator);
     }
     static hidden(parser = ts_matches_1.any) {
         return new Value(async () => {
-            const built = {
-                type: "hidden",
+            return {
+                spec: {
+                    type: "hidden",
+                },
+                validator: parser,
             };
-            return built;
         }, parser);
     }
-    map(fn) {
-        return new Value(this.build, this.validator.map(fn));
-    }
     /**
-     * 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,
-    })
-  
-    return InputSpec.of<Store>()({
-      myValue: a.withStore(),
-    })
-    ```
+     * @description Provides a way to define a hidden field with a static value. Useful for tracking
+     * @example
+     * ```
+      hiddenExample: Value.hidden(),
+     * ```
      */
-    withStore() {
-        return this;
+    static dynamicHidden(getParser) {
+        return new Value(async (options) => {
+            const validator = await getParser(options);
+            return {
+                spec: {
+                    type: "hidden",
+                },
+                validator,
+            };
+        }, ts_matches_1.any);
+    }
+    map(fn) {
+        return new Value(async (effects) => {
+            const built = await this.build(effects);
+            return {
+                spec: built.spec,
+                validator: built.validator.map(fn),
+            };
+        }, this.validator.map(fn));
     }
 }
 exports.Value = Value;