Rename tsSsgContext to pageContext.

Author: koculu

frontend/components/studioBrand.ts

@@ -1,7 +1,7 @@
 import {
   type LogoConfig,
   type LogoSize,
-  resolveTsSsgContext,
+  resolvePageContext,
 } from '@purestack/ts-common'
 import { defineComponent, html, type RefOrValue } from 'regor'
 
@@ -17,7 +17,7 @@ export function defineStudioBrandComponent() {
     props: ['size'],
     context: (head) => ({
       ...head.props,
-      config: resolveTsSsgContext(head).site.logo,
+      config: resolvePageContext(head).site.logo,
     }),
   })
 }

frontend/purestack.studio/guides/extending/regor.mdx

@@ -17,7 +17,13 @@ highlights:
 
 # Regor
 
-<a href="https://github.com/PureStackStudio/Regor" target="_blank" rel="noopener">Regor</a> is the component framework PureStack is built on. It runs in two places:
+<a
+  href="https://github.com/PureStackStudio/Regor"
+  target="_blank"
+  rel="noopener"
+  >Regor</a
+>
+is the component framework PureStack is built on. It runs in two places:
 
 <Grid columns="1" columnsSm="2" class="gap-3 mb-4">
   <Panel tone="neutral" bodyClass="p-3">
@@ -153,7 +159,7 @@ Every page goes through the same four steps:
 | Where it runs | Your build, once per page | The visitor's browser |
 | What it produces | Static HTML | A live, interactive interface |
 | Event handlers, `r-model`, timers | Not kept | Run normally |
-| Page data (`tsSsgContext`) | Available | Not available |
+| Page data (`pageContext`) | Available | Not available |
 | Components | All built-in and registered components | The component families you register |
 
 ## Regor at build time
@@ -185,24 +191,24 @@ A plain attribute passes a string. An attribute that starts with a colon is a Re
 
 ### Expressions and page data
 
-Text in double braces is a Regor expression, anywhere in a page. Inside markup, expressions can read `tsSsgContext`, which holds the page and site data that PureStack provides during the build:
+Text in double braces is a Regor expression, anywhere in a page. Inside markup, expressions can read `pageContext`, which holds the page and site data that PureStack provides during the build:
 
 | Field | Contents |
 | --- | --- |
-| `tsSsgContext.pageInfo.frontmatter` | The page's frontmatter, including any custom fields you add |
-| `tsSsgContext.pageInfo.urlPath` | The page's URL, such as `/guides/extending/regor/` |
-| `tsSsgContext.pageInfo.relPath` | The source file path inside the content folder |
-| `tsSsgContext.site` | The resolved site configuration |
-| `tsSsgContext.navigation`, `tsSsgContext.outline` | The page's navigation and heading outline |
-| `tsSsgContext.locale`, `tsSsgContext.locales` | The page's language and the site's languages |
+| `pageContext.pageInfo.frontmatter` | The page's frontmatter, including any custom fields you add |
+| `pageContext.pageInfo.urlPath` | The page's URL, such as `/guides/extending/regor/` |
+| `pageContext.pageInfo.relPath` | The source file path inside the content folder |
+| `pageContext.site` | The resolved site configuration |
+| `pageContext.navigation`, `pageContext.outline` | The page's navigation and heading outline |
+| `pageContext.locale`, `pageContext.locales` | The page's language and the site's languages |
 
 This page lists three highlights in its frontmatter. The panel below reads them during the build:
 
 <Panel tone="accent" variant="surface" bodyClass="p-3" class="mb-4">
   <p class="text-eyebrow mt-0">From this page's frontmatter</p>
-  <strong>{{ tsSsgContext.pageInfo.frontmatter.title }}</strong>
+  <strong>{{ pageContext.pageInfo.frontmatter.title }}</strong>
   <ul class="mb-0">
-    <li r-for="item in tsSsgContext.pageInfo.frontmatter.highlights">
+    <li r-for="item in pageContext.pageInfo.frontmatter.highlights">
       {{ item }}
     </li>
   </ul>
@@ -218,9 +224,9 @@ highlights:
 ---
 
 <Panel tone="accent" variant="surface" bodyClass="p-3">
-  <strong>{{ tsSsgContext.pageInfo.frontmatter.title }}</strong>
+  <strong>{{ pageContext.pageInfo.frontmatter.title }}</strong>
   <ul>
