@master/internal-site 0.1.1 → 0.1.3

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

@@ -20,6 +20,9 @@
 </script>
 
 <script lang="ts">
+  import '@master/internal-site/styles/interface.css'
+  import '@master/internal-site/styles/system/dialog.css'
+
   import '../../styles/docs-shell/documentation-search.css'
   import { untrack } from 'svelte'
   import Link from './Link.svelte'
@@ -38,6 +41,7 @@
   const tw = locale === 'tw'
   let opened = $state(false)
   let query = $state('')
+  let shortcutModifier = $state('⌘')
   let pages = $state.raw<DocumentationSearchPage[]>([])
   let error = $state('')
   let loading = $state(false)
@@ -67,6 +71,7 @@
   }
 
   function open(event?: Event) {
+    shortcutModifier = /Mac|iPhone|iPad|iPod/.test(navigator.platform) ? '⌘' : 'Ctrl'
     const trigger = (event as CustomEvent<{ trigger?: HTMLElement }> | undefined)?.detail?.trigger
     returnFocus = trigger instanceof HTMLElement ? trigger : document.activeElement as HTMLElement
     opened = true
@@ -169,6 +174,6 @@
         </li>{/each}{/if}
       </ol>
     </div>
-    <div class="ui-dialog-foot" aria-hidden="true"><span><span class="ui-kbd"><IconArrowUp size={12} /></span><span class="ui-kbd"><IconArrowDown size={12} /></span>{tw ? '選擇' : 'Navigate'}</span><span><span class="ui-kbd"><IconCornerDownLeft size={12} /></span>{tw ? '開啟' : 'Open'}</span><span>{tw ? '文件搜尋' : 'Documentation'}</span></div>
+    <div class="ui-dialog-foot" aria-hidden="true"><span><span class="ui-kbd"><IconArrowUp size={12} /></span><span class="ui-kbd"><IconArrowDown size={12} /></span>{tw ? '選擇' : 'Navigate'}</span><span><span class="ui-kbd"><IconCornerDownLeft size={12} /></span>{tw ? '開啟' : 'Open'}</span><span class="ui-search-shortcut">{tw ? '隨時搜尋' : 'Search anytime'}<kbd class="ui-kbd">{shortcutModifier}</kbd><kbd class="ui-kbd">K</kbd></span></div>
   </dialog>
 {/if}

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

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import '@master/internal-site/styles/system/segmented.css'
+
   import '../../styles/docs-shell/segments.css'
   import type { Snippet } from 'svelte'
 

package/src/docs-shell/components/StepSection.astro

@@ -1,6 +1,5 @@
 ---
-import '../../styles/system/data.css'
-import '../../styles/docs-shell/steps.css'
+import '../../styles/system/steps.css'
 import type { HTMLAttributes } from 'astro/types'
 
 type Props = HTMLAttributes<'ol'>

package/src/docs-shell/components/Tabs.astro

@@ -1,4 +1,5 @@
 ---
+import '@master/internal-site/styles/system/segmented.css'
 import type { HTMLAttributes } from 'astro/types'
 
 type Props = HTMLAttributes<'nav'>

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

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import '@master/internal-site/styles/system/fields.css'
+
   import type { HTMLSelectAttributes } from 'svelte/elements'
   import clsx from 'clsx'
   import { useThemeMode } from '../contexts/theme-mode.svelte'

package/src/docs-shell/components/markdown/Table.astro

@@ -1,4 +1,5 @@
 ---
+import '@master/internal-site/styles/system/table.css'
 ---
 
 <div class="ui-table">

package/src/docs-shell/components/markdown-components.ts

@@ -1,4 +1,3 @@
-import '../../styles/system/data.css'
 import Image from './Image.svelte'
 import Do from './Do.astro'
 import DoNot from './DoNot.astro'

package/src/docs-shell/remark/markdown-components.js

@@ -53,8 +53,29 @@ function fenceProps(node) {
   return props
 }
 
-const componentsExport = `import { markdownComponents as __markdownComponents } from '@master/internal-site/components/markdown-components'
-export const components = __markdownComponents`
+// A document imports only the components it renders. Importing a shared object
+// of every component also propagates every component's styles to every MDX page.
+const componentPaths = {
+  a: 'markdown/Anchor.astro', h2: 'markdown/Heading2.astro', h3: 'markdown/Heading3.astro',
+  img: 'Image.svelte', Image: 'Image.svelte', table: 'markdown/Table.astro',
+  Code: 'Code.astro', InlineCode: 'InlineCode.astro', PMAction: 'PMAction.astro',
+  Do: 'Do.astro', DoNot: 'DoNot.astro', Info: 'Info.astro', Warn: 'Warn.astro',
+  InteractingIndicator: 'InteractingIndicator.astro'
+}
+
+function documentComponents(tree) {
+  const used = new Set()
+  visit(tree, node => {
+    if (node.type === 'link' || node.type === 'linkReference') used.add('a')
+    if (node.type === 'image' || node.type === 'imageReference') used.add('img')
+    if (node.type === 'table') used.add('table')
+    if (node.type === 'heading' && [2, 3].includes(node.depth)) used.add(`h${node.depth}`)
+    if (['mdxJsxFlowElement', 'mdxJsxTextElement'].includes(node.type) && node.name in componentPaths) used.add(node.name)
+  })
+  const entries = [...used].sort().map((name, index) => ({ name, local: `__masterComponent${index}`, path: componentPaths[name] }))
+  return entries.map(({ local, path }) => `import ${local} from '@master/internal-site/components/${path}'`).join('\n')
+    + `\nexport const components = {${entries.map(({ name, local }) => `${name}: ${local}`).join(', ')}}`
+}
 
 /**
  * Markdown constructs that render through site components: fences become `Code` (or a
@@ -63,11 +84,6 @@ export const components = __markdownComponents`
  */
 export default function remarkMarkdownComponents() {
   return (tree) => {
-    tree.children.unshift({
-      type: 'mdxjsEsm',
-      value: componentsExport,
-      data: { estree: parse(componentsExport, { ecmaVersion: 'latest', sourceType: 'module' }) }
-    })
     visit(tree, (node, index, parent) => {
       if (!parent || index === undefined) return
       if (node.type === 'code') {
@@ -97,5 +113,10 @@ export default function remarkMarkdownComponents() {
         return index
       }
     })
+    const source = documentComponents(tree)
+    tree.children.unshift({
+      type: 'mdxjsEsm', value: source,
+      data: { estree: parse(source, { ecmaVersion: 'latest', sourceType: 'module' }) }
+    })
   }
 }

package/src/docs-shell/scripts/document.ts

@@ -44,4 +44,4 @@ const tableSizes = new ResizeObserver(entries => {
     else table.removeAttribute('tabindex')
   }
 })
-document.querySelectorAll<HTMLElement>('.ui-table:not([tabindex])').forEach(table => { if (!table.closest('site-island')) tableSizes.observe(table) })
+document.querySelectorAll<HTMLElement>('.ui-table:not([tabindex])').forEach(table => { if (!table.closest('astro-island')) tableSizes.observe(table) })

package/src/docs-shell/types/Metadata.ts

@@ -1,10 +1,21 @@
 export declare type MetadataTitle = string | { absolute: string } | { default: string, template?: string }
 
+/** An article's visible cover also supplies its social cards. */
+export interface ArticleCover {
+  src: string
+  alt: string
+  width: number
+  height: number
+  /** Optional PNG/JPEG version of the same artwork for social clients. */
+  socialImage?: string
+}
+
 /** Page metadata in the shape `docs-shell/utils/head` renders. */
 export declare type Metadata = {
   title?: MetadataTitle
   description?: string
   category?: string
+  cover?: ArticleCover
   robots?: string | { index?: boolean, follow?: boolean }
   alternates?: { canonical?: string }
   openGraph?: { title?: string, description?: string, siteName?: string, images?: string | string[] }

package/src/docs-shell/utils/generate-metadata.ts

@@ -38,7 +38,9 @@ export default async function generate(
       card: 'summary_large_image'
     }
   }
-  if (metadata.openGraph?.images) {
+  if (metadata.cover) {
+    baseMetadata.openGraph.images = baseMetadata.twitter.images = metadata.cover.socialImage ?? metadata.cover.src
+  } else if (metadata.openGraph?.images) {
     baseMetadata.twitter.images = metadata.openGraph.images
   } else {
     // postbuild-static renders each placeholder into a static /og image.

package/src/docs-shell/utils/head.ts

@@ -57,16 +57,19 @@ export function resolveHead(metadata: Partial<Metadata>, { project, siteURL, pat
     }
   }
   const { openGraph, twitter } = metadata
+  const coverImage = metadata.cover?.socialImage ?? metadata.cover?.src
   meta('property', 'og:title', openGraph?.title)
   meta('property', 'og:description', openGraph?.description)
   meta('property', 'og:site_name', openGraph?.siteName)
   // Open Graph and Twitter cards require absolute image URLs.
-  for (const image of list(openGraph?.images)) meta('property', 'og:image', absolute(image))
+  for (const image of list(coverImage ?? openGraph?.images)) meta('property', 'og:image', absolute(image))
+  if (metadata.cover) meta('property', 'og:image:alt', metadata.cover.alt)
   meta('name', 'twitter:card', twitter?.card)
   meta('name', 'twitter:site', twitter?.site)
   meta('name', 'twitter:creator', twitter?.creator)
   meta('name', 'twitter:title', twitter?.title)
   meta('name', 'twitter:description', twitter?.description)
-  for (const image of list(twitter?.images)) meta('name', 'twitter:image', absolute(image))
+  for (const image of list(coverImage ?? twitter?.images)) meta('name', 'twitter:image', absolute(image))
+  if (metadata.cover) meta('name', 'twitter:image:alt', metadata.cover.alt)
   return { title: resolveTitle(metadata.title, project), tags }
 }

package/src/examples/components/ArticleTransitionScene.svelte

@@ -1,4 +1,8 @@
 <script lang="ts">
+  import '@master/internal-site/styles/system/button-feedback.css'
+  import '@master/internal-site/styles/system/buttons.css'
+  import '@master/internal-site/styles/system/sheet.css'
+
   import Image from '@master/internal-site/components/Image.svelte'
   import IconArrowLeft from '@tabler/icons-svelte-runes/icons/arrow-left'
   import IconArrowUpRight from '@tabler/icons-svelte-runes/icons/arrow-up-right'

package/src/examples/layout-system/page.astro

@@ -1,6 +1,5 @@
 ---
 // Bare examples import the system parts they render: sheets and specimens.
-import '@master/internal-site/styles/system/surfaces.css'
 import '@master/internal-site/styles/system/specimens.css'
 import DemoItem from '@master/internal-site/demo/DemoItem.svelte'
 import DemoLabel from '@master/internal-site/demo/DemoLabel.svelte'

package/src/home/HomeBentoFrame.astro

@@ -1,4 +1,5 @@
 ---
+import './bento.css'
 import type { HTMLAttributes } from 'astro/types'
 
 type Props = HTMLAttributes<'div'>

package/src/home/HomeBentoGrid.astro

@@ -1,4 +1,5 @@
 ---
+import './bento.css'
 import type { HTMLAttributes } from 'astro/types'
 
 type Props = HTMLAttributes<'div'>

package/src/home/HomeFooter.svelte

@@ -6,7 +6,7 @@
   import IconMoon from '@tabler/icons-svelte-runes/icons/moon'
   import IconSun from '@tabler/icons-svelte-runes/icons/sun'
   import LanguageSelect from '@master/internal-site/components/LanguageSelect.svelte'
-  import Link from '@master/internal-site/components/Link.svelte'
+  import FooterNavLink from '../docs-shell/components/FooterLink.svelte'
   import ThemeSelect from '@master/internal-site/components/ThemeSelect.svelte'
   import { useThemeMode } from '@master/internal-site/contexts/theme-mode.svelte'
   import { getSite } from '@master/internal-site/site'
@@ -32,7 +32,7 @@
           <ul class="home-footer-links">
             {#each group.links as link (link.href)}
               <li>
-                <Link class="home-footer-link" href={link.href}>{t(link.name)}</Link>
+                <FooterNavLink class="home-footer-link" href={link.href} disabled={link.disabled}>{t(link.name)}</FooterNavLink>
               </li>
             {/each}
           </ul>

package/src/home/bento.css

@@ -0,0 +1,167 @@
+/* * Cards stand directly on the page ground: no shell around them, so every edge is the card's own 1px
+   * contour. A card may hold its figure in a well, 12px in, and nothing deeper. */
+/* The title and description stay together, with a separate illustration to their right. */
+/* * A narrow card cannot spare a 7rem column beside its copy: the title shares a row with a smaller
+   * illustration and the description takes the full measure below, so neither wraps a word or two per line. */
+/* * The well's contour is drawn above the figure, so a pane that fills the well never hides it and
+   * a pane's own edge never doubles it: every well reads as one 1px line. */
+@layer components {
+  .home-bento-frame {
+    position: relative;
+  }
+
+  .home-bento-grid {
+    display: grid;
+    gap: var(--home-gap);
+
+    @media (--md) {
+      gap: 1rem;
+    }
+  }
+
+  .home-bento-card {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+    border-radius: var(--home-radius-sheet);
+    background-color: var(--home-sheet);
+    box-shadow: 0 0 0 1px var(--home-hairline), var(--home-elevation-1);
+    transition: box-shadow var(--home-base) var(--home-ease);
+
+    &:hover {
+      box-shadow: 0 0 0 1px var(--home-rule), var(--home-elevation-1);
+    }
+  }
+  .home-bento-card-header {
+    /* Contain the header only: size containment on the subgrid card collapses auto-height code panes. */
+    container: home-card / inline-size;
+    padding: 1.75rem 1.5rem 2rem;
+
+    @media (--sm) {
+      padding: 2.25rem 2.25rem 2.5rem;
+    }
+
+    @media (--lg) {
+      padding: 2.5rem 2.75rem 2.75rem;
+    }
+  }
+
+  .home-bento-card-caption {
+    display: grid;
+    grid-template-columns: minmax(0, 44ch) 7rem;
+    /* In a wide card the copy keeps its measure and the illustration rides the card's right edge. */
+    justify-content: space-between;
+    align-items: start;
+    align-content: start;
+    column-gap: 1.5rem;
+  }
+
+  .home-bento-card-copy { min-width: 0; }
+
+  .home-bento-card-caption > .home-illustration {
+    --home-illustration-size: 7rem;
+  }
+  @container home-card (width < 28rem) {
+    .home-bento-card-caption {
+      grid-template-columns: minmax(0, 1fr) 4rem;
+      align-items: center;
+      gap: 0.75rem 1rem;
+    }
+    .home-bento-card-copy { display: contents; }
+    .home-bento-card-title { grid-column: 1; grid-row: 1; }
+    .home-bento-card-body { grid-column: 1 / -1; grid-row: 2; max-width: none; margin-top: 0; }
+    .home-bento-card-hint { grid-column: 1 / -1; grid-row: 3; margin-top: 0; }
+    .home-bento-card-caption > .home-illustration {
+      --home-illustration-size: 4rem;
+      grid-column: 2;
+      grid-row: 1;
+      margin-block: 0;
+    }
+  }
+
+  @container home-card (width < 16rem) {
+    .home-bento-card-caption { grid-template-columns: minmax(0, 1fr) 3rem; column-gap: 0.75rem; }
+    .home-bento-card-caption > .home-illustration { --home-illustration-size: 3rem; }
+  }
+
+  @container home-card (width < 12rem) {
+    .home-bento-card-caption { grid-template-columns: minmax(0, 1fr); }
+    .home-bento-card-caption > .home-illustration { display: none; }
+  }
+
+  @container home-card (width >= 28rem) {
+    .home-bento-card-caption { column-gap: 3rem; }
+  }
+
+  .home-bento-card-title {
+    min-width: 0;
+    margin: 0;
+    font-size: var(--home-card-title);
+    font-weight: var(--font-weight-regular);
+    line-height: 1.25;
+    letter-spacing: -0.025em;
+    color: var(--home-text);
+    text-wrap: balance;
+  }
+
+  .home-bento-card-body {
+    min-width: 0;
+    max-width: 44ch;
+    margin: 0.75rem 0 0;
+    font-size: var(--home-body);
+    line-height: 1.6;
+    color: var(--home-text-quiet);
+    text-wrap: pretty;
+  }
+
+  .home-bento-card-hint {
+    margin: 0.75rem 0 0;
+    font-size: var(--home-caption);
+    line-height: 1.5;
+    color: var(--home-text-faint);
+  }
+
+  .home-heading-link {
+    color: inherit;
+    text-decoration: none;
+    text-decoration-thickness: 1px;
+    text-underline-offset: 0.2em;
+
+    &:hover { text-decoration-line: underline; }
+
+    &:focus-visible {
+      border-radius: var(--radius-sm);
+      outline: 2px solid var(--home-ink);
+      outline-offset: 4px;
+    }
+  }
+  .home-bento-visual {
+    position: relative;
+    isolation: isolate;
+    overflow: hidden;
+    margin: auto var(--home-gap) var(--home-gap);
+    border-radius: var(--home-radius-well);
+    background-color: var(--home-well);
+
+    &::after {
+      position: absolute;
+      inset: 0;
+      z-index: 20;
+      border-radius: inherit;
+      box-shadow: var(--home-groove);
+      pointer-events: none;
+      content: '';
+    }
+  }
+
+  .home-bento-visual-top {
+    margin-top: 0;
+  }
+}
+
+@layer components { @media (forced-colors: active) { .home-bento-card { outline: 1px solid CanvasText; } } }
+
+@layer components {
+  .home-page:lang(zh) .home-bento-card-body { text-wrap: balance; }
+}

package/src/home/design.css

@@ -420,7 +420,7 @@
    * Han prose breaks between any two characters, so pretty wrapping still leaves a last line of two characters.
    * Short leads and card descriptions balance their lines instead.
    */
-  .home-page:lang(zh) :is(.home-section-body, .home-bento-card-body) {
+  .home-page:lang(zh) .home-section-body {
     text-wrap: balance;
   }