@stacksjs/forms 0.71.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2023 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,27 @@
+# @stacksjs/forms
+
+Native form definitions, conditional fields, validation, submissions, and
+notification helpers for Stacks applications.
+
+## Configuration
+
+Forms are an optional framework feature. Enable the bundle with:
+
+```bash
+./buddy forms:install
+```
+
+This enables `config/forms.ts` and the model-generated migrations for forms,
+fields, and submissions. Disable it with `./buddy forms:uninstall`.
+
+## Runtime API
+
+The package exposes typed helpers for:
+
+- defining and validating form schemas
+- evaluating conditional field visibility
+- normalizing and storing submissions
+- delivering submission notifications
+
+Application-specific form models and actions remain under `app/`. Reusable
+form behavior belongs in this package.

package/dist/conditions.d.ts

@@ -0,0 +1,12 @@
+import type { FieldConditions, FormFieldDefinition } from './types';
+/**
+ * Evaluate one field's visibility rules against the submitted values.
+ * No conditions = visible. The same function runs client-side for UX and
+ * server-side for correctness - the SERVER evaluation is the one that
+ * counts: a hidden required field is not required, and values submitted
+ * for hidden fields are discarded, so a tampered client can neither skip
+ * a required visible field nor smuggle values through a hidden one.
+ */
+export declare function evaluateConditions(conditions: FieldConditions | null | undefined, values: Record<string, unknown>): boolean;
+/** The fields visible for a given value set, in position order. */
+export declare function visibleFields(fields: FormFieldDefinition[], values: Record<string, unknown>): FormFieldDefinition[];

package/dist/definition.d.ts

@@ -0,0 +1,14 @@
+import type { FormDefinition } from './types';
+/**
+ * Load a form + its fields by uuid. `siteId` is REQUIRED and matched against
+ * the row (null site allowed for single-site apps passing null): a form uuid
+ * from one school must not render or accept submissions on another school's
+ * host.
+ */
+export declare function loadFormByUuid(uuid: string, siteId: number | null): Promise<FormDefinition | null>;
+/**
+ * The client-facing definition: everything a renderer needs, nothing an
+ * attacker wants (notify addresses, payment internals beyond what the UI
+ * must show).
+ */
+export declare function publicDefinition(form: FormDefinition): Record<string, unknown>;

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export type { SubmissionListRow, SubmitOptions, SubmitResult } from './submissions';
+export type {
+  FieldChoice,
+  FieldConditions,
+  FieldOptions,
+  FormDefinition,
+  FormFieldDefinition,
+  FormFieldType,
+  FormSettings,
+  SubmissionErrors,
+  ValidateSubmissionResult,
+} from './types';
+export { evaluateConditions, visibleFields } from './conditions';
+export { loadFormByUuid, publicDefinition } from './definition';
+export { dispatchSubmissionNotifications } from './notifications';
+export {
+  completeSubmissionPayment,
+  exportSubmissionsCsv,
+  fetchSubmissions,
+  submitForm,
+} from './submissions';
+export { computeAmountCents, validateSubmission } from './validate';

package/dist/index.js

@@ -0,0 +1,2 @@
+// @bun
+export{t as visibleFields,a as validateSubmission,f as submitForm,n as publicDefinition,m as loadFormByUuid,d as fetchSubmissions,b as exportSubmissionsCsv,s as evaluateConditions,u as dispatchSubmissionNotifications,S as computeAmountCents,l as completeSubmissionPayment};

package/dist/notifications.d.ts

@@ -0,0 +1,9 @@
+import type { FormDefinition } from './types';
+import type { SubmitResult } from './submissions';
+/**
+ * Post-submission notifications: staff notice to `settings.notifyEmails`,
+ * confirmation to the submitter when the form captured an email. Called by
+ * the route AFTER the write succeeds; every failure is logged, none block
+ * or undo the submission - the person's answers are already safe.
+ */
+export declare function dispatchSubmissionNotifications(form: FormDefinition, result: Extract<SubmitResult, { ok: true }>, submission: { email: string | null, name: string | null, values: Record<string, unknown> }): Promise<void>;

package/dist/submissions.d.ts

