@rangka/client 0.0.1

package/src/shell/ShellLayout.tsx

@@ -0,0 +1,231 @@
+import React, { useCallback, useEffect, useMemo } from 'react';
+import type { ReactNode } from 'react';
+import { XIcon } from 'lucide-react';
+import {
+  SidebarProvider,
+  SidebarInset,
+  SidebarTrigger,
+  Sidebar,
+  SidebarHeader,
+  SidebarContent,
+} from '@/components/ui/sidebar';
+import { Separator } from '@/components/ui/separator';
+import {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from '@/components/ui/breadcrumb';
+import { Button } from '@/components/ui/button';
+import { Icon } from '@/components/Icon';
+import { AppSidebar } from './app-sidebar/index.js';
+import type { AppSidebarNavSection, AppSidebarModule } from './app-sidebar/types.js';
+import { CommandPalette } from './CommandPalette.js';
+import { HeaderActions } from './HeaderActions.js';
+import { ShellDevTools } from './ShellDevTools.js';
+import { DrawerProvider, useDrawer } from './DrawerContext.js';
+import { ShellAPIProvider } from './ShellContext.js';
+import { useMeta } from '../context/MetaContext.js';
+import { useModule } from '../context/ModuleContext.js';
+import { useBootContext } from '../boot/BootProvider.js';
+import { useRouter, useRouterState } from '@tanstack/react-router';
+import { useBreadcrumbs } from './useBreadcrumbs.js';
+import type { NavigationTree } from '@rangka/shared';
+
+function ShellLayoutInner({ children }: { children: ReactNode }) {
+  const router = useRouter();
+  const currentPath = useRouterState({ select: (s) => s.location.pathname });
+  const { navigation, pages } = useMeta();
+  const { activeModule, setActiveModule, clearActiveModule } = useModule();
+  const { state } = useBootContext();
+  const { state: drawerState, closeDrawer } = useDrawer();
+
+  useEffect(() => {
+    const pathModule = currentPath.split('/').filter(Boolean)[0];
+    if (pathModule && navigation.some((n: NavigationTree) => n.module === pathModule)) {
+      setActiveModule(pathModule);
+    } else if (currentPath === '/') {
+      clearActiveModule();
+    }
+  }, [currentPath, navigation, setActiveModule, clearActiveModule]);
+
+  const handleNavigate = useCallback(
+    (path: string) => {
+      router.navigate({ to: path });
+    },
+    [router],
+  );
+
+  const currentPage = useMemo(() => {
+    const parts = currentPath.split('/').filter(Boolean);
+    if (parts.length >= 2) {
+      const pageKey = `${parts[0]}.${parts[1]}`;
+      return pages.find((p) => p.key === pageKey);
+    }
+    return undefined;
+  }, [currentPath, pages]);
+
+  const crumbs = useBreadcrumbs(currentPath, navigation, pages);
+
+  const handleAction = useCallback((action: string) => {
+    document.dispatchEvent(new CustomEvent('rangka:action', { detail: { action }, bubbles: true }));
+  }, []);
+
+  const headerActions = currentPage?.actions?.length ? (
+    <HeaderActions actions={currentPage.actions} onAction={handleAction} />
+  ) : undefined;
+
+  const modules: AppSidebarModule[] = navigation.map((mod: NavigationTree) => ({
+    name: mod.module,
+    label: mod.label,
+    icon: mod.icon ? <Icon name={mod.icon} size={14} /> : undefined,
+  }));
+
+  const sidebarNavigation: AppSidebarNavSection[] = useMemo(() => {
+    const activeNav = activeModule
+      ? navigation.filter((mod: NavigationTree) => mod.module === activeModule)
+      : [];
+    return activeNav.flatMap((mod: NavigationTree) =>
+      mod.sections.map((section) => ({
+        title: section.section,
+        icon: section.items[0]?.icon ? <Icon name={section.items[0].icon} /> : undefined,
+        items: section.items.map((item) => ({
+          title: item.label,
+          url: '/' + item.page.replace('.', '/'),
+        })),
+      })),
+    );
+  }, [activeModule, navigation]);
+
+  const handleModuleSwitch = useCallback(
+    (moduleName: string) => {
+      setActiveModule(moduleName);
+      const mod = navigation.find((n: NavigationTree) => n.module === moduleName);
+      const firstPage = mod?.sections[0]?.items[0]?.page;
+      if (firstPage) {
+        router.navigate({ to: '/' + firstPage.replace('.', '/') });
+      }
+    },
+    [navigation, router, setActiveModule],
+  );
+
+  const handleAllModules = useCallback(() => {
+    clearActiveModule();
+    router.navigate({ to: '/' });
+  }, [clearActiveModule, router]);
+
+  const handleLogout = useCallback(() => {
+    document.dispatchEvent(new CustomEvent('rangka:logout'));
+  }, []);
+
+  const handlePreferences = useCallback(() => {
+    router.navigate({ to: '/preferences' });
+  }, [router]);
+
+  const user =
+    state.status === 'ready'
+      ? { name: state.data.user.name, email: state.data.user.email }
+      : undefined;
+
+  const handleSearch = useCallback(() => {
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'k', ctrlKey: true }));
+  }, []);
+
+  const isModuleSelectorPage = !activeModule;
+
+  return (
+    <SidebarProvider className="h-svh !min-h-0">
+      <AppSidebar
+        modules={modules}
+        activeModule={activeModule ?? undefined}
+        onModuleSwitch={handleModuleSwitch}
+        onAllModules={handleAllModules}
+        onSearch={handleSearch}
+        navigation={sidebarNavigation}
+        currentPath={currentPath}
+        onNavigate={handleNavigate}
+        user={user}
+        onLogout={handleLogout}
+        onPreferences={handlePreferences}
+      />
+      <SidebarInset className="overflow-hidden">
+        <header className="flex h-12 shrink-0 items-center gap-2 border-b border-border bg-background px-4">
+          <SidebarTrigger className="-ml-1" />
+          {isModuleSelectorPage ? (
+            <>
+              <Separator orientation="vertical" className="mr-2" />
+              <span className="text-sm font-medium">Select Module</span>
+            </>
+          ) : (
+            <>
+              <Separator orientation="vertical" className="mr-2" />
+              <Breadcrumb>
+                <BreadcrumbList>
+                  {crumbs.map((crumb, i) => {
+                    const isLast = i === crumbs.length - 1;
+                    return (
+                      <React.Fragment key={crumb.path ?? crumb.label}>
+                        <BreadcrumbItem>
+                          {!isLast ? (
+                            <BreadcrumbLink
+                              asChild
+                              onClick={(e: React.MouseEvent) => {
+                                e.preventDefault();
+                                if (crumb.path) handleNavigate(crumb.path);
+                              }}
+                            >
+                              <a href={crumb.path ?? '#'}>{crumb.label}</a>
+                            </BreadcrumbLink>
+                          ) : (
+                            <BreadcrumbPage>{crumb.label}</BreadcrumbPage>
+                          )}
+                        </BreadcrumbItem>
+                        {!isLast && <BreadcrumbSeparator />}
+                      </React.Fragment>
+                    );
+                  })}
+                </BreadcrumbList>
+              </Breadcrumb>
+              {headerActions && (
+                <div className="ml-auto flex items-center gap-2">{headerActions}</div>
+              )}
+            </>
+          )}
+        </header>
+        <main className="flex-1 overflow-auto bg-muted">{children}</main>
+      </SidebarInset>
+
+      {drawerState.open && (
+        <Sidebar side="right" collapsible="none" className="w-80 border-l">
+          <SidebarHeader className="flex flex-row items-center justify-between border-b px-4 py-3">
+            <div>
+              {drawerState.title && <h3 className="text-sm font-medium">{drawerState.title}</h3>}
+              {drawerState.description && (
+                <p className="text-xs text-muted-foreground">{drawerState.description}</p>
+              )}
+            </div>
+            <Button variant="ghost" size="icon-sm" onClick={closeDrawer} aria-label="Close panel">
+              <XIcon />
+            </Button>
+          </SidebarHeader>
+          <SidebarContent className="p-4">{drawerState.content}</SidebarContent>
+        </Sidebar>
+      )}
+
+      <CommandPalette />
+      <ShellDevTools />
+    </SidebarProvider>
+  );
+}
+
+export function ShellLayout({ children }: { children: ReactNode }) {
+  return (
+    <DrawerProvider>
+      <ShellAPIProvider>
+        <ShellLayoutInner>{children}</ShellLayoutInner>
+      </ShellAPIProvider>
+    </DrawerProvider>
+  );
+}

