@ciderpress/ui 1.0.0-rc.11 → 1.0.0-rc.12

package/dist/theme/components/seo-head.tsx

@@ -0,0 +1,102 @@
+import { Head, useFrontmatter, useLocation, usePageData, useSite } from '@rspress/core/runtime'
+import { match } from 'massaman/match'
+import { isNil, isNotNil } from 'massaman/predicate'
+
+import type { SeoThemeConfig } from '../../seo-theme-config'
+import type { ResolvedSeoHeadData } from './seo-head-data'
+import { resolveSeoHeadData } from './seo-head-data'
+
+type SeoMetaEntry = readonly ['name' | 'property', string, string | undefined]
+type ResolvedSeoMetaEntry = readonly ['name' | 'property', string, string]
+
+/**
+ * Adds canonical, robots, Open Graph, and Twitter metadata on top of Rspress defaults.
+ *
+ * @returns Route-aware metadata for the current page, or `null` when SEO is not configured
+ */
+export default function SeoHead(): React.ReactElement | null {
+  const { site } = useSite()
+  const { page } = usePageData()
+  const { frontmatter } = useFrontmatter()
+  const { pathname } = useLocation()
+  const themeConfig = site.themeConfig as SeoThemeConfig
+  const siteSeo = themeConfig.seo
+  const seoBase = themeConfig.seoBase
+
+  if (isNil(siteSeo) || isNil(seoBase)) {
+    return null
+  }
+
+  const metadata = resolveSeoHeadData({
+    siteSeo,
+    base: seoBase,
+    siteDescription: site.description,
+    page,
+    pathname,
+    frontmatter,
+  })
+  const metaTags = resolveMetaTags(metadata)
+
+  return (
+    <Head>
+      {isNotNil(metadata.title) && <title>{metadata.title}</title>}
+      {isNotNil(metadata.canonical) && <link rel="canonical" href={metadata.canonical} />}
+      {metaTags.map(renderMetaTag)}
+    </Head>
+  )
+}
+
+/**
+ * Converts resolved SEO data into typed HTML meta-tag attributes.
+ *
+ * @private
+ */
+function resolveMetaTags(metadata: ResolvedSeoHeadData): readonly ResolvedSeoMetaEntry[] {
+  const entries: readonly SeoMetaEntry[] = [
+    ['name', 'description', metadata.description],
+    ['name', 'robots', metadata.robots],
+    ...match(metadata.openGraph)
+      .with(false, () => [])
+      .otherwise((openGraph): readonly SeoMetaEntry[] => [
+        ['property', 'og:url', openGraph.url],
+        ['property', 'og:title', openGraph.title],
+        ['property', 'og:description', openGraph.description],
+        ['property', 'og:type', openGraph.type],
+        ['property', 'og:site_name', openGraph.siteName],
+        ['property', 'og:locale', openGraph.locale],
+        ['property', 'og:image', openGraph.image],
+      ]),
+    ...match(metadata.twitter)
+      .with(false, () => [])
+      .otherwise((twitter): readonly SeoMetaEntry[] => [
+        ['name', 'twitter:card', twitter.card],
+        ['name', 'twitter:title', twitter.title],
+        ['name', 'twitter:description', twitter.description],
+        ['name', 'twitter:site', twitter.site],
+        ['name', 'twitter:creator', twitter.creator],
+        ['name', 'twitter:image', twitter.image],
+      ]),
+  ]
+  return entries.filter(isResolvedMetaEntry)
+}
+
+/**
+ * Narrows a meta entry after missing content is filtered out.
+ *
+ * @private
+ */
+function isResolvedMetaEntry(entry: SeoMetaEntry): entry is ResolvedSeoMetaEntry {
+  return isNotNil(entry[2])
+}
+
+/**
+ * Renders one typed meta-tag descriptor.
+ *
+ * @private
+ */
+function renderMetaTag([attribute, key, content]: ResolvedSeoMetaEntry): React.ReactElement {
+  return match(attribute)
+    .with('name', () => <meta key={key} name={key} content={content} />)
+    .with('property', () => <meta key={key} property={key} content={content} />)
+    .exhaustive()
+}

package/dist/theme/components/shared/IssueLinkIcon.tsx

