@poveste/app 0.14.0 → 0.16.0

package/src/app/util/render-tracker.ts

@@ -0,0 +1,31 @@
+/**
+ * Whether the render now under way inside a realm reported a throw.
+ *
+ * The host cannot see inside the realm, so "did this render succeed" has to be
+ * read off the two named messages it does see. A throw reaches
+ * `app.config.errorHandler` during mount and `SANDBOX_READY` is emitted after
+ * `await host.mount()` returns, so the order is always error-then-ready — which
+ * makes a ready with nothing recorded since the render began a clean render.
+ *
+ * Clearing on the story and variant ids changing instead cleared the pair being
+ * navigated *to*, so arriving at a broken story wiped its marker, and the fixed
+ * story the comment was about was never reached at all: a file edited in place
+ * keeps its ids, so that watcher did not fire on the one path it named (#597).
+ */
+export function createRenderTracker() {
+  let threw = false
+
+  return {
+    /** A new render is starting: what the previous one reported no longer holds. */
+    begin(): void {
+      threw = false
+    },
+    threw(): void {
+      threw = true
+    },
+    /** True when the render that has just reported ready said nothing before it. */
+    wasClean(): boolean {
+      return !threw
+    },
+  }
+}

package/src/app/util/scroll.ts

@@ -1,7 +1,33 @@
 import type { Ref } from 'vue'
-import scrollIntoView from 'scroll-into-view-if-needed'
 import { onMounted, watch } from 'vue'
 
+/**
+ * The closest ancestor that can actually scroll, or `null` for the viewport.
+ *
+ * `overlay` is in the test because it is what `overflow: overlay` computes to
+ * where it is still supported, and an element scrolling under it would
+ * otherwise be measured against the wrong box.
+ */
+function scrollParent(el: HTMLElement): HTMLElement | null {
+  for (let node = el.parentElement; node; node = node.parentElement) {
+    const style = getComputedStyle(node)
+    if (/auto|scroll|overlay/.test(style.overflowY + style.overflowX)) {
+      return node
+    }
+  }
+  return null
+}
+
+/** Whether the element is already wholly inside the box that would scroll. */
+function isVisibleIn(el: HTMLElement, scroller: HTMLElement | null): boolean {
+  const rect = el.getBoundingClientRect()
+  const bounds = scroller?.getBoundingClientRect()
+  const top = bounds?.top ?? 0
+  const bottom = bounds?.bottom ?? window.innerHeight
+
+  return rect.top >= top && rect.bottom <= bottom
+}
+
 // `el` is a template ref, so it is undefined until the component mounts and
 // again once it unmounts. `autoScroll` has always guarded for that; the
 // signature was the only thing claiming otherwise, and it made four callers
@@ -13,16 +39,28 @@ export function useScrollOnActive(active: Ref<boolean>, el: Ref<HTMLElement | un
     }
   }, { flush: 'post' })
 
