@poveste/app 0.20.0 → 0.21.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@poveste/app",
   "type": "module",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Pre-bundled UI for Poveste",
   "author": {
     "name": "Sorin Gitlan",
@@ -36,9 +36,9 @@
     "node": ">=22.22.2"
   },
   "dependencies": {
-    "@poveste/controls": "^0.20.0",
-    "@poveste/shared": "^0.20.0",
-    "@poveste/vendors": "^0.20.0",
+    "@poveste/controls": "^0.21.0",
+    "@poveste/shared": "^0.21.0",
+    "@poveste/vendors": "^0.21.0",
     "fuse.js": "^7.0.0",
     "shiki": "^4.5.0"
   },
@@ -61,13 +61,13 @@
     "fs-extra": "^11.4.1",
     "globby": "^16.2.4",
     "pathe": "^2.0.3",
-    "pinia": "^4.0.3",
-    "postcss": "^8.5.23",
+    "pinia": "^4.1.0",
+    "postcss": "^8.5.31",
     "postcss-cli": "^12.0.0",
     "tailwindcss": "^4.3.3",
     "typescript": "6.0.3",
     "vite": "^8.3.4",
-    "vitest": "^5.0.4",
+    "vitest": "^5.0.5",
     "vue": "^3.5.44",
     "vue-router": "^5.4.0",
     "vue-tsc": "^3.3.13"

package/src/app/components/layout/LayoutModal.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { Icon } from '@iconify/vue'
+import { nextTick, ref, watch } from 'vue'
 import { onKeyboardShortcut } from '../../util/keyboard'
 import LayoutPane from './LayoutPane.vue'
 
@@ -23,6 +24,48 @@ onKeyboardShortcut(['escape'], () => {
     close()
   }
 })
+
+// A dialog to the keyboard as well: focus moves in when it opens, Tab stays inside,
+// and closing hands focus back to whatever opened it, the layout chip or the page
+// behind a shortcut. Focus used to stay on the chip, behind the pane (#1372).
+const panel = ref<HTMLElement>()
+let opener: HTMLElement | null = null
+
+const FOCUSABLE = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+
+function focusables() {
+  return [...panel.value?.querySelectorAll<HTMLElement>(FOCUSABLE) ?? []]
+    .filter(element => !element.hasAttribute('disabled') && element.getClientRects().length > 0)
+}
+
+watch(() => props.shown, async (shown) => {
+  if (shown) {
+    opener = document.activeElement instanceof HTMLElement ? document.activeElement : null
+    await nextTick()
+    focusables()[0]?.focus()
+  }
+  else if (opener?.isConnected) {
+    opener.focus()
+    opener = null
+  }
+})
+
+function keepFocusInside(event: KeyboardEvent) {
+  const elements = focusables()
+  const first = elements[0]
+  const last = elements.at(-1)
+  if (!first || !last) {
+    return
+  }
+  if (event.shiftKey && document.activeElement === first) {
+    event.preventDefault()
+    last.focus()
+  }
+  else if (!event.shiftKey && document.activeElement === last) {
+    event.preventDefault()
+    first.focus()
+  }
+}
 </script>
 
 <template>
