@nysds/playground 0.1.0

package/src/state.ts

@@ -0,0 +1,237 @@
+/**
+ * Reads and writes the playground state in the URL.
+ *
+ * Two hash forms exist. `#code=` carries a compressed snapshot of the editors
+ * and is what a Share link produces. `#preset=` carries a preset id and stays
+ * readable, so it is used while a preset is loaded and unmodified.
+ */
+// lz-string ships CommonJS, so import the namespace as a default and read the
+// two functions off it. Named imports do not survive Node's CJS interop.
+import LZString from 'lz-string';
+
+const {compressToEncodedURIComponent, decompressFromEncodedURIComponent} = LZString;
+
+/** Everything the playground needs to restore a session. */
+export interface PlaygroundState {
+  /** The design system version the preview loads. */
+  version: string;
+  /** The user's HTML. */
+  html: string;
+  /** The user's CSS. */
+  css: string;
+  /** The user's JavaScript. */
+  js: string;
+}
+
+/** The compact object that goes into the hash. Short keys keep links short. */
+interface EncodedState {
+  v: string;
+  h: string;
+  c: string;
+  j: string;
+}
+
+/** What the current URL asks the playground to load. */
+export type LocationState =
+  | {kind: 'code'; state: PlaygroundState}
+  | {kind: 'preset'; id: string}
+  | {kind: 'default'};
+
+/** The query parameter that turns on presentation mode. */
+const PRESENT_PARAM = 'present';
+
+/** The query parameter that selects a deck. */
+const DECK_PARAM = 'deck';
+
+/** Compresses a state snapshot into the value of a `#code=` hash. */
+export function encodeState(state: PlaygroundState): string {
+  const payload: EncodedState = {
+    v: state.version,
+    h: state.html,
+    c: state.css,
+    j: state.js,
+  };
+  return compressToEncodedURIComponent(JSON.stringify(payload));
+}
+
+/** Expands a `#code=` hash value. Returns `null` when the value is unusable. */
+export function decodeState(encoded: string): PlaygroundState | null {
+  let json: string | null;
+  try {
+    json = decompressFromEncodedURIComponent(encoded);
+  } catch {
+    return null;
+  }
+  if (!json) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== 'object' || parsed === null) {
+    return null;
+  }
+  const candidate = parsed as Partial<EncodedState>;
+  if (
+    typeof candidate.v !== 'string' ||
+    typeof candidate.h !== 'string' ||
+    typeof candidate.c !== 'string' ||
+    typeof candidate.j !== 'string'
+  ) {
+    return null;
+  }
+  return {version: candidate.v, html: candidate.h, css: candidate.c, js: candidate.j};
+}
+
+/** Parses a hash string such as `#code=abc` into a {@link LocationState}. */
+export function parseHash(hash: string): LocationState {
+  const value = hash.startsWith('#') ? hash.slice(1) : hash;
+  if (value.startsWith('code=')) {
+    const state = decodeState(value.slice('code='.length));
+    if (state) {
+      return {kind: 'code', state};
+    }
+    return {kind: 'default'};
+  }
+  if (value.startsWith('preset=')) {
+    const id = decodeURIComponent(value.slice('preset='.length));
+    if (id) {
+      return {kind: 'preset', id};
+    }
+  }
+  return {kind: 'default'};
+}
+
+/** Reads the current browser location. */
+export function readLocation(): LocationState {
+  return parseHash(window.location.hash);
+}
+
+/**
+ * Returns the deck id the URL asks for, or `null` for the library deck.
+ */
+export function readDeckId(search: string = window.location.search): string | null {
+  return new URLSearchParams(search).get(DECK_PARAM);
+}
+
+/**
+ * Builds a URL for a deck and slide, keeping presentation mode.
+ *
+ * The library deck drops the `deck` parameter so its links stay short.
+ */
+export function deckUrl(
+  deckId: string,
+  presetId: string,
+  libraryDeckId: string,
+  href: string = window.location.href,
+): string {
+  const url = new URL(href);
+  if (deckId === libraryDeckId) {
+    url.searchParams.delete(DECK_PARAM);
+  } else {
+    url.searchParams.set(DECK_PARAM, deckId);
+  }
+  url.hash = presetId ? `#preset=${encodeURIComponent(presetId)}` : '';
+  return url.toString();
+}
+
+/** Reports whether the current URL requests presentation mode. */
+export function isPresentMode(search: string = window.location.search): boolean {
+  return new URLSearchParams(search).get(PRESENT_PARAM) === '1';
+}
+
+/**
+ * Returns the current URL with presentation mode turned on or off.
+ *
+ * The hash is preserved, so leaving presentation mode keeps you on the preset
+ * you were showing.
+ */
+export function presentUrl(on: boolean, href: string = window.location.href): string {
+  const url = new URL(href);
+  if (on) {
+    url.searchParams.set(PRESENT_PARAM, '1');
+  } else {
+    url.searchParams.delete(PRESENT_PARAM);
+  }
+  return url.toString();
+}
+
+/**
+ * Replaces the hash without adding a history entry.
+ *
+ * Query parameters stay untouched so `?present=1` survives every update.
+ */
+export function replaceHash(hash: string): void {
+  const url = new URL(window.location.href);
+  url.hash = hash;
+  window.history.replaceState(null, '', url.toString());
+}
+
+/** Writes a `#code=` hash for the given state. */
+export function writeCodeHash(state: PlaygroundState): void {
+  replaceHash(`#code=${encodeState(state)}`);
+}
+
+/** Writes a `#preset=` hash for the given preset id. */
+export function writePresetHash(id: string): void {
+  replaceHash(`#preset=${encodeURIComponent(id)}`);
+}
+
+/**
+ * Returns a function that runs `fn` after `delay` milliseconds of quiet.
+ *
+ * The playground uses it to keep edits from writing to the URL on every
+ * keystroke.
+ */
+export function debounce<T extends unknown[]>(
+  fn: (...args: T) => void,
+  delay: number,
+): {(...args: T): void; flush(): void; cancel(): void} {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let pending: T | undefined;
+  const run = (...args: T): void => {
+    pending = args;
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      timer = undefined;
+      const args = pending;
+      pending = undefined;
+      if (args) {
+        fn(...args);
+      }
+    }, delay);
+  };
+  run.flush = (): void => {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+    const args = pending;
+    pending = undefined;
+    if (args) {
+      fn(...args);
+    }
+  };
+  run.cancel = (): void => {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+    pending = undefined;
+  };
+  return run;
+}
+
+/** Turns a title into a filename-safe slug. */
+export function slugify(title: string): string {
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || 'playground';
+}