@@ -0,0 +1,33 @@
+import type { FormDefinition, SubmissionErrors } from './types';
+/**
+ * Accept a public submission. The caller (route/action) has already resolved
+ * the form for the request's site via `loadFormByUuid` - this validates,
+ * spam-guards, stores, and reports what should happen next (payment or
+ * confirmation). Notifications are the caller's follow-up so transports
+ * never block the write.
+ */
+export declare function submitForm(form: FormDefinition, payload: Record<string, unknown>, options?: SubmitOptions): Promise<SubmitResult>;
+/** Flip a paid submission to complete. Called from the payment webhook. */
+export declare function completeSubmissionPayment(submissionUuid: string, paymentIntentId: string): Promise<boolean>;
+/** Admin list, newest first. `formId` scoping is the caller's job to have authorized. */
+export declare function fetchSubmissions(formId: number, options?: { limit?: number, offset?: number }): Promise<SubmissionListRow[]>;
+/** The full submission set as CSV: field columns in position order + the typed columns. */
+export declare function exportSubmissionsCsv(form: FormDefinition): Promise<string>;
+export declare interface SubmitOptions {
+  ip?: string
+  renderedAtMs?: number
+  honeypot?: string
+}
+export declare interface SubmissionListRow {
+  id: number
+  uuid: string
+  values: Record<string, unknown>
+  email: string | null
+  name: string | null
+  status: string
+  amountCents: number | null
+  submittedAt: string | null
+}
+export type SubmitResult = | { ok: true, submissionId: number, submissionUuid: string, status: 'complete' | 'pending_payment', amountCents: number | null, confirmation: string | null, redirect: string | null }
+    | { ok: false, status: 422, errors: SubmissionErrors }
+    | { ok: false, status: 404 | 409 | 429, message: string }

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+export declare interface FieldChoice {
+  label: string
+  value: string
+}
+export declare interface FieldOptions {
+  placeholder?: string
+  choices?: FieldChoice[]
+  min?: number
+  max?: number
+  accept?: string[]
+  maxSizeMb?: number
+  amountCents?: number
+}
+export declare interface FieldConditions {
+  action: 'show' | 'hide'
+  logic: 'all' | 'any'
+  rules: {
+    field: string
+    op: 'eq' | 'neq' | 'contains' | 'gt' | 'lt' | 'empty' | 'not_empty'
+    value?: string | number
+  }[]
+}
+/** The runtime shape of a form field, parsed from its row. */
+export declare interface FormFieldDefinition {
+  name: string
+  label: string
+  type: FormFieldType
+  required: boolean
+  position: number
+  width: 'full' | 'half'
+  options: FieldOptions
+  conditions: FieldConditions | null
+}
+export declare interface FormSettings {
+  submitLabel?: string
+  confirmation?: { type: 'message' | 'redirect', value: string }
+  notifyEmails?: string[]
+  emailField?: string
+  nameField?: string
+  payment?: {
+    mode: 'fixed' | 'user_amount' | 'field_sum'
+    amountCents?: number
+    currency?: string
+    amountField?: string
+    minAmountCents?: number
+  }
+}
+export declare interface FormDefinition {
+  id: number
+  uuid: string
+  siteId: number | null
+  name: string
+  handle: string
+  status: 'draft' | 'active' | 'closed'
+  settings: FormSettings
+  fields: FormFieldDefinition[]
+}
+export declare interface SubmissionErrors {
+  [fieldName: string]: string
+}
+export type FormFieldType = | 'text' | 'textarea' | 'email' | 'phone' | 'select' | 'checkbox'
+    | 'radio' | 'date' | 'file' | 'currency' | 'section_break';
+export type ValidateSubmissionResult = | { ok: true, values: Record<string, unknown>, email: string | null, name: string | null, amountCents: number | null }
+    | { ok: false, errors: SubmissionErrors }

package/dist/validate.d.ts

@@ -0,0 +1,17 @@
+import type { FormDefinition, FormFieldDefinition, ValidateSubmissionResult } from './types';
+/**
+ * Server-computed payment amount. NEVER trusts a client total:
+ * `fixed` reads the form's setting, `field_sum` adds the currency fields'
+ * validated values, `user_amount` takes the named field but enforces the
+ * configured floor.
+ */
+export declare function computeAmountCents(form: FormDefinition, fields: FormFieldDefinition[], values: Record<string, unknown>): number | null;
+/**
+ * Validate an untrusted submission against a form definition.
+ *
+ * Visibility first: required-ness and value acceptance apply only to fields
+ * visible under the submitted values, and values for hidden or unknown
+ * fields are DISCARDED - the stored document contains exactly what the
+ * person could see.
+ */
+export declare function validateSubmission(form: FormDefinition, payload: Record<string, unknown>): ValidateSubmissionResult;

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@stacksjs/forms",
+  "type": "module",
+  "version": "0.71.1",
+  "description": "The Stacks form-builder functionality.",
+  "author": "Chris Breuer",
+  "contributors": [
+    "Chris Breuer <chris@stacksjs.com>"
+  ],
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/chrisbbreuer",
+  "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/core/forms#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/stacks.git",
+    "directory": "./storage/framework/core/forms"
+  },
+  "bugs": {
+    "url": "https://github.com/stacksjs/stacks/issues"
+  },
+  "keywords": [
+    "forms",
+    "form-builder",
+    "submissions",
+    "stacks"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./dist/index.js",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "bun": "./dist/*.js",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    },
+    "./*.js": {
+      "types": "./dist/*.d.ts",
+      "bun": "./dist/*.js",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    }
+  },
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build.ts",
+    "typecheck": "bun tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@stacksjs/config": "0.71.1",
+    "@stacksjs/database": "0.71.1",
+    "@stacksjs/notifications": "0.71.1",
+    "@stacksjs/storage": "0.71.1",
+    "@stacksjs/validation": "0.71.1",
+    "better-dx": "^0.2.23"
+  },
+  "sideEffects": false
+}