@streamline-pulse/formkrafter-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Streamline Pulse
+
+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,116 @@
+# @streamline-pulse/formkrafter-core
+
+The framework-agnostic heart of FormKrafter: form **specs**, immutable **mutation ops**, **validation**, a sandboxed **rules engine**, and injectable **services**. No DOM, no framework — it runs in browsers, Node, Bun, and workers alike.
+
+## The spec
+
+A form is a tree of `BrickSpec` nodes. Each brick has a `type` (`input`, `panel`, `collection`, `output`, `action`), an `id` (which registered brick renders it), `configs` (with a unique `uid` and a data `key`), plus optional `validations`, `rules`, `styles`, and `children`.
+
+```mermaid
+flowchart TD
+    F["panel · column<br/>key: form"] --> N["input · text<br/>key: name · required"]
+    F --> A["input · address<br/>key: address"]
+    F --> G["collection · data-grid<br/>key: contacts"]
+    G --> E["input · email<br/>key: email (per row)"]
+    G --> R["input · text<br/>key: role (per row)"]
+```
+
+Form data is a flat `Record<key, value>` — except inside a `collection`, where each row is its own scoped record: `{ name: 'Ada', contacts: [{ email, role }, …] }`.
+
+## Mutating specs: ops, patches, undo
+
+Never mutate a spec in place. Every operation returns a new spec plus RFC 6902 patches in both directions:
+
+```ts
+import { addBrick, moveBrick, removeBrick, updateBrickConfigs, SpecHistory } from '@streamline-pulse/formkrafter-core'
+
+const update = moveBrick(spec, '0.0', '0.2.0')   // dot-paths, pre-removal coordinates
+// update = { spec, patches, inverse }            // RFC 6902 both ways
+
+const history = new SpecHistory()
+history.record(update)
+spec = history.undo(update.spec)                  // and .redo(), .canUndo, .canRedo
+```
+
+```mermaid
+flowchart LR
+    S0[spec] -->|"moveBrick(spec, from, to)"| U["{ spec', patches, inverse }"]
+    U -->|record| H[(SpecHistory)]
+    H -->|undo → apply inverse| S0
+    H -->|redo → apply patches| S1[spec']
+```
+
+Available ops: `addBrick`, `removeBrick`, `moveBrick`, `duplicateBrick` (fresh uids), `updateBrickConfigs`, `updateBrickStyles`, `updateBrickValidations`, `updateBrickRules`. Addressing helpers: `getBrickAt(spec, path)`, `pointerOfUid(spec, uid)`, `iterateBricks(spec)`.
+
+Patches are plain RFC 6902 — persist them, sync them, audit them.
+
+## Validation
+
+Validations live on each brick and compile to a JSON Schema (Ajv + ajv-errors + ajv-formats):
+
+| Validator | Applies to | Parameter |
+|---|---|---|
+| `required` | all | — |
+| `minLength` / `maxLength` / `pattern` / `email` / `url` | string | number / regex |
+| `min` / `max` | number | number |
+| `minItems` / `maxItems` | array | number |
+| `custom` | all | JavaScript (sandboxed) |
+
+**Backend entry point** — same verdict as the frontend, including collection rows and `''`-as-missing semantics:
+
+```ts
+import { validateFormData } from '@streamline-pulse/formkrafter-core'
+
+const { valid, errors } = validateFormData(spec, payload, 'fr')
+// errors: { name: 'Ce champ est obligatoire', 'contacts[0].email': 'Email invalide' }
+```
+
+Messages resolve in cascade: author's message (optionally localized `{ en, fr }`) → built-in localized defaults (`en`/`fr` shipped, extend with `registerValidationMessages('de', {...})`).
+
+## Rules engine — no `eval`
+
+Rules drive dynamic behavior (`hidden`, `disabled`, `required`, computed `value`). Two modes:
+
+- **`jsonLogic`** (default): serializable, declarative — `{ "!": { "in": [{ "var": "country" }, ["FR","DE"]] } }`
+- **`javaScript`**: the escape hatch — executed by a built-in **AST interpreter** (Acorn-based), not `eval`:
+  - CSP-safe (no `unsafe-eval` needed anywhere)
+  - sandboxed: only `dataMap`/`value` plus whitelisted builtins (`Math`, `JSON`, `String`, …) — no `fetch`, no `globalThis`, no `constructor`/`__proto__` escapes
+  - supports expressions, ternaries, `const`/`if`/`return`, optional chaining, arrow functions (`.filter(x => …)`)
+  - unsupported syntax is rejected, runaway code is cut by an execution budget
+
+```ts
+import { runSandboxed, UnsafeEvalJsRunnerService, services } from '@streamline-pulse/formkrafter-core'
+
+runSandboxed('return items.filter((i) => i > 2)', { items: [1, 2, 3] })   // [3]
+
+// trusted environments can opt back into full JS:
+services.jsRunnerService = new UnsafeEvalJsRunnerService()
+```
+
+## Services (dependency injection points)
+
+| Service | Default | Replace when… |
+|---|---|---|
+| `services.jsRunnerService` | AST sandbox | you need full JS in a trusted context |
+| `services.dataSourceService` | `fetch` + per-URL/headers cache | auth, base URL, retry policy:<br/>`new FetchDataSourceService({ credentials: 'include', headers: {...} })` |
+| `services.fileUploadService` | base64 data-URL | real uploads (S3, API): return `{ name, type, size, url }` |
+
+## Shared singleton state
+
+`services` is a **page-wide singleton**, stored on `globalThis` under `Symbol.for("formkrafter.core.services")`. Bundlers routinely end up with several copies of this module in one app (your bundle imports core directly, and the Web Components bundle embeds its own copy) — without the shared store, replacing a service from your app would mutate a copy the components never read.
+
+What this means in practice:
+
+- `services.dataSourceService = …` (or any other override) takes effect **everywhere**, whichever bundle copy executes it — configure once at app startup.
+- Every FormKrafter instance on the page shares the same services, brick registry, and chrome translations. That is the intended behavior for host-level configuration; per-form differences belong in the spec, not in services.
+- The same pattern backs the brick registry and the i18n store in `formkrafter-wc`.
+
+## Localized content
+
+Any text in a spec may be a string or a per-locale object; resolution helpers are exported:
+
+```ts
+{ "label": { "en": "Full name", "fr": "Nom complet" } }
+```
+
+`resolveLocalizedText(value, locale)`, `resolveLocalizedRecord(configs, locale)`, `isLocalizedObject(value)` — validation messages resolve through the same mechanism.

