@saga-a2ui/lit 0.0.0-stage → 0.8.0-rc.1

package/src/actions/lit-actions.ts

@@ -0,0 +1,70 @@
+import {
+  createInstanceHost,
+  snapshotLimits,
+  type InstanceView,
+  type Limits,
+} from '@saga-a2ui/core/actions';
+import type { A2uiActions } from '../a2ui/app-element.js';
+import { mountOwners } from './mount-owner.js';
+
+export interface LitActionsOptions {
+  /**
+   * Application setup. Run once per presented surface, before it renders, with a view owned by
+   * that presentation alone. Discover instances with `watchById` (or `getById` for a unique ID)
+   * and bind definitions to the handles it delivers. Everything bound through those handles is
+   * disposed when the presentation ends.
+   */
+  readonly attach: (view: InstanceView) => void;
+  /**
+   * Receives the error of a setup that throws, and of a discovery callback that fails after
+   * setup began. The element shows its safe fallback in the first case; the error text itself
+   * goes only here, never into the page.
+   */
+  readonly onSetupError: (error: unknown) => void;
+  /**
+   * This application's defaults for every action bound through the integration: used for each
+   * bound (`deadlineMs`, `hookMs`) an action does not override itself, and before the SDK defaults
+   * of 30,000 ms of work and 5,000 ms per awaited hook or cleanup step. Each supplied value is
+   * checked when the integration is created, and copied, so changing the object afterwards
+   * affects nothing. Each presentation's host gets the same values; another integration has its own.
+   */
+  readonly limits?: Limits;
+}
+
+/**
+ * Makes `createA2uiAppElement` give each presented surface its own action host. Passing the
+ * result as `actions` is the one place an application opts in.
+ *
+ * Each actual mount owns its host, its bindings and its discovery subscriptions. They end when the
+ * surface is deleted or replaced, when setup fails, and when the app element disconnects. A
+ * reconnected element presents a new surface and so starts with a new host and a new `attach`.
+ */
+export function createLitActions(options: LitActionsOptions): A2uiActions {
+  const limits = snapshotLimits(options.limits);
+  return {
+    begin(presentation) {
+      const host = createInstanceHost({
+        onSetupError: options.onSetupError,
+        limits,
+      });
+      const end = (): void => {
+        host.close();
+        if (mountOwners.get(presentation.owner)?.host === host)
+          mountOwners.delete(presentation.owner);
+      };
+      mountOwners.set(presentation.owner, {
+        host,
+        surface: presentation.surface,
+        mount: presentation.mount,
+      });
+      try {
+        host.register(options.attach);
+      } catch (error) {
+        end();
+        options.onSetupError(error);
+        throw error;
+      }
+      return end;
+    },
+  };
+}

package/src/actions/mount-owner.ts

@@ -0,0 +1,42 @@
+import type { SurfaceModel } from '@a2ui/web_core/v0_9';
+import type { InstanceHost } from '@saga-a2ui/core/actions';
+
+/** What one app element presents while its action integration is active. */
+export interface MountOwner {
+  readonly host: InstanceHost;
+  readonly surface: SurfaceModel<any>;
+  /** The one `<a2ui-surface>` the app element rendered for this presentation. */
+  readonly mount: () => Element | undefined;
+}
+
+/** Set while an app element presents one surface, and removed when that presentation ends. */
+export const mountOwners = new WeakMap<Element, MountOwner>();
+
+/**
+ * Finds the host from the element's position in the DOM, not from the surface object: two
+ * `<a2ui-surface .surface=${S}>` mounts for one model share that key, and both would publish into
+ * one scope. The walk crosses shadow roots outward, remembers the nearest `<a2ui-surface>` it
+ * passes, stops at the first element that owns a presentation, and accepts only when that nearest
+ * surface element is the owner's own mount and the owner's surface is the one the element holds.
+ * Light DOM or slotted content that never passes through the owner's shadow tree finds nothing.
+ */
+export function hostOf(
+  element: Element,
+  surface: SurfaceModel<any>,
+): InstanceHost | undefined {
+  let nearestSurfaceElement: Element | undefined;
+  let root = element.getRootNode();
+  while (root instanceof ShadowRoot) {
+    const host = root.host;
+    if (host.localName === 'a2ui-surface') nearestSurfaceElement ??= host;
+    const owner = mountOwners.get(host);
+    if (owner) {
+      const sameMount =
+        nearestSurfaceElement !== undefined &&
+        nearestSurfaceElement === owner.mount();
+      return owner.surface === surface && sameMount ? owner.host : undefined;
+    }
+    root = host.getRootNode();
+  }
+  return undefined;
+}

