npm package contract

This page describes the publication contract of @vevedh/qform-builder-layer.

Package name

@vevedh/qform-builder-layer

Integration mode

export default defineNuxtConfig({
  extends: ['@vevedh/qform-builder-layer'],
})

Public exports

import type {
  FormBuilderSchema,
  FormBuilderValues,
  FormBuilderSavePayload,
  FormBuilderPublicApi,
  QFormBuilderLocale,
  QFormBuilderLocaleRegistry,
  QFormBuilderColumnDefinition,
  QFormBuilderValidationRuleRegistry,
  QFormBuilderThemeConfig,
  QFormBuilderConditionTree,
  QFormBuilderTemplateRegistry,
} from '@vevedh/qform-builder-layer/types'

Additional public subpaths include:

@vevedh/qform-builder-layer/catalog
@vevedh/qform-builder-layer/validation
@vevedh/qform-builder-layer/history
@vevedh/qform-builder-layer/tree
@vevedh/qform-builder-layer/theme
@vevedh/qform-builder-layer/conditions
@vevedh/qform-builder-layer/templates
@vevedh/qform-builder-layer/migrations
@vevedh/qform-builder-layer/schema-transfer
@vevedh/qform-builder-layer/quasar-options
@vevedh/qform-builder-layer/accessibility

The built-in locale dictionaries are also exported through:

import {
  enQFormBuilderLocale,
  frQFormBuilderLocale,
} from '@vevedh/qform-builder-layer/locales'

The public catalog registry is available through:

import {
  createCommunityCatalog,
  defineQFormElement,
  mergeQFormBuilderCatalog,
} from '@vevedh/qform-builder-layer/catalog'

Recommended types

Use the package types instead of copying internal implementation types from the source tree.

Nested column contract

The public QFormBuilderColumnDefinition type describes a q-columns column. It includes metadata, decorators, nested-data mode, responsive widths and the fields collection.

import type { QFormBuilderColumnDefinition } from '@vevedh/qform-builder-layer/types'

Published files

The npm package contains:

app/assets
app/catalog
app/components
app/composables
app/accessibility
app/constants
app/stores
app/locales
app/types
app/types.ts
app/conditions
app/history
app/tree
app/theme
app/migrations
app/templates
app/quasar-options
app/utils
app/validation
formkit.config.ts
nuxt.config.ts
README.md
LICENSE
CHANGELOG.md
COMMUNITY_EDITION.md
SECURITY.md
RELEASE_CHECKLIST.md
CONTRIBUTING.md

Files not published

The package must not include:

.playground
.nuxt
.output
node_modules
PROMPT_CONTEXT.md
patch-memory/PATCH_*.md
*.zip

Rules that must not be broken

• Do not inject demo routes into host applications.
• Do not force ssr: false from the layer.
• Do not use host-app aliases for internal runtime imports.
• Keep Pro features in separate packages.
• Keep French and English documentation page trees synchronized.

FormKit contract

The published nuxt.config.ts binds @formkit/nuxt to the package formkit.config.ts. Host applications must not replace formkit.configFile without registering qformBuilderQuasarPlugin again.

The bun run formkit:check script validates consistency across the catalog, runtime registry and playground.

Validation registry

import type { QFormBuilderValidationRuleRegistry } from '@vevedh/qform-builder-layer/types'
import { validateQFormBuilderRegex } from '@vevedh/qform-builder-layer/validation'

Runtime handlers must never be inserted into the JSON schema.

Advanced conditions

import type { QFormBuilderConditionTree } from '@vevedh/qform-builder-layer/types'
import {
  evaluateQFormBuilderConditionTree,
  parseQFormBuilderConditionExpression,
  serializeQFormBuilderConditionTree,
} from '@vevedh/qform-builder-layer/conditions'

The conditions subpath exposes a pure, serializable and bounded AST engine. Saved expressions remain compatible with the FormKit runtime; authorization decisions must always be enforced again in the Feathers/NFZ service.

Advanced tree

import type { QFormBuilderTreeDropIntent } from '@vevedh/qform-builder-layer/types'
import { resolveQFormBuilderTreeDropIntent } from '@vevedh/qform-builder-layer/tree'

Tree helpers are pure. Final mutations remain owned by the builder's multi-instance store.

Theme Builder and design tokens

import type { QFormBuilderThemeConfig } from '@vevedh/qform-builder-layer/types'
import { createQFormBuilderTheme } from '@vevedh/qform-builder-layer/theme'

The theme is serializable under settings.theme. The theme subpath exposes presets, normalization, deep merge, and CSS-variable generation.

Versioned migrations

import type { QFormBuilderDocument } from '@vevedh/qform-builder-layer/types'
import {
  createQFormBuilderDocument,
  migrateQFormBuilderDocument,
  parseQFormBuilderDocument,
} from '@vevedh/qform-builder-layer/migrations'

The migrations subpath exposes the canonical document, version constants, migration registry, and pure helpers. Unknown future versions are rejected while historical imports remain compatible.

Template registry

import type { QFormBuilderTemplateRegistry } from '@vevedh/qform-builder-layer/types'
import {
  applyQFormBuilderTemplate,
  defineQFormTemplate,
  mergeQFormBuilderTemplates,
} from '@vevedh/qform-builder-layer/templates'

The templates subpath exposes pure helpers and serializable definitions only. Schemas are sanitized before application, values and settings are bounded and allow-listed, prototype-pollution keys are rejected, name collisions are rewritten, and source objects are not mutated.

Accessibility API

import {
  useFormBuilderAccessibility,
  type QFormBuilderAccessibilityApi,
} from '@vevedh/qform-builder-layer/accessibility'

The accessibility subpath exposes localized announcements and deterministic focus restoration. Outside a builder instance, the composable keeps a safe no-op fallback.

Advanced Quasar options

import {
  filterQFormBuilderSelectOptions,
  normalizeQFormBuilderCssSize,
  normalizeQFormBuilderSelectModel,
  resolveQFormBuilderEditorToolbar,
} from '@vevedh/qform-builder-layer/quasar-options'

These helpers are pure and reusable by host applications. QSelect HTML rendering remains disabled for serializable schemas.

Candidate public API freeze

The pre-RC surface is described by public-api.manifest.json and enforced by:

bun run api:contract:check
bun run typecheck:contract

Additional subpaths:

@vevedh/qform-builder-layer/contract
@vevedh/qform-builder-layer/contract-manifest

Component contracts can be imported directly:

import type {
  FormBuilderProps,
  FormBuilderEvents,
  FormBuilderPublicApi,
  FormViewerProps,
  FormViewerEvents,
} from '@vevedh/qform-builder-layer/types'

See Public API stability.