@scalio-cloud/ui 0.17.0 → 0.18.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.18.1
+Page actions after Markus' feedback (2026-10-31, UISPEC section 2 "Page actions"). 0.18.0 was released before these
+changes were merged; apps use 0.18.1.
+- The slot is shown only when a page has actions and pushes the menu down; no reserved room, no separator line.
+- 0.25rem above the buttons, 0.875rem from the last button to the next section heading (half the usual gap).
+- Only Übersicht (first item of a first section without heading) is pinned; further items of that section stay in
+  the menu (Pulse: Geräte).
+- Buttons in the slot: same height (2.25rem), one line, long labels end with "…". Labels without "Neu" (README).
+- **Visible change:** only in apps that set `pageActions`. No token changes.
+
+## 0.18.0
+Page actions in the sidebar, first version (Markus 2026-10-31, reference Scalio Kontor; scalio-docs ADR 0042 Nachtrag).
+- New `react/actions.js`: `PageActions` puts a page's actions (Neu …, Import, Zurück) into a fixed slot in the
+  sidebar right below Übersicht from 768px; on phones they stay in the page header. `ActionSlot`, `useDesktop()`.
+- `Sidebar` gets `pageActions`: Übersicht pinned on top, then the slot (room for two buttons, line below), then the
+  sections. `shell.css`: an empty `.scalio-page-actions` is hidden. `react-dom` is an optional peer dependency.
+- **Visible change:** none until an app sets `pageActions`. No token changes.
+
 ## 0.17.0
 Scalio Pulse is built (scalio-docs ADR 0043, P1 started 2026-10-31).
 - Product switcher: "Pulse" is no longer marked "bald"; it behaves like the other apps (link from `SCALIO_APP_LINKS`).

package/README.md

@@ -129,6 +129,20 @@ Pages that belong together under one menu item keep their own addresses: the ite
 on top. An app with two work areas (Nexus Identity and HR) puts `<WorkspaceSwitcher options value onSelect />`
 into the sidebar's `top`.
 
+**Page actions in the sidebar** (from 0.18.0, UISPEC section 2): `<Sidebar pageActions ... />` keeps Übersicht (the
+first item of a first section without heading) on top and adds a slot right below it. A page wraps its actions in
+`<PageActions>`; from 768px they move into the slot, on phones they stay in the page header. The slot takes no
+room on pages without actions; with actions it pushes the menu down.
+
+```jsx
+<PageHeader title="Kontakte" actions={<PageActions><Button onClick={add}><Plus /> Kontakt</Button></PageActions>} />
+<PageHeader title={doc.number} actions={<PageActions><Button variant="outline" asChild><Link to="/invoices"><ArrowLeft /> Zurück</Link></Button></PageActions>} />
+```
+
+Only actions that start something or lead away go there (Neu …, Import, Scannen, Zurück), at most two per page.
+Labels without "Neu"/"New": the + icon says it ("+ Kontakt", not "+ Neuer Kontakt").
+Filters, search, tabs and Speichern stay on the page. Apps with their own sidebar place `<ActionSlot />` themselves.
+
 ## Settings page (React)
 
 Every area of the settings has its own address (`/settings/<area>`); the app's router picks the area, the

package/nav.css

@@ -17,6 +17,24 @@
 .scalio-sidebar-top { padding: 0.75rem 0.75rem 0; }
 .scalio-sidebar-scroll { flex: 1 1 auto; overflow-y: auto; padding: 0.5rem 0 0.75rem; }
 .scalio-nav-section + .scalio-nav-section { margin-top: 0.25rem; }