package/dist/brick/brick.d.ts

@@ -0,0 +1,63 @@
+import type { Validator } from "../validators/validator";
+import type { Validation } from "../validators/validation";
+import type { JSONSchemaType } from "../validators/json-schema-type";
+import { type Utils } from "./utils";
+import type { Rule } from "../rules/rule";
+import type { BrickSpec } from "../utils/brick-spec";
+import type { BrickType } from "../utils/brick-type";
+import type { BrickBaseConfigs, CommonBrickProps } from "../utils/common-brick-props";
+import type { BrickMoldDropType } from "../utils/drop-type";
+export interface BrickProps<DataType, Configs extends BrickBaseConfigs, Styles> extends CommonBrickProps<Configs, Styles> {
+    onConfigsChange?: (configs: BrickBaseConfigs & Record<string, unknown>, uid?: string) => void;
+    onStylesChange?: (styles: Record<string, unknown>, uid?: string) => void;
+    data?: DataType;
+    dataMap?: Record<string, unknown>;
+    onDataChange?: (value?: DataType) => void;
+    onMove?: (from: string, to: string) => void;
+    onDuplicate?: (path: string) => void;
+    onDelete?: (path: string) => void;
+    onAddBrick?: (brickMold: BrickMoldDropType, path: string) => void;
+    path: string;
+    error?: string;
+    disabled?: boolean;
+    locale?: string;
+    children?: unknown;
+    brickSpec?: BrickSpec;
+    editable?: boolean;
+    validations?: Validation[];
+    onValidationsChange?: (validations: Validation[], uid?: string) => void;
+    rules?: Rule[];
+    onRulesChange?: (rules: Rule[], uid?: string) => void;
+    utils: Utils;
+}
+export declare abstract class Brick<DataType, Configs extends BrickBaseConfigs, Styles extends Record<string, unknown>> {
+    readonly type: BrickType;
+    readonly dataType: JSONSchemaType;
+    readonly id: string;
+    readonly name: string;
+    readonly configsForm?: BrickSpec;
+    readonly category?: string;
+    readonly styles?: Styles;
+    readonly unWrapData: boolean;
+    readonly isPrivate: boolean;
+    readonly validators: Validator[];
+    readonly defaultConfigs?: Record<string, unknown>;
+    constructor(params: {
+        type: BrickType;
+        dataType: JSONSchemaType;
+        id: string;
+        name: string;
+        configsForm?: BrickSpec;
+        category?: string;
+        styles?: Styles;
+        unWrapData?: boolean;
+        isPrivate?: boolean;
+        validators?: Validator[];
+        defaultConfigs?: Record<string, unknown>;
+    });
+    abstract render(props: BrickProps<DataType, Configs, Styles>): unknown;
+    abstract renderBuilder(props: BrickProps<DataType, Configs, Styles>): unknown;
+    abstract getComponent(props: BrickProps<DataType, Configs, Styles>): unknown;
+    abstract getComponentWithActions(props: BrickProps<DataType, Configs, Styles>): unknown;
+    getBrickEmptySpec(): BrickSpec;
+}

