@astroapps/forms-core 1.0.0

package/lib/schemaInterface.d.ts

@@ -0,0 +1,102 @@
+import { EqualityFunc, FieldOption, SchemaField, ValidationMessageType } from "./schemaField";
+import { SchemaDataNode } from "./schemaDataNode";
+import { SchemaNode } from "./schemaNode";
+import { Control, ControlSetup } from "@astroapps/controls";
+/**
+ * Interface for schema-related operations.
+ */
+export interface SchemaInterface {
+    /**
+     * Checks if the value of a field is empty.
+     * @param field The schema field.
+     * @param value The value to check.
+     * @returns True if the value is empty, false otherwise.
+     */
+    isEmptyValue(field: SchemaField, value: any): boolean;
+    /**
+     * Gets the text representation of a field's value.
+     * @param field The schema field.
+     * @param value The value to convert.
+     * @param element Indicates if the value is an element, optional.
+     * @param options The field options, optional.
+     * @returns The text representation of the value.
+     */
+    textValue(field: SchemaField, value: any, element?: boolean, options?: FieldOption[]): string | undefined;
+    /**
+     * Gets the text representation of a field's value for a data node.
+     * @param dataNode
+     */
+    textValueForData(dataNode: SchemaDataNode): string | undefined;
+    /**
+     * Gets the length of a control's value.
+     * @param field The schema field.
+     * @param control The control to check.
+     * @returns The length of the control's value.
+     */
+    controlLength(field: SchemaField, control: Control<any>): number;
+    /**
+     * Gets the length of a field's value.
+     * @param field The schema field.
+     * @param value The value to check.
+     * @returns The length of the value.
+     */
+    valueLength(field: SchemaField, value: any): number;
+    /**
+     * Gets the data options for a schema data node.
+     * @param node The schema data node.
+     * @returns The data options.
+     */
+    getDataOptions(node: SchemaDataNode): FieldOption[] | null | undefined;
+    /**
+     * Gets the node options for a schema node.
+     * @param node The schema node.
+     * @returns The node options.
+     */
+    getNodeOptions(node: SchemaNode): FieldOption[] | null | undefined;
+    /**
+     * Gets the options for a schema field.
+     * @param field The schema field.
+     * @returns The field options.
+     */
+    getOptions(field: SchemaField): FieldOption[] | undefined | null;
+    /**
+     * Gets the filter options for a schema data node and field.
+     * @param array The schema data node.
+     * @param field The schema node.
+     * @returns The filter options.
+     */
+    getFilterOptions(array: SchemaDataNode, field: SchemaNode): FieldOption[] | undefined | null;
+    /**
+     * Parses a string value to milliseconds.
+     * @param field The schema field.
+     * @param v The string value to parse.
+     * @returns The parsed value in milliseconds.
+     */
+    parseToMillis(field: SchemaField, v: string): number;
+    /**
+     * Gets the validation message text for a field.
+     * @param field The schema field.
+     * @param messageType The type of validation message.
+     * @param actual The actual value.
+     * @param expected The expected value.
+     * @returns The validation message text.
+     */
+    validationMessageText(field: SchemaField, messageType: ValidationMessageType, actual: any, expected: any): string;
+    /**
+     * Compares two values of a field.
+     * @param field The schema field.
+     * @param v1 The first value.
+     * @param v2 The second value.
+     * @returns The comparison result.
+     */
+    compareValue(field: SchemaField, v1: unknown, v2: unknown): number;
+    /**
+     * Gets the search text for a field's value.
+     * @param field The schema field.
+     * @param value The value to search.
+     * @returns The search text.
+     */
+    searchText(field: SchemaField, value: any): string;
+    makeEqualityFunc(field: SchemaNode, element?: boolean): EqualityFunc;
+    makeControlSetup(field: SchemaNode, element?: boolean): ControlSetup<any>;
+}

package/lib/schemaNode.d.ts