package/src/shell/Toast.tsx

@@ -0,0 +1,58 @@
+import { useEffect, useRef, type ElementType } from 'react';
+import { InfoIcon, CheckCircleIcon, AlertTriangleIcon, AlertCircleIcon, XIcon } from 'lucide-react';
+import { cn } from '@/lib/utils';
+
+export type ToastType = 'info' | 'success' | 'warning' | 'error';
+
+export interface ToastProps {
+  message: string;
+  type: ToastType;
+  onDismiss: () => void;
+}
+
+const iconMap: Record<ToastType, ElementType> = {
+  info: InfoIcon,
+  success: CheckCircleIcon,
+  warning: AlertTriangleIcon,
+  error: AlertCircleIcon,
+};
+
+const colorMap: Record<ToastType, string> = {
+  info: 'border-blue-200 bg-blue-50 text-blue-900 dark:border-blue-800 dark:bg-blue-950 dark:text-blue-100',
+  success:
+    'border-green-200 bg-green-50 text-green-900 dark:border-green-800 dark:bg-green-950 dark:text-green-100',
+  warning:
+    'border-yellow-200 bg-yellow-50 text-yellow-900 dark:border-yellow-800 dark:bg-yellow-950 dark:text-yellow-100',
+  error:
+    'border-red-200 bg-red-50 text-red-900 dark:border-red-800 dark:bg-red-950 dark:text-red-100',
+};
+
+export function Toast({ message, type, onDismiss }: ToastProps) {
+  const timerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
+  const IconComp = iconMap[type];
+
+  useEffect(() => {
+    timerRef.current = setTimeout(onDismiss, 4000);
+    return () => clearTimeout(timerRef.current);
+  }, [onDismiss]);
+
+  return (
+    <div
+      className={cn(
+        'pointer-events-auto flex items-center gap-2 rounded-md border px-3 py-2 text-sm shadow-sm',
+        colorMap[type],
+      )}
+      role="alert"
+    >
+      <IconComp className="size-4 shrink-0" />
+      <span className="flex-1">{message}</span>
+      <button
+        onClick={onDismiss}
+        className="shrink-0 rounded-sm p-0.5 opacity-70 hover:opacity-100"
+        aria-label="Dismiss"
+      >
+        <XIcon className="size-3.5" />
+      </button>
+    </div>
+  );
+}

