@poveste/app 0.19.0 → 0.20.0

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

@@ -0,0 +1,257 @@
+<script lang="ts" setup>
+import type { DocProp } from '@poveste/shared'
+import type { ComponentDocsEntry } from '../../util/component-docs'
+import { tagHref, tagText } from '../../util/component-docs'
+
+defineProps<{
+  components: ComponentDocsEntry[]
+}>()
+
+function shownDefault(prop: DocProp) {
+  return prop.default ?? prop.defaultTag
+}
+</script>
+
+<template>
+  <div
+    class="poveste-component-docs"
+    data-testid="component-docs"
+  >
+    <section
+      v-for="component of components"
+      :key="component.file"
+      data-slot="component"
+      :data-component="component.name"
+    >
+      <h3 data-slot="component-name">
+        {{ component.name }}
+      </h3>
+
+      <p
+        v-if="component.error"
+        data-slot="error"
+      >
+        Could not read this component's types: {{ component.error }}
+      </p>
+
+      <template v-else-if="component.doc">
+        <table
+          v-if="component.doc.props.length"
+          data-slot="props"
+        >
+          <thead>
+            <tr>
+              <th>Prop</th>
+              <th>Type</th>
+              <th>Default</th>
+              <th>Description</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr
+              v-for="prop of component.doc.props"
+              :key="prop.name"
+              :data-prop="prop.name"
+            >
+              <td>
+                <code
+                  :class="{ deprecated: tagText(prop.tags, 'deprecated') !== undefined }"
+                >{{ prop.name }}</code><span
+                  v-if="prop.required"
+                  title="Required"
+                  data-slot="required"
+                >*</span>
+              </td>
+              <td><code>{{ prop.type }}</code></td>
+              <td>
+                <code v-if="shownDefault(prop) !== undefined">{{ shownDefault(prop) }}</code>
+                <span
+                  v-if="__POVESTE_DEV__ && prop.defaultConflict"
+                  :title="`The code's default is shown; the @default tag says ${prop.defaultTag}`"
+                  data-slot="default-conflict"
+                >≠</span>
+              </td>
+              <td>
+                <span
+                  v-if="tagText(prop.tags, 'deprecated') !== undefined"
+                  data-slot="deprecated"
+                >Deprecated<template v-if="tagText(prop.tags, 'deprecated')">: {{ tagText(prop.tags, 'deprecated') }}</template></span>
+                {{ prop.description }}
+                <template
+                  v-for="tag of prop.tags.filter(tag => tag.name === 'see' || tag.name === 'link')"
+                  :key="tag.text"
+                >
+                  <a
+                    v-if="tagHref(tag.text ?? '')"
+                    :href="tagHref(tag.text ?? '')"
+                    target="_blank"
+                    rel="noopener"
+                    data-slot="see"
+                  >{{ tag.text }}</a>
+                  <span
+                    v-else
+                    data-slot="see"
+                  >{{ tag.text }}</span>
+                </template>
+                <pre
+                  v-if="tagText(prop.tags, 'example')"
+                  data-slot="example"
+                ><code>{{ tagText(prop.tags, 'example') }}</code></pre>
+              </td>
+            </tr>
+          </tbody>
+        </table>
+
+        <table
+          v-if="component.doc.slots.length"
+          data-slot="slots"
+        >
+          <thead>
+            <tr>
+              <th>Slot</th>
+              <th>Type</th>
+              <th>Description</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr
+              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>
+          </tbody>
+        </table>
+
+        <table
+          v-if="component.doc.events.length"
+          data-slot="events"
+        >
+          <thead>
+            <tr>
+              <th>Event</th>
+              <th>Payload</th>
+              <th>Description</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr
+              v-for="event of component.doc.events"
+              :key="event.name"
+              :data-event="event.name"
+            >
+              <td><code>{{ event.name }}</code></td>
+              <td><code v-if="event.type">{{ event.type }}</code></td>
+              <td>{{ event.description }}</td>
+            </tr>
+          </tbody>
+        </table>
+      </template>
+    </section>
+  </div>
+</template>
+
+<style scoped>
+.poveste-component-docs {
+  padding: 1rem;
+  font-size: .875rem;
+  color: var(--color-gray-800);
+
+  /* On the subject, not `.ptw-dark &`: `.ptw-dark` sits above the `@scope` root (#101). */
+  &:where(.ptw-dark, .ptw-dark *) {
+    color: var(--color-gray-200);
+  }
+}
+
+section + section {
+  margin-top: 1.5rem;
+}
+
+h3 {
+  font-weight: 600;
+  font-size: 1rem;
+  margin-bottom: .5rem;
+}
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+  margin-bottom: 1rem;
+}
+
+th {
+  text-align: start;
+  font-weight: 500;
+  color: var(--color-gray-500);
+}
+
+th,
+td {
+  padding: .375rem .5rem;
+  border-bottom: 1px solid var(--color-gray-200);
+  vertical-align: top;
+
+  &:where(.ptw-dark, .ptw-dark *) {
+    border-color: var(--color-gray-750);
+  }
+}
+
+code {
+  font-size: .8125rem;
+  background-color: var(--color-gray-100);
+  border-radius: .25rem;
+  padding: 0 .25rem;
+
+  &:where(.ptw-dark, .ptw-dark *) {
+    background-color: var(--color-gray-750);
+  }
+}
+
+pre code {
+  display: block;
+  padding: .5rem;
+  margin-top: .25rem;
+  white-space: pre-wrap;
+}
+
+.deprecated {
+  text-decoration: line-through;
+}
+
+[data-slot='required'] {
+  color: var(--color-red-500);
+  margin-inline-start: .125rem;
+}
+
+[data-slot='deprecated'],
+[data-slot='default-conflict'] {
+  color: var(--color-amber-600);
+  font-weight: 500;
+
+  &:where(.ptw-dark, .ptw-dark *) {
+    color: var(--color-amber-400);
+  }
+}
+
+[data-slot='default-conflict'] {
+  margin-inline-start: .25rem;
+  cursor: help;
+}
+
+[data-slot='see'] {
+  display: block;
+  margin-top: .25rem;
+}
+
+a[data-slot='see'] {
+  color: var(--color-primary-500);
+  text-decoration: underline;
+}
+
+[data-slot='error'] {
+  color: var(--color-gray-500);
+}
+</style>

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

