@cosmicdrift/kumiko-renderer-web 0.178.1 → 0.181.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.178.1",
+  "version": "0.181.0",
   "description": "Web-platform bindings for @cosmicdrift/kumiko-renderer. HTML default-primitives, browser history-based navigation, EventSource-backed live events, and a one-call createKumikoApp that mounts the whole stack via react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -16,9 +16,9 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.178.1",
-    "@cosmicdrift/kumiko-headless": "0.178.1",
-    "@cosmicdrift/kumiko-renderer": "0.178.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.181.0",
+    "@cosmicdrift/kumiko-headless": "0.181.0",
+    "@cosmicdrift/kumiko-renderer": "0.181.0",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.8",

package/src/index.ts

@@ -114,6 +114,7 @@ export type { SidebarProps } from "./layout/sidebar";
 export { Sidebar } from "./layout/sidebar";
 export type { SidebarBrandProps } from "./layout/sidebar-brand";
 export { SidebarBrand } from "./layout/sidebar-brand";
+export { SidebarPanel } from "./layout/sidebar-panel";
 export type { SidebarUserProps } from "./layout/sidebar-user";
 export { SidebarUser } from "./layout/sidebar-user";
 export { parseTargetFromSearchParams } from "./layout/target-url";

package/src/layout/default-app-shell.tsx

