@nysds/playground 0.1.0

package/src/home.ts

@@ -0,0 +1,225 @@
+/**
+ * The home view: the list of decks in this browser and the ways to add one.
+ */
+import type {StoredDeck} from './deck-model';
+import {relativeTime} from './deck-model';
+
+/** Marks the one action whose glyph the design system does not ship. */
+const PLAY_ICON = 'play';
+
+/** Makes a deck id safe to put in an element id. */
+function slug(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_-]/g, '-');
+}
+
+/** What the home view asks the application to do. */
+export interface HomeActions {
+  /** Opens a deck in the editor. */
+  open(id: string): void;
+  /** Opens a deck in presentation mode. */
+  present(id: string): void;
+  /** Copies a deck. */
+  duplicate(id: string): Promise<void>;
+  /** Downloads a deck as JSON. */
+  exportDeck(id: string): Promise<void>;
+  /** Asks to delete a deck, confirming first. */
+  remove(deck: StoredDeck): void;
+  /** Creates a deck from a title the person types. */
+  create(): void;
+  /** Imports one or more JSON files. */
+  importFiles(files: FileList | File[]): Promise<void>;
+  /** Adds back any bundled deck the store is missing. */
+  restoreStarters(): Promise<void>;
+  /** Opens the editor with no deck. */
+  scratch(): void;
+  /** Opens the settings modal. */
+  openSettings(): void;
+}
+
+/** Renders and drives the home view. */
+export class HomeView {
+  private readonly root: HTMLElement;
+  private readonly list: HTMLElement;
+  private readonly fileInput: HTMLInputElement;
+  private readonly actions: HomeActions;
+
+  constructor(actions: HomeActions) {
+    this.actions = actions;
+    this.root = required('#home');
+    this.list = required('#deck-list');
+    this.fileInput = required<HTMLInputElement>('#import-file');
+    this.bind();
+  }
+
+  /** Shows the home view and hides the editor. */
+  show(decks: StoredDeck[]): void {
+    document.querySelector('#app')?.classList.add('app--home');
+    this.root.hidden = false;
+    document.title = 'NYSDS Playground';
+    this.render(decks);
+  }
+
+  /** Draws the deck cards. */
+  render(decks: StoredDeck[]): void {
+    this.list.replaceChildren();
+    if (decks.length === 0) {
+      const empty = document.createElement('p');
+      empty.className = 'home__empty';
+      empty.textContent = 'No decks yet. Create one, or restore the starter decks.';
+      this.list.append(empty);
+      return;
+    }
+    for (const deck of decks) {
+      this.list.append(this.card(deck));
+    }
+  }
+
+  private card(deck: StoredDeck): HTMLElement {
+    const column = document.createElement('div');
+    column.className =
+      'nys-mobile-lg:nys-grid-col-6 nys-tablet:nys-grid-col-4 nys-display-flex';
+
+    const card = document.createElement('nys-card');
+    // The heading is rendered in the default slot instead of through the
+    // `heading` property, because the property takes plain text and the title
+    // has to be a link.
+    const firstSlide = deck.slides[0]?.id ?? '';
+    const heading = document.createElement('h2');
+    heading.className = 'deck-card__title';
+    const link = document.createElement('a');
+    link.href = `?deck=${encodeURIComponent(deck.id)}&present=1#preset=${encodeURIComponent(firstSlide)}`;
+    link.textContent = deck.title;
+    heading.append(link);
+
+    const meta = document.createElement('p');
+    meta.className = 'deck-card__meta';
+    const slides = deck.slides.length === 1 ? '1 slide' : `${deck.slides.length} slides`;
+    meta.textContent = `${slides} · updated ${relativeTime(deck.updatedAt)}`;
+    card.append(heading, meta);
+
+    if (deck.description) {
+      const description = document.createElement('p');
+      description.className = 'deck-card__description';
+      description.textContent = deck.description;
+      card.append(description);
+    }
+
+    const footer = document.createElement('div');
+    footer.slot = 'footer';
+    footer.className = 'deck-card__actions';
+    footer.append(this.action('Edit', 'filled', () => this.actions.open(deck.id)));
+    footer.append(
+      ...this.circle(deck.id, 'Present', PLAY_ICON, () => this.actions.present(deck.id)),
+      ...this.circle(deck.id, 'Duplicate', 'content_copy', () =>
+        void this.actions.duplicate(deck.id),
+      ),
+      ...this.circle(deck.id, 'Export', 'download', () =>
+        void this.actions.exportDeck(deck.id),
+      ),
+      ...this.circle(deck.id, 'Delete', 'delete', () => this.actions.remove(deck)),
+    );
+    card.append(footer);
+    column.append(card);
+    return column;
+  }
+
+  private action(label: string, variant: string, handler: () => void): HTMLElement {
+    const button = document.createElement('nys-button');
+    button.setAttribute('label', label);
+    button.setAttribute('size', 'sm');
+    button.setAttribute('variant', variant);
+    button.addEventListener('nys-click', handler);
+    return button;
+  }
+
+  /**
+   * Builds one icon-only action and the tooltip that names it.
+   *
+   * `label` is the accessible name, which circle buttons render as
+   * visually hidden text, so the tooltip is the only visible hint.
+   */
+  private circle(
+    deckId: string,
+    label: string,
+    icon: string,
+    handler: () => void,
+  ): HTMLElement[] {
+    const id = `deck-${slug(deckId)}-${label.toLowerCase()}`;
+    const tooltip = document.createElement('nys-tooltip');
+    tooltip.setAttribute('for', id);
+    tooltip.setAttribute('text', label);
+
+    const button = document.createElement('nys-button');
+    button.id = id;
+    button.setAttribute('circle', '');
+    button.setAttribute('size', 'sm');
+    button.setAttribute('variant', 'outline');
+    button.setAttribute('label', label);
+    if (icon === PLAY_ICON) {
+      // NYSDS ships no play glyph, so this one comes in through the slot.
+      const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+      svg.setAttribute('slot', 'circle-icon');
+      svg.setAttribute('class', 'deck-card__play');
+      svg.setAttribute('viewBox', '0 -960 960 960');
+      svg.setAttribute('fill', 'currentColor');
+      svg.setAttribute('aria-hidden', 'true');
+      const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+      path.setAttribute('d', 'M320-200v-560l440 280-440 280Z');
+      svg.append(path);
+      button.append(svg);
+    } else {
+      button.setAttribute('icon', icon);
+    }
+    button.addEventListener('nys-click', handler);
+    return [tooltip, button];
+  }
+
+  private bind(): void {
+    on('#new-deck-button', () => this.actions.create());
+    on('#import-deck-button', () => this.fileInput.click());
+    on('#scratch-button', () => this.actions.scratch());
+    on('#restore-starters-button', () => void this.actions.restoreStarters());
+    on('#home-settings-button', () => this.actions.openSettings());
+
+    this.fileInput.addEventListener('change', () => {
+      const files = this.fileInput.files;
+      if (files && files.length > 0) {
+        void this.actions.importFiles(files);
+      }
+      // Clear the value so choosing the same file twice still fires.
+      this.fileInput.value = '';
+    });
+
+    // Dropping a deck file anywhere on the home view imports it.
+    const stop = (event: DragEvent): void => {
+      event.preventDefault();
+    };
+    this.root.addEventListener('dragover', (event) => {
+      stop(event);
+      this.root.classList.add('home--dragging');
+    });
+    this.root.addEventListener('dragleave', () => {
+      this.root.classList.remove('home--dragging');
+    });
+    this.root.addEventListener('drop', (event) => {
+      stop(event);
+      this.root.classList.remove('home--dragging');
+      const files = event.dataTransfer?.files;
+      if (files && files.length > 0) {
+        void this.actions.importFiles(files);
+      }
+    });
+  }
+}
+
+function on(selector: string, handler: () => void): void {
+  document.querySelector(selector)?.addEventListener('nys-click', handler);
+}
+
+function required<T extends HTMLElement = HTMLElement>(selector: string): T {
+  const element = document.querySelector<T>(selector);
+  if (!element) {
+    throw new Error(`The page is missing the element "${selector}".`);
+  }
+  return element;
+}

