@rangka/client 0.0.1

package/src/context/UserContext.tsx

@@ -0,0 +1,16 @@
+import { createContext, useContext, type ReactNode } from 'react';
+import type { BootUser } from '@rangka/shared';
+
+const UserContext = createContext<BootUser | null>(null);
+
+export function UserProvider({ user, children }: { user: BootUser; children: ReactNode }) {
+  return <UserContext.Provider value={user}>{children}</UserContext.Provider>;
+}
+
+export function useCurrentUser(): BootUser {
+  const ctx = useContext(UserContext);
+  if (!ctx) {
+    throw new Error('useCurrentUser must be used within a UserProvider');
+  }
+  return ctx;
+}

package/src/data/QueryProvider.tsx

@@ -0,0 +1,7 @@
+import { QueryClientProvider } from '@tanstack/react-query';
+import type { QueryClient } from '@tanstack/react-query';
+import type { ReactNode } from 'react';
+
+export function QueryProvider({ client, children }: { client: QueryClient; children: ReactNode }) {
+  return <QueryClientProvider client={client}>{children}</QueryClientProvider>;
+}

package/src/data/queryClient.ts

@@ -0,0 +1,18 @@
+import { QueryClient } from '@tanstack/react-query';
+
+export function createQueryClient(onSessionExpired: () => void): QueryClient {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: (failureCount, error) => {
+          if (error instanceof Response && error.status === 401) {
+            onSessionExpired();
+            return false;
+          }
+          return failureCount < 3;
+        },
+        staleTime: 30_000,
+      },
+    },
+  });
+}

package/src/data/useModelMeta.ts

@@ -0,0 +1,17 @@
+import { useMemo } from 'react';
+import type { ModelMeta } from '@rangka/shared';
+import { useMeta as useMetaContext } from '../context/MetaContext.js';
+
+export interface UseModelMetaResult {
+  modelMeta: ModelMeta | undefined;
+}
+
+export function useModelMeta(model: string | undefined): UseModelMetaResult {
+  const { models } = useMetaContext();
+
+  return useMemo(() => {
+    if (!model) return { modelMeta: undefined };
+    const meta = models[model];
+    return { modelMeta: meta };
+  }, [model, models]);
+}

package/src/data/useMutation.ts

@@ -0,0 +1,60 @@
+import { useMutation as useTanstackMutation, useQueryClient } from '@tanstack/react-query';
+import { apiClient } from '../api/client.js';
+import { modelToPath } from '../api/paths.js';
+
+export interface UseMutationResult {
+  create: (data: Record<string, unknown>) => Promise<unknown>;
+  update: (id: string, data: Record<string, unknown>) => Promise<unknown>;
+  remove: (id: string) => Promise<void>;
+  isLoading: boolean;
+}
+
+export function useMutation(model: string): UseMutationResult {
+  const queryClient = useQueryClient();
+  const basePath = modelToPath(model);
+
+  const invalidate = () => {
+    queryClient.invalidateQueries({ queryKey: ['model', model] });
+  };
+
+  const createMutation = useTanstackMutation({
+    mutationFn: async (data: Record<string, unknown>) => {
+      const response = await apiClient(basePath, {
+        method: 'POST',
+        body: JSON.stringify(data),
+      });
+      if (!response.ok) throw response;
+      return response.json();
+    },
+    onSuccess: invalidate,
+  });
+
+  const updateMutation = useTanstackMutation({
+    mutationFn: async ({ id, data }: { id: string; data: Record<string, unknown> }) => {
+      const response = await apiClient(`${basePath}/${id}`, {
+        method: 'PUT',
+        body: JSON.stringify(data),
+      });
+      if (!response.ok) throw response;
+      return response.json();
+    },
+    onSuccess: invalidate,
+  });
+
+  const removeMutation = useTanstackMutation({
+    mutationFn: async (id: string) => {
+      const response = await apiClient(`${basePath}/${id}`, {
+        method: 'DELETE',
+      });
+      if (!response.ok) throw response;
+    },
+    onSuccess: invalidate,
+  });
+
+  return {
+    create: (data) => createMutation.mutateAsync(data),
+    update: (id, data) => updateMutation.mutateAsync({ id, data }),
+    remove: (id) => removeMutation.mutateAsync(id),
+    isLoading: createMutation.isPending || updateMutation.isPending || removeMutation.isPending,
+  };
+}

