@shipfox/client-shell 0.2.0

package/src/compose/validate-registries.test.ts

@@ -0,0 +1,92 @@
+import {validateNavigation, validateSettingsSections} from './validate-registries.js';
+
+const duplicateNavigationMessage = /projects.*shipfox\.one.*acme\.two/u;
+const missingNavigationMessage = /insights.*acme\.two.*\/insights/u;
+const duplicateSettingsMessage = /members.*shipfox\.one.*acme\.two/u;
+const missingSettingsMessage = /sso.*acme\.two.*\/workspaces\/\$wid\/settings\/sso/u;
+
+describe('registry validation', () => {
+  test('names the id and both features for a duplicate navigation entry', () => {
+    expect(() =>
+      validateNavigation(
+        [
+          {
+            id: 'shipfox.one',
+            navigation: [{id: 'projects', scope: 'workspace', label: 'Projects', to: '/projects'}],
+          },
+          {
+            id: 'acme.two',
+            navigation: [{id: 'projects', scope: 'workspace', label: 'Projects', to: '/projects'}],
+          },
+        ],
+        ['/projects'],
+      ),
+    ).toThrow(duplicateNavigationMessage);
+  });
+
+  test('names the id, target, and feature for a missing navigation route', () => {
+    expect(() =>
+      validateNavigation(
+        [
+          {
+            id: 'acme.two',
+            navigation: [{id: 'insights', scope: 'workspace', label: 'Insights', to: '/insights'}],
+          },
+        ],
+        [],
+      ),
+    ).toThrow(missingNavigationMessage);
+  });
+
+  test('normalizes navigation targets before checking route existence', () => {
+    expect(() =>
+      validateNavigation(
+        [
+          {
+            id: 'acme.two',
+            navigation: [{id: 'insights', scope: 'workspace', label: 'Insights', to: '/insights/'}],
+          },
+        ],
+        ['/insights'],
+      ),
+    ).not.toThrow();
+  });
+
+  test('names the id and both features for a duplicate settings section', () => {
+    expect(() =>
+      validateSettingsSections(
+        [
+          {
+            id: 'shipfox.one',
+            settingsSections: [
+              {id: 'members', pathSegment: 'members', label: 'Members', icon: 'userLine'},
+            ],
+          },
+          {
+            id: 'acme.two',
+            settingsSections: [
+              {id: 'members', pathSegment: 'members', label: 'Members', icon: 'userLine'},
+            ],
+          },
+        ],
+        ['/workspaces/$wid/settings/members'],
+      ),
+    ).toThrow(duplicateSettingsMessage);
+  });
+
+  test('names the id, expected path, and feature for a missing settings route', () => {
+    expect(() =>
+      validateSettingsSections(
+        [
+          {
+            id: 'acme.two',
+            settingsSections: [
+              {id: 'sso', pathSegment: 'sso', label: 'Single sign-on', icon: 'userLine'},
+            ],
+          },
+        ],
+        [],
+      ),
+    ).toThrow(missingSettingsMessage);
+  });
+});

package/src/compose/validate-registries.ts

@@ -0,0 +1,61 @@
+import type {ClientFeature} from '#contract.js';
+import {NavCompositionError, SettingsCompositionError} from './errors.js';
+import {normalizeRoutePath} from './normalize-route-path.js';
+
+export function validateNavigation(
+  features: readonly ClientFeature[],
+  routePaths: Iterable<string>,
+): void {
+  const routes = new Set([...routePaths].map(normalizeRoutePath));
+  const entries = new Map<string, string>();
+  for (const feature of features) {
+    for (const entry of feature.navigation ?? []) {
+      const existingFeatureId = entries.get(entry.id);
+      if (existingFeatureId) {
+        throw new NavCompositionError(
+          entry.id,
+          `Navigation entry "${entry.id}" is contributed by both features "${existingFeatureId}" and "${feature.id}".`,
+          [existingFeatureId, feature.id],
+        );
+      }
+      const target = normalizeRoutePath(entry.to);
+      if (!routes.has(target)) {
+        throw new NavCompositionError(
+          entry.id,
+          `Navigation entry "${entry.id}" in feature "${feature.id}" targets missing route "${target}".`,
+          [feature.id],
+        );
+      }
+      entries.set(entry.id, feature.id);
+    }
+  }
+}
+
+export function validateSettingsSections(
+  features: readonly ClientFeature[],
+  routePaths: Iterable<string>,
+): void {
+  const routes = new Set(routePaths);
+  const sections = new Map<string, string>();
+  for (const feature of features) {
+    for (const section of feature.settingsSections ?? []) {
+      const existingFeatureId = sections.get(section.id);
+      if (existingFeatureId) {
+        throw new SettingsCompositionError(
+          section.id,
+          `Settings section "${section.id}" is contributed by both features "${existingFeatureId}" and "${feature.id}".`,
+          [existingFeatureId, feature.id],
+        );
+      }
+      const path = `/workspaces/$wid/settings/${section.pathSegment}`;
+      if (!routes.has(path)) {
+        throw new SettingsCompositionError(
+          section.id,
+          `Settings section "${section.id}" in feature "${feature.id}" requires route "${path}".`,
+          [feature.id],
+        );
+      }
+      sections.set(section.id, feature.id);
+    }
+  }
+}

