@master/internal-site 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@master/internal-site",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "description": "First-party Astro and Svelte website framework for Master sites.",
   "engines": {

package/src/astro/propagated-assets.ts

@@ -11,19 +11,29 @@ export interface PropagatedModule<T> {
   collectedStyles: (string | { id: string, content: string })[]
 }
 
+export interface PageStyle {
+  /** The dev-time Vite module id. Hydrated islands that import the same CSS update this element in place. */
+  id?: string
+  content: string
+}
+
 export interface PageAssets {
   links: string[]
-  styles: string[]
+  styles: PageStyle[]
 }
 
 export const propagatedAssetsQuery = '?astroPropagatedAssets'
 
 export function mergeAssets(...modules: PropagatedModule<unknown>[]): PageAssets {
   const links = new Set<string>()
-  const styles = new Set<string>()
+  const styles = new Map<string, PageStyle>()
   for (const module of modules) {
     module.collectedLinks.forEach((link) => links.add(link))
-    module.collectedStyles.forEach((style) => styles.add(typeof style === 'string' ? style : style.content))
+    for (const style of module.collectedStyles) {
+      const record: PageStyle = typeof style === 'string' ? { content: style } : style
+      const key = record.id ?? record.content
+      if (!styles.has(key)) styles.set(key, record)
+    }
   }
-  return { links: [...links], styles: [...styles] }
+  return { links: [...links], styles: [...styles.values()] }
 }

package/src/docs-shell/components/PageContentList.svelte

@@ -8,7 +8,6 @@
 <script lang="ts">
   import '@master/internal-site/styles/system/toc.css'
 
-  import Link from './Link.svelte'
   import PageContentTitle from './PageContentTitle.svelte'
   import { usePageContent, type PageContentItem } from './page-content.svelte'
   import groupPageContent from '../utils/group-page-content'
@@ -57,9 +56,9 @@
 
 <!-- The bootstrap script marks the live entry before hydration, so its attribute may differ from the first render. -->
 {#snippet nav({ id, title, level }: PageContentItem)}
-  <Link href={'#' + id} aria-current={pageContent.currentId === id ? 'location' : undefined} data-page-content-nav-id={id} data-level={level} lang={langOf(title)}>
+  <a href={'#' + id} aria-current={pageContent.currentId === id ? 'location' : undefined} data-page-content-nav-id={id} data-level={level} lang={langOf(title)}>
     <PageContentTitle {title} translate={translate ? t : undefined} />
-  </Link>
+  </a>
 {/snippet}
 
 <ol bind:this={element} {lang} data-fold={fold ? '' : undefined}>

package/src/docs-shell/components/page-content.svelte.ts

@@ -96,6 +96,10 @@ export function providePageContent(getItems: () => PageContentItem[]): PageConte
 
     updateCurrentId()
     initialUpdateTimeout = window.setTimeout(requestUpdate, 100)
+    // The rail can hydrate before a streamed article has delivered its headings.
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', requestUpdate, { once: true })
+    }
     document.addEventListener('scroll', requestUpdate, {
       capture: true,
       passive: true
@@ -103,6 +107,7 @@ export function providePageContent(getItems: () => PageContentItem[]): PageConte
     window.addEventListener('resize', requestUpdate, { passive: true })
 
     return () => {
+      document.removeEventListener('DOMContentLoaded', requestUpdate)
       document.removeEventListener('scroll', requestUpdate, true)
       window.removeEventListener('resize', requestUpdate)
       window.clearTimeout(initialUpdateTimeout)

package/src/docs-shell/layouts/Doc.astro

@@ -26,16 +26,12 @@ const pageContent = Array.isArray(toc) && toc.length > 0 ? toc : null
 ---
 
 <DocMain class={props.class} footerProps={footerProps}>
+  {/* Stream the rail before the article so both columns are present when its title first paints. */}
+  {pageContent && <PageContent client:load items={pageContent.map(({ id, title, level }) => ({ id, title, level }))} metadata={{ sourcePath: metadata.sourcePath, title: metadata.title }} />}
   <DocArticle aside={Boolean(pageContent)}>
     <ArticleHeader {...props} locale={locale} metadata={metadata} dictionaries={dictionaries} toc={pageContent} />
     <slot />
     <PageNavs locale={locale} metadata={metadata} pageCategories={pageCategories} dictionaries={dictionaries} />
   </DocArticle>
-  {pageContent && (
-    <Fragment>
-      {/* The rail's island serializes only the fields it renders. */}
-      <PageContent client:load items={pageContent.map(({ id, title, level }) => ({ id, title, level }))} metadata={{ sourcePath: metadata.sourcePath, title: metadata.title }} />
-      <PageContentBootstrap items={pageContent} />
-    </Fragment>
-  )}
+  {pageContent && <PageContentBootstrap items={pageContent} />}
 </DocMain>

package/src/layouts/Document.astro

@@ -9,6 +9,7 @@ import { localizePathname } from '../astro/route-paths'
 import { siteContextElementId } from '../docs-shell/site'
 import type { Metadata } from '../docs-shell/types/Metadata'
 import type { PageAssets } from '../astro/propagated-assets'
+import NavigationTransition from './NavigationTransition.astro'
 
 interface Props {
   metadata: Partial<Metadata>
@@ -45,6 +46,7 @@ if (['dark', 'light'].includes(value)) document.documentElement.style.colorSchem
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    {!bare && <NavigationTransition />}
     <link rel="icon" href="/favicon.ico" type="image/x-icon" sizes="any" />
     <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
     <script is:inline blocking="render" set:html={themeScript}></script>
@@ -56,7 +58,8 @@ if (['dark', 'light'].includes(value)) document.documentElement.style.colorSchem
         Their request-local context must already exist, even with cached CSS/JS. */}
     <script is:inline type="application/json" id={siteContextElementId} set:html={siteContextJSON}></script>
     {assets.links.map((href) => <link rel="stylesheet" href={href} />)}
-    {assets.styles.map((css) => <style is:inline set:html={css}></style>)}
+    {/* Without the dev id, Vite appends a second copy when an island imports the same CSS, reordering the cascade. */}
+    {assets.styles.map(({ id, content }) => <style is:inline data-vite-dev-id={id} set:html={content}></style>)}
     <title>{head.title}</title>
     {config.feeds?.map(feed => <link rel="alternate" type={feed.type} title={feed.title} href={new URL(feed.href, config.origin).href} />)}
     {head.tags.map(({ tag: Tag, attributes }) => <Tag {...attributes} />)}

package/src/layouts/NavigationTransition.astro

@@ -0,0 +1,58 @@
+<style is:inline>
+  @media (prefers-reduced-motion: no-preference) and (scripting: enabled) {
+    @view-transition { navigation: auto; types: master-navigation; }
+  }
+</style>
+<script is:inline>
+  (() => {
+    if (!('onpagereveal' in window)) return
+
+    const hasTitle = () => Boolean(document.querySelector('main h1')?.textContent?.trim())
+    const hasFragmentTarget = () => {
+      if (!location.hash) return true
+      try {
+        return Boolean(document.getElementById(decodeURIComponent(location.hash.slice(1))))
+      } catch {
+        return false
+      }
+    }
+
+    addEventListener('pageswap', ({ viewTransition, activation }) => {
+      if (!viewTransition) return
+      void viewTransition.ready.catch(() => {})
+      // The standalone examples own their transitions and do not opt in to the site capture.
+      const destination = activation?.entry?.url
+      if (destination && new URL(destination).pathname.startsWith('/examples/')) viewTransition.skipTransition()
+    })
+    addEventListener('pagereveal', ({ viewTransition }) => {
+      if (!viewTransition) return
+      void viewTransition.ready.catch(() => {})
+      if (!hasTitle() || !hasFragmentTarget()) viewTransition.skipTransition()
+    })
+
+    const activation = window.navigation?.activation
+    const source = activation ? activation.from?.url : document.referrer
+    const navigation = performance.getEntriesByType('navigation')[0]
+    if (!source || new URL(source).origin !== location.origin || navigation?.type === 'reload'
+      || document.visibilityState !== 'visible' || !matchMedia('(prefers-reduced-motion: no-preference)').matches) return
+
+    // The browser may reveal a buffered response before parsing its title. Release this short
+    // wait as soon as the title arrives. If the stream is slower, pagereveal skips the capture.
+    const blocker = document.createElement('link')
+    if (!('blocking' in blocker)) return
+    blocker.rel = 'expect'
+    blocker.href = '#master-navigation-ready'
+    blocker.setAttribute('blocking', 'render')
+    const release = () => {
+      observer.disconnect()
+      clearTimeout(timeout)
+      blocker.remove()
+    }
+    const observer = new MutationObserver(() => {
+      if (hasTitle()) release()
+    })
+    const timeout = setTimeout(release, 120)
+    observer.observe(document.documentElement, { childList: true, subtree: true, characterData: true })
+    document.head.append(blocker)
+  })()
+</script>

package/src/styles/docs-shell/docs.css

@@ -63,6 +63,7 @@
 
   /* The contents rail stands still beside the article; a long list scrolls inside it. */
   :is(.ui-docs-body > .ui-toc, .ui-docs-body > astro-island > .ui-toc) {
+    order: 1;
     position: sticky; top: var(--docs-header); display: flex; flex: none; flex-direction: column; align-self: start; width: var(--docs-rail); max-height: calc(100dvh - var(--docs-header));
     padding: 3.5rem var(--ui-space-lg) var(--ui-space-xl) 0;
   }

package/src/styles/system/header-core.css

@@ -1,4 +1,6 @@
 /* header-core: owned component styles; shared definitions come from the foundation. */
+@import './navigation-transitions.css';
+
 @layer components {
   .ui-app { min-height: 100dvh; background: var(--ui-surface-canvas); color: var(--ui-text-body); }
 

package/src/styles/system/navigation-transitions.css

@@ -0,0 +1,61 @@
+/* Cross-document captures only. The homepage and blog overlay headers travel with their page. */
+:root:active-view-transition-type(master-navigation) .ui-header:not([data-variant="stickable"]) {
+  view-transition-name: master-header;
+  view-transition-class: master-navigation-chrome;
+}
+
+:root:active-view-transition-type(master-navigation) #sidebar.ui-sidebar {
+  view-transition-name: master-sidebar;
+  view-transition-class: master-navigation-chrome;
+}
+
+:root:active-view-transition-type(master-navigation) .ui-docs-body .ui-toc[data-rail] {
+  view-transition-name: master-contents;
+  view-transition-class: master-navigation-chrome;
+}
+
+:root:active-view-transition-type(master-navigation)::view-transition {
+  pointer-events: none;
+}
+
+:root:active-view-transition-type(master-navigation)::view-transition-group(root) {
+  animation-duration: var(--ui-duration-quick);
+}
+
+/* Replace matching navigation in place while the page underneath crossfades. */
+:root:active-view-transition-type(master-navigation)::view-transition-group(.master-navigation-chrome) {
+  animation: none;
+}
+
+:root:active-view-transition-type(master-navigation)::view-transition-old(.master-navigation-chrome) {
+  animation: none;
+  opacity: 0;
+}
+
+:root:active-view-transition-type(master-navigation)::view-transition-new(.master-navigation-chrome) {
+  animation: none;
+  mix-blend-mode: normal;
+}
+
+/* If a layout gains or loses navigation, fade that capture with the page. */
+:root:active-view-transition-type(master-navigation)::view-transition-old(.master-navigation-chrome):only-child {
+  animation-name: master-navigation-chrome-out;
+  animation-duration: var(--ui-duration-quick);
+  animation-fill-mode: both;
+}
+
+:root:active-view-transition-type(master-navigation)::view-transition-new(.master-navigation-chrome):only-child {
+  animation-name: master-navigation-chrome-in;
+  animation-duration: var(--ui-duration-quick);
+  animation-fill-mode: both;
+}
+
+@keyframes master-navigation-chrome-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+@keyframes master-navigation-chrome-out {
+  from { opacity: 1; }
+  to { opacity: 0; }
+}