@xelqun/forms 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jay-Are Ocero
+
+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

@@ -1,3 +1,117 @@
-# Temporary Holding Version
+# Xelqun 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.
+PHP-defined, schema-driven forms for **Laravel + Inertia + Vue**. You describe a form in PHP, the package turns it into a versioned JSON schema, and generic Vue components render it. No Vue to write for normal forms.
+
+> **Status: pre-alpha.** The API will change. Built and tested against Laravel 13, Inertia 3, Vue 3.5 and Tailwind 4.
+
+```php
+class OrderForm extends Form
+{
+    public function schema(): array
+    {
+        return [
+            TextInput::make('customer')->required(),
+            Select::make('country_id')->relationship('country', 'name')
+                ->afterStateUpdated(fn (Set $set) => $set('state_id', null)),
+            Select::make('state_id')
+                ->options(fn (Get $get) => State::where('country_id', $get('country_id'))->pluck('name', 'id')),
+            Section::make('Business')->visibleWhen(When::eq('type', 'business'))->schema([
+                TextInput::make('company')->requiredWhen(When::eq('type', 'business')),
+            ]),
+            Repeater::make('items')->relationship()->schema([
+                TextInput::make('qty')->numeric(),
+                TextInput::make('price')->numeric(),
+                TextInput::make('subtotal')->computed('qty * price')->disabled(),
+            ]),
+            TextInput::make('total')->computed('sum(items.*.subtotal)')->disabled(),
+        ];
+    }
+}
+```
+
+## How it works
+
+- **Three tiers of rules.** Declarative conditions (`visibleWhen`, `requiredWhen`, `disabledWhen`) and calculations (`computed('qty * price')`) run in the browser with no server call. The server re-checks every condition, drops hidden values and recomputes every total on submit. Server closures (`options(fn (Get $get) => ...)`, `afterStateUpdated`) run only on the server.
+- **Automatic dependency tracking.** Closures read state through `Get`, which records what they read. The browser calls the server only when one of those paths changes, and the response is a small patch that is merged in place, so focus and cursor position are kept.
+- **Secure by default.** Forms are rebuilt on the server from an encrypted token (never a class name from the client). Every endpoint re-runs `authorize()` and validation.
+- **Stable row keys.** Repeater rows are keyed by UUIDs (or `record-{id}`), so Laravel validation errors map straight onto nested fields.
+- **Uploads stay out of the form state.** Files upload as soon as they are picked, and the state only holds a short token until the form is saved.
+
+## Installation
+
+```bash
+composer require xelqun/forms && php artisan xelqun-forms:install
+```
+
+The installer adds the matching version of the `@xelqun/forms` npm package with your package manager (npm, pnpm, Yarn or Bun, detected from the lockfile). It then adds the plugin to `resources/js/app.ts` and the stylesheet to `resources/css/app.css`. It's safe to run again, so run it after `composer update` to bring the npm package up to the same version.
+
+Use `--config` to publish the config file, or `--without-node` to skip the npm step. If the installer can't edit a file safely, it leaves the file alone and prints the step to do by hand:
+
+```ts
+// resources/js/app.ts
+import { createXelqunForms } from '@xelqun/forms';
+
+createInertiaApp({
+    withApp: (app) => app.use(createXelqunForms()),
+});
+```
+
+```css
+/* resources/css/app.css */
+@import 'tailwindcss';
+@import '@xelqun/forms/style.css';
+```
+
+Then render a form:
+
+```php
+// controller
+return Inertia::render('Orders/Edit', ['form' => OrderForm::make($order)->toSchema()]);
+
+public function update(Request $request, Order $order)
+{
+    OrderForm::make($order)->save($request);
+
+    return back();
+}
+```
+
+```vue
+<script setup lang="ts">
+import { XqForm, type FormSchema } from '@xelqun/forms';
+
+defineProps<{ form: FormSchema; orderId: number }>();
+</script>
+
+<template>
+    <XqForm :form="form" :action="`/orders/${orderId}`" method="put" />
+</template>
+```
+
+Section titles start at `h2`. If the form sits lower in your page's heading order, set it with `<XqForm :heading-level="3" />`.
+
+Components use their own `--xq-*` design tokens and `Xq*` names, so they work next to an app's own shadcn-vue components. Dark mode follows a `.dark` class or `[data-xq-theme=dark]`.
+
+## Security
+
+- **Schedule the cleanup.** Temporary uploads stay on disk until `php artisan xelqun-forms:prune-uploads` removes them, so run it from your scheduler.
+- **Authorize in `authorize()`.** `validate()`, `save()` and every internal endpoint call it, and it allows everything by default.
+- **Use `hidden()` to protect a field, not `visibleWhen()`.** `visibleWhen()` runs against state the browser controls. `hidden()` also blocks the field's search, upload and hooks.
+- **`Hidden` fields are not secret or read-only.** Their value comes back from the browser, so use `disabled()` for values users must not change.
+- **A disabled field submits what it was filled with**, even with `dehydrated()`, because the browser can't be trusted to send it back unchanged. To save a value the server derives, set it in `mutateBeforeSave()`.
+- **Limit uploads.** Without `acceptedFileTypes()` or `image()`, a field accepts any file except types a web server may run or a browser may treat as a page.
+
+## Development
+
+```bash
+composer install && vendor/bin/pest          # PHP tests
+npm install && npx vp test                   # Vitest
+vendor/bin/pint && vendor/bin/phpstan analyse
+npx vp check && npx vue-tsc --noEmit
+```
+
+The conformance fixtures in `tests/Fixtures/conformance` run in both Pest and Vitest, so the PHP and browser evaluators always agree. See [`docs/forms-plan.md`](docs/forms-plan.md) for the design.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,57 @@
 {
-  "name": "@xelqun/forms",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@xelqun/forms",
+    "version": "0.1.1",
+    "description": "Vue renderer for Xelqun Forms: PHP-defined, schema-driven forms for Laravel + Inertia.",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/199ocero/xelqun-forms.git"
+    },
+    "files": [
+        "resources/js",
+        "resources/css"
+    ],
+    "type": "module",
+    "sideEffects": [
+        "*.css",
+        "*.vue"
+    ],
+    "exports": {
+        ".": "./resources/js/index.ts",
+        "./style.css": "./resources/css/xelqun.css"
+    },
+    "scripts": {
+        "test": "vp test",
+        "check": "vp check",
+        "check:fix": "vp check --fix",
+        "types:check": "vue-tsc --noEmit"
+    },
+    "dependencies": {
+        "@internationalized/date": "^3.12.4",
+        "class-variance-authority": "^0.7.1",
+        "clsx": "^2.1.1",
+        "lucide-vue-next": "^1.0.0",
+        "reka-ui": "^2.11.0",
+        "tailwind-merge": "^3.2.0"
+    },
+    "devDependencies": {
+        "@inertiajs/vue3": "^3.0.0",
+        "@vitejs/plugin-vue": "^6.0.0",
+        "@vue/test-utils": "^2.4.6",
+        "happy-dom": "^21.0.4",
+        "typescript": "^5.2.2",
+        "vite-plus": "1.4.0",
+        "vitest": "^5.0.5",
+        "vue": "^3.5.13",
+        "vue-tsc": "^3.3.13"
+    },
+    "peerDependencies": {
+        "@inertiajs/vue3": "^3.0.0",
+        "vue": "^3.5.0"
+    },
+    "overrides": {
+        "glob": "^14.0.2",
+        "minimatch": "^11.0.1",
+        "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0"
+    }
+}

