@sempods/apps 0.7.1 → 0.8.0-dev.1

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

@@ -0,0 +1,167 @@
+// An example, not mounted: the default screen of a list app, built from the
+// SDK's quickstart screen with the kit. For a list app, copy it next to
+// App.tsx, render <ListScreen /> in place of <Start />, and rename the type,
+// fields, collection and texts to the app's own. Keep App.tsx's runtime,
+// provider and frame; take behaviour from the SDK's examples, never their
+// runtime, provider or styles.
+import {
+  LoadNotice,
+  RemoveButton,
+  ResourceEditor,
+  UnresolvedNotices,
+  UpdateNotice,
+  useCreation,
+  useFieldUpdate,
+  useList,
+  useMessages,
+  useResourceEditor,
+  useSelection,
+} from '@sempods/app-sdk/react';
+import { fields, flag, text } from '@sempods/client-sdk/edit';
+import { Composer } from '../ui/Composer.tsx';
+import { Dialog } from '../ui/Dialog.tsx';
+import { AddIcon } from '../ui/icons.tsx';
+
+const schema = 'https://schema.org/';
+
+/** What one row is: a name and whether it is done. */
+export const item = fields(
+  {
+    name: text(`${schema}name`, { language: null, trim: true }),
+    done: flag(`${schema}actionStatus`, {
+      on: `${schema}CompletedActionStatus`,
+      off: `${schema}PotentialActionStatus`,
+    }),
+  },
+  { type: `${schema}Action` },
+);
+
+// In an app these belong in src/texts.ts.
+const en = {
+  empty: 'Nothing here yet. Add the first item below.',
+  done: (name: string) => `Done: ${name}`,
+  remove: (name: string) => `Delete: ${name}`,
+  edit: 'Edit item',
+  close: 'Close',
+  name: 'Name',
+  newItem: 'New item',
+  add: 'Add',
+};
+const listTexts: { readonly en: typeof en; readonly de: typeof en } = {
+  en,
+  de: {
+    empty: 'Noch nichts hier. Füge unten den ersten Eintrag hinzu.',
+    done: (name) => `Erledigt: ${name}`,
+    remove: (name) => `Löschen: ${name}`,
+    edit: 'Eintrag bearbeiten',
+    close: 'Schließen',
+    name: 'Name',
+    newItem: 'Neuer Eintrag',
+    add: 'Hinzufügen',
+  },
+};
+
+export function ListScreen() {
+  const t = useMessages(listTexts);
+  const list = useList(item);
+  const items = list.data?.items;
+  // One hook for the list; each row gets its part with `mutate.for(row)`.
+  const mutate = useFieldUpdate(item);
+  const { selected, select } = useSelection();
+  const editor = useResourceEditor(selected, item);
+  const creation = useCreation(item, {
+    initial: { name: '', done: false },
+    collection: 'items',
+  });
+
+  return (
+    <>
+      {/* Loading, a failed read with "Try again", never a failure as empty. */}
+      <LoadNotice {...list} />
+      {(list.state.kind === 'ready' || list.state.kind === 'loading') &&
+        items?.length === 0 &&
+        list.data?.skipped === 0 && <p className="empty">{t.empty}</p>}
+      <ul className="rows">
+        {items?.map((entry) => {
+          const row = mutate.for(entry);
+          return (
+            <li key={entry.iri} className="row">
+              {/* The label is the checkbox's 44px touch target. */}
+              <label>
+                <input
+                  type="checkbox"
+                  checked={row.data.done}
+                  disabled={!row.canMutate}
+                  onChange={() => void row.update({ done: !row.data.done })}
+                />
+                <span className="visually-hidden">{t.done(row.data.name)}</span>
+              </label>
+              <button
+                className="row-name"
+                onClick={() => void select(entry.iri)}
+              >
+                {row.data.name}
+              </button>
+              {/* Asks in the SDK's dialog before it deletes. */}
+              <RemoveButton
+                disabled={!row.canMutate}
+                onRemove={row.remove}
+                label={t.remove(row.data.name)}
+              />
+              {/* The changed row is the confirmation; problems show here. */}
+              <UpdateNotice {...row.notice} quiet />
+            </li>
+          );
+        })}
+      </ul>
+      {/* Recovery for a row with an open write that is no longer listed. */}
+      <UnresolvedNotices of={mutate} shown={items} />
+      {/* Outside the rows, so the draft stays reachable if its row goes.
+          The SDK's Escape in a field cancels like Cancel and discards the
+          draft; × and a click beside the dialog ask first. */}
+      {selected && (
+        <Dialog
+          label={t.edit}
+          closeLabel={t.close}
+          onClose={() => void select(null)}
+        >
+          <ResourceEditor editor={editor} onClose={() => select(null)}>
+            {(draft, change) => (
+              <label>
+                {t.name}
+                <input
+                  value={draft.name}
+                  onChange={(event) => change({ name: event.target.value })}
+                />
+              </label>
+            )}
+          </ResourceEditor>
+        </Dialog>
+      )}
+      <UpdateNotice {...creation.notice} quiet />
+      <Composer>
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            void creation.create();
+          }}
+        >
+          <input
+            aria-label={t.newItem}
+            placeholder={t.newItem}
+            value={creation.draft.name}
+            disabled={!creation.canEdit}
+            onChange={(event) => creation.change({ name: event.target.value })}
+          />
+          <button
+            aria-label={t.add}
+            title={t.add}
+            disabled={!creation.canCreate}
+          >
+            <AddIcon />
+          </button>
+        </form>
+      </Composer>
+    </>
+  );
+}

