@raystack/chronicle 0.1.0-canary.1f5227c

package/src/themes/paper/ReadingProgress.module.css

@@ -0,0 +1,132 @@
+.container {
+  position: fixed;
+  right: var(--rs-space-4);
+  top: 100px;
+  width: 200px;
+  height: calc(100vh - 200px);
+  z-index: 10;
+}
+
+.inner {
+  position: absolute;
+  inset: 0;
+}
+
+.tickContainer {
+  position: absolute;
+  right: 0;
+  display: grid;
+  width: 6rem;
+  align-items: center;
+  justify-content: flex-end;
+}
+
+.tickLine {
+  height: 1px;
+  width: 0.5rem;
+  transition: all 100ms;
+}
+
+.tickLineBefore {
+  background-color: var(--rs-color-foreground-accent-primary);
+}
+
+.tickLineAfter {
+  background-color: var(--rs-color-background-neutral-tertiary);
+}
+
+.tickContainer:hover .tickLine {
+  width: 1rem;
+}
+
+.tickClickable {
+  position: absolute;
+  inset-inline: 0;
+  height: 0.5rem;
+  cursor: pointer;
+}
+
+.headingContainer {
+  transition: transform 150ms;
+}
+
+.headingContainer:hover {
+  transform: translateX(-0.125rem);
+}
+
+.headingLabel {
+  position: absolute;
+  display: flex;
+  height: 0.75rem;
+  align-items: center;
+  font-family: var(--rs-font-mono);
+  font-size: 0.75rem;
+  color: var(--rs-color-foreground-base-primary);
+  text-transform: capitalize;
+  opacity: 0;
+  transition: opacity 300ms;
+}
+
+.headingLink {
+  color: var(--rs-color-foreground-base-primary);
+  text-align: right;
+  font-family: var(--rs-font-mono);
+  font-size: var(--rs-font-size-mini);
+  font-weight: var(--rs-font-weight-regular);
+  line-height: var(--rs-line-height-mini);
+  letter-spacing: var(--rs-letter-spacing-mini);
+  text-decoration: none;
+  cursor: pointer;
+}
+
+.headingLink:hover {
+  color: var(--rs-color-foreground-accent-primary);
+}
+
+.container:hover .headingLabel {
+  opacity: 1;
+}
+
+.connectingLine {
+  position: absolute;
+  right: 0;
+  height: 1px;
+  background-color: var(--rs-color-background-neutral-emphasis);
+}
+
+.scrollMarkerContainer {
+  position: absolute;
+  right: 0;
+  z-index: 20;
+  transition: opacity 300ms;
+  pointer-events: none;
+}
+
+.scrollMarkerContainerReady {
+  opacity: 1;
+}
+
+.scrollMarkerContainerNotReady {
+  opacity: 0;
+}
+
+.scrollMarkerLine {
+  height: 1px;
+  width: 1rem;
+  background-color: var(--rs-color-foreground-accent-primary);
+}
+
+.scrollMarkerText {
+  position: absolute;
+  top: 0;
+  left: -2.5rem;
+  transform: translateY(-50%);
+  font-family: var(--rs-font-mono);
+  font-size: 0.75rem;
+  color: var(--rs-color-foreground-accent-primary);
+  transition: opacity 300ms;
+}
+
+.container:hover .scrollMarkerText {
+  opacity: 0;
+}

package/src/themes/paper/ReadingProgress.tsx

