@nice2dev/ui-forms 1.4.4 → 1.4.6

package/dist/index.d.ts

@@ -8,6 +8,8 @@ import { NiceDataSourceSchemaTable } from '@nice2dev/ui';
 import { NiceFieldValidationRule } from '@nice2dev/ui';
 import { NiceFormItem } from '@nice2dev/ui';
 import { NiceHookBinding } from '@nice2dev/ui';
+import { NiceNoCodeIo } from '@nice2dev/ui';
+import { NiceNoCodeStep } from '@nice2dev/ui';
 import { NiceRbacModel } from '@nice2dev/ui';
 import { NiceScriptRunnerProps } from '@nice2dev/ui';
 import { NiceStandardProps } from '@nice2dev/ui';
@@ -16,6 +18,18 @@ import { NiceViewDefinition } from '@nice2dev/ui';
 import { NiceWorkflowDefinition } from '@nice2dev/ui';
 import { RefAttributes } from 'react';
 
+/** The layout with a new folder in `group` (inside `parent` / `section`); returns its id too. */
+export declare function addStudioFolder(layout: NiceStudioLayout, folder: Omit<NiceStudioLayoutFolder, 'id'>): {
+    layout: NiceStudioLayout;
+    id: string;
+};
+
+/** The layout with a new section; returns the layout and the section's id. */
+export declare function addStudioSection(layout: NiceStudioLayout, label: string): {
+    layout: NiceStudioLayout;
+    id: string;
+};
+
 /** Generated fields → NiceSchemaForm fields, with their validation rules. */
 export declare function aiFormConfigToFormFields(config: {
     fields: readonly NiceAIFormFieldLike[];
@@ -46,17 +60,20 @@ export declare function defineManifestSection<TSchema extends JsonSchema>(sectio
 
 /** A starter access model: admin / user × view / create / edit / delete over the module's views and entities. */
 export declare function deriveDefaultRbac(module: {
-    manifest?: Row;
+    manifest?: Row_2;
     views?: ReadonlyArray<{
         id: string;
         name: string;
     }>;
-    entities?: readonly Row[];
+    entities?: readonly Row_2[];
 }): NiceRbacModel;
 
 /** Reads how `text` is written: BOM, line breaks, indentation, final newline, colon spacing. */
 export declare function detectJsonTextFormat(text: string): NiceJsonTextFormat;
 
+/** An empty layout: no sections, no folders — the flat tree. */
+export declare const emptyStudioLayout: () => NiceStudioLayout;
+
 /**
  * The file changes that store a document's new model: only files whose text differs from what
  * was read, plus files the encoder adds or removes.
@@ -67,7 +84,7 @@ export declare function encodeDocument(doc: NiceStudioDocument, model: unknown,
 export declare const endsWithAny: (...suffixes: string[]) => (path: string) => boolean;
 
 /** The module's entities as the tables NiceDataSourceBuilder queries. */
-export declare function entitiesToSchemas(entities: readonly Row[]): NiceDataSourceSchemaTable[];
+export declare function entitiesToSchemas(entities: readonly Row_2[]): NiceDataSourceSchemaTable[];
 
 /** The file name of a path. */
 export declare const fileName: (path: string) => string;
@@ -207,12 +224,27 @@ export declare interface FormSectionDefinition {
     fields: FormFieldDefinition[];
 }
 
+/** A list item back as the stored script: its definition merged onto the entry as stored. */
+export declare function fromStudioScriptItem(item: NiceStudioItem<NiceStudioScriptDef>): unknown;
+
 /**
  * Translations split into one file per language, edited as one document. A new language gets a
  * file shaped and formatted like its siblings; a language removed in the editor loses its file.
  */
 export declare function i18nFileKind(o?: NiceI18nFileKindOptions): NiceStudioFileKind<NiceStudioTranslations>;
 
+/**
+ * The kind of a stored script: its `kind`, else from what it holds — no-code steps, a SQL language
+ * or `sql` text, a C# language (server) — else browser code.
+ */
+export declare function inferStudioScriptKind(raw: Row): NiceStudioScriptKind;
+
+/** Whether a layout holds nothing (its file can go). */
+export declare const isEmptyStudioLayout: (layout: NiceStudioLayout) => boolean;
+
+/** Whether a path is a module's layout file. */
+export declare const isStudioLayoutPath: (path: string) => boolean;
+
 /**
  * A file holding a list of entries edited one at a time (views, workflows). Entries the editor
  * does not understand stay raw and round-trip as they are.
@@ -293,7 +325,7 @@ export declare function modulePrefix(files: readonly NiceStudioFile[]): string;
 
 export declare const nativeDataSourcesKind: NiceStudioFileKind<NiceDataSourceDef[]>;
 
-export declare const nativeEntitiesKind: NiceStudioFileKind<Row_2[]>;
+export declare const nativeEntitiesKind: NiceStudioFileKind<Row_3[]>;
 
 /** The file kinds of the native format, in matching order. */
 export declare const nativeFileKinds: NiceStudioFileKind[];
@@ -302,17 +334,29 @@ export declare const nativeHooksKind: NiceStudioFileKind<NiceHookBinding[]>;
 
 export declare const nativeI18nKind: NiceStudioFileKind<NiceStudioTranslations>;
 
-export declare const nativeManifestKind: NiceStudioFileKind<Row_2>;
+export declare const nativeManifestKind: NiceStudioFileKind<Row_3>;
 
 export declare const nativeRbacKind: NiceStudioFileKind<NiceRbacModel>;
 
-/** The studio's own format: manifest, entities, translations, views, workflows, data sources, access, hooks. */
+/** `{id}.scripts.json`: `{ scripts: [...], phases: { postInstall: [...] } }` (1.4.6). */
+export declare const nativeScriptsKind: NiceStudioFileKind<NiceStudioScripts>;
+
+/** The studio's own format: manifest, entities, translations, views, workflows, data sources, access, hooks, scripts. */
 export declare const nativeStudioPreset: NiceStudioPreset;
 
 export declare const nativeViewsKind: NiceStudioFileKind<NiceStudioItem<NiceViewDefinition>[]>;
 
 export declare const nativeWorkflowsKind: NiceStudioFileKind<NiceStudioItem<NiceWorkflowDefinition>[]>;
 
+/** A new script of a kind, with a starting body in its language. */
+export declare function newStudioScript(spec: NiceStudioNewScript): NiceStudioScriptDef;
+
+/** The script kinds, in the order "Add script" offers them. */
+export declare const NICE_STUDIO_SCRIPT_KINDS: readonly NiceStudioScriptKind[];
+
+/** Install phases offered for database scripts when the preset names none. */
+export declare const NICE_STUDIO_SCRIPT_PHASES: readonly string[];
+
 /** A generated field, as an AI form generator describes it. */
 export declare interface NiceAIFormFieldLike {
     id?: string;
@@ -409,6 +453,11 @@ export declare interface NiceDevelopmentStudioProps extends NiceStandardProps {
     reviewBeforeSave?: boolean;
     /** Runs script files (`script` documents) in a NiceScriptRunner. */
     scriptRunner?: Omit<NiceScriptRunnerProps, 'value' | 'onChange'>;
+    /**
+     * The host's data for a module's no-code scripts (1.4.6): with it the script editor's Run runs
+     * the steps against it (`read` a data source, `write` rows, `callScript`).
+     */
+    scriptIo?: (module: NiceStudioModuleKey) => NiceNoCodeIo | undefined;
     /** The host's own preview of a view (e.g. its runtime renderer): small in the preview, full beside the designer. */
     renderViewPreview?: (ctx: NiceStudioViewPreviewContext) => React.ReactNode;
     /** Extra parts of a module (payments, webhooks, …): rows under the module, opened full-screen. */
@@ -703,6 +752,22 @@ export declare interface NiceSchemaFormProps extends NiceStandardProps {
     tutorial?: NiceComponentTutorial;
 }
 
+/** Options of {@link scriptsFileKind}. */
+export declare interface NiceScriptsFileKindOptions {
+    id?: string;
+    label?: string;
+    labelKey?: string;
+    icon?: string;
+    match(path: string): boolean;
+    /** The property holding the scripts list. Default `scripts`; the file may also be the bare list. */
+    property?: string;
+    /**
+     * The property holding the database scripts per phase. Default `phases`. The same as `property`:
+     * that property holds either — a list of scripts or an object of phases (OmniVerk).
+     */
+    phasesProperty?: string;
+}
+
 /** A host's own action in the studio's tree header (e.g. "Open a folder…"). */
 export declare interface NiceStudioAction {
     key: string;
@@ -713,6 +778,11 @@ export declare interface NiceStudioAction {
     onSelect: () => void;
 }
 
+/** The studio's own editors. */
+export declare type NiceStudioBuiltinEditorId = 'manifest' | 'entities' | 'i18n' | 'views' | 'workflows' | 'permissions' | 'rbac' | 'dataSources' | 'seeds' | 'hooks' | 'script'
+/** A list of named scripts and database scripts per phase ({@link NiceStudioScripts}, 1.4.6). */
+| 'scriptList' | 'json' | 'text';
+
 /** What a file kind's decode and encode know about the module. */
 export declare interface NiceStudioCodecContext {
     moduleId: string;
@@ -734,8 +804,11 @@ export declare interface NiceStudioDocument<M = unknown> {
     error?: string;
 }
 
-/** The built-in editors a file kind can open in. */
-export declare type NiceStudioEditorId = 'manifest' | 'entities' | 'i18n' | 'views' | 'workflows' | 'permissions' | 'rbac' | 'dataSources' | 'seeds' | 'hooks' | 'script' | 'json' | 'text';
+/**
+ * The editors a file kind can open in: a built-in one, or the id of an editor the host registers
+ * (1.4.5 — the union was closed; an unknown id opens as raw JSON / text until one is registered).
+ */
+export declare type NiceStudioEditorId = NiceStudioBuiltinEditorId | (string & {});
 
 /** New and removed files of an encoded document. */
 export declare interface NiceStudioEncoded {
@@ -795,6 +868,11 @@ export declare interface NiceStudioFileKind<M = unknown> {
     /** The document a file belongs to (files with the same group open together). Default: the path. */
     group?(path: string): string;
     editor: NiceStudioEditorId;
+    /**
+     * The tree group its documents are listed under (1.4.5): one of the preset's `groups`, or a
+     * built-in group id. Default: the built-in group of its editor (none for raw JSON / text).
+     */
+    treeGroup?: string;
     /** The files of one document → the editor's model. Throwing opens the files as raw JSON / text. */
     decode(files: readonly NiceStudioFile[], ctx: NiceStudioCodecContext): M;
     /** The model → the document's files (only their text; unchanged files may be returned as they were). */
@@ -811,6 +889,20 @@ export declare interface NiceStudioGeneratedModule {
     }>;
 }
 
+/**
+ * A group of the tree a preset adds (1.4.5): its documents — of the kinds whose `treeGroup` names
+ * it — are listed one per row under it, like scripts.
+ */
+export declare interface NiceStudioGroupDef {
+    id: string;
+    label: string;
+    labelKey?: string;
+    /** NiceIcon name. */
+    icon?: string;
+    /** Where it goes among the groups (the built-in ones are 10, 20, … 100). Default: after them. */
+    order?: number;
+}
+
 /** A problem found in a module. */
 export declare interface NiceStudioIssue {
     severity: 'error' | 'warning' | 'info';
@@ -844,6 +936,40 @@ export declare interface NiceStudioItem<D> {
     rawReason?: string;
 }
 
+/** The layout of a module — the content of its `{prefix}.studio.json`. */
+export declare interface NiceStudioLayout {
+    version: 1;
+    sections: NiceStudioLayoutSection[];
+    folders: NiceStudioLayoutFolder[];
+    /** By entry ref, `group:key` — `entities:Customer`, `views:customer-list`. */
+    placement: Record<string, NiceStudioLayoutPlacement>;
+}
+
+/** A folder inside one group of a module (entities, views…), optionally nested and in a section. */
+export declare interface NiceStudioLayoutFolder {
+    id: string;
+    label: string;
+    /** The group it belongs to: `entities`, `views`, `workflows`, a preset's own group… */
+    group: string;
+    /** The folder it sits in. */
+    parent?: string;
+    /** The section it sits in (absent: the module's own groups). */
+    section?: string;
+}
+
+/** Where one entry sits: a section, a folder, an order among its siblings. */
+export declare interface NiceStudioLayoutPlacement {
+    section?: string;
+    folder?: string;
+    order?: number;
+}
+
+/** A section of a module: a band of the tree that holds groups (Sales, Warehouse…). */
+export declare interface NiceStudioLayoutSection {
+    id: string;
+    label: string;
+}
+
 /** What validators and generators get. */
 export declare interface NiceStudioModuleContext {
     key: NiceStudioModuleKey;
@@ -909,6 +1035,16 @@ export declare interface NiceStudioModuleSpec {
     permissions?: boolean;
 }
 
+/** What "Add script" asks for. */
+export declare interface NiceStudioNewScript {
+    kind: NiceStudioScriptKind;
+    /** The display name; the script's `name` is made from it. */
+    name: string;
+    language?: string;
+    category?: string;
+    trigger?: string;
+}
+
 /** A group of modules in a workspace (a category, a product line). */
 export declare interface NiceStudioPackage {
     id: string;
@@ -919,6 +1055,11 @@ export declare interface NiceStudioPackage {
     /** Computed from the modules (e.g. their `category`) rather than stored: it cannot be edited. */
     derived?: boolean;
     readOnly?: boolean;
+    /**
+     * The package it sits in (1.4.5): packages nest in the tree. An id with `/` (`Finance/Banking`, an
+     * OmniVerk category path) nests under the part before its last `/` without it.
+     */
+    parentId?: string;
 }
 
 /** An extra part of a module (payments, webhooks — anything host-specific): a row under the module in the tree, its content full-screen. */
@@ -951,6 +1092,8 @@ export declare interface NiceStudioPreset {
     id: string;
     /** Tried in order; a path no kind matches opens as raw JSON (`*.json`) or text. */
     kinds: NiceStudioFileKind[];
+    /** Groups of the tree the preset adds to the built-in ones (1.4.5). */
+    groups?: NiceStudioGroupDef[];
     /** The manifest's sections, each a form over part of the manifest. */
     manifestSections?: NiceManifestSection[];
     entities?: NiceStudioEntityOptions;
@@ -974,6 +1117,8 @@ export declare interface NiceStudioPreset {
         path: string;
         text: string;
     } | undefined;
+    /** Kinds, categories, triggers and phases of the module's scripts (1.4.6). */
+    scripts?: NiceStudioScriptOptions;
     /** Lifecycle triggers offered by a `hooks` document. */
     hooks?: {
         triggers: Array<{
@@ -1045,6 +1190,73 @@ export declare interface NiceStudioRevision {
     path?: string;
 }
 
+/** A named script of a module (1.4.6). Fields the studio does not edit stay in the stored entry. */
+export declare interface NiceStudioScriptDef {
+    id?: string;
+    /** The name other scripts and the app call it by (unique in the module). */
+    name: string;
+    displayName?: string;
+    description?: string;
+    kind: NiceStudioScriptKind;
+    /** `typescript`, `javascript`, `csharp`, `sql`… (none for a no-code script). */
+    language?: string;
+    /** Free grouping: `formatting`, `validation`, `integration`… */
+    category?: string;
+    /** What runs it: an event, a schedule, a button (one of the preset's `scripts.triggers`). */
+    trigger?: string;
+    parameters?: NiceStudioScriptParameter[];
+    returnType?: string;
+    /** The code (frontend, backend, SQL). */
+    source?: string;
+    /** A file of the module holding the code instead of `source`. */
+    sourcePath?: string;
+    /** The steps of a no-code script. */
+    steps?: NiceNoCodeStep[];
+}
+
+/**
+ * What a script is (1.4.6): code run in the browser (`frontend`), code run on the server
+ * (`backend`), no-code steps (`noCode`, run by `runNoCodeScript`) or a SQL query or procedure.
+ */
+export declare type NiceStudioScriptKind = 'frontend' | 'backend' | 'noCode' | 'sql';
+
+/** How a preset's scripts look (1.4.6). */
+export declare interface NiceStudioScriptOptions {
+    /** The kinds "Add script" offers. Default: all four. */
+    kinds?: NiceStudioScriptKind[];
+    /** Categories offered (the module's own are offered too). */
+    categories?: string[];
+    /** What can run a script. */
+    triggers?: Array<{
+        id: string;
+        label: string;
+        description?: string;
+    }>;
+    /** Install phases offered for database scripts. Default: preInstall, postInstall, preUninstall, postUninstall. */
+    phases?: string[];
+}
+
+/** A parameter of a script. */
+export declare interface NiceStudioScriptParameter {
+    name: string;
+    /** Its type as the script's language writes it (`string`, `Date | string`, `decimal`). */
+    type?: string;
+    description?: string;
+    default?: unknown;
+}
+
+/** The model of the `scriptList` editor (1.4.6): named scripts and database scripts per phase. */
+export declare interface NiceStudioScripts {
+    scripts: Array<NiceStudioItem<NiceStudioScriptDef>>;
+    /** SQL statements per install phase: `{ postInstall: ['CREATE INDEX …'] }`. */
+    phases?: Record<string, string[]>;
+    /**
+     * What the file can hold when one property keeps either (OmniVerk's `scripts` is a list of
+     * scripts or an object of phases): only named scripts, or only phases. Absent: both.
+     */
+    holds?: 'scripts' | 'phases';
+}
+
 /** The model of the `seeds` editor: rows per entity, plus demo rows. */
 export declare interface NiceStudioSeeds {
     seeds: Record<string, Array<Record<string, unknown>>>;
@@ -1123,6 +1335,12 @@ export declare function parseJsonText(text: string): {
     format: NiceJsonTextFormat;
 };
 
+/**
+ * A layout from its file's text — what it can read of it: unknown fields and broken entries are
+ * dropped, a text that does not parse gives the empty layout.
+ */
+export declare function parseStudioLayout(text: string | undefined): NiceStudioLayout;
+
 /**
  * `previous` with its content replaced by `next`, changing as few bytes as possible. Falls back
  * to {@link stringifyJsonText} in the file's own format when the text cannot be patched (invalid
@@ -1133,9 +1351,36 @@ export declare function patchJsonText(previous: string, next: unknown, options?:
 /** {@link patchJsonText}, also telling whether the patch was exact. */
 export declare function patchJsonTextDetailed(previous: string, next: unknown, options?: NiceJsonPatchOptions): NiceJsonPatchResult;
 
+/**
+ * The layout with an entry put somewhere: into a folder (its section follows the folder's), into a
+ * section (out of any folder), or back to its group (`{}`).
+ */
+export declare function placeStudioEntry(layout: NiceStudioLayout, ref: string, target: {
+    folder?: string;
+    section?: string;
+}): NiceStudioLayout;
+
 /** The translations inside a file: `translations`, `keys`, or the whole file when it is a flat map. */
 export declare function readTranslations(root: unknown): Record<string, string>;
 
+/**
+ * The layout without a section or folder. What it held moves up: a folder's entries and folders go
+ * to its parent (or the group), a section's folders and entries back to the module's own groups.
+ */
+export declare function removeStudioLayoutNode(layout: NiceStudioLayout, node: {
+    kind: 'section' | 'folder';
+    id: string;
+}): NiceStudioLayout;
+
+/** The layout after an entry was renamed — its placement follows it (`entities:Old` → `entities:New`). */
+export declare function renameStudioEntryRef(layout: NiceStudioLayout, from: string, to: string): NiceStudioLayout;
+
+/** The layout with a section or folder renamed. */
+export declare function renameStudioLayoutNode(layout: NiceStudioLayout, node: {
+    kind: 'section' | 'folder';
+    id: string;
+}, label: string): NiceStudioLayout;
+
 /** The kind a path opens with: the first that matches, else JSON or text. */
 export declare function resolveFileKind(kinds: readonly NiceStudioFileKind[], path: string): NiceStudioFileKind;
 
@@ -1143,21 +1388,51 @@ declare type Row = Record<string, unknown>;
 
 declare type Row_2 = Record<string, unknown>;
 
+declare type Row_3 = Record<string, unknown>;
+
 /** Parses JSON without a BOM and returns `fallback` when the text is not JSON. */
 export declare function safeJson<T = unknown>(text: string, fallback: T): T;
 
 /** Convert a FormSchema into DevExtreme-style form items. */
 export declare function schemaToFormItems(schema: FormSchema): any[];
 
+/**
+ * A file of named scripts and database scripts per phase (the `scriptList` editor). Scripts the
+ * form does not understand stay raw and round-trip as they are; a file whose phases are not lists
+ * of SQL text opens as raw JSON.
+ */
+export declare function scriptsFileKind(o: NiceScriptsFileKindOptions): NiceStudioFileKind<NiceStudioScripts>;
+
+/** A layout's file text: two-space JSON with a final newline, in the line ending of `previous`. */
+export declare function serializeStudioLayout(layout: NiceStudioLayout, previous?: string): string;
+
 /** A file-name-safe id out of a display name: "Bike rental" → `bike-rental`. */
 export declare function slugifyModuleId(name: string): string;
 
 /** Writes `value` in a given format (defaults: two spaces, LF, final newline, no BOM). */
 export declare function stringifyJsonText(value: unknown, format?: Partial<NiceJsonTextFormat>): string;
 
+/** The ref of an entry in a layout: `group:key`. */
+export declare const studioEntryRef: (group: string, key: string) => string;
+
+/**
+ * The path of a module's layout file: the one it has, else `{prefix}.studio.json` after the prefix
+ * of its files, else `module.studio.json`.
+ */
+export declare function studioLayoutPath(files: readonly NiceStudioFile[]): string;
+
+/** `"Send invoice"` → `sendInvoice`: a name usable as a function's. */
+export declare function studioScriptIdentifier(name: string): string;
+
+/** The languages of a kind, the first being the default (none for no-code). */
+export declare function studioScriptLanguages(kind: NiceStudioScriptKind): string[];
+
 /** Any other file, edited as text. */
 export declare const textFallbackKind: NiceStudioFileKind<string>;
 
+/** A stored script as a list item: with a definition when the form can keep every field it edits. */
+export declare function toStudioScriptItem(raw: unknown, index: number): NiceStudioItem<NiceStudioScriptDef>;
+
 /**
  * Validate a value object against a (subset of) Draft-07 JSON Schema.
  * Covers required, type, enum, minLength/maxLength, minimum/maximum and pattern.