@shipfox/client-shell 1.0.0 → 3.0.1

package/src/runtime/providers.test.tsx

@@ -1,51 +0,0 @@
-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

@@ -1,100 +0,0 @@
-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

@@ -1,42 +0,0 @@
-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

@@ -1,9 +0,0 @@
-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

@@ -1,48 +0,0 @@
-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

@@ -1,61 +0,0 @@
-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

@@ -1,57 +0,0 @@
-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

@@ -1,51 +0,0 @@
-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();

package/src/vite/evaluate-features.test.ts

@@ -1,89 +0,0 @@
-import {mkdtemp, realpath, rm, writeFile} from 'node:fs/promises';
-import {tmpdir} from 'node:os';
-import {join} from 'node:path';
-import {fileURLToPath} from 'node:url';
-import {evaluateFeatures} from './evaluate-features.js';
-
-const fixtureFeatures = fileURLToPath(new URL('../../test/fixtures/features.ts', import.meta.url));
-const contractSource = fileURLToPath(new URL('../contract.ts', import.meta.url));
-
-describe('evaluateFeatures', () => {
-  let directory: string;
-
-  beforeEach(async () => {
-    directory = await mkdtemp(join(tmpdir(), 'shipfox-client-shell-vite-'));
-  });
-
-  afterEach(async () => {
-    await rm(directory, {recursive: true, force: true});
-  });
-
-  test('reloads dependencies and reports them as watched files', async () => {
-    const features = join(directory, 'features.ts');
-    const contribution = join(directory, 'contribution.ts');
-    await writeFile(
-      features,
-      `import {feature} from './contribution.ts';
-export const features = [feature];`,
-    );
-    await writeFile(contribution, `export const feature = {id: 'acme.projects'};`);
-
-    await evaluateFeatures(features);
-    await writeFile(contribution, `export const feature = {id: 'acme.reports'};`);
-
-    const evaluated = await evaluateFeatures(features);
-
-    expect(evaluated.features).toEqual([{id: 'acme.reports'}]);
-    expect(evaluated.loadedFiles).toContain(await realpath(contribution));
-  });
-
-  test('reloads JSON dependencies and reports them as watched files', async () => {
-    const features = join(directory, 'features.ts');
-    const contribution = join(directory, 'contribution.json');
-    await writeFile(
-      features,
-      `import feature from './contribution.json';
-export const features = [feature];`,
-    );
-    await writeFile(contribution, JSON.stringify({id: 'acme.projects'}));
-
-    await evaluateFeatures(features);
-    await writeFile(contribution, JSON.stringify({id: 'acme.reports'}));
-
-    const evaluated = await evaluateFeatures(features);
-
-    expect(evaluated.features).toEqual([{id: 'acme.reports'}]);
-    expect(evaluated.loadedFiles).toContain(await realpath(contribution));
-  });
-
-  test('evicts JSON dependencies after evaluation fails', async () => {
-    const features = join(directory, 'features.ts');
-    const contribution = join(directory, 'contribution.json');
-    await writeFile(
-      features,
-      `import feature from './contribution.json';
-throw new Error('fixture failure');
-export const features = [feature];`,
-    );
-    await writeFile(contribution, JSON.stringify({id: 'acme.projects'}));
-
-    const failedEvaluation = evaluateFeatures(features);
-    await expect(failedEvaluation).rejects.toThrow('fixture failure');
-    await writeFile(
-      features,
-      `import feature from './contribution.json';
-export const features = [feature];`,
-    );
-    await writeFile(contribution, JSON.stringify({id: 'acme.reports'}));
-
-    const evaluated = await evaluateFeatures(features);
-
-    expect(evaluated.features).toEqual([{id: 'acme.reports'}]);
-  });
-
-  test('resolves package imports through the workspace source condition', async () => {
-    const evaluated = await evaluateFeatures(fixtureFeatures);
-
-    expect(evaluated.loadedFiles).toContain(await realpath(contractSource));
-  });
-});

package/src/vite/evaluate-features.ts

