@shipfox/client-shell 0.2.0

package/src/runtime/compose-client-app.tsx

@@ -0,0 +1,122 @@
+import {configureApiClient} from '@shipfox/client-api';
+import {
+  ConfigErrorScreen,
+  getWindowRuntimeConfig,
+  loadConfig,
+  setLoadedConfig,
+} from '@shipfox/client-config';
+import {ThemeProvider} from '@shipfox/react-ui/theme';
+import {Toaster} from '@shipfox/react-ui/toast';
+import {TooltipProvider} from '@shipfox/react-ui/tooltip';
+import {QueryClient} from '@tanstack/react-query';
+import {type AnyRouter, RouterProvider} from '@tanstack/react-router';
+import {createStore} from 'jotai';
+import {StrictMode, useEffect} from 'react';
+import {createRoot} from 'react-dom/client';
+import {composeRoutes} from '#compose/compose-routes.js';
+import {mergeConfigShapes} from '#compose/merge-config.js';
+import {validateProviderIds} from '#compose/validate-providers.js';
+import {validateNavigation, validateSettingsSections} from '#compose/validate-registries.js';
+import type {ClientFeature} from '#contract.js';
+import {useAuthState} from './auth.js';
+import {ChromeProvider, type ChromeSlots} from './chrome-context.js';
+import {ShellProviderStack} from './provider-stack.js';
+import type {WorkspaceSetupGate} from './workspace-setup.js';
+
+export function composeClientApp({
+  features,
+  router,
+  chrome,
+  workspaceSetup,
+}: {
+  features: readonly ClientFeature[];
+  router: AnyRouter;
+  chrome?: ChromeSlots;
+  workspaceSetup?: WorkspaceSetupGate;
+}) {
+  const routes = composeRoutes(features);
+  validateProviderIds(features);
+  validateNavigation(
+    features,
+    routes.map((route) => route.path),
+  );
+  validateSettingsSections(
+    features,
+    routes.map((route) => route.path),
+  );
+  const config = loadConfig(mergeConfigShapes(features), {
+    runtime: getWindowRuntimeConfig(),
+    build: (import.meta as ImportMeta & {env?: Record<string, unknown>}).env,
+  });
+  if (config.ok) setLoadedConfig(config.config);
+
+  return {
+    mount(element: HTMLElement): void {
+      const root = createRoot(element);
+      if (!config.ok) {
+        root.render(
+          <StrictMode>
+            <ThemeProvider>
+              <TooltipProvider>
+                <ConfigErrorScreen errors={config.errors} />
+              </TooltipProvider>
+            </ThemeProvider>
+          </StrictMode>,
+        );
+        return;
+      }
+
+      configureApiClient({baseUrl: configApiUrl(config.config)});
+      const queryClient = new QueryClient();
+      root.render(
+        <StrictMode>
+          <ChromeProvider chrome={chrome}>
+            <ShellProviderStack features={features} queryClient={queryClient} store={createStore()}>
+              <RoutedApp
+                router={router}
+                queryClient={queryClient}
+                workspaceSetup={workspaceSetup}
+              />
+              <Toaster />
+            </ShellProviderStack>
+          </ChromeProvider>
+        </StrictMode>,
+      );
+    },
+  };
+}
+
+function RoutedApp({
+  router,
+  queryClient,
+  workspaceSetup,
+}: {
+  router: AnyRouter;
+  queryClient: QueryClient;
+  workspaceSetup: WorkspaceSetupGate | undefined;
+}) {
+  const auth = useAuthState();
+
+  useEffect(() => {
+    if (!auth.isLoading) router.invalidate();
+  }, [auth.isLoading, router]);
+
+  return (
+    <RouterProvider
+      router={router as never}
+      context={{auth, queryClient, workspaceSetup} as never}
+    />
+  );
+}
+
+function configApiUrl(config: unknown): string {
+  if (
+    typeof config !== 'object' ||
+    config === null ||
+    !('apiUrl' in config) ||
+    typeof config.apiUrl !== 'string'
+  ) {
+    throw new Error('Composed client configuration must include a string apiUrl.');
+  }
+  return config.apiUrl;
+}

