@sempods/apps 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,206 @@ Each release lists what changed and **upgrade notes** for the assistant that
 applies it. The notes cover what an update cannot decide alone: owner files,
 configuration choices and the SDK migration.
 
+## 0.8.0
+
+### Changes
+
+SDK:
+
+- New repositories use SDK 0.6.0 (`@sempods/app-sdk` and
+  `@sempods/client-sdk`), and `@sempods/apps` supports `^0.6.0`. The 0.6.0
+  release notes and migration guide name what changes for apps: among others,
+  `AppShell` and `ConnectionControls` are gone, row commands move to
+  `mutate.for(item)`, SDK texts follow the browser language, lists keep their
+  rows while reloading, a cancelled re-authorization keeps the session, and
+  the leave confirmation shows above app dialogs.
+- After an SDK update, `sdk-update` and the app workflow point to the
+  installed release notes and migration guide
+  (`node_modules/@sempods/app-sdk/docs/releases/<version>.md`, `migration.md`)
+  instead of GitHub, and the workflow skips a section on adopting the release
+  in the apps template.
+
+Look:
+
+- Four themes in the skeleton's `src/themes/`: calm (the default, graphite on
+  white), fresh (teal), warm (terracotta on cream) and playful (violet). Each
+  sets the six `--sempods-*` colour tokens in light and dark mode with at
+  least 4.5:1 contrast, which a test checks; the SDK components read the same
+  tokens, so a theme restyles the whole app. Fonts and corner radii stay the
+  SDK's. An app imports one theme in `src/main.tsx`; `new-app --theme <name>`
+  chooses it.
+- The skeleton's `src/index.css` styles only the app's own markup and leaves
+  SDK components (`[data-sempods-ui]`) alone, so `AppAccess` keeps its
+  layout. App buttons read as text in the accent colour with a calm hover, a
+  visible focus and 44px touch targets. Inputs have 44px targets; checkboxes
+  and radios are a compact 24px box whose wrapping `<label>` is the 44px
+  target, as in the SDK. Lists lose the browser's indentation and bullets.
+- The page's `theme-color` follows light and dark mode, and the generated web
+  app manifest uses a white background and theme colour instead of green.
+- `new-app` draws the app icon as a monogram, the title's first letter on a
+  rounded square in the theme's accent, instead of a plain green square:
+  `public/favicon.svg` (in the theme's dark accent in dark mode) and the
+  manifest icons `icon-192.png` and `icon-512.png`, all from the same strokes.
+  A title that does not start with a letter A–Z, accents aside, gets the plain
+  square. `pnpm run icon <id>` (new) draws it again after a rename or a theme
+  change.
+- The skeleton's header shows the app's icon and name, room for the app's
+  icon actions and a menu (⋮) whose "Pods & sharing" opens `AppAccess`
+  management as its dialog (`onClose`), with signing out inside. It replaces
+  the "Data access" button. `AppAccess` shows the icon and the app's
+  description on the sign-in screen, `<AccessNotice only="write" />` beside it
+  says when a context is shared read-only, and the viewport adds
+  `viewport-fit=cover` and `interactive-widget=resizes-content`.
+- The skeleton has a small UI kit in `src/ui/`, styled by `ui.css` on the
+  `--sempods-*` tokens: `Menu` (a button with a list of actions or choices;
+  Escape, a press outside and the arrow keys), `ContextSwitch` (the everyday
+  switch between the contexts shared with the app over the SDK's
+  `useContexts`, in place of the header's `<h1>`), `Tabs` (views as links with
+  their routes), `Composer` (an input bar fixed at the bottom, above the home
+  indicator and, where browsers support it, the on-screen keyboard), `Dialog`
+  (modal, a bottom sheet on phones, for example around a `ResourceEditor`)
+  and line icons.
+- The skeleton ships `src/examples/ListScreen.tsx`, not mounted: the SDK's
+  quickstart screen built with the kit (loading and failed reads, an empty
+  state, rows with a labelled checkbox, the item's `ResourceEditor` in a
+  `Dialog`, `RemoveButton`, open outcomes and a `Composer`, which a list the
+  person can only read does not show). It compiles with every app, so it
+  stays valid against the SDK.
+
+Content and configuration:
+
+- Apps are international by default. `language` in `apps.json` accepts
+  `"auto"`, and `new-app` uses it unless `--language de` or `en` fixes one
+  language. The skeleton resolves the UI language and locale from the browser
+  with the SDK's `resolveLocale` (German or English, otherwise English, with
+  the browser's region for formats), passes both to `SempodsProvider` and
+  sets `<html lang>`. For `"auto"` the generated configuration keeps
+  `app.language` as `"auto"`, the manifest has no `lang` and the overview
+  announces no language for the app.
+- The skeleton keeps the app's own texts in `src/texts.ts`, one typed
+  catalogue per language, read with the SDK's `useMessages(texts)` and tested
+  in `src/texts.test.ts`; `src/start.ts` and its test are gone.
+- The app title has one source, `apps.json`. The generated
+  `vite.sempods.generated.ts` exports the Vite plugin `pageTitle`, which adds
+  the title to the head of the served and built page; the skeleton's
+  `vite.config.ts` uses it and its `index.html` has no `<title>` of its own.
+  `check` reports a page with its own title and a `vite.config.ts` without
+  the plugin.
+- `apps.json` accepts an optional `description` (one short sentence), set by
+  `new-app --description`. It becomes the generated `app.description`, which
+  the skeleton passes to `AppAccess`, the manifest's `description` and the
+  overview card's line.
+- Apps can give their views addresses: `routes` in an app's `apps.json` entry
+  lists lowercase English segments, for example `"routes": ["bought"]` for
+  `/<id>/bought`. The generated `app.routes` lists them, and `build-site`
+  writes `<id>/<route>.html`, so the published site answers each route
+  without a rewrite and unknown paths still show the not-found page. The
+  service worker serves the cached app for the start page and every route,
+  and the generated `returnTo` is a function the runtime calls when each
+  sign-in starts, so sign-in returns to the route the person is on.
+- The skeleton's `src/routes.ts` provides `useRoute()`: the current route,
+  `link(route)` for an `<a>` to it and `go(route)`, which switches views under
+  the SDK's leave policy (`useApp().navigate`); back and forward are guarded
+  the same way, and staying keeps the view and its address. It shows unknown
+  paths as the start page and drops a trailing slash. The runtime's
+  `replaceUrl` goes through it, so the return after a sign-in shows the right
+  view.
+- `migrate` moves existing apps where that is unambiguous: a `vite.config.ts`
+  unchanged from the skeleton gets the `pageTitle` plugin, and a page whose
+  only title is the app's title from `apps.json` loses it. It does so, and
+  regenerates the apps, also for a release whose starter is unchanged. A page
+  or `vite.config.ts` that is a symbolic link stops `update` and `migrate`
+  before they change anything.
+
+Instructions:
+
+- App planning settles purpose, personal versus shared data and context
+  access limits before generation, with at most three short questions at a
+  time. The assistant proposes layout, theme, name and icon; a vague request
+  need not wait for visual choices. Decisions go into the app's `NOTES.md`.
+- The workflow chooses reusable data mappings from existing data and
+  established vocabularies, preserving identities and fields other apps use.
+  If the owner wants, optional read-only inspection through a connected MCP
+  Pod informs this choice within an agreed scope. Setup and the user guide
+  explain that MCP is optional and separate from signing in to the app;
+  app trials still use synthetic data in dedicated test contexts.
+- Before generation, the workflow settles what the app reads, where new
+  records go and where existing records are edited: one context, several one
+  at a time, read all and write in one, edit overview rows in their source
+  contexts, or write into several. It starts from the installed SDK's path
+  for that shape. The skeleton's notes record Data and Vocabulary decisions,
+  including observed mappings and assumptions still to verify. Setup asks
+  for one test context per context the shape uses.
+- The app workflow starts a list from the list example, takes only behaviour
+  from the SDK's examples, deletes rows with `RemoveButton`, relies on the
+  SDK's list refresh when the page becomes visible again, adds kit parts only
+  when the app needs them, and describes routes, renaming and themes. It is
+  reordered: planning, optional data inspection, context shape, vocabulary,
+  `new-app`, screen, views, configuration.
+- A visual check before handover (`instructions/visual-check.md`): the
+  assistant takes screenshots at 375px and desktop width, light and dark, with
+  real states (empty, a few items, an open item, a notice), checks them
+  against a short checklist, fixes what fails and shows the owner the 375px
+  screenshot for a verdict. The app workflow and setup require it; visual
+  checks are their own kind of evidence in `NOTES.md`. The docs no longer say
+  the screen can be tried without a Pod: only the sign-in screen can.
+- The setup record of new repositories names "Test Pod and contexts" and the
+  owner's language for the app texts.
+
+### Upgrade notes
+
+1. The migration does by itself: it adds the root script `icon`, regenerates
+   every app (`app.routes`, `app.description` as `null` until set, the
+   manifest colours, the `pageTitle` plugin, the service worker's allowlist
+   for routes), moves apps to the generated page title where that is
+   unambiguous and replaces the viewport and green `theme-color` lines an
+   app's `index.html` kept from the 0.7 skeleton, listed under "Updated". For
+   any other app, `check` names what is left: add `pageTitle` from
+   `./vite.sempods.generated.ts` to the plugins in its `vite.config.ts`, as
+   the skeleton does, and remove the `<title>` from its `index.html`. A page title other than the one in `apps.json` was
+   chosen by hand: ask the owner whether it should be the app's title, put it
+   into `apps.json` and run `pnpm run regenerate`. Settle these cases before
+   the SDK move: `sdk-update` ends with `check` and stops on them.
+2. Then move the repository to SDK 0.6.0, on its own branch:
+   `pnpm run sdk-update 0.6.0`. Until then `check` reports the SDK as outside
+   the supported range, and apps created by `new-app` would use the old SDK
+   with a skeleton written for 0.6.0. Then follow the SDK's migration
+   checklist (`node_modules/@sempods/app-sdk/docs/migration.md`, "From 0.5.0
+   to 0.6.0") for each app: replace `AppShell`/`ConnectionControls` with the
+   skeleton's layout, move row commands to `mutate.for(item)`, handle
+   `not-sent` results, and check texts and dialogs that tests match. Run
+   `pnpm run check --standalone all` and list for the owner what to try on the
+   Pod: sign-in, reload, editing, guarded navigation and recovery.
+3. Existing apps keep their code, look and notes. When working on an app next,
+   offer what the owner wants of the new skeleton, from
+   `node_modules/@sempods/apps/skeleton/app/`, once the repository is on SDK
+   0.6.0:
+   - a theme: copy `src/themes/`, import the chosen one in `src/main.tsx`
+     before `index.css`, remove the token block from `index.css`, and run
+     `pnpm run icon <id>` for a monogram in its accent;
+   - the scoped CSS rules of `src/index.css`, where the app still has global
+     `header`, `button`, `input` or `select` rules: they stop shifting the
+     sign-in form and placing the `AppAccess` icon beside its title;
+   - the header with icon, name and menu, `src/ui/` and `AppAccess` with
+     `icon`, `description` and `onClose`, with their texts in `src/texts.ts`;
+   - routes, for an app that switches views by itself: copy `src/routes.ts`
+     and `src/routes.test.ts`, pass `replaceUrl` to `createBrowserRuntime` as
+     `src/App.tsx` does, list the routes in `apps.json` and run
+     `pnpm run regenerate`; an app that rewrote its address after a sign-in
+     can drop that code;
+   - the browser's language: set `language` to `"auto"` in `apps.json`, run
+     `pnpm run regenerate` and adopt `uiLocale` from `src/texts.ts` in
+     `src/App.tsx` (passed as `language` and `locale`, and
+     `document.documentElement.lang`), because `app.language` is then
+     `"auto"`; read the app's texts from a catalogue with both languages
+     through `useMessages`;
+   - Design, Data and Vocabulary sections in `NOTES.md`, following the app
+     workflow. Check personal/shared access assumptions, reuse of existing
+     data and the separate destinations of new records and edits. Offer MCP
+     inspection only when existing data is relevant and the owner wants it;
+     record unverified assumptions when it is skipped. These instructions
+     do not migrate existing Pod data.
+
 ## 0.7.1
 
 ### Changes

package/README.md

@@ -12,6 +12,8 @@ Create a repository with `pnpm create @sempods/apps <directory>`
 `package.json` runs the other commands through `sempods-apps <command>`:
 
 - `pnpm run new-app <id>` creates `apps/<id>` with the root's SDK version.
+- `pnpm run icon <id>` draws an app's monogram icon again in its theme's
+  accent.
 - `pnpm run dev <id>` starts that app.
 - `pnpm run regenerate` rewrites every app's generated configuration from
   `apps.json`, for example after a tooling update.
@@ -32,9 +34,10 @@ Create a repository with `pnpm create @sempods/apps <directory>`
 
 Contents:
 
-- `instructions/`: the setup procedure, the app workflow and the publish
-  guide; `skills/` holds the skill entries that route to them.
-- `skeleton/app/`: what a new app starts from. Files named `*.generated.ts` in
+- `instructions/`: the setup procedure, the app workflow, the visual check and
+  the publish guide; `skills/` holds the skill entries that route to them.
+- `skeleton/app/`: what a new app starts from, with its themes, UI kit and
+  list example. Files named `*.generated.ts` in
   an app are written from `apps.json`; do not edit them. `check` reports any
   difference, and `regenerate` rewrites them.
 - `shared/`: the starter of this release, its files stored by content hash in

package/bin/sempods-apps.mjs

@@ -7,6 +7,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 const COMMANDS = {
   create: 'create a new apps repository from the starter',
   'new-app': 'create apps/<id> and add it to apps.json',
+  icon: "draw an app's monogram icon again in its theme's accent",
   dev: 'start the development server of one app',
   regenerate: "rewrite every app's generated configuration from apps.json",
   'configure-site': 'record where the apps are published',