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

package/src/theme/components/home/workspaces.tsx

@@ -1,69 +1,181 @@
-import type { HomeShowcaseConfig } from '@ciderpress/config'
-import { useFrontmatter } from '@rspress/core/runtime'
+import type { TruncateConfig } from '@ciderpress/config'
 import { match, P } from 'massaman/match'
 import type React from 'react'
 
 import { useCiderpress } from '../../hooks/use-ciderpress'
-import type { WorkspaceGroupData } from '../../hooks/use-ciderpress'
+import type { WorkspaceCardData, WorkspaceGroupData } from '../../hooks/use-ciderpress'
+import { renderRichText } from '../../lib/rich-text.tsx'
 import { WorkspaceCard } from '../workspaces/card'
 import { WorkspaceGrid } from '../workspaces/grid'
 
+/**
+ * A single card compiled from `showcase.source` — the same shape as a
+ * workspace card, minus the grouping.
+ */
+export type ShowcaseCard = WorkspaceCardData
+
 interface FrontmatterWorkspacesHeading {
   readonly label?: string
   readonly title?: string
-  readonly subtitle?: string
+  readonly body?: string
+}
+
+interface HomeWorkspacesProps {
+  readonly heading?: FrontmatterWorkspacesHeading
+  /**
+   * Cards compiled from an explicit `showcase.source` path list. When
+   * present they render as one ungrouped grid; otherwise the grouped
+   * workspace data from the theme config is used.
+   */
+  readonly cards?: readonly ShowcaseCard[]
+  readonly columns?: 1 | 2 | 3 | 4
+  readonly truncate?: TruncateConfig
 }
 
+const DEFAULT_COLUMNS: 1 | 2 | 3 | 4 = 2
+
 /**
- * Smart orchestrator that reads workspace data from themeConfig
- * and renders workspace groups with the correct card component per type.
- *
- * Optionally renders a top-level heading above the workspace groups
- * when `home.showcase.heading` is configured. The sync engine writes
- * it into frontmatter as `workspacesHeading`.
+ * Showcase grid block. Renders either the cards compiled from an
+ * explicit `showcase.source` path list (one ungrouped grid) or the
+ * grouped workspace data serialized from the repo at build time. Grid
+ * layout — heading, columns, truncation — comes from props.
  *
- * @returns React element with workspace groups or null
+ * @param props - Optional heading, cards, column count, and truncation limits.
+ * @returns React element with the showcase grid, or null when empty.
  */