package/src/shell/ToastProvider.tsx

@@ -0,0 +1,60 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { ReactNode } from 'react';
+import { Toast } from './Toast.js';
+import type { ToastType } from './ShellContext.js';
+
+interface ToastItem {
+  id: string;
+  message: string;
+  type: ToastType;
+}
+
+let idCounter = 0;
+
+export function ToastProvider({ children }: { children: ReactNode }) {
+  const [toasts, setToasts] = useState<ToastItem[]>([]);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const addToast = useCallback((message: string, type: ToastType) => {
+    const id = String(++idCounter);
+    setToasts((prev) => {
+      const next = [...prev, { id, message, type }];
+      if (next.length > 5) return next.slice(next.length - 5);
+      return next;
+    });
+  }, []);
+
+  const removeToast = useCallback((id: string) => {
+    setToasts((prev) => prev.filter((t) => t.id !== id));
+  }, []);
+
+  useEffect(() => {
+    const handler = (e: Event) => {
+      const { message, type } = (e as CustomEvent).detail;
+      addToast(message, type ?? 'info');
+    };
+    document.addEventListener('rangka:toast', handler);
+    return () => document.removeEventListener('rangka:toast', handler);
+  }, [addToast]);
+
+  return (
+    <>
+      {children}
+      <div
+        ref={containerRef}
+        aria-live="polite"
+        role="status"
+        className="fixed bottom-4 right-4 z-[100] flex flex-col gap-2 pointer-events-none"
+      >
+        {toasts.map((toast) => (
+          <Toast
+            key={toast.id}
+            message={toast.message}
+            type={toast.type}
+            onDismiss={() => removeToast(toast.id)}
+          />
+        ))}
+      </div>
+    </>
+  );
+}

