@protolabsai/ui 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protolabsai/ui",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -31,6 +31,7 @@
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
     "@radix-ui/react-dropdown-menu": "^2.1.17",
+    "@radix-ui/react-popover": "^1.1.16",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@protolabsai/design": "0.5.0"

package/src/AppShell.full.stories.tsx

@@ -1,8 +1,9 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { useState } from "react";
-import { Button } from "./primitives";
+import { Badge, Button } from "./primitives";
 import { PanelHeader } from "./navigation";
-import { AppShell, MobileNav, SurfaceRail } from "./app-shell";
+import { StatusDot } from "./data";
+import { AppShell, MobileNav, SurfaceRail, UtilityBar } from "./app-shell";
 import type { MobileItem, RailItem } from "./app-shell";
 
 const meta: Meta = { title: "Components/AppShell" };
@@ -83,6 +84,19 @@ export const Full: Story = {
                 {surfaceBody(activeRight)}
               </>
             }
+            utilityBar={
+              <UtilityBar
+                start={<StatusDot status="success" pulse label="connected · 3 agents" />}
+                end={
+                  <>
+                    <Button size="sm" variant="ghost">
+                      Docs
+                    </Button>
+                    <Badge status="info">v0.11.0</Badge>
+                  </>
+                }
+              />
+            }
             mobileItems={mobile}
             mobileActiveId={activeLeft}
             onMobileSelect={setActiveLeft}

package/src/Overlays.stories.tsx

@@ -2,12 +2,41 @@ import type { Meta, StoryObj } from "@storybook/react";
 import { useState } from "react";
 import { Button } from "./primitives";
 import { Field } from "./forms";
-import { ConfirmDialog, Dialog, Drawer, Tooltip, ToastProvider, useToast } from "./overlays";
+import { ConfirmDialog, Dialog, Drawer, Popover, PopoverClose, Tooltip, ToastProvider, useToast } from "./overlays";
 
 const meta: Meta = { title: "Components/Overlays" };
 export default meta;
 type Story = StoryObj;
 
