From dda60ed5e45a1ae405b2878e104d852337bc9465 Mon Sep 17 00:00:00 2001
From: "bert.hausmans" <bert@hausmans.nl>
Date: Thu, 23 Apr 2026 23:57:39 +0200
Subject: [PATCH] refactor(form-schema): extract schema types and schema-driven
 behaviors to shared package

Moves formBuilder types, formValidation, useConditionalLogic, useFormSteps,
and formatFieldValue from apps/portal/src to packages/form-schema/src.
Adds @form-schema path alias to both apps/portal and apps/app.
Vue field components remain per-app to allow independent visual evolution.
Behavior-neutral: all 35 Vitest tests green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 apps/app/tsconfig.json                        |  9 ++++++++-
 apps/app/vite.config.ts                       |  3 +++
 apps/portal/auto-imports.d.ts                 |  7 -------
 .../public-form/DuplicateSubmissionHint.vue   |  2 +-
 .../public-form/FieldAvailabilityPicker.vue   |  4 ++--
 .../components/public-form/FieldBoolean.vue   |  2 +-
 .../public-form/FieldCheckboxList.vue         |  4 ++--
 .../src/components/public-form/FieldDate.vue  |  4 ++--
 .../src/components/public-form/FieldEmail.vue |  4 ++--
 .../components/public-form/FieldHeading.vue   |  2 +-
 .../public-form/FieldMultiselect.vue          |  4 ++--
 .../components/public-form/FieldNumber.vue    |  4 ++--
 .../components/public-form/FieldParagraph.vue |  2 +-
 .../src/components/public-form/FieldPhone.vue |  4 ++--
 .../src/components/public-form/FieldRadio.vue |  4 ++--
 .../components/public-form/FieldRenderer.vue  |  6 +++---
 .../public-form/FieldSectionPriority.vue      |  4 ++--
 .../components/public-form/FieldSelect.vue    |  4 ++--
 .../components/public-form/FieldTagPicker.vue |  4 ++--
 .../src/components/public-form/FieldText.vue  |  4 ++--
 .../components/public-form/FieldTextarea.vue  |  4 ++--
 .../src/components/public-form/FieldUrl.vue   |  4 ++--
 .../public-form/FormConfirmation.vue          |  8 ++++----
 .../components/public-form/FormErrorState.vue |  2 +-
 .../components/public-form/FormStepper.vue    |  2 +-
 .../src/composables/api/usePublicForm.ts      |  2 +-
 .../composables/api/usePublicFormSections.ts  |  2 +-
 .../composables/api/usePublicFormTimeSlots.ts |  2 +-
 apps/portal/src/composables/useFormDraft.ts   |  2 +-
 .../src/pages/register/[public_token].vue     |  8 ++++----
 .../FieldAvailabilityPicker.spec.ts           |  4 ++--
 .../public-form/FieldRenderer.test.ts         |  4 ++--
 .../public-form/FieldSectionPriority.spec.ts  |  4 ++--
 .../public-form/FieldTagPicker.spec.ts        |  4 ++--
 .../api/usePublicFormSections.spec.ts         |  2 +-
 .../api/usePublicFormTimeSlots.spec.ts        |  2 +-
 .../composables/useConditionalLogic.test.ts   |  4 ++--
 .../unit/DuplicateSubmissionHint.spec.ts      |  2 +-
 .../tests/unit/formatFieldValue.spec.ts       |  6 +++---
 apps/portal/tsconfig.json                     |  9 ++++++++-
 apps/portal/vite.config.ts                    |  1 +
 apps/portal/vitest.config.ts                  |  1 +
 packages/form-schema/README.md                | 19 +++++++++++++++++++
 .../src/composables/formatFieldValue.ts       |  4 ++--
 .../src/composables/useConditionalLogic.ts    |  2 +-
 .../src/composables/useFormSteps.ts           |  8 ++++----
 .../form-schema}/src/types/formBuilder.ts     |  0
 .../form-schema}/src/utils/formValidation.ts  |  4 ++--
 48 files changed, 114 insertions(+), 83 deletions(-)
 create mode 100644 packages/form-schema/README.md
 rename {apps/portal => packages/form-schema}/src/composables/formatFieldValue.ts (98%)
 rename {apps/portal => packages/form-schema}/src/composables/useConditionalLogic.ts (99%)
 rename {apps/portal => packages/form-schema}/src/composables/useFormSteps.ts (94%)
 rename {apps/portal => packages/form-schema}/src/types/formBuilder.ts (100%)
 rename {apps/portal => packages/form-schema}/src/utils/formValidation.ts (97%)