@@ -0,0 +1,54 @@
+import { SchemaField } from "./schemaField";
+export interface SchemaTreeLookup {
+    getSchema(schemaId: string): SchemaNode | undefined;
+    getSchemaTree(schemaId: string, additional?: SchemaField[]): SchemaTree | undefined;
+}
+export declare abstract class SchemaTree {
+    abstract rootNode: SchemaNode;
+    abstract getSchemaTree(schemaId: string): SchemaTree | undefined;
+    createChildNode(parent: SchemaNode, field: SchemaField): SchemaNode;
+    getSchema(schemaId: string): SchemaNode | undefined;
+}
+export declare function createSchemaTree(rootFields: SchemaField[], lookup?: SchemaTreeLookup): SchemaTree;
+export declare class SchemaNode {
+    id: string;
+    field: SchemaField;
+    tree: SchemaTree;
+    parent?: SchemaNode | undefined;
+    constructor(id: string, field: SchemaField, tree: SchemaTree, parent?: SchemaNode | undefined);
+    getSchema(schemaId: string): SchemaNode | undefined;
+    getUnresolvedFields(): SchemaField[];
+    getResolvedParent(noRecurse?: boolean): SchemaNode | undefined;
+    getResolvedFields(): SchemaField[];
+    getChildNodes(): SchemaNode[];
+    getChildField(field: string): SchemaField;
+    createChildNode(field: SchemaField): SchemaNode;
+    getChildNode(field: string): SchemaNode;
+}
+export declare function resolveSchemaNode(node: SchemaNode, fieldSegment: string): SchemaNode | undefined;
+export declare function createSchemaNode(field: SchemaField, lookup: SchemaTree, parent: SchemaNode | undefined): SchemaNode;
+export declare function createSchemaLookup<A extends Record<string, SchemaField[]>>(schemaMap: A): {
+    getSchema(schemaId: keyof A): SchemaNode;
+    getSchemaTree(schemaId: keyof A, additional?: SchemaField[]): SchemaTree;
+};
+export declare function schemaForFieldRef(fieldRef: string | undefined, schema: SchemaNode): SchemaNode;
+export declare function traverseSchemaPath<A>(fieldPath: string[], schema: SchemaNode, acc: A, next: (acc: A, node: SchemaNode) => A): A;
+export declare function traverseData(fieldPath: string[], root: SchemaNode, data: {
+    [k: string]: any;
+}): unknown;
+export declare function schemaForFieldPath(fieldPath: string[], schema: SchemaNode): SchemaNode;
+export declare function getSchemaNodePath(node: SchemaNode): string[];
+export declare function getSchemaNodePathString(node: SchemaNode): string;
+export declare function isCompoundNode(node: SchemaNode): boolean;
+/**
+ * Returns the relative path from a parent node to a child node.
+ * @param parent
+ * @param child
+ */
+export declare function relativePath(parent: SchemaNode, child: SchemaNode): string;
+/**
+ * Returns the relative path from a parent node to a child node.
+ * @param parentPath
+ * @param childPath
+ */
+export declare function relativeSegmentPath(parentPath: string[], childPath: string[]): string;

package/lib/schemaValidator.d.ts

@@ -0,0 +1,27 @@
+export declare enum ValidatorType {
+    Jsonata = "Jsonata",
+    Date = "Date",
+    Length = "Length"
+}
+export interface SchemaValidator {
+    type: string;
+}
+export interface JsonataValidator extends SchemaValidator {
+    type: ValidatorType.Jsonata;
+    expression: string;
+}
+export interface LengthValidator extends SchemaValidator {
+    type: ValidatorType.Length;
+    min?: number | null;
+    max?: number | null;
+}
+export declare enum DateComparison {
+    NotBefore = "NotBefore",
+    NotAfter = "NotAfter"
+}
+export interface DateValidator extends SchemaValidator {
+    type: ValidatorType.Date;
+    comparison: DateComparison;
+    fixedDate?: string | null;
+    daysFromCurrent?: number | null;
+}

package/lib/util.d.ts

