feat(forms): add PHP enums for form builder

9 backed string enums covering purpose, field type, submission status/mode/review,
field width, value storage hint, snapshot mode, webhook delivery status.
FormPurpose/FormFieldType include helper methods per ARCH §3/§5. All with
declare(strict_types=1) and values() helpers for validation rules.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

api/app/Enums/FormBuilder/FormFieldDisplayWidth.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\FormBuilder;
+
+enum FormFieldDisplayWidth: string
+{
+    case HALF = 'half';
+    case FULL = 'full';
+
+    /**
+     * @return array<int, string>
+     */
+    public static function values(): array
+    {
+        return array_map(fn (self $case): string => $case->value, self::cases());
+    }
+}

api/app/Enums/FormBuilder/FormFieldType.php

@@ -0,0 +1,98 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\FormBuilder;
+
+/**
+ * Built-in form field types per ARCH §5.1.
+ *
+ * Note: `form_fields.field_type` is stored as string (not DB enum) to allow
+ * runtime-registered custom types via CustomFieldTypeRegistry (§17.2).
+ */
+enum FormFieldType: string
+{
+    case TEXT = 'TEXT';
+    case TEXTAREA = 'TEXTAREA';
+    case EMAIL = 'EMAIL';
+    case PHONE = 'PHONE';
+    case NUMBER = 'NUMBER';
+    case DATE = 'DATE';
+    case DATETIME = 'DATETIME';
+    case BOOLEAN = 'BOOLEAN';
+    case RADIO = 'RADIO';
+    case SELECT = 'SELECT';
+    case MULTISELECT = 'MULTISELECT';
+    case CHECKBOX_LIST = 'CHECKBOX_LIST';
+    case FILE_UPLOAD = 'FILE_UPLOAD';
+    case IMAGE_UPLOAD = 'IMAGE_UPLOAD';
+    case SIGNATURE = 'SIGNATURE';
+    case TAG_PICKER = 'TAG_PICKER';
+    case HEADING = 'HEADING';
+    case PARAGRAPH = 'PARAGRAPH';
+    case URL = 'URL';
+    case SECTION_PRIORITY = 'SECTION_PRIORITY';
+    case AVAILABILITY_PICKER = 'AVAILABILITY_PICKER';
+    case TABLE_ROWS = 'TABLE_ROWS';
+
+    /**
+     * @return array<int, string>
+     */
+    public static function values(): array
+    {
+        return array_map(fn (self $case): string => $case->value, self::cases());
+    }
+
+    /**
+     * Recommended storage hint per ARCH §5.2. Suggestive, organiser may override.
+     */
+    public function recommendedValueStorageHint(): FormValueStorageHint
+    {
+        return match ($this) {
+            self::TEXT,
+            self::TEXTAREA,
+            self::EMAIL,
+            self::PHONE,
+            self::URL,
+            self::RADIO,
+            self::SELECT => FormValueStorageHint::STRING,
+
+            self::NUMBER => FormValueStorageHint::NUMBER,
+            self::DATE,
+            self::DATETIME => FormValueStorageHint::DATE,
+            self::BOOLEAN => FormValueStorageHint::BOOL,
+
+            default => FormValueStorageHint::JSON,
+        };
+    }
+
+    /**
+     * Per ARCH §7.1. Presentational types and complex payloads are not filterable.
+     */
+    public function isFilterable(): bool
+    {
+        return match ($this) {
+            self::TEXTAREA,
+            self::FILE_UPLOAD,
+            self::IMAGE_UPLOAD,
+            self::SIGNATURE,
+            self::HEADING,
+            self::PARAGRAPH,
+            self::TABLE_ROWS,
+            self::SECTION_PRIORITY,
+            self::AVAILABILITY_PICKER => false,
+            default => true,
+        };
+    }
+
+    /**
+     * HEADING and PARAGRAPH are presentational only — no stored value.
+     */
+    public function hasValue(): bool
+    {
+        return match ($this) {
+            self::HEADING, self::PARAGRAPH => false,
+            default => true,
+        };
+    }
+}

