@nysds/playground 0.1.0

package/src/present.ts

@@ -0,0 +1,398 @@
+/**
+ * Presentation mode.
+ *
+ * With `?present=1` the toolbar is hidden and the preview fills most of the
+ * viewport, but the editors stay visible and editable so the presenter can
+ * change a slide live. A caption bar at the bottom names the slide and carries
+ * the controls.
+ */
+import type {Slide, StoredDeck} from './deck-model';
+import {slideIndex} from './deck-model';
+import type {EditorPanes} from './editor-panes';
+import type {PaneId} from './editors';
+import {PANE_IDS} from './editors';
+import type {PresentationAction} from './keys';
+import {hintText, isTypingContext, routeKey} from './keys';
+import {applyEditorTheme, initialTheme, otherTheme, themeUrl, writeTheme} from './theme';
+import {STORAGE_KEYS, readKey, writeKey} from './settings';
+import {presentUrl} from './state';
+
+/** What presentation mode needs from the application shell. */
+export interface PresentationTarget {
+  /** Records whether the playground is presenting. */
+  setPresent(present: boolean): void;
+  /** The deck being presented. */
+  getDeck(): StoredDeck;
+  /** The id of the slide on screen, or `null` for a shared code link. */
+  getActivePresetId(): string | null;
+  /** Loads a slide, restoring any edits made to it earlier in the session. */
+  loadPreset(preset: Slide): void;
+  /** Discards this session's edits to the current slide. */
+  resetSlide(): void;
+}
+
+/** How long the keyboard hint stays on screen, in milliseconds. */
+const HINT_DURATION_MS = 6000;
+
+
+
+/** Drives the slideshow. */
+export class Presentation {
+  private readonly target: PresentationTarget;
+  private readonly app: HTMLElement;
+  private readonly caption: HTMLElement;
+  private readonly group: HTMLElement;
+  private readonly title: HTMLElement;
+  private readonly description: HTMLElement;
+  private readonly hint: HTMLElement;
+  private readonly notes: HTMLElement;
+  private readonly notesBody: HTMLElement;
+  private readonly notesButton: HTMLElement;
+  private readonly panes: EditorPanes;
+  private collapsed = false;
+  private notesOpen = false;
+  private presenting = false;
+
+  constructor(
+    target: PresentationTarget,
+    panes: EditorPanes,
+    root: Document | HTMLElement = document,
+  ) {
+    this.target = target;
+    this.panes = panes;
+    this.app = required(root, '#app');
+    this.caption = required(root, '#caption');
+    this.group = required(root, '#caption-group');
+    this.title = required(root, '#caption-title');
+    this.description = required(root, '#caption-description');
+    this.hint = required(root, '#present-hint');
+    this.notes = required(root, '#notes');
+    this.notesBody = required(root, '#notes-body');
+    this.notesButton = required(root, '#notes-button');
+  }
+
+  /** Binds the slide bar, then enters presentation mode when asked. */
+  start(present: boolean): void {
+    this.collapsed = readCollapsed();
+    this.applyCollapsed();
+    this.hidePreviewToolbar();
+    bindClick('#prev-button', () => this.step(-1));
+    bindClick('#next-button', () => this.step(1));
+    bindClick('#reset-slide-button', () => {
+      this.target.resetSlide();
+      this.refresh();
+      this.takeFocus();
+    });
+    bindClick('#notes-button', () => this.toggleNotes());
+    bindClick('#notes-close', () => this.closeNotes());
+    window.addEventListener('keydown', (event) => this.onKeyDown(event), true);
+    this.refresh();
+    if (present) {
+      this.setPresenting(true);
+    }
+  }
+
+  /**
+   * Enters presentation mode.
+   *
+   * The page is not reloaded, so the click that asked for it still counts as
+   * the user gesture that fullscreen requires.
+   */
+  enter(): void {
+    void document.documentElement.requestFullscreen?.().catch(() => undefined);
+    this.setPresenting(true);
+    this.takeFocus();
+  }
+
+  /** Leaves presentation mode, keeping the deck and slide in the URL. */
+  exit(): void {
+    if (document.fullscreenElement) {
+      void document.exitFullscreen?.().catch(() => undefined);
+    }
+    this.setPresenting(false);
+  }
+
+  /** Whether the playground is presenting. */
+  get isPresenting(): boolean {
+    return this.presenting;
+  }
+
+  private setPresenting(presenting: boolean): void {
+    this.presenting = presenting;
+    this.app.classList.toggle('app--present', presenting);
+    this.hint.hidden = true;
+    this.hint.classList.remove('present-hint--fading');
+    if (presenting) {
+      this.showHint();
+    } else {
+      this.closeNotes();
+    }
+    this.target.setPresent(presenting);
+    window.history.replaceState(null, '', presentUrl(presenting));
+    this.refresh();
+  }
+
+  /** Redraws the caption and the notes from whatever is currently loaded. */
+  refresh(): void {
+    const deck = this.target.getDeck();
+    const id = this.target.getActivePresetId();
+    const index = slideIndex(deck, id);
+    const preset = index >= 0 ? deck.slides[index] : undefined;
+    this.group.textContent = preset?.group ?? '';
+    this.title.textContent = preset?.title ?? 'Custom code';
+    this.description.textContent = preset?.description ?? '';
+    const counter =
+      deck.slides.length === 0
+        ? ''
+        : `${index >= 0 ? index + 1 : '—'} / ${deck.slides.length}`;
+    // One counter sits with the icons and another rides with the title on
+    // narrow screens; only one of them is ever visible.
+    for (const element of document.querySelectorAll<HTMLElement>('[data-count]')) {
+      element.textContent = counter;
+    }
+
+    const notes = preset?.notes ?? '';
+    this.notesBody.textContent = notes;
+    this.notesButton.hidden = notes === '';
+    // The tooltip has to go with its trigger, or it names a button nobody can
+    // see.
+    const notesTooltip = document.querySelector<HTMLElement>('nys-tooltip[for="notes-button"]');
+    if (notesTooltip) {
+      notesTooltip.hidden = notes === '';
+    }
+    if (!notes) {
+      this.closeNotes();
+    }
+    this.hint.textContent = hintText(notes !== '', this.panes.layout === 'columns');
+  }
+
+  /** Moves to the slide at `index`, clamped to the deck. */
+  goTo(index: number): void {
+    const deck = this.target.getDeck();
+    if (deck.slides.length === 0) {
+      return;
+    }
+    const clamped = Math.min(Math.max(index, 0), deck.slides.length - 1);
+    const preset = deck.slides[clamped];
+    if (preset) {
+      this.closeNotes();
+      this.target.loadPreset(preset);
+      this.refresh();
+      this.takeFocus();
+    }
+  }
+
+  private step(delta: number): void {
+    const deck = this.target.getDeck();
+    const current = slideIndex(deck, this.target.getActivePresetId());
+    // From a shared code link, stepping forward starts the deck and stepping
+    // back lands on the last slide.
+    const next = current === -1 ? (delta > 0 ? 0 : deck.slides.length - 1) : current + delta;
+    this.goTo(next);
+  }
+
+  private onKeyDown(event: KeyboardEvent): void {
+    // A dialog owns the keyboard while it is open, including its own Escape.
+    // Read the property rather than the attribute: the attribute only lands on
+    // the component's next render, which is a frame too late.
+    if (anyModalOpen()) {
+      return;
+    }
+    // While editing, these keys belong to the slide bar. Alt plus an arrow
+    // still steps from anywhere, as it does while presenting.
+    if (!this.presenting && !event.altKey && !this.caption.contains(event.target as Node)) {
+      return;
+    }
+    const typing = isTypingContext(tagNamesFor(event));
+    const action = routeKey(event, typing, this.panes.layout === 'columns');
+    if (action === null) {
+      return;
+    }
+    // Escape closes the notes before it leaves presentation mode.
+    if (action === 'exit' && this.notesOpen) {
+      event.preventDefault();
+      this.closeNotes();
+      this.takeFocus();
+      return;
+    }
+    event.preventDefault();
+    this.run(action);
+  }
+
+  private run(action: PresentationAction): void {
+    switch (action) {
+      case 'next':
+        this.step(1);
+        break;
+      case 'prev':
+        this.step(-1);
+        break;
+      case 'first':
+        this.goTo(0);
+        break;
+      case 'last':
+        this.goTo(this.target.getDeck().slides.length - 1);
+        break;
+      case 'toggle-code':
+        this.toggleCode();
+        break;
+      case 'toggle-notes':
+        this.toggleNotes();
+        break;
+      case 'toggle-layout':
+        this.panes.toggleLayout();
+        this.refresh();
+        this.takeFocus();
+        break;
+      case 'toggle-theme':
+        this.toggleTheme();
+        break;
+      case 'exit':
+        this.exit();
+        break;
+      default: {
+        const pane = paneFor(action);
+        if (pane) {
+          this.panes.togglePane(pane);
+          this.takeFocus();
+        }
+        break;
+      }
+    }
+  }
+
+  /** Switches the editors between light and dark and remembers the choice. */
+  private toggleTheme(): void {
+    const next = otherTheme(initialTheme());
+    applyEditorTheme(next);
+    writeTheme(next);
+    window.history.replaceState(null, '', themeUrl(next, window.location.href));
+    this.takeFocus();
+  }
+
+  private toggleCode(): void {
+    this.collapsed = !this.collapsed;
+    this.applyCollapsed();
+    writeCollapsed(this.collapsed);
+    this.takeFocus();
+  }
+
+  private applyCollapsed(): void {
+    this.app.classList.toggle('app--code-collapsed', this.collapsed);
+  }
+
+  private toggleNotes(): void {
+    if (this.notesOpen) {
+      this.closeNotes();
+      this.takeFocus();
+      return;
+    }
+    if (!this.notesBody.textContent) {
+      return;
+    }
+    this.notesOpen = true;
+    this.notes.hidden = false;
+    this.notes.focus?.();
+  }
+
+  private closeNotes(): void {
+    this.notesOpen = false;
+    this.notes.hidden = true;
+  }
+
+  /**
+   * Moves focus to the caption bar.
+   *
+   * The preview is a cross-origin iframe. Once it holds focus, key events go
+   * to the sandbox instead of this page, so the deck stops responding to the
+   * arrow keys. Reclaiming focus after every step keeps them working. After an
+   * edit, focus stays in the editor, which is what the presenter wants.
+   */
+  private takeFocus(): void {
+    this.caption.focus({preventScroll: true});
+  }
+
+  /**
+   * Hides the preview's own header bar so the slide fills the screen.
+   *
+   * `playground-preview` exposes no CSS part for the bar, so the rule goes
+   * into its shadow root. Setting `--playground-bar-height` alone leaves the
+   * label and the reload button visible.
+   */
+  private hidePreviewToolbar(): void {
+    const root = document.querySelector('#preview')?.shadowRoot;
+    if (!root) {
+      return;
+    }
+    try {
+      const sheet = new CSSStyleSheet();
+      sheet.replaceSync('#toolbar { display: none; }');
+      root.adoptedStyleSheets = [...root.adoptedStyleSheets, sheet];
+    } catch {
+      // Constructable stylesheets are optional. The bar is only cosmetic.
+    }
+  }
+
+  private showHint(): void {
+    this.hint.hidden = false;
+    window.setTimeout(() => {
+      this.hint.classList.add('present-hint--fading');
+      window.setTimeout(() => {
+        this.hint.hidden = true;
+      }, 700);
+    }, HINT_DURATION_MS);
+  }
+}
+
+/** Returns the column a `toggle-pane:` action names, or `undefined`. */
+function paneFor(action: PresentationAction): PaneId | undefined {
+  const prefix = 'toggle-pane:';
+  if (typeof action !== 'string' || !action.startsWith(prefix)) {
+    return undefined;
+  }
+  const pane = action.slice(prefix.length);
+  return PANE_IDS.find((candidate) => candidate === pane);
+}
+
+/** Returns the lowercase tag names on a key event's composed path. */
+function tagNamesFor(event: KeyboardEvent): string[] {
+  const path = typeof event.composedPath === 'function' ? event.composedPath() : [];
+  const names: string[] = [];
+  for (const node of path) {
+    const tag = (node as Element).tagName;
+    if (typeof tag === 'string') {
+      names.push(tag.toLowerCase());
+    }
+  }
+  if (names.length === 0 && event.target instanceof Element) {
+    names.push(event.target.tagName.toLowerCase());
+  }
+  return names;
+}
+
+function readCollapsed(): boolean {
+  return readKey(STORAGE_KEYS.codeCollapsed) === '1';
+}
+
+function writeCollapsed(collapsed: boolean): void {
+  writeKey(STORAGE_KEYS.codeCollapsed, collapsed ? '1' : '0');
+}
+
+/** Reports whether any design system dialog is on screen. */
+function anyModalOpen(): boolean {
+  return [...document.querySelectorAll('nys-modal')].some(
+    (modal) => (modal as HTMLElement & {open?: boolean}).open === true,
+  );
+}
+
+function bindClick(selector: string, handler: () => void): void {
+  document.querySelector(selector)?.addEventListener('nys-click', handler);
+}
+
+function required(root: Document | HTMLElement, selector: string): HTMLElement {
+  const element = root.querySelector<HTMLElement>(selector);
+  if (!element) {
+    throw new Error(`The page is missing the element "${selector}".`);
+  }
+  return element;
+}

