@khal-os/ui 1.0.0

package/src/components/theme-switcher.tsx

@@ -0,0 +1,59 @@
+'use client';
+
+import { Monitor, Moon, Sun } from 'lucide-react';
+import { useTheme } from 'next-themes';
+import { useEffect, useState } from 'react';
+import { cn } from '../utils';
+
+const themes = [
+	{ value: 'system', label: 'System', icon: Monitor },
+	{ value: 'light', label: 'Light', icon: Sun },
+	{ value: 'dark', label: 'Dark', icon: Moon },
+] as const;
+
+interface ThemeSwitcherProps {
+	small?: boolean;
+	className?: string;
+	onThemeSwitch?: (theme: string) => void;
+	disabled?: boolean;
+}
+
+function ThemeSwitcher({ small, className, onThemeSwitch, disabled }: ThemeSwitcherProps) {
+	const { theme, setTheme } = useTheme();
+	const [mounted, setMounted] = useState(false);
+	useEffect(() => setMounted(true), []);
+
+	// Avoid hydration mismatch: useTheme() returns different values on server vs client
+	const resolvedTheme = mounted ? theme : undefined;
+
+	return (
+		<fieldset
+			className={cn('inline-flex items-center gap-1 rounded-lg bg-gray-alpha-100 p-1', className)}
+			disabled={disabled}
+		>
+			{themes.map(({ value, label, icon: Icon }) => (
+				<button
+					key={value}
+					type="button"
+					role="radio"
+					aria-checked={resolvedTheme === value}
+					onClick={() => {
+						setTheme(value);
+						onThemeSwitch?.(value);
+					}}
+					className={cn(
+						'inline-flex items-center gap-1.5 rounded-md px-2.5 py-1 text-label-12 transition-colors cursor-pointer',
+						resolvedTheme === value
+							? 'bg-background-100 text-gray-1000 shadow-sm'
+							: 'text-gray-700 hover:text-gray-1000'
+					)}
+				>
+					<Icon className={small ? 'h-3.5 w-3.5' : 'h-4 w-4'} />
+					{!small && label}
+				</button>
+			))}
+		</fieldset>
+	);
+}
+
+export { ThemeSwitcher };

package/src/components/ticker-bar.tsx

@@ -0,0 +1,41 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import { cn } from '../utils';
+
+interface TickerBarProps {
+	/** Items to scroll — rendered twice for seamless looping */
+	children: ReactNode;
+	/** Animation duration in seconds (default 30) */
+	duration?: number;
+	/** Pause on hover */
+	pauseOnHover?: boolean;
+	className?: string;
+}
+
+function TickerBar({ children, duration = 30, pauseOnHover = true, className }: TickerBarProps) {
+	return (
+		<div
+			className={cn('relative w-full overflow-hidden', className)}
+			style={{
+				maskImage: 'linear-gradient(to right, transparent, black 10%, black 90%, transparent)',
+				WebkitMaskImage: 'linear-gradient(to right, transparent, black 10%, black 90%, transparent)',
+			}}
+		>
+			<div
+				className={cn('flex w-max', pauseOnHover && 'hover:[animation-play-state:paused]')}
+				style={{
+					animation: `khal-ticker ${duration}s linear infinite`,
+				}}
+			>
+				<div className="flex shrink-0 items-center">{children}</div>
+				<div className="flex shrink-0 items-center" aria-hidden>
+					{children}
+				</div>
+			</div>
+		</div>
+	);
+}
+
+export type { TickerBarProps };
+export { TickerBar };

package/src/components/tooltip.tsx

