@ciderpress/ui 1.0.0-rc.1

package/dist/theme/components/nav/branch-tag.tsx

@@ -0,0 +1,101 @@
+import type { SiteConfig } from '@ciderpress/config'
+import { match, P } from 'massaman/match'
+import type React from 'react'
+
+import { useCiderpress } from '../../hooks/use-ciderpress'
+
+import './branch-tag.css'
+import { Icon } from '../shared/icon.tsx'
+
+declare const __CIDERPRESS_GIT_BRANCH__: string | undefined
+
+/**
+ * Git branch tag — pill-shaped badge rendered via the `beforeNavMenu`
+ * layout slot. Hidden when on default branches (`main` or `master`) or
+ * when no `site.edit.repo` is configured. Uses the pixelarticons:git-branch
+ * icon.
+ *
+ * @returns React element, or `null` when on a default branch / unconfigured.
+ */
+export function BranchTag(): React.ReactElement | null {
+  const { site } = useCiderpress()
+  const branch = resolveBranch()
+
+  if (!branch || branch === 'main' || branch === 'master') {
+    return null
+  }
+
+  const href = buildBranchHref({ repo: resolveRepo(site), branch })
+  if (href === null) {
+    return null
+  }
+
+  return (
+    <a
+      className="cp-branch-tag"
+      href={href}
+      target="_blank"
+      rel="noopener noreferrer"
+      title={`Branch: ${branch}`}
+    >
+      <Icon icon="pixelarticons:git-branch" width={14} height={14} />
+      <span className="cp-branch-tag__text">{branch}</span>
+    </a>
+  )
+}
+
+export { BranchTag as default }
+
+/**
+ * Resolves the current git branch name from the build-time global,
+ * returning an empty string when undefined.
+ *
+ * @private
+ * @returns Current git branch name or empty string
+ */
+function resolveBranch(): string {
+  if (__CIDERPRESS_GIT_BRANCH__ !== undefined) {
+    return __CIDERPRESS_GIT_BRANCH__
+  }
+  return ''
+}
+
+/**
+ * Build a GitHub `/tree/<branch>` URL from the configured `site.edit.repo`.
+ *
+ * Accepts either a full URL (used as-is) or an `org/repo` slug
+ * (prefixed with `https://github.com/`). Returns `null` when `repo` is
+ * missing so the caller can omit the component entirely.
+ *
+ * @private
+ * @param params - The configured repo and the current branch.
+ * @returns Fully-qualified URL string, or `null` when unconfigured.
+ */
+function buildBranchHref(params: {
+  readonly repo: string | undefined
+  readonly branch: string
+}): string | null {
+  return match(params.repo)
+    .with(undefined, () => null)
+    .with('', () => null)
+    .with(P.string.startsWith('http'), (full) => `${full}/tree/${params.branch}`)
+    .otherwise((slug) => `https://github.com/${slug}/tree/${params.branch}`)
+}
+
+/**
+ * Pull the configured edit-repo slug off the site config, expressed
+ * with explicit null checks rather than optional chaining.
+ *
+ * @private
+ * @param site - The ciderpress site config (may be undefined).
+ * @returns The configured `edit.repo` value or `undefined`.
+ */
+function resolveRepo(site: SiteConfig | undefined): string | undefined {
+  if (site === undefined) {
+    return undefined
+  }
+  if (site.edit === undefined) {
+    return undefined
+  }
+  return site.edit.repo
+}

package/dist/theme/components/nav/ciderpress-doc-layout.tsx