@@ -0,0 +1,294 @@
+'use client'
+
+import { cx } from 'class-variance-authority'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import type { TocItem } from '@/types'
+import styles from './ReadingProgress.module.css'
+
+interface Heading {
+  title: string
+  level: number
+  id: string
+  url: string
+  yPosition: number
+}
+
+const ARTICLE_SELECTOR = '[data-article-content]'
+const TICK_HEIGHT = 20
+const NAV_HEIGHT = 60
+
+function calculateTickBounds(containerHeight: number) {
+  const numTicks = Math.floor(containerHeight / TICK_HEIGHT) + 1
+  const maxPosition = (numTicks - 1) * TICK_HEIGHT
+  return { numTicks, maxPosition }
+}
+
+function snapToTick(value: number, maxPosition: number): number {
+  const snapped = Math.round(value / TICK_HEIGHT) * TICK_HEIGHT
+  return Math.max(0, Math.min(snapped, maxPosition))
+}
+
+function resolveOverlaps(headings: Heading[], maxPosition: number): Heading[] {
+  if (headings.length <= 1) return headings
+
+  const resolved: Heading[] = []
+  let lastUsedPos = -TICK_HEIGHT
+
+  for (const heading of headings) {
+    let newPos = heading.yPosition
+    if (newPos <= lastUsedPos) {
+      newPos = lastUsedPos + TICK_HEIGHT
+    }
+    resolved.push({ ...heading, yPosition: newPos })
+    lastUsedPos = newPos
+  }
+
+  // Backward pass: clamp-and-shift to prevent overlapping positions
+  for (let i = resolved.length - 1; i >= 0; i--) {
+    const maxAllowed =
+      i === resolved.length - 1
+        ? maxPosition
+        : resolved[i + 1].yPosition - TICK_HEIGHT
+
+    const clampedPos = Math.max(0, maxAllowed)
+    if (resolved[i].yPosition > clampedPos) {
+      resolved[i] = { ...resolved[i], yPosition: clampedPos }
+      for (let j = i - 1; j >= 0; j--) {
+        const upperBound = resolved[j + 1].yPosition - TICK_HEIGHT
+        if (resolved[j].yPosition > upperBound) {
+          resolved[j] = { ...resolved[j], yPosition: Math.max(0, upperBound) }
+        } else {
+          break
+        }
+      }
+    }
+  }
+
+  return resolved
+}
+
+interface ReadingProgressProps {
+  items: TocItem[]
+}
+
+export function ReadingProgress({ items }: ReadingProgressProps) {
+  const [headings, setHeadings] = useState<Heading[]>([])
+  const [containerHeight, setContainerHeight] = useState<number>(0)
+  const [ready, setReady] = useState<boolean>(false)
+  const [isScrollable, setIsScrollable] = useState<boolean>(true)
+  const containerRef = useRef<HTMLDivElement>(null)
+  const scrollMarkerRef = useRef<HTMLDivElement>(null)
+  const scrollPosRef = useRef<number>(0)
+
+  const { numTicks, maxPosition } = useMemo(
+    () => calculateTickBounds(containerHeight),
+    [containerHeight]
+  )
+
+  const recalcHeadings = useCallback(() => {
+    const article = document.querySelector(ARTICLE_SELECTOR)
+    const container = containerRef.current
+    if (!article || !container || !items.length) return
+
+    const articleBox = article.getBoundingClientRect()
+    const containerBox = container.getBoundingClientRect()
+    const articleTop = articleBox.top + window.scrollY
+
+    const hasScroll = articleBox.height > window.innerHeight
+    setIsScrollable(hasScroll)
+    setContainerHeight(containerBox.height)
+
+    const { maxPosition: maxPos } = calculateTickBounds(containerBox.height)
+
+    const mapped = items
+      .map((tocItem) => {
+        const id = tocItem.url.startsWith('#') ? tocItem.url.slice(1) : tocItem.url
+        const node = document.getElementById(id)
+        if (!node) return null
+
+        const { top } = node.getBoundingClientRect()
+        const headingPosInArticle = top + window.scrollY - articleTop
+        const progress = headingPosInArticle / articleBox.height
+        const rawY = progress * maxPos
+        const yPos = snapToTick(rawY, maxPos)
+
+        return {
+          title: tocItem.title,
+          level: tocItem.depth,
+          id,
+          url: tocItem.url,
+          yPosition: yPos,
+        }
+      })
+      .filter((item): item is Heading => item !== null)
+
+    const resolvedItems = resolveOverlaps(mapped, maxPos)
+    setHeadings(resolvedItems)
+  }, [items])
+
+  // Imperative DOM updates to avoid React re-render on every scroll event
+  const handleScroll = useCallback(() => {
+    const article = document.querySelector(ARTICLE_SELECTOR)
+    const container = containerRef.current
+    const scrollMarker = scrollMarkerRef.current
+    if (!article || !container || !scrollMarker) return
+
+    const { top, height } = article.getBoundingClientRect()
+    const { height: cHeight } = container.getBoundingClientRect()
+    const viewportHeight = window.innerHeight
+    const { maxPosition: maxPos } = calculateTickBounds(cHeight)
+
+    let newScrollPos: number
+    if (top > 0) {
+      newScrollPos = 0
+    } else {
+      const scrolled = Math.abs(top)
+      const scrollRange = height - viewportHeight
+      const progress = scrollRange > 0 ? Math.min(1, scrolled / scrollRange) : 0
+      const rawPos = progress * maxPos
+      newScrollPos = snapToTick(rawPos, maxPos)
+    }
+
+    const prevScrollPos = scrollPosRef.current
+    if (newScrollPos !== prevScrollPos) {
+      scrollPosRef.current = newScrollPos
+      scrollMarker.style.top = `${newScrollPos}px`
+
+      const textEl = scrollMarker.querySelector('[data-scroll-text]')
+      if (textEl) {
+        textEl.textContent = (maxPos > 0 ? newScrollPos / maxPos : 0).toFixed(2)
+      }
+
+      const tickLines = container.querySelectorAll('[data-tick-line]')
+      tickLines.forEach((tick) => {
+        const tickPos = Number(tick.getAttribute('data-tick-pos'))
+        if (tickPos < newScrollPos) {
+          tick.classList.remove(styles.tickLineAfter)
+          tick.classList.add(styles.tickLineBefore)
+        } else {
+          tick.classList.remove(styles.tickLineBefore)
+          tick.classList.add(styles.tickLineAfter)
+        }
+      })
+    }
+  }, [])
+
+  useEffect(() => {
+    recalcHeadings()
+    handleScroll()
+    setReady(true)
+
+    const article = document.querySelector(ARTICLE_SELECTOR)
+    let ro: ResizeObserver | undefined
+    if (article) {
+      ro = new ResizeObserver(() => {
+        recalcHeadings()
+        handleScroll()
+      })
+      ro.observe(article)
+    }
+
+    window.addEventListener('resize', recalcHeadings)
+    window.addEventListener('scroll', handleScroll, { passive: true })
+
+    return () => {
+      ro?.disconnect()
+      window.removeEventListener('resize', recalcHeadings)
+      window.removeEventListener('scroll', handleScroll)
+    }
+  }, [recalcHeadings, handleScroll])
+
+  const scrollToTick = (y: number): void => {
+    const article = document.querySelector(ARTICLE_SELECTOR)
+    if (!article || maxPosition === 0) return
+
+    const articleBox = article.getBoundingClientRect()
+    const articleTop = articleBox.top + window.scrollY
+    const progress = y / maxPosition
+    const articlePos = progress * articleBox.height
+    const targetScroll = articleTop + articlePos - NAV_HEIGHT
+
+    window.scrollTo({ top: Math.max(0, targetScroll), behavior: 'smooth' })
+  }
+
+  const scrollToHeading = (id: string): void => {
+    const element = document.getElementById(id)
+    if (!element) return
+
+    const elementTop = element.getBoundingClientRect().top + window.scrollY
+    window.scrollTo({ top: Math.max(0, elementTop - NAV_HEIGHT), behavior: 'smooth' })
+  }
+
+  const ticks = useMemo(
+    () => Array.from({ length: numTicks }, (_, i) => i * TICK_HEIGHT),
+    [numTicks]
+  )
+
+  if (!isScrollable || ticks.length < 2) {
+    return <div ref={containerRef} className={styles.container} />
+  }
+
+  return (
+    <div ref={containerRef} className={styles.container}>
+      <div className={styles.inner}>
+        {ticks.map((y, i) => (
+          <div key={`tick-${i}`} style={{ top: `${y}px` }} className={styles.tickContainer}>
+            <div data-tick-line data-tick-pos={y} className={cx(styles.tickLine, styles.tickLineAfter)} />
+            <div className={styles.tickClickable} onClick={() => scrollToTick(y)} />
+          </div>
+        ))}
+
+        {headings.map((h, i) => (
+          <div key={h.id || i} className={styles.headingContainer}>
+            <div
+              className={styles.headingLabel}
+              style={{
+                top: `${h.yPosition - 6}px`,
+                right: '24px',
+                zIndex: h.level < 4 ? 10 : 0,
+                transitionDelay: `${50 * i}ms`,
+              }}
+            >
+              <a
+                href={h.url}
+                className={styles.headingLink}
+                onClick={(e) => {
+                  e.preventDefault()
+                  e.stopPropagation()
+                  scrollToHeading(h.id)
+                }}
+              >
+                {h.title}
+              </a>
+            </div>
+          </div>
+        ))}
+
+        {headings.map((h, i) => (
+          <div
+            key={`line-${i}`}
+            className={styles.connectingLine}
+            style={{
+              top: `${h.yPosition}px`,
+              width: `${Math.max(4, (3 - h.level) * 4 + 12)}px`,
+            }}
+          />
+        ))}
+
+        <div
+          ref={scrollMarkerRef}
+          className={cx(
+            styles.scrollMarkerContainer,
+            ready ? styles.scrollMarkerContainerReady : styles.scrollMarkerContainerNotReady
+          )}
+          style={{ top: '0px' }}
+        >
+          <div className={styles.scrollMarkerLine} />
+          <span data-scroll-text className={styles.scrollMarkerText}>
+            0.00
+          </span>
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/themes/paper/index.ts

@@ -0,0 +1,8 @@
+import { Layout } from './Layout'
+import { Page } from './Page'
+import type { Theme } from '@/types'
+
+export const paperTheme: Theme = {
+  Layout,
+  Page,
+}

package/src/themes/registry.ts

@@ -0,0 +1,14 @@
+import type { Theme } from '@/types'
+import { defaultTheme } from './default'
+import { paperTheme } from './paper'
+
+const themes: Record<string, Theme> = {
+  default: defaultTheme,
+  paper: paperTheme,
+}
+
+export function getTheme(name?: string): Theme {
+  if (!name || !themes[name]) return defaultTheme
+
+  return themes[name]
+}

package/src/types/config.ts

@@ -0,0 +1,80 @@
+export interface ChronicleConfig {
+  title: string
+  description?: string
+  url?: string
+  logo?: LogoConfig
+  theme?: ThemeConfig
+  navigation?: NavigationConfig
+  search?: SearchConfig
+  footer?: FooterConfig
+  api?: ApiConfig[]
+  llms?: LlmsConfig
+  analytics?: AnalyticsConfig
+}
+
+export interface LlmsConfig {
+  enabled?: boolean
+}
+
+export interface AnalyticsConfig {
+  enabled?: boolean
+  googleAnalytics?: GoogleAnalyticsConfig
+}
+
+export interface GoogleAnalyticsConfig {
+  measurementId: string
+}
+
+export interface ApiConfig {
+  name: string
+  spec: string
+  basePath: string
+  server: ApiServerConfig
+  auth?: ApiAuthConfig
+}
+
+export interface ApiServerConfig {
+  url: string
+  description?: string
+}
+
+export interface ApiAuthConfig {
+  type: string
+  header: string
+  placeholder?: string
+}
+
+export interface LogoConfig {
+  light?: string
+  dark?: string
+}
+
+export interface ThemeConfig {
+  name: 'default' | 'paper'
+  colors?: Record<string, string>
+}
+
+export interface NavigationConfig {
+  links?: NavLink[]
+  social?: SocialLink[]
+}
+
+export interface NavLink {
+  label: string
+  href: string
+}
+
+export interface SocialLink {
+  type: 'github' | 'twitter' | 'discord' | string
+  href: string
+}
+
+export interface SearchConfig {
+  enabled?: boolean
+  placeholder?: string
+}
+
+export interface FooterConfig {
+  copyright?: string
+  links?: NavLink[]
+}

package/src/types/content.ts

@@ -0,0 +1,36 @@
+import type { ReactNode } from 'react'
+
+export interface Frontmatter {
+  title: string
+  description?: string
+  order?: number
+  icon?: string
+  lastModified?: string
+}
+
+export interface Page {
+  slug: string[]
+  frontmatter: Frontmatter
+  content: ReactNode
+  toc: TocItem[]
+}
+
+export interface TocItem {
+  title: string
+  url: string
+  depth: number
+}
+
+export interface PageTreeItem {
+  type: 'page' | 'folder' | 'separator'
+  name: string
+  url?: string
+  order?: number
+  icon?: string
+  children?: PageTreeItem[]
+}
+
+export interface PageTree {
+  name: string
+  children: PageTreeItem[]
+}

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export * from './config'
+export * from './content'
+export * from './theme'

package/src/types/theme.ts

@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react'
+import type { ChronicleConfig } from './config'
+import type { Page, PageTree } from './content'
+
+export interface ThemeLayoutProps {
+  children: ReactNode
+  config: ChronicleConfig
+  tree: PageTree
+  classNames?: { layout?: string; body?: string; sidebar?: string; content?: string }
+}
+
+export interface ThemePageProps {
+  page: Page
+  config: ChronicleConfig
+  tree: PageTree
+}
+
+export interface Theme {
+  Layout: React.ComponentType<ThemeLayoutProps>
+  Page: React.ComponentType<ThemePageProps>
+  className?: string
+}

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "composite": false,
+    "declaration": true,
+    "declarationMap": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "inlineSources": false,
+    "isolatedModules": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "preserveWatchOutput": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "target": "es6",
+    "outDir": "dist",
+    "rootDir": ".",
+    "baseUrl": ".",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "moduleResolution": "bundler",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}