diff --git a/biome.json b/biome.json index 3137a434..c5187dea 100644 --- a/biome.json +++ b/biome.json @@ -3,6 +3,8 @@ "files": { "includes": [ "**", + "!frontend/out", + "!**/.*", "!**/dist", "!**/node_modules", "!**/.yarn", diff --git a/frontend/docs/dataGuide.ts b/frontend/docs/dataGuide.ts index 3e3d977a..022a2bed 100644 --- a/frontend/docs/dataGuide.ts +++ b/frontend/docs/dataGuide.ts @@ -64,15 +64,17 @@ export function createChartAppearanceState(): ChartAppearanceState { } } +export interface ChartAppearanceControls { + tone: Ref + variant: Ref + variantMode: Ref + width: Ref + showWidth?: RefOrValue + prefix: RefOrValue +} + export function defineChartAppearanceControls() { - return defineComponent<{ - tone: Ref - variant: Ref - variantMode: Ref - width: Ref - showWidth?: RefOrValue - prefix: RefOrValue - }>( + return defineComponent( html` @@ -94,11 +96,13 @@ export function defineChartAppearanceControls() { ) } +export interface ChartAppearanceGallery { + component: RefOrValue + axis: RefOrValue<'tone' | 'variant' | 'mode'> +} + export function defineChartAppearanceGallery() { - return defineComponent<{ - component: RefOrValue - axis: RefOrValue<'tone' | 'variant' | 'mode'> - }>( + return defineComponent( html`
{{ sample.label }} diff --git a/frontend/docs/docsComponents.ts b/frontend/docs/docsComponents.ts index 6e8a9b26..4b7200f6 100644 --- a/frontend/docs/docsComponents.ts +++ b/frontend/docs/docsComponents.ts @@ -1,9 +1,4 @@ import type { SiteConfig } from '@purestack/ts-common' -import { defineConsentPreviewComponent } from '../purestack.studio/components/site/consent/preview' -import { defineNavMenuPreviewComponent } from '../purestack.studio/components/site/nav-menu/preview' -import { definePageTocPreviewComponent } from '../purestack.studio/components/site/page-toc/preview' -import { defineSignInPreviewComponent } from '../purestack.studio/components/site/sign-in/preview' -import { defineTopBarPreviewComponent } from '../purestack.studio/components/site/top-bar/preview' import { defineApiPropertyComponent } from './apiProperty' import { defineComponentGuideComponents } from './componentGuide' import { defineChartAppearanceGallery } from './dataGuide' @@ -11,7 +6,14 @@ import { defineFormAppearanceGallery } from './formAppearance' import { defineLandingAppearanceGallery } from './landingGuide' import { defineModalExampleComponents } from './modal' import { defineSemanticToneGallery } from './semanticToneGuide' -import { defineSiteAppearanceGallery } from './siteGuide' +import { + defineConsentPreviewComponent, + defineNavMenuPreviewComponent, + definePageTocPreviewComponent, + defineSignInPreviewComponent, + defineTopBarPreviewComponent, +} from './sitePreviewComponents' +import { defineSiteAppearanceGallery } from './sitePreviews' export function defineDocumentationComponents(site: SiteConfig) { return { diff --git a/frontend/docs/landingGuide.ts b/frontend/docs/landingGuide.ts index 23b66bfc..e412fec5 100644 --- a/frontend/docs/landingGuide.ts +++ b/frontend/docs/landingGuide.ts @@ -23,12 +23,14 @@ const variants: ComponentVariant[] = [ 'none', ] +export interface LandingAppearanceGallery { + component: RefOrValue + axis: RefOrValue<'tone' | 'variant' | 'mode'> +} + /** Full, simultaneously visible samples of each component's public appearance API. */ export function defineLandingAppearanceGallery() { - return defineComponent<{ - component: RefOrValue - axis: RefOrValue<'tone' | 'variant' | 'mode'> - }>( + return defineComponent( html`
{{ sample.label }} diff --git a/frontend/docs/previewTemplate.ts b/frontend/docs/previewTemplate.ts new file mode 100644 index 00000000..cc330a1c --- /dev/null +++ b/frontend/docs/previewTemplate.ts @@ -0,0 +1,53 @@ +import type { PageTemplate } from '@purestack/ts-common' +import { h } from '@purestack/ts-html' + +const previewStyles = ` +html,body{margin:0;min-height:0;height:auto} +body.preview{display:block;min-height:0!important;padding:8px;box-sizing:border-box} +.site-guide-samples{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,16rem),1fr));gap:1rem} +.site-guide-sample{min-width:0} +.site-guide-sample>code{display:block;margin:0 0 1rem} +.site-guide-sample iframe{width:100%;border:0;display:block} +.preview .nav__menu,.preview .page-toc{position:static!important;width:100%!important;max-height:none!important} +.preview .page-toc__panel-toggle,.preview .page-toc__restore-toggle,.preview .nav__panel-toggle,.preview .nav__collapse-toggle{display:none!important} +.site-guide-sample .consent{position:static!important;pointer-events:auto!important} +.site-guide-sample .consent__banner{position:static!important;display:block!important;max-width:none!important;width:100%!important} +.site-guide-sample .consent__panel,.site-guide-sample [data-consent-settings]{display:none!important} +.site-guide-sample .site-footer{margin:0;padding:1rem} +.site-guide-sample .site-footer__inner{padding:0} +.site-guide-sample .site-footer__bottom{flex-direction:column!important;align-items:start!important} +.site-guide-sample .sign-in__panel{position:static!important;transform:none!important;min-width:0!important;width:100%!important} +.site-guide-sample .sign-in{width:100%} +.preview .topbar{position:static!important;padding:.5rem!important} +.site-guide-sample .topbar__search{min-width:0} +.site-guide-sample .text-title{font-size:1.15rem;line-height:1.35} +.site-guide-sample .site-logo{max-width:100%} +` + +// Presentation only: page head, assets, and component runtimes come from PureStack. +const frameScript = ` +document.querySelectorAll('.site-guide-sample details.sign-in').forEach(menu=>menu.open=true); +document.querySelectorAll('.site-guide-sample .consent__banner').forEach(banner=>{banner.hidden=false;banner.removeAttribute('aria-hidden')}); +if(window.parent!==window){ + const sync=()=>{document.documentElement.dataset.theme=parent.document.documentElement.dataset.theme||'light';document.documentElement.setAttribute('data-theme-ready','true')}; + sync(); + new MutationObserver(sync).observe(parent.document.documentElement,{attributes:true,attributeFilter:['data-theme']}); + const minimumHeight=frameElement ? parseFloat(frameElement.style.height)||0 : 0; + const resize=()=>{if(frameElement)frameElement.style.height=Math.max(minimumHeight,Math.ceil(document.body.getBoundingClientRect().height))+'px'}; + new ResizeObserver(resize).observe(document.body); + addEventListener('load',resize); +} +` + +export const previewTemplate: PageTemplate = ({ head, bodyHtml, pageInfo }) => { + head.push(h('style').raw(previewStyles)) + return h('html') + .attr({ lang: pageInfo.locale ?? 'en' }) + .push( + head, + h('body') + .class('preview template-doc doc-content tone--neutral') + .raw(bodyHtml) + .push(h('script').raw(frameScript)), + ) +} diff --git a/frontend/docs/semanticToneGuide.ts b/frontend/docs/semanticToneGuide.ts index f3910d52..3980b6ab 100644 --- a/frontend/docs/semanticToneGuide.ts +++ b/frontend/docs/semanticToneGuide.ts @@ -49,8 +49,12 @@ const variants: ComponentVariant[] = [ 'none', ] +export interface SemanticToneGallery { + axis: RefOrValue +} + export function defineSemanticToneGallery() { - return defineComponent<{ axis: RefOrValue }>( + return defineComponent( html`
{{ sample.label }} diff --git a/frontend/docs/siteGuide.ts b/frontend/docs/siteGuide.ts deleted file mode 100644 index fcec3e7a..00000000 --- a/frontend/docs/siteGuide.ts +++ /dev/null @@ -1,360 +0,0 @@ -import fs from 'node:fs/promises' -import path from 'node:path' -import type { - PageOutlineItem, - SiteConfig, - TsSsgContext, -} from '@purestack/ts-common' -import { - type ComponentVariant, - defineComponents, -} from '@purestack/ts-components' -import { renderApp } from '@purestack/ts-render' -import { SEMANTIC_TONES } from '@purestack/ts-style' -import { getSvgIcon } from '@purestack/ts-svg-icons' -import { withBasePath } from '@purestack/ts-util' -import { defineComponent, html, type RefOrValue, unref } from 'regor' - -const variants: ComponentVariant[] = [ - 'solid', - 'surface', - 'surfaceAlt', - 'spotlight', - 'glass', - 'flat', - 'flatAlt', - 'flatSolid', - 'outlineFill', - 'outline', - 'subtle', - 'subtleBtn', - 'link', - 'sheen', - 'underline', - 'rail', - 'bracket', - 'none', -] -const components = [ - 'SiteFooter', - 'TopBar', - 'NavMenu', - 'NavList', - 'PageToc', - 'SearchBox', - 'SignIn', - 'Consent', - 'SiteLogo', -] -const modes = new Set(['NavMenu', 'PageToc', 'SignIn', 'Consent']) -const slugOf = (name: string) => - name.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase() -const escapeAttribute = (value: string) => - value - .replaceAll('&', '&') - .replaceAll('"', '"') - .replaceAll('<', '<') - .replaceAll('>', '>') -const mark = - "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='8' fill='%232563eb'/%3E%3Cpath d='m8 16 5 5 11-11' fill='none' stroke='white' stroke-width='3'/%3E%3C/svg%3E" - -interface Sample { - label: string - template: string - signedIn?: boolean - search?: boolean - auth?: boolean - signUp?: boolean - outline?: PageOutlineItem[] -} - -function contextFor(site: SiteConfig, sample: Sample): TsSsgContext { - return { - site: { - ...site, - logo: { ...site.logo, brand: 'Studio', subtitle: undefined }, - pagefind: { ...site.pagefind, enabled: sample.search === true }, - auth: { - ...site.auth, - enabled: sample.auth !== false, - signUp: sample.signUp === true, - }, - consent: { - ...site.consent, - enabled: true, - categories: [], - services: [], - bannerTitle: 'Privacy choices', - bannerDescription: 'Choose how this example remembers preferences.', - }, - }, - pageInfo: { - relPath: 'components/site/index.mdx', - urlPath: '/components/site/', - frontmatter: { - template: 'doc', - hidden: false, - draft: false, - nav: { hidden: false }, - layout: { - showNav: false, - showToc: false, - showFooter: false, - fullWidth: false, - navMode: 'sidebar', - tocCollapsed: false, - }, - }, - }, - theme: site.style.theme, - basePath: site.basePath, - locales: site.i18n.locales, - defaultLocale: site.i18n.defaultLocale, - resolveLocaleHref: () => undefined, - resolvePublicHref: (href) => withBasePath(site.basePath, href), - recordScriptEntrypoint: () => {}, - recordRuntimeEmbed: () => {}, - navigation: { root: '/components/', items: [] }, - outline: sample.outline ?? [ - { - id: 'guide-intro', - title: 'Introduction', - depth: 2, - children: [{ id: 'guide-detail', title: 'Details', depth: 3 }], - }, - ], - } -} - -const previewCss = `html,body{margin:0;min-height:0;height:auto}body{padding:8px;box-sizing:border-box}.site-guide-samples{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,16rem),1fr));gap:1rem}.site-guide-sample{min-width:0}.site-guide-sample>code{display:block;margin:0 0 1rem}.site-guide-sample iframe{width:100%;border:0;display:block}.site-guide-sample .nav__menu,.site-guide-sample .page-toc{position:static!important;width:100%!important;max-height:none!important}.site-guide-sample .page-toc__panel-toggle,.site-guide-sample .page-toc__restore-toggle,.site-guide-sample .nav__panel-toggle,.site-guide-sample .nav__restore-toggle{display:none!important}.site-guide-sample .consent{position:static!important;pointer-events:auto!important}.site-guide-sample .consent__banner{position:static!important;display:block!important;max-width:none!important;width:100%!important}.site-guide-sample .consent__panel,.site-guide-sample [data-consent-settings]{display:none!important}.site-guide-sample .site-footer{margin:0;padding:1rem}.site-guide-sample .site-footer__inner{padding:0}.site-guide-sample .site-footer__bottom{flex-direction:column!important;align-items:start!important}.site-guide-sample .sign-in__panel{position:static!important;transform:none!important;min-width:0!important;width:100%!important}.site-guide-sample .sign-in{width:100%}.site-guide-sample .topbar{position:static!important;padding:.5rem!important}.site-guide-sample .topbar__search{min-width:0}.site-guide-sample .text-title{font-size:1.15rem;line-height:1.35}.site-guide-sample .site-logo{max-width:100%}` - -// Each frame follows its containing page's theme and grows to show every sample. -// No rendered page rewriting, global service registration, or preference mutation. -const frameScript = `document.querySelectorAll('.site-guide-sample details.sign-in').forEach(menu=>menu.open=true);document.querySelectorAll('.site-guide-sample .consent__banner').forEach(banner=>{banner.hidden=false;banner.removeAttribute('aria-hidden')});const sync=()=>{document.documentElement.dataset.theme=parent.document.documentElement.dataset.theme||'light';document.documentElement.setAttribute('data-theme-ready','true')};sync();new MutationObserver(sync).observe(parent.document.documentElement,{attributes:true,attributeFilter:['data-theme']});const resize=()=>{if(frameElement)frameElement.style.height=Math.ceil(document.body.getBoundingClientRect().height)+'px'};new ResizeObserver(resize).observe(document.body);addEventListener('load',resize);` - -function documentFor(site: SiteConfig, body: string, signedIn = false): string { - return `${body}` -} - -function templateFor( - name: string, - tone: string, - variant: string, - mode: string, - index: number, -): string { - const appearance = `tone="${tone}" variant="${variant}"${modes.has(name) ? ` variantMode="${mode}"` : ''}` - switch (name) { - case 'SiteLogo': - return `` - case 'TopBar': - return `` - case 'SignIn': - return `` - case 'Consent': - return `` - case 'SearchBox': - return `` - case 'NavMenu': - return `` - case 'NavList': - return `` - case 'PageToc': - return `` - default: - return `A shared starting point` - } -} - -function featureSamples(name: string): Sample[] { - switch (name) { - case 'TopBar': - return [ - { - label: 'SiteLogo identity', - template: '', - }, - { - label: 'ClassicLogo identity', - template: '', - }, - { - label: 'Search enabled by site config', - template: '', - search: true, - }, - { - label: 'Account access and avatar', - template: ``, - signedIn: true, - }, - ] - case 'SignIn': - return [ - { label: 'Signed out, sign-up disabled', template: '' }, - { - label: 'Signed out, sign-up enabled', - template: '', - signUp: true, - }, - { - label: 'Signed in, default account icon', - template: '', - signedIn: true, - }, - { - label: 'Signed in, custom avatar', - template: ``, - signedIn: true, - }, - { - label: 'Custom icons and avatar slot', - template: - 'Custom account destination', - signedIn: true, - }, - { - label: 'Authentication disabled', - template: - '

With site.auth.enabled false, no account control is rendered.

', - auth: false, - }, - ] - case 'PageToc': - return [ - { - label: 'Nested outline', - template: templateFor(name, 'accent', 'surface', 'stateless', 0), - }, - { - label: 'Flat outline and custom title', - template: '', - outline: [ - { id: 'guide-intro', title: 'Introduction', depth: 2 }, - { id: 'guide-detail', title: 'Details', depth: 2 }, - ], - }, - { - label: 'Empty outline', - template: '', - outline: [], - }, - ] - case 'NavMenu': - return [ - { - label: 'Active child and open ancestor', - template: templateFor(name, 'accent', 'surface', 'stateless', 0), - }, - { - label: 'Inactive, closed group', - template: - "", - }, - { - label: 'Leaf links and icons', - template: - "", - }, - { - label: 'Search and account configuration', - template: ``, - search: true, - signedIn: true, - }, - ] - default: - return [] - } -} - -export function defineSiteAppearanceGallery(site: SiteConfig) { - return defineComponent<{ - component: RefOrValue - axis: RefOrValue - }>( - html``, - { - props: ['component', 'axis'], - context: (head) => ({ - ...head.props, - title: `${unref(head.props.component)} ${unref(head.props.axis)} examples`, - previewHref: withBasePath( - site.basePath, - `/components/site/${slugOf(unref(head.props.component))}/guide-${unref(head.props.axis)}.html`, - ), - }), - }, - ) -} - -export async function writeSiteGuidePreviews(site: SiteConfig) { - for (const name of components) { - const axes = - name === 'SiteLogo' - ? ['tone'] - : name === 'NavList' - ? ['tone'] - : ['tone', 'variant', ...(modes.has(name) ? ['mode'] : [])] - if (featureSamples(name).length) axes.push('features') - for (const axis of axes) { - const values = - axis === 'tone' - ? SEMANTIC_TONES - : axis === 'variant' - ? variants - : ['stateless', 'stateful'] - const samples: Sample[] = - axis === 'features' - ? featureSamples(name) - : values.map((value, index) => ({ - label: value, - template: templateFor( - name, - axis === 'tone' ? value : 'accent', - axis === 'variant' - ? value - : axis === 'mode' - ? 'outlineFill' - : 'surface', - axis === 'mode' ? value : 'stateless', - index, - ), - })) - const cells = await Promise.all( - samples.map(async (sample) => { - const body = await renderApp(sample.template, { - components: defineComponents(getSvgIcon), - context: contextFor(site, sample), - }) - const inner = `
${body}
` - // TopBar has a fixed toggle ID; account state is a document-level class. - const isolated = - name === 'TopBar' || name === 'SignIn' || sample.signedIn - return `
${escapeAttribute(sample.label)}${isolated ? `` : body}
` - }), - ) - const cards = cells.join('') - const targets = - name === 'PageToc' - ? '

Introduction

Outline links have real targets in this document.

Details

Nested entries link to supporting content.

' - : '' - const output = path.join( - site.outDir, - 'components', - 'site', - slugOf(name), - `guide-${axis}.html`, - ) - await fs.mkdir(path.dirname(output), { recursive: true }) - await fs.writeFile( - output, - documentFor( - site, - `
${cards}
${targets}`, - ), - 'utf8', - ) - } - } -} diff --git a/frontend/docs/sitePreviewComponents.ts b/frontend/docs/sitePreviewComponents.ts new file mode 100644 index 00000000..3820883d --- /dev/null +++ b/frontend/docs/sitePreviewComponents.ts @@ -0,0 +1,81 @@ +import type { SiteConfig } from '@purestack/ts-common' +import { withBasePath } from '@purestack/ts-util' +import { defineComponent, html } from 'regor' + +export interface ConsentPreview { + title: string + previewHref: string + frameStyle: string +} + +export interface NavMenuPreview { + title: string + previewHref: string + frameStyle: string +} + +export interface PageTocPreview { + title: string + previewHref: string + frameStyle: string +} + +export interface SignInPreview { + title: string + previewHref: string + frameStyle: string +} + +export interface TopBarPreview { + title: string + previewHref: string + frameStyle: string +} + +const sitePreviewTemplate = html`` + +function resolveSitePreview(site: SiteConfig, slug: string, height: number) { + return { + title: `${slug} isolated example`, + previewHref: withBasePath( + site.basePath, + `/components/site/${slug}/preview/`, + ), + frameStyle: `height:${height}px`, + } +} + +export function defineConsentPreviewComponent(site: SiteConfig) { + return defineComponent(sitePreviewTemplate, { + props: [], + context: () => resolveSitePreview(site, 'consent', 560), + }) +} + +export function defineNavMenuPreviewComponent(site: SiteConfig) { + return defineComponent(sitePreviewTemplate, { + props: [], + context: () => resolveSitePreview(site, 'nav-menu', 400), + }) +} + +export function definePageTocPreviewComponent(site: SiteConfig) { + return defineComponent(sitePreviewTemplate, { + props: [], + context: () => resolveSitePreview(site, 'page-toc', 420), + }) +} + +export function defineSignInPreviewComponent(site: SiteConfig) { + return defineComponent(sitePreviewTemplate, { + props: [], + context: () => resolveSitePreview(site, 'sign-in', 340), + }) +} + +export function defineTopBarPreviewComponent(site: SiteConfig) { + return defineComponent(sitePreviewTemplate, { + props: [], + context: () => resolveSitePreview(site, 'top-bar', 260), + }) +} diff --git a/frontend/docs/sitePreviews.ts b/frontend/docs/sitePreviews.ts new file mode 100644 index 00000000..02c8231f --- /dev/null +++ b/frontend/docs/sitePreviews.ts @@ -0,0 +1,270 @@ +import type { SiteConfig } from '@purestack/ts-common' +import type { ComponentVariant } from '@purestack/ts-components' +import type { GeneratedPage } from '@purestack/ts-ssg' +import { SEMANTIC_TONES } from '@purestack/ts-style' +import { withBasePath } from '@purestack/ts-util' +import { defineComponent, html, type RefOrValue, unref } from 'regor' + +const variants: ComponentVariant[] = [ + 'solid', + 'surface', + 'surfaceAlt', + 'spotlight', + 'glass', + 'flat', + 'flatAlt', + 'flatSolid', + 'outlineFill', + 'outline', + 'subtle', + 'subtleBtn', + 'link', + 'sheen', + 'underline', + 'rail', + 'bracket', + 'none', +] +const components = [ + 'SiteFooter', + 'TopBar', + 'NavMenu', + 'NavList', + 'PageToc', + 'SearchBox', + 'SignIn', + 'Consent', + 'SiteLogo', +] +const modes = new Set(['NavMenu', 'PageToc', 'SignIn', 'Consent']) +const slugOf = (name: string) => + name.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase() +const escapeAttribute = (value: string) => + value + .replaceAll('&', '&') + .replaceAll('"', '"') + .replaceAll('<', '<') + .replaceAll('>', '>') +const mark = + "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='8' fill='%232563eb'/%3E%3Cpath d='m8 16 5 5 11-11' fill='none' stroke='white' stroke-width='3'/%3E%3C/svg%3E" + +interface Sample { + label: string + template: string +} + +function templateFor( + name: string, + tone: string, + variant: string, + mode: string, + index: number, +): string { + const appearance = `tone="${tone}" variant="${variant}"${modes.has(name) ? ` variantMode="${mode}"` : ''}` + switch (name) { + case 'SiteLogo': + return `` + case 'TopBar': + return `` + case 'SignIn': + return `` + case 'Consent': + return `` + case 'SearchBox': + return `` + case 'NavMenu': + return `` + case 'NavList': + return `` + case 'PageToc': + return `` + default: + return `A shared starting point` + } +} + +function featureSamples(name: string): Sample[] { + switch (name) { + case 'TopBar': + return [ + { + label: 'SiteLogo identity', + template: '', + }, + { + label: 'ClassicLogo identity', + template: '', + }, + { + label: 'Search enabled for this instance', + template: '', + }, + { + label: 'Account access and avatar', + template: ``, + }, + ] + case 'SignIn': + return [ + { + label: 'Signed out, sign-up disabled', + template: + '', + }, + { + label: 'Signed out, sign-up enabled', + template: + '', + }, + { + label: 'Signed in, default account icon', + template: '', + }, + { + label: 'Signed in, custom avatar', + template: ``, + }, + { + label: 'Custom icons and avatar slot', + template: + 'Custom account destination', + }, + { + label: 'Authentication disabled', + template: + '

With enabled false, no account control is rendered.

', + }, + ] + case 'PageToc': + return [ + { + label: 'Nested outline', + template: templateFor(name, 'accent', 'surface', 'stateless', 0), + }, + { + label: 'Flat outline and custom title', + template: ``, + }, + { + label: 'Empty outline', + template: '', + }, + ] + case 'NavMenu': + return [ + { + label: 'Active child and open ancestor', + template: templateFor(name, 'accent', 'surface', 'stateless', 0), + }, + { + label: 'Inactive, closed group', + template: ``, + }, + { + label: 'Leaf links and icons', + template: ``, + }, + { + label: 'Search and account configuration', + template: ``, + }, + ] + default: + return [] + } +} + +export interface SiteAppearanceGallery { + component: RefOrValue + axis: RefOrValue<'tone' | 'variant' | 'mode' | 'features'> +} + +export function defineSiteAppearanceGallery(site: SiteConfig) { + return defineComponent( + html``, + { + props: ['component', 'axis'], + context: (head) => ({ + ...head.props, + title: `${unref(head.props.component)} ${unref(head.props.axis)} examples`, + previewHref: withBasePath( + site.basePath, + `/components/site/${slugOf(unref(head.props.component))}/guide-${unref(head.props.axis)}/`, + ), + }), + }, + ) +} + +function sourceFor(title: string, body: string, showToc = false) { + return `---\ntemplate: preview\nindex: false\ntitle: ${title}\nlayout:\n showToc: ${showToc}\n---\n\n${body}` +} + +export function sitePreviewPages(): GeneratedPage[] { + const pages: GeneratedPage[] = [] + for (const name of components) { + const axes = + name === 'SiteLogo' || name === 'NavList' + ? ['tone'] + : ['tone', 'variant', ...(modes.has(name) ? ['mode'] : [])] + if (featureSamples(name).length) axes.push('features') + for (const axis of axes) { + const values = + axis === 'tone' + ? SEMANTIC_TONES + : axis === 'variant' + ? variants + : ['stateless', 'stateful'] + const samples: Sample[] = + axis === 'features' + ? featureSamples(name) + : values.map((value, index) => ({ + label: value, + template: templateFor( + name, + axis === 'tone' ? value : 'accent', + axis === 'variant' + ? value + : axis === 'mode' + ? 'outlineFill' + : 'surface', + axis === 'mode' ? value : 'stateless', + index, + ), + })) + const root = `components/site/${slugOf(name)}/guide-${axis}` + const cards = samples + .map((sample, index) => { + const template = sample.template + // TopBar owns a document-level navigation toggle ID. + const body = + name === 'TopBar' + ? `` + : template + if (name === 'TopBar') + pages.push({ + path: `${root}/sample-${index}.mdx`, + source: sourceFor( + sample.label, + `
${template}
`, + ), + }) + return `
${escapeAttribute(sample.label)}${body}
` + }) + .join('\n') + const targets = + name === 'PageToc' + ? '\n\n## Introduction\n\nOutline links have real targets.\n\n### Details\n\nSupporting content.' + : '' + pages.push({ + path: `${root}.mdx`, + source: sourceFor( + `${name} ${axis} examples`, + `
${cards}
${targets}`, + name === 'PageToc', + ), + }) + } + } + return pages +} diff --git a/frontend/purestack.studio/components/forms/multi-auto-complete-input/playground.ts b/frontend/purestack.studio/components/forms/multi-auto-complete-input/playground.ts index 5a7750c2..1106480b 100644 --- a/frontend/purestack.studio/components/forms/multi-auto-complete-input/playground.ts +++ b/frontend/purestack.studio/components/forms/multi-auto-complete-input/playground.ts @@ -149,11 +149,13 @@ const component = defineComponent( context: createMultiAutoCompleteInputExample, }, ) -const tagSuggestion = defineComponent<{ +export interface TagSuggestion { option: RefOrValue active?: RefOrValue query?: RefOrValue -}>( +} + +const tagSuggestion = defineComponent( html`{{ option.label }}{{ option.value }} · {{ active ? 'Active suggestion' : 'Available suggestion' }}{{ query ? ' · query: ' + query : '' }}`, { props: ['option', 'active', 'query'], diff --git a/frontend/purestack.studio/components/runtime/regor-app/playground.ts b/frontend/purestack.studio/components/runtime/regor-app/playground.ts index ddbb46c4..e1fe6530 100644 --- a/frontend/purestack.studio/components/runtime/regor-app/playground.ts +++ b/frontend/purestack.studio/components/runtime/regor-app/playground.ts @@ -5,7 +5,29 @@ import { defineFormInputField, definePanelComponents, } from '@purestack/ts-components' -import { batch, computed, createApp, defineComponent, html, ref } from 'regor' +import { + batch, + type ComputedRef, + computed, + createApp, + defineComponent, + html, + type Ref, + ref, +} from 'regor' + +export interface ReviewCounter { + prefix: string + title: string + completed: Ref + goal: Ref + note: Ref + locked: Ref + target: ComputedRef + complete: () => void + undo: () => void + reset: () => void +} const reviewTemplate = html` @@ -31,7 +53,7 @@ for (const mount of document.querySelectorAll( createApp( { components: { - ReviewCounter: defineComponent(reviewTemplate, { + ReviewCounter: defineComponent(reviewTemplate, { context: () => { const completed = ref(0) const goal = ref('5') diff --git a/frontend/purestack.studio/components/site/consent/consent.mdx b/frontend/purestack.studio/components/site/consent/consent.mdx index 287b118a..222fc789 100644 --- a/frontend/purestack.studio/components/site/consent/consent.mdx +++ b/frontend/purestack.studio/components/site/consent/consent.mdx @@ -17,7 +17,7 @@ nav: ## Make and revise a choice -Accept, reject or choose optional categories, then reopen settings. Reset clears only the isolated example’s saved choice. No tracking services are configured. +This preview uses the Studio's real consent settings and shares its saved privacy choice. Open settings to review the configured categories. @@ -26,13 +26,8 @@ Accept, reject or choose optional categories, then reopen settings. Reset clears - -```html - -``` - - - + + @@ -62,7 +57,7 @@ Compare stateless and stateful outlineFill treatments. Hover the samples; a stat ## Every step of the preference flow -Use the isolated working example to accept all, reject optional categories, manage individual categories, save, close, reopen, and reset. Its storage key is separate from this site’s own choice. +Use the working example to open, save, close, and reopen the Studio's real privacy settings. It shares the site's categories, services, and storage key.
diff --git a/frontend/purestack.studio/components/site/consent/preview.mdx b/frontend/purestack.studio/components/site/consent/preview.mdx new file mode 100644 index 00000000..8a202d2b --- /dev/null +++ b/frontend/purestack.studio/components/site/consent/preview.mdx @@ -0,0 +1,14 @@ +--- +template: preview +index: false +title: consent preview +--- + + +
+ +Manage privacy settings diff --git a/frontend/purestack.studio/components/site/consent/preview.ts b/frontend/purestack.studio/components/site/consent/preview.ts deleted file mode 100644 index 7fe9e136..00000000 --- a/frontend/purestack.studio/components/site/consent/preview.ts +++ /dev/null @@ -1,140 +0,0 @@ -import fs from 'node:fs/promises' -import path from 'node:path' -import type { SiteConfig, TsSsgContext } from '@purestack/ts-common' -import { defineComponents } from '@purestack/ts-components' -import { - buildConsentScript, - buildThemeSwitchScript, -} from '@purestack/ts-page-scripts' -import { renderApp } from '@purestack/ts-render' -import { getSvgIcon } from '@purestack/ts-svg-icons' -import { withBasePath } from '@purestack/ts-util' -import { defineComponent, html } from 'regor' - -export interface ConsentPreview { - previewHref: string -} - -const consentPreviewTemplate = html`` -const exampleTemplate = html` -
- - - Reset this example -` - -async function createConsentPreviewDocument(site: SiteConfig): Promise { - const context: TsSsgContext = { - site: { ...site }, - pageInfo: { - relPath: 'components/site/consent/consent.mdx', - urlPath: '/components/site/consent/', - frontmatter: { - template: 'doc', - hidden: false, - draft: false, - nav: { hidden: false }, - layout: { - showNav: false, - showToc: false, - showFooter: false, - fullWidth: false, - navMode: 'sidebar', - tocCollapsed: false, - }, - }, - }, - theme: site.style.theme, - basePath: site.basePath, - locales: site.i18n.locales, - defaultLocale: site.i18n.defaultLocale, - resolveLocaleHref: () => undefined, - resolvePublicHref: (href) => withBasePath(site.basePath, href), - recordScriptEntrypoint: () => {}, - recordRuntimeEmbed: () => {}, - } - context.site.consent = { - ...context.site.consent, - enabled: true, - storageKey: 'purestack-docs-consent-example', - policyVersion: 'example-1', - bannerTitle: 'Example privacy choices', - bannerDescription: 'This isolated example has no tracking services.', - privacyPolicyUrl: '/components/site/consent/', - privacyPolicyLabel: 'Read the consent guide', - categories: [ - { - id: 'necessary', - label: 'Necessary', - required: true, - description: 'Required for this example’s saved choice.', - }, - { - id: 'preferences', - label: 'Preferences', - description: 'Illustrative optional interface preferences.', - }, - { - id: 'analytics', - label: 'Analytics', - description: 'Illustrative optional category; no service is loaded.', - }, - { - id: 'marketing', - label: 'Marketing', - description: 'Illustrative optional category; no service is loaded.', - }, - ], - services: [], - } - const body = await renderApp(exampleTemplate, { - components: defineComponents(getSvgIcon), - context, - }) - const scripts = - buildThemeSwitchScript(['light', 'dark']) + - buildConsentScript(context.site.consent) - const documentHtml = `
${body}
` - return documentHtml -} - -export function defineConsentPreviewComponent(site: SiteConfig) { - return defineComponent(consentPreviewTemplate, { - context: () => ({ - previewHref: withBasePath( - site.basePath, - '/components/site/consent/preview.html', - ), - }), - }) -} - -export async function writeConsentPreview(site: SiteConfig) { - const output = path.join( - site.outDir, - 'components', - 'site', - 'consent', - 'preview.html', - ) - const documentHtml = await createConsentPreviewDocument(site) - await fs.mkdir(path.dirname(output), { recursive: true }) - await fs.writeFile(output, documentHtml, 'utf8') -} diff --git a/frontend/purestack.studio/components/site/nav-menu/nav-menu.mdx b/frontend/purestack.studio/components/site/nav-menu/nav-menu.mdx index 95da05a6..a5bed46e 100644 --- a/frontend/purestack.studio/components/site/nav-menu/nav-menu.mdx +++ b/frontend/purestack.studio/components/site/nav-menu/nav-menu.mdx @@ -85,7 +85,7 @@ In a client-side app, pass a shallow `sref` for `items` and a `ref` for `current ## Docked in the doc layout -This preview renders the menu exactly as the SSG does: from the site navigation, in its own document with the standard runtime. The current page opens its ancestor group. Expand Layout to inspect another branch; links open the real guides within the preview. +This ordinary page uses the standard documentation template, which renders the site's navigation with its configured appearance and runtime. The narrow iframe uses the mobile layout: open the menu with the header's navigation toggle. Open the full page in a wide window to try desktop sidebar collapse, restore, and resizing. Links open the real guides within the preview. @@ -94,16 +94,13 @@ This preview renders the menu exactly as the SSG does: from the site navigation,
- -```html - -``` - - - + + +Open the full-page layout preview + ## All ten semantic tones All supported values are visible together on the actual component, in an isolated document. @@ -169,6 +166,9 @@ Use [NavList](/components/site/nav-list/) when you already have prepared row sta variantMode signInAvatarSrc signInAvatarAlt + search + signInEnabled + signInSignedIn @@ -199,6 +199,18 @@ Use [NavList](/components/site/nav-list/) when you already have prepared row sta

Avatar alternative text forwarded to the account control.

 + +

Overrides search visibility for this instance.

+ + + +

Overrides account control visibility for this instance.

+ + + +

Forwards an explicit signed-in presentation to the account control.

+ + ### Composition
diff --git a/frontend/purestack.studio/components/site/nav-menu/preview.mdx b/frontend/purestack.studio/components/site/nav-menu/preview.mdx new file mode 100644 index 00000000..18223091 --- /dev/null +++ b/frontend/purestack.studio/components/site/nav-menu/preview.mdx @@ -0,0 +1,15 @@ +--- +template: doc +index: false +title: Docked navigation preview +layout: + showNav: true + showToc: false + showFooter: false +--- + +# Docked navigation + +The standard documentation template renders the site's navigation in its sidebar, with the configured appearance and navigation runtime. + +On a wide screen, collapse, restore, and resize the sidebar. In this narrow preview, use the header's navigation toggle to open the mobile panel. Expand a group or follow a link to explore the documentation. diff --git a/frontend/purestack.studio/components/site/nav-menu/preview.ts b/frontend/purestack.studio/components/site/nav-menu/preview.ts deleted file mode 100644 index ac922835..00000000 --- a/frontend/purestack.studio/components/site/nav-menu/preview.ts +++ /dev/null @@ -1,116 +0,0 @@ -import fs from 'node:fs/promises' -import path from 'node:path' -import type { SiteConfig, TsSsgContext } from '@purestack/ts-common' -import { defineComponents } from '@purestack/ts-components' -import { - buildMenuRuntimeScript, - buildNavMenuScript, - buildThemeSwitchScript, -} from '@purestack/ts-page-scripts' -import { renderApp } from '@purestack/ts-render' -import { getSvgIcon } from '@purestack/ts-svg-icons' -import { withBasePath } from '@purestack/ts-util' -import { defineComponent, html } from 'regor' - -export interface NavMenuPreview { - previewHref: string -} - -const navMenuPreviewTemplate = html`` -const exampleTemplate = html`` - -async function createNavMenuPreviewDocument(site: SiteConfig): Promise { - const context: TsSsgContext = { - site: { ...site }, - pageInfo: { - relPath: 'components/site/nav-menu/nav-menu.mdx', - urlPath: '/components/site/nav-menu/', - frontmatter: { - template: 'doc', - hidden: false, - draft: false, - nav: { hidden: false }, - layout: { - showNav: false, - showToc: false, - showFooter: false, - fullWidth: false, - navMode: 'sidebar', - tocCollapsed: false, - }, - }, - }, - theme: site.style.theme, - basePath: site.basePath, - locales: site.i18n.locales, - defaultLocale: site.i18n.defaultLocale, - resolveLocaleHref: () => undefined, - resolvePublicHref: (href) => withBasePath(site.basePath, href), - recordScriptEntrypoint: () => {}, - recordRuntimeEmbed: () => {}, - } - context.site.pagefind = { ...context.site.pagefind, enabled: false } - context.site.auth = { ...context.site.auth, enabled: false } - context.pageInfo = { - ...context.pageInfo, - urlPath: '/components/site/nav-menu/', - } - context.navigation = { - root: '/components/', - items: [ - { - title: 'Navigation', - children: [ - { title: 'NavMenu', url: '/components/site/nav-menu/' }, - { title: 'NavList', url: '/components/site/nav-list/' }, - ], - }, - { - title: 'Layout', - children: [ - { title: 'Flex', url: '/components/layout/flex/' }, - { title: 'Grid', url: '/components/layout/grid/' }, - ], - }, - ], - } - const body = await renderApp(exampleTemplate, { - components: defineComponents(getSvgIcon), - context, - }) - const scripts = - buildThemeSwitchScript(['light', 'dark']) + - buildNavMenuScript() + - buildMenuRuntimeScript() - const documentHtml = `
${body}
` - return documentHtml -} - -export function defineNavMenuPreviewComponent(site: SiteConfig) { - return defineComponent(navMenuPreviewTemplate, { - context: () => ({ - previewHref: withBasePath( - site.basePath, - '/components/site/nav-menu/preview.html', - ), - }), - }) -} - -export async function writeNavMenuPreview(site: SiteConfig) { - const output = path.join( - site.outDir, - 'components', - 'site', - 'nav-menu', - 'preview.html', - ) - const documentHtml = await createNavMenuPreviewDocument(site) - await fs.mkdir(path.dirname(output), { recursive: true }) - await fs.writeFile(output, documentHtml, 'utf8') -} diff --git a/frontend/purestack.studio/components/site/page-toc/page-toc.mdx b/frontend/purestack.studio/components/site/page-toc/page-toc.mdx index 5c636c74..938e6e28 100644 --- a/frontend/purestack.studio/components/site/page-toc/page-toc.mdx +++ b/frontend/purestack.studio/components/site/page-toc/page-toc.mdx @@ -26,13 +26,8 @@ The example uses a small outline in an isolated document. Each link resolves to - -```html - -``` - - - + + @@ -106,14 +101,14 @@ The default doc template already renders the page TOC; do not add a second copy
- +

PageOutlineItem[] with id, title, optional depth and children. Links are built as #id.

 @@ -136,7 +131,7 @@ The default doc template already renders the page TOC; do not add a second copy ### Composition
-

No slots. Register definePageTocComponents with BtnLink and Icon. SSG context supplies the outline when items is omitted; the standard runtime handles active-section and panel behavior.

+

No slots. Register definePageTocComponents with BtnLink and Icon. SSG context supplies the outline when outline is omitted; the standard runtime handles active-section and panel behavior.

## Related components diff --git a/frontend/purestack.studio/components/site/page-toc/preview.mdx b/frontend/purestack.studio/components/site/page-toc/preview.mdx new file mode 100644 index 00000000..31b7fa38 --- /dev/null +++ b/frontend/purestack.studio/components/site/page-toc/preview.mdx @@ -0,0 +1,19 @@ +--- +template: preview +index: false +title: page-toc preview +layout: + showToc: true +--- + + + +## Introduction + +A table of contents points to real section IDs. + +## Details + +### Contract + +Keep headings descriptive and ordered. diff --git a/frontend/purestack.studio/components/site/page-toc/preview.ts b/frontend/purestack.studio/components/site/page-toc/preview.ts deleted file mode 100644 index 5a9c6d45..00000000 --- a/frontend/purestack.studio/components/site/page-toc/preview.ts +++ /dev/null @@ -1,106 +0,0 @@ -import fs from 'node:fs/promises' -import path from 'node:path' -import type { SiteConfig, TsSsgContext } from '@purestack/ts-common' -import { defineComponents } from '@purestack/ts-components' -import { - buildPageTocScript, - buildThemeSwitchScript, -} from '@purestack/ts-page-scripts' -import { renderApp } from '@purestack/ts-render' -import { getSvgIcon } from '@purestack/ts-svg-icons' -import { withBasePath } from '@purestack/ts-util' -import { defineComponent, html } from 'regor' - -export interface PageTocPreview { - previewHref: string -} - -const pageTocPreviewTemplate = html`` -const exampleTemplate = html` -
-

Introduction

-

A table of contents points to real section IDs.

-
-
-

Details

-

Contract

-

Keep headings descriptive and ordered.

-
` - -async function createPageTocPreviewDocument(site: SiteConfig): Promise { - const context: TsSsgContext = { - site: { ...site }, - pageInfo: { - relPath: 'components/site/page-toc/page-toc.mdx', - urlPath: '/components/site/page-toc/', - frontmatter: { - template: 'doc', - hidden: false, - draft: false, - nav: { hidden: false }, - layout: { - showNav: false, - showToc: false, - showFooter: false, - fullWidth: false, - navMode: 'sidebar', - tocCollapsed: false, - }, - }, - }, - theme: site.style.theme, - basePath: site.basePath, - locales: site.i18n.locales, - defaultLocale: site.i18n.defaultLocale, - resolveLocaleHref: () => undefined, - resolvePublicHref: (href) => withBasePath(site.basePath, href), - recordScriptEntrypoint: () => {}, - recordRuntimeEmbed: () => {}, - } - context.outline = [ - { id: 'preview-introduction', title: 'Introduction', depth: 2 }, - { - id: 'preview-details', - title: 'Details', - depth: 2, - children: [{ id: 'preview-contract', title: 'Contract', depth: 3 }], - }, - ] - const body = await renderApp(exampleTemplate, { - components: defineComponents(getSvgIcon), - context, - }) - const scripts = - buildThemeSwitchScript(['light', 'dark']) + buildPageTocScript() - const documentHtml = `
${body}
` - return documentHtml -} - -export function definePageTocPreviewComponent(site: SiteConfig) { - return defineComponent(pageTocPreviewTemplate, { - context: () => ({ - previewHref: withBasePath( - site.basePath, - '/components/site/page-toc/preview.html', - ), - }), - }) -} - -export async function writePageTocPreview(site: SiteConfig) { - const output = path.join( - site.outDir, - 'components', - 'site', - 'page-toc', - 'preview.html', - ) - const documentHtml = await createPageTocPreviewDocument(site) - await fs.mkdir(path.dirname(output), { recursive: true }) - await fs.writeFile(output, documentHtml, 'utf8') -} diff --git a/frontend/purestack.studio/components/site/sign-in/preview.mdx b/frontend/purestack.studio/components/site/sign-in/preview.mdx new file mode 100644 index 00000000..f754c634 --- /dev/null +++ b/frontend/purestack.studio/components/site/sign-in/preview.mdx @@ -0,0 +1,25 @@ +--- +template: preview +index: false +title: sign-in preview +--- + + + Example workspace + + + Component library + + Workspace branding + + + + +

+ Open the account menu. These custom destinations are documentation links; this + preview does not sign you in. +

diff --git a/frontend/purestack.studio/components/site/sign-in/preview.ts b/frontend/purestack.studio/components/site/sign-in/preview.ts deleted file mode 100644 index 07e2ec00..00000000 --- a/frontend/purestack.studio/components/site/sign-in/preview.ts +++ /dev/null @@ -1,107 +0,0 @@ -import fs from 'node:fs/promises' -import path from 'node:path' -import type { SiteConfig, TsSsgContext } from '@purestack/ts-common' -import { defineComponents } from '@purestack/ts-components' -import { - buildMenuRuntimeScript, - buildThemeSwitchScript, -} from '@purestack/ts-page-scripts' -import { renderApp } from '@purestack/ts-render' -import { getSvgIcon } from '@purestack/ts-svg-icons' -import { withBasePath } from '@purestack/ts-util' -import { defineComponent, html } from 'regor' - -export interface SignInPreview { - previewHref: string -} - -const signInPreviewTemplate = html`` -const exampleTemplate = html` - Example workspace - - - Component library - - Workspace branding - - - - -

- Open the account menu. These custom destinations are documentation links; this - preview does not sign you in. -

` - -async function createSignInPreviewDocument(site: SiteConfig): Promise { - const context: TsSsgContext = { - site: { ...site }, - pageInfo: { - relPath: 'components/site/sign-in/sign-in.mdx', - urlPath: '/components/site/sign-in/', - frontmatter: { - template: 'doc', - hidden: false, - draft: false, - nav: { hidden: false }, - layout: { - showNav: false, - showToc: false, - showFooter: false, - fullWidth: false, - navMode: 'sidebar', - tocCollapsed: false, - }, - }, - }, - theme: site.style.theme, - basePath: site.basePath, - locales: site.i18n.locales, - defaultLocale: site.i18n.defaultLocale, - resolveLocaleHref: () => undefined, - resolvePublicHref: (href) => withBasePath(site.basePath, href), - recordScriptEntrypoint: () => {}, - recordRuntimeEmbed: () => {}, - } - context.site.auth = { ...context.site.auth, enabled: true, signUp: false } - const body = await renderApp(exampleTemplate, { - components: defineComponents(getSvgIcon), - context, - }) - const scripts = - buildThemeSwitchScript(['light', 'dark']) + buildMenuRuntimeScript() - const documentHtml = `
${body}
` - return documentHtml -} - -export function defineSignInPreviewComponent(site: SiteConfig) { - return defineComponent(signInPreviewTemplate, { - context: () => ({ - previewHref: withBasePath( - site.basePath, - '/components/site/sign-in/preview.html', - ), - }), - }) -} - -export async function writeSignInPreview(site: SiteConfig) { - const output = path.join( - site.outDir, - 'components', - 'site', - 'sign-in', - 'preview.html', - ) - const documentHtml = await createSignInPreviewDocument(site) - await fs.mkdir(path.dirname(output), { recursive: true }) - await fs.writeFile(output, documentHtml, 'utf8') -} diff --git a/frontend/purestack.studio/components/site/sign-in/sign-in.mdx b/frontend/purestack.studio/components/site/sign-in/sign-in.mdx index 319a2e5b..b5e463b7 100644 --- a/frontend/purestack.studio/components/site/sign-in/sign-in.mdx +++ b/frontend/purestack.studio/components/site/sign-in/sign-in.mdx @@ -26,13 +26,8 @@ The isolated preview enables the account component locally and uses working docu - -```html - -``` - - - + + @@ -68,7 +63,7 @@ Compare stateless and stateful outlineFill treatments. Hover the samples; a stat ## Account state and content slots -The comparisons show signed-out menus with and without sign-up, signed-in menus with a default icon or image avatar, custom icons and an avatar slot, and auth disabled. These are explicit document states for presentation; they do not create a session. The original working preview has real documentation links in its default slot. +The comparisons show signed-out menus with and without sign-up, signed-in menus with a default icon or image avatar, custom icons and an avatar slot, and auth disabled. These are explicit component states for presentation; they do not create a session. The original working preview has real documentation links in its default slot. The label prop supplies hidden trigger text; the trigger currently retains the fixed accessible label Account menu. avatarAlt applies to the image. The avatar slot takes precedence over the avatar image and accountIcon. @@ -82,7 +77,7 @@ The label prop supplies hidden trigger text; the trigger currently retains the f ## Behavior and accessibility -The component renders only when site.auth.enabled is true. It does not authenticate users itself. The standard auth-state hint controls signed-in versus signed-out presentation; the server remains responsible for session authorization. The native summary opens with Enter or Space, and the menu runtime handles Escape and outside clicks. +The component defaults to site.auth.enabled; the enabled prop overrides it for an instance. The signUp prop overrides site.auth.signUp, and signedIn selects a static presentation without creating a session. It does not authenticate users itself. The standard auth-state hint controls signed-in versus signed-out presentation; the server remains responsible for session authorization. The native summary opens with Enter or Space, and the menu runtime handles Escape and outside clicks. ## API reference @@ -100,6 +95,9 @@ The component renders only when site.auth.enabled is true. It does not authentic tone variant variantMode + enabled + signUp + signedIn @@ -134,6 +132,18 @@ The component renders only when site.auth.enabled is true. It does not authentic

Use stateless for content surfaces; stateful enables the treatment’s hover, focus and active styles. It does not add interaction handlers.

 + +

Overrides authentication UI visibility for this instance.

+ + + +

Overrides visibility of the default sign-up action.

+ + + +

Selects signed-in or signed-out presentation for this instance. Omit it to follow the runtime auth hint. This prop does not authenticate a session.

+ + ### Composition
diff --git a/frontend/purestack.studio/components/site/top-bar/preview.mdx b/frontend/purestack.studio/components/site/top-bar/preview.mdx new file mode 100644 index 00000000..14bebead --- /dev/null +++ b/frontend/purestack.studio/components/site/top-bar/preview.mdx @@ -0,0 +1,11 @@ +--- +template: preview +index: false +title: top-bar preview +--- + + +

+ A complete header in its own document. The logo links home and the theme control + changes this preview. +

diff --git a/frontend/purestack.studio/components/site/top-bar/preview.ts b/frontend/purestack.studio/components/site/top-bar/preview.ts deleted file mode 100644 index 729ac081..00000000 --- a/frontend/purestack.studio/components/site/top-bar/preview.ts +++ /dev/null @@ -1,93 +0,0 @@ -import fs from 'node:fs/promises' -import path from 'node:path' -import type { SiteConfig, TsSsgContext } from '@purestack/ts-common' -import { defineComponents } from '@purestack/ts-components' -import { - buildMenuRuntimeScript, - buildThemeSwitchScript, -} from '@purestack/ts-page-scripts' -import { renderApp } from '@purestack/ts-render' -import { getSvgIcon } from '@purestack/ts-svg-icons' -import { withBasePath } from '@purestack/ts-util' -import { defineComponent, html } from 'regor' - -export interface TopBarPreview { - previewHref: string -} - -const topBarPreviewTemplate = html`` -const exampleTemplate = html` -

- A complete header in its own document. The logo links home and the theme control - changes this preview. -

` - -async function createTopBarPreviewDocument(site: SiteConfig): Promise { - const context: TsSsgContext = { - site: { ...site }, - pageInfo: { - relPath: 'components/site/top-bar/top-bar.mdx', - urlPath: '/components/site/top-bar/', - frontmatter: { - template: 'doc', - hidden: false, - draft: false, - nav: { hidden: false }, - layout: { - showNav: false, - showToc: false, - showFooter: false, - fullWidth: false, - navMode: 'sidebar', - tocCollapsed: false, - }, - }, - }, - theme: site.style.theme, - basePath: site.basePath, - locales: site.i18n.locales, - defaultLocale: site.i18n.defaultLocale, - resolveLocaleHref: () => undefined, - resolvePublicHref: (href) => withBasePath(site.basePath, href), - recordScriptEntrypoint: () => {}, - recordRuntimeEmbed: () => {}, - } - context.site.pagefind = { ...context.site.pagefind, enabled: false } - const body = await renderApp(exampleTemplate, { - components: defineComponents(getSvgIcon), - context, - }) - const scripts = - buildThemeSwitchScript(['light', 'dark']) + buildMenuRuntimeScript() - const documentHtml = `
${body}
` - return documentHtml -} - -export function defineTopBarPreviewComponent(site: SiteConfig) { - return defineComponent(topBarPreviewTemplate, { - context: () => ({ - previewHref: withBasePath( - site.basePath, - '/components/site/top-bar/preview.html', - ), - }), - }) -} - -export async function writeTopBarPreview(site: SiteConfig) { - const output = path.join( - site.outDir, - 'components', - 'site', - 'top-bar', - 'preview.html', - ) - const documentHtml = await createTopBarPreviewDocument(site) - await fs.mkdir(path.dirname(output), { recursive: true }) - await fs.writeFile(output, documentHtml, 'utf8') -} diff --git a/frontend/purestack.studio/components/site/top-bar/top-bar.mdx b/frontend/purestack.studio/components/site/top-bar/top-bar.mdx index 03e06672..da923258 100644 --- a/frontend/purestack.studio/components/site/top-bar/top-bar.mdx +++ b/frontend/purestack.studio/components/site/top-bar/top-bar.mdx @@ -33,13 +33,8 @@ This preview reads the same logo configuration as the site. Search is disabled i - -```html - -``` - - - + + @@ -92,7 +87,7 @@ All supported values are visible together on the actual component, in an isolate ## Configuration controls the header -The comparisons above show both logo components, site-configured search, and explicit account access with an avatar. SearchBox is included when site.pagefind.enabled is true; searchEnabled is accepted but is overwritten by that site setting. signInEnabled explicitly requests the account control, and site.auth.enabled must also be true. +The comparisons above show both logo components, explicit search visibility, and account access with an avatar. The search prop overrides site.pagefind.enabled, and signInEnabled overrides site.auth.enabled for this header. The navigation toggle targets the doc layout’s fixed ID. Each header sample uses its own document. The working preview’s theme button switches that preview; appearance samples follow the guide’s theme. @@ -127,7 +122,7 @@ Both the top position and available scrolling height use the same setting. Deskt Custom documentation templates can set `--ps-doc-layout-sidebar-top` and `--ps-doc-layout-sidebar-top-mobile` on a shared ancestor of their sidebars. The default doc template sets both from site configuration automatically. -TopBar renders a fixed doc-nav-toggle ID and should appear once per document. Its mobile navigation toggle works with the standard doc layout. Logo content comes from site.logo. Search visibility currently follows site.pagefind.enabled, even when a searchEnabled prop is supplied. +TopBar renders a fixed doc-nav-toggle ID and should appear once per document. Its mobile navigation toggle works with the standard doc layout. Logo content comes from site.logo. Search visibility defaults to site.pagefind.enabled; the search prop overrides it. ## API reference @@ -147,7 +142,8 @@ TopBar renders a fixed doc-nav-toggle ID and should appear once per document. It signInAvatarSrc signInAvatarAlt signInEnabled - searchEnabled + search + signInSignedIn

- Shows the SignIn slot in the header; site.auth.enabled must also be true for - the account component to render. + Overrides site.auth.enabled for the account control in this header.

- Registered prop currently resolved from site configuration. Configure - pagefind.enabled to control search visibility. + Overrides site.pagefind.enabled for this instance.

+ +

Forwards an explicit signed-in presentation to the account control.

+ + ### Composition
diff --git a/frontend/purestack.studio/guides/purestack-cli.mdx b/frontend/purestack.studio/guides/purestack-cli.mdx index eddf582b..d3e6bc5e 100644 --- a/frontend/purestack.studio/guides/purestack-cli.mdx +++ b/frontend/purestack.studio/guides/purestack-cli.mdx @@ -84,6 +84,8 @@ Routes follow filenames and folders: `guide/index.md` and `guide/guide.mdx` are alternative names for the same route; do not keep both. The build reports duplicate routes as an error. Page frontmatter supplies a page's title, description, template, navigation order, and layout choices. If a page omits `template`, PureStack uses the documentation template. +Set `index: false` in frontmatter for a preview or unlisted page. PureStack still builds it and resolves links to it, but excludes it from generated navigation, search, and the sitemap and adds a robots `noindex` tag. `hidden: true` only hides a page from navigation. + Files such as `assets/logo.png` are copied into the output folder with their relative paths intact. The root `siteConfig.json` and navigation files are inputs to the build, not public assets. You can place `_nav.json` in a folder for custom or hybrid navigation, and `header.mdx` or `footer.mdx` for shared page sections. The [Site configuration guide](/guides/site-config/) shows how to enable and order navigation. A Markdown or MDX file whose name, or a folder above it, starts with `_` is never a page; pages show it with [``](/guides/shared-content/). A `purestack.config.ts` beside `siteConfig.json` adds code of your own, such as a brand skin, components, templates, or generated pages, through [plugins](/guides/plugins/). Every command loads it when it is present; like other `.ts` files in the content folder, it is never copied to the output. diff --git a/frontend/studioPlugin.ts b/frontend/studioPlugin.ts index 24da2fda..c34ad3eb 100644 --- a/frontend/studioPlugin.ts +++ b/frontend/studioPlugin.ts @@ -5,12 +5,8 @@ import { card } from './demoStyle' import { registerApiReferenceStyles } from './docs/apiReferenceStyles' import { registerComponentGuideStyles } from './docs/componentGuide' import { defineDocumentationComponents } from './docs/docsComponents' -import { writeSiteGuidePreviews } from './docs/siteGuide' -import { writeConsentPreview } from './purestack.studio/components/site/consent/preview' -import { writeNavMenuPreview } from './purestack.studio/components/site/nav-menu/preview' -import { writePageTocPreview } from './purestack.studio/components/site/page-toc/preview' -import { writeSignInPreview } from './purestack.studio/components/site/sign-in/preview' -import { writeTopBarPreview } from './purestack.studio/components/site/top-bar/preview' +import { previewTemplate } from './docs/previewTemplate' +import { sitePreviewPages } from './docs/sitePreviews' import { studioSkin } from './theme/studioSkin' import { registerStudioStyles } from './theme/studioStyles' @@ -22,7 +18,9 @@ export const studioPlugin = definePlugin({ ...defineStudioComponents(), ...defineDocumentationComponents(config), }), + pages: () => sitePreviewPages(), templates: { + preview: previewTemplate, studio: ({ head, bodyHtml, headerHtml, footerHtml }) => { head.push(h('style').raw(card.toCSS())) return h('html') @@ -50,13 +48,5 @@ export const studioPlugin = definePlugin({ registerApiReferenceStyles() registerComponentGuideStyles() }, - async onContentDiscovered(context) { - await writeSiteGuidePreviews(context.config) - await writeConsentPreview(context.config) - await writeNavMenuPreview(context.config) - await writePageTocPreview(context.config) - await writeSignInPreview(context.config) - await writeTopBarPreview(context.config) - }, }, }) diff --git a/packages/ts-common/src/frontmatter-types.ts b/packages/ts-common/src/frontmatter-types.ts index 1e14ae4c..9b400bb8 100644 --- a/packages/ts-common/src/frontmatter-types.ts +++ b/packages/ts-common/src/frontmatter-types.ts @@ -70,6 +70,15 @@ export interface PageFrontmatter { */ draft: boolean + /** + * Keeps the page out of the site when set to `false`: out of generated + * navigation, the search index, and the sitemap, with a `noindex` robots + * meta tag. The page is still built, and links to it still work. + * + * Defaults to `true`. + */ + index: boolean + /** * Navigation-specific overrides for this page. */ diff --git a/packages/ts-components/src/standard/navMenu/navMenu.ts b/packages/ts-components/src/standard/navMenu/navMenu.ts index f60d6287..d4f54f2a 100644 --- a/packages/ts-components/src/standard/navMenu/navMenu.ts +++ b/packages/ts-components/src/standard/navMenu/navMenu.ts @@ -27,10 +27,14 @@ export interface NavMenu { tone?: RefOrValue variant?: RefOrValue variantMode?: RefOrValue + signInSignedIn?: RefOrValue signInAvatarSrc?: RefOrValue signInAvatarAlt?: RefOrValue classes?: ComputedRef - searchEnabled?: boolean + search?: RefOrValue + signInEnabled?: RefOrValue + resolvedSignInEnabled?: ComputedRef + searchEnabled?: ComputedRef navRoot?: string } @@ -102,8 +106,11 @@ const navMenuTemplate = html`