@nice2dev/ui-forms 1.0.20 → 1.0.22

package/dist/index.d.ts

@@ -1,5 +1,19 @@
 import { default as default_2 } from 'react';
+import { ForwardRefExoticComponent } from 'react';
+import { NiceBaseProps } from '@nice2dev/ui-core';
+import { NiceComponentTutorial } from '@nice2dev/ui';
+import { NiceComponentTutorial as NiceComponentTutorial_2 } from '@nice2dev/ui-core';
+import { NiceConsoleTab } from '@nice2dev/ui';
+import { NiceFormItem } from '@nice2dev/ui';
+import { NiceHookBinding } from '@nice2dev/ui';
+import { NiceLifecycleHandlerOption } from '@nice2dev/ui';
+import { NiceLifecycleTrigger } from '@nice2dev/ui';
+import { NiceLogEntry } from '@nice2dev/ui';
+import { NiceRevision } from '@nice2dev/ui';
+import { NiceScriptRunnerProps } from '@nice2dev/ui';
 import { NiceStandardProps } from '@nice2dev/ui';
+import { NiceViewDefinitionV2 } from '@nice2dev/ui';
+import { RefAttributes } from 'react';
 
 declare interface AIGeneratedField {
     label: string;
@@ -248,6 +262,12 @@ declare interface FormFieldOption_2 {
     icon?: string;
 }
 
+/**
+ * Convert the repo's own {@link FormFieldDefinition}[] model into NiceForm items.
+ * Layout-only field types (heading/paragraph/divider/spacer/section/image) are skipped.
+ */
+export declare function formFieldsToFormItems(fields: FormFieldDefinition[], options?: JsonSchemaToFormItemsOptions): NiceFormItem[];
+
 /**
  * Available field types
  */
@@ -310,6 +330,16 @@ export declare interface FormSchema {
  */
 export declare function formSchemaToJsonSchema(form: FormSchema): JsonSchema;
 
+/** Convert a {@link FormSchema} to a {@link NiceViewDefinitionV2} (form kind). */
+export declare function formSchemaToV2(schema: FormSchema, options?: FormSchemaToV2Options): NiceViewDefinitionV2;
+
+export declare interface FormSchemaToV2Options {
+    /** Data source key the fields bind to. Default `'record'`. */
+    source?: string;
+    /** V2 grid column count. Default `12`. */
+    columns?: number;
+}
+
 /**
  * Form section definition
  */
@@ -354,6 +384,25 @@ export declare interface JsonSchema {
     additionalProperties?: boolean;
 }
 
+/**
+ * Convert a Draft-07 JSON Schema (object schema) into NiceForm items.
+ * Only top-level `properties` become fields; complex props use a JSON sub-editor.
+ */
+export declare function jsonSchemaToFormItems(schema: JsonSchema, options?: JsonSchemaToFormItemsOptions): NiceFormItem[];
+
+export declare interface JsonSchemaToFormItemsOptions {
+    /** Per-field overrides merged onto the generated item (label, type, colSpan, render, …). */
+    uiSchema?: Record<string, Partial<NiceFormItem>>;
+    /**
+     * Renderer for `array`-of-`object` properties. Injected (rather than imported)
+     * to avoid an import cycle with `NiceArrayField`. When omitted, such props fall
+     * back to a raw-JSON sub-editor.
+     */
+    renderArrayField?: (value: Array<Record<string, unknown>>, onChange: (rows: Array<Record<string, unknown>>) => void, itemSchema: JsonSchema, label?: string) => default_2.ReactNode;
+    /** Optional renderer for nested `object` properties (defaults to a JSON sub-editor). */
+    renderObjectField?: (value: Record<string, unknown>, onChange: (v: Record<string, unknown>) => void, schema: JsonSchema, label?: string) => default_2.ReactNode;
+}
+
 declare interface LookupConfig {
     entityType: string;
     displayField: string;
@@ -371,7 +420,52 @@ declare interface LookupConfig {
     }[];
 }
 
-export declare function NiceFormBuilder({ initialSchema, fields, onChange, onExport, onPreview, className, style, }: NiceFormBuilderProps): JSX.Element;
+export declare const NiceArrayField: ForwardRefExoticComponent<NiceArrayFieldProps & RefAttributes<HTMLDivElement>>;
+
+export declare interface NiceArrayFieldProps {
+    /** The array being edited (controlled). */
+    value: Array<Record<string, unknown>>;
+    /** Change callback with the full updated array. */
+    onChange: (rows: Array<Record<string, unknown>>) => void;
+    /** JSON Schema of a single item (object schema with `properties`). */
+    itemSchema: JsonSchema;
+    /** Label shown in the add/edit dialog title. */
+    title?: string;
+    /** Render read-only (no add / edit / delete). */
+    readOnly?: boolean;
+    /** Columns to surface in the grid (field names). Defaults to all item properties. */
+    columns?: string[];
+    className?: string;
+    style?: React.CSSProperties;
+    'data-testid'?: string;
+}
+
+export declare type NiceEntity = Record<string, unknown>;
+
+export declare const NiceEntityEditor: ForwardRefExoticComponent<NiceEntityEditorProps & RefAttributes<HTMLDivElement>>;
+
+export declare interface NiceEntityEditorProps extends NiceStandardProps {
+    /** Entities being edited (controlled). */
+    value: NiceEntity[];
+    /** Change callback with the full updated array. */
+    onChange: (entities: NiceEntity[]) => void;
+    /** JSON Schema for entity metadata (name, table, flags …). Defaults to the OmniVerk shape. */
+    entityMetaSchema?: JsonSchema;
+    /** JSON Schema for a single field. Defaults to the OmniVerk ModuleEntityField shape. */
+    fieldSchema?: JsonSchema;
+    /** Property holding the entity's fields. Default `'fields'`. */
+    fieldsKey?: string;
+    /** Property used as the entity label in the list. Default `'name'`. */
+    nameKey?: string;
+    /** Optional ER preview slot (e.g. NiceDatabaseSchemaViewer from @nice2dev/ui-diagrams). */
+    renderErPreview?: (entities: NiceEntity[]) => React.ReactNode;
+    /** Render read-only. */
+    readOnly?: boolean;
+    /** Optional guided tour. `true` = built-in; array/object = custom steps. Shows a "?" button. */
+    tutorial?: NiceComponentTutorial;
+}
+
+export declare function NiceFormBuilder({ initialSchema, fields, onChange, onExport, onPreview, className, style, tutorial, }: NiceFormBuilderProps): JSX.Element;
 
 export declare const NiceFormBuilderAI: default_2.ForwardRefExoticComponent<NiceFormBuilderAIProps & default_2.RefAttributes<NiceFormBuilderAIRef>>;
 
@@ -431,6 +525,8 @@ export declare interface NiceFormBuilderProps {
     className?: string;
     /** Style */
     style?: default_2.CSSProperties;
+    /** Optional guided tour. `true` = built-in; array/object = custom steps. Shows a "?" button. */
+    tutorial?: NiceComponentTutorial;
 }
 
 export declare const NiceFormDesigner: default_2.FC<NiceFormDesignerProps>;
@@ -474,6 +570,192 @@ export declare interface NiceFormDesignerProps extends NiceStandardProps {
     onLoadTemplate?: (templateId: string) => FormTemplate | null;
     /** Enable validation */
     enableValidation?: boolean;
+    /** Optional guided tour. `true` = built-in; array/object = custom steps. Shows a "?" button. */
+    tutorial?: NiceComponentTutorial;
+}
+
+export declare const NiceI18nEditor: ForwardRefExoticComponent<NiceI18nEditorProps & RefAttributes<HTMLDivElement>>;
+
+export declare interface NiceI18nEditorProps extends NiceBaseProps {
+    /** `{ [locale]: { [key]: value } }` (controlled). */
+    value: NiceI18nValue;
+    /** Change callback with the full updated map. */
+    onChange: (value: NiceI18nValue) => void;
+    /** Locale columns to show. Defaults to the locales present in `value`. */
+    locales?: string[];
+    /** Allow adding/removing locales. Default `true`. */
+    allowEditLocales?: boolean;
+    /** Allow adding/removing/renaming keys. Default `true`. */
+    allowEditKeys?: boolean;
+    /** Highlight empty cells as missing translations. Default `true`. */
+    highlightMissing?: boolean;
+    /** Render read-only. */
+    readOnly?: boolean;
+    /** Optional guided tour. `true` = built-in; array/object = custom steps. Shows a "?" button. */
+    tutorial?: NiceComponentTutorial_2;
+}
+
+export declare type NiceI18nValue = Record<string, Record<string, string>>;
+
+export declare const NiceManifestEditor: ForwardRefExoticComponent<NiceManifestEditorProps & RefAttributes<HTMLDivElement>>;
+
+export declare interface NiceManifestEditorProps extends NiceStandardProps {
+    /** The manifest object being edited (controlled). */
+    value: Record<string, unknown>;
+    /** Section descriptors — each renders a NiceSchemaForm over the manifest. */
+    sections: NiceManifestSection[];
+    /** Change callback with the full updated manifest. */
+    onChange: (manifest: Record<string, unknown>) => void;
+    /** Offer a Form ⇄ JSON toggle in each section. Default `true`. */
+    jsonView?: boolean;
+    /** When provided, adds a "Scripts" tab hosting a NiceScriptRunner. */
+    scriptRunner?: NiceScriptRunnerProps;
+    /** Lifecycle triggers — when provided, adds a "Lifecycle" tab. */
+    triggers?: NiceLifecycleTrigger[];
+    /** Current hook bindings. */
+    bindings?: NiceHookBinding[];
+    /** Handlers offered in the lifecycle binding picker. */
+    handlers?: NiceLifecycleHandlerOption[];
+    /** Bindings change callback. */
+    onBindingsChange?: (bindings: NiceHookBinding[]) => void;
+    /** Revisions — when provided, adds a "History" tab. */
+    revisions?: NiceRevision[];
+    /** Rollback callback for the history tab. */
+    onRollback?: (id: string) => void;
+    /** Lazy content resolver for the history diff. */
+    loadContent?: (id: string) => Promise<string>;
+    /** Logs for the bottom dock — when provided, a NiceLogConsole is shown. */
+    logs?: NiceLogEntry[];
+    /** Clear-logs callback. */
+    onClearLogs?: () => void;
+    /** Extra tabs appended after the built-in ones (e.g. payment / webhook panels). */
+    extraTabs?: NiceConsoleTab[];
+    /** Manifest-level validation surfaced in the status bar. */
+    validate?: (manifest: Record<string, unknown>) => NiceSchemaFormError[];
+    /** Console theme. Default `'light'`. */
+    theme?: 'dark' | 'light';
+    /** Editor height. Default `560`. */
+    height?: number | string;
+    /** Optional guided tour. `true` = built-in; array/object = custom steps. Shows a "?" button. */
+    tutorial?: NiceComponentTutorial;
+}
+
+/** One editable manifest section, described by a JSON Schema or field model. */
+export declare interface NiceManifestSection {
+    id: string;
+    title: string;
+    icon?: React.ReactNode;
+    /** JSON Schema describing this section's fields (subset of the manifest). */
+    schema?: JsonSchema;
+    /** Or the repo's field-descriptor model. */
+    fields?: FormFieldDefinition[];
+    /** Per-field UI overrides forwarded to NiceSchemaForm. */
+    uiSchema?: Record<string, Partial<NiceFormItem>>;
+}
+
+/** Pluggable persistence — implement over a filesystem, API, or in-memory store. */
+export declare interface NiceModuleDataProvider {
+    listModules(): Promise<NiceModuleSummary[]>;
+    loadModule(id: string): Promise<NiceModuleFiles>;
+    saveModule(id: string, files: NiceModuleFiles): Promise<void>;
+    createModule?(input: {
+        id: string;
+        name?: string;
+    }): Promise<NiceModuleSummary>;
+}
+
+export declare const NiceModuleEditor: ForwardRefExoticComponent<NiceModuleEditorProps & RefAttributes<HTMLDivElement>>;
+
+export declare interface NiceModuleEditorProps extends NiceStandardProps {
+    /** Persistence adapter. */
+    dataProvider: NiceModuleDataProvider;
+    /** Manifest sections (schema-driven). Provide the real target schema (e.g. OmniVerk). */
+    manifestSections: NiceManifestSection[];
+    /** Entity-editor configuration (schemas, ER preview slot). */
+    entityConfig?: NiceModuleEntityConfig;
+    /** Locales offered in the i18n editor. */
+    locales?: string[];
+    /** Extra module-level validation, merged with manifest-section schema validation. */
+    validate?: (files: NiceModuleFiles) => NiceSchemaFormError[];
+    /** Wires a Scripts tab (NiceScriptRunner). */
+    scriptRunner?: NiceScriptRunnerProps;
+    /** Wires a Lifecycle tab. */
+    triggers?: NiceLifecycleTrigger[];
+    bindings?: NiceHookBinding[];
+    handlers?: NiceLifecycleHandlerOption[];
+    onBindingsChange?: (bindings: NiceHookBinding[]) => void;
+    /** Wires a History tab. */
+    revisions?: NiceRevision[];
+    onRollback?: (id: string) => void;
+    loadContent?: (id: string) => Promise<string>;
+    /** Console theme. Default `'light'`. */
+    theme?: 'dark' | 'light';
+    /** Editor height. Default `640`. */
+    height?: number | string;
+    /** Optional guided tour. `true` = built-in tour; array/object = custom steps. Shows a "?" button. */
+    tutorial?: NiceComponentTutorial;
+}
+
+export declare interface NiceModuleEntityConfig {
+    entityMetaSchema?: JsonSchema;
+    fieldSchema?: JsonSchema;
+    fieldsKey?: string;
+    nameKey?: string;
+    renderErPreview?: (entities: NiceEntity[]) => React.ReactNode;
+}
+
+/** The editable files of one module. */
+export declare interface NiceModuleFiles {
+    manifest: Record<string, unknown>;
+    entities?: NiceEntity[];
+    i18n?: NiceI18nValue;
+    /** The module's views (`*.view.json`) — unified `NiceViewDefinitionV2` standard. */
+    views?: NiceViewDefinitionV2[];
+    /** Any extra parts the adapter wants to round-trip untouched. */
+    extra?: Record<string, unknown>;
+}
+
+/** A module entry shown in the browser. */
+export declare interface NiceModuleSummary {
+    id: string;
+    name?: string;
+    category?: string;
+    description?: string;
+}
+
+export declare const NiceSchemaForm: ForwardRefExoticComponent<NiceSchemaFormProps & RefAttributes<HTMLDivElement>>;
+
+/** A single validation problem produced by {@link validateAgainstJsonSchema}. */
+export declare interface NiceSchemaFormError {
+    field: string;
+    message: string;
+}
+
+export declare interface NiceSchemaFormProps extends NiceStandardProps {
+    /** Draft-07 JSON Schema (object schema). Provide this OR `fields`. */
+    schema?: JsonSchema;
+    /** The repo's own field-descriptor model. Provide this OR `schema`. */
+    fields?: FormFieldDefinition[];
+    /** Per-field UI overrides merged onto generated items (label, type, colSpan, render, …). */
+    uiSchema?: Record<string, Partial<NiceFormItem>>;
+    /** The value being edited (controlled). */
+    value: Record<string, unknown>;
+    /** Change callback with the full updated value. */
+    onChange: (value: Record<string, unknown>) => void;
+    /** Called whenever validation runs, with the current errors. */
+    onValidate?: (errors: NiceSchemaFormError[]) => void;
+    /** Offer a Form ⇄ JSON view toggle. Default `false`. */
+    showJsonView?: boolean;
+    /** Number of layout columns. Default `1`. */
+    columns?: number;
+    /** Label placement. Default `'top'`. */
+    labelPosition?: 'top' | 'left';
+    /** Render read-only. */
+    readOnly?: boolean;
+    /** Validate on every change and show inline errors. Default `true`. */
+    liveValidation?: boolean;
+    /** Optional guided tour. `true` = built-in; array/object = custom steps. Shows a "?" button. */
+    tutorial?: NiceComponentTutorial;
 }
 
 /**
@@ -483,6 +765,15 @@ export declare function schemaToFormItems(schema: FormSchema): any[];
 
 export declare function useFormDesigner(): FormDesignerContextValue;
 
+/** Convert a {@link NiceViewDefinitionV2} back to a {@link FormSchema} (best-effort). */
+export declare function v2ToFormSchema(view: NiceViewDefinitionV2): FormSchema;
+
+/**
+ * Validate a value object against a (subset of) Draft-07 JSON Schema.
+ * Covers required, type, enum, minLength/maxLength, minimum/maximum and pattern.
+ */
+export declare function validateAgainstJsonSchema(value: Record<string, unknown>, schema: JsonSchema): NiceSchemaFormError[];
+
 /**
  * Validate form schema
  */