package/src/data/useRecord.ts

@@ -0,0 +1,29 @@
+import { useQuery } from '@tanstack/react-query';
+import { apiClient } from '../api/client.js';
+import { modelToPath } from '../api/paths.js';
+
+export interface UseRecordResult<T = unknown> {
+  data: T | undefined;
+  isLoading: boolean;
+}
+
+export function useRecord<T = unknown>(
+  model: string,
+  id: string | null | undefined,
+): UseRecordResult<T> {
+  const query = useQuery<T>({
+    queryKey: ['model', model, id],
+    queryFn: async () => {
+      const path = `${modelToPath(model)}/${id}`;
+      const response = await apiClient(path);
+      if (!response.ok) throw response;
+      return response.json() as Promise<T>;
+    },
+    enabled: !!id,
+  });
+
+  return {
+    data: query.data,
+    isLoading: query.isLoading,
+  };
+}

package/src/data/useSource.ts

@@ -0,0 +1,112 @@
+import { useState, useCallback } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { apiClient } from '../api/client.js';
+import { modelToPath } from '../api/paths.js';
+
+export interface UseSourceOptions {
+  model?: string;
+  endpoint?: string;
+  params?: Record<string, unknown>;
+  page?: number;
+  pageSize?: number;
+  sort?: string;
+  filter?: Record<string, string>;
+}
+
+export interface UseSourceResult<T = unknown> {
+  data: T[] | undefined;
+  isLoading: boolean;
+  pagination: { total?: number; page: number; pageSize: number } | undefined;
+  setPage: (page: number) => void;
+  setPageSize: (size: number) => void;
+  setSort: (sort: string | undefined) => void;
+  setFilter: (field: string, value: string | undefined) => void;
+  clearFilters: () => void;
+  sortParam: string | undefined;
+  filterParams: Record<string, string>;
+}
+
+export function useSource<T = unknown>(options: UseSourceOptions): UseSourceResult<T> {
+  const { model, endpoint, params } = options;
+  const path = endpoint ?? (model ? modelToPath(model) : '');
+
+  const [page, setPage] = useState(options.page ?? 1);
+  const [pageSize, setPageSize] = useState(options.pageSize ?? 20);
+  const [sortParam, setSortParam] = useState<string | undefined>(options.sort);
+  const [filterParams, setFilterParams] = useState<Record<string, string>>(options.filter ?? {});
+
+  const allParams: Record<string, unknown> = {
+    ...params,
+    page: String(page),
+    pageSize: String(pageSize),
+  };
+  if (sortParam) {
+    allParams.sort = sortParam;
+  }
+  for (const [field, value] of Object.entries(filterParams)) {
+    allParams[`filter[${field}]`] = value;
+  }
+
+  const queryKey = model ? ['model', model, allParams] : ['endpoint', endpoint, allParams];
+
+  const query = useQuery<{ data: T[]; total?: number } | T[]>({
+    queryKey,
+    queryFn: async () => {
+      const url = new URL(path, window.location.origin);
+      for (const [key, value] of Object.entries(allParams)) {
+        url.searchParams.set(key, String(value));
+      }
+      const response = await apiClient(url.pathname + url.search);
+      if (!response.ok) throw response;
+      return response.json();
+    },
+    enabled: !!path,
+  });
+
+  const rawData = query.data;
+  let data: T[] | undefined;
+  let total: number | undefined;
+
+  if (rawData && !Array.isArray(rawData) && 'data' in rawData) {
+    data = rawData.data;
+    total = rawData.total;
+  } else if (Array.isArray(rawData)) {
+    data = rawData;
+  }
+
+  const setFilterField = useCallback((field: string, value: string | undefined) => {
+    setFilterParams((prev) => {
+      const next = { ...prev };
+      if (value === undefined || value === '') {
+        delete next[field];
+      } else {
+        next[field] = value;
+      }
+      return next;
+    });
+    setPage(1);
+  }, []);
+
+  const clearFilters = useCallback(() => {
+    setFilterParams({});
+    setPage(1);
+  }, []);
+
+  const handleSetPageSize = useCallback((size: number) => {
+    setPageSize(size);
+    setPage(1);
+  }, []);
+
+  return {
+    data,
+    isLoading: query.isLoading,
+    pagination: { total, page, pageSize },
+    setPage,
+    setPageSize: handleSetPageSize,
+    setSort: setSortParam,
+    setFilter: setFilterField,
+    clearFilters,
+    sortParam,
+    filterParams,
+  };
+}

