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

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

@@ -0,0 +1,490 @@
+import type { PageSeoConfig, RobotsConfig, SeoConfig } from '@ciderpress/config'
+import { isMatching, P } from 'massaman/match'
+import { isBoolean, isNil, isPlainObject, isString, isUndefined } from 'massaman/predicate'
+
+import { resolveSeoPageUrl } from '../lib/seo-url'
+
+const PAGE_SEO_KEYS = [
+  'title',
+  'description',
+  'canonical',
+  'socialImage',
+  'robots',
+  'openGraph',
+  'twitter',
+] as const
+const ROBOTS_KEYS = ['index', 'follow'] as const
+const OPEN_GRAPH_KEYS = ['title', 'description', 'type', 'image'] as const
+const TWITTER_KEYS = ['title', 'description', 'card', 'image', 'creator'] as const
+
+/**
+ * Inputs needed to resolve route-aware SEO metadata.
+ */
+export interface ResolveSeoHeadDataParams {
+  readonly siteSeo: SeoConfig
+  readonly base: string
+  readonly siteDescription: string
+  readonly page: {
+    readonly title: string
+    readonly description?: string
+  }
+  readonly pathname: string
+  readonly frontmatter: Readonly<Record<string, unknown>>
+}
+
+/**
+ * Fully resolved Open Graph metadata, or `false` when disabled.
+ */
+export interface ResolvedOpenGraphMetadata {
+  readonly url: string
+  readonly title: string
+  readonly description: string
+  readonly type: 'website' | 'article'
+  readonly siteName?: string
+  readonly locale?: string
+  readonly image?: string
+}
+
+/**
+ * Fully resolved Twitter card metadata, or `false` when disabled.
+ */
+export interface ResolvedTwitterMetadata {
+  readonly card: 'summary' | 'summary_large_image'
+  readonly title: string
+  readonly description: string
+  readonly site?: `@${string}`
+  readonly creator?: `@${string}`
+  readonly image?: string
+}
+
+/**
+ * Route-aware metadata consumed by the SEO head renderer.
+ */
+export interface ResolvedSeoHeadData {
+  readonly title?: string
+  readonly description?: string
+  readonly canonical?: string
+  readonly robots?: string
+  readonly openGraph: ResolvedOpenGraphMetadata | false
+  readonly twitter: ResolvedTwitterMetadata | false
+}
+
+/**
+ * Resolves validated site and page SEO inputs into render-ready metadata.
+ *
+ * Invalid Markdown `frontmatter.seo` values are ignored so unvalidated YAML
+ * cannot leak malformed values into the document head.
+ *
+ * @param params - Site defaults, page data, route, and raw frontmatter
+ * @returns Immutable metadata for the React head renderer
+ */
+export function resolveSeoHeadData(params: ResolveSeoHeadDataParams): ResolvedSeoHeadData {
+  const pageSeo = resolvePageSeo(params.frontmatter)
+  const title = pageSeo.title ?? params.page.title
+  const description = pageSeo.description ?? params.page.description ?? params.siteDescription
+  const socialImage = resolveSocialImage({
+    origin: params.siteSeo.origin,
+    siteSeo: params.siteSeo,
+    pageSeo,
+  })
+
+  return {
+    title: resolveDocumentTitle({ title, template: params.siteSeo.titleTemplate, pageSeo }),
+    description: resolveDescription({ description, pageSeo }),
+    canonical: resolveCanonical({
+      origin: params.siteSeo.origin,
+      base: params.base,
+      pathname: params.pathname,
+      pageSeo,
+    }),
+    robots: resolveRobots({ defaults: params.siteSeo.robots, overrides: pageSeo.robots }),
+    openGraph: resolveOpenGraph({
+      origin: params.siteSeo.origin,
+      base: params.base,
+      pathname: params.pathname,
+      siteSeo: params.siteSeo,
+      pageSeo,
+      title,
+      description,
+      socialImage,
+    }),
+    twitter: resolveTwitter({
+      origin: params.siteSeo.origin,
+      siteSeo: params.siteSeo,
+      pageSeo,
+      title,
+      description,
+      socialImage,
+    }),
+  }
+}
+
+/**
+ * Validates the nested SEO block from raw Markdown frontmatter.
+ *
+ * @private
+ */
+function resolvePageSeo(frontmatter: Readonly<Record<string, unknown>>): PageSeoConfig {
+  if (!isPageSeoConfig(frontmatter.seo)) {
+    return {}
+  }
+  return frontmatter.seo
+}
+
+/**
+ * Validates the small page SEO shape without shipping Zod to the browser.
+ *
+ * @private
+ */
+function isPageSeoConfig(value: unknown): value is PageSeoConfig {
+  if (!isPlainObject(value) || !hasOnlyKeys(value, PAGE_SEO_KEYS)) {
+    return false
+  }
+  return (
+    isOptionalString(value['title']) &&
+    isOptionalString(value['description']) &&
+    isCanonical(value['canonical']) &&
+    isOptionalImageUrl(value['socialImage']) &&
+    isRobotsConfig(value['robots']) &&
+    isOpenGraphConfig(value['openGraph']) &&
+    isTwitterConfig(value['twitter'])
+  )
+}
+
+/**
+ * Validates optional crawler directives.
+ *
+ * @private
+ */
+function isRobotsConfig(value: unknown): boolean {
+  if (isUndefined(value)) {
+    return true
+  }
+  if (!isPlainObject(value) || !hasOnlyKeys(value, ROBOTS_KEYS)) {
+    return false
+  }
+  return isOptionalBoolean(value['index']) && isOptionalBoolean(value['follow'])
+}
+
+/**
+ * Validates optional Open Graph overrides.
+ *
+ * @private
+ */
+function isOpenGraphConfig(value: unknown): boolean {
+  if (isUndefined(value) || value === false) {
+    return true
+  }
+  if (!isPlainObject(value) || !hasOnlyKeys(value, OPEN_GRAPH_KEYS)) {
+    return false
+  }
+  return (
+    isOptionalString(value['title']) &&
+    isOptionalString(value['description']) &&
+    (isUndefined(value['type']) || value['type'] === 'website' || value['type'] === 'article') &&
+    isOptionalImageUrl(value['image'])
+  )
+}
+
+/**
+ * Validates optional Twitter card overrides.
+ *
+ * @private
+ */
+function isTwitterConfig(value: unknown): boolean {
+  if (isUndefined(value) || value === false) {
+    return true
+  }
+  if (!isPlainObject(value) || !hasOnlyKeys(value, TWITTER_KEYS)) {
+    return false
+  }
+  return (
+    isOptionalString(value['title']) &&
+    isOptionalString(value['description']) &&
+    (isUndefined(value['card']) ||
+      value['card'] === 'summary' ||
+      value['card'] === 'summary_large_image') &&
+    isOptionalImageUrl(value['image']) &&
+    (isUndefined(value['creator']) || isTwitterHandle(value['creator']))
+  )
+}
+
+/**
+ * Checks that a record contains no fields outside its supported schema.
+ *
+ * @private
+ */
+function hasOnlyKeys(
+  value: Readonly<Record<PropertyKey, unknown>>,
+  keys: readonly string[]
+): boolean {
+  return Object.keys(value).every((key) => keys.includes(key))
+}
+
+/**
+ * Validates an optional string field.
+ *
+ * @private
+ */
+function isOptionalString(value: unknown): boolean {
+  return isUndefined(value) || isString(value)
+}
+
+/**
+ * Validates an optional boolean field.
+ *
+ * @private
+ */
+function isOptionalBoolean(value: unknown): boolean {
+  return isUndefined(value) || isBoolean(value)
+}
+
+/**
+ * Validates an optional canonical URL or explicit suppression.
+ *
+ * @private
+ */
+function isCanonical(value: unknown): boolean {
+  return isUndefined(value) || value === false || (isString(value) && isHttpUrl(value))
+}
+
+/**
+ * Validates an optional social image URL.
+ *
+ * @private
+ */
+function isOptionalImageUrl(value: unknown): boolean {
+  return isUndefined(value) || (isString(value) && value.length > 0 && isHttpOrRelativeUrl(value))
+}
+
+/**
+ * Checks that an account handle uses Twitter's supported username shape.
+ *
+ * @private
+ */
+function isTwitterHandle(value: string): boolean {
+  return /^@[A-Za-z0-9_]{1,15}$/u.test(value)
+}
+
+/**
+ * Checks that a URL is absolute and uses HTTP(S).
+ *
+ * @private
+ */
+function isHttpUrl(value: string): boolean {
+  if (!URL.canParse(value)) {
+    return false
+  }
+  const protocol = new URL(value).protocol
+  return protocol === 'https:' || protocol === 'http:'
+}
+
+/**
+ * Checks that an image is an HTTP(S) URL or relative URL path.
+ *
+ * @private
+ */
+function isHttpOrRelativeUrl(value: string): boolean {
+  if (!URL.canParse(value, 'https://ciderpress.invalid')) {
+    return false
+  }
+  return isHttpUrl(new URL(value, 'https://ciderpress.invalid').href)
+}
+
+/**
+ * Applies the site title template only when Ciderpress must override the document title.
+ *
+ * @private
+ */
+function resolveDocumentTitle(params: {
+  readonly title: string
+  readonly template: string | false | undefined
+  readonly pageSeo: PageSeoConfig
+}): string | undefined {
+  if (isNil(params.template) && isNil(params.pageSeo.title)) {
+    return undefined
+  }
+  if (params.template === false || isNil(params.template)) {
+    return params.title
+  }
+  return params.template.replaceAll('%s', params.title)
+}
+
+/**
+ * Emits a description only when page SEO explicitly overrides the framework default.
+ *
+ * @private
+ */
+function resolveDescription(params: {
+  readonly description: string
+  readonly pageSeo: PageSeoConfig
+}): string | undefined {
+  if (isNil(params.pageSeo.description)) {
+    return undefined
+  }
+  return params.description
+}
+
+/**
+ * Resolves canonical overrides while honoring explicit suppression.
+ *
+ * @private
+ */
+function resolveCanonical(params: {
+  readonly origin: string
+  readonly base: string
+  readonly pathname: string
+  readonly pageSeo: PageSeoConfig
+}): string | undefined {
+  if (params.pageSeo.canonical === false) {
+    return undefined
+  }
+  if (isMatching(P.string, params.pageSeo.canonical)) {
+    return params.pageSeo.canonical
+  }
+  return resolveSeoPageUrl(params)
+}
+
+/**
+ * Resolves the shared social image against the production origin.
+ *
+ * @private
+ */
+function resolveSocialImage(params: {
+  readonly origin: string
+  readonly siteSeo: SeoConfig
+  readonly pageSeo: PageSeoConfig
+}): string | undefined {
+  const image = params.pageSeo.socialImage ?? params.siteSeo.socialImage
+  if (isNil(image)) {
+    return undefined
+  }
+  return new URL(image, params.origin).href
+}
+
+/**
+ * Merges Open Graph defaults and page overrides into render-ready metadata.
+ *
+ * @private
+ */
+function resolveOpenGraph(params: {
+  readonly origin: string
+  readonly base: string
+  readonly pathname: string
+  readonly siteSeo: SeoConfig
+  readonly pageSeo: PageSeoConfig
+  readonly title: string
+  readonly description: string
+  readonly socialImage: string | undefined
+}): ResolvedOpenGraphMetadata | false {
+  if (params.siteSeo.openGraph === false || params.pageSeo.openGraph === false) {
+    return false
+  }
+  const openGraph = { ...params.siteSeo.openGraph, ...params.pageSeo.openGraph }
+  return {
+    url: resolveSeoPageUrl(params),
+    title: openGraph.title ?? params.title,
+    description: openGraph.description ?? params.description,
+    type: openGraph.type ?? 'website',
+    siteName: openGraph.siteName,
+    locale: openGraph.locale,
+    image: resolveProviderImage({
+      origin: params.origin,
+      override: openGraph.image,
+      fallback: params.socialImage,
+    }),
+  }
+}
+
+/**
+ * Merges Twitter defaults and page overrides into render-ready metadata.
+ *
+ * @private
+ */
+function resolveTwitter(params: {
+  readonly origin: string
+  readonly siteSeo: SeoConfig
+  readonly pageSeo: PageSeoConfig
+  readonly title: string
+  readonly description: string
+  readonly socialImage: string | undefined
+}): ResolvedTwitterMetadata | false {
+  if (params.siteSeo.twitter === false || params.pageSeo.twitter === false) {
+    return false
+  }
+  const twitter = {
+    card: 'summary_large_image' as const,
+    ...params.siteSeo.twitter,
+    ...params.pageSeo.twitter,
+  }
+  return {
+    card: twitter.card,
+    title: twitter.title ?? params.title,
+    description: twitter.description ?? params.description,
+    site: twitter.site,
+    creator: twitter.creator,
+    image: resolveProviderImage({
+      origin: params.origin,
+      override: twitter.image,
+      fallback: params.socialImage,
+    }),
+  }
+}
+
+/**
+ * Applies a provider-specific image over the shared social image.
+ *
+ * @private
+ */
+function resolveProviderImage(params: {
+  readonly origin: string
+  readonly override: string | undefined
+  readonly fallback: string | undefined
+}): string | undefined {
+  if (isNil(params.override)) {
+    return params.fallback
+  }
+  return new URL(params.override, params.origin).href
+}
+
+/**
+ * Converts merged crawler flags into a robots directive.
+ *
+ * @private
+ */
+function resolveRobots(params: {
+  readonly defaults: RobotsConfig | undefined
+  readonly overrides: RobotsConfig | undefined
+}): string | undefined {
+  if (isNil(params.defaults) && isNil(params.overrides)) {
+    return undefined
+  }
+  const resolved = { index: true, follow: true, ...params.defaults, ...params.overrides }
+  const index = resolveIndexDirective(resolved.index)
+  const follow = resolveFollowDirective(resolved.follow)
+  return `${index}, ${follow}`
+}
+
+/**
+ * Maps the index flag to its robots directive.
+ *
+ * @private
+ */
+function resolveIndexDirective(index: boolean): 'index' | 'noindex' {
+  if (index) {
+    return 'index'
+  }
+  return 'noindex'
+}
+
+/**
+ * Maps the follow flag to its robots directive.
+ *
+ * @private
+ */
+function resolveFollowDirective(follow: boolean): 'follow' | 'nofollow' {
+  if (follow) {
+    return 'follow'
+  }
+  return 'nofollow'
+}

package/src/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/src/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/src/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;
+}