@foormjs/atscript 0.2.0

package/dist/index.mjs

@@ -0,0 +1,227 @@
+import { FNPool } from '@prostojs/deserialize-fn';
+
+const pool = new FNPool();
+/**
+ * Compiles a field-level function string from a @foorm.fn.* annotation
+ * into a callable function. Uses FNPool for caching.
+ *
+ * The function string should be an arrow or regular function expression:
+ *   "(v, data, ctx, entry) => !data.firstName"
+ *
+ * The compiled function receives a single TFoormFnScope object:
+ *   { v, data, context, entry }
+ */
+function compileFieldFn(fnStr) {
+    const code = `return (${fnStr})(v, data, context, entry)`;
+    return pool.getFn(code);
+}
+/**
+ * Compiles a form-level function string from a @foorm.fn.title,
+ * @foorm.fn.submit.text, or @foorm.fn.submit.disabled annotation.
+ *
+ * The function string should be:
+ *   "(data, ctx) => someExpression"
+ *
+ * The compiled function receives a single TFoormFnScope object:
+ *   { data, context }
+ */
+function compileTopFn(fnStr) {
+    const code = `return (${fnStr})(data, context)`;
+    return pool.getFn(code);
+}
+/**
+ * Compiles a validator function string from a @foorm.validate annotation.
+ *
+ * The function string should be:
+ *   "(v, data, ctx) => boolean | string"
+ *
+ * The compiled function receives a single TFoormFnScope object:
+ *   { v, data, context }
+ */
+function compileValidatorFn(fnStr) {
+    const code = `return (${fnStr})(v, data, context)`;
+    return pool.getFn(code);
+}
+
+function foormValidatorPlugin(foormCtx) {
+    return (ctx, def, value) => {
+        var _a, _b, _c;
+        const validators = (_a = def.metadata) === null || _a === void 0 ? void 0 : _a.get('foorm.validate');
+        if (!validators) {
+            return undefined;
+        }
+        const fns = Array.isArray(validators) ? validators : [validators];
+        const data = (_b = foormCtx === null || foormCtx === void 0 ? void 0 : foormCtx.data) !== null && _b !== void 0 ? _b : {};
+        const context = (_c = foormCtx === null || foormCtx === void 0 ? void 0 : foormCtx.context) !== null && _c !== void 0 ? _c : {};
+        for (const fnStr of fns) {
+            if (typeof fnStr !== 'string') {
+                continue;
+            }
+            const fn = compileValidatorFn(fnStr);
+            const result = fn({ v: value, data, context });
+            if (result !== true) {
+                ctx.error(typeof result === 'string' ? result : 'Validation failed');
+                return false;
+            }
+        }
+        return undefined;
+    };
+}
+
+/** Known foorm primitive extension tags that map directly to field types. */
+const FOORM_TAGS = new Set(['action', 'paragraph', 'select', 'radio', 'checkbox']);
+/** Converts a static @foorm.options annotation value to TFoormEntryOptions[]. */
+function parseStaticOptions(raw) {
+    const items = Array.isArray(raw) ? raw : [raw];
+    return items.map(item => {
+        // Multi-arg annotations are stored as { label, value? }
+        if (typeof item === 'object' && item !== null && 'label' in item) {
+            const { label, value } = item;
+            return value !== undefined ? { key: value, label } : label;
+        }
+        // Plain string fallback (single-arg or raw value)
+        return String(item);
+    });
+}
+/**
+ * Resolves a static annotation or a @foorm.fn.* computed annotation.
+ * If the fn annotation exists, compiles it. Otherwise falls back to the
+ * static annotation or the default value.
+ */
+function resolveComputed(staticKey, fnKey, metadata, compileFn, defaultValue) {
+    const fnStr = metadata.get(fnKey);
+    if (typeof fnStr === 'string') {
+        return compileFn(fnStr);
+    }
+    const staticVal = metadata.get(staticKey);
+    if (staticVal !== undefined) {
+        return staticVal;
+    }
+    return defaultValue;
+}
+/**
+ * Converts an ATScript annotated type into a TFoormModel.
+ *
+ * Reads @foorm.*, @meta.*, and @expect.* annotations from the type's
+ * metadata to build field definitions with static or computed properties.
+ *
+ * @example
+ * ```ts
+ * import { RegistrationForm } from './registration.as'
+ * import { createFoorm } from '@foormjs/atscript'
+ *
+ * const model = createFoorm(RegistrationForm)
+ * const data = createFormData(model.fields)
+ * const validator = getFormValidator(model)
+ * ```
+ */
+function createFoorm(type) {
+    var _a, _b;
+    const metadata = type.metadata;
+    const props = type.type.props;
+    // Form-level metadata
+    const title = resolveComputed('foorm.title', 'foorm.fn.title', metadata, compileTopFn, '');
+    const submitText = resolveComputed('foorm.submit.text', 'foorm.fn.submit.text', metadata, compileTopFn, 'Submit');
+    const submitDisabled = (() => {
+        const fnStr = metadata.get('foorm.fn.submit.disabled');
+        if (typeof fnStr === 'string') {
+            return compileTopFn(fnStr);
+        }
+        return false;
+    })();
+    const submit = { text: submitText, disabled: submitDisabled };
+    // Build fields from props
+    const fields = [];
+    for (const [name, prop] of props.entries()) {
+        const pm = prop.metadata;
+        const tags = (_a = prop.type) === null || _a === void 0 ? void 0 : _a.tags;
+        // Determine field type from @foorm.type, foorm primitive tags, or default
+        const foormType = pm.get('foorm.type');
+        const foormTag = tags ? [...tags].find(t => FOORM_TAGS.has(t)) : undefined;
+        const fieldType = (_b = foormType !== null && foormType !== void 0 ? foormType : foormTag) !== null && _b !== void 0 ? _b : 'text';
+        // Build validators from @foorm.validate
+        const validators = [];
+        const validateAnnotation = pm.get('foorm.validate');
+        if (validateAnnotation) {
+            const fns = Array.isArray(validateAnnotation) ? validateAnnotation : [validateAnnotation];
+            for (const fnStr of fns) {
+                if (typeof fnStr === 'string') {
+                    validators.push(compileValidatorFn(fnStr));
+                }
+            }
+        }
+        const field = {
+            field: name,
+            type: fieldType,
+            component: pm.get('foorm.component'),
+            autocomplete: pm.get('foorm.autocomplete'),
+            altAction: pm.get('foorm.altAction'),
+            order: pm.get('foorm.order'),
+            name: name,
+            label: resolveComputed('meta.label', 'foorm.fn.label', pm, compileFieldFn, name),
+            description: resolveComputed('meta.description', 'foorm.fn.description', pm, compileFieldFn, ''),
+            hint: resolveComputed('meta.hint', 'foorm.fn.hint', pm, compileFieldFn, ''),
+            placeholder: resolveComputed('meta.placeholder', 'foorm.fn.placeholder', pm, compileFieldFn, ''),
+            optional: (() => {
+                var _a;
+                const fnStr = pm.get('foorm.fn.optional');
+                if (typeof fnStr === 'string') {
+                    return compileFieldFn(fnStr);
+                }
+                return (_a = prop.optional) !== null && _a !== void 0 ? _a : false;
+            })(),
+            disabled: (() => {
+                const fnStr = pm.get('foorm.fn.disabled');
+                if (typeof fnStr === 'string') {
+                    return compileFieldFn(fnStr);
+                }
+                return pm.get('foorm.disabled') !== undefined;
+            })(),
+            hidden: (() => {
+                const fnStr = pm.get('foorm.fn.hidden');
+                if (typeof fnStr === 'string') {
+                    return compileFieldFn(fnStr);
+                }
+                return pm.get('foorm.hidden') !== undefined;
+            })(),
+            classes: (() => {
+                const fnStr = pm.get('foorm.fn.classes');
+                if (typeof fnStr === 'string') {
+                    return compileFieldFn(fnStr);
+                }
+                return undefined;
+            })(),
+            styles: (() => {
+                const fnStr = pm.get('foorm.fn.styles');
+                if (typeof fnStr === 'string') {
+                    return compileFieldFn(fnStr);
+                }
+                return undefined;
+            })(),
+            options: (() => {
+                const fnStr = pm.get('foorm.fn.options');
+                if (typeof fnStr === 'string') {
+                    return compileFieldFn(fnStr);
+                }
+                const staticOpts = pm.get('foorm.options');
+                if (staticOpts) {
+                    return parseStaticOptions(staticOpts);
+                }
+                return undefined;
+            })(),
+            value: pm.get('foorm.value'),
+            validators,
+            // ATScript @expect constraints
+            maxLength: pm.get('expect.maxLength'),
+            minLength: pm.get('expect.minLength'),
+            min: pm.get('expect.min'),
+            max: pm.get('expect.max'),
+        };
+        fields.push(field);
+    }
+    // Sort by explicit order, preserving original order for unordered fields
+    fields.sort((a, b) => { var _a, _b; return ((_a = a.order) !== null && _a !== void 0 ? _a : Infinity) - ((_b = b.order) !== null && _b !== void 0 ? _b : Infinity); });
+    return { title, submit, fields };
+}
+
+export { compileFieldFn, compileTopFn, compileValidatorFn, createFoorm, foormValidatorPlugin };