-export function HomeWorkspaces(): React.ReactElement | null {
-  const { workspaces, home } = useCiderpress()
-  const gridConfig = home && home.showcase
-  const { frontmatter } = useFrontmatter()
-  const heading = (frontmatter as Record<string, unknown>).workspacesHeading as
-    | FrontmatterWorkspacesHeading
-    | undefined
+export function HomeWorkspaces(props: HomeWorkspacesProps): React.ReactElement | null {
+  const { workspaces } = useCiderpress()
+  const { heading, cards, columns, truncate } = props
+  const resolvedColumns = match(columns)
+    .with(P.nonNullable, (c) => c)
+    .otherwise(() => DEFAULT_COLUMNS)
 
-  return match(workspaces)
+  // A `cards` key means the block declared an explicit `showcase.source`
+  // — an empty array is "that source resolved to nothing", not "fall back
+  // to the workspace deck". Only an absent key takes the fallback.
+  const body = match(cards)
     .with(
-      P.when((w): w is readonly WorkspaceGroupData[] => Array.isArray(w) && w.length > 0),
-      (groups) => (
-        <div className="cp-workspace-section">
-          <hr className="cp-divider" />
-          {match(heading)
-            .with(undefined, () => null)
-            .otherwise((h) => (
-              <div className="cp-feature-section-head">
-                {match(h.label)
-                  .with(undefined, () => null)
-                  .otherwise((e) => (
-                    <div className="cp-feature-section-head__eyebrow">{e}</div>
-                  ))}
-                {match(h.title)
-                  .with(undefined, () => null)
-                  .otherwise((t) => (
-                    <h2 className="cp-feature-section-head__title">{t}</h2>
-                  ))}
-                {match(h.subtitle)
-                  .with(undefined, () => null)
-                  .otherwise((s) => (
-                    <p className="cp-feature-section-head__sub">{s}</p>
-                  ))}
-              </div>
-            ))}
-          {groups.map((group) => renderGroup(group, gridConfig))}
-        </div>
-      )
+      P.when((c): c is readonly ShowcaseCard[] => Array.isArray(c)),
+      (list) =>
+        match(list.length === 0)
+          .with(true, () => null)
+          .otherwise(() => [renderCardGrid(list, resolvedColumns, truncate)])
+    )
+    .otherwise(() =>
+      match(workspaces)
+        .with(
+          P.when((w): w is readonly WorkspaceGroupData[] => Array.isArray(w) && w.length > 0),
+          (groups) => groups.map((group, i) => renderGroup(group, resolvedColumns, truncate, i))
+        )
+        .otherwise(() => null)
     )
-    .otherwise(() => null)
+
+  return match(body)
+    .with(null, () => null)
+    .otherwise((content) => (
+      <div className="cp-workspace-section">
+        {/* The rule separates this band from the heading above it, so a
+            block with no heading of its own would render it as an orphan
+            line floating over the cards. */}
+        {match(renderHeading(heading))
+          .with(P.nullish, () => null)
+          .otherwise((head) => (
+            <>
+              <hr className="cp-divider" />
+              {head}
+            </>
+          ))}
+        {content}
+      </div>
+    ))
+}
+
+/**
+ * Render the block heading, or nothing when every field is absent.
+ *
+ * @private
+ * @param heading - Flat heading trio from the block
+ * @returns Heading element, or null
+ */
+function renderHeading(
+  heading: FrontmatterWorkspacesHeading | undefined
+): React.ReactElement | null {
+  if (heading === undefined) {
+    return null
+  }
+  const { label, title, body } = heading
+  const hasContent = [label, title, body].some((value) => typeof value === 'string')
+  if (!hasContent) {
+    return null
+  }
+  return (
+    <div className="cp-feature-section-head">
+      {match(label)
+        .with(P.string, (e) => (
+          <div className="cp-feature-section-head__eyebrow">{renderRichText(e)}</div>
+        ))
+        .otherwise(() => null)}
+      {match(title)
+        .with(P.string, (t) => (
+          <h2 className="cp-feature-section-head__title">{renderRichText(t)}</h2>
+        ))
+        .otherwise(() => null)}
+      {match(body)
+        .with(P.string, (s) => <p className="cp-feature-section-head__sub">{renderRichText(s)}</p>)
+        .otherwise(() => null)}
+    </div>
+  )
+}
+
+/**
+ * Render an ungrouped grid of cards compiled from `showcase.source`.
+ *
+ * @private
+ * @param cards - Resolved showcase cards
+ * @param columns - Column count for the grid
+ * @param truncate - Optional line-clamp limits for card text
+ * @returns Ungrouped workspace grid element
+ */
+function renderCardGrid(
+  cards: readonly ShowcaseCard[],
+  columns: 1 | 2 | 3 | 4,
+  truncate: TruncateConfig | undefined
+): React.ReactElement {
+  return (
+    <WorkspaceGrid key="showcase-source" columns={columns}>
+      {cards.map((card, i) => renderCard(card, i, truncate))}
+    </WorkspaceGrid>
+  )
+}
+
+/**
+ * Render a single showcase / workspace card.
+ *
+ * @private
+ * @param card - Card data
+ * @param index - Array index for key generation
+ * @param truncate - Optional line-clamp limits for card text
+ * @returns Workspace card element
+ */
+function renderCard(
+  card: WorkspaceCardData,
+  index: number,
+  truncate: TruncateConfig | undefined
+): React.ReactElement {
+  return (
+    <WorkspaceCard
+      key={`${card.title}-${index}`}
+      title={card.title}
+      href={card.href}
+      icon={card.icon}
+      scope={card.scope}
+      description={card.description}
+      tags={card.tags}
+      badge={card.badge}
+      titleLines={truncate && truncate.title}
+      descriptionLines={truncate && truncate.description}
+    />
+  )
 }
 
 /**
@@ -71,37 +183,27 @@ export function HomeWorkspaces(): React.ReactElement | null {
  *
  * @private
  * @param group - Workspace group data with heading, description, and cards
- * @param gridConfig - Optional grid layout config for columns and truncation
+ * @param columns - Column count for the grid
+ * @param truncate - Optional line-clamp limits for card text
+ * @param index - Position in the group list, to disambiguate the key
  * @returns Workspace grid element
  */
 function renderGroup(
   group: WorkspaceGroupData,
-  gridConfig: HomeShowcaseConfig | undefined
+  columns: 1 | 2 | 3 | 4,
+  truncate: TruncateConfig | undefined,
+  index: number
 ): React.ReactElement {
-  const titleLines = gridConfig && gridConfig.truncate && gridConfig.truncate.title
-  const descLines = gridConfig && gridConfig.truncate && gridConfig.truncate.description
-
   return (
+    // Heading alone is not unique — two configured workspace groups may
+    // share a title, which collided into one React key.
     <WorkspaceGrid
-      key={group.heading}
+      key={`${group.heading}-${index}`}
       heading={group.heading}
       description={group.description}
-      columns={gridConfig && gridConfig.columns}
+      columns={columns}
     >
-      {group.cards.map((card, i) => (
-        <WorkspaceCard
-          key={`${card.title}-${i}`}
-          title={card.title}
-          href={card.href}
-          icon={card.icon}
-          scope={card.scope}
-          description={card.description}
-          tags={card.tags}
-          badge={card.badge}
-          titleLines={titleLines}
-          descriptionLines={descLines}
-        />
-      ))}
+      {group.cards.map((card, i) => renderCard(card, i, truncate))}
     </WorkspaceGrid>
   )
 }

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')
+  })
+})