@khal-os/ui 1.0.0

package/src/primitives/index.ts

@@ -0,0 +1,22 @@
+// OS Primitives — UI building blocks for desktop app chrome.
+// Built on top of shadcn/ui components and Geist design tokens.
+//
+// These fill the gap between shadcn's web-focused components and the
+// needs of a desktop-style app (toolbars, split panes, status bars, etc.).
+//
+// shadcn/ui components to use directly (from @/components/ui/*):
+//   Button, Input, Badge, Spinner, Separator, Tooltip, Toggle (Switch),
+//   ContextMenu, Command (CommandDialog), DropdownMenu, Note, LoadingDots,
+//   ThemeSwitcher
+
+export { CollapsibleSidebar, useSidebar } from './collapsible-sidebar';
+export { Dialog } from './dialog';
+export { EmptyState } from './empty-state';
+export { ListView } from './list-view';
+export { PropertyPanel } from './property-panel';
+export { SectionHeader } from './section-header';
+export { SidebarNav } from './sidebar-nav';
+export { SplitPane } from './split-pane';
+export { StatusBadge } from './status-badge';
+export { StatusBar } from './status-bar';
+export { Toolbar } from './toolbar';

package/src/primitives/list-view.tsx

@@ -0,0 +1,155 @@
+'use client';
+
+import { type KeyboardEvent, type ReactNode, useCallback, useEffect, useRef, useState } from 'react';
+
+// ---------------------------------------------------------------------------
+// ListView — selectable list with keyboard navigation.
+//
+// Usage:
+//   <ListView
+//     items={files}
+//     selected={selectedId}
+//     onSelect={setSelectedId}
+//     onActivate={(item) => openFile(item)}
+//     renderItem={(item, { selected, focused }) => (
+//       <div className="flex items-center gap-2">
+//         <FileIcon name={item.name} />
+//         <span>{item.name}</span>
+//       </div>
+//     )}
+//     getKey={(item) => item.id}
+//   />
+// ---------------------------------------------------------------------------
+
+interface ListViewProps<T> {
+	items: T[];
+	selected?: string | string[] | null;
+	onSelect?: (key: string | null) => void;
+	onActivate?: (item: T) => void;
+	renderItem: (item: T, state: { selected: boolean; focused: boolean; index: number }) => ReactNode;
+	getKey: (item: T) => string;
+	multiSelect?: boolean;
+	emptyMessage?: string;
+	className?: string;
+}
+
+export function ListView<T>({
+	items,
+	selected,
+	onSelect,
+	onActivate,
+	renderItem,
+	getKey,
+	multiSelect = false,
+	emptyMessage = 'No items',
+	className = '',
+}: ListViewProps<T>) {
+	const [focusIndex, setFocusIndex] = useState(0);
+	const listRef = useRef<HTMLDivElement>(null);
+
+	const selectedSet = new Set(selected == null ? [] : Array.isArray(selected) ? selected : [selected]);
+
+	const clamp = useCallback((i: number) => Math.max(0, Math.min(items.length - 1, i)), [items.length]);
+
+	useEffect(() => {
+		setFocusIndex((prev) => clamp(prev));
+	}, [items.length, clamp]);
+
+	const scrollToIndex = useCallback((i: number) => {
+		const el = listRef.current?.children[i] as HTMLElement | undefined;
+		el?.scrollIntoView({ block: 'nearest' });
+	}, []);
+
+	const handleKeyDown = useCallback(
+		(e: KeyboardEvent) => {
+			switch (e.key) {
+				case 'ArrowDown': {
+					e.preventDefault();
+					const next = clamp(focusIndex + 1);
+					setFocusIndex(next);
+					scrollToIndex(next);
+					if (!multiSelect) onSelect?.(getKey(items[next]));
+					break;
+				}
+				case 'ArrowUp': {
+					e.preventDefault();
+					const prev = clamp(focusIndex - 1);
+					setFocusIndex(prev);
+					scrollToIndex(prev);
+					if (!multiSelect) onSelect?.(getKey(items[prev]));
+					break;
+				}
+				case 'Home': {
+					e.preventDefault();
+					setFocusIndex(0);
+					scrollToIndex(0);
+					if (!multiSelect && items.length > 0) onSelect?.(getKey(items[0]));
+					break;
+				}
+				case 'End': {
+					e.preventDefault();
+					const last = items.length - 1;
+					setFocusIndex(last);
+					scrollToIndex(last);
+					if (!multiSelect && items.length > 0) onSelect?.(getKey(items[last]));
+					break;
+				}
+				case 'Enter':
+				case ' ': {
+					e.preventDefault();
+					const item = items[focusIndex];
+					if (item) {
+						onSelect?.(getKey(item));
+						if (e.key === 'Enter') onActivate?.(item);
+					}
+					break;
+				}
+			}
+		},
+		[focusIndex, items, clamp, scrollToIndex, onSelect, onActivate, getKey, multiSelect]
+	);
+
+	if (items.length === 0) {
+		return (
+			<div className={`flex h-full items-center justify-center text-label-13 text-gray-800 ${className}`}>
+				{emptyMessage}
+			</div>
+		);
+	}
+
+	return (
+		<div
+			ref={listRef}
+			className={`overflow-y-auto outline-none ${className}`}
+			role="listbox"
+			tabIndex={0}
+			onKeyDown={handleKeyDown}
+			aria-multiselectable={multiSelect}
+		>
+			{items.map((item, i) => {
+				const key = getKey(item);
+				const isSelected = selectedSet.has(key);
+				const isFocused = i === focusIndex;
+
+				return (
+					<div
+						key={key}
+						role="option"
+						aria-selected={isSelected}
+						className={`cursor-default select-none px-2 py-1 transition-colors
+              ${isSelected ? 'bg-blue-700/15 text-gray-1000' : 'text-gray-1000'}
+              ${isFocused && !isSelected ? 'bg-gray-alpha-100' : ''}
+              hover:bg-gray-alpha-200`}
+						onClick={() => {
+							setFocusIndex(i);
+							onSelect?.(key);
+						}}
+						onDoubleClick={() => onActivate?.(item)}
+					>
+						{renderItem(item, { selected: isSelected, focused: isFocused, index: i })}
+					</div>
+				);
+			})}
+		</div>
+	);
+}