package/resources/css/xelqun.css

@@ -0,0 +1,162 @@
+/*
+ * Xelqun Forms styles. Import once in the app's Tailwind entry:
+ *   @import '@xelqun/forms/style.css';
+ * The @source below makes Tailwind scan the package's components.
+ */
+@source "../js";
+
+@theme inline {
+    --color-xq-background: var(--xq-background);
+    --color-xq-foreground: var(--xq-foreground);
+    --color-xq-card: var(--xq-card);
+    --color-xq-card-foreground: var(--xq-card-foreground);
+    --color-xq-popover: var(--xq-popover);
+    --color-xq-popover-foreground: var(--xq-popover-foreground);
+    --color-xq-primary: var(--xq-primary);
+    --color-xq-primary-foreground: var(--xq-primary-foreground);
+    --color-xq-secondary: var(--xq-secondary);
+    --color-xq-secondary-foreground: var(--xq-secondary-foreground);
+    --color-xq-muted: var(--xq-muted);
+    --color-xq-muted-foreground: var(--xq-muted-foreground);
+    --color-xq-accent: var(--xq-accent);
+    --color-xq-accent-foreground: var(--xq-accent-foreground);
+    --color-xq-destructive: var(--xq-destructive);
+    --color-xq-destructive-foreground: var(--xq-destructive-foreground);
+    --color-xq-success: var(--xq-success);
+    --color-xq-border: var(--xq-border);
+    --color-xq-input: var(--xq-input);
+    --color-xq-ring: var(--xq-ring);
+    --radius-xq-sm: calc(var(--xq-radius) - 4px);
+    --radius-xq-md: calc(var(--xq-radius) - 2px);
+    --radius-xq-lg: var(--xq-radius);
+    --radius-xq-xl: calc(var(--xq-radius) + 4px);
+}
+
+:root {
+    --xq-radius: 0.625rem;
+    --xq-background: oklch(1 0 0);
+    --xq-foreground: oklch(0.2 0.01 270);
+    --xq-card: oklch(1 0 0);
+    --xq-card-foreground: oklch(0.2 0.01 270);
+    --xq-popover: oklch(1 0 0);
+    --xq-popover-foreground: oklch(0.2 0.01 270);
+    --xq-primary: oklch(0.5 0.2 272);
+    --xq-primary-foreground: oklch(0.99 0 0);
+    --xq-secondary: oklch(0.96 0.006 270);
+    --xq-secondary-foreground: oklch(0.25 0.02 270);
+    --xq-muted: oklch(0.965 0.004 270);
+    --xq-muted-foreground: oklch(0.52 0.015 270);
+    --xq-accent: oklch(0.955 0.012 272);
+    --xq-accent-foreground: oklch(0.25 0.04 272);
+    --xq-destructive: oklch(0.54 0.22 27);
+    --xq-destructive-foreground: oklch(0.99 0 0);
+    --xq-success: oklch(0.47 0.12 155);
+    --xq-border: oklch(0.915 0.006 270);
+    --xq-input: oklch(0.885 0.008 270);
+    --xq-ring: oklch(0.55 0.19 272);
+}
+
+.dark,
+[data-xq-theme='dark'] {
+    --xq-background: oklch(0.17 0.008 270);
+    --xq-foreground: oklch(0.97 0.004 270);
+    --xq-card: oklch(0.205 0.01 270);
+    --xq-card-foreground: oklch(0.97 0.004 270);
+    --xq-popover: oklch(0.22 0.01 270);
+    --xq-popover-foreground: oklch(0.97 0.004 270);
+    --xq-primary: oklch(0.68 0.16 272);
+    --xq-primary-foreground: oklch(0.16 0.02 272);
+    --xq-secondary: oklch(0.27 0.012 270);
+    --xq-secondary-foreground: oklch(0.95 0.004 270);
+    --xq-muted: oklch(0.25 0.01 270);
+    --xq-muted-foreground: oklch(0.7 0.012 270);
+    --xq-accent: oklch(0.28 0.025 272);
+    --xq-accent-foreground: oklch(0.96 0.01 272);
+    --xq-destructive: oklch(0.68 0.19 25);
+    --xq-destructive-foreground: oklch(0.17 0.02 25);
+    --xq-success: oklch(0.72 0.15 155);
+    --xq-border: oklch(1 0 0 / 10%);
+    --xq-input: oklch(1 0 0 / 14%);
+    --xq-ring: oklch(0.68 0.16 272);
+}
+
+/*
+ * Responsive grid driven by CSS variables set from the schema
+ * (see gridStyle() and spanStyle() in composables/layout.ts).
+ */
+/* Custom properties inherit, so reset them at each level to keep nested grids independent. */
+.xq-grid {
+    --xq-span: initial;
+    --xq-span-sm: initial;
+    --xq-span-md: initial;
+    --xq-span-lg: initial;
+    --xq-span-xl: initial;
+    display: grid;
+    gap: 1.25rem 1rem;
+    grid-template-columns: repeat(var(--xq-cols, 1), minmax(0, 1fr));
+}
+
+.xq-cell {
+    --xq-cols: initial;
+    --xq-cols-sm: initial;
+    --xq-cols-md: initial;
+    --xq-cols-lg: initial;
+    --xq-cols-xl: initial;
+    min-width: 0;
+    grid-column: var(--xq-span, auto);
+}
+
+@media (min-width: 40rem) {
+    .xq-grid {
+        grid-template-columns: repeat(var(--xq-cols-sm, var(--xq-cols, 1)), minmax(0, 1fr));
+    }
+
+    .xq-cell {
+        grid-column: var(--xq-span-sm, var(--xq-span, auto));
+    }
+}
+
+@media (min-width: 48rem) {
+    .xq-grid {
+        grid-template-columns: repeat(
+            var(--xq-cols-md, var(--xq-cols-sm, var(--xq-cols, 1))),
+            minmax(0, 1fr)
+        );
+    }
+
+    .xq-cell {
+        grid-column: var(--xq-span-md, var(--xq-span-sm, var(--xq-span, auto)));
+    }
+}
+
+@media (min-width: 64rem) {
+    .xq-grid {
+        grid-template-columns: repeat(
+            var(--xq-cols-lg, var(--xq-cols-md, var(--xq-cols-sm, var(--xq-cols, 1)))),
+            minmax(0, 1fr)
+        );
+    }
+
+    .xq-cell {
+        grid-column: var(--xq-span-lg, var(--xq-span-md, var(--xq-span-sm, var(--xq-span, auto))));
+    }
+}
+
+@media (min-width: 80rem) {
+    .xq-grid {
+        grid-template-columns: repeat(
+            var(
+                --xq-cols-xl,
+                var(--xq-cols-lg, var(--xq-cols-md, var(--xq-cols-sm, var(--xq-cols, 1))))
+            ),
+            minmax(0, 1fr)
+        );
+    }
+
+    .xq-cell {
+        grid-column: var(
+            --xq-span-xl,
+            var(--xq-span-lg, var(--xq-span-md, var(--xq-span-sm, var(--xq-span, auto))))
+        );
+    }
+}

