@sempods/apps 0.7.1 → 0.8.0-dev.1

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

@@ -0,0 +1,85 @@
+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 title, 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. Shows `fallback` (the app's icon and name)
+ * until a context is selected. Name things in the person's words: `label`
+ * "List", `shareMore` "Share more lists …".
+ */
+export function ContextSwitch({
+  icon,
+  label,
+  texts,
+  fallback,
+}: {
+  readonly icon: ReactNode;
+  readonly fallback: ReactNode;
+  /** 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 fallback;
+  // 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">
+      <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,103 @@
+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))
+      )
+        opener.focus();
+    };
+  }, [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>
+  );
+}

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

package/skeleton/app/src/ui/dismiss.ts

@@ -0,0 +1,30 @@
+import { useEffect, type RefObject } from 'react';
+
+/**
+ * Closes a popup on a pointer press outside `container` or on Escape, and
+ * returns focus to `button` after Escape.
+ */
+export function useDismiss(
+  open: boolean,
+  close: () => void,
+  container: RefObject<HTMLElement | null>,
+  button: RefObject<HTMLElement | null>,
+) {
+  useEffect(() => {
+    if (!open) return;
+    const onPointer = (event: PointerEvent) => {
+      if (!container.current?.contains(event.target as Node)) close();
+    };
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape') return;
+      close();
+      button.current?.focus();
+    };
+    document.addEventListener('pointerdown', onPointer);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('pointerdown', onPointer);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [open, close, container, button]);
+}

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

@@ -0,0 +1,53 @@
+// Line icons for icon buttons, drawn in the text colour. Each is decorative:
+// the button carries the name (aria-label and title).
+import type { ReactNode } from 'react';
+
+function Icon({ size = 22, children }: { size?: number; children: ReactNode }) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      width={size}
+      height={size}
+      aria-hidden="true"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      {children}
+    </svg>
+  );
+}
+
+export const MenuIcon = () => (
+  <Icon>
+    <circle cx="12" cy="5" r="1" />
+    <circle cx="12" cy="12" r="1" />
+    <circle cx="12" cy="19" r="1" />
+  </Icon>
+);
+
+export const ReloadIcon = () => (
+  <Icon>
+    <path d="M20 12a8 8 0 1 1-2.34-5.66M20 4v5h-5" />
+  </Icon>
+);
+
+export const AddIcon = () => (
+  <Icon>
+    <path d="M12 5v14M5 12h14" />
+  </Icon>
+);
+
+export const CloseIcon = () => (
+  <Icon size={20}>
+    <path d="M6 6l12 12M18 6L6 18" />
+  </Icon>
+);
+
+export const ChevronIcon = () => (
+  <Icon size={16}>
+    <path d="M6 9l6 6 6-6" />
+  </Icon>
+);

package/skeleton/app/src/ui/ui.css

@@ -0,0 +1,240 @@
+/* The small UI kit: header, menu, context switch, tabs, bottom bar and
+   dialog, on the --sempods-* tokens of index.css. Calm and flat: one line per
+   edge, no shadows. */
+
+/* Header: the app (or the context switch) at the start, icon actions and the
+   menu at the end, on one line at every width. A long name shrinks and wraps
+   inside the title, so the menu stays on screen. */
+main > header {
+  flex-wrap: nowrap;
+}
+main > header h1 {
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+.header-actions {
+  display: flex;
+  align-items: center;
+  flex: none;
+}
+.header-actions button {
+  padding: 10px;
+  color: var(--sempods-text);
+}
+
+/* Keeps a heading for screen readers without showing it. */
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
+/* Menu: a button and a short list below it. */
+.menu {
+  position: relative;
+  min-width: 0;
+}
+.menu-items {
+  position: absolute;
+  top: 100%;
+  z-index: 10;
+  display: grid;
+  min-width: 14rem;
+  max-width: calc(100vw - 32px);
+  padding: 4px;
+  border: 1px solid var(--sempods-line);
+  border-radius: 8px;
+  background: var(--sempods-bg);
+}
+.menu-end {
+  right: 0;
+}
+.menu-start {
+  left: 0;
+}
+.menu-items button {
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  text-align: start;
+  color: var(--sempods-text);
+  font-weight: 400;
+}
+.menu-items small {
+  display: block;
+  color: var(--sempods-muted);
+  font-size: 0.8rem;
+}
+.menu-check {
+  flex: none;
+  width: 1rem;
+}
+.menu-items hr {
+  width: 100%;
+  margin: 4px 0;
+  border: 0;
+  border-top: 1px solid var(--sempods-line);
+}
+
+/* Context switch: app icon and the current context, as the header's title;
+   a failed request to share more shows below it. */
+.context-switch-wrap {
+  min-width: 0;
+}
+.context-switch > button {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  max-width: 100%;
+  padding: 8px 8px 8px 0;
+  color: var(--sempods-text);
+  font-size: 1.15rem;
+}
+.context-switch > button img {
+  flex: none;
+  width: 28px;
+  height: 28px;
+}
+.context-name {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.context-switch-problem {
+  margin: 0;
+  color: var(--sempods-muted);
+  font-size: 0.875rem;
+}
+
+/* Lists of items: a row with its checkbox, its name (opens the item) and its
+   actions; the empty state is a quiet line. */
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 4px;
+  border-bottom: 1px solid var(--sempods-line);
+}
+.row-name {
+  flex: 1;
+  min-width: 0;
+  text-align: start;
+  color: var(--sempods-text);
+  font-weight: 400;
+}
+/* A row's notice (a problem or an open outcome) takes its own line. */
+.row > [data-sempods-ui='notice'] {
+  flex-basis: 100%;
+}
+.empty {
+  color: var(--sempods-muted);
+}
+
+/* Tabs: the views as links on one line; the current one is underlined on
+   the row's only line. */
+.tabs {
+  display: flex;
+  gap: 1.25rem;
+  margin: 4px 0 8px;
+  border-bottom: 1px solid var(--sempods-line);
+}
+.tabs a {
+  margin-bottom: -1px;
+  padding: 10px 0;
+  border-bottom: 2px solid transparent;
+  color: var(--sempods-muted);
+  text-decoration: none;
+  white-space: nowrap;
+}
+.tabs a:hover {
+  color: var(--sempods-text);
+}
+.tabs a[aria-current='page'] {
+  border-bottom-color: var(--sempods-accent);
+  color: var(--sempods-text);
+  font-weight: 500;
+}
+
+/* Bottom bar: fixed in thumb reach, above the home indicator; the page
+   leaves room for it. */
+.composer {
+  position: fixed;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  z-index: 5;
+  padding: 10px 16px calc(10px + env(safe-area-inset-bottom));
+  border-top: 1px solid var(--sempods-line);
+  background: var(--sempods-bg);
+}
+.composer-content {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  max-width: 728px;
+  margin-inline: auto;
+}
+.composer-content > form {
+  display: flex;
+  flex: 1;
+  align-items: center;
+  gap: 8px;
+}
+.composer-content input {
+  flex: 1;
+  min-width: 0;
+  border: 0;
+  background: transparent;
+}
+/* The bar's top line frames the input; the caret shows the focus. */
+.composer-content input:focus-visible {
+  outline: none;
+}
+main:has(.composer) {
+  padding-bottom: calc(88px + env(safe-area-inset-bottom));
+}
+
+/* Dialog: centred, a bottom sheet on phones. */
+.dialog {
+  width: min(28rem, calc(100vw - 2rem));
+  max-height: calc(100dvh - 2rem);
+  padding: 0;
+  border: 1px solid var(--sempods-line);
+  border-radius: 12px;
+  background: var(--sempods-bg);
+  color: var(--sempods-text);
+}
+.dialog::backdrop {
+  background: color-mix(in srgb, #000 35%, transparent);
+}
+.dialog-close {
+  float: right;
+  margin: 4px;
+  color: var(--sempods-muted);
+}
+.dialog-body {
+  clear: both;
+  padding: 0 20px 20px;
+}
+@media (max-width: 30rem) {
+  .dialog {
+    width: 100vw;
+    max-width: 100vw;
+    margin: auto 0 0;
+    border-radius: 12px 12px 0 0;
+  }
+}
+
+/* A primary action: filled, for the one main step of a dialog or form. */
+button.primary {
+  width: 100%;
+  background: var(--sempods-accent);
+  color: var(--sempods-on-accent);
+}
+button.primary:hover:not(:disabled) {
+  background: var(--sempods-accent);
+  opacity: 0.9;
+}

package/skeleton/app/vite.config.ts

@@ -1,13 +1,13 @@
 import react from '@vitejs/plugin-react';
 import { defineConfig } from 'vite';
 import { VitePWA } from 'vite-plugin-pwa';
-import { base, pwa, server } from './vite.sempods.generated.ts';
+import { base, pageTitle, pwa, server } from './vite.sempods.generated.ts';
 
-// Base path, development port and PWA settings come from apps.json through the
-// generated file; add your own plugins and options here.
+// Base path, development port, page title and PWA settings come from apps.json
+// through the generated file; add your own plugins and options here.
 export default defineConfig({
   base,
   server,
   preview: server,
-  plugins: [react(), ...(pwa ? [VitePWA(pwa)] : [])],
+  plugins: [react(), pageTitle, ...(pwa ? [VitePWA(pwa)] : [])],
 });

package/skills/update/SKILL.md

@@ -72,5 +72,7 @@ instead.
    request's branch, or open a pull request "Update the tooling to <version>",
    with the migration report, each manual case and how it was decided, and
    what to try. Tell the owner what changed in plain words and
-   what they should try. App code, app notes and the owner's entries in
-   `package.json` are never rewritten by the migration.
+   what they should try. App notes and the owner's entries in `package.json`
+   are never rewritten by the migration; of the apps' files it only
+   regenerates the generated configuration and moves files still unchanged
+   from the skeleton where a release's upgrade notes say so.

package/skeleton/app/public/favicon.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="#176354"/></svg>