@@ -0,0 +1,247 @@
+import { useFrontmatter, useLocation } from '@rspress/core/runtime'
+import { DocContent, DocFooter, Outline, Overview, Sidebar, useWatchToc } from '@rspress/core/theme'
+import type { DocLayoutProps } from '@rspress/core/theme'
+import { clsx } from 'clsx'
+import { match } from 'massaman/match'
+import { useEffect, useMemo, useState } from 'react'
+import type React from 'react'
+
+import { CiderpressLayoutContext } from './ciderpress-layout-context'
+
+/**
+ * Ciderpress replacement for Rspress's `<DocLayout />`. Re-exported
+ * from the theme entry so Rspress's `<Layout />` (which imports
+ * `DocLayout` via `@rspress/core/theme`) picks this version up
+ * automatically.
+ *
+ * Why a full re-implementation instead of a `beforeDoc` wrapper:
+ *
+ *   1. Rspress's DocLayout unconditionally renders
+ *      `<div className="rp-doc-layout__menu">{sidebarMenu}</div>` —
+ *      and the inner `<SidebarMenu />` is hardcoded inside the
+ *      private `useSidebarMenu` hook (not swappable). CSS-hiding the
+ *      wrapper leaves the React subtree (and the focus-trap, body-
+ *      scroll-lock, click-outside listeners it installs) live, which
+ *      we don't want when our own `<CiderpressDocsBar />` is the
+ *      sticky sub-header.
+ *
+ *   2. The sidebar/outline drawer state lives entirely inside
+ *      `useSidebarMenu` and isn't exposed publicly. By owning the
+ *      DocLayout we own the state, which then flows through
+ *      `<CiderpressLayoutContext />` to `<CiderpressDocsBar />` so
+ *      the bar's toggle button drives the drawer directly (no
+ *      `document.querySelector` against Rspress internals).
+ *
+ * Behavioural parity preserved: SSR markdown short-circuit, all
+ * `before*` / `after*` slots, frontmatter-driven sidebar / outline /
+ * footer toggles, doc-wide variant, overview-page variant, and the
+ * `useWatchToc` ref on the article body.
+ *
+ * @param props - Standard `DocLayoutProps` (slots + components).
+ * @returns Doc-layout React element.
+ */
+export function CiderpressDocLayout(props: DocLayoutProps): React.ReactElement {
+  const {
+    beforeDocFooter,
+    afterDocFooter,
+    beforeDoc,
+    afterDoc,
+    beforeDocContent,
+    afterDocContent,
+    beforeOutline,
+    afterOutline,
+    beforeSidebar,
+    afterSidebar,
+    components,
+  } = props
+  const { frontmatter } = useFrontmatter()
+  const fmRecord = frontmatter as Record<string, unknown>
+  const isOverviewPage = fmRecord.overview === true
+  const sidebarConfig = match(fmRecord.sidebar)
+    .with(false, () => false as const)
+    .with('placeholder', () => 'placeholder' as const)
+    .otherwise(() => true as const)
+  const showSidebar = sidebarConfig === true
+  const showSidebarPlaceholder = sidebarConfig === false || sidebarConfig === 'placeholder'
+  const isLegacyPlaceholder = sidebarConfig === 'placeholder'
+  const showOutline = match(fmRecord.outline)
+    .with(false, () => false)
+    .otherwise(() => true)
+  const showDocFooter = match(fmRecord.footer)
+    .with(false, () => false)
+    .otherwise(() => true)
+  const isDocWide = fmRecord.pageType === 'doc-wide'
+
+  const [isSidebarOpen, setIsSidebarOpen] = useState(false)
+  const [isOutlineOpen, setIsOutlineOpen] = useState(false)
+  const { pathname } = useLocation()
+
+  // Close drawers when navigating to a new page.
+  useEffect(() => {
+    setIsSidebarOpen(false)
+    setIsOutlineOpen(false)
+  }, [pathname])
+
+  // Body scroll lock ONLY while the SIDEBAR drawer is open — the
+  // outline is now a dropdown / side popout that lives in the bar
+  // and doesn't take over the viewport, so locking page scroll for
+  // it makes the page feel "frozen" without good reason.
+  useEffect(() => {
+    if (globalThis.document === undefined) {
+      return
+    }
+    const html = globalThis.document.documentElement
+    match(isSidebarOpen)
+      .with(true, () => {
+        html.dataset.cpDrawerOpen = 'true'
+      })
+      .otherwise(() => {
+        delete html.dataset.cpDrawerOpen
+      })
+  }, [isSidebarOpen])
+
+  const { rspressDocRef } = useWatchToc()
+
+  const contextValue = useMemo(
+    () => ({ isSidebarOpen, setIsSidebarOpen, isOutlineOpen, setIsOutlineOpen }),
+    [isSidebarOpen, isOutlineOpen]
+  )
+
+  if (process.env.__SSR_MD__) {
+    return (
+      <>
+        {match(isOverviewPage)
+          .with(true, () => (
+            <Overview content={<DocContent components={components} isOverviewPage />} />
+          ))
+          .otherwise(() => (
+            <DocContent components={components} />
+          ))}
+      </>
+    )
+  }
+
+  const sidebarSlot = match({ showSidebar, showSidebarPlaceholder })
+    .with({ showSidebar: true }, () => (
+      <aside
+        className={clsx(
+          'rp-doc-layout__sidebar',
+          isSidebarOpen && 'rp-doc-layout__sidebar--open',
+          'rp-scrollbar'
+        )}
+      >
+        {beforeSidebar}
+        <Sidebar />
+        {afterSidebar}
+      </aside>
+    ))
+    .with({ showSidebarPlaceholder: true }, () => (
+      <aside
+        className={clsx(
+          'rp-doc-layout__sidebar-placeholder',
+          isLegacyPlaceholder && 'rp-doc-layout__sidebar-placeholder--legacy'
+        )}
+        style={docWideStyle(isDocWide)}
+      />
+    ))
+    .otherwise(() => null)
+
+  const mainSlot = match(isOverviewPage)
+    .with(true, () => (
+      <main className="rp-doc-layout__overview">
+        {beforeDocContent}
+        <Overview content={<DocContent components={components} isOverviewPage />} />
+        {afterDocContent}
+      </main>
+    ))
+    .otherwise(() => (
+      <div className={clsx('rp-doc-layout__doc', isDocWide && 'rp-doc-layout__doc--wide')}>
+        <main className="rp-doc-layout__doc-container">
+          {beforeDocContent}
+          <div className="rp-doc rspress-doc" ref={rspressDocRef}>
+            <DocContent components={components} />
+          </div>
+          {afterDocContent}
+          {beforeDocFooter}
+          {showDocFooter && <DocFooter />}
+          {afterDocFooter}
+        </main>
+      </div>
+    ))
+
+  // No `--open` class on the outline rail: at >=1280px it's a sticky
+  // desktop rail; at <=1279px Rspress styles it as a fixed overlay
+  // drawer that we don't want. <CiderpressDocsBar /> renders its own
+  // dropdown using the same `<Toc />` component, so the rail just
+  // stays hidden via Rspress's default `visibility: hidden` at narrow
+  // widths.
+  const outlineSlot = match({ isOverviewPage, showOutline })
+    .with({ isOverviewPage: true }, () => null)
+    .with({ showOutline: true }, () => (
+      <aside className={clsx('rp-doc-layout__outline', 'rp-scrollbar')}>
+        {beforeOutline}
+        <Outline />
+        {afterOutline}
+      </aside>
+    ))
+    .otherwise(() => (
+      <aside className="rp-doc-layout__outline-placeholder" style={docWideStyle(isDocWide)} />
+    ))
+
+  return (
+    <CiderpressLayoutContext.Provider value={contextValue}>
+      {beforeDoc}
+      <div className="rp-doc-layout__container rp-doc-layout__container--no-menu">
+        {/* Mask only renders for the sidebar drawer — the outline
+            uses an in-bar dropdown (`<CiderpressDocsBar />`'s
+            outline-dropdown) with its own document-mousedown
+            click-outside handler, no modal chrome needed. */}
+        {isSidebarOpen && (
+          <div
+            className="cp-drawer-mask"
+            onClick={makeCloseDrawers(setIsSidebarOpen, setIsOutlineOpen)}
+            aria-hidden="true"
+          />
+        )}
+        {sidebarSlot}
+        {mainSlot}
+        {outlineSlot}
+      </div>
+      {afterDoc}
+    </CiderpressLayoutContext.Provider>
+  )
+}
+
+/**
+ * Produce the inline style for the placeholder rails when the page is
+ * `doc-wide` (zero-width placeholders so the prose can claim the space).
+ *
+ * @private
+ * @param isDocWide - True when the active page is `doc-wide`.
+ * @returns Style object or undefined when no override is needed.
+ */
+function docWideStyle(isDocWide: boolean): React.CSSProperties | undefined {
+  if (isDocWide) {
+    return { width: '0' }
+  }
+}
+
+/**
+ * Build a single onClick handler that closes both drawers. Inlined so
+ * `setIsSidebarOpen` / `setIsOutlineOpen` don't need to be wrapped in
+ * `useCallback`s that re-create on every state flip.
+ *
+ * @private
+ * @param setSidebar - Setter for the sidebar drawer state.
+ * @param setOutline - Setter for the outline drawer state.
+ * @returns Click handler.
+ */
+function makeCloseDrawers(
+  setSidebar: React.Dispatch<React.SetStateAction<boolean>>,
+  setOutline: React.Dispatch<React.SetStateAction<boolean>>
+): () => void {
+  return () => {
+    setSidebar(false)
+    setOutline(false)
+  }
+}