package/src/preset-schema.ts

@@ -0,0 +1,228 @@
+/**
+ * Types and validation for preset and deck JSON.
+ *
+ * This module imports nothing, so `src/state.test.ts` can load it directly
+ * under `node --test`.
+ */
+
+/** One of the three editor columns. */
+export type PaneId = 'html' | 'css' | 'js';
+
+/** The editor columns, in the order they appear. */
+export const PANE_IDS: readonly PaneId[] = ['html', 'css', 'js'];
+
+/** One playground example. */
+export interface Preset {
+  /** The id used in `#preset=`. */
+  id: string;
+  /** The short name shown in the menu, the caption, and the page title. */
+  title: string;
+  /** One sentence shown in the presentation caption. */
+  description: string;
+  /** An optional section label, such as `1. Lock it down`. */
+  group: string;
+  /** Presenter notes. Never rendered in the preview. */
+  notes: string;
+  /** The HTML the example loads into the HTML tab. */
+  html: string;
+  /** The CSS the example loads into the CSS tab. */
+  css: string;
+  /** The JavaScript the example loads into the JS tab. */
+  js: string;
+  /** The design system version to switch to, or `latest`. */
+  version: string;
+  /**
+   * Which editor columns to expand when this example loads, as any of
+   * `"html"`, `"css"`, and `"js"`.
+   *
+   * It applies only to the side-by-side layout, and every column not listed is
+   * collapsed. An empty array collapses all three. `null` means the file left
+   * the field out, which leaves the current columns as they are.
+   */
+  editors: PaneId[] | null;
+}
+
+/** An ordered set of examples that presentation mode steps through. */
+export interface Deck {
+  /** The id used in `?deck=`. Derived from the filename. */
+  id: string;
+  /** The name shown in the deck menu. */
+  title: string;
+  /** One sentence describing the deck. */
+  description: string;
+  /** CSS injected into every slide's hidden head. */
+  baseCss: string;
+  /** The slides, in order. */
+  presets: Preset[];
+}
+
+/** Receives a validation message. Defaults to `console.error`. */
+export type Report = (message: string) => void;
+
+const defaultReport: Report = (message) => console.error(message);
+
+const defaultWarn: Report = (message) => console.warn(message);
+
+/** Turns `../presets/01-button.json` into `button`. */
+export function idFromPresetPath(path: string): string {
+  const filename = path.split('/').pop() ?? path;
+  return filename.replace(/\.json$/i, '').replace(/^\d+[-_]/, '');
+}
+
+/** Turns `../decks/styling-levels.json` into `styling-levels`. */
+export function idFromDeckPath(path: string): string {
+  const filename = path.split('/').pop() ?? path;
+  return filename.replace(/\.json$/i, '');
+}
+
+/** Reads a string field, reporting anything that is present but not a string. */
+function readString(
+  record: Record<string, unknown>,
+  key: string,
+  path: string,
+  fallback: string,
+  report: Report,
+): string {
+  const value = record[key];
+  if (typeof value === 'string') {
+    return value;
+  }
+  if (value !== undefined) {
+    report(`Preset "${path}" has a "${key}" field of type ${typeof value}. Expected a string.`);
+  }
+  return fallback;
+}
+
+/**
+ * Reads an optional `editors` array.
+ *
+ * Returns `null` when the field is absent. Entries that are not pane ids are
+ * reported and dropped, so one typo does not cost the whole example.
+ */
+function readPanes(
+  record: Record<string, unknown>,
+  path: string,
+  report: Report,
+): PaneId[] | null {
+  const value = record['editors'];
+  if (value === undefined) {
+    return null;
+  }
+  if (!Array.isArray(value)) {
+    report(
+      `Preset "${path}" has an "editors" field of type ${typeof value}. ` +
+        'Expected an array of "html", "css", or "js".',
+    );
+    return null;
+  }
+  const panes: PaneId[] = [];
+  for (const entry of value) {
+    if (typeof entry === 'string' && (PANE_IDS as readonly string[]).includes(entry)) {
+      if (!panes.includes(entry as PaneId)) {
+        panes.push(entry as PaneId);
+      }
+    } else {
+      report(
+        `Preset "${path}" lists ${JSON.stringify(entry)} in "editors". ` +
+          'Expected "html", "css", or "js". Ignoring it.',
+      );
+    }
+  }
+  return panes;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Validates one preset.
+ *
+ * `fallbackId` is the id derived from the filename. Library presets always use
+ * it; deck slides must carry their own `id`.
+ *
+ * Returns `null` when the file cannot be used at all.
+ */
+export function parsePreset(
+  path: string,
+  raw: unknown,
+  fallbackId: string | null,
+  report: Report = defaultReport,
+): Preset | null {
+  if (!isRecord(raw)) {
+    report(`Preset "${path}" is not a JSON object. Skipping it.`);
+    return null;
+  }
+  const id = fallbackId ?? readString(raw, 'id', path, '', report);
+  if (!id) {
+    report(`Preset "${path}" is missing the required string field "id". Skipping it.`);
+    return null;
+  }
+  if (raw['title'] === undefined) {
+    report(`Preset "${path}" is missing the required string field "title".`);
+  }
+  if (raw['html'] === undefined) {
+    report(`Preset "${path}" is missing the required string field "html".`);
+  }
+  return {
+    id,
+    title: readString(raw, 'title', path, id, report),
+    description: readString(raw, 'description', path, '', report),
+    group: readString(raw, 'group', path, '', report),
+    notes: readString(raw, 'notes', path, '', report),
+    html: readString(raw, 'html', path, '', report),
+    css: readString(raw, 'css', path, '', report),
+    js: readString(raw, 'js', path, '', report),
+    version: readString(raw, 'version', path, 'latest', report) || 'latest',
+    editors: readPanes(raw, path, report),
+  };
+}
+
+/**
+ * Validates one deck file. Returns `null` when the file is unusable.
+ *
+ * `report` receives errors; `warn` receives advisories, such as a deck that
+ * still carries a `boilerplate.head` key.
+ */
+export function parseDeck(
+  path: string,
+  raw: unknown,
+  report: Report = defaultReport,
+  warn: Report = defaultWarn,
+): Deck | null {
+  if (!isRecord(raw)) {
+    report(`Deck "${path}" is not a JSON object. Skipping it.`);
+    return null;
+  }
+  const id = idFromDeckPath(path);
+  const rawPresets = raw['presets'];
+  if (!Array.isArray(rawPresets) || rawPresets.length === 0) {
+    report(`Deck "${path}" needs a non-empty "presets" array. Skipping it.`);
+    return null;
+  }
+  const boilerplate = isRecord(raw['boilerplate']) ? raw['boilerplate'] : {};
+  if (boilerplate['head'] !== undefined) {
+    warn(
+      `Deck "${path}" sets "boilerplate.head", which the playground ignores. ` +
+        'The playground already loads the design system, and the version menu controls it.',
+    );
+  }
+  const presets: Preset[] = [];
+  rawPresets.forEach((entry, index) => {
+    const preset = parsePreset(`${path}#presets[${index}]`, entry, null, report);
+    if (preset) {
+      presets.push(preset);
+    }
+  });
+  if (presets.length === 0) {
+    report(`Deck "${path}" has no usable presets. Skipping it.`);
+    return null;
+  }
+  return {
+    id,
+    title: readString(raw, 'title', path, id, report),
+    description: readString(raw, 'description', path, '', report),
+    baseCss: typeof boilerplate['baseCss'] === 'string' ? boilerplate['baseCss'] : '',
+    presets,
+  };
+}

package/src/route.test.ts

@@ -0,0 +1,56 @@
+/** Checks the view a URL asks for and when history moves need a reboot. */
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {needsReboot, routeFor, sameRoute, slideIdFromHash} from './routing.ts';
+
+test('a bare URL lands on the home page', () => {
+  assert.deepEqual(routeFor('', ''), {kind: 'home'});
+  assert.deepEqual(routeFor('?theme=dark', ''), {kind: 'home'});
+  assert.deepEqual(routeFor('?present=1', ''), {kind: 'home'});
+});
+
+test('a deck id opens that deck', () => {
+  assert.deepEqual(routeFor('?deck=styling-levels', ''), {
+    kind: 'deck',
+    id: 'styling-levels',
+  });
+  assert.deepEqual(routeFor('?deck=a&present=1', '#preset=b'), {kind: 'deck', id: 'a'});
+});
+
+test('a shared hash without a deck opens the scratch pad', () => {
+  assert.deepEqual(routeFor('', '#code=N4Igb'), {kind: 'scratch'});
+  assert.deepEqual(routeFor('', '#preset=button'), {kind: 'scratch'});
+  assert.deepEqual(routeFor('?theme=dark', '#code=x'), {kind: 'scratch'});
+});
+
+test('moving between views needs a reboot', () => {
+  const home = routeFor('', '');
+  const scratch = routeFor('', '#code=x');
+  const deck = routeFor('?deck=a', '#preset=one');
+  const other = routeFor('?deck=b', '');
+
+  assert.equal(needsReboot(home, scratch), true);
+  assert.equal(needsReboot(scratch, home), true);
+  assert.equal(needsReboot(home, deck), true);
+  assert.equal(needsReboot(deck, other), true);
+});
+
+test('moving between slides of one deck does not', () => {
+  const first = routeFor('?deck=a', '#preset=one');
+  const second = routeFor('?deck=a&present=1', '#preset=two');
+  assert.equal(needsReboot(first, second), false);
+  assert.equal(sameRoute(first, second), true);
+});
+
+test('the home page stays the home page whatever the settings say', () => {
+  assert.equal(needsReboot(routeFor('', ''), routeFor('?theme=dark&font=large', '')), false);
+});
+
+test('slideIdFromHash reads only a preset hash', () => {
+  assert.equal(slideIdFromHash('#preset=01-a'), '01-a');
+  assert.equal(slideIdFromHash('preset=01-a'), '01-a');
+  assert.equal(slideIdFromHash('#code=abc'), null);
+  assert.equal(slideIdFromHash(''), null);
+  assert.equal(slideIdFromHash('#preset='), null);
+});