package/src/shell/app-sidebar/AppSidebar.tsx

@@ -0,0 +1,44 @@
+import { Sidebar, SidebarHeader, SidebarContent, SidebarFooter } from '@/components/ui/sidebar';
+import { ModuleSwitcher } from './ModuleSwitcher';
+import { SearchMenu } from './SearchMenu';
+import { NavMain } from './NavMain';
+import { NavUser } from './NavUser';
+import type { AppSidebarProps } from './types';
+
+export function AppSidebar({
+  modules,
+  activeModule,
+  onModuleSwitch,
+  onAllModules,
+  onSearch,
+  navigation,
+  currentPath,
+  onNavigate,
+  user,
+  onLogout,
+  onPreferences,
+}: AppSidebarProps) {
+  return (
+    <Sidebar collapsible="offcanvas">
+      <SidebarHeader>
+        <ModuleSwitcher
+          modules={modules}
+          activeModule={activeModule}
+          onModuleSwitch={onModuleSwitch}
+          onAllModules={onAllModules}
+        />
+        {onSearch && <SearchMenu onSearch={onSearch} />}
+      </SidebarHeader>
+      <SidebarContent>
+        {navigation.length > 0 && (
+          <NavMain sections={navigation} currentPath={currentPath} onNavigate={onNavigate} />
+        )}
+      </SidebarContent>
+      {user && (
+        <SidebarFooter>
+          <NavUser user={user} onLogout={onLogout} onPreferences={onPreferences} />
+        </SidebarFooter>
+      )}
+    </Sidebar>
+  );
+}

package/src/shell/app-sidebar/ModuleSwitcher.tsx