package/src/icon-names.ts

@@ -0,0 +1,117 @@
+/**
+ * The icon names that ship with NYSDS.
+ *
+ * NYSDS bundles a curated subset of Material Symbols, not the whole set. An
+ * icon name outside this list renders as empty space. Source:
+ * https://designsystem.ny.gov/components/icon/ and the icon library in
+ * @nysds/components 1.21.0. Update this list when a release adds icons.
+ */
+export const NYSDS_ICON_NAMES: ReadonlySet<string> = new Set([
+  'ac_unit',
+  'account_balance_filled',
+  'account_circle',
+  'add',
+  'air',
+  'arrow_back',
+  'arrow_downward',
+  'arrow_forward',
+  'arrow_upward',
+  'attach_file',
+  'calendar_month',
+  'cancel',
+  'cancel_filled',
+  'check',
+  'check_circle',
+  'chevron_down',
+  'chevron_left',
+  'chevron_right',
+  'chevron_up',
+  'clear_day',
+  'close',
+  'code',
+  'content_copy',
+  'coronavirus',
+  'delete',
+  'download',
+  'download_done',
+  'drive_folder_upload',
+  'edit_square',
+  'emergency_home',
+  'error',
+  'expand_all',
+  'filter_alt',
+  'filter_list',
+  'height',
+  'help',
+  'info',
+  'language',
+  'language_filled',
+  'link',
+  'location_on',
+  'lock_filled',
+  'mail',
+  'menu',
+  'more_vert',
+  'notifications',
+  'open_in_new',
+  'phone_in_talk',
+  'print',
+  'progress_activity',
+  'publish',
+  'rainy',
+  'refresh',
+  'remove',
+  'schedule',
+  'search',
+  'share',
+  'sms',
+  'social_bluesky',
+  'social_facebook',
+  'social_flickr',
+  'social_google_play',
+  'social_instagram',
+  'social_linkedin',
+  'social_pinterest',
+  'social_rss',
+  'social_snapchat',
+  'social_soundcloud',
+  'social_threads',
+  'social_tiktok',
+  'social_tumblr',
+  'social_vimeo',
+  'social_x',
+  'social_youtube',
+  'sort',
+  'straight',
+  'thumb_down',
+  'thumb_up',
+  'upload_file',
+  'visibility',
+  'visibility_off',
+  'warning',
+]);
+
+/** Attribute names whose values are icon names. */
+export const ICON_ATTRIBUTES = ['icon', 'prefixIcon', 'suffixIcon'] as const;
+
+/**
+ * Finds icon names used in a chunk of HTML: `icon`, `prefixIcon`, and
+ * `suffixIcon` attributes on any element, plus `name` on `<nys-icon>`.
+ */
+export function findIconNames(html: string): string[] {
+  const found: string[] = [];
+  const attrPattern = /\b(?:icon|prefixIcon|suffixIcon)\s*=\s*"([^"]*)"/gi;
+  for (const match of html.matchAll(attrPattern)) {
+    found.push(match[1]);
+  }
+  const nysIconPattern = /<nys-icon\b[^>]*\bname\s*=\s*"([^"]*)"/gi;
+  for (const match of html.matchAll(nysIconPattern)) {
+    found.push(match[1]);
+  }
+  return found;
+}
+
+/** Returns the icon names in `html` that NYSDS does not ship. */
+export function unknownIconNames(html: string): string[] {
+  return findIconNames(html).filter((name) => name !== '' && !NYSDS_ICON_NAMES.has(name));
+}

