@react-typed-forms/schemas 1.0.0-dev.2 → 1.0.0-dev.21

package/README.md

@@ -0,0 +1,223 @@
+
+# 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`.
+
+TODO - buildSchema, FieldOptions, extending FieldType
+
+### `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/controlRender.d.ts

@@ -1,95 +1,112 @@
-import { ActionControlDefinition, AnyControlDefinition, CompoundField, ControlDefinition, DataControlDefinition, DisplayControlDefinition, FieldOption, GroupedControlsDefinition, SchemaField } from "./types";
-import React, { Key, ReactElement } from "react";
+import { ActionControlDefinition, AdornmentPlacement, CompoundField, ControlAdornment, ControlDefinition, DataControlDefinition, DisplayControlDefinition, EntityExpression, FieldOption, GroupedControlsDefinition, RenderOptions, SchemaField, SchemaValidator } from "./types";
+import { Key, ReactElement, ReactNode } from "react";
 import { Control } from "@react-typed-forms/core";
+export interface SchemaHooks {
+    useExpression(expr: EntityExpression, formState: FormEditState): Control<any | undefined>;
+    useValidators(formState: FormEditState, isVisible: boolean, control: Control<any>, required: boolean, validations?: SchemaValidator[] | null): void;
+}
 export interface FormEditHooks {
-    useDataProperties(formState: FormEditState, definition: DataControlDefinition, field: SchemaField): DataControlProperties;
-    useGroupProperties(formState: FormEditState, definition: GroupedControlsDefinition, currentHooks: FormEditHooks): GroupControlProperties;
-    useDisplayProperties(formState: FormEditState, definition: DisplayControlDefinition): DisplayControlProperties;
-    useActionProperties(formState: FormEditState, definition: ActionControlDefinition): ActionControlProperties;
+    useDataProperties(formState: FormEditState, definition: DataControlDefinition, field: SchemaField): DataRendererProps;
+    useGroupProperties(formState: FormEditState, definition: GroupedControlsDefinition): GroupRendererProps;
+    useDisplayProperties(formState: FormEditState, definition: DisplayControlDefinition): DisplayRendererProps;
+    useActionProperties(formState: FormEditState, definition: ActionControlDefinition): ActionRendererProps;
+    schemaHooks: SchemaHooks;
 }
