@fieldia/designer 0.0.0-stage → 0.11.0

package/src/lib/designer.d.mts

@@ -0,0 +1,470 @@
+import { type AnswerRule, type ColumnCount, type ColumnsByWidth, type Field, type LabelPlace, type OptionsFrom, type PartLookKind, type Page, type PageLook, type SetWhen } from '@fieldia/core';
+import { type Condition } from './conditions.mjs';
+import { type HeaderCommands } from './header-commands.mjs';
+import { type ListCommands } from './list-commands.mjs';
+import { type OptionDetails } from './kind-commands.mjs';
+import { type ChoiceCommands } from './choice-commands.mjs';
+import { type InputCommands } from './input-commands.mjs';
+import { type StructureCommands } from './structure-commands.mjs';
+import { type PageCheck } from './page-checks.mjs';
+import { type LineColumn, type QuestionKind } from './kinds.mjs';
+import type { AppKind } from './app-kinds.mjs';
+import { type PageTemplate } from './templates.mjs';
+import type { DesignerAssistant } from './assistant.mjs';
+import type { BlockKind, Drop, NewPart } from './layout-ops.mjs';
+import type { BlockPatch, LookPatch, PartLookPatch, SectionLook } from './layout-settings.mjs';
+import type { EachChange } from './layout-several.mjs';
+import { type PageJsonResult } from './page-json.mjs';
+import { type AnswerRulePatch } from './rules-commands.mjs';
+import { type StepsCommands } from './steps-commands.mjs';
+import { type LookValues } from './look-presets.mjs';
+import { type Fold } from './group-fold.mjs';
+import { type DesignerLocale, type DesignerWords } from './designer-words.mjs';
+import { type FormPartPatch, type SavedFormRef } from './saved-forms.mjs';
+/**
+ * The editing model behind the designer: no DOM, so it is tested in Node.
+ *
+ * Every edit is a command that produces a new page. The page is validated
+ * before it replaces the old one, so an edit that would break the page is
+ * refused with the reason, never applied. Each edit is one undo step; a run of
+ * typing in one label merges into one. Drafts are saved apart from published
+ * versions, so editing never changes a form people are filling in.
+ *
+ * Given the backend's model, it offers the model's fields as they are: a
+ * field from the model keeps what it holds, and only changes editor.
+ */
+export { columnKind, kindFits, kindName, kindOfField, kindsFor, QUESTION_KINDS, SCREEN_KINDS, storedAs } from './kinds.mjs';
+export type { LineColumn, QuestionKind } from './kinds.mjs';
+export type { AppKind, AppKindContext, AppKindPreviewContext, AppKindSettings } from './app-kinds.mjs';
+export { isBlank, SCREEN_TEMPLATES, SURVEY_TEMPLATES, type PageTemplate } from './templates.mjs';
+export { askAssistant, type AssistantResult, type AssistantRun, type DesignerAssistant } from './assistant.mjs';
+export type { HeaderCommands, HeaderPartKind, HeaderPartPatch } from './header-commands.mjs';
+export type { ListActionPatch, ListCommands, ListOptionsPatch } from './list-commands.mjs';
+export { pageChanges, pageChecks, type CheckFix, type PageCheck } from './page-checks.mjs';
+export type { BlockKind, Drop, NewPart } from './layout-ops.mjs';
+export type { BlockPatch, LookPatch, PartLookPatch, SectionLook } from './layout-settings.mjs';
+export type { EachChange } from './layout-several.mjs';
+export type { Fold } from './group-fold.mjs';
+export type { JsonProblem, PageJsonResult } from './page-json.mjs';
+export type { AnswerRulePatch } from './rules-commands.mjs';
+export type { FormPartPatch, SavedFormRef } from './saved-forms.mjs';
+export type { StepPatch, StepsCommands } from './steps-commands.mjs';
+export type { Moment, StepPath, StepsPlace } from './steps-places.mjs';
+export { createBrowserLookStore, createMemoryLookStore } from './look-store.mjs';
+export type { LookValues } from './look-presets.mjs';
+export { DESIGNER_WORDS, designerLocale, type DesignerLocale, type DesignerWords } from './designer-words.mjs';
+/** What a page is for: a survey (wizard of steps), an app screen (sections), a record's sheet, or a list of records. */
+export type PageKind = 'survey' | 'screen' | 'sheet' | 'list';
+/**
+ * A page with nothing on it yet, titled: a survey with its first page, a
+ * screen with its first section, a sheet with its record's name, a list with
+ * its column. What it names (Page 1, Section 1) is in the designer's
+ * language (`locale`), English unless said; and a page begun in another
+ * language is written in it (`language`), so its form speaks it too.
+ */
+export declare function blankPage(kind: PageKind, title: string, options?: {
+    locale?: string;
+}): Page;
+export interface PublishedVersion {
+    version: number;
+    publishedAt: string;
+    page: Page;
+}
+/** Where pages are kept. An app implements this for its own storage. */
+export interface PageStore {
+    load(id: string): Promise<{
+        draft: Page | null;
+        versions: PublishedVersion[];
+    }>;
+    saveDraft(page: Page): Promise<void>;
+    publish(page: Page): Promise<number>;
+    /**
+     * The saved forms that can be placed in another page, by id and title:
+     * those with a published version. Optional: without it, the designer offers
+     * no saved form to place.
+     */
+    list?(): Promise<SavedFormRef[]>;
+}
+/** A look of one's own, kept by name to use again on other pages: the values a preset sets, any left to the skin. */
+export interface SavedLook {
+    id: string;
+    name: string;
+    look: LookValues;
+}
+/**
+ * Where looks of one's own are kept. An app implements this to keep them for
+ * a whole workspace on its server; without one, the designer keeps them in
+ * this browser (`createBrowserLookStore`). A store that rejects is said in
+ * the editor, in the words of its error.
+ */
+export interface LookStore {
+    /** Every look kept. The designer shows them by name. */
+    list(): Promise<SavedLook[]>;
+    /** Keep a look: a new one by a new id, or one kept already — renamed — in its place. */
+    save(look: SavedLook): Promise<void>;
+    remove(id: string): Promise<void>;
+}
+export declare function createMemoryPageStore(): PageStore & {
+    pages: Map<string, {
+        draft: Page | null;
+        versions: PublishedVersion[];
+    }>;
+};
+export interface DesignerState {
+    page: Page;
+    /** The element being edited. */
+    selected: string | null;
+    /** Every part picked, in the order picked: `selected` is the one picked last. */
+    picked: string[];
+    canUndo: boolean;
+    canRedo: boolean;
+    /** Why the last edit was refused. Empty when it was applied. */
+    issues: string[];
+    /** The draft differs from the last published version. */
+    unpublished: boolean;
+    versions: readonly PublishedVersion[];
+}
+export interface QuestionPatch {
+    label?: string;
+    required?: boolean;
+    help?: string;
+    placeholder?: string;
+}
+/** Where something is added: after an element, or in a container — at a place among its children, or at its end. */
+export interface Where {
+    after?: string;
+    parent?: string;
+    index?: number;
+}
+/** A field of the backend's model, by its name. */
+export interface ModelField {
+    name: string;
+    field: Field;
+}
+export interface Designer extends HeaderCommands, ListCommands, ChoiceCommands, InputCommands, StructureCommands, StepsCommands {
+    /** The designer's own words, in its language: English unless `locale` said another it speaks. */
+    readonly words: DesignerWords;
+    /**
+     * The designer's language, when one was given: its own words are in it, and
+     * the editors run its way — Arabic right to left, English left to right —
+     * whatever the direction of the page around them. Null when none was given:
+     * English, running the way the page around it does.
+     */
+    readonly locale: DesignerLocale | null;
+    getPage(): Page;
+    /** The model's fields not on the page yet, in the model's order. Empty without a model. */
+    modelFields(): ModelField[];
+    /** Show a field of the model, as the model has it: after `after`, or at the end of `parent` (or of the last container). Returns its node's id. */
+    addModelField(name: string, where?: Where): string | false;
+    /** The kinds a question can be shown as: for a field from the model, only those that fit what it holds. */
+    kindsFor(id: string): QuestionKind[];
+    /** Whether the question shows a field of the model, whose definition is the backend's. */
+    isFromModel(id: string): boolean;
+    getState(): DesignerState;
+    subscribe(listener: (state: DesignerState) => void): () => void;
+    select(id: string | null): void;
+    /** Add a question after `after`, or at the end of `parent` (or of the last container). Returns its id. */
+    addQuestion(kind: string, where?: Where): string | false;
+    updateQuestion(id: string, patch: QuestionPatch): boolean;
+    setOptions(id: string, labels: string[]): boolean;
+    changeKind(id: string, kind: string): boolean;
+    moveNode(id: string, delta: number): boolean;
+    /** Put a part in a step or section, at a place among its parts; with `pick`, it is picked too, as one change. */
+    placeNode(id: string, parent: string, index: number, options?: {
+        pick?: boolean;
+    }): boolean;
+    duplicateNode(id: string): string | false;
+    removeNode(id: string): boolean;
+    /** A step for a survey, a section for a screen or a sheet, or a section in a tab (`parent`). Returns its id. */
+    /**
+     * A section, or a survey's page: at the end, in a tab (`parent`), or — a
+     * page — right after a question (`after`), the questions under it on its
+     * page moving onto the new one, as Google Forms adds a section.
+     */
+    addContainer(label: string, where?: {
+        parent?: string;
+        after?: string;
+    }): string | false;
+    /** A screen of sections becomes a sheet, or a sheet without tabs a screen of sections. */
+    setLayoutKind(kind: 'sections' | 'sheet'): boolean;
+    /** A sheet's title: a text field taken out of its section, or `null` to put it back first in the first section. */
+    setTitleField(nodeId: string | null): boolean;
+    /** Tabs on a sheet, after `after` or at the end: one tab, with a section. Returns the tabs' id. */
+    addTabs(where?: {
+        after?: string;
+    }): string | false;
+    /** One more tab, with a section. Returns its id. */
+    addTab(tabsId: string, label: string): string | false;
+    renameContainer(id: string, label: string): boolean;
+    /**
+     * Show a page or a question only when earlier answers say so: all of the
+     * rules, or any. One field and one value is the short form; `null`, or no
+     * rules, always shows it.
+     */
+    setCondition(id: string, condition: Condition | {
+        field: string;
+        equals: string | number | boolean;
+    } | null): boolean;
+    /**
+     * A field required, or read-only, only when a rule holds; `null` for no
+     * rule. A field always required becomes required only then; a field the
+     * model always requires cannot be.
+     */
+    setRule(id: string, which: 'required' | 'readonly', condition: Condition | {
+        field: string;
+        equals: string | number | boolean;
+    } | null): boolean;
+    /** A group's columns: one count, or a count for a desktop (`wide`), a tablet (`medium`) and a phone (`narrow`). */
+    setColumns(sectionId: string, columns: ColumnCount | ColumnsByWidth): boolean;
+    /** How many columns a field, a group, tabs, words, a button, a spacer or an image spans. */
+    setColspan(nodeId: string, span: number): boolean;
+    /** Put a section's fields in this order with these widths, as one edit (a canvas drag). */
+    arrangeSection(sectionId: string, items: {
+        id: string;
+        colspan: number;
+    }[]): boolean;
+    setPageInfo(info: {
+        title?: string;
+        description?: string;
+    }): boolean;
+    /** The records a link, links or a table of lines point to, by their model's name. */
+    setRelation(id: string, model: string): boolean;
+    /** An amount's currency, such as USD. */
+    setCurrency(id: string, code: string): boolean;
+    /** Where a rating, a scale or a progress runs from and to. */
+    setRange(id: string, range: {
+        min: number;
+        max: number;
+    }): boolean;
+    /** An "Other" choice after the options, with a box for an answer of one's own: for multiple choice and checkboxes. */
+    setOther(id: string, on: boolean): boolean;
+    /** How the field's widget shows it, such as the words at a scale's ends; `null` or nothing takes a setting away. */
+    setWidgetOptions(id: string, patch: Record<string, string | number | boolean | null>): boolean;
+    /**
+     * Which kinds of file a file upload takes (media types, such as image/*), and
+     * the largest, in bytes; whether it, or an image, takes several files, and as
+     * few and as many as it takes. `null` lifts a limit; one file again lifts both counts.
+     */
+    setFileRules(id: string, rules: {
+        accept?: string[];
+        maxSize?: number | null;
+        multiple?: boolean;
+        minFiles?: number | null;
+        maxFiles?: number | null;
+    }): boolean;
+    /**
+     * Drop a part where it goes, as one edit: a part on the page, by its id, or
+     * a new one from the toolbox. Returns its id, and picks it.
+     */
+    place(part: string | NewPart, drop: Drop): string | false;
+    /** What a drop would do, in the words the drag chip says: "beside “First name”". `moving` is the part dragged, when it is on the page. */
+    describeDrop(drop: Drop, moving?: string): string;
+    /** Why a drop cannot be made, such as "A row holds four"; null when it can. */
+    dropRefusal(drop: Drop, moving?: string): string | null;
+    /** Parts that sit together, in a new group, side by side, or a tab each. Returns what holds them, and picks it. */
+    wrap(ids: string[], kind: 'group' | 'side' | 'tabs'): string | false;
+    /** A group's parts, or every tab's, where it was; they are picked. */
+    ungroup(id: string): boolean;
+    /** A copy of each part right after it; the copies are picked. */
+    duplicate(ids: string[]): string[] | false;
+    /** Take several parts off the page, as one edit. */
+    remove(ids: string[]): boolean;
+    /** Pick a part; with `add`, pick it as well as those picked, or let it go if it was. */
+    pick(id: string, options?: {
+        add?: boolean;
+    }): void;
+    /** How a group looks, and where its fields' labels sit and how wide; `null` takes a setting back. */
+    setSectionLook(id: string, look: SectionLook): boolean;
+    /** Where one field's label sits; `null` for where its group or the page puts labels. */
+    setFieldLabels(id: string, place: LabelPlace | null): boolean;
+    /** The page's look: colour, font, spacing, corners, labels, scheme; `null` takes a setting back. */
+    setLook(patch: LookPatch): boolean;
+    /**
+     * One kind of part's look, over the page's: text boxes, choices, groups,
+     * buttons or tables, with the settings `PART_LOOKS` gives each. `null` takes
+     * a setting back, or the whole kind. Each change is one undo step; a run of
+     * colours tried, one after another, is one, as typing is.
+     */
+    setPartLook(kind: PartLookKind, patch: PartLookPatch | null): boolean;
+    /** A block after `after`, or in `parent` at `index`, or at the end of the last container. Returns its id, and picks it. */
+    addBlock(kind: BlockKind, where?: Where): string | false;
+    /** A table of lines' columns, in order. */
+    setLineColumns(id: string, columns: LineColumn[]): boolean;
+    /** An option's picture and points for a quiz; `null` or empty takes either away. */
+    setOptionDetails(id: string, index: number, details: OptionDetails): boolean;
+    /** A matrix's rows or columns, by their words, in order. */
+    setMatrixItems(id: string, which: 'rows' | 'columns', labels: string[]): boolean;
+    /** Which parts an address asks for: street, city, postcode, country. */
+    setAddressParts(id: string, parts: string[]): boolean;
+    /** Whether pictures to choose from take one answer or several. */
+    setSeveral(id: string, on: boolean): boolean;
+    undo(): void;
+    redo(): void;
+    /** Publish the draft as the next version. Returns its number. */
+    publish(): Promise<number>;
+    /** What people would trip over on the page as it is, what would stop them first. */
+    checks(): PageCheck[];
+    /** Do a check's fix: delete an empty page, drop a rule that can never hold, or pick what it is about. */
+    fixCheck(check: PageCheck): boolean;
+    /** Make a published version the draft again. Undoable. */
+    revertTo(version: number): boolean;
+    /** Resolves once every draft save started so far has finished. */
+    settled(): Promise<void>;
+    /** A language to translate the page into, by tag (`ar`, `pt-BR`). Not the page's own language. */
+    addLanguage(tag: string): boolean;
+    /** A language taken out, with every word translated into it. */
+    removeLanguage(tag: string): boolean;
+    /** One word's translation; empty or `null` takes it away. Typing in one word is one undo step. */
+    setTranslation(tag: string, source: string, text: string | null): boolean;
+    /** Many translations at once, by language then by word, as one edit; languages the page has not got are added. Returns how many were filled. */
+    fillTranslations(words: Record<string, Record<string, string>>): number | false;
+    /** Let go of words' translations in every language, as one edit: for words no longer on the page. */
+    forgetWords(sources: string[]): boolean;
+    /** The language the page's own words are written in, by tag, as one edit: not one it keeps a translation into. */
+    setPageLanguage(tag: string): boolean;
+    /** Several parts' width, where their labels sit, or whether they are required, as one edit; none changes when one cannot. */
+    setEach(ids: string[], change: EachChange): boolean;
+    /** The page as JSON: two spaces deep, its keys in the order the page keeps them. */
+    pageJson(): string;
+    /** A whole page written as JSON, as one edit; refused with each problem's line and column, the page kept as it was. */
+    setPageJson(text: string): PageJsonResult;
+    /** The app's lists of choices a choice may take its options from, as the app named them. */
+    lists(): AppList[];
+    /** A choice's options taken from one of the app's lists, changing with other fields; `null` for options written here. */
+    setOptionsFrom(id: string, from: OptionsFrom | null): boolean;
+    /** A block's words and look, a button's label, a picture's address and description; a run of typing in one is one undo step. */
+    updateBlock(id: string, patch: BlockPatch): boolean;
+    /**
+     * Several parts' widths as one edit: two trading width across the gutter
+     * between them. With `twelfths`, widths are twelfths of their row, and a
+     * group of one to four columns is divided in twelfths first, in the same edit.
+     */
+    setWidths(widths: {
+        id: string;
+        span: number;
+    }[], options?: {
+        twelfths?: boolean;
+    }): boolean;
+    /** A field's value worked out from others, such as `price * qty`; `null` makes it a field to fill in again. Typing a formula is one undo step. */
+    setCompute(id: string, expression: string | null): boolean;
+    /** Values set when a condition starts to hold, in order; `null` or none takes them away. Typing in one box is one undo step. */
+    setSetWhen(id: string, items: SetWhen[] | null): boolean;
+    /** A rule the answer must keep, after the others: one that fits what the field holds. */
+    addAnswerRule(id: string, rule: AnswerRule): boolean;
+    /** One answer rule changed: a value sets what it asks, `null` takes that away. Typing in one box is one undo step. */
+    updateAnswerRule(id: string, index: number, patch: AnswerRulePatch): boolean;
+    removeAnswerRule(id: string, index: number): boolean;
+    /** The app's own kinds, as kinds, in the order the app gave them. */
+    appKinds(): QuestionKind[];
+    /** The templates this page can start from: Fieldia's for a survey or a screen, then the app's made the same way. */
+    templates(): PageTemplate[];
+    /** A whole page in place of this one, as one edit — a template, or what an assistant made — keeping this page's id and where its answers go. Refused, saying why, for one that is not a page, or is for the other editor. */
+    replacePage(page: Page): boolean;
+    /** The app's own assistant, when the app gave the designer one. */
+    assistant(): DesignerAssistant | null;
+    /** Pick these parts at once, in this order, the last leading; any not on the page, or named twice, is left out. */
+    pickMany(ids: string[]): void;
+    /**
+     * Move parts in reading order into a group, a tab, tabs or a survey's page,
+     * before the part now at `index` there (the parts moved counted where they
+     * are), as one edit; they stay picked. Returns them, in reading order.
+     */
+    moveParts(ids: string[], parentId: string, index: number): string[] | false;
+    /** Why parts cannot be moved into `parentId`, such as “A tab holds parts, not other tabs”; null when they can. */
+    moveRefusal(ids: string[], parentId: string): string | null;
+    /** Where a move would put them, in the words the drag chip says: “into “Home address”, before “City””. */
+    describeMove(ids: string[], parentId: string, index: number): string;
+    /** The parts, with their fields' definitions, as JSON for the clipboard; false when none is a part of the page. */
+    copyParts(ids: string[]): string | false;
+    /**
+     * Paste the parts a copy holds, as one edit: after the part picked, into the
+     * group, tab or page picked, or at the end. Ids are new; a field whose name
+     * is taken takes a free one, and what its rules read follows it. Returns
+     * the parts pasted, picked, and how many rules were left off for reading a
+     * field the page has not got.
+     */
+    pasteParts(text: string): {
+        ids: string[];
+        dropped: number;
+    } | false;
+    /** A look to start from, by its id: its accent, font, spacing, corners and colours, as one undo step; where labels sit is kept. */
+    setLookPreset(id: string): boolean;
+    /**
+     * A whole look on the page as one undo step, as a preset is put on it — a
+     * look of one's own: its accent, font, spacing, corners and colours, each it
+     * leaves unset given back to the skin. Where labels sit is kept.
+     */
+    useLook(look: PageLook): boolean;
+    /** Where looks of one's own are kept: the app's store, or this browser's, one for every designer on the page. */
+    looks(): LookStore;
+    /** Whether a group folds by its title, and how it starts; refused for a group with no title. */
+    setFold(id: string, fold: Fold): boolean;
+    /** Whether a saved form can be placed in the page: the app's store lists its saved forms (`PageStore.list`). */
+    canPlaceForms(): boolean;
+    /** The saved forms that can be placed in this page: the store's, this page itself left out. None without a store that lists them. */
+    savedForms(): Promise<SavedFormRef[]>;
+    /**
+     * A saved form as this page would place it: its published versions, newest
+     * last, and the page of the version kept to, or of the latest. Undefined
+     * while it loads — its listeners are told once it has — and null when the
+     * store has none.
+     */
+    savedForm(id: string, version?: number): {
+        versions: readonly PublishedVersion[];
+        page: Page | null;
+    } | null | undefined;
+    /** Load a saved form afresh, and every saved form it places: once loaded, one that would hold this page is refused. */
+    loadSavedForm(id: string): Promise<void>;
+    /**
+     * Place a saved form after `after`, or in `parent` at `index`, its answers
+     * under a name of its own (after its title). Returns its id, and picks it.
+     * Refused when it would hold this page, as far as what has loaded tells.
+     */
+    addForm(pageId: string, where?: Where): string | false;
+    /** A saved form placed here: which one, the version it keeps to, where its answers go, its title. */
+    setForm(id: string, patch: FormPartPatch): boolean;
+    /** Whether a saved form can be opened where it is made: the app gave the designer a way to (`openForm`). */
+    canOpenForm(): boolean;
+    /** Open a saved form where it is made, the app's way. */
+    openForm(pageId: string): void;
+}
+/** One of the app's lists of choices, by the name its data source answers to, and the words a person picks it by. */
+export interface AppList {
+    name: string;
+    label: string;
+}
+export declare function createDesigner(options: {
+    page: Page;
+    store?: PageStore;
+    versions?: PublishedVersion[];
+    model?: Record<string, Field>;
+    lists?: AppList[];
+    /** The app's own kinds of field, offered after Fieldia's. One whose id or widget is taken is refused. */
+    kinds?: readonly AppKind[];
+    /** The app's own templates, offered after Fieldia's to a blank page made the same way. */
+    templates?: readonly PageTemplate[];
+    /** The app's own assistant, which makes a page from what a person describes. Without one, nothing about it shows. */
+    assistant?: DesignerAssistant;
+    /** Where looks of one's own are kept, for a whole workspace. Without one, in this browser. */
+    looks?: LookStore;
+    /**
+     * The designer's own language, as a language tag (`ar`, `en`): its buttons,
+     * menus, messages and checks in it — English and Arabic; English for any
+     * other — and its editors running that language's way. The page's own
+     * words are never translated: they are the page's. English, taking the
+     * direction of the page around it, unless said.
+     */
+    locale?: DesignerLocale | (string & {});
+    /** Open a saved form placed in the page where it is made, by its id: “Open it” on the canvas. Without one, it is not offered. */
+    openForm?: (id: string) => void;
+}): Designer;
+export declare namespace createDesigner {
+    var open: (id: string, store: PageStore, options?: {
+        model?: Record<string, Field>;
+        lists?: AppList[];
+        kinds?: readonly AppKind[];
+        looks?: LookStore;
+        openForm?: (id: string) => void;
+        locale?: DesignerLocale | (string & {});
+    }) => Promise<Designer>;
+}