@contraagent/elements 0.0.0-stage → 0.1.0

package/src/graph/card.ts

@@ -0,0 +1,209 @@
+// The selection's card in the graph's frame: placed beside the selected item
+// (`place-card`), joined to it for the keyboard, and the focus put back on the item.
+// The card's content is the host's (the `inspector` slot).
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import { PAD, placeCard, type Box } from './place-card.js';
+
+export interface CardOptions {
+  /** The card is a sheet under the frame (a narrow screen): it is not placed. */
+  docked: () => boolean;
+  /** The frame's height. */
+  frameH: () => number;
+  /** The card needs another least height of the frame (`room`): make the frame that tall. */
+  grow: () => void;
+  /** A pointer is down on the frame. */
+  pressed: () => boolean;
+  /** The shadow root of a view drawn by another element in the frame (a mark matrix), or null. */
+  inner: () => ParentNode | null;
+}
+
+/** The selected item as drawn, what the card keeps clear of, and the box it is shown in. */
+export interface Anchor {
+  item: HTMLElement;
+  clear: HTMLElement;
+  frame: HTMLElement;
+}
+
+/** The focused element, inside the shadow roots it is in. */
+function deepActive(root: DocumentOrShadowRoot | null | undefined): Element | null {
+  let at = root?.activeElement ?? null;
+  while (at?.shadowRoot?.activeElement) at = at.shadowRoot.activeElement;
+  return at;
+}
+
+/**
+ * The card (`.insp`) of the selected item in the host's frame (`.main > .frame`):
+ * a table row (`tr.sel > th`), a mark (`.mark.sel`, `.taskchip.sel`, in the frame or
+ * in the view of `inner`), a node (`.node.sel`) or a cluster (`.cluster.sel`). It
+ * runs after every draw, pan, zoom and scroll (`place`), and keeps Tab and Shift+Tab
+ * between the item and its card.
+ */
+export class CardController implements ReactiveController {
+  /** The frame height the card needs (0 without one). */
+  room = 0;
+  /** Focus is being put back, not moved by the reader: it does not select. */
+  quiet = false;
+
+  constructor(
+    private readonly host: ReactiveControllerHost & HTMLElement,
+    private readonly o: CardOptions,
+  ) {
+    host.addController(this);
+  }
+
+  hostConnected(): void {
+    this.host.addEventListener('keydown', this.onTabToCard);
+  }
+
+  hostDisconnected(): void {
+    this.host.removeEventListener('keydown', this.onTabToCard);
+  }
+
+  private get root(): ParentNode {
+    return this.host.shadowRoot ?? this.host;
+  }
+
+  private get focused(): Element | null {
+    return deepActive(this.host.shadowRoot);
+  }
+
+  /** The card, when there is a selection. */
+  card(): HTMLElement | null {
+    return this.root.querySelector<HTMLElement>('.insp');
+  }
+
+  /** The card's content: the elements the host put in the `inspector` slot. */
+  content(): Element[] {
+    return this.card()?.querySelector('slot')?.assignedElements({ flatten: true }) ?? [];
+  }
+
+  /** The buttons and links of the card's content, in order. */
+  private actions(): HTMLElement[] {
+    return this.content().flatMap((el) => [...(el.matches('button, a[href]') ? [el as HTMLElement] : []), ...el.querySelectorAll<HTMLElement>('button, a[href]')]);
+  }
+
+  /**
+   * The selected item as drawn (a mark, a node, a cluster's header), what the card keeps clear of
+   * (a mark's whole node), and the box it is shown in (the frame, or a mark matrix).
+   */
+  anchor(): Anchor | null {
+    const frame = this.root.querySelector<HTMLElement>('.main > .frame');
+    const row = frame?.querySelector<HTMLElement>('tr.sel > th');
+    if (frame && row) return { item: row, clear: row, frame };
+    const sel = frame?.querySelector<HTMLElement>('.mark.sel, .taskchip.sel, .node.sel, .cluster.sel') ?? this.o.inner()?.querySelector<HTMLElement>('.mark.sel');
+    if (!frame || !sel) return null;
+    // A cluster: the card points at its header, where its name is, and keeps clear of the whole cluster when there is room.
+    const item = sel.classList.contains('cluster') ? (sel.querySelector<HTMLElement>(':scope > .hd') ?? sel) : sel;
+    return { item, clear: item.closest<HTMLElement>('.node') ?? sel, frame };
+  }
+
+  /** Put the card beside the selected item, inside the frame; hide it while the item is out of view. */
+  place(): void {
+    const card = this.card();
+    const docked = this.o.docked();
+    const room = card && !docked ? card.querySelector<HTMLElement>('.scroll')!.scrollHeight + 24 + 2 * PAD : 0;
+    if (room !== this.room && (room > this.o.frameH() || this.room > 0)) {
+      this.room = room;
+      this.o.grow();
+    }
+    if (!card || docked) return;
+    const a = this.anchor();
+    const main = this.root.querySelector<HTMLElement>('.main');
+    if (!a || !main) {
+      card.classList.remove('placed');
+      return;
+    }
+    const m = main.getBoundingClientRect();
+    const rel = (r: DOMRect): Box => ({ left: r.left - m.left, top: r.top - m.top, width: r.width, height: r.height });
+    const item = rel(a.item.getBoundingClientRect());
+    const clear = rel(a.clear.getBoundingClientRect());
+    const f = rel(a.frame.getBoundingClientRect());
+    // A mark matrix scrolls: the item hides when scrolled out of it.
+    const port = a.frame.querySelector<HTMLElement>('.mx') ?? this.o.inner()?.querySelector<HTMLElement>('.mx');
+    const inView = placeCard(item, port ? rel(port.getBoundingClientRect()) : f, { width: 0, height: 0 }).shown;
+    const scroll = card.querySelector<HTMLElement>('.scroll');
+    if (scroll) scroll.style.maxHeight = `${Math.max(120, f.height - 2 * PAD - 24)}px`;
+    const size = { width: card.offsetWidth, height: card.offsetHeight };
+    let p = placeCard(clear, f, size, item);
+    if (!p.fits && a.clear !== a.item && !a.clear.classList.contains('node')) p = placeCard(item, f, size);
+    card.classList.toggle('placed', p.shown && inView);
+    card.dataset['side'] = p.side;
+    card.style.left = `${p.x}px`;
+    card.style.top = `${p.y}px`;
+    card.style.setProperty('--arrow', `${p.arrow}px`);
+  }
+
+  /** The focusable that stands for the selected item: the mark itself, or a node's or a cluster's name. */
+  itemFocus(): HTMLElement | null {
+    const a = this.anchor();
+    if (!a) return null;
+    return a.item.matches('button') ? a.item : a.item.querySelector<HTMLElement>('.name');
+  }
+
+  /**
+   * The selected item's focusable described by the card, and what a live region says
+   * of the item: its name and its status (the card content's first heading and its
+   * `[data-status]`), '' without a selection.
+   */
+  describe(): [name: string, status: string] {
+    const roots = [this.root, this.o.inner()].filter((r): r is ParentNode => !!r);
+    for (const r of roots) for (const el of r.querySelectorAll('[aria-describedby="insp"]')) el.removeAttribute('aria-describedby');
+    const own = this.itemFocus();
+    const card = this.card();
+    if (own && card) {
+      // An item in the view of another element (a mark matrix) names the card by reference: an id does not cross shadow roots.
+      if (own.getRootNode() === card.getRootNode()) own.setAttribute('aria-describedby', 'insp');
+      else if ('ariaDescribedByElements' in own) (own as HTMLElement & { ariaDescribedByElements: Element[] }).ariaDescribedByElements = [card];
+    }
+    const content = this.content();
+    const find = (sel: string) => content.map((el) => (el.matches(sel) ? el : el.querySelector(sel))).find(Boolean) ?? null;
+    return [find('h1, h2, h3, h4, h5, h6')?.textContent?.trim() ?? '', find('[data-status]')?.textContent?.trim() ?? ''];
+  }
+
+  /** Focus `el` without selecting what it is on. */
+  focusQuietly(el: HTMLElement | null | undefined): void {
+    this.quiet = true;
+    el?.focus();
+    this.quiet = false;
+  }
+
+  /** Run `f` now, or, while a pointer is down on the frame, once it is released (a scroll under a pressed pointer would move the click elsewhere). */
+  whenReleased(f: () => void): void {
+    if (!this.o.pressed()) return f();
+    globalThis.addEventListener('pointerup', () => setTimeout(f), { once: true });
+  }
+
+  /** On a narrow screen: scroll the selected item into view when it is out of it or under the sheet. */
+  revealOverSheet(): void {
+    const item = this.anchor()?.item;
+    if (!item) return;
+    const r = item.getBoundingClientRect();
+    const sheet = this.card()?.getBoundingClientRect();
+    const bottom = Math.min(globalThis.innerHeight, sheet?.top ?? Infinity);
+    if (r.top < 0 || r.bottom > bottom) item.scrollIntoView({ block: 'center' });
+  }
+
+  /** Shift+Tab on the card's first action comes back to the item; Escape puts the focus back on the item first. */
+  readonly onCardKey = (e: KeyboardEvent): void => {
+    if (e.key === 'Tab' && e.shiftKey && e.target === this.actions()[0]) {
+      const own = this.itemFocus();
+      if (!own) return;
+      e.preventDefault();
+      this.focusQuietly(own);
+    } else if (e.key === 'Escape') {
+      // The card goes with the selection: the focus goes back to the item first.
+      this.focusQuietly(this.itemFocus());
+    }
+  };
+
+  /** Tab on the selected item goes on to its card. */
+  private readonly onTabToCard = (e: KeyboardEvent): void => {
+    if (e.key !== 'Tab' || e.shiftKey || e.defaultPrevented) return;
+    const own = this.itemFocus();
+    if (!own || this.focused !== own) return;
+    const first = this.actions()[0];
+    if (!first) return;
+    e.preventDefault();
+    first.focus();
+  };
+}

