@peter.prib/renderengine 0.2.10 → 0.4.0

package/src/workspace/parts/RequirementsPart.js

@@ -0,0 +1,465 @@
+import { Part } from '../Part.js';
+import { el } from '../dom.js';
+import { ModelHosted } from './ModelHosted.js';
+import { EditorPart } from './EditorPart.js';
+import { MenuBar } from '../../charting/MenuBar.js';
+import { ToolbarMenu, ToolbarSelect, ToolbarText } from '../../charting/toolbar/index.js';
+import { FormDialog } from '../../charting/FormDialog.js';
+import { ModelCheckDialog } from '../../charting/ModelCheckDialog.js';
+import { PopupMenu } from '../../charting/PopupMenu.js';
+import {
+    RequirementsModel, RequirementsFileFormat, TrackerExportFileFormat, StoryboardFileFormat,
+} from '../../charting/requirements/index.js';
+
+/** The ways the model is shown: [id, label]. */
+const VIEWS = Object.freeze([['map', 'Story map'], ['backlog', 'Backlog']]);
+
+/** How a story card and the map's headers look, from the workspace theme. */
+const CARD = {
+    background: 'var(--ws-panel-bg, #fff)', color: 'var(--ws-fg, #222)', border: '1px solid var(--ws-border, #ccc)',
+    borderLeft: '4px solid #f0c040', borderRadius: '4px', padding: '6px 8px', margin: '0 0 6px', fontSize: '12px', cursor: 'pointer',
+};
+const HEAD = { padding: '6px 8px', fontWeight: '600', fontSize: '12px', textAlign: 'left', verticalAlign: 'top', cursor: 'pointer' };
+const CELL = { padding: '6px', verticalAlign: 'top', minWidth: '180px', borderTop: '1px solid var(--ws-border, #ddd)', borderLeft: '1px solid var(--ws-border, #ddd)' };
+const BADGE = { display: 'inline-block', marginRight: '6px', color: 'var(--ws-muted, #777)', fontSize: '11px' };
+
+/**
+ * RequirementsPart — a requirements model (RequirementsModel) in a pane, as an
+ * agile team works with it: a **story map** (epics across, releases down,
+ * each story a card — dragged to another epic or release, or among its
+ * neighbours) or the **backlog** (every story in order, a row each). A card
+ * or a row opened edits the story: its narrative ("As a … I want … so that
+ * …"), acceptance criteria, status, priority, points, labels and traces to
+ * what realises it in the other models. Model ▸ adds epics, releases and
+ * stories, brings stories in from a tracker's export or a storyboard, and
+ * checks the model (RequirementsChecker); the toolbar shows how complete it
+ * is (coverage: criteria, traces).
+ *
+ * A model of a ModelsPart (`editorType: 'requirements'`) as the other
+ * modellers' are (ModelHosted): saved as `.requirements.json`, opened from a
+ * tracker's export or a storyboard too, kept, compared and merged, a proposal
+ * reviewed.
+ *
+ * A host extends it by subclass: `traceTargets()` — what a story can be traced
+ * to (the elements of its other models); `resolveTrace(trace)` — whether a
+ * trace's target is there (for the check); `storyStatus(story)` — a live state
+ * shown on the card (a work item's), `{label, color?, title?}` or null;
+ * `searchByMeaning(query)` — the stories nearest a question (a vector
+ * store's), which puts Model ▸ Find by meaning… in the menu.
+ *
+ * Spec: `{ id, type: 'requirements', title?, view?: 'map'|'backlog', ...the
+ * model as RequirementsModel takes it }`.
+ */
+export class RequirementsPart extends ModelHosted(Part) {
+    static type = 'requirements';
+
+    static VIEWS = VIEWS;
+
+    constructor(spec = {}) {
+        super(spec);
+        this._adoptModel(new RequirementsModel(spec));
+        /** The view shown: 'map' or 'backlog'. */
+        this.view = VIEWS.some(([id]) => id === spec.view) ? spec.view : 'map';
+        this.menuBar = null;
+        this.body = null;
+    }
+
+    // ===== A model saved as a file, kept, backed up =====
+
+    /** Its own format first (what it saves as), then what other tools wrote (import only). */
+    fileFormats() {
+        return [
+            RequirementsFileFormat.instance ??= new RequirementsFileFormat(),
+            TrackerExportFileFormat.instance ??= new TrackerExportFileFormat(),
+            StoryboardFileFormat.instance ??= new StoryboardFileFormat(),
+        ];
+    }
+
+    /** Edit another model (one opened, imported or kept). */
+    replaceModel(model) {
+        this._adoptModel(model);
+        this.afterModelEdit();
+    }
+
+    afterModelEdit() {
+        if (this.menuBar) { this.menuBar.items = this.menuBarItems(); this.menuBar.render?.(); }
+        this._draw();
+    }
+
+    // ===== What a host adds =====
+
+    /** What a story can be traced to: `[{kind, ref, name, model?}]`. None here; a host gives its models' elements. */
+    traceTargets() {
+        return [];
+    }
+
+    /** Whether a trace's target is there: true, false, or undefined (cannot tell). */
+    resolveTrace(trace) {
+        return undefined;
+    }
+
+    /** A live state shown on a story's card: `{label, color?, title?}`, or null. */
+    storyStatus(story) {
+        return null;
+    }
+
+    /**
+     * The stories nearest a question by meaning, best first: a promise of
+     * `[{id, score}]` (score 0..1). None here; a host with a vector store gives
+     * them, and Model ▸ Find by meaning… is offered.
+     */
+    searchByMeaning(query) {
+        return null;
+    }
+
+    /** Whether stories can be found by meaning here (a host gives searchByMeaning). */
+    get searchable() {
+        return this.searchByMeaning !== RequirementsPart.prototype.searchByMeaning;
+    }
+
+    // ===== Shown =====
+
+    render() {
+        Object.assign(this.container.style, { display: 'flex', flexDirection: 'column', height: '100%' });
+        const toolbar = this.container.appendChild(el({}, this.document));
+        this.body = this.container.appendChild(el({ style: { flex: '1 1 auto', minHeight: '0', overflow: 'auto', padding: '8px', background: 'var(--ws-bg, #fafafa)' } }, this.document));
+        this.menuBar = new MenuBar({ container: toolbar, items: this.menuBarItems(), document: this.document }).render();
+        this._draw();
+    }
+
+    /** Draw the view shown. @private */
+    _draw() {
+        if (!this.body) return;
+        this.body.replaceChildren(el(this.view === 'backlog' ? this.backlogSpec() : this.storyMapSpec(), this.document));
+    }
+
+    /** Show the story map or the backlog. */
+    setView(view) {
+        if (!VIEWS.some(([id]) => id === view)) return;
+        this.view = view;
+        this._draw();
+        this.menuBar?.refresh?.();
+    }
+
+    menuBarItems() {
+        const host = this.modelsHost;
+        return [
+            new ToolbarMenu('File', () => this.fileItems()),
+            new ToolbarMenu('Edit', () => this.undoItems()),
+            ...(host ? [new ToolbarMenu('Tools', () => host.toolItems(this))] : []),
+            new ToolbarMenu('Model', () => this.modelItems()),
+            new ToolbarSelect('View', () => VIEWS.map(([id, label]) => [id, label]), () => this.view, (v) => this.setView(v)),
+            new ToolbarText(() => this.coverageText()),
+        ];
+    }
+
+    /** How complete it is, in a line: stories, with criteria, traced. */
+    coverageText() {
+        const c = this.model.coverage();
+        if (!c.stories) return 'No stories yet';
+        const pct = (share) => `${Math.round(share * 100)}%`;
+        return `${c.stories} stor${c.stories === 1 ? 'y' : 'ies'} · ${pct(c.criteriaShare)} with acceptance criteria · ${pct(c.traceShare)} traced`;
+    }
+
+    /** Model ▸: new epic, release and story; stories brought in; the check. */
+    modelItems() {
+        return [
+            { label: 'New story…', action: () => this.editStory(null) },
+            { label: 'New epic…', action: () => this.editEpic(null) },
+            { label: 'New release…', action: () => this.editRelease(null) },
+            { separator: true },
+            ...EditorPart.menuGroup('Bring in stories', [
+                { label: 'From a tracker\'s export (Jira, Azure DevOps, GitLab)…', action: () => this.bringFrom(this.fileFormats()[1]) },
+                { label: 'From a storyboard (Markdown)…', action: () => this.bringFrom(this.fileFormats()[2]) },
+            ]),
+            { separator: true },
+            ...(this.searchable ? [{ label: 'Find by meaning…', action: () => this.findByMeaning() }] : []),
+            { label: 'Check model…', action: () => this.checkModel() },
+        ];
+    }
+
+    /** Ask what to look for, then list the stories nearest it by meaning; one chosen is opened. */
+    findByMeaning() {
+        return new FormDialog({
+            title: 'Find stories by meaning', document: this.document, submitLabel: 'Find',
+            description: 'Describe what you are looking for in your own words: stories that mean the same are found, whatever their words.',
+            fields: [{ key: 'query', label: 'Looking for', value: '' }],
+            validate: (v) => (String(v.query ?? '').trim() ? null : 'Say what to look for'),
+            onApply: ({ query }) => this.showFound(query),
+        }).open();
+    }
+
+    /** The stories nearest `query` (searchByMeaning), listed to open; a failure said. */
+    async showFound(query) {
+        let results;
+        try {
+            results = (await this.searchByMeaning(query)) ?? [];
+        } catch (err) {
+            (this.document.defaultView ?? globalThis).alert?.(`Could not search: ${err.message}`);
+            return null;
+        }
+        const found = results.filter(r => this.model.story(r.id)).map(r => ({
+            code: 'found', severity: 'info', kind: 'story', ids: [r.id],
+            message: `${Math.round((r.score ?? 0) * 100)}% — ${this.model.story(r.id).name}`,
+        }));
+        new ModelCheckDialog({
+            findings: found, title: `Stories like "${query}"`, empty: 'No story found: index the model for search, or ask another way.',
+            onReveal: (f) => this.revealFinding(f), document: this.document,
+        }).open();
+        return found;
+    }
+
+    /**
+     * Bring a file's epics, releases and stories into this model (an import
+     * format's spec), as one undo step: one with the id of one here replaces it.
+     */
+    bringFrom(format, options = {}) {
+        return this.readInto({
+            ...options, accept: format.accept, what: 'the file',
+            command: (bytes, name) => {
+                const spec = format.spec(new TextDecoder().decode(bytes));
+                if (!spec.stories.length && !spec.epics.length) return null;
+                return this.model.bringCommand(spec, `Bring in "${name}"`);
+            },
+            nothing: (name) => `"${name}" has no epics or stories.`,
+        });
+    }
+
+    /** The findings (RequirementsChecker, traces resolved by the host); one opened edits its story or epic. */
+    checkModel() {
+        const findings = this.model.checker({ resolve: (trace) => this.resolveTrace(trace) }).run();
+        new ModelCheckDialog({ findings, onReveal: (f) => this.revealFinding(f), document: this.document }).open();
+        return findings;
+    }
+
+    /** Open what a finding is about. */
+    revealFinding(finding) {
+        const [id] = finding.ids ?? [];
+        if (finding.kind === 'epic') return this.editEpic(id);
+        if (finding.kind === 'story') return this.editStory(id);
+        return null;
+    }
+
+    // ===== The views, as element specs =====
+
+    /** A story as a card: its name, its sentence, and badges (criteria, traces, points, status). */
+    cardSpec(story) {
+        const live = this.storyStatus(story);
+        const badges = [
+            story.criteria.length ? `✓ ${story.criteria.length}` : '✓ none',
+            story.traces.length ? `→ ${story.traces.length}` : null,
+            story.points != null ? `${story.points} pt` : null,
+            story.status || null,
+        ].filter(Boolean);
+        return {
+            cls: 'rq-card', dataset: { storyId: story.id }, attrs: { draggable: 'true', title: RequirementsModel.narrative(story) || story.description || story.name },
+            style: { ...CARD, ...(story.criteria.length ? {} : { borderLeftColor: '#e08a3c' }) },
+            on: {
+                click: () => this.editStory(story.id),
+                contextmenu: (e) => { e.preventDefault(); PopupMenu.show(e.clientX, e.clientY, this.storyMenuItems(story.id), this.document); },
+                dragstart: (e) => { e.dataTransfer?.setData('text/plain', story.id); },
+                dragover: (e) => e.preventDefault(),
+                drop: (e) => { e.preventDefault(); e.stopPropagation(); this.dropStory(e.dataTransfer?.getData('text/plain'), { before: story.id, epic: story.epic, release: story.release }); },
+            },
+            children: [
+                { text: story.name, style: { fontWeight: '600' } },
+                ...(story.want ? [{ text: RequirementsModel.narrative(story), style: { color: 'var(--ws-muted, #666)', margin: '2px 0' } }] : []),
+                {
+                    style: { marginTop: '4px' },
+                    children: [
+                        ...badges.map(text => ({ tag: 'span', text, style: BADGE })),
+                        ...(live ? [{ tag: 'span', text: live.label, attrs: { title: live.title ?? '' }, style: { ...BADGE, color: '#fff', background: live.color ?? '#557', borderRadius: '8px', padding: '0 6px' } }] : []),
+                    ],
+                },
+            ],
+        };
+    }
+
+    /** The story map: a table, epics across, releases down; a cell takes a card dropped on it, and + adds one there. */
+    storyMapSpec() {
+        const map = this.model.storyMap();
+        const drop = (epic, release) => ({
+            dragover: (e) => e.preventDefault(),
+            drop: (e) => { e.preventDefault(); this.dropStory(e.dataTransfer?.getData('text/plain'), { epic, release }); },
+        });
+        return {
+            tag: 'table', cls: 'rq-map', style: { borderCollapse: 'collapse', color: 'var(--ws-fg, #222)' },
+            children: [
+                {
+                    tag: 'thead', children: [{
+                        tag: 'tr', children: [
+                            { tag: 'th', style: HEAD },
+                            ...map.columns.map(c => ({
+                                tag: 'th', text: c.name, dataset: { epicId: c.id }, style: { ...HEAD, background: 'var(--ws-panel-bg, #fff)', borderBottom: '3px solid #6b8fd6' },
+                                attrs: { title: c.epic?.description ?? '' },
+                                on: c.epic ? { click: () => this.editEpic(c.id) } : {},
+                            })),
+                        ],
+                    }],
+                },
+                {
+                    tag: 'tbody', children: map.rows.map(r => ({
+                        tag: 'tr', dataset: { releaseId: r.id }, children: [
+                            { tag: 'th', text: r.name, style: { ...HEAD, color: 'var(--ws-muted, #666)' }, on: r.release ? { click: () => this.editRelease(r.id) } : {} },
+                            ...map.columns.map(c => ({
+                                tag: 'td', cls: 'rq-cell', dataset: { epicId: c.id, releaseId: r.id }, style: CELL, on: drop(c.id, r.id),
+                                children: [
+                                    ...map.cell(c.id, r.id).map(s => this.cardSpec(s)),
+                                    { tag: 'button', text: '+', attrs: { title: 'New story here' }, style: { border: 'none', background: 'none', color: 'var(--ws-muted, #888)', cursor: 'pointer' }, on: { click: () => this.editStory(null, { epic: c.id, release: r.id }) } },
+                                ],
+                            })),
+                        ],
+                    })),
+                },
+            ],
+        };
+    }
+
+    /** The backlog: every story in order, a row each. */
+    backlogSpec() {
+        const epicName = (id) => this.model.epic(id)?.name ?? '';
+        const releaseName = (id) => this.model.release(id)?.name ?? '';
+        const columns = ['Story', 'Epic', 'Release', 'Status', 'Priority', 'Points', 'Criteria', 'Traces'];
+        return {
+            tag: 'table', cls: 'rq-backlog', style: { borderCollapse: 'collapse', width: '100%', fontSize: '12px', color: 'var(--ws-fg, #222)' },
+            children: [
+                { tag: 'thead', children: [{ tag: 'tr', children: columns.map(c => ({ tag: 'th', text: c, style: { ...HEAD, borderBottom: '1px solid var(--ws-border, #ccc)' } })) }] },
+                {
+                    tag: 'tbody', children: this.model.stories.map(s => ({
+                        tag: 'tr', dataset: { storyId: s.id }, style: { cursor: 'pointer' },
+                        on: { click: () => this.editStory(s.id), contextmenu: (e) => { e.preventDefault(); PopupMenu.show(e.clientX, e.clientY, this.storyMenuItems(s.id), this.document); } },
+                        children: [s.name, epicName(s.epic), releaseName(s.release), s.status, s.priority, s.points ?? '', s.criteria.length, s.traces.length]
+                            .map(text => ({ tag: 'td', text, style: { padding: '4px 8px', borderBottom: '1px solid var(--ws-border, #eee)' } })),
+                    })),
+                },
+            ],
+        };
+    }
+
+    /** A card dropped: the story moved there (before the card it fell on). */
+    dropStory(id, { epic, release, before = null }) {
+        if (!id || !this.model.story(id) || id === before) return null;
+        return this.runModelEdit(this.model.moveStoryCommand(id, { epic, release, before }));
+    }
+
+    /** A story's right-click menu. */
+    storyMenuItems(id) {
+        return [
+            { label: 'Edit story…', action: () => this.editStory(id) },
+            { label: 'Trace to…', action: () => this.editTraces(id) },
+            { separator: true },
+            { label: 'Remove story', action: () => this.runModelEdit(this.model.removeStoryCommand(id)) },
+        ];
+    }
+
+    // ===== Dialogs =====
+
+    /** The fields a story is edited in (one definition: the dialog shows them, saveStory reads them). */
+    storyFields(story = {}) {
+        const choices = (list, none) => [['', none], ...list.map(x => [x.id, x.name])];
+        const statuses = [...new Set([...RequirementsModel.STATUSES, ...(story.status ? [story.status] : [])])];
+        return [
+            { key: 'name', label: 'Story', value: story.name ?? '' },
+            { key: 'epic', label: 'Epic', type: 'select', value: story.epic ?? '', choices: choices(this.model.epics, 'No epic') },
+            { key: 'release', label: 'Release', type: 'select', value: story.release ?? '', choices: choices(this.model.releases, 'Not planned') },
+            { type: 'heading', label: 'As a … I want … so that …' },
+            { key: 'as', label: 'As a', value: story.as ?? '' },
+            { key: 'want', label: 'I want', value: story.want ?? '' },
+            { key: 'soThat', label: 'So that', value: story.soThat ?? '' },
+            { key: 'description', label: 'Description', type: 'textarea', rows: 3, value: story.description ?? '' },
+            { key: 'criteria', label: 'Acceptance criteria (one a line)', type: 'textarea', rows: 4, value: (story.criteria ?? []).map(c => c.text).join('\n') },
+            { key: 'status', label: 'Status', type: 'select', value: story.status ?? '', choices: [['', '—'], ...statuses.map(s => [s, s])] },
+            { key: 'priority', label: 'Priority', value: story.priority ?? '' },
+            { key: 'points', label: 'Points', type: 'number', value: story.points ?? '' },
+            { key: 'labels', label: 'Labels (comma between)', value: (story.labels ?? []).join(', ') },
+        ];
+    }
+
+    /**
+     * A story's values from its dialog, as RequirementsModel takes them; a
+     * criterion whose text is unchanged keeps its id.
+     */
+    storyFromValues(values, story = null) {
+        const old = new Map((story?.criteria ?? []).map(c => [c.text, c.id]));
+        return {
+            name: String(values.name ?? '').trim(), epic: values.epic ?? '', release: values.release ?? '',
+            as: values.as ?? '', want: values.want ?? '', soThat: values.soThat ?? '', description: values.description ?? '',
+            criteria: String(values.criteria ?? '').split('\n').map(t => t.trim()).filter(Boolean).map(text => (old.has(text) ? { id: old.get(text), text } : text)),
+            status: values.status ?? '', priority: values.priority ?? '',
+            points: values.points === '' || values.points == null || Number.isNaN(Number(values.points)) ? null : Number(values.points),
+            labels: String(values.labels ?? '').split(',').map(l => l.trim()).filter(Boolean),
+        };
+    }
+
+    /** Edit a story (`id` null: a new one, where `at` says). */
+    editStory(id, at = {}) {
+        const story = id ? this.model.story(id) : null;
+        if (id && !story) return null;
+        return new FormDialog({
+            title: story ? `Story: ${story.name}` : 'New story', document: this.document, submitLabel: story ? 'Save' : 'Add',
+            fields: this.storyFields(story ?? { epic: at.epic ?? '', release: at.release ?? '' }),
+            validate: (v) => (String(v.name ?? '').trim() ? null : 'A story needs a name'),
+            onApply: (values) => this.runModelEdit(this.model.saveStoryCommand(id, this.storyFromValues(values, story))),
+        }).open();
+    }
+
+    /** Edit a story's traces: each a row (kind, what, its name), what the host offers suggested. */
+    editTraces(id) {
+        const story = this.model.story(id);
+        if (!story) return null;
+        const targets = this.traceTargets();
+        return new FormDialog({
+            title: `Traces: ${story.name}`, document: this.document,
+            description: 'What realises this story: an ArchiMate requirement or work package, an element, a data concept, entity or table.',
+            fields: [{
+                key: 'traces', label: '', type: 'rows', addLabel: 'Add trace', value: story.traces,
+                columns: [
+                    { key: 'kind', label: 'Kind', type: 'select', choices: RequirementsModel.TRACE_KINDS },
+                    { key: 'ref', label: 'What (its id)', suggestions: targets.map(t => t.ref) },
+                    { key: 'name', label: 'Name', suggestions: targets.map(t => t.name).filter(Boolean) },
+                ],
+            }],
+            onApply: ({ traces = [] }) => {
+                // A ref the host knows names itself, and says which model it is in.
+                const known = new Map(targets.map(t => [t.ref, t]));
+                const rows = traces.filter(t => t.ref).map(t => ({ ...known.get(t.ref), ...t, name: t.name || known.get(t.ref)?.name || '' }));
+                return this.runModelEdit(this.model.saveStoryCommand(id, { traces: rows }));
+            },
+        }).open();
+    }
+
+    editEpic(id) {
+        const epic = id ? this.model.epic(id) : null;
+        if (id && !epic) return null;
+        return new FormDialog({
+            title: epic ? `Epic: ${epic.name}` : 'New epic', document: this.document, submitLabel: epic ? 'Save' : 'Add',
+            fields: [
+                { key: 'name', label: 'Epic', value: epic?.name ?? '' },
+                { key: 'description', label: 'Outcome', type: 'textarea', rows: 3, value: epic?.description ?? '' },
+            ],
+            validate: (v) => (String(v.name ?? '').trim() ? null : 'An epic needs a name'),
+            onApply: (v) => this.runModelEdit(this.model.saveEpicCommand(id, { name: v.name.trim(), description: v.description ?? '' })),
+        }).open();
+    }
+
+    editRelease(id) {
+        const release = id ? this.model.release(id) : null;
+        if (id && !release) return null;
+        return new FormDialog({
+            title: release ? `Release: ${release.name}` : 'New release', document: this.document, submitLabel: release ? 'Save' : 'Add',
+            fields: [{ key: 'name', label: 'Release', value: release?.name ?? '' }],
+            validate: (v) => (String(v.name ?? '').trim() ? null : 'A release needs a name'),
+            onApply: (v) => this.runModelEdit(this.model.saveReleaseCommand(id, { name: v.name.trim() })),
+        }).open();
+    }
+
+    dispose() {
+        this.menuBar?.dispose?.();
+        super.dispose();
+    }
+
+    /** The spec again: the model, and the view shown. */
+    serialize() {
+        return { ...super.serialize(), ...this.model.toJSON(), view: this.view };
+    }
+}

package/src/workspace/storage/ModelLibrary.js

@@ -11,9 +11,15 @@ export class ModelLibrary {
     /** The key prefix of a kept model. */
     static PREFIX = 'model:';
 
-    /** @param {KeyValueStore} store */
-    constructor(store) {
+    /**
+     * @param {KeyValueStore} store
+     * @param {Object} [options]
+     * @param {string} [options.label] - Where it keeps models, as its menu names it
+     */
+    constructor(store, { label = 'This browser' } = {}) {
         this.store = store;
+        /** Where it keeps models, as the File menu names it ('This browser'). */
+        this.label = label;
     }
 
     /** A new id for a model to keep. */