package/src/element-registration.ts

@@ -0,0 +1,48 @@
+// Custom-element registration for an application's catalog. This module deliberately imports no
+// renderer, so the rule can be exercised without a DOM.
+
+/** One custom element an application needs: a catalog component's `LitComponentApi` fits as is. */
+export interface ElementDefinition {
+  readonly tagName: string;
+  readonly element: CustomElementConstructor;
+}
+
+/** The part of `CustomElementRegistry` that registration uses. */
+export interface ElementRegistry {
+  get(tagName: string): CustomElementConstructor | undefined;
+  define(tagName: string, element: CustomElementConstructor): void;
+}
+
+/** A tag is already bound to a different constructor, so using it would render the wrong component. */
+export class ElementConflictError extends Error {
+  constructor(readonly tagName: string) {
+    super(
+      `The custom element <${tagName}> is already defined with a different constructor. ` +
+        'Give each implementation its own tag name.',
+    );
+    this.name = 'ElementConflictError';
+  }
+}
+
+/**
+ * Defines each element in the registry. Setup is explicit: importing this package registers nothing.
+ *
+ * - A tag that is not defined yet is defined.
+ * - A tag already bound to the very same constructor is left alone, so repeating setup is harmless.
+ * - A tag bound to a different constructor fails with `ElementConflictError`. The existing
+ *   definition is never replaced, and no definition from the failing call is added: every tag is
+ *   checked before the first one is defined.
+ */
+export function defineElements(
+  definitions: readonly ElementDefinition[],
+  registry: ElementRegistry = customElements,
+): void {
+  const missing = new Map<string, CustomElementConstructor>();
+  for (const { tagName, element } of definitions) {
+    const existing = registry.get(tagName) ?? missing.get(tagName);
+    if (existing !== undefined && existing !== element)
+      throw new ElementConflictError(tagName);
+    if (existing === undefined) missing.set(tagName, element);
+  }
+  for (const [tagName, element] of missing) registry.define(tagName, element);
+}

package/src/faithful-card/adopt-styles.ts