package/src/icons.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Fails when the shell, a preset, or a deck uses an icon NYSDS doesn't ship.
+ *
+ * A missing icon renders as empty space, which looks broken on a projector.
+ */
+import assert from 'node:assert/strict';
+import {readFileSync, readdirSync} from 'node:fs';
+import {join} from 'node:path';
+import test from 'node:test';
+
+import {findIconNames, unknownIconNames} from './icon-names.ts';
+
+const ROOT = join(import.meta.dirname, '..');
+
+/** Reads every `.json` file in a directory and yields its name and text. */
+function jsonFiles(dir: string): Array<{name: string; text: string}> {
+  return readdirSync(join(ROOT, dir))
+    .filter((file) => file.endsWith('.json'))
+    .map((file) => ({name: `${dir}/${file}`, text: readFileSync(join(ROOT, dir, file), 'utf8')}));
+}
+
+/** Pulls every string value out of parsed JSON, however deeply nested. */
+function stringValues(value: unknown): string[] {
+  if (typeof value === 'string') {
+    return [value];
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap(stringValues);
+  }
+  if (value && typeof value === 'object') {
+    return Object.values(value).flatMap(stringValues);
+  }
+  return [];
+}
+
+test('findIconNames reads icon attributes and nys-icon names', () => {
+  const html =
+    '<nys-button prefixIcon="refresh"></nys-button>' +
+    '<nys-button circle icon="close" label="x"></nys-button>' +
+    '<nys-icon name="info"></nys-icon>' +
+    '<nys-checkbox name="terms"></nys-checkbox>';
+  assert.deepEqual(findIconNames(html), ['refresh', 'close', 'info']);
+  assert.deepEqual(unknownIconNames('<nys-button prefixIcon="restart_alt">'), ['restart_alt']);
+});
+
+test('index.html uses only NYSDS icons', () => {
+  const html = readFileSync(join(ROOT, 'index.html'), 'utf8');
+  assert.deepEqual(unknownIconNames(html), []);
+});
+
+for (const dir of ['presets', 'decks']) {
+  for (const file of jsonFiles(dir)) {
+    test(`${file.name} uses only NYSDS icons`, () => {
+      const markup = stringValues(JSON.parse(file.text)).join('\n');
+      assert.deepEqual(unknownIconNames(markup), []);
+    });
+  }
+}

package/src/keys.ts