@@ -0,0 +1,42 @@
+import type React from 'react'
+
+import type { IssueLinkProvider } from '../../../plugins/issue-links/remark-issue-links.ts'
+import { Icon } from './icon.tsx'
+
+const PROVIDER_ICONS = {
+  asana: 'logos:asana-icon',
+  bitbucket: 'devicon:bitbucket',
+  clickup: 'simple-icons:clickup',
+  confluence: 'devicon:confluence',
+  dash0: 'simple-icons:dash0',
+  datadog: 'logos:datadog',
+  figma: 'devicon:figma',
+  github: 'simple-icons:github',
+  gitlab: 'logos:gitlab-icon',
+  'google-docs': 'mdi:file-document',
+  'google-drive': 'logos:google-drive',
+  'google-sheets': 'mdi:google-spreadsheet',
+  jira: 'devicon:jira',
+  launchdarkly: 'logos:launchdarkly-icon',
+  linear: 'simple-icons:linear',
+  loom: 'logos:loom-icon',
+  notion: 'simple-icons:notion',
+  npm: 'logos:npm-icon',
+  postman: 'logos:postman-icon',
+  posthog: 'logos:posthog-icon',
+  pulumi: 'logos:pulumi-icon',
+  pagerduty: 'logos:pagerduty',
+  sentry: 'simple-icons:sentry',
+  slack: 'logos:slack-icon',
+  trello: 'logos:trello',
+  vercel: 'simple-icons:vercel',
+} as const satisfies Record<IssueLinkProvider, string>
+
+interface IssueLinkIconProps {
+  readonly provider: IssueLinkProvider
+}
+
+/** Render a URL badge's provider mark through the shared Iconify pipeline. */
+export default function IssueLinkIcon({ provider }: IssueLinkIconProps): React.ReactElement {
+  return <Icon aria-hidden="true" className="cp-issue-link__icon" icon={PROVIDER_ICONS[provider]} />
+}

package/dist/theme/components/shared/issue-link.css

@@ -0,0 +1,74 @@
+/** URL-derived resource badges with provider-specific icons. */
+
+.rp-doc a.rp-link.cp-issue-link {
+  display: inline-flex;
+  gap: 0.35em;
+  align-items: center;
+  padding: 0.14em 0.55em;
+  border: 1px solid var(--cp-c-border);
+  border-radius: var(--cp-radius-pill);
+  background: var(--cp-c-bg-soft);
+  background-image: none;
+  color: var(--cp-c-text-2);
+  font-size: 0.82em;
+  font-weight: 600;
+  line-height: 1.35;
+  text-decoration: none;
+  text-shadow: none;
+  vertical-align: 0.08em;
+  white-space: nowrap;
+}
+
+.rp-doc a.rp-link.cp-issue-link:hover {
+  border-color: var(--cp-c-text-3);
+  background: color-mix(in srgb, var(--cp-c-bg-soft) 82%, var(--cp-c-text-1));
+  background-image: none;
+  color: var(--cp-c-text-1);
+  opacity: 1;
+  text-decoration: none;
+  text-shadow: none;
+}
+
+.rp-doc a.rp-link.cp-issue-link[target='_blank']::after {
+  content: none;
+}
+
+.rp-doc a.rp-link.cp-issue-link:focus-visible {
+  outline: 2px solid var(--cp-c-brand-1);
+  outline-offset: 2px;
+}
+
+.cp-issue-link__icon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  flex: none;
+}
+
+.cp-issue-link__reference {
+  color: var(--cp-c-text-3);
+  font-size: 0.92em;
+  font-weight: 650;
+  font-variant-numeric: tabular-nums;
+}
+
+.cp-issue-link--github .cp-issue-link__icon,
+.cp-issue-link--notion .cp-issue-link__icon,
+.cp-issue-link--sentry .cp-issue-link__icon {
+  color: var(--cp-c-text-1);
+}
+
+.cp-issue-link--google-docs .cp-issue-link__icon {
+  color: #4285f4;
+}
+
+.cp-issue-link--google-sheets .cp-issue-link__icon {
+  color: #0f9d58;
+}
+
+html[data-cp-variant='dark'] .cp-issue-link--linear .cp-issue-link__icon,
+html[data-cp-variant='dark'] .cp-issue-link--launchdarkly .cp-issue-link__icon,
+html[data-cp-variant='dark'] .cp-issue-link--vercel .cp-issue-link__icon {
+  color: #fff;
+  fill: #fff;
+}

package/dist/theme/index.tsx

@@ -73,6 +73,7 @@ import './components/openapi/openapi.css'
 import './components/shared/accordion.css'
 import './components/shared/columns.css'
 import './components/shared/status-badge.css'
+import './components/shared/issue-link.css'
 import './components/shared/frame.css'
 import './components/shared/tooltip.css'
 import './components/shared/prompt.css'

package/dist/theme/lib/seo-url.ts

