@shipfox/client-shell 1.0.0 → 3.0.1

package/src/components/workspace-switcher.tsx

@@ -1,75 +0,0 @@
-import {
-  Command,
-  CommandEmpty,
-  CommandGroup,
-  CommandInput,
-  CommandItem,
-  CommandList,
-  CommandSeparator,
-} from '@shipfox/react-ui/command';
-import {Icon} from '@shipfox/react-ui/icon';
-import {useNavigate} from '@tanstack/react-router';
-import {useSetAtom} from 'jotai';
-import {useAuthState} from '#runtime/auth.js';
-import {lastWorkspaceIdAtom} from '#runtime/last-workspace.js';
-
-export function WorkspaceSwitcher({
-  activeWorkspaceId,
-  onSelect,
-}: {
-  activeWorkspaceId?: string;
-  onSelect?: () => void;
-}) {
-  const {workspaces} = useAuthState();
-  const navigate = useNavigate();
-  const setLastWorkspaceId = useSetAtom(lastWorkspaceIdAtom);
-  const selectWorkspace = (wid: string) => {
-    try {
-      setLastWorkspaceId(wid);
-    } catch {
-      // Local storage is best effort.
-    }
-    navigate({to: '/workspaces/$wid', params: {wid}});
-    onSelect?.();
-  };
-  return (
-    <Command>
-      <CommandInput placeholder="Search workspaces..." />
-      <CommandList className="max-h-none overflow-visible overflow-y-visible p-0">
-        <div className="max-h-300 overflow-y-auto overflow-x-hidden p-4 scrollbar">
-          <CommandEmpty>No workspaces found.</CommandEmpty>
-          <CommandGroup heading="Workspaces">
-            {workspaces.map((workspace) => (
-              <CommandItem
-                key={workspace.id}
-                value={workspace.id}
-                keywords={[workspace.name]}
-                onSelect={() => selectWorkspace(workspace.id)}
-              >
-                <Icon
-                  name="check"
-                  className={`size-16 mr-8 ${activeWorkspaceId === workspace.id ? 'opacity-100' : 'opacity-0'}`}
-                />
-                {workspace.name}
-              </CommandItem>
-            ))}
-          </CommandGroup>
-        </div>
-        <CommandSeparator alwaysRender className="mx-0" />
-        <CommandGroup forceMount className="p-4">
-          <CommandItem
-            value="__create"
-            onSelect={() => {
-              navigate({to: '/setup/workspaces/new' as never});
-              onSelect?.();
-            }}
-            forceMount
-          >
-            <Icon name="addLine" className="size-16" />
-            Create workspace
-          </CommandItem>
-        </CommandGroup>
-      </CommandList>
-    </Command>
-  );
-}

package/src/compose/compose-routes.test.ts

@@ -1,112 +0,0 @@
-import type {ClientFeature} from '#contract.js';
-import {composeRoutes} from './compose-routes.js';
-
-const base: ClientFeature = {
-  id: 'shipfox.base',
-  routes: [{path: '/projects', parent: 'root', impl: 'base'}],
-};
-const collisionMessage = /\/projects.*shipfox\.base.*acme\.insights/u;
-const danglingOverrideMessage = /\/missing.*acme\.insights/u;
-const competingOverridesMessage = /\/projects.*acme\.one.*acme\.two/u;
-
-describe('composeRoutes', () => {
-  test('appends a unique route and explicitly replaces an existing route', () => {
-    const routes = composeRoutes([
-      base,
-      {
-        id: 'acme.insights',
-        routes: [{path: '/projects', parent: 'root', override: true, impl: 'override'}],
-      },
-      {id: 'acme.audit', routes: [{path: '/audit', parent: 'root', impl: 'audit'}]},
-    ]);
-
-    expect(routes).toEqual([
-      {
-        path: '/projects',
-        parent: 'root',
-        override: true,
-        impl: 'override',
-        featureId: 'acme.insights',
-      },
-      {path: '/audit', parent: 'root', impl: 'audit', featureId: 'acme.audit'},
-    ]);
-  });
-
-  test('names the path and both features for a collision', () => {
-    expect(() =>
-      composeRoutes([
-        base,
-        {id: 'acme.insights', routes: [{path: '/projects', parent: 'root', impl: 'next'}]},
-      ]),
-    ).toThrow(collisionMessage);
-  });
-
-  test('normalizes trailing slashes before collision checks', () => {
-    expect(() =>
-      composeRoutes([
-        base,
-        {
-          id: 'acme.insights',
-          routes: [{path: '/projects/', parent: 'root', impl: 'next'}],
-        },
-      ]),
-    ).toThrow(collisionMessage);
-  });
-
-  test('names the path and feature for a dangling override', () => {
-    expect(() =>
-      composeRoutes([
-        {
-          id: 'acme.insights',
-          routes: [{path: '/missing', parent: 'root', override: true, impl: 'next'}],
-        },
-      ]),
-    ).toThrow(danglingOverrideMessage);
-  });
-
-  test('names the path and both features for competing overrides', () => {
-    expect(() =>
-      composeRoutes([
-        base,
-        {
-          id: 'acme.one',
-          routes: [{path: '/projects', parent: 'root', override: true, impl: 'one'}],
-        },
-        {
-          id: 'acme.two',
-          routes: [{path: '/projects', parent: 'root', override: true, impl: 'two'}],
-        },
-      ]),
-    ).toThrow(competingOverridesMessage);
-  });
-
-  test('rejects an override that changes the route anchor', () => {
-    expect(() =>
-      composeRoutes([
-        {
-          id: 'shipfox.projects',
-          routes: [
-            {
-              path: '/workspaces/$wid/projects',
-              parent: 'workspaceLayout',
-              impl: 'base',
-            },
-          ],
-        },
-        {
-          id: 'acme.projects',
-          routes: [
-            {
-              path: '/workspaces/$wid/projects',
-              parent: 'root',
-              override: true,
-              impl: 'override',
-            },
-          ],
-        },
-      ]),
-    ).toThrow(
-      'Route override for "/workspaces/$wid/projects" from feature "acme.projects" cannot change anchor from "workspaceLayout" in feature "shipfox.projects" to "root".',
-    );
-  });
-});