+export const PopoverStory: Story = {
+  name: "Popover",
+  render: () => (
+    <div style={{ display: "flex", gap: 40, padding: 40, justifyContent: "center" }}>
+      <Popover trigger={<Button>Filter ▾</Button>}>
+        <div style={{ display: "grid", gap: 10 }}>
+          <Field label="Search" value="" placeholder="agent name…" />
+          <div style={{ display: "flex", justifyContent: "flex-end", gap: 8 }}>
+            <PopoverClose>
+              <Button size="sm" variant="ghost">
+                Cancel
+              </Button>
+            </PopoverClose>
+            <PopoverClose>
+              <Button size="sm" variant="primary">
+                Apply
+              </Button>
+            </PopoverClose>
+          </div>
+        </div>
+      </Popover>
+      <Popover side="right" align="start" trigger={<Button variant="ghost">Details →</Button>}>
+        Anchored floating content — collision-aware, dismiss on outside-click or Esc. The generic
+        primitive under filters, pickers, and comboboxes.
+      </Popover>
+    </div>
+  ),
+};
+
 export const Modal: Story = {
   render: () => {
     function Demo() {

package/src/Primitives.stories.tsx

@@ -1,10 +1,46 @@
 import type { Meta, StoryObj } from "@storybook/react";
-import { Callout, Divider, Kbd, TextLink } from "./primitives";
+import { useState } from "react";
+import { Avatar, AvatarGroup, Callout, Divider, Kbd, Tag, TextLink } from "./primitives";
 
 const meta: Meta = { title: "Components/Primitives/Atoms" };
 export default meta;
 type Story = StoryObj;
 
+export const Avatars: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: 24, alignItems: "center" }}>
+      <Avatar name="Jon Reed" />
+      <Avatar name="Cindi Vox" size={40} />
+      <Avatar name="ORBIS" size={22} />
+      <AvatarGroup>
+        <Avatar name="Jon Reed" />
+        <Avatar name="Cindi Vox" />
+        <Avatar name="Beads" />
+        <Avatar name="+3" />
+      </AvatarGroup>
+    </div>
+  ),
+};
+
+export const Tags: Story = {
+  render: () => {
+    function Demo() {
+      const [tags, setTags] = useState(["streaming", "a2a", "voice", "router"]);
+      return (
+        <div style={{ display: "flex", gap: 8, flexWrap: "wrap", alignItems: "center" }}>
+          <Tag>read-only</Tag>
+          {tags.map((t) => (
+            <Tag key={t} onRemove={() => setTags((ts) => ts.filter((x) => x !== t))}>
+              {t}
+            </Tag>
+          ))}
+        </div>
+      );
+    }
+    return <Demo />;
+  },
+};
+
 export const Callouts: Story = {
   render: () => (
     <div style={{ display: "grid", gap: 16, maxWidth: 560 }}>

package/src/app-shell.tsx

@@ -280,6 +280,9 @@ export type AppShellProps = {
   onMobileSelect?: (id: string) => void;
   quickBarIds?: string[];
   mobileBreakpoint?: number;
+  /** Bottom 40px track — global utility actions / status / tickers. Presentation
+   *  only; the host fills it (compose a `UtilityBar`). Desktop only. */
+  utilityBar?: ReactNode;
   className?: string;
 };
 
@@ -308,6 +311,7 @@ export function AppShell({
   onMobileSelect,
   quickBarIds,
   mobileBreakpoint = 768,
+  utilityBar,
   className,
 }: AppShellProps) {
   const isMobile = useIsMobile(mobileBreakpoint);
@@ -445,35 +449,38 @@ export function AppShell({
   const ctxRight = onRailContextMenu ? (e: ReactMouseEvent, id: string) => onRailContextMenu("right", e, id) : undefined;
 
   const renderShell = (leftRail: ReactNode, rightRail: ReactNode) => (
-    <div className={cx("pl-appshell", className)}>
-      {leftRail}
-      <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>
-      )}
-      {rightRail}
+    <div className={cx("pl-appshell-frame", className)}>
+      <div className="pl-appshell">
+        {leftRail}
+        <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>
+        )}
+        {rightRail}
+      </div>
+      {utilityBar != null && <div className="pl-appshell__utility">{utilityBar}</div>}
     </div>
   );
 
@@ -511,3 +518,24 @@ export function AppShell({
     </DndContext>
   );
 }
+
+/** Bottom utility-bar chrome — start cluster · spacer · end cluster. Compose
+ *  shipped primitives (StatusDot, Badge, Spinner, Menu) inside; pass to
+ *  AppShell's `utilityBar` slot. Presentation only. */
+export function UtilityBar({
+  start,
+  end,
+  className,
+}: {
+  start?: ReactNode;
+  end?: ReactNode;
+  className?: string;
+}) {
+  return (
+    <div className={cx("pl-utilitybar", className)}>
+      <div className="pl-utilitybar__cluster">{start}</div>
+      <div className="pl-utilitybar__spacer" />
+      <div className="pl-utilitybar__cluster">{end}</div>
+    </div>
+  );
+}

package/src/forms.tsx

@@ -48,27 +48,26 @@ export function Select({ className, children, ...rest }: SelectHTMLAttributes<HT
   );
 }
 