package/src/theme.ts

@@ -0,0 +1,82 @@
+/**
+ * Light and dark editor themes.
+ *
+ * The preview always shows the design system as it is. Only the code editors
+ * change. Light is the default because projectors wash out dark backgrounds.
+ * Dark suits screen recordings, where a dark pane frames the light preview.
+ */
+import lightTheme from 'playground-elements/themes/eclipse.css.js';
+import darkTheme from 'playground-elements/themes/material-darker.css.js';
+
+import {DEFAULTS, STORAGE_KEYS, readKey, writeKey} from './settings.ts';
+
+/** The two editor themes the playground offers. */
+export type EditorTheme = 'light' | 'dark';
+
+/** The query parameter that picks the editor theme, as in `?theme=dark`. */
+export const THEME_PARAM = 'theme';
+
+/** The CodeMirror theme class each choice maps to. */
+const THEME_CLASSES: Record<EditorTheme, string> = {
+  light: 'playground-theme-eclipse',
+  dark: 'playground-theme-material-darker',
+};
+
+/** Reads `?theme=` from a query string. Returns `null` when it isn't set. */
+export function readThemeParam(search: string): EditorTheme | null {
+  const value = new URLSearchParams(search).get(THEME_PARAM);
+  return value === 'dark' || value === 'light' ? value : null;
+}
+
+/** Returns the other theme. */
+export function otherTheme(theme: EditorTheme): EditorTheme {
+  return theme === 'dark' ? 'light' : 'dark';
+}
+
+/** Returns the URL with `?theme=` set to the given theme. */
+export function themeUrl(theme: EditorTheme, href: string): string {
+  const url = new URL(href);
+  url.searchParams.set(THEME_PARAM, theme);
+  return url.toString();
+}
+
+/**
+ * Picks the theme for this visit: the URL wins, then the remembered choice,
+ * then dark.
+ *
+ * A theme chosen before is kept, so changing the default does not recolour
+ * anyone's editors on them.
+ */
+export function initialTheme(search: string = window.location.search): EditorTheme {
+  const fromUrl = readThemeParam(search);
+  if (fromUrl) {
+    return fromUrl;
+  }
+  const stored = readKey(STORAGE_KEYS.theme);
+  if (stored === 'dark' || stored === 'light') {
+    return stored;
+  }
+  return DEFAULTS.theme;
+}
+
+let sheetsAdopted = false;
+
+/** Applies a theme to the document so it reaches the editors. */
+export function applyEditorTheme(theme: EditorTheme): void {
+  if (!sheetsAdopted) {
+    const sheets = [lightTheme.styleSheet, darkTheme.styleSheet].filter(
+      (sheet): sheet is CSSStyleSheet => sheet !== undefined,
+    );
+    document.adoptedStyleSheets = [...document.adoptedStyleSheets, ...sheets];
+    sheetsAdopted = true;
+  }
+  for (const [name, className] of Object.entries(THEME_CLASSES)) {
+    document.body.classList.toggle(className, name === theme);
+  }
+  document.body.dataset.editorTheme = theme;
+}
+
+/** Remembers the theme for the next visit. */
+export function writeTheme(theme: EditorTheme): void {
+  writeKey(STORAGE_KEYS.theme, theme);
+}

