flexdesk 0.4.7 → 0.6.0

package/src/flow/kit/settings_schema.js

@@ -0,0 +1,175 @@
+/**
+ * THE SETTINGS-SCHEMA SUBSET a step type's `config_schema` may use (36 §3.2).
+ *
+ * The subset is the one the consumer's SERVER enforces — the keyword set, the
+ * type names and every refusal sentence are a port of a Python module
+ * (`check_schema` in Tables' workflow engine; the data-flow core's
+ * `settings_schema` ports the same one), and a fixture of schemas with both
+ * verdicts (`tests/fixtures/flow_kit_settings_schema.json`) is read by both
+ * sides so they cannot drift:
+ *
+ *   type (one name or a list), enum, const, required, properties,
+ *   additionalProperties (boolean only), items, minItems/maxItems,
+ *   minimum/maximum, minLength/maxLength, format: "uuid";
+ *   annotations title, description, default, examples; and any `x-` hint.
+ *
+ * `oneOf`, `anyOf`, `$ref` and `pattern` are refused for reasons that hold in a
+ * browser too: a regular expression is read three ways by three engines (`$`
+ * also matches before a final newline in Python and .NET, not in JavaScript),
+ * and a union is exactly the construct a generated form cannot draw honestly.
+ *
+ * THE KIT DRAWS FROM A SCHEMA AND NEVER VALIDATES A VALUE AGAINST ONE: whether
+ * a setting is valid is the server's answer, drawn as a finding.
+ *
+ * ══ SENTENCE FOR SENTENCE ══════════════════════════════════════════════
+ *
+ * `checkSettingsSchema` returns the FIRST refusal the Python raises, in the
+ * Python's words, or `null`. Two quirks are kept on purpose, because "the same
+ * sentence" is the contract and a tidier one here would be a drift there:
+ *
+ *  - four refusals (`properties`, `additionalProperties`, `format`,
+ *    `required`) name the path WITHOUT the `<root>` fallback, so at the root
+ *    they read `": properties must be an object."`;
+ *  - names are quoted the way Python's `repr` quotes them (`'oneOf'`, and
+ *    `"it's"` for a name holding an apostrophe).
+ *
+ * One difference cannot be closed from here: a JavaScript object lists keys
+ * that look like integers ("1", "2") first, where a Python dict keeps the
+ * document's order. Which refusal is FIRST can then differ for a schema with
+ * integer-like property names; the fixture holds none.
+ */
+
+export const SETTINGS_SCHEMA_ANNOTATIONS = Object.freeze(['title', 'description', 'default', 'examples']);
+export const SETTINGS_SCHEMA_KEYWORDS = Object.freeze([
+    'type', 'enum', 'const', 'required', 'properties', 'additionalProperties', 'items',
+    'minItems', 'maxItems', 'minimum', 'maximum', 'minLength', 'maxLength', 'format',
+]);
+export const SETTINGS_SCHEMA_TYPES = Object.freeze(['object', 'array', 'string', 'integer', 'number',
+                                                    'boolean', 'null']);
+
+/** 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']);
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** Python's `repr` of the values a schema refusal quotes. */
+export function pyRepr(value) {
+    if (value === null || value === undefined) return 'None';
+    if (value === true) return 'True';
+    if (value === false) return 'False';
+    if (typeof value === 'number') return String(value);
+    if (typeof value === 'string') {
+        const q = value.includes("'") && !value.includes('"') ? '"' : "'";
+        let out = '';
+        for (const ch of value) {
+            const code = ch.codePointAt(0);
+            if (ch === '\\') out += '\\\\';
+            else if (ch === q) out += `\\${q}`;
+            else if (ch === '\n') out += '\\n';
+            else if (ch === '\r') out += '\\r';
+            else if (ch === '\t') out += '\\t';
+            else if (code < 0x20 || code === 0x7f) out += `\\x${code.toString(16).padStart(2, '0')}`;
+            else out += ch;
+        }
+        return q + out + q;
+    }
+    return JSON.stringify(value);
+}
+
+/**
+ * The first way `schema` leaves the subset, as the server's sentence, or
+ * `null` when it is inside it.
+ */
+export function checkSettingsSchema(schema, path = '') {
+    const where = path || '<root>';
+    if (!isPlainObject(schema)) return `${where}: a schema must be an object.`;
+    for (const [key, value] of Object.entries(schema)) {
+        if (SETTINGS_SCHEMA_ANNOTATIONS.includes(key) || key.startsWith('x-')) continue;
+        if (!SETTINGS_SCHEMA_KEYWORDS.includes(key)) return `${where}: the keyword ${pyRepr(key)} is not supported.`;
+        if (key === 'type') {
+            for (const n of (Array.isArray(value) ? value : [value])) {
+                if (!SETTINGS_SCHEMA_TYPES.includes(n)) return `${where}: unknown type ${pyRepr(n)}.`;
+            }
+        } else if (key === 'properties') {
+            if (!isPlainObject(value)) return `${path}: properties must be an object.`;
+            for (const [name, sub] of Object.entries(value)) {
+                const refused = checkSettingsSchema(sub, path ? `${path}.${name}` : name);
+                if (refused) return refused;
+            }
+        } else if (key === 'items') {
+            const refused = checkSettingsSchema(value, `${path}[]`);
+            if (refused) return refused;
+        } else if (key === 'additionalProperties' && typeof value !== 'boolean') {
+            return `${path}: additionalProperties must be true or false.`;
+        } else if (key === 'format' && value !== 'uuid') {
+            return `${path}: only format 'uuid' is supported.`;
+        } else if (key === 'required' && !(Array.isArray(value) && value.every((v) => typeof v === 'string'))) {
+            return `${path}: required must be a list of names.`;
+        }
+    }
+    return null;
+}
+
+/** The settings a schema declares, in the schema's order: `[{key, spec, required}]`. */
+export function fieldsFromSchema(schema) {
+    const props = isPlainObject(schema?.properties) ? schema.properties : {};
+    const required = new Set(Array.isArray(schema?.required) ? schema.required : []);
+    return Object.entries(props).map(([key, spec]) => ({
+        key, spec: isPlainObject(spec) ? spec : {}, required: required.has(key),
+    }));
+}
+
+/** A setting's label: its `title`, else its key in words (`max_attempts` → "Max attempts"). */
+export function titleOf(key, spec = {}) {
+    if (spec?.title) return String(spec.title);
+    const words = String(key).replace(/_/g, ' ');
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+/** The first JSON-Schema type a spec names (a list's first), or undefined. */
+export function primaryType(spec) {
+    return Array.isArray(spec?.type) ? spec.type[0] : spec?.type;
+}
+
+/** Every type a spec admits, as a list. */
+export function admittedTypes(spec) {
+    return [].concat(spec?.type ?? []);
+}
+
+/**
+ * Is `field` drawn while the step's settings are `value`? Its `x-ui-when`
+ * (`{field, in}`) names a sibling; the sibling's stored value — or, absent,
+ * its schema `default`, which is what the server will apply — must be one of
+ * `in`. A hint that names no sibling, or is malformed, never hides a field: a
+ * setting nobody can reach is worse than one drawn too often.
+ */
+export function fieldVisible(field, value, fields = []) {
+    const when = field?.spec?.['x-ui-when'];
+    if (!isPlainObject(when) || typeof when.field !== 'string' || !Array.isArray(when.in)) return true;
+    const sibling = fields.find((f) => f.key === when.field);
+    const stored = value && typeof value === 'object' ? value[when.field] : undefined;
+    const current = stored !== undefined ? stored : sibling?.spec?.default;
+    return when.in.some((v) => v === current);
+}
+
+/** The fields drawn for `value`, honouring every `x-ui-when`. */
+export function visibleFields(fields, value) {
+    return fields.filter((f) => fieldVisible(f, value, fields));
+}
+
+/** The keys some field's `x-ui-when` reads — a change to one of them repaints the panel. */
+export function whenKeys(fields) {
+    const keys = new Set();
+    for (const f of fields) {
+        const when = f?.spec?.['x-ui-when'];
+        if (isPlainObject(when) && typeof when.field === 'string') keys.add(when.field);
+    }
+    return keys;
+}
+
+/** A spec's `x-ui-enum-labels` word for `v`, or `v` as text. */
+export function enumLabel(spec, v) {
+    const words = spec?.['x-ui-enum-labels'];
+    return isPlainObject(words) && words[v] !== undefined ? String(words[v]) : String(v);
+}

package/src/flow/kit/step_picker.js

@@ -0,0 +1,209 @@
+/**
+ * THE STEP PICKER — what "+" opens (36 §3.5).
+ *
+ *     const picked = await openStepPicker({anchor, entries, categories, where, paste, strings});
+ *     // → {entry} | {paste: true} | null
+ *
+ * Grouped by category, searchable over each entry's label, sub, description
+ * and id (the box has focus on open); ↑ ↓ choose, stepping over a refused row;
+ * Enter adds; Esc closes; *"Paste a copied step · Ctrl+V"* is its footer when
+ * `paste` is set — and Ctrl+V in the EMPTY search box pastes the step (with
+ * text in the box it pastes text, as a search box should).
+ *
+ * An entry with a `refusal` is drawn greyed WITH its sentence under it and
+ * cannot be chosen — never hidden, because "why can I not add it here" is the
+ * question the next screen would otherwise have to answer.
+ *
+ * ENTRIES ARE THE EDITOR'S, NOT THE CATALOGUE'S: an outline offers blocks
+ * ("If … otherwise" is a condition and its two arms) beside plain steps, and
+ * lanes offer sources only after "Add a source". The picker draws what it is
+ * handed.
+ *
+ * It is a FlexDesk popover (`dom.js`): `role="dialog"` holding a `listbox`
+ * whose active option is the search box's `aria-activedescendant`; it returns
+ * focus to its anchor when it closes. The promise carries `close()`.
+ */
+
+import { el, icon, nextOption, openPopover, toneClass, uid } from './dom.js';
+import { createStrings, say } from './strings.js';
+
+const words = (s) => String(s ?? '').toLowerCase();
+
+/**
+ * @param {object} o
+ * @param {HTMLElement} o.anchor
+ * @param {{id: string, label: string, sub?: string, description?: string, icon?: string, tone?: string,
+ *          category?: string, refusal?: string}[]} o.entries
+ * @param {{id: string, label: string, layout?: 'list'|'grid'}[]} [o.categories]  groups, in order
+ * @param {string} [o.where]     "inside For each row, after Check eligibility"
+ * @param {{label?: string}|null} [o.paste]   a copied step can be pasted here
+ * @param {object} [o.strings]
+ * @param {string} [o.title]     the heading; `Add a step` by default
+ */
+export function openStepPicker({ anchor, entries = [], categories = [], where = '', paste = null, strings = null,
+                                 title = null } = {}) {
+    const S = createStrings(strings);
+    let settle;
+    const done = new Promise((resolve) => { settle = resolve; });
+    let result = null;
+
+    const root = el('div', 'twm-flow-picker');
+    const headingId = uid('picker-title');
+    const head = el('div', 'twm-flow-picker__head');
+    const heading = el('span', 'twm-flow-picker__title', title ?? say(S, 'addStep'));
+    heading.id = headingId;
+    head.appendChild(heading);
+    if (where) head.appendChild(el('span', 'twm-flow-picker__where', where));
+    root.appendChild(head);
+
+    const listId = uid('picker-list');
+    const searchRow = el('div', 'twm-flow-picker__search');
+    searchRow.appendChild(icon('search', 'twm-flow-picker__search-icon'));
+    const search = el('input', 'twm-flow-picker__input');
+    search.type = 'search';
+    search.placeholder = say(S, 'searchSteps');
+    search.setAttribute('aria-label', say(S, 'searchSteps'));
+    search.setAttribute('role', 'combobox');
+    search.setAttribute('aria-controls', listId);
+    search.setAttribute('aria-expanded', 'true');
+    search.setAttribute('aria-autocomplete', 'list');
+    search.autocomplete = 'off';
+    searchRow.appendChild(search);
+    root.appendChild(searchRow);
+
+    const list = el('div', 'twm-flow-picker__list');
+    list.id = listId;
+    list.setAttribute('role', 'listbox');
+    list.setAttribute('aria-labelledby', headingId);
+    root.appendChild(list);
+    const empty = el('p', 'twm-flow-picker__empty');
+    empty.hidden = true;
+    root.appendChild(empty);
+
+    // Groups in the categories' order; an entry whose category is not listed
+    // goes in a group of its own after them.
+    const order = (Array.isArray(categories) ? categories : []).map((c) => ({ ...c }));
+    for (const e of entries) {
+        const cat = e.category ?? '';
+        if (!order.some((c) => String(c.id) === String(cat))) order.push({ id: cat, label: cat, layout: 'list' });
+    }
+    const options = [];
+    for (const cat of order) {
+        const mine = entries.filter((e) => String(e.category ?? '') === String(cat.id));
+        if (!mine.length) continue;
+        const group = el('div', 'twm-flow-picker__group');
+        group.setAttribute('role', 'group');
+        const gid = uid('picker-group');
+        const glabel = el('div', 'twm-flow-picker__group-label', cat.label ?? '');
+        glabel.id = gid;
+        group.setAttribute('aria-labelledby', gid);
+        const items = el('div', `twm-flow-picker__items${cat.layout === 'grid' ? ' twm-flow-picker__items--grid' : ''}`);
+        for (const entry of mine) {
+            const opt = el('div', `twm-flow-picker__option${entry.refusal ? ' twm-flow-picker__option--refused' : ''}`);
+            opt.id = uid('picker-option');
+            opt.setAttribute('role', 'option');
+            opt.setAttribute('aria-selected', 'false');
+            if (entry.refusal) opt.setAttribute('aria-disabled', 'true');
+            opt.dataset.entry = String(entry.id);
+            const chip = el('span', `twm-flow-picker__chip ${toneClass('twm-flow-picker__chip', entry.tone)}`);
+            chip.appendChild(icon(entry.icon || ''));
+            chip.setAttribute('aria-hidden', 'true');
+            const text = el('span', 'twm-flow-picker__words');
+            const line = el('span', 'twm-flow-picker__label', entry.label ?? entry.id);
+            if (entry.sub) line.appendChild(el('span', 'twm-flow-picker__sub', ` ${entry.sub}`));
+            text.appendChild(line);
+            if (entry.description && cat.layout !== 'grid') {
+                text.appendChild(el('span', 'twm-flow-picker__description', entry.description));
+            }
+            if (entry.refusal) text.appendChild(el('span', 'twm-flow-picker__refusal', entry.refusal));
+            opt.append(chip, text);
+            // The search box keeps focus: an option is chosen by a click, not focused by a press.
+            opt.addEventListener('mousedown', (ev) => ev.preventDefault());
+            opt.addEventListener('click', () => {
+                if (entry.refusal) return;
+                choose({ entry });
+            });
+            opt.addEventListener('mousemove', () => { if (!entry.refusal) activate(opt); });
+            options.push({ opt, entry, group, haystack: [entry.label, entry.sub, entry.description, entry.id].map(words).join(' ') });
+            items.appendChild(opt);
+        }
+        group.append(glabel, items);
+        list.appendChild(group);
+    }
+
+    const foot = el('div', 'twm-flow-picker__foot');
+    foot.appendChild(el('span', 'twm-flow-picker__keys', say(S, 'pickerKeys')));
+    if (paste) {
+        const p = el('button', 'twm-flow-picker__paste', paste.label ?? say(S, 'pasteStep'));
+        p.type = 'button';
+        p.addEventListener('click', () => choose({ paste: true }));
+        foot.appendChild(p);
+    }
+    root.appendChild(foot);
+
+    let active = null;
+    function activate(opt) {
+        if (active === opt) return;
+        active?.setAttribute('aria-selected', 'false');
+        active?.classList.remove('twm-flow-picker__option--active');
+        active = opt;
+        if (opt) {
+            opt.setAttribute('aria-selected', 'true');
+            opt.classList.add('twm-flow-picker__option--active');
+            search.setAttribute('aria-activedescendant', opt.id);
+            opt.scrollIntoView?.({ block: 'nearest' });
+        } else {
+            search.removeAttribute('aria-activedescendant');
+        }
+    }
+
+    function filter() {
+        const terms = words(search.value).split(/\s+/).filter(Boolean);
+        let shown = 0;
+        for (const o of options) {
+            const hit = terms.every((t) => o.haystack.includes(t));
+            o.opt.hidden = !hit;
+            if (hit) shown += 1;
+        }
+        for (const g of list.querySelectorAll('.twm-flow-picker__group')) {
+            g.hidden = ![...g.querySelectorAll('[role="option"]')].some((o) => !o.hidden);
+        }
+        empty.hidden = shown > 0;
+        empty.textContent = shown > 0 ? '' : say(S, 'nothingMatches', search.value.trim());
+        if (!active || active.hidden) activate(nextOption(list, null, 1));
+    }
+
+    function choose(value) {
+        result = value;
+        handle.close('chosen');
+    }
+
+    search.addEventListener('input', filter);
+    search.addEventListener('keydown', (ev) => {
+        if (ev.isComposing) return;
+        if (ev.key === 'ArrowDown' || ev.key === 'ArrowUp') {
+            ev.preventDefault();
+            activate(nextOption(list, active, ev.key === 'ArrowDown' ? 1 : -1) || active);
+        } else if (ev.key === 'Enter') {
+            ev.preventDefault();
+            const hit = options.find((o) => o.opt === active);
+            if (hit && !hit.entry.refusal) choose({ entry: hit.entry });
+        } else if ((ev.ctrlKey || ev.metaKey) && String(ev.key).toLowerCase() === 'v' && paste && !search.value) {
+            ev.preventDefault();
+            choose({ paste: true });
+        }
+    });
+    root.addEventListener('focusout', (ev) => {
+        const to = ev.relatedTarget;
+        if (to && !root.contains(to) && to !== anchor) handle.close('blur');
+    });
+
+    const handle = openPopover({
+        anchor, content: root, label: title ?? say(S, 'addStep'), className: 'twm-flow-popover--picker',
+        focus: search, onClose: () => settle(result),
+    });
+    if (handle.toggled) settle(null);
+    else filter();
+    done.close = () => handle.close('closed');
+    return done;
+}

package/src/flow/kit/strings.js

@@ -0,0 +1,102 @@
+/**
+ * EVERY WORD A FLOW EDITOR DRAWS (36 §3.13).
+ *
+ * The defaults are English and name no domain: a step, a source, a value. What
+ * a consumer calls its parts — what an error port means, what a loop's foot
+ * says — comes from the consumer's `strings`, or from an editor's block
+ * mapping, and is never guessed here.
+ *
+ * A string is text, or a function of its arguments for the ones that count or
+ * quote something (`stepsInside(3)`). `createStrings(...layers)` lays the
+ * layers over the defaults left to right, so an editor lays its own defaults
+ * over the kit's and the consumer's over both:
+ *
+ *     const strings = createStrings(OUTLINE_STRINGS, options.strings);
+ *
+ * `say(strings, key, ...args)` reads one either way, and falls back to the key
+ * itself — a missing string shows as its name on the screen, which a reader
+ * reports, rather than as an empty label nobody notices.
+ */
+
+const plural = (n, one, many) => (n === 1 ? one : many.replace('{n}', String(n)));
+
+export const FLOW_STRINGS = Object.freeze({
+    // ── the words every editor shares ──────────────────────────────────
+    step: 'step',
+    steps: 'steps',
+    addStep: 'Add a step',
+    removeStep: 'Remove step',
+    duplicate: 'Duplicate',
+    rename: 'Rename',
+    undo: 'Undo',
+    redo: 'Redo',
+    undoTitle: 'Undo (Ctrl+Z)',
+    redoTitle: 'Redo (Ctrl+Y)',
+    foldAll: 'Fold all',
+    unfoldAll: 'Unfold all',
+    stepsInside: (n) => plural(n, '1 step inside', '{n} steps inside'),
+    stepsShow: 'Steps show',
+    thePreview: 'The preview',
+    theLastRun: 'The last run',
+    addSource: 'Add a source — starts a new lane',
+    settings: 'Settings',
+    readOnly: 'Read only',
+
+    // ── the settings panel and its fields ──────────────────────────────
+    required: ' *',
+    requiredLabel: 'required',
+    choose: 'Choose…',
+    defaultOption: (v) => `Default (${v})`,
+    notFound: (v) => `${v} (not found)`,
+    noControl: 'This setting has no control in this editor; its value is kept as it is.',
+    unknownWidget: (name) => `This setting needs the "${name}" control, which this editor does not have. `
+        + 'Its value is kept as it is.',
+    foldDefaults: 'Defaults',
+    add: 'Add',
+    remove: 'Remove',
+    removeNamed: (what) => `Remove ${what}`,
+    addAssignment: 'Add assignment',
+    name: 'Name',
+    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.',
+    noColumnsChosen: 'None chosen',
+    fieldFinding: 'Fix this before publishing',
+
+    // ── reference chips and Insert a value ─────────────────────────────
+    insertValue: 'Insert a value',
+    insertValueGlyph: '{ }',
+    searchValues: 'Search values',
+    wholeValue: (label) => `All of ${label}`,
+    back: 'Back',
+    insertsLine: (ref) => `Inserts ${ref} — shown as a chip, kept as text.`,
+    noValues: 'Nothing to insert here yet.',
+    valueKeys: '↑ ↓ choose · Enter inserts · Esc closes',
+
+    // ── the step picker ────────────────────────────────────────────────
+    searchSteps: 'Search steps',
+    pickerKeys: '↑ ↓ choose · Enter adds · Esc closes',
+    pasteStep: 'Paste a copied step · Ctrl+V',
+    nothingMatches: (q) => `Nothing matches “${q}”.`,
+
+    // ── findings ───────────────────────────────────────────────────────
+    toFix: (n) => plural(n, '1 thing to fix before this can be published.',
+                         '{n} things to fix before this can be published.'),
+    toLookAt: (n) => plural(n, '1 thing to look at.', '{n} things to look at.'),
+    goToIt: 'Go to it',
+    theFlow: 'The flow',
+    findingLine: (where, message) => (where ? `${where} — ${message}` : message),
+});
+
+/** The defaults with each layer laid over them, left to right; frozen. */
+export function createStrings(...layers) {
+    return Object.freeze(Object.assign({}, FLOW_STRINGS, ...layers.filter((l) => l && typeof l === 'object')));
+}
+
+/** One string: text as it is, a function called with `args`, the key when absent. */
+export function say(strings, key, ...args) {
+    const s = strings?.[key] ?? FLOW_STRINGS[key];
+    if (typeof s === 'function') return s(...args);
+    return s === undefined || s === null ? String(key) : String(s);
+}