@@ -0,0 +1,87 @@
+import { ChevronsUpDownIcon, LayoutGridIcon } from 'lucide-react';
+import {
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuButton,
+  useSidebar,
+} from '@/components/ui/sidebar';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import type { AppSidebarModule } from './types';
+
+interface ModuleSwitcherProps {
+  modules: AppSidebarModule[];
+  activeModule?: string;
+  onModuleSwitch: (name: string) => void;
+  onAllModules?: () => void;
+}
+
+export function ModuleSwitcher({
+  modules,
+  activeModule,
+  onModuleSwitch,
+  onAllModules,
+}: ModuleSwitcherProps) {
+  const { isMobile } = useSidebar();
+  const active = modules.find((m) => m.name === activeModule) ?? modules[0];
+
+  if (!active) return null;
+
+  return (
+    <SidebarMenu>
+      <SidebarMenuItem>
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <SidebarMenuButton
+              size="lg"
+              className="data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground"
+            >
+              <div className="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+                {active.icon ?? <span className="text-xs font-bold">{active.label[0]}</span>}
+              </div>
+              <div className="grid flex-1 text-left text-sm leading-tight">
+                <span className="truncate font-medium">{active.label}</span>
+              </div>
+              <ChevronsUpDownIcon className="ml-auto" />
+            </SidebarMenuButton>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent
+            className="w-[--radix-dropdown-menu-trigger-width] min-w-48"
+            align="start"
+            side={isMobile ? 'bottom' : 'bottom'}
+            sideOffset={4}
+          >
+            {modules.map((mod) => (
+              <DropdownMenuItem
+                key={mod.name}
+                onClick={() => onModuleSwitch(mod.name)}
+                className="gap-2 p-2"
+              >
+                <div className="flex size-6 items-center justify-center rounded-md border">
+                  {mod.icon ?? <span className="text-xs">{mod.label[0]}</span>}
+                </div>
+                {mod.label}
+              </DropdownMenuItem>
+            ))}
+            {onAllModules && (
+              <>
+                <DropdownMenuSeparator />
+                <DropdownMenuItem onClick={onAllModules} className="gap-2 p-2">
+                  <div className="flex size-6 items-center justify-center rounded-md border bg-transparent">
+                    <LayoutGridIcon />
+                  </div>
+                  All modules
+                </DropdownMenuItem>
+              </>
+            )}
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </SidebarMenuItem>
+    </SidebarMenu>
+  );
+}

package/src/shell/app-sidebar/NavMain.tsx

@@ -0,0 +1,64 @@
+import { ChevronRightIcon } from 'lucide-react';
+import {
+  SidebarGroup,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuButton,
+  SidebarMenuSub,
+  SidebarMenuSubButton,
+  SidebarMenuSubItem,
+} from '@/components/ui/sidebar';
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@/components/ui/collapsible';
+import type { AppSidebarNavSection } from './types';
+
+interface NavMainProps {
+  sections: AppSidebarNavSection[];
+  currentPath: string;
+  onNavigate: (url: string) => void;
+}
+
+export function NavMain({ sections, currentPath, onNavigate }: NavMainProps) {
+  return (
+    <SidebarGroup>
+      <SidebarMenu>
+        {sections.map((section) => (
+          <Collapsible
+            key={section.title}
+            asChild
+            defaultOpen={section.items.some((item) => currentPath === item.url)}
+            className="group/collapsible"
+          >
+            <SidebarMenuItem>
+              <CollapsibleTrigger asChild>
+                <SidebarMenuButton tooltip={section.title}>
+                  {section.icon}
+                  <span>{section.title}</span>
+                  <ChevronRightIcon className="ml-auto transition-transform duration-200 group-data-[state=open]/collapsible:rotate-90" />
+                </SidebarMenuButton>
+              </CollapsibleTrigger>
+              <CollapsibleContent>
+                <SidebarMenuSub>
+                  {section.items.map((item) => (
+                    <SidebarMenuSubItem key={item.url}>
+                      <SidebarMenuSubButton asChild isActive={currentPath === item.url}>
+                        <a
+                          href={item.url}
+                          onClick={(e) => {
+                            e.preventDefault();
+                            onNavigate(item.url);
+                          }}
+                        >
+                          <span>{item.title}</span>
+                        </a>
+                      </SidebarMenuSubButton>
+                    </SidebarMenuSubItem>
+                  ))}
+                </SidebarMenuSub>
+              </CollapsibleContent>
+            </SidebarMenuItem>
+          </Collapsible>
+        ))}
+      </SidebarMenu>
+    </SidebarGroup>
+  );
+}

package/src/shell/app-sidebar/NavUser.tsx

