@parallelworks/ui 0.92.0 → 0.93.0

package/README.md

@@ -8,6 +8,7 @@ so an application ships only what it imports:
 | `.` | theme contract, primitives (buttons, inputs, tables, tooltips, modals, dropdowns, settings layouts, page header), `UIProvider` |
 | `./theme` | theme seeds and presets, `generateTheme`, `applyTheme`, `fitSeed` |
 | `./icons` | the icon barrel |
+| `./app-frame` | inset application frame, resizable navigation, icon rail, and mobile drawer |
 | `./list` | list pages, tables, row menus and list controls |
 | `./form` | `DynamicForm` and its field registry |
 | `./graph` | job dependency graph and tree view, and the visual workflow editor: the graph, the run form as an inputs editor, and their dialogs |
@@ -16,7 +17,7 @@ so an application ships only what it imports:
 | `./file-explorer` | object storage explorer over a host-supplied provider |
 | `./access` | `AccessDrawer`: who has access to a resource, and granting roles to people and groups |
 | `./ai`, `./ai/openai`, `./ai/mock` | chat interface and adapters |
-| `./theme.css`, `./base.css`, `./fonts.css`, `./styles.css`, `./logviewer.css`, `./ai.css` | stylesheets |
+| `./theme.css`, `./base.css`, `./fonts.css`, `./styles.css`, `./logviewer.css`, `./ai.css`, `./app-frame.css` | stylesheets |
 
 Hosts bind strings, navigation, data hooks and the workflow engine through
 `UIProvider`, which also shows the package's toasts:
@@ -1245,3 +1246,75 @@ colors and sizing can obscure labels or make controls hard to use. Keep trusted
 confirmation summaries, permissions, and security notices outside the authored
 layout. Full stylesheets or mutually untrusted embedded applications require a
 separate isolation design.
+
+## Application frame
+
+`AppFrame` provides a sidebar and an inset content surface. The sidebar collapses
+to a 64px icon rail, resizes with a pointer or keyboard, and becomes a modal
+navigation drawer below 768px. Its header, scrolling navigation, and footer stay
+separate from the page's scrolling content. Long navigation labels truncate within
+the current sidebar width; badges remain visible. Navigation scrollbar tracks stay
+hidden while wheel and keyboard scrolling keep destinations reachable in short
+containers.
+
+```tsx
+import { AppFrame, AppFrameNavItem, AppFrameToggle } from '@parallelworks/ui/app-frame'
+import '@parallelworks/ui/app-frame.css'
+
+<AppFrame
+  navigationKey={pathname}
+  brand={({ expanded }) => expanded ? <Wordmark /> : <Mark />}
+  navigation={
+    <nav aria-label="Main navigation">
+      <AppFrameNavItem label="Projects" icon={<ProjectsIcon />} href="/projects" selected />
+    </nav>
+  }
+  footer={({ isMobile }) => !isMobile && <AppFrameToggle />}
+  header={<PageTools />}
+>
+  <ProjectList />
+</AppFrame>
+```
+
+`PageTools` can use `useAppFrame().isMobile` to show an `AppFrameToggle` on small
+screens. The drawer supplies its own close button, traps focus, closes on Escape
+or an outside click, and returns focus to its opener. Navigation items close it
+on an ordinary click; modified links keep the current view in place. A changed
+`navigationKey` also dismisses it.
+Reopening mobile navigation restores its scroll position within the current
+section. Closing it unmounts its contents, including any nested popups.
+Use `navigationResetKey` for a section identifier when navigation scroll should
+survive route changes within that section. It defaults to `navigationKey`.
+`sidebarProps` passes host attributes, styling, and events to the desktop sidebar
+and mobile dialog, for example a navigation context menu. The frame retains its
+own layout, dialog semantics, and measured width.
+
+The host owns routing, persistence, identity, permissions, and page tools. Links
+use `UIProvider`'s link slot. Pass `expanded`/`onExpandedChange` and
+`width`/`onWidthChange` to persist preferences, or use the uncontrolled defaults.
+Pointer drags preview their width locally and call `onWidthChange` once when the
+gesture ends, so persistence does not run on every pointer movement.
+`defaultWidth` is 240, bounded by `minWidth` (200) and `maxWidth` (400); compact
+applications can choose smaller bounds. The resize handle supports arrows, Home,
+End, drag-to-collapse, and double-click to restore `defaultWidth`. Logical layout
+and resizing support right-to-left direction. Reduced motion disables resizing
+and drawer transitions. `resizable={false}` removes the handle.
+
+`brand`, `navigation`, and `footer` accept nodes or functions receiving the frame
+state. `header` sits above the main content; `banner` spans both columns.
+`fullBleed` removes the 8px inset and 12px rounded border. The frame fills the
+viewport by default; pass `style={{ height: '100%' }}` for a bounded container.
+The mobile drawer stays inside the frame, below its banner, and uses the chosen
+sidebar width, capped to leave 48px for dismissal. It slides from the navigation
+edge while the backdrop fades; both finish in 200ms and respect reduced motion.
+
+The five `--theme-sidebar-*` tokens produced by `generateTheme` style navigation:
+`bg`, `text`, `hover`, `active-bg`, and `active-text`. Without them the frame uses
+the ordinary surface and accent tokens. Content uses `--theme-app-bg` and
+`--theme-border`. Supply translated `labels` for navigation, skip, open, close,
+expand, collapse, and resize actions. The frame owns the main landmark and skip
+link; put page content inside it without nesting a second `<main>`.
+
+Frame styles use the `pw-ui` cascade layer. Put broad host element defaults
+(such as anchor colors and scrollbar styling) in a lower-priority layer declared
+before the package styles, so they do not replace navigation states.