-/** Toggle switch. Controlled via `checked` / `onCheckedChange`. */
+/** Toggle switch. Controlled via `checked` / `onCheckedChange`. Spreads the
+ *  rest of the input attributes (id, name, aria-*, data-*) onto the inner input —
+ *  so an external `<label htmlFor>` can associate. */
 export function Switch({
   checked,
   onCheckedChange,
-  disabled,
   label,
   className,
-}: {
-  checked?: boolean;
+  ...rest
+}: Omit<InputHTMLAttributes<HTMLInputElement>, "onChange" | "type"> & {
   onCheckedChange?: (checked: boolean) => void;
-  disabled?: boolean;
   label?: ReactNode;
-  className?: string;
 }) {
   return (
-    <label className={cx("pl-switch", disabled && "pl-switch--disabled", className)}>
+    <label className={cx("pl-switch", rest.disabled && "pl-switch--disabled", className)}>
       <input
         type="checkbox"
+        {...rest}
         className="pl-switch__input"
         checked={checked}
-        disabled={disabled}
         onChange={(e) => onCheckedChange?.(e.target.checked)}
       />
       <span className="pl-switch__track" aria-hidden>
@@ -79,27 +78,26 @@ export function Switch({
   );
 }
 
-/** Checkbox. Controlled via `checked` / `onCheckedChange`. */
+/** Checkbox. Controlled via `checked` / `onCheckedChange`. Spreads the rest of
+ *  the input attributes (id, name, aria-*, data-*) onto the inner input, so an
+ *  external `<label htmlFor>` can associate. */
 export function Checkbox({
   checked,
   onCheckedChange,
-  disabled,
   label,
   className,
-}: {
-  checked?: boolean;
+  ...rest
+}: Omit<InputHTMLAttributes<HTMLInputElement>, "onChange" | "type"> & {
   onCheckedChange?: (checked: boolean) => void;
-  disabled?: boolean;
   label?: ReactNode;
-  className?: string;
 }) {
   return (
-    <label className={cx("pl-checkbox", disabled && "pl-checkbox--disabled", className)}>
+    <label className={cx("pl-checkbox", rest.disabled && "pl-checkbox--disabled", className)}>
       <input
         type="checkbox"
+        {...rest}
         className="pl-checkbox__input"
         checked={checked}
-        disabled={disabled}
         onChange={(e) => onCheckedChange?.(e.target.checked)}
       />
       <span className="pl-checkbox__box" aria-hidden />

package/src/overlays.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode, RefObject } from "react";
 import { createContext, useCallback, useContext, useEffect, useId, useRef, useState } from "react";
+import * as RPopover from "@radix-ui/react-popover";
 import { cx } from "./internal";
 import type { Status } from "./internal";
 import { Button } from "./primitives";
@@ -297,3 +298,47 @@ export function Tooltip({
     </span>
   );
 }
+
+/** Anchored floating content (Radix-backed) — the generic primitive under
+ *  filters, pickers, comboboxes, etc. Collision-aware positioning + dismissal
+ *  handled by Radix. Controlled or uncontrolled via `open` / `onOpenChange`. */
+export function Popover({
+  trigger,
+  children,
+  open,
+  onOpenChange,
+  side = "bottom",
+  align = "center",
+  className,
+}: {
+  /** The element that opens the popover (rendered as the anchor). */
+  trigger: ReactNode;
+  children: ReactNode;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  side?: "top" | "right" | "bottom" | "left";
+  align?: "start" | "center" | "end";
+  className?: string;
+}) {
+  return (
+    <RPopover.Root open={open} onOpenChange={onOpenChange}>
+      <RPopover.Trigger asChild>{trigger}</RPopover.Trigger>
+      <RPopover.Portal>
+        <RPopover.Content
+          className={cx("pl-popover", className)}
+          side={side}
+          align={align}
+          sideOffset={6}
+          collisionPadding={8}
+        >
+          {children}
+        </RPopover.Content>
+      </RPopover.Portal>
+    </RPopover.Root>
+  );
+}
+
+/** Dismiss the enclosing Popover — wrap a Button/element (e.g. a "Done" action). */
+export function PopoverClose({ children }: { children: ReactNode }) {
+  return <RPopover.Close asChild>{children}</RPopover.Close>;
+}

package/src/primitives.tsx

@@ -88,3 +88,69 @@ export function TextLink({
     />
   );
 }
+
+/** Identity avatar — an image, or initials derived from `name`. */
+export function Avatar({
+  src,
+  alt,
+  name,
+  size = 28,
+  className,
+}: {
+  src?: string;
+  alt?: string;
+  name?: string;
+  size?: number;
+  className?: string;
+}) {
+  const initials = name
+    ? name
+        .trim()
+        .split(/\s+/)
+        .slice(0, 2)
+        .map((w) => w[0])
+        .join("")
+        .toUpperCase()
+    : "";
+  return (
+    <span
+      className={cx("pl-avatar", className)}
+      style={{ width: size, height: size, fontSize: Math.round(size * 0.38) }}
+      role="img"
+      aria-label={alt ?? name}
+    >
+      {src ? (
+        <img className="pl-avatar__img" src={src} alt={alt ?? name ?? ""} />
+      ) : (
+        <span aria-hidden>{initials || "?"}</span>
+      )}
+    </span>
+  );
+}
+
+/** Overlapping avatar stack — wrap Avatar children. */
+export function AvatarGroup({ className, ...rest }: HTMLAttributes<HTMLDivElement>) {
+  return <div className={cx("pl-avatar-group", className)} {...rest} />;
+}
+
+/** Interactive token / chip. Pass `onRemove` for a removable chip. */
+export function Tag({
+  children,
+  onRemove,
+  className,
+}: {
+  children: ReactNode;
+  onRemove?: () => void;
+  className?: string;
+}) {
+  return (
+    <span className={cx("pl-tag", className)}>
+      <span className="pl-tag__label">{children}</span>
+      {onRemove && (
+        <button type="button" className="pl-tag__remove" aria-label="Remove" onClick={onRemove}>
+          ×
+        </button>
+      )}
+    </span>
+  );
+}

package/src/styles/app-shell.css

@@ -160,14 +160,50 @@
 }
 
 /* ── AppShell (dual-rail + 3-column) ─────────────────────────────────────────── */
+/* Vertical frame: content row (1fr) + optional utility bar (40px). */
+.pl-appshell-frame {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+  background: var(--pl-color-bg);
+  color: var(--pl-color-fg);
+}
 .pl-appshell {
   display: flex;
   align-items: stretch;
-  height: 100%;
+  flex: 1 1 auto;
   min-height: 0;
   background: var(--pl-color-bg);
   color: var(--pl-color-fg);
 }
+/* Utility bar — the bottom 40px track (third grid row). Desktop only. */
+.pl-appshell__utility {
+  flex: 0 0 40px;
+  height: 40px;
+  display: flex;
+  align-items: center;
+  border-top: var(--pl-border-width) solid var(--pl-color-border);
+  background: var(--pl-color-bg-raised);
+}
+.pl-utilitybar {
+  display: flex;
+  align-items: center;
+  gap: var(--pl-space-2);
+  width: 100%;
+  height: 100%;
+  padding: 0 var(--pl-space-3);
+  font-size: 12px;
+  color: var(--pl-color-fg-muted);
+}
+.pl-utilitybar__cluster {
+  display: flex;
+  align-items: center;
+  gap: var(--pl-space-3);
+}
+.pl-utilitybar__spacer {
+  flex: 1;
+}
 
 .pl-appshell__col {
   display: flex;

package/src/styles/overlays.css

@@ -293,3 +293,18 @@
   top: 50%;
   transform: translateY(-50%);
 }
+
+/* ── Popover (Radix-backed) ──────────────────────────────────────────────────── */
+.pl-popover {
+  min-width: 200px;
+  max-width: 320px;
+  padding: var(--pl-space-3);
+  font-size: 13px;
+  line-height: 1.5;
+  color: var(--pl-color-fg);
+  background: var(--pl-color-bg-raised);
+  border: var(--pl-border-width) solid var(--pl-color-border-strong);
+  border-radius: var(--pl-radius);
+  box-shadow: var(--pl-shadow-popover);
+  z-index: 1200;
+}

package/src/styles/primitives.css

@@ -217,3 +217,71 @@
   width: 16px;
   height: 16px;
 }
+
+/* ── Avatar ──────────────────────────────────────────────────────────────────── */
+.pl-avatar {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  overflow: hidden;
+  border-radius: 50%;
+  background: var(--pl-color-bg-subtle);
+  border: var(--pl-border-width) solid var(--pl-color-border);
+  color: var(--pl-color-fg-muted);
+  font-family: var(--pl-font-mono);
+  font-weight: var(--pl-font-weight-medium);
+  line-height: 1;
+  user-select: none;
+}
+.pl-avatar__img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+.pl-avatar-group {
+  display: inline-flex;
+  align-items: center;
+}
+.pl-avatar-group > .pl-avatar {
+  margin-left: -8px;
+  box-shadow: 0 0 0 2px var(--pl-color-bg);
+}
+.pl-avatar-group > .pl-avatar:first-child {
+  margin-left: 0;
+}
+
+/* ── Tag / Chip ──────────────────────────────────────────────────────────────── */
+.pl-tag {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  height: 20px;
+  padding: 0 6px;
+  font-family: var(--pl-font-mono);
+  font-size: 11px;
+  color: var(--pl-color-fg);
+  background: var(--pl-color-bg-subtle);
+  border: var(--pl-border-width) solid var(--pl-color-border);
+  border-radius: var(--pl-radius);
+}
+.pl-tag__remove {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 14px;
+  height: 14px;
+  margin-right: -2px;
+  padding: 0;
+  font-size: 13px;
+  line-height: 1;
+  color: var(--pl-color-fg-muted);
+  background: none;
+  border: none;
+  border-radius: 50%;
+  cursor: pointer;
+}
+.pl-tag__remove:hover {
+  color: var(--pl-color-fg);
+  background: var(--pl-color-bg-hover);
+}