@@ -5,9 +5,11 @@ 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 { povesteConfig } from '../../util/config.js'
 import BaseEmpty from '../base/BaseEmpty.vue'
 import DevOnlyToolbarOpenInEditor from '../toolbar/DevOnlyToolbarOpenInEditor.vue'
+import ComponentDocs from './ComponentDocs.vue'
 
 export function useStoryDoc(story: Ref<Story>) {
   const renderedDoc = ref('')
@@ -76,6 +78,9 @@ 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))
+
 // Markdown links to other stories
 const router = useRouter()
 
@@ -185,7 +190,7 @@ const filePath = computed(() => story.value.file?.docsFilePath ?? (props.standal
     </div>
 
     <BaseEmpty
-      v-if="!renderedDoc"
+      v-if="!renderedDoc && !components?.length"
     >
       <Icon
         icon="carbon:document-unknown"
@@ -194,11 +199,15 @@ const filePath = computed(() => story.value.file?.docsFilePath ?? (props.standal
       No documentation available
     </BaseEmpty>
     <div
-      v-else
+      v-if="renderedDoc"
       ref="renderedEl"
       class="prose dark:prose-invert p-4 max-w-none"
       data-testid="story-docs"
       v-html="renderedDoc"
     />
+    <ComponentDocs
+      v-if="components?.length"
+      :components="components"
+    />
   </div>
 </template>

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

@@ -19,8 +19,21 @@ const props = defineProps<{
 // down were both errors about a type nobody meant to declare.
 const generateSourceCodeFn = shallowRef<GenerateSourceCode | null>(null)
 
+// Until a source has settled, an empty one means "not yet", not "none": a copy in
+// that window said "Nothing to copy" with the source a moment away (#1314).
+const dynamicSettled = ref(false)
+const staticSettled = ref(false)
+
 watchEffect(async () => {
-  const generate = await loadGenerateSourceCode(props.story)
+  let generate: GenerateSourceCode | undefined
+  try {
+    generate = await loadGenerateSourceCode(props.story)
+  }
+  finally {
+    if (!generate) {
+      dynamicSettled.value = true
+    }
+  }
   if (generate) {
     generateSourceCodeFn.value = markRaw(generate)
   }
@@ -40,6 +53,7 @@ watch(() => [props.variant, generateSourceCodeFn.value], async () => {
   if (!generateSourceCodeFn.value) return
   error.value = null
   dynamicSourceCode.value = ''
+  dynamicSettled.value = false
   try {
     dynamicSourceCode.value = (await getDynamicSourceCode(props.variant, generateSourceCodeFn.value)) ?? ''
   }
@@ -47,6 +61,7 @@ watch(() => [props.variant, generateSourceCodeFn.value], async () => {
     console.error(e)
     error.value = e instanceof Error ? e.message : String(e)
   }
+  dynamicSettled.value = true
 
   // Auto-switch
   if (!dynamicSourceCode.value) {
@@ -62,11 +77,19 @@ watch(() => [props.variant, generateSourceCodeFn.value], async () => {
 const staticSourceCode = ref('')
 watch(() => [props.story, props.story?.file?.source], async () => {
   staticSourceCode.value = ''
-  staticSourceCode.value = (await getStaticSourceCode(props.story)) ?? ''
+  staticSettled.value = false
+  try {
+    staticSourceCode.value = (await getStaticSourceCode(props.story)) ?? ''
+  }
+  finally {
+    staticSettled.value = true
+  }
 }, {
   immediate: true,
 })
 
+const loading = computed(() => displayedSource.value === 'dynamic' ? !dynamicSettled.value : !staticSettled.value)
+
 const displayedSourceCode = computed(() => {
   if (displayedSource.value === 'dynamic') {
     return dynamicSourceCode.value
@@ -189,6 +212,7 @@ watch(sourceHtml, async () => {
 
       <HstCopyIcon
         :content="displayedSourceCode"
+        :loading="loading"
         class="flex-none"
       />
     </div>
@@ -205,7 +229,7 @@ watch(sourceHtml, async () => {
         icon="carbon:code-hide"
         class="w-8 h-8 opacity-50 mb-6"
       />
-      <span>Not available</span>
+      <span>{{ loading ? 'Loading' : 'Not available' }}</span>
     </BaseEmpty>
 
     <textarea

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

@@ -7,8 +7,8 @@ export default {
 <script lang="ts" setup>
 import type { Component } from 'vue'
 import type { Story } from '../../types'
-import { clientSupportPlugins } from 'virtual:$poveste-support-plugins-client'
 import { markRaw, ref, watchEffect } from 'vue'
+import { loadClientPlugin } from '../../util/client-plugin.js'
 
 const props = defineProps<{
   story: Story
@@ -17,10 +17,8 @@ const props = defineProps<{
 const mountComponent = ref<Component | null>(null)
 
 watchEffect(async () => {
-  const supportPluginId = props.story.file?.supportPluginId
-  const clientPlugin = supportPluginId ? clientSupportPlugins[supportPluginId] : undefined
-  if (clientPlugin) {
-    const pluginModule = await clientPlugin()
+  const pluginModule = await loadClientPlugin(props.story.file?.supportPluginId)
+  if (pluginModule) {
     mountComponent.value = markRaw(pluginModule.MountStory)
   }
 })

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

@@ -7,8 +7,8 @@ export default {
 <script lang="ts" setup>
 import type { Component } from 'vue'
 import type { Story } from '../../types'
-import { clientSupportPlugins } from 'virtual:$poveste-support-plugins-client'
 import { markRaw, ref, watchEffect } from 'vue'
+import { loadClientPlugin } from '../../util/client-plugin.js'
 
 const props = defineProps<{
   story: Story
@@ -17,17 +17,9 @@ const props = defineProps<{
 const mountComponent = ref<Component | null>(null)
 
 watchEffect(async () => {
-  const supportPluginId = props.story.file?.supportPluginId
-  const clientPlugin = supportPluginId ? clientSupportPlugins[supportPluginId] : undefined
-  if (clientPlugin) {
-    try {
-      const pluginModule = await clientPlugin()
-      mountComponent.value = markRaw(pluginModule.RenderStory)
-    }
-    catch (e) {
-      console.error(e)
-      throw e
-    }
+  const pluginModule = await loadClientPlugin(props.story.file?.supportPluginId)
+  if (pluginModule) {
+    mountComponent.value = markRaw(pluginModule.RenderStory)
   }
 })
 </script>

package/src/app/components/toolbar/DevOnlyToolbarOpenInEditor.vue

@@ -14,7 +14,6 @@ defineProps<{
   <HstTooltip :content="tooltip">
     <TopBarChipItem
       aria-label="Open story in editor"
-      target="_blank"
       class="poveste-toolbar-open-in-editor"
       @click="openInEditor(file)"
     >

package/src/app/router.ts

@@ -1,3 +1,4 @@
+import type { Router } from 'vue-router'
 import { createRouter, createWebHashHistory, createWebHistory } from 'vue-router'
 import { povesteConfig } from './util/config'
 
@@ -12,18 +13,28 @@ function createRouterHistory() {
   }
 }
 
-export const router = createRouter({
-  history: createRouterHistory(),
-  routes: [
-    {
-      path: '/',
-      name: 'home',
-      component: () => import('./components/HomeView.vue'),
-    },
-    {
-      path: '/story/:storyId',
-      name: 'story',
-      component: () => import('./components/story/StoryView.vue'),
-    },
-  ],
-})
+function newRouter(): Router {
+  return createRouter({
+    history: createRouterHistory(),
+    routes: [
+      {
+        path: '/',
+        name: 'home',
+        component: () => import('./components/HomeView.vue'),
+      },
+      {
+        path: '/story/:storyId',
+        name: 'story',
+        component: () => import('./components/story/StoryView.vue'),
+      },
+    ],
+  })
+}
+
+// A page in `poveste dev` can hold two copies of this module: each importer's
+// URL is stamped when the server serves it, and a story edit stamps most of the
+// chrome. Every copy hands out the router the app installed, or the story store
+// read one still at `/` and the page showed no story until reloaded (#1320).
+export const router: Router = import.meta.hot
+  ? (import.meta.hot.data.router ??= newRouter())
+  : newRouter()

package/src/app/util/client-plugin.ts

@@ -0,0 +1,33 @@
+import type { ClientSupportPlugin } from '@poveste/shared'
+import type { Component } from 'vue'
+import { reportStoryError, toStoryError } from '@poveste/shared'
+import { clientSupportPlugins } from 'virtual:$poveste-support-plugins-client'
+import { occupant } from './occupant.js'
+
+/*
+ * A framework's client imports the book's setup file, so a setup file that throws
+ * when it loads fails here, for every story, before any story code runs. In a
+ * built book nothing else reported it: Vue's production build only logs an async
+ * effect's rejection, and every preview stayed blank with the error in the console
+ * alone (#1323). Not rethrown, because Vue's development build would rethrow it as
+ * an unhandled rejection, whose report would replace this one.
+ */
+export async function loadClientPlugin(supportPluginId: string | undefined): Promise<ClientSupportPlugin<Component> | undefined> {
+  const load = supportPluginId ? clientSupportPlugins[supportPluginId] : undefined
+  if (!load) {
+    return undefined
+  }
+  try {
+    return await load()
+  }
+  catch (error) {
+    const { message, stack } = toStoryError(error)
+    const reported = Object.assign(new Error(`The story renderer failed to load, and it imports the setup file: ${message}`), { stack })
+    reportStoryError(reported, {
+      storyId: occupant.storyId ?? undefined,
+      variantId: occupant.variantId ?? undefined,
+    })
+    console.error(error)
+    return undefined
+  }
+}

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

@@ -0,0 +1,3 @@
+// 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'

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

@@ -0,0 +1,78 @@
+import type { 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. */
+  name: string
+  doc?: ComponentDoc
+  error?: string
+}
+
+interface StoryDocsResult {
+  storyId: string
+  components: Record<string, { doc?: ComponentDoc, error?: string }>
+}
+
+export function toEntries(result: StoryDocsResult): ComponentDocsEntry[] {
+  return Object.entries(result.components).map(([file, { doc, error }]) => ({
+    file,
+    name: file.split('/').pop()!.replace(/\.[^.]+$/, ''),
+    ...doc ? { doc } : {},
+    ...error ? { error } : {},
+  }))
+}
+
+export function tagText(tags: DocTag[], name: string): string | undefined {
+  const tag = tags.find(tag => tag.name === name)
+  return tag ? (tag.text ?? '') : undefined
+}
+
+/** A `@see` or `@link` points somewhere only when it carries a URL. */
+export function tagHref(text: string): string | undefined {
+  return /https?:\/\/\S+/.exec(text)?.[0]
+}
+
+/**
+ * The components a story imports, documented. In dev they are asked of the server
+ * when this is first used, which is what starts extraction at all (#1159); in a
+ * built book they come from what `poveste build` extracted.
+ */
+export function useComponentDocs(storyId: Ref<string | undefined>) {
+  const components = ref<ComponentDocsEntry[]>()
+  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
+    }, { immediate: true })
+    return { components }
+  }
+
+  function ask() {
+    if (storyId.value) {
+      hot!.send('poveste:docgen-request', { storyId: storyId.value })
+    }
+  }
+  function onResult(result: StoryDocsResult) {
+    if (result.storyId === storyId.value) {
+      components.value = toEntries(result)
+    }
+  }
+
+  hot.on('poveste:docgen-result', onResult)
+  hot.on('poveste:docgen-stale', ask)
+  onBeforeUnmount(() => {
+    hot.off('poveste:docgen-result', onResult)
+    hot.off('poveste:docgen-stale', ask)
+  })
+  watch(storyId, () => {
+    components.value = undefined
+    ask()
+  }, { immediate: true })
+
+  return { components }
+}