@nysds/playground 0.1.0

package/src/decks.test.ts

@@ -0,0 +1,288 @@
+/**
+ * Checks for the deck model and the route decision.
+ *
+ * These cover the parts of the store that do not need IndexedDB: id
+ * generation, collision handling, import normalization, the export shape, and
+ * seed diffing.
+ */
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  copyOfDeck,
+  makeDeck,
+  makeSlide,
+  missingStarters,
+  nextSlideId,
+  normalizeImport,
+  relativeTime,
+  slideIndex,
+  slugify,
+  staleStarters,
+  toDeckFile,
+  uniqueId,
+} from './deck-model.ts';
+import type {StoredDeck} from './deck-model.ts';
+
+const NOW = new Date('2026-09-16T12:00:00.000Z');
+
+function deck(id: string, extra: Partial<StoredDeck> = {}): StoredDeck {
+  return {
+    id,
+    title: id,
+    description: '',
+    baseCss: '',
+    slides: [makeSlide({id: 'slide-1', title: 'Slide 1', html: 'x'})],
+    createdAt: NOW.toISOString(),
+    updatedAt: NOW.toISOString(),
+    ...extra,
+  };
+}
+
+test('slugify makes a url-safe id', () => {
+  assert.equal(slugify('Three Levels of Strictness!'), 'three-levels-of-strictness');
+  assert.equal(slugify('  '), 'deck');
+  assert.equal(slugify('a'.repeat(120)).length, 60);
+});
+
+test('uniqueId appends a counter until the id is free', () => {
+  assert.equal(uniqueId('deck', []), 'deck');
+  assert.equal(uniqueId('deck', ['deck']), 'deck-2');
+  assert.equal(uniqueId('deck', ['deck', 'deck-2', 'deck-3']), 'deck-4');
+});
+
+test('nextSlideId falls back to a numbered id and avoids collisions', () => {
+  const slides = [makeSlide({id: 'intro', title: 'Intro'})];
+  assert.equal(nextSlideId('Second', slides), 'second');
+  assert.equal(nextSlideId('Intro', slides), 'intro-2');
+  assert.equal(nextSlideId('   ', slides), 'slide-2');
+});
+
+test('makeDeck starts with one usable slide', () => {
+  const made = makeDeck('My Deck', ['my-deck'], NOW);
+  assert.equal(made.id, 'my-deck-2');
+  assert.equal(made.title, 'My Deck');
+  assert.equal(made.slides.length, 1);
+  assert.equal(made.slides[0]?.html, '<nys-button label="Excelsior"></nys-button>\n');
+  assert.equal(made.createdAt, made.updatedAt);
+});
+
+test('copyOfDeck takes a free id and drops the starter link', () => {
+  const copy = copyOfDeck(deck('library', {starter: 'library'}), ['library', 'library-copy'], NOW);
+  assert.equal(copy.id, 'library-copy-2');
+  assert.equal(copy.title, 'Copy of library');
+  assert.equal(copy.starter, undefined);
+});
+
+test('slideIndex finds a slide or reports -1', () => {
+  const d = deck('a');
+  assert.equal(slideIndex(d, 'slide-1'), 0);
+  assert.equal(slideIndex(d, 'missing'), -1);
+  assert.equal(slideIndex(d, null), -1);
+});
+
+test('toDeckFile writes the deck file shape without timestamps', () => {
+  const file = toDeckFile(deck('a', {title: 'A', description: 'd', baseCss: 'p{}'}));
+  assert.deepEqual(Object.keys(file), ['title', 'description', 'boilerplate', 'presets']);
+  assert.deepEqual(file.boilerplate, {baseCss: 'p{}'});
+  assert.equal(file.presets.length, 1);
+  assert.equal('createdAt' in file, false);
+});
+
+test('normalizeImport accepts a deck file and tolerates extra keys', () => {
+  const result = normalizeImport(
+    {
+      $comment: 'ignore me',
+      title: 'Styling Levels',
+      boilerplate: {head: '<link>', baseCss: 'body{}'},
+      presets: [{id: '01-a', title: 'A', html: '<p>a</p>'}],
+    },
+    [],
+    'styling-levels',
+    NOW,
+  );
+  assert.equal(result.ok, true);
+  if (!result.ok) {
+    return;
+  }
+  assert.equal(result.deck.id, 'styling-levels');
+  assert.equal(result.deck.baseCss, 'body{}');
+  assert.equal(result.deck.slides.length, 1);
+});
+
+test('normalizeImport appends a suffix when the file name is taken', () => {
+  const raw = {title: 'Three levels of strictness', presets: [{id: 'a', title: 'A', html: 'x'}]};
+  const first = normalizeImport(raw, ['styling-levels'], 'styling-levels', NOW);
+  assert.equal(first.ok && first.deck.id, 'styling-levels-2');
+  const second = normalizeImport(raw, ['styling-levels', 'styling-levels-2'], 'styling-levels', NOW);
+  assert.equal(second.ok && second.deck.id, 'styling-levels-3');
+});
+
+test('normalizeImport falls back to the title when there is no file name', () => {
+  const raw = {title: 'Styling Levels', presets: [{id: 'a', title: 'A', html: 'x'}]};
+  const result = normalizeImport(raw, [], '', NOW);
+  assert.equal(result.ok, true);
+  assert.equal(result.ok ? result.deck.id : '', 'styling-levels');
+});
+
+test('normalizeImport accepts a single preset as a one-slide deck', () => {
+  const result = normalizeImport(
+    {title: 'Button', html: '<nys-button></nys-button>', css: '', js: ''},
+    [],
+    'button',
+    NOW,
+  );
+  assert.equal(result.ok, true);
+  if (!result.ok) {
+    return;
+  }
+  assert.equal(result.deck.slides.length, 1);
+  assert.equal(result.deck.title, 'Button');
+});
+
+test('normalizeImport rejects what is not a deck', () => {
+  assert.equal(normalizeImport([1, 2], [], 'x', NOW).ok, false);
+  assert.equal(normalizeImport('nope', [], 'x', NOW).ok, false);
+  assert.equal(normalizeImport({presets: []}, [], 'x', NOW).ok, false);
+});
+
+test('missingStarters adds only the starters the store has not seen', () => {
+  const starters = [
+    deck('library', {starter: 'library'}),
+    deck('styling-levels', {starter: 'styling-levels'}),
+  ];
+  assert.equal(missingStarters(starters, []).length, 2);
+  assert.deepEqual(
+    missingStarters(starters, [deck('library', {starter: 'library'})]).map((d) => d.id),
+    ['styling-levels'],
+  );
+  assert.equal(missingStarters(starters, starters).length, 0);
+});
+
+test('missingStarters keeps a restored starter off an id already in use', () => {
+  const starters = [deck('library', {starter: 'library'})];
+  const stored = [deck('library')];
+  assert.deepEqual(missingStarters(starters, stored).map((d) => d.id), ['library-2']);
+});
+
+test('relativeTime reads as a person would say it', () => {
+  const now = new Date('2026-09-16T12:00:00.000Z');
+  assert.equal(relativeTime('2026-09-16T09:00:00.000Z', now), 'today');
+  assert.equal(relativeTime('2026-09-15T09:00:00.000Z', now), 'yesterday');
+  assert.equal(relativeTime('2026-09-10T12:00:00.000Z', now), '6 days ago');
+  assert.equal(relativeTime('2026-07-16T12:00:00.000Z', now), '2 months ago');
+  assert.equal(relativeTime('not a date', now), 'unknown');
+});
+
+/* Confirm dialog handler lifetime ---------------------------------------- */
+
+/**
+ * The shape of `confirmAction` in `src/main.ts`, minus the DOM.
+ *
+ * Deleting one deck used to delete its neighbour: dismissing the modal with
+ * its own close button skipped the Cancel handler, so the next question added
+ * a second listener and one confirmation answered both.
+ */
+function makeConfirm(): {
+  ask(onConfirm: () => void): void;
+  confirm(): void;
+  dismiss(): void;
+} {
+  const listeners = new Set<() => void>();
+  let controller: {abort(): void} | undefined;
+  return {
+    ask(onConfirm) {
+      controller?.abort();
+      const handler = (): void => {
+        listeners.delete(handler);
+        controller = undefined;
+        onConfirm();
+      };
+      listeners.add(handler);
+      controller = {
+        abort() {
+          listeners.delete(handler);
+        },
+      };
+    },
+    confirm() {
+      for (const handler of [...listeners]) {
+        handler();
+      }
+    },
+    dismiss() {
+      controller?.abort();
+      controller = undefined;
+    },
+  };
+}
+
+test('confirming answers only the question on screen', () => {
+  const confirm = makeConfirm();
+  const answered: string[] = [];
+  // The first question is dismissed without Cancel, the way the modal's own
+  // close button does it.
+  confirm.ask(() => answered.push('first'));
+  confirm.ask(() => answered.push('second'));
+  confirm.confirm();
+  assert.deepEqual(answered, ['second']);
+});
+
+test('confirming twice does not repeat the previous answer', () => {
+  const confirm = makeConfirm();
+  const answered: string[] = [];
+  confirm.ask(() => answered.push('a'));
+  confirm.confirm();
+  confirm.ask(() => answered.push('b'));
+  confirm.confirm();
+  assert.deepEqual(answered, ['a', 'b']);
+});
+
+test('dismissing leaves nothing to answer', () => {
+  const confirm = makeConfirm();
+  const answered: string[] = [];
+  confirm.ask(() => answered.push('a'));
+  confirm.dismiss();
+  confirm.confirm();
+  assert.deepEqual(answered, []);
+});
+
+/* Untitled decks ---------------------------------------------------------- */
+
+test('a new deck is called Untitled and takes the next free id', () => {
+  const first = makeDeck('Untitled', [], NOW);
+  assert.equal(first.id, 'untitled');
+  assert.equal(first.title, 'Untitled');
+
+  const second = makeDeck('Untitled', ['untitled'], NOW);
+  assert.equal(second.id, 'untitled-2');
+
+  const third = makeDeck('Untitled', ['untitled', 'untitled-2'], NOW);
+  assert.equal(third.id, 'untitled-3');
+});
+
+test('renaming a deck does not move its id', () => {
+  // The id is generated once, at creation; a later title is only a label.
+  const deck = makeDeck('Untitled', [], NOW);
+  const renamed = {...deck, title: 'Three levels of strictness'};
+  assert.equal(renamed.id, 'untitled');
+});
+
+test('staleStarters finds untouched copies seeded under a retired key', () => {
+  const retired = [{starter: 'old', replacedBy: 'new', title: 'Old title'}];
+  const starters = [deck('new', {starter: 'new', title: 'New title'})];
+  const untouched = deck('old', {starter: 'old', title: 'Old title'});
+  const renamed = deck('old', {starter: 'old', title: 'My deck'});
+  const edited = deck('old', {
+    starter: 'old',
+    title: 'Old title',
+    slides: [makeSlide({id: 'slide-1', title: 'Slide 1', html: 'changed'})],
+  });
+  const unrelated = deck('mine');
+
+  assert.deepEqual(
+    staleStarters([untouched, renamed, edited, unrelated], retired, starters),
+    [untouched],
+  );
+  assert.deepEqual(staleStarters([untouched], retired, []), []);
+});

