@frigear-nu/forms 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @frigear-nu/forms
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Dynamic, database-stored forms for the frigear ecosystem. A form is a JSON definition (single page or stepped,
+with conditional fields), submissions are stored with a snapshot of the definition they were answered against, and
+delivery (email, webhooks, ...) hangs off the `forms:submitted` Nitro hook.
+
+Full documentation: `apps/docs/content/4.modules/26.forms.md`.
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@frigear-nu/forms'],
+  forms: {
+    settings: { pages: { form: true, admin: true, adminForm: true, adminSubmissions: true, adminSubmission: true } },
+  },
+})
+```
+
+```ts
+// server/plugins/forms-policy.ts - who may manage forms (denied by default)
+export default defineNitroPlugin((nitro) => {
+  nitro.hooks.hook('forms:authorize', (ctx) => { ctx.allowed = isStaff(ctx.userId) })
+})
+```

package/dist/module.d.mts

@@ -0,0 +1,281 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { H3Event } from 'h3';
+
+/** A text that is either one string or a map of locale -> string. */
+type Translated = string | Record<string, string>;
+type FormStatus = 'draft' | 'published' | 'archived';
+type FormMode = 'single' | 'stepped';
+type FormStorage = 'db' | 'none';
+type DeliveryStatus = 'none' | 'pending' | 'delivered' | 'failed';
+type FieldType = 'text' | 'email' | 'tel' | 'number' | 'textarea' | 'select' | 'radio' | 'checkbox' | 'date' | 'file' | 'markdown';
+type ConditionOp = 'eq' | 'neq' | 'in' | 'truthy';
+/** Shows a field (or step) only while the condition on another field's answer holds. */
+type Condition = {
+    /** Key of the field whose answer is inspected. */
+    field: string;
+    op: ConditionOp;
+    /** Compared value for `eq`/`neq`; a list of accepted values for `in`. Unused for `truthy`. */
+    value?: unknown;
+};
+type FieldOption = {
+    value: string;
+    label: Translated;
+};
+type FieldValidation = {
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    /** Regular expression source the (non-empty) value must match. */
+    pattern?: string;
+    /** Files only. */
+    maxFiles?: number;
+    /** Files only, bytes per file. */
+    maxSize?: number;
+    /** Files only, accepted MIME types or `type/*` wildcards. */
+    accept?: string[];
+    /** Replaces the default error message of every rule on this field. */
+    message?: Translated;
+};
+type FormField = {
+    /** Unique across the whole form; the key of the answer. */
+    key: string;
+    type: FieldType;
+    /** Markdown text for `markdown` fields (they collect no answer). */
+    content?: Translated;
+    label?: Translated;
+    description?: Translated;
+    placeholder?: Translated;
+    required?: boolean;
+    options?: FieldOption[];
+    /** `file` fields only: allow more than one file. */
+    multiple?: boolean;
+    /** Browser `autocomplete` token, e.g. `email`. */
+    autocomplete?: string;
+    validation?: FieldValidation;
+    showIf?: Condition;
+};
+type FormStep = {
+    /** Unique across the form. */
+    id: string;
+    title?: Translated;
+    description?: Translated;
+    showIf?: Condition;
+    fields: FormField[];
+};
+type FormDelivery = {
+    email?: {
+        /** Recipient addresses. */
+        to: string[];
+        subject?: Translated;
+    };
+};
+type FormSubmitSettings = {
+    label?: Translated;
+    successMessage?: Translated;
+    /** Same-origin path to go to after a successful submit. */
+    redirect?: string;
+    /** Offers "send another" after submit; these field keys stay filled in. */
+    allowResubmit?: {
+        keep: string[];
+    };
+};
+type FormDefinition = {
+    mode: FormMode;
+    /** `none` never stores answers (or files): they are only emitted through `forms:submitted` and emailed. */
+    storage: FormStorage;
+    steps: FormStep[];
+    submit?: FormSubmitSettings;
+    delivery?: FormDelivery;
+};
+type ModuleOptions = {
+    settings?: {
+        pages?: {
+            /** Public form page; must contain a `:slug` param. `true` = `/forms/:slug`. */
+            form?: string | boolean;
+            /** Admin list of forms. `true` = `/admin/forms`. */
+            admin?: string | boolean;
+            /** Admin form editor; must contain an `:id` param. `true` = `/admin/forms/:id`. */
+            adminForm?: string | boolean;
+            /** Admin submissions of one form; must contain an `:id` param. `true` = `/admin/forms/:id/submissions`. */
+            adminSubmissions?: string | boolean;
+            /** One submission; must contain `:id` and `:submissionId`. `true` = `/admin/forms/:id/submissions/:submissionId`. */
+            adminSubmission?: string | boolean;
+        };
+        /** Submissions allowed per client and form within `rateLimitWindowSeconds`. Defaults to `10`. `0` disables. */
+        rateLimit?: number;
+        /** Defaults to `600`. */
+        rateLimitWindowSeconds?: number;
+    };
+    /**
+     * Opt-in seeding. Nothing is ever inserted unless `enabled` is `true`; then only slugs that
+     * do not exist yet are inserted (existing forms are never overwritten).
+     */
+    seed?: {
+        enabled?: boolean;
+        forms?: SeedForm[];
+    };
+};
+type SeedForm = {
+    slug: string;
+    name: string;
+    status?: FormStatus;
+    definition: FormDefinition;
+};
+type FormsRuntimeConfig = {
+    rateLimit: number;
+    rateLimitWindowSeconds: number;
+    seed: {
+        enabled: boolean;
+        forms: SeedForm[];
+    };
+};
+type PublicModuleOptions = {
+    pages: {
+        form?: string;
+        admin?: string;
+        adminForm?: string;
+        adminSubmissions?: string;
+        adminSubmission?: string;
+    };
+};
+type AuthorizeContext = {
+    event: H3Event;
+    userId: number;
+    allowed: boolean;
+};
+type SubmittedFile = {
+    fieldKey: string;
+    filename: string;
+    contentType: string;
+    size: number;
+    /** Blob pathname; `null` when the form does not store (`storage: 'none'` never has files). */
+    pathname: string | null;
+};
+type SubmittedContext = {
+    event: H3Event;
+    form: {
+        id: string;
+        slug: string;
+        name: string;
+        version: number;
+        definition: FormDefinition;
+    };
+    /** Validated answers keyed by field key. File fields hold the file names. */
+    answers: Record<string, unknown>;
+    files: SubmittedFile[];
+    locale: string;
+    userId: number | null;
+    /** `null` when the form has `storage: 'none'`. */
+    submissionId: string | null;
+    stored: boolean;
+    /** Set by a handler to report that it delivered the submission (email delivery does). */
+    delivered: boolean;
+};
+type DeliveredContext = {
+    submissionId: string | null;
+    formSlug: string;
+    status: 'delivered' | 'failed';
+    error?: string;
+};
+type PublicFormDto = {
+    id: string;
+    slug: string;
+    name: string;
+    version: number;
+    /** The definition without `delivery` (recipients are never public). */
+    definition: Omit<FormDefinition, 'delivery'>;
+};
+type FormSummaryDto = {
+    id: string;
+    slug: string;
+    name: string;
+    status: FormStatus;
+    version: number;
+    storage: FormStorage;
+    mode: FormMode;
+    submissionCount: number;
+    updatedAt: string;
+};
+type FormAdminDto = {
+    id: string;
+    slug: string;
+    name: string;
+    status: FormStatus;
+    version: number;
+    definition: FormDefinition;
+    createdAt: string;
+    updatedAt: string;
+};
+type SubmissionSummaryDto = {
+    id: string;
+    createdAt: string;
+    locale: string;
+    userId: number | null;
+    deliveryStatus: DeliveryStatus;
+    /** First few answers as `label: value`, for the list view. */
+    preview: {
+        label: string;
+        value: string;
+    }[];
+};
+type SubmissionFileDto = {
+    id: string;
+    fieldKey: string;
+    filename: string;
+    contentType: string;
+    size: number;
+};
+type SubmissionDto = {
+    id: string;
+    formId: string;
+    formSlug: string;
+    formVersion: number;
+    definition: FormDefinition;
+    answers: Record<string, unknown>;
+    files: SubmissionFileDto[];
+    locale: string;
+    userId: number | null;
+    deliveryStatus: DeliveryStatus;
+    deliveryError: string | null;
+    createdAt: string;
+};
+type SubmitResponse = {
+    ok: true;
+    id: string | null;
+};
+/** Descriptor of a picked/uploaded file, as validated on both client and server. */
+type FileDescriptor = {
+    name: string;
+    size: number;
+    type: string;
+};
+
+declare module '@nuxt/schema' {
+    interface NuxtConfig {
+        forms?: ModuleOptions;
+    }
+    interface RuntimeConfig {
+        forms: FormsRuntimeConfig;
+    }
+    interface PublicRuntimeConfig {
+        forms: PublicModuleOptions;
+    }
+}
+declare module 'nitropack' {
+    interface NitroRuntimeHooks {
+        /** Staff gate (definitions, submissions, files): set `ctx.allowed = true` to let the user in. Denied by default. */
+        'forms:authorize': (ctx: AuthorizeContext) => void | Promise<void>;
+        /**
+         * A valid submission was received (and stored, unless the form has `storage: 'none'`). Deliver it
+         * here (webhooks, CRM, ...); set `ctx.delivered = true` once done. Throwing marks delivery failed.
+         */
+        'forms:submitted': (ctx: SubmittedContext) => void | Promise<void>;
+        /** Delivery of a submission finished (successfully or not). */
+        'forms:delivered': (ctx: DeliveredContext) => void | Promise<void>;
+    }
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { AuthorizeContext, Condition, ConditionOp, DeliveredContext, DeliveryStatus, FieldOption, FieldType, FieldValidation, FileDescriptor, FormAdminDto, FormDefinition, FormDelivery, FormField, FormMode, FormStatus, FormStep, FormStorage, FormSubmitSettings, FormSummaryDto, FormsRuntimeConfig, ModuleOptions, PublicFormDto, PublicModuleOptions, SeedForm, SubmissionDto, SubmissionFileDto, SubmissionSummaryDto, SubmitResponse, SubmittedContext, SubmittedFile, Translated };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@frigear-nu/forms",
+  "configKey": "forms",
+  "version": "0.0.2",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,102 @@
+import { defineNuxtModule, createResolver, hasNuxtModule, addServerImportsDir, addServerPlugin, addImports, addComponentsDir, extendPages, addServerHandler } from '@nuxt/kit';
+import { registerModule, registerLocales, registerDatabaseTable, defineModulePage } from '@frigear-nu/module-kit/utils';
+
+const MODULE_NAME = "@frigear-nu/forms";
+function resolvePagePath(setting, defaultPath) {
+  if (typeof setting === "string") return setting;
+  if (setting === true) return defaultPath;
+  return void 0;
+}
+const module$1 = defineNuxtModule({
+  meta: { name: MODULE_NAME, configKey: "forms" },
+  defaults: {
+    settings: { pages: {}, rateLimit: 10, rateLimitWindowSeconds: 600 },
+    seed: { enabled: false, forms: [] }
+  },
+  moduleDependencies: {
+    "@nuxthub/core": {
+      version: ">=0.10",
+      defaults: { kv: true, blob: true }
+    },
+    "@frigear-nu/module-kit": { version: ">=0.0.1" },
+    "@frigear-nu/users": { version: ">=0.0.1" },
+    "@frigear-nu/notify": { version: ">=0.0.1" },
+    "@frigear-nu/menu": { version: ">=0.0.1", optional: true }
+  },
+  async setup(options, nuxt) {
+    registerModule(MODULE_NAME, nuxt);
+    const resolver = createResolver(import.meta.url);
+    registerLocales(nuxt, resolver.resolve("./runtime/i18n/lang"));
+    const settings = options.settings ?? {};
+    const withMenus = hasNuxtModule("@frigear-nu/menu");
+    const formPath = resolvePagePath(settings.pages?.form, "/forms/:slug");
+    const adminPath = resolvePagePath(settings.pages?.admin, "/admin/forms");
+    const adminFormPath = resolvePagePath(settings.pages?.adminForm, "/admin/forms/:id");
+    const adminSubmissionsPath = resolvePagePath(settings.pages?.adminSubmissions, "/admin/forms/:id/submissions");
+    const adminSubmissionPath = resolvePagePath(settings.pages?.adminSubmission, "/admin/forms/:id/submissions/:submissionId");
+    nuxt.options.runtimeConfig.forms = {
+      rateLimit: settings.rateLimit ?? 10,
+      rateLimitWindowSeconds: settings.rateLimitWindowSeconds ?? 600,
+      seed: { enabled: options.seed?.enabled ?? false, forms: options.seed?.forms ?? [] }
+    };
+    nuxt.options.runtimeConfig.public.forms = {
+      pages: {
+        form: formPath,
+        admin: adminPath,
+        adminForm: adminFormPath,
+        adminSubmissions: adminSubmissionsPath,
+        adminSubmission: adminSubmissionPath
+      }
+    };
+    await registerDatabaseTable(nuxt, {
+      resolver,
+      schema: (dialect) => `./runtime/server/db/schema.${dialect}`
+    });
+    const route = (method, path, file) => addServerHandler({ route: `/api/forms${path}`, method, handler: resolver.resolve(`./runtime/server/routes/${file}`) });
+    route("get", "/admin/forms", "admin/forms.get");
+    route("post", "/admin/forms", "admin/forms.post");
+    route("get", "/admin/forms/:id", "admin/form.get");
+    route("patch", "/admin/forms/:id", "admin/form.patch");
+    route("delete", "/admin/forms/:id", "admin/form.delete");
+    route("get", "/admin/forms/:id/submissions", "admin/submissions.get");
+    route("post", "/admin/import", "admin/import.post");
+    route("get", "/admin/submissions/:id", "admin/submission.get");
+    route("get", "/admin/submissions/:id/files/:fileId", "admin/submission-file.get");
+    route("post", "/admin/submissions/:id/redeliver", "admin/submission-redeliver.post");
+    route("get", "/:slug", "public/form.get");
+    route("post", "/:slug/submit", "public/submit.post");
+    addServerImportsDir(resolver.resolve("./runtime/server/utils"));
+    addServerPlugin(resolver.resolve("./runtime/server/plugins/email-delivery"));
+    addServerPlugin(resolver.resolve("./runtime/server/plugins/seed"));
+    addImports([
+      { name: "useForm", from: resolver.resolve("./runtime/app/composables/useForms") },
+      { name: "useFormsLocale", from: resolver.resolve("./runtime/app/composables/useForms") },
+      { name: "useFormsPaths", from: resolver.resolve("./runtime/app/composables/useForms") },
+      { name: "useFormStepper", from: resolver.resolve("./runtime/app/composables/useFormStepper") }
+    ]);
+    addComponentsDir({ path: resolver.resolve("./runtime/app/components") });
+    const pages = [
+      { name: "forms-form", path: formPath, file: "form.vue" },
+      { name: "forms-admin", path: adminPath, file: "admin.vue" },
+      { name: "forms-admin-form", path: adminFormPath, file: "admin-form.vue" },
+      { name: "forms-admin-submissions", path: adminSubmissionsPath, file: "admin-submissions.vue" },
+      { name: "forms-admin-submission", path: adminSubmissionPath, file: "admin-submission.vue" }
+    ];
+    if (pages.some((page) => page.path)) {
+      extendPages((existing) => {
+        const taken = new Set(existing.map((page) => page.path));
+        for (const page of pages) {
+          if (page.path && !taken.has(page.path)) {
+            existing.push(defineModulePage(MODULE_NAME, { name: page.name, path: page.path, file: resolver.resolve(`./runtime/app/pages/${page.file}`) }));
+          }
+        }
+      });
+    }
+    if (withMenus) {
+      const { registerMenuSource } = await import('@frigear-nu/menu/utils');
+      registerMenuSource(nuxt, { file: resolver.resolve("./runtime/menus"), menu: "dashboard.account" });
+    }
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/app/components/FormField.d.vue.ts

@@ -0,0 +1,16 @@
+import type { FormField } from '../../../types.js';
+type __VLS_Props = {
+    field: FormField;
+    locale: string;
+};
+type __VLS_ModelProps = {
+    modelValue?: unknown;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:modelValue": (value: unknown) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: ((value: unknown) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/app/components/FormField.vue

@@ -0,0 +1,80 @@
+<script setup>
+import { renderMarkdown, translate } from "../../utils";
+const props = defineProps({
+  field: { type: Object, required: true },
+  locale: { type: String, required: true }
+});
+const model = defineModel({ type: null });
+const text = (value) => translate(value, props.locale) || void 0;
+const items = computed(() => (props.field.options ?? []).map((option) => ({
+  value: option.value,
+  label: translate(option.label, props.locale) || option.value
+})));
+const html = computed(() => renderMarkdown(translate(props.field.content, props.locale)));
+const isCheckbox = computed(() => props.field.type === "checkbox");
+</script>
+
+<template>
+  <!-- eslint-disable vue/no-v-html -- renderMarkdown escapes all input -->
+  <div
+    v-if="field.type === 'markdown'"
+    class="prose prose-sm max-w-none text-muted"
+    v-html="html"
+  />
+  <!-- eslint-enable vue/no-v-html -->
+
+  <UFormField
+    v-else
+    :name="field.key"
+    :label="isCheckbox ? void 0 : text(field.label)"
+    :description="isCheckbox ? void 0 : text(field.description)"
+    :required="field.required"
+  >
+    <UTextarea
+      v-if="field.type === 'textarea'"
+      v-model="model"
+      :placeholder="text(field.placeholder)"
+      :rows="5"
+      class="w-full"
+    />
+    <USelect
+      v-else-if="field.type === 'select'"
+      v-model="model"
+      :items="items"
+      :placeholder="text(field.placeholder)"
+      class="w-full"
+    />
+    <URadioGroup
+      v-else-if="field.type === 'radio'"
+      v-model="model"
+      :items="items"
+    />
+    <UCheckbox
+      v-else-if="field.type === 'checkbox'"
+      v-model="model"
+      :label="text(field.label)"
+      :description="text(field.description)"
+    />
+    <UInputNumber
+      v-else-if="field.type === 'number'"
+      v-model="model"
+      :placeholder="text(field.placeholder)"
+      class="w-full"
+    />
+    <UFileUpload
+      v-else-if="field.type === 'file'"
+      v-model="model"
+      :multiple="field.multiple"
+      :accept="field.validation?.accept?.join(',')"
+      class="w-full"
+    />
+    <UInput
+      v-else
+      v-model="model"
+      :type="field.type === 'date' ? 'date' : field.type === 'tel' ? 'tel' : field.type === 'email' ? 'email' : 'text'"
+      :autocomplete="field.autocomplete"
+      :placeholder="text(field.placeholder)"
+      class="w-full"
+    />
+  </UFormField>
+</template>

package/dist/runtime/app/components/FormField.vue.d.ts

@@ -0,0 +1,16 @@
+import type { FormField } from '../../../types.js';
+type __VLS_Props = {
+    field: FormField;
+    locale: string;
+};
+type __VLS_ModelProps = {
+    modelValue?: unknown;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:modelValue": (value: unknown) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:modelValue"?: ((value: unknown) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/app/components/FormRenderer.d.vue.ts

@@ -0,0 +1,19 @@
+import type { FormDefinition, PublicFormDto } from '../../../types.js';
+type FormShape = Pick<PublicFormDto, 'slug' | 'definition'> & {
+    definition: Omit<FormDefinition, 'delivery'>;
+};
+type __VLS_Props = {
+    /** Slug of a published form (loaded from the API). */
+    slug?: string;
+    /** A definition to render directly (admin preview, tests). */
+    form?: FormShape;
+    /** Validates and steps like normal, but never posts. */
+    preview?: boolean;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    submitted: (id: string | null) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onSubmitted?: ((id: string | null) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;