@nice2dev/ui-forms 1.4.4 → 1.4.5

package/dist/index.d.ts

@@ -16,6 +16,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[];
@@ -57,6 +69,9 @@ export declare function deriveDefaultRbac(module: {
 /** 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.
@@ -213,6 +228,12 @@ export declare interface FormSectionDefinition {
  */
 export declare function i18nFileKind(o?: NiceI18nFileKindOptions): NiceStudioFileKind<NiceStudioTranslations>;
 
+/** 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.
@@ -713,6 +734,9 @@ 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' | 'json' | 'text';
+
 /** What a file kind's decode and encode know about the module. */
 export declare interface NiceStudioCodecContext {
     moduleId: string;
@@ -734,8 +758,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 +822,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 +843,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 +890,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;
@@ -919,6 +999,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 +1036,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;
@@ -1123,6 +1210,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 +1226,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;
 
@@ -1149,12 +1269,24 @@ 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 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;
+
 /** Any other file, edited as text. */
 export declare const textFallbackKind: NiceStudioFileKind<string>;