package/src/version-catalog.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure helpers for the design system version list.
+ *
+ * This module imports nothing, so `src/state.test.ts` can load it directly
+ * under `node --test`.
+ */
+
+/** The versions the CDN can serve for both packages. */
+export interface VersionCatalog {
+  /** Versions available in both packages, newest first. */
+  all: string[];
+  /** Stable versions only, newest first. */
+  stable: string[];
+  /** The newest stable version, used to resolve `latest`. */
+  latest: string;
+  /** Whether the list came from the fallback because the API was unreachable. */
+  usedFallback: boolean;
+}
+
+/** Reports whether a version string is a prerelease, such as `2.0.0-next.1`. */
+export function isPrerelease(version: string): boolean {
+  return version.includes('-');
+}
+
+/**
+ * Picks the version to load for a requested version string.
+ *
+ * `latest` and an empty string resolve to the newest stable release. A version
+ * the CDN does not list also falls back to the newest stable, which keeps a
+ * mistyped or unpublished version in a shared link from breaking the preview.
+ * That check is skipped when the catalog came from the built-in fallback list,
+ * because that list names only a handful of releases.
+ */
+export function chooseVersion(requested: string, catalog: VersionCatalog): string {
+  if (!requested || requested === 'latest') {
+    return catalog.latest || requested;
+  }
+  if (!catalog.usedFallback && !catalog.all.includes(requested)) {
+    return catalog.latest || requested;
+  }
+  return requested;
+}

package/src/versions.ts

