flexdesk 0.17.13 → 0.17.15

package/src/core/state_guard_config.js

@@ -23,6 +23,22 @@ const DEFAULT_ALLOWED_ATTRIBUTES = Object.freeze([
 const DEFAULT_ALLOWED_ATTRIBUTE_PREFIXES = Object.freeze([
 ]);
 
+// What belongs here: the keys FlexDesk's own widgets write (the last group,
+// which tests/state_guard_defaults.test.mjs keeps complete by scanning src/),
+// the third-party attributes Plotly sets, and generic UI words. What does not:
+// one application's own keys. Whether `data-order-id` is a legitimate write is
+// that application's call, and it says so by adding the key (see
+// docs/concepts/state-guard.md). A key listed here for one embedder's sake that
+// no widget writes is a key every OTHER embedder's strict guard lets through
+// without a word, which is the one thing a strict guard is there to stop.
+//
+// The list does not yet meet that, and it has not been audited key by key:
+// many keys no widget writes are still here, some of them carried over from one
+// application's markup (series-id, dataset-id, func-name and connector-id are
+// examples). Thirteen that name one application's concepts were taken out. The
+// test pins nine of the rest as still allowed, so dropping one is a deliberate
+// edit, and the docs tell an embedder that a strict guard built from the
+// defaults lets a write of such a key through. Do not add another like them.
 const DEFAULT_ALLOWED_DATASET_KEYS = Object.freeze([
     'testid',
     'phase',
@@ -70,11 +86,8 @@ const DEFAULT_ALLOWED_DATASET_KEYS = Object.freeze([
     'node-name',
     'lang',
     'playback-control',
-    // Simulation/scenario state keys
+    // Generic state words
     'status',
-    'scenario-id',
-    'run-id',
-    'run-state',
     'selected',
     'active',
     'disabled',
@@ -90,13 +103,10 @@ const DEFAULT_ALLOWED_DATASET_KEYS = Object.freeze([
     'input-index',
     'output-index',
     'port-index',
-    // Scenario editor keys
+    // Identifier and binding keys
     'source',
     'series-id',
     'dataset-id',
-    'mirror-input-bound',
-    'mirror-change-bound',
-    'mirror-input',
     'bound',
     'field',
     'key',
@@ -105,14 +115,11 @@ const DEFAULT_ALLOWED_DATASET_KEYS = Object.freeze([
     'tab-id',
     'param-id',
     'target-id',
-    'override-type',
     // Tree view component keys
     'item-id',
     'category-id',
-    // Calibration page keys
-    'info-for',
-    'column',
     // Data page keys
+    'column',
     'readonly',
     'id',
     'action',
@@ -131,12 +138,6 @@ const DEFAULT_ALLOWED_DATASET_KEYS = Object.freeze([
     'label',
     'title',
     'description',
-    // DSL generator keys
-    'dsl-state',
-    'dsl-section-registered',
-    'dsl-scrollbars-installed',
-    'dsl-tabs-bound',
-    'dsl-controls-bound',
     // Inline highlighter keys
     'inline-hl',
     // Overlay scrollbar keys (UI-only, not state storage)

package/src/tiling/desktops.js

@@ -27,6 +27,25 @@ const DEFAULT_PANEL_STATE = {
     bottom: true,
 };
 
+/** An object that is not an array: what a saved desktop or map is. */
+function _isRecord(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/** Throw a `TypeError` saying what the saved layout was expected to hold at
+ *  `path` and what it held instead (see the same helper in tile_tree.js, which
+ *  reads the trees these desktops hold). */
+function _expect(ok, path, want, got) {
+    if (ok) return;
+    let shown;
+    if (got === undefined) shown = 'nothing';
+    else {
+        try { shown = JSON.stringify(got); } catch { shown = String(got); }
+        if (shown.length > 40) shown = `${shown.slice(0, 37)}...`;
+    }
+    throw new TypeError(`${path}: expected ${want}, found ${shown}`);
+}
+
 /**
  * `seed()` yields the leaf a fresh (or emptied) desktop starts with. It comes
  * from the taxonomy's root kind — see WindowManager, which supplies it. The
@@ -178,23 +197,65 @@ export class DesktopManager {
         };
     }
 
+    /**
+     * Rebuild the manager from what `serialize()` wrote. `null`/`undefined` is
+     * nothing saved and gives the fresh manager.
+     *
+     * The blob is whatever the host's `state` held under `DESKTOPS_KEY`: a file
+     * anyone can truncate or edit, which is valid JSON of any shape. So it is
+     * read STRICTLY, and a blob that `serialize()` could not have written throws
+     * a `TypeError` naming the path and what was expected there. It builds only
+     * objects of its own and touches nothing its caller holds, which is what lets
+     * `WindowManager.load` treat a throw as "nothing saved" with nothing to undo.
+     *
+     * Strict about SHAPE, not about every value. What the loader, the tree
+     * operations and the renderer index, iterate or branch on has to be what they
+     * need (containers, node and tab kinds, `dir`, `children`, `sizes`,
+     * `activeTabIdx`). What is only drawn or coerced is taken as it is: a desktop's
+     * `id`, `label`, `group` and `fixed`, a panel's flag, a tab's title and props,
+     * `activeIdx`. A layout that fails on one of those would be thrown away for
+     * nothing, and an app can put almost anything in a title.
+     *
+     * And strict is not hostile to an old blob. A key the loader has always given
+     * a default may be absent: a desktop's `id`, `label` and `panels`, the keys
+     * later releases added (`panelShares`, `group`, `fixed`), and a leaf's `tabs`
+     * and `pageTabs`. What `serialize()` has always written and the loader cannot
+     * do without (`desktops`, a desktop's `tree`, a split's `dir`, `children` and
+     * `sizes`) may not.
+     */
     static deserialize(blob, { seed, panelDefaults = null } = {}) {
         const m = new DesktopManager({ seed, panelDefaults });
-        if (!blob || !Array.isArray(blob.desktops) || blob.desktops.length === 0) return m;
-        m.desktops = blob.desktops.map((raw) => ({
-            id: raw.id || `desk-${Math.random().toString(36).slice(2,8)}`,
-            label: raw.label || '?',
-            tree: raw.tree ? TileTree.deserialize(raw.tree) : new TileTree(),
-            windows: [],
-            // A RESTORED desktop's own answer wins over the default: the user
-            // closed that panel, and re-opening it on every reload is the bug
-            // this merge order avoids. The default only fills a key the stored
-            // blob predates.
-            panels: { ...m.panelDefaults, ...(raw.panels || {}) },
-            panelShares: { ...(raw.panelShares || {}) },
-            group: raw.group || null,
-            fixed: !!raw.fixed,
-        }));
+        if (blob == null) return m;
+        _expect(Array.isArray(blob.desktops) && blob.desktops.length > 0,
+            'desktops', 'a non-empty array of desktops', blob.desktops);
+        m.desktops = blob.desktops.map((raw, i) => {
+            const at = `desktops[${i}]`;
+            _expect(_isRecord(raw), at, 'a desktop, an object', raw);
+            // `null` is a desktop with nothing on it (serialize() writes that);
+            // a desktop with no `tree` key at all is not one serialize() writes.
+            _expect(raw.tree === null || (_isRecord(raw.tree) && _isRecord(raw.tree.root)),
+                `${at}.tree`, '{ root }, or null for an empty desktop', raw.tree);
+            _expect(raw.panels == null || _isRecord(raw.panels), `${at}.panels`, 'an object', raw.panels);
+            // The VALUES of `panels` and `panelShares` are not checked: the loader
+            // already coerces a flag (`!!`) and `_validShare` drops a share that
+            // is not one, so the panel opens at its default.
+            _expect(raw.panelShares == null || _isRecord(raw.panelShares),
+                `${at}.panelShares`, 'an object', raw.panelShares);
+            return {
+                id: raw.id || `desk-${Math.random().toString(36).slice(2,8)}`,
+                label: raw.label || '?',
+                tree: raw.tree ? TileTree.deserialize(raw.tree, `${at}.tree`) : new TileTree(),
+                windows: [],
+                // A RESTORED desktop's own answer wins over the default: the user
+                // closed that panel, and re-opening it on every reload is the bug
+                // this merge order avoids. The default only fills a key the stored
+                // blob predates.
+                panels: { ...m.panelDefaults, ...(raw.panels || {}) },
+                panelShares: { ...(raw.panelShares || {}) },
+                group: raw.group || null,
+                fixed: !!raw.fixed,
+            };
+        });
         // Empty tree → seed with the taxonomy root so the desktop is usable.
         for (const d of m.desktops) {
             if (!d.tree.rootId) d.tree.setRoot(makeLeaf(seed()));
@@ -212,7 +273,9 @@ export class DesktopManager {
  * against a host that cannot persist (e.g. the standalone demo).
  */
 
-const DESKTOPS_KEY = 'desktops';
+/** The logical state key the layout is saved under. Exported so a warning about
+ *  a layout that could not be read can name it. */
+export const DESKTOPS_KEY = 'desktops';
 
 export async function loadDesktops(state) {
     if (!state) return null;

package/src/tiling/keymap.js

@@ -287,6 +287,70 @@ function _compose(mods, key) {
     return [...used, k].join('+');
 }
 
+/** What counts as "focus is in an editable field": a key press aimed at one of
+ *  these may be typing. */
+const TEXT_FIELDS = 'input, textarea, select, [contenteditable="true"]';
+
+/**
+ * Whether Alt on this machine is a key that TYPES: Option on a Mac (and on an
+ * iPad with a keyboard). Option changes the character on every Mac layout, so
+ * Option+digit is how a programmer types `{ } [ ] | \ @ #` on a German,
+ * Spanish, Swedish or French keyboard, where Windows and Linux keep Alt for
+ * shortcuts and type those with AltGr. Nothing in the event tells the two
+ * apart (a US Windows Alt+Shift+2 and a German Mac Option+8 both arrive as
+ * `altKey` with a printable `key`), so this is read from the platform, at the
+ * key press so that it is never stale.
+ */
+function _altTypes() {
+    const nav = globalThis.navigator;
+    return /^(mac|iphone|ipad|ipod)/i.test(nav?.userAgentData?.platform || nav?.platform || '');
+}
+
+/**
+ * The digit ('1'..'9') a keydown on the digit row stands for, or null.
+ *
+ * `e.key` is what the layout and the modifiers TYPE, and `Alt+Shift+2` names a
+ * key, not a character. With Shift held a US keyboard's 2 types "@" and a
+ * German one's '"'; Option on a Mac types "™" or "€"; and an AZERTY keyboard's
+ * digit row types "&", "é", '"' and the like with no modifier at all and the
+ * digits only with Shift. Read `e.key` and Alt+Shift+2 is never seen from a
+ * real key press (only from a synthetic event that sets `key: '2'`, which is
+ * how the tests hid it), and on AZERTY it is the unshifted Alt+1..9 that never
+ * fire. `e.code` is the key's position (`Digit2`), which neither Shift nor the
+ * layout changes.
+ *
+ * `e.key` is still read in three cases:
+ *
+ *  - An event with no `Digit` code: a synthetic one that carries only `key`,
+ *    and the numpad (`Numpad2`), whose `key` is the digit itself with NumLock
+ *    on and a navigation key ("ArrowDown") with it off. The numpad is left to
+ *    say which it is, so a numpad used as arrows still moves focus.
+ *  - AltGr. Windows reports it as Ctrl+Alt, and a German, French or Spanish
+ *    layout types `{ [ ] @ # |` on its digit row with it. Taking those events
+ *    for Alt+digit would switch desktops, and swallow the character in a
+ *    field (the Alt chords work in fields), instead of typing it.
+ *  - Option on a Mac, with focus in an editable field. It types the same
+ *    characters AltGr does (German Option+8 is "{"), but arrives as a bare
+ *    `altKey` with no Ctrl and no AltGraph state, so the AltGr test above does
+ *    not see it. Out of a field nothing is typed, so there the key's position
+ *    is read as everywhere else and Option+2 switches desktop; in a field the
+ *    character is typed, as it was before the position was read, and the
+ *    chord waits for focus to leave the field. The test is the platform, not
+ *    "does `key` look like a character": US Windows Alt+Shift+2 types "@" in
+ *    the same way and is the very press this function exists to read.
+ *
+ * This is for the digit row only. Letter keys move with the layout (AZERTY and
+ * QWERTZ swap some, Dvorak most), so `KeyW` is not "the W key" there: a letter
+ * chord stays named by the character its key types.
+ */
+function _digitOfEvent(e) {
+    const typesCharacter = e.getModifierState?.('AltGraph') || (e.ctrlKey && e.altKey)
+        || (_altTypes() && !!e.target?.closest?.(TEXT_FIELDS));
+    const byPosition = typesCharacter ? null : /^Digit([1-9])$/.exec(e.code ?? '');
+    if (byPosition) return byPosition[1];
+    return /^[1-9]$/.test(e.key) ? e.key : null;
+}
+
 /**
  * The chord id a keydown event is read as, in `DEFAULT_CHORDS`' spelling, or
  * null. This is NOT an exact match on the modifier set: it reads an event the
@@ -303,6 +367,9 @@ function _compose(mods, key) {
  *   F1..F12, Shift+Left/Right, Ctrl+Left/Right     exactly those modifiers
  *   with Alt held, Ctrl and Meta are ignored:
  *     Alt(+Shift)+1..9, +H, +V, +Arrow             Shift picks the Alt+Shift+… row
+ *                                                  (1..9 by the key's position,
+ *                                                  not the character it types:
+ *                                                  see `_digitOfEvent`)
  *     Alt+T / N / W / F                            Shift ignored
  *     any other Alt+letter                         Alt+Letter
  *
@@ -330,7 +397,8 @@ function _chordOfEvent(e) {
         return null;
     }
     const sh = shift ? 'Shift+' : '';
-    if (/^[1-9]$/.test(key)) return `Alt+${sh}${key}`;
+    const digit = _digitOfEvent(e);
+    if (digit) return `Alt+${sh}${digit}`;
     if (lower === 'h' || lower === 'v') return `Alt+${sh}${lower.toUpperCase()}`;
     if (lower === 't' || lower === 'n' || lower === 'w' || lower === 'f') return `Alt+${lower.toUpperCase()}`;
     if (ARROWS.includes(key)) return `Alt+${sh}${key}`;
@@ -442,7 +510,7 @@ export function installKeymap({ wm, palette, navSelector = null, bindings = null
         if (!chord) return;
         const b = table.get(chord);
         if (!b || b.disabled) return;
-        if (!b.inField && e.target?.closest?.('input, textarea, select, [contenteditable="true"]')) return;
+        if (!b.inField && e.target?.closest?.(TEXT_FIELDS)) return;
         if (b.run(ctx, e) !== false) e.preventDefault();
     };
 

package/src/tiling/shell.js

@@ -62,7 +62,11 @@ import { openForm } from '../ui/components/modal.js';
  *                                     it through (the palette + tile tab menu
  *                                     hand it to the entity catalog's fetchers).
  * @param {object}     [cfg.eventBus]
- * @param {object}     [cfg.logger]
+ * @param {object}     [cfg.logger]     `{ warn? }`. Told of problems the shell
+ *                                      carries on from: a keymap binding it
+ *                                      does not know, a saved layout it cannot
+ *                                      read (the default one opens instead).
+ *                                      Else `console`.
  * @param {object}     [cfg.tableStore] threaded into ctx for table persistence
  * @param {object}     [cfg.events]     bus-event NAMES the WM listens for
  * @param {object}     [cfg.rootCrumb]  the breadcrumb's leading segment
@@ -237,6 +241,7 @@ export async function createShell({
         host,
         taxonomy,
         events,
+        logger,
         panelDefaults: panels,
         snapPromotion,
         promoteInPlace,
@@ -703,7 +708,9 @@ function _tileContextMenu(wm, leafId, x, y) {
     ];
     if (wm.desktops.desktops.length > 1 && !isPanel) {
         for (const [i, d] of wm.desktops.desktops.entries()) {
-            // C40. Never onto a fixed desktop — `moveFocusedToDesktop` refuses.
+            // C40. Never onto a fixed desktop, nor the one you are on, and (see
+            // `isPanel` above) never a panel: `moveFocusedToDesktop` refuses all
+            // three too, because the keyboard reaches it without this menu.
             if (i === wm.desktops.activeIdx || d.fixed) continue;
             items.push({ label: `Move to desktop ${d.label}`, icon: 'sweep',
                          action: `move:${i}` });

package/src/tiling/tile_breadcrumb.js

@@ -24,14 +24,19 @@
 /** Build a breadcrumb strip element + render initial state. Returns
  *  `{ el, destroy }`. The strip is wired to the WM (clicks open content
  *  in the primary tile) and, when the embedder supplies a `rootCrumb`
- *  with a `subscribe` hook, to whatever keeps the root label fresh. */
+ *  with a `subscribe` hook, to whatever keeps the root label fresh.
+ *  While the path is a single segment (the tile itself) the strip is
+ *  `hidden` and takes no room; `refresh()` shows it once there are more. */
 export function mountTileBreadcrumb(kind, props, ctx) {
     const eventBus  = ctx?.eventBus;
     const taxonomy  = ctx?.taxonomy;
     const rootCrumb = ctx?.rootCrumb || null;
     if (!taxonomy) {
         console.error('[breadcrumb] no taxonomy in ctx — cannot render');
-        return { el: document.createElement('nav'), destroy: () => {} };
+        const el = document.createElement('nav');
+        el.className = 'twm-topbar-breadcrumb twm-tile-breadcrumb';
+        el.hidden = true;   // nothing to draw: no strip, as for a one-segment path
+        return { el, refresh: () => {}, destroy: () => {} };
     }
     const root = document.createElement('nav');
     root.className = 'twm-topbar-breadcrumb twm-tile-breadcrumb';
@@ -82,9 +87,12 @@ export function mountTileBreadcrumb(kind, props, ctx) {
         try { return ctx.trailSegments() || []; }
         catch (err) { console.warn('[breadcrumb] trailSegments threw', err); return []; }
     };
+    // One segment is the tile itself, which its title already names: the strip
+    // is hidden (and its page-shell slot with it) until there is a level above.
     const render = () => {
-        _renderInto(root,
-            _segments(kind, props, taxonomy, rootCrumb, rootLabel, navigate, trailOf()));
+        const segments = _segments(kind, props, taxonomy, rootCrumb, rootLabel, navigate, trailOf());
+        _renderInto(root, segments);
+        root.hidden = segments.length < 2;
     };
     render();