Contrat du package npm

Cette page décrit le contrat de publication de @vevedh/qform-builder-layer.

Nom du package

@vevedh/qform-builder-layer

Mode d’intégration

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

Exports publics

{
  ".": {
    "types": "./app/types.ts",
    "default": "./nuxt.config.ts"
  },
  "./nuxt.config": "./nuxt.config.ts",
  "./formkit.config": "./formkit.config.ts",
  "./types": {
    "types": "./app/types.ts",
    "default": "./app/types.ts"
  },
  "./locales": {
    "types": "./app/locales/index.ts",
    "default": "./app/locales/index.ts"
  },
  "./catalog": {
    "types": "./app/catalog/index.ts",
    "default": "./app/catalog/index.ts"
  },
  "./validation": {
    "types": "./app/validation/index.ts",
    "default": "./app/validation/index.ts"
  },
  "./history": {
    "types": "./app/history/index.ts",
    "default": "./app/history/index.ts"
  },
  "./tree": {
    "types": "./app/tree/index.ts",
    "default": "./app/tree/index.ts"
  },
  "./theme": {
    "types": "./app/theme/index.ts",
    "default": "./app/theme/index.ts"
  },
  "./conditions": {
    "types": "./app/conditions/index.ts",
    "default": "./app/conditions/index.ts"
  },
  "./templates": {
    "types": "./app/templates/index.ts",
    "default": "./app/templates/index.ts"
  },
  "./accessibility": {
    "types": "./app/accessibility/index.ts",
    "default": "./app/accessibility/index.ts"
  },
  "./quasar-options": {
    "types": "./app/quasar-options/index.ts",
    "default": "./app/quasar-options/index.ts"
  },
  "./schema-transfer": {
    "types": "./app/utils/schemaTransfer.ts",
    "default": "./app/utils/schemaTransfer.ts"
  },
  "./migrations": {
    "types": "./app/migrations/index.ts",
    "default": "./app/migrations/index.ts"
  },
  "./types/*": "./app/types/*.ts",
  "./package.json": "./package.json"
}

Le registre public du catalogue est disponible via :

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

Types recommandés

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

Contrat des colonnes imbriquées

Le type public QFormBuilderColumnDefinition décrit une colonne de q-columns. Il couvre les métadonnées, les décorateurs, le mode de données imbriquées, les largeurs responsive et la collection fields.

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

Fichiers publiés

Le champ files limite volontairement le contenu publié :

app/assets
app/accessibility
app/catalog
app/components
app/composables
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
docs
formkit.config.ts
nuxt.config.ts
README.md
LICENSE
CHANGELOG.md
COMMUNITY_EDITION.md
SECURITY.md

Fichiers non publiés

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

Règles à ne pas casser

1. Ne pas ajouter app/pages dans le layer publié.
2. Ne pas ajouter app/app.vue dans le layer publié.
3. Ne pas forcer ssr: false dans le nuxt.config.ts racine.
4. Ne pas dépendre de chemins générés comme .playground/.nuxt dans le tsconfig.json racine.
5. Ne pas ajouter de code Pro complet dans Community.

Contrat FormKit

Le nuxt.config.ts publié lie @formkit/nuxt au formkit.config.ts du package. Les applications hôtes ne doivent pas remplacer formkit.configFile sans réenregistrer qformBuilderQuasarPlugin.

Le script bun run formkit:check vérifie la cohérence entre le catalogue, le registre runtime et le playground.

Registre de validation

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

Les handlers runtime ne doivent jamais être insérés dans le schéma JSON.

Conditions avancées

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

Le sous-chemin conditions expose un moteur AST pur, sérialisable et borné. Les expressions enregistrées restent compatibles avec le runtime FormKit ; les décisions d’autorisation doivent toujours être recalculées côté Feathers/NFZ.

Arborescence avancée

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

Les helpers de l’arbre sont purs. Les mutations finales restent appliquées par le store multi-instance du builder.

Theme Builder et design tokens

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

Le thème est sérialisable dans settings.theme. Le sous-chemin theme expose les presets, le normaliseur, la fusion profonde et la conversion en variables CSS.

Migrations versionnées

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

Le sous-chemin migrations expose le document canonique, les constantes de version, le registre de migrations et les helpers purs. Les versions futures inconnues sont refusées et les imports historiques restent compatibles.

Registre de modèles

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

Le sous-chemin templates expose uniquement des helpers purs et des définitions sérialisables. Les schémas sont assainis avant application, les valeurs et réglages sont bornés et filtrés, les clés de pollution de prototype sont refusées, les collisions de noms sont réécrites et les objets sources ne sont pas mutés.

API d’accessibilité

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

Le sous-chemin accessibility expose l’API d’annonce localisée et de restitution déterministe du focus. Hors d’une instance de builder, le composable conserve un repli no-op sûr.

Options avancées Quasar

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

Ces helpers sont purs et réutilisables par les applications hôtes. Le rendu HTML de QSelect reste désactivé pour les schémas sérialisables.

Gel candidat de l’API publique

La surface pré-RC est décrite par public-api.manifest.json et contrôlée par :

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

Sous-chemins supplémentaires :

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

Les contrats de composants sont importables directement :

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

Voir Stabilité de l’API publique.