@@ -0,0 +1,88 @@
+/**
+ * Fetches the design system versions the CDN can serve.
+ *
+ * Only versions that exist in both packages are offered, because the preview
+ * loads the component bundle and the stylesheet at the same version.
+ */
+import {PLAYGROUND_CONFIG} from './playground.config';
+import type {VersionCatalog} from './version-catalog';
+import {chooseVersion, isPrerelease} from './version-catalog';
+
+export type {VersionCatalog};
+export {chooseVersion, isPrerelease};
+
+/** The subset of the jsDelivr response the playground reads. */
+interface JsdelivrPackage {
+  tags?: Record<string, string>;
+  versions?: string[];
+}
+
+let cached: Promise<VersionCatalog> | undefined;
+
+/** Fetches the published versions of one npm package. */
+async function fetchVersions(name: string): Promise<JsdelivrPackage> {
+  const response = await fetch(`${PLAYGROUND_CONFIG.versionsApi}${name}`);
+  if (!response.ok) {
+    throw new Error(`The versions API answered ${response.status} for ${name}.`);
+  }
+  return (await response.json()) as JsdelivrPackage;
+}
+
+/** Builds the fallback catalog from the configured list. */
+function fallbackCatalog(): VersionCatalog {
+  const all = [...PLAYGROUND_CONFIG.fallbackVersions];
+  const stable = all.filter((version) => !isPrerelease(version));
+  return {
+    all,
+    stable,
+    latest: stable[0] ?? all[0] ?? '',
+    usedFallback: true,
+  };
+}
+
+/**
+ * Returns the version catalog, fetching it at most once per page load.
+ *
+ * When the API is unreachable, the configured fallback list is returned
+ * instead so the playground still works offline.
+ */
+export function loadVersions(): Promise<VersionCatalog> {
+  if (!cached) {
+    cached = buildCatalog().catch((error: unknown) => {
+      console.warn('Could not load the version list from the CDN.', error);
+      return fallbackCatalog();
+    });
+  }
+  return cached;
+}
+
+async function buildCatalog(): Promise<VersionCatalog> {
+  const [components, styles] = await Promise.all([
+    fetchVersions(PLAYGROUND_CONFIG.packages.components.name),
+    fetchVersions(PLAYGROUND_CONFIG.packages.styles.name),
+  ]);
+  const stylesVersions = new Set(styles.versions ?? []);
+  const all = (components.versions ?? []).filter((version) => stylesVersions.has(version));
+  if (all.length === 0) {
+    throw new Error('The two packages share no published versions.');
+  }
+  const stable = all.filter((version) => !isPrerelease(version));
+  const taggedLatest = components.tags?.latest;
+  const latest =
+    taggedLatest && all.includes(taggedLatest) ? taggedLatest : (stable[0] ?? all[0]);
+  return {all, stable, latest: latest ?? '', usedFallback: false};
+}
+
+/**
+ * Turns `latest` into a concrete version number, fetching the catalog first.
+ */
+export async function resolveVersion(version: string): Promise<string> {
+  const catalog = await loadVersions();
+  const chosen = chooseVersion(version, catalog);
+  if (chosen !== version) {
+    if (version && version !== 'latest') {
+      console.warn(`The CDN does not list version ${version}. Loading ${chosen} instead.`);
+    }
+  }
+  return chosen || PLAYGROUND_CONFIG.fallbackVersions[0] || 'latest';
+}

package/src/wrapper.ts