-    <li r-for="item in tsSsgContext.pageInfo.frontmatter.highlights">{{ item }}</li>
+    <li r-for="item in pageContext.pageInfo.frontmatter.highlights">{{ item }}</li>
   </ul>
 </Panel>
 ```
@@ -294,9 +300,10 @@ export default defineConfig({
 >
   Export the interface that types a component, as <code>ReleaseNote</code> is
   exported here. The
-  <a href="/guides/getting-started/vscode-extension/">VS Code extension</a> finds components
-  through their exported interfaces. Without the export, it can't complete the
-  component's props or jump from a tag in your markup to the component's source.
+  <a href="/guides/getting-started/vscode-extension/">VS Code extension</a>
+  finds components through their exported interfaces. Without the export, it
+  can't complete the component's props or jump from a tag in your markup to the
+  component's source.
 </AlertBox>
 
 Then use it in any page. Content between the tags fills the `<slot>`:
@@ -307,7 +314,7 @@ Then use it in any page. Content between the tags fills the `<slot>`:
 </ReleaseNote>
 ```
 
-Tag names match registered keys regardless of case, so `<ReleaseNote>` finds `releaseNote`. The kebab-case form `<release-note>` works too. Components can also read page data. Pass the component head to `resolveTsSsgContext` from `@purestack/ts-common`, as the built-in navigation and page-link components do.
+Tag names match registered keys regardless of case, so `<ReleaseNote>` finds `releaseNote`. The kebab-case form `<release-note>` works too. Components can also read page data. Pass the component head to `resolvePageContext` from `@purestack/ts-common`, as the built-in navigation and page-link components do.
 
 ## Regor in the browser
 
@@ -332,8 +339,8 @@ Browser apps do not get the build's component list. Each app registers the compo
 <AlertBox tone="info" icon="tabler:info-circle" title="Register icons too">
   Register each icon your app shows, including the defaults that components draw
   themselves, such as the arrow in a select field. The
-  <a href="/guides/styling/icons/#icons-in-browser-apps">Icons guide</a> lists those
-  defaults.
+  <a href="/guides/styling/icons/#icons-in-browser-apps">Icons guide</a> lists
+  those defaults.
 </AlertBox>
 
 ### Template syntax

packages/ts-common/README.md

@@ -5,6 +5,6 @@ scripts. This package defines site configuration, page frontmatter, navigation,
 logos, templates, and the rendering context so those packages agree on the same
 shapes.
 
-Import types such as `SiteConfig`, `PageFrontmatter`, and `TsSsgContext` when
-building a custom integration. The runtime exports `resolveTsSsgContext` and
-`tryResolveTsSsgContext` find the site context in a Regor component.
+Import types such as `SiteConfig`, `PageFrontmatter`, and `PageContext` when
+building a custom integration. The runtime exports `resolvePageContext` and
+`tryResolvePageContext` find the site context in a Regor component.

packages/ts-common/src/index.ts

