@react-typed-forms/schemas 3.0.0-dev.99 → 4.1.0

package/README.md

@@ -0,0 +1,292 @@
+
+# React typed forms schemas
+
+A simple abstraction on top of `@react-typed-forms/core` for defining JSON compatible schemas and 
+rendering UIs for users to enter that data. 
+
+## Install
+
+```npm
+npm install @react-typed-forms/schemas
+```
+
+## Example
+
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=../examples/src/docs/schemas-example.tsx) -->
+<!-- The below code snippet is automatically added from ../examples/src/docs/schemas-example.tsx -->
+```tsx
+import { useControl } from "@react-typed-forms/core";
+import React from "react";
+import {
+  buildSchema,
+  createDefaultRenderers,
+  createFormRenderer,
+  defaultFormEditHooks,
+  defaultTailwindTheme,
+  defaultValueForFields,
+  FormRenderer,
+  intField,
+  renderControl,
+  stringField,
+  useControlDefinitionForSchema,
+} from "@react-typed-forms/schemas";
+
+/** Define your form */
+interface SimpleForm {
+  firstName: string;
+  lastName: string;
+  yearOfBirth: number;
+}
+
+/* Build your schema fields. Importantly giving them Display Names for showing in a UI */
+const simpleSchema = buildSchema<SimpleForm>({
+  firstName: stringField("First Name"),
+  lastName: stringField("Last Name", { required: true }),
+  yearOfBirth: intField("Year of birth", { defaultValue: 1980 }),
+});
+
+/* Create a form renderer based on a simple tailwind css based theme */
+const renderer: FormRenderer = createFormRenderer(
+  [],
+  createDefaultRenderers(defaultTailwindTheme),
+);
+
+export default function SimpleSchemasExample() {
+  /* Create a `Control` for collecting the data, the schema fields can be used to get a default value */
+  const data = useControl<SimpleForm>(() =>
+    defaultValueForFields(simpleSchema),
+  );
+
+  /* Generate a ControlDefinition automatically from the schema */
+  const controlDefinition = useControlDefinitionForSchema(simpleSchema);
+
+  return (
+    <div className="container my-4 max-w-2xl">
+      {/* Render the ControlDefinition using `data` for the form state */}
+      {renderControl(controlDefinition, data, {
+        fields: simpleSchema,
+        renderer,
+        hooks: defaultFormEditHooks,
+      })}
+      <pre>{JSON.stringify(data.value, null, 2)}</pre>
+    </div>
+  );
+}
+```
+<!-- AUTO-GENERATED-CONTENT:END -->
+
+This will produce this UI:
+
+<img src="../../images/schemas.png">
+
+## Schema Fields and Control Definitions
+
+### `SchemaField`
+
+A `SchemaField` is a JSON object which describes the definition of a field inside the context of a JSON object. Each `SchemaField` must have a field name and a `FieldType` which will map to JSON. The following built in types are defined with these JSON mappings:
+
+* `String` - A JSON string
+* `Bool` - A JSON boolean
+* `Int` - A JSON number
+* `Double` - A JSON number
+* `Date` - A date stored as 'yyyy-MM-dd' in a JSON string
+* `DateTime` - A date and time stored in ISO8601 format in a JSON string
+* `Compound` - A JSON object with a list of `SchemaField` children
+
+Each `SchemaField` can also be marked as a `collection` which means that it will be mapped to a JSON array of the defined `FieldType`.
+
+### Defining fields
+
+While you can define a `SchemaField` as plain JSON, e.g. 
+```json
+[
+  {
+    "type": "String",
+    "field": "firstName",
+    "displayName": "First Name"
+  },
+  {
+    "type": "String",
+    "field": "lastName",
+    "displayName": "Last Name",
+    "required": true
+  },
+  {
+    "type": "Int",
+    "field": "yearOfBirth",
+    "displayName": "Year of birth",
+    "defaultValue": 1980
+  }
+]
+```
+
+However if you have existing types which you would like to define `SchemaField`s for the library contains a function called `buildSchema` a type safe way of generating fields for a type:
+
+```tsx
+interface SimpleForm {
+  firstName: string;
+  lastName: string;
+  yearOfBirth: number;
+}
+
+const simpleSchema = buildSchema<SimpleForm>({
+  firstName: stringField("First Name"),
+  lastName: stringField("Last Name", { required: true }),
+  yearOfBirth: intField("Year of birth", { defaultValue: 1980 }),
+});
+```
+
+### Field options
+
+Often a field only has a set of allowed values, e.g. a enum. `SchemaField` allows this to be modeled by 
+providing an array of `FieldOption`: 
+
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./src/types.ts&lines=37-41) -->
+<!-- The below code snippet is automatically added from ./src/types.ts -->
+```ts
+export interface FieldOption {
+  name: string;
+  value: any;
+}
+```
+<!-- AUTO-GENERATED-CONTENT:END -->
+
+For example you could only allow certain last names:
+
+```ts
+stringField('Last Name', { 
+    required: true,
+    options:[ 
+        { name: "Smith", value: "smith" }, 
+        { name: "Jones", value: "jones" }
+    ]
+});
+```
+
+<img src="../../images/schemas-option.png">
+
+### `ControlDefinition`
+
+A `ControlDefinition` is a JSON object which describes what should be rendered in a UI. Each `ControlDefinition` can be one of 4 distinct types:
+
+* `DataControlDefinition` - Points to a `SchemaField` in order to render a control for editing of data.
+* `GroupedControlsDefinition` - Contains an optional title and a list of `ControlDefinition` children which should be rendered as a group. Optionally can refer to a `SchemaField` with type `Compound` in order to capture nested data.
+* `DisplayControlDefinition` - Render readonly content, current text and HTML variants are defined.
+* `ActionControlDefinition` - Renders an action button, useful for hooking forms up with outside functionality.
+
+If you don't care about the layout of the form that much you can generate the definition automatically by using `useControlDefinitionForSchema()`.
+
+TODO renderOptions, DataRenderType for choosing render style.
+
+## Form Renderer
+
+The actual rendering of the UI is abstracted into an object which contains functions for rendering the various `ControlDefinition`s and various parts of the UI:
+
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./src/controlRender.tsx&lines=128-138) -->
+<!-- The below code snippet is automatically added from ./src/controlRender.tsx -->
+```tsx
+export interface FormRenderer {
+  renderData: (props: DataRendererProps) => ReactElement;
+  renderGroup: (props: GroupRendererProps) => ReactElement;
+  renderDisplay: (props: DisplayRendererProps) => ReactElement;
+  renderAction: (props: ActionRendererProps) => ReactElement;
+  renderArray: (props: ArrayRendererProps) => ReactElement;
+  renderLabel: (props: LabelRendererProps, elem: ReactElement) => ReactElement;
+  renderVisibility: (visible: Visibility, elem: ReactElement) => ReactElement;
+  renderAdornment: (props: AdornmentProps) => AdornmentRenderer;
+}
+```
+<!-- AUTO-GENERATED-CONTENT:END -->
+
+The `createFormRenderer` function takes an array of `RendererRegistration` which allows for customising the rendering.
+
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./src/renderers.tsx&lines=109-118) -->
+<!-- The below code snippet is automatically added from ./src/renderers.tsx -->
+```tsx
+export type RendererRegistration =
+  | DataRendererRegistration
+  | GroupRendererRegistration
+  | DisplayRendererRegistration
+  | ActionRendererRegistration
+  | LabelRendererRegistration
+  | ArrayRendererRegistration
+  | AdornmentRendererRegistration
+  | VisibilityRendererRegistration;
+```
+<!-- AUTO-GENERATED-CONTENT:END -->
+
+Probably the most common customisation would be to add a `DataRendererRegistration` which will change the way a `DataControlDefinition` is rendered for a particular FieldType:
+
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./src/renderers.tsx&lines=48-61) -->
+<!-- The below code snippet is automatically added from ./src/renderers.tsx -->
+```tsx
+export interface DataRendererRegistration {
+  type: "data";
+  schemaType?: string | string[];
+  renderType?: string | string[];
+  options?: boolean;
+  collection?: boolean;
+  match?: (props: DataRendererProps) => boolean;
+  render: (
+    props: DataRendererProps,
+    defaultLabel: (label?: Partial<LabelRendererProps>) => LabelRendererProps,
+    renderers: FormRenderer,
+  ) => ReactElement;
+}
+```
+<!-- AUTO-GENERATED-CONTENT:END -->
+* The `schemaType` field specifies which `FieldType`(s) should use this `DataRendererRegistration`, unspecified means allow any.
+* The `renderType` field specifies which `DataRenderType` this registration applies to.
+* The `match` function can be used if the matching logic is more complicated than provided by the other.
+* The `render` function does the actual rendering if the ControlDefinition/SchemaField matches the registration.
+
+A good example of a custom DataRendererRegistration is the `muiTextField` which renders `String` fields using the `FTextField` wrapper of the `@react-typed-forms/mui` library:
+
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=../schemas-mui/src/index.tsx&lines=12-35) -->
+<!-- The below code snippet is automatically added from ../schemas-mui/src/index.tsx -->
+```tsx
+export function muiTextfieldRenderer(
+  variant?: "standard" | "outlined" | "filled",
+): DataRendererRegistration {
+  return {
+    type: "data",
+    schemaType: FieldType.String,
+    renderType: DataRenderType.Standard,
+    render: (r, makeLabel, { renderVisibility }) => {
+      const { title, required } = makeLabel();
+      return renderVisibility(
+        r.visible,
+        <FTextField
+          variant={variant}
+          required={required}
+          fullWidth
+          size="small"
+          state={r.control}
+          label={title}
+        />,
+      );
+    },
+  };
+}
+```
+<!-- AUTO-GENERATED-CONTENT:END -->
+
+Changing the simple example above to use the following:
+
+```tsx
+const renderer: FormRenderer = createFormRenderer(
+    [muiTextFieldRenderer()], 
+    createDefaultRenderer (defaultTailwindTheme));
+```
+
+This will produce this UI:
+
+<img src="../../images/schemas-muifield.png">
+
+## TODO
+
+* Label rendering
+* Visibility
+* Arrays
+* Display controls
+