package/src/graph/host.ts

@@ -0,0 +1,100 @@
+// What the graph's views read from `cae-layered-graph` and call on it. Each view is
+// a function of the element (`GraphHost`, its private members included) that renders
+// into its shadow root.
+import type { ReactiveControllerHost } from 'lit';
+import type { StateStyles } from '../primitives/states.js';
+import type { CardController } from './card.js';
+import type { GraphLayout } from './layout.js';
+import { markGrid } from './marks.js';
+import type { PanZoomController } from './pan-zoom.js';
+import type { LayeredGraphStrings } from './strings.js';
+import type { Arrangement, DrawnGraph, GraphClusterInput, GraphMark, GraphNode } from './types.js';
+
+/** The failed marks a node drawn as a bar lists by name. */
+export const BAR_LIST = 8;
+
+/**
+ * The element as its views see it: what it shows, the state the views change
+ * (each change renders the element again), its controllers and what it sends.
+ */
+export interface GraphHost extends ReactiveControllerHost, HTMLElement {
+  readonly renderRoot: ParentNode;
+  /** The graph, its nodes with their defaults. */
+  readonly drawn: DrawnGraph;
+  readonly arr: Arrangement;
+  readonly states: StateStyles;
+  readonly words: LayeredGraphStrings;
+  readonly selected: string | null;
+  readonly nodes: ReadonlyMap<string, GraphNode>;
+  readonly clusters: ReadonlyMap<string, GraphClusterInput>;
+  /** Where everything is drawn, and whether it was drawn for this graph (`key`). */
+  readonly lay: GraphLayout | null;
+  readonly laidOut: boolean;
+  /** Top to bottom. */
+  readonly down: boolean;
+  readonly barAt: number;
+  /** The node table is shown. */
+  readonly asTable: boolean;
+  /** The series (or a mark's id, for a mark outside any series) under the pointer or focus. */
+  hover: string | null;
+  /** Each group's focused mark (roving tabindex): one tab stop per group. */
+  readonly active: Map<string, number>;
+  readonly pz: PanZoomController;
+  readonly card: CardController;
+  renderIcon(name: string): unknown;
+  /** The series (or mark id) highlighted, and the marks it lights. */
+  lit(): { key: string | null; on: ReadonlySet<string> | null };
+  /** Select an item by its id (null: none). */
+  select(id: string | null): void;
+  /** Focus moved by the reader selects what it is on; focus put back does not. */
+  focusSelect(id: string): void;
+  /** An item's action: Enter, a double click, a card's first link. */
+  act(id: string): void;
+  /** Enter a cluster's inner view. */
+  drill(id: string): void;
+  /** Open (`open`) or close an item that can be drawn open. */
+  toggle(id: string, open: boolean): void;
+  /** The view switch. */
+  showView(view: 'graph' | 'table'): void;
+}
+
+/** A mark in a node, with its series id ('' outside any series). */
+export interface Slot {
+  m: GraphMark;
+  series: string;
+}
+
+/** How a group of marks lays out. */
+export interface Grid {
+  cols: number;
+  size: number;
+  gap: number;
+}
+
+/** A group of marks with one tab stop: a node's marks, or the failed marks a node drawn as a bar lists. */
+export interface MarkGroup {
+  id: string;
+  slots: (Slot | null)[];
+  grid: Grid;
+}
+
+/** A node's marks in slot order: one per series (null where the series has none here), then those outside any series. */
+export const slotsOf = (n: Pick<GraphNode, 'marks' | 'loose'>, series: readonly string[]): (Slot | null)[] => [
+  ...n.marks.map((m, i) => (m ? { m, series: series[i] ?? '' } : null)),
+  ...n.loose.map((m) => ({ m, series: '' })),
+];
+
+/** A group's grid: the graph's, so a series sits at one place in every node; a group without series lays out its own few marks. */
+export function gridOf(n: Pick<GraphNode, 'marks' | 'loose'>, series: number): Grid {
+  const slots = n.marks.length + n.loose.length;
+  const g = markGrid(n.marks.length ? series : slots);
+  return { cols: Math.min(g.cols, Math.max(1, slots)), size: g.size, gap: g.size >= 10 ? 4 : 2 };
+}
+
+/** The first slot that holds a mark. */
+export function firstMark(slots: readonly (Slot | null)[]): number {
+  return Math.max(0, slots.findIndex((m) => m !== null));
+}
+
+/** What a mark highlights: its series, or itself outside any series. */
+export const hlKeyOf = (s: Slot): string => s.series || s.m.id;

