@nysds/playground 0.1.0

package/src/routing.ts

@@ -0,0 +1,60 @@
+/**
+ * Which view a URL asks for, and when a history move needs a fresh boot.
+ *
+ * The router runs once at start-up, so going back or forward between views has
+ * to be turned into a reload. These helpers are pure so `src/route.test.ts`
+ * can cover the rule without a browser.
+ */
+
+/** The three views the playground can show. */
+export type Route =
+  | {kind: 'home'}
+  | {kind: 'deck'; id: string}
+  | {kind: 'scratch'};
+
+/**
+ * Decides between the home page and the editor.
+ *
+ * A deck id opens that deck. A `#code=` or `#preset=` hash without a deck id
+ * opens the scratch pad, which is what a shared link and the CLI produce.
+ * Anything else lands on the home page.
+ */
+export function routeFor(search: string, hash: string): Route {
+  const deck = new URLSearchParams(search).get('deck');
+  if (deck) {
+    return {kind: 'deck', id: deck};
+  }
+  const value = hash.startsWith('#') ? hash.slice(1) : hash;
+  if (value.startsWith('code=') || value.startsWith('preset=')) {
+    return {kind: 'scratch'};
+  }
+  return {kind: 'home'};
+}
+
+/** Reports whether two routes show the same view of the same deck. */
+export function sameRoute(a: Route, b: Route): boolean {
+  if (a.kind !== b.kind) {
+    return false;
+  }
+  return a.kind === 'deck' && b.kind === 'deck' ? a.id === b.id : true;
+}
+
+/**
+ * Reports whether a history move has to reload the page.
+ *
+ * Moving within one deck only changes the slide, which the app handles in
+ * place. Everything else changes which view is mounted.
+ */
+export function needsReboot(from: Route, to: Route): boolean {
+  return !sameRoute(from, to);
+}
+
+/** Returns the slide id a URL names, or `null`. */
+export function slideIdFromHash(hash: string): string | null {
+  const value = hash.startsWith('#') ? hash.slice(1) : hash;
+  if (!value.startsWith('preset=')) {
+    return null;
+  }
+  const id = decodeURIComponent(value.slice('preset='.length));
+  return id || null;
+}

package/src/settings.ts

