@poveste/app 0.12.3 → 0.13.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@poveste/app",
   "type": "module",
-  "version": "0.12.3",
+  "version": "0.13.1",
   "description": "Pre-bundled UI for Poveste",
   "author": {
     "name": "Sorin Gitlan",
@@ -38,14 +38,14 @@
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "dependencies": {
-    "@fontsource/noto-sans-display": "^5.3.0",
-    "@poveste/controls": "^0.12.3",
-    "@poveste/shared": "^0.12.3",
-    "@poveste/vendors": "^0.12.3",
+    "@poveste/controls": "^0.13.1",
+    "@poveste/shared": "^0.13.1",
+    "@poveste/vendors": "^0.13.1",
     "fuse.js": "^7.0.0",
     "shiki": "^3.0.0"
   },
   "devDependencies": {
+    "@fontsource/noto-sans-display": "^5.3.0",
     "@iconify-json/carbon": "^1.2.25",
     "@iconify-json/fluent": "1.2.56",
     "@iconify-json/mdi": "^1.2.3",
@@ -67,10 +67,12 @@
     "typescript": "5.6.3",
     "vite": "^8.2.0",
     "vitest": "^4.1.10",
-    "vue": "^3.5.26"
+    "vue": "^3.5.26",
+    "vue-tsc": "^2.1.10"
   },
   "scripts": {
     "build": "pnpm run icons && rimraf dist && vite build && pnpm run build:css && node ./scripts/copy.mjs",
+    "typecheck": "vue-tsc --noEmit",
     "build:css": "postcss src/app/style/main.pcss -o ./dist/style.css",
     "icons": "node ./scripts/icons.mjs",
     "test": "vitest run",

package/src/__tests__/font.spec.ts

@@ -1,8 +1,8 @@
-import { readFileSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
 // @ts-expect-error plain script, no types
-import { FONT_PACKAGE, generateFontCss } from '../../scripts/font.mjs'
+import { FONT_PACKAGE, generateFontCss, referencedFiles } from '../../scripts/font.mjs'
 
 // Vitest runs from the package root, and stubs `?raw` CSS imports to empty.
 // Newlines are normalised: the shipped sheet is checked in, so a Windows
@@ -13,6 +13,52 @@ const read = (path: string) => readFileSync(join(process.cwd(), path), 'utf8').r
 const shipped = read('src/app/style/font.css')
 const upstream = read(join('node_modules', FONT_PACKAGE, 'index.css'))
 
+describe('the vendored files', () => {
+  // The sheet and the files are one artifact now that the package is a
+  // devDependency: a book asking for a face that is not on disk renders the
+  // fallback, and nothing else would say so (#306).
+  it('ships every file the sheet asks for', () => {
+    const missing = referencedFiles(shipped).filter(file => !existsSync(join(process.cwd(), 'src/app/style/fonts', file)))
+
+    expect(missing).toEqual([])
+  })
+
+  // The other direction: a subset upstream drops or renames leaves a file the
+  // sheet no longer names, and `files: ['dist', 'src']` would publish it.
+  it('ships nothing the sheet does not ask for', () => {
+    const named = new Set([...referencedFiles(shipped), 'LICENSE'])
+    const orphans = readdirSync(join(process.cwd(), 'src/app/style/fonts')).filter(file => !named.has(file))
+
+    expect(orphans).toEqual([])
+  })
+
+  it('asks for at least one, so a sheet that references nothing is not a pass', () => {
+    expect(referencedFiles(shipped).length).toBeGreaterThan(0)
+  })
+
+  // SIL OFL requires the notice to travel with the font.
+  it('carries the licence the font is under', () => {
+    expect(read('src/app/style/fonts/LICENSE')).toContain('SIL Open Font License')
+  })
+
+  // Vendoring froze these bytes. A Fontsource patch that fixes hinting or adds
+  // a glyph keeps the filenames and unicode-ranges, so the sheet comparison
+  // below stays green while the files it names are stale — the property that
+  // installing the package used to provide for free.
+  it('matches upstream byte for byte, since a bump no longer ships itself', () => {
+    const stale = referencedFiles(shipped).filter(file => !readFileSync(join(process.cwd(), 'src/app/style/fonts', file))
+      .equals(readFileSync(join(process.cwd(), 'node_modules', FONT_PACKAGE, 'files', file))))
+
+    expect(stale).toEqual([])
+  })
+
+  // `read`, not `readFileSync`: the licence is checked in, so a Windows
+  // checkout hands it back with CRLF against the LF of the installed copy.
+  it('carries upstream\'s own licence text, not a copy that has drifted', () => {
+    expect(read('src/app/style/fonts/LICENSE')).toBe(read(join('node_modules', FONT_PACKAGE, 'LICENSE')))
+  })
+})
+
 describe('the bundled app face', () => {
   it('matches the installed package, so a bump cannot go unnoticed', () => {
     expect(shipped).toBe(generateFontCss(upstream))

package/src/app/App.vue

@@ -107,6 +107,15 @@ onMounted(() => {
 
 const commandStore = useCommandStore()
 const layoutStore = useLayoutStore()
+
+/*
+ * Coerced once, because the pane prop and the heading below have to be exact
+ * complements. A stored settings object written before a key existed leaves it
+ * `undefined`, which a Boolean prop reads as its `true` default while `!` reads
+ * as `false` — so both the real header and its stand-in rendered, giving the
+ * page two `h1`s and two banners (#596).
+ */
+const storyListVisible = computed(() => !!layoutStore.settings.storyListVisible)
 </script>
 
 <template>
@@ -132,79 +141,84 @@ const layoutStore = useLayoutStore()
       }"
     >
       <div
-        v-if="isMobile"
-        class="h-full flex flex-col divide-y divide-gray-100 dark:divide-gray-800"
-      >
-        <div class="flex items-center gap-2 pr-4">
-          <AppHeader class="flex-1" />
-          <AppActions
-            class="flex-none"
-            @layout="isLayoutOpen = true"
-            @search="isSearchOpen = true"
-          />
-        </div>
-        <Breadcrumb
-          :tree="tree"
-          :stories="stories"
-        />
-        <main class="grow flex flex-col min-h-0">
-          <RouterView class="grow" />
-        </main>
-      </div>
-
-      <BaseSplitPane
-        v-else-if="layoutStore.settings.storyListVisible"
-        save-id="main-horiz"
-        :min="5"
-        :max="50"
-        :default-split="15"
-        class="h-full"
+        class="h-full flex flex-col"
+        :class="{ 'divide-y divide-gray-100 dark:divide-gray-800': isMobile }"
       >
-        <template #first>
-          <div class="flex flex-col h-full bg-gray-100 dark:bg-gray-750 __poveste-pane-shadow-from-right">
-            <AppHeader class="flex-none" />
-            <nav
-              aria-label="Stories"
-              class="flex-1 flex flex-col min-h-0"
-            >
-              <StoryList
-                :tree="tree"
-                :stories="stories"
-                class="flex-1"
-              />
-            </nav>
-          </div>
-        </template>
-
-        <template #last>
-          <main class="flex flex-col h-full">
-            <TopBar
+        <!--
+          The mobile chrome is a sibling of `main`, not a child: `AppHeader`
+          carries the page's banner and its only `h1`, and a `header` inside
+          `main` is neither (#310).
+        -->
+        <template v-if="isMobile">
+          <div class="flex items-center gap-2 pr-4">
+            <AppHeader class="flex-1" />
+            <AppActions
+              class="flex-none"
               @layout="isLayoutOpen = true"
               @search="isSearchOpen = true"
             />
-            <RouterView class="flex-1 min-h-0" />
-          </main>
+          </div>
+          <Breadcrumb
+            :tree="tree"
+            :stories="stories"
+          />
         </template>
-      </BaseSplitPane>
-      <template v-else>
+
         <!--
-          The story list is hidden in this layout, and `AppHeader` went with it —
-          taking the page's only `h1` and its banner. A heading has to exist in
-          every layout, and it has to sit inside a landmark, so this branch
-          carries its own (#310).
+          With the story list hidden `AppHeader` goes with it, taking the page's
+          only `h1` and its banner. A heading has to exist in every layout, and
+          it has to sit inside a landmark, so this stands in for it (#310).
         -->
-        <header class="sr-only">
+        <header
+          v-else-if="!storyListVisible"
+          class="sr-only"
+        >
           <h1>{{ povesteConfig.theme?.title ?? 'Poveste' }}</h1>
         </header>
 
-        <main class="h-full flex flex-col">
-          <TopBar
-            @layout="isLayoutOpen = true"
-            @search="isSearchOpen = true"
-          />
-          <RouterView class="flex-1 min-h-0" />
-        </main>
-      </template>
+        <!--
+          One split pane for every layout, mobile included. Each chrome used to
+          be a branch carrying its own `RouterView`, so switching between them
+          moved the routed view in the tree and cold-booted the sandbox under
+          it. The settings toggles were #596; `isMobile` is a live media query,
+          so this one fired on a window resize (#600).
+        -->
+        <BaseSplitPane
+          save-id="main-horiz"
+          :min="5"
+          :max="50"
+          :default-split="15"
+          :show-first="!isMobile && storyListVisible"
+          class="flex-1 min-h-0"
+        >
+          <template #first>
+            <div class="flex flex-col h-full bg-gray-100 dark:bg-gray-750 __poveste-pane-shadow-from-right">
+              <AppHeader class="flex-none" />
+              <nav
+                aria-label="Stories"
+                class="flex-1 flex flex-col min-h-0"
+              >
+                <StoryList
+                  :tree="tree"
+                  :stories="stories"
+                  class="flex-1"
+                />
+              </nav>
+            </div>
+          </template>
+
+          <template #last>
+            <main class="flex flex-col h-full">
+              <TopBar
+                v-if="!isMobile"
+                @layout="isLayoutOpen = true"
+                @search="isSearchOpen = true"
+              />
+              <RouterView class="flex-1 min-h-0" />
+            </main>
+          </template>
+        </BaseSplitPane>
+      </div>
 
       <LayoutModal
         v-if="!isMobile"

package/src/app/components/base/BaseListItemLink.vue

@@ -1,10 +1,20 @@
 <script lang="ts">
+import type { PropType } from 'vue'
+import type { RouteLocationRaw } from 'vue-router'
 import { defineComponent } from 'vue'
 
 export default defineComponent({
   inheritAttrs: false,
 
   props: {
+    // Declared rather than passed through `$attrs`: with
+    // `inheritAttrs: false` the checker cannot see it there, and
+    // router-link requires it.
+    to: {
+      type: [String, Object] as PropType<RouteLocationRaw>,
+      required: true,
+    },
+
     isActive: {
       type: Boolean,
       default: undefined,
@@ -31,6 +41,7 @@ export default defineComponent({
 <template>
   <RouterLink
     v-slot="{ isActive: linkIsActive, href, navigate }"
+    :to="to"
     class="poveste-base-list-item-link"
     v-bind="$attrs"
     custom
@@ -42,7 +53,7 @@ export default defineComponent({
       :class="[
         $attrs.class,
         (isActive != null ? isActive : linkIsActive)
-          ? 'active bg-primary-500 hover:bg-primary-600 text-white dark:text-black'
+          ? 'active bg-primary-700 hover:bg-primary-800 dark:bg-primary-500 dark:hover:bg-primary-600 text-white dark:text-black'
           : 'hover:bg-primary-100 dark:hover:bg-primary-900',
       ]"
       @click="handleNavigate($event, navigate)"

package/src/app/components/base/BaseOverflowTab.vue

@@ -1,10 +1,20 @@
 <script lang="ts">
+import type { PropType } from 'vue'
+import type { RouteLocationRaw } from 'vue-router'
 import { defineComponent } from 'vue'
 
 export default defineComponent({
   inheritAttrs: false,
 
   props: {
+    // Declared rather than passed through `$attrs`: with
+    // `inheritAttrs: false` the checker cannot see it there, and
+    // router-link requires it.
+    to: {
+      type: [String, Object] as PropType<RouteLocationRaw>,
+      required: true,
+    },
+
     exact: {
       type: Boolean,
       default: false,
@@ -21,6 +31,7 @@ export default defineComponent({
 <template>
   <router-link
     v-slot="{ isActive, isExactActive, href, navigate }"
+    :to="to"
     class="poveste-base-overflow-tab"
     v-bind="$attrs"
     custom
@@ -30,7 +41,7 @@ export default defineComponent({
       :href="href"
       class="px-4 h-10 min-w-[150px] inline-flex items-center hover:bg-primary-50 dark:hover:bg-primary-900 relative text-gray-900 dark:text-gray-100"
       :class="{
-        'text-primary-500 dark:text-primary-400': matched != null ? matched : (exact && isExactActive) || (!exact && isActive),
+        'text-primary-700 dark:text-primary-400': matched != null ? matched : (exact && isExactActive) || (!exact && isActive),
       }"
       @click="navigate"
     >

package/src/app/components/base/BaseSplitPane.vue

@@ -48,6 +48,34 @@ const props = defineProps({
     type: Boolean,
     default: true,
   },
+
+  /**
+   * Whether the first pane exists at all.
+   *
+   * Dropping it here rather than at the call site keeps the other slot at one
+   * position in the tree, so a layout that sometimes has nothing to put beside
+   * its content does not remount that content when it gains or loses the pane
+   * (#328). A `v-if` inside this component leaves a comment placeholder, so the
+   * surviving pane keeps its index and Vue patches it rather than rebuilding it;
+   * a `v-if` at the call site, choosing between a pane and a bare element, is
+   * what does not.
+   */
+  showFirst: {
+    type: Boolean,
+    default: true,
+  },
+
+  /**
+   * The same for the last pane — see `showFirst` (#596).
+   *
+   * At most one of the two is meant to be false. Both false renders an empty
+   * box that still persists a split, which is a caller mistake rather than a
+   * mode this component supports.
+   */
+  showLast: {
+    type: Boolean,
+    default: true,
+  },
 })
 
 const emit = defineEmits({
@@ -66,36 +94,48 @@ watch(() => props.split, (value) => {
   immediate: true,
 })
 
-if (props.saveId) {
-  const storageKey = `${SAVE_PREFIX}-split-pane-${props.saveId}`
+/*
+ * The key follows `saveId`, which callers build from reactive state —
+ * `story-main-${placement}` changes when the reader moves the options pane.
+ * Reading it once at setup only looked right while a layout change happened to
+ * remount this component; hiding a pane instead of replacing it removed that,
+ * and a stale key writes one placement's split over the other's (#596).
+ */
+const storageKey = computed(() => props.saveId ? `${SAVE_PREFIX}-split-pane-${props.saveId}` : null)
+
+watch(storageKey, (key) => {
+  if (!key) {
+    return
+  }
 
-  const savedValue = localStorage.getItem(storageKey)
+  const savedValue = localStorage.getItem(key)
+  let parsedValue
   if (savedValue != null) {
-    let parsedValue
     try {
       parsedValue = JSON.parse(savedValue)
     }
     catch (e) {
       console.error(e)
     }
-
-    if (typeof parsedValue === 'number') {
-      currentSplit.value = parsedValue
-    }
   }
 
-  watch(currentSplit, (value) => {
-    localStorage.setItem(storageKey, JSON.stringify(value))
-  })
+  // A key with nothing behind it means this layout has never been sized, so it
+  // starts from its own default rather than keeping the previous layout's.
+  currentSplit.value = typeof parsedValue === 'number' ? parsedValue : props.defaultSplit
+}, {
+  immediate: true,
+})
 
-  watch(currentSplit, (value) => {
-    if (value !== props.split) {
-      emit('update:split', value)
-    }
-  }, {
-    immediate: true,
-  })
-}
+watch(currentSplit, (value) => {
+  if (storageKey.value) {
+    localStorage.setItem(storageKey.value, JSON.stringify(value))
+  }
+  if (value !== props.split) {
+    emit('update:split', value)
+  }
+}, {
+  immediate: true,
+})
 
 const boundSplit = computed(() => {
   if (currentSplit.value < props.min) {
@@ -109,13 +149,27 @@ const boundSplit = computed(() => {
   }
 })
 
-const leftStyle = computed(() => ({
-  [props.orientation === 'landscape' ? 'width' : 'height']: props.fixed ? `${boundSplit.value}px` : `${boundSplit.value}%`,
-}))
+const axis = computed(() => props.orientation === 'landscape' ? 'width' : 'height')
 
-const rightStyle = computed(() => ({
-  [props.orientation === 'landscape' ? 'width' : 'height']: props.fixed ? null : `${100 - boundSplit.value}%`,
-}))
+/** Whether there are two panes to divide, drag between, or share the axis. */
+const hasBothPanes = computed(() => props.showFirst && props.showLast)
+
+// A sole pane takes the axis whichever half it is, and loses the `flex-none` /
+// `flex-1` modifiers below that only mean something against a sibling — the
+// `fixed` case included, where a pixel width would pin it beside dead space.
+const leftStyle = computed(() => {
+  if (!hasBothPanes.value) {
+    return { [axis.value]: '100%' }
+  }
+  return { [axis.value]: props.fixed ? `${boundSplit.value}px` : `${boundSplit.value}%` }
+})
+
+const rightStyle = computed(() => {
+  if (!hasBothPanes.value) {
+    return { [axis.value]: '100%' }
+  }
+  return { [axis.value]: props.fixed ? null : `${100 - boundSplit.value}%` }
+})
 
 const dragging = ref(false)
 let startPosition = 0
@@ -157,6 +211,15 @@ function dragEnd() {
   removeDragListeners()
 }
 
+// The dragger goes with the boundary, but the listeners are on `window` and
+// this component now outlives the toggle that removed it — so a drag in flight
+// would otherwise keep writing a split for a divider that is no longer there.
+watch(hasBothPanes, (both) => {
+  if (!both && dragging.value) {
+    dragEnd()
+  }
+})
+
 function removeDragListeners() {
   window.removeEventListener('mousemove', dragMove)
   window.removeEventListener('mouseup', dragEnd)
@@ -179,17 +242,19 @@ onUnmounted(() => {
     }"
   >
     <div
+      v-if="showFirst"
       class="relative top-0 left-0 z-20"
       :class="{
         'pointer-events-none': dragging,
-        'border-r border-gray-300/30 dark:border-gray-800': orientation === 'landscape' && showDivider,
-        'flex-none': fixed,
+        'border-r border-gray-300/30 dark:border-gray-800': orientation === 'landscape' && showDivider && hasBothPanes,
+        'flex-none': fixed && hasBothPanes,
       }"
       :style="leftStyle"
     >
       <slot name="first" />
 
       <div
+        v-if="hasBothPanes"
         class="dragger absolute z-100 hover:bg-primary-500/50 transition-colors duration-150 delay-150"
         :class="{
           'top-0 bottom-0 cursor-ew-resize': orientation === 'landscape',
@@ -201,11 +266,12 @@ onUnmounted(() => {
       />
     </div>
     <div
+      v-if="showLast"
       class="relative bottom-0 right-0"
       :class="{
         'pointer-events-none': dragging,
-        'border-t border-gray-300/30 dark:border-gray-800': orientation === 'portrait' && showDivider,
-        'flex-1': fixed,
+        'border-t border-gray-300/30 dark:border-gray-800': orientation === 'portrait' && showDivider && hasBothPanes,
+        'flex-1': fixed && hasBothPanes,
       }"
       :style="rightStyle"
     >

package/src/app/components/base/BaseTab.vue

@@ -1,10 +1,20 @@
 <script lang="ts">
+import type { PropType } from 'vue'
+import type { RouteLocationRaw } from 'vue-router'
 import { defineComponent } from 'vue'
 
 export default defineComponent({
   inheritAttrs: false,
 
   props: {
+    // Declared rather than passed through `$attrs`: with
+    // `inheritAttrs: false` the checker cannot see it there, and
+    // router-link requires it.
+    to: {
+      type: [String, Object] as PropType<RouteLocationRaw>,
+      required: true,
+    },
+
     exact: {
       type: Boolean,
       default: false,
@@ -21,6 +31,7 @@ export default defineComponent({
 <template>
   <router-link
     v-slot="{ isActive, isExactActive, href, navigate }"
+    :to="to"
     class="poveste-base-tab"
     v-bind="$attrs"
     custom
@@ -30,7 +41,7 @@ export default defineComponent({
       :href="href"
       class="px-4 h-full inline-flex items-center hover:bg-primary-50 dark:hover:bg-primary-900 relative text-gray-900 dark:text-gray-100"
       :class="{
-        'text-primary-500 dark:text-primary-400': matched != null ? matched : (exact && isExactActive) || (!exact && isActive),
+        'text-primary-700 dark:text-primary-400': matched != null ? matched : (exact && isExactActive) || (!exact && isActive),
       }"
       @click="navigate"
     >

package/src/app/components/command/CommandPrompts.vue

@@ -1,5 +1,6 @@
 <script lang="ts" setup>
 import type { ClientCommand } from '@poveste/shared'
+import type { Component } from 'vue'
 import { nextTick, onMounted, reactive, ref } from 'vue'
 import { executeCommand, getCommandContext } from '../../util/commands.js'
 import BaseButton from '../base/BaseButton.vue'
@@ -67,8 +68,15 @@ onMounted(() => {
       {{ command.label }}
     </div>
 
+    <!--
+      `promptTypes[prompt.type]` resolves to the component whose `prompt` prop
+      is that member of the union, but nothing states the correlation and the
+      checker cannot infer it. Splitting this into `v-if` branches per type is
+      what makes it checkable; that is a refactor of untested UI, so it waits
+      for coverage rather than riding along with the type gate (#441).
+    -->
     <component
-      :is="promptTypes[prompt.type]"
+      :is="promptTypes[prompt.type] as Component"
       v-for="(prompt, index) of command.prompts"
       :key="prompt.field"
       ref="promptComps"

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

@@ -33,7 +33,7 @@ const hasEvents = computed(() => eventsStore.events.length)
       :to="{ ...$route, query: { ...$route.query, tab: 'docs' } }"
       :matched="$route.query.tab === 'docs'"
       :class="{
-        'opacity-50': !renderedDoc,
+        'opacity-70': !renderedDoc,
       }"
     >
       Docs
@@ -42,7 +42,7 @@ const hasEvents = computed(() => eventsStore.events.length)
       :to="{ ...$route, query: { ...$route.query, tab: 'events' } }"
       :matched="$route.query.tab === 'events'"
       :class="{
-        'opacity-50': !hasEvents,
+        'opacity-70': !hasEvents,
       }"
     >
       Events
@@ -62,7 +62,7 @@ const hasEvents = computed(() => eventsStore.events.length)
         :to="{ ...$route, query: { ...$route.query, tab: 'docs' } }"
         :matched="$route.query.tab === 'docs'"
         :class="{
-          'opacity-50': !renderedDoc,
+          'opacity-70': !renderedDoc,
         }"
       >
         Docs
@@ -71,7 +71,7 @@ const hasEvents = computed(() => eventsStore.events.length)
         :to="{ ...$route, query: { ...$route.query, tab: 'events' } }"
         :matched="$route.query.tab === 'events'"
         :class="{
-          'opacity-50': !hasEvents,
+          'opacity-70': !hasEvents,
         }"
       >
         Events