package/src/runtime/define-route.test.ts

@@ -0,0 +1,15 @@
+import {defineRoute, isRouteImpl} from './define-route.js';
+
+describe('isRouteImpl', () => {
+  test('accepts implementations created by defineRoute', () => {
+    const route = defineRoute({component: () => null});
+
+    expect(isRouteImpl(route)).toBe(true);
+  });
+
+  test('rejects a default component without a route implementation', () => {
+    const component = () => null;
+
+    expect(isRouteImpl(component)).toBe(false);
+  });
+});

package/src/runtime/define-route.ts

@@ -0,0 +1,33 @@
+import type {ComponentType} from 'react';
+
+export interface RouteImplOptions {
+  component?: ComponentType;
+  loader?: unknown;
+  validateSearch?: unknown;
+  beforeLoad?: unknown;
+  staticData?: unknown;
+  pendingComponent?: ComponentType;
+  errorComponent?: ComponentType;
+}
+
+const routeImplBrand = Symbol('routeImpl');
+
+export interface RouteImpl<O extends RouteImplOptions = RouteImplOptions> {
+  readonly options: O;
+  readonly [routeImplBrand]: true;
+}
+
+export function defineRoute<const O extends RouteImplOptions>(options: O): RouteImpl<O> {
+  return {options, [routeImplBrand]: true};
+}
+
+export function isRouteImpl(value: unknown): value is RouteImpl {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    routeImplBrand in value &&
+    'options' in value &&
+    typeof value.options === 'object' &&
+    value.options !== null
+  );
+}

package/src/runtime/index.ts

@@ -0,0 +1,19 @@
+export {WorkspaceCrumb, type WorkspaceCrumbProps} from '#components/workspace-crumb.js';
+export {WorkspaceSwitcher} from '#components/workspace-switcher.js';
+export * from '../compose/compose-routes.js';
+export * from '../compose/errors.js';
+export * from '../compose/merge-config.js';
+export * from '../compose/normalize-route-path.js';
+export * from '../compose/validate-providers.js';
+export * from '../compose/validate-registries.js';
+export * from './active-workspace.js';
+export * from './anchor-paths.js';
+export * from './anchors.js';
+export * from './auth.js';
+export * from './chrome-context.js';
+export * from './compose-client-app.js';
+export * from './define-route.js';
+export * from './last-workspace.js';
+export * from './nav-order.js';
+export * from './router-context.js';
+export * from './workspace-setup.js';

package/src/runtime/last-workspace.ts