package/src/editor-panes.ts

@@ -0,0 +1,190 @@
+/**
+ * Drives the editor pane: the tabs layout, the side-by-side columns, and which
+ * columns are collapsed.
+ */
+import type {EditorLayout, PaneId} from './editors';
+import {
+  PANE_FILES,
+  PANE_IDS,
+  initialLayout,
+  otherLayout,
+  readCollapsedPanes,
+  writeCollapsedPanes,
+  writeLayout,
+} from './editors';
+import {DEFAULTS} from './settings';
+
+/** The elements that make up one column. */
+interface ColumnElements {
+  column: HTMLElement;
+  label: HTMLElement;
+  collapse: HTMLElement;
+  editor: HTMLElement;
+}
+
+/** Shows one layout at a time and remembers what the presenter collapsed. */
+export class EditorPanes {
+  private readonly app: HTMLElement;
+  private readonly tabsLayout: HTMLElement;
+  private readonly columnsLayout: HTMLElement;
+  private readonly tabsEditor: HTMLElement;
+  private readonly columns: Record<PaneId, ColumnElements>;
+  private readonly onLayoutChange: (layout: EditorLayout) => void;
+
+  private currentLayout: EditorLayout;
+  private collapsed: Set<PaneId>;
+
+  constructor(onLayoutChange: (layout: EditorLayout) => void = () => {}) {
+    this.onLayoutChange = onLayoutChange;
+    this.app = required('#app');
+    this.tabsLayout = required('#tabs-layout');
+    this.columnsLayout = required('#columns-layout');
+    this.tabsEditor = required('#file-editor');
+    this.columns = Object.fromEntries(
+      PANE_IDS.map((pane) => [
+        pane,
+        {
+          column: required(`#column-${pane}`),
+          label: required(`#column-${pane}-label`),
+          collapse: required(`#column-${pane}-collapse`),
+          editor: required(`#column-${pane}-editor`),
+        },
+      ]),
+    ) as Record<PaneId, ColumnElements>;
+
+    this.currentLayout = initialLayout();
+    this.collapsed = readCollapsedPanes();
+    this.bind();
+    this.render();
+  }
+
+  /** The layout on screen. */
+  get layout(): EditorLayout {
+    return this.currentLayout;
+  }
+
+  /** Reports whether a column is collapsed. */
+  isCollapsed(pane: PaneId): boolean {
+    return this.collapsed.has(pane);
+  }
+
+  /** Switches between the tabs layout and the columns layout. */
+  setLayout(layout: EditorLayout, persist = true): void {
+    if (layout === this.currentLayout) {
+      return;
+    }
+    this.currentLayout = layout;
+    if (persist) {
+      writeLayout(layout);
+    }
+    this.render();
+    this.onLayoutChange(layout);
+  }
+
+  /** Flips to the other layout. */
+  toggleLayout(): void {
+    this.setLayout(otherLayout(this.currentLayout));
+  }
+
+  /** Collapses a column, or brings it back. */
+  togglePane(pane: PaneId): void {
+    if (this.collapsed.has(pane)) {
+      this.collapsed.delete(pane);
+    } else {
+      this.collapsed.add(pane);
+    }
+    writeCollapsedPanes(this.collapsed);
+    this.render();
+  }
+
+  /**
+   * Applies a slide's `editors` field.
+   *
+   * `null` means the slide said nothing about the columns, so whatever is on
+   * screen stays.
+   */
+  applyCollapsed(collapsed: Set<PaneId> | null): void {
+    if (collapsed === null) {
+      return;
+    }
+    this.collapsed = new Set(collapsed);
+    writeCollapsedPanes(this.collapsed);
+    this.render();
+  }
+
+  /** Returns to the tabs layout with every column expanded. */
+  reset(): void {
+    this.collapsed = new Set();
+    writeCollapsedPanes(this.collapsed);
+    if (this.currentLayout === DEFAULTS.layout) {
+      this.render();
+      return;
+    }
+    this.setLayout(DEFAULTS.layout);
+  }
+
+  private bind(): void {
+    for (const pane of PANE_IDS) {
+      const {label, collapse} = this.columns[pane];
+      label.addEventListener('click', () => this.togglePane(pane));
+      collapse.addEventListener('nys-click', () => this.togglePane(pane));
+    }
+  }
+
+  private render(): void {
+    const columns = this.currentLayout === 'columns';
+    this.app.classList.toggle('app--columns', columns);
+    this.tabsLayout.hidden = columns;
+    this.columnsLayout.hidden = !columns;
+
+    for (const pane of PANE_IDS) {
+      const {column, label, collapse} = this.columns[pane];
+      const isCollapsed = this.collapsed.has(pane);
+      const {label: name} = PANE_FILES[pane];
+      column.classList.toggle('column--collapsed', isCollapsed);
+      label.setAttribute('aria-expanded', String(!isCollapsed));
+      label.title = isCollapsed ? `Expand ${name}` : `Collapse ${name}`;
+      collapse.setAttribute('label', `Collapse ${name}`);
+    }
+
+    this.refreshVisibleEditors();
+  }
+
+  /**
+   * Makes the editors that just became visible re-read their file, and stops
+   * the ones that are off screen from writing anything back.
+   *
+   * Both layouts stay mounted, so a hidden editor still holds the document it
+   * had when it was last seen. `project.editFile` does not fire
+   * `filesChanged`, so it never learns about edits made in the other layout,
+   * and on its next render it would write that stale text back over them.
+   * Marking it read-only keeps its CodeMirror from emitting changes at all.
+   */
+  private refreshVisibleEditors(): void {
+    const columns = this.currentLayout === 'columns';
+    const visible = new Set<HTMLElement>(
+      columns
+        ? PANE_IDS.filter((pane) => !this.collapsed.has(pane)).map(
+            (pane) => this.columns[pane].editor,
+          )
+        : [this.tabsEditor],
+    );
+    const all = [this.tabsEditor, ...PANE_IDS.map((pane) => this.columns[pane].editor)];
+    for (const editor of all) {
+      (editor as HTMLElement & {readonly?: boolean}).readonly = !visible.has(editor);
+    }
+    requestAnimationFrame(() => {
+      for (const editor of visible) {
+        (editor as HTMLElement & {requestUpdate?: () => void}).requestUpdate?.();
+      }
+    });
+  }
+}
+
+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/editors.ts