@@ -0,0 +1,162 @@
+/**
+ * Key routing for presentation mode.
+ *
+ * The presenter edits code on the slide, so plain arrow keys have to reach the
+ * editor. These helpers decide when a key means "change slide" and when it
+ * means "move the caret". They take plain data so `src/state.test.ts` can
+ * exercise them without a DOM.
+ */
+
+import type {PaneId} from './preset-schema';
+
+/** Asks presentation mode to collapse or expand one editor column. */
+export type TogglePaneAction = `toggle-pane:${PaneId}`;
+
+/** What a key press asks presentation mode to do. */
+export type PresentationAction =
+  | 'next'
+  | 'prev'
+  | 'first'
+  | 'last'
+  | 'toggle-code'
+  | 'toggle-notes'
+  | 'toggle-theme'
+  | 'toggle-layout'
+  | TogglePaneAction
+  | 'exit';
+
+/** The column each number key toggles in the side-by-side layout. */
+const PANE_KEYS: Record<string, PaneId> = {'1': 'html', '2': 'css', '3': 'js'};
+
+/** The parts of a `KeyboardEvent` that routing depends on. */
+export interface KeyLike {
+  key: string;
+  altKey: boolean;
+  ctrlKey: boolean;
+  metaKey: boolean;
+}
+
+/**
+ * Reports whether a key press asks for an immediate preview rebuild.
+ *
+ * `Cmd/Ctrl+Enter` and `Cmd/Ctrl+S` work everywhere, including mid-edit, so the
+ * presenter never has to leave the editor to see a change.
+ */
+export function isBuildShortcut(event: KeyLike): boolean {
+  if (!event.ctrlKey && !event.metaKey) {
+    return false;
+  }
+  return event.key === 'Enter' || event.key === 's' || event.key === 'S';
+}
+
+/** Elements whose key presses belong to the person typing, not to the deck. */
+const TYPING_TAGS = new Set([
+  'playground-file-editor',
+  'playground-code-editor',
+  'input',
+  'textarea',
+  'select',
+]);
+
+/**
+ * Reports whether a key press landed in something the presenter is typing in.
+ *
+ * Pass the lowercase tag names from the event's `composedPath()`, which
+ * crosses shadow roots and so sees the CodeMirror editor inside
+ * `playground-file-editor`.
+ */
+export function isTypingContext(pathTagNames: readonly string[]): boolean {
+  return pathTagNames.some((tag) => TYPING_TAGS.has(tag));
+}
+
+/** Maps `ArrowRight` and friends to a step, or returns `null`. */
+function stepFor(key: string): PresentationAction | null {
+  switch (key) {
+    case 'ArrowRight':
+    case 'ArrowDown':
+      return 'next';
+    case 'ArrowLeft':
+    case 'ArrowUp':
+      return 'prev';
+    default:
+      return null;
+  }
+}
+
+/**
+ * Decides what a key press does.
+ *
+ * `Alt` plus an arrow steps the deck from anywhere, including mid-edit. Every
+ * other shortcut is ignored while the presenter is typing, so the editor keeps
+ * its own arrow keys, space bar, and Escape.
+ *
+ * Set `columns` when the side-by-side layout is on. The number keys toggle a
+ * column only then, so they stay free otherwise.
+ */
+export function routeKey(
+  event: KeyLike,
+  typing: boolean,
+  columns = false,
+): PresentationAction | null {
+  if (event.ctrlKey || event.metaKey) {
+    return null;
+  }
+  if (event.altKey) {
+    return stepFor(event.key);
+  }
+  if (typing) {
+    return null;
+  }
+  const step = stepFor(event.key);
+  if (step) {
+    return step;
+  }
+  switch (event.key) {
+    case 'PageDown':
+    case ' ':
+      return 'next';
+    case 'PageUp':
+      return 'prev';
+    case 'Home':
+      return 'first';
+    case 'End':
+      return 'last';
+    case 'Escape':
+      return 'exit';
+    case 'c':
+    case 'C':
+      return 'toggle-code';
+    case 'n':
+    case 'N':
+      return 'toggle-notes';
+    case 't':
+    case 'T':
+      return 'toggle-theme';
+    case 'e':
+    case 'E':
+      return 'toggle-layout';
+    default:
+      break;
+  }
+  const pane = columns ? PANE_KEYS[event.key] : undefined;
+  return pane ? `toggle-pane:${pane}` : null;
+}
+
+/**
+ * Builds the on-screen hint.
+ *
+ * Notes are left out when the slide has none, and the column shortcuts only
+ * appear in the side-by-side layout.
+ */
+export function hintText(hasNotes: boolean, columns: boolean): string {
+  const parts = ['← → or Alt+← → to change slides', 'c code', 'e layout'];
+  if (columns) {
+    parts.push('1 2 3 panes');
+  }
+  parts.push('t theme');
+  if (hasNotes) {
+    parts.push('n notes');
+  }
+  parts.push('Esc exit');
+  return parts.join(' · ');
+}