diff --git a/apps/app/tsconfig.json b/apps/app/tsconfig.json
index a0d3eaa8..3b692e40 100644
--- a/apps/app/tsconfig.json
+++ b/apps/app/tsconfig.json
@@ -39,6 +39,12 @@
       ],
       "@validators": [
         "./src/@core/utils/validators"
+      ],
+      "@form-schema/*": [
+        "../../packages/form-schema/src/*"
+      ],
+      "vue": [
+        "./node_modules/vue"
       ]
     },
     "lib": [
@@ -63,7 +69,8 @@
     "./src/**/*.vue",
     "./themeConfig.ts",
     "./auto-imports.d.ts",
-    "./components.d.ts"
+    "./components.d.ts",
+    "../../packages/form-schema/src/**/*"
   ],
   "exclude": [
     "./dist",
diff --git a/apps/app/vite.config.ts b/apps/app/vite.config.ts
index f7057706..1f3f2ebc 100644
--- a/apps/app/vite.config.ts
+++ b/apps/app/vite.config.ts
@@ -110,6 +110,9 @@ export default defineConfig({
           import.meta.url,
         ),
       ),
+      "@form-schema": fileURLToPath(
+        new URL("../../packages/form-schema/src", import.meta.url),
+      ),
     },
   },
   server: {
diff --git a/apps/portal/auto-imports.d.ts b/apps/portal/auto-imports.d.ts
index 300451ce..b0004a7e 100644
--- a/apps/portal/auto-imports.d.ts
+++ b/apps/portal/auto-imports.d.ts
@@ -434,19 +434,16 @@ declare module 'vue' {
     readonly eagerComputed: UnwrapRef<typeof import('@vueuse/core')['eagerComputed']>
     readonly effectScope: UnwrapRef<typeof import('vue')['effectScope']>
     readonly emailValidator: UnwrapRef<typeof import('./src/@core/utils/validators')['emailValidator']>
-    readonly evaluateConditionalLogic: UnwrapRef<typeof import('./src/composables/useConditionalLogic')['evaluateConditionalLogic']>
     readonly extendRef: UnwrapRef<typeof import('@vueuse/core')['extendRef']>
     readonly extractErrorBody: UnwrapRef<typeof import('./src/composables/useFormDraft')['extractErrorBody']>
     readonly extractRetryAfterSeconds: UnwrapRef<typeof import('./src/composables/useFormDraft')['extractRetryAfterSeconds']>
     readonly formatDate: UnwrapRef<typeof import('./src/@core/utils/formatters')['formatDate']>
     readonly formatDateToMonthShort: UnwrapRef<typeof import('./src/@core/utils/formatters')['formatDateToMonthShort']>
-    readonly formatFieldValue: UnwrapRef<typeof import('./src/composables/formatFieldValue')['formatFieldValue']>
     readonly generateDeviceFingerprint: UnwrapRef<typeof import('./src/utils/deviceFingerprint')['generateDeviceFingerprint']>
     readonly getActivePinia: UnwrapRef<typeof import('pinia')['getActivePinia']>
     readonly getCurrentInstance: UnwrapRef<typeof import('vue')['getCurrentInstance']>
     readonly getCurrentScope: UnwrapRef<typeof import('vue')['getCurrentScope']>
     readonly getDeviceName: UnwrapRef<typeof import('./src/utils/deviceFingerprint')['getDeviceName']>
-    readonly getValidatorsForField: UnwrapRef<typeof import('./src/utils/formValidation')['getValidatorsForField']>
     readonly h: UnwrapRef<typeof import('vue')['h']>
     readonly hexToRgb: UnwrapRef<typeof import('./src/@core/utils/colorConverter')['hexToRgb']>
     readonly ignorableWatch: UnwrapRef<typeof import('@vueuse/core')['ignorableWatch']>
@@ -456,14 +453,12 @@ declare module 'vue' {
     readonly isDefined: UnwrapRef<typeof import('@vueuse/core')['isDefined']>
     readonly isEmpty: UnwrapRef<typeof import('./src/@core/utils/helpers')['isEmpty']>
     readonly isEmptyArray: UnwrapRef<typeof import('./src/@core/utils/helpers')['isEmptyArray']>
-    readonly isFieldValueEmpty: UnwrapRef<typeof import('./src/utils/formValidation')['isFieldValueEmpty']>
     readonly isNullOrUndefined: UnwrapRef<typeof import('./src/@core/utils/helpers')['isNullOrUndefined']>
     readonly isObject: UnwrapRef<typeof import('./src/@core/utils/helpers')['isObject']>
     readonly isProxy: UnwrapRef<typeof import('vue')['isProxy']>
     readonly isReactive: UnwrapRef<typeof import('vue')['isReactive']>
     readonly isReadonly: UnwrapRef<typeof import('vue')['isReadonly']>
     readonly isRef: UnwrapRef<typeof import('vue')['isRef']>
-    readonly isStepValid: UnwrapRef<typeof import('./src/composables/useFormSteps')['isStepValid']>
     readonly isToday: UnwrapRef<typeof import('./src/@core/utils/helpers')['isToday']>
     readonly kFormatter: UnwrapRef<typeof import('./src/@core/utils/formatters')['kFormatter']>
     readonly lengthValidator: UnwrapRef<typeof import('./src/@core/utils/validators')['lengthValidator']>
@@ -526,7 +521,6 @@ declare module 'vue' {
     readonly resolveUnref: UnwrapRef<typeof import('@vueuse/core')['resolveUnref']>
     readonly resolveVuetifyTheme: UnwrapRef<typeof import('./src/@core/utils/vuetify')['resolveVuetifyTheme']>
     readonly rgbaToHex: UnwrapRef<typeof import('./src/@core/utils/colorConverter')['rgbaToHex']>
-    readonly runValidators: UnwrapRef<typeof import('./src/utils/formValidation')['runValidators']>
     readonly setActivePinia: UnwrapRef<typeof import('pinia')['setActivePinia']>
     readonly setMapStoreSuffix: UnwrapRef<typeof import('pinia')['setMapStoreSuffix']>
     readonly shallowReactive: UnwrapRef<typeof import('vue')['shallowReactive']>
@@ -623,7 +617,6 @@ declare module 'vue' {
     readonly useFocus: UnwrapRef<typeof import('@vueuse/core')['useFocus']>
     readonly useFocusWithin: UnwrapRef<typeof import('@vueuse/core')['useFocusWithin']>
     readonly useFormDraft: UnwrapRef<typeof import('./src/composables/useFormDraft')['useFormDraft']>
-    readonly useFormSteps: UnwrapRef<typeof import('./src/composables/useFormSteps')['useFormSteps']>
     readonly useFps: UnwrapRef<typeof import('@vueuse/core')['useFps']>
     readonly useFullscreen: UnwrapRef<typeof import('@vueuse/core')['useFullscreen']>
     readonly useGamepad: UnwrapRef<typeof import('@vueuse/core')['useGamepad']>
diff --git a/apps/portal/src/components/public-form/DuplicateSubmissionHint.vue b/apps/portal/src/components/public-form/DuplicateSubmissionHint.vue
index b24e8ec8..ffc41624 100644
--- a/apps/portal/src/components/public-form/DuplicateSubmissionHint.vue
+++ b/apps/portal/src/components/public-form/DuplicateSubmissionHint.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { PublicFormSubmissionDuplicate } from '@/types/formBuilder'
+import type { PublicFormSubmissionDuplicate } from '@form-schema/types/formBuilder'
 
 const props = defineProps<{
   data: PublicFormSubmissionDuplicate | null
diff --git a/apps/portal/src/components/public-form/FieldAvailabilityPicker.vue b/apps/portal/src/components/public-form/FieldAvailabilityPicker.vue
index c9cf3db3..6a84c6d7 100644
--- a/apps/portal/src/components/public-form/FieldAvailabilityPicker.vue
+++ b/apps/portal/src/components/public-form/FieldAvailabilityPicker.vue
@@ -1,8 +1,8 @@
 <script setup lang="ts">
 import { usePublicFormTimeSlots } from '@/composables/api/usePublicFormTimeSlots'
 import { usePublicFormToken } from '@/composables/publicFormInjection'
-import type { PublicFormField, PublicFormTimeSlot } from '@/types/formBuilder'
-import { getValidatorsForField, runValidators } from '@/utils/formValidation'
+import type { PublicFormField, PublicFormTimeSlot } from '@form-schema/types/formBuilder'
+import { getValidatorsForField, runValidators } from '@form-schema/utils/formValidation'
 
 const props = defineProps<{
   field: PublicFormField
diff --git a/apps/portal/src/components/public-form/FieldBoolean.vue b/apps/portal/src/components/public-form/FieldBoolean.vue
index 6f825894..f0063a46 100644
--- a/apps/portal/src/components/public-form/FieldBoolean.vue
+++ b/apps/portal/src/components/public-form/FieldBoolean.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { PublicFormField } from '@/types/formBuilder'
+import type { PublicFormField } from '@form-schema/types/formBuilder'
 
 const props = defineProps<{
   field: PublicFormField
diff --git a/apps/portal/src/components/public-form/FieldCheckboxList.vue b/apps/portal/src/components/public-form/FieldCheckboxList.vue
index a5a733fa..40d8314a 100644
--- a/apps/portal/src/components/public-form/FieldCheckboxList.vue
+++ b/apps/portal/src/components/public-form/FieldCheckboxList.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import type { FieldOption, PublicFormField } from '@/types/formBuilder'
-import { getValidatorsForField, runValidators } from '@/utils/formValidation'
+import type { FieldOption, PublicFormField } from '@form-schema/types/formBuilder'
+import { getValidatorsForField, runValidators } from '@form-schema/utils/formValidation'
 
 const props = defineProps<{
   field: PublicFormField
diff --git a/apps/portal/src/components/public-form/FieldDate.vue b/apps/portal/src/components/public-form/FieldDate.vue
index 318cda4c..47da8b65 100644
--- a/apps/portal/src/components/public-form/FieldDate.vue
+++ b/apps/portal/src/components/public-form/FieldDate.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import type { PublicFormField } from '@/types/formBuilder'
-import { getValidatorsForField } from '@/utils/formValidation'
+import type { PublicFormField } from '@form-schema/types/formBuilder'
+import { getValidatorsForField } from '@form-schema/utils/formValidation'
 
 const props = defineProps<{
   field: PublicFormField
diff --git a/apps/portal/src/components/public-form/FieldEmail.vue b/apps/portal/src/components/public-form/FieldEmail.vue
index 6fe03648..71396b80 100644
--- a/apps/portal/src/components/public-form/FieldEmail.vue
+++ b/apps/portal/src/components/public-form/FieldEmail.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import type { PublicFormField } from '@/types/formBuilder'
-import { getValidatorsForField } from '@/utils/formValidation'
+import type { PublicFormField } from '@form-schema/types/formBuilder'
+import { getValidatorsForField } from '@form-schema/utils/formValidation'
 
 const props = defineProps<{
   field: PublicFormField
diff --git a/apps/portal/src/components/public-form/FieldHeading.vue b/apps/portal/src/components/public-form/FieldHeading.vue
index cb5b9fcc..7b1c38d9 100644
--- a/apps/portal/src/components/public-form/FieldHeading.vue
+++ b/apps/portal/src/components/public-form/FieldHeading.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { PublicFormField } from '@/types/formBuilder'
+import type { PublicFormField } from '@form-schema/types/formBuilder'
 
 defineProps<{
   field: PublicFormField
diff --git a/apps/portal/src/components/public-form/FieldMultiselect.vue b/apps/portal/src/components/public-form/FieldMultiselect.vue
index 48d579fd..1eeacbe7 100644
--- a/apps/portal/src/components/public-form/FieldMultiselect.vue
+++ b/apps/portal/src/components/public-form/FieldMultiselect.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import type { FieldOption, PublicFormField } from '@/types/formBuilder'
-import { getValidatorsForField } from '@/utils/formValidation'
+import type { FieldOption, PublicFormField } from '@form-schema/types/formBuilder'
+import { getValidatorsForField } from '@form-schema/utils/formValidation'
 
 const props = defineProps<{
   field: PublicFormField
diff --git a/apps/portal/src/components/public-form/FieldNumber.vue b/apps/portal/src/components/public-form/FieldNumber.vue
index 933315f4..8cfa0832 100644
--- a/apps/portal/src/components/public-form/FieldNumber.vue
+++ b/apps/portal/src/components/public-form/FieldNumber.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import type { PublicFormField } from '@/types/formBuilder'
-import { getValidatorsForField } from '@/utils/formValidation'
+import type { PublicFormField } from '@form-schema/types/formBuilder'
+import { getValidatorsForField } from '@form-schema/utils/formValidation'
 
 const props = defineProps<{
   field: PublicFormField
diff --git a/apps/portal/src/components/public-form/FieldParagraph.vue b/apps/portal/src/components/public-form/FieldParagraph.vue
index 646e1a3e..17f86883 100644
--- a/apps/portal/src/components/public-form/FieldParagraph.vue
+++ b/apps/portal/src/components/public-form/FieldParagraph.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { PublicFormField } from '@/types/formBuilder'
+import type { PublicFormField } from '@form-schema/types/formBuilder'
 
 defineProps<{
   field: PublicFormField
diff --git a/apps/portal/src/components/public-form/FieldPhone.vue b/apps/portal/src/components/public-form/FieldPhone.vue
index e33807d4..f4d92f47 100644
--- a/apps/portal/src/components/public-form/FieldPhone.vue
+++ b/apps/portal/src/components/public-form/FieldPhone.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import type { PublicFormField } from '@/types/formBuilder'
-import { getValidatorsForField } from '@/utils/formValidation'
+import type { PublicFormField } from '@form-schema/types/formBuilder'
+import { getValidatorsForField } from '@form-schema/utils/formValidation'
 
 const props = defineProps<{
   field: PublicFormField
diff --git a/apps/portal/src/components/public-form/FieldRadio.vue b/apps/portal/src/components/public-form/FieldRadio.vue
index 6cb9b362..91ddc55a 100644
--- a/apps/portal/src/components/public-form/FieldRadio.vue
+++ b/apps/portal/src/components/public-form/FieldRadio.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import type { FieldOption, PublicFormField } from '@/types/formBuilder'
-import { getValidatorsForField } from '@/utils/formValidation'
+import type { FieldOption, PublicFormField } from '@form-schema/types/formBuilder'
+import { getValidatorsForField } from '@form-schema/utils/formValidation'
 
 const props = defineProps<{
   field: PublicFormField
diff --git a/apps/portal/src/components/public-form/FieldRenderer.vue b/apps/portal/src/components/public-form/FieldRenderer.vue
index a4e2b78a..bdf49b96 100644
--- a/apps/portal/src/components/public-form/FieldRenderer.vue
+++ b/apps/portal/src/components/public-form/FieldRenderer.vue
@@ -16,9 +16,9 @@ import FieldTagPicker from './FieldTagPicker.vue'
 import FieldText from './FieldText.vue'
 import FieldTextarea from './FieldTextarea.vue'
 import FieldUrl from './FieldUrl.vue'
-import { evaluateConditionalLogic } from '@/composables/useConditionalLogic'
-import { FormFieldType } from '@/types/formBuilder'
-import type { FormFieldDisplayWidth, FormValues, PublicFormField } from '@/types/formBuilder'
+import { evaluateConditionalLogic } from '@form-schema/composables/useConditionalLogic'
+import { FormFieldType } from '@form-schema/types/formBuilder'
+import type { FormFieldDisplayWidth, FormValues, PublicFormField } from '@form-schema/types/formBuilder'
 
 const props = defineProps<{
   field: PublicFormField
diff --git a/apps/portal/src/components/public-form/FieldSectionPriority.vue b/apps/portal/src/components/public-form/FieldSectionPriority.vue
index 3c7cd501..7307f1b5 100644
--- a/apps/portal/src/components/public-form/FieldSectionPriority.vue
+++ b/apps/portal/src/components/public-form/FieldSectionPriority.vue
@@ -3,8 +3,8 @@ import draggable from 'vuedraggable'
 import { useDisplay } from 'vuetify'
 import { usePublicFormSections } from '@/composables/api/usePublicFormSections'
 import { usePublicFormToken } from '@/composables/publicFormInjection'
-import type { PublicFormField, PublicFormSectionOption, SectionPriorityValue } from '@/types/formBuilder'
-import { getValidatorsForField, runValidators } from '@/utils/formValidation'
+import type { PublicFormField, PublicFormSectionOption, SectionPriorityValue } from '@form-schema/types/formBuilder'
+import { getValidatorsForField, runValidators } from '@form-schema/utils/formValidation'
 
 const props = defineProps<{
   field: PublicFormField
diff --git a/apps/portal/src/components/public-form/FieldSelect.vue b/apps/portal/src/components/public-form/FieldSelect.vue
index 2bbbb603..eea5feef 100644
--- a/apps/portal/src/components/public-form/FieldSelect.vue
+++ b/apps/portal/src/components/public-form/FieldSelect.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import type { FieldOption, PublicFormField } from '@/types/formBuilder'
-import { getValidatorsForField } from '@/utils/formValidation'
+import type { FieldOption, PublicFormField } from '@form-schema/types/formBuilder'
+import { getValidatorsForField } from '@form-schema/utils/formValidation'
 
 const props = defineProps<{
   field: PublicFormField
diff --git a/apps/portal/src/components/public-form/FieldTagPicker.vue b/apps/portal/src/components/public-form/FieldTagPicker.vue
index 47ada402..76db5041 100644
--- a/apps/portal/src/components/public-form/FieldTagPicker.vue
+++ b/apps/portal/src/components/public-form/FieldTagPicker.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import type { AvailableTag, PublicFormField } from '@/types/formBuilder'
-import { getValidatorsForField } from '@/utils/formValidation'
+import type { AvailableTag, PublicFormField } from '@form-schema/types/formBuilder'
+import { getValidatorsForField } from '@form-schema/utils/formValidation'
 
 const props = defineProps<{
   field: PublicFormField
diff --git a/apps/portal/src/components/public-form/FieldText.vue b/apps/portal/src/components/public-form/FieldText.vue
index dc5f92d5..09599242 100644
--- a/apps/portal/src/components/public-form/FieldText.vue
+++ b/apps/portal/src/components/public-form/FieldText.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import type { PublicFormField } from '@/types/formBuilder'
-import { getValidatorsForField } from '@/utils/formValidation'
+import type { PublicFormField } from '@form-schema/types/formBuilder'
+import { getValidatorsForField } from '@form-schema/utils/formValidation'
 
 const props = defineProps<{
   field: PublicFormField
diff --git a/apps/portal/src/components/public-form/FieldTextarea.vue b/apps/portal/src/components/public-form/FieldTextarea.vue
index 9553c493..40c04709 100644
--- a/apps/portal/src/components/public-form/FieldTextarea.vue
+++ b/apps/portal/src/components/public-form/FieldTextarea.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import type { PublicFormField } from '@/types/formBuilder'
-import { getValidatorsForField } from '@/utils/formValidation'
+import type { PublicFormField } from '@form-schema/types/formBuilder'
+import { getValidatorsForField } from '@form-schema/utils/formValidation'
 
 const props = defineProps<{
   field: PublicFormField
diff --git a/apps/portal/src/components/public-form/FieldUrl.vue b/apps/portal/src/components/public-form/FieldUrl.vue
index 3fda8e50..a054e8b4 100644
--- a/apps/portal/src/components/public-form/FieldUrl.vue
+++ b/apps/portal/src/components/public-form/FieldUrl.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import type { PublicFormField } from '@/types/formBuilder'
-import { getValidatorsForField } from '@/utils/formValidation'
+import type { PublicFormField } from '@form-schema/types/formBuilder'
+import { getValidatorsForField } from '@form-schema/utils/formValidation'
 
 const props = defineProps<{
   field: PublicFormField
diff --git a/apps/portal/src/components/public-form/FormConfirmation.vue b/apps/portal/src/components/public-form/FormConfirmation.vue
index 9876eb77..6df1d80c 100644
--- a/apps/portal/src/components/public-form/FormConfirmation.vue
+++ b/apps/portal/src/components/public-form/FormConfirmation.vue
@@ -3,16 +3,16 @@ import DuplicateSubmissionHint from './DuplicateSubmissionHint.vue'
 import IdentityMatchBanner from './IdentityMatchBanner.vue'
 import { usePublicFormSections } from '@/composables/api/usePublicFormSections'
 import { usePublicFormTimeSlots } from '@/composables/api/usePublicFormTimeSlots'
-import { formatFieldValue } from '@/composables/formatFieldValue'
-import type { FormStep } from '@/composables/useFormSteps'
+import { formatFieldValue } from '@form-schema/composables/formatFieldValue'
+import type { FormStep } from '@form-schema/composables/useFormSteps'
 import { usePublicFormToken } from '@/composables/publicFormInjection'
-import { FormFieldType } from '@/types/formBuilder'
+import { FormFieldType } from '@form-schema/types/formBuilder'
 import type {
   FormValues,
   PublicFormField,
   PublicFormSubmissionDuplicate,
   PublicFormSubmissionIdentityMatch,
-} from '@/types/formBuilder'
+} from '@form-schema/types/formBuilder'
 
 const props = defineProps<{
   steps: FormStep[]
diff --git a/apps/portal/src/components/public-form/FormErrorState.vue b/apps/portal/src/components/public-form/FormErrorState.vue
index df42f815..fa1a1f69 100644
--- a/apps/portal/src/components/public-form/FormErrorState.vue
+++ b/apps/portal/src/components/public-form/FormErrorState.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { FormErrorCode } from '@/types/formBuilder'
+import type { FormErrorCode } from '@form-schema/types/formBuilder'
 
 const props = defineProps<{
   errorCode?: FormErrorCode | string
diff --git a/apps/portal/src/components/public-form/FormStepper.vue b/apps/portal/src/components/public-form/FormStepper.vue
index 436419a2..8dfe067b 100644
--- a/apps/portal/src/components/public-form/FormStepper.vue
+++ b/apps/portal/src/components/public-form/FormStepper.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { useDisplay } from 'vuetify'
-import type { FormStep } from '@/composables/useFormSteps'
+import type { FormStep } from '@form-schema/composables/useFormSteps'
 
 const props = defineProps<{
   steps: FormStep[]
diff --git a/apps/portal/src/composables/api/usePublicForm.ts b/apps/portal/src/composables/api/usePublicForm.ts
index 79b6c18f..b3b19a09 100644
--- a/apps/portal/src/composables/api/usePublicForm.ts
+++ b/apps/portal/src/composables/api/usePublicForm.ts
@@ -9,7 +9,7 @@ import type {
   SaveDraftBody,
   StartDraftBody,
   SubmitBody,
-} from '@/types/formBuilder'
+} from '@form-schema/types/formBuilder'
 
 interface ApiResponse<T> {
   data: T
diff --git a/apps/portal/src/composables/api/usePublicFormSections.ts b/apps/portal/src/composables/api/usePublicFormSections.ts
index 20dd2600..9b337155 100644
--- a/apps/portal/src/composables/api/usePublicFormSections.ts
+++ b/apps/portal/src/composables/api/usePublicFormSections.ts
@@ -1,7 +1,7 @@
 import { useQuery } from '@tanstack/vue-query'
 import type { Ref } from 'vue'
 import { apiClient } from '@/lib/axios'
-import type { PublicFormSectionOption } from '@/types/formBuilder'
+import type { PublicFormSectionOption } from '@form-schema/types/formBuilder'
 
 interface ApiResponse<T> {
   data: T
diff --git a/apps/portal/src/composables/api/usePublicFormTimeSlots.ts b/apps/portal/src/composables/api/usePublicFormTimeSlots.ts
index 13d3a195..24a3cfbe 100644
--- a/apps/portal/src/composables/api/usePublicFormTimeSlots.ts
+++ b/apps/portal/src/composables/api/usePublicFormTimeSlots.ts
@@ -1,7 +1,7 @@
 import { useQuery } from '@tanstack/vue-query'
 import type { Ref } from 'vue'
 import { apiClient } from '@/lib/axios'
-import type { PublicFormTimeSlot } from '@/types/formBuilder'
+import type { PublicFormTimeSlot } from '@form-schema/types/formBuilder'
 
 interface ApiResponse<T> {
   data: T
diff --git a/apps/portal/src/composables/useFormDraft.ts b/apps/portal/src/composables/useFormDraft.ts
index 3277b37a..37f1902a 100644
--- a/apps/portal/src/composables/useFormDraft.ts
+++ b/apps/portal/src/composables/useFormDraft.ts
@@ -7,7 +7,7 @@ import {
   useSaveFormDraft,
   useSubmitForm,
 } from '@/composables/api/usePublicForm'
-import type { FormValues, PublicFormSubmission, SaveDraftBody } from '@/types/formBuilder'
+import type { FormValues, PublicFormSubmission, SaveDraftBody } from '@form-schema/types/formBuilder'
 
 /** sessionStorage key for reusing an idempotency key across reloads. */
 export function draftIdempotencyKey(token: string): string {
diff --git a/apps/portal/src/pages/register/[public_token].vue b/apps/portal/src/pages/register/[public_token].vue
index 6756dc18..7383c863 100644
--- a/apps/portal/src/pages/register/[public_token].vue
+++ b/apps/portal/src/pages/register/[public_token].vue
@@ -9,11 +9,11 @@ import { extractErrorBody, useFetchPublicFormSchema } from '@/composables/api/us
 import { usePublicFormSections } from '@/composables/api/usePublicFormSections'
 import { usePublicFormTimeSlots } from '@/composables/api/usePublicFormTimeSlots'
 import { useFormDraft } from '@/composables/useFormDraft'
-import { isStepValid, useFormSteps } from '@/composables/useFormSteps'
-import { formatFieldValue } from '@/composables/formatFieldValue'
+import { isStepValid, useFormSteps } from '@form-schema/composables/useFormSteps'
+import { formatFieldValue } from '@form-schema/composables/formatFieldValue'
 import { providePublicFormToken } from '@/composables/publicFormInjection'
-import { FormFieldType } from '@/types/formBuilder'
-import type { FormErrorCode, PublicFormField } from '@/types/formBuilder'
+import { FormFieldType } from '@form-schema/types/formBuilder'
+import type { FormErrorCode, PublicFormField } from '@form-schema/types/formBuilder'
 
 definePage({
   name: 'public-form-register',
diff --git a/apps/portal/tests/components/public-form/FieldAvailabilityPicker.spec.ts b/apps/portal/tests/components/public-form/FieldAvailabilityPicker.spec.ts
index f0cf05e2..5e4a3111 100644
--- a/apps/portal/tests/components/public-form/FieldAvailabilityPicker.spec.ts
+++ b/apps/portal/tests/components/public-form/FieldAvailabilityPicker.spec.ts
@@ -21,8 +21,8 @@ vi.mock('@/composables/publicFormInjection', () => ({
 }))
 
 import FieldAvailabilityPicker from '@/components/public-form/FieldAvailabilityPicker.vue'
-import { FormFieldType } from '@/types/formBuilder'
-import type { PublicFormField, PublicFormTimeSlot } from '@/types/formBuilder'
+import { FormFieldType } from '@form-schema/types/formBuilder'
+import type { PublicFormField, PublicFormTimeSlot } from '@form-schema/types/formBuilder'
 
 function field(partial: Partial<PublicFormField> = {}): PublicFormField {
   return {
diff --git a/apps/portal/tests/components/public-form/FieldRenderer.test.ts b/apps/portal/tests/components/public-form/FieldRenderer.test.ts
index 2a644c70..ed2f26fa 100644
--- a/apps/portal/tests/components/public-form/FieldRenderer.test.ts
+++ b/apps/portal/tests/components/public-form/FieldRenderer.test.ts
@@ -1,8 +1,8 @@
 import { mount } from '@vue/test-utils'
 import { describe, expect, it } from 'vitest'
 import FieldRenderer from '@/components/public-form/FieldRenderer.vue'
-import { FormFieldType } from '@/types/formBuilder'
-import type { PublicFormField } from '@/types/formBuilder'
+import { FormFieldType } from '@form-schema/types/formBuilder'
+import type { PublicFormField } from '@form-schema/types/formBuilder'
 
 function makeField(partial: Partial<PublicFormField>): PublicFormField {
   return {
diff --git a/apps/portal/tests/components/public-form/FieldSectionPriority.spec.ts b/apps/portal/tests/components/public-form/FieldSectionPriority.spec.ts
index e35380e9..2efeccc5 100644
--- a/apps/portal/tests/components/public-form/FieldSectionPriority.spec.ts
+++ b/apps/portal/tests/components/public-form/FieldSectionPriority.spec.ts
@@ -36,8 +36,8 @@ vi.mock('vuedraggable', () => ({
 }))
 
 import FieldSectionPriority from '@/components/public-form/FieldSectionPriority.vue'
-import { FormFieldType } from '@/types/formBuilder'
-import type { PublicFormField, PublicFormSectionOption } from '@/types/formBuilder'
+import { FormFieldType } from '@form-schema/types/formBuilder'
+import type { PublicFormField, PublicFormSectionOption } from '@form-schema/types/formBuilder'
 
 function field(partial: Partial<PublicFormField> = {}): PublicFormField {
   return {
diff --git a/apps/portal/tests/components/public-form/FieldTagPicker.spec.ts b/apps/portal/tests/components/public-form/FieldTagPicker.spec.ts
index c1bdb045..ce42d540 100644
--- a/apps/portal/tests/components/public-form/FieldTagPicker.spec.ts
+++ b/apps/portal/tests/components/public-form/FieldTagPicker.spec.ts
@@ -1,8 +1,8 @@
 import { mount } from '@vue/test-utils'
 import { describe, expect, it } from 'vitest'
 import FieldTagPicker from '@/components/public-form/FieldTagPicker.vue'
-import { FormFieldType } from '@/types/formBuilder'
-import type { AvailableTag, PublicFormField } from '@/types/formBuilder'
+import { FormFieldType } from '@form-schema/types/formBuilder'
+import type { AvailableTag, PublicFormField } from '@form-schema/types/formBuilder'
 
 function field(partial: Partial<PublicFormField> = {}): PublicFormField {
   return {
diff --git a/apps/portal/tests/composables/api/usePublicFormSections.spec.ts b/apps/portal/tests/composables/api/usePublicFormSections.spec.ts
index 45be8e17..cdeccad4 100644
--- a/apps/portal/tests/composables/api/usePublicFormSections.spec.ts
+++ b/apps/portal/tests/composables/api/usePublicFormSections.spec.ts
@@ -9,7 +9,7 @@ vi.mock('@/lib/axios', () => ({
 
 import { apiClient } from '@/lib/axios'
 import { usePublicFormSections } from '@/composables/api/usePublicFormSections'
-import type { PublicFormSectionOption } from '@/types/formBuilder'
+import type { PublicFormSectionOption } from '@form-schema/types/formBuilder'
 
 interface MockedApi { get: ReturnType<typeof vi.fn> }
 const mocked = apiClient as unknown as MockedApi
diff --git a/apps/portal/tests/composables/api/usePublicFormTimeSlots.spec.ts b/apps/portal/tests/composables/api/usePublicFormTimeSlots.spec.ts
index 3dd597c1..48d5e9bc 100644
--- a/apps/portal/tests/composables/api/usePublicFormTimeSlots.spec.ts
+++ b/apps/portal/tests/composables/api/usePublicFormTimeSlots.spec.ts
@@ -9,7 +9,7 @@ vi.mock('@/lib/axios', () => ({
 
 import { apiClient } from '@/lib/axios'
 import { usePublicFormTimeSlots } from '@/composables/api/usePublicFormTimeSlots'
-import type { PublicFormTimeSlot } from '@/types/formBuilder'
+import type { PublicFormTimeSlot } from '@form-schema/types/formBuilder'
 
 interface MockedApi { get: ReturnType<typeof vi.fn> }
 const mocked = apiClient as unknown as MockedApi
diff --git a/apps/portal/tests/composables/useConditionalLogic.test.ts b/apps/portal/tests/composables/useConditionalLogic.test.ts
index c1305c14..55f3484c 100644
--- a/apps/portal/tests/composables/useConditionalLogic.test.ts
+++ b/apps/portal/tests/composables/useConditionalLogic.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
-import { evaluateConditionalLogic } from '@/composables/useConditionalLogic'
-import type { ConditionalLogic } from '@/types/formBuilder'
+import { evaluateConditionalLogic } from '@form-schema/composables/useConditionalLogic'
+import type { ConditionalLogic } from '@form-schema/types/formBuilder'
 
 describe('evaluateConditionalLogic', () => {
   it('returns true when logic is null or undefined', () => {
diff --git a/apps/portal/tests/unit/DuplicateSubmissionHint.spec.ts b/apps/portal/tests/unit/DuplicateSubmissionHint.spec.ts
index 98aa0e81..d4c07123 100644
--- a/apps/portal/tests/unit/DuplicateSubmissionHint.spec.ts
+++ b/apps/portal/tests/unit/DuplicateSubmissionHint.spec.ts
@@ -1,7 +1,7 @@
 import { mount } from '@vue/test-utils'
 import { describe, expect, it } from 'vitest'
 import DuplicateSubmissionHint from '@/components/public-form/DuplicateSubmissionHint.vue'
-import type { PublicFormSubmissionDuplicate } from '@/types/formBuilder'
+import type { PublicFormSubmissionDuplicate } from '@form-schema/types/formBuilder'
 
 function mountHint(data: PublicFormSubmissionDuplicate | null) {
   return mount(DuplicateSubmissionHint, {
diff --git a/apps/portal/tests/unit/formatFieldValue.spec.ts b/apps/portal/tests/unit/formatFieldValue.spec.ts
index 5baff42d..b13740df 100644
--- a/apps/portal/tests/unit/formatFieldValue.spec.ts
+++ b/apps/portal/tests/unit/formatFieldValue.spec.ts
@@ -1,12 +1,12 @@
 import { describe, expect, it } from 'vitest'
-import { formatFieldValue } from '@/composables/formatFieldValue'
-import { FormFieldType } from '@/types/formBuilder'
+import { formatFieldValue } from '@form-schema/composables/formatFieldValue'
+import { FormFieldType } from '@form-schema/types/formBuilder'
 import type {
   AvailableTag,
   PublicFormField,
   PublicFormSectionOption,
   PublicFormTimeSlot,
-} from '@/types/formBuilder'
+} from '@form-schema/types/formBuilder'
 
 function field(partial: Partial<PublicFormField> = {}): PublicFormField {
   return {
diff --git a/apps/portal/tsconfig.json b/apps/portal/tsconfig.json
index bbb26f24..9284402a 100644
--- a/apps/portal/tsconfig.json
+++ b/apps/portal/tsconfig.json
@@ -40,6 +40,12 @@
       "@validators": [
         "./src/@core/utils/validators"
       ],
+      "@form-schema/*": [
+        "../../packages/form-schema/src/*"
+      ],
+      "vue": [
+        "./node_modules/vue"
+      ],
     },
     "lib": [
       "esnext",
@@ -63,7 +69,8 @@
     "./src/**/*.vue",
     "./themeConfig.ts",
     "./auto-imports.d.ts",
-    "./components.d.ts"
+    "./components.d.ts",
+    "../../packages/form-schema/src/**/*"
   ],
   "exclude": [
     "./dist",
diff --git a/apps/portal/vite.config.ts b/apps/portal/vite.config.ts
index accf8821..016de2fe 100644
--- a/apps/portal/vite.config.ts
+++ b/apps/portal/vite.config.ts
@@ -84,6 +84,7 @@ export default defineConfig({
       '@images': fileURLToPath(new URL('./src/assets/images/', import.meta.url)),
       '@styles': fileURLToPath(new URL('./src/assets/styles/', import.meta.url)),
       '@configured-variables': fileURLToPath(new URL('./src/assets/styles/variables/_template.scss', import.meta.url)),
+      '@form-schema': fileURLToPath(new URL('../../packages/form-schema/src', import.meta.url)),
     },
   },
   server: {
diff --git a/apps/portal/vitest.config.ts b/apps/portal/vitest.config.ts
index 728a5aea..b3b9afc3 100644
--- a/apps/portal/vitest.config.ts
+++ b/apps/portal/vitest.config.ts
@@ -23,6 +23,7 @@ export default defineConfig({
       '@images': fileURLToPath(new URL('./src/assets/images/', import.meta.url)),
       '@styles': fileURLToPath(new URL('./src/assets/styles/', import.meta.url)),
       '@validators': fileURLToPath(new URL('./src/@core/utils/validators', import.meta.url)),
+      '@form-schema': fileURLToPath(new URL('../../packages/form-schema/src', import.meta.url)),
     },
   },
   test: {
diff --git a/packages/form-schema/README.md b/packages/form-schema/README.md
new file mode 100644
index 00000000..6ac8ef8c
--- /dev/null
+++ b/packages/form-schema/README.md
@@ -0,0 +1,19 @@
+# @form-schema
+
+Shared schema contract and schema-driven behaviors for Crewli form rendering. Consumed by apps/portal (public submission) and apps/app (organizer builder + submissions review).
+
+## What lives here
+
+- `types/` — TypeScript types and enum constants mirroring backend `FormBuilder` enums and `PublicForm(Schema|Submission)Resource`
+- `utils/formValidation.ts` — validation rule builders driven by `FormFieldValidationRules`
+- `composables/useConditionalLogic.ts` — evaluate `conditional_logic.show_when` against field values
+- `composables/useFormSteps.ts` — step navigation logic for multi-step forms
+- `composables/formatFieldValue.ts` — render a stored submission value as a human-readable string
+
+## What does NOT live here
+
+Vue components. Each app renders its own UI. Portal has full-fidelity submit components; app has builder-preview and submissions-review components. Sharing renderers would couple the two apps' visual styles, which we explicitly want to avoid.
+
+## Contract stability
+
+This is an alias-only shared directory inside the monorepo — no npm package, no semver. Breaking changes (new field type, new validation key, new conditional operator) require updating both apps in the same PR. TypeScript will flag missing cases in dispatchers.
diff --git a/apps/portal/src/composables/formatFieldValue.ts b/packages/form-schema/src/composables/formatFieldValue.ts
similarity index 98%
rename from apps/portal/src/composables/formatFieldValue.ts
rename to packages/form-schema/src/composables/formatFieldValue.ts
index aef60573..5d38b5a4 100644
--- a/apps/portal/src/composables/formatFieldValue.ts
+++ b/packages/form-schema/src/composables/formatFieldValue.ts
@@ -1,10 +1,10 @@
-import { FormFieldType } from '@/types/formBuilder'
+import { FormFieldType } from '../types/formBuilder'
 import type {
   PublicFormField,
   PublicFormSectionOption,
   PublicFormTimeSlot,
   SectionPriorityValue,
-} from '@/types/formBuilder'
+} from '../types/formBuilder'
 
 const EMPTY = '—'
 const LOADING = 'Laden…'
diff --git a/apps/portal/src/composables/useConditionalLogic.ts b/packages/form-schema/src/composables/useConditionalLogic.ts
similarity index 99%
rename from apps/portal/src/composables/useConditionalLogic.ts
rename to packages/form-schema/src/composables/useConditionalLogic.ts
index 1b592d07..74878765 100644
--- a/apps/portal/src/composables/useConditionalLogic.ts
+++ b/packages/form-schema/src/composables/useConditionalLogic.ts
@@ -4,7 +4,7 @@ import type {
   ConditionalOperator,
   ConditionalRule,
   FormValues,
-} from '@/types/formBuilder'
+} from '../types/formBuilder'
 
 function isEmptyValue(v: unknown): boolean {
   if (v === null || v === undefined) return true
diff --git a/apps/portal/src/composables/useFormSteps.ts b/packages/form-schema/src/composables/useFormSteps.ts
similarity index 94%
rename from apps/portal/src/composables/useFormSteps.ts
rename to packages/form-schema/src/composables/useFormSteps.ts
index fdace76d..eb2bfce8 100644
--- a/apps/portal/src/composables/useFormSteps.ts
+++ b/packages/form-schema/src/composables/useFormSteps.ts
@@ -1,9 +1,9 @@
 import { computed } from 'vue'
 import type { ComputedRef, Ref } from 'vue'
-import { evaluateConditionalLogic } from '@/composables/useConditionalLogic'
-import { FormFieldType } from '@/types/formBuilder'
-import type { FormValues, PublicFormField, PublicFormSchema } from '@/types/formBuilder'
-import { isFieldValueEmpty } from '@/utils/formValidation'
+import { evaluateConditionalLogic } from './useConditionalLogic'
+import { FormFieldType } from '../types/formBuilder'
+import type { FormValues, PublicFormField, PublicFormSchema } from '../types/formBuilder'
+import { isFieldValueEmpty } from '../utils/formValidation'
 
 export type StepKind = 'submitter' | 'section' | 'heading_group' | 'flat' | 'review'
 
diff --git a/apps/portal/src/types/formBuilder.ts b/packages/form-schema/src/types/formBuilder.ts
similarity index 100%
rename from apps/portal/src/types/formBuilder.ts
rename to packages/form-schema/src/types/formBuilder.ts
diff --git a/apps/portal/src/utils/formValidation.ts b/packages/form-schema/src/utils/formValidation.ts
similarity index 97%
rename from apps/portal/src/utils/formValidation.ts
rename to packages/form-schema/src/utils/formValidation.ts
index a17fe830..8594ce53 100644
--- a/apps/portal/src/utils/formValidation.ts
+++ b/packages/form-schema/src/utils/formValidation.ts
@@ -1,6 +1,6 @@
 import { emailValidator, regexValidator, requiredValidator, urlValidator } from '@core/utils/validators'
-import { FormFieldType } from '@/types/formBuilder'
-import type { PublicFormField } from '@/types/formBuilder'
+import { FormFieldType } from '../types/formBuilder'
+import type { PublicFormField } from '../types/formBuilder'
 
 export type Validator = (value: unknown) => true | string