package/dist/app-frame/app-frame.css

@@ -0,0 +1,281 @@
+@layer pw-ui {
+  /* The frame uses the same sidebar tokens as the theme generator. */
+  .pw-app-frame {
+    display: flex;
+    flex-direction: column;
+    height: 100dvh;
+    min-height: 0;
+    isolation: isolate;
+    background: var(--theme-sidebar-bg, var(--theme-muted-panel-bg));
+    color: var(--theme-app);
+  }
+  .pw-frame-body {
+    display: flex;
+    flex: 1;
+    min-height: 0;
+    position: relative;
+    overflow: hidden;
+  }
+  .pw-frame-sidebar,
+  .pw-frame-drawer {
+    display: flex;
+    flex-direction: column;
+    flex-shrink: 0;
+    min-height: 0;
+    background: var(--theme-sidebar-bg, var(--theme-muted-panel-bg));
+    color: var(--theme-sidebar-text, var(--theme-app));
+  }
+  .pw-frame-sidebar {
+    position: relative;
+    transition: width 200ms cubic-bezier(0.25, 0.1, 0.25, 1);
+  }
+  .pw-frame-sidebar[data-resizing] {
+    transition: none;
+    user-select: none;
+  }
+  .pw-frame-brand {
+    padding: 12px 12px 4px;
+    flex-shrink: 0;
+    min-width: 0;
+    overflow: hidden;
+  }
+  .pw-frame-links {
+    flex: 1;
+    overflow-x: hidden;
+    overflow-y: auto;
+    padding: 12px;
+    min-width: 0;
+    min-height: 0;
+    scrollbar-width: none;
+  }
+  .pw-frame-links::-webkit-scrollbar {
+    display: none;
+  }
+  .pw-frame-links nav {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    gap: 4px;
+  }
+  .pw-frame-footer {
+    flex-shrink: 0;
+    padding: 8px 12px;
+  }
+  .pw-frame-nav-item {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    min-height: 36px;
+    min-width: 0;
+    width: 100%;
+    border: 0;
+    border-radius: 8px;
+    padding: 8px;
+    background: transparent;
+    color: inherit;
+    font: inherit;
+    font-size: 14px;
+    font-weight: 500;
+    line-height: 20px;
+    cursor: pointer;
+    text-decoration: none;
+    text-align: start;
+    transition: background-color 150ms ease-out;
+  }
+  .pw-frame-nav-item:hover,
+  .pw-frame-toggle:hover {
+    background: var(--theme-sidebar-hover, var(--theme-hover));
+  }
+  .pw-frame-nav-item[aria-current] {
+    background: var(--theme-sidebar-active-bg, var(--theme-accent-subtle));
+    color: var(--theme-sidebar-active-text, var(--theme-accent));
+  }
+  .pw-frame-nav-item:is(:disabled, [aria-disabled]) {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+  .pw-frame-nav-icon {
+    display: flex;
+    flex: 0 0 18px;
+    align-items: center;
+    justify-content: center;
+  }
+  .pw-frame-nav-icon svg {
+    width: 18px;
+    height: 18px;
+  }
+  .pw-frame-nav-label {
+    flex: 1;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .pw-frame-nav-badge {
+    flex-shrink: 0;
+    font-size: 12px;
+    font-variant-numeric: tabular-nums;
+  }
+  [data-sidebar-mode="rail"] .pw-frame-nav-item {
+    padding-inline: 0;
+    justify-content: center;
+    height: 40px;
+  }
+  .pw-frame-toggle {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 36px;
+    height: 36px;
+    border: 0;
+    border-radius: 8px;
+    padding: 0;
+    color: inherit;
+    background: transparent;
+    cursor: pointer;
+    flex-shrink: 0;
+  }
+  .pw-frame-toggle svg {
+    width: 18px;
+    height: 18px;
+  }
+  .pw-frame-sidebar :focus-visible,
+  .pw-frame-drawer :focus-visible {
+    outline: 2px solid currentColor;
+    outline-offset: 2px;
+  }
+  .pw-frame-resize {
+    position: absolute;
+    z-index: 1;
+    inset-block: 0;
+    inset-inline-end: -4px;
+    width: 8px;
+    cursor: col-resize;
+    touch-action: none;
+  }
+  .pw-frame-resize::after {
+    content: "";
+    position: absolute;
+    inset-block: 8px;
+    inset-inline-start: 3px;
+    width: 2px;
+    border-radius: 2px;
+  }
+  .pw-frame-resize:hover::after,
+  .pw-frame-resize:focus-visible::after {
+    background: var(--theme-sidebar-text, var(--theme-accent));
+    opacity: 0.5;
+  }
+  .pw-frame-surface-wrap {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+    min-height: 0;
+    padding: 8px;
+    padding-inline-start: 0;
+  }
+  .pw-frame-surface {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+    min-height: 0;
+    overflow: hidden;
+    isolation: isolate;
+    border: 1px solid var(--theme-border);
+    border-radius: 12px;
+    background: var(--theme-app-bg);
+    background-clip: padding-box;
+  }
+  .pw-frame-header,
+  .pw-frame-banner {
+    flex-shrink: 0;
+  }
+  .pw-frame-main {
+    flex: 1;
+    min-width: 0;
+    min-height: 0;
+    overflow: auto;
+  }
+  .pw-app-frame[data-full-bleed] .pw-frame-surface-wrap {
+    padding: 0;
+  }
+  .pw-app-frame[data-full-bleed] .pw-frame-surface {
+    border: 0;
+    border-radius: 0;
+  }
+  .pw-app-frame[data-mobile] .pw-frame-surface-wrap {
+    padding: 8px;
+  }
+  .pw-app-frame[data-mobile][data-full-bleed] .pw-frame-surface-wrap {
+    padding: 0;
+  }
+  .pw-frame-backdrop {
+    position: absolute;
+    inset: 0;
+    z-index: var(--layer-drawer, 1100);
+    background: var(--theme-backdrop, rgb(0 0 0 / 0.35));
+    transition: opacity 200ms cubic-bezier(0.25, 0.1, 0.25, 1);
+  }
+  .pw-frame-backdrop[data-starting-style],
+  .pw-frame-backdrop[data-ending-style] {
+    opacity: 0;
+  }
+  .pw-frame-drawer {
+    position: absolute;
+    inset-block: 8px;
+    inset-inline-start: 8px;
+    max-width: calc(100% - 48px);
+    z-index: var(--layer-drawer, 1100);
+    border-radius: 12px;
+    box-shadow: 0 12px 32px rgb(0 0 0 / 0.2);
+    outline: none;
+    transform: translateX(0);
+    transition: transform 200ms cubic-bezier(0.25, 0.1, 0.25, 1);
+  }
+  .pw-frame-drawer[data-starting-style],
+  .pw-frame-drawer[data-ending-style] {
+    transform: translateX(calc(-100% - 16px));
+  }
+  .pw-frame-drawer:dir(rtl)[data-starting-style],
+  .pw-frame-drawer:dir(rtl)[data-ending-style] {
+    transform: translateX(calc(100% + 16px));
+  }
+  .pw-frame-mobile-close {
+    display: flex;
+    justify-content: flex-end;
+    padding: 4px 4px 0;
+  }
+  .pw-frame-drawer .pw-frame-brand {
+    padding-top: 0;
+  }
+  .pw-frame-drawer .pw-frame-nav-item,
+  .pw-app-frame[data-mobile] .pw-frame-toggle {
+    min-height: 44px;
+  }
+  .pw-app-frame[data-mobile] .pw-frame-toggle {
+    width: 44px;
+    height: 44px;
+  }
+  .pw-frame-skip {
+    position: fixed;
+    inset-block-start: -100px;
+    inset-inline-start: 8px;
+    padding: 8px 16px;
+    border-radius: 6px;
+    background: var(--theme-panel-bg);
+    color: var(--theme-app);
+    z-index: var(--layer-popover, 1400);
+  }
+  .pw-frame-skip:focus {
+    inset-block-start: 8px;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .pw-frame-sidebar,
+    .pw-frame-backdrop,
+    .pw-frame-drawer,
+    .pw-frame-nav-item {
+      transition: none;
+    }
+  }
+}

package/dist/app-frame/index.d.ts

@@ -0,0 +1,73 @@
+import { type HTMLAttributes, type MouseEvent, type ReactNode } from 'react';
+import { type LinkTarget } from '../components/AppLink.js';
+export interface AppFrameLabels {
+    navigation: string;
+    skipToContent: string;
+    openNavigation: string;
+    closeNavigation: string;
+    expandSidebar: string;
+    collapseSidebar: string;
+    resizeSidebar: string;
+}
+export interface AppFrameState {
+    /** Labels stay visible in the mobile drawer even when the desktop rail is collapsed. */
+    expanded: boolean;
+    isMobile: boolean;
+    mobileOpen: boolean;
+    toggle: () => void;
+    closeNavigation: () => void;
+}
+export declare function useAppFrame(): AppFrameState;
+type Slot = ReactNode | ((state: AppFrameState) => ReactNode);
+export interface AppFrameProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    children: ReactNode;
+    /** Identity at the top of navigation. Render a compact mark when expanded is false. */
+    brand?: Slot;
+    navigation: Slot;
+    footer?: Slot;
+    /** Page tools above the independently scrolling main content. */
+    header?: ReactNode;
+    /** Optional notice above both navigation and content. */
+    banner?: ReactNode;
+    expanded?: boolean;
+    defaultExpanded?: boolean;
+    onExpandedChange?: (expanded: boolean) => void;
+    width?: number;
+    defaultWidth?: number;
+    /** Commits once when a drag ends, and on each keyboard or reset action. */
+    onWidthChange?: (width: number) => void;
+    minWidth?: number;
+    maxWidth?: number;
+    railWidth?: number;
+    resizable?: boolean;
+    /** Viewport width below which navigation becomes a modal drawer. */
+    mobileBreakpoint?: number;
+    /** A changed route key closes mobile navigation. */
+    navigationKey?: string;
+    /** Reset navigation scroll only when this section changes; defaults to navigationKey. */
+    navigationResetKey?: string;
+    /** Attributes shared by desktop navigation and the mobile dialog. */
+    sidebarProps?: HTMLAttributes<HTMLElement>;
+    /** Removes the inset and border around content. */
+    fullBleed?: boolean;
+    labels?: Partial<AppFrameLabels>;
+    mainId?: string;
+    mainClassName?: string;
+}
+/** An inset application surface beside a resizable icon rail or navigation column.
+ * Router, identity, persistence and permissions belong to the host. Import app-frame.css. */
+export declare function AppFrame({ children, brand, navigation, footer, header, banner, expanded: controlledExpanded, defaultExpanded, onExpandedChange, width: controlledWidth, defaultWidth, onWidthChange, minWidth, maxWidth, railWidth, resizable, mobileBreakpoint, navigationKey, navigationResetKey, sidebarProps, fullBleed, labels: labelOverrides, mainId: suppliedMainId, mainClassName, className, style, ...props }: AppFrameProps): import("react").JSX.Element;
+/** Put in the page header on mobile, and the sidebar footer on desktop. */
+export declare function AppFrameToggle({ className, ...props }: Omit<HTMLAttributes<HTMLButtonElement>, 'children'>): import("react").JSX.Element;
+export interface AppFrameNavItemProps extends LinkTarget {
+    label: string;
+    icon: ReactNode;
+    selected?: boolean;
+    badge?: ReactNode;
+    disabled?: boolean;
+    onClick?: (event: MouseEvent<HTMLElement>) => void;
+    className?: string;
+}
+/** Router-aware navigation that keeps icon-only rail items named and discoverable. */
+export declare function AppFrameNavItem({ label, icon, selected, badge, disabled, onClick, className, ...target }: AppFrameNavItemProps): import("react").JSX.Element;
+export {};

package/dist/app-frame/index.js

@@ -0,0 +1,369 @@
+import { cx } from "../cx.js";
+import { CloseIcon, SidebarCloseIcon, SidebarOpenIcon } from "../icons.js";
+import { Tooltip } from "../components/Tooltip.js";
+import { AppLink, isPlainClick } from "../components/AppLink.js";
+import { createContext, useCallback, useContext, useEffect, useId, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { Dialog } from "@base-ui/react/dialog";
+//#region src/app-frame/index.tsx
+var defaultLabels = {
+	navigation: "Main navigation",
+	skipToContent: "Skip to content",
+	openNavigation: "Open navigation",
+	closeNavigation: "Close navigation",
+	expandSidebar: "Expand sidebar",
+	collapseSidebar: "Collapse sidebar",
+	resizeSidebar: "Resize sidebar"
+};
+var Context = createContext(null);
+function useAppFrame() {
+	const context = useContext(Context);
+	if (!context) throw new Error("useAppFrame requires AppFrame");
+	return context;
+}
+function useFrameContext() {
+	const context = useContext(Context);
+	if (!context) throw new Error("App frame controls require AppFrame");
+	return context;
+}
+function useMobile(breakpoint) {
+	const media = useMemo(() => typeof window === "undefined" ? null : window.matchMedia(`(max-width: ${breakpoint - 1}px)`), [breakpoint]);
+	return useSyncExternalStore(useMemo(() => (changed) => {
+		media?.addEventListener("change", changed);
+		return () => media?.removeEventListener("change", changed);
+	}, [media]), () => media?.matches ?? false, () => false);
+}
+function slot(value, state) {
+	return typeof value === "function" ? value(state) : value;
+}
+/** An inset application surface beside a resizable icon rail or navigation column.
+* Router, identity, persistence and permissions belong to the host. Import app-frame.css. */
+function AppFrame({ children, brand, navigation, footer, header, banner, expanded: controlledExpanded, defaultExpanded = true, onExpandedChange, width: controlledWidth, defaultWidth = 240, onWidthChange, minWidth = 200, maxWidth = 400, railWidth = 64, resizable = true, mobileBreakpoint = 768, navigationKey, navigationResetKey = navigationKey, sidebarProps, fullBleed = false, labels: labelOverrides, mainId: suppliedMainId, mainClassName, className, style, ...props }) {
+	const id = useId();
+	const mainId = suppliedMainId ?? `${id}-main`;
+	const navigationId = `${id}-navigation`;
+	const [ownExpanded, setOwnExpanded] = useState(defaultExpanded);
+	const [ownWidth, setOwnWidth] = useState(defaultWidth);
+	const [dragWidth, setDragWidth] = useState(null);
+	const [mobileOpen, setMobileOpen] = useState(false);
+	const [resizing, setResizing] = useState(false);
+	const desktopExpanded = controlledExpanded ?? ownExpanded;
+	const minimum = Math.max(railWidth, minWidth);
+	const maximum = Math.max(minimum, maxWidth);
+	const clamp = (n) => Math.min(maximum, Math.max(minimum, Number.isFinite(n) ? n : defaultWidth));
+	const width = clamp(dragWidth ?? controlledWidth ?? ownWidth);
+	const isMobile = useMobile(mobileBreakpoint);
+	const labels = {
+		...defaultLabels,
+		...labelOverrides
+	};
+	const navRef = useRef(null);
+	const scrollRef = useRef(null);
+	const savedScrollTop = useRef(0);
+	const restoreScroll = useCallback((node) => {
+		scrollRef.current = node;
+		if (node) node.scrollTop = savedScrollTop.current;
+	}, []);
+	const portalRef = useRef(null);
+	const drag = useRef(null);
+	useEffect(() => {
+		if (!isMobile && resizable) return;
+		drag.current = null;
+		setDragWidth(null);
+		setResizing(false);
+	}, [isMobile, resizable]);
+	const setExpanded = (next) => {
+		setOwnExpanded(next);
+		onExpandedChange?.(next);
+	};
+	const setWidth = (next) => {
+		const value = clamp(next);
+		setOwnWidth(value);
+		onWidthChange?.(value);
+	};
+	const closeNavigation = () => setMobileOpen(false);
+	const state = {
+		expanded: isMobile || desktopExpanded,
+		isMobile,
+		mobileOpen,
+		toggle: () => isMobile ? setMobileOpen(!mobileOpen) : setExpanded(!desktopExpanded),
+		closeNavigation,
+		labels,
+		navigationId
+	};
+	const previousLocation = useRef({
+		navigationKey,
+		navigationResetKey,
+		isMobile
+	});
+	useEffect(() => {
+		if (previousLocation.current.navigationKey === navigationKey && previousLocation.current.navigationResetKey === navigationResetKey && previousLocation.current.isMobile === isMobile) return;
+		if (previousLocation.current.navigationKey !== navigationKey || previousLocation.current.isMobile !== isMobile) setMobileOpen(false);
+		if (previousLocation.current.navigationResetKey !== navigationResetKey || previousLocation.current.isMobile !== isMobile) {
+			savedScrollTop.current = 0;
+			scrollRef.current?.scrollTo({ top: 0 });
+		}
+		previousLocation.current = {
+			navigationKey,
+			navigationResetKey,
+			isMobile
+		};
+	}, [
+		navigationKey,
+		navigationResetKey,
+		isMobile
+	]);
+	const navContent = /* @__PURE__ */ jsxs(Fragment$1, { children: [
+		brand && /* @__PURE__ */ jsx("div", {
+			className: "pw-frame-brand",
+			children: slot(brand, state)
+		}),
+		/* @__PURE__ */ jsx("div", {
+			className: "pw-frame-links",
+			ref: restoreScroll,
+			onScroll: (event) => {
+				savedScrollTop.current = event.currentTarget.scrollTop;
+			},
+			children: slot(navigation, state)
+		}),
+		footer && /* @__PURE__ */ jsx("div", {
+			className: "pw-frame-footer",
+			children: slot(footer, state)
+		})
+	] });
+	const resize = (clientX, pointerId) => {
+		const current = drag.current;
+		if (!current || current.pointerId !== pointerId) return;
+		const next = (clientX - current.origin) * current.direction;
+		if (desktopExpanded && next < minimum - 80) setExpanded(false);
+		else if (!desktopExpanded && next >= minimum - 50) {
+			setExpanded(true);
+			current.width = clamp(next);
+			setDragWidth(current.width);
+		} else if (desktopExpanded) {
+			current.width = clamp(next);
+			setDragWidth(current.width);
+		}
+	};
+	const endResize = (event) => {
+		const ended = drag.current;
+		if (!ended || ended.pointerId !== event.pointerId) return;
+		drag.current = null;
+		setResizing(false);
+		setDragWidth(null);
+		if (desktopExpanded && ended.width !== ended.startWidth) setWidth(ended.width);
+	};
+	return /* @__PURE__ */ jsx(Context, {
+		value: state,
+		children: /* @__PURE__ */ jsxs("div", {
+			...props,
+			className: cx("pw-app-frame", className),
+			"data-mobile": isMobile || void 0,
+			"data-full-bleed": fullBleed || void 0,
+			style,
+			children: [
+				/* @__PURE__ */ jsx("a", {
+					className: "pw-frame-skip",
+					href: `#${mainId}`,
+					onClick: (event) => {
+						event.preventDefault();
+						document.getElementById(mainId)?.focus();
+					},
+					children: labels.skipToContent
+				}),
+				banner && /* @__PURE__ */ jsx("div", {
+					className: "pw-frame-banner",
+					children: banner
+				}),
+				/* @__PURE__ */ jsxs("div", {
+					className: "pw-frame-body",
+					children: [
+						!isMobile && /* @__PURE__ */ jsxs("aside", {
+							...sidebarProps,
+							ref: navRef,
+							id: navigationId,
+							className: cx("pw-frame-sidebar", sidebarProps?.className),
+							"data-sidebar-mode": desktopExpanded ? "expanded" : "rail",
+							"data-resizing": resizing || void 0,
+							style: {
+								...sidebarProps?.style,
+								width: desktopExpanded ? width : railWidth
+							},
+							children: [navContent, resizable && /* @__PURE__ */ jsx("div", {
+								role: "separator",
+								tabIndex: 0,
+								"aria-orientation": "vertical",
+								"aria-label": labels.resizeSidebar,
+								"aria-controls": navigationId,
+								"aria-valuemin": railWidth,
+								"aria-valuemax": maximum,
+								"aria-valuenow": Math.round(desktopExpanded ? width : railWidth),
+								className: "pw-frame-resize",
+								onPointerDown: (event) => {
+									if (event.button !== 0 || event.isPrimary === false || drag.current) return;
+									event.preventDefault();
+									const rect = navRef.current?.getBoundingClientRect();
+									if (!rect) return;
+									const rtl = getComputedStyle(event.currentTarget).direction === "rtl";
+									drag.current = {
+										origin: rtl ? rect.right : rect.left,
+										direction: rtl ? -1 : 1,
+										pointerId: event.pointerId,
+										startWidth: width,
+										width
+									};
+									event.currentTarget.setPointerCapture(event.pointerId);
+									setResizing(true);
+								},
+								onPointerMove: (event) => resize(event.clientX, event.pointerId),
+								onPointerUp: endResize,
+								onPointerCancel: endResize,
+								onLostPointerCapture: endResize,
+								onDoubleClick: () => {
+									setExpanded(true);
+									setWidth(defaultWidth);
+								},
+								onKeyDown: (event) => {
+									const rtl = getComputedStyle(event.currentTarget).direction === "rtl";
+									const smaller = rtl ? "ArrowRight" : "ArrowLeft";
+									if (![
+										smaller,
+										rtl ? "ArrowLeft" : "ArrowRight",
+										"Home",
+										"End"
+									].includes(event.key)) return;
+									event.preventDefault();
+									if (event.key === "Home") {
+										setExpanded(true);
+										setWidth(minimum);
+									} else if (event.key === "End") {
+										setExpanded(true);
+										setWidth(maximum);
+									} else if (event.key === smaller) {
+										if (width <= minimum) setExpanded(false);
+										else if (desktopExpanded) setWidth(width - 16);
+									} else if (!desktopExpanded) setExpanded(true);
+									else setWidth(width + 16);
+								}
+							})]
+						}),
+						/* @__PURE__ */ jsx("div", {
+							className: "pw-frame-surface-wrap",
+							children: /* @__PURE__ */ jsxs("div", {
+								className: "pw-frame-surface",
+								children: [header && /* @__PURE__ */ jsx("div", {
+									className: "pw-frame-header",
+									children: header
+								}), /* @__PURE__ */ jsx("main", {
+									id: mainId,
+									tabIndex: -1,
+									className: cx("pw-frame-main", mainClassName),
+									children
+								})]
+							})
+						}),
+						/* @__PURE__ */ jsx("div", { ref: portalRef })
+					]
+				}),
+				isMobile && /* @__PURE__ */ jsx(Dialog.Root, {
+					open: mobileOpen,
+					onOpenChange: setMobileOpen,
+					children: /* @__PURE__ */ jsxs(Dialog.Portal, {
+						container: portalRef,
+						children: [/* @__PURE__ */ jsx(Dialog.Backdrop, { className: "pw-frame-backdrop" }), /* @__PURE__ */ jsxs(Dialog.Popup, {
+							...sidebarProps,
+							id: navigationId,
+							className: cx("pw-frame-drawer", sidebarProps?.className),
+							"aria-label": labels.navigation,
+							"aria-modal": "true",
+							"data-sidebar-mode": "drawer",
+							style: {
+								...sidebarProps?.style,
+								width
+							},
+							children: [/* @__PURE__ */ jsx("div", {
+								className: "pw-frame-mobile-close",
+								children: /* @__PURE__ */ jsx(Dialog.Close, {
+									className: "pw-frame-toggle",
+									"aria-label": labels.closeNavigation,
+									children: /* @__PURE__ */ jsx(CloseIcon, {})
+								})
+							}), navContent]
+						})]
+					})
+				})
+			]
+		})
+	});
+}
+/** Put in the page header on mobile, and the sidebar footer on desktop. */
+function AppFrameToggle({ className, ...props }) {
+	const { expanded, isMobile, mobileOpen, toggle, labels, navigationId } = useFrameContext();
+	const label = isMobile ? mobileOpen ? labels.closeNavigation : labels.openNavigation : expanded ? labels.collapseSidebar : labels.expandSidebar;
+	return /* @__PURE__ */ jsx(Tooltip, {
+		content: label,
+		side: isMobile ? "bottom" : "right",
+		children: /* @__PURE__ */ jsx("button", {
+			...props,
+			type: "button",
+			className: cx("pw-frame-toggle", className),
+			"aria-label": label,
+			"aria-expanded": isMobile ? mobileOpen : expanded,
+			"aria-controls": navigationId,
+			onClick: (event) => {
+				props.onClick?.(event);
+				if (!event.defaultPrevented) toggle();
+			},
+			children: expanded && !isMobile ? /* @__PURE__ */ jsx(SidebarCloseIcon, {}) : /* @__PURE__ */ jsx(SidebarOpenIcon, {})
+		})
+	});
+}
+/** Router-aware navigation that keeps icon-only rail items named and discoverable. */
+function AppFrameNavItem({ label, icon, selected, badge, disabled, onClick, className, ...target }) {
+	const { expanded, closeNavigation } = useFrameContext();
+	const props = {
+		className: cx("pw-frame-nav-item", className),
+		"aria-current": selected ? "page" : void 0,
+		onClick: (event) => {
+			if (disabled) {
+				event.preventDefault();
+				return;
+			}
+			onClick?.(event);
+			if (!event.defaultPrevented && isPlainClick(event)) closeNavigation();
+		},
+		children: /* @__PURE__ */ jsxs(Fragment$1, { children: [
+			/* @__PURE__ */ jsx("span", {
+				className: "pw-frame-nav-icon",
+				"aria-hidden": "true",
+				children: icon
+			}),
+			/* @__PURE__ */ jsx("span", {
+				className: expanded ? "pw-frame-nav-label" : "sr-only",
+				children: label
+			}),
+			expanded && badge != null && /* @__PURE__ */ jsx("span", {
+				className: "pw-frame-nav-badge",
+				"aria-hidden": "true",
+				children: badge
+			})
+		] })
+	};
+	const item = target.href ? /* @__PURE__ */ jsx(AppLink, {
+		...target,
+		...props,
+		disabled
+	}) : /* @__PURE__ */ jsx("button", {
+		...props,
+		type: "button",
+		disabled
+	});
+	return expanded ? item : /* @__PURE__ */ jsx(Tooltip, {
+		content: label,
+		side: "right",
+		delay: 0,
+		children: item
+	});
+}
+//#endregion
+export { AppFrame, AppFrameNavItem, AppFrameToggle, useAppFrame };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parallelworks/ui",
-  "version": "0.92.0",
+  "version": "0.93.0",
   "description": "React UI components: a theme contract, icons, brand logos, primitives, lists, forms, a job graph, a code editor, a log viewer, a file explorer and an AI chat, each on its own subpath",
   "license": "Apache-2.0",
   "repository": {
@@ -76,7 +76,12 @@
       "types": "./dist/ai/adapter/mock/index.d.ts",
       "import": "./dist/ai/adapter/mock/index.js"
     },
-    "./ai.css": "./dist/ai/ai.css"
+    "./ai.css": "./dist/ai/ai.css",
+    "./app-frame": {
+      "types": "./dist/app-frame/index.d.ts",
+      "import": "./dist/app-frame/index.js"
+    },
+    "./app-frame.css": "./dist/app-frame/app-frame.css"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
@@ -148,7 +153,7 @@
   "scripts": {
     "build": "vite build && pnpm build:types && pnpm build:css",
     "build:types": "tsc -p tsconfig.build.json && node scripts/declaration-extensions.mjs",
-    "build:css": "mkdir -p dist/styles dist/logviewer dist/ai && cp src/styles/theme.css src/styles/base.css src/styles/fonts.css src/styles/*.woff2 dist/styles/ && tailwindcss -i ./src/styles.css -o ./dist/styles.css --minify && cp src/logviewer/logviewer.css dist/logviewer/ && cp src/ai/ai.css dist/ai/",
+    "build:css": "mkdir -p dist/styles dist/logviewer dist/ai && cp src/styles/theme.css src/styles/base.css src/styles/fonts.css src/styles/*.woff2 dist/styles/ && tailwindcss -i ./src/styles.css -o ./dist/styles.css --minify && cp src/logviewer/logviewer.css dist/logviewer/ && cp src/ai/ai.css dist/ai/ && mkdir -p dist/app-frame && cp src/app-frame/app-frame.css dist/app-frame/",
     "clean": "rm -rf dist",
     "test": "vitest run",
     "lint:package": "publint --strict",