@nervur-org/dock 0.3.0

package/human/screen.ts

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: Apache-2.0
+// The human side: one avatar, one surface. The surface is the least a
+// screen can be: it shows a page and hands back a submitted form, and that
+// is all this side asks of a terrain. A DOM is one surface; a test is
+// another. The side keeps the model, speaks it as a page after every change
+// through `html.ts`, calls the avatar when a form comes back, and re-asks
+// her describe after each call, so a digest that moved is a page that
+// moved. A push is appended and shown the moment it lands.
+import { digest } from '@nervur-org/nervur';
+import type { Blueprint, JsonObject } from '@nervur-org/nervur';
+import { word, type Serving, type Subject } from '../beings/side.ts';
+import { isInvitation } from '@nervur-org/nervur';
+import type { Invitation } from '@nervur-org/nervur';
+import { page, values, hintFor, mine, asks, standing, stands, type Model, type Raw } from './html.ts';
+import { sanitiseTree, answersIn } from './tree.ts';
+import { groups, sanitise } from '../beings/look.ts';
+import { isSilence, isWord } from '@nervur-org/nervur';
+
+export type Surface = {
+  show(html: string): void;
+  // The surface calls this when a form is submitted: the ask's name and
+  // the fields as strings. Set once by the side.
+  onSubmit: ((ask: string, raw: Raw) => void) | undefined;
+};
+
+// `after` runs after every ask the side makes, a submitted form, her
+// describe, her look and the read-only asks run on open alike, as it does
+// for the model side: every ask rotates her keys, and a harbor that must
+// write what the ward changed hooks it. A side that saved only after a form
+// would bring her back from a reload with a stale count, and the far door
+// would refuse her. `admit` is what to do
+// with an answer that is an invitation: a guest at a world's door is let in
+// by it, and a side with no `admit` shows it as any answer. `focus` is one
+// standing she carries shown as the whole page, the page at
+// `web./<ward>/<being>`, and `at` the world's page address the sections and a
+// focused page link to.
+// `ended` is called when her describe says the relation is over, so a shell
+// can offer the one act left, leaving. It is told and never obeyed: the
+// shell decides what to put in front of the human, and nothing here drops a
+// ward.
+export type Options = { after?: () => Promise<void>; notice?: string; admit?: (invitation: Invitation) => Promise<void>; focus?: string; at?: string; ended?: () => Promise<void> };
+export async function screenSide(avatar: Subject, surface: Surface, options: Options = {}): Promise<Serving & { model: Model; refresh(): Promise<void> }> {
+  const after = options.after ?? (async () => {});
+  const notice = options.notice ?? '';
+  const model: Model = { blueprint: null, look: {}, tree: null, pages: {}, notice, standing: 'in', answers: {}, pushes: [], ...(options.focus !== undefined ? { focus: options.focus } : {}), ...(options.at !== undefined ? { at: options.at } : {}) };
+  let seen: string | null = null;
+  const show = () => surface.show(page(model));
+
+  // Her describe, again: the page follows the digest.
+  const refresh = async () => {
+    const bp = await avatar.tools();
+    if ('error' in bp && !('asks' in bp)) {
+      // the last page she gave stays, with the answers under it, and the
+      // notice says where the human stands now: her relation ended, the
+      // world away for the moment, or her own error, told apart because
+      // only one of the three is over
+      model.standing = standing(bp.error);
+      model.notice = stands(bp.error);
+      if (model.standing === 'ended') await options.ended?.();
+    } else {
+      model.standing = 'in';
+      const d = await digest(bp as Blueprint);
+      const moved = d !== seen;
+      if (moved) {
+        seen = d;
+        model.blueprint = bp as Blueprint;
+        for (const k of Object.keys(model.answers)) if (!(bp as Blueprint).asks.some((a) => a.name === k)) delete model.answers[k];
+        // her look, once per digest: how she wants her page painted, and what each ask is
+        if ((bp as Blueprint).asks.some((a) => a.name === 'look')) {
+          const l = await avatar.call('look');
+          model.look = isSilence(l) || isWord(l) ? {} : sanitise(l);
+        } else model.look = {};
+      }
+      // her page, after every ask: a tree of values from what she holds now, or nothing and her asks
+      // are forms. A cell moved is a page moved, and her describe need not have; so the answers the
+      // page shows are run again with it, and the page never stands more than one ask behind her
+      const trees = () => [model.tree ? answersIn(model.tree) : [], ...Object.entries(model.pages).map(([id, t]) => (t ? answersIn(t).map((n) => `${id}-${n}`) : []))].flat();
+      const shows = new Set(trees());
+      const tree = async (name: string) => {
+        const t = await avatar.call(name);
+        return isSilence(t) || isWord(t) ? null : sanitiseTree(t);
+      };
+      model.tree = (bp as Blueprint).asks.some((a) => a.name === 'page') ? await tree('page') : null;
+      // and the page of every standing she carries, the same way, painted in that standing's section;
+      // a name a carried page uses is one of that standing's asks, carried, and nothing else
+      model.pages = {};
+      for (const [id, g] of Object.entries(groups(bp as Blueprint))) if (typeof g.page === 'string' && (bp as Blueprint).asks.some((a) => a.name === g.page)) model.pages[id] = await tree(g.page);
+      const wanted = new Set(trees());
+      for (const n of shows) if (wanted.has(n)) delete model.answers[n];
+      // a read-only ask that needs nothing typed is run on her behalf once per digest, and one her page
+      // shows the answer of after every ask, so the page opens and stays with what it shows
+      for (const a of (bp as Blueprint).asks) {
+        // What the side fills for itself is not something a human has to
+        // type, so an ask whose only required argument is the moment has
+        // nothing left to ask and runs like one with no arguments at all.
+        const needs = asks(a).length > 0;
+        const run = wanted.has(a.name) || (moved && hintFor(bp as Blueprint, model.look, a.name).readOnly);
+        if (run && !needs && !(a.name in model.answers)) model.answers[a.name] = word(await avatar.call(a.name, mine(a)));
+      }
+    }
+    await after();
+    show();
+  };
+
+  surface.onSubmit = (name, raw) => void submit(name, raw);
+  const submit = async (name: string, raw: Raw) => {
+    const ask = model.blueprint?.asks.find((a) => a.name === name);
+    if (!ask) return;
+    const v = values(ask, raw);
+    if ('error' in v) {
+      model.answers[name] = { word: 'error', value: { error: v.error } };
+      return show();
+    }
+    const out = await avatar.call(name, v.args);
+    await after();
+    if (options.admit && isInvitation(out)) return options.admit(out);
+    model.answers[name] = word(out);
+    await refresh();
+  };
+
+  const ear = (object: JsonObject) => {
+    model.pushes.push(object);
+    show();
+  };
+  avatar.ears.add(ear);
+
+  await refresh();
+  return {
+    model,
+    refresh,
+    close: async () => {
+      avatar.ears.delete(ear);
+      surface.onSubmit = undefined;
+    },
+  };
+}

