@shipfox/client-shell 0.2.0

package/src/components/nav-tabs.tsx

@@ -0,0 +1,47 @@
+import {Link, useParams} from '@tanstack/react-router';
+import {useReducedMotion} from 'framer-motion';
+import type {NavTabEntry} from '#contract.js';
+
+export function NavTabs({
+  entries,
+  scope,
+}: {
+  entries: readonly NavTabEntry[];
+  scope: NavTabEntry['scope'];
+}) {
+  const params = useParams({strict: false}) as {wid?: string; pid?: string};
+  const reduced = useReducedMotion();
+  const tabs = entries.filter((entry) => entry.scope === scope);
+  const tabClassName = `h-40 inline-flex items-center px-4 text-sm font-medium transition-colors ${reduced ? '' : 'transition-[border-color]'}`;
+  const activeProps = {
+    className: 'border-b-2 border-border-highlights-interactive text-foreground-neutral-base',
+    'aria-selected': 'true' as const,
+  };
+  const inactiveProps = {
+    className: 'border-b-2 border-transparent text-foreground-neutral-muted',
+    'aria-selected': 'false' as const,
+  };
+
+  return (
+    <div
+      role="tablist"
+      aria-label={`${scope === 'project' ? 'Project' : 'Workspace'} sections`}
+      className="sticky top-56 z-20 h-40 px-16 flex items-end gap-12 bg-background-subtle-base border-b border-border-neutral-base"
+    >
+      {tabs.map((entry) => (
+        <Link
+          key={entry.id}
+          to={entry.to as never}
+          params={params as never}
+          role="tab"
+          activeOptions={{exact: entry.exact ?? false}}
+          activeProps={activeProps}
+          inactiveProps={inactiveProps}
+          className={tabClassName}
+        >
+          {entry.label}
+        </Link>
+      ))}
+    </div>
+  );
+}

package/src/components/not-found-page.tsx

@@ -0,0 +1,14 @@
+import {Header, Text} from '@shipfox/react-ui/typography';
+import {Link} from '@tanstack/react-router';
+
+export function NotFoundPage() {
+  return (
+    <main className="mx-auto max-w-[960px] px-24 py-48">
+      <Header variant="h1">Page not found</Header>
+      <Text size="md" className="text-foreground-neutral-muted">
+        This Shipfox page does not exist.
+      </Text>
+      <Link to="/">Go home</Link>
+    </main>
+  );
+}

package/src/components/settings-nav.tsx

@@ -0,0 +1,35 @@
+import {Button} from '@shipfox/react-ui/button';
+import {Icon} from '@shipfox/react-ui/icon';
+import {Link, useMatchRoute, useParams} from '@tanstack/react-router';
+import type {SettingsSectionEntry} from '#contract.js';
+
+export function SettingsNav({entries}: {entries: readonly SettingsSectionEntry[]}) {
+  const params = useParams({strict: false}) as {wid?: string};
+  const matchRoute = useMatchRoute();
+  if (!params.wid) return null;
+  return (
+    <nav aria-label="Workspace settings" className="flex flex-col gap-4">
+      {entries.map((entry) => {
+        const to = `/workspaces/$wid/settings/${entry.pathSegment}`;
+        const active = Boolean(matchRoute({to: to as never, params: {wid: params.wid} as never}));
+        return (
+          <Button
+            key={entry.id}
+            asChild
+            variant={active ? 'secondary' : 'transparent'}
+            className="w-full justify-start"
+          >
+            <Link
+              to={to as never}
+              params={{wid: params.wid} as never}
+              aria-current={active ? 'page' : undefined}
+            >
+              <Icon name={entry.icon} className="size-16" />
+              {entry.label}
+            </Link>
+          </Button>
+        );
+      })}
+    </nav>
+  );
+}

package/src/components/user-menu.tsx

@@ -0,0 +1,59 @@
+import {Avatar} from '@shipfox/react-ui/avatar';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '@shipfox/react-ui/dropdown-menu';
+import {useTheme} from '@shipfox/react-ui/hooks';
+import type {Theme} from '@shipfox/react-ui/theme';
+import {Link} from '@tanstack/react-router';
+import {useAuthState} from '#runtime/auth.js';
+
+const themeOptions: Array<{value: Theme; label: string}> = [
+  {value: 'light', label: 'Light'},
+  {value: 'dark', label: 'Dark'},
+  {value: 'system', label: 'System'},
+];
+export function UserMenu() {
+  const {user} = useAuthState();
+  const {theme, setTheme} = useTheme();
+  const email = user?.email ?? '';
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <button
+          type="button"
+          aria-label="User menu"
+          className="rounded-full focus-visible:outline-none focus-visible:shadow-button-neutral-focus"
+        >
+          <Avatar size="sm" content="letters" fallback={email} />
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" sideOffset={8} className="min-w-[220px]">
+        <DropdownMenuLabel className="text-xs text-foreground-neutral-muted truncate">
+          {email}
+        </DropdownMenuLabel>
+        <DropdownMenuSeparator />
+        <DropdownMenuLabel className="text-xs text-foreground-neutral-muted">
+          Theme
+        </DropdownMenuLabel>
+        <DropdownMenuRadioGroup value={theme} onValueChange={(value) => setTheme(value as Theme)}>
+          {themeOptions.map((option) => (
+            <DropdownMenuRadioItem key={option.value} value={option.value}>
+              {option.label}
+            </DropdownMenuRadioItem>
+          ))}
+        </DropdownMenuRadioGroup>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem asChild>
+          <Link to={'/auth/logout' as never}>Logout</Link>
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}

package/src/components/workspace-crumb.tsx

@@ -0,0 +1,43 @@
+import {Icon} from '@shipfox/react-ui/icon';
+import {Popover, PopoverContent, PopoverTrigger} from '@shipfox/react-ui/popover';
+import {Link} from '@tanstack/react-router';
+import {useState} from 'react';
+import type {Workspace} from '#runtime/auth.js';
+import {WorkspaceSwitcher} from './workspace-switcher.js';
+
+export interface WorkspaceCrumbProps {
+  workspace: Workspace;
+  compact?: boolean;
+}
+
+export function WorkspaceCrumb({workspace, compact = false}: WorkspaceCrumbProps) {
+  const [open, setOpen] = useState(false);
+  return (
+    <div className="flex items-center">
+      <Link
+        to="/workspaces/$wid"
+        params={{wid: workspace.id}}
+        aria-current="page"
+        className={`inline-block text-md font-medium text-foreground-neutral-base px-6 py-4 rounded-6 hover:bg-background-components-hover transition-colors truncate ${compact ? 'max-w-[120px] sm:max-w-[200px]' : 'max-w-[200px]'}`}
+      >
+        {workspace.name}
+      </Link>
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger asChild>
+          <button
+            type="button"
+            aria-label="Switch workspace"
+            aria-haspopup="listbox"
+            aria-expanded={open}
+            className="ml-2 grid place-items-center size-24 rounded-4 text-foreground-neutral-muted hover:bg-background-components-hover hover:text-foreground-neutral-base transition-colors"
+          >
+            <Icon name="arrowDownSLine" className="size-16" />
+          </button>
+        </PopoverTrigger>
+        <PopoverContent className="w-[280px] p-0" align="start" sideOffset={8}>
+          <WorkspaceSwitcher activeWorkspaceId={workspace.id} onSelect={() => setOpen(false)} />
+        </PopoverContent>
+      </Popover>
+    </div>
+  );
+}

package/src/components/workspace-switcher.tsx

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

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

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

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

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

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

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

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

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

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