@@ -0,0 +1,97 @@
+import { ChevronsUpDownIcon, LogOutIcon, SettingsIcon } from 'lucide-react';
+import {
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuButton,
+  useSidebar,
+} from '@/components/ui/sidebar';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
+import type { AppSidebarUser } from './types';
+
+function getInitials(name: string): string {
+  return name
+    .split(' ')
+    .map((w) => w[0])
+    .filter(Boolean)
+    .slice(0, 2)
+    .join('')
+    .toUpperCase();
+}
+
+interface NavUserProps {
+  user: AppSidebarUser;
+  onLogout?: () => void;
+  onPreferences?: () => void;
+}
+
+export function NavUser({ user, onLogout, onPreferences }: NavUserProps) {
+  const { isMobile: _isMobile } = useSidebar();
+
+  return (
+    <SidebarMenu>
+      <SidebarMenuItem>
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <SidebarMenuButton
+              size="lg"
+              className="data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground"
+            >
+              <Avatar className="h-8 w-8 rounded-lg">
+                {user.avatar && <AvatarImage src={user.avatar} alt={user.name} />}
+                <AvatarFallback className="rounded-lg">{getInitials(user.name)}</AvatarFallback>
+              </Avatar>
+              <div className="grid flex-1 text-left text-sm leading-tight">
+                <span className="truncate font-medium">{user.name}</span>
+                <span className="truncate text-xs">{user.email}</span>
+              </div>
+              <ChevronsUpDownIcon className="ml-auto size-4" />
+            </SidebarMenuButton>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent
+            className="w-[--radix-dropdown-menu-trigger-width] min-w-48"
+            side="top"
+            align="start"
+            sideOffset={4}
+          >
+            <DropdownMenuLabel className="p-0 font-normal">
+              <div className="flex items-center gap-2 px-1 py-1.5 text-left text-sm">
+                <Avatar className="h-8 w-8 rounded-lg">
+                  {user.avatar && <AvatarImage src={user.avatar} alt={user.name} />}
+                  <AvatarFallback className="rounded-lg">{getInitials(user.name)}</AvatarFallback>
+                </Avatar>
+                <div className="grid flex-1 text-left text-sm leading-tight">
+                  <span className="truncate font-medium">{user.name}</span>
+                  <span className="truncate text-xs">{user.email}</span>
+                </div>
+              </div>
+            </DropdownMenuLabel>
+            <DropdownMenuSeparator />
+            {onPreferences && (
+              <DropdownMenuItem onClick={onPreferences}>
+                <SettingsIcon />
+                Preferences
+              </DropdownMenuItem>
+            )}
+            {onLogout && (
+              <>
+                <DropdownMenuSeparator />
+                <DropdownMenuItem onClick={onLogout}>
+                  <LogOutIcon />
+                  Log out
+                </DropdownMenuItem>
+              </>
+            )}
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </SidebarMenuItem>
+    </SidebarMenu>
+  );
+}

package/src/shell/app-sidebar/SearchMenu.tsx

@@ -0,0 +1,22 @@
+import { SearchIcon } from 'lucide-react';
+import { SidebarMenu, SidebarMenuItem, SidebarMenuButton } from '@/components/ui/sidebar';
+
+interface SearchMenuProps {
+  onSearch: () => void;
+}
+
+export function SearchMenu({ onSearch }: SearchMenuProps) {
+  return (
+    <SidebarMenu>
+      <SidebarMenuItem>
+        <SidebarMenuButton onClick={onSearch} tooltip="Search">
+          <SearchIcon />
+          <span>Search</span>
+          <kbd className="ml-auto rounded border border-sidebar-border bg-sidebar px-1.5 py-0.5 text-[10px] font-medium text-sidebar-foreground/70">
+            Ctrl K
+          </kbd>
+        </SidebarMenuButton>
+      </SidebarMenuItem>
+    </SidebarMenu>
+  );
+}

package/src/shell/app-sidebar/index.ts

@@ -0,0 +1,8 @@
+export { AppSidebar } from './AppSidebar';
+export type {
+  AppSidebarProps,
+  AppSidebarModule,
+  AppSidebarNavSection,
+  AppSidebarNavItem,
+  AppSidebarUser,
+} from './types';