@nice2dev/ui-forms 1.4.12 → 1.4.14

package/dist/index.d.ts

@@ -90,6 +90,15 @@ export declare function entitiesToSchemas(entities: readonly Row_2[]): NiceDataS
 /** The file name of a path. */
 export declare const fileName: (path: string) => string;
 
+/**
+ * The files that refer to `name` by `rules`, with how many references each holds — what a rename
+ * would rewrite.
+ */
+export declare function findStudioReferences(files: readonly NiceStudioTextFile[], rules: readonly NiceStudioReferenceRule[], name: string, options?: NiceStudioRenameOptions): Array<{
+    path: string;
+    count: number;
+}>;
+
 /**
  * A section narrowed to the properties a form can edit in this manifest: a value that does not fit
  * its property's schema ({@link jsonValueFitsSchema}) leaves the section and is edited as JSON
@@ -243,6 +252,9 @@ export declare function inferStudioScriptKind(raw: Row): NiceStudioScriptKind;
 /** Whether a layout holds nothing (its file can go). */
 export declare const isEmptyStudioLayout: (layout: NiceStudioLayout) => boolean;
 
+/** Whether folder `id` is `ancestor` or sits, at any depth, inside it. */
+export declare function isStudioFolderWithin(layout: NiceStudioLayout, id: string, ancestor: string): boolean;
+
 /** Whether a path is a module's layout file. */
 export declare const isStudioLayoutPath: (path: string) => boolean;
 
