flexdesk 0.17.3 → 0.17.5

package/docs/concepts/state-guard.md

@@ -0,0 +1,58 @@
+# State guard
+
+> **Package:** `@flexdesk/core` · [All docs](../README.md)
+
+## The state guard: who wrote that attribute (0.17.0)
+
+`StateGuardService` blocks (`strict`) or reports (`warn`) `data-*` writes that
+are on no allow-list. A module override lets one module write a key nobody
+else may:
+
+```js
+import { StateGuardService, DEFAULT_STATE_GUARD_CONFIG } from '@flexdesk/core';
+
+const guard = new StateGuardService({ eventBus, config: { ...DEFAULT_STATE_GUARD_CONFIG, mode: 'strict' } });
+guard.allow('src/app/my_widget.js', ['data-foo']);   // a literal substring of the module, or a RegExp
+```
+
+A write is attributed to the frame that made it: the URL or path of the file
+that called `setAttribute`, `removeAttribute` or `dataset`, without line and
+column, whatever your directory layout. A FlexDesk widget's write is the
+widget's, not that of the app module that called the widget. To attribute
+writes further up the stack instead, pass `moduleFramePattern`: the first
+frame from the writer up whose location matches names the module, by the
+pattern's first capture group if it has one.
+
+```js
+config: { ...DEFAULT_STATE_GUARD_CONFIG, moduleFramePattern: /(src\/app\/[^/]+\.js)/ }
+// a write made inside @flexdesk/widgets on behalf of src/app/my_widget.js
+// is now attributed to 'src/app/my_widget.js'
+```
+
+The defaults are `mode: 'warn'`, no module overrides and no frame pattern.
+Before 0.17.0 the module was only found under a `js_new/` path, the defaults
+carried one application's override, and the mode read one application's debug
+global; choose strict mode in your own code.
+
+### The defaults cover FlexDesk's own keys (0.17.0)
+
+`DEFAULT_STATE_GUARD_CONFIG` includes every data key FlexDesk's own widgets
+write, so the shell, dialogs, forms, tooltips, tiles and flow editors run under
+`mode: 'strict'` with no violation. The list also carries some keys that
+FlexDesk itself does not write. Add your application's keys on top:
+
+```js
+const guard = new StateGuardService({ eventBus, logger, config: {
+    ...DEFAULT_STATE_GUARD_CONFIG,
+    allowedDatasetKeys: [...DEFAULT_STATE_GUARD_CONFIG.allowedDatasetKeys, 'order-id'],
+} });
+```
+
+An allow-list key may be spelled either way: `orderId` and `order-id` are the
+same key, in the allow-list and in module overrides
+(`allow(pattern, attributes, { datasetKeys })` and `config.moduleOverrides`)
+alike. camelCase maps to kebab-case as the DOM does for ordinary keys: each
+capital letter becomes `-` plus its lower-case form. So `rowID` is `row-i-d`
+(what `dataset.rowID` writes), not `rowid`; to allow `data-id`, list `id`.
+Before 0.17.0 a camelCase entry never matched, and some entries named keys no
+element carries.

package/docs/concepts/styling.md