package/resources/js/components/XqFieldWrapper.vue

@@ -0,0 +1,59 @@
+<script setup lang="ts">
+import { LoaderCircle } from 'lucide-vue-next';
+import { computed } from 'vue';
+import { useFormStore } from '../composables/context';
+import type { SchemaNode } from '../schema/types';
+import XqLabel from '../ui/XqLabel.vue';
+
+const props = defineProps<{
+    node: SchemaNode;
+    id: string;
+    /** The control the label points at, or null when it only names a group. */
+    labelFor?: string | null;
+    /** Announce the error as soon as it appears, for errors outside a submit. */
+    announceError?: boolean;
+    error?: string | null;
+    required?: boolean;
+    hideLabel?: boolean;
+}>();
+
+const store = useFormStore();
+const loading = computed(() => store.isLoading(props.node));
+</script>
+
+<template>
+    <div
+        class="gap-2 grid"
+        :data-xq-path="node.path"
+        :data-invalid="error ? '' : undefined"
+        :aria-busy="loading || undefined"
+    >
+        <XqLabel
+            v-if="node.label && !hideLabel"
+            :id="`${id}-label`"
+            :for="labelFor === null ? undefined : (labelFor ?? id)"
+            class="gap-0.5"
+        >
+            {{ node.label }}
+            <span v-if="required" class="text-xq-destructive" aria-hidden="true">*</span>
+            <span v-if="required" class="sr-only">(required)</span>
+            <LoaderCircle
+                v-if="loading"
+                class="ml-1 size-3 motion-safe:animate-spin text-xq-muted-foreground"
+                aria-hidden="true"
+            />
+        </XqLabel>
+        <slot />
+        <p v-if="node.hint && !error" :id="`${id}-hint`" class="text-xs text-xq-muted-foreground">
+            {{ node.hint }}
+        </p>
+        <p
+            v-if="error"
+            :id="`${id}-error`"
+            :role="announceError ? 'alert' : undefined"
+            class="text-xs font-medium text-xq-destructive"
+        >
+            {{ error }}
+        </p>
+    </div>
+</template>