package/lib/controlBuilder.d.ts

@@ -0,0 +1,14 @@
+import { ControlDefinition, DataControlDefinition, DisplayControlDefinition, DynamicProperty, EntityExpression, FieldValueExpression, GroupedControlsDefinition, JsonataExpression, SchemaField } from "./types";
+import { ActionRendererProps } from "./controlRender";
+export declare function dataControl(field: string, title?: string | null, options?: Partial<DataControlDefinition>): DataControlDefinition;
+export declare function textDisplayControl(text: string, options?: Partial<DisplayControlDefinition>): DisplayControlDefinition;
+export declare function htmlDisplayControl(html: string, options?: Partial<DisplayControlDefinition>): DisplayControlDefinition;
+export declare function dynamicDefaultValue(expr: EntityExpression): DynamicProperty;
+export declare function visibility(expr: EntityExpression): DynamicProperty;
+export declare function fieldEqExpr(field: string, value: any): FieldValueExpression;
+export declare function jsonataExpr(expression: string): JsonataExpression;
+export declare function groupedControl(children: ControlDefinition[], title?: string, options?: Partial<GroupedControlsDefinition>): GroupedControlsDefinition;
+export declare function compoundControl(field: string, title: string | undefined, children: ControlDefinition[], options?: Partial<DataControlDefinition>): DataControlDefinition;
+export declare function createAction(actionId: string, onClick: () => void, actionText?: string): ActionRendererProps;
+export declare const emptyGroupDefinition: GroupedControlsDefinition;
+export declare function useControlDefinitionForSchema(sf: SchemaField[], definition?: GroupedControlsDefinition): GroupedControlsDefinition;