@@ -0,0 +1,47 @@
+# Theming and CSS
+
+> **Stylesheets:** `flexdesk/css/tokens`, `flexdesk/css/reset`, `flexdesk/css` · [All docs](../README.md)
+
+## Styling
+
+Three stylesheets, and that is the whole CSS contract:
+
+| | Specifier | Resolves to | |
+|---|---|---|---|
+| `dist/tokens.css` | `flexdesk/css/tokens` | `css/tokens.css` | Every rule reads `var(--…)` from here. Swap this one file and the shell restyles. |
+| `dist/reset.css` | `flexdesk/css/reset` | `dist/reset.css` | The reset. |
+| `dist/flexdesk.css` | `flexdesk/css` | `dist/flexdesk.css` | The library. Every class is `twm-` prefixed (the original working name; the prefix is stable and not worth a breaking rename). |
+
+A bundler, an import-map generator or `require.resolve` reaches each one by its
+specifier, through the package's `exports` map, which closes every other path
+into the package. The map sends `flexdesk/css/tokens` to the source
+`css/tokens.css`, not `dist/tokens.css`. The two are identical in a release,
+since `dist/` is rebuilt in the release commit, but can differ on a working
+checkout. `flexdesk/css/reset` is missing from 0.16.1 and earlier,
+where it fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`.
+
+`createDetailHeader` follows the prefix too: a badge is a `.twm-detail-header__badge`
+pill (a badge's `className` is added beside it, to recolour it), and an action is a
+`.twm-btn` — `variant: 'primary'` adds `.twm-btn--primary`, `'danger'` adds
+`.twm-btn--danger` — that also carries `.twm-detail-header__btn` and
+`.twm-detail-header__btn--<variant>`. The unprefixed `detail-header__badge` and
+`detail-header__btn--<variant>` it emitted before, which no FlexDesk rule styled, are
+gone.
+
+`@flexdesk/editor`'s components keep the class names they were extracted with, and
+`flexdesk.css` styles them: `SplitPaneContainer` (`.split-pane-container`,
+`.split-pane`, a 4px `.split-pane-divider` with a 10px hit target),
+`EditorPane` (`.editor-pane`, `.editor-pane__body`, `.notebook-editor-container`)
+and `NotebookSearchBar` (`.nb-search-bar*`). `setPanes()` adds `.split-pane` to the
+elements you hand it and leaves their own classes alone (it used to replace them,
+which stripped `.editor-pane` off an `EditorPane`).
+
+One exception to the prefix: `HelpModal` (`@flexdesk/widgets`) keeps its older
+`help-` classes (`help-modal-overlay`, `help-modal`, `help-index`, …), and
+`flexdesk.css` styles them — a centred dialog on a dimmed overlay, drawn over
+managed windows. `.help-article` holds your provider's rendered HTML and styles
+its plain elements (headings, code, tables, lists).
+
+Icons are rendered by applying the `material-symbols-outlined` class. FlexDesk does
+not ship the font — supply it from Google Fonts or self-host. Without it, icons fall
+back to their text names and nothing breaks.

package/docs/quickstart.md

@@ -0,0 +1,179 @@
+# Quickstart
+
+From an empty folder to a shell with a table in it. You need a text editor and a static file server. There is no bundler, no framework and no build step.
+
+## Install
+
+```bash
+npm install flexdesk
+```
+
+The package ships a prebuilt `dist/`. Copy it into your site (the examples below call the copy `vendor/flexdesk/`) and load it through an import map:
+
+```bash
+mkdir -p vendor && cp -r node_modules/flexdesk/dist vendor/flexdesk
+```
+
+Under a bundler you need none of that. Import the entries as `flexdesk/core`, `flexdesk/host`, `flexdesk/wm`, `flexdesk/widgets` (and `flexdesk/charts`, `flexdesk/tiles`, `flexdesk/editor`, `flexdesk/canvas`, `flexdesk/flow`), and the stylesheets as `flexdesk/css/tokens`, `flexdesk/css/reset` and `flexdesk/css`. The rest of these docs write the entries as `@flexdesk/wm` and so on, which is the name the import map below gives them.
+
+## The page
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <title>My first shell</title>
+    <script type="importmap">
+    { "imports": {
+        "@flexdesk/core":    "./vendor/flexdesk/core.js",
+        "@flexdesk/host":    "./vendor/flexdesk/host.js",
+        "@flexdesk/wm":      "./vendor/flexdesk/wm.js",
+        "@flexdesk/widgets": "./vendor/flexdesk/widgets.js"
+    } }
+    </script>
+
+    <!-- Optional: the icon font. Without it, icons show their text names. -->
+    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined" />
+
+    <!-- The whole CSS contract, in this order. -->
+    <link href="./vendor/flexdesk/tokens.css"   rel="stylesheet" />
+    <link href="./vendor/flexdesk/reset.css"    rel="stylesheet" />
+    <link href="./vendor/flexdesk/flexdesk.css" rel="stylesheet" />
+
+    <style>
+        html, body { height: 100%; margin: 0; }
+        body {
+            background: var(--surface-0);
+            color: var(--text-primary);
+            font-family: var(--font-family-sans);
+            display: flex; flex-direction: column;
+        }
+        #nav { flex: 0 0 auto; }
+        #app { flex: 1 1 0; min-height: 0; position: relative; }   /* the shell fills this */
+    </style>
+</head>
+<body class="twm-body">
+    <div id="nav"></div>
+    <div id="app"></div>
+    <script type="module" src="./main.js"></script>
+</body>
+</html>
+```
+
+The three stylesheets are the whole CSS contract. `tokens.css` defines every colour, space and font the rules read, `reset.css` is the reset, and `flexdesk.css` is the library. It reads the tokens but does not define them, so without `tokens.css` its colours, spacing and fonts are undefined. See [Theming and CSS](concepts/styling.md#styling).
+
+FlexDesk does not ship the icon font (Material Symbols Outlined). Load it from Google Fonts or self-host it. Nothing else breaks without it.
+
+## Hello, shell
+
+```js
+import { createShell, createTaxonomy, createEntityCatalog } from '@flexdesk/wm';
+import { createHost } from '@flexdesk/host';
+import { DataTable } from '@flexdesk/widgets';
+
+const store = new Map();
+
+const shell = await createShell({
+    root: document.getElementById('app'),
+
+    // YOUR ontology. FlexDesk has none.
+    taxonomy: createTaxonomy({
+        root: 'cosmos',
+        kinds: {
+            cosmos: { label: 'Cosmos', icon: 'public', isTopNav: true, sources: ['planet'] },
+            planet: { label: 'Planet', icon: 'circle' },
+            moon: {
+                label: 'Moon',
+                // "jupiter/europa" — your naming convention, not the library's.
+                ancestors: ({ id }) => {
+                    const i = String(id).indexOf('/');
+                    return i > 0 ? [{ kind: 'planet', id: String(id).slice(0, i) }] : [];
+                },
+            },
+        },
+    }),
+
+    entities: createEntityCatalog({ sources: [/* what the palette searches */] }),
+    content:  { planet: (hostEl, props) => { /* render a tile */ } },
+
+    // Where persistence goes. An in-memory Map is a perfectly good host.
+    host: createHost({
+        state: {
+            read:  async (k) => store.get(k) ?? null,
+            write: async (k, v) => (store.set(k, v), true),
+        },
+    }),
+
+    // Chrome is ELEMENTS, not selectors. The library never guesses at your markup.
+    chrome: { topNav: document.getElementById('nav') },
+});
+```
+
+A working version of exactly this — planets and moons, a mock host, no backend —
+lives in `demo/`.
+
+Save that as `main.js`. What each part is:
+
+- **`taxonomy`** is your ontology: the kinds of thing your application has and how they nest. FlexDesk has none of its own.
+- **`entities`** is what the command palette (Ctrl+K) searches.
+- **`content`** is one factory per kind. It renders that kind into a tile.
+- **`host`** is where persistence goes. An in-memory `Map` is a perfectly good host; [the host port](concepts/host-port.md#the-host-port) covers the real ones.
+- **`chrome`** is the elements the shell paints into, not selectors. The library never guesses at your markup.
+
+## Put a table in a tile
+
+Give the root kind a content factory that mounts a [DataTable](components/data-table.md). `DataTable` is in `@flexdesk/widgets`, which the first snippet already imports.
+
+```js
+const PLANETS = [
+    ['Mercury', '0', '0.39'],
+    ['Venus',   '0', '0.72'],
+    ['Earth',   '1', '1.00'],
+    ['Mars',    '2', '1.52'],
+];
+
+const planetsTable = (hostEl) => {
+    // A tile body is a flex column. Give the table a box that fills it, in normal flow:
+    // absolute positioning would let the table escape the tile.
+    const box = document.createElement('div');
+    box.style.cssText = 'height:100%; display:flex; flex-direction:column; min-height:0;';
+    hostEl.appendChild(box);
+    DataTable.mount(box, {
+        headers: ['Planet', 'Moons', 'Distance (AU)'],
+        rows: PLANETS,
+        sortable: true,
+    });
+};
+
+// …and in createShell({ … }), in place of the planet factory:
+content: {
+    cosmos: planetsTable,
+    // The three panels ask for content by these names. Without a factory they show a placeholder.
+    'panel:left':   (hostEl) => { hostEl.textContent = 'Left panel'; },
+    'panel:right':  (hostEl) => { hostEl.textContent = 'Right panel'; },
+    'panel:bottom': (hostEl) => { hostEl.textContent = 'Bottom panel'; },
+},
+```
+
+`cosmos` is the root kind and a top-nav kind, so the shell opens it first. Click a header to sort. The placeholder a panel shows when nothing is registered for it reads "no factory registered yet": the registry working, though it looks like a bug.
+
+## See the full demo
+
+`demo/` in the repository is a complete version of this page: planets and moons, an in-memory host, panels, desktops and the command palette, with no backend. It loads `dist/`, and ES modules do not load from `file://`, so serve the repository root with any static file server and open `/demo/`:
+
+```bash
+git clone https://github.com/nor-os/FlexDesk.git
+cd FlexDesk
+python3 -m http.server 8080      # or any static server
+# then open http://localhost:8080/demo/
+```
+
+The other pages in `demo/` are one-component pages: `datatable_070.html`, `records.html`, `flow_canvas.html`, `flow_outline.html`, `flow_lanes.html`, `flow_kit.html` and `flow_modeler.html`.
+
+## Where next
+
+- **A component.** Each has a page: [Shell and navigation](components/shell.md), [DataTable](components/data-table.md), [Forms and dialogs](components/forms-and-dialogs.md), and the rest in the [component index](README.md#components).
+- **How the pieces fit.** [Packages and entry points](concepts/packages-and-entry-points.md), the [host port](concepts/host-port.md), [domain neutrality](concepts/domain-neutrality.md) and [theming](concepts/styling.md).
+- **Doing it well.** [Best practices](best-practices.md).
+- **What changed.** The [changelog](../CHANGELOG.md).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "flexdesk",
-    "version": "0.17.3",
+    "version": "0.17.5",
     "description": "A tiling window manager and widget set for desktop-class web applications. Zero runtime dependencies.",
     "license": "MIT",
     "repository": {
@@ -28,6 +28,7 @@
         "canvas.js",
         "flow.js",
         "css",
+        "docs",
         "README.md",
         "CHANGELOG.md",
         "LICENSE",

package/src/charts/data_series_plot_window.js

@@ -107,7 +107,8 @@ class DataSeriesPlotWindow {
             this._config = { ...saved };
             this._config.yColumns = (saved.yColumns || []).filter(c => this._numericColumns.has(c.header));
         } else {
-            this._config = DataSeriesPlotWindow.createDefaultConfig(this.headers, this._numericColumns);
+            this._config = DataSeriesPlotWindow.createDefaultConfig(
+                this.headers, this._numericColumns, this.classifyHeader);
         }
 
         this.#createWindow();
@@ -694,13 +695,26 @@ class DataSeriesPlotWindow {
 
     // ── Default config factory ───────────────────────────────────────────
 
-    static createDefaultConfig(headers, numericColumns) {
+    /**
+     * The config a series with no saved one opens with: the first numeric
+     * column `classifyHeader` calls `'time'` is X (else the first numeric
+     * column), and up to MAX_AUTO_COLUMNS other numeric columns are Y.
+     *
+     * Static, so it has no window: the header classifier is a parameter. A
+     * window passes its own (`options.classifyHeader`); a caller that passes
+     * none gets the default, which knows `t`/`time`/`step`/`period`.
+     *
+     * @param {string[]} headers
+     * @param {Set<string>} [numericColumns] - absent => every column is numeric
+     * @param {(header: string) => string} [classifyHeader=defaultClassifyHeader]
+     */
+    static createDefaultConfig(headers, numericColumns, classifyHeader = defaultClassifyHeader) {
         const isNumeric = numericColumns instanceof Set ? (h) => numericColumns.has(h) : () => true;
 
         // Find best X column (time-like, must be numeric)
         let xColumn = '';
         for (const h of headers) {
-            if (isNumeric(h) && this.classifyHeader(h) === 'time') {
+            if (isNumeric(h) && classifyHeader(h) === 'time') {
                 xColumn = h;
                 break;
             }

package/src/ui/components/slide_out_panel.js

@@ -58,7 +58,7 @@ export class SlideOutPanel extends ComponentBase {
         header.className = 'twm-slide-out-panel__header';
 
         this.#headerIcon = document.createElement('span');
-        this.#headerIcon.className = 'material-symbols-outlined';
+        this.#headerIcon.className = 'twm-slide-out-panel__icon material-symbols-outlined';
 
         this.#headerTitle = document.createElement('span');
         this.#headerTitle.className = 'twm-slide-out-panel__title';
@@ -206,13 +206,24 @@ export class SlideOutPanel extends ComponentBase {
      *  engine that predates it), and the width subtracted is the panel's
      *  laid-out one, which `min-width` may hold above the requested
      *  width. Rounding happens in screen pixels, so at 100% the output is
-     *  exactly what it always was. */
+     *  exactly what it always was.
+     *
+     *  NEVER WIDER THAN THE HOST (BUG-0035). The right edge is pinned, so a
+     *  panel wider than its host (700px by default, `min-width: 400px`)
+     *  reached past the host's left edge across the neighbouring pane. The
+     *  host's width, in the panel's CSS pixels, goes on the panel as
+     *  `--twm-slide-out-host-w`, which the stylesheet uses as `max-width`
+     *  and as the ceiling of the 400px `min-width`; it is set BEFORE the
+     *  width is read so the read sees the capped layout, and the width is
+     *  capped here too for an engine that lays nothing out. */
     #trackGeometry = () => {
         if (!this.#open || !this.#panel || !this.#container) return;
         const r = this.#container.getBoundingClientRect();
         const zoom = this.#panel.currentCSSZoom || 1;
-        const width = this.#panel.offsetWidth || this.#width;
+        const hostWidth = r.width / zoom;
         const s = this.#panel.style;
+        s.setProperty('--twm-slide-out-host-w', `${hostWidth}px`);
+        const width = Math.min(this.#panel.offsetWidth || this.#width, hostWidth);
         s.position = 'fixed';
         s.top      = `${Math.round(r.top) / zoom}px`;
         s.left     = `${Math.round(r.right - width * zoom) / zoom}px`;

package/src/ui/utils/auto_scrollbars.js

@@ -58,12 +58,15 @@ export function thumbGeometry(scrollSize, clientSize, scrollPos, trackLen) {
  *
  * @param {Element} el
  * @param {Element[][]} stacks  what `elementsFromPoint` gave at each point,
- *   topmost first. The overlay layer's own bars are skipped.
+ *   topmost first. The overlay layer's own bars are skipped, and so are the
+ *   window's `.twm-resize-handle` edge strips (BUG-0036): they lie over every
+ *   pane flush against a window edge and are chrome, not cover.
  * @returns {boolean}
  */
 export function barCovered(el, stacks) {
+    const passThrough = (h) => h.closest?.('.twm-autoscroll-layer') || h.closest?.('.twm-resize-handle');
     return stacks.some((stack) => {
-        const top = (stack || []).find((h) => !h.closest?.('.twm-autoscroll-layer'));
+        const top = (stack || []).find((h) => !passThrough(h));
         return Boolean(top) && top !== el && !el.contains(top);
     });
 }
@@ -277,6 +280,16 @@ export function installAutoScrollbars(root = document.body, { exclude = null } =
         cancelAnimationFrame(raf);
         raf = requestAnimationFrame(() => { for (const el of managed.keys()) place(el); });
     };
+    // An element taken out of the page (a managed window closed) takes its
+    // bars with it at once. They live in the layer, not in the element, so
+    // otherwise they would stay on screen through the hide delay and fade.
+    const sweep = new MutationObserver((mutations) => {
+        if (!managed.size || !mutations.some((m) => m.removedNodes.length)) return;
+        for (const el of [...managed.keys()]) {
+            if (!el.isConnected) { drop(el); hoverChain.delete(el); }
+        }
+    });
+    sweep.observe(root, { childList: true, subtree: true });
 
     doc.addEventListener('mouseover', onOver, true);
     doc.addEventListener('mouseout', onLeaveWindow, true);
@@ -293,6 +306,7 @@ export function installAutoScrollbars(root = document.body, { exclude = null } =
             doc.removeEventListener('scroll', onScroll, true);
             win.removeEventListener('resize', onResize);
             doc.removeEventListener('focusin', onResize, true);
+            sweep.disconnect();
             for (const el of [...managed.keys()]) drop(el);
             root.classList.remove(ROOT_CLASS);
         },