@rangka/client 0.0.1

package/src/router/hooks.ts

@@ -0,0 +1,43 @@
+import {
+  useNavigate as useTanstackNavigate,
+  useParams as useTanstackParams,
+  useSearch,
+  useMatches,
+  useRouter,
+} from '@tanstack/react-router';
+
+export function useNavigate() {
+  const navigate = useTanstackNavigate();
+  return (to: string, options?: { replace?: boolean }) => {
+    navigate({ to, replace: options?.replace });
+  };
+}
+
+export function useParams(): Record<string, string> {
+  return useTanstackParams({ strict: false }) as Record<string, string>;
+}
+
+export function useRoute(): { pageKey: string | undefined; path: string } {
+  const router = useRouter();
+  const matches = useMatches();
+  const currentMatch = matches[matches.length - 1];
+  const path = router.state.location.pathname;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const pageKey = (currentMatch?.staticData as any)?.pageKey as string | undefined;
+  return { pageKey, path };
+}
+
+export function useSearchParams(): [URLSearchParams, (params: Record<string, string>) => void] {
+  const search = useSearch({ strict: false }) as Record<string, string>;
+  const navigate = useTanstackNavigate();
+
+  const searchParams = new URLSearchParams(search);
+
+  const setSearchParams = (params: Record<string, string>) => {
+    const merged = { ...search, ...params };
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    navigate({ search: merged as any });
+  };
+
+  return [searchParams, setSearchParams];
+}

package/src/shell/CommandPalette.tsx