package/src/compose/compose-routes.ts

@@ -1,60 +0,0 @@
-import type {ClientFeature, RouteContribution} from '#contract.js';
-import {RouteCompositionError} from './errors.js';
-import {normalizeRoutePath} from './normalize-route-path.js';
-
-export interface ComposedRoute extends RouteContribution {
-  featureId: string;
-}
-
-export function composeRoutes(features: readonly ClientFeature[]): ComposedRoute[] {
-  const routes = new Map<string, ComposedRoute>();
-  for (const feature of features) {
-    for (const contribution of feature.routes ?? []) {
-      const normalizedContribution = {
-        ...contribution,
-        path: normalizeRoutePath(contribution.path),
-      };
-      const existing = routes.get(normalizedContribution.path);
-      if (!existing) {
-        if (normalizedContribution.override) {
-          throw new RouteCompositionError(
-            normalizedContribution.path,
-            `Route override for "${normalizedContribution.path}" from feature "${feature.id}" has no route to replace.`,
-            [feature.id],
-          );
-        }
-        routes.set(normalizedContribution.path, {
-          ...normalizedContribution,
-          featureId: feature.id,
-        });
-        continue;
-      }
-      if (!normalizedContribution.override) {
-        throw new RouteCompositionError(
-          normalizedContribution.path,
-          `Route "${normalizedContribution.path}" is contributed by both features "${existing.featureId}" and "${feature.id}". Set override: true to replace it explicitly.`,
-          [existing.featureId, feature.id],
-        );
-      }
-      if (existing.override) {
-        throw new RouteCompositionError(
-          normalizedContribution.path,
-          `Route "${normalizedContribution.path}" has competing overrides from features "${existing.featureId}" and "${feature.id}".`,
-          [existing.featureId, feature.id],
-        );
-      }
-      if (existing.parent !== normalizedContribution.parent) {
-        throw new RouteCompositionError(
-          normalizedContribution.path,
-          `Route override for "${normalizedContribution.path}" from feature "${feature.id}" cannot change anchor from "${existing.parent}" in feature "${existing.featureId}" to "${normalizedContribution.parent}".`,
-          [existing.featureId, feature.id],
-        );
-      }
-      routes.set(normalizedContribution.path, {
-        ...normalizedContribution,
-        featureId: feature.id,
-      });
-    }
-  }
-  return [...routes.values()];
-}

package/src/compose/errors.ts

@@ -1,54 +0,0 @@
-abstract class CompositionError extends Error {
-  public readonly featureIds: readonly string[];
-
-  protected constructor(name: string, message: string, featureIds: readonly string[]) {
-    super(message);
-    this.name = name;
-    this.featureIds = featureIds;
-  }
-}
-
-export class RouteCompositionError extends CompositionError {
-  public readonly path: string;
-
-  constructor(path: string, message: string, featureIds: readonly string[]) {
-    super('RouteCompositionError', message, featureIds);
-    this.path = path;
-  }
-}
-
-export class ProviderCompositionError extends CompositionError {
-  public readonly id: string;
-
-  constructor(id: string, message: string, featureIds: readonly string[]) {
-    super('ProviderCompositionError', message, featureIds);
-    this.id = id;
-  }
-}
-
-export class NavCompositionError extends CompositionError {
-  public readonly id: string;
-
-  constructor(id: string, message: string, featureIds: readonly string[]) {
-    super('NavCompositionError', message, featureIds);
-    this.id = id;
-  }
-}
-
-export class SettingsCompositionError extends CompositionError {
-  public readonly id: string;
-
-  constructor(id: string, message: string, featureIds: readonly string[]) {
-    super('SettingsCompositionError', message, featureIds);
-    this.id = id;
-  }
-}
-
-export class ConfigCompositionError extends CompositionError {
-  public readonly key: string;
-
-  constructor(key: string, message: string, featureIds: readonly string[]) {
-    super('ConfigCompositionError', message, featureIds);
-    this.key = key;
-  }
-}

