flexdesk 0.16.1 → 0.17.0

package/src/flow/kit/logic_graph.js

@@ -5,8 +5,17 @@
  *
  * The shape is the consumer server's:
  *
- *     { nodes: [{ id, type, label?, config, position: {x, y} }],
- *       connections: [{ source, target, sourcePort, targetPort }] }
+ *     { nodes: [{ id, type, label?, config, position: {x, y}, collapsed? }],
+ *       connections: [{ source, target, sourcePort, targetPort }],
+ *       groups?: [{ id, label?, tone?, nodes: [id, …] }],
+ *       notes?: [{ id, text, position: {x, y}, size?: {w?, h?} }] }
+ *
+ * `groups` and `notes` (0.17.0) are there only when the graph has some: a
+ * graph without them is the same object, and the same text, it always was. A
+ * group is FLAT and a node is in one group at most — `normalise` keeps a node
+ * in the first group that names it, leaves out ids that are not nodes of the
+ * graph, and drops a group left with no member. `removeNode` takes the node
+ * out of its group, and the group with its last member.
  *
  * **The editors decide nothing a publish depends on.** Whether a graph is a
  * valid flow is the consumer's validator, drawn as findings. What `canConnect`
@@ -16,8 +25,10 @@
  * returned, never thrown into a console.
  *
  * `serialise` is byte-stable: node keys in the order `id, type, label?, config,
- * position`, config keys sorted, nodes and connections in the order they were
- * drawn — so a graph opened and saved with no edit is the identical text.
+ * position, collapsed?` (`collapsed` only when it is `true`, so a graph that
+ * never folded a node is the text it always was), config keys sorted, nodes and connections in the order they were
+ * drawn (and then the groups and the notes, in theirs) — so a graph opened and
+ * saved with no edit is the identical text.
  */
 
 import { createStrings } from './strings.js';
@@ -33,6 +44,7 @@ export const LOGIC_GRAPH_STRINGS = Object.freeze({
     connectNotFlow: (how) => (how
         ? `Only flow ports connect; a data port is read as ${how}.`
         : 'Only flow ports connect; a data port is read, not connected.'),
+    connectKinds: 'A flow port connects to a flow port, and a data port to a data port.',
     connectTwice: 'These two are already connected.',
     connectOneLine: (port) => `The ${port} port takes one connection; `
         + 'use a step that runs several branches.',
@@ -42,16 +54,62 @@ export function emptyGraph() {
     return { nodes: [], connections: [] };
 }
 
+const round = (v) => Math.round(Number(v) || 0);
+
+/** The groups worth keeping: flat, each node in the first group that names it. */
+function groupsOf(list, nodeIds) {
+    const out = [];
+    const ids = new Set();
+    const placed = new Set();
+    for (const gr of Array.isArray(list) ? list : []) {
+        if (!gr || typeof gr !== 'object' || gr.id === undefined || gr.id === null || gr.id === '') continue;
+        const id = String(gr.id);
+        if (ids.has(id)) continue;
+        const nodes = [];
+        for (const raw of Array.isArray(gr.nodes) ? gr.nodes : []) {
+            const n = String(raw);
+            if (!nodeIds.has(n) || placed.has(n)) continue;
+            placed.add(n);
+            nodes.push(n);
+        }
+        if (!nodes.length) continue;
+        ids.add(id);
+        out.push({ id, ...(gr.label ? { label: String(gr.label) } : {}), ...(gr.tone ? { tone: String(gr.tone) } : {}),
+                   nodes });
+    }
+    return out;
+}
+
+/** The notes worth keeping: an id each, their text, where they are and the size they were given. */
+function notesOf(list) {
+    const out = [];
+    const ids = new Set();
+    for (const note of Array.isArray(list) ? list : []) {
+        if (!note || typeof note !== 'object' || note.id === undefined || note.id === null || note.id === '') continue;
+        const id = String(note.id);
+        if (ids.has(id)) continue;
+        ids.add(id);
+        const w = round(note.size?.w);
+        const h = round(note.size?.h);
+        const size = { ...(w > 0 ? { w } : {}), ...(h > 0 ? { h } : {}) };
+        out.push({ id, text: note.text === undefined || note.text === null ? '' : String(note.text),
+                   position: { x: round(note.position?.x), y: round(note.position?.y) },
+                   ...(Object.keys(size).length ? { size } : {}) });
+    }
+    return out;
+}
+
 /** A deep copy with every field the graph carries, and nothing else. */
 export function normalise(graph) {
     const g = graph && typeof graph === 'object' ? graph : emptyGraph();
-    return {
+    const out = {
         nodes: (Array.isArray(g.nodes) ? g.nodes : []).map((n) => ({
             id: String(n.id),
             type: String(n.type),
             ...(n.label ? { label: String(n.label) } : {}),
             config: n.config && typeof n.config === 'object' ? structuredClone(n.config) : {},
             position: { x: Math.round(Number(n.position?.x) || 0), y: Math.round(Number(n.position?.y) || 0) },
+            ...(n.collapsed === true ? { collapsed: true } : {}),
         })),
         connections: (Array.isArray(g.connections) ? g.connections : []).map((c) => ({
             source: String(c.source),
@@ -60,6 +118,11 @@ export function normalise(graph) {
             targetPort: String(c.targetPort || 'in'),
         })),
     };
+    const groups = groupsOf(g.groups, new Set(out.nodes.map((n) => n.id)));
+    if (groups.length) out.groups = groups;
+    const notes = notesOf(g.notes);
+    if (notes.length) out.notes = notes;
+    return out;
 }
 
 function sortedKeys(value) {
@@ -76,11 +139,13 @@ export function serialise(graph) {
     return JSON.stringify({
         nodes: g.nodes.map((n) => ({
             id: n.id, type: n.type, ...(n.label ? { label: n.label } : {}),
-            config: sortedKeys(n.config), position: n.position,
+            config: sortedKeys(n.config), position: n.position, ...(n.collapsed ? { collapsed: true } : {}),
         })),
         connections: g.connections.map((c) => ({
             source: c.source, target: c.target, sourcePort: c.sourcePort, targetPort: c.targetPort,
         })),
+        ...(g.groups ? { groups: g.groups } : {}),
+        ...(g.notes ? { notes: g.notes } : {}),
     });
 }
 
@@ -118,9 +183,15 @@ export function addNode(graph, typeId, position = null, { id = null, label = nul
     return node;
 }
 
+/** Take a step away, with its lines; its group shrinks, and goes with its last member. */
 export function removeNode(graph, nodeId) {
     graph.nodes = graph.nodes.filter((n) => n.id !== nodeId);
     graph.connections = graph.connections.filter((c) => c.source !== nodeId && c.target !== nodeId);
+    if (Array.isArray(graph.groups)) {
+        for (const gr of graph.groups) gr.nodes = gr.nodes.filter((id) => id !== nodeId);
+        graph.groups = graph.groups.filter((gr) => gr.nodes.length);
+        if (!graph.groups.length) delete graph.groups;
+    }
 }
 
 export function moveNode(graph, nodeId, position) {
@@ -143,9 +214,13 @@ function portOf(catalogue, node, name, direction) {
  * `{ok: false, reason}` — the editor shows the reason where the gesture failed.
  * `dataRead` is the consumer's words for how a data port is read instead
  * (`syntax.format(...)`), put in the refusal.
+ *
+ * With `dataPorts: true` a data port connects to a data port (never to a flow
+ * port) and a data output carries any number of lines; whatever else limits a
+ * data connection is the caller's (the canvas editor asks a `ConnectorRouter`).
  */
 export function canConnect(graph, catalogue, { source, sourcePort, target, targetPort },
-                           { strings = null, dataRead = null } = {}) {
+                           { strings = null, dataRead = null, dataPorts = false } = {}) {
     const S = createStrings(LOGIC_GRAPH_STRINGS, strings);
     if (source === target) return { ok: false, reason: S.connectSelf };
     const from = graph.nodes.find((n) => n.id === source);
@@ -155,14 +230,15 @@ export function canConnect(graph, catalogue, { source, sourcePort, target, targe
     const inp = portOf(catalogue, to, targetPort, 'input');
     if (!out) return { ok: false, reason: S.connectNoOutput(sourcePort) };
     if (!inp) return { ok: false, reason: S.connectNoInput(targetPort) };
-    if ((out.port_type || 'FLOW') !== 'FLOW' || (inp.port_type || 'FLOW') !== 'FLOW') {
-        return { ok: false, reason: S.connectNotFlow(dataRead) };
-    }
+    const flowOut = (out.port_type || 'FLOW') === 'FLOW';
+    const flowIn = (inp.port_type || 'FLOW') === 'FLOW';
+    if (!dataPorts && (!flowOut || !flowIn)) return { ok: false, reason: S.connectNotFlow(dataRead) };
+    if (flowOut !== flowIn) return { ok: false, reason: S.connectKinds };
     if (graph.connections.some((c) => c.source === source && c.sourcePort === sourcePort
                                     && c.target === target && c.targetPort === targetPort)) {
         return { ok: false, reason: S.connectTwice };
     }
-    if (!out.multiple && graph.connections.some((c) => c.source === source && c.sourcePort === sourcePort)) {
+    if (flowOut && !out.multiple && graph.connections.some((c) => c.source === source && c.sourcePort === sourcePort)) {
         return { ok: false, reason: S.connectOneLine(out.label || sourcePort) };
     }
     return { ok: true };
@@ -171,13 +247,19 @@ export function canConnect(graph, catalogue, { source, sourcePort, target, targe
 /** Connect when `canConnect` allows it; returns its verdict either way. */
 export function connect(graph, catalogue, edge, options = {}) {
     const verdict = canConnect(graph, catalogue, edge, options);
-    if (verdict.ok) {
-        graph.connections.push({ source: edge.source, target: edge.target,
-                                 sourcePort: edge.sourcePort, targetPort: edge.targetPort });
-    }
+    if (verdict.ok) addConnection(graph, edge);
     return verdict;
 }
 
+/**
+ * Append the line `edge` describes, asking nothing — for a caller whose own
+ * rules already allowed it (the canvas editor's `connections` option). The one
+ * place a connection row is built.
+ */
+export function addConnection(graph, { source, target, sourcePort, targetPort }) {
+    graph.connections.push({ source, target, sourcePort, targetPort });
+}
+
 export function disconnect(graph, edge) {
     graph.connections = graph.connections.filter((c) => !sameEdge(c, edge));
 }

package/src/flow/kit/settings_schema.js

@@ -49,7 +49,8 @@ export const SETTINGS_SCHEMA_TYPES = Object.freeze(['object', 'array', 'string',
 
 /** The `x-ui-` hints the kit reads (36 §3.2); the server ignores every `x-` key. */
 export const UI_HINTS = Object.freeze(['x-ui-widget', 'x-ui-references', 'x-ui-when', 'x-ui-placeholder',
-                                       'x-ui-enum-labels', 'x-ui-multiline', 'x-ui-fold']);
+                                       'x-ui-enum-labels', 'x-ui-enum-descriptions', 'x-ui-multiline',
+                                       'x-ui-fold', 'x-ui-add-label', 'x-ui-formula-references']);
 
 const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 

package/src/flow/kit/strings.js

@@ -60,7 +60,9 @@ export const FLOW_STRINGS = Object.freeze({
     value: 'Value',
     formula: 'Formula',
     textOrValue: 'Text, or insert a value',
-    noColumns: 'There are no columns to choose from yet: connect a step before this one.',
+    noColumns: 'Columns not known yet: type the name.',
+    columnName: 'Column name',
+    columnNames: 'Column name, then Enter',
     noColumnsChosen: 'None chosen',
     fieldFinding: 'Fix this before publishing',
 

package/src/flow/kit/widgets.js

@@ -29,6 +29,7 @@
  */
 
 import { button, el, uid } from './dom.js';
+import { choiceList, selectBox, shownValue, toggleChips } from '../../ui/components/choice_controls.js';
 import { createChipInput } from './chip_input.js';
 import { resolveSyntaxes } from './references.js';
 import { admittedTypes, enumLabel, fieldsFromSchema, primaryType, titleOf, visibleFields, whenKeys }
@@ -37,9 +38,6 @@ import { createStrings, say } from './strings.js';
 
 // ── values that keep their type ──────────────────────────────────────────
 
-/** A stored value as a one-line box shows it: a string as itself, anything else as JSON. */
-export const shownValue = (v) => (v === undefined ? '' : typeof v === 'string' ? v : JSON.stringify(v));
-
 /**
  * The text typed into a box, as a value OF THE TYPE IT WAS:
  *  - an untouched box writes back what was stored, exactly;
@@ -71,34 +69,6 @@ function textBox(value, { type = 'text', placeholder = '', label = '' } = {}) {
     return input;
 }
 
-/** A `<select>` over `options` (`{value, label, disabled?}`), keeping a stored value it lacks. */
-function selectBox(options, value, { empty = null, label = '', notFound = (v) => `${v} (not found)` } = {}) {
-    const box = el('select', 'twm-flow-input twm-flow-input--select');
-    if (label) box.setAttribute('aria-label', label);
-    const values = [];
-    if (empty !== null) {
-        box.appendChild(new Option(empty, ''));
-        values.push(undefined);
-    }
-    options.forEach((opt) => {
-        const o = new Option(opt.label, String(values.length));
-        if (opt.disabled) o.disabled = true;
-        box.appendChild(o);
-        values.push(opt.value);
-    });
-    const at = values.findIndex((v, i) => i >= (empty !== null ? 1 : 0) && v === value);
-    if (value !== undefined && value !== null && value !== '' && at < 0) {
-        // A stored value the list no longer offers is KEPT as its own option:
-        // it must not silently become the first entry on the next save.
-        box.appendChild(new Option(notFound(shownValue(value)), String(values.length)));
-        values.push(value);
-        box.value = String(values.length - 1);
-    } else {
-        box.value = at >= 0 ? String(at) : (empty !== null ? '' : '0');
-    }
-    return { box, valueOf: () => (box.value === '' ? undefined : values[Number(box.value)]) };
-}
-
 /**
  * A textarea as tall as its text — wrapped lines included — up to `maxLines`,
  * then it scrolls. Measured from `scrollHeight` once laid out (a
@@ -345,49 +315,6 @@ function stringListWidget(spec, value, ctx) {
     return { el: rows.el, destroy: rows.destroy };
 }
 
-/** Toggle chips over a fixed list; the stored list follows the list's order,
- *  and a stored entry the list lacks is kept, marked, until it is toggled off. */
-function toggleChips({ options, value, label, readOnly, onChange, notFound }) {
-    const root = el('div', 'twm-flow-togglechips');
-    root.setAttribute('role', 'group');
-    if (label) root.setAttribute('aria-label', label);
-    const known = options.map((o) => o.value);
-    const chosen = new Set((Array.isArray(value) ? value : []).filter((v) => known.includes(v)));
-    const strays = (Array.isArray(value) ? value : []).filter((v) => !known.includes(v));
-    const emit = () => {
-        const out = [...known.filter((v) => chosen.has(v)), ...strays];
-        onChange(out.length ? out : undefined);
-    };
-    const chipFor = (text, pressed, toggle, stray = false) => {
-        const b = el('button', `twm-flow-togglechip${stray ? ' twm-flow-togglechip--missing' : ''}`, text);
-        b.type = 'button';
-        b.setAttribute('aria-pressed', pressed ? 'true' : 'false');
-        b.disabled = Boolean(readOnly);
-        b.addEventListener('click', () => {
-            const on = toggle();
-            b.setAttribute('aria-pressed', on ? 'true' : 'false');
-            emit();
-        });
-        return b;
-    };
-    for (const o of options) {
-        root.appendChild(chipFor(o.label, chosen.has(o.value), () => {
-            if (chosen.has(o.value)) chosen.delete(o.value); else chosen.add(o.value);
-            return chosen.has(o.value);
-        }));
-    }
-    for (const v of [...strays]) {
-        const b = chipFor(notFound(shownValue(v)), true, () => {
-            const i = strays.indexOf(v);
-            if (i >= 0) { strays.splice(i, 1); return false; }
-            strays.push(v);
-            return true;
-        }, true);
-        root.appendChild(b);
-    }
-    return root;
-}
-
 /** A multi-select from `items.enum`, drawn as chips. */
 function enumChipsWidget(spec, value, ctx) {
     const S = ctx.strings;
@@ -398,7 +325,7 @@ function enumChipsWidget(spec, value, ctx) {
         el: toggleChips({
             options: values.map((v) => ({ value: v, label: words(v) })), value, label: ctx.label,
             readOnly: ctx.readOnly, onChange: (v) => ctx.set(v), notFound: (v) => say(S, 'notFound', v),
-        }),
+        }).el,
     };
 }
 
@@ -408,43 +335,41 @@ function choiceCardsWidget(spec, value, ctx) {
     const values = Array.isArray(spec.enum) ? spec.enum : [];
     const descriptions = spec['x-ui-enum-descriptions'] && typeof spec['x-ui-enum-descriptions'] === 'object'
         ? spec['x-ui-enum-descriptions'] : {};
-    const root = el('div', 'twm-flow-choices');
-    root.setAttribute('role', 'radiogroup');
-    if (ctx.label) root.setAttribute('aria-label', ctx.label);
-    const name = uid('choice');
-    const current = value !== undefined ? value : spec.default;
-    const radios = [];
-    for (const v of values) {
-        const row = el('label', 'twm-flow-choice');
-        const radio = el('input', 'twm-flow-choice__radio');
-        radio.type = 'radio';
-        radio.name = name;
-        radio.checked = v === current;
-        radio.disabled = Boolean(ctx.readOnly);
-        radio.addEventListener('change', () => { if (radio.checked) ctx.set(v); });
-        radios.push(radio);
-        const words = el('span', 'twm-flow-choice__words');
-        words.appendChild(el('span', 'twm-flow-choice__label', enumLabel(spec, v)));
-        if (descriptions[v] !== undefined) words.appendChild(el('span', 'twm-flow-choice__sub', descriptions[v]));
-        row.append(radio, words);
-        root.appendChild(row);
-    }
-    if (current !== undefined && !values.includes(current)) {
-        root.appendChild(el('p', 'twm-flow-field__note', say(ctx.strings, 'notFound', shownValue(current))));
-    }
-    return { el: root, focus: () => (radios.find((r) => r.checked) || radios[0])?.focus({ preventScroll: true }) };
+    const list = choiceList({
+        options: values.map((v) => ({ value: v, label: enumLabel(spec, v), description: descriptions[v] })),
+        value: value !== undefined ? value : spec.default,
+        name: uid('choice'), label: ctx.label, readOnly: ctx.readOnly,
+        onChange: (v) => ctx.set(v), notFound: (v) => say(ctx.strings, 'notFound', v),
+    });
+    return { el: list.el, focus: list.focus };
 }
 
 const columnWords = (c) => (c.type ? `${c.name} · ${c.type}` : String(c.name));
 
+/**
+ * The columns are NOT KNOWN YET (`ctx.columns()` is null: nothing described or
+ * previewed the step's input so far): a column is typed by name, and the field
+ * says why it is not a choice. The name is stored as typed; once the columns
+ * arrive the panel is drawn again and the same setting is a choice among them,
+ * a name they lack kept and marked not found.
+ */
+function columnsNotKnownNote(S) {
+    return el('p', 'twm-flow-field__note', say(S, 'noColumns'));
+}
+
 /** One column of the step's input, by NAME. */
 function upstreamColumnWidget(spec, value, ctx) {
     const S = ctx.strings;
     const columns = ctx.columns?.();
     if (!Array.isArray(columns)) {
-        const note = el('p', 'twm-flow-field__note', say(S, 'noColumns'));
-        if (value !== undefined) note.appendChild(el('span', 'twm-flow-field__kept', ` ${shownValue(value)}`));
-        return { el: note };
+        const root = el('div', 'twm-flow-field__typed');
+        const box = textBox(shownValue(value), { label: ctx.label,
+                                                 placeholder: spec['x-ui-placeholder'] ?? say(S, 'columnName') });
+        box.spellcheck = false;
+        box.readOnly = Boolean(ctx.readOnly);
+        box.addEventListener('input', () => ctx.set(clean(typedValue(box.value, value))));
+        root.append(box, columnsNotKnownNote(S));
+        return { el: root, focus: () => box.focus({ preventScroll: true }) };
     }
     const { box, valueOf } = selectBox(columns.map((c) => ({ value: String(c.name), label: columnWords(c) })),
                                        value, { empty: say(S, 'choose'), label: ctx.label,
@@ -454,23 +379,75 @@ function upstreamColumnWidget(spec, value, ctx) {
     return { el: box };
 }
 
+/**
+ * Names typed into a chip list: Enter (or a comma, or leaving the box) makes
+ * the text a chip, pressing a chip removes it. The list keeps the order the
+ * names were given in, a name given twice once, and a stored entry as it is.
+ */
+function typedChips({ value, label, placeholder, readOnly, onChange, strings }) {
+    const root = el('div', 'twm-flow-togglechips twm-flow-typedchips');
+    root.setAttribute('role', 'group');
+    if (label) root.setAttribute('aria-label', label);
+    const list = Array.isArray(value) ? [...value] : [];
+    const input = textBox('', { label, placeholder });
+    input.classList.add('twm-flow-typedchips__input');
+    input.spellcheck = false;
+    input.readOnly = Boolean(readOnly);
+    const emit = () => onChange(list.length ? [...list] : undefined);
+    const chipFor = (v) => {
+        const text = shownValue(v);
+        const b = el('button', 'twm-flow-togglechip', text);
+        b.type = 'button';
+        b.setAttribute('aria-pressed', 'true');
+        b.setAttribute('aria-label', say(strings, 'removeNamed', text));
+        b.title = say(strings, 'removeNamed', text);
+        b.disabled = Boolean(readOnly);
+        b.addEventListener('click', () => {
+            const i = list.indexOf(v);
+            if (i >= 0) list.splice(i, 1);
+            b.remove();
+            emit();
+            input.focus({ preventScroll: true });
+        });
+        return b;
+    };
+    const take = () => {
+        const name = input.value.replace(/,+$/, '').trim();
+        input.value = '';
+        if (!name || list.includes(name)) return;
+        list.push(name);
+        root.insertBefore(chipFor(name), input);
+        emit();
+    };
+    for (const v of list) root.appendChild(chipFor(v));
+    root.appendChild(input);
+    input.addEventListener('keydown', (ev) => {
+        if (ev.isComposing || (ev.key !== 'Enter' && ev.key !== ',')) return;
+        ev.preventDefault();
+        take();
+    });
+    input.addEventListener('blur', () => { if (input.value.trim()) take(); });
+    return { el: root, input };
+}
+
 /** Several columns of the step's input, by name, as chips in the input's order. */
 function upstreamColumnsWidget(spec, value, ctx) {
     const S = ctx.strings;
     const columns = ctx.columns?.();
     if (!Array.isArray(columns)) {
-        const note = el('p', 'twm-flow-field__note', say(S, 'noColumns'));
-        if (Array.isArray(value) && value.length) {
-            note.appendChild(el('span', 'twm-flow-field__kept', ` ${value.map(shownValue).join(', ')}`));
-        }
-        return { el: note };
+        const root = el('div', 'twm-flow-field__typed');
+        const chips = typedChips({ value, label: ctx.label, readOnly: ctx.readOnly, strings: S,
+                                   placeholder: spec['x-ui-placeholder'] ?? say(S, 'columnNames'),
+                                   onChange: (v) => ctx.set(v) });
+        root.append(chips.el, columnsNotKnownNote(S));
+        return { el: root, focus: () => chips.input.focus({ preventScroll: true }) };
     }
     return {
         el: toggleChips({
             options: columns.map((c) => ({ value: String(c.name), label: String(c.name) })), value,
             label: ctx.label, readOnly: ctx.readOnly, onChange: (v) => ctx.set(v),
             notFound: (v) => say(S, 'notFound', v),
-        }),
+        }).el,
     };
 }