@peter.prib/renderengine 0.4.0 → 0.7.0

package/src/charting/modelTree/TreeBuilder.js

@@ -1,3 +1,20 @@
+/** A row of the tree, branch or leaf: one line, compact; a label too long ends in an ellipsis. */
+const ROW_STYLE = `
+    cursor: pointer;
+    padding: 1px 4px;
+    margin: 0;
+    border-radius: 3px;
+    user-select: none;
+    border-left: 3px solid transparent;
+    transition: background-color 0.1s;
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    line-height: 1.35;
+    white-space: nowrap;
+    overflow: hidden;
+`;
+
 /**
  * Generic tree component builder for hierarchical node rendering.
  * Handles expand/collapse, selection, context menus, and recursive rendering.
@@ -19,8 +36,14 @@ export class TreeBuilder {
      * @param {Map<string, boolean>} [options.openState] - Which folders are open, by node id: kept
      *   by the caller so a rebuilt tree opens them as they were. A folder not in it is open unless
      *   its node says `collapsed: true`; opening or closing one records it here.
+     * @param {(node) => boolean} [options.filter] - Which leaves are shown: a folder is shown when a
+     *   leaf under it is, and open while filtering. None: every node.
+     * @param {number} [options.leafLimit] - The leaves a folder shows; the rest wait behind a
+     *   "▸ N more" row, which shows them. The folders inside it always show.
+     * @param {Set<string>} [options.shownAll] - The folders (by node id) showing every leaf, kept by
+     *   the caller as openState is; asking for "more" records the folder here.
      */
