@webship.co/workspace 1.0.0-rc1 → 1.0.1

package/core/workspace-app/PLUGINS.md

@@ -150,7 +150,8 @@ module.exports.register = (api) => {
 | `api.addFragment(handler)` | GET handler for `/fragments/p/<plugin>/<rest>`. Context: `{ req, res, send, rest, searchParams }`. |
 | `api.addPageActions(fn)` | `fn({ view, key, meta })` returns a rail group `{ label, items: [html] }` or null. Runs on every page render. |
 | `api.addProjectActions(fn)` | `fn({ key, project, dir, meta })` returns HTML appended to that project row's actions (or null). Runs per row on `projects`-kind pages. |
-| `api.addRowMenu(slot, { label, row }, fn)` | A named menu on every project row, in a slot the Buttons settings arrange like a built-in one. `fn({ key, project, dir, meta, allowed, vals })` returns the menu's HTML, or null for a row it has nothing for. |
+| `api.addRowMenu(slot, { label, row }, fn)` | A named menu on every project row, in a slot the Buttons settings arrange like a built-in one. `fn({ key, project, dir, meta, allowed, vals })` returns the menu's HTML, or null for a row it has nothing for — or `{ html, body }`, a menu whose body loads when it opens (below). |
+| `api.capabilities` | What this dashboard can do that an older one could not, as a `Set` of names; a package that serves several dashboards checks it before using a newer form of an answer. So far: `row-menu-body`. |
 | `api.addPage(re, handler)` | A whole page: GET requests whose path matches `re`. `handler({ req, res, match, send })` writes the response itself. |
 | `api.addProjectChip(fn)` | A chip in the project card's meta line. `fn({ key, project, dir, meta })` returns HTML or null. |
 | `api.addFolderSetup({ html, steps, prompt, problem })` | A section of the New-folder form (`html(ws, { allowed })`), the shell steps it adds (`steps(ws, name, form, ctx)` → array), the lines it adds to the Claude Code prompt (`prompt(…)` → array) and its validation (`problem(ws, form, ctx)` → '' or why). |
@@ -165,6 +166,50 @@ module.exports.register = (api) => {
 | `api.addSessionLog(fn)` | Where a session's log lives when the dashboard does not know: `fn(session, dirs)` returns a file in one of `dirs`, or ''. |
 | `api.addAssistantContext(fn)` | A paragraph of the assistant's system context: what this plugin lets it reach, and the rules. |
 
+### A row menu whose body loads when it opens
+
+A page of fifty rows must not carry fifty copies of every menu. Instead of the whole menu, a row-menu
+function may return an object:
+
+```js
+api.addRowMenu('cloud', { label: 'CLOUD', row: 0 }, ({ key, project, dir, allowed }) => {
+  if (!allowed.has('cloud')) return null;
+  return {
+    html: `<button class="uk-button uk-button-default uk-button-small" type="button">CLOUD <span uk-icon="icon: chevron-down; ratio: .6"></span></button>`,
+    body: `/fragments/p/${api.name}/menu/${encodeURIComponent(key)}/${encodeURIComponent(project)}`,
+    caption: 'linked',            // optional: the small text beside the button
+    classes: 'act-menu-hosting',  // optional: extra classes on the menu's wrapper
+  };
+});
+// The body: what used to be inside the dropdown, as a fragment.
+api.addFragment(({ send, rest }) => {
+  const m = rest.match(/^menu\/([a-z0-9_-]+)\/([a-zA-Z0-9_-]+)$/);
+  if (m) return send(`<ul class="uk-nav uk-dropdown-nav"><li><a href …>…</a></li></ul>`);
+});
+```
+
+| Key | What it is |
+| --- | --- |
+| `html` | The button that opens the menu. Required. |
+| `body` | The URL of a fragment this plugin serves (under `/fragments/p/<plugin>/`) whose response is the dropdown's inner HTML, normally one `<ul class="uk-nav uk-dropdown-nav">`. Required. |
+| `caption` | The text beside the button (`not linked`, `3 running`), or none. |
+| `classes` | Extra classes on the `.uk-inline.act-menu` wrapper, after the `act-menu-<slot>` the core adds. |
+
+The core draws `<span class="act-with-status"><div class="uk-inline act-menu act-menu-<slot> …">` + the
+button + an empty `uk-dropdown` shell + the caption. The shell carries `hx-get` to
+`/fragments/row-menu/<slot>/<ws>/<project>?body=<url>` with `hx-trigger="menu-opened"`: UIkit's
+`beforeshow` on the dropdown is relayed as `menu-opened` by `public/ui.js`, so the body is fetched each
+time the menu opens and never before. The core asks the plugin's `body` URL itself and arranges the
+items the way it arranges an inline menu's (the Buttons settings hide, order and add your own actions to
+it alike), so a lazy menu behaves like an inline one once open. A string return is unchanged: the whole
+menu, inline. A plugin that must also run on a dashboard older than this form checks
+`api.capabilities && api.capabilities.has('row-menu-body')` and falls back to the string.
+
+The core's own menus take the same road: DDEV, COMPOSER, Tests, SCREENS, NODE and More are drawn as this shell and
+answer at `/fragments/row-menu/<slot>/<ws>/<project>` with no `body` parameter, their items computed for
+that one project when the menu opens (a page of fifty rows is a third of what it was). A plugin's
+`body` must still name one of its own fragments; the core slots are not open to one.
+
 `api.lib` also lends `tabModalHtml`, `hubDomain()`, `listScreens()`, `agentSessions()`, `screenLogFor()`, `claudeSessionsFor()` and
 `screensCached()` (the last `screen -ls`, for a renderer that cannot wait). The types of all of it are
 `@webship.co/workspace-plugin-api`; a plugin written in TypeScript is checked against them.

package/core/workspace-app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workspace-dashboard",
-  "version": "1.0.0-rc1",
+  "version": "1.0.1",
   "description": "The Webship Workspace dashboard: a lean core (workspaces, builders, settings, the assistant shell, the plugin system) that every feature joins as a @webship.co/workspace-<name> plugin — required with npm, then activated, installed and configured.",
   "license": "ISC",
   "main": "server.js",

package/core/workspace-app/plugin-loader.js

@@ -84,7 +84,7 @@ const actions = {};          // '/actions/p/<plugin>/<action>' -> handler(ctx)
 const fragments = {};        // '<plugin>' -> handler({ req, res, send, rest, searchParams })
 const pageActionFns = [];    // ({ view, key, meta }) -> { label, items: [html] } | null
 const projectActionFns = []; // ({ key, project, dir, meta }) -> html | null
-const rowMenus = {};         // '<slot>' -> ({ key, project, dir, meta, allowed, vals }) -> html | null
+const rowMenus = {};         // '<slot>' -> ({ key, project, dir, meta, allowed, vals }) -> html | { html, body, caption, classes } | null
 const pages = [];            // { re, handler({ req, res, match, send }) }
 const chipFns = [];          // ({ key, project, dir, meta }) -> html | null
 const folderSetups = [];     // { html(ws, ctx), steps(ws, name, form, ctx), prompt(ws, name, form, ctx), problem(ws, form, ctx) }
@@ -133,11 +133,17 @@ function appliesTo(config, workspaceKey) {
   return list.length === 0 || list.includes(workspaceKey);
 }
 
+// What this dashboard can do that an older one could not, for a package that serves several
+// dashboards: a plugin checks `api.capabilities.has(…)` before it uses a newer form of an answer.
+//   row-menu-body  a row-menu function may return `{ html, body }`: the body loads when the menu opens.
+const CAPABILITIES = Object.freeze(new Set(['row-menu-body']));
+
 function makeApi(name, config) {
   return {
     name,
     config,
     lib,
+    capabilities: CAPABILITIES,
     // This plugin's own settings file (core/config/plugin.<name>.settings.yml): read it, or change one
     // key or one list in place with comments kept. Secret-named keys stay out of the browser like
     // any setting.
@@ -163,7 +169,9 @@ function makeApi(name, config) {
     },
     // A named menu on every project row, in the slot the layout settings arrange: `spec` is
     // `{ label, row }` like a built-in button's. The function draws it, or returns null for a row
-    // the plugin has nothing to say about.
+    // the plugin has nothing to say about. It may also return `{ html, body, caption, classes }`:
+    // the button, and the URL of a fragment that answers the dropdown's inner HTML when the menu
+    // opens — so a page of fifty rows carries fifty buttons, not fifty menus (rowMenuHtml).
     addRowMenu(slot, spec, fn) {
       if (!/^[a-z0-9-]+$/.test(slot)) throw new Error(`${name}: invalid row menu slot '${slot}'`);
       rowLayout.registerButton({ id: slot, label: spec.label || slot, row: spec.row || 0, columns: spec.columns, menu: spec.menu });
@@ -376,11 +384,84 @@ function pluginProjectActionsHtml(ctx) {
 function pluginRowMenus(ctx) {
   const out = {};
   for (const [slot, fn] of Object.entries(rowMenus)) {
-    try { out[slot] = fn(ctx) || ''; } catch (_) { out[slot] = ''; }
+    try { out[slot] = rowMenuHtml(slot, fn(ctx), ctx); } catch (_) { out[slot] = ''; }
   }
   return out;
 }
 
+/**
+ * What a row-menu function answered, as the row's HTML.
+ *
+ * A string is the whole menu, drawn inline as it always was. An object `{ html, body, caption, classes }`
+ * is a menu whose body loads when it opens: `html` is the button, `body` the URL of a fragment the
+ * plugin serves (under /fragments/p/<plugin>/) whose response is the dropdown's inner HTML, `caption`
+ * the small text beside the button and `classes` extra classes on the menu's wrapper. The page then
+ * carries the button, the caption and an empty dropdown shell; UIkit's `beforeshow` on the shell is
+ * relayed as `menu-opened` (public/ui.js), and htmx fetches the body into it. The fetch goes through
+ * /fragments/row-menu/<slot>/<ws>/<project>, which asks the plugin's URL and arranges the items the
+ * way the Buttons settings arrange an inline menu's (hidden entries, order, your own actions).
+ */
+function rowMenuHtml(slot, result, ctx = {}) {
+  if (!result) return '';
+  if (typeof result === 'string') return result;
+  if (typeof result !== 'object' || typeof result.html !== 'string' || !result.html
+    || typeof result.body !== 'string' || !/^\/fragments\/p\/[a-z0-9-]+\//.test(result.body)) return '';
+  return menuShellHtml(slot, {
+    key: ctx.key, project: ctx.project, html: result.html, caption: result.caption, classes: result.classes,
+    query: `?body=${encodeURIComponent(result.body)}`,
+  });
+}
+
+/**
+ * The shell of a row menu whose body loads when it opens — the one markup for a plugin's lazy menu and for
+ * the core's own (DDEV, COMPOSER, Tests, SCREENS, NODE, More): `<span class="act-with-status">` around the
+ * `.uk-inline.act-menu.act-menu-<slot>` wrapper, the button (`html`), an empty `uk-dropdown` shell and the
+ * caption. The shell fetches `/fragments/row-menu/<slot>/<ws>/<project><query>` on `menu-opened` (the relay
+ * of UIkit's `beforeshow` in public/ui.js) and swaps the answer in as its inner HTML; `triggers` adds more
+ * (SCREENS also polls, for the badges it swaps out of band). `classes` go on the wrapper after
+ * `act-menu-<slot>`, `dropdownClasses` on the shell after `act-menu-lazy` (a menu's own width class).
+ */
+function menuShellHtml(slot, { key, project, html, caption, classes, dropdownClasses, triggers, query = '' } = {}) {
+  const url = `/fragments/row-menu/${encodeURIComponent(slot)}/${encodeURIComponent(key || '')}/${encodeURIComponent(project || '')}${query}`;
+  const wrap = ['uk-inline', 'act-menu', `act-menu-${slot}`, ...String(classes || '').split(/\s+/).filter(Boolean)];
+  const drop = ['act-menu-lazy', ...String(dropdownClasses || '').split(/\s+/).filter(Boolean)];
+  const trigger = ['menu-opened', ...String(triggers || '').split(/\s*,\s*/).filter(Boolean)].join(', ');
+  const cap = caption === undefined || caption === null || caption === '' ? ''
+    : `<span class="act-status uk-text-meta">${esc(String(caption))}</span>`;
+  return `<span class="act-with-status"><div class="${esc([...new Set(wrap)].join(' '))}">${html}`
+    + `<div uk-dropdown="mode: click; pos: bottom-right" class="${esc([...new Set(drop)].join(' '))}" hx-get="${esc(url)}" hx-trigger="${esc(trigger)}" hx-target="this" hx-swap="innerHTML">`
+    + '<ul class="uk-nav uk-dropdown-nav"><li class="uk-nav-header">…</li></ul></div></div>'
+    + `${cap}</span>`;
+}
+
+/** Whether a plugin registered a row menu in this slot. */
+const pluginRowMenuSlot = (slot) => Object.prototype.hasOwnProperty.call(rowMenus, slot);
+
+/**
+ * The body of a lazy row menu: the plugin's fragment at `body` (a /fragments/p/<plugin>/… URL), asked
+ * the way a browser would and answered as `{ status, html }` instead of written to a response — so the
+ * caller can arrange the items before sending them. A plugin that never answers is given 30 seconds.
+ */
+function pluginRowMenuBody(body, req = {}) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (status, html) => { if (done) return; done = true; clearTimeout(timer); resolve({ status, html }); };
+    const timer = setTimeout(() => finish(504, '<li class="uk-nav-header">The menu did not answer.</li>'), 30000);
+    if (typeof timer.unref === 'function') timer.unref();
+    let status = 200;
+    let out = '';
+    const res = {
+      writeHead(code) { status = code || 200; },
+      setHeader() {},
+      write(chunk) { out += String(chunk || ''); },
+      end(chunk) { out += String(chunk || ''); finish(status, out); },
+    };
+    const pathname = String(body).split('?')[0];
+    const hit = pluginFragment(pathname, { url: body, method: 'GET', headers: (req && req.headers) || {} }, res);
+    if (!hit) finish(404, '<li class="uk-nav-header">No such menu.</li>');
+  });
+}
+
 /** The chips plugins put in a project card's meta line. */
 function pluginProjectChipsHtml(ctx) {
   let html = '';
@@ -460,7 +541,7 @@ loadPlugins();
 
 module.exports = {
   pluginActions: actions, pluginFragment, pluginPage, pluginPageActionGroups, pluginProjectActionsHtml,
-  pluginRowMenus, pluginProjectChipsHtml, pluginFolderSetups, pluginCssFiles, pluginLabels,
+  pluginRowMenus, rowMenuHtml, menuShellHtml, pluginRowMenuSlot, pluginRowMenuBody, pluginProjectChipsHtml, pluginFolderSetups, pluginCssFiles, pluginLabels,
   pluginProjectBadgesHtml, pluginSettingsOptions, pluginScreenStarted, pluginWorkKeyLink, pluginWorkPrompt, pluginSessionLog, pluginAssistantContext, pluginForge, pluginForges, pluginOpenWith, pluginFolderLinks, pluginWorkspaceView,
   loadedPlugins: loaded, pluginConfigs,
 };

package/core/workspace-app/plugins-page.js

@@ -93,7 +93,7 @@ function pluginsPageHtml() {
         <strong>configure</strong> its own settings file. The same as <code>bash core/scripts/plugins.sh</code>.</p>
       <form class="uk-flex uk-flex-middle uk-margin-small-bottom plugin-require" hx-post="/actions/plugins" hx-target="#webship-workspace-output" hx-swap="innerHTML">
         <input type="hidden" name="verb" value="require">
-        <input class="uk-input uk-form-small uk-form-width-large" name="spec" placeholder="github:webship/workspace-jira" aria-label="Package to require" required pattern="[A-Za-z0-9@:/._#+~-]+">
+        <input class="uk-input uk-form-small uk-form-width-large" name="spec" placeholder="@webship.co/workspace-jira" aria-label="Package to require" required pattern="[A-Za-z0-9@:/._#+~-]+">
         <button class="uk-button uk-button-default uk-button-small uk-margin-small-left" type="submit">Require</button>
       </form>
       <div class="plugin-cards">${cards || '<p class="uk-text-meta">No plugin packages yet. Pick one from the catalogue below, or require one above.</p>'}</div>

package/core/workspace-app/public/ui.js

@@ -315,9 +315,14 @@ document.body.addEventListener('click', (e) => {
 // sessions is the one thing you open the menu to read, and reading a thirty-second-old one is how you
 // end up clicking a session that has already finished.
 //
-// UIkit emits `beforeshow` on the dropdown, and htmx listens for `menu-opened` on the list inside it.
+// UIkit emits `beforeshow` on the dropdown, and htmx listens for `menu-opened` on the list inside it —
+// or on the dropdown itself, when the whole body loads as it opens (a plugin's lazy row menu). The
+// relay, rather than `hx-trigger="beforeshow"` on the dropdown: a nav inside a menu emits `beforeshow`
+// too when it unfolds, and that bubbling up must not fetch the menu again under the pointer.
 document.addEventListener('beforeshow', (e) => {
-  const list = e.target.querySelector && e.target.querySelector('[hx-trigger*="menu-opened"]');
+  const t = e.target;
+  if (!t || !t.querySelector) return;
+  const list = (t.matches && t.matches('[hx-trigger*="menu-opened"]')) ? t : t.querySelector('[hx-trigger*="menu-opened"]');
   if (list) list.dispatchEvent(new CustomEvent('menu-opened'));
 }, true);
 
@@ -798,7 +803,18 @@ function foldDdevMenus(root) {
   });
 }
 document.addEventListener('DOMContentLoaded', () => foldDdevMenus());
-document.body.addEventListener('htmx:after:swap', (e) => foldDdevMenus(swappedEl(e)));
+document.body.addEventListener('htmx:after:swap', (e) => {
+  const el = swappedEl(e);
+  // A menu whose body just arrived — a row menu loading as it opens, SCREENS on its poll — is the dropdown
+  // itself, which the swap left in place with its fold mark while the folded rows went with the old body.
+  // Marked unfolded again; folded now if it is open, else by `shown` when it opens.
+  if (el && el.matches && el.matches('.act-menu .uk-dropdown')) {
+    delete el.dataset.folded;
+    if (el.classList.contains('uk-open')) foldDdevMenus(el.parentElement);
+    return;
+  }
+  foldDdevMenus(el);
+});
 // A menu that opens upwards near the top would sit under the top bar; the page moves down to show it.
 document.addEventListener('shown', (e) => {
   const d = e.target;