@@ -0,0 +1,211 @@
+/**
+ * Every playground setting and the one place that touches `localStorage`.
+ *
+ * Each setting can also come from the URL, so a link can open the playground
+ * configured a particular way. The URL wins over the remembered value, and the
+ * remembered value wins over the default.
+ *
+ * The parsing and clamping here are pure, so `src/state.test.ts` exercises them
+ * without a DOM. Only the `read*`/`write*` helpers touch storage, and every one
+ * of them tolerates storage being blocked.
+ */
+import type {EditorLayout} from './editors.ts';
+import type {PaneId} from './preset-schema.ts';
+import {PANE_IDS} from './preset-schema.ts';
+import type {EditorTheme} from './theme.ts';
+
+/** The code font sizes the settings modal offers. */
+export type FontSize = 'small' | 'medium' | 'large';
+
+/** How soon an edit reaches the preview. */
+export type UpdateMode = 'typing' | 'pause' | 'manual';
+
+/** The pixel size each font choice maps to. */
+export const FONT_SIZES: Record<FontSize, string> = {
+  small: '13px',
+  medium: '15px',
+  large: '18px',
+};
+
+/**
+ * How long the playground waits for typing to stop before it rebuilds, in
+ * milliseconds. `manual` never rebuilds on its own.
+ */
+export const UPDATE_DELAYS: Record<UpdateMode, number | null> = {
+  typing: 800,
+  pause: 2000,
+  manual: null,
+};
+
+/** The defaults a fresh visit, and "Reset settings", start from. */
+export const DEFAULTS = {
+  theme: 'dark' as EditorTheme,
+  layout: 'columns' as EditorLayout,
+  fontSize: 'medium' as FontSize,
+  updateMode: 'typing' as UpdateMode,
+  prereleases: false,
+  drawerSize: 32,
+};
+
+/** Every key the playground writes, so "Reset settings" can clear them all. */
+export const STORAGE_KEYS = {
+  theme: 'nysds-playground:editor-theme',
+  layout: 'nysds-playground:editor-layout',
+  fontSize: 'nysds-playground:font-size',
+  updateMode: 'nysds-playground:update-mode',
+  prereleases: 'nysds-playground:prereleases',
+  collapsedPanes: 'nysds-playground:collapsed-panes',
+  drawerSize: 'nysds-playground:present-editor-size',
+  codeCollapsed: 'nysds-playground:present-code-collapsed',
+} as const;
+
+/* URL parsing ----------------------------------------------------------- */
+
+/** Reads `?font=`. Returns `null` when it is absent or unrecognised. */
+export function readFontParam(search: string): FontSize | null {
+  const value = new URLSearchParams(search).get('font');
+  return value === 'small' || value === 'medium' || value === 'large' ? value : null;
+}
+
+/** Reads `?update=`. Returns `null` when it is absent or unrecognised. */
+export function readUpdateParam(search: string): UpdateMode | null {
+  const value = new URLSearchParams(search).get('update');
+  return value === 'typing' || value === 'pause' || value === 'manual' ? value : null;
+}
+
+/** Keeps a pane ratio inside the range the layout can actually render. */
+export function clampRatio(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) {
+    return min;
+  }
+  return Math.min(Math.max(value, min), max);
+}
+
+/* Storage --------------------------------------------------------------- */
+
+/** Reads one key, returning `null` when storage is unavailable or empty. */
+export function readKey(key: string): string | null {
+  try {
+    return window.localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+/** Writes one key, ignoring storage that refuses to take it. */
+export function writeKey(key: string, value: string): void {
+  try {
+    window.localStorage.setItem(key, value);
+  } catch {
+    // Private browsing can block storage. The setting still applies this visit.
+  }
+}
+
+/** Picks a setting: the URL first, then storage, then the default. */
+function choose<T extends string>(
+  fromUrl: T | null,
+  key: string,
+  valid: readonly T[],
+  fallback: T,
+): T {
+  if (fromUrl) {
+    return fromUrl;
+  }
+  const stored = readKey(key);
+  return valid.includes(stored as T) ? (stored as T) : fallback;
+}
+
+/** The code font size for this visit. */
+export function initialFontSize(search: string = window.location.search): FontSize {
+  return choose(
+    readFontParam(search),
+    STORAGE_KEYS.fontSize,
+    ['small', 'medium', 'large'],
+    DEFAULTS.fontSize,
+  );
+}
+
+/** The preview update mode for this visit. */
+export function initialUpdateMode(search: string = window.location.search): UpdateMode {
+  return choose(
+    readUpdateParam(search),
+    STORAGE_KEYS.updateMode,
+    ['typing', 'pause', 'manual'],
+    DEFAULTS.updateMode,
+  );
+}
+
+/** Whether the version menu lists prereleases. */
+export function readPrereleases(): boolean {
+  const stored = readKey(STORAGE_KEYS.prereleases);
+  return stored === null ? DEFAULTS.prereleases : stored === '1';
+}
+
+/** Remembers whether the version menu lists prereleases. */
+export function writePrereleases(on: boolean): void {
+  writeKey(STORAGE_KEYS.prereleases, on ? '1' : '0');
+}
+
+/** Reads a remembered pane ratio, clamped to the range the layout allows. */
+export function readRatio(key: string, fallback: number, min: number, max: number): number {
+  const raw = readKey(key);
+  if (raw === null) {
+    return fallback;
+  }
+  const parsed = Number.parseFloat(raw);
+  return Number.isFinite(parsed) ? clampRatio(parsed, min, max) : fallback;
+}
+
+/** Remembers a pane ratio. */
+export function writeRatio(key: string, ratio: number): void {
+  writeKey(key, ratio.toFixed(2));
+}
+
+/** Reads the collapsed editor columns. */
+export function readCollapsedPanes(): Set<PaneId> {
+  const raw = readKey(STORAGE_KEYS.collapsedPanes);
+  if (!raw) {
+    return new Set();
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (!Array.isArray(parsed)) {
+      return new Set();
+    }
+    return new Set(
+      parsed.filter((pane): pane is PaneId => (PANE_IDS as readonly unknown[]).includes(pane)),
+    );
+  } catch {
+    return new Set();
+  }
+}
+
+/** Remembers the collapsed editor columns. */
+export function writeCollapsedPanes(collapsed: ReadonlySet<PaneId>): void {
+  writeKey(STORAGE_KEYS.collapsedPanes, JSON.stringify([...collapsed]));
+}
+
+/** Clears every playground key, so the next read falls back to the defaults. */
+export function clearAllSettings(): void {
+  for (const key of Object.values(STORAGE_KEYS)) {
+    try {
+      window.localStorage.removeItem(key);
+    } catch {
+      // Nothing to do when storage refuses.
+    }
+  }
+}
+
+/** Applies a code font size to the editors. */
+export function applyFontSize(size: FontSize): void {
+  // The dark theme block also sets this property on `body`, so an inline style
+  // on `body` is what reliably wins.
+  document.body.style.setProperty('--playground-code-font-size', FONT_SIZES[size]);
+}
+
+/** Returns the URL with a setting's query parameter set. */
+export function settingUrl(name: string, value: string, href: string): string {
+  const url = new URL(href);
+  url.searchParams.set(name, value);
+  return url.toString();
+}

package/src/starters.ts

@@ -0,0 +1,86 @@
+/**
+ * The decks and examples bundled with the build.
+ *
+ * These are starter content. They seed the browser store the first time the
+ * playground runs; after that the app reads only from the store. Every JSON
+ * file in `decks/` becomes a starter deck, and all of `presets/` becomes one
+ * starter deck called the component library.
+ */
+import type {RetiredStarter, StoredDeck} from './deck-model.ts';
+import {makeSlide} from './deck-model.ts';
+import type {Preset} from './preset-schema.ts';
+import {idFromPresetPath, parseDeck, parsePreset} from './preset-schema.ts';
+
+/** The starter id of the deck built from `presets/*.json`. */
+export const LIBRARY_STARTER_ID = 'library';
+
+const presetModules = import.meta.glob<unknown>('../presets/*.json', {
+  eager: true,
+  import: 'default',
+});
+
+const deckModules = import.meta.glob<unknown>('../decks/*.json', {
+  eager: true,
+  import: 'default',
+});
+
+/** A timestamp every starter shares, so seeding is deterministic. */
+const SEEDED_AT = new Date(0).toISOString();
+
+const libraryPresets: Preset[] = Object.keys(presetModules)
+  .sort()
+  .map((path) => parsePreset(path, presetModules[path], idFromPresetPath(path)))
+  .filter((preset): preset is Preset => preset !== null)
+  .map((preset) => makeSlide(preset));
+
+const libraryDeck: StoredDeck = {
+  id: LIBRARY_STARTER_ID,
+  title: 'Component library',
+  description: 'One example for every part of the design system.',
+  baseCss: '',
+  slides: libraryPresets,
+  createdAt: SEEDED_AT,
+  updatedAt: SEEDED_AT,
+  starter: LIBRARY_STARTER_ID,
+};
+
+const bundledDecks: StoredDeck[] = Object.keys(deckModules)
+  .sort()
+  .map((path): StoredDeck | null => {
+    const deck = parseDeck(path, deckModules[path]);
+    if (!deck) {
+      return null;
+    }
+    return {
+      id: deck.id,
+      title: deck.title,
+      description: deck.description,
+      baseCss: deck.baseCss,
+      slides: deck.presets.map((preset) => makeSlide(preset)),
+      createdAt: SEEDED_AT,
+      updatedAt: SEEDED_AT,
+      starter: deck.id,
+    };
+  })
+  .filter((deck): deck is StoredDeck => deck !== null);
+
+/** Every bundled deck, with the component library first. */
+export const STARTER_DECKS: StoredDeck[] = [libraryDeck, ...bundledDecks].filter(
+  (deck) => deck.slides.length > 0,
+);
+
+/**
+ * Starter keys that earlier builds seeded under a different file name.
+ *
+ * Renaming a file in `decks/` changes the deck's id and starter key, so a
+ * browser that seeded the old name keeps that copy and seeds the new name
+ * beside it. Listing the old name here lets `seedStarters` drop the stale copy
+ * when nothing in it has changed.
+ */
+export const RETIRED_STARTERS: readonly RetiredStarter[] = [
+  {
+    starter: 'styling-levels',
+    replacedBy: 'customizing-components',
+    title: 'Three levels of strictness',
+  },
+];