package/src/hooks/use-mobile.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+
+const MOBILE_BREAKPOINT = 768;
+
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined);
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    };
+    mql.addEventListener('change', onChange);
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    return () => mql.removeEventListener('change', onChange);
+  }, []);
+
+  return !!isMobile;
+}

package/src/index.css

@@ -0,0 +1,260 @@
+@import 'tailwindcss';
+@import 'tw-animate-css';
+@import 'shadcn/tailwind.css';
+@import '@fontsource-variable/inter';
+@import 'tw-animate-css';
+@import 'shadcn/tailwind.css';
+@import '@fontsource-variable/inter';
+@import 'tw-animate-css';
+@import 'shadcn/tailwind.css';
+@import '@fontsource-variable/inter';
+
+@custom-variant dark (&:is(.dark *));
+
+@source "../src";
+
+@keyframes page-enter {
+  from {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@theme inline {
+  --animate-page-enter: page-enter 150ms ease-out;
+  --font-heading: var(--font-sans);
+
+  --font-sans: 'Inter Variable', sans-serif;
+
+  --color-sidebar-ring: var(--sidebar-ring);
+
+  --color-sidebar-border: var(--sidebar-border);
+
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+
+  --color-sidebar-accent: var(--sidebar-accent);
+
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+
+  --color-sidebar-primary: var(--sidebar-primary);
+
+  --color-sidebar-foreground: var(--sidebar-foreground);
+
+  --color-sidebar: var(--sidebar);
+
+  --color-chart-5: var(--chart-5);
+
+  --color-chart-4: var(--chart-4);
+
+  --color-chart-3: var(--chart-3);
+
+  --color-chart-2: var(--chart-2);
+
+  --color-chart-1: var(--chart-1);
+
+  --color-ring: var(--ring);
+
+  --color-input: var(--input);
+
+  --color-border: var(--border);
+
+  --color-destructive: var(--destructive);
+
+  --color-accent-foreground: var(--accent-foreground);
+
+  --color-accent: var(--accent);
+
+  --color-muted-foreground: var(--muted-foreground);
+
+  --color-muted: var(--muted);
+
+  --color-secondary-foreground: var(--secondary-foreground);
+
+  --color-secondary: var(--secondary);
+
+  --color-primary-foreground: var(--primary-foreground);
+
+  --color-primary: var(--primary);
+
+  --color-popover-foreground: var(--popover-foreground);
+
+  --color-popover: var(--popover);
+
+  --color-card-foreground: var(--card-foreground);
+
+  --color-card: var(--card);
+
+  --color-foreground: var(--foreground);
+
+  --color-background: var(--background);
+
+  --radius-sm: calc(var(--radius) * 0.6);
+
+  --radius-md: calc(var(--radius) * 0.8);
+
+  --radius-lg: var(--radius);
+
+  --radius-xl: calc(var(--radius) * 1.4);
+
+  --radius-2xl: calc(var(--radius) * 1.8);
+
+  --radius-3xl: calc(var(--radius) * 2.2);
+
+  --radius-4xl: calc(var(--radius) * 2.6);
+}
+
+:root {
+  --background: oklch(1 0 0);
+
+  --foreground: oklch(0.145 0 0);
+
+  --card: oklch(1 0 0);
+
+  --card-foreground: oklch(0.145 0 0);
+
+  --popover: oklch(1 0 0);
+
+  --popover-foreground: oklch(0.145 0 0);
+
+  --primary: oklch(0.5 0.134 242.749);
+
+  --primary-foreground: oklch(0.977 0.013 236.62);
+
+  --secondary: oklch(0.967 0.001 286.375);
+
+  --secondary-foreground: oklch(0.21 0.006 285.885);
+
+  --muted: oklch(0.97 0 0);
+
+  --muted-foreground: oklch(0.556 0 0);
+
+  --accent: oklch(0.5 0.134 242.749);
+
+  --accent-foreground: oklch(0.977 0.013 236.62);
+
+  --destructive: oklch(0.577 0.245 27.325);
+
+  --border: oklch(0.922 0 0);
+
+  --input: oklch(0.8 0 0);
+
+  --ring: oklch(0.708 0 0);
+
+  --chart-1: oklch(0.809 0.105 251.813);
+
+  --chart-2: oklch(0.623 0.214 259.815);
+
+  --chart-3: oklch(0.546 0.245 262.881);
+
+  --chart-4: oklch(0.488 0.243 264.376);
+
+  --chart-5: oklch(0.424 0.199 265.638);
+
+  --radius: 0.625rem;
+
+  --sidebar: oklch(0.985 0 0);
+
+  --sidebar-foreground: oklch(0.145 0 0);
+
+  --sidebar-primary: oklch(0.588 0.158 241.966);
+
+  --sidebar-primary-foreground: oklch(0.977 0.013 236.62);
+
+  --sidebar-accent: oklch(0.97 0 0);
+
+  --sidebar-accent-foreground: oklch(0.205 0 0);
+
+  --sidebar-border: oklch(0.922 0 0);
+
+  --sidebar-ring: oklch(0.708 0 0);
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+
+  --foreground: oklch(0.985 0 0);
+
+  --card: oklch(0.205 0 0);
+
+  --card-foreground: oklch(0.985 0 0);
+
+  --popover: oklch(0.205 0 0);
+
+  --popover-foreground: oklch(0.985 0 0);
+
+  --primary: oklch(0.443 0.11 240.79);
+
+  --primary-foreground: oklch(0.977 0.013 236.62);
+
+  --secondary: oklch(0.274 0.006 286.033);
+
+  --secondary-foreground: oklch(0.985 0 0);
+
+  --muted: oklch(0.269 0 0);
+
+  --muted-foreground: oklch(0.708 0 0);
+
+  --accent: oklch(0.443 0.11 240.79);
+
+  --accent-foreground: oklch(0.977 0.013 236.62);
+
+  --destructive: oklch(0.704 0.191 22.216);
+
+  --border: oklch(1 0 0 / 10%);
+
+  --input: oklch(1 0 0 / 25%);
+
+  --ring: oklch(0.556 0 0);
+
+  --chart-1: oklch(0.809 0.105 251.813);
+
+  --chart-2: oklch(0.623 0.214 259.815);
+
+  --chart-3: oklch(0.546 0.245 262.881);
+
+  --chart-4: oklch(0.488 0.243 264.376);
+
+  --chart-5: oklch(0.424 0.199 265.638);
+
+  --sidebar: oklch(0.205 0 0);
+
+  --sidebar-foreground: oklch(0.985 0 0);
+
+  --sidebar-primary: oklch(0.685 0.169 237.323);
+
+  --sidebar-primary-foreground: oklch(0.293 0.066 243.157);
+
+  --sidebar-accent: oklch(0.269 0 0);
+
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+
+  --sidebar-border: oklch(1 0 0 / 10%);
+
+  --sidebar-ring: oklch(0.556 0 0);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+  html {
+    @apply text-base font-sans;
+    font-size: 17px;
+  }
+  button,
+  a,
+  [role='button'],
+  [role='menuitem'],
+  [role='option'],
+  [data-slot='sidebar-menu-button'],
+  [data-slot='sidebar-menu-sub-button'] {
+    cursor: pointer;
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export { useNavigate, useParams, useRoute, useSearchParams } from './router/hooks.js';
+export { useSource, type UseSourceOptions, type UseSourceResult } from './data/useSource.js';
+export { useRecord, type UseRecordResult } from './data/useRecord.js';
+export { useMutation, type UseMutationResult } from './data/useMutation.js';
+export { useModelMeta } from './data/useModelMeta.js';
+export { useCurrentUser } from './context/UserContext.js';
+export { usePermissions, type PermissionsApi } from './context/PermissionsContext.js';
+export { useMeta, type MetaData } from './context/MetaContext.js';
+export { useShell, type ShellAPI, type ToastType } from './shell/ShellContext.js';
+export { App } from './App.js';
+export {
+  WidgetSlotRenderer,
+  useActionHandlers,
+  type UseActionHandlersOptions,
+  type WidgetSlotRendererProps,
+} from './widgets/shell/index.js';

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/main.tsx

@@ -0,0 +1,17 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import './index.css';
+import { App } from './App.js';
+import { registerBuiltInWidgets } from './widgets/components/register.js';
+
+registerBuiltInWidgets();
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
+
+if (window.parent !== window) {
+  import('./studio/index.js');
+}

package/src/router/NotFound.tsx

@@ -0,0 +1,8 @@
+export function NotFound() {
+  return (
+    <div role="alert">
+      <h1>Page not found</h1>
+      <p>The page you are looking for does not exist.</p>
+    </div>
+  );
+}

package/src/router/RouterProvider.tsx

@@ -0,0 +1,7 @@
+import { RouterProvider as TanstackRouterProvider } from '@tanstack/react-router';
+import type { Router } from '@tanstack/react-router';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function RouterProvider({ router }: { router: Router<any, any, any, any> }) {
+  return <TanstackRouterProvider router={router} />;
+}

package/src/router/buildRouteTree.tsx

@@ -0,0 +1,63 @@
+import type { PageDefinition } from '@rangka/shared';
+import { createRootRoute, createRoute, Outlet, type AnyRoute } from '@tanstack/react-router';
+import { PageOutlet } from '../shell/PageOutlet.js';
+import { ShellLayout } from '../shell/ShellLayout.js';
+import { ModuleSelectorPage } from '../shell/ModuleSelectorPage.js';
+
+function RootLayout() {
+  return (
+    <ShellLayout>
+      <Outlet />
+    </ShellLayout>
+  );
+}
+
+function pageKeyToPath(key: string): string {
+  return '/' + key.replace(/\./g, '/');
+}
+
+export function buildRouteTree(pages: PageDefinition[]) {
+  const rootRoute = createRootRoute({
+    component: RootLayout,
+  });
+
+  const indexRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: '/',
+    component: ModuleSelectorPage,
+  });
+
+  const childRoutes: AnyRoute[] = [indexRoute];
+
+  childRoutes.push(
+    ...pages.map((page) => {
+      const path = page.path ?? pageKeyToPath(page.key);
+      const pageKey = page.key;
+      return createRoute({
+        getParentRoute: () => rootRoute,
+        path,
+        component: () => PageOutlet({ pageKey }),
+      });
+    }),
+  );
+
+  const notFoundRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: '*',
+    component: NotFound,
+  });
+
+  childRoutes.push(notFoundRoute);
+  rootRoute.addChildren(childRoutes);
+
+  return rootRoute;
+}
+
+function NotFound() {
+  return (
+    <div role="alert">
+      <h1>Page not found</h1>
+      <p>The page you are looking for does not exist.</p>
+    </div>
+  );
+}

package/src/router/createShellRouter.ts

@@ -0,0 +1,9 @@
+import type { PageDefinition } from '@rangka/shared';
+import { createRouter, type Router } from '@tanstack/react-router';
+import { buildRouteTree } from './buildRouteTree.jsx';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createShellRouter(pages: PageDefinition[]): Router<any, any, any, any> {
+  const routeTree = buildRouteTree(pages);
+  return createRouter({ routeTree });
+}