@sempods/apps 0.8.0 → 0.9.0-dev.1

package/scripts/sdk-update.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 // One SDK release for the root and every registered app: the manifests name
-// it, pnpm installs it, and the update counts only once node_modules has it
-// and check passes. Usage: pnpm run sdk-update <version|latest>
+// it for both SDK packages and the UI kit, pnpm installs it, and the update
+// counts only once node_modules has it and check passes.
+// Usage: pnpm run sdk-update <version|latest>
 import {
   existsSync,
   readFileSync,
@@ -11,17 +12,20 @@ import {
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
+import semver from 'semver';
 import { readApps } from './lib/apps.mjs';
-import { formatJson, ifPresent, readJson } from './lib/json.mjs';
+import { formatJson, ifPresent, readJson, sortedKeys } from './lib/json.mjs';
 import { migrationState } from './migrate.mjs';
 import { repositoryRoot } from './lib/paths.mjs';
 import { INSTALL, pnpm, pnpmJson, scriptArgs } from './lib/pnpm.mjs';
 import {
+  appSdk,
   compareVersions,
   EXACT_VERSION,
   PENDING_UPDATE,
   REFERENCE,
   SDK,
+  UI_KIT,
 } from './lib/sdk.mjs';
 
 
@@ -39,6 +43,7 @@ export function registryLookup(root, name, version) {
       `${name}@${version}`,
       'version',
       'dependencies',
+      'peerDependencies',
       '--json',
     ]);
   } catch (error) {
@@ -100,21 +105,37 @@ export function planUpdate(
     throw new Error(
       `${SDK[0]}@${version} must depend on exactly ${SDK[1]}@${version}; found ${JSON.stringify(app.dependencies?.[SDK[1]])}`,
     );
+  // The UI kit is released with the SDK, at the same version.
+  const kit = lookup(UI_KIT, version);
+  if (kit?.version !== version)
+    throw new Error(
+      `${UI_KIT}@${version} is missing or returned an unexpected version; the UI kit is released with the SDK since 0.7.0`,
+    );
+  const peer = kit.peerDependencies?.[SDK[0]];
+  if (!peer || !semver.satisfies(version, peer, { includePrerelease: true }))
+    throw new Error(
+      `${UI_KIT}@${version} must support ${SDK[0]}@${version}; it asks for ${JSON.stringify(peer)}`,
+    );
 
+  // The root declares every SDK package and gains the UI kit when it lacks
+  // it; an app moves only what it declares.
   const entries = [
-    ['package.json', 'devDependencies'],
+    ['package.json', 'devDependencies', true],
     ...readApps(root).apps.map(({ id }) => [
       `apps/${id}/package.json`,
       'dependencies',
+      false,
     ]),
   ];
   const changes = [];
-  for (const [file, section] of entries) {
+  for (const [file, section, isRoot] of entries) {
     const path = join(root, file);
     const original = readFileSync(path, 'utf8');
     const manifest = JSON.parse(original);
-    for (const name of SDK) {
+    const names = isRoot ? SDK : appSdk(manifest[section]);
+    for (const name of names) {
       const current = manifest[section]?.[name];
+      if (name === UI_KIT && current === undefined) continue;
       if (!EXACT_VERSION.test(current ?? ''))
         throw new Error(
           `${file}: ${section}.${name} must already be an exact semver`,
@@ -124,8 +145,9 @@ export function planUpdate(
           `${file}: downgrade from ${current} to ${version} requires --allow-downgrade`,
         );
     }
-    if (SDK.every((name) => manifest[section][name] === version)) continue;
-    for (const name of SDK) manifest[section][name] = version;
+    if (names.every((name) => manifest[section]?.[name] === version)) continue;
+    for (const name of names) manifest[section][name] = version;
+    manifest[section] = sortedKeys(manifest[section]);
     changes.push({
       path,
       original,
@@ -136,7 +158,7 @@ export function planUpdate(
 }
 
 
-/** Whether node_modules has both SDK packages at `version` and the reference. */
+/** Whether node_modules has the SDK packages at `version` and the reference. */
 export function installedStateComplete(root, version) {
   try {
     return (
@@ -187,7 +209,7 @@ export function applyUpdate(
   run(INSTALL);
   if (!installed())
     throw new Error(
-      `node_modules does not have both SDK packages at ${plan.version} with ${REFERENCE}; fix the cause and run the same command again`,
+      `node_modules does not have ${SDK.join(', ')} at ${plan.version} with ${REFERENCE}; fix the cause and run the same command again`,
     );
   run(['run', 'check']);
   rmSync(pending);

package/shared/files/{e13474647ebaf26d042d76f4917203d209a2b14c0d2af8d12139ea328530823e → 3b75b42e15713ac93916d9c2978c2826dfedef18ed5255d444482484bc4b3334}

@@ -50,20 +50,23 @@ updates:
       - dependency-name: '@types/node'
         update-types:
           - 'version-update:semver-major'
-    # A dependency joins the first group it matches. Both SDK packages move
-    # together in one PR; the tooling has its own, since it brings a starter
-    # migration (update skill). Security updates move only affected packages:
-    # their SDK group joins advisories for both, and a PR that moves one is
-    # completed with sdk-update (Update the SDK in the app workflow).
+    # A dependency joins the first group it matches. The SDK packages and the
+    # UI kit move together in one PR; the tooling has its own, since it brings
+    # a starter migration (update skill). Security updates move only affected
+    # packages: their SDK group joins advisories for several, and a PR that
+    # moves only some is completed with sdk-update (Update the SDK in the app
+    # workflow).
     groups:
       sempods-sdk:
         patterns:
           - '@sempods/app-sdk'
+          - '@sempods/app-ui'
           - '@sempods/client-sdk'
       sempods-sdk-security:
         applies-to: 'security-updates'
         patterns:
           - '@sempods/app-sdk'
+          - '@sempods/app-ui'
           - '@sempods/client-sdk'
       sempods-apps:
         patterns:

package/shared/files/{843c078e84912158607ebb8ce0042589d676a742bcd3cf8b6c474d62ff3a6845 → 5f709dbc1d0ab5c918a1ff06c32342a3f95569b1570793bfd3a03642bb6a7e43}

@@ -14,13 +14,15 @@
     "configure-site": "sempods-apps configure-site",
     "build-site": "sempods-apps build-site",
     "check": "sempods-apps check",
+    "check:theme": "sempods-apps check-theme",
     "sdk-update": "sempods-apps sdk-update",
     "update": "sempods-apps update",
     "migrate": "sempods-apps migrate"
   },
   "devDependencies": {
-    "@sempods/app-sdk": "0.6.0",
+    "@sempods/app-sdk": "0.7.0-dev.2",
+    "@sempods/app-ui": "0.7.0-dev.2",
     "@sempods/apps": "0.0.0",
-    "@sempods/client-sdk": "0.6.0"
+    "@sempods/client-sdk": "0.7.0-dev.2"
   }
 }

package/shared/snapshot.json

@@ -1,13 +1,13 @@
 {
   "format": 1,
-  "revision": "b39743fd5d824bb8bd37eaa9298b23ffe281dfd41799d652b5295f96191fdc02",
+  "revision": "e49f59f05c9dbe752680cd6986a428b544398e8bef7fe3d555111f0054cb46a5",
   "files": {
     ".agents/skills/app-workflow/SKILL.md": "0221b70340152ba3cc615342254603b29b89c4d7d944d7b3b3e647873bdcefa0",
     ".agents/skills/update/SKILL.md": "d3ca3a13c6524a2ee9382977ddc0539790813225f366306024a58c957a4716ee",
     ".claude/skills/app-workflow/SKILL.md": "0221b70340152ba3cc615342254603b29b89c4d7d944d7b3b3e647873bdcefa0",
     ".claude/skills/update/SKILL.md": "d3ca3a13c6524a2ee9382977ddc0539790813225f366306024a58c957a4716ee",
     ".github/codeql/codeql-config.yml": "528d7544990228d6d66fa62423775338fe1716326fc68371fb2665aee86e39b0",
-    ".github/dependabot.yml": "e13474647ebaf26d042d76f4917203d209a2b14c0d2af8d12139ea328530823e",
+    ".github/dependabot.yml": "3b75b42e15713ac93916d9c2978c2826dfedef18ed5255d444482484bc4b3334",
     ".github/workflows/check.yml": "8b7567319e18694aeca8722107281a760e3100239c6d0f548acb71e1806fa172",
     ".github/workflows/codeql.yml": "7a7b7c820db3a2946fd2b3148972ada8073bcc5752f03793ea2069f5b7a3f260",
     ".gitignore": "c2a4b026a87f6c8e7473e7fc456c6020b63c7e675087f6b58013ed5163c2f6ee",
@@ -19,7 +19,7 @@
     "apps.json": "9945f9bd573e5af8aad2e65cc8b4284fbb1d7e8b96c4efdd42eeb49132fb4327",
     "apps/.gitkeep": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
     "docs/start.md": "e1c798ec8536cf8cff6c19caf622fa9076ae210b0d1733a6e82ea2c1f4104c43",
-    "package.json": "843c078e84912158607ebb8ce0042589d676a742bcd3cf8b6c474d62ff3a6845",
+    "package.json": "5f709dbc1d0ab5c918a1ff06c32342a3f95569b1570793bfd3a03642bb6a7e43",
     "pnpm-workspace.yaml": "4660ca1887261ae658c7f587190e2b71ac91d15b1b6c4cf04dec823fdd0da654"
   }
 }

package/skeleton/app/package.json

@@ -11,15 +11,18 @@
     "preview": "vite preview"
   },
   "dependencies": {
+    "lucide-react": "1.65.0",
     "react": "19.3.1",
     "react-dom": "19.3.1"
   },
   "devDependencies": {
+    "@tailwindcss/vite": "4.3.3",
     "@types/node": "24.19.2",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
     "@vitejs/plugin-react": "6.1.2",
     "oxlint": "1.89.0",
+    "tailwindcss": "4.3.3",
     "typescript": "7.0.2",
     "vite": "8.3.5",
     "vite-plugin-pwa": "2.0.0",

package/skeleton/app/src/App.tsx

@@ -1,4 +1,4 @@
-import { useRef, useState } from 'react';
+import { useState } from 'react';
 import { createBrowserRuntime } from '@sempods/app-sdk';
 import {
   AccessNotice,
@@ -9,16 +9,25 @@ import {
   useMessages,
   useSdkLocale,
 } from '@sempods/app-sdk/react';
+import {
+  ActionButton,
+  HeaderMenu,
+  ScreenDialog,
+  replaceUrl,
+  useNav,
+} from '@sempods/app-ui';
 import { NewVersionNotice } from './NewVersionNotice.tsx';
-import { replaceUrl } from './routes.ts';
+import { inApp, places } from './places.ts';
 import { app, runtimeOptions } from './sempods.generated.ts';
 import { texts, uiLocale } from './texts.ts';
-import { MenuIcon } from './ui/icons.tsx';
-import { Menu } from './ui/Menu.tsx';
 
 // One runtime for the app's lifetime, created outside rendering. Its return
-// after a sign-in goes through the router, which then shows that route.
-const runtime = createBrowserRuntime({ ...runtimeOptions, replaceUrl });
+// after a sign-in goes through the router, which then shows that address,
+// always one in the app.
+const runtime = createBrowserRuntime({
+  ...runtimeOptions,
+  replaceUrl: (url) => replaceUrl(inApp(url)),
+});
 
 // One UI language for the app's texts, the SDK components and the page.
 const { locale, language } = uiLocale(app.language, navigator.languages);
@@ -28,7 +37,7 @@ document.documentElement.lang = language;
 if (import.meta.hot) import.meta.hot.dispose(() => runtime.dispose());
 
 // The app icon (public/favicon.svg), decorative next to the app's name.
-const icon = <img src={`${app.basePath}favicon.svg`} alt="" />;
+const icon = <img src={`${app.basePath}favicon.svg`} alt="" className="size-7" />;
 
 export default function App({
   registration,
@@ -46,29 +55,34 @@ export default function App({
 // The app owns its layout: a header with the app's icon and name, its icon
 // actions and a menu; AppAccess beside the content for sign-in and recovery,
 // and as a dialog for managing Pods and sharing from the menu. An app that
-// switches between contexts (lists) puts ui/ContextSwitch in place of the
-// h1.
+// switches between contexts (lists) puts src/examples/ContextSwitch.tsx in
+// place of the h1.
 function Frame() {
+  // The shown place of the app's address model (places.ts). Call it once,
+  // here, and pass `nav` to the screens that link or switch.
+  const nav = useNav(places);
   const [managing, setManaging] = useState(false);
-  const menuButton = useRef<HTMLButtonElement>(null);
-  const { connections } = useAppState();
+  // `pod` is the active signed-in Pod; a saved connection that needs a new
+  // sign-in has none.
+  const { connections, pod } = useAppState();
   const { messages } = useSdkLocale();
   const t = useMessages(texts);
   const header = connections.length > 0;
+  const { place } = nav;
+  const toStart = () => nav.go({ kind: 'start' }, { replace: true });
   return (
-    <main>
+    <main className="mx-auto max-w-3xl p-4">
       {header && (
-        <header>
-          <h1>
+        <header className="flex flex-wrap items-center justify-between gap-2">
+          <h1 className="flex items-center gap-2 text-2xl font-semibold">
             {icon}
             {app.title}
           </h1>
-          <div className="header-actions">
-            {/* The app's own icon actions go here. */}
-            <Menu
+          <div className="flex items-center gap-2">
+            {/* The app's own icon actions go here, as
+                <ActionButton variant="ghost" shape="round-sm" label="…">. */}
+            <HeaderMenu
               label={t.menu}
-              trigger={<MenuIcon />}
-              button={menuButton}
               items={[
                 {
                   label: messages.controls.dataAccess,
@@ -88,12 +102,30 @@ function Frame() {
         headingLevel={header ? 2 : 1}
         open={managing}
         onClose={() => setManaging(false)}
-        focusTarget={menuButton}
       />
       <AccessNotice only="write" />
       <TargetScreen>
         <Start />
       </TargetScreen>
+      {/* An explicit page once the person is signed in; a modal before that
+          would cover the sign-in, and closing it would lose the link. */}
+      {place.kind === 'not-found' && pod && (
+        <ScreenDialog
+          title={t.notFound}
+          open
+          onRequestClose={toStart}
+        >
+          <div className="grid gap-4">
+            <p>{place.reason === 'invalid' ? t.invalidLink : t.notFoundText}</p>
+            <ActionButton
+              shape="pill"
+              onPress={toStart}
+            >
+              {t.toStart}
+            </ActionButton>
+          </div>
+        </ScreenDialog>
+      )}
     </main>
   );
 }
@@ -101,5 +133,5 @@ function Frame() {
 // Replace this screen with your app. It renders once a Pod context is chosen.
 function Start() {
   const t = useMessages(texts);
-  return <p>{t.start}</p>;
+  return <p className="mt-6">{t.start}</p>;
 }

package/skeleton/app/src/examples/ContextSwitch.tsx

@@ -0,0 +1,131 @@
+// An example, not mounted: the everyday switch for an app that works in one
+// of several contexts at a time (for example lists), built with the UI kit's
+// menu parts. Copy it next to App.tsx and render it in place of the header's
+// <h1>, with the app's icon and title.
+import type { ReactNode } from 'react';
+import { useContexts, useSdkLocale } from '@sempods/app-sdk/react';
+import {
+  Button,
+  DropdownMenu,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '@sempods/app-ui';
+import { ChevronDownIcon } from 'lucide-react';
+
+/**
+ * The app icon and the current context's name in place of the header's
+ * `<h1>`, opening a menu with the readable contexts, their access and a way
+ * to share more. The SDK's `useContexts` loads the contexts, selects a
+ * sensible one and switches under the leave policy; this component only shows
+ * them. Until a context is selected it shows the app's icon and `title` as the
+ * `<h1>`; then the `<h1>` names the app for screen readers only, outside the
+ * menu. Name things in the person's words: `label` "List", `shareMore`
+ * "Share more lists …".
+ */
+export function ContextSwitch({
+  icon,
+  title,
+  label,
+  texts,
+}: {
+  readonly icon: ReactNode;
+  /** The app's name. */
+  readonly title: string;
+  /** What a context is in this app, for example "List". */
+  readonly label: string;
+  readonly texts: { readonly shareMore: string };
+}) {
+  const {
+    contexts,
+    selected,
+    select,
+    failed,
+    retry,
+    canShare,
+    share,
+    shareProblem,
+  } = useContexts();
+  const { messages } = useSdkLocale();
+  if (!selected)
+    return (
+      <h1 className="flex items-center gap-2 text-2xl font-semibold">
+        {icon}
+        {title}
+      </h1>
+    );
+  return (
+    <div className="grid min-w-0 gap-1">
+      <h1 className="sr-only">{title}</h1>
+      <DropdownMenuTrigger>
+        <Button
+          variant="ghost"
+          className="h-11 max-w-full justify-start gap-2 px-2 text-xl font-semibold"
+          aria-label={`${label}: ${selected.name}`}
+        >
+          {icon}
+          <span className="truncate">{selected.name}</span>
+          <ChevronDownIcon />
+        </Button>
+        <DropdownMenu placement="bottom start" className="min-w-56">
+          {/* The contexts as checked choices; the actions below are not. */}
+          <DropdownMenuGroup
+            aria-label={label}
+            selectionMode="single"
+            selectedKeys={[selected.iri]}
+          >
+            {contexts.map((context) => (
+              <DropdownMenuItem
+                key={context.iri}
+                id={context.iri}
+                className="min-h-11"
+                textValue={context.name}
+                onAction={() => {
+                  if (context.iri !== selected.iri) void select(context.iri);
+                }}
+              >
+                <span className="grid">
+                  {context.name}
+                  {/* The SDK's own words, as in its management dialog. */}
+                  <span className="text-sm text-muted-foreground">
+                    {context.writable
+                      ? messages.controls.canChange
+                      : messages.controls.canRead}
+                  </span>
+                </span>
+              </DropdownMenuItem>
+            ))}
+          </DropdownMenuGroup>
+          {(failed || canShare) && <DropdownMenuSeparator />}
+          {/* A failed reload keeps the known contexts and offers to try
+              again. */}
+          {failed && (
+            <DropdownMenuItem
+              id="retry"
+              className="min-h-11"
+              onAction={() => void retry()}
+            >
+              {messages.controls.retry}
+            </DropdownMenuItem>
+          )}
+          {canShare && (
+            <DropdownMenuItem
+              id="share"
+              className="min-h-11"
+              onAction={() => void share()}
+            >
+              {texts.shareMore}
+            </DropdownMenuItem>
+          )}
+        </DropdownMenu>
+      </DropdownMenuTrigger>
+      {/* A failed request to share says why below the switch. */}
+      {shareProblem && (
+        <p role="alert" className="text-sm text-destructive">
+          {shareProblem}
+        </p>
+      )}
+    </div>
+  );
+}