@@ -0,0 +1,61 @@
+// How an application's own styles reach a Lit card. The card lives inside shadow roots that the
+// catalog and the A2UI surface create, and a page's or an element's stylesheet cannot select into
+// them, so a rule such as `.saga-card p` would never match. The view therefore carries the
+// application's constructable stylesheets, and each card adopts them into the root it is in for as
+// long as it is connected. Custom properties inherit through shadow roots and need none of this.
+
+/** The part of a document or shadow root that style adoption uses. */
+export interface StyleRoot {
+  adoptedStyleSheets: CSSStyleSheet[];
+}
+
+/** Per sheet in a root: how many cards hold it, and whether adoption (not the root's owner) put it there. */
+interface Holding {
+  count: number;
+  readonly inserted: boolean;
+}
+
+const holders = new WeakMap<object, Map<CSSStyleSheet, Holding>>();
+
+/**
+ * Adds `sheets` to `root`, after the sheets it already has, and returns the function that gives
+ * them back. A sheet several cards share stays until the last of them lets go. Only a sheet that
+ * adoption itself inserted is ever removed: one the root already had is its owner's and stays,
+ * whoever adopts it too. The returned function acts once. A root that cannot adopt styles is left
+ * alone.
+ */
+export function adoptStyles(
+  root: StyleRoot,
+  sheets: readonly CSSStyleSheet[],
+): () => void {
+  if (!Array.isArray(root.adoptedStyleSheets) || sheets.length === 0)
+    return () => undefined;
+  const holdings = holders.get(root) ?? new Map<CSSStyleSheet, Holding>();
+  holders.set(root, holdings);
+  for (const sheet of sheets) {
+    const held = holdings.get(sheet);
+    if (held !== undefined) {
+      held.count += 1;
+      continue;
+    }
+    const inserted = !root.adoptedStyleSheets.includes(sheet);
+    if (inserted) root.adoptedStyleSheets = [...root.adoptedStyleSheets, sheet];
+    holdings.set(sheet, { count: 1, inserted });
+  }
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    for (const sheet of sheets) {
+      const held = holdings.get(sheet);
+      if (held === undefined) continue;
+      held.count -= 1;
+      if (held.count > 0) continue;
+      holdings.delete(sheet);
+      if (held.inserted)
+        root.adoptedStyleSheets = root.adoptedStyleSheets.filter(
+          (one) => one !== sheet,
+        );
+    }
+  };
+}

package/src/faithful-card/blocked-fragment.ts

@@ -0,0 +1,58 @@
+import { html, type TemplateResult } from 'lit';
+
+// How a fragment the content policy blocks (a link, an image reference or raw markup) is shown:
+// as an accessible placeholder, or, once the reader reveals it, as its source text. Both are fixed
+// templates with text bindings. Nothing here activates a destination, loads an image or builds
+// markup from the source, so revealing changes visibility only.
+
+export type BlockedKind = 'link' | 'image' | 'markup';
+
+export interface BlockedFragment {
+  readonly kind: BlockedKind;
+  /** Stable hook for tests and styling: `md-link-inert`, `md-image-blocked` or `md-markup`. */
+  readonly testId: string;
+  /** Why the policy blocked it (a decision reason, or `load-failed`). */
+  readonly reason: string;
+  readonly revealed: boolean;
+  /** Readable text that stands in for the fragment, for example `[Image blocked: chart]`. */
+  readonly placeholder: string;
+  /** The source form shown when revealed. It may wrap the fragment's own label. */
+  readonly source: (label: TemplateResult | undefined) => TemplateResult;
+  /** Ordinary text that belongs to the fragment, such as a link's label, kept in place either way. */
+  readonly label?: TemplateResult;
+  /** A block-level fragment occupies its own paragraph; an inline one stays in its line. */
+  readonly block?: boolean;
+}
+
+/** An inline or block placeholder, or the revealed source, in the fragment's original position. */
+export function blockedFragment(fragment: BlockedFragment): TemplateResult {
+  const { kind, testId, reason, revealed, placeholder, source, label, block } =
+    fragment;
+  const presentation = revealed ? 'source' : 'placeholder';
+  // The placeholder is the card's own wording, so it is marked as an annotation; the supplied label
+  // beside it, and revealed source, are the author's text and are never marked.
+  const annotation = html`<span data-annotation=${`${kind}-blocked`}
+    >${placeholder}</span
+  >`;
+  const standIn =
+    label === undefined ? annotation : html`${label} ${annotation}`;
+  const content = revealed ? source(label) : standIn;
+  return block === true
+    ? html`<p
+        class="saga-card-source"
+        data-testid=${testId}
+        data-kind=${kind}
+        data-reason=${reason}
+        data-presentation=${presentation}
+      >
+        ${content}
+      </p>`
+    : html`<span
+        class="saga-card-blocked"
+        data-testid=${testId}
+        data-kind=${kind}
+        data-reason=${reason}
+        data-presentation=${presentation}
+        >${content}</span
+      >`;
+}

package/src/faithful-card/card-surface.ts