package/src/config/config-screen.test.tsx

@@ -0,0 +1,37 @@
+import {getLoadedConfig} from '@shipfox/client-config';
+import {act, screen} from '@testing-library/react';
+import {z} from 'zod';
+import {defineClientFeature} from '#contract.js';
+import {composeClientApp} from '#runtime/compose-client-app.js';
+
+describe('composed config', () => {
+  test('renders ConfigErrorScreen when a feature-required key is missing', async () => {
+    window.__SHIPFOX_CONFIG__ = undefined;
+    const fetchSpy = vi.spyOn(globalThis, 'fetch');
+    const element = document.createElement('div');
+    document.body.append(element);
+    const app = composeClientApp({
+      features: [defineClientFeature({id: 'acme.config', configShape: {ssoIssuer: z.url()}})],
+      router: {} as never,
+    });
+
+    await act(async () => app.mount(element));
+
+    expect(await screen.findByRole('heading', {name: 'Configuration error'})).toBeVisible();
+    expect(fetchSpy).not.toHaveBeenCalled();
+    element.remove();
+  });
+
+  test('loads a present feature config value into the shared config', () => {
+    const shape = z.string();
+    window.__SHIPFOX_CONFIG__ = {SSO_ISSUER: 'https://id.example.test'};
+    const app = composeClientApp({
+      features: [defineClientFeature({id: 'acme.config', configShape: {ssoIssuer: shape}})],
+      router: {} as never,
+    });
+    expect(app).toBeDefined();
+    expect(getLoadedConfig<{ssoIssuer: string}>()).toMatchObject({
+      ssoIssuer: 'https://id.example.test',
+    });
+  });
+});

package/src/config/shell-config.ts

@@ -0,0 +1,10 @@
+import {apiConfigShape} from '@shipfox/client-api';
+import {z} from 'zod';
+
+export const shellConfigShape = {
+  ...apiConfigShape,
+  environment: z
+    .enum(['development', 'staging', 'production'])
+    .default('production')
+    .describe('Deployment environment name shown in diagnostics and reported to monitoring.'),
+};

package/src/contract.ts

