@protolabsai/ui 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protolabsai/ui",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/src/AppShell.full.stories.tsx

@@ -0,0 +1,128 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import { AppShell, Button, MobileNav, PanelHeader, SurfaceRail } from "./index";
+import type { MobileItem, RailItem } from "./index";
+
+const meta: Meta = { title: "Components/AppShell" };
+export default meta;
+type Story = StoryObj;
+
+const G = () => (
+  <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5">
+    <rect x="2.5" y="2.5" width="11" height="11" rx="2" />
+  </svg>
+);
+
+const LEFT: RailItem[] = [
+  { id: "chat", label: "Chat", icon: <G />, dot: true },
+  { id: "activity", label: "Activity", icon: <G />, badge: 12 },
+  { id: "flows", label: "Flows", icon: <G /> },
+  { id: "knowledge", label: "Know", icon: <G /> },
+];
+const RIGHT: RailItem[] = [
+  { id: "inbox", label: "Inbox", icon: <G />, badge: 3 },
+  { id: "telemetry", label: "Stats", icon: <G /> },
+];
+
+const surfaceBody = (label: string) => (
+  <div style={{ flex: 1, padding: 16, color: "var(--pl-color-fg-muted)", fontSize: 13, fontFamily: "var(--pl-font-mono)" }}>
+    {label} surface content…
+  </div>
+);
+
+export const Full: Story = {
+  render: () => {
+    function Demo() {
+      const [activeLeft, setActiveLeft] = useState("chat");
+      const [activeRight, setActiveRight] = useState("inbox");
+      const [rightWidth, setRightWidth] = useState(360);
+      const [collapsed, setCollapsed] = useState(false);
+      const mobile: MobileItem[] = [...LEFT, ...RIGHT].map((i) => ({ id: i.id, label: i.label, icon: i.icon }));
+      return (
+        <div style={{ height: 480, border: "1px solid var(--pl-color-border)", borderRadius: 4, overflow: "hidden" }}>
+          <AppShell
+            leftItems={LEFT}
+            rightItems={RIGHT}
+            activeLeft={activeLeft}
+            activeRight={activeRight}
+            onSelect={(side, id) => {
+              if (side === "left") setActiveLeft(id);
+              else {
+                setActiveRight(id);
+                setCollapsed(false);
+              }
+            }}
+            rightWidth={rightWidth}
+            onRightWidthChange={setRightWidth}
+            rightCollapsed={collapsed}
+            onCollapse={setCollapsed}
+            leftContent={
+              <>
+                <PanelHeader title={activeLeft} actions={<Button size="sm">Action</Button>} />
+                {surfaceBody(activeLeft)}
+              </>
+            }
+            rightContent={
+              <>
+                <PanelHeader
+                  compact
+                  title={activeRight}
+                  actions={
+                    <Button size="sm" variant="ghost" onClick={() => setCollapsed(true)}>
+                      Collapse
+                    </Button>
+                  }
+                />
+                {surfaceBody(activeRight)}
+              </>
+            }
+            mobileItems={mobile}
+            mobileActiveId={activeLeft}
+            onMobileSelect={setActiveLeft}
+            quickBarIds={["chat", "activity", "flows", "inbox", "telemetry"]}
+          />
+        </div>
+      );
+    }
+    return <Demo />;
+  },
+};
+
+export const Rail: Story = {
+  render: () => {
+    function Demo() {
+      const [active, setActive] = useState("activity");
+      return (
+        <div style={{ height: 320, width: 64, border: "1px solid var(--pl-color-border)", borderRadius: 4 }}>
+          <SurfaceRail
+            side="left"
+            ariaLabel="Surfaces"
+            items={LEFT}
+            activeId={active}
+            onSelect={setActive}
+            onContextMenu={(e) => e.preventDefault()}
+          />
+        </div>
+      );
+    }
+    return <Demo />;
+  },
+};
+
+export const Mobile: Story = {
+  render: () => {
+    function Demo() {
+      const [active, setActive] = useState("chat");
+      const mobile: MobileItem[] = [...LEFT, ...RIGHT].map((i) => ({ id: i.id, label: i.label, icon: i.icon }));
+      return (
+        <div style={{ width: 360, border: "1px solid var(--pl-color-border)", borderRadius: 4 }}>
+          <div style={{ height: 220, padding: 16, color: "var(--pl-color-fg-muted)", fontFamily: "var(--pl-font-mono)", fontSize: 13 }}>
+            {active} surface — tap “More” for the full list
+          </div>
+          <MobileNav items={mobile} activeId={active} onSelect={setActive} quickBarIds={["chat", "activity", "flows", "inbox"]} />
+        </div>
+      );
+    }
+    return <Demo />;
+  },
+};