package/dist/brick/types.d.ts

@@ -0,0 +1,25 @@
+import type { BrickBaseConfigs, CommonBrickProps } from "../utils/common-brick-props";
+import type { BrickSpec } from "../utils/brick-spec";
+import type { CollectionUtils, InputUtils, PanelUtils } from "./utils";
+interface BrickProps<Configs extends BrickBaseConfigs, Styles> extends CommonBrickProps<Configs, Styles> {
+    path: string;
+    error?: string;
+    editable?: boolean;
+}
+export interface PanelBrickProps<Configs extends BrickBaseConfigs, Styles> extends BrickProps<Configs, Styles> {
+    children?: unknown;
+    utils: PanelUtils;
+}
+export interface InputBrickProps<DataType, Configs extends BrickBaseConfigs, Styles> extends BrickProps<Configs, Styles> {
+    data?: DataType;
+    onDataChange?: (value?: DataType) => void;
+    utils: InputUtils;
+}
+export interface CollectionBrickProps<DataType, Configs extends BrickBaseConfigs, Styles> extends BrickProps<Configs, Styles> {
+    brickSpec?: BrickSpec;
+    children?: unknown;
+    data?: DataType;
+    onDataChange?: (value?: DataType) => void;
+    utils: CollectionUtils;
+}
+export {};

package/dist/brick/utils.d.ts

@@ -0,0 +1,20 @@
+import type { Rule } from "../rules/rule";
+export type CommonUtils = object;
+export type InputUtils = CommonUtils;
+export type PanelUtils = CommonUtils;
+export type CollectionUtils = CommonUtils;
+export type ActionUtils = {
+    validateForm: () => {
+        isValid: boolean;
+    };
+} & CommonUtils;
+export type Utils = InputUtils & PanelUtils & CollectionUtils & ActionUtils;
+export declare const evalBrickCode: (code: string, data?: Record<string, unknown>) => unknown;
+type Properties = {
+    value?: string;
+    required?: boolean;
+    hidden?: boolean;
+    disabled?: boolean;
+};
+export declare const getAffectedProperties: (rules?: Rule[], dataMap?: Record<string, unknown>) => Properties;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+export { BrickType } from "./utils/brick-type";
+export { BrickMold } from "./utils/brick-mold";
+export { DropType, BrickMoldDropType, BrickSpecDropType } from "./utils/drop-type";
+export { BrickStyles } from "./utils/brick-styles";
+export { BrickBaseConfigs, CommonBrickProps, WithBrickBaseConfigs } from "./utils/common-brick-props";
+export { BrickSpec, buildValidationSchema, iterateBricks, iterateSchemaBricks } from "./utils/brick-spec";
+export { PanelBrickProps, InputBrickProps, CollectionBrickProps } from "./brick/types";
+export { Brick, BrickProps } from "./brick/brick";
+export { CommonUtils, PanelUtils, InputUtils, CollectionUtils, ActionUtils, Utils, getAffectedProperties, evalBrickCode } from "./brick/utils";
+export { Rule } from "./rules/rule";
+export { Effect } from "./rules/effect";
+export { Validator, ValidationResult, validateBrickSpecData, validateBrickSpecDataDetailed, validateFormData } from "./validators/validator";
+export { defaultValidationMessage, registerValidationMessages } from "./validators/default-messages";
+export { Validation } from "./validators/validation";
+export { JSONSchemaType } from "./validators/json-schema-type";
+export { services } from "./services";
+export { JsRunnerService, SandboxJsRunnerService, JsRunnerServiceImplementation } from "./services/js_runner_service";
+export { UnsafeEvalJsRunnerService } from "./services/unsafe_js_runner_service";
+export { runSandboxed } from "./services/sandbox_interpreter";
+export { DataSourceService, FetchDataSourceService } from "./services/data_source_service";
+export { FileLike, UploadedFile, FileUploadService, Base64FileUploadService } from "./services/file_upload_service";
+export { LocalizedText, isLocalizedObject, resolveLocalizedText, resolveLocalizedRecord } from "./utils/localized-text";
+export { pointerFromPath, pointerOfUid, getBrickAt } from "./ops/pointer";
+export { SpecUpdate, addBrick, removeBrick, moveBrick, duplicateBrick, updateBrickConfigs, updateBrickStyles, updateBrickValidations, updateBrickRules } from "./ops/ops";
+export { SpecHistory } from "./ops/history";
+export type { Operation } from "fast-json-patch";