describe-me 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "describe-me",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Living component documentation generated from your Vitest tests: viewer and CLI",
   "keywords": [
     "vitest",
@@ -43,13 +43,13 @@
   "dependencies": {
     "rrweb-snapshot": "^2.1.6",
     "vite": "^8.3.0",
-    "@describe-me/core": "^0.2.0"
+    "@describe-me/core": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "^22"
   },
   "scripts": {
     "build": "rimraf dist-cli && tsc -p tsconfig.cli.json",
-    "dev": "node dist-cli/main.js dev --data ../../examples/react-basic/.describe-me"
+    "dev": "node dist-cli/main.js dev --data ../../examples/react-browser/.describe-me"
   }
 }

package/src/data.ts

@@ -1,5 +1,5 @@
 import type { rebuildIntoSandboxedIframe } from 'rrweb-snapshot'
-import type { Manifest } from '@describe-me/core/types'
+import { ASSET_URL_PREFIX, type Manifest } from '@describe-me/core/types'
 import { allTests, currentTest, state } from './state.js'
 import { rerender } from './rerender.js'
 
@@ -39,16 +39,27 @@ export async function loadManifest(): Promise<void> {
   rerender()
 }
 
-/** Fetch one serialized DOM, memoized until the next manifest load. */
+/**
+ * Fetch one serialized DOM, memoized until the next manifest load. Asset URLs
+ * are made absolute here, against the page, because the snapshot replays in a
+ * sandboxed iframe that has no base URL of its own. The stage and the gallery
+ * thumbnails both load through this.
+ */
 export function loadSnapshot(path: string): Promise<SerializedNode> {
   let pending = snapshotCache.get(path)
   if (!pending) {
-    pending = fetch(`__data/${path}`, { cache: 'no-store' }).then(
-      (response) => response.json() as Promise<SerializedNode>,
-    )
+    pending = fetch(`__data/${path}`, { cache: 'no-store' })
+      .then((response) => response.text())
+      .then((json) => parseSnapshot(json))
 
     snapshotCache.set(path, pending)
   }
 
   return pending
 }
+
+function parseSnapshot(json: string): SerializedNode {
+  const assetsUrl = new URL('__data/assets/', location.href).href
+
+  return JSON.parse(json.replaceAll(ASSET_URL_PREFIX, assetsUrl)) as SerializedNode
+}

package/src/diagnostics-menu.ts

@@ -0,0 +1,102 @@
+import { manifestDiagnostics } from '@describe-me/core/diagnostics'
+import type { Manifest } from '@describe-me/core/types'
+import { el } from './el.js'
+import { select } from './state.js'
+
+/** Long lists are cut here; the rest is summed up in one line. */
+const LIST_LIMIT = 40
+
+function section(title: string, hint: string, items: HTMLElement[]): HTMLElement {
+  const shown = items.slice(0, LIST_LIMIT)
+  const rest = items.length - shown.length
+  const list = el('ul', { class: 'issues-list' }, ...shown)
+
+  if (rest > 0) {
+    list.append(el('li', { class: 'issues-more' }, `+${rest} more`))
+  }
+
+  return el(
+    'section',
+    { class: 'issues-section' },
+    el('h3', {}, title, el('span', { class: 'issues-count' }, String(items.length))),
+    el('p', { class: 'issues-hint' }, hint),
+    list,
+  )
+}
+
+/**
+ * A header chip that opens the list of what this manifest could not document:
+ * anonymous components, components without props docs and assets that will not
+ * load. Absent when there is nothing to report.
+ */
+export function renderDiagnosticsMenu(manifest: Manifest): HTMLElement | null {
+  const { anonymous, undocumented, assetsMissing } = manifestDiagnostics(manifest)
+  const count = anonymous.length + undocumented.length + assetsMissing.length
+
+  if (count === 0) {
+    return null
+  }
+
+  const sections: HTMLElement[] = []
+
+  if (anonymous.length > 0) {
+    const items = anonymous.map((test) =>
+      el(
+        'li',
+        {},
+        el('button', { class: 'issues-link', click: () => select(test.testId) }, test.fullName),
+      ),
+    )
+
+    sections.push(
+      section(
+        'Anonymous components',
+        'Export the component from a project module (it is named after its export) or give it a displayName.',
+        items,
+      ),
+    )
+  }
+
+  if (undocumented.length > 0) {
+    const items = undocumented.map((component) =>
+      el(
+        'li',
+        {},
+        el('span', { class: 'mono' }, component.name),
+        el('span', { class: 'issues-meta' }, `${component.tests} tests`),
+      ),
+    )
+
+    sections.push(
+      section(
+        'No props docs',
+        'Its props could not be read: is it exported from a TypeScript module, and is typescript installed?',
+        items,
+      ),
+    )
+  }
+
+  if (assetsMissing.length > 0) {
+    const items = assetsMissing.map((path) => el('li', { class: 'mono' }, path))
+
+    sections.push(
+      section(
+        'Assets not found',
+        'Not found under the project root or public/, so they will not load here.',
+        items,
+      ),
+    )
+  }
+
+  return el(
+    'details',
+    { class: 'issues' },
+    el(
+      'summary',
+      { class: 'stat warn' },
+      el('b', {}, String(count)),
+      count === 1 ? 'issue' : 'issues',
+    ),
+    el('div', { class: 'issues-panel' }, ...sections),
+  )
+}

