@nice2dev/ui-forms 1.3.10 → 1.3.11

package/dist/studio.d.ts

@@ -0,0 +1,796 @@
+import { default as default_2 } from 'react';
+import { NiceDataSourceDef } from '@nice2dev/ui';
+import { NiceDataSourceSchemaTable } from '@nice2dev/ui';
+import { NiceFormItem } from '@nice2dev/ui';
+import { NiceHookBinding } from '@nice2dev/ui';
+import { NiceRbacModel } from '@nice2dev/ui';
+import { NiceViewDefinition } from '@nice2dev/ui';
+import { NiceWorkflowDefinition } from '@nice2dev/ui';
+
+/** A file holding one array, either bare or under `property`; the rest of the file is kept. */
+export declare function arrayFileKind<T>(o: NiceArrayFileKindOptions): NiceStudioFileKind<T[]>;
+
+/**
+ * The documents of a module: files grouped by kind and group, each decoded. A document whose
+ * files a kind cannot decode — or would not store unchanged — opens raw, one JSON / text
+ * document per file, with the error.
+ */
+export declare function buildDocuments(kinds: readonly NiceStudioFileKind[], files: readonly NiceStudioFile[], ctx: NiceStudioCodecContext): NiceStudioDocument[];
+
+/** A provider over modules held in memory, with versions, conflicts and revisions. */
+export declare function createMemoryStudioProvider(options: NiceMemoryStudioOptions): NiceMemoryStudioProvider;
+
+/**
+ * Identity helper that infers the precise `schema` type from a section literal,
+ * so consumers can write a plain JSON-Schema object without `as JsonSchema`
+ * assertions. `const general = defineManifestSection({ id, title, schema: {…} });`
+ */
+export declare function defineManifestSection<TSchema extends JsonSchema>(section: NiceManifestSection<TSchema>): NiceManifestSection<TSchema>;
+
+/** A starter access model: admin / user × view / create / edit / delete over the module's views and entities. */
+export declare function deriveDefaultRbac(module: {
+    manifest?: Row;
+    views?: ReadonlyArray<{
+        id: string;
+        name: string;
+    }>;
+    entities?: readonly Row[];
+}): NiceRbacModel;
+
+/** Reads how `text` is written: BOM, line breaks, indentation, final newline, colon spacing. */
+export declare function detectJsonTextFormat(text: string): NiceJsonTextFormat;
+
+/**
+ * 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.
+ */
+export declare function encodeDocument(doc: NiceStudioDocument, model: unknown, files: readonly NiceStudioFile[], ctx: NiceStudioCodecContext): NiceStudioFileChange[];
+
+/** Ends with one of the suffixes (case-insensitive). */
+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[];
+
+/** The file name of a path. */
+export declare const fileName: (path: string) => string;
+
+/**
+ * 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
+ * among the "Other properties".
+ */
+export declare function fitManifestSection(section: NiceManifestSection, manifest: Record<string, unknown>): {
+    section: NiceManifestSection;
+    keys: string[];
+};
+
+/** Conditional visibility rule. */
+declare interface FormFieldCondition {
+    field: string;
+    operator: 'equals' | 'notEquals' | 'contains' | 'greaterThan' | 'lessThan' | 'isEmpty' | 'isNotEmpty';
+    value?: any;
+}
+
+/** Form field definition. */
+declare interface FormFieldDefinition {
+    /** Unique field ID */
+    id: string;
+    /** Field type */
+    type: FormFieldType;
+    /** Field name (for form data) */
+    name: string;
+    /** Display label */
+    label?: string;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Help text */
+    helpText?: string;
+    /** Default value */
+    defaultValue?: any;
+    /** Options for select/radio fields. Plain strings are treated as `{ value: s, label: s }`. */
+    options?: Array<FormFieldOption | string>;
+    /** Validation rules */
+    validations?: FormFieldValidation[];
+    /** Convenience flag — expanded into a `required` validation rule when serialised. */
+    required?: boolean;
+    /** Conditional visibility */
+    conditions?: FormFieldCondition[];
+    /** Is field disabled */
+    disabled?: boolean;
+    /** Is field readonly */
+    readonly?: boolean;
+    /** Column span (1-12) */
+    colSpan?: number;
+    /** Custom CSS class */
+    className?: string;
+    /** Custom styles */
+    style?: default_2.CSSProperties;
+    /** Additional field-specific props */
+    props?: Record<string, any>;
+    /** Nested fields (for section type) */
+    children?: FormFieldDefinition[];
+}
+
+/** Option for select/radio fields. */
+declare interface FormFieldOption {
+    value: string | number;
+    label: string;
+    disabled?: boolean;
+    /** Optional stable identifier for keyed rendering. */
+    id?: string;
+}
+
+/** Available field types. */
+declare type FormFieldType = 'text' | 'textarea' | 'number' | 'email' | 'password' | 'phone' | 'url' | 'date' | 'datetime' | 'time' | 'select' | 'multiselect' | 'checkbox' | 'toggle' | 'radio' | 'slider' | 'rating' | 'color' | 'file' | 'signature' | 'richtext' | 'markdown' | 'code' | 'heading' | 'paragraph' | 'divider' | 'spacer' | 'image' | 'section';
+
+/** Validation rule. */
+declare interface FormFieldValidation {
+    type: 'required' | 'minLength' | 'maxLength' | 'min' | 'max' | 'pattern' | 'email' | 'url' | 'custom';
+    value?: string | number | boolean;
+    message?: string;
+}
+
+/**
+ * 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>;
+
+/**
+ * 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.
+ */
+export declare function itemsFileKind<D>(o: NiceItemsFileKindOptions<D>): NiceStudioFileKind<Array<NiceStudioItem<D>>>;
+
+/** Any JSON file, edited as JSON. */
+export declare const jsonFallbackKind: NiceStudioFileKind<unknown>;
+
+/**
+ * A kind for one JSON file per document: `select` picks the model out of the file, `assign` puts
+ * it back, and the file's text is patched so only the changed values move.
+ */
+export declare function jsonFileKind<M>(o: NiceJsonFileKindOptions<M>): NiceStudioFileKind<M>;
+
+export declare interface JsonSchema {
+    $schema?: string;
+    $id?: string;
+    type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'null';
+    title?: string;
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    enum?: Array<string | number | boolean | null>;
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    pattern?: string;
+    format?: string;
+    default?: unknown;
+    additionalProperties?: boolean;
+}
+
+/**
+ * Whether a value has exactly the shape its schema describes — every object key known to the
+ * schema, every array item of the item schema, an `enum` value among its options — so a form can
+ * edit it without losing or reshaping anything. Seeds written by hand often do not (a per-language
+ * `description` object, a list of strings where the schema has objects); such a value is edited
+ * as JSON instead.
+ */
+export declare function jsonValueFitsSchema(value: unknown, schema: JsonSchema | undefined): boolean;
+
+/** Whether two JSON values are equal (objects compared by their keys, not their order). */
+export declare function jsonValuesEqual(a: unknown, b: unknown): boolean;
+
+/**
+ * Text from an editor given the line breaks and BOM of the file it replaces. A browser text box
+ * hands back LF only (and some drop a BOM), which would rewrite every line of a CRLF file.
+ */
+export declare function keepTextFormat(text: string, original: string | undefined): string;
+
+/** The manifest keys the sections' schemas cover — the rest shows on an "Other properties" tab. */
+export declare function manifestSectionKeys(sections: readonly NiceManifestSection[]): Set<string>;
+
+/** The prefix a module's files share (`orders` of `orders.manifest.json`). */
+export declare function modulePrefix(files: readonly NiceStudioFile[]): string;
+
+export declare const nativeDataSourcesKind: NiceStudioFileKind<NiceDataSourceDef[]>;
+
+export declare const nativeEntitiesKind: NiceStudioFileKind<Row_2[]>;
+
+/** The file kinds of the native format, in matching order. */
+export declare const nativeFileKinds: NiceStudioFileKind[];
+
+export declare const nativeHooksKind: NiceStudioFileKind<NiceHookBinding[]>;
+
+export declare const nativeI18nKind: NiceStudioFileKind<NiceStudioTranslations>;
+
+export declare const nativeManifestKind: NiceStudioFileKind<Row_2>;
+
+export declare const nativeRbacKind: NiceStudioFileKind<NiceRbacModel>;
+
+/** The studio's own format: manifest, entities, translations, views, workflows, data sources, access, hooks. */
+export declare const nativeStudioPreset: NiceStudioPreset;
+
+export declare const nativeViewsKind: NiceStudioFileKind<NiceStudioItem<NiceViewDefinition>[]>;
+
+export declare const nativeWorkflowsKind: NiceStudioFileKind<NiceStudioItem<NiceWorkflowDefinition>[]>;
+
+/** Options of {@link arrayFileKind}. */
+export declare interface NiceArrayFileKindOptions {
+    id: string;
+    label: string;
+    labelKey?: string;
+    icon?: string;
+    editor: NiceStudioEditorId;
+    match(path: string): boolean;
+    /** The property holding the array (`views`); the file may also be the bare array. */
+    property: string;
+    /** The property that identifies an item, for minimal diffs. */
+    itemKey?: string;
+}
+
+/** Options of {@link i18nFileKind}. */
+export declare interface NiceI18nFileKindOptions {
+    id?: string;
+    label?: string;
+    labelKey?: string;
+    /**
+     * The locale of a path and the path without it, or `null` when the path is not a translation.
+     * Default: `{prefix}.{locale}.i18n.json` (`en`, `pl`, `pt-BR`, `zh-CN`).
+     */
+    parse?(path: string): {
+        group: string;
+        locale: string;
+    } | null;
+    /** The path of a new language's file in a group. Default: `{group}.{locale}.i18n.json`. */
+    pathFor?(group: string, locale: string): string;
+}
+
+/** Options of {@link itemsFileKind}. */
+export declare interface NiceItemsFileKindOptions<D> extends NiceArrayFileKindOptions {
+    /** A stored entry as a list item: with `definition` when the editor understands it. */
+    toItem(raw: unknown, index: number): NiceStudioItem<D>;
+    /** A list item back as the stored entry (merge onto `item.source` to keep unknown fields). */
+    fromItem(item: NiceStudioItem<D>): unknown;
+}
+
+/** Options of {@link jsonFileKind}. */
+export declare interface NiceJsonFileKindOptions<M> {
+    id: string;
+    label: string;
+    labelKey?: string;
+    icon?: string;
+    match(path: string): boolean;
+    editor: NiceStudioEditorId;
+    /** The editor's model out of the file's parsed JSON. */
+    select(root: unknown, ctx: NiceStudioCodecContext): M;
+    /** The file's JSON with the model put back (return a new root; the text is patched in place). */
+    assign(root: unknown, model: M, ctx: NiceStudioCodecContext): unknown;
+    /** Identifies array items for the patch (see {@link NiceJsonPatchOptions.arrayKey}). */
+    arrayKey?: NiceJsonPatchOptions['arrayKey'];
+}
+
+/** Options of {@link patchJsonText}. */
+export declare interface NiceJsonPatchOptions {
+    /**
+     * The property that identifies the items of an array (by JSON pointer of the array), so a
+     * removed or inserted item does not shift every item after it. Without it the items are
+     * matched by `name`, `id`, `code`, `key`, `slug`, `state` or `Id` when every item has a unique
+     * one, otherwise by position.
+     */
+    arrayKey?: (pointer: string) => string | undefined;
+}
+
+/** What {@link patchJsonTextDetailed} did. */
+export declare interface NiceJsonPatchResult {
+    text: string;
+    /** `false`: the text could not be patched in place and was written anew in its format. */
+    exact: boolean;
+    /** Why it was written anew. */
+    reason?: string;
+}
+
+/**
+ * JSON text that keeps its look (NiceDevelopmentStudio).
+ *
+ * Seed files are written by hand and by many tools: a UTF-8 BOM, CRLF, two or four spaces or tabs,
+ * rows aligned in columns, `25.0` instead of `25`. Writing them back with `JSON.stringify` turns a
+ * one-field edit into a diff of the whole file. `patchJsonText` changes only the bytes of what
+ * changed: untouched values keep their exact text, a changed value replaces only its own token,
+ * added and removed members follow the indentation around them.
+ *
+ * No React and no dependencies — usable in Node (validators, CI) as well as in the studio.
+ */
+/** How a JSON file is written. */
+export declare interface NiceJsonTextFormat {
+    /** Starts with a UTF-8 byte order mark (kept as a leading U+FEFF). */
+    bom: boolean;
+    eol: '\n' | '\r\n';
+    /** One level of indentation (`'  '`, `'    '`, `'\t'`). */
+    indent: string;
+    /** Ends with a line break. */
+    finalNewline: boolean;
+    /** A space after the colon of a property. */
+    colonSpace: boolean;
+}
+
+/**
+ * One editable manifest section, described by a JSON Schema or field model.
+ *
+ * Generic over `TSchema` so a literal JSON-Schema object keeps its precise type
+ * (use {@link defineManifestSection} for inference) — no `as JsonSchema` casts on
+ * nested `properties`. Defaults to `JsonSchema`, so `NiceManifestSection` and
+ * `NiceManifestSection[]` keep working unchanged.
+ */
+export declare interface NiceManifestSection<TSchema extends JsonSchema = JsonSchema> {
+    id: string;
+    title: string;
+    icon?: default_2.ReactNode;
+    /** JSON Schema describing this section's fields (subset of the manifest). */
+    schema?: TSchema;
+    /** Or the repo's field-descriptor model. */
+    fields?: FormFieldDefinition[];
+    /** Per-field UI overrides forwarded to NiceSchemaForm. */
+    uiSchema?: Record<string, Partial<NiceFormItem>>;
+}
+
+/** A module given to {@link createMemoryStudioProvider}. */
+export declare interface NiceMemoryStudioModule {
+    id: string;
+    packageId?: string;
+    label?: string;
+    description?: string;
+    icon?: string;
+    version?: string;
+    readOnly?: boolean;
+    /** Its files: path → exact text. */
+    files: Record<string, string>;
+}
+
+/** Options of {@link createMemoryStudioProvider}. */
+export declare interface NiceMemoryStudioOptions {
+    workspaces: NiceMemoryStudioWorkspace[];
+    templates?: NiceStudioTemplate[];
+    /** Keep earlier versions of written files (default true). */
+    revisions?: boolean;
+}
+
+/** {@link NiceStudioProvider} plus a way to read everything back. */
+export declare interface NiceMemoryStudioProvider extends NiceStudioProvider {
+    /** The current state, in the shape the provider was created from. */
+    snapshot(): NiceMemoryStudioOptions;
+}
+
+/** A workspace given to {@link createMemoryStudioProvider}. */
+export declare interface NiceMemoryStudioWorkspace extends NiceStudioWorkspace {
+    /** Stored packages; without them packages are the modules' `packageId`s. */
+    packages?: Array<Omit<NiceStudioPackage, 'workspaceId'>>;
+    modules: NiceMemoryStudioModule[];
+}
+
+/** Options of {@link objectFileKind}. */
+export declare interface NiceObjectFileKindOptions {
+    id: string;
+    label: string;
+    labelKey?: string;
+    icon?: string;
+    editor: NiceStudioEditorId;
+    match(path: string): boolean;
+}
+
+/** What a file kind's decode and encode know about the module. */
+export declare interface NiceStudioCodecContext {
+    moduleId: string;
+    /** All files of the module (e.g. to read the manifest while decoding views). */
+    files: readonly NiceStudioFile[];
+    locales: readonly 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}`. */
+    key: string;
+    kind: NiceStudioFileKind<M>;
+    paths: string[];
+    /** For the explorer and the tab (the file name, or the group). */
+    label: string;
+    /** The decoded model; absent when decoding failed (`error`) — the document then opens raw. */
+    model?: M;
+    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';
+
+/** New and removed files of an encoded document. */
+export declare interface NiceStudioEncoded {
+    files: Array<{
+        path: string;
+        text: string;
+    }>;
+    deleted?: string[];
+}
+
+/** Entity editor settings of a preset. */
+export declare interface NiceStudioEntityOptions {
+    /** JSON Schema of an entity's own properties (name, table, flags). */
+    entityMetaSchema?: JsonSchema;
+    /** JSON Schema of one field. */
+    fieldSchema?: JsonSchema;
+    /** Property holding the fields. Default `fields`. */
+    fieldsKey?: string;
+    /** Property holding the name. Default `name`. */
+    nameKey?: string;
+}
+
+/** One file of a module: its path inside the module and its exact text (a BOM as a leading U+FEFF). */
+export declare interface NiceStudioFile {
+    /** Relative to the module folder, `/`-separated (e.g. `inv.invoices.entities.json`, `services/x.js`). */
+    path: string;
+    text: string;
+    /** Opaque version for conflict checks (hash, `lastModified:size`, ETag). */
+    version?: string;
+    /** This file cannot be written (e.g. shipped and read-only in production). */
+    readOnly?: boolean;
+}
+
+/** A change the studio asks the provider to write. */
+export declare type NiceStudioFileChange = {
+    type: 'write';
+    path: string;
+    text: string;
+    baseVersion?: string;
+} | {
+    type: 'delete';
+    path: string;
+    baseVersion?: string;
+};
+
+/**
+ * A kind of file and how the studio edits it. A document is one file, or several when `group`
+ * puts them together (the translations of one prefix in every locale).
+ */
+export declare interface NiceStudioFileKind<M = unknown> {
+    id: string;
+    label: string;
+    labelKey?: string;
+    /** NiceIcon name. */
+    icon?: string;
+    match(path: string): boolean;
+    /** The document a file belongs to (files with the same group open together). Default: the path. */
+    group?(path: string): string;
+    editor: NiceStudioEditorId;
+    /** 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). */
+    encode(model: M, files: readonly NiceStudioFile[], ctx: NiceStudioCodecContext): NiceStudioEncoded;
+}
+
+/** A generated module, before it is created. */
+export declare interface NiceStudioGeneratedModule {
+    id: string;
+    packageId?: string;
+    files: Array<{
+        path: string;
+        text: string;
+    }>;
+}
+
+/** A problem found in a module. */
+export declare interface NiceStudioIssue {
+    severity: 'error' | 'warning' | 'info';
+    /** Stable code of the rule (e.g. `manifest.required`). */
+    code?: string;
+    /** English text. */
+    message: string;
+    /** Translation key of `message`, with `{name}` placeholders filled from `params`. */
+    messageKey?: string;
+    params?: Record<string, string | number>;
+    moduleId?: string;
+    /** The file it is about. */
+    path?: string;
+    /** Where in that file: a JSON pointer (`/entities/0/fields/2`). */
+    pointer?: string;
+}
+
+/**
+ * An entry of a list document — a view, a workflow — that its editor may or may not understand.
+ * An entry in a shape the editor does not know keeps only `source` and is edited as raw JSON.
+ */
+export declare interface NiceStudioItem<D> {
+    /** Stable within the document (an id, a name, a position). */
+    key: string;
+    label: string;
+    /** The editor's model of the entry; absent for an entry edited raw. */
+    definition?: D;
+    /** The entry as it is stored. */
+    source: unknown;
+    /** Why the entry is edited raw (shown to the user). */
+    rawReason?: string;
+}
+
+/** What validators and generators get. */
+export declare interface NiceStudioModuleContext {
+    key: NiceStudioModuleKey;
+    files: readonly NiceStudioFile[];
+    documents: readonly NiceStudioDocument[];
+}
+
+/** Which module, in which workspace. */
+export declare interface NiceStudioModuleKey {
+    workspaceId: string;
+    id: string;
+}
+
+/** A module as listed in the explorer. */
+export declare interface NiceStudioModuleRef extends NiceStudioModuleKey {
+    packageId?: string;
+    label: string;
+    description?: string;
+    icon?: string;
+    version?: string;
+    /** Where it lives, for display (a folder, a URL). */
+    location?: string;
+    readOnly?: boolean;
+    /** Another workspace's module with the same id wins over this one (e.g. shipped over overlay). */
+    shadowedBy?: string;
+    /** Its file paths, when the listing knows them (lets the explorer show files without reading). */
+    files?: string[];
+    /** Extra text the explorer's search looks in. */
+    search?: string;
+}
+
+/** The answers of the new-module wizard. */
+export declare interface NiceStudioModuleSpec {
+    workspaceId: string;
+    packageId?: string;
+    /** Display name, e.g. "Bike rental". */
+    name: string;
+    description?: string;
+    icon?: string;
+    /** Entities to create, in the preset's entity shape. */
+    entities: Array<Record<string, unknown>>;
+    locales: string[];
+    /** Scaffold a list and a form view per entity. */
+    views?: boolean;
+    /** Scaffold viewer / editor / admin permissions. */
+    permissions?: boolean;
+}
+
+/** A group of modules in a workspace (a category, a product line). */
+export declare interface NiceStudioPackage {
+    id: string;
+    workspaceId: string;
+    label: string;
+    description?: string;
+    icon?: string;
+    /** Computed from the modules (e.g. their `category`) rather than stored: it cannot be edited. */
+    derived?: boolean;
+    readOnly?: boolean;
+}
+
+/** The model of the `permissions` editor: permission codes and the groups (roles) granting them. */
+export declare interface NiceStudioPermissions {
+    permissions: Array<{
+        code: string;
+        name?: string;
+        description?: string;
+    }>;
+    groups: Array<{
+        id: string;
+        label: string;
+        description?: string;
+        permissions: string[];
+    }>;
+}
+
+/**
+ * How one host's modules look: which files there are (kinds), what the manifest holds (sections),
+ * which languages are required, how a module is checked and generated.
+ */
+export declare interface NiceStudioPreset {
+    id: string;
+    /** Tried in order; a path no kind matches opens as raw JSON (`*.json`) or text. */
+    kinds: NiceStudioFileKind[];
+    /** The manifest's sections, each a form over part of the manifest. */
+    manifestSections?: NiceManifestSection[];
+    entities?: NiceStudioEntityOptions;
+    /** Languages offered for translations. */
+    locales?: string[];
+    /** Languages every module must have. */
+    requiredLocales?: string[];
+    /** The module's id from its files (e.g. the manifest's `packageName`). */
+    moduleId?(files: readonly NiceStudioFile[]): string | undefined;
+    validateModule?(ctx: NiceStudioModuleContext): NiceStudioIssue[];
+    generateModule?(spec: NiceStudioModuleSpec, ctx: {
+        existingIds: ReadonlySet<string>;
+    }): Promise<NiceStudioGeneratedModule>;
+    duplicateModule?(files: readonly NiceStudioFile[], target: {
+        id: string;
+        packageId?: string;
+        name?: string;
+    }): Promise<NiceStudioGeneratedModule>;
+    /** A new, empty file of a kind (the explorer's "New file"). */
+    newFile?(kindId: string, ctx: NiceStudioModuleContext): {
+        path: string;
+        text: string;
+    } | undefined;
+    /** Lifecycle triggers offered by a `hooks` document. */
+    hooks?: {
+        triggers: Array<{
+            id: string;
+            label: string;
+            description?: string;
+            group?: string;
+        }>;
+        handlers?: Array<{
+            id: string;
+            label: string;
+            description?: string;
+        }>;
+    };
+    /** Extra template properties (shown in the template editor). */
+    templateSchema?: JsonSchema;
+}
+
+/**
+ * How the studio reaches the host's modules. Only the four list/read/write methods are needed;
+ * each optional one turns on the matching feature (create, delete, packages, templates,
+ * validation, history) and its absence hides it.
+ */
+export declare interface NiceStudioProvider {
+    listWorkspaces(): Promise<NiceStudioWorkspace[]>;
+    listModules(workspaceId: string): Promise<NiceStudioModuleRef[]>;
+    readModule(key: NiceStudioModuleKey): Promise<NiceStudioFile[]>;
+    /** Writes only the files given (the studio drops changes that leave a file's text as it was). */
+    writeModule(key: NiceStudioModuleKey, changes: NiceStudioFileChange[]): Promise<NiceStudioWriteResult>;
+    /** Stored packages. Absent: the explorer groups modules by their `packageId`. */
+    listPackages?(workspaceId: string): Promise<NiceStudioPackage[]>;
+    createModule?(input: {
+        workspaceId: string;
+        packageId?: string;
+        id: string;
+        files: Array<{
+            path: string;
+            text: string;
+        }>;
+    }): Promise<NiceStudioModuleRef>;
+    deleteModule?(key: NiceStudioModuleKey): Promise<void>;
+    savePackage?(pkg: NiceStudioPackage): Promise<NiceStudioPackage>;
+    deletePackage?(ref: {
+        workspaceId: string;
+        id: string;
+    }): Promise<void>;
+    listTemplates?(): Promise<NiceStudioTemplate[]>;
+    /** `previousId`: the template's id before a rename. */
+    saveTemplate?(template: NiceStudioTemplate, options?: {
+        previousId?: string;
+    }): Promise<NiceStudioTemplate>;
+    deleteTemplate?(id: string): Promise<void>;
+    /** Server-side checks, on top of the preset's own. */
+    validate?(key: NiceStudioModuleKey, files: NiceStudioFile[]): Promise<NiceStudioIssue[]>;
+    listRevisions?(key: NiceStudioModuleKey, path?: string): Promise<NiceStudioRevision[]>;
+    readRevision?(key: NiceStudioModuleKey, revisionId: string, path?: string): Promise<string>;
+    rollback?(key: NiceStudioModuleKey, revisionId: string, path?: string): Promise<void>;
+}
+
+/** A saved earlier version of a module or one of its files. */
+export declare interface NiceStudioRevision {
+    id: string;
+    /** When it was saved: epoch ms. */
+    timestamp: number;
+    label?: string;
+    author?: string;
+    summary?: string;
+    /** The file it belongs to (absent: the whole module). */
+    path?: string;
+}
+
+/** The model of the `seeds` editor: rows per entity, plus demo rows. */
+export declare interface NiceStudioSeeds {
+    seeds: Record<string, Array<Record<string, unknown>>>;
+    demoSeeds?: Record<string, Array<Record<string, unknown>>>;
+}
+
+/** A template: a set of modules installed together (an industry bundle). */
+export declare interface NiceStudioTemplate {
+    id: string;
+    category?: string;
+    subCategory?: string;
+    parentId?: string;
+    icon?: string;
+    sortOrder?: number;
+    tags?: string[];
+    /** Name and description per language: `{ en: { name, description } }`. */
+    translations: Record<string, {
+        name: string;
+        description?: string;
+    }>;
+    modules: NiceStudioTemplateModule[];
+    /** Anything else the host's template carries, kept as it is. */
+    extra?: Record<string, unknown>;
+    readOnly?: boolean;
+}
+
+/** A module of a template. */
+export declare interface NiceStudioTemplateModule {
+    moduleId: string;
+    required?: boolean;
+    condition?: string;
+    description?: string;
+}
+
+/** Translations of one document: `{ en: { key: text }, pl: { … } }` (the shape of NiceI18nEditor). */
+export declare type NiceStudioTranslations = Record<string, Record<string, string>>;
+
+/** A place modules live in — a project: shipped seeds, a custom overlay, a tenant's modules. */
+export declare interface NiceStudioWorkspace {
+    id: string;
+    label: string;
+    description?: string;
+    icon?: string;
+    /** Modules here can be opened but not changed. */
+    readOnly?: boolean;
+}
+
+/** The outcome of writing a module. */
+export declare type NiceStudioWriteResult = {
+    ok: true;
+    versions?: Record<string, string>;
+    revision?: string;
+} | {
+    ok: false;
+    conflicts: Array<{
+        path: string;
+        currentVersion?: string;
+    }>;
+};
+
+/** A file whose whole content is the model (a manifest, an access model). */
+export declare function objectFileKind<T extends object>(o: NiceObjectFileKindOptions): NiceStudioFileKind<T>;
+
+/** Parses JSON text that may start with a BOM, and tells how it is written. */
+export declare function parseJsonText(text: string): {
+    value: unknown;
+    format: NiceJsonTextFormat;
+};
+
+/**
+ * `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
+ * JSON, duplicate keys) or the patch would not read back as `next`.
+ */
+export declare function patchJsonText(previous: string, next: unknown, options?: NiceJsonPatchOptions): string;
+
+/** {@link patchJsonText}, also telling whether the patch was exact. */
+export declare function patchJsonTextDetailed(previous: string, next: unknown, options?: NiceJsonPatchOptions): NiceJsonPatchResult;
+
+/** 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 kind a path opens with: the first that matches, else JSON or text. */
+export declare function resolveFileKind(kinds: readonly NiceStudioFileKind[], path: string): NiceStudioFileKind;
+
+declare type Row = Record<string, unknown>;
+
+declare type Row_2 = 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;
+
+/** 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;
+
+/** Any other file, edited as text. */
+export declare const textFallbackKind: NiceStudioFileKind<string>;
+
+/** The file with its translations replaced, in the same place they were. */
+export declare function writeTranslations(root: unknown, entries: Record<string, string>): unknown;
+
+export { }