package/src/primitives/property-panel.tsx

@@ -0,0 +1,108 @@
+'use client';
+
+import { type ReactNode } from 'react';
+import { Separator } from '../components/separator';
+
+// ---------------------------------------------------------------------------
+// PropertyPanel — key-value inspector panel (like Finder's "Get Info").
+//
+// Usage:
+//   <PropertyPanel title="File Info">
+//     <PropertyPanel.Section title="General">
+//       <PropertyPanel.Row label="Name" value="document.pdf" />
+//       <PropertyPanel.Row label="Size" value="2.4 MB" />
+//       <PropertyPanel.Row label="Modified" value="Feb 10, 2026" />
+//     </PropertyPanel.Section>
+//     <PropertyPanel.Section title="Permissions">
+//       <PropertyPanel.Row label="Owner" value="vercel-sandbox" />
+//       <PropertyPanel.Row label="Group" value="users" />
+//     </PropertyPanel.Section>
+//   </PropertyPanel>
+// ---------------------------------------------------------------------------
+
+interface PropertyPanelProps {
+	title?: string;
+	children: ReactNode;
+	className?: string;
+}
+
+function PropertyPanelRoot({ title, children, className = '' }: PropertyPanelProps) {
+	return (
+		<div className={`flex flex-col overflow-y-auto ${className}`}>
+			{title && (
+				<div className="sticky top-0 z-10 border-b border-gray-alpha-200 bg-background-100 px-3 py-2">
+					<h3 className="text-label-13 font-medium text-gray-1000">{title}</h3>
+				</div>
+			)}
+			<div className="flex flex-col">{children}</div>
+		</div>
+	);
+}
+
+// ---------------------------------------------------------------------------
+// PropertyPanel.Section
+// ---------------------------------------------------------------------------
+
+function PropertySection({
+	title,
+	children,
+	collapsible: _collapsible = false,
+	defaultOpen: _defaultOpen = true,
+}: {
+	title?: string;
+	children: ReactNode;
+	collapsible?: boolean;
+	defaultOpen?: boolean;
+}) {
+	return (
+		<div className="border-b border-gray-alpha-200 last:border-b-0">
+			{title && (
+				<div className="px-3 pt-3 pb-1">
+					<span className="text-label-13 font-medium text-gray-800">{title}</span>
+				</div>
+			)}
+			<div className={`px-3 pb-2 ${title ? '' : 'pt-2'}`}>{children}</div>
+		</div>
+	);
+}
+
+// ---------------------------------------------------------------------------
+// PropertyPanel.Row
+// ---------------------------------------------------------------------------
+
+interface PropertyRowProps {
+	label: string;
+	value?: ReactNode;
+	children?: ReactNode;
+	mono?: boolean;
+	copyable?: boolean;
+}
+
+function PropertyRow({ label, value, children, mono }: PropertyRowProps) {
+	return (
+		<div className="flex items-baseline justify-between gap-4 py-1">
+			<dt className="shrink-0 text-label-13 text-gray-800">{label}</dt>
+			<dd className={`min-w-0 truncate text-right text-label-13 text-gray-1000 ${mono ? 'font-mono' : ''}`}>
+				{children ?? value}
+			</dd>
+		</div>
+	);
+}
+
+// ---------------------------------------------------------------------------
+// PropertyPanel.Separator
+// ---------------------------------------------------------------------------
+
+function PropertySeparator() {
+	return <Separator className="my-1" />;
+}
+
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+
+export const PropertyPanel = Object.assign(PropertyPanelRoot, {
+	Section: PropertySection,
+	Row: PropertyRow,
+	Separator: PropertySeparator,
+});