package/resources/js/components/XqForm.vue

@@ -0,0 +1,128 @@
+<script setup lang="ts">
+import { CircleAlert } from 'lucide-vue-next';
+import { computed, inject, onMounted, provide, ref } from 'vue';
+import { HEADING_LEVEL, provideFormStore } from '../composables/context';
+import { REGISTRY } from '../composables/registry';
+import { useXqForm } from '../composables/useXqForm';
+import type { FormStore } from '../core/store';
+import { cn } from '../lib/utils';
+import type { FormSchema } from '../schema/types';
+import XqButton from '../ui/XqButton.vue';
+import { createRegistry } from './defaults';
+import XqNode from './XqNode.vue';
+
+const props = withDefaults(
+    defineProps<{
+        form: FormStore | FormSchema;
+        action?: string;
+        method?: 'post' | 'put' | 'patch';
+        submitLabel?: string;
+        preserveState?: boolean | 'errors';
+        /** Heading level of top-level section titles. Set it to fit the page around the form. */
+        headingLevel?: 2 | 3 | 4 | 5 | 6;
+        class?: string;
+    }>(),
+    { method: 'post', submitLabel: 'Save', headingLevel: 2, preserveState: 'errors' },
+);
+const emit = defineEmits<{
+    submit: [store: FormStore];
+    success: [page: unknown];
+    error: [errors: Record<string, string>];
+}>();
+
+function isStore(value: FormStore | FormSchema): value is FormStore {
+    return 'state' in value && 'submit' in value && typeof value.submit === 'function';
+}
+
+const store = isStore(props.form) ? props.form : useXqForm(props.form);
+const { processing, uploading, fatalError, liveError } = store;
+const syncing = store.queue.busy;
+const errorCount = computed(() => Object.keys(store.errors).length);
+
+provideFormStore(store);
+provide(HEADING_LEVEL, props.headingLevel);
+provide(REGISTRY, inject(REGISTRY, null) ?? createRegistry());
+
+const root = ref<HTMLFormElement | null>(null);
+
+onMounted(() => {
+    store.root.value = root.value;
+});
+
+function submit(): void {
+    if (!props.action) {
+        emit('submit', store);
+
+        return;
+    }
+
+    void store.submit(props.action, {
+        method: props.method,
+        preserveState: props.preserveState,
+        onSuccess: (page) => emit('success', page),
+        onError: (errors) => emit('error', errors),
+    });
+}
+</script>
+
+<template>
+    <form
+        ref="root"
+        :class="cn('xq-form gap-6 grid', props.class)"
+        :data-xq-form="store.id"
+        novalidate
+        @submit.prevent="submit"
+    >
+        <div class="xq-grid">
+            <XqNode v-for="node in store.components" :key="node.key" :node="node" />
+        </div>
+        <p role="status" class="sr-only">
+            <template v-if="errorCount">
+                {{ errorCount }} {{ errorCount === 1 ? 'field needs' : 'fields need' }} attention.
+            </template>
+        </p>
+        <div
+            v-if="fatalError"
+            role="alert"
+            class="bottom-4 gap-2 px-3 py-2 text-sm shadow-lg sticky z-10 flex items-start rounded-xq-md border border-xq-destructive/40 bg-xq-card text-xq-destructive"
+        >
+            <CircleAlert class="mt-0.5 size-4 shrink-0" />
+            {{ fatalError }}
+        </div>
+        <div
+            v-if="liveError"
+            role="alert"
+            class="bottom-4 gap-3 px-3 py-2 text-sm shadow-lg sticky z-10 flex items-center justify-between rounded-xq-md border border-xq-destructive/40 bg-xq-card text-xq-destructive"
+        >
+            <span class="gap-2 flex items-start">
+                <CircleAlert class="mt-0.5 size-4 shrink-0" />
+                {{ liveError }}
+            </span>
+            <XqButton
+                type="button"
+                variant="outline"
+                size="sm"
+                :disabled="syncing"
+                @click="store.queue.retry()"
+            >
+                Try again
+            </XqButton>
+        </div>
+        <slot
+            name="actions"
+            :store="store"
+            :processing="processing"
+            :uploading="uploading"
+            :submit="submit"
+        >
+            <div v-if="action" class="gap-3 flex items-center justify-end">
+                <span v-if="uploading" class="text-xs text-xq-muted-foreground"
+                    >Waiting for uploads…</span
+                >
+                <XqButton type="submit" :disabled="processing">
+                    {{ processing ? 'Saving…' : submitLabel }}
+                </XqButton>
+            </div>
+        </slot>
+    </form>
+</template>

