@sempods/apps 0.8.0 → 0.9.0-dev.1

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

@@ -1,27 +1,32 @@
 // 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,
+// SDK's quickstart screen with the UI kit (@sempods/app-ui). For a list app,
+// copy it next to App.tsx, change its import of '../places.ts' to
+// './places.ts', render <ListScreen nav={nav} /> in place of <Start />,
+// declare the item address in apps.json (`"resources": ["items/:id"]`) and
+// run pnpm run regenerate; then rename the type, fields, collection, address
+// 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 { useEffect, useRef } from 'react';
 import {
   LoadNotice,
   RemoveButton,
   ResourceEditor,
   UnresolvedNotices,
   UpdateNotice,
+  useAppState,
+  useContextEditor,
   useCreation,
   useFieldUpdate,
   useList,
   useMessages,
-  useResourceEditor,
-  useSelection,
+  useSdkLocale,
   useWorkflowAccess,
 } 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';
+import { ActionButton, Input, ScreenDialog, type Nav } from '@sempods/app-ui';
+import { PlusIcon } from 'lucide-react';
+import type { Place } from '../places.ts';
 
 const schema = 'https://schema.org/';
 
@@ -44,7 +49,6 @@ const en = {
   done: (name: string) => `Done: ${name}`,
   remove: (name: string) => `Delete: ${name}`,
   edit: 'Edit item',
-  close: 'Close',
   name: 'Name',
   newItem: 'New item',
   add: 'Add',
@@ -57,58 +61,71 @@ const listTexts: { readonly en: typeof en; readonly de: typeof en } = {
     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() {
+export function ListScreen({ nav }: { readonly nav: Nav<Place> }) {
   const t = useMessages(listTexts);
   // A list that can only be read gets no input and no invitation to add.
   const { write } = useWorkflowAccess();
+  const { view } = useAppState();
   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',
   });
+  const input = useRef<HTMLInputElement>(null);
+  if (!view) return null;
+  const { place } = nav;
+  // A link names the Context the list reads, so the address keeps its source.
+  const itemPlace = (subject: string): Place => ({
+    kind: 'item',
+    subject,
+    context: view.contextIri,
+  });
 
   return (
-    <>
+    // Room below the rows for the bar fixed at the bottom.
+    <div className="mt-4 pb-28">
       {/* 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">{write ? t.empty : t.emptyReadOnly}</p>
+          <p className="py-6 text-muted-foreground">
+            {write ? t.empty : t.emptyReadOnly}
+          </p>
         )}
-      <ul className="rows">
+      <ul className="divide-y">
         {items?.map((entry) => {
           const row = mutate.for(entry);
           return (
-            <li key={entry.iri} className="row">
+            <li key={entry.iri} className="flex min-h-14 items-center gap-1">
               {/* The label is the checkbox's 44px touch target. */}
-              <label>
+              <label className="flex size-11 shrink-0 cursor-pointer items-center justify-center">
                 <input
                   type="checkbox"
+                  className="size-6 accent-primary"
                   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>
+                <span className="sr-only">{t.done(row.data.name)}</span>
               </label>
-              <button
-                className="row-name"
-                onClick={() => void select(entry.iri)}
+              {/* The item's own address: a plain click opens its dialog, a
+                  modified click a new tab. */}
+              <a
+                {...nav.link(itemPlace(entry.iri))}
+                className="flex min-h-11 flex-1 items-center rounded-md px-2 hover:bg-muted"
               >
                 {row.data.name}
-              </button>
+              </a>
               {/* Asks in the SDK's dialog before it deletes. */}
               <RemoveButton
                 disabled={!row.canMutate}
@@ -123,54 +140,135 @@ export function ListScreen() {
       </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>
-      )}
+      <ItemDialog
+        subject={place.kind === 'item' ? place.subject : null}
+        // The Context the address names; only an address without one uses
+        // the selected Context.
+        context={(place.kind === 'item' && place.context) || view.contextIri}
+        title={t.edit}
+        label={t.name}
+        // Back to where it was opened from, after a direct entry to the
+        // start; the list refreshes on its own time, so a slow read never
+        // keeps the dialog open.
+        leave={() => {
+          nav.close({ kind: 'start' });
+          void list.reload();
+        }}
+      />
       <UpdateNotice {...creation.notice} quiet />
       {write && (
-        <Composer>
+        // A bar fixed at the bottom, in thumb reach, above the home indicator.
+        // Render it outside views that switch: switching does not ask about
+        // an unsent creation draft, and unmounting loses it.
+        <div className="fixed inset-x-0 bottom-0 z-10 border-t bg-background px-4 pt-2.5 pb-[calc(0.625rem+env(safe-area-inset-bottom))]">
           <form
+            className="mx-auto flex max-w-3xl items-center gap-2"
             onSubmit={(event) => {
               event.preventDefault();
+              // The field keeps the focus, also after a press on Add, so the
+              // keyboard stays for the next item. Only this press moves it.
+              input.current?.focus();
               void creation.create();
             }}
           >
-            <input
+            <Input
+              ref={input}
+              className="h-11 flex-1"
               aria-label={t.newItem}
               placeholder={t.newItem}
               value={creation.draft.name}
-              disabled={!creation.canEdit}
+              // While a creation is pending the field stays focused and
+              // cannot change; a confirmed creation empties it.
+              readOnly={creation.busy}
+              disabled={!creation.canEdit && !creation.busy}
               onChange={(event) => creation.change({ name: event.target.value })}
             />
-            <button
-              aria-label={t.add}
-              title={t.add}
-              disabled={!creation.canCreate}
+            <ActionButton
+              type="submit"
+              shape="round-sm"
+              label={t.add}
+              isDisabled={!creation.canCreate}
             >
-              <AddIcon />
-            </button>
+              <PlusIcon />
+            </ActionButton>
           </form>
-        </Composer>
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * The item's screen: a dialog that follows the address, with the SDK's
+ * editor for the Context the address names. Escape, Close and a press beside
+ * it ask before an unsaved edit is discarded; Back does too.
+ */
+function ItemDialog({
+  subject,
+  context,
+  title,
+  label,
+  leave,
+}: {
+  readonly subject: string | null;
+  readonly context: string;
+  readonly title: string;
+  readonly label: string;
+  readonly leave: () => void;
+}) {
+  const { messages } = useSdkLocale();
+  const edit = useContextEditor(item);
+  const { open, close } = edit;
+  // While the SDK changes the target (`changing`), it opens no editor; the
+  // effect runs again once the change has settled.
+  const { changing } = useAppState();
+  useEffect(() => {
+    if (changing) return;
+    if (subject) void open({ subject, context });
+    else void close();
+  }, [subject, context, changing, open, close]);
+  // An editor still showing another target is not this dialog's.
+  const editor =
+    subject &&
+    edit.target?.subject === subject &&
+    edit.target.context === context
+      ? edit.editor
+      : null;
+  // The SDK asks before a dirty draft is discarded; leaving the address does
+  // not wait for the list to reload.
+  const requestClose = async () => {
+    if (await edit.close()) leave();
+  };
+  return (
+    <ScreenDialog
+      title={title}
+      open={subject !== null}
+      onRequestClose={() => void requestClose()}
+    >
+      {edit.phase === 'unavailable' && edit.problem ? (
+        // A source Context the app cannot read: no editor, no other Context.
+        <p role="alert">{messages.contextProblems?.[edit.problem]}</p>
+      ) : (
+        <ResourceEditor
+          editor={editor}
+          quiet
+          onClose={() => void requestClose()}
+          labels={{ name: label }}
+        >
+          {(draft, change) => (
+            <label className="grid gap-1.5">
+              {label}
+              <Input
+                value={draft.name}
+                onChange={(event) =>
+                  change({ ...draft, name: event.target.value })
+                }
+                required
+              />
+            </label>
+          )}
+        </ResourceEditor>
       )}
-    </>
+    </ScreenDialog>
   );
 }

package/skeleton/app/src/index.css

@@ -1,110 +1,10 @@
-:root {
-  /* 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: var(--sempods-text);
-  background: var(--sempods-bg);
-}
-body {
-  margin: 0;
-}
-main {
-  max-width: 760px;
-  margin: auto;
-  padding: 16px;
-}
-/* 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;
-}
-main > header h1 {
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
-  margin: 0;
-  font-size: 1.4rem;
-}
-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;
-  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;
-}
-/* Lists of items, without the browser's indentation and bullets. */
-:where(ul):not(:where([data-sempods-ui] *)) {
-  padding-inline-start: 0;
-  list-style: none;
-}
+/* The app's stylesheet. The layer order comes first: Tailwind's reset (base)
+   stays below the SDK's styles (sempods), and the app's classes (components,
+   utilities) apply on and inside SDK surfaces. Then Tailwind, the UI kit with
+   its theme contract, and the app's theme. Keep unlayered element rules
+   (`button { … }`) out of this file: they would override every SDK rule. */
+@layer theme, base, sempods, components, utilities;
+@import 'tailwindcss';
+@import '@sempods/app-ui/styles.css';
+/* The app's theme: one of src/themes/; switch by changing this line. */
+@import './themes/__APP_THEME__.css';

package/skeleton/app/src/main.tsx

@@ -1,9 +1,7 @@
 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';
+// Tailwind, the UI kit and the app's theme.
 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/places.test.ts

@@ -0,0 +1,128 @@
+import { createBrowserRuntime } from '@sempods/app-sdk';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  addressModel,
+  decodeSubject,
+  encodeSubject,
+  inApp,
+  ITEM,
+} from './places.ts';
+import { app, runtimeOptions } from './sempods.generated.ts';
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe('places', () => {
+  const model = addressModel({
+    basePath: '/konsum/',
+    routes: ['bought'],
+    resources: [ITEM],
+  });
+  const subject = 'https://pod.example/data/items/milk#it';
+  const id = encodeSubject(subject);
+
+  it('reads the place of an address under the app path', () => {
+    expect(model.parse('/konsum/', '').place).toEqual({ kind: 'start' });
+    expect(model.parse('/konsum/bought/', '')).toEqual({
+      place: { kind: 'view', route: 'bought' },
+      canonical: '/konsum/bought',
+    });
+    expect(model.parse(`/konsum/items/${id}`, '').place).toEqual({
+      kind: 'item',
+      subject,
+    });
+    expect(model.parse('/konsum/callback', '?code=x').canonical).toBe(
+      '/konsum/callback?code=x',
+    );
+  });
+
+  it('keeps the query of a view while it normalises the address', () => {
+    expect(model.parse('/konsum/bought/', '?filter=open').canonical).toBe(
+      '/konsum/bought?filter=open',
+    );
+    expect(model.parse('/konsum/', '?task=x').canonical).toBe('/konsum/?task=x');
+  });
+
+  it('keeps the rest of an item query after its context', () => {
+    const search = '?tab=history&context=urn%3Actx%3A1';
+    expect(model.parse(`/konsum/items/${id}/`, search)).toEqual({
+      place: { kind: 'item', subject, context: 'urn:ctx:1' },
+      canonical: `/konsum/items/${id}?context=urn%3Actx%3A1&tab=history`,
+    });
+    expect(model.parse(`/konsum/items/${id}`, '?tab=history').canonical).toBe(
+      `/konsum/items/${id}?tab=history`,
+    );
+  });
+
+  it('keeps the source Context the address names', () => {
+    const context = 'https://pod.example/contexts/home';
+    const place = { kind: 'item', subject, context } as const;
+    const address = model.format(place);
+    const [path, query] = address.split('?');
+    expect(model.parse(path!, `?${query}`).place).toEqual(place);
+  });
+
+  it('shows unknown and invalid addresses as not found, keeping them', () => {
+    expect(model.parse('/konsum/other', '')).toEqual({
+      place: { kind: 'not-found', reason: 'unknown' },
+      canonical: '/konsum/other',
+    });
+    expect(model.parse('/konsum/items/!!', '').place).toEqual({
+      kind: 'not-found',
+      reason: 'invalid',
+    });
+    expect(model.parse(`/konsum/items/${id}`, '?context=x').place).toEqual({
+      kind: 'not-found',
+      reason: 'invalid',
+    });
+    expect(model.parse('/notes/', '').place.kind).toBe('not-found');
+  });
+
+  it('finds no item an app has not declared', () => {
+    const plain = addressModel({
+      basePath: '/konsum/',
+      routes: [],
+      resources: [],
+    });
+    expect(plain.parse(`/konsum/items/${id}`, '').place).toEqual({
+      kind: 'not-found',
+      reason: 'unknown',
+    });
+  });
+
+  it('returns a callback without a matching sign-in to the start page', async () => {
+    // An expired sign-in in a browser with nothing saved: the runtime gets
+    // `/` and the app keeps the person in it.
+    const callback = new URL(
+      `http://127.0.0.1:5180${app.basePath}callback?code=unused&state=expired`,
+    );
+    vi.stubGlobal('location', callback);
+    const seen: string[] = [];
+    const runtime = createBrowserRuntime({
+      ...runtimeOptions,
+      location: () => callback.href,
+      // A free lock, so the runtime reads the empty store.
+      locks: { request: (name, _options, granted) => granted({ name }) },
+      openStore: async () => ({
+        read: async () => undefined,
+        list: async () => ({ records: [], unreadable: [] }),
+        commit: async () => {
+          throw new Error('nothing to commit');
+        },
+        close() {},
+      }),
+      replaceUrl: (url) => seen.push(inApp(url)),
+    });
+    const report = await runtime.initialize();
+    expect(report).toMatchObject({ storage: 'durable', problem: 'attempt' });
+    expect(seen).toEqual([app.basePath]);
+    expect(inApp(`${app.basePath}bought?filter=open`)).toBe(
+      `${app.basePath}bought?filter=open`,
+    );
+  });
+
+  it('encodes a subject as one path segment', () => {
+    expect(id).toMatch(/^[A-Za-z0-9_-]+$/);
+    expect(decodeSubject(id)).toBe(subject);
+    expect(decodeSubject('bm90IGFuIElSSQ')).toBeNull();
+  });
+});