@@ -1,114 +0,0 @@
-import {randomUUID} from 'node:crypto';
-import {realpath} from 'node:fs/promises';
-import {createRequire} from 'node:module';
-import {resolve} from 'node:path';
-import {register} from 'tsx/cjs/api';
-import type {ClientFeature} from '#contract.js';
-
-const require = createRequire(import.meta.url);
-const nodeModulesPathPattern = /[\\/]node_modules[\\/]/;
-
-export interface EvaluatedFeatures {
-  features: readonly ClientFeature[];
-  loadedFiles: readonly string[];
-}
-
-function loadedModuleGraph(namespaceQuery: string): {
-  cacheKeys: Set<string>;
-  loadedPaths: Set<string>;
-} {
-  const cacheKeys = new Set<string>();
-  const loadedPaths = new Set<string>();
-  const keysByModule = new Map<NodeJS.Module, string[]>();
-
-  for (const [cacheKey, cachedModule] of Object.entries(require.cache)) {
-    if (!cachedModule) continue;
-    const keys = keysByModule.get(cachedModule) ?? [];
-    keys.push(cacheKey);
-    keysByModule.set(cachedModule, keys);
-  }
-
-  const visited = new Set<NodeJS.Module>();
-  function visit(cachedModule: NodeJS.Module): void {
-    if (visited.has(cachedModule)) return;
-    visited.add(cachedModule);
-
-    for (const cacheKey of keysByModule.get(cachedModule) ?? []) {
-      const path = cacheKey.endsWith(namespaceQuery)
-        ? cacheKey.slice(0, -namespaceQuery.length)
-        : cacheKey;
-      const isLocal = !nodeModulesPathPattern.test(path);
-      if (isLocal) loadedPaths.add(path);
-      if (isLocal || cacheKey.endsWith(namespaceQuery)) cacheKeys.add(cacheKey);
-    }
-
-    for (const child of cachedModule.children) visit(child);
-  }
-
-  for (const [cacheKey, cachedModule] of Object.entries(require.cache)) {
-    if (cachedModule && cacheKey.endsWith(namespaceQuery)) visit(cachedModule);
-  }
-
-  return {cacheKeys, loadedPaths};
-}
-
-async function localFiles(paths: Iterable<string>): Promise<string[]> {
-  const files = new Set<string>();
-  for (const path of paths) {
-    if (nodeModulesPathPattern.test(path)) continue;
-    files.add(await realpath(path).catch(() => path));
-  }
-  return [...files];
-}
-
-export async function evaluateFeatures(featuresModule: string): Promise<EvaluatedFeatures> {
-  const resolvedFeaturesModule = await realpath(resolve(featuresModule));
-  const namespace = randomUUID();
-  const namespaceQuery = `?namespace=${namespace}`;
-  const loader = register({namespace});
-  const loadedPaths = new Set<string>([resolvedFeaturesModule]);
-  const cacheKeys = new Set<string>();
-  const initialCacheKeys = new Set(Object.keys(require.cache));
-  let module: {default?: unknown; features?: unknown};
-  try {
-    module = loader.require(resolvedFeaturesModule, import.meta.url) as {
-      default?: unknown;
-      features?: unknown;
-    };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(
-      `Failed to evaluate features module "${resolvedFeaturesModule}". Features modules must be Node-safe: ${message}`,
-      {cause: error},
-    );
-  } finally {
-    const graph = loadedModuleGraph(namespaceQuery);
-    for (const path of graph.loadedPaths) loadedPaths.add(path);
-    for (const cacheKey of graph.cacheKeys) cacheKeys.add(cacheKey);
-    for (const cacheKey of Object.keys(require.cache)) {
-      if (initialCacheKeys.has(cacheKey)) continue;
-      const path = cacheKey.endsWith(namespaceQuery)
-        ? cacheKey.slice(0, -namespaceQuery.length)
-        : cacheKey;
-      const isLocal = !nodeModulesPathPattern.test(path);
-      if (isLocal) loadedPaths.add(path);
-      if (isLocal || cacheKey.endsWith(namespaceQuery)) cacheKeys.add(cacheKey);
-    }
-    loader.unregister();
-    for (const cacheKey of cacheKeys) delete require.cache[cacheKey];
-    for (const cacheKey of Object.keys(require.cache))
-      if (cacheKey.endsWith(namespaceQuery)) delete require.cache[cacheKey];
-  }
-
-  const features = module.features ?? module.default;
-  if (!Array.isArray(features)) {
-    throw new TypeError(
-      `Features module "${resolvedFeaturesModule}" must export a features array.`,
-    );
-  }
-
-  return {
-    features: features as readonly ClientFeature[],
-    loadedFiles: await localFiles(loadedPaths),
-  };
-}

package/src/vite/generate.test.ts

@@ -1,22 +0,0 @@
-import {readFile} from 'node:fs/promises';
-import {fileURLToPath} from 'node:url';
-import {composeRoutes} from '#compose/compose-routes.js';
-import {navigationEntries, settingsEntries} from '#runtime/registries.js';
-import {features} from '#test/fixtures/features.js';
-import {generateAppModule} from './generate.js';
-
-const goldenFile = fileURLToPath(
-  new URL('../../test/typecheck/shipfox-app.gen.ts', import.meta.url),
-);
-
-describe('generateAppModule', () => {
-  test('matches the checked composition fixture', async () => {
-    const generated = generateAppModule({
-      routes: composeRoutes(features),
-      navigation: navigationEntries(features),
-      settingsSections: settingsEntries(features),
-    });
-
-    await expect(readFile(goldenFile, 'utf8')).resolves.toBe(generated);
-  });
-});