@@ -0,0 +1,181 @@
+import type { LitComponentApi } from '@a2ui/lit/v0_9';
+import { Catalog } from '@a2ui/web_core/v0_9';
+import {
+  cardData,
+  cardLayout,
+  FAITHFUL_CARD_CATALOG_ID,
+  type CardContent,
+  type ImageConsentScope,
+} from '@saga-a2ui/components/faithful-card';
+import { html, nothing } from 'lit';
+import { keyed } from 'lit/directives/keyed.js';
+import {
+  createA2uiAppElement,
+  type A2uiUpdateResult,
+} from '../a2ui/app-element.js';
+import { faithfulCardEntry } from './catalog.js';
+import { requestContentView } from './content-view.js';
+
+// The card's surface for Lit: layer A's layout presented by layer B's app element over the card's
+// own catalog, with the one operation that chooses what the card shows. Selection is not a data
+// update. `present` ends the previous presentation (its image consent, its late link and image
+// answers, its source toggles) and starts a new one even when the text is equal, so a reader's
+// earlier choices never carry over to a new answer. An ordinary update of an own-catalog surface
+// stays in place and is the app element's `updateData`; it is not this operation.
+
+/** The tag of the card surface element. `registerFaithfulCard` defines it. */
+export const CARD_SURFACE_TAG = 'saga-faithful-card-surface';
+
+/**
+ * What an application does with the card. Place `element` in the document beneath the element that
+ * provides the card's view (`provideContentView`).
+ */
+export interface CardSurface {
+  /** The element that shows the card: an empty card until the first `present`. */
+  readonly element: HTMLElement;
+  /**
+   * Shows `content` as a new presentation. Never throws. Content the surface refuses (for example
+   * markdown that is not text) returns the failure and leaves the shown presentation untouched,
+   * consent included. Content the view's reader refuses is not refused here: the card shows its
+   * own failure for it, in place of the content. Content presented before `element` is in the
+   * document is shown once it is.
+   */
+  present(content: CardContent): A2uiUpdateResult;
+  /** Ends the presentation and empties the card. The next `present` shows again. */
+  clear(): void;
+  /** Ends the surface. Idempotent. Afterwards `present` fails and the card shows nothing. */
+  dispose(): void;
+}
+
+const layout = cardLayout();
+const catalog = new Catalog<LitComponentApi>(FAITHFUL_CARD_CATALOG_ID, 'v0.9', [
+  faithfulCardEntry,
+]);
+
+/** What the element shows: set by the surface that owns it, never by the application. */
+interface Shown {
+  readonly content: CardContent | undefined;
+  /** Advances with every presentation, so the previous one is replaced even by equal text. */
+  readonly presentation: number;
+  /** True once the surface is disposed: nothing is shown. An empty or cleared card is still shown, empty. */
+  readonly ended: boolean;
+}
+
+/** The state of one card surface. Only this module can make one. */
+class OpenedCardSurface implements CardSurface {
+  readonly element: FaithfulCardSurfaceElement;
+  private readonly listeners = new Set<() => void>();
+  private consent: ImageConsentScope | undefined;
+  private ended = false;
+  private current: Shown = {
+    content: undefined,
+    presentation: 0,
+    ended: false,
+  };
+
+  constructor() {
+    this.element = new FaithfulCardSurfaceElement();
+    this.element.owner = this;
+  }
+
+  get shown(): Shown {
+    return this.current;
+  }
+
+  /** The mounted element tells this surface which consent scope its view owns; it takes it back on removal. */
+  attach(
+    consent: ImageConsentScope | undefined,
+    listener: () => void,
+  ): () => void {
+    this.consent = consent;
+    this.listeners.add(listener);
+    return () => {
+      if (this.consent === consent) this.consent = undefined;
+      this.listeners.delete(listener);
+    };
+  }
+
+  present(content: CardContent): A2uiUpdateResult {
+    if (this.ended)
+      return {
+        ok: false,
+        failure: { kind: 'rejected', message: 'The surface was disposed.' },
+      };
+    // Checked against the layout first, so content it refuses changes nothing: not the shown
+    // presentation, and not the consent given for it.
+    const checked = layout.update(cardData(content));
+    if (!checked.ok) return { ok: false, failure: checked.failure };
+    this.replace(content);
+    return { ok: true };
+  }
+
+  clear(): void {
+    if (!this.ended) this.replace(undefined);
+  }
+
+  dispose(): void {
+    if (this.ended) return;
+    this.ended = true;
+    this.replace(undefined);
+  }
+
+  private replace(content: CardContent | undefined): void {
+    this.consent?.revokeAll();
+    this.current = {
+      content,
+      presentation: this.current.presentation + 1,
+      ended: this.ended,
+    };
+    for (const listener of [...this.listeners]) listener();
+  }
+}
+
+/** The element behind {@link CardSurface}: an app element over the card's layout and catalog. */
+export class FaithfulCardSurfaceElement extends createA2uiAppElement({
+  catalog,
+  layout,
+}) {
+  /** Set once by the surface that created this element. */
+  owner?: OpenedCardSurface;
+  private detach?: () => void;
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+    this.detach = this.owner?.attach(requestContentView(this)?.consent, () => {
+      this.apply();
+      this.requestUpdate();
+    });
+    this.apply();
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.detach?.();
+    this.detach = undefined;
+  }
+
+  override render() {
+    const shown = this.owner?.shown;
+    if (shown === undefined || shown.ended) return nothing;
+    // The key is the presentation: a new one mounts a fresh card, which carries nothing of the old.
+    return html`${keyed(shown.presentation, super.render())}`;
+  }
+
+  /** Brings the connected session's data to what the card should show: the content, or nothing. */
+  private apply(): void {
+    if (!this.isConnected) return;
+    this.updateData(cardData(this.owner?.shown.content ?? { markdown: '' }));
+  }
+}
+
+/**
+ * Opens a card surface, empty until the first `present`. Needs `registerFaithfulCard()` to have
+ * run, since the surface is a custom element; throws naming that when it has not.
+ */
+export function openFaithfulCardSurface(): CardSurface {
+  if (customElements.get(CARD_SURFACE_TAG) !== FaithfulCardSurfaceElement)
+    throw new Error(
+      `<${CARD_SURFACE_TAG}> is not defined: call registerFaithfulCard() before opening a card surface.`,
+    );
+  return new OpenedCardSurface();
+}