api/app/Enums/FormBuilder/FormPurpose.php

@@ -0,0 +1,119 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\FormBuilder;
+
+enum FormPurpose: string
+{
+    case EVENT_REGISTRATION = 'event_registration';
+    case USER_PROFILE = 'user_profile';
+    case ARTIST_PROFILE = 'artist_profile';
+    case COMPANY_PROFILE = 'company_profile';
+    case ARTIST_ADVANCE = 'artist_advance';
+    case SUPPLIER_INTAKE = 'supplier_intake';
+    case INCIDENT_REPORT = 'incident_report';
+    case FEEDBACK = 'feedback';
+    case POST_EVENT_EVALUATION = 'post_event_evaluation';
+    case SIGNATURE_CONTRACT = 'signature_contract';
+    case SIGNATURE_CODE_OF_CONDUCT = 'signature_code_of_conduct';
+    case SIGNATURE_RECEIPT = 'signature_receipt';
+    case ABSENCE_REPORT = 'absence_report';
+    case CHECK_OUT_INVENTORY = 'check_out_inventory';
+    case PUBLIC_COMPLAINT = 'public_complaint';
+    case PUBLIC_PRESS_REQUEST = 'public_press_request';
+    case PUBLIC_RSVP = 'public_rsvp';
+    case ONBOARDING_WIZARD = 'onboarding_wizard';
+    case EVENT_SETUP_WIZARD = 'event_setup_wizard';
+    case COMPANY_CUSTOM = 'company_custom';
+    case ARTIST_CUSTOM = 'artist_custom';
+    case CUSTOM = 'custom';
+
+    /**
+     * @return array<int, string>
+     */
+    public static function values(): array
+    {
+        return array_map(fn (self $case): string => $case->value, self::cases());
+    }
+
+    /**
+     * Default subject_type for each purpose per ARCH §3.1.
+     * null = subject may be null (public or ambiguous).
+     */
+    public function defaultSubjectType(): ?string
+    {
+        return match ($this) {
+            self::EVENT_REGISTRATION,
+            self::POST_EVENT_EVALUATION,
+            self::SIGNATURE_RECEIPT,
+            self::ABSENCE_REPORT,
+            self::CHECK_OUT_INVENTORY => 'person',
+
+            self::USER_PROFILE,
+            self::SIGNATURE_CODE_OF_CONDUCT => 'user',
+
+            self::ARTIST_PROFILE,
+            self::ARTIST_ADVANCE,
+            self::ARTIST_CUSTOM => 'artist',
+
+            self::COMPANY_PROFILE,
+            self::SUPPLIER_INTAKE,
+            self::COMPANY_CUSTOM => 'company',
+
+            self::ONBOARDING_WIZARD => 'organisation',
+            self::EVENT_SETUP_WIZARD => 'event',
+
+            self::INCIDENT_REPORT,
+            self::FEEDBACK,
+            self::SIGNATURE_CONTRACT => 'user',
+
+            self::PUBLIC_COMPLAINT,
+            self::PUBLIC_PRESS_REQUEST,
+            self::PUBLIC_RSVP,
+            self::CUSTOM => null,
+        };
+    }
+
+    public function defaultSubmissionMode(): FormSubmissionMode
+    {
+        return match ($this) {
+            self::EVENT_REGISTRATION,
+            self::ARTIST_ADVANCE,
+            self::SUPPLIER_INTAKE => FormSubmissionMode::DRAFT_SINGLE,
+
+            self::INCIDENT_REPORT,
+            self::FEEDBACK,
+            self::SIGNATURE_RECEIPT,
+            self::ABSENCE_REPORT,
+            self::CHECK_OUT_INVENTORY,
+            self::PUBLIC_COMPLAINT,
+            self::PUBLIC_PRESS_REQUEST => FormSubmissionMode::MULTIPLE,
+
+            self::USER_PROFILE,
+            self::ARTIST_PROFILE,
+            self::COMPANY_PROFILE,
+            self::POST_EVENT_EVALUATION,
+            self::SIGNATURE_CONTRACT,
+            self::SIGNATURE_CODE_OF_CONDUCT,
+            self::PUBLIC_RSVP,
+            self::ONBOARDING_WIZARD,
+            self::EVENT_SETUP_WIZARD,
+            self::COMPANY_CUSTOM,
+            self::ARTIST_CUSTOM,
+            self::CUSTOM => FormSubmissionMode::SINGLE,
+        };
+    }
+
+    public function allowsPublicAccess(): bool
+    {
+        return match ($this) {
+            self::PUBLIC_COMPLAINT,
+            self::PUBLIC_PRESS_REQUEST,
+            self::PUBLIC_RSVP,
+            self::ARTIST_ADVANCE,
+            self::SUPPLIER_INTAKE => true,
+            default => false,
+        };
+    }
+}