package/resources/js/components/XqNode.vue

@@ -0,0 +1,22 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useFormStore } from '../composables/context';
+import { spanStyle } from '../composables/layout';
+import { useRegistry } from '../composables/registry';
+import type { SchemaNode } from '../schema/types';
+import XqUnknownNode from './XqUnknownNode.vue';
+
+const props = defineProps<{ node: SchemaNode }>();
+const store = useFormStore();
+const registry = useRegistry();
+
+const visible = computed(() => props.node.type !== 'hidden' && store.isVisible(props.node));
+const component = computed(() => registry?.get(props.node.type) ?? null);
+</script>
+
+<template>
+    <div v-if="visible" class="xq-cell" :style="spanStyle(node.span)" :data-xq-key="node.key">
+        <component :is="component" v-if="component" :node="node" />
+        <XqUnknownNode v-else :node="node" />
+    </div>
+</template>

package/resources/js/components/XqUnknownNode.vue

@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import type { SchemaNode } from '../schema/types';
+
+defineProps<{ node: SchemaNode }>();
+</script>
+
+<template>
+    <div
+        class="px-3 py-2 text-xs rounded-xq-md border border-dashed border-xq-destructive/50 bg-xq-destructive/5 text-xq-destructive"
+    >
+        No component is registered for type
+        <code class="font-mono font-semibold">{{ node.type }}</code> ({{ node.key }}). Register one
+        with <code class="font-mono">createXelqunForms({ components })</code>.
+    </div>
+</template>

