@verbb/plugin-kit-forms 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## Unreleased
+
+## 2.0.0 - 2026-07-19
+
+### Added
+- Initial public release of `@verbb/plugin-kit-forms` — headless schema form engine for Craft CP settings screens.
+- Builtin lazy `$field` keys: `text`, `textarea`, `number`, `select`, `radioGroup`, `lightswitch`, `color`, `checkboxSelect`, `combobox`, `group`, `date`, `codeEditor`.
+- Framework UI bindings consume this package from `@verbb/plugin-kit-react/forms` and `@verbb/plugin-kit-vue/forms`.
+
+### Changed
+- Package versions lockstep with `@verbb/plugin-kit-web`, React/Vue adapters, and related `@verbb/plugin-kit-*` packages at `2.0.0`.

package/LICENSE.md

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

@@ -0,0 +1,62 @@
+# `@verbb/plugin-kit-forms`
+
+Framework-agnostic **SchemaForm engine** — state, validation, schema traversal, and conditions — with **no UI framework dependencies**.
+
+React and Vue layer their own renderer, field components, and registry on top:
+
+- `@verbb/plugin-kit-react/forms`
+- `@verbb/plugin-kit-vue/forms`
+
+Most apps import those surfaces, not this package directly.
+
+## Install
+
+```bash
+npm install @verbb/plugin-kit-forms
+```
+
+## What lives here
+
+| Area | Contents |
+|------|----------|
+| State | `FormStateStore` (`subscribe` / path get-set, errors, touched, dirty) |
+| Validation | `createValidationEngine`, built-in rule handlers (`required`, `min`, `max`, `email`, …) |
+| Schema | `normalizeSchema`, types, traversal, Jexl `evaluateCondition` |
+| i18n | `translate` / `setTranslateFunction` (falls back to `Craft.t`, then the raw message) |
+
+## What stays out
+
+`SchemaFormEngine`, `Field`, registries, and field components are framework-specific. Product-owned fields (handles, element selects, variable pickers, …) are registered by the host app — they are not kit builtins. Styling and controls live in `@verbb/plugin-kit-web`.
+
+Builtin `$field` keys (documented under Forms): `text`, `textarea`, `number`, `select`, `radioGroup`, `lightswitch`, `color`, `checkboxSelect`, `combobox`, `group`, `date`, `codeEditor`.
+
+## Engine usage
+
+```ts
+import {
+  FormStateStore,
+  createValidationEngine,
+  normalizeSchema,
+  setTranslateFunction,
+  type SchemaIndex,
+} from '@verbb/plugin-kit-forms';
+
+setTranslateFunction((category, message, params) => Craft.t(category, message, params));
+
+const store = new FormStateStore(defaultValues);
+const index: SchemaIndex = {
+  schema: normalizeSchema(compiled.schema),
+  fieldEntries: compiled.fieldEntries,
+};
+const { validate } = createValidationEngine(index);
+
+const result = validate(store.state.values);
+```
+
+## Dependencies
+
+Runtime: [`jexl`](https://github.com/TomFrost/jexl), [`lodash-es`](https://lodash.com/). Kept external so consumers dedupe a single copy.
+
+## Docs
+
+[docs.verbb.io/plugin-kit/forms](https://docs.verbb.io/plugin-kit/forms/)

package/dist/index.d.ts

@@ -0,0 +1,170 @@
+export declare const buildGroupedMessage: (message: string, parentLabel?: string, childLabel?: string) => string;
+
+export declare type ConditionDataResolver = (values: FormValues, field?: SchemaNode) => Record<string, unknown>;
+
+export declare const createSchemaFieldIndex: (node: unknown) => {
+    fieldNames: string[];
+    hasField: (fieldName: string) => boolean;
+};
+
+export declare const createValidationEngine: (index: SchemaIndex, options?: {
+    conditionDataResolver?: ConditionDataResolver;
+}) => {
+    validate: (values: FormValues) => ValidationResult;
+};
+
+export declare const emailOrVariableRule: (value: unknown, label: string) => string | null;
+
+export declare const emailRule: (value: unknown, label: string) => string | null;
+
+export declare const evaluateCondition: (condition: string | undefined, data: Record<string, unknown>) => any;
+
+export declare const extractFieldNames: (content: TraversalValue) => string[];
+
+export declare const extractFields: (nodes: TraversalValue) => TraversalNode[];
+
+export declare type FieldEntry = {
+    path: string;
+    field: SchemaNode;
+};
+
+export declare type FormState = {
+    values: Record<string, unknown>;
+    errors: Record<string, string[]>;
+    touched: Set<string>;
+    dirty: Set<string>;
+};
+
+export declare class FormStateStore {
+    state: FormState;
+    private listeners;
+    private initialValues;
+    constructor(initialValues?: Record<string, unknown>);
+    subscribe(listener: FormSubscriber): () => void;
+    notify(): void;
+    getValue(path: string): unknown;
+    setValue(path: string, value: unknown): void;
+    setValues(values: Record<string, unknown>): void;
+    setErrors(errors: Record<string, string[]>): void;
+    clearErrors(): void;
+    setTouched(path: string, touched?: boolean): void;
+    reset(values?: Record<string, unknown>): void;
+}
+
+declare type FormSubscriber = () => void;
+
+export declare type FormValues = Record<string, unknown>;
+
+export declare const getSchemaFieldNames: (node: unknown) => string[];
+
+export declare const handleRule: (value: unknown) => string | null;
+
+export declare const hasSchemaErrors: (errors: Record<string, unknown> | undefined, node: unknown) => boolean;
+
+export declare const isRequiredRuleName: (ruleName: string) => boolean;
+
+export declare const maxRule: (value: unknown, label: string, args: string[]) => string | null;
+
+export declare const minRule: (value: unknown, label: string, args: string[]) => string | null;
+
+export declare type NestedFormApi = {
+    path: string;
+    validate: () => {
+        fields: Record<string, string[]>;
+    } | undefined;
+    getValues: () => FormValues;
+};
+
+export declare const normalizeSchema: (items: SchemaRenderable, path?: string) => SchemaRenderable;
+
+export declare const REQUIRED_RULE_NAMES: Set<string>;
+
+/**
+ * Required check for TipTap/ProseMirror JSON fields (`validation: 'requiredRichText'`).
+ * Empty docs are JSON (`[]` / bare paragraphs), not `''` — handled via `isEmptyValue`.
+ */
+export declare const requiredRichTextRule: (value: unknown, label: string) => string | null;
+
+export declare const requiredRule: (value: unknown, label: string) => string | null;
+
+declare type RuleContext = {
+    path: string;
+    values: Record<string, unknown>;
+    field: SchemaNode;
+};
+
+export declare type RuleHandler = (value: unknown, label: string, args: string[], context?: RuleHandlerContext) => string | null;
+
+export declare type RuleHandlerContext = {
+    path: string;
+    values: Record<string, unknown>;
+    field: SchemaNode;
+};
+
+export declare const ruleHandlers: Record<string, RuleHandler>;
+
+export declare type SchemaFieldApi = {
+    state: {
+        value: unknown;
+    };
+    handleChange: (valueOrEvent: unknown) => void;
+    handleBlur: () => void;
+    errors: string[];
+};
+
+export declare type SchemaIndex = {
+    schema: SchemaRenderable;
+    fieldEntries: FieldEntry[];
+};
+
+export declare type SchemaNode = {
+    _id?: string;
+    _data?: Record<string, unknown>;
+    _scopePath?: string;
+    name?: string;
+    label?: string;
+    required?: boolean;
+    validation?: string;
+    columns?: unknown[];
+    children?: SchemaRenderable;
+    schema?: SchemaRenderable;
+    schemaChildPrefix?: string;
+    $field?: string;
+    $cmp?: string;
+    $el?: string;
+    type?: string;
+    if?: string;
+    hideOnIf?: boolean;
+    attrs?: Record<string, unknown>;
+    props?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+
+export declare type SchemaRenderable = SchemaNode | string | SchemaRenderable[];
+
+export declare const setTranslateFunction: (fn?: (category: string, message: string, params?: TranslateParams) => string) => void;
+
+export declare const setTranslationCategory: (category: string) => void;
+
+export declare const translate: (message: string, params?: TranslateParams) => string;
+
+export declare type TranslateParams = Record<string, string>;
+
+declare type TraversalNode = Record<string, unknown> & {
+    $field?: string;
+    name?: string;
+    children?: TraversalValue;
+    schema?: TraversalValue;
+};
+
+declare type TraversalValue = TraversalNode | TraversalNode[] | null | undefined;
+
+export declare const traverseSchema: (node: TraversalValue, visitor: (node: TraversalNode) => void) => void;
+
+export declare const uniqueHandleRule: (value: unknown, label: string, args: string[], context?: RuleContext) => string | null;
+
+export declare type ValidationResult = {
+    fields: Record<string, string[]>;
+} | undefined;
+
+export { }