@@ -0,0 +1,92 @@
+/**
+ * The two editor layouts and the state of the side-by-side columns.
+ *
+ * `tabs` shows one file at a time behind a tab bar. `columns` shows all three
+ * files next to each other, and any column can be collapsed to a narrow strip.
+ */
+// The explicit extension lets `node --test` load these modules directly, the
+// same way `src/state.test.ts` imports them.
+import type {PaneId} from './preset-schema.ts';
+import {PANE_IDS} from './preset-schema.ts';
+import {
+  DEFAULTS,
+  STORAGE_KEYS,
+  readCollapsedPanes,
+  readKey,
+  writeCollapsedPanes,
+  writeKey,
+} from './settings.ts';
+
+export {readCollapsedPanes, writeCollapsedPanes};
+
+export type {PaneId};
+export {PANE_IDS};
+
+/** How the editors are arranged. */
+export type EditorLayout = 'tabs' | 'columns';
+
+/** The query parameter that picks the layout, as in `?editors=columns`. */
+export const EDITORS_PARAM = 'editors';
+
+/** The project file and tab label behind each column. */
+export const PANE_FILES: Record<PaneId, {file: string; label: string}> = {
+  html: {file: 'snippet.html', label: 'HTML'},
+  css: {file: 'styles.css', label: 'CSS'},
+  js: {file: 'script.js', label: 'JS'},
+};
+
+/** Reads `?editors=` from a query string. Returns `null` when it isn't set. */
+export function readLayoutParam(search: string): EditorLayout | null {
+  const value = new URLSearchParams(search).get(EDITORS_PARAM);
+  return value === 'columns' || value === 'tabs' ? value : null;
+}
+
+/** Returns the other layout. */
+export function otherLayout(layout: EditorLayout): EditorLayout {
+  return layout === 'columns' ? 'tabs' : 'columns';
+}
+
+/** Returns the URL with `?editors=` set to the given layout. */
+export function layoutUrl(layout: EditorLayout, href: string): string {
+  const url = new URL(href);
+  url.searchParams.set(EDITORS_PARAM, layout);
+  return url.toString();
+}
+
+/**
+ * Turns a preset's `editors` field into the set of columns to collapse.
+ *
+ * Every column the preset does not list is collapsed, so a slide that names
+ * `["html", "css"]` puts JavaScript out of the way. A preset that leaves the
+ * field out returns `null`, which means "keep whatever is on screen".
+ */
+export function collapsedForPreset(editors: PaneId[] | null): Set<PaneId> | null {
+  if (editors === null) {
+    return null;
+  }
+  return new Set(PANE_IDS.filter((pane) => !editors.includes(pane)));
+}
+
+/**
+ * Picks the layout for this visit: the URL wins, then the remembered choice,
+ * then the side-by-side columns.
+ *
+ * A layout chosen before is kept, so changing the default does not move
+ * anyone's editors on them.
+ */
+export function initialLayout(search: string = window.location.search): EditorLayout {
+  const fromUrl = readLayoutParam(search);
+  if (fromUrl) {
+    return fromUrl;
+  }
+  const stored = readKey(STORAGE_KEYS.layout);
+  if (stored === 'columns' || stored === 'tabs') {
+    return stored;
+  }
+  return DEFAULTS.layout;
+}
+
+/** Remembers the layout for the next visit. */
+export function writeLayout(layout: EditorLayout): void {
+  writeKey(STORAGE_KEYS.layout, layout);
+}