@@ -33,6 +33,7 @@ import {
 import { fillClasses } from "./fill-classes";
 import { NavTree } from "./nav-tree";
 import { ShellHeader } from "./shell-header";
+import { SidebarPanelProvider, useSidebarPanelHost } from "./sidebar-panel";
 
 export type DefaultAppShellUser = {
   readonly id: string;
@@ -85,42 +86,52 @@ export function DefaultAppShell({
   children,
 }: DefaultAppShellProps): ReactNode {
   const fillCls = fillClasses(fill);
+  // Second column only when a screen fills it (sidebar-09 pattern) — otherwise
+  // every other screen would carry an empty strip next to the navigation.
+  const panel = useSidebarPanelHost();
   return (
     <SidebarProvider {...fillCls.provider}>
-      {/* sidebar-07-Muster: Standard-Variante (border-r, flush content) +
+      <SidebarPanelProvider value={panel.value}>
+        {/* sidebar-07-Muster: Standard-Variante (border-r, flush content) +
           collapsible="icon" — der Rail klappt auf Icon-Breite zu (Trigger/Rail). */}
-      <Sidebar collapsible="icon">
-        <SidebarHeader data-kumiko-layout="sidebar-header">{brand}</SidebarHeader>
-        {sidebarActions !== undefined && (
-          <SidebarGroup
-            data-kumiko-layout="sidebar-actions"
-            className="flex-row items-center gap-1 py-0"
-          >
-            {sidebarActions}
-          </SidebarGroup>
-        )}
-        <SidebarContent data-kumiko-layout="sidebar-nav">
-          <NavTree
+        <Sidebar collapsible="icon">
+          <SidebarHeader data-kumiko-layout="sidebar-header">{brand}</SidebarHeader>
+          {sidebarActions !== undefined && (
+            <SidebarGroup
+              data-kumiko-layout="sidebar-actions"
+              className="flex-row items-center gap-1 py-0"
+            >
+              {sidebarActions}
+            </SidebarGroup>
+          )}
+          <SidebarContent data-kumiko-layout="sidebar-nav">
+            <NavTree
+              schema={schema}
+              {...(user !== undefined && { user })}
+              {...(navBadges !== undefined && { navBadges })}
+            />
+          </SidebarContent>
+          {sidebarFooter !== undefined && (
+            <SidebarFooter data-kumiko-layout="sidebar-footer">{sidebarFooter}</SidebarFooter>
+          )}
+          <SidebarRail />
+        </Sidebar>
+        <div
+          ref={panel.ref}
+          data-kumiko-layout="sidebar-panel"
+          className={panel.occupied ? "flex h-svh shrink-0 flex-col" : "hidden"}
+        />
+        <SidebarInset className={fillCls.inset}>
+          <ShellHeader
             schema={schema}
             {...(user !== undefined && { user })}
-            {...(navBadges !== undefined && { navBadges })}
+            {...(headerActions !== undefined && { headerActions })}
           />
-        </SidebarContent>
-        {sidebarFooter !== undefined && (
-          <SidebarFooter data-kumiko-layout="sidebar-footer">{sidebarFooter}</SidebarFooter>
-        )}
-        <SidebarRail />
-      </Sidebar>
-      <SidebarInset className={fillCls.inset}>
-        <ShellHeader
-          schema={schema}
-          {...(user !== undefined && { user })}
-          {...(headerActions !== undefined && { headerActions })}
-        />
-        <main className={fillCls.main}>
-          <UserRolesProvider roles={user?.roles}>{children}</UserRolesProvider>
-        </main>
-      </SidebarInset>
+          <main className={fillCls.main}>
+            <UserRolesProvider roles={user?.roles}>{children}</UserRolesProvider>
+          </main>
+        </SidebarInset>
+      </SidebarPanelProvider>
     </SidebarProvider>
   );
 }

package/src/layout/nav-tree.tsx

@@ -147,6 +147,8 @@ const NAV_ICONS: Readonly<Record<string, typeof Folder>> = {
   hash: Hash,
   download: Download,
   rocket: Rocket,
+  // Was imported but never registered — `icon: "plus"` silently fell back.
+  plus: Plus,
 };
 
 export type NavTreeProps = {
@@ -309,23 +311,44 @@ function NavLeadingIcon({
   node,
   active,
   expanded = false,
+  label,
 }: {
   node: NavNode;
   active: boolean;
   expanded?: boolean;
+  /** Only needed for the rail fallback — see below. */
+  label?: string;
 }): ReactNode {
   const iconKey = expanded && node.icon === "folder" ? "folder-open" : node.icon;
   const NavIcon =
     iconKey !== undefined && Object.hasOwn(NAV_ICONS, iconKey) ? NAV_ICONS[iconKey] : undefined;
   if (NavIcon !== undefined) return <NavIcon aria-hidden="true" className="shrink-0" />;
+  const initial = label?.trim().charAt(0).toUpperCase();
   return (
-    <span
-      aria-hidden="true"
-      className={cn(
-        "inline-block size-1.5 rounded-full",
-        active ? "bg-sidebar-accent-foreground" : "bg-sidebar-foreground/40",
+    <>
+      {/* Expanded, a dot is enough: the label sits next to it and carries the
+          meaning. Collapsed the dot is worthless — a rail of identical dots says
+          nothing about what you are clicking. There the initial takes its place
+          until the app sets an icon. */}
+      <span
+        aria-hidden="true"
+        className={cn(
+          "inline-block size-1.5 shrink-0 rounded-full group-data-[collapsible=icon]:hidden",
+          active ? "bg-sidebar-accent-foreground" : "bg-sidebar-foreground/40",
+        )}
+      />
+      {initial !== undefined && initial !== "" && (
+        <span
+          aria-hidden="true"
+          className={cn(
+            "hidden size-4 shrink-0 items-center justify-center font-medium text-xs group-data-[collapsible=icon]:flex",
+            active ? "text-sidebar-accent-foreground" : "text-sidebar-foreground/70",
+          )}
+        >
+          {initial}
+        </span>
       )}
-    />
+    </>
   );
 }
 
@@ -645,8 +668,10 @@ function NavMenuNode({ node, collapsed, onToggle }: NavSubProps): ReactNode {
             to={{ ...(s.workspaceId !== undefined && { workspaceId: s.workspaceId }), screenId }}
             {...(s.active && { "aria-current": "page" })}
           >
-            <NavLeadingIcon node={node} active={s.active} />
-            <span className="min-w-0 truncate">{s.displayLabel}</span>
+            <NavLeadingIcon node={node} active={s.active} label={s.displayLabel} />
+            <span className="min-w-0 truncate group-data-[collapsible=icon]:hidden">
+              {s.displayLabel}
+            </span>
             <NavBadge node={node} />
           </KumikoLink>
         </SidebarMenuButton>
@@ -666,8 +691,10 @@ function NavMenuNode({ node, collapsed, onToggle }: NavSubProps): ReactNode {
           tooltip={s.displayLabel}
           onClick={() => dispatch(target)}
         >
-          <NavLeadingIcon node={node} active={s.active} />
-          <span className="min-w-0 truncate">{s.displayLabel}</span>
+          <NavLeadingIcon node={node} active={s.active} label={s.displayLabel} />
+          <span className="min-w-0 truncate group-data-[collapsible=icon]:hidden">
+            {s.displayLabel}
+          </span>
           <NavBadge node={node} />
         </SidebarMenuButton>
         <NodeActions node={node} />
@@ -685,8 +712,8 @@ function NavMenuNode({ node, collapsed, onToggle }: NavSubProps): ReactNode {
         }}
         {...(s.expandable && { "aria-expanded": s.isExpanded })}
       >
-        <NavLeadingIcon node={node} active={false} expanded={s.isExpanded} />
-        <span className="truncate">{s.displayLabel}</span>
+        <NavLeadingIcon node={node} active={false} expanded={s.isExpanded} label={s.displayLabel} />
+        <span className="truncate group-data-[collapsible=icon]:hidden">{s.displayLabel}</span>
         {s.expandable &&
           (s.isExpanded ? (
             <ChevronDown className="ml-auto" />
@@ -753,8 +780,10 @@ function NavSubNode({ node, collapsed, onToggle }: NavSubProps): ReactNode {
             to={{ ...(s.workspaceId !== undefined && { workspaceId: s.workspaceId }), screenId }}
             {...(s.active && { "aria-current": "page" })}
           >
-            <NavLeadingIcon node={node} active={s.active} />
-            <span className="min-w-0 truncate">{s.displayLabel}</span>
+            <NavLeadingIcon node={node} active={s.active} label={s.displayLabel} />
+            <span className="min-w-0 truncate group-data-[collapsible=icon]:hidden">
+              {s.displayLabel}
+            </span>
             <NavBadge node={node} />
           </KumikoLink>
         </SidebarMenuSubButton>
@@ -771,8 +800,10 @@ function NavSubNode({ node, collapsed, onToggle }: NavSubProps): ReactNode {
       <SidebarMenuSubItem>
         <SidebarMenuSubButton asChild isActive={s.active}>
           <button type="button" onClick={() => dispatch(target)}>
-            <NavLeadingIcon node={node} active={s.active} />
-            <span className="min-w-0 truncate">{s.displayLabel}</span>
+            <NavLeadingIcon node={node} active={s.active} label={s.displayLabel} />
+            <span className="min-w-0 truncate group-data-[collapsible=icon]:hidden">
+              {s.displayLabel}
+            </span>
             <NavBadge node={node} />
           </button>
         </SidebarMenuSubButton>
@@ -792,8 +823,13 @@ function NavSubNode({ node, collapsed, onToggle }: NavSubProps): ReactNode {
             if (s.expandable) onToggle(node.qualifiedName);
           }}
         >
-          <NavLeadingIcon node={node} active={false} expanded={s.isExpanded} />
-          <span className="truncate">{s.displayLabel}</span>
+          <NavLeadingIcon
+            node={node}
+            active={false}
+            expanded={s.isExpanded}
+            label={s.displayLabel}
+          />
+          <span className="truncate group-data-[collapsible=icon]:hidden">{s.displayLabel}</span>
         </button>
       </SidebarMenuSubButton>
       <NodeActions node={node} />

package/src/layout/sidebar-panel.tsx

@@ -0,0 +1,177 @@
+// A second sidebar column for screens that need a list next to the navigation
+// rather than inside the content — the shadcn `sidebar-09` pattern (mail
+// client) against the `sidebar-07` the shell otherwise runs.
+//
+// Why a slot and not a screen layout: the area sits outside the `SidebarInset`
+// and therefore above the ShellHeader. A screen renders by definition *into*
+// the content, below the header, and cannot reach that spot from there. The
+// slot inverts the direction: the shell holds the space, the screen fills it
+// through a portal and stays an ordinary screen otherwise.
+//
+// With no screen filling it the shell does not render the space at all — no
+// empty strip on every other screen.
+
+import {
+  createContext,
+  type ReactNode,
+  type PointerEvent as ReactPointerEvent,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import { createPortal } from "react-dom";
+import { cn } from "../lib/cn";
+
+type SlotElement = HTMLElement | null;
+
+type SidebarPanelSlot = {
+  readonly element: SlotElement;
+  /** Tells the shell state whether a screen is currently claiming the space. */
+  readonly setOccupied: (occupied: boolean) => void;
+};
+
+const SidebarPanelContext = createContext<SidebarPanelSlot | null>(null);
+
+export const SidebarPanelProvider = SidebarPanelContext.Provider;
+
+/** Shells only — screens use `SidebarPanel`. */
+export function useSidebarPanelSlot(): SidebarPanelSlot | null {
+  return useContext(SidebarPanelContext);
+}
+
+export type SidebarPanelProps = {
+  readonly children: ReactNode;
+  /** Initial width in px. After the first drag the stored width wins. */
+  readonly defaultWidth?: number;
+  readonly minWidth?: number;
+  readonly maxWidth?: number;
+  /** localStorage key for the dragged width. Without a key nothing is stored —
+   *  two screens with their own list should not overwrite each other's width. */
+  readonly storageKey?: string;
+  readonly className?: string;
+};
+
+const DEFAULT_WIDTH = 340;
+const DEFAULT_MIN = 260;
+const DEFAULT_MAX = 640;
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+function readStoredWidth(key: string | undefined): number | null {
+  if (key === undefined || typeof window === "undefined") return null;
+  const raw = window.localStorage.getItem(key);
+  if (raw === null) return null;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+/** Renders its children into the second sidebar column when the shell offers
+ *  one. When it does not (public surface, tests, an older shell) the children
+ *  land in place — the screen stays usable instead of losing its list.
+ *
+ *  The width drags like in any mail client: the handle sits on the divider and
+ *  the result survives a reload (with `storageKey`). */
+export function SidebarPanel({
+  children,
+  defaultWidth = DEFAULT_WIDTH,
+  minWidth = DEFAULT_MIN,
+  maxWidth = DEFAULT_MAX,
+  storageKey,
+  className,
+}: SidebarPanelProps): ReactNode {
+  const slot = useSidebarPanelSlot();
+  const setOccupied = slot?.setOccupied;
+  const [width, setWidth] = useState<number>(() =>
+    clamp(readStoredWidth(storageKey) ?? defaultWidth, minWidth, maxWidth),
+  );
+  const dragging = useRef(false);
+
+  useEffect(() => {
+    if (setOccupied === undefined) return;
+    setOccupied(true);
+    return () => setOccupied(false);
+  }, [setOccupied]);
+
+  // Listeners on window, not on the handle: a fast drag leaves the 4px strip
+  // between two frames, and a handler on the element would lose the drag there.
+  useEffect(() => {
+    const onMove = (event: PointerEvent) => {
+      if (!dragging.current) return;
+      event.preventDefault();
+      setWidth(clamp(event.clientX, minWidth, maxWidth));
+    };
+    const onUp = () => {
+      if (!dragging.current) return;
+      dragging.current = false;
+      document.body.style.removeProperty("cursor");
+      document.body.style.removeProperty("user-select");
+    };
+    window.addEventListener("pointermove", onMove);
+    window.addEventListener("pointerup", onUp);
+    return () => {
+      window.removeEventListener("pointermove", onMove);
+      window.removeEventListener("pointerup", onUp);
+    };
+  }, [minWidth, maxWidth]);
+
+  useEffect(() => {
+    if (storageKey === undefined || typeof window === "undefined") return;
+    window.localStorage.setItem(storageKey, String(width));
+  }, [storageKey, width]);
+
+  const startDrag = useCallback((event: ReactPointerEvent<HTMLDivElement>) => {
+    event.preventDefault();
+    dragging.current = true;
+    // Set globally while dragging: otherwise the cursor flickers as soon as the
+    // pointer sits over the list instead of the handle, and a drag selects the
+    // row text on the way.
+    document.body.style.setProperty("cursor", "col-resize");
+    document.body.style.setProperty("user-select", "none");
+  }, []);
+
+  const content = (
+    <div
+      data-kumiko-layout="sidebar-panel-body"
+      className={cn(
+        "relative flex h-full shrink-0 flex-col border-sidebar-border border-r bg-sidebar",
+        className,
+      )}
+      style={{ width: `${width}px` }}
+    >
+      {children}
+      {/* No keyboard equivalent on purpose: the width is optional, the content
+          stays fully reachable without ever dragging. */}
+      <div
+        data-kumiko-layout="sidebar-panel-handle"
+        onPointerDown={startDrag}
+        className="absolute inset-y-0 right-0 w-1 cursor-col-resize bg-transparent transition-colors hover:bg-sidebar-border"
+      />
+    </div>
+  );
+
+  if (slot?.element == null) {
+    return content;
+  }
+  return createPortal(content, slot.element);
+}
+
+/** Shell-side counterpart: holds the slot element and the occupied state. Its
+ *  own hook so both shells (WorkspaceShell, DefaultAppShell) share one wiring
+ *  instead of getting the same thing half right twice. */
+export function useSidebarPanelHost(): {
+  readonly occupied: boolean;
+  readonly value: SidebarPanelSlot;
+  readonly ref: (node: SlotElement) => void;
+} {
+  const [element, setElement] = useState<SlotElement>(null);
+  const [occupied, setOccupied] = useState(false);
+  return {
+    occupied,
+    value: { element, setOccupied },
+    ref: setElement,
+  };
+}

package/src/layout/workspace-shell.tsx

@@ -47,6 +47,7 @@ import { EditorPanel } from "./editor-panel";
 import { fillClasses } from "./fill-classes";
 import { lastSegment, NavTree } from "./nav-tree";
 import { ShellHeader } from "./shell-header";
+import { SidebarPanelProvider, useSidebarPanelHost } from "./sidebar-panel";
 import { parseTargetFromSearchParams } from "./target-url";
 import { WorkspaceSwitcher } from "./workspace-switcher";
 
@@ -225,33 +226,43 @@ export function WorkspaceShell({
   // above the content. topbarActions render right inside the header row
   // instead of a separate topbar — one header line, not two.
   const fillCls = fillClasses(fill);
+  // Zweite Spalte nur wenn ein Screen sie fuellt (sidebar-09-Muster) — sonst
+  // stuende auf jedem anderen Screen ein leerer Streifen neben der Navigation.
+  const panel = useSidebarPanelHost();
   return (
     <SidebarProvider {...fillCls.provider}>
-      <Sidebar collapsible="icon">
-        <SidebarHeader data-kumiko-layout="sidebar-header">
-          {brand}
-          {switcher}
-        </SidebarHeader>
-        <SidebarContent data-kumiko-layout="sidebar-nav">{sidebarContent}</SidebarContent>
-        {sidebarFooter !== undefined && (
-          <SidebarFooter data-kumiko-layout="sidebar-footer">{sidebarFooter}</SidebarFooter>
-        )}
-        <SidebarRail />
-      </Sidebar>
-      <SidebarInset className={fillCls.inset}>
-        <ShellHeader
-          schema={app}
-          {...(user !== undefined && { user })}
-          {...(topbarActions !== undefined && { headerActions: topbarActions })}
-        />
-        <main className={fillCls.main}>
-          {activeTarget !== undefined ? (
-            <EditorPanel resolvers={resolvers} />
-          ) : (
-            <UserRolesProvider roles={user?.roles}>{children}</UserRolesProvider>
+      <SidebarPanelProvider value={panel.value}>
+        <Sidebar collapsible="icon">
+          <SidebarHeader data-kumiko-layout="sidebar-header">
+            {brand}
+            {switcher}
+          </SidebarHeader>
+          <SidebarContent data-kumiko-layout="sidebar-nav">{sidebarContent}</SidebarContent>
+          {sidebarFooter !== undefined && (
+            <SidebarFooter data-kumiko-layout="sidebar-footer">{sidebarFooter}</SidebarFooter>
           )}
-        </main>
-      </SidebarInset>
+          <SidebarRail />
+        </Sidebar>
+        <div
+          ref={panel.ref}
+          data-kumiko-layout="sidebar-panel"
+          className={panel.occupied ? "flex h-svh shrink-0 flex-col" : "hidden"}
+        />
+        <SidebarInset className={fillCls.inset}>
+          <ShellHeader
+            schema={app}
+            {...(user !== undefined && { user })}
+            {...(topbarActions !== undefined && { headerActions: topbarActions })}
+          />
+          <main className={fillCls.main}>
+            {activeTarget !== undefined ? (
+              <EditorPanel resolvers={resolvers} />
+            ) : (
+              <UserRolesProvider roles={user?.roles}>{children}</UserRolesProvider>
+            )}
+          </main>
+        </SidebarInset>
+      </SidebarPanelProvider>
     </SidebarProvider>
   );
 }