package/lib/controlRender.d.ts

@@ -1,95 +1,112 @@
-import { ActionControlDefinition, AnyControlDefinition, CompoundField, ControlDefinition, DataControlDefinition, DisplayControlDefinition, FieldOption, GroupedControlsDefinition, ScalarField, SchemaField } from "./types";
-import React, { Key, ReactElement } from "react";
+import { FC, Key, ReactNode } from "react";
 import { Control } from "@react-typed-forms/core";
-export interface FormEditHooks {
-    useDataProperties(formState: FormEditState, definition: DataControlDefinition, field: ScalarField): DataControlProperties;
-    useGroupProperties(formState: FormEditState, definition: GroupedControlsDefinition, currentHooks: FormEditHooks): GroupControlProperties;
-    useDisplayProperties(formState: FormEditState, definition: DisplayControlDefinition): DisplayControlProperties;
-    useActionProperties(formState: FormEditState, definition: ActionControlDefinition): ActionControlProperties;
+import { AdornmentPlacement, ControlAdornment, ControlDefinition, DataControlDefinition, DisplayData, FieldOption, GroupRenderOptions, RenderOptions, SchemaField } from "./types";
+import { ControlGroupContext } from "./util";
+export interface FormRenderer {
+    renderData: (props: DataRendererProps, asArray: (() => ReactNode) | undefined) => (layout: ControlLayoutProps) => ControlLayoutProps;
+    renderGroup: (props: GroupRendererProps) => ReactNode;
+    renderDisplay: (props: DisplayRendererProps) => ReactNode;
+    renderAction: (props: ActionRendererProps) => ReactNode;
+    renderArray: (props: ArrayRendererProps) => ReactNode;
+    renderAdornment: (props: AdornmentProps) => AdornmentRenderer;
+    renderLabel: (props: LabelRendererProps, labelStart: ReactNode, labelEnd: ReactNode) => ReactNode;
+    renderLayout: (props: ControlLayoutProps) => ReactNode;
+    renderVisibility: (control: Control<Visibility | undefined>, children: () => ReactNode) => ReactNode;
 }
-export interface DataControlProperties {
-    readonly: boolean;
-    visible: boolean;
-    options: FieldOption[] | undefined;
-    defaultValue: any;
+export interface DisplayRendererProps {
+    data: DisplayData;
+}
+export interface AdornmentProps {
+    adornment: ControlAdornment;
+}
+export declare const AppendAdornmentPriority = 0;
+export declare const WrapAdornmentPriority = 1000;
+export interface AdornmentRenderer {
+    apply(children: RenderedLayout): void;
+    adornment?: ControlAdornment;
+    priority: number;
+}
+export interface ArrayRendererProps {
+    addAction?: ActionRendererProps;
     required: boolean;
-    customRender?: (props: DataRendererProps, control: Control<any>) => ReactElement;
+    removeAction?: (childIndex: number) => ActionRendererProps;
+    childCount: number;
+    renderChild: (childIndex: number) => ReactNode;
+    childKey: (childIndex: number) => Key;
+    arrayControl?: Control<any[] | undefined | null>;
 }
-export interface GroupControlProperties {
+export interface Visibility {
     visible: boolean;
-    hooks: FormEditHooks;
+    showing: boolean;
 }
-export interface DisplayControlProperties {
-    visible: boolean;
+export interface RenderedLayout {
+    labelStart?: ReactNode;
+    labelEnd?: ReactNode;
+    controlStart?: ReactNode;
+    controlEnd?: ReactNode;
+    label?: ReactNode;
+    children?: ReactNode;
 }
-export interface ActionControlProperties {
-    visible: boolean;
-    onClick: () => void;
+export interface ControlLayoutProps {
+    label?: LabelRendererProps;
+    errorControl?: Control<any>;
+    adornments?: AdornmentRenderer[];
+    children?: ReactNode;
+    processLayout?: (props: ControlLayoutProps) => ControlLayoutProps;
 }
-export interface ControlData {
-    [field: string]: any;
+export declare enum LabelType {
+    Control = 0,
+    Group = 1
 }
-export interface FormEditState {
-    fields: SchemaField[];
-    data: Control<ControlData>;
-    readonly?: boolean;
+export interface LabelRendererProps {
+    type: LabelType;
+    hide?: boolean | null;
+    label: ReactNode;
+    required?: boolean | null;
+    forId?: string;
 }
-export interface FormRendererComponents {
-    renderData: (props: DataRendererProps, control: Control<any>, element: boolean, renderers: FormRendererComponents) => ReactElement;
-    renderCompound: (props: CompoundGroupRendererProps, control: Control<any>, renderers: FormRendererComponents) => ReactElement;
-    renderGroup: (props: GroupRendererProps) => ReactElement;
-    renderDisplay: (props: DisplayRendererProps) => ReactElement;
-    renderAction: (props: ActionRendererProps) => ReactElement;
+export interface GroupRendererProps {
+    renderOptions: GroupRenderOptions;
+    childCount: number;
+    renderChild: (child: number) => ReactNode;
 }
-export declare const FormRendererComponentsContext: React.Context<FormRendererComponents | undefined>;
-export declare function useFormRendererComponents(): FormRendererComponents;
-export interface DisplayRendererProps {
-    definition: DisplayControlDefinition;
-    properties: DisplayControlProperties;
+export interface DataRendererProps {
+    renderOptions: RenderOptions;
+    field: SchemaField;
+    id: string;
+    control: Control<any>;
+    readonly: boolean;
+    required: boolean;
+    options: FieldOption[] | undefined | null;
+    hidden: boolean;
 }
 export interface ActionRendererProps {
-    definition: ActionControlDefinition;
-    properties: ActionControlProperties;
+    actionId: string;
+    actionText: string;
+    onClick: () => void;
 }
-export interface DataRendererProps {
-    definition: DataControlDefinition;
-    properties: DataControlProperties;
-    field: ScalarField;
-    formEditState?: FormEditState;
+export interface ControlRenderProps {
+    control: Control<any>;
 }
-export interface GroupRendererProps {
-    definition: Omit<GroupedControlsDefinition, "children">;
-    properties: GroupControlProperties;
-    childCount: number;
-    renderChild: (child: number, wrapChild: (key: Key, childElem: ReactElement) => ReactElement) => ReactElement;
-}
-export interface CompoundGroupRendererProps {
-    definition: GroupedControlsDefinition;
-    field: CompoundField;
-    properties: GroupControlProperties;
-    renderChild: (key: Key, control: ControlDefinition, data: Control<{
-        [field: string]: any;
-    }>, wrapChild: (key: Key, childElem: ReactElement) => ReactElement) => ReactElement;
-}
-export declare function isScalarField(sf: SchemaField): sf is ScalarField;
-export declare function isCompoundField(sf: SchemaField): sf is CompoundField;
-export type AnySchemaFields = SchemaField | ScalarField | (Omit<CompoundField, "children"> & {
-    children: AnySchemaFields[];
-});
-export declare function applyDefaultValues(v: {
-    [k: string]: any;
-} | undefined, fields: SchemaField[]): any;
-export declare function applyDefaultForField(v: any, field: SchemaField, parent: SchemaField[], notElement?: boolean): any;
-export declare function defaultValueForFields(fields: SchemaField[]): any;
-export declare function defaultValueForField(sf: SchemaField): any;
-export declare function elementValueForField(sf: SchemaField): any;
-export declare function findScalarField(fields: SchemaField[], field: string): ScalarField | undefined;
-export declare function findCompoundField(fields: SchemaField[], field: string): CompoundField | undefined;
-export declare function findField(fields: SchemaField[], field: string): SchemaField | undefined;
-export declare function fieldDisplayName(sf: SchemaField): string;
-export declare function controlTitle(title: string | undefined, field: SchemaField): string;
-export declare function renderControl(definition: AnyControlDefinition, formState: FormEditState, hooks: FormEditHooks, key: Key, wrapChild?: (key: Key, db: ReactElement) => ReactElement): ReactElement;
-export declare function controlForField(field: string, formState: FormEditState): Control<any>;
-export declare function fieldForControl(c: ControlDefinition): string | undefined;
-export declare function isSchemaControl(c: ControlDefinition): c is DataControlDefinition;
-export declare function isGroupControl(c: ControlDefinition): c is GroupedControlsDefinition;
+export interface FormContextOptions {
+    readonly?: boolean | null;
+    hidden?: boolean;
+}
+export type CreateDataProps = (definition: DataControlDefinition, field: SchemaField, groupContext: ControlGroupContext, control: Control<any>, options: FormContextOptions) => DataRendererProps;
+export interface ControlRenderOptions extends FormContextOptions {
+    useDataHook?: (c: ControlDefinition) => CreateDataProps;
+    clearHidden?: boolean;
+}
+export declare function useControlRenderer(definition: ControlDefinition, fields: SchemaField[], renderer: FormRenderer, options?: ControlRenderOptions): FC<ControlRenderProps>;
+export declare function lookupSchemaField(c: ControlDefinition, fields: SchemaField[]): SchemaField | undefined;
+export declare function getControlData(schemaField: SchemaField | undefined, parentContext: ControlGroupContext): [Control<any> | undefined, ControlGroupContext];
+export declare const defaultDataProps: CreateDataProps;
+export type ChildRenderer = (k: Key, childIndex: number, props: ControlRenderProps) => ReactNode;
+export declare function renderControlLayout(c: ControlDefinition, renderer: FormRenderer, childCount: number, childRenderer: ChildRenderer, dataProps: CreateDataProps, dataOptions: FormContextOptions, groupContext: ControlGroupContext, childControl?: Control<any>, schemaField?: SchemaField): ControlLayoutProps;
+export declare function appendMarkup(k: keyof RenderedLayout, markup: ReactNode): (layout: RenderedLayout) => void;
+export declare function wrapMarkup(k: keyof RenderedLayout, wrap: (ex: ReactNode) => ReactNode): (layout: RenderedLayout) => void;
+export declare function layoutKeyForPlacement(pos: AdornmentPlacement): keyof RenderedLayout;
+export declare function appendMarkupAt(pos: AdornmentPlacement, markup: ReactNode): (layout: RenderedLayout) => void;
+export declare function wrapMarkupAt(pos: AdornmentPlacement, wrap: (ex: ReactNode) => ReactNode): (layout: RenderedLayout) => void;
+export declare function renderLayoutParts(props: ControlLayoutProps, renderer: FormRenderer): RenderedLayout;
+export declare function controlTitle(title: string | undefined | null, field: SchemaField): string;

package/lib/hooks.d.ts

@@ -1,9 +1,9 @@
-import { DataControlDefinition, EntityExpression, FieldOption, ScalarField, ControlDefinition } from "./types";
-import { DataControlProperties, FormEditHooks, FormEditState } from "./controlRender";
-export type ExpressionHook = (expr: EntityExpression, formState: FormEditState) => any;
-export declare function useDefaultValue(definition: DataControlDefinition, field: ScalarField, formState: FormEditState, useExpression: ExpressionHook): any;
-export declare function useIsControlVisible(definition: ControlDefinition, formState: FormEditState, useExpression: ExpressionHook): boolean;
-export declare function getDefaultScalarControlProperties(control: DataControlDefinition, field: ScalarField, visible: boolean, defaultValue: any, readonly?: boolean): DataControlProperties;
-export declare function getOptionsForScalarField(field: ScalarField): FieldOption[] | undefined;
-export declare const defaultExpressionHook: ExpressionHook;
-export declare function createFormEditHooks(useExpression: ExpressionHook): FormEditHooks;
+import { ControlDefinition, DynamicPropertyType, SchemaField } from "./types";
+import { Control } from "@react-typed-forms/core";
+import { ControlGroupContext } from "./util";
+export declare function useEvalVisibilityHook(definition: ControlDefinition, schemaField?: SchemaField): EvalExpressionHook<boolean>;
+export declare function useEvalDefaultValueHook(definition: ControlDefinition, schemaField?: SchemaField): EvalExpressionHook;
+export type EvalExpressionHook<A = any> = (groupContext: ControlGroupContext) => Control<A | undefined>;
+export declare function useEvalDynamicHook(definition: ControlDefinition, type: DynamicPropertyType): EvalExpressionHook | undefined;
+export declare function matchesType(context: ControlGroupContext, types?: string[] | null): boolean | undefined;
+export declare function useJsonataExpression(jExpr: string, data: Control<any>): Control<any>;

package/lib/index.d.ts

@@ -1,4 +1,8 @@
 export * from "./types";
 export * from "./schemaBuilder";
+export * from "./controlBuilder";
 export * from "./controlRender";
-export * from "./hooks";
+export * from "./util";
+export * from "./renderers";
+export * from "./tailwind";
+export * from "./validators";