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

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;
+}

package/src/theme/components/sidebar/sidebar-filter.test.ts

@@ -43,6 +43,22 @@ const groupWithoutLink: SidebarData[number] = {
   items: [{ text: 'Deep Page', link: '/packages/deep/page' }],
 }
 
+const launchpad: SidebarData[number] = {
+  text: 'Launchpad',
+  link: '/launchpad',
+  collapsible: true,
+  collapsed: true,
+  items: [
+    {
+      text: 'Concepts',
+      collapsible: true,
+      collapsed: false,
+      items: [{ text: 'Architecture', link: '/launchpad/concepts/architecture' }],
+    },
+    { text: 'Getting Started', link: '/launchpad/getting-started' },
+  ],
+}
+
 const fullSidebar: SidebarData = [gettingStarted, packages, contributing]
 const scopes: readonly string[] = ['/packages', '/contributing']
 
@@ -60,25 +76,49 @@ describe('resolveScopedSidebar()', () => {
     expect(result[0]).toMatchObject({ text: 'Getting Started' })
   })
 
-  it('should show only the matching standalone section on an exact scope path', () => {
+  it('should flatten the matching standalone section on an exact scope path', () => {
     const result = resolveScopedSidebar(fullSidebar, '/packages', scopes)
 
-    expect(result).toHaveLength(1)
-    expect(result[0]).toMatchObject({ text: 'Packages' })
+    expect(result).toStrictEqual([
+      { text: 'Packages', link: '/packages' },
+      { text: 'CLI', link: '/packages/cli' },
+      { text: 'Core', link: '/packages/core' },
+    ])
   })
 
-  it('should show only the matching standalone section on a nested scope path', () => {
+  it('should flatten the matching standalone section on a nested scope path', () => {
     const result = resolveScopedSidebar(fullSidebar, '/packages/cli', scopes)
 
-    expect(result).toHaveLength(1)
-    expect(result[0]).toMatchObject({ text: 'Packages' })
+    expect(result).toStrictEqual([
+      { text: 'Packages', link: '/packages' },
+      { text: 'CLI', link: '/packages/cli' },
+      { text: 'Core', link: '/packages/core' },
+    ])
   })
 
-  it('should show only contributing items on the contributing scope', () => {
+  it('should flatten contributing items on the contributing scope', () => {
     const result = resolveScopedSidebar(fullSidebar, '/contributing/guides', scopes)
 
-    expect(result).toHaveLength(1)
-    expect(result[0]).toMatchObject({ text: 'Contributing' })
+    expect(result).toStrictEqual([
+      { text: 'Contributing', link: '/contributing' },
+      { text: 'Guides', link: '/contributing/guides' },
+      { text: 'Standards', link: '/contributing/standards' },
+    ])
+  })
+
+  it('should promote an island page before its preserved nested groups', () => {
+    const result = resolveScopedSidebar([launchpad], '/launchpad', ['/launchpad'])
+
+    expect(result).toStrictEqual([
+      { text: 'Launchpad', link: '/launchpad' },
+      {
+        text: 'Concepts',
+        collapsible: true,
+        collapsed: false,
+        items: [{ text: 'Architecture', link: '/launchpad/concepts/architecture' }],
+      },
+      { text: 'Getting Started', link: '/launchpad/getting-started' },
+    ])
   })
 
   it('should not mutate the original sidebar data', () => {

package/src/theme/components/sidebar/sidebar-filter.ts

@@ -19,9 +19,9 @@ type SidebarDataItem = SidebarData[number]
  * Resolve the sidebar items visible for the current scope.
  *
  * When the current pathname matches a standalone scope (e.g. `/packages`),
- * only that section's sidebar items are returned. For all other paths,
- * standalone sections are excluded and the remaining sections form a
- * unified sidebar.
+ * a linked section is promoted to a sidebar root before its children. An
+ * unlinked section returns only its children. For all other paths, standalone
+ * sections are excluded and the remaining sections form a unified sidebar.
  *
  * @param items - Full unified sidebar items
  * @param pathname - Current decoded URL pathname
@@ -44,7 +44,7 @@ export function resolveScopedSidebar(
   const all = [...items]
 
   if (standaloneMatch) {
-    return all.filter((item) => belongsToScope(item, standaloneMatch))
+    return all.filter((item) => belongsToScope(item, standaloneMatch)).flatMap(flattenScopeRoot)
   }
 
   return all.filter((item) => !scopes.some((scope) => belongsToScope(item, scope)))
@@ -77,3 +77,23 @@ export function belongsToScope(item: SidebarDataItem, scope: string): boolean {
   }
   return false
 }
+
+/**
+ * Convert a standalone section wrapper into a normal root page followed by
+ * its nested sidebar structure.
+ *
+ * @private
+ * @param item - Matching standalone sidebar root
+ * @returns The root page and children, or the root itself when it has no children
+ */
+function flattenScopeRoot(item: SidebarDataItem): readonly SidebarDataItem[] {
+  if (Object.hasOwn(item, 'items')) {
+    const { items } = item as { readonly items: readonly SidebarDataItem[] }
+    if (Object.hasOwn(item, 'text') && Object.hasOwn(item, 'link')) {
+      const { text, link } = item as { readonly text: string; readonly link: string }
+      return [{ text, link }, ...items]
+    }
+    return items
+  }
+  return [item]
+}

package/src/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'
@@ -101,7 +102,14 @@ export type { FeatureCardProps, FeatureItem } from './components/home/feature-ca
 export { PageRail } from './components/home/page-rail'
 export type { PageRailProps } from './components/home/page-rail'
 export { Hero } from './components/home/hero'
-export type { HeroProps, HeroAction } from './components/home/hero'
+export type {
+  HeroProps,
+  HeroAction,
+  HeroBackground,
+  HeroBackgroundImage,
+  HeroBackgroundSource,
+  HeroBackgroundVariants,
+} from './components/home/hero'
 export { HeroDemo } from './components/home/hero-demo'
 export { TrustStrip } from './components/home/trust-strip'
 export type { TrustStripProps } from './components/home/trust-strip'

package/src/theme/lib/rich-text-parse.ts

@@ -82,10 +82,8 @@ export const MARK_CLASS = 'cp-mark'
 // to 128k chars (0.19ms -> 0.45ms) across tag-name runs, attribute runs,
 // quote runs, unbalanced parens, and unterminated quotes. The pattern this
 // replaced *was* quadratic (2ms -> 427ms over the same range).
-/* oxlint-disable security/detect-unsafe-regex -- disjoint alternations, measured linear */
 const TOKEN_PATTERN =
   /(?:\\([*=`[\]<\\]))|(?:`([^`]+)`)|(?:\*\*([\s\S]+?)\*\*)|(?:==([\s\S]+?)==)|(?:(?<!\*)\*(?=[^\s*])([^*\n]+?)(?<=[^\s*])\*(?!\*))|(?:\[([^\]]*)\]\(((?:[^()\s]|\([^()\s]*\))+)\))|(?:<(\/?)\s*([a-zA-Z][a-zA-Z0-9-]*)(?=[\s/>])((?:"[^"]*"|'[^']*'|[^>"'])*)>)/
-/* oxlint-enable security/detect-unsafe-regex */
 
 const ATTR_PATTERN = /([a-zA-Z-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g
 

package/src/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/src/theme/lib/theme-favicon.ts

@@ -23,9 +23,7 @@ export function syncThemeFavicon(html: HTMLElement): void {
   const surface = resolveSurfaceColor(html)
   const dataUri = buildIconDataUri(brand, shadow, surface)
   const link = ensureFaviconLink()
-  // oxlint-disable-next-line functional/immutable-data -- boundary mutation: updating link element href
   link.type = 'image/svg+xml'
-  // oxlint-disable-next-line functional/immutable-data -- boundary mutation: updating link element href
   link.href = dataUri
 }
 
@@ -118,7 +116,6 @@ function ensureFaviconLink(): HTMLLinkElement {
     return existing
   }
   const link = globalThis.document.createElement('link')
-  // oxlint-disable-next-line functional/immutable-data -- boundary mutation: initialising newly created link element
   link.rel = 'icon'
   globalThis.document.head.append(link)
   return link

package/src/theme/styles/themes/honeycrisp.css

@@ -288,7 +288,7 @@ html[data-cp-theme='honeycrisp'][data-cp-variant='dark'] {
 }
 
 html[data-cp-theme='honeycrisp'][data-cp-variant='light'] {
-  --cp-c-brand-1: #dc2626;
+  --cp-c-brand-1: #d02020;
   --cp-c-brand-2: #b91c1c;
   --cp-c-brand-3: #7f1d1d;
   --cp-c-brand-fg: #ffffff;
@@ -301,15 +301,15 @@ html[data-cp-theme='honeycrisp'][data-cp-variant='light'] {
   --cp-c-warn: #d97706;
   --cp-c-info: #2563eb;
   --cp-c-muted: #888888;
-  --cp-c-bg: #ffffff;
-  --cp-c-bg-alt: #f9f9f9;
-  --cp-c-bg-elv: #f5f5f5;
-  --cp-c-bg-soft: #f0f0f0;
-  --cp-c-bg-icon: #cccccc;
-  --cp-c-home-bg: #ffffff;
+  --cp-c-bg: #f7f5f0;
+  --cp-c-bg-alt: #f1eee7;
+  --cp-c-bg-elv: #fffdf8;
+  --cp-c-bg-soft: #ebe7dc;
+  --cp-c-bg-icon: #d5cebe;
+  --cp-c-home-bg: #f7f5f0;
   --cp-c-overlay-faint: rgba(0, 0, 0, 0.1);
-  --cp-c-gutter: #f5f5f5;
-  --cp-code-block-bg: #f5f5f5;
+  --cp-c-gutter: #f1eee7;
+  --cp-code-block-bg: #f1eee7;
   --cp-c-text-1: #1a1a1a;
   --cp-c-text-2: rgba(26, 26, 26, 0.72);
   --cp-c-text-3: rgba(26, 26, 26, 0.48);
@@ -384,7 +384,7 @@ html[data-cp-theme='honeycrisp'][data-cp-variant='light'] {
   --cp-oas-deprecated: var(--cp-c-text-3);
   --cp-oas-required: #dc2626;
   --cp-button-brand-bg: #b91c1c;
-  --cp-button-brand-hover-bg: #dc2626;
+  --cp-button-brand-hover-bg: #d02020;
   --cp-button-brand-active-bg: #7f1d1d;
   --cp-button-brand-text: #ffffff;
   --cp-s-1: 1px;
@@ -535,12 +535,12 @@ html[data-cp-theme='honeycrisp'][data-cp-variant='light'] {
   --cp-blur-base: 8px;
   --cp-gradient-brand: linear-gradient(135deg, var(--cp-c-brand-1), var(--cp-c-brand-3));
   --cp-gradient-hero-title: linear-gradient(135deg, var(--cp-c-brand-1), var(--cp-c-brand-light));
-  --rp-c-bg: #ffffff;
-  --rp-c-bg-alt: #f9f9f9;
-  --rp-c-bg-dark: #f5f5f5;
-  --rp-c-bg-mute: #ffffff;
-  --rp-c-bg-soft: #f0f0f0;
-  --rp-c-brand: #dc2626;
+  --rp-c-bg: #f7f5f0;
+  --rp-c-bg-alt: #f1eee7;
+  --rp-c-bg-dark: #f1eee7;
+  --rp-c-bg-mute: #f7f5f0;
+  --rp-c-bg-soft: #ebe7dc;
+  --rp-c-brand: #d02020;
   --rp-c-brand-light: #ef4444;
   --rp-c-brand-lighter: #fca5a5;
   --rp-c-brand-dark: #b91c1c;
@@ -549,15 +549,15 @@ html[data-cp-theme='honeycrisp'][data-cp-variant='light'] {
   --rp-c-divider: #e2e2e2;
   --rp-c-divider-dark: #d0d0d0;
   --rp-c-divider-light: #e2e2e2;
-  --rp-c-link: #dc2626;
+  --rp-c-link: #d02020;
   --rp-c-text-1: #1a1a1a;
   --rp-c-text-2: rgba(26, 26, 26, 0.72);
   --rp-c-text-3: rgba(26, 26, 26, 0.48);
   --rp-c-text-4: rgba(26, 26, 26, 0.48);
   --rp-c-text-code: #1a1a1a;
-  --rp-code-block-bg: #f5f5f5;
-  --rp-home-background-bg: #ffffff;
-  --rp-home-feature-bg: #f0f0f0;
+  --rp-code-block-bg: #f1eee7;
+  --rp-home-background-bg: #f7f5f0;
+  --rp-home-feature-bg: #ebe7dc;
   --rp-home-hero-secondary-color: rgba(26, 26, 26, 0.72);
   --rp-home-hero-title-color: #1a1a1a;
   --rp-font-family-base: