@sempods/apps 0.7.1 → 0.8.0

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>
+  );
+}

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

@@ -0,0 +1,94 @@
+import type { ReactNode } from 'react';
+import { useContexts, useSdkLocale } from '@sempods/app-sdk/react';
+import { ChevronIcon } from './icons.tsx';
+import { Menu } from './Menu.tsx';
+
+/**
+ * The everyday switch for an app that works in one of several contexts at a
+ * time (for example lists): 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>
+        {icon}
+        {title}
+      </h1>
+    );
+  // A failed reload keeps the known contexts and offers to try again; a
+  // failed request to share says why below the switch.
+  const actions = [
+    ...(failed
+      ? [{ label: messages.controls.retry, onSelect: () => void retry() }]
+      : []),
+    ...(canShare
+      ? [{ label: texts.shareMore, onSelect: () => void share() }]
+      : []),
+  ];
+  return (
+    <div className="context-switch-wrap">
+      <h1 className="visually-hidden">{title}</h1>
+      <Menu
+        className="context-switch"
+        align="start"
+        label={`${label}: ${selected.name}`}
+        trigger={
+          <>
+            {icon}
+            <span className="context-name">{selected.name}</span>
+            <ChevronIcon />
+          </>
+        }
+        items={[
+          ...contexts.map((context) => ({
+            label: context.name,
+            // The SDK's own words, as in its management dialog.
+            hint: context.writable
+              ? messages.controls.canChange
+              : messages.controls.canRead,
+            checked: context.iri === selected.iri,
+            onSelect: () => {
+              if (context.iri !== selected.iri) void select(context.iri);
+            },
+          })),
+          ...(actions.length > 0 ? [null, ...actions] : []),
+        ]}
+      />
+      {shareProblem && (
+        <p role="alert" className="context-switch-problem">
+          {shareProblem}
+        </p>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,120 @@
+import {
+  useEffect,
+  useRef,
+  useState,
+  type MouseEvent,
+  type ReactNode,
+} from 'react';
+import { CloseIcon } from './icons.tsx';
+
+/**
+ * A modal dialog, a bottom sheet on phones, for example around an item's
+ * `ResourceEditor`. Escape, the × button and a press beside the dialog (on
+ * its backdrop) ask the owner to close it; it
+ * only goes away when the owner unmounts it, so a declined close (unsaved
+ * changes) keeps it open. The SDK's leave confirmation shows above it.
+ * "Pods & sharing" needs none: `AppAccess` with `onClose` brings its own.
+ */
+export function Dialog({
+  label,
+  closeLabel,
+  onClose,
+  children,
+}: {
+  readonly label: string;
+  readonly closeLabel: string;
+  /** Asked to close; unmount the dialog to close it, keep it to decline. */
+  readonly onClose: () => void | Promise<void>;
+  readonly children: ReactNode;
+}) {
+  const dialog = useRef<HTMLDialogElement>(null);
+  // What had focus before the dialog opened, for example the item it shows.
+  const [opener] = useState(() => document.activeElement);
+  // Open as a modal once mounted; unmounting removes it. (Closing it in an
+  // effect cleanup would fire `close` under React's StrictMode re-run.)
+  // Removing an open dialog does not restore focus as close() would, so the
+  // cleanup returns it to the opener unless it has moved on elsewhere.
+  useEffect(() => {
+    const element = dialog.current;
+    if (element && !element.open) element.showModal();
+    return () => {
+      const focused = document.activeElement;
+      if (
+        opener instanceof HTMLElement &&
+        opener.isConnected &&
+        (!focused || focused === document.body || element?.contains(focused))
+      )
+        restoreFocus(opener);
+    };
+  }, [opener]);
+  // A press on the backdrop targets the dialog element outside its box. Both
+  // ends of the press count, so selecting text inside and releasing beside it
+  // does not close.
+  const beside = (event: MouseEvent) => {
+    const box = dialog.current?.getBoundingClientRect();
+    return (
+      event.target === dialog.current &&
+      !!box &&
+      (event.clientX < box.left ||
+        event.clientX > box.right ||
+        event.clientY < box.top ||
+        event.clientY > box.bottom)
+    );
+  };
+  const pressedBeside = useRef(false);
+  // Ask the owner; if it keeps the dialog, make sure it is open again.
+  const request = async () => {
+    await onClose();
+    const element = dialog.current;
+    if (element && !element.open) element.showModal();
+  };
+  return (
+    <dialog
+      ref={dialog}
+      className="dialog"
+      aria-label={label}
+      onCancel={(event) => {
+        // Escape: the browser would close the dialog before the owner decides.
+        event.preventDefault();
+        void request();
+      }}
+      // Browsers may still close it (a repeated Escape without a user
+      // activation); then the owner decides as well.
+      onClose={() => void request()}
+      onPointerDown={(event) => {
+        pressedBeside.current = beside(event);
+      }}
+      onClick={(event) => {
+        if (pressedBeside.current && beside(event)) void request();
+        pressedBeside.current = false;
+      }}
+    >
+      <button
+        className="dialog-close"
+        aria-label={closeLabel}
+        title={closeLabel}
+        onClick={() => void request()}
+      >
+        <CloseIcon />
+      </button>
+      <div className="dialog-body">{children}</div>
+    </dialog>
+  );
+}
+
+// The SDK keeps the page inert for a moment while a guarded change settles,
+// for example clearing the selection that closed the dialog. Focus waits for
+// it a few frames; each frame gives up once focus has moved on meanwhile.
+function restoreFocus(opener: HTMLElement, frames = 10) {
+  if (!opener.isConnected) return;
+  if (!opener.closest('[inert]')) {
+    opener.focus();
+    return;
+  }
+  if (frames > 0)
+    requestAnimationFrame(() => {
+      const focused = document.activeElement;
+      if (!focused || focused === document.body)
+        restoreFocus(opener, frames - 1);
+    });
+}

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