package/skeleton/app/src/index.css

@@ -1,10 +1,11 @@
 :root {
-  /* Follow the system's light or dark mode; the SDK components follow the page.
-     The colours match the SDK defaults, so AppAccess sits seamlessly on the page. */
+  /* Follow the system's light or dark mode. The colours are the --sempods-*
+     tokens of the app's theme (src/themes/, imported in main.tsx), which
+     colour the app and the SDK components alike. */
   color-scheme: light dark;
   font-family: system-ui, sans-serif;
-  color: light-dark(#202923, #e8eee9);
-  background: light-dark(#fff, #191b1a);
+  color: var(--sempods-text);
+  background: var(--sempods-bg);
 }
 body {
   margin: 0;
@@ -14,24 +15,96 @@ main {
   margin: auto;
   padding: 16px;
 }
-header {
+/* The app's own header; AppAccess brings its own. */
+main > header {
   display: flex;
   flex-wrap: wrap;
   align-items: center;
   justify-content: space-between;
   gap: 0.5rem;
 }
-header h1 {
+main > header h1 {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
   margin: 0;
   font-size: 1.4rem;
 }
-button,
-input,
-select {
+main > header h1 img {
+  width: 28px;
+  height: 28px;
+}
+
+/* The rules below style the app's own markup only. SDK components
+   ([data-sempods-ui]) bring their own styles and are left alone. :where()
+   keeps these rules at zero specificity, so any class overrides them. */
+
+/* Actions read as text, like the SDK's secondary actions: accent colour, no
+   frame, a calm hover and a visible focus, with 44px touch targets. */
+:where(button):not(:where([data-sempods-ui] *, [data-sempods-button])) {
+  min-width: 44px;
+  min-height: 44px;
+  padding: 10px 12px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--sempods-accent);
   font: inherit;
-  margin: 0.25rem;
-  padding: 0.4rem;
+  font-weight: 500;
+  cursor: pointer;
+}
+:where(button):not(:where([data-sempods-ui] *, [data-sempods-button])):where(
+    :hover:not(:disabled)
+  ) {
+  background: color-mix(in srgb, var(--sempods-accent) 8%, transparent);
+}
+:where(button):not(:where([data-sempods-ui] *, [data-sempods-button])):where(
+    :disabled
+  ) {
+  color: var(--sempods-muted);
+  cursor: default;
+}
+:where(input, select, textarea):not(
+    :where([data-sempods-ui] *, [type='checkbox'], [type='radio'])
+  ) {
+  box-sizing: border-box;
+  min-height: 44px;
+  padding: 8px 10px;
+  border: 1px solid var(--sempods-line);
+  border-radius: 6px;
+  background: var(--sempods-bg);
+  color: var(--sempods-text);
+  font: inherit;
+}
+/* A compact box; its wrapping <label> is the 44px touch target, as in the
+   SDK. Margins are not clickable, so wrap every checkbox in its label. */
+:where(input[type='checkbox'], input[type='radio']):not(
+    :where([data-sempods-ui] *)
+  ) {
+  flex: none;
+  width: 24px;
+  height: 24px;
+  margin: 0;
+  margin-inline-end: 10px;
+  accent-color: var(--sempods-accent);
+}
+:where(label:has(input[type='checkbox'], input[type='radio'])):not(
+    :where([data-sempods-ui] *)
+  ) {
+  display: inline-flex;
+  align-items: center;
+  min-width: 44px;
+  min-height: 44px;
+  cursor: pointer;
+}
+:where(button, input, select, textarea, a):not(
+    :where([data-sempods-ui] *, [data-sempods-button])
+  ):where(:focus-visible) {
+  outline: 2px solid var(--sempods-accent);
+  outline-offset: 2px;
 }
-input[type='checkbox'] {
-  accent-color: light-dark(#226044, #8acda6);
+/* Lists of items, without the browser's indentation and bullets. */
+:where(ul):not(:where([data-sempods-ui] *)) {
+  padding-inline-start: 0;
+  list-style: none;
 }

package/skeleton/app/src/main.tsx

@@ -1,6 +1,9 @@
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
+// The app's theme: one of src/themes/; switch by changing this line.
+import './themes/__APP_THEME__.css';
 import './index.css';
+import './ui/ui.css';
 import App from './App.tsx';
 import { registerAppWorker } from './pwa.ts';
 import { app } from './sempods.generated.ts';

package/skeleton/app/src/pwa.ts

@@ -1,4 +1,4 @@
-// Adapted from the sempods TypeScript SDK v0.2.0 recipe
+// Adapted from the sempods TypeScript SDK v0.6.0 recipe
 // examples/todo/pwa/register.tsx, licensed under Apache-2.0; see
 // the LICENSE and NOTICE of the @sempods/app-sdk package. Changes: this header; the notice
 // component moved to NewVersionNotice.tsx.

package/skeleton/app/src/routes.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { pathOf, routeOf } from './routes.ts';
+
+describe('routes', () => {
+  const routes = ['open', 'bought'] as const;
+
+  it('reads the route of an address under the app path', () => {
+    expect(routeOf('/konsum/bought', routes, '/konsum/')).toBe('bought');
+    expect(routeOf('/konsum/bought/', routes, '/konsum/')).toBe('bought');
+    expect(routeOf('/konsum/', routes, '/konsum/')).toBeUndefined();
+    expect(routeOf('/konsum/other', routes, '/konsum/')).toBeUndefined();
+    expect(routeOf('/notes/bought', routes, '/konsum/')).toBeUndefined();
+  });
+
+  it('writes the address of a route', () => {
+    expect(pathOf('bought', '/konsum/')).toBe('/konsum/bought');
+    expect(pathOf(undefined, '/konsum/')).toBe('/konsum/');
+  });
+});

package/skeleton/app/src/routes.ts

@@ -0,0 +1,139 @@
+import {
+  useCallback,
+  useEffect,
+  useSyncExternalStore,
+  type MouseEvent,
+} from 'react';
+import { useApp } from '@sempods/app-sdk/react';
+import { app } from './sempods.generated.ts';
+
+// The app's views as addresses: the start page at the app's path and one
+// route per entry in apps.json `routes` (for example /<id>/bought). Links,
+// bookmarks and the back button work, and the published site answers every
+// route without rewrites.
+
+/** A route listed in apps.json; undefined is the start page. */
+export type Route = (typeof app.routes)[number];
+
+/** The route of an address; undefined for the start page and unknown paths. */
+export function routeOf<R extends string>(
+  path: string,
+  routes: readonly R[],
+  base: string,
+): R | undefined {
+  if (!path.startsWith(base)) return undefined;
+  const segment = path.slice(base.length).replace(/\/$/, '');
+  return routes.find((route) => route === segment);
+}
+
+/** The address of a route; the start page is the app's path. */
+export function pathOf(route: string | undefined, base: string): string {
+  return route === undefined ? base : `${base}${route}`;
+}
+
+// The address the app shows. It changes only through the functions below, so
+// a declined navigation keeps the current view.
+let shown = typeof location === 'object' ? location.pathname : '';
+// The position of the shown entry in the session history, kept in its state,
+// so a declined back or forward can return to it without a new entry.
+let position: number =
+  typeof history === 'object' ? (history.state?.position ?? 0) : 0;
+// Set while the router itself undoes a step, whose popstate it ignores.
+let undoing = false;
+const listeners = new Set<() => void>();
+function show(path: string) {
+  shown = path;
+  for (const listener of listeners) listener();
+}
+function subscribe(listener: () => void) {
+  listeners.add(listener);
+  return () => void listeners.delete(listener);
+}
+
+/**
+ * Replaces the address without a new history entry. Pass it to the runtime
+ * (`replaceUrl`), so the return to the original route after a sign-in shows
+ * that route.
+ */
+export function replaceUrl(url: string) {
+  history.replaceState({ position }, '', url);
+  show(location.pathname);
+}
+
+/**
+ * The current route, `go` to switch it and `link(route)`, the props of an
+ * `<a>` that switches to it. Switching, back and forward run
+ * under the SDK's leave policy: an unsaved edit asks first, and staying keeps
+ * the view, its address and the history. An unsent creation draft is not
+ * asked about; keep such input (a Composer) outside the switched views. Call it once, in the app's frame, and pass the
+ * route down.
+ */
+export function useRoute() {
+  const path = useSyncExternalStore(subscribe, () => shown);
+  const route: Route | undefined = routeOf(path, app.routes, app.basePath);
+  const { navigate } = useApp();
+
+  useEffect(() => {
+    const onPop = () => {
+      if (undoing) {
+        undoing = false;
+        return;
+      }
+      const to = location.pathname;
+      const target: number = history.state?.position ?? 0;
+      void navigate(() => {
+        position = target;
+        show(to);
+      }).then((left) => {
+        // Staying: step back to the shown entry; the history stays intact.
+        if (left || target === position) return;
+        undoing = true;
+        history.go(position - target);
+      });
+    };
+    addEventListener('popstate', onPop);
+    return () => removeEventListener('popstate', onPop);
+  }, [navigate]);
+
+  // One address per view: unknown paths show the start page, and a trailing
+  // slash goes. The callback keeps its address until the runtime has read it.
+  useEffect(() => {
+    const normal = pathOf(route, app.basePath);
+    if (path !== normal && path !== `${app.basePath}callback`)
+      replaceUrl(normal + location.search + location.hash);
+  }, [path, route]);
+
+  const go = useCallback(
+    (next: Route | undefined) => {
+      if (next === route) return;
+      void navigate(() => {
+        position += 1;
+        history.pushState({ position }, '', pathOf(next, app.basePath));
+        show(location.pathname);
+      });
+    },
+    [navigate, route],
+  );
+  // Props for a link to a route: its own address, so it opens in a new tab or
+  // gets bookmarked, while a plain click switches in place through `go`
+  // instead of loading the page past the leave policy.
+  const link = useCallback(
+    (next: Route | undefined) => ({
+      href: pathOf(next, app.basePath),
+      onClick: (event: MouseEvent) => {
+        if (
+          event.button !== 0 ||
+          event.metaKey ||
+          event.ctrlKey ||
+          event.shiftKey ||
+          event.altKey
+        )
+          return;
+        event.preventDefault();
+        go(next);
+      },
+    }),
+    [go],
+  );
+  return { route, go, link };
+}

package/skeleton/app/src/texts.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { app } from './sempods.generated.ts';
+import { texts, uiLocale } from './texts.ts';
+
+describe('texts', () => {
+  it('has every text in every language', () => {
+    const keys = Object.keys(texts.en);
+    for (const catalogue of [texts.en, texts.de]) {
+      expect(Object.keys(catalogue)).toEqual(keys);
+      for (const text of Object.values(catalogue)) expect(text).not.toBe('');
+    }
+  });
+
+  it('takes the language from the browser unless one is configured', () => {
+    expect(uiLocale('auto', ['de-AT', 'en'])).toEqual({
+      locale: 'de-AT',
+      language: 'de',
+    });
+    // An unsupported language keeps its regional formats with English texts.
+    expect(uiLocale('auto', ['fr-FR'])).toEqual({
+      locale: 'fr-FR',
+      language: 'en',
+    });
+    expect(uiLocale('de', ['en-US']).language).toBe('de');
+    // The generated configuration imports without a browser.
+    expect(['en', 'de']).toContain(uiLocale(app.language, []).language);
+  });
+});

package/skeleton/app/src/texts.ts

@@ -0,0 +1,35 @@
+import { resolveLocale, type Language } from '@sempods/app-sdk';
+
+/**
+ * The UI language and the regional formats. With "auto" in apps.json they
+ * come from the browser: German or English, otherwise English, with the
+ * browser's region for dates and numbers. A fixed language keeps its own.
+ */
+export function uiLocale(
+  configured: string,
+  browser: readonly string[],
+): { readonly locale: string; readonly language: Language } {
+  return resolveLocale(configured === 'auto' ? undefined : configured, browser);
+}
+
+// The app's own texts in English and German, read in components with the
+// SDK's useMessages(texts); SDK components bring their own, and SDK texts are
+// reused where they fit (useSdkLocale().messages.controls). Both languages
+// have every key, so TypeScript reports a missing translation. Add the app's
+// texts here, never inline in components.
+const en = {
+  start: 'Connected. Tell your assistant what this app should do.',
+  newVersion:
+    'A new version is ready. It is used once every window of this app has been closed.',
+  menu: 'Menu',
+};
+
+export const texts: { readonly en: typeof en; readonly de: typeof en } = {
+  en,
+  de: {
+    start: 'Verbunden. Beschreibe deinem Assistenten, was diese App tun soll.',
+    newVersion:
+      'Eine neue Version ist bereit. Sie wird verwendet, sobald alle Fenster dieser App geschlossen sind.',
+    menu: 'Menü',
+  },
+};

package/skeleton/app/src/themes/calm.css

@@ -0,0 +1,11 @@
+/* Calm: graphite on white, quiet and neutral; the default.
+   The --sempods-* tokens colour the app and the SDK components alike, in
+   light and dark mode; each pair keeps at least 4.5:1 contrast. */
+:root {
+  --sempods-bg: light-dark(#ffffff, #111315);
+  --sempods-text: light-dark(#1f2933, #e5e7eb);
+  --sempods-muted: light-dark(#6b7280, #9ca3af);
+  --sempods-line: light-dark(#e5e7eb, #2d3138);
+  --sempods-accent: light-dark(#1f2933, #e5e7eb);
+  --sempods-on-accent: light-dark(#ffffff, #111315);
+}

package/skeleton/app/src/themes/fresh.css

@@ -0,0 +1,11 @@
+/* Fresh: clear teal and cool greys, light and open.
+   The --sempods-* tokens colour the app and the SDK components alike, in
+   light and dark mode; each pair keeps at least 4.5:1 contrast. */
+:root {
+  --sempods-bg: light-dark(#ffffff, #0e171d);
+  --sempods-text: light-dark(#11293a, #e1edf3);
+  --sempods-muted: light-dark(#58697a, #94a8b6);
+  --sempods-line: light-dark(#dce8ef, #22343f);
+  --sempods-accent: light-dark(#0a6680, #5ec6e4);
+  --sempods-on-accent: light-dark(#ffffff, #06212b);
+}

package/skeleton/app/src/themes/playful.css

@@ -0,0 +1,11 @@
+/* Playful: violet and soft lilac, lively and friendly.
+   The --sempods-* tokens colour the app and the SDK components alike, in
+   light and dark mode; each pair keeps at least 4.5:1 contrast. */
+:root {
+  --sempods-bg: light-dark(#ffffff, #14111c);
+  --sempods-text: light-dark(#241a3a, #ece6f8);
+  --sempods-muted: light-dark(#665e7c, #a49cbc);
+  --sempods-line: light-dark(#e9e4f3, #2e2742);
+  --sempods-accent: light-dark(#6a3bd2, #b59cff);
+  --sempods-on-accent: light-dark(#ffffff, #1b1036);
+}

package/skeleton/app/src/themes/warm.css

@@ -0,0 +1,11 @@
+/* Warm: terracotta on cream, cosy and homely.
+   The --sempods-* tokens colour the app and the SDK components alike, in
+   light and dark mode; each pair keeps at least 4.5:1 contrast. */
+:root {
+  --sempods-bg: light-dark(#fdfaf6, #1a1512);
+  --sempods-text: light-dark(#2b211b, #efe6dd);
+  --sempods-muted: light-dark(#74675c, #ab9d90);
+  --sempods-line: light-dark(#ece2d8, #3a2f28);
+  --sempods-accent: light-dark(#9c4128, #f0a184);
+  --sempods-on-accent: light-dark(#ffffff, #2a120a);
+}

package/skeleton/app/src/ui/Composer.tsx

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+
+/**
+ * A bar fixed at the bottom of the screen, in thumb reach, for the input that
+ * is always there (for example "add an item"). The page leaves room for it,
+ * it sits above the home indicator, and with the skeleton's viewport setting
+ * (interactive-widget=resizes-content) it stays above the on-screen keyboard
+ * in browsers that support that. iOS Safari overlays the keyboard instead.
+ * Render it in the frame, outside views that tabs switch: switching views
+ * does not ask about an unsent creation draft, and unmounting loses it.
+ */
+export function Composer({ children }: { readonly children: ReactNode }) {
+  return (
+    <div className="composer">
+      <div className="composer-content">{children}</div>
+    </div>
+  );
+}