package/human/style.ts

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+// The stylesheet: the kit, and then what the screen alone has.
+//
+// One stylesheet for every screen there is, whatever carries it: the web
+// route serves it beside the tab's bundle, and the desk app's window
+// carries it in its own. A screen that looked like another product on
+// another terrain would be two designs to keep and one of them always
+// behind. It is one string and not four files because a screen builds its
+// own page and has nowhere to put a link.
+//
+// The kit brings the tokens, its own light and dark face, the reset, the
+// baseline, the bare controls and every piece a page is made of. The
+// painter emits those pieces and nothing else, so what follows is small:
+// the page's one column, and the few things the shells alone have, the
+// door, a local being's section, moving a world, the daemon's state line.
+// Nothing below mints a colour or a size; every one is a slot or a scale,
+// so a face swapped for another swaps the screen with it. A far being's
+// look sets the kit's slots on her own section, and the kit does the rest.
+import { CSS as KIT, TOKENS, BASE, COMPONENTS } from '@nervur-org/ui/css';
+
+const SCREEN = [
+  // One column that is a phone first and a desk after: the same page, more
+  // air. The insets are the phone's: an app fills the screen, corners and
+  // camera and all, so the first line of the page would otherwise sit under
+  // the clock. `env()` is zero everywhere else, so a tab and a window are
+  // laid out by the gutter alone.
+  'body{max-width:var(--nv-page-w-md);margin-inline:auto;padding-inline:calc(var(--nv-page-gutter) + env(safe-area-inset-left)) calc(var(--nv-page-gutter) + env(safe-area-inset-right));padding-block:env(safe-area-inset-top) calc(var(--nv-space-8) + env(safe-area-inset-bottom))}',
+  'main{display:flex;flex-direction:column;gap:var(--nv-space-4)}',
+  // a subsection holding a form and the answer under it, and the sections
+  // of one being's page after another
+  'main>.nv-stack>section+section,main>.nv-stack>section+.nv-standing,main>.nv-stack>.nv-standing+section{margin-block-start:var(--nv-space-3)}',
+  // a far being's logo beside her name, and the way to her own page
+  'img.logo{height:var(--nv-icon-lg)}a.open,a.back{text-decoration:none;font-weight:var(--nv-weight-medium)}a.back::before{content:"\\2190  "}',
+  // A place the side vouches for reads as a place to go. One it will not
+  // vouch for reads as what it is, an address the human may copy and weigh,
+  // and it is deliberately not underlined and not the accent: it must never
+  // look like something the page is willing to stand behind. A link that
+  // leaves the world wears the origin it goes to, out of the anchor's own
+  // data, so a human reads where she is going on the page rather than in a
+  // status bar she may never look at.
+  'a.link.out::after{content:" \\2197 " attr(data-origin);font-size:var(--nv-text-sm);color:var(--nv-color-fg-muted)}span.link.away{border:1px dashed var(--nv-color-border-strong)}',
+  // a being of the world running in the tab: her own section under the far page
+  'section.local{border-block-start:1px solid var(--nv-color-border);margin-block:var(--nv-space-5) 0;padding-block-start:var(--nv-space-3)}',
+  // moving a world to another device, and leaving one: quiet, at the foot
+  // of the page, and the offer wrapping rather than running off the side,
+  // since it is one long word
+  '.move,section.held{display:flex;flex-direction:column;gap:var(--nv-space-2);align-items:flex-start;border-block-start:1px solid var(--nv-color-border);margin-block:var(--nv-space-7) 0;padding-block-start:var(--nv-space-3);font-size:var(--nv-text-sm);color:var(--nv-color-fg-muted)}.move .invitation,section.held .invitation{font-family:var(--nv-font-mono);font-size:var(--nv-text-xs);overflow-wrap:anywhere}',
+  'section.held .worlds{display:flex;flex-wrap:wrap;gap:var(--nv-space-2)}',
+  // a foot the shell hid stays hidden: a class that lays it out would otherwise beat the attribute
+  '.move[hidden],section.held[hidden]{display:none}',
+  // the door page: one thing on air, vertically centred in the window
+  'main[data-door]{min-height:70vh;justify-content:center}main[data-door] .nv-picture{width:var(--nv-space-7);height:var(--nv-space-7);color:var(--nv-color-accent)}',
+  // the desk window: the state of the daemon behind the page, a line, and nothing when all is well
+  'p.state:empty{display:none}',
+].join('');
+
+export const CSS = `${KIT}\n${SCREEN}`;
+
+// The same screen for a world that wears a design of its own: the kit
+// without its own face, since the kit's contract says a surface loads the
+// default face or a design's and never both, and the design's stylesheet
+// is linked after it by the route that serves it.
+export const BARE = `${TOKENS}\n${BASE}\n${COMPONENTS}\n${SCREEN}`;