-export interface DataControlProperties {
+export interface DataRendererProps {
+    definition: DataControlDefinition;
+    renderOptions: RenderOptions;
+    visible: Visibility;
+    control: Control<any>;
+    field: SchemaField;
+    array?: ArrayRendererProps;
     readonly: boolean;
-    visible: boolean;
-    options: FieldOption[] | undefined;
     defaultValue: any;
     required: boolean;
-    customRender?: (props: DataRendererProps, control: Control<any>) => ReactElement;
+    options: FieldOption[] | undefined | null;
+    customRender?: (props: DataRendererProps) => ReactElement;
+    formState: FormEditState;
 }
-export interface GroupControlProperties {
-    visible: boolean;
+export interface GroupRendererProps {
+    definition: Omit<GroupedControlsDefinition, "children">;
+    visible: Visibility;
+    field?: CompoundField;
+    array?: ArrayRendererProps;
+    hideTitle: boolean;
     hooks: FormEditHooks;
-}
-export interface DisplayControlProperties {
-    visible: boolean;
-}
-export interface ActionControlProperties {
-    visible: boolean;
-    onClick: () => void;
+    childCount: number;
+    renderChild: (child: number) => ReactElement;
 }
 export interface ControlData {
     [field: string]: any;
 }
-export interface FormEditState {
+export interface FormDataContext {
     fields: SchemaField[];
     data: Control<ControlData>;
+}
+export interface FormEditState extends FormDataContext {
+    hooks: FormEditHooks;
+    renderer: FormRenderer;
     readonly?: boolean;
+    invisible?: boolean;
+}
+export type RenderControlOptions = Omit<FormEditState, "data">;
+export interface ArrayRendererProps {
+    definition: DataControlDefinition | GroupedControlsDefinition;
+    control: Control<any[]>;
+    field: SchemaField;
+    addAction?: ActionRendererProps;
+    removeAction?: (childCount: number) => ActionRendererProps;
+    childCount: number;
+    renderChild: (childCount: number) => ReactElement;
+    childKey: (childCount: number) => Key;
 }
-export interface FormRendererComponents {
-    renderData: (props: DataRendererProps, control: Control<any>, element: boolean, renderers: FormRendererComponents) => ReactElement;
-    renderCompound: (props: CompoundGroupRendererProps, control: Control<any>, renderers: FormRendererComponents) => ReactElement;
+export interface AdornmentProps {
+    key: Key;
+    definition: ControlAdornment;
+}
+export interface AdornmentRenderer {
+    wrap?: (children: ReactElement) => ReactElement;
+    child?: [AdornmentPlacement, ReactNode];
+}
+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;
+}
+export interface Visibility {
+    value: boolean;
+    canChange: boolean;
+}
+export interface LabelRendererProps {
+    visible: Visibility;
+    title?: ReactNode;
+    forId?: string;
+    required: boolean;
+    control?: Control<any>;
+    group?: boolean;
+    renderAdornment: (placement: AdornmentPlacement) => ReactElement;
 }
-export declare const FormRendererComponentsContext: React.Context<FormRendererComponents | undefined>;
-export declare function useFormRendererComponents(): FormRendererComponents;
 export interface DisplayRendererProps {
     definition: DisplayControlDefinition;
-    properties: DisplayControlProperties;
+    visible: Visibility;
 }
 export interface ActionRendererProps {
     definition: ActionControlDefinition;
-    properties: ActionControlProperties;
-}
-export interface DataRendererProps {
-    definition: DataControlDefinition;
-    properties: DataControlProperties;
-    field: SchemaField;
-    formEditState?: FormEditState;
-}
-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;
+    visible: Visibility;
+    onClick: () => void;
 }
-export declare function isScalarField(sf: SchemaField): sf is SchemaField;
-export declare function isCompoundField(sf: SchemaField): sf is CompoundField;
 export type AnySchemaFields = SchemaField | (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): SchemaField | 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 controlTitle(title: string | undefined | null, field: SchemaField): string;
+export declare function renderControl<S extends ControlDefinition>(definition: S, data: Control<any>, options: RenderControlOptions, key?: Key): ReactElement;
 export declare function controlForField(field: string, formState: FormEditState): Control<any>;
-export declare function fieldForControl(c: ControlDefinition): string | undefined;
-export declare function isDataControl(c: ControlDefinition): c is DataControlDefinition;
-export declare function isGroupControl(c: ControlDefinition): c is GroupedControlsDefinition;
+export declare function fieldForControl(c: ControlDefinition): string | null | undefined;
+export declare const AlwaysVisible: Visibility;
+export declare function createAction(label: string, onClick: () => void, actionId?: string): ActionRendererProps;
+export declare function visitControlData<S extends ControlDefinition, A>(definition: S, { fields, data }: FormDataContext, cb: (definition: DataControlDefinition, control: Control<any>) => A | undefined): A | undefined;

package/lib/hooks.d.ts

@@ -1,9 +1,11 @@
-import { DataControlDefinition, EntityExpression, FieldOption, ControlDefinition, SchemaField } from "./types";
-import { DataControlProperties, FormEditHooks, FormEditState } from "./controlRender";
-export type ExpressionHook = (expr: EntityExpression, formState: FormEditState) => any;
-export declare function useDefaultValue(definition: DataControlDefinition, field: SchemaField, formState: FormEditState, useExpression: ExpressionHook): any;
-export declare function useIsControlVisible(definition: ControlDefinition, formState: FormEditState, useExpression: ExpressionHook): boolean;
-export declare function getDefaultScalarControlProperties(control: DataControlDefinition, field: SchemaField, visible: boolean, defaultValue: any, readonly?: boolean): DataControlProperties;
-export declare function getOptionsForScalarField(field: SchemaField): FieldOption[] | undefined;
-export declare const defaultExpressionHook: ExpressionHook;
-export declare function createFormEditHooks(useExpression: ExpressionHook): FormEditHooks;
+import { ControlDefinition, DataControlDefinition, FieldOption, GroupedControlsDefinition, SchemaField } from "./types";
+import { DataRendererProps, FormEditHooks, FormEditState, SchemaHooks, Visibility } from "./controlRender";
+import { Control } from "@react-typed-forms/core";
+export declare function useDefaultValue(definition: DataControlDefinition, field: SchemaField, formState: FormEditState, hooks: SchemaHooks): any;
+export declare function useIsControlVisible(definition: ControlDefinition, formState: FormEditState, hooks: SchemaHooks): Visibility;
+export declare function getDefaultScalarControlProperties(definition: DataControlDefinition, field: SchemaField, visible: Visibility, defaultValue: any, control: Control<any>, formState: FormEditState): DataRendererProps;
+export declare function getOptionsForScalarField(field: SchemaField): FieldOption[] | undefined | null;
+export declare function createDefaultSchemaHooks(): SchemaHooks;
+export declare const defaultFormEditHooks: FormEditHooks;
+export declare function createFormEditHooks(schemaHooks: SchemaHooks): FormEditHooks;
+export declare function useControlDefinitionForSchema(sf: SchemaField[], definition?: GroupedControlsDefinition): GroupedControlsDefinition;

package/lib/index.d.ts

@@ -2,3 +2,6 @@ export * from "./types";
 export * from "./schemaBuilder";
 export * from "./controlRender";
 export * from "./hooks";
+export * from "./util";
+export * from "./renderers";
+export * from "./tailwind";