@@ -0,0 +1,84 @@
+/**
+ * Builds the preview document that wraps the user's markup.
+ *
+ * The wrapper is a file of its own, hidden from the editors, so the HTML pane
+ * holds nothing but the user's snippet. That keeps select-all and copy honest
+ * and the line numbers correct.
+ */
+
+/** The options that vary between wrappers. */
+export interface WrapperOptions {
+  /** The absolute URL of the design system stylesheet. */
+  stylesHref: string;
+  /** The absolute URL of the design system component bundle. */
+  componentsSrc: string;
+  /** Extra markup to append to the `<head>`. */
+  extraHeadHtml?: string;
+  /**
+   * CSS that applies to every slide in a deck.
+   *
+   * It goes into the head as a `<style>`, so it styles the preview without
+   * taking up room in the CSS tab.
+   */
+  baseCss?: string;
+  /** The `<title>` of the preview document. */
+  title?: string;
+}
+
+/**
+ * Wraps the user's markup in a complete HTML document.
+ *
+ * The result is never shown in an editor, so it is written for the browser
+ * rather than for reading.
+ */
+export function wrapUserHtml(userHtml: string, options: WrapperOptions): string {
+  const title = options.title ?? 'Preview';
+  const head = [
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    `<title>${escapeHtmlText(title)}</title>`,
+    `<link rel="stylesheet" href="${options.stylesHref}">`,
+    // The design system reset removes the body margin. Put the browser default
+    // back so a lone button doesn't sit against the edge. Deck base CSS and the
+    // CSS tab load later, so either can set `body { margin: 0 }` to remove it.
+    '<style>body{margin:8px}</style>',
+    options.extraHeadHtml ?? '',
+    options.baseCss ? `<style>${options.baseCss}</style>` : '',
+    '<link rel="stylesheet" href="./styles.css">',
+    `<script type="module" src="${options.componentsSrc}"></script>`,
+  ].join('');
+  return [
+    '<!doctype html>',
+    '<html lang="en">',
+    `<head>${head}</head>`,
+    '<body>',
+    userHtml,
+    '<script type="module" src="./script.js"></script>',
+    '</body>',
+    '</html>',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Rewrites relative `href` and `src` values in head markup to absolute URLs.
+ *
+ * The preview runs on a different origin from the playground, so a link
+ * written relative to the playground page, such as `./fonts/nysds-fonts.css`,
+ * has to be resolved against the page before it goes into the preview.
+ */
+export function resolveHeadUrls(html: string, baseUrl: string): string {
+  return html.replace(
+    /\b(href|src)=(["'])(\.{1,2}\/[^"']*)\2/g,
+    (_match, attr: string, quote: string, value: string) =>
+      `${attr}=${quote}${new URL(value, baseUrl).href}${quote}`,
+  );
+}
+
+/** Escapes text that goes into an HTML text node. */
+function escapeHtmlText(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["vite/client"],
+    "strict": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "useDefineForClassFields": true,
+    "experimentalDecorators": false
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/vite.config.ts

@@ -0,0 +1,62 @@
+import {createRequire} from 'node:module';
+import {readFileSync} from 'node:fs';
+import {defineConfig, type Plugin} from 'vite';
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Files that `playground-elements` loads at runtime through a relative
+ * `new URL(..., import.meta.url)` reference rather than a static import.
+ *
+ * `playground-project.js` starts the TypeScript worker with
+ * `new URL('./playground-typescript-worker.js', import.meta.url)`, and that
+ * worker imports `./internal/typescript.js`. Rollup may or may not rewrite the
+ * `new URL` call into a hashed asset, so copy both files next to the emitted
+ * chunks. The relative lookup then resolves either way.
+ */
+const RUNTIME_WORKER_FILES = [
+  {
+    from: 'playground-elements/playground-typescript-worker.js',
+    to: 'assets/playground-typescript-worker.js',
+  },
+  {
+    from: 'playground-elements/internal/typescript.js',
+    to: 'assets/internal/typescript.js',
+  },
+];
+
+/** Copies the playground TypeScript worker and its dependency into `dist`. */
+function copyPlaygroundWorker(): Plugin {
+  return {
+    name: 'copy-playground-worker',
+    apply: 'build',
+    generateBundle() {
+      for (const file of RUNTIME_WORKER_FILES) {
+        this.emitFile({
+          type: 'asset',
+          fileName: file.to,
+          source: readFileSync(require.resolve(file.from)),
+        });
+      }
+    },
+  };
+}
+
+export default defineConfig({
+  // Relative asset URLs keep the build portable to GitHub Pages project sites.
+  base: './',
+  plugins: [copyPlaygroundWorker()],
+  build: {
+    target: 'es2022',
+  },
+  optimizeDeps: {
+    // Serve playground-elements unbundled in dev so its relative worker URL
+    // resolves against /node_modules/playground-elements/.
+    exclude: ['playground-elements'],
+  },
+  // The preview iframe runs on unpkg.com and loads the fonts from this
+  // server. Font requests always need CORS, and Vite only allows localhost
+  // origins by default.
+  server: {cors: true},
+  preview: {cors: true},
+});