@@ -39,9 +39,9 @@ export type {
   PageTranslationInfo,
 } from './page-template-types'
 export {
-  resolveTsSsgContext,
-  tryResolveTsSsgContext,
-} from './resolveTsSsgContext'
+  resolvePageContext,
+  tryResolvePageContext,
+} from './resolvePageContext'
 export type {
   AnalyticsConfig,
   AuthConfig,
@@ -64,6 +64,6 @@ export type {
 } from './site-config-types'
 export type {
   PageOutlineItem,
-  TsSsgContext,
+  PageContext,
   TsSsgNavigation,
 } from './ts-ssg-context'

packages/ts-common/src/resolvePageContext.ts

@@ -0,0 +1,37 @@
+import type { PageContext } from './ts-ssg-context'
+
+type ContextCarrier = {
+  pageContext?: PageContext
+}
+
+type HeadLike = {
+  ctx?: unknown[]
+}
+
+function hasPageContext(value: unknown): value is ContextCarrier {
+  return typeof value === 'object' && value !== null && 'pageContext' in value
+}
+
+function hasContextStack(value: unknown): value is HeadLike {
+  return typeof value === 'object' && value !== null && 'ctx' in value
+}
+
+export function resolvePageContext(head: unknown): PageContext {
+  const stack = hasContextStack(head) && Array.isArray(head.ctx) ? head.ctx : []
+  for (const ctx of stack) {
+    if (!hasPageContext(ctx)) continue
+    if (ctx.pageContext) return ctx.pageContext
+  }
+  throw new Error('pageContext is not available in the Regor context stack.')
+}
+
+export function tryResolvePageContext(
+  head: unknown,
+): PageContext | undefined {
+  const stack = hasContextStack(head) && Array.isArray(head.ctx) ? head.ctx : []
+  for (const ctx of stack) {
+    if (!hasPageContext(ctx)) continue
+    if (ctx.pageContext) return ctx.pageContext
+  }
+  return undefined
+}

packages/ts-common/src/resolveTsSsgContext.ts

@@ -21,7 +21,7 @@ export interface TsSsgNavigation {
   pageLinks?: PageNavigationLinks
 }
 
-export interface TsSsgContext {
+export interface PageContext {
   site: SiteConfig
   pageInfo: PageInfo
   navigation?: TsSsgNavigation

packages/ts-common/src/ts-ssg-context.ts

@@ -17,7 +17,7 @@ describe('BarChart rendering', () => {
     const app = createApp(
       {
         components: defineBarChartComponents(),
-        tsSsgContext: createTestContext(),
+        pageContext: createTestContext(),
         items: values.map((value, index) => ({
           label: `Day ${index + 1}`,
           value,
@@ -57,7 +57,7 @@ describe('BarChart rendering', () => {
     const app = createApp(
       {
         components: defineBarChartComponents(),
-        tsSsgContext: createTestContext(),
+        pageContext: createTestContext(),
         items: [
           { label: 'Core', value: 42, color: '#18a999' },
           { label: 'Edge', value: 28, color: '#f4a261' },
@@ -102,7 +102,7 @@ describe('BarChart rendering', () => {
     const app = createApp(
       {
         components: defineBarChartComponents(),
-        tsSsgContext: createTestContext(),
+        pageContext: createTestContext(),
         items: [{ label: 'Invalid', value: Number.NaN }],
       },
       {
@@ -131,7 +131,7 @@ describe('BarChart rendering', () => {
     const app = createApp(
       {
         components: defineBarChartComponents(),
-        tsSsgContext: createTestContext(),
+        pageContext: createTestContext(),
         items: [{ label: 'Core', value: 42 }],
       },
       {

packages/ts-components/src/standard/barChart/barChart.test.ts

@@ -1,4 +1,4 @@
-import { type TsSsgContext, tryResolveTsSsgContext } from '@purestack/ts-common'
+import { type PageContext, tryResolvePageContext } from '@purestack/ts-common'
 import type { SemanticTone } from '@purestack/ts-style'
 import {
   type ComputedRef,
@@ -104,7 +104,7 @@ function defineButtonLinkComponent() {
       'iconOnly',
       'ariaLabel',
     ],
-    context: (head) => resolveBtnLink(head.props, tryResolveTsSsgContext(head)),
+    context: (head) => resolveBtnLink(head.props, tryResolvePageContext(head)),
   })
 }
 
@@ -132,7 +132,7 @@ function resolveBtn(props: Btn): Btn {
 
 function resolveBtnLink(
   props: BtnLink,
-  context: TsSsgContext | undefined,
+  context: PageContext | undefined,
 ): BtnLink {
   return {
     ...props,
@@ -176,7 +176,7 @@ function resolveShowEndIcon(props: BtnBase) {
   return hasIcon && unref(props.iconPosition) === 'end'
 }
 
-function resolveButtonHref(props: BtnLink, context: TsSsgContext | undefined) {
+function resolveButtonHref(props: BtnLink, context: PageContext | undefined) {
   const value = unref(props.href)
   const href = typeof value === 'string' ? value.trim() : undefined
   return href ? (context?.resolvePublicHref(href) ?? href) : undefined

packages/ts-components/src/standard/btn/btn.ts

@@ -1,7 +1,7 @@
 import {
   type ClassicLogoConfig,
-  type TsSsgContext,
-  tryResolveTsSsgContext,
+  type PageContext,
+  tryResolvePageContext,
 } from '@purestack/ts-common'
 import {
   getCurrentThemePaletteVar,
@@ -19,8 +19,16 @@ import {
 } from 'regor'
 
 const logoTemplate = html`<div class="classic-logo" :style="logo.layoutStyle">
-  <a class="classic-logo__link" :href="logo.href === null ? undefined : (logo.href ?? '/')" :aria-label="logo.ariaLabel">
-    <span class="classic-logo__glyph" :style="logo.glyphStyle" aria-hidden="true">
+  <a
+    class="classic-logo__link"
+    :href="logo.href === null ? undefined : (logo.href ?? '/')"
+    :aria-label="logo.ariaLabel"
+  >
+    <span
+      class="classic-logo__glyph"
+      :style="logo.glyphStyle"
+      aria-hidden="true"
+    >
       <Icon :name="logo.icon" r-if="logo.icon"/>
       <span class="classic-logo__glyph-mark" r-else></span>
     </span>
@@ -105,7 +113,7 @@ interface ResolvedClassicLogo {
 
 function resolveClassicLogo(
   props: Partial<ClassicLogoConfig>,
-  context: TsSsgContext | undefined,
+  context: PageContext | undefined,
 ): ResolvedClassicLogo {
   const brand = props.brand
   const letterColors = props.letterColors
@@ -416,7 +424,7 @@ function defineClassicLogoComponent() {
             Object.entries(direct).filter(([, value]) => value !== undefined),
           ),
         }
-        return resolveClassicLogo(options, tryResolveTsSsgContext(head))
+        return resolveClassicLogo(options, tryResolvePageContext(head))
       }),
     }),
   })