package/src/graph/icons.ts

@@ -0,0 +1,23 @@
+// The graph's own icons: a cluster that repeats, and an inner view.
+import { html } from 'lit';
+
+/** A cycle: a circle that comes back round to where it started, its head at the top right. */
+export const cycleIcon = (size = 14) =>
+  html`<svg class="ic loop-ic" width=${size} height=${size} viewBox="0 0 16 16" aria-hidden="true" focusable="false">
+    <path d="M12.7,9.71 A5,5 0 1 1 11.21,4.17" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"></path>
+    <path d="M12.44,5.2 L9.15,5.06 L11.73,2 z" fill="currentColor"></path>
+  </svg>`;
+
+/** Something with an inner view: two cards, one behind the other, as a node with one is drawn. */
+export const innerIcon = () =>
+  html`<svg class="ic in-ic" width="12" height="12" viewBox="0 0 12 12" aria-hidden="true" focusable="false">
+    <rect x="3.4" y="0.7" width="7.9" height="7.9" rx="1.6" fill="none" stroke="currentColor" stroke-width="1.2"></rect>
+    <path d="M0.7,3.6 V9.7 Q0.7,11.3 2.3,11.3 H8.4" fill="none" stroke="currentColor" stroke-width="1.2" stroke-linecap="round"></path>
+  </svg>`;
+
+/** Show inside (a plus) or hide inside (a minus), in a square: the control of an item that can be drawn open. */
+export const toggleIcon = (open: boolean) =>
+  html`<svg class="ic tog-ic" width="12" height="12" viewBox="0 0 12 12" aria-hidden="true" focusable="false">
+    <rect x="0.7" y="0.7" width="10.6" height="10.6" rx="2.2" fill="none" stroke="currentColor" stroke-width="1.2"></rect>
+    <path d=${open ? 'M3.5,6 H8.5' : 'M3.5,6 H8.5 M6,3.5 V8.5'} fill="none" stroke="currentColor" stroke-width="1.3" stroke-linecap="round"></path>
+  </svg>`;

package/src/graph/index.ts

@@ -0,0 +1,16 @@
+// A layered graph: `@contraagent/elements/graph`. `CaeLayeredGraph` is registered
+// by `@contraagent/elements/graph/define` (with the elements it renders).
+export * from './types.js';
+export { arrange, extentOf, isPoint, orderRows, rankLayers, type GraphShape } from './arrange.js';
+export * from './layout.js';
+export * from './paths.js';
+export * from './view.js';
+export * from './nav.js';
+export * from './marks.js';
+export * from './place-card.js';
+export * from './pan-zoom.js';
+export * from './card.js';
+export * from './icons.js';
+export * from './strings.js';
+export * from './styles.js';
+export * from './layered-graph.js';