package/src/compose/merge-config.test.ts

@@ -1,26 +0,0 @@
-import {z} from 'zod';
-import {mergeConfigShapes} from './merge-config.js';
-
-const duplicateConfigMessage = /shared.*shipfox\.one.*acme\.two/u;
-
-describe('mergeConfigShapes', () => {
-  test('names the key and both features for independent duplicate schemas', () => {
-    expect(() =>
-      mergeConfigShapes([
-        {id: 'shipfox.one', configShape: {shared: z.string()}},
-        {id: 'acme.two', configShape: {shared: z.string()}},
-      ]),
-    ).toThrow(duplicateConfigMessage);
-  });
-
-  test('deduplicates the exact same schema instance', () => {
-    const shared = z.string();
-
-    expect(
-      mergeConfigShapes([
-        {id: 'shipfox.one', configShape: {shared}},
-        {id: 'acme.two', configShape: {shared}},
-      ]).shared,
-    ).toBe(shared);
-  });
-});

package/src/compose/merge-config.ts

@@ -1,27 +0,0 @@
-import type {z} from 'zod';
-import {shellConfigShape} from '#config/shell-config.js';
-import type {ClientFeature} from '#contract.js';
-import {ConfigCompositionError} from './errors.js';
-
-export function mergeConfigShapes(features: readonly ClientFeature[]): z.ZodRawShape {
-  const merged = {...shellConfigShape} as Record<string, z.ZodRawShape[string]>;
-  const owners = new Map<string, string>(
-    Object.keys(shellConfigShape).map((key) => [key, 'shell']),
-  );
-  for (const feature of features) {
-    for (const [key, schema] of Object.entries(feature.configShape ?? {})) {
-      const existing = merged[key];
-      if (existing && existing !== schema) {
-        const existingFeatureId = owners.get(key) ?? 'shell';
-        throw new ConfigCompositionError(
-          key,
-          `Config key "${key}" is contributed by both features "${existingFeatureId}" and "${feature.id}". Reuse the same schema instance to intentionally share it.`,
-          [existingFeatureId, feature.id],
-        );
-      }
-      merged[key] = schema;
-      owners.set(key, feature.id);
-    }
-  }
-  return merged as z.ZodRawShape;
-}

package/src/compose/normalize-route-path.ts

@@ -1,6 +0,0 @@
-const trailingSlashes = /\/+$/u;
-
-export function normalizeRoutePath(path: string): string {
-  if (path === '/') return path;
-  return path.replace(trailingSlashes, '') || '/';
-}

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

@@ -1,31 +0,0 @@
-import type {ClientFeature} from '#contract.js';
-import {validateProviderIds} from './validate-providers.js';
-
-const duplicateProviderMessage = /flags.*shipfox\.one.*acme\.two/u;
-
-describe('validateProviderIds', () => {
-  test('names an id and both features for duplicate providers', () => {
-    expect(() =>
-      validateProviderIds([
-        {id: 'shipfox.one', providers: [{id: 'flags', Component: () => null}]},
-        {id: 'acme.two', providers: [{id: 'flags', Component: () => null}]},
-      ]),
-    ).toThrow(duplicateProviderMessage);
-  });
-
-  test.each([
-    'theme',
-    'tooltip',
-    'query-client',
-    'jotai-store',
-    'auth',
-    'router',
-    'toaster',
-  ])('rejects reserved provider id %s', (id) => {
-    const features: ClientFeature[] = [
-      {id: 'acme.feature', providers: [{id, Component: () => null}]},
-    ];
-
-    expect(() => validateProviderIds(features)).toThrow(new RegExp(`${id}.*acme\\.feature`, 'u'));
-  });
-});

package/src/compose/validate-providers.ts

@@ -1,36 +0,0 @@
-import type {ClientFeature} from '#contract.js';
-import {ProviderCompositionError} from './errors.js';
-
-const reservedProviderIds = new Set([
-  'theme',
-  'tooltip',
-  'query-client',
-  'jotai-store',
-  'auth',
-  'router',
-  'toaster',
-]);
-
-export function validateProviderIds(features: readonly ClientFeature[]): void {
-  const providers = new Map<string, string>();
-  for (const feature of features) {
-    for (const provider of feature.providers ?? []) {
-      if (reservedProviderIds.has(provider.id)) {
-        throw new ProviderCompositionError(
-          provider.id,
-          `Provider id "${provider.id}" in feature "${feature.id}" is reserved by the shell.`,
-          [feature.id],
-        );
-      }
-      const existingFeatureId = providers.get(provider.id);
-      if (existingFeatureId) {
-        throw new ProviderCompositionError(
-          provider.id,
-          `Provider id "${provider.id}" is contributed by both features "${existingFeatureId}" and "${feature.id}".`,
-          [existingFeatureId, feature.id],
-        );
-      }
-      providers.set(provider.id, feature.id);
-    }
-  }
-}

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

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

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

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

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

@@ -1,47 +0,0 @@
-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;
-}