+  /*
+   * What `scroll-into-view-if-needed` was here for: centre the element, but
+   * only when it is not already on screen. The platform has no single option
+   * for that pair — `block: 'center'` always scrolls, and `block: 'nearest'`
+   * never centres — so the "if needed" half is the check above and the
+   * "centre" half is the native call.
+   *
+   * Two `getBoundingClientRect` reads, on an activation event rather than per
+   * frame, so this is not the per-event shape CONVENTIONS.md rule 6 is about.
+   *
+   * The library took `boundary: document.body`, which native has no equivalent
+   * for: it will scroll every scrollable ancestor up to the document. The
+   * chrome's layout is full-height and the document does not scroll, so there
+   * is nothing above the pane for it to move.
+   */
   function autoScroll() {
-    if (el.value) {
-      scrollIntoView(el.value, {
-        scrollMode: 'if-needed',
-        block: 'center',
-        inline: 'nearest',
-        behavior: 'smooth',
-        boundary: document.body,
-      })
+    const target = el.value
+    if (!target || isVisibleIn(target, scrollParent(target))) {
+      return
     }
+
+    target.scrollIntoView({ block: 'center', inline: 'nearest', behavior: 'smooth' })
   }
 
   onMounted(() => {

package/src/app/util/state.ts

@@ -1,9 +1,43 @@
-import { clone, omit } from '@poveste/shared'
+import { clone, isMarkedRaw, isPlainObject, omit } from '@poveste/shared'
 import { isRef, unref } from 'vue'
 
-const isObject = val => val !== null && typeof val === 'object'
+const isObject = (val: unknown): val is object => val !== null && typeof val === 'object'
 
-export function toRawDeep(val, clean = false, seen = new WeakMap()) {
+/**
+ * A value the caller must leave out rather than carry, because it cannot make
+ * the trip this copy is being made for.
+ */
+const DROP = Symbol('poveste.drop')
+
+/**
+ * A detached copy of `val`, with refs unwrapped.
+ *
+ * `clean` means the copy leaves the realm — it is posted to the other side of
+ * the sandbox bridge, or stored as a preset — so values that cannot survive
+ * that are dropped rather than carried: functions, and anything Vue has marked
+ * raw.
+ *
+ * Marked values are dropped rather than passed through, because `__v_skip` is
+ * non-enumerable and does not cross `structuredClone`. Handing one over would
+ * strip the mark and hand the far side a plain graph to deep-watch, which is
+ * how the first attempt at #957 turned a slow story into a hanging one. A key
+ * the sandbox never sends is a key the controls panel does not show, and for
+ * the case this aims at — a template ref onto a component's exposed object —
+ * that is a control nobody could have used anyway.
+ *
+ * Without `clean` the copy stays in this realm, so a marked value is carried by
+ * reference. That is what the two Vues' bridge wants: an identity both sides
+ * share, which `isEquivalent` then settles by `Object.is` instead of walking.
+ */
+export function toRawDeep(val: unknown, clean = false, seen: WeakMap<object, any> = new WeakMap()): any {
+  const value = walk(val, clean, seen)
+
+  // Only a nested key is ever dropped. A state object that is itself marked
+  // would otherwise leave here as the sentinel.
+  return value === DROP ? {} : value
+}
+
+function walk(val: unknown, clean: boolean, seen: WeakMap<object, any>): any {
   const unwrappedValue = isRef(val) ? unref(val) : val
 
   if (typeof unwrappedValue === 'symbol') {
@@ -14,16 +48,27 @@ export function toRawDeep(val, clean = false, seen = new WeakMap()) {
     return unwrappedValue
   }
 
+  if (isMarkedRaw(unwrappedValue)) {
+    return clean ? DROP : unwrappedValue
+  }
+
   if (seen.has(unwrappedValue)) {
     return seen.get(unwrappedValue)
   }
 
+  if (!Array.isArray(unwrappedValue) && !isPlainObject(unwrappedValue)) {
+    return notPlain(unwrappedValue, clean, seen)
+  }
+
   if (Array.isArray(unwrappedValue)) {
     const result: unknown[] = []
     seen.set(unwrappedValue, result)
-    let list = unwrappedValue.map(value => toRawDeep(value, clean, seen))
+    let list = unwrappedValue.map(value => walk(value, clean, seen))
     if (clean) {
-      list = list.filter(value => typeof value !== 'function')
+      // Dropped the same way a function is, indices and all: an array that has
+      // one of these in it comes out shorter, which is what has always happened
+      // to an array of functions.
+      list = list.filter(value => typeof value !== 'function' && value !== DROP)
     }
     result.push(...list)
     return result
@@ -31,17 +76,105 @@ export function toRawDeep(val, clean = false, seen = new WeakMap()) {
   else {
     const result = {}
     seen.set(unwrappedValue, result)
-    toRawObject(unwrappedValue, result, clean, seen)
+    toRawObject(unwrappedValue as Record<any, any>, result, clean, seen)
     return result
   }
 }
 
-function toRawObject(obj: Record<any, any>, target: Record<any, any>, clean = false, seen = new WeakMap()) {
+/**
+ * A value with a prototype of its own — a `Date`, a `Map`, a class instance.
+ *
+ * These used to fall past every branch into `toRawObject`, whose `Object.keys`
+ * is empty for most of them, so they arrived as `{}` with no error and no
+ * warning (#977). `postMessage` is structured clone, and structured clone
+ * carries `Date`, `Map`, `Set`, `RegExp`, `Error`, typed arrays and `BigInt`
+ * intact — so they were being destroyed here, before the transport that would
+ * have carried them was ever reached.
+ *
+ * Structured clone is therefore the line, rather than a list authored here:
+ * it is the boundary that actually exists, it needs no maintaining as the
+ * platform adds types, and adopting it is what makes this walk agree with
+ * `isEquivalent`, which refuses to compare anything that is not plain.
+ *
+ * Without `clean` the copy stays in this realm, so the value is carried by
+ * reference — the same answer `copyState` in `@poveste/shared` gives, and the
+ * identity `isEquivalent` then settles by `Object.is`.
+ */
+function notPlain(value: object, clean: boolean, seen: WeakMap<object, any>): any {
+  if (!clean) {
+    return value
+  }
+
+  if (value instanceof Map || value instanceof Set) {
+    return walkCollection(value, seen)
+  }
+
+  try {
+    const copy = structuredClone(value)
+    seen.set(value, copy)
+    return copy
+  }
+  catch {
+    // `URL`, a DOM node, a `Promise`: structured clone refuses them, so passing
+    // one through would turn a silent flattening into a thrown `DataCloneError`
+    // mid-sync. Dropped the way a function is, and the key does not arrive.
+    return DROP
+  }
+}
+
+/**
+ * `Map` and `Set`, walked rather than handed to `structuredClone`, for two
+ * measured reasons.
+ *
+ * They hold user values, so this walk's own rules have to reach inside them: a
+ * function or a marked value in a `Map` is the same problem it is in an array,
+ * and an array already comes out shorter for it. Cloning the whole container
+ * would carry a function straight into a `DataCloneError`, and would strip a
+ * marked value's `__v_skip` and hand the far side a plain graph to deep-watch
+ * — which is the hazard #974 exists to prevent.
+ *
+ * And these are the only types here that Vue proxies. `structuredClone` throws
+ * `DataCloneError` on a reactive `Map` while the raw one clones fine, so a
+ * `Map` in reactive state would be refused and dropped — a second silence
+ * rather than a fix for the first. `Date`, `RegExp`, `Error` and typed arrays
+ * are not proxied, so the path below never meets a proxy and needs no `toRaw`.
+ */
+function walkCollection(value: Map<any, any> | Set<any>, seen: WeakMap<object, any>): any {
+  const keep = (walked: any) => walked !== DROP && typeof walked !== 'function'
+
+  if (value instanceof Set) {
+    const copy = new Set()
+    seen.set(value, copy)
+    for (const entry of value) {
+      const walked = walk(entry, true, seen)
+      if (keep(walked)) copy.add(walked)
+    }
+    return copy
+  }
+
+  const copy = new Map()
+  seen.set(value, copy)
+  for (const [key, entry] of value) {
+    const walkedKey = walk(key, true, seen)
+    const walked = walk(entry, true, seen)
+    if (keep(walkedKey) && keep(walked)) copy.set(walkedKey, walked)
+  }
+  return copy
+}
+
+function toRawObject(obj: Record<any, any>, target: Record<any, any>, clean: boolean, seen: WeakMap<object, any>) {
   Object.keys(obj).forEach((key) => {
     if (clean && typeof obj[key] === 'function') {
       return
     }
-    target[key] = toRawDeep(obj[key], clean, seen)
+
+    const value = walk(obj[key], clean, seen)
+
+    if (value === DROP) {
+      return
+    }
+
+    target[key] = value
   })
 }
 

package/src/app/util/variant.ts

@@ -10,17 +10,27 @@ import { useRoute } from 'vue-router'
  * has to tell "a variant is on its way" from "this story is waiting for the
  * reader to pick one" needs the same answer it will give — hence one predicate
  * rather than two copies of the condition (#328).
+ *
+ * Any story with variants, deliberately. It used to require a remembered choice
+ * or exactly one variant, which made `StoryView`'s `variants[0]` fallback
+ * unreachable: a story with several variants and no history satisfied neither
+ * clause, so the first visit of a session showed an empty panel and every visit
+ * after it worked, because the first one recorded the history (#724).
+ *
+ * No layout clause. Grid stories already auto-selected on revisit through the
+ * remembered choice, so excluding them here would auto-open them on the second
+ * visit and never the first — this defect, made permanent for one layout.
  */
 // A type predicate rather than `boolean`: the body already establishes that the
 // story is there, and returning `boolean` threw that away at every call site —
 // `StoryView` reads the story twice immediately after this returns true.
 export function autoSelectsVariant(story: Story | null | undefined): story is Story {
-  return !!story && (!!story.lastSelectedVariant || story.variants.length === 1)
+  return !!story && story.variants.length > 0
 }
 
 export function useCurrentVariantRoute(variant: Ref<Variant>) {
   const route = useRoute()
-  const isActive = computed(() => route.query.variantId === variant.value.id)
+  const isActive = computed(() => route.query['variantId'] === variant.value.id)
   const targetRoute = computed(() => ({
     ...route,
     query: {

package/dist/app/style/floating.pcss

@@ -1,40 +0,0 @@
-/* @TODO custom themes */
-
-.v-popper {
-  line-height: 0;
-}
-
-.v-popper--theme-dropdown {
-  /*
-   * Written with the `dark:` variant rather than a `.ptw-dark &` descendant
-   * rule. The chrome CSS is wrapped in `@scope`, and `.ptw-dark` sits on
-   * `<html>` — above the scope root — so a descendant rule keyed on it never
-   * matches and the dropdown silently falls back to floating-vue's stock light
-   * theme. `dark:` compiles to `&:where(.ptw-dark, .ptw-dark *)`, which puts the
-   * condition on the subject and survives the wrapper. See #101.
-   */
-  .v-popper__inner {
-    @apply dark:bg-gray-700 dark:border-gray-850 dark:text-gray-100;
-  }
-
-  .v-popper__arrow-inner {
-    @apply dark:border-gray-700;
-  }
-
-  .v-popper__arrow-outer {
-    @apply dark:border-gray-850;
-  }
-
-  &.v-popper__popper--show-from .v-popper__wrapper {
-    transform: scale(.75);
-  }
-
-  &.v-popper__popper--show-to .v-popper__wrapper {
-    transform: none;
-    transition: transform .15s cubic-bezier(0, 1, .5, 1);
-  }
-}
-
-.v-popper__popper:focus-visible {
-  outline: none;
-}

package/dist/bundled/util/tooltip.js

@@ -1,14 +0,0 @@
-import { isMac } from "./env.js";
-import { formatKey } from "./keyboard.js";
-//#region src/app/util/tooltip.ts
-function makeTooltip(descriptionHtml, keyboardShortcut) {
-	return {
-		content: `<div>${descriptionHtml}</div><div class="flex items-center gap-1 mt-2 text-sm">${genKeyboardShortcutHtml(keyboardShortcut({ isMac }))}</div>`,
-		html: true
-	};
-}
-function genKeyboardShortcutHtml(shortcut) {
-	return `<span class="border border-gray-600 px-1 rounded-sm text-gray-400">${shortcut.split("+").map((k) => formatKey(k.trim())).join(" ")}</span>`;
-}
-//#endregion
-export { makeTooltip };

package/src/app/style/floating.pcss

@@ -1,40 +0,0 @@
-/* @TODO custom themes */
-
-.v-popper {
-  line-height: 0;
-}
-
-.v-popper--theme-dropdown {
-  /*
-   * Written with the `dark:` variant rather than a `.ptw-dark &` descendant
-   * rule. The chrome CSS is wrapped in `@scope`, and `.ptw-dark` sits on
-   * `<html>` — above the scope root — so a descendant rule keyed on it never
-   * matches and the dropdown silently falls back to floating-vue's stock light
-   * theme. `dark:` compiles to `&:where(.ptw-dark, .ptw-dark *)`, which puts the
-   * condition on the subject and survives the wrapper. See #101.
-   */
-  .v-popper__inner {
-    @apply dark:bg-gray-700 dark:border-gray-850 dark:text-gray-100;
-  }
-
-  .v-popper__arrow-inner {
-    @apply dark:border-gray-700;
-  }
-
-  .v-popper__arrow-outer {
-    @apply dark:border-gray-850;
-  }
-
-  &.v-popper__popper--show-from .v-popper__wrapper {
-    transform: scale(.75);
-  }
-
-  &.v-popper__popper--show-to .v-popper__wrapper {
-    transform: none;
-    transition: transform .15s cubic-bezier(0, 1, .5, 1);
-  }
-}
-
-.v-popper__popper:focus-visible {
-  outline: none;
-}

package/src/app/util/tooltip.ts

@@ -1,13 +0,0 @@
-import { isMac } from './env.js'
-import { formatKey } from './keyboard.js'
-
-export function makeTooltip(descriptionHtml: string, keyboardShortcut: (options: { isMac: boolean }) => string) {
-  return {
-    content: `<div>${descriptionHtml}</div><div class="flex items-center gap-1 mt-2 text-sm">${genKeyboardShortcutHtml(keyboardShortcut({ isMac }))}</div>`,
-    html: true,
-  }
-}
-
-function genKeyboardShortcutHtml(shortcut: string) {
-  return `<span class="border border-gray-600 px-1 rounded-sm text-gray-400">${shortcut.split('+').map(k => formatKey(k.trim())).join(' ')}</span>`
-}