@@ -0,0 +1,22 @@
+import {atomWithStorage} from 'jotai/utils';
+
+const storageKey = 'shipfox.lastWorkspaceId';
+
+export const lastWorkspaceIdAtom = atomWithStorage<string | undefined>(storageKey, undefined);
+
+export function getLastWorkspaceId(): string | undefined {
+  if (typeof window === 'undefined') return undefined;
+  try {
+    const raw = window.localStorage.getItem(storageKey);
+    if (!raw) return undefined;
+    const parsed: unknown = JSON.parse(raw);
+    return typeof parsed === 'string' ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function rememberLastWorkspaceId(workspaceId: string): void {
+  if (typeof window === 'undefined') return;
+  window.localStorage.setItem(storageKey, JSON.stringify(workspaceId));
+}

package/src/runtime/nav-order.ts

@@ -0,0 +1 @@
+export const NAV_ORDER = {projects: 100, settings: 900, runs: 100, workflows: 200} as const;

package/src/runtime/provider-stack.tsx

@@ -0,0 +1,39 @@
+import {ThemeProvider} from '@shipfox/react-ui/theme';
+import {TooltipProvider} from '@shipfox/react-ui/tooltip';
+import {type QueryClient, QueryClientProvider} from '@tanstack/react-query';
+import {type createStore, Provider as JotaiProvider} from 'jotai';
+import type {PropsWithChildren, ReactNode} from 'react';
+import type {ClientFeature} from '#contract.js';
+import {AuthRuntime, type AuthRuntimeProps} from './auth.js';
+
+type Store = ReturnType<typeof createStore>;
+
+export function ShellProviderStack({
+  features,
+  queryClient,
+  store,
+  auth,
+  children,
+}: PropsWithChildren<{
+  features: readonly ClientFeature[];
+  queryClient: QueryClient;
+  store: Store;
+  auth?: Pick<AuthRuntimeProps, 'effects'>;
+}>) {
+  const featureProviders = features.flatMap((feature) => feature.providers ?? []);
+  const nestedProviders = featureProviders.reduceRight<ReactNode>(
+    (content, provider) => <provider.Component key={provider.id}>{content}</provider.Component>,
+    children,
+  );
+  return (
+    <ThemeProvider>
+      <TooltipProvider>
+        <QueryClientProvider client={queryClient}>
+          <JotaiProvider store={store}>
+            <AuthRuntime {...auth}>{nestedProviders}</AuthRuntime>
+          </JotaiProvider>
+        </QueryClientProvider>
+      </TooltipProvider>
+    </ThemeProvider>
+  );
+}

package/src/runtime/providers.test.tsx

@@ -0,0 +1,51 @@
+import {QueryClient, useQueryClient} from '@tanstack/react-query';
+import {render} from '@testing-library/react';
+import {createStore, useStore} from 'jotai';
+import type {PropsWithChildren} from 'react';
+import {defineClientFeature} from '#contract.js';
+import {ShellProviderStack} from './provider-stack.js';
+
+describe('ShellProviderStack', () => {
+  test('gives providers the shell query client and store in feature declaration order', () => {
+    const queryClient = new QueryClient();
+    const store = createStore();
+    const breadcrumbs: string[] = [];
+    const received: Array<{queryClient: QueryClient; store: ReturnType<typeof createStore>}> = [];
+    const Probe = ({id, children}: PropsWithChildren<{id: string}>) => {
+      received.push({queryClient: useQueryClient(), store: useStore()});
+      breadcrumbs.push(id);
+      return <>{children}</>;
+    };
+    const features = [
+      defineClientFeature({
+        id: 'shipfox.first',
+        providers: [{id: 'first', Component: ({children}) => <Probe id="first">{children}</Probe>}],
+      }),
+      defineClientFeature({
+        id: 'acme.second',
+        providers: [
+          {id: 'second', Component: ({children}) => <Probe id="second">{children}</Probe>},
+          {id: 'third', Component: ({children}) => <Probe id="third">{children}</Probe>},
+        ],
+      }),
+    ];
+
+    render(
+      <ShellProviderStack
+        features={features}
+        queryClient={queryClient}
+        store={store}
+        auth={{effects: false}}
+      >
+        <div>Content</div>
+      </ShellProviderStack>,
+    );
+
+    expect(breadcrumbs).toEqual(['first', 'second', 'third']);
+    expect(received).toEqual([
+      {queryClient, store},
+      {queryClient, store},
+      {queryClient, store},
+    ]);
+  });
+});

package/src/runtime/registries.test.tsx

@@ -0,0 +1,100 @@
+import {screen, within} from '@testing-library/react';
+import {defineClientFeature} from '#contract.js';
+import {renderComposedShell} from '#test/render.js';
+import {defineRoute} from './define-route.js';
+
+describe('composition registries', () => {
+  test('sorts navigation and settings entries by order, feature position, then declaration order', async () => {
+    const features = [
+      defineClientFeature({
+        id: 'shipfox.first',
+        navigation: [
+          {
+            id: 'first-a',
+            scope: 'workspace',
+            label: 'First A',
+            to: '/workspaces/$wid/first-a/',
+            order: 100,
+          },
+          {
+            id: 'first-b',
+            scope: 'workspace',
+            label: 'First B',
+            to: '/workspaces/$wid/first-b',
+            order: 100,
+          },
+        ],
+        settingsSections: [
+          {id: 'first', pathSegment: 'first', label: 'First setting', icon: 'userLine', order: 100},
+        ],
+        routes: [
+          {path: '/workspaces/$wid/first-a', parent: 'workspaceLayout', impl: 'first-a'},
+          {path: '/workspaces/$wid/first-b', parent: 'workspaceLayout', impl: 'first-b'},
+          {
+            path: '/workspaces/$wid/settings/first',
+            parent: 'workspaceSettings',
+            impl: 'first-setting',
+          },
+        ],
+      }),
+      defineClientFeature({
+        id: 'acme.second',
+        navigation: [
+          {
+            id: 'second',
+            scope: 'workspace',
+            label: 'Second',
+            to: '/workspaces/$wid/second',
+            order: 100,
+          },
+        ],
+        settingsSections: [
+          {
+            id: 'second',
+            pathSegment: 'second',
+            label: 'Second setting',
+            icon: 'userLine',
+            order: 200,
+          },
+        ],
+        routes: [
+          {path: '/workspaces/$wid/second', parent: 'workspaceLayout', impl: 'second'},
+          {
+            path: '/workspaces/$wid/settings/second',
+            parent: 'workspaceSettings',
+            impl: 'second-setting',
+          },
+        ],
+      }),
+    ];
+
+    await renderComposedShell({
+      features,
+      initialPath: '/workspaces/workspace/settings/first',
+      resolveImpl: () => defineRoute({component: () => <h1>Settings page</h1>}),
+    });
+
+    expect(await screen.findByRole('heading', {name: 'Workspace settings'})).toBeVisible();
+    expect((await screen.findAllByRole('tab')).map((tab) => tab.textContent)).toEqual([
+      'First A',
+      'First B',
+      'Second',
+    ]);
+    expect((await screen.findAllByRole('tab'))[0]).toHaveAttribute(
+      'href',
+      '/workspaces/workspace/first-a',
+    );
+    const settingsNavigation = screen.getByRole('navigation', {name: 'Workspace settings'});
+    expect(settingsNavigation.parentElement).toHaveClass('grid', 'grid-cols-[180px_minmax(0,1fr)]');
+    const settingsLinks = within(settingsNavigation).getAllByRole('link');
+    const [firstSettingsLink] = settingsLinks;
+    if (!firstSettingsLink) throw new Error('Expected at least one settings link.');
+
+    expect(settingsLinks.map((link) => link.textContent)).toEqual([
+      'First setting',
+      'Second setting',
+    ]);
+    expect(firstSettingsLink).toHaveClass('w-full', 'justify-start');
+    expect(firstSettingsLink.querySelector('svg')).toHaveClass('size-16');
+  });
+});

package/src/runtime/registries.ts

@@ -0,0 +1,42 @@
+import {normalizeRoutePath} from '#compose/normalize-route-path.js';
+import type {ClientFeature, NavTabEntry, SettingsSectionEntry} from '#contract.js';
+
+interface Ordered<T> {
+  entry: T;
+  featureIndex: number;
+  declarationIndex: number;
+}
+
+function byOrder<T extends {order?: number}>(left: Ordered<T>, right: Ordered<T>): number {
+  return (
+    (left.entry.order ?? 500) - (right.entry.order ?? 500) ||
+    left.featureIndex - right.featureIndex ||
+    left.declarationIndex - right.declarationIndex
+  );
+}
+
+export function navigationEntries(features: readonly ClientFeature[]): NavTabEntry[] {
+  return features
+    .flatMap((feature, featureIndex) =>
+      (feature.navigation ?? []).map((entry, declarationIndex) => ({
+        entry,
+        featureIndex,
+        declarationIndex,
+      })),
+    )
+    .sort(byOrder)
+    .map(({entry}) => ({...entry, to: normalizeRoutePath(entry.to)}));
+}
+
+export function settingsEntries(features: readonly ClientFeature[]): SettingsSectionEntry[] {
+  return features
+    .flatMap((feature, featureIndex) =>
+      (feature.settingsSections ?? []).map((entry, declarationIndex) => ({
+        entry,
+        featureIndex,
+        declarationIndex,
+      })),
+    )
+    .sort(byOrder)
+    .map(({entry}) => entry);
+}

package/src/runtime/router-context.ts

@@ -0,0 +1,9 @@
+import type {QueryClient} from '@tanstack/react-query';
+import type {AuthStateValue} from './auth.js';
+import type {WorkspaceSetupGate} from './workspace-setup.js';
+
+export interface RouterContext {
+  auth: AuthStateValue | undefined;
+  queryClient: QueryClient | undefined;
+  workspaceSetup?: WorkspaceSetupGate;
+}

package/src/runtime/routes.test.tsx

@@ -0,0 +1,48 @@
+import {screen} from '@testing-library/react';
+import {defineClientFeature} from '#contract.js';
+import {renderComposedShell} from '#test/render.js';
+import {defineRoute} from './define-route.js';
+
+describe('composed routes', () => {
+  test('renders a feature-added route through memory history', async () => {
+    const feature = defineClientFeature({
+      id: 'acme.insights',
+      routes: [{path: '/insights', parent: 'root', impl: 'insights'}],
+    });
+
+    await renderComposedShell({
+      features: [feature],
+      initialPath: '/insights',
+      resolveImpl: () => defineRoute({component: () => <h1>Insights</h1>}),
+    });
+
+    expect(await screen.findByRole('heading', {name: 'Insights'})).toBeVisible();
+  });
+
+  test('renders an explicit route override instead of the upstream route', async () => {
+    const features = [
+      defineClientFeature({
+        id: 'shipfox.projects',
+        routes: [{path: '/projects', parent: 'root', impl: 'upstream'}],
+      }),
+      defineClientFeature({
+        id: 'acme.projects',
+        routes: [{path: '/projects', parent: 'root', override: true, impl: 'override'}],
+      }),
+    ];
+
+    await renderComposedShell({
+      features,
+      initialPath: '/projects',
+      resolveImpl: (specifier) =>
+        defineRoute({
+          component: () => (
+            <h1>{specifier === 'override' ? 'Commercial projects' : 'Upstream projects'}</h1>
+          ),
+        }),
+    });
+
+    expect(await screen.findByRole('heading', {name: 'Commercial projects'})).toBeVisible();
+    expect(screen.queryByText('Upstream projects')).not.toBeInTheDocument();
+  });
+});

package/src/runtime/workspace-setup.tsx

@@ -0,0 +1,61 @@
+import {ApiError} from '@shipfox/client-api';
+import {Button} from '@shipfox/react-ui/button';
+import {Callout} from '@shipfox/react-ui/callout';
+import {FullPageLoader} from '@shipfox/react-ui/loader';
+import {Header, Text} from '@shipfox/react-ui/typography';
+import type {QueryClient} from '@tanstack/react-query';
+import {type ErrorComponentProps, useRouter} from '@tanstack/react-router';
+
+export interface WorkspaceSetupState {
+  hideProjectNavigation: boolean;
+}
+export interface WorkspaceSetupRouteOptions {
+  queryClient: QueryClient;
+  workspaceId: string;
+  pathname: string;
+}
+export type WorkspaceSetupGate = (
+  options: WorkspaceSetupRouteOptions,
+) => Promise<WorkspaceSetupState>;
+
+export class WorkspaceSetupLoadError extends Error {
+  constructor(public override readonly cause: unknown) {
+    super(cause instanceof Error ? cause.message : 'Workspace setup load failed');
+    this.name = 'WorkspaceSetupLoadError';
+  }
+}
+export function WorkspaceSetupPending() {
+  return <FullPageLoader />;
+}
+export function WorkspaceLayoutErrorRoute({error, reset}: ErrorComponentProps) {
+  const router = useRouter();
+  const retry = () => {
+    reset();
+    void router.invalidate();
+  };
+  const setupError = error instanceof WorkspaceSetupLoadError;
+  const message =
+    error instanceof ApiError
+      ? error.message
+      : setupError && error.cause instanceof ApiError
+        ? error.cause.message
+        : 'Try again in a moment.';
+  return (
+    <main className="min-h-screen bg-background-subtle-base px-24 py-32 max-[520px]:px-16">
+      <div className="mx-auto flex w-full max-w-[640px] flex-col gap-24">
+        <Header variant="h1">{setupError ? 'Workspace setup' : 'Workspace'}</Header>
+        <Callout role="alert" type="error">
+          <div className="flex flex-col gap-8">
+            <Text size="sm" bold>
+              {setupError ? 'Could not load workspace setup' : 'Could not load workspace'}
+            </Text>
+            <Text size="sm">{message}</Text>
+            <Button size="sm" variant="secondary" onClick={retry} className="w-fit">
+              Retry
+            </Button>
+          </div>
+        </Callout>
+      </div>
+    </main>
+  );
+}

package/src/testing/index.test.tsx

@@ -0,0 +1,57 @@
+import {getLoadedConfig} from '@shipfox/client-config';
+import {QueryClient, useQueryClient} from '@tanstack/react-query';
+import {render, screen} from '@testing-library/react';
+import {createStore, useStore} from 'jotai';
+import {createShellDecorator, ShellProviders} from './index.js';
+
+describe('shell testing helpers', () => {
+  test('uses caller-owned state and installs runtime config', () => {
+    const queryClient = new QueryClient();
+    const store = createStore();
+    const config = {apiUrl: 'https://example.test'};
+    const Probe = () => {
+      const receivedQueryClient = useQueryClient();
+      const receivedStore = useStore();
+      return (
+        <div>
+          {receivedQueryClient === queryClient && receivedStore === store
+            ? 'caller state'
+            : 'default state'}
+        </div>
+      );
+    };
+
+    render(
+      <ShellProviders queryClient={queryClient} store={store} config={config}>
+        <Probe />
+      </ShellProviders>,
+    );
+
+    expect(screen.getByText('caller state')).toBeInTheDocument();
+    expect(getLoadedConfig()).toEqual(config);
+  });
+
+  test('creates a configured Storybook decorator', () => {
+    const DecoratedStory = createShellDecorator({config: {mode: 'storybook'}})(
+      () => <div>Story content</div>,
+      {} as never,
+    );
+
+    render(DecoratedStory);
+
+    expect(screen.getByText('Story content')).toBeInTheDocument();
+    expect(getLoadedConfig()).toEqual({mode: 'storybook'});
+  });
+
+  test('does not refresh auth when rendering static testing providers', () => {
+    const fetchSpy = vi.spyOn(globalThis, 'fetch');
+
+    render(
+      <ShellProviders>
+        <div>Static content</div>
+      </ShellProviders>,
+    );
+
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});

package/src/testing/index.tsx

@@ -0,0 +1,51 @@
+import {setLoadedConfig} from '@shipfox/client-config';
+import type {Decorator} from '@storybook/react';
+import {QueryClient, type QueryClient as QueryClientInstance} from '@tanstack/react-query';
+import {createStore} from 'jotai';
+import {type PropsWithChildren, useState} from 'react';
+import type {ClientFeature} from '#contract.js';
+import {ShellProviderStack} from '../runtime/provider-stack.js';
+
+type Store = ReturnType<typeof createStore>;
+
+export interface ShellProvidersOptions {
+  features?: readonly ClientFeature[];
+  queryClient?: QueryClientInstance;
+  store?: Store;
+  config?: unknown;
+}
+
+export function ShellProviders({
+  features = [],
+  queryClient: providedQueryClient,
+  store: providedStore,
+  config,
+  children,
+}: PropsWithChildren<ShellProvidersOptions>) {
+  const [defaultQueryClient] = useState(
+    () => new QueryClient({defaultOptions: {queries: {retry: false}}}),
+  );
+  const [defaultStore] = useState(createStore);
+  if (config !== undefined) setLoadedConfig(config);
+
+  return (
+    <ShellProviderStack
+      features={features}
+      queryClient={providedQueryClient ?? defaultQueryClient}
+      store={providedStore ?? defaultStore}
+      auth={{effects: false}}
+    >
+      {children}
+    </ShellProviderStack>
+  );
+}
+
+export function createShellDecorator(options: ShellProvidersOptions = {}): Decorator {
+  return (Story) => (
+    <ShellProviders {...options}>
+      <Story />
+    </ShellProviders>
+  );
+}
+
+export const shellDecorator = createShellDecorator();