@@ -0,0 +1,118 @@
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type KeyboardEvent,
+  type ReactNode,
+  type RefObject,
+} from 'react';
+import { useDismiss } from './dismiss.ts';
+
+export type MenuItem = {
+  readonly label: string;
+  /** A second, muted line, for example the access to a context. */
+  readonly hint?: string;
+  /** For a choice among several: marks the current one. */
+  readonly checked?: boolean;
+  readonly onSelect: () => void;
+};
+
+/**
+ * A button that opens a short list of actions or choices. It closes on a
+ * choice, Escape or a press outside; a choice and Escape return focus to the
+ * button.
+ * `null` in `items` draws a separator.
+ */
+export function Menu({
+  label,
+  trigger,
+  items,
+  align = 'end',
+  button,
+  className,
+}: {
+  /** The button's name for screen readers; also its tooltip. */
+  readonly label: string;
+  /** The button's content, usually an icon. */
+  readonly trigger: ReactNode;
+  readonly items: readonly (MenuItem | null)[];
+  /** Which edge of the button the list lines up with. */
+  readonly align?: 'start' | 'end';
+  /** The button, for example to return focus to it later. */
+  readonly button?: RefObject<HTMLButtonElement | null>;
+  readonly className?: string;
+}) {
+  const [open, setOpen] = useState(false);
+  const container = useRef<HTMLDivElement>(null);
+  const own = useRef<HTMLButtonElement>(null);
+  const ref = button ?? own;
+  const close = useCallback(() => setOpen(false), []);
+  useDismiss(open, close, container, ref);
+  const list = useRef<HTMLDivElement>(null);
+  const choice = items.some((item) => item?.checked !== undefined);
+  // Focus moves into the list on opening; the arrow keys move within it.
+  useEffect(() => {
+    if (open) list.current?.querySelector('button')?.focus();
+  }, [open]);
+  const onKeyDown = (event: KeyboardEvent) => {
+    if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return;
+    event.preventDefault();
+    const entries = [...(list.current?.querySelectorAll('button') ?? [])];
+    const at = entries.indexOf(document.activeElement as HTMLButtonElement);
+    const step = event.key === 'ArrowDown' ? 1 : -1;
+    entries[(at + step + entries.length) % entries.length]?.focus();
+  };
+
+  return (
+    <div className={`menu ${className ?? ''}`} ref={container}>
+      <button
+        ref={ref}
+        aria-label={label}
+        title={label}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        onClick={() => setOpen(!open)}
+      >
+        {trigger}
+      </button>
+      {open && (
+        <div
+          role="menu"
+          ref={list}
+          className={`menu-items menu-${align}`}
+          onKeyDown={onKeyDown}
+        >
+          {items.map((item, i) =>
+            item ? (
+              <button
+                key={i}
+                role={item.checked === undefined ? 'menuitem' : 'menuitemradio'}
+                aria-checked={item.checked}
+                onClick={() => {
+                  close();
+                  // Focus goes back to the button before the action, which
+                  // may move it on, for example into a dialog it opens.
+                  ref.current?.focus();
+                  item.onSelect();
+                }}
+              >
+                {choice && (
+                  <span className="menu-check" aria-hidden="true">
+                    {item.checked ? '✓' : ''}
+                  </span>
+                )}
+                <span>
+                  {item.label}
+                  {item.hint && <small>{item.hint}</small>}
+                </span>
+              </button>
+            ) : (
+              <hr key={i} />
+            ),
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,39 @@
+import type { useRoute, Route } from '../routes.ts';
+
+export type View = {
+  /** The route; undefined for the start page. */
+  readonly route: Route | undefined;
+  readonly label: string;
+};
+
+/**
+ * The app's views as tabs on one line: links with their own addresses, so
+ * they open in a new tab or get bookmarked; a plain click switches in place
+ * under the SDK's leave policy. Pass `route` and `link` from `useRoute()`.
+ */
+export function Tabs({
+  label,
+  views,
+  current,
+  link,
+}: {
+  /** The name of the navigation for screen readers. */
+  readonly label: string;
+  readonly views: readonly View[];
+  readonly current: Route | undefined;
+  readonly link: ReturnType<typeof useRoute>['link'];
+}) {
+  return (
+    <nav aria-label={label} className="tabs">
+      {views.map(({ route, label }) => (
+        <a
+          key={route ?? ''}
+          {...link(route)}
+          aria-current={route === current ? 'page' : undefined}
+        >
+          {label}
+        </a>
+      ))}
+    </nav>
+  );
+}