@@ -0,0 +1,76 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useRouter } from '@tanstack/react-router';
+import {
+  Command,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+} from '@/components/ui/command';
+import { Dialog, DialogContent } from '@/components/ui/dialog';
+import { useMeta } from '../context/MetaContext.js';
+
+export interface CommandPaletteGroup {
+  group: string;
+  items: { id: string; label: string }[];
+}
+
+export function CommandPalette() {
+  const [open, setOpen] = useState(false);
+  const { pages } = useMeta();
+  const router = useRouter();
+
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+        e.preventDefault();
+        setOpen((prev) => !prev);
+      }
+    };
+    document.addEventListener('keydown', handler);
+    return () => document.removeEventListener('keydown', handler);
+  }, []);
+
+  const groups = useMemo((): CommandPaletteGroup[] => {
+    return [
+      {
+        group: 'Pages',
+        items: pages.map((page) => ({
+          id: page.path ?? '/' + page.key.replace('.', '/'),
+          label: page.label,
+        })),
+      },
+    ];
+  }, [pages]);
+
+  const handleSelect = useCallback(
+    (itemId: string) => {
+      setOpen(false);
+      router.navigate({ to: itemId });
+    },
+    [router],
+  );
+
+  return (
+    <Dialog open={open} onOpenChange={setOpen}>
+      <DialogContent className="overflow-hidden p-0 sm:max-w-lg">
+        <Command className="[&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:text-xs [&_[cmdk-group-heading]]:text-muted-foreground">
+          <CommandInput placeholder="Search pages..." />
+          <CommandList>
+            <CommandEmpty>No results found.</CommandEmpty>
+            {groups.map((group) => (
+              <CommandGroup key={group.group} heading={group.group}>
+                {group.items.map((item) => (
+                  <CommandItem key={item.id} onSelect={() => handleSelect(item.id)}>
+                    {item.label}
+                  </CommandItem>
+                ))}
+              </CommandGroup>
+            ))}
+          </CommandList>
+        </Command>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/src/shell/ConfirmDialog.tsx

@@ -0,0 +1,34 @@
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+  DialogFooter,
+} from '@/components/ui/dialog';
+import { Button } from '@/components/ui/button';
+
+export interface ConfirmDialogProps {
+  message: string;
+  onConfirm: () => void;
+  onCancel: () => void;
+}
+
+export function ConfirmDialog({ message, onConfirm, onCancel }: ConfirmDialogProps) {
+  return (
+    <Dialog open onOpenChange={(open) => !open && onCancel()}>
+      <DialogContent className="sm:max-w-sm">
+        <DialogHeader>
+          <DialogTitle>Confirm</DialogTitle>
+          <DialogDescription>{message}</DialogDescription>
+        </DialogHeader>
+        <DialogFooter>
+          <Button variant="outline" onClick={onCancel}>
+            Cancel
+          </Button>
+          <Button onClick={onConfirm}>Confirm</Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/src/shell/ConfirmProvider.tsx

@@ -0,0 +1,56 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { ReactNode } from 'react';
+import { ConfirmDialog } from './ConfirmDialog.js';
+
+interface ConfirmRequest {
+  message: string;
+  resolve: (value: boolean) => void;
+}
+
+export function ConfirmProvider({ children }: { children: ReactNode }) {
+  const [current, setCurrent] = useState<ConfirmRequest | null>(null);
+  const queue = useRef<ConfirmRequest[]>([]);
+
+  const processNext = useCallback(() => {
+    if (queue.current.length > 0) {
+      setCurrent(queue.current.shift()!);
+    } else {
+      setCurrent(null);
+    }
+  }, []);
+
+  const handleResponse = useCallback(
+    (value: boolean) => {
+      current?.resolve(value);
+      processNext();
+    },
+    [current, processNext],
+  );
+
+  useEffect(() => {
+    const handler = (e: Event) => {
+      const { message, resolve } = (e as CustomEvent).detail;
+      const request: ConfirmRequest = { message, resolve };
+      if (current) {
+        queue.current.push(request);
+      } else {
+        setCurrent(request);
+      }
+    };
+    document.addEventListener('rangka:confirm', handler);
+    return () => document.removeEventListener('rangka:confirm', handler);
+  }, [current]);
+
+  return (
+    <>
+      {children}
+      {current && (
+        <ConfirmDialog
+          message={current.message}
+          onConfirm={() => handleResponse(true)}
+          onCancel={() => handleResponse(false)}
+        />
+      )}
+    </>
+  );
+}

package/src/shell/DrawerContext.tsx

@@ -0,0 +1,44 @@
+import { createContext, useContext, useState, useCallback, type ReactNode } from 'react';
+import type { Size } from './types.js';
+
+export interface DrawerState {
+  open: boolean;
+  title?: ReactNode;
+  description?: ReactNode;
+  content?: ReactNode;
+  size?: Size;
+}
+
+export interface DrawerAPI {
+  state: DrawerState;
+  openDrawer(config: Omit<DrawerState, 'open'>): void;
+  closeDrawer(): void;
+}
+
+const DrawerContext = createContext<DrawerAPI | null>(null);
+
+export function DrawerProvider({ children }: { children: ReactNode }) {
+  const [state, setState] = useState<DrawerState>({ open: false });
+
+  const openDrawer = useCallback((config: Omit<DrawerState, 'open'>) => {
+    setState({ ...config, open: true });
+  }, []);
+
+  const closeDrawer = useCallback(() => {
+    setState((prev) => ({ ...prev, open: false }));
+  }, []);
+
+  return (
+    <DrawerContext.Provider value={{ state, openDrawer, closeDrawer }}>
+      {children}
+    </DrawerContext.Provider>
+  );
+}
+
+export function useDrawer(): DrawerAPI {
+  const ctx = useContext(DrawerContext);
+  if (!ctx) {
+    throw new Error('useDrawer must be used within a DrawerProvider');
+  }
+  return ctx;
+}

package/src/shell/HeaderActions.tsx

@@ -0,0 +1,31 @@
+import type { Action } from '@rangka/shared';
+import { Button } from '@/components/ui/button';
+import { Icon } from '@/components/Icon';
+
+interface HeaderActionsProps {
+  actions: Action[];
+  onAction?: (action: string) => void;
+}
+
+export function HeaderActions({ actions, onAction }: HeaderActionsProps) {
+  return (
+    <>
+      {actions.map((action, i) => {
+        if (action.type === 'button') {
+          return (
+            <Button
+              key={i}
+              size="sm"
+              variant={action.variant === 'primary' ? 'default' : 'secondary'}
+              onClick={() => action.action && onAction?.(action.action)}
+            >
+              {action.icon && <Icon name={action.icon} data-icon="inline-start" />}
+              {action.label}
+            </Button>
+          );
+        }
+        return null;
+      })}
+    </>
+  );
+}

package/src/shell/ModuleSelectorPage.tsx

@@ -0,0 +1,149 @@
+import { useState, useCallback, useMemo } from 'react';
+import { SearchIcon } from 'lucide-react';
+import { Input } from '@/components/ui/input';
+import { Card, CardHeader, CardTitle, CardDescription, CardContent } from '@/components/ui/card';
+import { Badge } from '@/components/ui/badge';
+import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import { Icon } from '@/components/Icon';
+import { useMeta } from '../context/MetaContext.js';
+import { useModule } from '../context/ModuleContext.js';
+import { useRouter } from '@tanstack/react-router';
+import type { NavigationTree } from '@rangka/shared';
+
+type FilterTab = 'all' | 'favorite' | 'internal' | 'external';
+
+export function ModuleSelectorPage() {
+  const [search, setSearch] = useState('');
+  const [activeTab, setActiveTab] = useState<FilterTab>('all');
+  const { navigation } = useMeta();
+  const { setActiveModule } = useModule();
+  const router = useRouter();
+
+  const modulesWithPages = navigation.filter(
+    (mod: NavigationTree) =>
+      mod.sections.length > 0 && mod.sections.some((s) => s.items.length > 0),
+  );
+
+  const filtered = useMemo(() => {
+    let result = modulesWithPages;
+
+    if (activeTab === 'internal') {
+      result = result.filter((mod: NavigationTree) => mod.type !== 'external');
+    } else if (activeTab === 'external') {
+      result = result.filter((mod: NavigationTree) => mod.type === 'external');
+    } else if (activeTab === 'favorite') {
+      result = result.filter((mod: NavigationTree) => {
+        const favorites = JSON.parse(localStorage.getItem('rangka:favorite-modules') || '[]');
+        return favorites.includes(mod.module);
+      });
+    }
+
+    if (search) {
+      result = result.filter((mod: NavigationTree) =>
+        mod.label.toLowerCase().includes(search.toLowerCase()),
+      );
+    }
+
+    return result;
+  }, [modulesWithPages, activeTab, search]);
+
+  const moduleColors: Record<string, string> = {
+    blue: 'bg-blue-500/10 text-blue-600 ring-blue-500/20',
+    green: 'bg-green-500/10 text-green-600 ring-green-500/20',
+    purple: 'bg-purple-500/10 text-purple-600 ring-purple-500/20',
+    orange: 'bg-orange-500/10 text-orange-600 ring-orange-500/20',
+    red: 'bg-red-500/10 text-red-600 ring-red-500/20',
+    teal: 'bg-teal-500/10 text-teal-600 ring-teal-500/20',
+    pink: 'bg-pink-500/10 text-pink-600 ring-pink-500/20',
+    amber: 'bg-amber-500/10 text-amber-600 ring-amber-500/20',
+  };
+
+  const getColorClasses = (color?: string) =>
+    moduleColors[color ?? ''] ?? 'bg-primary/10 text-primary ring-primary/20';
+
+  const handleModuleSelect = 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],
+  );
+
+  return (
+    <div className="p-6">
+      <div className="mb-4 flex items-center gap-4">
+        <Tabs value={activeTab} onValueChange={(v) => setActiveTab(v as FilterTab)}>
+          <TabsList variant="line">
+            <TabsTrigger value="all" className="text-sm">
+              All
+            </TabsTrigger>
+            <TabsTrigger value="favorite" className="text-sm">
+              Favorite
+            </TabsTrigger>
+            <TabsTrigger value="internal" className="text-sm">
+              Internal
+            </TabsTrigger>
+            <TabsTrigger value="external" className="text-sm">
+              External
+            </TabsTrigger>
+          </TabsList>
+        </Tabs>
+      </div>
+
+      <div className="mb-6 grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4">
+        <div className="relative">
+          <SearchIcon className="absolute left-3 top-1/2 size-4 -translate-y-1/2 text-muted-foreground" />
+          <Input
+            placeholder="Search modules..."
+            value={search}
+            onChange={(e) => setSearch(e.target.value)}
+            className="bg-card pl-9 ring-1 ring-foreground/10"
+          />
+        </div>
+      </div>
+
+      {filtered.length === 0 ? (
+        <p className="text-sm text-muted-foreground">No modules found</p>
+      ) : (
+        <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
+          {filtered.map((mod: NavigationTree) => (
+            <Card
+              key={mod.module}
+              className="cursor-pointer"
+              onClick={() => handleModuleSelect(mod.module)}
+            >
+              <CardHeader>
+                <div className="flex items-center gap-3">
+                  <div
+                    className={`flex size-9 shrink-0 items-center justify-center rounded-md ring-1 ${getColorClasses(mod.color)}`}
+                  >
+                    {mod.icon ? (
+                      <Icon name={mod.icon} size={18} />
+                    ) : (
+                      <span className="text-sm font-bold">{mod.label[0]}</span>
+                    )}
+                  </div>
+                  <div className="min-w-0 flex-1">
+                    <CardTitle>{mod.label}</CardTitle>
+                  </div>
+                  <Badge variant="outline" className="shrink-0 text-[10px]">
+                    {mod.type === 'external' ? 'External' : 'Internal'}
+                  </Badge>
+                </div>
+              </CardHeader>
+              <CardContent className="flex-1">
+                <CardDescription className="line-clamp-3">
+                  {mod.description || 'No description'}
+                </CardDescription>
+              </CardContent>
+            </Card>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/shell/PageOutlet.tsx

@@ -0,0 +1,21 @@
+import { useMemo } from 'react';
+import { useMeta } from '../context/MetaContext.js';
+import { WidgetSlotRenderer } from '../widgets/shell/WidgetSlotRenderer.js';
+
+export function PageOutlet({ pageKey }: { pageKey: string }) {
+  const { pages } = useMeta();
+  const page = useMemo(() => pages.find((p) => p.key === pageKey), [pages, pageKey]);
+
+  if (!page) {
+    return <div data-page-key={pageKey}>Page not found: {pageKey}</div>;
+  }
+
+  return (
+    <div
+      data-page-key={pageKey}
+      className="w-full h-full px-6 py-4 flex flex-col gap-6 animate-page-enter"
+    >
+      <WidgetSlotRenderer nodes={page.body} />
+    </div>
+  );
+}

package/src/shell/ShellContext.tsx

@@ -0,0 +1,45 @@
+import { createContext, useContext, useMemo, type ReactNode } from 'react';
+import { useNavigate as useRouterNavigate } from '../router/hooks.js';
+
+export type ToastType = 'info' | 'success' | 'warning' | 'error';
+
+export interface ShellAPI {
+  toast(message: string, type?: ToastType): void;
+  confirm(message: string): Promise<boolean>;
+  navigate(path: string): void;
+}
+
+const ShellContext = createContext<ShellAPI | null>(null);
+
+export function ShellAPIProvider({ children }: { children: ReactNode }) {
+  const navigate = useRouterNavigate();
+
+  const api = useMemo(
+    (): ShellAPI => ({
+      toast(message: string, type: ToastType = 'info') {
+        document.dispatchEvent(new CustomEvent('rangka:toast', { detail: { message, type } }));
+      },
+      confirm(message: string): Promise<boolean> {
+        return new Promise((resolve) => {
+          document.dispatchEvent(
+            new CustomEvent('rangka:confirm', { detail: { message, resolve } }),
+          );
+        });
+      },
+      navigate(path: string) {
+        navigate(path);
+      },
+    }),
+    [navigate],
+  );
+
+  return <ShellContext.Provider value={api}>{children}</ShellContext.Provider>;
+}
+
+export function useShell(): ShellAPI {
+  const ctx = useContext(ShellContext);
+  if (!ctx) {
+    throw new Error('useShell must be used within a ShellAPIProvider');
+  }
+  return ctx;
+}

package/src/shell/ShellDevTools.tsx

@@ -0,0 +1,153 @@
+import { useState } from 'react';
+import { useDrawer } from './DrawerContext.js';
+
+export function ShellDevTools() {
+  const [visible, setVisible] = useState(false);
+  const { state, openDrawer, closeDrawer } = useDrawer();
+
+  if (import.meta.env.PROD) return null;
+
+  return (
+    <>
+      <button
+        onClick={() => setVisible(!visible)}
+        className="fixed bottom-3 right-3 z-[9999] flex h-7 w-7 items-center justify-center rounded-sm bg-primary text-primary-foreground text-xs font-bold shadow-sm"
+        aria-label="Toggle dev tools"
+      >
+        D
+      </button>
+
+      {visible && (
+        <div className="fixed bottom-12 right-3 z-[9999] w-72 rounded-sm border border-border bg-background p-3 shadow-md">
+          <h3 className="mb-2 text-xs font-semibold text-foreground">Shell Dev Tools</h3>
+
+          <div className="space-y-2">
+            <fieldset className="space-y-1.5 border border-border rounded-sm p-2">
+              <legend className="px-1 text-xs text-muted-foreground">Drawer</legend>
+              <div className="flex items-center gap-1.5 text-xs text-muted-foreground">
+                <span>Status:</span>
+                <span className={state.open ? 'text-success' : 'text-muted-foreground'}>
+                  {state.open ? 'Open' : 'Closed'}
+                </span>
+              </div>
+              <div className="flex flex-wrap gap-1.5">
+                <button
+                  onClick={() =>
+                    openDrawer({
+                      title: 'Debug Drawer',
+                      description: 'Opened from dev tools',
+                      size: 'sm',
+                      content: <DebugDrawerContent />,
+                    })
+                  }
+                  className="rounded-sm bg-background-raised px-2 py-1 text-xs text-foreground hover:bg-border"
+                >
+                  Open SM
+                </button>
+                <button
+                  onClick={() =>
+                    openDrawer({
+                      title: 'Debug Drawer',
+                      description: 'Medium width panel',
+                      size: 'md',
+                      content: <DebugDrawerContent />,
+                    })
+                  }
+                  className="rounded-sm bg-background-raised px-2 py-1 text-xs text-foreground hover:bg-border"
+                >
+                  Open MD
+                </button>
+                <button
+                  onClick={() =>
+                    openDrawer({
+                      title: 'Debug Drawer',
+                      description: 'Large width panel',
+                      size: 'lg',
+                      content: <DebugDrawerContent />,
+                    })
+                  }
+                  className="rounded-sm bg-background-raised px-2 py-1 text-xs text-foreground hover:bg-border"
+                >
+                  Open LG
+                </button>
+                <button
+                  onClick={closeDrawer}
+                  className="rounded-sm bg-background-raised px-2 py-1 text-xs text-foreground hover:bg-border"
+                >
+                  Close
+                </button>
+              </div>
+            </fieldset>
+
+            <fieldset className="space-y-1.5 border border-border rounded-sm p-2">
+              <legend className="px-1 text-xs text-muted-foreground">Sidebar</legend>
+              <div className="flex flex-wrap gap-1.5">
+                <button
+                  onClick={() => document.dispatchEvent(new CustomEvent('rangka:sidebar-toggle'))}
+                  className="rounded-sm bg-background-raised px-2 py-1 text-xs text-foreground hover:bg-border"
+                >
+                  Toggle Collapse
+                </button>
+              </div>
+            </fieldset>
+
+            <fieldset className="space-y-1.5 border border-border rounded-sm p-2">
+              <legend className="px-1 text-xs text-muted-foreground">Events</legend>
+              <div className="flex flex-wrap gap-1.5">
+                <button
+                  onClick={() =>
+                    document.dispatchEvent(
+                      new CustomEvent('rangka:drawer-open', {
+                        detail: {
+                          title: 'Event Drawer',
+                          description: 'Via rangka:drawer-open',
+                          size: 'md',
+                        },
+                      }),
+                    )
+                  }
+                  className="rounded-sm bg-background-raised px-2 py-1 text-xs text-foreground hover:bg-border"
+                >
+                  Fire drawer-open
+                </button>
+                <button
+                  onClick={() => document.dispatchEvent(new CustomEvent('rangka:drawer-close'))}
+                  className="rounded-sm bg-background-raised px-2 py-1 text-xs text-foreground hover:bg-border"
+                >
+                  Fire drawer-close
+                </button>
+              </div>
+            </fieldset>
+          </div>
+        </div>
+      )}
+    </>
+  );
+}
+
+function DebugDrawerContent() {
+  return (
+    <div className="space-y-3">
+      <div className="rounded-sm border border-border p-3">
+        <h4 className="text-sm font-medium text-foreground">Sample Record</h4>
+        <p className="mt-1 text-xs text-muted-foreground">
+          This is a debug drawer opened from the dev tools panel.
+        </p>
+      </div>
+      <div className="space-y-2">
+        <div className="flex justify-between text-xs">
+          <span className="text-muted-foreground">ID</span>
+          <span className="font-mono text-foreground">REC-001</span>
+        </div>
+        <div className="flex justify-between text-xs">
+          <span className="text-muted-foreground">Status</span>
+          <span className="text-success">Active</span>
+        </div>
+        <div className="flex justify-between text-xs">
+          <span className="text-muted-foreground">Created</span>
+          <span className="text-foreground">2026-06-12</span>
+        </div>
+      </div>
+    </div>
+  );
+}