@peter.prib/renderengine 0.2.10 → 0.4.0

package/src/workspace/parts/EditorPart.js

@@ -304,7 +304,7 @@ export class EditorPart extends Part {
             ...EditorPart.menuGroup('New', some(...this.newItems(), models['New model'], ...(this.modelsHost?.baseItems?.() ?? []))),
             { separator: true },
             ...some(open, models['Open… in a new tab'], ...saving, models['Duplicate model'], models['Close model']),
-            ...EditorPart.menuGroup('This browser', this.modelsHost?.keepItems?.(this) ?? []),
+            ...EditorPart.menuGroup(this.modelsHost?.keptWhere ?? 'This browser', this.modelsHost?.keepItems?.(this) ?? []),
             { separator: true },
             ...EditorPart.menuGroup('Import', this.importItems(), { prefix: true }),
             ...EditorPart.menuGroup('Export', this.exportItems(), { prefix: true }),

package/src/workspace/parts/ModelFile.js

@@ -133,7 +133,9 @@ export class ModelFile {
     /** Open what `choose()` read: the part edits its model, from that file. Returns the model. */
     adopt({ model, name, format, handle = null }) {
         this.part.replaceModel(model);
-        Object.assign(this, { name, format, handle });
+        // Read from another tool's export (a format that only reads): a new model, saved in the part's own format.
+        if (format && format.exports === false) Object.assign(this, { name: null, format: null, handle: null });
+        else Object.assign(this, { name, format, handle });
         this.showState();
         return model;
     }

package/src/workspace/parts/ModelHosted.js

@@ -0,0 +1,176 @@
+import { ModelFile } from './ModelFile.js';
+import { EditorPart } from './EditorPart.js';
+import { modelFileMenuItems } from '../../charting/ModelFileFormat.js';
+import { pickFile } from '../../charting/toolbar/pickFile.js';
+
+/**
+ * ModelHosted — what a part that edits one model as a whole (an
+ * EditableModel: DataModelPart, RequirementsPart) needs to be one of a
+ * ModelsPart's models, as an EditorPart is: its file (ModelFile: Open…, Save,
+ * Save As…, • while changed, asking before the page is left), kept by the
+ * host (`keepId`, `keepEntry`), its File menu (New, Duplicate, Close model,
+ * where models are kept, Import of what other tools wrote), Undo and Redo,
+ * running a model-wide edit (a merge, a proposal taken) as one undo step,
+ * and reading a file into the model as one (readInto).
+ *
+ * A mixin, for parts on different bases (a ChartPart, a plain Part):
+ * `class DataModelPart extends ModelHosted(ChartPart)`. The part gives
+ * `fileFormats()` (its own first: what it saves as), and `afterModelEdit()`
+ * to show an edit (redraw).
+ */
+export const ModelHosted = (Base) => class extends Base {
+    constructor(spec = {}) {
+        super(spec);
+        /** The file it is open from and saved to. */
+        this.file = new ModelFile(this);
+        /** Its id among the models kept by its host, or null. */
+        this.keepId = spec.keepId ?? null;
+    }
+
+    /** Its file formats: none here. @abstract */
+    fileFormats() {
+        return [];
+    }
+
+    /** What a new file is saved as: its first format. */
+    saveFormat() {
+        return this.fileFormats()[0];
+    }
+
+    /** The ModelsPart it is a tab of, or null. */
+    get modelsHost() {
+        return this.ctx?.models ?? null;
+    }
+
+    /** The page it is in. */
+    get document() {
+        return this.container?.ownerDocument ?? globalThis.document;
+    }
+
+    /** What its tab and the page title show: the file's name (or the model's), and • while changed. */
+    get fileLabel() {
+        return this.file.label;
+    }
+
+    /** The model as kept by its host (ModelFile#keepEntry). */
+    keepEntry() {
+        return this.file.keepEntry();
+    }
+
+    /** A model opened from a file: in a host's new tab, else in place of this one (as EditorPart does). */
+    onImported(model) {
+        return EditorPart.prototype.onImported.call(this, model);
+    }
+
+    /** The file or its saved state changed: a ModelsPart's tab follows it. */
+    onFileState() {
+        this.modelsHost?.fileStateChanged?.(this);
+    }
+
+    /** Edit `model`: as saved, and every change of it shows (• and the title) and is kept. @protected */
+    _adoptModel(model) {
+        this._unsubscribeEdits?.();
+        this.model = model;
+        model.markSaved();
+        this._unsubscribeEdits = model.onEdit(() => {
+            this.file.showState();
+            this.modelsHost?.modelEdited?.(this);
+        });
+    }
+
+    mount(host, ctx) {
+        const first = !this.mounted;
+        super.mount(host, ctx);
+        if (first) {
+            this.file.listen();
+            this.file.showState();
+        }
+    }
+
+    /** Show an edit of the model (a redraw): a subclass's. */
+    afterModelEdit() {}
+
+    /** Run a model-wide edit (a merge) as one undo step, then show it. */
+    runModelEdit(command) {
+        if (!command) return null;
+        this.model.history.execute(command);
+        this.afterModelEdit();
+        return command;
+    }
+
+    /**
+     * File ▸: Open…, Save, Save As…, Import of what other tools wrote (its
+     * formats that only read), then with a ModelsPart New model, Duplicate,
+     * Close model, and where models are kept ▸.
+     */
+    fileItems() {
+        const host = this.modelsHost;
+        return EditorPart.tidyMenu([
+            ...this.file.menuItems(),
+            ...EditorPart.menuGroup('Import', this.importItems(), { prefix: true }),
+            ...(host ? [
+                { separator: true },
+                ...EditorPart.menuGroup('New', [{ label: 'New model', action: () => host.newModel() }, ...(host.baseItems?.() ?? [])]),
+                { label: 'Duplicate model', action: () => host.duplicate(this) },
+                { label: 'Close model', action: () => host.closeModel(this.id) },
+                ...EditorPart.menuGroup(host.keptWhere ?? 'This browser', host.keepItems?.(this) ?? []),
+            ] : []),
+        ]);
+    }
+
+    /** Import ▸: each format that only reads (another tool's export), opened as a new model. */
+    importItems() {
+        return modelFileMenuItems(this.fileFormats().filter(f => f.exports === false), {
+            model: () => this.model, only: 'import', onImport: (model) => this.onImported(model), document: () => this.document,
+        });
+    }
+
+    /**
+     * Ask for a file, make a command from its bytes, and run it as one undo
+     * step; a file that cannot be read, or brings nothing, is reported.
+     * @param {Object} how
+     * @param {string} how.accept - The file chooser's filter
+     * @param {string} how.what - What is read, for the report ('the landscape')
+     * @param {(bytes: Uint8Array, name: string) => Command|null} how.command
+     * @param {(name: string) => string} how.nothing - The report when the command is null
+     * @param {() => void} [how.then] - What to show once it is run (before the redraw)
+     * @param {(accept: string) => Promise<File|null>} [how.chooseFile]
+     * @param {(message: string) => void} [how.report]
+     * @returns {Promise<Command|null>}
+     */
+    async readInto({ accept, what, command: make, nothing, then = () => {}, chooseFile = null, report = null }) {
+        const doc = this.container?.ownerDocument ?? globalThis.document;
+        const tell = report ?? ((message) => (doc.defaultView ?? globalThis).alert(message));
+        const file = await (chooseFile ?? ((filter) => pickFile(filter, doc)))(accept);
+        if (!file) return null;
+        let command;
+        try {
+            command = make(new Uint8Array(await file.arrayBuffer()), file.name);
+        } catch (err) {
+            tell(`Could not read ${what}: ${err.message}`);
+            return null;
+        }
+        if (!command) {
+            tell(nothing(file.name));
+            return null;
+        }
+        then();
+        this.runModelEdit(command);
+        return command;
+    }
+
+    /** Undo and Redo, each named by what it undoes (a merge is one step). */
+    undoItems() {
+        const history = this.model.history;
+        return [
+            { label: history.canUndo ? `Undo ${history.undoLabel}` : 'Undo', disabled: !history.canUndo || undefined, action: () => { history.undo(); this.afterModelEdit(); } },
+            { label: history.canRedo ? `Redo ${history.redoLabel}` : 'Redo', disabled: !history.canRedo || undefined, action: () => { history.redo(); this.afterModelEdit(); } },
+        ];
+    }
+
+    dispose() {
+        this._unsubscribeEdits?.();
+        this.file.restoreTitle();
+        super.dispose();
+    }
+};

package/src/workspace/parts/ModelsPart.js

@@ -8,6 +8,7 @@ import { downloadBlob } from '../../exportImage.js';
 import { IndexedDbStore } from '../storage/KeyValueStore.js';
 import { ModelLibrary } from '../storage/ModelLibrary.js';
 import { BackupFolder } from '../storage/BackupFolder.js';
+import { Benchmark } from '../../charting/model/Benchmark.js';
 
 /**
  * ModelsPart — several models open at once (as Archi's model tree holds
@@ -41,6 +42,23 @@ import { BackupFolder } from '../storage/BackupFolder.js';
  * closed open again next time. File ▸ This browser opens a kept model, stops
  * keeping one, backs them all up (BackupFolder: a folder chosen once, such as
  * one OneDrive or Google Drive syncs, else downloads) and chooses that folder.
+ *
+ * Where models are kept is the host's to say: a `modelLibrary` among the
+ * workspace's services (`workspace.services`, reaching this part as
+ * `ctx.modelLibrary`) is used in place of the browser's — anything with
+ * ModelLibrary's methods (keep, load, list, openOnes, setOpen, remove) and a
+ * `label` for the menu ('The engine'). An entry is the model in its editor's
+ * file format, so a host stores it as it likes: a database row, a file, a
+ * graph built from it. The backup folder stays in the browser.
+ *
+ * Proposals: a model offered as a change to the one in front — by an agent,
+ * a colleague, an import — with why (`propose`). Tools ▸ Proposals lists them;
+ * each is reviewed as a merge (ModelMergeDialog, its rationale shown), so what
+ * is taken is chosen and is one undo step. Taking or dismissing one removes it.
+ *
+ * A host adds tools of its own for the model in front — an agent to run on
+ * it, say — as `modelTools(part, models)` among the workspace's services: its
+ * items end the Tools menu.
  */
 export class ModelsPart extends Part {
     static type = 'models';
@@ -58,6 +76,9 @@ export class ModelsPart extends Part {
         this.backups = null;
         /** Edits waiting to be kept, by part id. @private */
         this._pending = new Map();
+        /** Changes offered, not yet taken or dismissed (propose). */
+        this.proposals = [];
+        this._proposalSeq = 0;
     }
 
     /** What a copy's name ends with (copyName). */
@@ -104,8 +125,8 @@ export class ModelsPart extends Part {
      * @param {Array<EditorPart>} starting - The models the spec opened
      */
     async startKeeping(starting = []) {
-        const store = await this.openStore();
-        this.library = new ModelLibrary(store);
+        const store = await this.openStore();   // the backup folder's, whoever keeps the models
+        this.library = this.ctx?.modelLibrary ?? new ModelLibrary(store);
         const win = this.container?.ownerDocument?.defaultView ?? globalThis;
         this.backups = new BackupFolder({
             store, window: win,
@@ -195,7 +216,7 @@ export class ModelsPart extends Part {
     async askOpenKept() {
         const open = new Set(this.models().map(p => p.keepId));
         const entries = this.ownKept(await this.library.list()).filter(e => !open.has(e.id));
-        if (!entries.length) { this.tell('Every model kept in this browser is open.'); return null; }
+        if (!entries.length) { this.tell(`Every model kept (${this.keptWhere}) is open.`); return null; }
         return new FormDialog({
             title: 'Open a kept model',
             fields: [{
@@ -234,7 +255,7 @@ export class ModelsPart extends Part {
     async backUpAndTell() {
         for (const part of this.models()) await this.keep(part);
         const files = await this.backupFiles();
-        if (!files.length) { this.tell('Nothing is kept in this browser yet.'); return null; }
+        if (!files.length) { this.tell(`Nothing is kept (${this.keptWhere}) yet.`); return null; }
         const { location, names } = await this.backups.backUp(files);
         this.tell(`Backed up ${names.length} model${names.length === 1 ? '' : 's'} to the ${location}:\n\n${names.join('\n')}`);
         return { location, names };
@@ -247,6 +268,83 @@ export class ModelsPart extends Part {
         return dir;
     }
 
+    /** Where models are kept, as the File menu names it: the library's label. */
+    get keptWhere() {
+        return this.library?.label ?? 'This browser';
+    }
+
+    // ===== Proposals =====
+
+    /**
+     * Offer a change: the model proposed — `spec`, a model as this workbench's
+     * editor takes it (as a base is given), or `entry`, a model in one of the
+     * editor's file formats (`{format, data}`, as a kept one is) — with a
+     * `title` and why (`rationale`), from `source` (who or what proposed it).
+     * `onSettle(outcome, {bench})` hears whether it was 'taken' or
+     * 'dismissed' and, taken, how what was taken moved the bench. Returns the proposal.
+     * @param {{title: string, rationale?: string, source?: string, spec?: Object, entry?: {format: string, data: *}, onSettle?: Function}} proposal
+     */
+    propose({ title, rationale = '', source = '', spec = null, entry = null, onSettle = null }) {
+        if (!spec && !entry) throw new TypeError('A proposal needs a model spec');
+        const id = `${this.id}-proposal-${++this._proposalSeq}`;
+        const part = this.registry.create({ ...ModelsPart.copySpec(spec ?? {}), id, type: this.editorType });
+        if (entry) {
+            const format = part.fileFormats().find(f => f.label === entry.format);
+            if (!format) { part.dispose?.(); throw new Error(`No ${entry.format} format here to read the proposal in`); }
+            part.replaceModel(format.import(entry.data));
+        }
+        const proposal = { id, title: title || part.model?.name || 'Proposal', rationale, source, part, onSettle };
+        this.proposals.push(proposal);
+        return proposal;
+    }
+
+    /**
+     * How the proposal would move the model's measures (Benchmark), were it
+     * taken whole: `[{label, before, after, change, …}]`.
+     */
+    proposalBench(part, proposal) {
+        return Benchmark.compare(Benchmark.of(part.model), Benchmark.of(proposal.part.model));
+    }
+
+    /** Forget a proposal: not wanted (`outcome` 'dismissed'), or taken. Its proposer hears which. */
+    dismissProposal(proposal, outcome = 'dismissed', note = {}) {
+        if (!this.proposals.includes(proposal)) return;
+        this.proposals = this.proposals.filter(p => p !== proposal);
+        proposal.onSettle?.(outcome, note);
+        proposal.part?.dispose?.();
+    }
+
+    /**
+     * Review a proposal against `part`'s model: its differences, chosen as a
+     * merge (ModelMergeDialog), its rationale above them. Merging takes it.
+     */
+    reviewProposal(part, proposal) {
+        const bench = this.proposalBench(part, proposal);
+        return new ModelMergeDialog({
+            ...this._comparing(part, proposal.part),
+            theirsName: proposal.title,
+            note: [proposal.source && `Proposed by ${proposal.source}.`, proposal.rationale, bench.length && `Taken whole: ${Benchmark.text(bench)}.`].filter(Boolean).join(' '),
+            onMerge: (command) => {
+                // What was taken (the parts chosen), measured: the model before the merge and after.
+                const before = Benchmark.of(part.model);
+                part.runModelEdit(command);
+                this.dismissProposal(proposal, 'taken', { bench: Benchmark.text(Benchmark.compare(before, Benchmark.of(part.model))) });
+            },
+        }).open();
+    }
+
+    /** Tools ▸ Proposals: each, to review or dismiss. */
+    proposalItems(part) {
+        if (!this.proposals.length) return [{ label: 'None waiting', disabled: true }];
+        return this.proposals.map(p => ({
+            label: p.source ? `${p.title} — ${p.source}` : p.title,
+            items: [
+                { label: 'Review and merge…', action: () => this.reviewProposal(part, p) },
+                { label: 'Dismiss', action: () => this.dismissProposal(p) },
+            ],
+        }));
+    }
+
     /** Tell the user (the page's alert). @protected */
     tell(message) {
         const win = this.container?.ownerDocument?.defaultView ?? globalThis;
@@ -301,6 +399,19 @@ export class ModelsPart extends Part {
             this.registry.create({ ...ModelsPart.copySpec(spec), id: `${this.id}-base-${i + 1}`, type: this.editorType })));
     }
 
+    /**
+     * Replace the bases: a host whose reference models change (a live
+     * database after its schema changed) gives them afresh. The parts made
+     * for the old ones are disposed; nothing open is touched.
+     * @param {Array<Object>} specs - Editor part specs, as `bases` in the spec
+     */
+    setBases(specs = []) {
+        for (const base of this._bases ?? []) base.dispose?.();
+        this._bases = null;
+        this.spec.bases = specs;
+        return this.bases();
+    }
+
     /** What a copy of a model is called: " (copy)" after its name, once (a copy of a copy is not "… (copy) (copy)"). */
     static copyName(name) {
         const plain = String(name || 'Untitled');
@@ -327,9 +438,33 @@ export class ModelsPart extends Part {
         return part;
     }
 
-    /** File ▸ New ▸'s items from bases: From base: <name>, one a base. */
+    /**
+     * Open a base to look at (by its place in `bases`): a tab of its own copy,
+     * named as the base is with " (view)", that can be laid out and moved
+     * about but is never kept — a live database seen as it is, without making a
+     * design of it. Returns the part.
+     */
+    viewBase(index) {
+        const spec = this.bases()[index]?.spec;
+        if (!spec) return null;
+        const { id, keepId, ...copy } = ModelsPart.copySpec(spec);
+        const part = this.newModel({ ...copy, name: `${copy.name ?? this.baseLabel(this.bases()[index], index)}${ModelsPart.VIEW_SUFFIX}` });
+        part.keepOff = true;
+        this.work.focus(part.id);
+        return part;
+    }
+
+    /** What a base viewed is called: " (view)" after its name. */
+    static VIEW_SUFFIX = ' (view)';
+
+    /** File ▸ New ▸'s items from bases: From base: <name>, a design from one; View base: <name>, one to look at. */
     baseItems() {
-        return this.bases().map((base, i) => ({ label: `From base: ${this.baseLabel(base, i)}`, action: () => this.newFromBase(i) }));
+        const bases = this.bases();
+        return [
+            ...bases.map((base, i) => ({ label: `From base: ${this.baseLabel(base, i)}`, action: () => this.newFromBase(i) })),
+            ...(bases.length ? [{ separator: true }] : []),
+            ...bases.map((base, i) => ({ label: `View base: ${this.baseLabel(base, i)}`, action: () => this.viewBase(i) })),
+        ];
     }
 
     /**
@@ -362,6 +497,10 @@ export class ModelsPart extends Part {
         return [
             { label: 'Compare with', items: each((a, b) => this.compare(a, b)) },
             { label: 'Merge from', items: each((a, b) => this.merge(a, b)) },
+            { separator: true },
+            { label: `Proposals (${this.proposals.length})`, items: this.proposalItems(part) },
+            // The host's own tools for the model in front (`services.modelTools(part, models)`: agents, say).
+            ...(typeof this.ctx?.modelTools === 'function' ? [{ separator: true }, ...this.ctx.modelTools(part, this)] : []),
         ];
     }
 
@@ -446,7 +585,7 @@ export class ModelsPart extends Part {
         return [
             ...(saves ? [save, saveAs, { separator: true }, { label: 'Duplicate model', action: () => this.duplicate(part) }] : []),
             ...(compare ? [compare, merge] : []),
-            ...(keeping.length ? [{ label: 'This browser', items: keeping }] : []),
+            ...(keeping.length ? [{ label: this.keptWhere, items: keeping }] : []),
             { separator: true },
             { label: 'Close model', action: () => this.closeModel(part.id) },
             { label: 'Close other models', disabled: !others.length || undefined, action: () => { for (const id of others) this.closeModel(id); } },