@@ -0,0 +1,62 @@
+'use client';
+
+import * as TooltipPrimitive from '@radix-ui/react-tooltip';
+import * as React from 'react';
+import { cn } from '../utils';
+
+const TooltipProvider = TooltipPrimitive.Provider;
+const TooltipRoot = TooltipPrimitive.Root;
+const TooltipTrigger = TooltipPrimitive.Trigger;
+
+const TooltipContent = React.forwardRef<
+	React.ComponentRef<typeof TooltipPrimitive.Content>,
+	React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>
+>(({ className, sideOffset = 4, style, ...props }, ref) => (
+	<TooltipPrimitive.Portal>
+		<TooltipPrimitive.Content
+			ref={ref}
+			sideOffset={sideOffset}
+			className={cn(
+				'z-[9999] overflow-hidden rounded-md px-2.5 py-1 text-label-12',
+				'animate-in fade-in-0 zoom-in-95',
+				'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+				'data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
+				className
+			)}
+			style={{
+				background: 'var(--khal-text-primary, var(--ds-gray-1000))',
+				color: 'var(--khal-text-inverse, var(--ds-background-100))',
+				...style,
+			}}
+			{...props}
+		/>
+	</TooltipPrimitive.Portal>
+));
+TooltipContent.displayName = TooltipPrimitive.Content.displayName;
+
+interface SimpleTooltipProps {
+	text: React.ReactNode;
+	children: React.ReactNode;
+	position?: 'top' | 'bottom' | 'left' | 'right';
+	delay?: boolean;
+	delayTime?: number;
+	desktopOnly?: boolean;
+	className?: string;
+}
+
+function Tooltip({ text, children, position = 'top', delay, delayTime, desktopOnly, className }: SimpleTooltipProps) {
+	const delayDuration = delayTime ?? (delay ? 400 : 200);
+
+	return (
+		<TooltipProvider delayDuration={delayDuration}>
+			<TooltipRoot>
+				<TooltipTrigger asChild>{children}</TooltipTrigger>
+				<TooltipContent side={position} className={cn(desktopOnly && 'max-md:hidden', className)}>
+					{text}
+				</TooltipContent>
+			</TooltipRoot>
+		</TooltipProvider>
+	);
+}
+
+export { Tooltip, TooltipContent, TooltipProvider, TooltipRoot, TooltipTrigger };

package/src/components/window-minimized-context.tsx

@@ -0,0 +1,29 @@
+'use client';
+
+import { createContext, useContext } from 'react';
+
+/**
+ * Exposes the parent window's minimized state to deeply nested child components.
+ * Terminal panes use this to dispose WebGL contexts when minimized (GPU savings)
+ * and re-attach them on restore.
+ */
+const WindowMinimizedContext = createContext(false);
+
+export const WindowMinimizedProvider = WindowMinimizedContext.Provider;
+
+export function useWindowMinimized(): boolean {
+	return useContext(WindowMinimizedContext);
+}
+
+/**
+ * Exposes the parent window's focused/active state to child components.
+ * Apps use this to pause polling, animations, and heavy rendering when
+ * their window is behind another (app-nap behavior).
+ */
+const WindowActiveContext = createContext(true);
+
+export const WindowActiveProvider = WindowActiveContext.Provider;
+
+export function useWindowActive(): boolean {
+	return useContext(WindowActiveContext);
+}

package/src/hooks/useReducedMotion.ts

