@raystack/chronicle 0.1.0-canary.0efaef0

package/src/themes/default/index.ts

@@ -0,0 +1,11 @@
+import type { Theme } from '@/types';
+import { Layout } from './Layout';
+import { Page } from './Page';
+import { Toc } from './Toc';
+
+export const defaultTheme: Theme = {
+  Layout,
+  Page
+};
+
+export { Layout, Page, Toc };

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

@@ -0,0 +1,71 @@
+.nav {
+  display: flex;
+  flex-direction: column;
+  gap: var(--rs-space-5);
+}
+
+.chapter {
+  display: flex;
+  flex-direction: column;
+  gap: var(--rs-space-2);
+}
+
+.chapterLabel {
+  font-size: var(--rs-font-size-small);
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--rs-color-foreground-base-primary);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.chapterItems {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--rs-space-1);
+  padding-left: var(--rs-space-4);
+}
+
+.link {
+  display: flex;
+  align-items: center;
+  gap: var(--rs-space-2);
+  font-size: var(--rs-font-size-small);
+  color: var(--rs-color-foreground-base-tertiary);
+  text-decoration: none;
+  padding: var(--rs-space-1) 0;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.link:hover {
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.active {
+  color: var(--rs-color-foreground-accent-primary);
+  font-weight: 500;
+}
+
+.icon {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+}
+
+.subLabel {
+  font-size: var(--rs-font-size-small);
+  font-weight: 500;
+  color: var(--rs-color-foreground-base-secondary);
+  margin-top: var(--rs-space-3);
+  display: block;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}

package/src/themes/paper/ChapterNav.tsx

@@ -0,0 +1,115 @@
+import { Link as RouterLink, useLocation } from 'react-router';
+import { MethodBadge } from '@/components/api/method-badge';
+import type { PageTree, PageTreeItem } from '@/types';
+import styles from './ChapterNav.module.css';
+
+const iconMap: Record<string, React.ReactNode> = {
+  'method-get': <MethodBadge method='GET' size='micro' />,
+  'method-post': <MethodBadge method='POST' size='micro' />,
+  'method-put': <MethodBadge method='PUT' size='micro' />,
+  'method-delete': <MethodBadge method='DELETE' size='micro' />,
+  'method-patch': <MethodBadge method='PATCH' size='micro' />
+};
+
+interface ChapterNavProps {
+  tree: PageTree;
+}
+
+function buildChapterIndices(
+  children: PageTreeItem[]
+): Map<PageTreeItem, number> {
+  const indices = new Map<PageTreeItem, number>();
+  let index = 0;
+  for (const item of children) {
+    if (item.type === 'folder' && item.children) {
+      index++;
+      indices.set(item, index);
+    }
+  }
+  return indices;
+}
+
+export function ChapterNav({ tree }: ChapterNavProps) {
+  const { pathname } = useLocation();
+  const chapterIndices = buildChapterIndices(tree.children);
+
+  return (
+    <nav className={styles.nav}>
+      <ul className={styles.chapterItems}>
+        {tree.children.map(item => {
+          if (item.type === 'separator') return null;
+
+          if (item.type === 'folder' && item.children) {
+            const chapterIndex = chapterIndices.get(item) ?? 0;
+            return (
+              <li key={item.name} className={styles.chapter}>
+                <span className={styles.chapterLabel}>
+                  {String(chapterIndex).padStart(2, '0')}. {item.name}
+                </span>
+                <ul className={styles.chapterItems}>
+                  {item.children.map(child => (
+                    <ChapterItem
+                      key={child.url ?? child.name}
+                      item={child}
+                      pathname={pathname}
+                    />
+                  ))}
+                </ul>
+              </li>
+            );
+          }
+
+          return (
+            <ChapterItem
+              key={item.url ?? item.name}
+              item={item}
+              pathname={pathname}
+            />
+          );
+        })}
+      </ul>
+    </nav>
+  );
+}
+
+function ChapterItem({
+  item,
+  pathname
+}: {
+  item: PageTreeItem;
+  pathname: string;
+}) {
+  if (item.type === 'separator') return null;
+
+  if (item.type === 'folder' && item.children) {
+    return (
+      <li>
+        <span className={styles.subLabel}>{item.name}</span>
+        <ul className={styles.chapterItems}>
+          {item.children.map(child => (
+            <ChapterItem
+              key={child.url ?? child.name}
+              item={child}
+              pathname={pathname}
+            />
+          ))}
+        </ul>
+      </li>
+    );
+  }
+
+  const isActive = pathname === item.url;
+  const icon = item.icon ? iconMap[item.icon] : null;
+
+  return (
+    <li>
+      <RouterLink
+        to={item.url ?? '#'}
+        className={`${styles.link} ${isActive ? styles.active : ''}`}
+      >
+        {icon && <span className={styles.icon}>{icon}</span>}
+        <span>{item.name}</span>
+      </RouterLink>
+    </li>
+  );
+}

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

@@ -0,0 +1,33 @@
+.layout {
+  --paper-sidebar-width: 260px;
+
+  min-height: 100vh;
+}
+
+.body {
+  flex: 1;
+}
+
+.sidebar {
+  width: var(--paper-sidebar-width);
+  padding: var(--rs-space-7) var(--rs-space-5);
+  background: var(--rs-color-background-neutral-primary);
+  overflow-y: auto;
+  font-family: "SF Mono", "Fira Code", "Fira Mono", "Roboto Mono", monospace;
+}
+
+.title {
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--rs-color-foreground-accent-primary);
+  font-family: inherit;
+  font-size: var(--rs-font-size-mono-large);
+  margin-bottom: var(--rs-space-7);
+}
+
+.content {
+  flex: 1;
+  overflow-y: auto;
+  background: var(--rs-color-background-neutral-primary);
+  padding-right: var(--paper-sidebar-width);
+}

package/src/themes/paper/Layout.tsx

@@ -0,0 +1,37 @@
+'use client';
+
+import { Flex, Headline } from '@raystack/apsara';
+import { cx } from 'class-variance-authority';
+import { Footer } from '@/components/ui/footer';
+import type { ThemeLayoutProps } from '@/types';
+import { ChapterNav } from './ChapterNav';
+import styles from './Layout.module.css';
+
+export function Layout({
+  children,
+  config,
+  tree,
+  classNames
+}: ThemeLayoutProps) {
+  return (
+    <Flex direction='column' className={cx(styles.layout, classNames?.layout)}>
+      <Flex className={cx(styles.body, classNames?.body)}>
+        <aside className={cx(styles.sidebar, classNames?.sidebar)}>
+          <Headline
+            size='small'
+            weight='medium'
+            as='h1'
+            className={styles.title}
+          >
+            {config.title}
+          </Headline>
+          <ChapterNav tree={tree} />
+        </aside>
+        <div className={cx(styles.content, classNames?.content)}>
+          {children}
+        </div>
+      </Flex>
+      <Footer config={config.footer} />
+    </Flex>
+  );
+}

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

@@ -0,0 +1,181 @@
+.main {
+  --paper-navbar-height: 40px;
+  --paper-navbar-padding: var(--rs-space-3);
+  --paper-navbar-total: calc(
+    var(--paper-navbar-height) +
+    var(--paper-navbar-padding) *
+    2 +
+    1px
+  );
+
+  flex: 1;
+  max-width: 1024px;
+  margin: 0 auto;
+}
+
+.navbar {
+  height: var(--paper-navbar-height);
+  padding: var(--paper-navbar-padding) 0;
+  border-bottom: 1px solid var(--rs-color-border-base-primary);
+  justify-content: space-between;
+  width: 100%;
+  position: fixed;
+  top: 0;
+  background: var(--rs-color-background-neutral-primary);
+  z-index: 10;
+  max-width: 1024px;
+}
+
+.navLeft {
+  align-items: center;
+}
+
+.navRight {
+  align-items: center;
+}
+
+.arrow {
+  display: flex;
+  align-items: center;
+  color: var(--rs-color-foreground-base-primary);
+  text-decoration: none;
+}
+
+.arrow:hover {
+  color: var(--rs-color-foreground-accent-primary);
+}
+
+.arrowDisabled {
+  display: flex;
+  align-items: center;
+  color: var(--rs-color-foreground-base-tertiary);
+  opacity: 0.4;
+  cursor: default;
+  border: none;
+  background: none;
+  padding: 0;
+}
+
+.breadcrumb {
+  font-family: "SF Mono", "Fira Code", monospace;
+  font-size: var(--rs-font-size-small);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  margin-left: var(--rs-space-3);
+}
+
+.separator {
+  margin: 0 var(--rs-space-2);
+  color: var(--rs-color-foreground-base-tertiary);
+}
+
+.crumbLink {
+  color: var(--rs-color-foreground-base-tertiary);
+  text-decoration: none;
+}
+
+.crumbLink:hover {
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.crumbActive {
+  color: var(--rs-color-foreground-base-primary);
+  font-weight: 600;
+}
+
+.article {
+  flex: 1;
+  min-width: 0;
+  margin-top: var(--paper-navbar-total);
+  padding: 0 var(--rs-space-7);
+}
+
+.searchButton {
+  height: 28px;
+  padding: 0 var(--rs-space-3);
+  font-size: var(--rs-font-size-small);
+  border: none;
+  box-shadow: none;
+}
+
+.content {
+  font-family: Georgia, "Times New Roman", serif;
+  line-height: 1.8;
+  background: var(--rs-color-background-base-primary);
+  padding: var(--rs-space-9);
+  border-left: 1px solid var(--rs-color-border-base-primary);
+  border-right: 1px solid var(--rs-color-border-base-primary);
+  box-shadow:
+    0 1px 3px rgba(0, 0, 0, 0.08),
+    0 4px 12px rgba(0, 0, 0, 0.04);
+  margin-bottom: var(--rs-space-9);
+}
+
+.content h1,
+.content h2,
+.content h3,
+.content h4,
+.content h5,
+.content h6 {
+  line-height: 1.4;
+}
+
+.content h1 {
+  margin: 2rem 0 1rem;
+  font-size: 2rem;
+}
+
+.content h2 {
+  margin: 1.75rem 0 0.75rem;
+  font-size: 1.5rem;
+}
+
+.content h3 {
+  margin: 1.5rem 0 0.5rem;
+  font-size: 1.25rem;
+}
+
+.content h4 {
+  margin: 1.25rem 0 0.5rem;
+  font-size: 1.1rem;
+}
+
+.content h5 {
+  margin: 1rem 0 0.5rem;
+  font-size: 1rem;
+}
+
+.content h6 {
+  margin: 1rem 0 0.5rem;
+  font-size: 0.875rem;
+}
+
+.content p {
+  margin: 0.75rem 0;
+}
+
+.content ul,
+.content ol {
+  margin: 0.75rem 0;
+  padding-left: 1.5rem;
+  margin-bottom: var(--rs-space-5);
+}
+
+.content li {
+  font-size: var(--rs-font-size-regular);
+  margin: var(--rs-space-2) 0;
+}
+
+.content table {
+  margin-bottom: var(--rs-space-5);
+}
+
+.content [role="tablist"] {
+  margin-bottom: var(--rs-space-3);
+}
+
+.content blockquote {
+  margin: 1rem 0;
+  padding-left: 1rem;
+  border-left: 3px solid var(--rs-color-border-base-primary);
+}

package/src/themes/paper/Page.tsx

@@ -0,0 +1,126 @@
+import { ChevronLeftIcon, ChevronRightIcon } from '@heroicons/react/24/outline';
+import { Flex } from '@raystack/apsara';
+import { useMemo } from 'react';
+import { Link as RouterLink, useLocation } from 'react-router';
+import { Search } from '@/components/ui/search';
+import type { PageTreeItem, ThemePageProps } from '@/types';
+import styles from './Page.module.css';
+import { ReadingProgress } from './ReadingProgress';
+
+function flattenTree(items: PageTreeItem[]): PageTreeItem[] {
+  const result: PageTreeItem[] = [];
+  for (const item of items) {
+    if (item.type === 'page' && item.url) result.push(item);
+    if (item.children) result.push(...flattenTree(item.children));
+  }
+  return result;
+}
+
+function findBreadcrumb(
+  items: PageTreeItem[],
+  slug: string[]
+): { label: string; href: string }[] {
+  const result: { label: string; href: string }[] = [];
+  for (let i = 0; i < slug.length; i++) {
+    const path = '/' + slug.slice(0, i + 1).join('/');
+    const found = findInTree(items, path);
+    result.push({ label: found?.name ?? slug[i], href: path });
+  }
+  return result;
+}
+
+function findInTree(
+  items: PageTreeItem[],
+  path: string
+): PageTreeItem | undefined {
+  for (const item of items) {
+    if (item.url === path) return item;
+    if (item.children) {
+      const found = findInTree(item.children, path);
+      if (found) return found;
+    }
+  }
+  return undefined;
+}
+
+export function Page({ page, config, tree }: ThemePageProps) {
+  const { pathname } = useLocation();
+
+  const { prev, next, crumbs } = useMemo(() => {
+    const pages = flattenTree(tree.children);
+    const currentIndex = pages.findIndex(p => p.url === pathname);
+    return {
+      prev: currentIndex > 0 ? pages[currentIndex - 1] : null,
+      next: currentIndex < pages.length - 1 ? pages[currentIndex + 1] : null,
+      crumbs: findBreadcrumb(tree.children, page.slug)
+    };
+  }, [tree, pathname, page.slug]);
+
+  return (
+    <>
+      <main className={styles.main}>
+        <Flex align='center' className={styles.navbar}>
+          <Flex align='center' gap='small' className={styles.navLeft}>
+            {prev ? (
+              <RouterLink
+                to={prev.url!}
+                className={styles.arrow}
+                aria-label='Previous page'
+              >
+                <ChevronLeftIcon width={14} height={14} />
+              </RouterLink>
+            ) : (
+              <button
+                disabled
+                className={styles.arrowDisabled}
+                aria-label='Previous page'
+              >
+                <ChevronLeftIcon width={14} height={14} />
+              </button>
+            )}
+            {next ? (
+              <RouterLink
+                to={next.url!}
+                className={styles.arrow}
+                aria-label='Next page'
+              >
+                <ChevronRightIcon width={14} height={14} />
+              </RouterLink>
+            ) : (
+              <button
+                disabled
+                className={styles.arrowDisabled}
+                aria-label='Next page'
+              >
+                <ChevronRightIcon width={14} height={14} />
+              </button>
+            )}
+            <nav className={styles.breadcrumb}>
+              {crumbs.map((crumb, i) => (
+                <span key={crumb.href}>
+                  {i > 0 && <span className={styles.separator}>/</span>}
+                  {i === crumbs.length - 1 ? (
+                    <span className={styles.crumbActive}>{crumb.label}</span>
+                  ) : (
+                    <RouterLink to={crumb.href} className={styles.crumbLink}>
+                      {crumb.label}
+                    </RouterLink>
+                  )}
+                </span>
+              ))}
+            </nav>
+          </Flex>
+          <Flex align='center' className={styles.navRight}>
+            {config.search?.enabled && (
+              <Search className={styles.searchButton} />
+            )}
+          </Flex>
+        </Flex>
+        <article className={styles.article} data-article-content>
+          <div className={styles.content}>{page.content}</div>
+        </article>
+      </main>
+      <ReadingProgress items={page.toc} />
+    </>
+  );
+}

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