@@ -0,0 +1,14 @@
+import { CleanupScope, Control, ControlSetup } from "@astroapps/controls";
+/**
+ * Type representing a JSON path, which can be a string or a number.
+ */
+export type JsonPath = string | number;
+/**
+ * Converts a JSON path array to a string.
+ * @param jsonPath - The JSON path array to convert.
+ * @param customIndex - Optional function to customize the index format.
+ * @returns The JSON path string.
+ */
+export declare function jsonPathString(jsonPath: JsonPath[], customIndex?: (n: number) => string): string;
+export declare function createScopedComputed<T>(parent: CleanupScope, compute: () => T): Control<T>;
+export declare function createScoped<T>(parent: CleanupScope, value: T, setup?: ControlSetup<T>): Control<T>;

package/lib/validators.d.ts

@@ -0,0 +1,23 @@
+import { DateValidator, JsonataValidator, LengthValidator, SchemaValidator } from "./schemaValidator";
+import { ControlDefinition } from "./controlDefinition";
+import { SchemaDataNode } from "./schemaDataNode";
+import { Control } from "@astroapps/controls";
+import { SchemaInterface } from "./schemaInterface";
+import { FormContextOptions } from "./formState";
+import { FormNode } from "./formNode";
+export interface ValidationEvalContext {
+    addSync(validate: (value: unknown) => string | undefined | null): void;
+    addCleanup(cleanup: () => void): void;
+    validationEnabled: Control<boolean>;
+    parentData: SchemaDataNode;
+    data: SchemaDataNode;
+    schemaInterface: SchemaInterface;
+    formContext: Control<FormContextOptions>;
+}
+export type ValidatorEval<T extends SchemaValidator> = (validation: T, context: ValidationEvalContext) => void;
+export declare const jsonataValidator: ValidatorEval<JsonataValidator>;
+export declare const lengthValidator: ValidatorEval<LengthValidator>;
+export declare const dateValidator: ValidatorEval<DateValidator>;
+export declare const defaultValidators: Record<string, ValidatorEval<any>>;
+export declare function createValidators(def: ControlDefinition, context: ValidationEvalContext): void;
+export declare function setupValidation(controlImpl: Control<FormContextOptions>, definition: ControlDefinition, dataNode: Control<SchemaDataNode | undefined>, schemaInterface: SchemaInterface, parent: SchemaDataNode, formNode: FormNode): void;

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@astroapps/forms-core",
+  "version": "1.0.0",
+  "description": "",
+  "type": "module",
+  "main": "lib/index.cjs",
+  "module": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    "types": "./lib/index.d.ts",
+    "require": "./lib/index.cjs",
+    "default": "./lib/index.js"
+  },
+  "author": "Astrolabe Enterprises",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/astrolabe-apps/astrolabe-common/issues"
+  },
+  "homepage": "https://github.com/astrolabe-apps/astrolabe-common#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "react",
+    "typescript",
+    "forms"
+  ],
+  "dependencies": {
+    "clsx": "^1 || ^2",
+    "uuid": "^10.0.0",
+    "jsonata": "^2.0.4"
+  },
+  "peerDependencies": {
+    "@astroapps/controls": "^1.3.0"
+  },
+  "devDependencies": {
+    "@astroapps/controls": "^1.3.0",
+    "jest": "^29.7.0",
+    "tsx": "^4.19.1",
+    "fast-check": "^3.22.0",
+    "ts-jest": "^29.2.5",
+    "@jest/globals": "^29.7.0",
+    "typedoc": "^0.27.2",
+    "@types/uuid": "^10.0.0",
+    "@types/react": "^18.2.28",
+    "markdown-magic": "^2.6.1",
+    "microbundle": "^0.15.1",
+    "nswag": "^13.18.2",
+    "prettier": "^3.0.3",
+    "rimraf": "^3.0.2",
+    "typescript": "^5.6.2"
+  },
+  "scripts": {
+    "build": "rimraf ./lib/ node_modules/.cache && microbundle -f modern,cjs --no-compress",
+    "watch": "microbundle -w -f modern,cjs --no-compress",
+    "test": "jest --coverage",
+    "play": "tsx test/play.ts",
+    "update-readme": "md-magic --path README.md"
+  }
+}