package/resources/js/components/defaults.ts

@@ -0,0 +1,44 @@
+import { toComponent } from '../composables/registry';
+import type { ComponentRegistry, ComponentResolver } from '../composables/registry';
+import XqCheckboxField from './fields/XqCheckboxField.vue';
+import XqRadioField from './fields/XqRadioField.vue';
+import XqRepeaterField from './fields/XqRepeaterField.vue';
+import XqSelectField from './fields/XqSelectField.vue';
+import XqTextareaField from './fields/XqTextareaField.vue';
+import XqTextInputField from './fields/XqTextInputField.vue';
+import XqToggleField from './fields/XqToggleField.vue';
+import XqFieldset from './layouts/XqFieldset.vue';
+import XqGrid from './layouts/XqGrid.vue';
+import XqSection from './layouts/XqSection.vue';
+import XqTabsLayout from './layouts/XqTabsLayout.vue';
+
+/**
+ * Built-in renderers keyed by schema node type. Heavier fields are code-split.
+ */
+export function defaultComponents(): Record<string, ComponentResolver> {
+    return {
+        'text-input': XqTextInputField,
+        textarea: XqTextareaField,
+        select: XqSelectField,
+        checkbox: XqCheckboxField,
+        toggle: XqToggleField,
+        radio: XqRadioField,
+        'date-picker': () => import('./fields/XqDatePickerField.vue'),
+        'file-upload': () => import('./fields/XqFileUploadField.vue'),
+        repeater: XqRepeaterField,
+        section: XqSection,
+        grid: XqGrid,
+        fieldset: XqFieldset,
+        tabs: XqTabsLayout,
+    };
+}
+
+export function createRegistry(custom: Record<string, ComponentResolver> = {}): ComponentRegistry {
+    const registry: ComponentRegistry = new Map();
+
+    for (const [type, resolver] of Object.entries({ ...defaultComponents(), ...custom })) {
+        registry.set(type, toComponent(resolver));
+    }
+
+    return registry;
+}