+/* Page actions (react/actions.js): Übersicht stays on top, then the slot for the page's actions. The slot takes no
+   room when a page has no actions; with actions it shows them and pushes the menu down. No separator line. */
+.scalio-sidebar-pinned { flex-shrink: 0; padding-top: 0.5rem; }
+.scalio-action-slot { flex-shrink: 0; margin: 0 0.75rem; }
+.scalio-sidebar-scroll.has-action-slot { padding-top: 0; }
+.scalio-side-actions, .scalio-side-actions > div { display: flex; flex-direction: column; align-items: stretch; gap: 0.375rem; }
+.scalio-side-actions { padding-top: 0.25rem; }
+/* Below the buttons: half the usual space before the next heading (0.875rem instead of 1.75rem), a little room
+   before a plain menu item. */
+.scalio-action-slot:has(.scalio-side-actions:not(:empty)) + .scalio-sidebar-scroll > .scalio-nav-section:first-child > .scalio-nav-heading { padding-top: 0.875rem; }
+.scalio-action-slot:has(.scalio-side-actions:not(:empty)) + .scalio-sidebar-scroll > .scalio-nav-section:first-child:not(:has(> .scalio-nav-heading)) { padding-top: 0.375rem; }
+.scalio-side-actions:empty { display: none; }
+/* Same height for every button (2.25rem), one line; a long label is cut with "…". */
+.scalio-side-actions > :not(div), .scalio-side-actions > div > * {
+  box-sizing: border-box; width: 100%; height: 2.25rem; min-height: 0; margin: 0; justify-content: center;
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+}
+.scalio-side-actions input[type="file"], .scalio-side-actions [hidden] { display: none; }
 .scalio-nav-heading {
   padding: 1.25rem 1.25rem 0.5rem; font-size: 11px; font-weight: 700; text-transform: uppercase;
   letter-spacing: 0.12em; color: hsl(var(--muted-foreground));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalio-cloud/ui",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "description": "Scalio Control Room design tokens, Tailwind preset, self-hosted fonts, the shared app header, sign-in layout, sidebar and page blocks",
   "license": "SEE LICENSE IN README.md",
   "private": false,
@@ -46,7 +46,8 @@
   },
   "peerDependencies": {
     "react": ">=18",
-    "tailwindcss": ">=3.3 <4"
+    "tailwindcss": ">=3.3 <4",
+    "react-dom": ">=18"
   },
   "peerDependenciesMeta": {
     "tailwindcss": {
@@ -54,6 +55,9 @@
     },
     "react": {
       "optional": true
+    },
+    "react-dom": {
+      "optional": true
     }
   },
   "scripts": {

package/react/actions.js

@@ -0,0 +1,77 @@
+"use strict";
+// Page actions in the sidebar (UISPEC section 2, "Seitenaktionen", from 0.18.0). Buttons such as "Neu ...",
+// "Import" or "Zurück" sit right below Übersicht, close to the navigation, instead of far right in the page
+// header. The slot takes no room when a page has no actions; with actions it pushes the menu down.
+// Phones have no sidebar: there the actions stay in the page header.
+//
+// The app turns the slot on with <Sidebar pageActions />; a page wraps its actions in <PageActions>.
+// No provider: the slot registers itself in a small store, so pages need no wiring.
+const React = require("react");
+const h = React.createElement;
+
+const DESKTOP_QUERY = "(min-width: 768px)";
+
+let slotEl = null;
+const listeners = new Set();
+
+function setActionSlot(el) {
+  if (slotEl === el) return;
+  slotEl = el;
+  listeners.forEach((fn) => fn());
+}
+
+function subscribe(fn) {
+  listeners.add(fn);
+  return () => listeners.delete(fn);
+}
+
+const getSlot = () => slotEl;
+const getServerSlot = () => null;
+
+function useActionSlot() {
+  return React.useSyncExternalStore(subscribe, getSlot, getServerSlot);
+}
+
+function matchesDesktop() {
+  return typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia(DESKTOP_QUERY).matches;
+}
+
+// True from 768px, the width from which the sidebar is shown (nav.css).
+function useDesktop() {
+  const [desktop, setDesktop] = React.useState(matchesDesktop);
+  React.useEffect(() => {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return undefined;
+    const mq = window.matchMedia(DESKTOP_QUERY);
+    const on = () => setDesktop(mq.matches);
+    on();
+    if (mq.addEventListener) {
+      mq.addEventListener("change", on);
+      return () => mq.removeEventListener("change", on);
+    }
+    mq.addListener(on);
+    return () => mq.removeListener(on);
+  }, []);
+  return desktop;
+}
+
+// The empty slot in the sidebar. Sidebar renders it when pageActions is set; apps with their own sidebar
+// can place it themselves.
+function ActionSlot({ testId }) {
+  return h("div", { ref: setActionSlot, className: "scalio-action-slot", "data-testid": testId || "action-slot" });
+}
+
+// Wrap a page's actions: in the sidebar slot from 768px, otherwise where it stands (page header).
+// Only for actions that start something or lead away (Neu, Import, Scannen, Zurück); filters, search and
+// Speichern stay on the page.
+function PageActions({ children, testId }) {
+  const slot = useActionSlot();
+  const desktop = useDesktop();
+  if (children == null || children === false) return null;
+  if (slot && desktop) {
+    const ReactDOM = require("react-dom");
+    return ReactDOM.createPortal(h("div", { className: "scalio-side-actions", "data-testid": testId || "page-actions" }, children), slot);
+  }
+  return h(React.Fragment, null, children);
+}
+
+module.exports = { PageActions, ActionSlot, useActionSlot, useDesktop, setActionSlot };

package/react/index.js

@@ -378,6 +378,6 @@ module.exports = {
   TEST_IDS,
   initials,
 };
-Object.assign(module.exports, Nav, Blocks, require("./settings"), require("./support"), require("./security"), require("./license"), require("./palette"), require("./unify"), require("./profile"));
+Object.assign(module.exports, Nav, Blocks, require("./settings"), require("./support"), require("./security"), require("./license"), require("./palette"), require("./unify"), require("./profile"), require("./actions"));
 // After the exports above: auth.js uses LanguageToggle and ThemeToggle from this module.
 Object.assign(module.exports, require("./auth"));

package/react/nav.js

@@ -6,6 +6,7 @@ const React = require("react");
 const h = React.createElement;
 const Icons = require("./icons");
 const { labelsFor } = require("./labels");
+const { ActionSlot } = require("./actions");
 
 function cx() {
   return Array.prototype.slice.call(arguments).filter(Boolean).join(" ");
@@ -101,14 +102,28 @@ function SearchButton({ search, lang, labels, testIdPrefix, onNavigate }) {
 
 // Sidebar. variant "desktop" shows from 768px, "drawer" is the same content inside NavDrawer.
 // link: the router's NavLink (gets to, end, className(fn), onClick); without it plain <a> + activePath.
+// pageActions: a slot for the page's actions (react/actions.js) right below Übersicht, desktop only.
+// Übersicht (first item of the first section when it has no heading) then stays on top and does not scroll.
 function Sidebar(props) {
   const {
     nav, link, activePath, top, search, primaryAction, footer, version, commit, lang, labels,
-    variant, onNavigate, testId, testIdPrefix,
+    variant, onNavigate, testId, testIdPrefix, pageActions,
   } = props;
   const prefix = testIdPrefix != null ? testIdPrefix : variant === "drawer" ? "m-" : "";
   const L = labelsFor(lang, labels);
   const sections = visibleSections(nav);
+  const slot = !!pageActions && variant !== "drawer";
+  // Only Übersicht (first item of a first section without heading) is pinned; the rest of that section scrolls.
+  const first = sections[0];
+  const pinned = slot && first && !first.label ? Object.assign({}, first, { items: first.items.slice(0, 1) }) : null;
+  const rest = !pinned ? sections : first.items.length > 1 ? [Object.assign({}, first, { items: first.items.slice(1) })].concat(sections.slice(1)) : sections.slice(1);
+  const section = (sec, i) =>
+    h(
+      "div",
+      { key: sec.id || i, className: "scalio-nav-section", "data-section": sec.id },
+      sec.label ? h("div", { className: cx("scalio-nav-heading", sec.tone && `is-${sec.tone}`) }, sec.label) : null,
+      sec.items.map((item) => h(NavItem, { key: item.to, item, link, activePath, onNavigate, testIdPrefix: prefix }))
+    );
   return h(
     "nav",
     {
@@ -119,18 +134,9 @@ function Sidebar(props) {
     top ? h("div", { className: "scalio-sidebar-top" }, top) : null,
     h(SearchButton, { search, lang, labels, testIdPrefix: prefix, onNavigate }),
     h(PrimaryAction, { action: primaryAction, link, onNavigate, testIdPrefix: prefix }),
-    h(
-      "div",
-      { className: "scalio-sidebar-scroll" },
-      sections.map((sec, i) =>
-        h(
-          "div",
-          { key: sec.id || i, className: "scalio-nav-section", "data-section": sec.id },
-          sec.label ? h("div", { className: cx("scalio-nav-heading", sec.tone && `is-${sec.tone}`) }, sec.label) : null,
-          sec.items.map((item) => h(NavItem, { key: item.to, item, link, activePath, onNavigate, testIdPrefix: prefix }))
-        )
-      )
-    ),
+    pinned ? h("div", { className: "scalio-sidebar-pinned" }, section(pinned, 0)) : null,
+    slot ? h(ActionSlot, { testId: `${prefix}action-slot` }) : null,
+    h("div", { className: cx("scalio-sidebar-scroll", slot && "has-action-slot") }, rest.map(section)),
     footer || version
       ? h(
           "div",

package/shell.css

@@ -102,6 +102,7 @@ a.scalio-btn { text-decoration: none; }
 @media (min-width: 640px) { .scalio-page-title { font-size: 1.875rem; } }
 .scalio-page-subtitle { margin: 0.25rem 0 0; font-size: 0.875rem; color: hsl(var(--muted-foreground)); }
 .scalio-page-actions { display: flex; flex-wrap: wrap; align-items: center; gap: 0.5rem; }
+.scalio-page-actions:empty { display: none; }
 
 .scalio-version {
   padding: 0.5rem 0.75rem; font-family: 'JetBrains Mono', monospace; font-size: 10px;