package/src/index.tsx

@@ -7,6 +7,9 @@ import type {
   ButtonHTMLAttributes,
   HTMLAttributes,
   InputHTMLAttributes,
+  KeyboardEvent as ReactKeyboardEvent,
+  MouseEvent as ReactMouseEvent,
+  PointerEvent as ReactPointerEvent,
   ReactNode,
   RefObject,
   SelectHTMLAttributes,
@@ -1022,3 +1025,305 @@ export function Skeleton({
 export function SkeletonGroup({ className, ...rest }: HTMLAttributes<HTMLDivElement>) {
   return <div className={cx("pl-skel-group", className)} {...rest} />;
 }
+
+// ── App shell (SurfaceRail · MobileNav · AppShell) ───────────────────────────
+// The operator-console shell, converged from protoAgent's production ADR 0035
+// dual-rail layout. All three are dumb + props-driven; persistence (rail order,
+// widths, active surfaces) stays app-side — AppShell is controlled.
+
+export type RailItem = {
+  id: string;
+  label: string;
+  icon: ReactNode;
+  /** Count badge (caps at "9+"). Mutually exclusive with `dot`. */
+  badge?: number;
+  /** Pulsing indicator, no count (e.g. a background stream). */
+  dot?: boolean;
+};
+
+/** Vertical icon rail — both the left and right rails render through this.
+ *  `onContextMenu` is the integration point for the DS `Menu` (right-click →
+ *  host calls menuRef.open({x,y})); the menu's registry/keying stays app-side. */
+export function SurfaceRail({
+  side,
+  ariaLabel,
+  items,
+  activeId,
+  onSelect,
+  onContextMenu,
+}: {
+  side: "left" | "right";
+  ariaLabel: string;
+  items: RailItem[];
+  activeId: string;
+  onSelect: (id: string) => void;
+  onContextMenu?: (e: ReactMouseEvent, id: string) => void;
+}) {
+  return (
+    <aside className={cx("pl-rail", side === "right" && "pl-rail--right")} aria-label={ariaLabel}>
+      {items.map((it) => (
+        <button
+          key={it.id}
+          type="button"
+          className={cx("pl-rail__btn", it.id === activeId && "pl-rail__btn--active")}
+          title={it.label}
+          aria-label={it.label}
+          aria-current={it.id === activeId ? "page" : undefined}
+          onClick={() => onSelect(it.id)}
+          onContextMenu={onContextMenu ? (e) => onContextMenu(e, it.id) : undefined}
+        >
+          <span className="pl-rail__icon" aria-hidden>
+            {it.icon}
+          </span>
+          <span className="pl-rail__label">{it.label}</span>
+          {it.badge ? (
+            <span className="pl-rail__badge">{it.badge > 9 ? "9+" : it.badge}</span>
+          ) : it.dot ? (
+            <span className="pl-rail__dot" aria-label="active" />
+          ) : null}
+        </button>
+      ))}
+    </aside>
+  );
+}
+
+export type MobileItem = { id: string; label: string; icon: ReactNode };
+
+/** Mobile shell (<768px): a bottom quick-bar (first 5 pinned surfaces) + a
+ *  "More" button that opens the full surface list in a DS `Drawer`. */
+export function MobileNav({
+  items,
+  activeId,
+  onSelect,
+  quickBarIds,
+}: {
+  items: MobileItem[];
+  activeId: string;
+  onSelect: (id: string) => void;
+  /** Surfaces pinned to the bottom bar (first 5 used). */
+  quickBarIds: string[];
+}) {
+  const [open, setOpen] = useState(false);
+  const byId = new Map(items.map((i) => [i.id, i] as const));
+  const quick = quickBarIds
+    .map((id) => byId.get(id))
+    .filter((i): i is MobileItem => Boolean(i))
+    .slice(0, 5);
+  const pick = (id: string) => {
+    onSelect(id);
+    setOpen(false);
+  };
+  return (
+    <>
+      <nav className="pl-mobilenav" aria-label="Quick surfaces">
+        {quick.map((it) => (
+          <button
+            key={it.id}
+            type="button"
+            className={cx("pl-mobilenav__tab", it.id === activeId && "pl-mobilenav__tab--active")}
+            onClick={() => pick(it.id)}
+          >
+            <span className="pl-mobilenav__icon" aria-hidden>
+              {it.icon}
+            </span>
+            <span>{it.label}</span>
+          </button>
+        ))}
+        <button type="button" className="pl-mobilenav__tab" onClick={() => setOpen(true)} aria-label="All surfaces">
+          <span className="pl-mobilenav__icon" aria-hidden>
+            <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round">
+              <path d="M3 6h18M3 12h18M3 18h18" />
+            </svg>
+          </span>
+          <span>More</span>
+        </button>
+      </nav>
+      <Drawer open={open} onClose={() => setOpen(false)} side="right" title="Surfaces" width={280}>
+        <div className="pl-mobilenav__list">
+          {items.map((it) => (
+            <button
+              key={it.id}
+              type="button"
+              className={cx("pl-mobilenav__list-item", it.id === activeId && "pl-mobilenav__list-item--active")}
+              onClick={() => pick(it.id)}
+            >
+              <span className="pl-mobilenav__icon" aria-hidden>
+                {it.icon}
+              </span>
+              <span>{it.label}</span>
+            </button>
+          ))}
+        </div>
+      </Drawer>
+    </>
+  );
+}
+
+/** True below `breakpoint` px (client-only; false on first paint). */
+function useIsMobile(breakpoint: number) {
+  const [mobile, setMobile] = useState(false);
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return;
+    const mq = window.matchMedia(`(max-width: ${breakpoint - 1}px)`);
+    const update = () => setMobile(mq.matches);
+    update();
+    mq.addEventListener("change", update);
+    return () => mq.removeEventListener("change", update);
+  }, [breakpoint]);
+  return mobile;
+}
+
+export type AppShellProps = {
+  leftItems: RailItem[];
+  rightItems: RailItem[];
+  activeLeft: string;
+  activeRight: string;
+  onSelect: (side: "left" | "right", id: string) => void;
+  /** Right-click on a rail icon — wire to a DS `Menu` for move/reorder etc. */
+  onRailContextMenu?: (side: "left" | "right", e: ReactMouseEvent, id: string) => void;
+  leftContent: ReactNode;
+  rightContent: ReactNode;
+  /** Controlled right-column width (px). */
+  rightWidth: number;
+  onRightWidthChange: (width: number) => void;
+  rightCollapsed?: boolean;
+  onCollapse?: (collapsed: boolean) => void;
+  minRightWidth?: number;
+  maxRightWidth?: number;
+  /** Mobile (<breakpoint) config. Omit to disable the mobile shell. */
+  mobileItems?: MobileItem[];
+  mobileActiveId?: string;
+  onMobileSelect?: (id: string) => void;
+  quickBarIds?: string[];
+  mobileBreakpoint?: number;
+  className?: string;
+};
+
+/** The full dual-rail operator shell:
+ *  `[left rail][left column][resize handle][right column][right rail]`,
+ *  collapsing to `MobileNav` below `mobileBreakpoint`. Controlled — the host
+ *  owns the surface registry and persists rail order / widths / active state. */
+export function AppShell({
+  leftItems,
+  rightItems,
+  activeLeft,
+  activeRight,
+  onSelect,
+  onRailContextMenu,
+  leftContent,
+  rightContent,
+  rightWidth,
+  onRightWidthChange,
+  rightCollapsed = false,
+  onCollapse,
+  minRightWidth = 280,
+  maxRightWidth = 720,
+  mobileItems,
+  mobileActiveId,
+  onMobileSelect,
+  quickBarIds,
+  mobileBreakpoint = 768,
+  className,
+}: AppShellProps) {
+  const isMobile = useIsMobile(mobileBreakpoint);
+  const drag = useRef<{ startX: number; startW: number } | null>(null);
+  const clamp = useCallback(
+    (w: number) => Math.min(maxRightWidth, Math.max(minRightWidth, w)),
+    [minRightWidth, maxRightWidth],
+  );
+
+  const onPointerDown = useCallback(
+    (e: ReactPointerEvent<HTMLDivElement>) => {
+      e.preventDefault();
+      drag.current = { startX: e.clientX, startW: rightWidth };
+      e.currentTarget.setPointerCapture(e.pointerId);
+    },
+    [rightWidth],
+  );
+  const onPointerMove = useCallback(
+    (e: ReactPointerEvent<HTMLDivElement>) => {
+      if (!drag.current) return;
+      onRightWidthChange(clamp(drag.current.startW + (drag.current.startX - e.clientX)));
+    },
+    [clamp, onRightWidthChange],
+  );
+  const onPointerUp = useCallback((e: ReactPointerEvent<HTMLDivElement>) => {
+    drag.current = null;
+    e.currentTarget.releasePointerCapture?.(e.pointerId);
+  }, []);
+  const onKeyDown = useCallback(
+    (e: ReactKeyboardEvent<HTMLDivElement>) => {
+      const step = e.shiftKey ? 48 : 16;
+      if (e.key === "ArrowLeft") {
+        e.preventDefault();
+        onRightWidthChange(clamp(rightWidth + step));
+      } else if (e.key === "ArrowRight") {
+        e.preventDefault();
+        onRightWidthChange(clamp(rightWidth - step));
+      }
+    },
+    [rightWidth, clamp, onRightWidthChange],
+  );
+
+  if (isMobile && mobileItems && onMobileSelect && quickBarIds) {
+    return (
+      <div className={cx("pl-appshell", "pl-appshell--mobile", className)}>
+        <div className="pl-appshell__mobile-stage">{leftContent}</div>
+        <MobileNav
+          items={mobileItems}
+          activeId={mobileActiveId ?? activeLeft}
+          onSelect={onMobileSelect}
+          quickBarIds={quickBarIds}
+        />
+      </div>
+    );
+  }
+
+  const showRight = !rightCollapsed && rightItems.length > 0;
+  return (
+    <div className={cx("pl-appshell", className)}>
+      <SurfaceRail
+        side="left"
+        ariaLabel="Left surfaces"
+        items={leftItems}
+        activeId={activeLeft}
+        onSelect={(id) => onSelect("left", id)}
+        onContextMenu={onRailContextMenu ? (e, id) => onRailContextMenu("left", e, id) : undefined}
+      />
+      <main className="pl-appshell__col pl-appshell__col--left">{leftContent}</main>
+      {showRight && (
+        <div
+          className="pl-appshell__handle"
+          role="separator"
+          aria-orientation="vertical"
+          aria-label="Resize right panel"
+          aria-valuenow={rightWidth}
+          aria-valuemin={minRightWidth}
+          aria-valuemax={maxRightWidth}
+          tabIndex={0}
+          onPointerDown={onPointerDown}
+          onPointerMove={onPointerMove}
+          onPointerUp={onPointerUp}
+          onKeyDown={onKeyDown}
+          onDoubleClick={() => onCollapse?.(true)}
+        />
+      )}
+      {showRight && (
+        <aside
+          className="pl-appshell__col pl-appshell__col--right"
+          style={{ flex: `0 0 ${rightWidth}px`, width: rightWidth }}
+        >
+          {rightContent}
+        </aside>
+      )}
+      <SurfaceRail
+        side="right"
+        ariaLabel="Right surfaces"
+        items={rightItems}
+        activeId={activeRight}
+        onSelect={(id) => onSelect("right", id)}
+        onContextMenu={onRailContextMenu ? (e, id) => onRailContextMenu("right", e, id) : undefined}
+      />
+    </div>
+  );
+}

package/src/styles.css

@@ -1275,6 +1275,193 @@ a.pl-row:hover {
   color: var(--pl-color-fg-muted);
 }
 
+/* ── SurfaceRail (icon rail) ─────────────────────────────────────────────────── */
+.pl-rail {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  gap: 2px;
+  width: 64px;
+  flex-shrink: 0;
+  padding: 6px;
+  background: var(--pl-color-bg-raised);
+  border-right: var(--pl-border-width) solid var(--pl-color-border);
+}
+.pl-rail--right {
+  border-right: none;
+  border-left: var(--pl-border-width) solid var(--pl-color-border);
+}
+.pl-rail__btn {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 3px;
+  padding: 8px 2px;
+  background: none;
+  border: none;
+  border-radius: var(--pl-radius);
+  color: var(--pl-color-fg-muted);
+  cursor: pointer;
+  font: inherit;
+  transition:
+    background var(--pl-motion-fast) var(--pl-motion-ease),
+    color var(--pl-motion-fast) var(--pl-motion-ease);
+}
+.pl-rail__btn:hover {
+  background: var(--pl-color-bg-hover);
+  color: var(--pl-color-fg);
+}
+.pl-rail__btn--active {
+  background: var(--pl-color-bg-subtle);
+  color: var(--pl-color-fg);
+}
+.pl-rail__icon {
+  display: inline-flex;
+}
+.pl-rail__icon svg {
+  width: 18px;
+  height: 18px;
+}
+.pl-rail__label {
+  max-width: 100%;
+  overflow: hidden;
+  font-size: 9px;
+  line-height: 1.1;
+  text-align: center;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.pl-rail__badge {
+  position: absolute;
+  top: 4px;
+  right: 9px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 15px;
+  height: 15px;
+  padding: 0 4px;
+  font-family: var(--pl-font-mono);
+  font-size: 9px;
+  color: var(--pl-color-fg);
+  background: var(--pl-color-bg-subtle);
+  border: var(--pl-border-width) solid var(--pl-color-border-strong);
+  border-radius: 999px;
+}
+.pl-rail__dot {
+  position: absolute;
+  top: 6px;
+  right: 14px;
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  background: var(--pl-color-status-info);
+  animation: pl-dot-pulse var(--pl-motion-status) var(--pl-motion-ease-in-out) infinite;
+}
+
+/* ── MobileNav (bottom bar + drawer list) ────────────────────────────────────── */
+.pl-mobilenav {
+  display: flex;
+  align-items: stretch;
+  background: var(--pl-color-bg-raised);
+  border-top: var(--pl-border-width) solid var(--pl-color-border);
+}
+.pl-mobilenav__tab {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 3px;
+  padding: 8px 2px;
+  background: none;
+  border: none;
+  color: var(--pl-color-fg-muted);
+  font: inherit;
+  font-size: 10px;
+  cursor: pointer;
+}
+.pl-mobilenav__tab--active {
+  color: var(--pl-color-fg);
+}
+.pl-mobilenav__icon {
+  display: inline-flex;
+}
+.pl-mobilenav__icon svg {
+  width: 18px;
+  height: 18px;
+}
+.pl-mobilenav__list {
+  display: grid;
+  gap: 2px;
+}
+.pl-mobilenav__list-item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  padding: 10px 8px;
+  background: none;
+  border: none;
+  border-radius: var(--pl-radius);
+  color: var(--pl-color-fg);
+  font: inherit;
+  font-size: 14px;
+  text-align: left;
+  cursor: pointer;
+}
+.pl-mobilenav__list-item:hover {
+  background: var(--pl-color-bg-hover);
+}
+.pl-mobilenav__list-item--active {
+  background: var(--pl-color-bg-subtle);
+}
+
+/* ── AppShell (dual-rail + 3-column) ─────────────────────────────────────────── */
+.pl-appshell {
+  display: flex;
+  align-items: stretch;
+  height: 100%;
+  min-height: 0;
+  background: var(--pl-color-bg);
+  color: var(--pl-color-fg);
+}
+.pl-appshell__col {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+}
+.pl-appshell__col--left {
+  flex: 1 1 auto;
+}
+.pl-appshell__col--right {
+  flex: 0 0 auto;
+  border-left: var(--pl-border-width) solid var(--pl-color-border);
+}
+.pl-appshell__handle {
+  flex: 0 0 auto;
+  width: 5px;
+  cursor: col-resize;
+  background: transparent;
+  touch-action: none;
+  transition: background var(--pl-motion-fast) var(--pl-motion-ease);
+}
+.pl-appshell__handle:hover,
+.pl-appshell__handle:focus-visible {
+  background: var(--pl-color-border-strong);
+  outline: none;
+}
+.pl-appshell--mobile {
+  flex-direction: column;
+}
+.pl-appshell__mobile-stage {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow: auto;
+}
+
 /* ── Skeleton (loading placeholder) ──────────────────────────────────────────── */
 .pl-skel {
   display: block;
@@ -1311,6 +1498,7 @@ a.pl-row:hover {
   .pl-drawer,
   .pl-toast,
   .pl-dot--pulse,
+  .pl-rail__dot,
   .pl-spinner {
     animation: none;
   }