describe-me 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "describe-me",
-  "version": "0.6.0",
+  "version": "0.7.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.0"
+    "@describe-me/core": "^0.7.0"
   },
   "peerDependencies": {
     "vite": "^6.4.0 || ^7.0.0 || ^8.0.0"

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

@@ -2,6 +2,7 @@ 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 {
@@ -26,8 +27,8 @@ function keyHint(): HTMLElement {
 }
 
 /**
- * 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,6 +57,11 @@ export function renderInspector(): HTMLElement[] {
     ),
   )
 
+  const tags = tagButtons(test)
+  if (tags) {
+    status.append(tags)
+  }
+
   sections.push(status)
 
   if (test.component) {

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)
   }
 

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/regions.ts

@@ -7,6 +7,8 @@ export interface Regions {
   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
   center: HTMLElement
@@ -33,8 +35,9 @@ 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)
   const center = el('div', { class: 'center' })
   const inspector = el('aside', { class: 'inspector' })
 
@@ -42,7 +45,7 @@ export function regions(): Regions {
     .getElementById('app')!
     .replaceChildren(header, banner, el('div', { class: 'body' }, sidebar, center, inspector))
 
-  built = { header, banner, sidebar, search, tree, center, inspector }
+  built = { header, banner, sidebar, search, tagFilter, tree, center, inspector }
 
   return built
 }

package/src/render-tree.ts

@@ -4,6 +4,7 @@ import { regions } from './regions.js'
 import { renderSidebar } from './sidebar.js'
 import { currentTest, state } from './state.js'
 import { suiteKey } from './suite-key.js'
+import { tagFilterBar } from './tag-filter-bar.js'
 
 let revealed: string | null = null
 
@@ -20,12 +21,12 @@ function expandPathTo(test: ManifestTest): void {
 }
 
 /**
- * Fill the sidebar's tree. A test selected since the last reveal gets its
- * module and suites opened and its row scrolled into view. A refresh that
- * keeps the test leaves the sidebar's scroll alone.
+ * Fill the sidebar's tree and the tag filter above it. A test selected since
+ * the last reveal gets its module and suites opened and its row scrolled into
+ * view. A refresh that keeps the test leaves the sidebar's scroll alone.
  */
 export function renderTree(): void {
-  const { tree } = regions()
+  const { tagFilter, tree } = regions()
   const test = state.suiteKey ? null : currentTest()
   const reveal = test !== null && test.id !== revealed
 
@@ -39,6 +40,8 @@ export function renderTree(): void {
     revealed = test.id
   }
 
+  tagFilter.replaceChildren(...tagFilterBar())
+  tagFilter.hidden = state.tag === null
   tree.replaceChildren(...renderSidebar(renderTree))
 
   if (reveal) {

package/src/shown-tags.ts

@@ -0,0 +1,11 @@
+import { DOCS_TAG, NO_DOCS_TAG, type ManifestTest } from '@describe-me/core/types'
+
+const HIDDEN = new Set<string>([DOCS_TAG, NO_DOCS_TAG])
+
+/**
+ * The tags the viewer shows for a test. `docs` and `no-docs` only pick which
+ * tests record, and with `stories: 'tagged'` every story carries `docs`.
+ */
+export function shownTags(test: ManifestTest): string[] {
+  return (test.tags ?? []).filter((tag) => !HIDDEN.has(tag))
+}

package/src/sidebar.ts

@@ -1,13 +1,15 @@
 import type { ManifestModule, ManifestTest } from '@describe-me/core/types'
 import { CollapsedSuites } from './collapsed-suites.js'
 import { el } from './el.js'
-import { matchesQuery } from './matches-query.js'
+import { filterActive } from './filter-active.js'
+import { matchesFilter } from './matches-filter.js'
+import { shownTags } from './shown-tags.js'
 import { soleSuite } from './sole-suite.js'
 import { select, selectSuite, state } from './state.js'
 import { suiteKey } from './suite-key.js'
 import { buildTree, type SuiteNode } from './tree.js'
 
-/** What every row of one repaint needs to know. `collapsed` is `null` while a search is on. */
+/** What every row of one repaint needs to know. `collapsed` is `null` while a filter is on. */
 interface Walk {
   moduleId: string
   collapsed: CollapsedSuites | null
@@ -69,6 +71,17 @@ function suiteButton(label: string, key: string): HTMLElement {
   )
 }
 
+/** The test's tags, quiet next to its name. A row is a button, so they are not buttons too. */
+function tagChips(test: ManifestTest): HTMLElement | null {
+  const tags = shownTags(test)
+
+  if (tags.length === 0) {
+    return null
+  }
+
+  return el('span', { class: 'test-tags' }, ...tags.map((tag) => el('span', { class: 'tag' }, tag)))
+}
+
 function testButton(test: ManifestTest): HTMLElement {
   return el(
     'button',
@@ -79,16 +92,17 @@ function testButton(test: ManifestTest): HTMLElement {
     },
     el('span', { class: `dot ${test.state}` }),
     el('span', { class: 'test-name' }, test.name),
+    tagChips(test),
     el('span', { class: 'n' }, String(test.frames.length)),
   )
 }
 
-/** The rows under one suite, in source order. A search leaves out tests that do not match. */
+/** The rows under one suite, in source order. A filter leaves out tests that do not match. */
 function renderRows(node: SuiteNode, path: string[], walk: Walk): DocumentFragment {
   const rows = document.createDocumentFragment()
   for (const child of node.children) {
     if (!('suites' in child)) {
-      if (matchesQuery(child, walk.moduleId, state.query)) {
+      if (matchesFilter(child, walk.moduleId)) {
         rows.append(testButton(child))
       }
 
@@ -104,7 +118,7 @@ function renderRows(node: SuiteNode, path: string[], walk: Walk): DocumentFragme
   return rows
 }
 
-/** A suite and its rows, or `null` when a search leaves nothing in it. */
+/** A suite and its rows, or `null` when a filter leaves nothing in it. */
 function renderSuite(node: SuiteNode, path: string[], walk: Walk): HTMLElement | null {
   const key = suiteKey(walk.moduleId, path)
   const header = headerRow(suiteButton(node.name, key), node.name, key, walk)
@@ -121,14 +135,14 @@ function renderSuite(node: SuiteNode, path: string[], walk: Walk): HTMLElement |
   return el('div', { class: 'suite' }, header, rows)
 }
 
-/** A module block, or `null` when a search leaves nothing in it. */
+/** A module block, or `null` when a filter leaves nothing in it. */
 function renderModule(
   mod: ManifestModule,
   collapsed: CollapsedSuites | null,
   onToggle: () => void,
 ): HTMLElement | null {
   const walk: Walk = { moduleId: mod.id, collapsed, onToggle }
-  // On the whole tree, so a module header keeps its shape while a search narrows it.
+  // On the whole tree, so a module header keeps its shape while a filter narrows it.
   const root = buildTree(mod)
   const only = soleSuite(root)
   const path = only ? [only.name] : []
@@ -152,9 +166,22 @@ function renderModule(
   return el('div', { class: 'module' }, header, el('div', { class: 'suite root' }, rows))
 }
 
+/** What the empty sidebar says, naming the search, the tag or both. */
+function noMatches(): string {
+  const query = state.query.trim()
+
+  if (state.tag === null) {
+    return `no tests match "${query}"`
+  }
+
+  return query
+    ? `no tests tagged "${state.tag}" match "${query}"`
+    : `no tests tagged "${state.tag}"`
+}
+
 /**
  * One block per test module, each holding its suite tree, or a line saying the
- * search found nothing. `onToggle` repaints after a module or suite opens or closes.
+ * filter found nothing. `onToggle` repaints after a module or suite opens or closes.
  */
 export function renderSidebar(onToggle: () => void): HTMLElement[] {
   const manifest = state.manifest
@@ -162,14 +189,14 @@ export function renderSidebar(onToggle: () => void): HTMLElement[] {
     return []
   }
 
-  const query = state.query.trim()
-  const collapsed = query ? null : CollapsedSuites.for(manifest.root)
+  const filtered = filterActive()
+  const collapsed = filtered ? null : CollapsedSuites.for(manifest.root)
   const blocks = manifest.modules
     .map((mod) => renderModule(mod, collapsed, onToggle))
     .filter((block): block is HTMLElement => block !== null)
 
-  if (blocks.length === 0 && query) {
-    return [el('div', { class: 'empty' }, `no tests match "${query}"`)]
+  if (blocks.length === 0 && filtered) {
+    return [el('div', { class: 'empty' }, noMatches())]
   }
 
   return blocks

package/src/state-hash.ts

@@ -1,6 +1,9 @@
 import type { State } from './state.js'
 
-/** The link of a view, without the `#`: the selection, the frame, the viewport size and Live. */
+/**
+ * The link of a view, without the `#`: the selection, the frame, the viewport
+ * size, Live and the tag filter.
+ */
 export function stateHash(state: State): string {
   const params = new URLSearchParams()
   if (state.suiteKey) {
@@ -27,5 +30,9 @@ export function stateHash(state: State): string {
     params.set('live', '1')
   }
 
+  if (state.tag !== null) {
+    params.set('tag', state.tag)
+  }
+
   return params.toString()
 }

package/src/state.ts

@@ -23,6 +23,8 @@ export interface State {
   scale: number
   /** The sidebar's search. Neither in the link nor stored. */
   query: string
+  /** The tag the sidebar is narrowed to. `tag=` in the link, so a filtered list can be shared. */
+  tag: string | null
 }
 
 export const state: State = {
@@ -36,6 +38,7 @@ export const state: State = {
   issuesOpen: false,
   scale: 1,
   query: '',
+  tag: null,
 }
 
 export function readHash(): void {
@@ -44,6 +47,7 @@ export function readHash(): void {
   state.suiteKey = params.get('suite')
   state.frame = Number(params.get('frame') ?? 0) || 0
   state.live = params.get('live') === '1'
+  state.tag = params.get('tag') || null
   state.viewport = {
     width: parseViewportSize(params.get('w')),
     height: parseViewportSize(params.get('h'), MIN_FRAME_HEIGHT),
@@ -87,6 +91,13 @@ export function select(testId: string, frame = 0, mode: 'push' | 'replace' = 'pu
   rerender()
 }
 
+/** Narrow the sidebar to the tests with `tag`, or show every test again with `null`. */
+export function filterByTag(tag: string | null): void {
+  state.tag = tag
+  writeHash('push')
+  rerender()
+}
+
 /** Show the overview of a suite or module. The selected test is kept, so going back works. */
 export function selectSuite(key: string): void {
   state.suiteKey = key

package/src/style.css

@@ -378,6 +378,32 @@ a {
   border-color: var(--ring);
   outline-offset: 0;
 }
+/* The tag the tree is narrowed to, under the search. Clearing it is one click away. */
+.tag-filter {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  margin: -6px 0 12px;
+  padding: 0 9px;
+  color: var(--ink-3);
+  font-size: 12px;
+}
+.tag-filter[hidden] {
+  display: none;
+}
+.tag-filter-clear {
+  margin-left: auto;
+  width: 20px;
+  height: 20px;
+  border-radius: var(--r-sm);
+  color: var(--ink-3);
+  line-height: 1;
+}
+.tag-filter-clear:hover {
+  background: var(--hover);
+  color: var(--ink);
+}
+
 .tree > .empty {
   padding: 4px 9px;
   color: var(--ink-3);
@@ -518,6 +544,37 @@ a {
   border-radius: 0 2px 2px 0;
   background: var(--accent);
 }
+/* Tags come from the codebase, so they are set in the mono face, quiet next to the name. */
+.tag {
+  display: inline-block;
+  padding: 0 7px;
+  border-radius: var(--r-pill);
+  background: var(--tint);
+  color: var(--accent);
+  font-family: var(--font-mono);
+  font-size: 10.5px;
+  font-weight: 400;
+  line-height: 17px;
+  white-space: nowrap;
+}
+.test-tags {
+  display: inline-flex;
+  flex-shrink: 0;
+  gap: 4px;
+}
+.tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin-top: 10px;
+}
+button.tag:hover {
+  background: var(--tint-strong);
+}
+button.tag.active {
+  background: var(--accent);
+  color: var(--panel);
+}
 .test .n {
   margin-left: auto;
   color: var(--ink-3);

package/src/sync-selection.ts

@@ -1,11 +1,24 @@
+import type { Manifest, ManifestTest } from '@describe-me/core/types'
+import { filterActive } from './filter-active.js'
 import { resolveTestId } from './resolve-test-id.js'
 import { stateHash } from './state-hash.js'
 import { allTests, currentTest, state, writeHash } from './state.js'
+import { visibleTests } from './visible-tests.js'
+
+/**
+ * The first test, or the first a filter leaves, so a link with only a tag
+ * opens one of its tests.
+ */
+function firstTest(manifest: Manifest): ManifestTest | undefined {
+  const shown = filterActive() ? visibleTests() : []
+
+  return shown[0] ?? allTests(manifest)[0]
+}
 
 /**
  * Point the selection at a test the manifest holds, falling back to the first
- * one, and clamp the frame. The link is corrected in place, without a history
- * entry. Does not repaint.
+ * one the search and the tag leave, and clamp the frame. The link is corrected
+ * in place, without a history entry. Does not repaint.
  */
 export function syncSelection(): void {
   if (!state.manifest) {
@@ -16,7 +29,7 @@ export function syncSelection(): void {
   if (resolved) {
     state.testId = resolved
   } else {
-    state.testId = allTests(state.manifest)[0]?.id ?? null
+    state.testId = firstTest(state.manifest)?.id ?? null
     state.frame = 0
   }
 

package/src/tag-buttons.ts

@@ -0,0 +1,30 @@
+import type { ManifestTest } from '@describe-me/core/types'
+import { el } from './el.js'
+import { shownTags } from './shown-tags.js'
+import { filterByTag, state } from './state.js'
+
+/** The test's tags in the inspector. One narrows the sidebar to its tests, and again shows all. */
+export function tagButtons(test: ManifestTest): HTMLElement | null {
+  const tags = shownTags(test)
+
+  if (tags.length === 0) {
+    return null
+  }
+
+  const buttons = tags.map((tag) => {
+    const active = tag === state.tag
+
+    return el(
+      'button',
+      {
+        class: `tag${active ? ' active' : ''}`,
+        'aria-pressed': String(active),
+        title: active ? 'show every test' : `show only the tests tagged ${tag}`,
+        click: () => filterByTag(active ? null : tag),
+      },
+      tag,
+    )
+  })
+
+  return el('div', { class: 'tags' }, ...buttons)
+}

package/src/tag-filter-bar.ts

@@ -0,0 +1,24 @@
+import { el } from './el.js'
+import { filterByTag, state } from './state.js'
+
+/** The line above the tree while a tag narrows it, with the button that clears the filter. */
+export function tagFilterBar(): HTMLElement[] {
+  if (state.tag === null) {
+    return []
+  }
+
+  return [
+    el('span', { class: 'tag-filter-label' }, 'tagged'),
+    el('span', { class: 'tag' }, state.tag),
+    el(
+      'button',
+      {
+        class: 'tag-filter-clear',
+        'aria-label': `Show every test, not only those tagged ${state.tag}`,
+        title: 'show every test',
+        click: () => filterByTag(null),
+      },
+      '×',
+    ),
+  ]
+}

package/src/visible-tests.ts

@@ -1,6 +1,7 @@
 import type { ManifestTest } from '@describe-me/core/types'
 import { CollapsedSuites } from './collapsed-suites.js'
-import { matchesQuery } from './matches-query.js'
+import { filterActive } from './filter-active.js'
+import { matchesFilter } from './matches-filter.js'
 import { soleSuite } from './sole-suite.js'
 import { state } from './state.js'
 import { suiteKey } from './suite-key.js'
@@ -15,7 +16,7 @@ function collect(
 ): void {
   for (const child of node.children) {
     if (!('suites' in child)) {
-      if (matchesQuery(child, moduleId, state.query)) {
+      if (matchesFilter(child, moduleId)) {
         into.push(child)
       }
 
@@ -30,8 +31,8 @@ function collect(
 }
 
 /**
- * The tests the sidebar shows, in its order, after the search and the
- * collapsed suites. It walks the same tree by the same rules as the sidebar.
+ * The tests the sidebar shows, in its order, after the search, the tag filter
+ * and the collapsed suites. It walks the same tree by the same rules as the sidebar.
  */
 export function visibleTests(): ManifestTest[] {
   const manifest = state.manifest
@@ -39,8 +40,8 @@ export function visibleTests(): ManifestTest[] {
     return []
   }
 
-  // A search shows every match, collapsed or not.
-  const collapsed = state.query.trim() ? null : CollapsedSuites.for(manifest.root)
+  // A search or a tag shows every match, collapsed or not.
+  const collapsed = filterActive() ? null : CollapsedSuites.for(manifest.root)
   const tests: ManifestTest[] = []
 
   for (const mod of manifest.modules) {