package/src/header.ts

@@ -1,3 +1,4 @@
+import { renderDiagnosticsMenu } from './diagnostics-menu.js'
 import { el } from './el.js'
 import { allTests, state } from './state.js'
 
@@ -5,7 +6,7 @@ function stat(count: number, label: string, tone?: 'pass' | 'fail'): HTMLElement
   return el('span', { class: tone ? `stat ${tone}` : 'stat' }, el('b', {}, String(count)), label)
 }
 
-/** Wordmark, pass/fail counts and the time of the last run. */
+/** Wordmark, pass/fail counts, what could not be documented and the time of the last run. */
 export function renderHeader(): HTMLElement {
   const manifest = state.manifest
   const tests = manifest ? allTests(manifest) : []
@@ -26,6 +27,7 @@ export function renderHeader(): HTMLElement {
     { class: 'header' },
     wordmark,
     summary,
+    manifest && renderDiagnosticsMenu(manifest),
     el('span', { class: 'right live' }, 'updated ', el('span', { class: 'mono' }, when)),
   )
 }

package/src/style.css

@@ -208,6 +208,104 @@ a {
   box-shadow: 0 0 0 3px color-mix(in srgb, var(--pass) 18%, transparent);
 }
 
+/* ---------------------------------------------------------- diagnostics -- */
+
+.issues {
+  position: relative;
+  font-size: 12px;
+}
+.issues > summary {
+  padding: 2px 9px;
+  border-radius: var(--r-pill);
+  background: color-mix(in srgb, var(--warn) 12%, transparent);
+  color: var(--warn);
+  cursor: pointer;
+  list-style: none;
+}
+.issues > summary::-webkit-details-marker {
+  display: none;
+}
+.issues > summary b {
+  color: inherit;
+}
+.issues[open] > summary {
+  box-shadow: 0 0 0 2px var(--ring);
+}
+.issues-panel {
+  position: absolute;
+  top: calc(100% + 8px);
+  left: 0;
+  z-index: 20;
+  width: 440px;
+  max-height: 70vh;
+  overflow: auto;
+  padding: 6px 0;
+  border: 1px solid var(--line);
+  border-radius: var(--r-lg);
+  background: var(--raised);
+  box-shadow: var(--shadow-md);
+}
+.issues-section {
+  padding: 10px 16px;
+}
+.issues-section + .issues-section {
+  border-top: 1px solid var(--line-soft);
+}
+.issues-section h3 {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  margin: 0;
+  color: var(--ink);
+  font-size: 12px;
+  font-weight: 600;
+}
+.issues-count {
+  color: var(--ink-3);
+  font-weight: 400;
+  font-variant-numeric: tabular-nums;
+}
+.issues-hint {
+  margin: 4px 0 8px;
+  color: var(--ink-3);
+  line-height: 1.45;
+}
+.issues-list {
+  display: grid;
+  gap: 2px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.issues-list li {
+  display: flex;
+  justify-content: space-between;
+  gap: 12px;
+  overflow: hidden;
+  color: var(--ink-2);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.issues-link {
+  overflow: hidden;
+  padding: 2px 0;
+  border: 0;
+  background: none;
+  color: var(--accent);
+  font: inherit;
+  text-align: left;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  cursor: pointer;
+}
+.issues-link:hover {
+  text-decoration: underline;
+}
+.issues-meta,
+.issues-more {
+  color: var(--ink-3);
+}
+
 /* -------------------------------------------------------------- sidebar -- */
 
 .sidebar {

package/vite.config.ts

@@ -1,10 +1,34 @@
 import { cpSync, existsSync, readFileSync, statSync, watch } from 'node:fs'
-import { dirname, join, resolve, sep } from 'node:path'
+import { dirname, extname, join, resolve, sep } from 'node:path'
 import { defineConfig, type Plugin } from 'vite'
 
+/** Content types of what the data directory holds: the manifest, snapshots and copied project assets. */
+const CONTENT_TYPES: Record<string, string> = {
+  '.json': 'application/json',
+  '.css': 'text/css',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+}
+
+function contentType(file: string): string {
+  return CONTENT_TYPES[extname(file).toLowerCase()] ?? 'application/octet-stream'
+}
+
 /** Where the manifest and snapshots live. The CLI sets this; the default is the example project. */
 function dataDir(): string {
-  return resolve(process.env.DESCRIBE_ME_DIR ?? '../../examples/react-basic/.describe-me')
+  return resolve(process.env.DESCRIBE_ME_DIR ?? '../../examples/react-browser/.describe-me')
 }
 
 /**
@@ -60,7 +84,7 @@ function describeMeData(): Plugin {
           return next()
         }
 
-        response.setHeader('Content-Type', 'application/json')
+        response.setHeader('Content-Type', contentType(absolute))
         response.setHeader('Cache-Control', 'no-store')
         response.end(readFileSync(absolute))
       })