@@ -0,0 +1,21 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+/**
+ * Returns true when the user prefers reduced motion (OS setting or app toggle).
+ */
+export function useReducedMotion(): boolean {
+	const [reduced, setReduced] = useState(false);
+
+	useEffect(() => {
+		const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
+		setReduced(mq.matches || document.documentElement.dataset.reduceMotion === 'true');
+
+		const handler = (e: MediaQueryListEvent) => setReduced(e.matches);
+		mq.addEventListener('change', handler);
+		return () => mq.removeEventListener('change', handler);
+	}, []);
+
+	return reduced;
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+// App component props type
+export interface AppComponentProps {
+	windowId: string;
+	meta?: Record<string, unknown>;
+}
+
+// Auth — re-export from SDK
+export { SUBJECTS, useKhalAuth, useKhalAuth as useOSAuth, useNats, useNatsSubscription } from '@khal-os/sdk/app';
+// shadcn/ui components — local implementations
+export * from './components/avatar';
+export * from './components/badge';
+export * from './components/button';
+export * from './components/ContextMenu';
+export * from './components/command';
+// Design system components — local implementations
+export * from './components/cost-counter';
+// Design system components — LP section patterns
+export * from './components/data-row';
+export * from './components/dropdown-menu';
+export * from './components/glass-card';
+export * from './components/input';
+export * from './components/khal-logo';
+export * from './components/live-feed';
+export * from './components/mesh-gradient';
+export * from './components/metric-display';
+export * from './components/note';
+export * from './components/number-flow';
+export * from './components/pill-badge';
+export * from './components/progress-bar';
+export * from './components/section-card';
+export * from './components/separator';
+export * from './components/spinner';
+export * from './components/status-dot';
+export * from './components/switch';
+export * from './components/theme-provider';
+export * from './components/theme-switcher';
+export * from './components/ticker-bar';
+export * from './components/tooltip';
+export {
+	useWindowActive,
+	useWindowMinimized,
+	WindowActiveProvider,
+	WindowMinimizedProvider,
+} from './components/window-minimized-context';
+// Hooks
+export { useReducedMotion } from './hooks/useReducedMotion';
+// Animations
+export { fadeIn, fadeUp, khalEasing, scaleUp, springConfig, staggerChild, staggerContainer } from './lib/animations';
+// OS Primitives — local implementations
+export * from './primitives';
+export type { DesktopNotification, DesktopNotifMode, NotificationUrgency, TrayIcon } from './stores/notification-store';
+// Stores (OS-level state)
+export { useNotificationStore } from './stores/notification-store';
+export { useThemeStore } from './stores/theme-store';
+// LP Design Tokens
+export * from './tokens/lp-tokens';
+// Utilities
+export { cn } from './utils';

package/src/lib/animations.ts

@@ -0,0 +1,50 @@
+/**
+ * KhalOS animation presets — motion.js configurations for OS-wide use.
+ * Import these in components for consistent, branded animations.
+ */
+
+/** Custom easing curve — KhalOS primary */
+export const khalEasing = [0.22, 1, 0.36, 1] as const;
+
+/** Spring config for interactive elements */
+export const springConfig = {
+	stiffness: 300,
+	damping: 22,
+} as const;
+
+/** Window open animation — fade up with blur */
+export const fadeUp = {
+	initial: { opacity: 0, y: 12, filter: 'blur(4px)' },
+	animate: { opacity: 1, y: 0, filter: 'blur(0px)' },
+	transition: { duration: 0.7, ease: khalEasing },
+} as const;
+
+/** App launch animation — scale up with blur */
+export const scaleUp = {
+	initial: { opacity: 0, scale: 0.96, filter: 'blur(6px)' },
+	animate: { opacity: 1, scale: 1, filter: 'blur(0px)' },
+	transition: { duration: 0.9, ease: khalEasing },
+} as const;
+
+/** Stagger container — children appear with 0.12s delay */
+export const staggerContainer = {
+	animate: {
+		transition: {
+			staggerChildren: 0.12,
+		},
+	},
+} as const;
+
+/** Stagger child — each item fades up */
+export const staggerChild = {
+	initial: { opacity: 0, y: 8 },
+	animate: { opacity: 1, y: 0 },
+	transition: { duration: 0.4, ease: khalEasing },
+} as const;
+
+/** Fade in — simple opacity animation */
+export const fadeIn = {
+	initial: { opacity: 0 },
+	animate: { opacity: 1 },
+	transition: { duration: 0.5, ease: khalEasing },
+} as const;

package/src/primitives/collapsible-sidebar.tsx

@@ -0,0 +1,226 @@
+'use client';
+
+import { createContext, type ReactNode, useCallback, useContext, useRef, useState } from 'react';
+
+// ---------------------------------------------------------------------------
+// CollapsibleSidebar — resizable sidebar with collapse/expand toggle.
+//
+// Usage:
+//   <CollapsibleSidebar defaultSize={220} min={160} max={360}>
+//     <CollapsibleSidebar.Header>
+//       <span>Explorer</span>
+//       <CollapsibleSidebar.CollapseButton />
+//     </CollapsibleSidebar.Header>
+//     <CollapsibleSidebar.Content>
+//       <FileTree />
+//     </CollapsibleSidebar.Content>
+//   </CollapsibleSidebar>
+// ---------------------------------------------------------------------------
+
+interface SidebarContextValue {
+	collapsed: boolean;
+	toggle: () => void;
+	size: number;
+}
+
+const SidebarContext = createContext<SidebarContextValue>({
+	collapsed: false,
+	toggle: () => {},
+	size: 220,
+});
+
+export function useSidebar() {
+	return useContext(SidebarContext);
+}
+
+interface CollapsibleSidebarProps {
+	children: ReactNode;
+	defaultSize?: number;
+	min?: number;
+	max?: number;
+	defaultCollapsed?: boolean;
+	side?: 'left' | 'right';
+	className?: string;
+}
+
+function CollapsibleSidebarRoot({
+	children,
+	defaultSize = 220,
+	min = 140,
+	max = 400,
+	defaultCollapsed = false,
+	side = 'left',
+	className = '',
+}: CollapsibleSidebarProps) {
+	const [collapsed, setCollapsed] = useState(defaultCollapsed);
+	const [size, setSize] = useState(defaultSize);
+	const dragging = useRef(false);
+	const startX = useRef(0);
+	const startSize = useRef(0);
+
+	const toggle = useCallback(() => setCollapsed((v) => !v), []);
+
+	const onPointerDown = useCallback(
+		(e: React.PointerEvent) => {
+			if (collapsed) return;
+			e.preventDefault();
+			dragging.current = true;
+			startX.current = e.clientX;
+			startSize.current = size;
+			(e.target as HTMLElement).setPointerCapture(e.pointerId);
+		},
+		[collapsed, size]
+	);
+
+	const onPointerMove = useCallback(
+		(e: React.PointerEvent) => {
+			if (!dragging.current) return;
+			const delta = side === 'left' ? e.clientX - startX.current : startX.current - e.clientX;
+			setSize(Math.min(max, Math.max(min, startSize.current + delta)));
+		},
+		[side, min, max]
+	);
+
+	const onPointerUp = useCallback(() => {
+		dragging.current = false;
+	}, []);
+
+	const resizeHandle = (
+		<div
+			className={`w-px shrink-0 cursor-col-resize bg-gray-alpha-200 transition-colors hover:w-0.5 hover:bg-blue-700/50 active:w-0.5 active:bg-blue-700 ${
+				collapsed ? 'pointer-events-none' : ''
+			}`}
+			onPointerDown={onPointerDown}
+			onPointerMove={onPointerMove}
+			onPointerUp={onPointerUp}
+			role="separator"
+			aria-orientation="vertical"
+		/>
+	);
+
+	return (
+		<SidebarContext.Provider value={{ collapsed, toggle, size }}>
+			<div className={`flex shrink-0 ${className}`} style={{ width: collapsed ? 0 : size }}>
+				{side === 'right' && resizeHandle}
+				<div
+					className={`flex h-full flex-col overflow-hidden transition-[width] duration-150 ${
+						collapsed ? 'w-0' : 'w-full'
+					}`}
+				>
+					{children}
+				</div>
+				{side === 'left' && resizeHandle}
+			</div>
+		</SidebarContext.Provider>
+	);
+}
+
+// ---------------------------------------------------------------------------
+// CollapsibleSidebar.Header
+// ---------------------------------------------------------------------------
+
+function SidebarHeader({ children, className = '' }: { children: ReactNode; className?: string }) {
+	return (
+		<div className={`flex h-9 shrink-0 items-center justify-between border-b border-gray-alpha-200 px-3 ${className}`}>
+			{children}
+		</div>
+	);
+}
+
+// ---------------------------------------------------------------------------
+// CollapsibleSidebar.CollapseButton
+// ---------------------------------------------------------------------------
+
+function CollapseButton({ className = '' }: { className?: string }) {
+	const { collapsed, toggle } = useSidebar();
+	return (
+		<button
+			onClick={toggle}
+			className={`inline-flex h-5 w-5 items-center justify-center rounded text-gray-800 hover:bg-gray-alpha-200 hover:text-gray-1000 transition-colors ${className}`}
+			aria-label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
+		>
+			<svg width="12" height="12" viewBox="0 0 12 12" fill="none">
+				<path
+					d={collapsed ? 'M4.5 2L8.5 6L4.5 10' : 'M8.5 2L4.5 6L8.5 10'}
+					stroke="currentColor"
+					strokeWidth="1.5"
+					strokeLinecap="round"
+					strokeLinejoin="round"
+				/>
+			</svg>
+		</button>
+	);
+}
+
+// ---------------------------------------------------------------------------
+// CollapsibleSidebar.Content
+// ---------------------------------------------------------------------------
+
+function SidebarContent({ children, className = '' }: { children: ReactNode; className?: string }) {
+	return <div className={`flex-1 overflow-y-auto ${className}`}>{children}</div>;
+}
+
+// ---------------------------------------------------------------------------
+// CollapsibleSidebar.Section
+// ---------------------------------------------------------------------------
+
+function SidebarSection({
+	title,
+	children,
+	className = '',
+}: {
+	title?: string;
+	children: ReactNode;
+	className?: string;
+}) {
+	return (
+		<div className={`${className}`}>
+			{title && (
+				<div className="px-3 pt-2 pb-1">
+					<span className="text-label-13 font-medium text-gray-800">{title}</span>
+				</div>
+			)}
+			{children}
+		</div>
+	);
+}
+
+// ---------------------------------------------------------------------------
+// CollapsibleSidebar.Item
+// ---------------------------------------------------------------------------
+
+interface SidebarItemProps {
+	children: ReactNode;
+	icon?: ReactNode;
+	active?: boolean;
+	indent?: number;
+	onClick?: () => void;
+	className?: string;
+}
+
+function SidebarItem({ children, icon, active, indent = 0, onClick, className = '' }: SidebarItemProps) {
+	return (
+		<button
+			onClick={onClick}
+			className={`flex w-full items-center gap-2 rounded-md px-2 py-1 text-left text-label-13 transition-colors
+        ${active ? 'bg-gray-alpha-200 text-gray-1000' : 'text-gray-900 hover:bg-gray-alpha-100 hover:text-gray-1000'}
+        ${className}`}
+			style={{ paddingLeft: 8 + indent * 12 }}
+		>
+			{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>
+		</button>
+	);
+}
+
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+
+export const CollapsibleSidebar = Object.assign(CollapsibleSidebarRoot, {
+	Header: SidebarHeader,
+	CollapseButton,
+	Content: SidebarContent,
+	Section: SidebarSection,
+	Item: SidebarItem,
+});

package/src/primitives/dialog.tsx

@@ -0,0 +1,76 @@
+'use client';
+
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
+
+/* ------------------------------------------------------------------ */
+/*  Minimal compound Dialog primitive for OS chrome.                   */
+/*  Enough to satisfy DeleteConfirmDialog; expand as needed.           */
+/* ------------------------------------------------------------------ */
+
+interface DialogRootProps {
+	open: boolean;
+	onClose: () => void;
+	children: ReactNode;
+}
+
+function DialogRoot({ open, onClose, children }: DialogRootProps) {
+	if (!open) return null;
+	return (
+		<div className="fixed inset-0 z-50 flex items-center justify-center bg-black/40" onClick={onClose}>
+			<div
+				className="bg-popover text-popover-foreground rounded-lg border p-6 shadow-lg"
+				onClick={(e) => e.stopPropagation()}
+			>
+				{children}
+			</div>
+		</div>
+	);
+}
+
+function Body({ children }: { children: ReactNode }) {
+	return <div className="flex items-start gap-4">{children}</div>;
+}
+
+function Icon({ children, variant: _variant }: { children: ReactNode; variant?: string }) {
+	return <div className="shrink-0">{children}</div>;
+}
+
+function Title({ children }: { children: ReactNode }) {
+	return <h2 className="text-lg font-semibold">{children}</h2>;
+}
+
+function Description({ children }: { children: ReactNode }) {
+	return <p className="text-muted-foreground text-sm">{children}</p>;
+}
+
+function Actions({ children }: { children: ReactNode }) {
+	return <div className="mt-4 flex justify-end gap-2">{children}</div>;
+}
+
+type BtnProps = ButtonHTMLAttributes<HTMLButtonElement> & { variant?: string };
+
+function Cancel({ children, ...props }: BtnProps) {
+	return (
+		<button type="button" className="rounded px-3 py-1.5 text-sm hover:bg-muted" {...props}>
+			{children}
+		</button>
+	);
+}
+
+function Confirm({ children, variant: _variant, ...props }: BtnProps) {
+	return (
+		<button type="button" className="rounded bg-destructive px-3 py-1.5 text-sm text-destructive-foreground" {...props}>
+			{children}
+		</button>
+	);
+}
+
+export const Dialog = Object.assign(DialogRoot, {
+	Body,
+	Icon,
+	Title,
+	Description,
+	Actions,
+	Cancel,
+	Confirm,
+});

package/src/primitives/empty-state.tsx

@@ -0,0 +1,43 @@
+'use client';
+
+import { type ReactNode } from 'react';
+
+// ---------------------------------------------------------------------------
+// EmptyState — placeholder for empty views (no files, no results, etc.).
+//
+// Usage:
+//   <EmptyState
+//     icon={<FolderOpen />}
+//     title="No files"
+//     description="This folder is empty."
+//     action={<Button onClick={upload}>Upload File</Button>}
+//   />
+// ---------------------------------------------------------------------------
+
+interface EmptyStateProps {
+	icon?: ReactNode;
+	title: string;
+	description?: string;
+	action?: ReactNode;
+	compact?: boolean;
+	className?: string;
+}
+
+export function EmptyState({ icon, title, description, action, compact, className = '' }: EmptyStateProps) {
+	return (
+		<div
+			className={`flex flex-col items-center justify-center text-center ${
+				compact ? 'gap-2 py-6' : 'gap-3 py-12'
+			} ${className}`}
+		>
+			{icon && (
+				<div className={`text-gray-700 ${compact ? '[&>svg]:h-5 [&>svg]:w-5' : '[&>svg]:h-8 [&>svg]:w-8'}`}>{icon}</div>
+			)}
+			<div className="space-y-0.5">
+				<p className="text-label-13 font-medium text-gray-1000">{title}</p>
+				{description && <p className={`text-gray-800 ${compact ? 'text-label-13' : 'text-label-13'}`}>{description}</p>}
+			</div>
+			{action && <div className="mt-2 shrink-0">{action}</div>}
+		</div>
+	);
+}