@@ -35,9 +78,19 @@ onKeyboardShortcut(['escape'], () => {
       class="absolute inset-0"
       @click="close()"
     />
-    <div class="bg-white dark:bg-gray-900 md:mt-16 md:mx-auto w-screen max-w-[512px] shadow-xl border border-gray-200 dark:border-gray-750 rounded-lg relative divide-y divide-gray-200 dark:divide-gray-850">
+    <div
+      ref="panel"
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="poveste-layout-modal-title"
+      class="bg-white dark:bg-gray-900 md:mt-16 md:mx-auto w-screen max-w-[512px] shadow-xl border border-gray-200 dark:border-gray-750 rounded-lg relative divide-y divide-gray-200 dark:divide-gray-850"
+      @keydown.tab="keepFocusInside"
+    >
       <div class="flex items-center px-6 py-3 text-gray-900 dark:text-gray-100">
-        <h2 class="flex-1 text-sm font-medium m-0">
+        <h2
+          id="poveste-layout-modal-title"
+          class="flex-1 text-sm font-medium m-0"
+        >
           Customize Layout
         </h2>
         <button

package/src/app/components/panel/ComponentDocs.vue

@@ -1,12 +1,17 @@
 <script lang="ts" setup>
 import type { DocProp } from '@poveste/shared'
 import type { ComponentDocsEntry } from '../../util/component-docs'
-import { tagHref, tagText } from '../../util/component-docs'
+import { computed } from 'vue'
+import { modelLabel, OPEN_PARTS, rootFirst, tagHref, tagText } from '../../util/component-docs'
 
-defineProps<{
+const props = defineProps<{
   components: ComponentDocsEntry[]
+  /** The story's file, which names the family whose root opens first. */
+  storyFile?: string | undefined
 }>()
 
+const ordered = computed(() => rootFirst(props.components, props.storyFile))
+
 function shownDefault(prop: DocProp) {
   return prop.default ?? prop.defaultTag
 }
@@ -17,15 +22,22 @@ function shownDefault(prop: DocProp) {
     class="poveste-component-docs"
     data-testid="component-docs"
   >
-    <section
-      v-for="component of components"
+    <details
+      v-for="(component, index) of ordered"
       :key="component.file"
+      :open="ordered.length <= OPEN_PARTS || index === 0"
       data-slot="component"
       :data-component="component.name"
     >
-      <h3 data-slot="component-name">
-        {{ component.name }}
-      </h3>
+      <summary>
+        <h3 data-slot="component-name">
+          {{ component.name }}<code
+            v-if="component.doc?.generic"
+            title="The component's type parameters, as its script declares them"
+            data-slot="generic"
+          >&lt;{{ component.doc.generic }}&gt;</code>
+        </h3>
+      </summary>
 
       <p
         v-if="component.error"
@@ -61,6 +73,11 @@ function shownDefault(prop: DocProp) {
                   title="Required"
                   data-slot="required"
                 >*</span>
+                <code
+                  v-if="modelLabel(component.doc, prop.name)"
+                  :title="`Bound two ways with ${modelLabel(component.doc, prop.name)}, through the update:${prop.name} event`"
+                  data-slot="model"
+                >{{ modelLabel(component.doc, prop.name) }}</code>
               </td>
               <td><code>{{ prop.type }}</code></td>
               <td>
@@ -114,15 +131,26 @@ function shownDefault(prop: DocProp) {
             </tr>
           </thead>
           <tbody>
-            <tr
+            <template
               v-for="slot of component.doc.slots"
               :key="slot.name"
-              :data-slot-name="slot.name"
             >
-              <td><code>{{ slot.name }}</code></td>
-              <td><code v-if="slot.type">{{ slot.type }}</code></td>
-              <td>{{ slot.description }}</td>
-            </tr>
+              <tr :data-slot-name="slot.name">
+                <td><code>{{ slot.name }}</code></td>
+                <!-- Its props are listed below, one row each; the type string would only repeat them. -->
+                <td><code v-if="slot.type && !slot.props?.length">{{ slot.type }}</code></td>
+                <td>{{ slot.description }}</td>
+              </tr>
+              <tr
+                v-for="slotProp of slot.props ?? []"
+                :key="`${slot.name}.${slotProp.name}`"
+                :data-slot-prop="slotProp.name"
+              >
+                <td><code>{{ slotProp.name }}</code></td>
+                <td><code>{{ slotProp.type }}</code></td>
+                <td>{{ slotProp.description }}</td>
+              </tr>
+            </template>
           </tbody>
         </table>
 
@@ -143,14 +171,21 @@ function shownDefault(prop: DocProp) {
               :key="event.name"
               :data-event="event.name"
             >
-              <td><code>{{ event.name }}</code></td>
+              <td>
+                <code>{{ event.name }}</code>
+                <code
+                  v-if="modelLabel(component.doc, event.name)"
+                  :title="`Bound two ways with ${modelLabel(component.doc, event.name)}, with the ${event.name.slice('update:'.length)} prop`"
+                  data-slot="model"
+                >{{ modelLabel(component.doc, event.name) }}</code>
+              </td>
               <td><code v-if="event.type">{{ event.type }}</code></td>
               <td>{{ event.description }}</td>
             </tr>
           </tbody>
         </table>
       </template>
-    </section>
+    </details>
   </div>
 </template>
 
@@ -166,14 +201,19 @@ function shownDefault(prop: DocProp) {
   }
 }
 
-section + section {
+details + details {
   margin-top: 1.5rem;
 }
 
+summary {
+  cursor: pointer;
+  margin-bottom: .5rem;
+}
+
 h3 {
+  display: inline;
   font-weight: 600;
   font-size: 1rem;
-  margin-bottom: .5rem;
 }
 
 table {
@@ -221,11 +261,37 @@ pre code {
   text-decoration: line-through;
 }
 
+/* Its own line: a constraint wrapped beside the name broke mid-phrase in the narrow panel. */
+/* A prop a slot passes its content, under the slot it belongs to. */
+[data-slot-prop] td:first-child {
+  padding-inline-start: 1rem;
+}
+
+[data-slot='generic'] {
+  display: block;
+  width: fit-content;
+  margin-top: .25rem;
+  font-size: .75rem;
+  font-weight: 400;
+  cursor: help;
+}
+
 [data-slot='required'] {
   color: var(--color-red-500);
   margin-inline-start: .125rem;
 }
 
+[data-slot='model'] {
+  display: inline-block;
+  margin-inline-start: .375rem;
+  color: var(--color-primary-600);
+  cursor: help;
+
+  &:where(.ptw-dark, .ptw-dark *) {
+    color: var(--color-primary-400);
+  }
+}
+
 [data-slot='deprecated'],
 [data-slot='default-conflict'] {
   color: var(--color-amber-600);

package/src/app/components/panel/StoryDocs.vue

@@ -5,7 +5,7 @@ import { Icon } from '@iconify/vue'
 import { markdownFiles } from 'virtual:$poveste-markdown-files'
 import { computed, nextTick, ref, toRefs, watch, watchEffect } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
-import { useComponentDocs } from '../../util/component-docs.js'
+import { onlySections, useComponentDocs } from '../../util/component-docs.js'
 import { povesteConfig } from '../../util/config.js'
 import BaseEmpty from '../base/BaseEmpty.vue'
 import DevOnlyToolbarOpenInEditor from '../toolbar/DevOnlyToolbarOpenInEditor.vue'
@@ -79,7 +79,8 @@ const { story } = toRefs(props)
 const { renderedDoc } = useStoryDoc(story)
 
 // Opening the docs is what starts auto-docs extraction (#1159).
-const { components } = useComponentDocs(computed(() => story.value?.id))
+const { components: allComponents, pending, off } = useComponentDocs(computed(() => story.value?.id))
+const components = computed(() => allComponents.value && onlySections(allComponents.value, story.value?.autoDocs))
 
 // Markdown links to other stories
 const router = useRouter()
@@ -189,8 +190,33 @@ const filePath = computed(() => story.value.file?.docsFilePath ?? (props.standal
       />
     </div>
 
+    <!--
+      The same empty panel said "still reading" and "off, for a reason" alike (#1400).
+      A built book's data is a chunk away, so it shows nothing until then, not a spinner.
+    -->
     <BaseEmpty
-      v-if="!renderedDoc && !components?.length"
+      v-if="__POVESTE_DEV__ && !renderedDoc && !components?.length && pending"
+      data-testid="docs-pending"
+    >
+      <Icon
+        icon="carbon:circle-dash"
+        class="w-8 h-8 opacity-50 mb-6 animate-spin"
+      />
+      Reading component types…
+      <span class="text-sm opacity-70 mt-2">The first time can take a while.</span>
+    </BaseEmpty>
+    <BaseEmpty
+      v-else-if="!pending && !renderedDoc && !components?.length && off"
+      data-testid="docs-off"
+    >
+      <Icon
+        icon="carbon:document-unknown"
+        class="w-8 h-8 opacity-50 mb-6"
+      />
+      {{ off }}
+    </BaseEmpty>
+    <BaseEmpty
+      v-else-if="!pending && !renderedDoc && !components?.length"
     >
       <Icon
         icon="carbon:document-unknown"
@@ -208,6 +234,7 @@ const filePath = computed(() => story.value.file?.docsFilePath ?? (props.standal
     <ComponentDocs
       v-if="components?.length"
       :components="components"
+      :story-file="story.file?.filePath"
     />
   </div>
 </template>

package/src/app/components/panel/StorySourceCode.vue

@@ -6,7 +6,7 @@ import { Icon } from '@iconify/vue'
 import { HstCopyIcon, HstTooltip } from '@poveste/controls'
 import { computed, markRaw, nextTick, onMounted, ref, shallowRef, watch, watchEffect } from 'vue'
 import { isDark } from '../../util/dark'
-import { getDynamicSourceCode, getStaticSourceCode, loadGenerateSourceCode } from '../../util/docs'
+import { getDynamicSourceCode, getStaticSourceCode, loadGenerateSourceCode, sourceLang } from '../../util/docs'
 import { getHighlighter } from '../../util/highlighter'
 import BaseEmpty from '../base/BaseEmpty.vue'
 
@@ -112,7 +112,7 @@ onMounted(async () => {
 
 const sourceHtml = computed(() => displayedSourceCode.value
   ? highlighter.value?.codeToHtml(displayedSourceCode.value, {
-      lang: 'html',
+      lang: sourceLang(props.story),
       theme: isDark.value ? 'github-dark' : 'github-light-high-contrast',
     })
   : '')

package/src/app/components/story/StoryResponsivePreview.vue

@@ -6,6 +6,7 @@ import { HstTooltip } from '@poveste/controls'
 import { useEventListener } from '@vueuse/core'
 import { computed, onUnmounted, ref } from 'vue'
 import { usePreviewSettingsStore } from '../../stores/preview-settings'
+import { usePreviewDark } from '../../util/color-scheme'
 import CheckerboardPattern from '../misc/CheckerboardPattern.vue'
 import HatchedPattern from '../misc/HatchedPattern.vue'
 
@@ -21,6 +22,7 @@ const props = withDefaults(defineProps<{
 })
 
 const settings = usePreviewSettingsStore().currentSettings
+const previewDark = usePreviewDark(settings)
 
 // Resize
 
@@ -183,7 +185,8 @@ const sizeTooltip = computed(() => `${responsiveWidth.value ?? 'Auto'} × ${resp
           // padding (#264). Gated on `responsive`, not `isResponsiveEnabled`:
           // a single-view story with `responsiveDisabled` still needs its own
           // chrome, it just loses the draggers.
-          responsive ? 'bg-white dark:bg-gray-700' : '',
+          // The preview's scheme, not the chrome's, which `dark:` would follow (#1449).
+          responsive ? (previewDark ? 'bg-gray-700' : 'bg-white') : '',
           isResponsiveEnabled ? {
             'w-fit': !!finalWidth,
             'h-fit': !!finalHeight,

package/src/app/components/story/StoryVariantGridItem.vue

@@ -148,8 +148,11 @@ const useIframe = computed(() => {
 
     <!-- Body -->
     <div
-      class="border bg-white dark:bg-gray-700 rounded flex-1 p-4 relative"
+      class="border rounded flex-1 p-4 relative"
       :class="{
+        // The preview's scheme, not the chrome's, which `dark:` would follow (#1449).
+        'bg-gray-700': previewDark,
+        'bg-white': !previewDark,
         'border-gray-100 dark:border-gray-800': !isActive,
         'border-primary-200 dark:border-primary-900': isActive,
       }"

package/src/app/components/story/StoryVariantSinglePreviewRemote.vue

@@ -50,7 +50,7 @@ function postState(changes: Record<string, any>) {
   iframe.value?.contentWindow?.postMessage({
     type: STATE_SYNC,
     state: changes,
-  })
+  }, window.location.origin)
 }
 
 let bridge = createStateBridge(postState)
@@ -105,9 +105,11 @@ function fromCurrentOccupant(data: { storyId?: string, variantId?: string }) {
 useEventListener(window, 'message', (event) => {
   // With many grid iframes mounted, every sandbox postMessage hits every
   // parent listener. Skip events that didn't originate from this iframe.
-  // Paired with the origin check in `sandbox.ts`, which guards the other
-  // direction (#379).
   if (event.source !== iframe.value?.contentWindow) return
+  // And from the book's own origin: the frame keeps its window when a story
+  // navigates it off-site, and the site it lands on could post here (#1494).
+  // The other direction is `sandbox.ts`'s check (#379).
+  if (event.origin !== window.location.origin) return
   switch (event.data?.type) {
     case STATE_SYNC:
       if (!fromCurrentOccupant(event.data)) break
@@ -279,7 +281,7 @@ function syncSettings() {
     iframe.value.contentWindow.postMessage({
       type: PREVIEW_SETTINGS_SYNC,
       settings: toRaw(settings),
-    })
+    }, window.location.origin)
   }
 }
 

package/src/app/index.ts

@@ -1,6 +1,6 @@
 import { addCollection } from '@iconify/vue'
 import { createPinia } from 'pinia'
-import { generation } from 'virtual:$poveste-stories'
+import { generation, onUpdate, icons as storyIcons } from 'virtual:$poveste-stories'
 import { createApp, watch } from 'vue'
 import App from './App.vue'
 import { setupPluginApi } from './plugin.js'
@@ -13,11 +13,20 @@ import 'virtual:$poveste-theme'
 export async function mountMainApp() {
   // The chrome's icon data ships with the app. Without this every Icon fetched
   // its data from api.iconify.design at runtime — a handful of CDN requests per
-  // boot, and no toolbar offline (#219). Story icons a user sets still resolve
-  // through the runtime lookup.
+  // boot, and no toolbar offline (#219).
   for (const collection of iconCollections) {
     addCollection(collection)
   }
+  // And the icons a book's stories name, where the book has the collection
+  // installed; the rest still resolve through the runtime lookup (#255).
+  for (const collection of storyIcons) {
+    addCollection(collection)
+  }
+  onUpdate((_files: unknown, _tree: unknown, icons: typeof storyIcons = []) => {
+    for (const collection of icons) {
+      addCollection(collection)
+    }
+  })
 
   // The chrome's own scheme, for the browser: it paints the chrome's native
   // controls and scrollbars, and reads no class (#991). Here rather than in the

package/src/app/sandbox.ts

@@ -18,6 +18,8 @@ import { applyPreviewSettings, loadStoredPreviewSettings, receivedSettings } fro
 import { createStateBridge } from './util/state-bridge.js'
 import { toRawDeep } from './util/state.js'
 import { isBenignResizeObserverEvent } from './util/uncaught.js'
+// The book's `theme.colors`, under the private names the controls' tokens read (#1443).
+import 'virtual:$poveste-theme'
 
 const query = parseQuery(window.location.search)
 
@@ -115,6 +117,9 @@ watch(previewDark, (value) => {
       el.classList.toggle(className, value)
     }
   }
+  // A builtin control in the story keys its dark rules on `.ptw-dark`, so it follows
+  // the preview it sits in, not the chrome around it (#1443).
+  document.documentElement.classList.toggle('ptw-dark', value)
 }, {
   immediate: true,
 })

package/src/app/util/component-docs-data.ts

@@ -1,3 +1,6 @@
-// What `poveste build` extracted, in a chunk of its own: loaded when a reader first
-// opens a story's docs, so a book whose docs nobody opens never downloads it.
-export { componentDocs } from 'virtual:$poveste-component-docs'
+import type { ComponentDoc } from '@poveste/shared'
+import { componentDocs as data } from 'virtual:$poveste-component-docs'
+
+// What `poveste build` extracted: a small map from each story to its components, each
+// in a chunk of its own, so a reader downloads only the tables of the stories they open (#1429).
+export const componentDocs: Record<string, Record<string, () => Promise<{ default: { doc: ComponentDoc } }>>> = data

package/src/app/util/component-docs.ts

@@ -1,11 +1,11 @@
-import type { ComponentDoc, DocTag } from '@poveste/shared'
+import type { AutoDocsSection, ComponentDoc, DocTag } from '@poveste/shared'
 import type { Ref } from 'vue'
 import { onBeforeUnmount, ref, watch } from 'vue'
 
 export interface ComponentDocsEntry {
   /** Relative to the book's root. */
   file: string
-  /** The file name without its extension. */
+  /** The component's own name, else the file name without its extension. */
   name: string
   doc?: ComponentDoc
   error?: string
@@ -13,18 +13,78 @@ export interface ComponentDocsEntry {
 
 interface StoryDocsResult {
   storyId: string
-  components: Record<string, { doc?: ComponentDoc, error?: string }>
+  components: Record<string, { doc?: ComponentDoc, error?: string, name?: string }>
+  /** Why auto-docs is off for this story, as the terminal says it. */
+  off?: string
 }
 
 export function toEntries(result: StoryDocsResult): ComponentDocsEntry[] {
-  return Object.entries(result.components).map(([file, { doc, error }]) => ({
+  return Object.entries(result.components).map(([file, { doc, error, name }]) => ({
     file,
-    name: file.split('/').pop()!.replace(/\.[^.]+$/, ''),
+    // A JSX story's result is keyed by the story file, so the extractor names the component,
+    // and an unnamed one, such as an inline function, goes by the story's file name.
+    name: doc?.name ?? name ?? file.split('/').pop()!.replace(/(?:\.story)?\.[^.]+$/, ''),
     ...doc ? { doc } : {},
     ...error ? { error } : {},
   }))
 }
 
+/**
+ * Only the sections a story's `autoDocs` names, in the table's own order. A component
+ * left with nothing to show is dropped; one that failed keeps its error (#1398).
+ */
+export function onlySections(entries: ComponentDocsEntry[], autoDocs: boolean | AutoDocsSection[] | undefined): ComponentDocsEntry[] {
+  if (!Array.isArray(autoDocs)) {
+    return entries
+  }
+  return entries.flatMap((entry) => {
+    if (!entry.doc) {
+      return [entry]
+    }
+    const doc = {
+      ...entry.doc,
+      props: autoDocs.includes('props') ? entry.doc.props : [],
+      slots: autoDocs.includes('slots') ? entry.doc.slots : [],
+      events: autoDocs.includes('events') ? entry.doc.events : [],
+    }
+    return doc.props.length || doc.slots.length || doc.events.length ? [{ ...entry, doc }] : []
+  })
+}
+
+/** Above this many, a story's components after the first start collapsed: a compound story can name 27 parts (#1432). */
+export const OPEN_PARTS = 3
+
+/**
+ * A compound component's root first, `SelectRoot` before `SelectTrigger`, else the order
+ * they came in. A story rendering two families, such as a Select inside a Calendar, opens
+ * the root its own folder or file is named for: `Calendar/story/CalendarSelect.story.vue`
+ * opens `CalendarRoot`, not the `SelectRoot` it imported first.
+ */
+export function rootFirst(entries: ComponentDocsEntry[], storyFile?: string): ComponentDocsEntry[] {
+  const roots = entries.filter(entry => entry.name.endsWith('Root'))
+  const family = (entry: ComponentDocsEntry) => entry.name.slice(0, -'Root'.length)
+  const segments = storyFile?.split(/[\\/]/) ?? []
+  const fileName = segments.at(-1) ?? ''
+  const root = roots.find(entry => segments.slice(0, -1).includes(family(entry)))
+    ?? roots.find(entry => fileName.startsWith(family(entry)))
+    ?? roots[0]
+  return root ? [root, ...entries.filter(entry => entry !== root)] : entries
+}
+
+/**
+ * The `v-model` a prop and its `update:` event make together, as a template writes it:
+ * `v-model` for `modelValue`, `v-model:open` for `open` (#1436). Asked with either name,
+ * so the two rows of a pair, one under Props and one under Events, carry the same mark.
+ */
+export function modelLabel(doc: ComponentDoc, name: string): string | undefined {
+  const prop = name.startsWith('update:') ? name.slice('update:'.length) : name
+  const paired = doc.props.some(candidate => candidate.name === prop) && doc.events.some(event => event.name === `update:${prop}`)
+  if (!paired) {
+    return undefined
+  }
+  return prop === 'modelValue' ? 'v-model' : `v-model:${prop}`
+}
+
 export function tagText(tags: DocTag[], name: string): string | undefined {
   const tag = tags.find(tag => tag.name === name)
   return tag ? (tag.text ?? '') : undefined
@@ -42,24 +102,53 @@ export function tagHref(text: string): string | undefined {
  */
 export function useComponentDocs(storyId: Ref<string | undefined>) {
   const components = ref<ComponentDocsEntry[]>()
+  // Asked and not yet answered: the first answer can take many seconds (#1400).
+  const pending = ref(false)
+  const off = ref<string>()
   const hot = import.meta.hot
   if (!hot) {
-    watch(storyId, async (id) => {
-      const { componentDocs } = await import('./component-docs-data')
-      const docs = id ? componentDocs[id] : undefined
-      components.value = id && docs ? toEntries({ storyId: id, components: docs }) : undefined
+    // The chunk loads on first use, and until then the tab said there were no docs (#1400).
+    watch(storyId, async (id, _, onCleanup) => {
+      // Another story opened while these loaded.
+      let stale = false
+      onCleanup(() => stale = true)
+      pending.value = true
+      try {
+        const { componentDocs } = await import('./component-docs-data')
+        const loaders = id ? componentDocs[id] : undefined
+        const docs = loaders && Object.fromEntries(await Promise.all(Object.entries(loaders).map(async ([file, load]) => [file, (await load()).default])))
+        if (!stale) {
+          components.value = id && docs ? toEntries({ storyId: id, components: docs }) : undefined
+        }
+      }
+      catch (error) {
+        // A chunk the server no longer has, as in a tab left open across a deploy:
+        // no table, rather than a tab that waits forever.
+        if (!stale) {
+          components.value = undefined
+          console.error('[poveste] could not load this story\'s component docs:', error)
+        }
+      }
+      finally {
+        if (!stale) {
+          pending.value = false
+        }
+      }
     }, { immediate: true })
-    return { components }
+    return { components, pending, off }
   }
 
   function ask() {
     if (storyId.value) {
+      pending.value = true
       hot!.send('poveste:docgen-request', { storyId: storyId.value })
     }
   }
   function onResult(result: StoryDocsResult) {
     if (result.storyId === storyId.value) {
       components.value = toEntries(result)
+      off.value = result.off
+      pending.value = false
     }
   }
 
@@ -71,8 +160,10 @@ export function useComponentDocs(storyId: Ref<string | undefined>) {
   })
   watch(storyId, () => {
     components.value = undefined
+    off.value = undefined
+    pending.value = false
     ask()
   }, { immediate: true })
 
-  return { components }
+  return { components, pending, off }
 }