@tinvar/react 0.0.0-stage → 0.4.0

package/src/head.js

@@ -0,0 +1,360 @@
+'use client';
+
+// The document's title, meta tags and links, from any component.
+//
+// tinvar-spec.md, "Operations and tooling": "React 19 hoists <title> and
+// <meta> from components; add key-based dedupe, one title, a global title
+// template, and PHP-rendered fallback tags marked for replacement."
+//
+// React hoists every <title>, <meta> and <link> a component renders into
+// <head>, all of them: a layout and its page each naming a title leaves two,
+// and the browser shows whichever comes first; each naming a canonical URL
+// leaves two, and a crawler believes neither. So the tags go through these
+// components instead, which agree among themselves on one per key:
+//
+//   - the one deepest in the route wins -- the page over its layouts, read
+//     from the <Segment> it sits in, whatever order they render in -- and
+//     among equals, the one mounted last;
+//   - <Title> applies the provider's template, and the provider's default
+//     stands under every title, so a page that names none still has one;
+//   - a <Meta> is keyed by its name, property or http-equiv, or `headKey`;
+//   - a <HeadLink> by what makes two links the same link: see linkKey().
+//
+// A raw <title>, written without <Title>, takes part too, at the document's
+// depth: on the server the renderer keeps one title of all of them, and in
+// the browser the provider keeps the winner first in <head>, where the
+// browser reads a document's title from (arrangeTitles()). A raw <link>
+// takes part on the server alone, at the document's depth and keyed as
+// <HeadLink> keys it, unless it is one of React's resources; in the browser
+// it is React's to hoist and remove, so a link that changes with the page
+// belongs in a <HeadLink>.
+//
+// On the server every tag renders, marked with its key and depth, and the
+// renderer keeps one of each key in the document's head (packages/renderer
+// src/head.js), dropping the PHP-rendered fallbacks any of them replaces. In
+// the browser the same agreement is reached once they mount, and the losers
+// render nothing.
+
+import {
+  createContext,
+  createElement,
+  useContext,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useState,
+  useSyncExternalStore,
+} from 'react';
+import { useSegmentDepth } from './segment.js';
+
+/** Marks a tag PHP rendered for a component's to replace (see Tinvar\Protocol\HeadTag). */
+export const FALLBACK_ATTRIBUTE = 'data-tinvar-head';
+
+/** What a fallback is marked with. */
+export const FALLBACK = 'fallback';
+
+/** The key a tag is deduplicated by, on the element. */
+export const KEY_ATTRIBUTE = 'data-tinvar-key';
+
+/** Its depth in the route, on the element. */
+export const DEPTH_ATTRIBUTE = 'data-tinvar-depth';
+
+/** The key every title shares: there is one title. */
+export const TITLE_KEY = 'title';
+
+/**
+ * The key a meta tag is deduplicated by.
+ *
+ * @param {Record<string, unknown>} props
+ * @returns {string | null} null for a tag with nothing to key it by, which is never deduplicated
+ */
+export function metaKey(props) {
+  if (typeof props.headKey === 'string' && props.headKey !== '') return props.headKey;
+  if (typeof props.name === 'string') return `name:${props.name}`;
+  if (typeof props.property === 'string') return `property:${props.property}`;
+  if (typeof props.httpEquiv === 'string') return `http-equiv:${props.httpEquiv.toLowerCase()}`;
+  if (props.charSet !== undefined) return 'charset';
+  return null;
+}
+
+/**
+ * Rels whose links are the page's icon at a size: a deeper one stands in
+ * for a shallower one of the same size and media, whatever its href.
+ */
+const ICON_RELS = new Set([
+  'icon',
+  'shortcut icon',
+  'apple-touch-icon',
+  'apple-touch-icon-precomposed',
+  'mask-icon',
+]);
+
+/**
+ * The key a link is deduplicated by.
+ *
+ *   - `headKey`, given: the application's own.
+ *   - canonical: the rel alone. A document has one canonical URL, so the
+ *     page's replaces its layout's, whatever either names.
+ *   - alternate with an hreflang: the rel and the language -- one
+ *     translation of the page per language.
+ *   - an icon: the rel, its sizes, its media and its type -- one icon per
+ *     size, per colour scheme, per format. A browser picks among icons of
+ *     different types by what it can draw, so an SVG and a PNG fallback
+ *     with no sizes are two icons, not one replacing the other.
+ *   - anything else: the rel and the href. Two links to the same thing for
+ *     the same reason are one link; a preload, a preconnect, a feed or a
+ *     manifest named twice -- by a layout and a page -- is written once.
+ *
+ * A stylesheet is never keyed: React's own resources dedupe stylesheets by
+ * href and order them by precedence, and a <HeadLink rel="stylesheet">
+ * renders React's <link> exactly as given (see HeadLink).
+ *
+ * @param {Record<string, unknown>} props
+ * @returns {string | null} null for a link with nothing to key it by, which is never deduplicated
+ */
+export function linkKey(props) {
+  if (typeof props.headKey === 'string' && props.headKey !== '') return `link:${props.headKey}`;
+  const rel = typeof props.rel === 'string' ? props.rel.trim().toLowerCase().replace(/\s+/g, ' ') : '';
+  if (rel === '' || rel === 'stylesheet') return null;
+  if (rel === 'canonical') return 'link:canonical';
+
+  const hrefLang = props.hrefLang ?? props.hreflang;
+  if (rel === 'alternate' && typeof hrefLang === 'string' && hrefLang !== '') {
+    return `link:alternate:${hrefLang.toLowerCase()}`;
+  }
+  if (ICON_RELS.has(rel)) {
+    const sizes = typeof props.sizes === 'string' ? props.sizes.trim().toLowerCase() : '';
+    const media = typeof props.media === 'string' ? props.media.trim() : '';
+    const type = typeof props.type === 'string' ? props.type.trim().toLowerCase() : '';
+    return `link:${rel}:${sizes}:${media}:${type}`;
+  }
+  return typeof props.href === 'string' && props.href !== '' ? `link:${rel}:${props.href}` : null;
+}
+
+/**
+ * The tags mounted in the browser, and which of each key wins.
+ *
+ * @returns {{
+ *   register(id: string, key: string, depth: number): () => void,
+ *   wins(id: string): boolean,
+ *   subscribe(listener: () => void): () => void,
+ * }}
+ */
+export function createHeadStore() {
+  /** @type {Map<string, { key: string, depth: number, order: number }>} */
+  const entries = new Map();
+  const listeners = new Set();
+  let order = 0;
+
+  const notify = () => {
+    for (const listener of listeners) listener();
+  };
+
+  return {
+    register(id, key, depth) {
+      entries.set(id, { key, depth, order: order++ });
+      notify();
+      return () => {
+        entries.delete(id);
+        notify();
+      };
+    },
+    wins(id) {
+      const mine = entries.get(id);
+      // Not registered yet -- the render before its effect -- or not in a
+      // provider's view at all: it renders, as the server did.
+      if (mine === undefined) return true;
+      for (const [other, entry] of entries) {
+        if (other === id || entry.key !== mine.key) continue;
+        if (entry.depth > mine.depth || (entry.depth === mine.depth && entry.order > mine.order))
+          return false;
+      }
+      return true;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+
+/**
+ * @typedef {{ store: ReturnType<typeof createHeadStore> | null, titleTemplate: string | null }} HeadContextValue
+ */
+const HeadContext = createContext(/** @type {HeadContextValue} */ ({ store: null, titleTemplate: null }));
+
+/**
+ * The title template and default for the page, around the document.
+ *
+ * @param {{ titleTemplate?: string, defaultTitle?: string, children?: unknown }} props `titleTemplate`
+ *        holds `%s` where a <Title>'s text goes; `defaultTitle` is the title when no
+ *        component names one, used as it is
+ */
+export function HeadProvider({ titleTemplate, defaultTitle, children }) {
+  // One store for the provider's life: the document's, kept across every
+  // page the router mounts into it.
+  const [store] = useState(createHeadStore);
+  const value = useMemo(() => ({ store, titleTemplate: titleTemplate ?? null }), [store, titleTemplate]);
+
+  // A raw <title> is React's to hoist, and in the browser React puts each
+  // newly mounted title ahead of the others -- so a page's raw title showed
+  // over its <Title>, or a layout's raw title over the page's. The winner is
+  // kept first instead, whenever the store's tags change or the head does.
+  useLayoutEffect(() => {
+    if (typeof document === 'undefined' || typeof MutationObserver === 'undefined') return undefined;
+    const head = document.head;
+    if (head === null) return undefined;
+    const arrange = () => arrangeTitles(head);
+    const observer = new MutationObserver(arrange);
+    observer.observe(head, { childList: true });
+    const unsubscribe = store.subscribe(arrange);
+    arrange();
+    return () => {
+      observer.disconnect();
+      unsubscribe();
+    };
+  }, [store]);
+
+  return createElement(
+    HeadContext.Provider,
+    { value },
+    defaultTitle === undefined
+      ? null
+      : createElement(HeadTag, { kind: 'title', depth: -1, text: defaultTitle }),
+    children,
+  );
+}
+
+/**
+ * The document's title. Its text goes through the provider's template.
+ *
+ * @param {{ children: string | number | readonly (string | number)[] }} props
+ */
+export function Title({ children }) {
+  const { titleTemplate } = useContext(HeadContext);
+  // React hoists a <title> with exactly one text child, so the text is one
+  // string however it was written.
+  const text = Array.isArray(children) ? children.join('') : String(children);
+  // Given by a function, so the text goes in as written: given as a
+  // string, `$'` or `$&` in a product's name was a replacement pattern.
+  const shown = titleTemplate === null ? text : titleTemplate.replace('%s', () => text);
+
+  return createElement(HeadTag, { kind: 'title', depth: useSegmentDepth(), text: shown });
+}
+
+/**
+ * A meta tag, one per name, property or http-equiv -- or per `headKey`,
+ * for a key of your own.
+ *
+ * @param {Record<string, unknown> & { headKey?: string }} props
+ */
+export function Meta(props) {
+  return createElement(HeadTag, { kind: 'meta', depth: useSegmentDepth(), props });
+}
+
+/**
+ * A link in the document's head, one per key (linkKey()): one canonical
+ * URL, one icon per size and type, one alternate per language, and no link written
+ * twice -- or per `headKey`, for a key of your own.
+ *
+ * A stylesheet goes to React as it is, unkeyed and unmarked: React already
+ * keeps one of each href, orders them by `precedence`, and holds the page
+ * until they have loaded, none of which a link that gives way to another
+ * could do.
+ *
+ * @param {Record<string, unknown> & { rel: string, headKey?: string }} props
+ */
+export function HeadLink(props) {
+  const depth = useSegmentDepth();
+  if (typeof props.rel === 'string' && props.rel.trim().toLowerCase() === 'stylesheet') {
+    const { headKey: _ignored, ...attributes } = props;
+    return createElement('link', attributes);
+  }
+  return createElement(HeadTag, { kind: 'link', depth, props });
+}
+
+/**
+ * One tag, rendered only while it wins its key.
+ *
+ * @param {{ kind: 'title' | 'meta' | 'link', depth: number, text?: string, props?: Record<string, unknown> }} props
+ */
+function HeadTag({ kind, depth, text, props }) {
+  const { store } = useContext(HeadContext);
+  const id = useId();
+  const key = kind === 'title' ? TITLE_KEY : kind === 'link' ? linkKey(props ?? {}) : metaKey(props ?? {});
+
+  useLayoutEffect(() => {
+    if (store === null || key === null) return undefined;
+    return store.register(id, key, depth);
+  }, [store, id, key, depth]);
+
+  // The server and the hydrating render show every tag, as the document
+  // has them; the renderer already kept one of each key there.
+  const wins = useSyncExternalStore(
+    store?.subscribe ?? noSubscription,
+    () => store === null || key === null || store.wins(id),
+    () => true,
+  );
+
+  // A title that has just come to win -- the default once the page's went --
+  // is put first as it mounts, before the browser paints; a raw title is
+  // put in its place by the provider's observer, a microtask later.
+  useLayoutEffect(() => {
+    if (kind === 'title' && wins && store !== null && typeof document !== 'undefined' && document.head) {
+      arrangeTitles(document.head);
+    }
+  }, [kind, wins, store, text]);
+
+  if (!wins) return null;
+
+  const marks = { [DEPTH_ATTRIBUTE]: String(depth), ...(key === null ? {} : { [KEY_ATTRIBUTE]: key }) };
+  if (kind === 'title') return createElement('title', marks, text);
+
+  const { headKey: _ignored, ...attributes } = props ?? {};
+  return createElement(kind, { ...attributes, ...marks });
+}
+
+const noSubscription = () => () => {};
+
+/**
+ * Puts the title that wins first in $head, where the browser reads the
+ * document's title from, as the renderer resolves them on the server: the
+ * deepest, a raw <title> at the document's depth (0), a PHP fallback below
+ * everything, and among equals the newest -- the first in the head, since
+ * React inserts each title it mounts ahead of the others.
+ *
+ * Moved, never removed: every title in the head is React's, which removes
+ * it itself when its component unmounts, from wherever it is. The losers
+ * stay in the head, after the winner, where they change nothing the
+ * browser shows.
+ *
+ * @param {HTMLHeadElement} head
+ * @returns {Element | null} the winner, or null for a head with no title
+ */
+export function arrangeTitles(head) {
+  const titles = [...head.querySelectorAll('title')].filter((title) => title.parentNode === head);
+  if (titles.length < 2) return titles[0] ?? null;
+
+  let winner = titles[0];
+  let best = depthOf(winner);
+  for (const title of titles.slice(1)) {
+    const depth = depthOf(title);
+    if (depth > best) {
+      winner = title;
+      best = depth;
+    }
+  }
+
+  // Only when it is not first already: a move is a mutation the observer
+  // hears, and this would otherwise answer it for ever.
+  if (titles[0] !== winner) head.insertBefore(winner, titles[0]);
+  return winner;
+}
+
+/** @param {Element} title */
+function depthOf(title) {
+  if (title.getAttribute(FALLBACK_ATTRIBUTE) === FALLBACK) return -Infinity;
+  if (!title.hasAttribute(KEY_ATTRIBUTE)) return 0;
+  const depth = Number(title.getAttribute(DEPTH_ATTRIBUTE));
+  return Number.isFinite(depth) ? depth : 0;
+}

package/src/inbox-view.d.ts

@@ -0,0 +1,17 @@
+import type { ReactElement } from 'react';
+import type { InboxClient, InboxEntry } from './inbox.js';
+
+export interface InboxProps<T extends string = string> {
+  client: InboxClient<T>;
+  /** The bell's name, and the panel's: "Notifications" by default. */
+  label?: string;
+  /** What an empty inbox says. */
+  empty?: string;
+  className?: string;
+  limit?: number;
+  /** Called when an entry is opened, after it is marked read; without it, its path is navigated to. */
+  onOpen?: (entry: InboxEntry<T>) => void;
+}
+
+/** A bell and the user's notifications, unstyled: every part carries `data-inbox` to style it by. */
+export declare function Inbox<T extends string>(props: InboxProps<T>): ReactElement;

package/src/inbox-view.js

@@ -0,0 +1,105 @@
+'use client';
+
+// <Inbox>: a bell and the user's notifications, unstyled (ADR 0155).
+//
+//   <Inbox client={inbox.customer} onOpen={(entry) => navigate(entry.url)} />
+//
+// A button saying how many are unread, which opens a list of the newest
+// entries -- each its title and body as text, never markup, read when it
+// is opened -- with "Mark all read" and, while there are more, "Show
+// more". Everything carries a `data-inbox` attribute to style it by, and
+// the button its count as `data-unread`. An application with a design
+// system of its own builds its bell on useInbox() instead.
+
+import { createElement as h, useId, useState } from 'react';
+import { sitePath } from './inbox.js';
+import { useInbox } from './use-inbox.js';
+
+/**
+ * @param {{
+ *   client: ReturnType<typeof import('./inbox.js').inboxClient>,
+ *   label?: string,
+ *   empty?: string,
+ *   className?: string,
+ *   limit?: number,
+ *   onOpen?: (entry: { id: string, url: string | null }) => void,
+ * }} props
+ */
+export function Inbox({ client, label = 'Notifications', empty = 'Nothing yet.', className, limit, onOpen }) {
+  const inbox = useInbox(client, limit === undefined ? {} : { limit });
+  const [open, setOpen] = useState(false);
+  const panel = useId();
+
+  /** @param {{ id: string, url: string | null, readAt: string | null }} entry */
+  const openEntry = (entry) => {
+    if (entry.readAt === null) void inbox.markRead([entry.id]);
+    if (onOpen) {
+      onOpen(entry);
+    } else {
+      // A path on this site alone: `/\\host` and `/\t/host` lead off it as
+      // `//host` does.
+      const path = sitePath(entry.url);
+      if (path !== null) globalThis.location?.assign(path);
+    }
+  };
+
+  return h(
+    'div',
+    { className, 'data-inbox': 'root' },
+    h(
+      'button',
+      {
+        type: 'button',
+        'data-inbox': 'bell',
+        'data-unread': inbox.unread,
+        'aria-expanded': open,
+        'aria-controls': panel,
+        'aria-label': inbox.unread > 0 ? `${label}, ${inbox.unread} unread` : label,
+        onClick: () => setOpen((was) => !was),
+      },
+      label,
+      inbox.unread > 0
+        ? h('span', { 'data-inbox': 'count', 'aria-hidden': true }, String(inbox.unread))
+        : null,
+    ),
+    open
+      ? h(
+          'section',
+          { id: panel, 'data-inbox': 'panel', 'aria-label': label },
+          inbox.unread > 0
+            ? h(
+                'button',
+                { type: 'button', 'data-inbox': 'mark-all', onClick: () => void inbox.markAllRead() },
+                'Mark all read',
+              )
+            : null,
+          inbox.entries.length === 0 && !inbox.loading
+            ? h('p', { 'data-inbox': 'empty' }, empty)
+            : h(
+                'ul',
+                { 'data-inbox': 'list' },
+                inbox.entries.map((entry) =>
+                  h(
+                    'li',
+                    { key: entry.id, 'data-inbox': 'entry', 'data-read': entry.readAt !== null },
+                    h(
+                      'button',
+                      { type: 'button', 'data-inbox': 'open', onClick: () => openEntry(entry) },
+                      h('strong', null, entry.title),
+                      entry.body === '' ? null : h('span', null, entry.body),
+                      h('time', { dateTime: entry.createdAt }, new Date(entry.createdAt).toLocaleString()),
+                    ),
+                  ),
+                ),
+              ),
+          inbox.hasMore
+            ? h(
+                'button',
+                { type: 'button', 'data-inbox': 'more', onClick: () => void inbox.loadMore() },
+                'Show more',
+              )
+            : null,
+        )
+      : null,
+  );
+}

package/src/inbox.d.ts

@@ -0,0 +1,108 @@
+/** A signed-in user's in-app inbox (ADR 0155). */
+
+import type { ListenOptions } from './channel.js';
+
+export declare const INBOX_PATH: '/_inbox/';
+
+/** The channels a notification goes out on. */
+export type NotificationChannel = 'mail' | 'push' | 'inbox';
+
+/** What codegen writes for each #[Notification]: the channels it sends on. */
+export interface NotificationShape {
+  channels: NotificationChannel;
+}
+
+/** One entry: text to draw as text, and a path on this site. */
+export interface InboxEntry<T extends string = string> {
+  id: string;
+  type: T;
+  title: string;
+  body: string;
+  url: string | null;
+  /** ISO 8601. */
+  createdAt: string;
+  readAt: string | null;
+}
+
+export interface InboxPage<T extends string = string> {
+  entries: InboxEntry<T>[];
+  unread: number;
+  /** The id the next page goes on from, or null for the last page. */
+  next: string | null;
+}
+
+/** What the inbox's personal channel says when the feed changes. */
+export interface InboxUpdate<T extends string = string> {
+  unread: number;
+  entry: InboxEntry<T> | null;
+  read: string[];
+  allRead: boolean;
+}
+
+export interface NotificationPreference<T extends string = string> {
+  type: T;
+  label: string;
+  description: string;
+  channels: NotificationChannel[];
+  enabled: NotificationChannel[];
+}
+
+export interface NotificationPreferences<T extends string = string> {
+  types: NotificationPreference<T>[];
+}
+
+export interface NotificationChoice<T extends string = string> {
+  type: T;
+  channel: NotificationChannel;
+  enabled: boolean;
+}
+
+/** $url where it is a path on this site, else null: never `//host`, `/\\host` or a control character. */
+export declare function sitePath(url: unknown): string | null;
+
+/** An entry as the server writes one, its link kept only on this site; null for anything else. */
+export declare function readEntry(value: unknown): InboxEntry | null;
+
+/** An update as the inbox's channel says one; null for anything else. */
+export declare function readUpdate(value: unknown): InboxUpdate | null;
+
+/** A call the server refused, or that never got an answer (status 0). */
+export declare class InboxError extends Error {
+  readonly inbox: string;
+  readonly status: number;
+  readonly body: unknown;
+}
+
+export interface InboxClient<T extends string = string> {
+  readonly name: string;
+  /** Its personal channel: `inbox.{name}`. */
+  readonly channel: string;
+  page(page?: { before?: string | null; limit?: number }): Promise<InboxPage<T>>;
+  markRead(ids: string[]): Promise<{ unread: number }>;
+  markAllRead(): Promise<{ unread: number }>;
+  preferences(): Promise<NotificationPreferences<T>>;
+  choose(choices: NotificationChoice<T>[]): Promise<NotificationPreferences<T>>;
+  /** Hears the feed change until the returned function is called. */
+  listen(
+    onUpdate: (update: InboxUpdate<T>) => void,
+    options?: Pick<ListenOptions, 'onError' | 'onGap'>,
+  ): () => void;
+}
+
+export interface InboxClientOptions {
+  fetch?: typeof fetch;
+  document?: { cookie?: string } | null;
+  /** How the personal channel is listened to: the channel runtime's listen(), unless a test hands in its own. */
+  listen?: typeof import('./channel.js').listen;
+}
+
+export declare function inboxClient<T extends string = string>(
+  name: string,
+  options?: InboxClientOptions,
+): InboxClient<T>;
+
+/** Builds the typed `inbox` codegen exports: a client for each #[Inbox], by name. */
+export declare function inboxes<M extends { [K in keyof M]: NotificationShape }, N extends string>(
+  names: N[],
+  options?: InboxClientOptions,
+): { [K in N]: InboxClient<keyof M & string> };