package/src/primitives/section-header.tsx

@@ -0,0 +1,19 @@
+export function SectionHeader({
+	title,
+	description,
+	children,
+}: {
+	title: string;
+	description?: string;
+	children?: React.ReactNode;
+}) {
+	return (
+		<div className="mb-4 flex items-start justify-between">
+			<div>
+				<h2 className="text-copy-13 font-medium text-gray-1000">{title}</h2>
+				{description && <p className="mt-0.5 text-copy-13 text-gray-900">{description}</p>}
+			</div>
+			{children}
+		</div>
+	);
+}

package/src/primitives/sidebar-nav.tsx

@@ -0,0 +1,110 @@
+'use client';
+
+import type { ReactNode } from 'react';
+
+// ---------------------------------------------------------------------------
+// SidebarNav — reusable sidebar navigation for app shells.
+//
+// Extracts the repeated sidebar + tab-button pattern used across Settings,
+// AppStore, etc.  Designed to sit inside a SplitPane.Panel.
+//
+// Usage:
+//   <SidebarNav label="Settings" title="Settings">
+//     <SidebarNav.Item active={tab === "a"} onClick={() => setTab("a")} icon={<Icon />}>
+//       Appearance
+//     </SidebarNav.Item>
+//   </SidebarNav>
+//
+//   // Multiple sections:
+//   <SidebarNav label="App Store">
+//     <SidebarNav.Group title="Packages">
+//       <SidebarNav.Item ...>GUI Apps</SidebarNav.Item>
+//     </SidebarNav.Group>
+//     <SidebarNav.Group title="Repos">
+//       ...
+//     </SidebarNav.Group>
+//   </SidebarNav>
+// ---------------------------------------------------------------------------
+
+interface SidebarNavProps {
+	children: ReactNode;
+	/** Accessible label for the <nav> element */
+	label: string;
+	/** Optional heading displayed at the top of the sidebar */
+	title?: string;
+	className?: string;
+}
+
+function SidebarNavRoot({ children, label, title, className = '' }: SidebarNavProps) {
+	return (
+		<nav className={`flex flex-col py-2 ${className}`} aria-label={label}>
+			{title && (
+				<div className="px-3 pb-1">
+					<span className="text-copy-13 font-medium text-gray-800">{title}</span>
+				</div>
+			)}
+			{children}
+		</nav>
+	);
+}
+
+// ---------------------------------------------------------------------------
+// SidebarNav.Group — optional section divider with a title
+// ---------------------------------------------------------------------------
+
+interface SidebarNavGroupProps {
+	children: ReactNode;
+	title?: string;
+	className?: string;
+}
+
+function SidebarNavGroup({ children, title, className = '' }: SidebarNavGroupProps) {
+	return (
+		<div className={className}>
+			{title && (
+				<div className="px-3 pt-4 pb-1">
+					<span className="text-copy-13 font-medium text-gray-800">{title}</span>
+				</div>
+			)}
+			{children}
+		</div>
+	);
+}
+
+// ---------------------------------------------------------------------------
+// SidebarNav.Item — a single navigation button
+// ---------------------------------------------------------------------------
+
+interface SidebarNavItemProps {
+	children: ReactNode;
+	active?: boolean;
+	onClick?: () => void;
+	icon?: ReactNode;
+	/** Trailing content (e.g. a count badge) */
+	suffix?: ReactNode;
+	className?: string;
+}
+
+function SidebarNavItem({ children, active, onClick, icon, suffix, className = '' }: SidebarNavItemProps) {
+	return (
+		<button
+			onClick={onClick}
+			className={`mx-1 flex items-center gap-2 rounded-md px-2 py-1 text-copy-13 transition-colors ${
+				active ? 'bg-gray-alpha-200 text-gray-1000' : 'text-gray-900 hover:bg-gray-alpha-100 hover:text-gray-1000'
+			} ${className}`}
+		>
+			{icon && <span className="shrink-0 text-gray-800 [&>svg]:h-3.5 [&>svg]:w-3.5">{icon}</span>}
+			<span className="min-w-0 truncate">{children}</span>
+			{suffix && <span className="ml-auto font-mono text-copy-13 tabular-nums text-gray-700">{suffix}</span>}
+		</button>
+	);
+}
+
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+
+export const SidebarNav = Object.assign(SidebarNavRoot, {
+	Group: SidebarNavGroup,
+	Item: SidebarNavItem,
+});