@@ -324,6 +336,17 @@ export declare function manifestSectionKeys(sections: readonly NiceManifestSecti
 /** The prefix a module's files share (`orders` of `orders.manifest.json`). */
 export declare function modulePrefix(files: readonly NiceStudioFile[]): string;
 
+/**
+ * The layout with a folder moved (1.4.14): into another folder of its group (its section follows that
+ * folder's), into a section, or to its group's top (`{}`). The folders and entries inside it come
+ * along into the same section. A move into itself or a folder inside it, or into a folder of another
+ * group, leaves the layout as it was.
+ */
+export declare function moveStudioFolder(layout: NiceStudioLayout, folderId: string, target: {
+    parent?: string;
+    section?: string;
+}): NiceStudioLayout;
+
 export declare const nativeDataSourcesKind: NiceStudioFileKind<NiceDataSourceDef[]>;
 
 export declare const nativeEntitiesKind: NiceStudioFileKind<Row_3[]>;
@@ -354,6 +377,17 @@ 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;
 
+/**
+ * Where the native files refer to an entity or a data source by name (1.4.15):
+ * - entities: a field's `references`, a view's data source `entity` and the standard sources
+ *   `{name}All` / `{name}ById`, a workflow's `entityType`, a data source's tables (an entity without
+ *   `tableName`), access resources (`entity:{name}`) and their grants, translation keys, a no-code
+ *   script's `target`, an integration operation's `source` / `target`;
+ * - data source keys: a view's `ref`, a script's `source` / `target`, a union's `sources`, an
+ *   integration operation's `source`.
+ */
+export declare const nativeStudioReferences: NiceStudioReferenceRules;
+
 export declare const nativeViewsKind: NiceStudioFileKind<NiceStudioItem<NiceViewDefinition>[]>;
 
 export declare const nativeWorkflowsKind: NiceStudioFileKind<NiceStudioItem<NiceWorkflowDefinition>[]>;
@@ -814,6 +848,21 @@ export declare interface NiceStudioCodecContext {
     locales: readonly string[];
 }
 
+/** A module another module depends on (1.4.15 — the tree's Dependencies group, OmniVerk wishlist #1). */
+export declare interface NiceStudioDependency {
+    /** The module it names: its id or package name. */
+    id: string;
+    /** Needed (`true`) or optional (`false`); unknown when absent. */
+    required?: boolean;
+    /** Why the module needs it. */
+    reason?: string;
+    minVersion?: string;
+    /** Declared in the manifest, or only referred to (a field of an entity of that module). */
+    via: 'manifest' | 'reference';
+    /** The entities of that module the files refer to. */
+    refers?: string[];
+}
+
 /** A document of an open module: the files one editor works on. */
 export declare interface NiceStudioDocument<M = unknown> {
     /** Stable within the module: `${kind.id}:${group}`. */
@@ -1168,6 +1217,13 @@ export declare interface NiceStudioPreset {
     requiredLocales?: string[];
     /** The module's id from its files (e.g. the manifest's `packageName`). */
     moduleId?(files: readonly NiceStudioFile[]): string | undefined;
+    /**
+     * Where the module's files refer to an entity or a data source by name (1.4.15): renaming one in
+     * the studio rewrites these places too. Without it, a rename changes only the entity itself.
+     */
+    references?: NiceStudioReferenceRules;
+    /** The modules a module depends on, for the tree's Dependencies group (1.4.15). */
+    dependencies?(ctx: NiceStudioModuleContext): NiceStudioDependency[];
     validateModule?(ctx: NiceStudioModuleContext): NiceStudioIssue[];
     generateModule?(spec: NiceStudioModuleSpec, ctx: {
         existingIds: ReadonlySet<string>;
@@ -1249,6 +1305,71 @@ export declare interface NiceStudioProvider {
     rollback?(key: NiceStudioModuleKey, revisionId: string, path?: string): Promise<void>;
 }
 
+/** One kind of place a name is referred to in a module's files. */
+export declare type NiceStudioReferenceRule = {
+    /** A property, at any depth, whose string value (or each string of its array) holds the name. */
+    prop: string;
+    /**
+     * How the value holds it: all of it (default); its first part before a `.` (`Order.Status`,
+     * `Order.Created`); its last part after a `.` or `/` (`Sales.Order`, `Sales/Order` — only with
+     * the module's own qualifiers); or the part before a `?` (`Order?filter=…`).
+     */
+    part?: 'whole' | 'head' | 'tail' | 'query';
+    /** Text before the name in the value (`entity:`). */
+    prefix?: string;
+    /** Only objects held by this key (an array's or object's key): `tables`, `relations`. */
+    within?: string;
+    /** Refers to the entity's table, which is its name only while it has no `tableName`. */
+    table?: boolean;
+    /** Only files whose path matches. */
+    files?: RegExp;
+} | {
+    /**
+     * The keys of the object held by this key (at any depth; `a.b` for nested keys) are names:
+     * `seeds`, `demoSeeds`, `grants`.
+     */
+    keysOf: string;
+    prefix?: string;
+    files?: RegExp;
+} | {
+    /** A property whose string value is JSON text: the rules apply inside it (`viewJson`). */
+    jsonIn: string;
+    files?: RegExp;
+} | {
+    /** Object keys built from the name: `{name}` marks it (`entity.{name}.`, `field.{name}.`). */
+    keyPattern: string;
+    files?: RegExp;
+} | {
+    /** A whole string value, anywhere, built from the name: `{name}All`, `{name}ById`. */
+    value: string;
+    files?: RegExp;
+};
+
+/** The rules of a preset, by what is renamed. */
+export declare interface NiceStudioReferenceRules {
+    entity?: NiceStudioReferenceRule[];
+    dataSource?: NiceStudioReferenceRule[];
+}
+
+export declare interface NiceStudioRenameOptions {
+    /**
+     * The module's own names a qualified reference may carry (`Sales` in `Sales.Order`): its id, its
+     * package. Qualified references to other modules are never touched.
+     */
+    qualifiers?: readonly string[];
+    /** Only qualified references (`Sales.Order`) — for the other modules that refer to this one. */
+    qualifiedOnly?: boolean;
+    /** The renamed entity has its own `tableName`: rules about its table do not apply. */
+    ownTable?: boolean;
+}
+
+export declare interface NiceStudioRenameResult {
+    /** The files that changed, with their new text. */
+    files: NiceStudioTextFile[];
+    /** How many references were rewritten. */
+    count: number;
+}
+
 /** A saved earlier version of a module or one of its files. */
 export declare interface NiceStudioRevision {
     id: string;
@@ -1362,6 +1483,12 @@ export declare interface NiceStudioTemplateModule {
     description?: string;
 }
 
+/** A file as the studio holds it. */
+export declare interface NiceStudioTextFile {
+    path: string;
+    text: string;
+}
+
 /** Translations of one document: `{ en: { key: text }, pl: { … } }` (the shape of NiceI18nEditor). */
 export declare type NiceStudioTranslations = Record<string, Record<string, string>>;
 
@@ -1400,6 +1527,12 @@ export declare type NiceStudioWriteResult = {
 /** A file whose whole content is the model (a manifest, an access model). */
 export declare function objectFileKind<T extends object>(o: NiceObjectFileKindOptions): NiceStudioFileKind<T>;
 
+/**
+ * The layout with entries put in this order among their siblings (1.4.14 — dragging rows of the
+ * tree): each gets `order` = its index; their section and folder stay.
+ */
+export declare function orderStudioEntries(layout: NiceStudioLayout, refs: readonly string[]): NiceStudioLayout;
+
 /** Parses JSON text that may start with a BOM, and tells how it is written. */
 export declare function parseJsonText(text: string): {
     value: unknown;
@@ -1424,7 +1557,8 @@ export declare function patchJsonTextDetailed(previous: string, next: unknown, o
 
 /**
  * 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 (`{}`).
+ * section (out of any folder), or back to its group (`{}`). A folder of another group (1.4.14 — a
+ * drag can aim anywhere) leaves the layout as it was.
  */
 export declare function placeStudioEntry(layout: NiceStudioLayout, ref: string, target: {
     folder?: string;
@@ -1452,6 +1586,12 @@ export declare function renameStudioLayoutNode(layout: NiceStudioLayout, node: {
     id: string;
 }, label: string): NiceStudioLayout;
 
+/**
+ * The files with every reference to `from` renamed to `to`, by `rules`. Only JSON files are read;
+ * a file that does not parse is left alone. Returns the changed files and the count.
+ */
+export declare function renameStudioReferences(files: readonly NiceStudioTextFile[], rules: readonly NiceStudioReferenceRule[], from: string, to: string, options?: NiceStudioRenameOptions): NiceStudioRenameResult;
+
 /** The kind a path opens with: the first that matches, else JSON or text. */
 export declare function resolveFileKind(kinds: readonly NiceStudioFileKind[], path: string): NiceStudioFileKind;
 
@@ -1483,6 +1623,13 @@ 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;
 
+/**
+ * A module's dependencies (1.4.15 — OmniVerk wishlist #1): the declared ones, each with the entities
+ * of it the files refer to, then the modules only referred to (`Other.Entity` in a field) that are
+ * not declared. Qualifiers are matched without regard to `.` / `/` and case.
+ */
+export declare function studioDependencies(declared: readonly NiceStudioDependency[], files: readonly NiceStudioTextFile[], rules: readonly NiceStudioReferenceRule[], own?: readonly string[]): NiceStudioDependency[];
+
 /** The ref of an entry in a layout: `group:key`. */
 export declare const studioEntryRef: (group: string, key: string) => string;
 
@@ -1492,6 +1639,17 @@ export declare const studioEntryRef: (group: string, key: string) => string;
  */
 export declare function studioLayoutPath(files: readonly NiceStudioFile[]): string;
 
+/**
+ * The qualified references (`Other.Entity`, `Other/Entity`) in the places `rules` mark with
+ * `part: 'tail'` whose qualifier is not one of `own` — the other modules a module refers to, for its
+ * dependencies.
+ */
+export declare function studioQualifiedReferences(files: readonly NiceStudioTextFile[], rules: readonly NiceStudioReferenceRule[], own?: readonly string[]): Array<{
+    qualifier: string;
+    name: string;
+    path: string;
+}>;
+
 /** `"Send invoice"` → `sendInvoice`: a name usable as a function's. */
 export declare function studioScriptIdentifier(name: string): string;