@@ -0,0 +1,47 @@
+import type {IconName} from '@shipfox/react-ui/icon';
+import type {ComponentType, PropsWithChildren} from 'react';
+import type {z} from 'zod';
+
+export type AnchorId = 'root' | 'workspaceLayout' | 'projectLayout' | 'workspaceSettings';
+
+export interface RouteContribution {
+  path: string;
+  parent: AnchorId;
+  override?: boolean;
+  impl: string;
+}
+
+export interface FeatureProvider {
+  id: string;
+  Component: ComponentType<PropsWithChildren>;
+}
+
+export interface NavTabEntry {
+  id: string;
+  scope: 'workspace' | 'project';
+  label: string;
+  to: string;
+  exact?: boolean;
+  order?: number;
+}
+
+export interface SettingsSectionEntry {
+  id: string;
+  pathSegment: string;
+  label: string;
+  icon: IconName;
+  order?: number;
+}
+
+export interface ClientFeature<S extends z.ZodRawShape = z.ZodRawShape> {
+  id: string;
+  routes?: readonly RouteContribution[];
+  providers?: readonly FeatureProvider[];
+  navigation?: readonly NavTabEntry[];
+  settingsSections?: readonly SettingsSectionEntry[];
+  configShape?: S;
+}
+
+export function defineClientFeature<const T extends ClientFeature>(feature: T): T {
+  return feature;
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './contract.js';

package/src/runtime/active-workspace.ts

@@ -0,0 +1,13 @@
+import {useParams} from '@tanstack/react-router';
+import {useAuthState, type Workspace} from './auth.js';
+
+export function useActiveWorkspace(): Workspace {
+  const workspace = useMaybeActiveWorkspace();
+  if (!workspace) throw new Error('useActiveWorkspace called outside a /workspaces/$wid route');
+  return workspace;
+}
+
+export function useMaybeActiveWorkspace(): Workspace | undefined {
+  const {wid} = useParams({strict: false}) as {wid?: string};
+  return useAuthState().workspaces.find((workspace) => workspace.id === wid);
+}

package/src/runtime/anchor-paths.ts

@@ -0,0 +1,18 @@
+const anchorPaths = {
+  root: '/',
+  workspaceLayout: '/workspaces/$wid',
+  projectLayout: '/workspaces/$wid/projects/$pid',
+  workspaceSettings: '/workspaces/$wid/settings',
+} as const;
+
+export {anchorPaths};
+
+export function routePathForAnchor(anchor: keyof typeof anchorPaths, fullPath: string): string {
+  const anchorPath = anchorPaths[anchor];
+  if (anchor === 'root') return fullPath;
+  if (fullPath === anchorPath) return '/';
+  if (!fullPath.startsWith(`${anchorPath}/`)) {
+    throw new Error(`Route "${fullPath}" must be nested under anchor "${anchor}" (${anchorPath}).`);
+  }
+  return fullPath.slice(anchorPath.length);
+}

package/src/runtime/anchors.tsx

@@ -0,0 +1,106 @@
+import {ShipfoxLoader} from '@shipfox/react-ui/loader';
+import {Header, Text} from '@shipfox/react-ui/typography';
+import {createRootRouteWithContext, createRoute, Outlet, redirect} from '@tanstack/react-router';
+import {MainLayout} from '#components/main-layout.js';
+import {NotFoundPage} from '#components/not-found-page.js';
+import {SettingsNav} from '#components/settings-nav.js';
+import type {NavTabEntry, SettingsSectionEntry} from '#contract.js';
+import {useActiveWorkspace} from './active-workspace.js';
+import {anchorPaths} from './anchor-paths.js';
+import {useChrome} from './chrome-context.js';
+import {rememberLastWorkspaceId} from './last-workspace.js';
+import type {RouterContext} from './router-context.js';
+import {WorkspaceLayoutErrorRoute, WorkspaceSetupPending} from './workspace-setup.js';
+
+export {routePathForAnchor} from './anchor-paths.js';
+
+export function buildAnchorSkeleton({
+  navigation,
+  settingsSections,
+}: {
+  navigation: readonly NavTabEntry[];
+  settingsSections: readonly SettingsSectionEntry[];
+}) {
+  const rootRoute = createRootRouteWithContext<RouterContext>()({
+    component: Outlet,
+    notFoundComponent: NotFoundPage,
+  });
+  const workspaceLayout = createRoute({
+    getParentRoute: () => rootRoute,
+    path: anchorPaths.workspaceLayout,
+    beforeLoad: async ({context, params, location}) => {
+      try {
+        rememberLastWorkspaceId(params.wid);
+      } catch {
+        // Local storage is best effort.
+      }
+      const auth = context.auth;
+      if (!auth || auth.isLoading || !context.queryClient) return;
+      if (!auth.isAuthenticated)
+        throw redirect({to: '/auth/login' as never, search: {redirect: location.href} as never});
+      if (!auth.workspaces.some((workspace) => workspace.id === params.wid))
+        throw redirect({to: '/'});
+      if (!context.workspaceSetup)
+        throw new Error('Client composition includes workspace routes but no workspaceSetup gate.');
+      return await context.workspaceSetup({
+        queryClient: context.queryClient,
+        workspaceId: params.wid,
+        pathname: location.pathname,
+      });
+    },
+    pendingComponent: () => (
+      <div className="flex h-screen items-center justify-center">
+        <ShipfoxLoader size={64} animation="circular" color="orange" background="dark" />
+      </div>
+    ),
+    errorComponent: WorkspaceLayoutErrorRoute,
+    component: () => {
+      const setupState = workspaceLayout.useRouteContext() as {hideProjectNavigation?: boolean};
+      return setupState.hideProjectNavigation === undefined ? (
+        <WorkspaceSetupPending />
+      ) : (
+        <MainLayout
+          navigation={navigation}
+          hideProjectNavigation={setupState.hideProjectNavigation}
+        />
+      );
+    },
+  });
+  const projectLayout = createRoute({
+    getParentRoute: () => workspaceLayout,
+    path: '/projects/$pid',
+    component: () => {
+      const {ProjectLayoutGuard} = useChrome();
+      return <ProjectLayoutGuard />;
+    },
+  });
+  const workspaceSettings = createRoute({
+    getParentRoute: () => workspaceLayout,
+    path: '/settings',
+    component: () => {
+      const workspace = useActiveWorkspace();
+      return (
+        <div className="flex w-full flex-col gap-24">
+          <header className="flex flex-col gap-6">
+            <Header variant="h2">Workspace settings</Header>
+            <Text size="sm" className="text-foreground-neutral-muted">
+              Configure {workspace.name}.
+            </Text>
+          </header>
+
+          <div className="grid grid-cols-[180px_minmax(0,1fr)] gap-32 max-[760px]:grid-cols-1">
+            <SettingsNav entries={settingsSections} />
+            <Outlet />
+          </div>
+        </div>
+      );
+    },
+  });
+  return {
+    anchors: {root: rootRoute, workspaceLayout, projectLayout, workspaceSettings},
+    rootRoute,
+    workspaceLayout,
+    projectLayout,
+    workspaceSettings,
+  };
+}

package/src/runtime/assemble-route-tree.ts

@@ -0,0 +1,42 @@
+import {createRoute} from '@tanstack/react-router';
+import type {ComposedRoute} from '#compose/compose-routes.js';
+import {buildAnchorSkeleton, routePathForAnchor} from '#runtime/anchors.js';
+import type {RouteImpl} from '#runtime/define-route.js';
+
+export type ResolveRouteImpl = (specifier: string) => RouteImpl | Promise<RouteImpl>;
+
+export async function assembleRouteTree(
+  routes: readonly ComposedRoute[],
+  options: {
+    resolveImpl: ResolveRouteImpl;
+    navigation: Parameters<typeof buildAnchorSkeleton>[0]['navigation'];
+    settingsSections: Parameters<typeof buildAnchorSkeleton>[0]['settingsSections'];
+  },
+) {
+  const skeleton = buildAnchorSkeleton(options);
+  const children = await Promise.all(
+    routes.map(async (route) => {
+      const impl = await options.resolveImpl(route.impl);
+      return {
+        parent: route.parent,
+        route: createRoute({
+          getParentRoute: () => skeleton.anchors[route.parent] as never,
+          path: routePathForAnchor(route.parent, route.path),
+          ...impl.options,
+        } as never),
+      };
+    }),
+  );
+  const childrenFor = (anchor: keyof typeof skeleton.anchors) =>
+    children.filter((child) => child.parent === anchor).map((child) => child.route);
+  const projectLayout = skeleton.projectLayout.addChildren(childrenFor('projectLayout'));
+  const workspaceSettings = skeleton.workspaceSettings.addChildren(
+    childrenFor('workspaceSettings'),
+  );
+  const workspaceLayout = skeleton.workspaceLayout.addChildren([
+    ...childrenFor('workspaceLayout'),
+    projectLayout,
+    workspaceSettings,
+  ]);
+  return skeleton.rootRoute.addChildren([...childrenFor('root'), workspaceLayout]);
+}

package/src/runtime/auth.tsx

@@ -0,0 +1,213 @@
+import type {LoginResponseDto, UserDto} from '@shipfox/api-auth-dto';
+import type {MembershipWithWorkspaceDto} from '@shipfox/api-workspaces-dto';
+import {ApiError, apiRequest, configureApiClient} from '@shipfox/client-api';
+import {useQueryClient} from '@tanstack/react-query';
+import {atom, useAtomValue, useSetAtom, useStore} from 'jotai';
+import type {PropsWithChildren} from 'react';
+import {useCallback, useEffect, useMemo} from 'react';
+
+const REFRESH_EARLY_MS = 5 * 60 * 1000;
+const REFRESH_RETRY_DELAY_MS = 60_000;
+const BASE64_URL_REPLACEMENTS = {dash: /-/g, underscore: /_/g} as const;
+
+export type AuthStatus = 'loading' | 'authenticated' | 'guest';
+
+export interface Workspace {
+  id: string;
+  name: string;
+  membershipId: string;
+}
+
+export interface AuthState {
+  status: AuthStatus;
+  token?: string;
+  user?: UserDto;
+  workspaces?: Workspace[];
+}
+
+export interface AuthStateValue extends AuthState {
+  isLoading: boolean;
+  isAuthenticated: boolean;
+  workspaces: Workspace[];
+  hasWorkspace: boolean;
+}
+
+export const initialAuthState: AuthState = {status: 'loading'};
+export const authStateAtom = atom<AuthState>(initialAuthState);
+export const authRefreshQueryKey = ['auth', 'refresh'] as const;
+export const userWorkspacesQueryKey = ['workspaces', 'mine'] as const;
+
+export function toAuthenticatedState(
+  result: LoginResponseDto,
+  memberships: MembershipWithWorkspaceDto[] = [],
+): AuthState {
+  return {
+    status: 'authenticated',
+    token: result.token,
+    user: result.user,
+    workspaces: memberships.map((membership) => ({
+      id: membership.workspace_id,
+      name: membership.workspace_name,
+      membershipId: membership.id,
+    })),
+  };
+}
+
+export function useAuthState(): AuthStateValue {
+  const state = useAtomValue(authStateAtom);
+  return useMemo(
+    () => ({
+      ...state,
+      workspaces: state.workspaces ?? [],
+      isLoading: state.status === 'loading',
+      isAuthenticated: state.status === 'authenticated',
+      hasWorkspace: (state.workspaces ?? []).length > 0,
+    }),
+    [state],
+  );
+}
+
+export async function listUserWorkspaces(token?: string) {
+  return await apiRequest<{memberships: MembershipWithWorkspaceDto[]}>(
+    '/workspaces',
+    token ? {headers: {authorization: `Bearer ${token}`}} : {},
+  );
+}
+
+async function refreshAuthRequest() {
+  return await apiRequest<LoginResponseDto>('/auth/refresh', {method: 'POST'});
+}
+
+function decodeBase64Url(value: string): string {
+  const base64 = value
+    .replace(BASE64_URL_REPLACEMENTS.dash, '+')
+    .replace(BASE64_URL_REPLACEMENTS.underscore, '/');
+  return atob(base64.padEnd(Math.ceil(base64.length / 4) * 4, '='));
+}
+
+function readJwtExp(token: string): number | undefined {
+  const [, payload] = token.split('.');
+  if (!payload) return undefined;
+  try {
+    const parsed = JSON.parse(decodeBase64Url(payload)) as {exp?: unknown};
+    return typeof parsed.exp === 'number' && Number.isFinite(parsed.exp) ? parsed.exp : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function getAuthRefreshDelayMs(token: string, nowMs = Date.now()): number | undefined {
+  const exp = readJwtExp(token);
+  return exp === undefined ? undefined : exp * 1000 - nowMs - REFRESH_EARLY_MS;
+}
+
+export function useRefreshAuth() {
+  const queryClient = useQueryClient();
+  const setState = useSetAtom(authStateAtom);
+  return useCallback(async () => {
+    try {
+      const result = await queryClient.fetchQuery({
+        queryKey: authRefreshQueryKey,
+        queryFn: refreshAuthRequest,
+        retry: false,
+        staleTime: 0,
+      });
+      let memberships: MembershipWithWorkspaceDto[] = [];
+      try {
+        const workspaces = await queryClient.fetchQuery({
+          queryKey: userWorkspacesQueryKey,
+          queryFn: () => listUserWorkspaces(result.token),
+          retry: false,
+          staleTime: 0,
+        });
+        memberships = workspaces.memberships;
+      } catch {
+        // A valid session remains usable while workspace hydration retries on the next route load.
+      }
+      setState(toAuthenticatedState(result, memberships));
+      return result;
+    } catch (error) {
+      if (error instanceof ApiError && error.status === 401) setState({status: 'guest'});
+      throw error;
+    }
+  }, [queryClient, setState]);
+}
+
+export interface AuthRuntimeProps extends PropsWithChildren {
+  effects?: boolean;
+}
+
+export function AuthRuntime({children, effects = true}: AuthRuntimeProps) {
+  const store = useStore();
+  const authState = useAtomValue(authStateAtom);
+  const refreshAuth = useRefreshAuth();
+
+  useEffect(() => {
+    if (!effects) return;
+    configureApiClient({
+      getAccessToken: () => store.get(authStateAtom).token,
+      refreshAccessToken: async () => (await refreshAuth()).token,
+    });
+  }, [effects, refreshAuth, store]);
+
+  useEffect(() => {
+    if (!effects) return;
+    refreshAuth().catch(() => undefined);
+  }, [effects, refreshAuth]);
+
+  useEffect(() => {
+    if (!effects || authState.status !== 'authenticated' || !authState.token) return;
+
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    let disposed = false;
+    let refreshing = false;
+    const clearRefreshTimer = () => {
+      if (timeout !== undefined) clearTimeout(timeout);
+      timeout = undefined;
+    };
+    const scheduleRefresh = (delayMs: number) => {
+      clearRefreshTimer();
+      timeout = setTimeout(runRefresh, Math.max(0, delayMs));
+    };
+    const retryIfStillDue = () => {
+      const current = store.get(authStateAtom);
+      if (current.status !== 'authenticated' || !current.token) return;
+      const delay = getAuthRefreshDelayMs(current.token);
+      if (delay !== undefined && delay <= 0) scheduleRefresh(REFRESH_RETRY_DELAY_MS);
+    };
+    function runRefresh() {
+      if (disposed || refreshing) return;
+      refreshing = true;
+      clearRefreshTimer();
+      refreshAuth()
+        .catch(() => undefined)
+        .finally(() => {
+          refreshing = false;
+          if (!disposed) retryIfStillDue();
+        });
+    }
+    const refreshIfDue = () => {
+      const current = store.get(authStateAtom);
+      if (current.status !== 'authenticated' || !current.token) return;
+      const delay = getAuthRefreshDelayMs(current.token);
+      if (delay !== undefined && delay <= 0) runRefresh();
+    };
+    const refreshIfVisible = () => {
+      if (document.visibilityState === 'visible') refreshIfDue();
+    };
+    const delay = getAuthRefreshDelayMs(authState.token);
+    if (delay !== undefined) scheduleRefresh(delay);
+    window.addEventListener('focus', refreshIfDue);
+    window.addEventListener('online', refreshIfDue);
+    document.addEventListener('visibilitychange', refreshIfVisible);
+    return () => {
+      disposed = true;
+      clearRefreshTimer();
+      window.removeEventListener('focus', refreshIfDue);
+      window.removeEventListener('online', refreshIfDue);
+      document.removeEventListener('visibilitychange', refreshIfVisible);
+    };
+  }, [authState.status, authState.token, effects, refreshAuth, store]);
+
+  return children;
+}

package/src/runtime/chrome-context.tsx

@@ -0,0 +1,22 @@
+import type {ComponentType, PropsWithChildren} from 'react';
+import {createContext, useContext} from 'react';
+
+export interface ChromeSlots {
+  ProjectBreadcrumb: ComponentType;
+  ProjectLayoutGuard: ComponentType;
+}
+
+const ChromeContext = createContext<ChromeSlots | undefined>(undefined);
+
+export function ChromeProvider({
+  chrome,
+  children,
+}: PropsWithChildren<{chrome: ChromeSlots | undefined}>) {
+  return <ChromeContext.Provider value={chrome}>{children}</ChromeContext.Provider>;
+}
+
+export function useChrome(): ChromeSlots {
+  const chrome = useContext(ChromeContext);
+  if (!chrome) throw new Error('Client composition must provide browser chrome slots.');
+  return chrome;
+}