describe-me 0.6.1 → 0.8.0

package/index.html

@@ -4,6 +4,17 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>describe-me</title>
+    <script>
+      // Before the stylesheet and the body, so the first paint has the stored theme. src/theme-switch.ts writes the key.
+      try {
+        const theme = localStorage.getItem('describe-me:theme')
+        if (theme === 'light' || theme === 'dark') {
+          document.documentElement.dataset.theme = theme
+        }
+      } catch {
+        // Without storage the viewer follows the system.
+      }
+    </script>
     <link rel="stylesheet" href="/src/style.css" />
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "describe-me",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Living component documentation from your Vitest tests: the viewer and CLI of describe-me",
   "keywords": [
     "vitest",
@@ -45,7 +45,7 @@
   "sideEffects": false,
   "dependencies": {
     "rrweb-snapshot": "^2.1.6",
-    "@describe-me/core": "^0.6.1"
+    "@describe-me/core": "^0.8.0"
   },
   "peerDependencies": {
     "vite": "^6.4.0 || ^7.0.0 || ^8.0.0"

package/src/auto-canvas.ts

@@ -0,0 +1,70 @@
+let probe: CanvasRenderingContext2D | null = null
+
+function probeContext(): CanvasRenderingContext2D | null {
+  if (!probe) {
+    const canvas = document.createElement('canvas')
+    canvas.width = 1
+    canvas.height = 1
+    probe = canvas.getContext('2d', { willReadFrequently: true })
+  }
+
+  return probe
+}
+
+/**
+ * The sRGB bytes of a CSS color, alpha last. The canvas parses every syntax
+ * the browser knows, `oklch()` and `color()` included. A `fillStyle` it
+ * rejects keeps the previous one, so an unknown color reads as transparent.
+ */
+function colorBytes(color: string): Uint8ClampedArray | null {
+  const context = probeContext()
+  if (!context) {
+    return null
+  }
+
+  context.clearRect(0, 0, 1, 1)
+  context.fillStyle = 'transparent'
+  context.fillStyle = color
+  context.fillRect(0, 0, 1, 1)
+
+  return context.getImageData(0, 0, 1, 1).data
+}
+
+function paintsDark(element: Element | null, view: Window): boolean {
+  const bytes = element ? colorBytes(view.getComputedStyle(element).backgroundColor) : null
+  if (!bytes) {
+    return false
+  }
+
+  const [red = 0, green = 0, blue = 0, alpha = 0] = bytes
+  const lightness = (299 * red + 587 * green + 114 * blue) / 1000
+
+  return alpha >= 255 / 2 && lightness < 128
+}
+
+function declaresDark(root: Element, view: Window): boolean {
+  const names = view.getComputedStyle(root).colorScheme.split(' ')
+
+  return names.includes('dark') && !names.includes('light')
+}
+
+/**
+ * What `auto` means for a replayed frame: dark when its root declares only a
+ * dark scheme, or when `html` or `body` paints a dark `background-color`.
+ * Call it while the iframe's `color-scheme` is `light`, so the page's own
+ * `prefers-color-scheme: dark` rules do not decide, and neither do the viewer
+ * or the system. A document it cannot read is light.
+ */
+export function autoCanvas(iframe: HTMLIFrameElement): 'light' | 'dark' {
+  const frameDocument = iframe.contentDocument
+  const view = frameDocument?.defaultView
+  if (!frameDocument || !view) {
+    return 'light'
+  }
+
+  const root = frameDocument.documentElement
+  const dark =
+    declaresDark(root, view) || paintsDark(root, view) || paintsDark(frameDocument.body, view)
+
+  return dark ? 'dark' : 'light'
+}

package/src/canvas-of.ts

@@ -0,0 +1,12 @@
+import { state } from './state.js'
+
+/**
+ * The canvas a frame stands on. A frame's `color-scheme` is `dark` on the dark
+ * canvas and `light` on the other two.
+ */
+export type Canvas = 'light' | 'dark' | 'transparent'
+
+/** The canvas the background switch picks, with `auto` standing for what `'auto'` resolves to. */
+export function canvasOf(auto: 'light' | 'dark'): Canvas {
+  return state.background === 'auto' ? auto : state.background
+}

package/src/collapse-props.ts

@@ -0,0 +1,52 @@
+import { el } from './el.js'
+import { state } from './state.js'
+
+const SHOWN_ROWS = 10
+// A short tail shows in full, so the button never says "Show 1 more".
+const MIN_HIDDEN_ROWS = 3
+
+function applyFold(rows: HTMLTableRowElement[], button: HTMLButtonElement, key: string): void {
+  const expanded = state.expandedProps.has(key)
+  rows.forEach((row, index) => {
+    row.hidden = !expanded && index >= SHOWN_ROWS
+  })
+
+  button.textContent = expanded ? 'Show fewer' : `Show ${rows.length - SHOWN_ROWS} more`
+  button.setAttribute('aria-expanded', expanded ? 'true' : 'false')
+}
+
+/**
+ * Append the prop rows to `table`, folded to the first few when there are many,
+ * with a button under them that unfolds them. `key` names the table in
+ * `state.expandedProps`, so a rebuilt table opens as it was left.
+ */
+export function collapseProps(
+  table: HTMLTableElement,
+  rows: HTMLTableRowElement[],
+  key: string,
+): HTMLElement[] {
+  table.append(...rows)
+  if (rows.length - SHOWN_ROWS < MIN_HIDDEN_ROWS) {
+    return [table]
+  }
+
+  const button = el('button', { type: 'button', class: 'props-more', 'aria-expanded': 'false' })
+  button.addEventListener('click', () => {
+    if (state.expandedProps.has(key)) {
+      state.expandedProps.delete(key)
+    } else {
+      state.expandedProps.add(key)
+    }
+
+    applyFold(rows, button, key)
+    if (!state.expandedProps.has(key)) {
+      // The rows above it go away, which can move the button out of view.
+      button.scrollIntoView({ block: 'nearest' })
+    }
+  })
+
+  // Final before insertion, so the overview's scroll restore sees the real height.
+  applyFold(rows, button, key)
+
+  return [table, button]
+}

package/src/filter-active.ts

@@ -0,0 +1,6 @@
+import { state } from './state.js'
+
+/** A search or a tag narrows the sidebar. Collapsed suites then open, so every match shows. */
+export function filterActive(): boolean {
+  return state.query.trim() !== '' || state.tag !== null
+}

package/src/inspector.ts

@@ -1,7 +1,10 @@
+import type { ManifestTest } from '@describe-me/core/types'
+import { collapseProps } from './collapse-props.js'
 import { el } from './el.js'
 import { liveSection } from './live-section.js'
 import { liveShown } from './live-shown.js'
 import { currentTest, state } from './state.js'
+import { tagButtons } from './tag-buttons.js'
 import { valueCell } from './value-cell.js'
 
 function keyHint(): HTMLElement {
@@ -25,9 +28,35 @@ function keyHint(): HTMLElement {
   return hint
 }
 
+/** The props the component got, folded when there are many. Frames and Live of a test share the fold. */
+function propsSection(
+  test: ManifestTest,
+  name: string,
+  props: Record<string, unknown>,
+): HTMLElement {
+  const section = el('section', {}, el('h3', {}, `component · ${name}`))
+  const table = el('table', { class: 'kv' })
+  const entries = Object.entries(props)
+
+  if (!entries.length) {
+    table.append(el('tr', {}, el('td', {}, el('span', { class: 'hint' }, 'no props'))))
+    section.append(table)
+
+    return section
+  }
+
+  const rows = entries.map(([key, value]) =>
+    el('tr', {}, el('td', {}, key), el('td', {}, valueCell(value))),
+  )
+
+  section.append(...collapseProps(table, rows, `test:${test.id}`))
+
+  return section
+}
+
 /**
- * The inspector's sections for one test: status, component props, the
- * current frame or the live section, errors.
+ * The inspector's sections for one test: status and tags, component props,
+ * the current frame or the live section, errors.
  */
 export function renderInspector(): HTMLElement[] {
   const test = currentTest()
@@ -56,19 +85,15 @@ export function renderInspector(): HTMLElement[] {
     ),
   )
 
+  const tags = tagButtons(test)
+  if (tags) {
+    status.append(tags)
+  }
+
   sections.push(status)
 
   if (test.component) {
-    const table = el('table', { class: 'kv' })
-    for (const [key, value] of Object.entries(props)) {
-      table.append(el('tr', {}, el('td', {}, key), el('td', {}, valueCell(value))))
-    }
-
-    if (!Object.keys(props).length) {
-      table.append(el('tr', {}, el('td', {}, el('span', { class: 'hint' }, 'no props'))))
-    }
-
-    sections.push(el('section', {}, el('h3', {}, `component · ${test.component.name}`), table))
+    sections.push(propsSection(test, test.component.name, props))
   }
 
   if (live) {

package/src/keyboard.ts

@@ -1,4 +1,5 @@
 import type { ManifestTest } from '@describe-me/core/types'
+import { filterActive } from './filter-active.js'
 import { liveShown } from './live-shown.js'
 import { regions } from './regions.js'
 import { rerender } from './rerender.js'
@@ -36,7 +37,8 @@ function nearestShown(shown: ManifestTest[], id: string, step: 1 | -1): Manifest
 /**
  * The next or previous test the sidebar shows. From a test hidden in a
  * collapsed suite, that is the nearest shown row in sidebar order. From a test
- * the search does not match, ↓ enters at the first match and ↑ at the last.
+ * the search or the tag filter leaves out, ↓ enters at the first match and ↑
+ * at the last.
  */
 function neighbour(id: string, step: 1 | -1): ManifestTest | undefined {
   const tests = visibleTests()
@@ -45,7 +47,7 @@ function neighbour(id: string, step: 1 | -1): ManifestTest | undefined {
     return tests[index + step]
   }
 
-  if (state.query.trim() === '') {
+  if (!filterActive()) {
     return nearestShown(tests, id, step)
   }
 
@@ -105,6 +107,11 @@ export function onKey(event: KeyboardEvent): void {
     return
   }
 
+  // The handle takes ← → for its width, and no other shortcut fits while it has focus.
+  if (event.target === regions().sidebarHandle) {
+    return
+  }
+
   if (isSearchKey(event)) {
     const { search } = regions()
     search.focus()

package/src/main.ts

@@ -10,6 +10,7 @@ import { renderAll } from './render-all.js'
 import { renderFrame } from './render-frame.js'
 import { setRerender } from './rerender.js'
 import { wireSearchField } from './search-field.js'
+import { wireSidebarHandle } from './sidebar-handle.js'
 import { stateHash } from './state-hash.js'
 import { readHash, state } from './state.js'
 import { syncSelection } from './sync-selection.js'
@@ -45,10 +46,11 @@ window.addEventListener('popstate', onLocationChange)
 window.addEventListener('hashchange', onLocationChange)
 listenToLive()
 wireSearchField(regions().search)
+wireSidebarHandle(regions().sidebarHandle)
 
 loadManifest().catch((err) => {
-  const { header, center } = regions()
-  header.replaceChildren(...renderHeader())
+  const { headerInfo, center } = regions()
+  headerInfo.replaceChildren(...renderHeader())
   center.replaceChildren(
     el('div', { class: 'empty' }, `no manifest yet — run vitest first (${String(err)})`),
   )

package/src/matches-filter.ts

@@ -0,0 +1,12 @@
+import type { ManifestTest } from '@describe-me/core/types'
+import { matchesQuery } from './matches-query.js'
+import { state } from './state.js'
+
+/** Whether the sidebar shows the test: it matches the search and carries the tag filtered by. */
+export function matchesFilter(test: ManifestTest, moduleId: string): boolean {
+  if (state.tag !== null && !(test.tags ?? []).includes(state.tag)) {
+    return false
+  }
+
+  return matchesQuery(test, moduleId, state.query)
+}

package/src/matches-query.ts

@@ -1,10 +1,14 @@
 import type { ManifestTest } from '@describe-me/core/types'
+import { shownTags } from './shown-tags.js'
 
-/** Whether every word of the sidebar's search occurs in the test's full name, file or component. */
+/**
+ * Whether every word of the sidebar's search occurs in the test's full name,
+ * file, component or tags.
+ */
 export function matchesQuery(test: ManifestTest, moduleId: string, query: string): boolean {
   const terms = query.trim().toLowerCase().split(/\s+/).filter(Boolean)
-  const fields = [test.fullName, moduleId, test.component?.name ?? ''].map((field) =>
-    field.toLowerCase(),
+  const fields = [test.fullName, moduleId, test.component?.name ?? '', ...shownTags(test)].map(
+    (field) => field.toLowerCase(),
   )
 
   return terms.every((term) => fields.some((field) => field.includes(term)))

package/src/overview.ts

@@ -42,11 +42,12 @@ function renderComponent(
   }
 
   section.append(el('h3', {}, 'props'))
+  const key = `component:${name}`
   if (doc) {
-    section.append(renderPropsTable(computeCoverage(doc, tests)))
+    section.append(...renderPropsTable(computeCoverage(doc, tests), key))
   } else {
     const hint = 'no type information (rerun tests with the latest reporter)'
-    section.append(renderPropsTable([]), el('div', { class: 'hint' }, hint))
+    section.append(...renderPropsTable([], key), el('div', { class: 'hint' }, hint))
   }
 
   section.append(

package/src/paint-live.ts

@@ -5,6 +5,9 @@ import { liveSrc } from './live-src.js'
 import { resetLiveSession } from './reset-live-session.js'
 import { state } from './state.js'
 
+/** The fade of the live frame and of the underlay. Matches the transitions in `style.css`. */
+const FADE_MS = 150
+
 /** The live slot on the stage, when it shows `src` and no Restart came since. */
 function keptSlot(frames: HTMLElement, src: string): HTMLElement | null {
   const slot = frames.querySelector<HTMLElement>(':scope > .live-slot')
@@ -16,7 +19,7 @@ function keptSlot(frames: HTMLElement, src: string): HTMLElement | null {
 /** No `sandbox`: the live page runs the component, its scripts and its timers. */
 function buildSlot(test: ManifestTest, src: string): HTMLElement {
   const iframe = el('iframe', { src, title: `${test.fullName}, live` })
-  const slot = el('div', { class: 'stage-slot live-slot' }, iframe)
+  const slot = el('div', { class: 'stage-slot live-slot loading' }, iframe)
 
   // Never `generatedAt` or `frame`, so the stage never takes it for a recorded frame.
   slot.dataset.test = test.id
@@ -26,10 +29,59 @@ function buildSlot(test: ManifestTest, src: string): HTMLElement {
 }
 
 /**
- * Put the live slot of `test` on the stage, alone. A slot that already shows
- * the same page stays, so a size change, an overview or a manifest reload
- * keeps the component's state. A new test, a Restart or another base builds
- * a new frame with a fresh session.
+ * The slot that stays under the live frame of `test` while it loads: the one
+ * already there, or, for a new live frame, the recorded frame of the same test
+ * turned into one in place. A frame of another test never stays.
+ */
+function pickUnderlay(frames: HTMLElement, test: ManifestTest, built: boolean): HTMLElement | null {
+  const underlay = frames.querySelector<HTMLElement>(':scope > .live-underlay')
+
+  if (underlay?.dataset.test === test.id) {
+    return underlay
+  }
+
+  const recorded = frames.querySelector<HTMLElement>(
+    ':scope > .stage-slot[data-frame]:not(.incoming)',
+  )
+
+  if (!built || recorded?.dataset.test !== test.id) {
+    return null
+  }
+
+  // Without `frame` the stage never takes it for a recorded frame, and `data-auto`
+  // keeps its scheme. `inert`, because a dimmed iframe paints above the live one.
+  recorded.classList.add('live-underlay')
+  recorded.inert = true
+  delete recorded.dataset.frame
+  delete recorded.dataset.generatedAt
+
+  return recorded
+}
+
+/**
+ * End the loading state once the live page reported a status, whatever it is.
+ * Every paint runs it, and a timer rather than `transitionend` removes the
+ * underlay, because reduced motion has no transition to end.
+ */
+function settle(slot: HTMLElement, underlay: HTMLElement | null): void {
+  const loading = liveSession.status === 'loading'
+
+  slot.classList.toggle('loading', loading)
+
+  if (loading || !underlay || underlay.classList.contains('leaving')) {
+    return
+  }
+
+  underlay.classList.add('leaving')
+  setTimeout(() => underlay.remove(), FADE_MS)
+}
+
+/**
+ * Put the live slot of `test` on the stage. A slot that already shows the same
+ * page stays, so a size change, an overview or a manifest reload keeps the
+ * component's state. A new test, a Restart or another base builds a new frame
+ * with a fresh session. A new frame loads see-through over the dimmed recorded
+ * frame of the same test, until its page reports a status.
  */
 export function paintLive(stage: HTMLElement, frames: HTMLElement, test: ManifestTest): void {
   const base = state.preview.base
@@ -41,21 +93,24 @@ export function paintLive(stage: HTMLElement, frames: HTMLElement, test: Manifes
 
   const kept = keptSlot(frames, src)
   const slot = kept ?? buildSlot(test, src)
+  const underlay = pickUnderlay(frames, test, kept === null)
   const previousTest = frames.querySelector<HTMLElement>(':scope > .stage-slot')?.dataset.test
 
   // Slots leave only through `remove()`. Moving one elsewhere would reload its iframe blank.
   for (const child of Array.from(frames.children)) {
-    if (child !== slot) {
+    if (child !== slot && child !== underlay) {
       child.remove()
     }
   }
 
   if (kept) {
+    settle(slot, underlay)
     return
   }
 
   resetLiveSession(test.id)
   frames.append(slot)
+  settle(slot, underlay)
 
   if (previousTest !== test.id) {
     stage.scrollTo(0, 0)

package/src/parse-stage-background.ts

@@ -0,0 +1,11 @@
+/** What the stage's canvas shows, and the color scheme of the frames on it. */
+export type StageBackground = 'auto' | 'light' | 'dark' | 'transparent'
+
+/** The background a link's `bg` names. Anything else, a missing value included, is `'auto'`. */
+export function parseStageBackground(text: string | null): StageBackground {
+  if (text === 'light' || text === 'dark' || text === 'transparent') {
+    return text
+  }
+
+  return 'auto'
+}

package/src/props-table.ts

@@ -1,3 +1,4 @@
+import { collapseProps } from './collapse-props.js'
 import type { CoverageEntry, PropCoverage } from './coverage.js'
 import { el } from './el.js'
 
@@ -45,28 +46,31 @@ function coveredCell(coverage: PropCoverage): HTMLElement {
   return cell
 }
 
-/** The props of one component as a table: name, type, and which values the tests covered. */
-export function renderPropsTable(coverage: PropCoverage[]): HTMLElement {
+/**
+ * The props of one component as a table: name, type, and which values the tests
+ * covered. A long table folds, and `key` keeps it unfolded across repaints.
+ */
+export function renderPropsTable(coverage: PropCoverage[], key: string): HTMLElement[] {
   const table = el('table', { class: 'kv props' })
   table.append(el('tr', {}, el('th', {}, 'prop'), el('th', {}, 'type'), el('th', {}, 'covered')))
 
-  for (const item of coverage) {
-    table.append(
-      el(
-        'tr',
-        {},
-        nameCell(item),
-        el('td', { class: 'prop-type' }, item.prop.type),
-        coveredCell(item),
-      ),
-    )
-  }
-
   if (!coverage.length) {
     table.append(
       el('tr', {}, el('td', { colspan: '3' }, el('span', { class: 'hint' }, 'no props'))),
     )
+
+    return [table]
   }
 
-  return table
+  const rows = coverage.map((item) =>
+    el(
+      'tr',
+      {},
+      nameCell(item),
+      el('td', { class: 'prop-type' }, item.prop.type),
+      coveredCell(item),
+    ),
+  )
+
+  return collapseProps(table, rows, key)
 }

package/src/regions.ts

@@ -1,16 +1,25 @@
 import { el } from './el.js'
+import { SidebarWidth } from './sidebar-width.js'
+import { renderThemeSwitch } from './theme-switch.js'
 
 export interface Regions {
-  header: HTMLElement
+  /** The wordmark, counts, issues and run time in the header, which repaints fill. */
+  headerInfo: HTMLElement
   /** The version warning under the header, hidden unless the data comes from another release line. */
   banner: HTMLElement
   sidebar: HTMLElement
   /** The sidebar's search field, above the tree. */
   search: HTMLInputElement
+  /** The tag the tree is narrowed to, between the search and the tree. Hidden without one. */
+  tagFilter: HTMLElement
   /** The sidebar's module blocks go here. */
   tree: HTMLElement
+  /** The separator on the sidebar's right edge that sets its width. */
+  sidebarHandle: HTMLElement
   center: HTMLElement
   inspector: HTMLElement
+  /** The grid of sidebar, handle, center and inspector, which holds `--sidebar-width`. */
+  columns: HTMLElement
 }
 
 let built: Regions | null = null
@@ -24,7 +33,8 @@ export function regions(): Regions {
     return built
   }
 
-  const header = el('header', { class: 'header' })
+  const headerInfo = el('div', { class: 'header-info' })
+  const header = el('header', { class: 'header' }, headerInfo, renderThemeSwitch())
   const banner = el('div', { class: 'version-banner', role: 'status', hidden: true })
   const search = el('input', {
     class: 'sidebar-search',
@@ -33,16 +43,38 @@ export function regions(): Regions {
     'aria-label': 'Search tests',
   })
 
+  const tagFilter = el('div', { class: 'tag-filter', role: 'status', hidden: true })
   const tree = el('div', { class: 'tree' })
-  const sidebar = el('aside', { class: 'sidebar' }, search, tree)
+  const sidebar = el('aside', { class: 'sidebar' }, search, tagFilter, tree)
+  // Outside the sidebar, which scrolls, so the handle stays put while the tree moves.
+  const sidebarHandle = el('div', {
+    class: 'sidebar-handle',
+    role: 'separator',
+    'aria-orientation': 'vertical',
+    'aria-label': 'Sidebar width',
+    'aria-valuemin': String(SidebarWidth.MIN),
+    tabindex: '0',
+    title: 'Drag to resize. Double-click to reset.',
+  })
+
   const center = el('div', { class: 'center' })
   const inspector = el('aside', { class: 'inspector' })
+  const columns = el('div', { class: 'body' }, sidebar, sidebarHandle, center, inspector)
 
-  document
-    .getElementById('app')!
-    .replaceChildren(header, banner, el('div', { class: 'body' }, sidebar, center, inspector))
+  document.getElementById('app')!.replaceChildren(header, banner, columns)
 
-  built = { header, banner, sidebar, search, tree, center, inspector }
+  built = {
+    headerInfo,
+    banner,
+    sidebar,
+    search,
+    tagFilter,
+    tree,
+    sidebarHandle,
+    center,
+    inspector,
+    columns,
+  }
 
   return built
 }

package/src/render-all.ts

@@ -5,6 +5,7 @@ import { renderOverviewInspector } from './overview-inspector.js'
 import { regions } from './regions.js'
 import { renderFrame } from './render-frame.js'
 import { renderTree } from './render-tree.js'
+import { showSidebarWidth } from './show-sidebar-width.js'
 import { state } from './state.js'
 import { testView } from './test-view.js'
 import { versionBanner } from './version-banner.js'
@@ -53,13 +54,14 @@ function showTest(center: HTMLElement): void {
 
 /** Repaint every region from `state`: the overview when a suite is selected, else one test. */
 export function renderAll(): void {
-  const { header, banner, center, inspector } = regions()
-  header.replaceChildren(...renderHeader())
+  const { headerInfo, banner, center, inspector } = regions()
+  headerInfo.replaceChildren(...renderHeader())
 
   const text = versionBanner(state.manifest)
   banner.textContent = text ?? ''
   banner.hidden = text === null
 
+  showSidebarWidth()
   renderTree()
 
   if (state.suiteKey) {