package/src/primitives/split-pane.tsx

@@ -0,0 +1,146 @@
+'use client';
+
+import { type CSSProperties, type ReactNode, useCallback, useRef, useState, useSyncExternalStore } from 'react';
+
+// ---------------------------------------------------------------------------
+// SplitPane — resizable two-panel layout (horizontal or vertical).
+//
+// Usage:
+//   <SplitPane defaultSize={240} min={120} max={400}>
+//     <SplitPane.Panel>Sidebar</SplitPane.Panel>
+//     <SplitPane.Panel>Main</SplitPane.Panel>
+//   </SplitPane>
+//
+//   <SplitPane direction="vertical" defaultSize={200} min={100}>
+//     <SplitPane.Panel>Top</SplitPane.Panel>
+//     <SplitPane.Panel>Bottom</SplitPane.Panel>
+//   </SplitPane>
+// ---------------------------------------------------------------------------
+
+interface SplitPaneProps {
+	children: [ReactNode, ReactNode];
+	direction?: 'horizontal' | 'vertical';
+	defaultSize?: number;
+	min?: number;
+	max?: number;
+	/** On narrow viewports, stack panels vertically and hide the resize handle */
+	collapseBelow?: number;
+	onResize?: (size: number) => void;
+	className?: string;
+}
+
+function useMediaQuery(query: string) {
+	const subscribe = useCallback(
+		(callback: () => void) => {
+			const mql = window.matchMedia(query);
+			mql.addEventListener('change', callback);
+			return () => mql.removeEventListener('change', callback);
+		},
+		[query]
+	);
+	const getSnapshot = useCallback(() => window.matchMedia(query).matches, [query]);
+	const getServerSnapshot = useCallback(() => false, []);
+	return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+
+function SplitPaneRoot({
+	children,
+	direction = 'horizontal',
+	defaultSize = 240,
+	min = 100,
+	max = 600,
+	collapseBelow = 640,
+	onResize,
+	className = '',
+}: SplitPaneProps) {
+	const [size, setSize] = useState(defaultSize);
+	const containerRef = useRef<HTMLDivElement>(null);
+	const dragging = useRef(false);
+	const startPos = useRef(0);
+	const startSize = useRef(0);
+	const isMobile = useMediaQuery(`(max-width: ${collapseBelow}px)`);
+
+	const isHorizontal = direction === 'horizontal' && !isMobile;
+	const [first, second] = children;
+
+	const onPointerDown = useCallback(
+		(e: React.PointerEvent) => {
+			e.preventDefault();
+			dragging.current = true;
+			startPos.current = isHorizontal ? e.clientX : e.clientY;
+			startSize.current = size;
+			(e.target as HTMLElement).setPointerCapture(e.pointerId);
+		},
+		[isHorizontal, size]
+	);
+
+	const onPointerMove = useCallback(
+		(e: React.PointerEvent) => {
+			if (!dragging.current) return;
+			const delta = (isHorizontal ? e.clientX : e.clientY) - startPos.current;
+			const next = Math.min(max, Math.max(min, startSize.current + delta));
+			setSize(next);
+			onResize?.(next);
+		},
+		[isHorizontal, min, max, onResize]
+	);
+
+	const onPointerUp = useCallback(() => {
+		dragging.current = false;
+	}, []);
+
+	// On mobile, stack vertically with no resize handle
+	if (isMobile) {
+		return (
+			<div ref={containerRef} className={`flex flex-col h-full w-full overflow-hidden ${className}`}>
+				<div className="shrink-0 overflow-auto border-b border-gray-alpha-200">{first}</div>
+				<div className="flex-1 overflow-hidden">{second}</div>
+			</div>
+		);
+	}
+
+	const firstStyle: CSSProperties = isHorizontal
+		? { width: size, minWidth: min, maxWidth: max, flexShrink: 0 }
+		: { height: size, minHeight: min, maxHeight: max, flexShrink: 0 };
+
+	return (
+		<div
+			ref={containerRef}
+			className={`flex ${isHorizontal ? 'flex-row' : 'flex-col'} h-full w-full overflow-hidden ${className}`}
+		>
+			<div style={firstStyle} className="overflow-hidden">
+				{first}
+			</div>
+			<div
+				className={`shrink-0 ${
+					isHorizontal
+						? 'w-px cursor-col-resize hover:w-0.5 hover:bg-blue-700/50 active:w-0.5 active:bg-blue-700'
+						: 'h-px cursor-row-resize hover:h-0.5 hover:bg-blue-700/50 active:h-0.5 active:bg-blue-700'
+				} bg-gray-alpha-200 transition-colors`}
+				onPointerDown={onPointerDown}
+				onPointerMove={onPointerMove}
+				onPointerUp={onPointerUp}
+				role="separator"
+				aria-orientation={isHorizontal ? 'vertical' : 'horizontal'}
+				tabIndex={0}
+			/>
+			<div className="flex-1 overflow-hidden">{second}</div>
+		</div>
+	);
+}
+
+// ---------------------------------------------------------------------------
+// SplitPane.Panel — thin wrapper for semantic clarity
+// ---------------------------------------------------------------------------
+
+function Panel({ children, className = '' }: { children: ReactNode; className?: string }) {
+	return <div className={`h-full w-full overflow-auto ${className}`}>{children}</div>;
+}
+
+// ---------------------------------------------------------------------------
+// Export as compound component
+// ---------------------------------------------------------------------------
+
+export const SplitPane = Object.assign(SplitPaneRoot, {
+	Panel,
+});

package/src/primitives/status-badge.tsx

@@ -0,0 +1,10 @@
+import { Badge } from '../components/badge';
+
+export function StatusBadge({ status }: { status: string }) {
+	const variant = status === 'active' ? 'green' : status === 'creating' ? 'amber' : status === 'error' ? 'red' : 'gray';
+	return (
+		<Badge variant={variant} size="sm" contrast="low">
+			{status}
+		</Badge>
+	);
+}

package/src/primitives/status-bar.tsx

@@ -0,0 +1,100 @@
+'use client';
+
+import { type ReactNode } from 'react';
+import { Separator } from '../components/separator';
+
+// ---------------------------------------------------------------------------
+// StatusBar — bottom bar for app-level status, breadcrumbs, and indicators.
+//
+// Usage:
+//   <StatusBar>
+//     <StatusBar.Item>Ln 42, Col 18</StatusBar.Item>
+//     <StatusBar.Separator />
+//     <StatusBar.Item>UTF-8</StatusBar.Item>
+//     <StatusBar.Spacer />
+//     <StatusBar.Item icon={<CheckCircle />} variant="success">Saved</StatusBar.Item>
+//   </StatusBar>
+// ---------------------------------------------------------------------------
+
+interface StatusBarProps {
+	children: ReactNode;
+	className?: string;
+}
+
+function StatusBarRoot({ children, className = '' }: StatusBarProps) {
+	return (
+		<div
+			className={`flex h-6 shrink-0 items-center gap-0 border-t border-gray-alpha-200 bg-background-100 px-2 font-mono text-label-13 text-gray-900 ${className}`}
+			role="status"
+		>
+			{children}
+		</div>
+	);
+}
+
+// ---------------------------------------------------------------------------
+// StatusBar.Item
+// ---------------------------------------------------------------------------
+
+interface StatusBarItemProps {
+	children: ReactNode;
+	icon?: ReactNode;
+	variant?: 'default' | 'success' | 'warning' | 'error';
+	onClick?: () => void;
+	className?: string;
+}
+
+const variantColors = {
+	default: 'text-gray-900',
+	success: 'text-green-900',
+	warning: 'text-amber-900',
+	error: 'text-red-900',
+};
+
+function StatusBarItem({ children, icon, variant = 'default', onClick, className = '' }: StatusBarItemProps) {
+	const classes = `inline-flex items-center gap-1 px-1.5 py-0.5 rounded-sm ${variantColors[variant]} ${
+		onClick ? 'cursor-pointer hover:bg-gray-alpha-200 transition-colors' : ''
+	} ${className}`;
+
+	if (onClick) {
+		return (
+			<button className={classes} onClick={onClick}>
+				{icon}
+				{children}
+			</button>
+		);
+	}
+
+	return (
+		<span className={classes}>
+			{icon}
+			{children}
+		</span>
+	);
+}
+
+// ---------------------------------------------------------------------------
+// StatusBar.Separator
+// ---------------------------------------------------------------------------
+
+function StatusBarSeparator() {
+	return <Separator orientation="vertical" className="mx-0.5 h-3" />;
+}
+
+// ---------------------------------------------------------------------------
+// StatusBar.Spacer
+// ---------------------------------------------------------------------------
+
+function StatusBarSpacer() {
+	return <div className="flex-1" />;
+}
+
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+
+export const StatusBar = Object.assign(StatusBarRoot, {
+	Item: StatusBarItem,
+	Separator: StatusBarSeparator,
+	Spacer: StatusBarSpacer,
+});