-    constructor(doc, { container, rootNodes = [], onNodeClick = null, onNodeContext = null, getNodeChildren = null, openState = new Map(), iconFor = null } = {}) {
+    constructor(doc, { container, rootNodes = [], onNodeClick = null, onNodeContext = null, getNodeChildren = null, openState = new Map(), iconFor = null, filter = null, leafLimit = Infinity, shownAll = new Set() } = {}) {
         this.doc = doc;
         this.container = container;
         this.rootNodes = rootNodes;
@@ -29,7 +52,12 @@ export class TreeBuilder {
         this.getNodeChildren = getNodeChildren;
         this.openState = openState;
         this.iconFor = iconFor;
+        this.filter = filter;
+        this.leafLimit = leafLimit;
+        this.shownAll = shownAll;
         this.selectedNode = null;
+        /** Each node's shown children, asked for once per render (getNodeChildren makes new nodes). */
+        this._children = new WeakMap();
     }
 
     /**
@@ -40,10 +68,25 @@ export class TreeBuilder {
         const container = this.container;
         if (!container) return;
 
-        container.innerHTML = '';
-        for (const node of nodes) {
-            container.appendChild(this._renderNode(node));
+        this._children = new WeakMap();
+        container.replaceChildren(...nodes.filter(node => this._shown(node)).map(node => this._renderNode(node)));
+    }
+
+    /** A node's children that are shown: with a filter, the leaves it keeps and the folders holding one. @private */
+    _childrenOf(node) {
+        if (!this._children.has(node)) {
+            const all = this.getNodeChildren?.(node) || [];
+            this._children.set(node, this.filter ? all.filter(child => this._shown(child)) : all);
         }
+        return this._children.get(node);
+    }
+
+    /** Whether a node is shown: always without a filter; else a leaf the filter keeps, or a folder with a shown child. @private */
+    _shown(node) {
+        if (!this.filter) return true;
+        if (this._childrenOf(node).length) return true;
+        // A folder whose children are all filtered out is not a leaf to test.
+        return !(this.getNodeChildren?.(node) || []).length && !!this.filter(node);
     }
 
     /**
@@ -51,14 +94,8 @@ export class TreeBuilder {
      * @private
      */
     _renderNode(node) {
-        const children = this.getNodeChildren?.(node) || [];
-        const hasChildren = children.length > 0;
-
-        if (hasChildren) {
-            return this._renderExpandable(node, children);
-        } else {
-            return this._renderLeaf(node);
-        }
+        const children = this._childrenOf(node);
+        return children.length ? this._renderExpandable(node, children) : this._renderLeaf(node);
     }
 
     /**
@@ -67,23 +104,13 @@ export class TreeBuilder {
      */
     _renderExpandable(node, children) {
         const details = this.doc.createElement('details');
-        details.open = this.openState.get(node.id) ?? !node.collapsed;
+        // Open while filtering, to show what was found (not recorded); else as it was.
+        details.open = this.filter ? true : this.openState.get(node.id) ?? !node.collapsed;
         details.setAttribute('data-node-id', node.id);
-        details.addEventListener('toggle', () => this.openState.set(node.id, details.open));
+        details.addEventListener('toggle', () => { if (!this.filter) this.openState.set(node.id, details.open); });
 
         const summary = this.doc.createElement('summary');
-        summary.style.cssText = `
-            cursor: pointer;
-            padding: 4px 6px;
-            margin: 2px 0;
-            border-radius: 3px;
-            user-select: none;
-            border-left: 3px solid transparent;
-            transition: background-color 0.1s;
-            display: flex;
-            align-items: center;
-            gap: 6px;
-        `;
+        summary.style.cssText = ROW_STYLE;
         summary.setAttribute('data-node-id', node.id);
 
         this._applyNodeStyling(summary, node);
@@ -95,15 +122,45 @@ export class TreeBuilder {
         details.appendChild(summary);
 
         const childContainer = this.doc.createElement('div');
-        childContainer.style.cssText = 'padding-left: 16px;';
-        for (const child of children) {
-            childContainer.appendChild(this._renderNode(child));
-        }
+        childContainer.style.cssText = 'padding-left: 12px;';
+        this._fillChildren(childContainer, node, children);
         details.appendChild(childContainer);
 
         return details;
     }
 
+    /**
+     * A folder's children: its folders, and its leaves up to leafLimit, then a
+     * "▸ N more" row that shows the rest (unless the folder shows them all already).
+     * @private
+     */
+    _fillChildren(container, node, children) {
+        const limit = this.shownAll.has(node.id) ? Infinity : this.leafLimit;
+        let leaves = 0;
+        let waiting = 0;
+        const rows = [];
+        for (const child of children) {
+            if (!this._childrenOf(child).length && leaves++ >= limit) { waiting++; continue; }
+            rows.push(this._renderNode(child));
+        }
+        if (waiting) rows.push(this._moreRow(waiting, () => {
+            this.shownAll.add(node.id);
+            this._fillChildren(container, node, children);
+        }));
+        container.replaceChildren(...rows);
+    }
+
+    /** The row standing for `count` leaves not shown; choosing it calls `showAll`. @private */
+    _moreRow(count, showAll) {
+        const row = this.doc.createElement('div');
+        row.setAttribute('data-tree-more', String(count));
+        row.style.cssText = `${ROW_STYLE} color: #666; font-style: italic;`;
+        row.textContent = `▸ ${count} more`;
+        row.title = 'Show them all';
+        row.addEventListener('click', (e) => { e.stopPropagation(); showAll(); });
+        return row;
+    }
+
     /**
      * Render a leaf node without children.
      * @private
@@ -111,23 +168,12 @@ export class TreeBuilder {
     _renderLeaf(node) {
         const leaf = this.doc.createElement('div');
         leaf.setAttribute('data-node-id', node.id);
-        // Element leaves are filter targets and drag sources; mark them here so a rebuilt tree keeps that.
+        // Element leaves are drag sources; mark them here so a rebuilt tree keeps that.
         if (node.type === 'element' && node._element) {
             leaf.setAttribute('data-element-id', node._element.id);
             leaf.draggable = true;
         }
-        leaf.style.cssText = `
-            padding: 4px 6px;
-            margin: 2px 0;
-            border-radius: 3px;
-            cursor: pointer;
-            user-select: none;
-            border-left: 3px solid transparent;
-            transition: background-color 0.1s;
-            display: flex;
-            align-items: center;
-            gap: 6px;
-        `;
+        leaf.style.cssText = ROW_STYLE;
 
         this._applyNodeStyling(leaf, node);
         leaf.addEventListener('click', (e) => this._handleNodeClick(e, leaf, node));
@@ -153,13 +199,15 @@ export class TreeBuilder {
         } else if (node.icon) {
             const icon = this.doc.createElement('span');
             icon.textContent = node.icon;
-            icon.style.cssText = 'flex-shrink: 0; font-size: 14px;';
+            icon.style.cssText = 'flex-shrink: 0; font-size: 11px;';
             element.appendChild(icon);
         }
 
-        // Label
+        // Label: one line, cut with an ellipsis; the whole of it on hover.
         const label = this.doc.createElement('span');
         label.textContent = node.label || 'Untitled';
+        label.style.cssText = 'overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0;';
+        element.title = label.textContent;
         element.appendChild(label);
     }
 

package/src/charting/modelTree/TreeViewMode.js

@@ -7,6 +7,13 @@ export class TreeViewMode {
     static key = null;          // registry key; subclasses override
     static label = '';          // human-readable label; subclasses override
 
+    /** Whether `text` is in any of `fields` (case ignored); no text matches everything. */
+    static textMatches(text, fields) {
+        if (!text) return true;
+        const lower = text.toLowerCase();
+        return fields.some(f => String(f ?? '').toLowerCase().includes(lower));
+    }
+
     constructor() {
         if (new.target === TreeViewMode) {
             throw new TypeError('TreeViewMode is abstract — subclass it');
@@ -59,12 +66,8 @@ export class TreeViewMode {
      */
     _matchesFilter(item, { text = '', typeIds = null, specializationIds = null, propertyIds = null, inDescriptions = false } = {}) {
         // Text filter (label or type; the description too when asked)
-        if (text) {
-            const textLower = text.toLowerCase();
-            const fields = [item.label, item.type, ...(inDescriptions ? [item.description] : [])];
-            if (!fields.some(f => String(f ?? '').toLowerCase().includes(textLower))) {
-                return false;
-            }
+        if (!TreeViewMode.textMatches(text, [item.label, item.type, ...(inDescriptions ? [item.description] : [])])) {
+            return false;
         }
 
         // Type filter (elements only; 'type:business-actor' format)

package/src/charting/modelTree/viewFolders.js

@@ -6,23 +6,32 @@ const VIEW_ICONS = Object.freeze({ canvas: '🎨' });
  * keeps them: each view remembers its sub-folder path (`archiFolder`, folder
  * steps {id, name}). A folder node per sub-folder at this depth (holding the
  * views under it, opened a level deeper), then the views that sit here, each
- * in the model's order.
+ * in the model's order. A sub-folder that holds no view is there too, from
+ * its path (the model's `emptyViewFolders`).
  * @param {Array<Object>} views
  * @param {number} [depth]
+ * @param {Array<Array<{id, name}>>} [emptyFolders] - The paths of the folders with no view in them
  * @returns {Array<Object>} TreeBuilder nodes: {id, label, icon, type: 'view-folder'|'view', ...}
  */
-export function viewFolderNodes(views, depth = 0) {
+export function viewFolderNodes(views, depth = 0, emptyFolders = []) {
     const folders = new Map();
+    const folderOf = (step) => {
+        if (!folders.has(step.id)) folders.set(step.id, { step, views: [], empty: [] });
+        return folders.get(step.id);
+    };
     const here = [];
     for (const view of views) {
         const step = view.archiFolder?.[depth];
         if (!step) { here.push(view); continue; }
-        if (!folders.has(step.id)) folders.set(step.id, { step, views: [] });
-        folders.get(step.id).views.push(view);
+        folderOf(step).views.push(view);
+    }
+    for (const path of emptyFolders) {
+        if (path.length > depth) folderOf(path[depth]).empty.push(path);
     }
     return [
-        ...[...folders.values()].map(({ step, views: inside }) => ({
-            id: `view-folder-${step.id}`, label: step.name || 'Untitled Folder', icon: '📁', type: 'view-folder', _views: inside, _depth: depth + 1,
+        ...[...folders.values()].map(({ step, views: inside, empty }) => ({
+            id: `view-folder-${step.id}`, label: step.name || 'Untitled Folder', icon: '📁', type: 'view-folder',
+            _views: inside, _emptyFolders: empty, _depth: depth + 1,
         })),
         ...here.map(view => ({
             id: view.id, label: view.name || view.title || 'Untitled View', icon: VIEW_ICONS[view.constructor.kind] ?? '📄', type: 'view', _view: view,

package/src/charting/requirements/AzureDevOpsApi.js

@@ -0,0 +1,55 @@
+import { TrackerApi } from './TrackerApi.js';
+
+/**
+ * Azure DevOps (Boards) through its REST API: a WIQL query for a project's
+ * work items (but its tasks — TRACKERS), then the items, 200 at a time. Signs
+ * in with a personal access token. Each item's link is its page in Boards.
+ */
+export class AzureDevOpsApi extends TrackerApi {
+    static tracker = 'azure';
+
+    /** Most ids one work-items request takes. */
+    static BATCH = 200;
+
+    static API_VERSION = '7.1';
+
+    static baseUrlPlaceholder = 'https://dev.azure.com/your-organisation';
+
+    static tokenHint = 'A personal access token with Work Items (Read)';
+
+    static get ownFields() {
+        return [
+            { key: 'project', label: 'Project', required: true, placeholder: 'The project, e.g. Shop' },
+            { key: 'query', label: 'WIQL condition', placeholder: "[System.AreaPath] UNDER 'Shop\\Checkout' (and the project's)" },
+        ];
+    }
+
+    headers() {
+        return { Authorization: `Basic ${TrackerApi.base64(`:${this.connection.token}`)}` };
+    }
+
+    /** The WIQL: the project's work items, not its tasks, and the condition given. */
+    get wiql() {
+        const types = this.skipTypes.map(t => `'${t.replace(/'/g, "''")}'`).join(', ');
+        const condition = String(this.connection.query ?? '').trim();
+        return `SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project`
+            + (types ? ` AND [System.WorkItemType] NOT IN (${types})` : '')
+            + (condition ? ` AND (${condition})` : '')
+            + ' ORDER BY [System.Id]';
+    }
+
+    async _read() {
+        const project = encodeURIComponent(String(this.connection.project).trim());
+        const version = `api-version=${this.constructor.API_VERSION}`;
+        const { json } = await this.request(this.url(`/${project}/_apis/wit/wiql?${version}`), { method: 'POST', body: { query: this.wiql } });
+        const ids = (json.workItems ?? []).map(w => w.id);
+        const value = [];
+        for (let i = 0; i < ids.length; i += this.constructor.BATCH) {
+            const batch = ids.slice(i, i + this.constructor.BATCH);
+            const { json: items } = await this.request(this.url(`/${project}/_apis/wit/workitems?ids=${batch.join(',')}&${version}`));
+            const got = (items.value ?? []).map(w => ({ ...w, url: this.url(`/${project}/_workitems/edit/${w.id}`) }));
+            if (this.keep(value, got)) { this.truncated ||= i + batch.length < ids.length; break; }
+        }
+        return { value };
+    }
+}

package/src/charting/requirements/GitLabApi.js

@@ -0,0 +1,43 @@
+import { TrackerApi } from './TrackerApi.js';
+
+/**
+ * GitLab through its REST API: a project's issues, open and closed, 100 a
+ * page; filtered as its issues API filters (`labels=…&milestone=…`). Signs
+ * in with a personal, project or group access token. An issue's epic
+ * (GitLab Premium) is its epic.
+ */
+export class GitLabApi extends TrackerApi {
+    static tracker = 'gitlab';
+
+    static PAGE = 100;
+
+    static baseUrlPlaceholder = 'https://gitlab.com';
+
+    static tokenHint = 'An access token with read_api';
+
+    static get ownFields() {
+        return [
+            { key: 'project', label: 'Project', required: true, placeholder: 'group/project, or its id' },
+            { key: 'query', label: 'Filter', placeholder: 'labels=requirements&milestone=Release 2 (as the issues API takes)' },
+        ];
+    }
+
+    headers() {
+        return { 'PRIVATE-TOKEN': String(this.connection.token) };
+    }
+
+    async _read() {
+        const project = encodeURIComponent(String(this.connection.project).trim());
+        const issues = [];
+        for (let page = 1; page;) {
+            const params = new URLSearchParams(String(this.connection.query ?? '').trim());
+            for (const [k, v] of Object.entries({ state: params.get('state') ?? 'all', per_page: String(this.constructor.PAGE), page: String(page) })) params.set(k, v);
+            const { json, headers } = await this.request(this.url(`/api/v4/projects/${project}/issues?${params}`));
+            const got = Array.isArray(json) ? json : [];
+            const next = Number(headers?.get?.('x-next-page')) || (got.length === this.constructor.PAGE && !headers?.has?.('x-next-page') ? page + 1 : 0);
+            if (this.keep(issues, got)) { this.truncated ||= !!next; break; }
+            page = got.length ? next : 0;
+        }
+        return issues;
+    }
+}

package/src/charting/requirements/JiraApi.js

@@ -0,0 +1,69 @@
+import { TrackerApi } from './TrackerApi.js';
+
+/**
+ * Jira through its REST API: the issues a JQL query finds (a project's, by
+ * default), every field (custom ones too: story points, acceptance criteria).
+ * Jira Cloud signs in with an email and an API token and pages by token
+ * (`/rest/api/3/search/jql`); Jira Server and Data Center with a personal
+ * access token (no email), paging by offset (`/rest/api/2/search`).
+ */
+export class JiraApi extends TrackerApi {
+    static tracker = 'jira';
+
+    static PAGE = 100;
+
+    static baseUrlPlaceholder = 'https://your-site.atlassian.net';
+
+    static tokenHint = 'Jira Cloud: an API token (with the email above). Server / Data Center: a personal access token (no email).';
+
+    static get ownFields() {
+        return [
+            { key: 'edition', label: 'Jira', type: 'select', choices: [['cloud', 'Cloud'], ['server', 'Server / Data Center']], value: 'cloud' },
+            { key: 'user', label: 'Email', placeholder: 'The account the API token is for (Cloud)' },
+            { key: 'project', label: 'Project key', placeholder: 'SHOP — or leave it and give a JQL query' },
+            { key: 'query', label: 'JQL', placeholder: 'project = SHOP AND issuetype != Sub-task (instead of the project)' },
+        ];
+    }
+
+    problems() {
+        const out = super.problems();
+        if (!String(this.connection.project ?? '').trim() && !String(this.connection.query ?? '').trim()) out.push('A project key or a JQL query is needed.');
+        return out;
+    }
+
+    /** The JQL: the one given, else the project's issues in key order. */
+    get jql() {
+        const { query, project } = this.connection;
+        if (String(query ?? '').trim()) return String(query).trim();
+        return `project = "${String(project).trim().replace(/"/g, '\\"')}" ORDER BY key`;
+    }
+
+    headers() {
+        const { user, token } = this.connection;
+        return { Authorization: String(user ?? '').trim() ? `Basic ${TrackerApi.base64(`${String(user).trim()}:${token}`)}` : `Bearer ${token}` };
+    }
+
+    async _read() {
+        const issues = [];
+        const page = this.constructor.PAGE;
+        const query = (extra) => new URLSearchParams({ jql: this.jql, fields: '*all', maxResults: String(page), ...extra }).toString();
+        if (this.connection.edition === 'server') {
+            for (let startAt = 0; ; startAt += page) {
+                const { json } = await this.request(this.url(`/rest/api/2/search?${query({ startAt: String(startAt) })}`));
+                const got = json.issues ?? [];
+                const more = got.length > 0 && startAt + got.length < (json.total ?? 0);
+                if (this.keep(issues, got)) { this.truncated ||= more; break; }
+                if (!more) break;
+            }
+        } else {
+            for (let token = null; ;) {
+                const { json } = await this.request(this.url(`/rest/api/3/search/jql?${query(token ? { nextPageToken: token } : {})}`));
+                const got = json.issues ?? [];
+                token = json.isLast ? null : json.nextPageToken ?? null;
+                if (this.keep(issues, got)) { this.truncated ||= !!token; break; }
+                if (!token || !got.length) break;
+            }
+        }
+        return { issues };
+    }
+}

package/src/charting/requirements/TrackerApi.js

@@ -0,0 +1,142 @@
+import { TrackerExport, TRACKERS } from './TrackerExport.js';
+
+/** Text as base64, whatever its characters (btoa takes only Latin-1). */
+function base64(text) {
+    const bytes = new TextEncoder().encode(String(text));
+    let binary = '';
+    for (const b of bytes) binary += String.fromCharCode(b);
+    return btoa(binary);
+}
+
+/**
+ * TrackerApi — a tracker read through its API rather than from an export: the
+ * issues a connection names, page by page, as the JSON `TrackerExport` reads
+ * (so an API's answer and a file saved from it make the same model). A
+ * subclass per tracker (`JiraApi`, `AzureDevOpsApi`, `GitLabApi`) says where
+ * its issues are, how it pages and how it is signed in to; what a connection
+ * asks for is `fields`, which a host builds its form from.
+ *
+ * `fetch` is given (a server's, or a test's): a tracker's token belongs where
+ * the request is made, which is seldom a browser. Nothing here keeps or logs
+ * the token; an error says what the tracker answered, not what was sent.
+ */
+export class TrackerApi {
+    /** The tracker's key in TRACKERS ('jira'). */
+    static tracker = null;
+
+    /** Most issues read from one connection: a connection naming a whole site is stopped there (`truncated`). */
+    static MAX_ISSUES = 5000;
+
+    /**
+     * What a connection asks for, in order: `{key, label, type?, choices?,
+     * required?, secret?, placeholder?, hint?}` — `secret` written, never
+     * shown back. The tracker's own between its address and its token.
+     */
+    static get fields() {
+        return [
+            { key: 'name', label: 'Name', required: true, placeholder: 'What people pick it by, e.g. "Shop backlog"' },
+            { key: 'baseUrl', label: 'Address', required: true, placeholder: this.baseUrlPlaceholder },
+            ...this.ownFields,
+            { key: 'token', label: 'Token', type: 'password', required: true, secret: true, hint: this.tokenHint },
+        ];
+    }
+
+    /** @protected */
+    static get ownFields() { return []; }
+
+    /** @protected */
+    static baseUrlPlaceholder = 'https://…';
+
+    /** @protected */
+    static tokenHint = 'An access token that may read the issues';
+
+    /**
+     * @param {Object} connection - Its `fields`' values (and `columns`, a TrackerExport's own columns)
+     * @param {Object} [options]
+     * @param {Function} [options.fetch] - The fetch to read with (default: the global one)
+     * @param {number} [options.maxIssues] - Most issues read (default MAX_ISSUES)
+     */
+    constructor(connection, { fetch = globalThis.fetch, maxIssues = new.target.MAX_ISSUES } = {}) {
+        this.connection = connection ?? {};
+        this.fetch = fetch;
+        this.maxIssues = maxIssues;
+        /** Whether the last read stopped at maxIssues. */
+        this.truncated = false;
+    }
+
+    get tracker() { return this.constructor.tracker; }
+
+    /** What the tracker is called ('Jira'). */
+    get label() { return TrackerExport.label(this.tracker); }
+
+    /** What is wrong with the connection, before anything is asked of the tracker: messages, none when it will do. */
+    problems() {
+        const c = this.connection;
+        const out = this.constructor.fields.filter(f => f.required && !String(c[f.key] ?? '').trim()).map(f => `${f.label} is needed.`);
+        if (c.baseUrl && !/^https?:\/\/[^\s/]+/i.test(String(c.baseUrl).trim())) out.push(`Address must start http:// or https:// ("${c.baseUrl}").`);
+        return out;
+    }
+
+    /** The issues, as the tracker's API gives them (the JSON TrackerExport reads). */
+    async read() {
+        const problems = this.problems();
+        if (problems.length) throw new Error(`${this.label} connection "${this.connection.name ?? ''}": ${problems.join(' ')}`);
+        this.truncated = false;
+        return this._read();
+    }
+
+    /** The issues as a requirements model's spec, named as the connection is. */
+    async model() {
+        const json = await this.read();
+        const { tracker, ...spec } = new TrackerExport({ tracker: this.tracker, columns: this.connection.columns ?? {} }).read(json);
+        return { name: this.connection.name || `${this.label} issues`, ...spec };
+    }
+
+    /** @protected @abstract */
+    async _read() {
+        throw new Error(`${this.constructor.name} does not say how to read ${this.label}`);
+    }
+
+    /** The headers that sign in. @protected @abstract */
+    headers() {
+        return {};
+    }
+
+    /** A path on the tracker's address. @protected */
+    url(path) {
+        return `${String(this.connection.baseUrl).trim().replace(/\/+$/, '')}${path}`;
+    }
+
+    /**
+     * A request to the tracker, its answer's JSON and headers; an answer
+     * other than OK an error saying what the tracker said. @protected
+     */
+    async request(url, { method = 'GET', body } = {}) {
+        if (typeof this.fetch !== 'function') throw new Error('No fetch to read the tracker with');
+        const res = await this.fetch(url, {
+            method,
+            headers: { Accept: 'application/json', ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}), ...this.headers() },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`${this.label} answered ${res.status}${res.statusText ? ` ${res.statusText}` : ''}${text ? `: ${text.slice(0, 300)}` : ''}`);
+        }
+        return { json: await res.json(), headers: res.headers };
+    }
+
+    /** Issues kept up to maxIssues; true once it is reached. @protected */
+    keep(into, more) {
+        for (const issue of more) {
+            if (into.length >= this.maxIssues) { this.truncated = true; return true; }
+            into.push(issue);
+        }
+        return into.length >= this.maxIssues;
+    }
+
+    /** @protected */
+    static base64 = base64;
+
+    /** @protected — the tracker's issue types not read (TRACKERS: its sub-tasks). */
+    get skipTypes() { return TRACKERS[this.tracker]?.skipTypes ?? []; }
+}

package/src/charting/requirements/TrackerExport.js

@@ -167,15 +167,16 @@ export class TrackerExport {
         return found?.[0] ?? null;
     }
 
-    /** @private */
+    /** @private — an API's JSON, given as text or already parsed. */
     static _json(text) {
+        if (text && typeof text === 'object') return text;
         const s = String(text ?? '').trim();
         if (!s.startsWith('{') && !s.startsWith('[')) return null;
         try { return JSON.parse(s); } catch { return null; }
     }
 
     /**
-     * The export as a requirements model's spec.
+     * The export (its text; an API's JSON as text or parsed — TrackerApi) as a requirements model's spec.
      * @returns {{epics: Array, releases: Array, stories: Array, tracker: string|null}}
      */
     read(text) {

package/src/charting/requirements/index.js

@@ -5,3 +5,8 @@ export { RequirementsFileFormat } from './RequirementsFileFormat.js';
 export { TrackerExportFileFormat, StoryboardFileFormat } from './RequirementsImportFormats.js';
 export { TrackerExport, TRACKERS, criteriaFrom, narrativeFrom, withoutNarrative } from './TrackerExport.js';
 export { Storyboard } from './Storyboard.js';
+export { TrackerApi } from './TrackerApi.js';
+export { JiraApi } from './JiraApi.js';
+export { AzureDevOpsApi } from './AzureDevOpsApi.js';
+export { GitLabApi } from './GitLabApi.js';
+export { TRACKER_APIS, trackerApi, trackerConnectionFields } from './trackerApis.js';

package/src/charting/requirements/trackerApis.js

@@ -0,0 +1,21 @@
+import { JiraApi } from './JiraApi.js';
+import { AzureDevOpsApi } from './AzureDevOpsApi.js';
+import { GitLabApi } from './GitLabApi.js';
+
+/** Each tracker's API, by its key in TRACKERS. */
+export const TRACKER_APIS = Object.freeze({ jira: JiraApi, azure: AzureDevOpsApi, gitlab: GitLabApi });
+
+/**
+ * The API reader for a connection (`connection.tracker`: 'jira', 'azure',
+ * 'gitlab'); `options` as TrackerApi takes them.
+ */
+export function trackerApi(connection, options) {
+    const Api = TRACKER_APIS[connection?.tracker];
+    if (!Api) throw new Error(`No API reader for tracker "${connection?.tracker ?? ''}" (${Object.keys(TRACKER_APIS).join(', ')})`);
+    return new Api(connection, options);
+}
+
+/** What each tracker's connection asks for: `[{tracker, label, fields}]`, for a host's form. */
+export function trackerConnectionFields() {
+    return Object.entries(TRACKER_APIS).map(([tracker, Api]) => ({ tracker, label: new Api({}).label, fields: Api.fields }));
+}