package/src/faithful-card/catalog.ts

@@ -0,0 +1,29 @@
+import { A2uiLitElement, type LitComponentApi } from '@a2ui/lit/v0_9';
+import { FaithfulCardApi } from '@saga-a2ui/components/faithful-card';
+import { html, nothing } from 'lit';
+
+/**
+ * The catalog element. It binds the contract's two values to the card element and nothing else:
+ * the trusted reader, policy and callbacks come from the enclosing view, never from properties.
+ */
+export class FaithfulCardElement extends A2uiLitElement<
+  typeof FaithfulCardApi
+> {
+  protected readonly api = FaithfulCardApi;
+
+  render() {
+    const props = this.controller?.props;
+    if (!props) return nothing;
+    return html`<saga-faithful-card-content
+      .contractVersion=${props.contractVersion}
+      .markdown=${props.markdown}
+    ></saga-faithful-card-content>`;
+  }
+}
+
+/** The catalog entry. An application lists it in its own catalog, then calls `registerFaithfulCard`. */
+export const faithfulCardEntry = {
+  ...FaithfulCardApi,
+  tagName: 'saga-faithful-card',
+  element: FaithfulCardElement,
+} satisfies LitComponentApi;

package/src/faithful-card/content-view.ts

@@ -0,0 +1,102 @@
+import {
+  createCardView,
+  type CardViewSettings,
+  type FaithfulCardReader,
+  type ImageConsentScope,
+  type ContentPolicy,
+  type ImageEnforcement,
+} from '@saga-a2ui/components/faithful-card';
+import type { HostLinks } from '@saga-a2ui/core/host-links';
+
+/**
+ * Everything a card needs from its view, passed explicitly when the view is created: the trusted
+ * reader (Markdown dialect and content bound), the immutable trusted policy, the one way to ask
+ * the host to open a link, whether the image restrictions the policy relies on are demonstrably
+ * in force, and this view's own scope for the reader's revocable image consent. Nothing here is
+ * module-wide state, so two views never share or change each other's effects or consent. The
+ * scope is separate from the policy: whoever observes a retirement signal for the view (a new
+ * selection, teardown) calls `consent.revokeAll()`.
+ */
+export interface ContentView {
+  readonly reader: FaithfulCardReader;
+  readonly policy: ContentPolicy;
+  readonly hostLinks: HostLinks;
+  readonly imageEnforcement: ImageEnforcement;
+  readonly consent: ImageConsentScope;
+  /**
+   * The application's own stylesheets for the card. A card lives inside shadow roots that a rule
+   * of the page cannot select into, so each connected card adopts these into the root it is in
+   * (see `adopt-styles.ts`). Custom properties need none of this: they inherit.
+   */
+  readonly styles?: readonly CSSStyleSheet[];
+}
+
+/** What {@link createFaithfulCardView} takes: the renderer-neutral settings and, for Lit, the application's styles. */
+export interface LitCardViewSettings extends CardViewSettings {
+  readonly styles?: readonly CSSStyleSheet[];
+}
+
+/**
+ * Creates the view an application provides to its cards, once: the reader for its dialect and
+ * content bound, the policy and host links it passes, image enforcement established from the
+ * Content-Security-Policy values it passes (it reads no document: a caller that has one reads the
+ * values and passes them in, for example with the Lit stack's `documentContentSecurityPolicies`) and a
+ * fresh consent scope that ends with the view. Throws, naming the setting, when the reader
+ * settings are invalid; no view exists then.
+ */
+export function createFaithfulCardView(
+  settings: LitCardViewSettings,
+): ContentView {
+  const { styles, ...cardSettings } = settings;
+  return Object.freeze({
+    ...createCardView(cardSettings),
+    ...(styles === undefined ? {} : { styles: Object.freeze([...styles]) }),
+  });
+}
+
+export const CONTENT_VIEW_REQUEST = 'saga-content-view-request';
+
+/**
+ * Sent upward by a card when it connects. The nearest view answers with its own
+ * {@link ContentView}. A card nobody answers refuses to show anything.
+ */
+export class ContentViewRequest extends Event {
+  private answer?: ContentView;
+
+  constructor() {
+    super(CONTENT_VIEW_REQUEST, { bubbles: true, composed: true });
+  }
+
+  get view(): ContentView | undefined {
+    return this.answer;
+  }
+
+  /** The nearest view answers first; later answers are ignored. */
+  provide(view: ContentView): void {
+    this.answer ??= view;
+    this.stopPropagation();
+  }
+}
+
+/**
+ * Makes `host` the view for the cards inside it: they receive `view` when they connect. Returns
+ * the function that ends it. The host's own element decides when to call each; nothing is
+ * registered anywhere else.
+ */
+export function provideContentView(
+  host: EventTarget,
+  view: ContentView,
+): () => void {
+  const answer = (event: Event) => {
+    if (event instanceof ContentViewRequest) event.provide(view);
+  };
+  host.addEventListener(CONTENT_VIEW_REQUEST, answer);
+  return () => host.removeEventListener(CONTENT_VIEW_REQUEST, answer);
+}
+
+/** Asks the nearest enclosing view for its content settings. */
+export function requestContentView(from: EventTarget): ContentView | undefined {
+  const request = new ContentViewRequest();
+  from.dispatchEvent(request);
+  return request.view;
+}