@@ -0,0 +1,28 @@
+/**
+ * Resolves the production root URL for a base-mounted documentation site.
+ *
+ * @param params - Production origin and resolved Rspress base path
+ * @returns Absolute URL for the deployed site root
+ */
+export function resolveSeoSiteUrl(params: {
+  readonly origin: string
+  readonly base: string
+}): string {
+  return new URL(params.base, params.origin).href
+}
+
+/**
+ * Resolves a basename-stripped router pathname against the deployed site root.
+ *
+ * @param params - Production origin, resolved Rspress base, and router pathname
+ * @returns Absolute production URL for the page
+ */
+export function resolveSeoPageUrl(params: {
+  readonly origin: string
+  readonly base: string
+  readonly pathname: string
+}): string {
+  const siteUrl = resolveSeoSiteUrl(params)
+  const relativePathname = params.pathname.replace(/^\/+/, '')
+  return new URL(relativePathname, siteUrl).href
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ciderpress/ui",
-  "version": "1.0.0-rc.11",
+  "version": "1.0.0-rc.12",
   "description": "Rspress plugin, theme components, and styles for ciderpress",
   "keywords": [
     "ciderpress",
@@ -57,6 +57,7 @@
     "@iconify-json/vscode-icons": "^1.2.65",
     "@iconify/react": "^6.0.2",
     "@mermaid-js/layout-elk": "^0.2.2",
+    "@rspress/plugin-sitemap": "^2.0.19",
     "clsx": "^2.1.1",
     "katex": "^0.17.0",
     "massaman": "^0.3.0",
@@ -65,13 +66,13 @@
     "react-aria-components": "^1.19.0",
     "ts-morph": "^28.0.0",
     "unist-util-visit": "^5.1.0",
-    "@ciderpress/config": "1.0.0-rc.8",
+    "@ciderpress/config": "1.0.0-rc.9",
     "@ciderpress/theme": "1.0.0-rc.5"
   },
   "devDependencies": {
     "@ladle/react": "^5.1.1",
     "@rslib/core": "0.23.1",
-    "@rspress/core": "^2.0.16",
+    "@rspress/core": "^2.0.19",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "esbuild": "^0.28.1",
@@ -86,7 +87,7 @@
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "@rspress/core": "^2.0.16",
+    "@rspress/core": "^2.0.19",
     "react": "^19.2.5",
     "react-dom": "^19.2.5"
   },

package/src/theme/components/seo-head-data.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, it } from 'vitest'
+
+import type { ResolveSeoHeadDataParams } from './seo-head-data'
+import { resolveSeoHeadData } from './seo-head-data'
+
+const baseParams: ResolveSeoHeadDataParams = {
+  siteSeo: { origin: 'https://docs.example.com' },
+  base: '/',
+  siteDescription: 'Site description',
+  page: { title: 'Authentication', description: 'Page description' },
+  pathname: '/guides/authentication',
+  frontmatter: {},
+}
+
+describe('resolveSeoHeadData()', () => {
+  it('should resolve route metadata from site and page defaults', () => {
+    expect(resolveSeoHeadData(baseParams)).toStrictEqual({
+      title: undefined,
+      description: undefined,
+      canonical: 'https://docs.example.com/guides/authentication',
+      robots: undefined,
+      openGraph: {
+        url: 'https://docs.example.com/guides/authentication',
+        title: 'Authentication',
+        description: 'Page description',
+        type: 'website',
+        siteName: undefined,
+        locale: undefined,
+        image: undefined,
+      },
+      twitter: {
+        card: 'summary_large_image',
+        title: 'Authentication',
+        description: 'Page description',
+        site: undefined,
+        creator: undefined,
+        image: undefined,
+      },
+    })
+  })
+
+  it('should preserve the deployment base in production page URLs', () => {
+    const result = resolveSeoHeadData({ ...baseParams, base: '/project/' })
+
+    expect(result.canonical).toBe('https://docs.example.com/project/guides/authentication')
+    expect(result.openGraph).toMatchObject({
+      url: 'https://docs.example.com/project/guides/authentication',
+    })
+  })
+
+  it('should apply site defaults and nested page overrides', () => {
+    const result = resolveSeoHeadData({
+      ...baseParams,
+      siteSeo: {
+        origin: 'https://docs.example.com',
+        titleTemplate: '%s | Acme',
+        socialImage: '/social/default.png',
+        openGraph: { siteName: 'Acme', locale: 'en_US' },
+        twitter: { card: 'summary', site: '@acme' },
+      },
+      frontmatter: {
+        seo: {
+          title: 'API Authentication',
+          description: 'Authenticate with Acme.',
+          socialImage: '/social/auth.png',
+          openGraph: { type: 'article', image: '/social/og.png' },
+          twitter: { creator: '@author', image: '/social/twitter.png' },
+        },
+      },
+    })
+
+    expect(result.title).toBe('API Authentication | Acme')
+    expect(result.description).toBe('Authenticate with Acme.')
+    expect(result.openGraph).toStrictEqual({
+      url: 'https://docs.example.com/guides/authentication',
+      title: 'API Authentication',
+      description: 'Authenticate with Acme.',
+      type: 'article',
+      siteName: 'Acme',
+      locale: 'en_US',
+      image: 'https://docs.example.com/social/og.png',
+    })
+    expect(result.twitter).toStrictEqual({
+      card: 'summary',
+      title: 'API Authentication',
+      description: 'Authenticate with Acme.',
+      site: '@acme',
+      creator: '@author',
+      image: 'https://docs.example.com/social/twitter.png',
+    })
+  })
+
+  it('should suppress only the canonical link when canonical is false', () => {
+    const result = resolveSeoHeadData({
+      ...baseParams,
+      frontmatter: { seo: { canonical: false } },
+    })
+
+    expect(result.canonical).toBeUndefined()
+    expect(result.openGraph).toMatchObject({
+      url: 'https://docs.example.com/guides/authentication',
+    })
+  })
+
+  it('should honor an absolute canonical override', () => {
+    const result = resolveSeoHeadData({
+      ...baseParams,
+      frontmatter: { seo: { canonical: 'https://canonical.example.com/auth' } },
+    })
+
+    expect(result.canonical).toBe('https://canonical.example.com/auth')
+  })
+
+  it('should disable provider metadata from site or page settings', () => {
+    const siteDisabled = resolveSeoHeadData({
+      ...baseParams,
+      siteSeo: { origin: 'https://docs.example.com', openGraph: false },
+    })
+    const pageDisabled = resolveSeoHeadData({
+      ...baseParams,
+      frontmatter: { seo: { twitter: false } },
+    })
+
+    expect(siteDisabled.openGraph).toBe(false)
+    expect(pageDisabled.twitter).toBe(false)
+  })
+
+  it('should merge page robots directives over site defaults', () => {
+    const result = resolveSeoHeadData({
+      ...baseParams,
+      siteSeo: {
+        origin: 'https://docs.example.com',
+        robots: { index: true, follow: false },
+      },
+      frontmatter: { seo: { robots: { index: false } } },
+    })
+
+    expect(result.robots).toBe('noindex, nofollow')
+  })
+
+  it('should ignore the entire page SEO block when raw frontmatter is invalid', () => {
+    const result = resolveSeoHeadData({
+      ...baseParams,
+      frontmatter: {
+        seo: {
+          title: 'Ignored title',
+          robots: { index: 'false' },
+        },
+      },
+    })
+
+    expect(result.title).toBeUndefined()
+    expect(result.robots).toBeUndefined()
+    expect(result.openGraph).toMatchObject({ title: 'Authentication' })
+  })
+
+  it('should ignore malformed raw social URLs and Twitter handles', () => {
+    const malformedImage = resolveSeoHeadData({
+      ...baseParams,
+      frontmatter: { seo: { socialImage: 'http://[' } },
+    })
+    const malformedHandle = resolveSeoHeadData({
+      ...baseParams,
+      frontmatter: { seo: { twitter: { creator: '@foo bar' } } },
+    })
+
+    expect(malformedImage.openGraph).toMatchObject({ image: undefined })
+    expect(malformedHandle.twitter).toMatchObject({ creator: undefined })
+  })
+
+  it('should fall back from provider images to the shared social image', () => {
+    const result = resolveSeoHeadData({
+      ...baseParams,
+      siteSeo: {
+        origin: 'https://docs.example.com',
+        socialImage: '/social/default.png',
+      },
+    })
+
+    expect(result.openGraph).toMatchObject({
+      image: 'https://docs.example.com/social/default.png',
+    })
+    expect(result.twitter).toMatchObject({
+      image: 'https://docs.example.com/social/default.png',
+    })
+  })
+
+  it('should emit an untemplated title when title templating is explicitly disabled', () => {
+    const result = resolveSeoHeadData({
+      ...baseParams,
+      siteSeo: { origin: 'https://docs.example.com', titleTemplate: false },
+    })
+
+    expect(result.title).toBe('Authentication')
+  })
+})