@poveste/app 0.19.1 → 0.21.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@poveste/app",
   "type": "module",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "description": "Pre-bundled UI for Poveste",
   "author": {
     "name": "Sorin Gitlan",
@@ -36,16 +36,16 @@
     "node": ">=22.22.2"
   },
   "dependencies": {
-    "@poveste/controls": "^0.19.1",
-    "@poveste/shared": "^0.19.1",
-    "@poveste/vendors": "^0.19.1",
+    "@poveste/controls": "^0.21.0",
+    "@poveste/shared": "^0.21.0",
+    "@poveste/vendors": "^0.21.0",
     "fuse.js": "^7.0.0",
-    "shiki": "^4.4.3"
+    "shiki": "^4.5.0"
   },
   "devDependencies": {
     "@fontsource/noto-sans-display": "^5.3.0",
-    "@iconify-json/carbon": "^1.2.27",
-    "@iconify-json/fluent": "1.2.58",
+    "@iconify-json/carbon": "^1.2.28",
+    "@iconify-json/fluent": "1.2.60",
     "@iconify-json/mdi": "^1.2.3",
     "@iconify-json/ri": "^1.2.10",
     "@iconify/utils": "^3.1.7",
@@ -53,24 +53,24 @@
     "@tailwindcss/postcss": "^4.3.3",
     "@tailwindcss/typography": "^0.5.20",
     "@types/fs-extra": "^11.0.4",
-    "@types/node": "^26.6.3",
-    "@vitejs/plugin-vue": "^6.0.9",
+    "@types/node": "^26.6.5",
+    "@vitejs/plugin-vue": "^6.0.10",
     "@vueuse/core": "^15.0.0",
     "chokidar": "^5.0.0",
-    "concurrently": "^10.0.5",
+    "concurrently": "^10.0.6",
     "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.1",
-    "vitest": "^5.0.2",
-    "vue": "^3.5.43",
-    "vue-router": "^5.3.1",
-    "vue-tsc": "^3.3.11"
+    "vite": "^8.3.4",
+    "vitest": "^5.0.5",
+    "vue": "^3.5.44",
+    "vue-router": "^5.4.0",
+    "vue-tsc": "^3.3.13"
   },
   "scripts": {
     "build": "pnpm run icons && rimraf dist && vite build && pnpm run build:css && node ./scripts/copy.mjs",

package/src/app/components/HomeView.vue

@@ -2,10 +2,10 @@
 import { computed } from 'vue'
 import PovesteLogo from '../assets/poveste.svg'
 import { useStoryStore } from '../stores/story'
-import { customLogos, povesteConfig } from '../util/config'
+import { customLogos } from '../util/config'
 import HomeCounter from './app/HomeCounter.vue'
 
-const logoUrl = computed(() => povesteConfig.theme?.logo?.square ? customLogos?.square ?? PovesteLogo : PovesteLogo)
+const logoUrl = computed(() => customLogos?.square ?? PovesteLogo)
 const storyStore = useStoryStore()
 
 const stats = computed(() => {

package/src/app/components/app/AppLogo.vue

@@ -6,15 +6,13 @@ import PovesteLogoLight from '../../assets/poveste-text.svg'
 import { customLogos, povesteConfig } from '../../util/config'
 import { isDark } from '../../util/dark'
 
-// `theme.logo` is what the config asked for; `customLogos` is the resolved URL
-// map from the virtual module. Two objects, so a check on one narrows nothing
-// about the other — and falling back to the bundled logo beats rendering an
-// `<img>` with no `src` if they ever disagree.
+// `customLogos` holds a served URL for each logo the config names. The config's
+// own entries are paths on the machine that built the book, and are not sent (#1383).
 const logoUrl = computed(() => {
   if (isDark.value) {
-    return povesteConfig.theme.logo?.dark ? customLogos?.dark ?? PovesteLogoDark : PovesteLogoDark
+    return customLogos?.dark ?? PovesteLogoDark
   }
-  return povesteConfig.theme.logo?.light ? customLogos?.light ?? PovesteLogoLight : PovesteLogoLight
+  return customLogos?.light ?? PovesteLogoLight
 })
 
 const altText = computed(() => `${povesteConfig.theme.title} logo`)

package/src/app/components/app/TopBarChipItem.vue

@@ -1,10 +1,59 @@
 <template>
-  <!-- Without an href this is not a link, so `aria-label` on it is prohibited and
-       it has no accessible role. Chip items are used both ways (#310). -->
-  <a
-    :role="$attrs['href'] ? undefined : 'button'"
-    class="poveste-top-bar-chip-item flex items-center gap-1 px-2.5 py-1.5 hover:bg-white/50 active:bg-white/70 dark:hover:bg-white/10 dark:active:bg-white/15 hover:text-primary-500 dark:hover:text-primary-400 cursor-pointer text-gray-900 dark:text-gray-100 transition-colors"
+  <!-- A link where it navigates, a button everywhere else. An `<a>` without an
+       href is not focusable, so a keyboard could not reach the chip (#1351). -->
+  <component
+    :is="$attrs['href'] ? 'a' : 'button'"
+    :type="$attrs['href'] ? undefined : 'button'"
+    class="poveste-top-bar-chip-item"
+    data-slot="top-bar-chip-item"
   >
     <slot />
-  </a>
+  </component>
 </template>
+
+<style lang="postcss">
+.poveste-top-bar-chip-item {
+  display: flex;
+  align-items: center;
+  gap: .25rem;
+  padding: .375rem .625rem;
+  border: 0;
+  font: inherit;
+  color: var(--color-gray-900);
+  cursor: pointer;
+
+  @media (prefers-reduced-motion: no-preference) {
+    transition: color .15s ease-out, background-color .15s ease-out;
+  }
+
+  &:hover {
+    background-color: rgb(255 255 255 / .5);
+    color: var(--color-primary-500);
+  }
+
+  &:active {
+    background-color: rgb(255 255 255 / .7);
+  }
+
+  /* Inset: the chip clips its items to its rounded border. */
+  &:focus-visible {
+    outline: 2px solid var(--color-primary-500);
+    outline-offset: -2px;
+  }
+
+  /* Spelled out on the subject: `.ptw-dark` sits above the `@scope` root, so a
+     descendant rule keyed on it never matches from in here (#101). */
+  &:where(.ptw-dark, .ptw-dark *) {
+    color: var(--color-gray-100);
+
+    &:hover {
+      background-color: rgb(255 255 255 / .1);
+      color: var(--color-primary-400);
+    }
+
+    &:active {
+      background-color: rgb(255 255 255 / .15);
+    }
+  }
+}
+</style>

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

@@ -1,6 +1,5 @@
 <script setup lang="ts">
 import { Icon } from '@iconify/vue'
-import BaseListItem from '../base/BaseListItem.vue'
 
 defineProps<{
   title: string
@@ -15,10 +14,14 @@ defineEmits<{
 </script>
 
 <template>
-  <BaseListItem
-    :is-active="isActive"
-    class="px-6 py-4 gap-4"
-    @navigate="$emit('click')"
+  <!-- A button: `BaseListItem` is an `<a>` with no href, which a keyboard cannot
+       reach (#1351). -->
+  <button
+    type="button"
+    class="poveste-layout-item"
+    :class="{ active: isActive }"
+    data-slot="layout-item"
+    @click="$emit('click')"
   >
     <Icon
       class="w-4 h-4 flex-none"
@@ -32,5 +35,52 @@ defineEmits<{
       :icon="stateIcon"
       aria-hidden="true"
     />
-  </BaseListItem>
+  </button>
 </template>
+
+<style lang="postcss">
+.poveste-layout-item {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  width: 100%;
+  padding: 1rem 1.5rem;
+  border: 0;
+  font: inherit;
+  text-align: start;
+  color: var(--color-gray-900);
+  cursor: pointer;
+
+  &:hover {
+    background-color: var(--color-primary-100);
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--color-primary-500);
+    outline-offset: -2px;
+  }
+
+  &.active {
+    background-color: var(--color-primary-500);
+    color: var(--color-white);
+
+    &:hover {
+      background-color: var(--color-primary-600);
+    }
+  }
+
+  /* Spelled out on the subject: `.ptw-dark` sits above the `@scope` root, so a
+     descendant rule keyed on it never matches from in here (#101). */
+  &:where(.ptw-dark, .ptw-dark *) {
+    color: var(--color-gray-100);
+
+    &:hover {
+      background-color: var(--color-primary-900);
+    }
+
+    &.active {
+      color: var(--color-black);
+    }
+  }
+}
+</style>

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

@@ -0,0 +1,323 @@
+<script lang="ts" setup>
+import type { DocProp } from '@poveste/shared'
+import type { ComponentDocsEntry } from '../../util/component-docs'
+import { computed } from 'vue'
+import { modelLabel, OPEN_PARTS, rootFirst, tagHref, tagText } from '../../util/component-docs'
+
+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
+}
+</script>
+
+<template>
+  <div
+    class="poveste-component-docs"
+    data-testid="component-docs"
+  >
+    <details
+      v-for="(component, index) of ordered"
+      :key="component.file"
+      :open="ordered.length <= OPEN_PARTS || index === 0"
+      data-slot="component"
+      :data-component="component.name"
+    >
+      <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"
+        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>
+                <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>
+                <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>
+            <template
+              v-for="slot of component.doc.slots"
+              :key="slot.name"
+            >
+              <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>
+
+        <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>
+                <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>
+    </details>
+  </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);
+  }
+}
+
+details + details {
+  margin-top: 1.5rem;
+}
+
+summary {
+  cursor: pointer;
+  margin-bottom: .5rem;
+}
+
+h3 {
+  display: inline;
+  font-weight: 600;
+  font-size: 1rem;
+}
+
+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;
+}
+
+/* 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);
+  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>