api/app/Enums/FormBuilder/FormSchemaSnapshotMode.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\FormBuilder;
+
+enum FormSchemaSnapshotMode: string
+{
+    case NEVER = 'never';
+    case ON_SUBMIT = 'on_submit';
+    case ALWAYS = 'always';
+
+    /**
+     * @return array<int, string>
+     */
+    public static function values(): array
+    {
+        return array_map(fn (self $case): string => $case->value, self::cases());
+    }
+}

api/app/Enums/FormBuilder/FormSubmissionMode.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\FormBuilder;
+
+enum FormSubmissionMode: string
+{
+    case SINGLE = 'single';
+    case MULTIPLE = 'multiple';
+    case DRAFT_SINGLE = 'draft_single';
+
+    /**
+     * @return array<int, string>
+     */
+    public static function values(): array
+    {
+        return array_map(fn (self $case): string => $case->value, self::cases());
+    }
+}

api/app/Enums/FormBuilder/FormSubmissionReviewStatus.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\FormBuilder;
+
+enum FormSubmissionReviewStatus: string
+{
+    case PENDING_REVIEW = 'pending_review';
+    case APPROVED = 'approved';
+    case REJECTED = 'rejected';
+    case CHANGES_REQUESTED = 'changes_requested';
+
+    /**
+     * @return array<int, string>
+     */
+    public static function values(): array
+    {
+        return array_map(fn (self $case): string => $case->value, self::cases());
+    }
+}

api/app/Enums/FormBuilder/FormSubmissionStatus.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\FormBuilder;
+
+enum FormSubmissionStatus: string
+{
+    case DRAFT = 'draft';
+    case SUBMITTED = 'submitted';
+    case ARCHIVED = 'archived';
+
+    /**
+     * @return array<int, string>
+     */
+    public static function values(): array
+    {
+        return array_map(fn (self $case): string => $case->value, self::cases());
+    }
+}

api/app/Enums/FormBuilder/FormValueStorageHint.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\FormBuilder;
+
+enum FormValueStorageHint: string
+{
+    case JSON = 'json';
+    case STRING = 'string';
+    case NUMBER = 'number';
+    case DATE = 'date';
+    case BOOL = 'bool';
+
+    /**
+     * @return array<int, string>
+     */
+    public static function values(): array
+    {
+        return array_map(fn (self $case): string => $case->value, self::cases());
+    }
+}

api/app/Enums/FormBuilder/FormWebhookDeliveryStatus.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\FormBuilder;
+
+enum FormWebhookDeliveryStatus: string
+{
+    case PENDING = 'pending';
+    case DELIVERED = 'delivered';
+    case FAILED = 'failed';
+    case DEAD_LETTER = 'dead_letter';
+
+    /**
+     * @return array<int, string>
+     */
+    public static function values(): array
+    {
+        return array_map(fn (self $case): string => $case->value, self::cases());
+    }
+}