flexdesk 0.17.1 → 0.17.3

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.17.3 (2026-10-22)
+
+A patch release: everything below is additive. Every entry is documented in a
+README section headed "(0.17.3)"; each entry links to it.
+
+### Added and changed
+
+- [One toast, one history entry, one unread](README.md#one-toast-one-history-entry-one-unread-0173): `NotificationCenter.history` holds one entry per toast however it was raised (`show()`, `warn()` / `error()` / `info()` / `success()`, `toast:show`, `notification:show`, `log:entry`), and a toast that leaves marks its own entry `dismissed: true` with the `reason` instead of adding a second one. `nc.subscribe(fn)` calls `fn(entry, center)` once per entry added and answers the unsubscribe. `NotificationHistory` follows the centre through `subscribe()`, so every toast counts once on the bell, also one raised through the API (BUG-0034). It no longer watches the bus for toasts: its `notificationCenter` is a `NotificationCenter` (or anything with `history` and `subscribe`).
+
+### Removed or renamed exports
+
+None. Compared with 0.17.2, across every entry point (`core`, `widgets`, `wm`,
+`host`, `canvas`, `flow`, `charts`, `tiles`, `editor`) and the package
+`exports` map, no export was added, removed or renamed. Not an export but worth
+knowing: `NotificationCenter` gained the `subscribe(fn)` method (see above).
+
+## 0.17.2 (2026-10-22)
+
+A patch release: everything below is additive. Every entry is documented in a
+README section headed "(0.17.2)"; each entry links to it.
+
+### Added and changed
+
+- [An open single instance takes new props: `navigate(props)`](README.md#an-open-single-instance-takes-new-props-navigateprops-0172): opening a `single` kind that is already open with new props reveals it and calls its content's `navigate(props)` hook once; the props are recorded on the tab. An open that names no props only reveals.
+- [A link to a kind nobody registered](README.md#a-link-to-a-kind-nobody-registered-0172): `wm.navigate` to a kind that is not registered logs one warning, changes nothing and returns `false`.
+- [A palette row drawn disabled, with a reason](README.md#a-palette-row-drawn-disabled-with-a-reason-0172): a command with `enabled: () => false` is listed greyed (`aria-disabled`), does nothing when picked, and shows its `disabledReason` as a tooltip.
+- [A catalog source only behind its prefix: `scopedOnly`](README.md#a-catalog-source-only-behind-its-prefix-scopedonly-0172): a catalog source with `scopedOnly: true` is searched only when its prefix is typed, in the flat and the grouped palette.
+- [The settings categories outside the page: `SettingsCategories`](README.md#the-settings-categories-outside-the-page-settingscategories-0172): `SettingsView` can leave out its own category list and filter, and `SettingsCategories` (new export from `@flexdesk/widgets`) shows them anywhere, kept in step with the view.
+- [Toast cards are styled and clickable](README.md#toast-cards-are-styled-and-clickable-0172): toast cards use `twm-notification` and `twm-notification--<severity>`, styled in flexdesk.css and base.css, with their entry animation defined there; cards take pointer events, so their buttons work (BUG-0033). A sheet that targeted `.notification` must target `.twm-notification`.
+
+### Removed or renamed exports
+
+None. Compared with 0.17.1, across every entry point (`core`, `widgets`, `wm`,
+`host`, `canvas`, `flow`, `charts`, `tiles`, `editor`) and the package
+`exports` map, exports were only added: `SettingsCategories` in `@flexdesk/widgets`.
+Not an export but worth knowing: toast cards changed class from `notification`
+to `twm-notification` (see above).
+
 ## 0.17.1 (2026-10-21)
 
 A patch release: everything below is additive. Every entry is documented in a

package/README.md

@@ -237,6 +237,65 @@ with it. The taxonomy answers `isSingle(kind)`, `instanceKey(kind, props)` and
 `singleReason(kind)`; the window manager answers `isSingleKind(kind)`,
 `findInstance(kind, props)` and `revealInstance(kind, props)`.
 
+### An open single instance takes new props: `navigate(props)` (0.17.2)
+
+Revealing a `single` instance used to drop the props the open asked for: the
+observatory kept showing the planet it was opened with. A content factory that
+returns a `navigate(props)` hook from its mount is now handed them:
+
+```js
+content: {
+    observatory: (el, props) => {
+        const view = mountObservatory(el, props);
+        return {
+            destroy: () => view.destroy(),
+            navigate: (next) => view.focusPlanet(next.planet),   // already open: go there
+        };
+    },
+},
+
+wm.navigate('observatory', { planet: 'mars' });   // open: revealed, then navigate({ planet: 'mars' })
+```
+
+- **Every open path that reveals the instance calls it once**, after the
+  reveal, with a copy of the new props — `navigate`, the top nav,
+  `openInPrimary`, `openInTab*`, `splitLeafWith`, Back. The same props twice
+  are two calls; nothing is deduplicated, and no second instance is mounted.
+- **The props are recorded on the instance's tab** (or its window's), so a
+  top-nav page restore or a reload mounts it with the latest. The tile is not
+  rebuilt by the write.
+- **An open that names no props only reveals** — the top-nav button,
+  `openInPrimary(kind)`, `navigate(kind)`: it asks to see the instance, not to
+  empty it, so the hook is not called and the tab keeps its props.
+- **A content without the hook is revealed as before**: its tab keeps its props
+  and nothing is called. A hook that throws is a console warning.
+
+### A link to a kind nobody registered (0.17.2)
+
+`wm.navigate(kind, props, opts)` returns `true` once it has routed the
+navigation. A `kind` the shell's `content` map has no factory for is refused
+instead, on every destination (`main`, `origin`, a new tab, a window, a split,
+the legacy `target`):
+
+```js
+if (!wm.navigate(link.kind, link.props)) {
+    // nothing opened: tell the user the link is dead
+}
+```
+
+- **One `console.warn` naming the kind**, per call, and `false` back.
+- **Nothing changes**: no tile, tab, window or desktop, no per-tab history, no
+  `onChange` — and no "no factory registered yet" placeholder tile, which is
+  what such a link used to leave behind.
+- **No exception reaches the caller**, whatever `kind` is (`undefined`, `null`
+  and `''` included).
+
+A shell that only navigates to kinds it registered sees no change; the return
+value is new, so code that ignored it is unaffected. A split destination used
+to hand back the new leaf's id; it now returns `true` like the others — call
+`wm.splitLeafWith(...)` for the id. A restored layout that names an
+unregistered kind still draws its placeholder: only `navigate` refuses.
+
 ### A pane that names what it shows: `ctx.setTitle` (0.12.1)
 
 A content factory receives `(hostEl, props, ctx)`, and `ctx` carries, per pane,
@@ -450,6 +509,60 @@ topic.* The fallback comes from `HelpModal.open(id, { fallback })`
 (`@flexdesk/widgets`), and you can pass one yourself. A topic id that nobody
 provides now shows *Help topic not found.* where it used to raise a load error.
 
+### A palette row drawn disabled, with a reason (0.17.2)
+
+A palette row (a command from `commands`, or any other row) may carry
+`enabled: () => boolean` and `disabledReason`. While `enabled()` returns false
+the row is still listed, so it can say why it does nothing:
+
+```js
+palette: {
+    commands: () => [
+        { id: 'save', label: 'Save', action: save,
+          enabled: () => dirty, disabledReason: 'Nothing to save' },
+    ],
+},
+```
+
+- The row gets the class `twm-cmdpal__item--disabled` and `aria-disabled="true"`,
+  and `disabledReason`, when given, is its `title` (the tooltip). The stylesheet
+  greys it.
+- Picking it with a click, Enter, Ctrl+Enter or Shift+Enter runs nothing: not
+  its `action`, not `onPick`. The palette stays open on it.
+- The arrow keys still move onto it and past it.
+- `enabled()` is called again on every draw and every pick, so the row follows
+  your state while the palette is open. An `enabled()` that throws counts as
+  false.
+- A row without `enabled` is drawn and picked as before. Both layouts (flat and
+  `grouped`) behave the same way.
+
+`tests/command_palette_disabled.test.mjs` drives it in jsdom.
+
+### A catalog source only behind its prefix: `scopedOnly` (0.17.2)
+
+A source can be too broad to compete with everything else in the palette: help
+topics, say, which would crowd every query. Mark it `scopedOnly` and its rows are
+listed only once its prefix has made the type chip:
+
+```js
+createEntityCatalog({
+    sources: [
+        { navKind: 'model', list: listModels, shape: toRow },
+        { navKind: 'topic', list: listTopics, shape: toRow, scopedOnly: true },
+    ],
+    aliases: { help: ['topic'] },
+});
+```
+
+A plain typed query (`solver`) lists no `topic` row, in the flat and the grouped
+layout alike: no row, no group header, no *Show all*. `help: solver` or
+`topic: solver` lists its rows as any source's, and `help:` alone lists them all.
+The mark is the palette's business: `loadAll`, `loadGrouped` and the tile menu
+still return every source, a picked row reaches `onPick` as its `shape` made it,
+and commands and `empty()` rows of the same kind are not held back. A source
+without the option, or with `scopedOnly: false`, is searched exactly as in
+0.17.1. A value that is not a boolean is refused with a `TypeError`.
+
 ### Your keys, not the window manager's: `keymap` (0.17.0)
 
 The window manager binds F1..F12, Backspace, Ctrl+K, Ctrl+Tab, Ctrl/Shift+Arrows,
@@ -3034,6 +3147,52 @@ title; default "Settings"). The markup is `.twm-settings` >
 `.twm-settings__row` (`--modified`); `flexdesk.css` styles it from tokens.
 `tests/settings_view.test.mjs` covers it in jsdom.
 
+## The settings categories outside the page: `SettingsCategories` (0.17.2)
+
+A `SettingsView` made with `sidebar: false` draws no sidebar: no heading, no
+filter box, no category list and no *Reset all*, only the chosen category's
+settings (or the filter's matches). `new SettingsCategories({ view })` (in
+`@flexdesk/widgets`) draws those parts for that view wherever it is mounted,
+for example in an app's left navigator:
+
+```js
+import { SettingsView, SettingsCategories } from '@flexdesk/widgets';
+
+const view = new SettingsView({ store, eventBus: bus, sidebar: false });
+view.mount(pageHost);
+const cats = new SettingsCategories({ view });
+cats.mount(navigatorHost);
+
+const off = view.subscribe(({ category, query }) => { /* e.g. a tab title */ });
+// …
+off();
+cats.dispose();
+view.dispose();
+```
+
+It keeps no state of its own. Typing in its filter box is `view.setQuery()`,
+clicking a category is `view.selectCategory()` and its *Reset all* is
+`view.resetAll()`, which asks the view's `confirm` first and changes nothing
+unless it resolves true. It redraws from the view whenever the view's category,
+filter or registered categories change, so the two agree whichever side moved
+them: `view.selectCategory('window')` marks that category in the list, and
+`view.setQuery('shadow')` puts the text in its filter box. As in the view's own
+sidebar, choosing a category clears the filter, and no category is marked while
+the filter is in effect. Its clicks and keystrokes act once the view is mounted.
+
+Two methods on `SettingsView` serve it and anything else that follows the view:
+`subscribe(fn)` calls `fn({ category, query })` after each such change and
+answers the unsubscribe; `isFiltering()` is true while the filter's trimmed
+text is not empty. `settingsViewContent({ …, sidebar: false })` passes the
+option through. A view made without `sidebar` (or with `sidebar: true`) draws
+exactly as in 0.17.1.
+
+The markup is `.twm-settings-categories` > `.twm-settings__search`,
+`.twm-settings__nav` (`button.twm-settings__cat`, `--active`) and
+`.twm-settings__reset-all`, the same parts and classes as the sidebar's;
+`flexdesk.css` styles it, leaving its width and padding to the host.
+`tests/settings_view.test.mjs` §11–§14 cover it.
+
 ## A step wizard: `Wizard` (0.17.0)
 
 `new Wizard({ steps, data, onFinish, onCancel, labels })` (in `@flexdesk/widgets`)
@@ -3368,7 +3527,8 @@ again: its pane hears `onShow` and `onSelect` fires, and nothing is written back
 Toasts, from `toast:show` on the bus (or `toastInfo` / `toastWarn` /
 `toastError` / `toastSuccess`) or `show()`. A payload with `persistent: true`
 stays until its × is clicked. `history` keeps every notification shown, and
-`NotificationHistory` puts it behind a bell in the bottom bar.
+`NotificationHistory` puts it behind a bell in the bottom bar (one entry per toast;
+`subscribe(fn)` hears each one, 0.17.3).
 
 *New in 0.11.0:* **`overflow: 'collapse'`.** By default, a toast past
 `maxVisible` (3) pushes the oldest off the screen. With `'collapse'`, the toasts
@@ -3429,6 +3589,51 @@ job.on('end', () => nc.update(id, { progress: 1, severity: 'success', message: '
 
 `tests/notification_progress.test.mjs` holds it in jsdom.
 
+### Toast cards are styled and clickable (0.17.2)
+
+A toast card is `.twm-notification` with `.twm-notification--<severity>`
+(`info`, `success`, `warn`, `error`, `fatal`), and the "+N more" summary is
+`.twm-notification.twm-notification--summary`. `flexdesk.css` gives the card its
+background, a left border in the severity's colour (`--color-success`,
+`--color-warning`, `--color-danger`; info keeps the blue) and the entry
+animation `twm-notification-in`, which the sheet now defines. The card sets
+`pointer-events: auto` over the root's `none`, so its buttons and its
+click-to-close work.
+
+Until 0.17.2 the card carried the bare `notification` / `notification--<severity>`
+classes, which no FlexDesk sheet styled: the card had no background and no
+border, and inherited `pointer-events: none`, so its buttons could not be
+clicked. A consumer stylesheet that targeted `.notification` should target
+`.twm-notification` instead. The live region is `.twm-notification-center__live-region`.
+`tests/notification_toast_styles.test.mjs` holds the classes, the cascade and
+the sheets.
+
+### One toast, one history entry, one unread (0.17.3)
+
+`history` holds **one entry per toast**, however it was raised: `show()`, the
+`warn()` / `error()` / `info()` / `success()` helpers, `toast:show`,
+`notification:show` or `log:entry`. A toast that leaves (timeout, ×, overflow,
+`clearAll`) marks its own entry `dismissed: true` with the `reason`, and adds
+no entry. **`nc.subscribe(fn)`** calls `fn(entry, center)` once for each entry
+added, after it is in `history` (not for a `skipHistory` toast, and not for a
+dismissal), and answers the unsubscribe; `dispose()` drops every listener.
+
+`NotificationHistory` follows the centre through `subscribe()`: every entry
+recorded is one unread on the bell until the popover is opened, also past
+`historyLimit`. It no longer watches the bus for toasts, so its
+`notificationCenter` is a `NotificationCenter` (or anything with `history` and
+`subscribe`).
+
+```js
+const off = nc.subscribe((entry) => console.log('recorded', entry.severity, entry.message));
+nc.warn('Disk almost full');          // the bell says 1
+```
+
+Until 0.17.3 the bell counted only on bus events, so a toast raised through
+`show()` / `warn()` / `error()` / `info()` never raised its badge, and a dismissal
+was pushed as a second entry: a toast that timed out was in `history` twice
+and counted twice. `tests/notification_history_follows_center.test.mjs` holds it.
+
 ### Alerts with history: a log, a pane, a tab host and a bell (0.14.0)
 
 A toast is the moment. The **alert log** keeps what came in until it is

package/css/base.css

@@ -275,6 +275,28 @@
     flex-direction: column;
     gap: var(--space-lg);
 }
+/* A toast card. The root takes no pointer events (it overlays the page), so the
+ * card takes them back: without this its buttons cannot be clicked (BUG-0033). */
+.twm-notification {
+    pointer-events: auto;
+    background: #1f1f20;
+    border: 1px solid #2f2f31;
+    border-left: 4px solid #4fc1ff;
+    border-radius: var(--radius-lg);
+    padding: var(--space-lg) 14px;
+    box-shadow: 0 12px 32px rgba(0, 0, 0, 0.45);
+    animation: twm-notification-in 160ms ease-out;
+    min-width: 280px;
+    cursor: pointer;
+}
+.twm-notification--success { border-left-color: var(--color-success, #3fb950); }
+.twm-notification--warn    { border-left-color: var(--color-warning, #ff9800); }
+.twm-notification--error,
+.twm-notification--fatal   { border-left-color: var(--color-danger, #c74e4e); }
+@keyframes twm-notification-in {
+    from { opacity: 0; transform: translateY(6px); }
+    to { opacity: 1; transform: translateY(0); }
+}
 .twm-notification__header {
     display: flex;
     align-items: center;
@@ -425,7 +447,7 @@
     box-shadow: 0 12px 32px rgba(0, 0, 0, 0.45);
     display: flex;
     flex-direction: column;
-    animation: notification-in 160ms ease-out;
+    animation: twm-notification-in 160ms ease-out;
 }
 .twm-notification-history__header {
     display: flex;

package/css/flexdesk.css

@@ -283,6 +283,28 @@
     flex-direction: column;
     gap: var(--space-lg);
 }
+/* A toast card. The root takes no pointer events (it overlays the page), so the
+ * card takes them back: without this its buttons cannot be clicked (BUG-0033). */
+.twm-notification {
+    pointer-events: auto;
+    background: #1f1f20;
+    border: 1px solid #2f2f31;
+    border-left: 4px solid #4fc1ff;
+    border-radius: var(--radius-lg);
+    padding: var(--space-lg) 14px;
+    box-shadow: 0 12px 32px rgba(0, 0, 0, 0.45);
+    animation: twm-notification-in 160ms ease-out;
+    min-width: 280px;
+    cursor: pointer;
+}
+.twm-notification--success { border-left-color: var(--color-success, #3fb950); }
+.twm-notification--warn    { border-left-color: var(--color-warning, #ff9800); }
+.twm-notification--error,
+.twm-notification--fatal   { border-left-color: var(--color-danger, #c74e4e); }
+@keyframes twm-notification-in {
+    from { opacity: 0; transform: translateY(6px); }
+    to { opacity: 1; transform: translateY(0); }
+}
 
 /* NotificationCenter `overflow: 'collapse'`: the toasts past maxVisible, as one. */
 .twm-notification--summary {
@@ -455,7 +477,7 @@
     box-shadow: 0 12px 32px rgba(0, 0, 0, 0.45);
     display: flex;
     flex-direction: column;
-    animation: notification-in 160ms ease-out;
+    animation: twm-notification-in 160ms ease-out;
 }
 .twm-notification-history__header {
     display: flex;
@@ -8322,6 +8344,9 @@ body.twm-dragging * { user-select: none; }
 .twm-cmdpal__item--active .twm-cmdpal__acts { display: flex; }
 /* A copy verb a single kind refuses: drawn, greyed, with the reason as its title. */
 .twm-cmdpal__act--disabled { opacity: 0.45; }
+/* 0.17.2. A row whose `enabled()` says no: listed, reachable by the arrows,
+ * greyed, with its `disabledReason` as the title; picking it does nothing. */
+.twm-cmdpal__item--disabled { opacity: 0.45; cursor: default; }
 .twm-cmdpal__item--active .twm-cmdpal__kind,
 .twm-cmdpal__item--active .twm-cmdpal__shortcut { display: none; }
 .twm-cmdpal__item--more { color: var(--text-muted); font-size: var(--font-size-sm); }
@@ -10541,6 +10566,17 @@ button.twm-alerts__ref:hover { text-decoration: underline; }
     padding: var(--space-xl) 0;
     color: var(--text-muted);
 }
+/* SettingsCategories (0.17.2): the sidebar's filter, categories and
+ * Reset all, mounted outside the view; the host sets its width and padding. */
+.twm-settings-categories {
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+    height: 100%;
+    gap: var(--space-sm);
+    color: var(--text-body);
+    font-size: var(--font-size-sm);
+}
 /* ══ end SETTINGS VIEW ══ */
 
 /* ══ DOCUMENT OUTLINE (0.17.0) ═══════════════════════════════════════

package/dist/flexdesk.css

@@ -283,6 +283,28 @@
     flex-direction: column;
     gap: var(--space-lg);
 }
+/* A toast card. The root takes no pointer events (it overlays the page), so the
+ * card takes them back: without this its buttons cannot be clicked (BUG-0033). */
+.twm-notification {
+    pointer-events: auto;
+    background: #1f1f20;
+    border: 1px solid #2f2f31;
+    border-left: 4px solid #4fc1ff;
+    border-radius: var(--radius-lg);
+    padding: var(--space-lg) 14px;
+    box-shadow: 0 12px 32px rgba(0, 0, 0, 0.45);
+    animation: twm-notification-in 160ms ease-out;
+    min-width: 280px;
+    cursor: pointer;
+}
+.twm-notification--success { border-left-color: var(--color-success, #3fb950); }
+.twm-notification--warn    { border-left-color: var(--color-warning, #ff9800); }
+.twm-notification--error,
+.twm-notification--fatal   { border-left-color: var(--color-danger, #c74e4e); }
+@keyframes twm-notification-in {
+    from { opacity: 0; transform: translateY(6px); }
+    to { opacity: 1; transform: translateY(0); }
+}
 
 /* NotificationCenter `overflow: 'collapse'`: the toasts past maxVisible, as one. */
 .twm-notification--summary {
@@ -455,7 +477,7 @@
     box-shadow: 0 12px 32px rgba(0, 0, 0, 0.45);
     display: flex;
     flex-direction: column;
-    animation: notification-in 160ms ease-out;
+    animation: twm-notification-in 160ms ease-out;
 }
 .twm-notification-history__header {
     display: flex;
@@ -8322,6 +8344,9 @@ body.twm-dragging * { user-select: none; }
 .twm-cmdpal__item--active .twm-cmdpal__acts { display: flex; }
 /* A copy verb a single kind refuses: drawn, greyed, with the reason as its title. */
 .twm-cmdpal__act--disabled { opacity: 0.45; }
+/* 0.17.2. A row whose `enabled()` says no: listed, reachable by the arrows,
+ * greyed, with its `disabledReason` as the title; picking it does nothing. */
+.twm-cmdpal__item--disabled { opacity: 0.45; cursor: default; }
 .twm-cmdpal__item--active .twm-cmdpal__kind,
 .twm-cmdpal__item--active .twm-cmdpal__shortcut { display: none; }
 .twm-cmdpal__item--more { color: var(--text-muted); font-size: var(--font-size-sm); }
@@ -10541,6 +10566,17 @@ button.twm-alerts__ref:hover { text-decoration: underline; }
     padding: var(--space-xl) 0;
     color: var(--text-muted);
 }
+/* SettingsCategories (0.17.2): the sidebar's filter, categories and
+ * Reset all, mounted outside the view; the host sets its width and padding. */
+.twm-settings-categories {
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+    height: 100%;
+    gap: var(--space-sm);
+    color: var(--text-body);
+    font-size: var(--font-size-sm);
+}
 /* ══ end SETTINGS VIEW ══ */
 
 /* ══ DOCUMENT OUTLINE (0.17.0) ═══════════════════════════════════════