package/dist/plugin.cjs

@@ -0,0 +1,303 @@
+'use strict';
+
+var core = require('@atscript/core');
+
+/**
+ * Attempts to compile a function string with `new Function` and returns
+ * diagnostic errors if it fails. Used by @foorm.fn.* and @foorm.validate
+ * annotation validate hooks.
+ */
+function validateFnString(fnStr, range) {
+    try {
+        // eslint-disable-next-line no-new-func
+        new Function('v', 'data', 'context', 'entry', `return (${fnStr})(v, data, context, entry)`);
+    }
+    catch (error) {
+        return [
+            {
+                severity: 1,
+                message: `Invalid function string: ${error.message}`,
+                range,
+            },
+        ];
+    }
+    return undefined;
+}
+function fnAnnotation(description) {
+    return new core.AnnotationSpec({
+        description,
+        nodeType: ['prop'],
+        argument: {
+            name: 'fn',
+            type: 'string',
+            description: 'JS function string: (value, data, context, entry) => result',
+        },
+        validate(token, args) {
+            if (args[0]) {
+                return validateFnString(args[0].text, args[0].range);
+            }
+            return undefined;
+        },
+    });
+}
+function fnTopAnnotation(description) {
+    return new core.AnnotationSpec({
+        description,
+        nodeType: ['interface'],
+        argument: {
+            name: 'fn',
+            type: 'string',
+            description: 'JS function string: (data, context) => result',
+        },
+        validate(token, args) {
+            if (args[0]) {
+                return validateFnString(args[0].text, args[0].range);
+            }
+            return undefined;
+        },
+    });
+}
+const annotations = {
+    foorm: {
+        // ── Form-level static annotations ────────────────────────
+        title: new core.AnnotationSpec({
+            description: 'Static form title',
+            nodeType: ['interface'],
+            argument: {
+                name: 'title',
+                type: 'string',
+                description: 'The form title text',
+            },
+        }),
+        submit: {
+            text: new core.AnnotationSpec({
+                description: 'Static submit button text',
+                nodeType: ['interface'],
+                argument: {
+                    name: 'text',
+                    type: 'string',
+                    description: 'Submit button label',
+                },
+            }),
+        },
+        // ── Field-level static annotations ───────────────────────
+        type: new core.AnnotationSpec({
+            description: 'Field input type',
+            nodeType: ['prop'],
+            argument: {
+                name: 'type',
+                type: 'string',
+                values: [
+                    'text',
+                    'password',
+                    'number',
+                    'select',
+                    'textarea',
+                    'checkbox',
+                    'radio',
+                    'date',
+                    'paragraph',
+                    'action',
+                ],
+                description: 'The input type for this field',
+            },
+        }),
+        component: new core.AnnotationSpec({
+            description: 'Named component override for rendering this field',
+            nodeType: ['prop'],
+            argument: {
+                name: 'name',
+                type: 'string',
+                description: 'Component name from the components registry',
+            },
+        }),
+        autocomplete: new core.AnnotationSpec({
+            description: 'HTML autocomplete attribute value',
+            nodeType: ['prop'],
+            argument: {
+                name: 'value',
+                type: 'string',
+                description: 'Autocomplete value (e.g., "email", "given-name")',
+            },
+        }),
+        altAction: new core.AnnotationSpec({
+            description: 'Alternate submit action name for this field',
+            nodeType: ['prop'],
+            argument: {
+                name: 'action',
+                type: 'string',
+                description: 'The action name emitted on submit',
+            },
+        }),
+        value: new core.AnnotationSpec({
+            description: 'Default value for this field',
+            nodeType: ['prop'],
+            argument: {
+                name: 'value',
+                type: 'string',
+                description: 'Default value (parsed by field type at runtime)',
+            },
+        }),
+        order: new core.AnnotationSpec({
+            description: 'Explicit rendering order for this field',
+            nodeType: ['prop'],
+            argument: {
+                name: 'order',
+                type: 'number',
+                description: 'Numeric order (lower = earlier)',
+            },
+        }),
+        hidden: new core.AnnotationSpec({
+            description: 'Statically mark this field as hidden',
+            nodeType: ['prop'],
+        }),
+        disabled: new core.AnnotationSpec({
+            description: 'Statically mark this field as disabled',
+            nodeType: ['prop'],
+        }),
+        // ── Options annotation ──────────────────────────────────
+        options: new core.AnnotationSpec({
+            description: 'Static option for select/radio fields. Repeat for each option. Label is the display text, value is the key (defaults to label).',
+            nodeType: ['prop'],
+            multiple: true,
+            mergeStrategy: 'replace',
+            argument: [
+                {
+                    name: 'label',
+                    type: 'string',
+                    description: 'Display label for the option',
+                },
+                {
+                    name: 'value',
+                    type: 'string',
+                    optional: true,
+                    description: 'Value/key for the option (defaults to label if omitted)',
+                },
+            ],
+        }),
+        // ── Validation annotation ────────────────────────────────
+        validate: new core.AnnotationSpec({
+            description: 'Custom JS validator function string. Returns true for pass, or an error message string.',
+            nodeType: ['prop'],
+            multiple: true,
+            mergeStrategy: 'append',
+            argument: {
+                name: 'fn',
+                type: 'string',
+                description: 'JS function string: (value, data, context) => boolean | string',
+            },
+            validate(token, args) {
+                if (args[0]) {
+                    return validateFnString(args[0].text, args[0].range);
+                }
+                return undefined;
+            },
+        }),
+        // ── Computed (fn) annotations ────────────────────────────
+        fn: {
+            // Form-level computed
+            title: fnTopAnnotation('Computed form title: (data, context) => string'),
+            submit: {
+                text: fnTopAnnotation('Computed submit button text: (data, context) => string'),
+                disabled: fnTopAnnotation('Computed submit disabled state: (data, context) => boolean'),
+            },
+            // Field-level computed
+            label: fnAnnotation('Computed label: (value, data, context, entry) => string'),
+            description: fnAnnotation('Computed description: (value, data, context, entry) => string'),
+            hint: fnAnnotation('Computed hint: (value, data, context, entry) => string'),
+            placeholder: fnAnnotation('Computed placeholder: (value, data, context, entry) => string'),
+            disabled: fnAnnotation('Computed disabled state: (value, data, context, entry) => boolean'),
+            hidden: fnAnnotation('Computed hidden state: (value, data, context, entry) => boolean'),
+            optional: fnAnnotation('Computed optional state: (value, data, context, entry) => boolean'),
+            classes: fnAnnotation('Computed CSS classes: (value, data, context, entry) => string | Record<string, boolean>'),
+            styles: fnAnnotation('Computed inline styles: (value, data, context, entry) => string | Record<string, string>'),
+            options: fnAnnotation('Computed select/radio options: (value, data, context, entry) => Array'),
+        },
+    },
+};
+
+const primitives = {
+    foorm: {
+        type: 'phantom',
+        isContainer: true,
+        documentation: 'Non-data UI elements for form rendering',
+        extensions: {
+            action: {
+                documentation: 'Form action button — not a data field, excluded from form data. Use with @foorm.altAction to define alternate submit actions.',
+            },
+            paragraph: {
+                documentation: 'Read-only paragraph text — rendered as static content, not an input field. Use @meta.label for the paragraph text.',
+            },
+            select: {
+                type: 'string',
+                documentation: 'Dropdown select field. Use @foorm.options to define static choices or @foorm.fn.options for computed choices.',
+            },
+            radio: {
+                type: 'string',
+                documentation: 'Radio button group. Use @foorm.options to define static choices or @foorm.fn.options for computed choices.',
+            },
+            checkbox: {
+                type: 'boolean',
+                documentation: 'Single boolean checkbox toggle.',
+            },
+        },
+    },
+};
+
+const BUILTIN_TYPES = [
+    'text',
+    'password',
+    'number',
+    'select',
+    'textarea',
+    'checkbox',
+    'radio',
+    'date',
+    'paragraph',
+    'action',
+];
+function foormPlugin(opts) {
+    return {
+        name: 'foorm',
+        config() {
+            var _a, _b, _c, _d;
+            if (!((_a = opts === null || opts === void 0 ? void 0 : opts.extraTypes) === null || _a === void 0 ? void 0 : _a.length) && !((_b = opts === null || opts === void 0 ? void 0 : opts.components) === null || _b === void 0 ? void 0 : _b.length)) {
+                return { primitives, annotations };
+            }
+            const foormNs = annotations.foorm;
+            const overrides = {};
+            if ((_c = opts.extraTypes) === null || _c === void 0 ? void 0 : _c.length) {
+                overrides.type = new core.AnnotationSpec({
+                    description: 'Field input type',
+                    nodeType: ['prop'],
+                    argument: {
+                        name: 'type',
+                        type: 'string',
+                        values: [...BUILTIN_TYPES, ...opts.extraTypes],
+                        description: 'The input type for this field',
+                    },
+                });
+            }
+            if ((_d = opts.components) === null || _d === void 0 ? void 0 : _d.length) {
+                overrides.component = new core.AnnotationSpec({
+                    description: 'Named component override for rendering this field',
+                    nodeType: ['prop'],
+                    argument: {
+                        name: 'name',
+                        type: 'string',
+                        values: opts.components,
+                        description: 'Component name from the components registry',
+                    },
+                });
+            }
+            return {
+                primitives,
+                annotations: Object.assign(Object.assign({}, annotations), { foorm: Object.assign(Object.assign({}, foormNs), overrides) }),
+            };
+        },
+    };
+}
+
+exports.annotations = annotations;
+exports.foormPlugin = foormPlugin;
+exports.primitives = primitives;

package/dist/plugin.d.ts

@@ -0,0 +1,23 @@
+import { TAnnotationsTree, TAtscriptConfig, TAtscriptPlugin } from '@atscript/core';
+
+declare const annotations: TAnnotationsTree;
+
+declare const primitives: TAtscriptConfig['primitives'];
+
+interface TFoormPluginOptions {
+    /**
+     * Additional field type values to allow in @foorm.type annotation.
+     * Built-in values: text, password, number, select, textarea, checkbox, radio, date, paragraph, action
+     */
+    extraTypes?: string[];
+    /**
+     * List of custom component names available in the project.
+     * Enables IDE autocomplete and validation for @foorm.component annotation.
+     * When omitted, @foorm.component accepts any string.
+     */
+    components?: string[];
+}
+declare function foormPlugin(opts?: TFoormPluginOptions): TAtscriptPlugin;
+
+export { annotations, foormPlugin, primitives };
+export type { TFoormPluginOptions };