flexdesk 0.10.0 → 0.11.1

package/README.md

@@ -794,6 +794,97 @@ disposed.
 dispose when the table is put back. Before 0.7.0, a table taken out, put back
 and taken out again could be disposed by the first departure's timer.
 
+### DataTable: your own right-click items, a render hook, the keyboard, a remembered page
+
+These options let an application drop a private copy of the DataTable kept for
+them. Every one is off until you set it, and a table that sets none of them
+draws and behaves as in 0.9.1.
+
+```js
+const queue = DataTable.mount(host, {
+    headers, rows, pagination: true, sortable: true, filterable: true,
+    stateStore, persistKey: `queue:${view}`,
+    persistPage: !!savedView,              // an ad-hoc view shares its key: start it on page 1
+    getRowKey: (row) => row[0],
+    contextMenuItems: (row, rowIdx, ctx) => [
+        { label: ctx.selection.length > 1 ? `Open ${ctx.selection.length}` : 'Open',
+          icon: 'open_in_new', action: 'open' },
+        { separator: true },
+        { label: 'Delete…', icon: 'delete', action: 'delete', danger: true,
+          disabled: !canDelete(row), title: canDelete(row) ? '' : 'Closed records stay' },
+    ],
+    onContextMenuAction: (action, rowIdx, row, ctx) => run(action, ctx.selectedRows),
+    onRender: (t) => status.textContent = `${t.getDisplayedRows().length} of ${rows.length} shown`,
+    keyboardNav: true,
+    onRowKeyDown: (rowIdx, row, ev) => {
+        if (row && ev.key === 'Enter' && (ev.ctrlKey || ev.metaKey)) { openElsewhere(row); return true; }
+        if (row && ev.altKey && ev.key.toLowerCase() === 't') { openInTab(row); return true; }
+    },
+    onRowActivate: (i, row) => open(row),
+    activateOn: ['click', 'enter'],
+});
+queue.focus();
+```
+
+**The right-click menu**
+
+| Option | What it does |
+|---|---|
+| `contextMenuItems` | Your items in the table's own right-click menu: an array, or `(row, rowIdx, ctx) => items`, asked on every right-click of a row. An item is `{ label, icon, action, disabled, danger, title }` or `{ separator: true }`, drawn like the copy items (`disabled` greys it out, `danger` draws it red, `title` says why). `ctx` is `{ rowIdx, row, colIdx, value, selection, selectedRows }`: the row and the cell under the pointer (`colIdx` is null on the row-number column) and the selection, which by then includes the row. Your items come first; with `copyable`, a separator and the two copy items follow. Set without `copyable`, the menu has your items only, and a row you give no items gets the browser's own menu. |
+| `onContextMenuAction(action, rowIdx, row, ctx)` | Called when one of your items is chosen, after the menu has closed. The copy items never call it, so an action may be named anything. |
+
+**What the table shows**
+
+| Option | What it does |
+|---|---|
+| `onRender(table)` | Called at the end of every render: the first one, `setData`, a sort, a filter, a page. A hook that throws is reported on the console and the table still draws. |
+| `getDisplayedRows()` | The rows the table shows, filtered and sorted, across every page and not only the one on screen. It returns a copy. With server-side paging it is the page held. |
+
+**The keyboard**
+
+| Option | What it does |
+|---|---|
+| `keyboardNav: true` | On the focused table, ArrowUp and ArrowDown move the selection one row through the page shown, in the order shown, and Home and End go to its first and last row. With Shift they select the range from the anchor, as Shift-click does (not on a `selectable: 'single'` table). The row is scrolled into view and `onSelectionChange` is told. Keys pressed in a control inside the table are left alone. Needs `selectable`. |
+| `onRowKeyDown(rowIdx, row, ev)` | Called for every key pressed on the focused table, before the table's own keys, with the row Enter would open (the one row selected, the selection's anchor, or else the active row) or `null`. Return `true` to take the key: its default is prevented and nothing after it sees it, neither the table (Enter's `onRowActivate`, the arrows, copy) nor the page. Use it for the keys `activateOn` does not take, such as Ctrl+Enter or Alt+T. |
+| `focus()` | Puts the keyboard focus on the table's body without scrolling the page. Returns `false` when nothing is drawn yet. |
+
+**A remembered page**
+
+| Option | What it does |
+|---|---|
+| `persistPage: true` | With `persistKey` and `stateStore`, saves the client page with the sort and filters, and opens the table on it again. If the rows have shrunk since, it opens on the last page. A new filter, and a sort under `resetPageOnSort`, go to the first page and save that. Rows given after mounting (`rows: []`, then `setData`) still open on the saved page. Server-side paging is not affected: its page is your `offset`. Off by default, because a key shared by different row sets, such as ad-hoc filters or search results, must not reopen on a page of the previous list. Without it, the saved state is exactly what 0.9.1 saves. |
+
+### DataTable: columns hidden until somebody asks for them
+
+A column can be part of the row data without being drawn. People choose which
+columns they see from the header's right-click menu, and the choice is
+remembered. A table that sets none of these options draws every column, as in
+0.9.1.
+
+```js
+const list = DataTable.mount(host, {
+    headers: ['Id', 'Summary', 'Status', ...customFields.map((f) => f.label)],
+    rows,
+    hiddenColumns: customFields.map((_, i) => 3 + i),   // not shown until picked
+    columnChooser: true,
+    stateStore, persistKey: 'bugs:queue',
+    onColumnsChange: (hidden) => console.log('hidden now', hidden),
+});
+list.setColumnVisible(3, true);
+```
+
+| Option | What it does |
+|---|---|
+| `hiddenColumns: [colIdx, ...]` | These columns are not drawn: no header, no filter box, no cell, no width in the fit, and they are left out of a copy and of `downloadCSV()`. They stay in the row data, so `renderCell`, `contextMenuItems`, `sortBy` and `setFilter` still see them. The last column shown can never be hidden; a list that hides all of them keeps the first. `setData({ hiddenColumns })` applies a new list. Column indices are positions, so a new `headers` list keeps the set by position. |
+| `columnChooser: true` | A right-click on the header opens a menu that lists every column, with a check mark on those shown. Choosing one shows or hides it. The last column shown is greyed out and says why. Without the option the header keeps the browser's menu. |
+| `setColumnVisible(colIdx, on)` | Shows or hides a column from code. Returns whether anything changed. The widths of the other columns, dragged or fitted, stay with their columns; a column shown again is measured. |
+| `getHiddenColumns()` | The hidden columns' indices, ascending. |
+| `onColumnsChange(hidden)` | Called after every change of the set: the chooser, `setColumnVisible` and `setData({ hiddenColumns })`. |
+| With `persistKey` | The set is saved with the sort and the filters and restored on mount. A saved set wins over `hiddenColumns`, so a column somebody chose stays chosen. A table without these options saves exactly what 0.9.1 saves. |
+
+A column sorted on and then hidden keeps the order; its arrow comes back with
+the column.
+
 ### Scrollbars
 
 `installAutoScrollbars(root)` (from `@flexdesk/widgets`) replaces the browser's
@@ -1426,6 +1517,105 @@ card starts no native drag (a `dragstart` counter at 0) and moves nothing. Real
 arrows, Delete, Ctrl+Z and Backspace do what is said above, and three real
 keystrokes ask the preview once.
 
+## Forms: `openForm`
+
+`openForm({ title, fields, defaults, submitLabel })` (in `@flexdesk/widgets`)
+opens a modal form and resolves with `{ [name]: value }`, or `null` when it is
+cancelled. Fields are `text`, `number`, `password`, `select`, `textarea`,
+`checkbox` and `picker`; `{ section: 'Label' }` entries are headings. Each of
+the four additions below is opt-in, and a form that uses none of them renders
+and submits exactly as in 0.9.1.
+
+### A form that adapts: `onFieldChange`
+
+```js
+openForm({
+    fields: [
+        { name: 'type', label: 'Type', type: 'select', options: ['bug', 'story'] },
+        { section: 'Story', name: 'story' },          // a NAMED section can be hidden
+        { name: 'points', label: 'Points', type: 'number', required: true },
+    ],
+    onFieldChange: (name, value, api) => {
+        const story = api.get('type') === 'story';
+        api.setVisible('story', story);
+        api.setVisible('points', story);
+    },
+});
+```
+
+`onFieldChange(name, value, api)` is called once when the form opens (with
+`name === null`, so the form starts consistent with its defaults) and after
+every field's `change`. `api` addresses fields and named sections by name:
+
+- `setVisible(name, on)` hides or shows the row. A hidden row keeps its value
+  and is still submitted, but it is not asked about: its `required` and its
+  `validator` stand down until it is shown again.
+- `get(name)` reads the control as it stands: a checkbox as a boolean,
+  anything else as its string.
+- `set(name, value)` writes it. It does not call `onFieldChange` back, so a
+  hook that fills one field from another cannot loop.
+
+A hook that throws is logged and the form carries on.
+
+### Hidden rows stay hidden
+
+`.twm-modal__row` is a grid, and a grid rule beats the `display: none` that
+the `hidden` attribute gets from the browser, so a hidden row stayed on
+screen. `flexdesk.css` now has `.twm-modal__row[hidden],
+.twm-modal__section[hidden] { display: none !important }`, and `setVisible`
+also sets the row's inline `display`, so it holds under a stylesheet of your
+own as well.
+
+### A value you look up: `type: 'picker'`
+
+```js
+{ name: 'parent', label: 'Parent', type: 'picker', required: true,
+  pick: async (current) => ({ value: 'EPIC-0001', label: 'EPIC-0001 — Auth rewrite' }),
+  displayFor: (value) => titleOf(value) }
+```
+
+The row shows a read-only box and a search button. The button, or a click on
+the box, awaits `pick(currentValue)`. Return `{ value, label }` (the label is
+shown, the value is submitted), a bare value (shown through `displayFor`, or
+as itself), or `null` to leave the field as it was. `displayFor(value)` gives
+the text for the value the form opens with and for `api.set`. The value is
+kept in a hidden input, which the browser's own `required` check skips, so
+`required: true` on a picker is checked by the form instead. The markup is
+`.twm-picker` > `.twm-picker__display` + `.twm-btn.twm-picker__btn`.
+
+### A select you may type into: `create`
+
+A `select` with a `create` spec is a type-ahead combobox: pick an option or
+type a new value. `create: { onCreate, hint }` makes the typed value into an
+entity before the form resolves, and shows "↳ will create *hint* …" while you
+type. `create: true` is the plain case: the typed value is submitted as typed,
+with no hint, because nothing is created. Until now `create: true` failed the
+submit with "onCreate is not a function".
+
+`tests/open_form.test.mjs` mounts the real `openForm` in jsdom and covers all
+four, plus a plain form submitting as before.
+
+## Notifications: `NotificationCenter`
+
+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.
+
+*New in 0.11.0:* **`overflow: 'collapse'`.** By default, a toast past
+`maxVisible` (3) pushes the oldest off the screen. With `'collapse'`, the toasts
+on screen stay, and the rest wait behind one **"+N more"** toast whose count
+follows them. Each comes in as a visible one closes. A sticky alert is never
+pushed off unseen. Clicking the summary calls `summaryAction(held)` and emits
+`notification:summary` with `{held}`, so a history panel can open. Every toast
+is in `history` as it arrives, waiting or not.
+
+```js
+const nc = new NotificationCenter({ eventBus, maxVisible: 3, overflow: 'collapse',
+                                    summaryAction: () => history.open() });
+nc.mount(document.body);
+```
+
 ## The host port
 
 FlexDesk never touches `pywebview`, `fetch`, `localStorage` or the filesystem. It

package/css/base.css

@@ -6001,7 +6001,7 @@ button.twm-about-dialog__btn--close:focus {
 /* ── the popover both pickers are drawn in ──────────────────────────── */
 .twm-flow-popover {
     position: fixed;
-    z-index: var(--z-popover);
+    z-index: var(--z-over-windows, 7100);  /* over the managed window it opened from */
     display: flex;
     flex-direction: column;
     box-sizing: border-box;
@@ -7328,7 +7328,7 @@ button.twm-about-dialog__btn--close:focus {
 /* the grip drag: a ghost under the pointer, and a drop line naming the place */
 .twm-flow-outline__ghost {
     position: fixed;
-    z-index: var(--z-popover);
+    z-index: var(--z-over-windows, 7100);  /* over the managed window it opened from */
     box-sizing: border-box;
     display: flex;
     align-items: center;

package/css/flexdesk.css

@@ -279,6 +279,22 @@
     flex-direction: column;
     gap: var(--space-lg);
 }
+
+/* NotificationCenter `overflow: 'collapse'`: the toasts past maxVisible, as one. */
+.twm-notification--summary {
+    display: block;
+    width: 100%;
+    padding: 6px 12px;
+    font: inherit;
+    font-size: 12px;
+    text-align: left;
+    color: var(--text-secondary, #9a9a9a);
+    background: var(--surface-2, #2d2d2d);
+    border: 1px dashed var(--border-strong, #383838);
+    border-radius: var(--radius-md, 6px);
+    cursor: pointer;
+}
+.twm-notification--summary:hover { color: var(--text-primary, #e0e0e0); }
 .twm-notification__header {
     display: flex;
     align-items: center;
@@ -5065,6 +5081,36 @@ button.twm-about-dialog__btn--close:focus {
     color: var(--ea-accent);
     font-style: italic;
 }
+/* Picker = a read-only display of the looked-up value + its search button.
+ * The display takes the field-well styling of the text inputs above. */
+.twm-managed-window--modal .twm-picker {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    min-width: 0;
+}
+.twm-managed-window--modal .twm-picker .twm-picker__display {
+    flex: 1 1 auto;
+    min-width: 0;
+    cursor: pointer;
+}
+.twm-managed-window--modal .twm-picker__btn {
+    flex: 0 0 auto;
+    min-height: 22px;
+    padding: 0 6px;
+    border-radius: 0;
+}
+.twm-managed-window--modal .twm-picker__btn .material-symbols-outlined {
+    font-size: 15px;
+}
+/* A row (or named section) hidden by openForm's `setVisible`. `[hidden]`
+ * carries only the UA sheet's `display: none`, which the grid and flex rules
+ * on `.twm-modal__row` / `.twm-modal__section` beat — so a hidden row stayed
+ * on screen. */
+.twm-modal__row[hidden],
+.twm-modal__section[hidden] {
+    display: none !important;
+}
 /* Action strip — true footer band, flush against the modal edges,
  * darker chrome bg, top border + 1px highlight above. Right-aligned
  * buttons, primary stays rightmost. */
@@ -8490,7 +8536,7 @@ tr:hover .twm-row-action { opacity: 1; }
 /* ── the popover both pickers are drawn in ──────────────────────────── */
 .twm-flow-popover {
     position: fixed;
-    z-index: var(--z-popover);
+    z-index: var(--z-over-windows, 7100);  /* over the managed window it opened from */
     display: flex;
     flex-direction: column;
     box-sizing: border-box;
@@ -9817,7 +9863,7 @@ tr:hover .twm-row-action { opacity: 1; }
 /* the grip drag: a ghost under the pointer, and a drop line naming the place */
 .twm-flow-outline__ghost {
     position: fixed;
-    z-index: var(--z-popover);
+    z-index: var(--z-over-windows, 7100);  /* over the managed window it opened from */
     box-sizing: border-box;
     display: flex;
     align-items: center;

package/css/tokens.css

@@ -115,6 +115,10 @@
     --z-popover:  200;
     --z-modal:    1000;
     --z-toast:    10000;
+    /* What opens FROM a managed window and must draw over it: managed windows
+       stack from 6000 to 6999 (managed_window.js), so a popover at
+       --z-popover would open behind the window that opened it. */
+    --z-over-windows: 7100;
 
     /* ── Transitions ──────────────────────────────────────────── */
     --transition-fast:   120ms ease;

package/dist/charts.js

@@ -39,10 +39,10 @@ import {
   setPlotlySource,
   uid,
   updateChart
-} from "./chunk-WKTYKXWF.js";
+} from "./chunk-EHHTKD7B.js";
 import {
   createRafResizeObserver
-} from "./chunk-JLCJWCRS.js";
+} from "./chunk-6CGH73BC.js";
 import {
   ManagedWindow
 } from "./chunk-6JSOVNID.js";

package/dist/{chunk-H4LT43RS.js → chunk-5QPGYHBN.js}

@@ -1,6 +1,6 @@
 import {
   modalHost
-} from "./chunk-6NG7YVBG.js";
+} from "./chunk-6EZPPN4E.js";
 
 // src/help/help_registry.js
 var EMPTY_PROVIDER = Object.freeze({
@@ -472,4 +472,4 @@ export {
   showContextMenu,
   hideContextMenu
 };
-//# sourceMappingURL=chunk-H4LT43RS.js.map
+//# sourceMappingURL=chunk-5QPGYHBN.js.map