@clidey/dory 1.0.7 → 1.9.0

package/src/types/config.ts

@@ -40,9 +40,15 @@ export interface DoryNavigationPage {
   [key: string]: string;
 }
 
+/** Page entry with extras, e.g. { "page": "components/overview", "badge": "New" }. */
+export interface DoryNavigationPageEntry {
+  page: string;
+  badge?: string;
+}
+
 export interface DoryNavigationGroup {
   group: string;
-  pages: string[];
+  pages: Array<string | DoryNavigationPageEntry>;
 }
 
 export interface DoryNavigationTab {
@@ -109,6 +115,8 @@ export interface DorySeo {
   author?: string;
   /** Absolute URL or path resolved against config.url. */
   ogImage?: string;
+  /** Generate a branded PNG for each page at build time. Default: true. */
+  generateSocialImages?: boolean;
   twitterCard?: 'summary' | 'summary_large_image';
   /** e.g. "en_US" */
   locale?: string;
@@ -123,6 +131,40 @@ export interface DoryTheme {
   radius?: string;
 }
 
+/** One entry in the sidebar version picker. */
+export interface DoryVersion {
+  label: string;
+  /** Local docs folder and URL prefix, e.g. "v1" for docs/v1/*.mdx. */
+  id?: string;
+  /** External published site; retained for existing configurations. */
+  url?: string;
+  navigation?: DoryNavigation;
+}
+
+export interface DoryLocale {
+  code: string;
+  label: string;
+  /** Optional translated tab and group labels; page keys remain the same. */
+  navigation?: DoryNavigation;
+  /** Navigation for translated older versions, keyed by version ID. */
+  versions?: Record<string, DoryNavigation>;
+}
+
+export interface DoryI18n {
+  defaultLocale: string;
+  locales: DoryLocale[];
+}
+
+/** Source repository for "Edit this page" and "Report an issue" links. GitHub-style URLs. */
+export interface DoryRepository {
+  /** Repository URL, e.g. "https://github.com/clidey/dory". */
+  url: string;
+  /** Branch the edit link opens. Default: "main". */
+  branch?: string;
+  /** Folder holding the docs inside the repository, e.g. "docs". Default: the repository root. */
+  path?: string;
+}
+
 export interface DoryConfig {
   name: string;
   title?: string;
@@ -132,6 +174,15 @@ export interface DoryConfig {
   url?: string;
   /** Path prefix the site is served under, e.g. "/docs". Default: served at the root. */
   basePath?: string;
+  /** Shown in the sidebar version card, e.g. "1.0.8 · Latest". */
+  version?: string;
+  /** Other published versions; when set, the version card becomes a picker that opens the chosen URL. */
+  versions?: DoryVersion[];
+  /** Place translations in docs/<locale>/ with the same page keys. */
+  i18n?: DoryI18n;
+  /** Name in the footer copyright line. Default: `name`. */
+  copyright?: string;
+  repository?: DoryRepository;
   twitter?: string;
   favicon: string;
   colors?: DoryColors;
@@ -141,5 +192,6 @@ export interface DoryConfig {
   logo: DoryLogo;
   embed?: DoryEmbedConfig;
   analytics?: DoryAnalytics;
+  chat?: { suggestedQuestions?: string[] };
   seo?: DorySeo;
 }

package/src/ui/breadcrumb.tsx

@@ -0,0 +1,17 @@
+/** Mono "Docs / Group / Page" trail above the page title. */
+export function Breadcrumb({ group, title }: { group?: string; title?: string }) {
+  const parts = ['Docs', group, title].filter((part): part is string => Boolean(part))
+
+  return (
+    <nav aria-label="Breadcrumb" className="dory-breadcrumb">
+      <ol className="flex flex-wrap items-center gap-2">
+        {parts.map((part, index) => (
+          <li key={index} className="flex items-center gap-2 whitespace-nowrap" aria-current={index === parts.length - 1 ? 'page' : undefined}>
+            {index > 0 && <span aria-hidden="true">/</span>}
+            <span>{part}</span>
+          </li>
+        ))}
+      </ol>
+    </nav>
+  )
+}

package/src/ui/docs-header-view.tsx

@@ -0,0 +1,32 @@
+import type { ComponentChildren } from 'preact';
+import { Badge } from '@clidey/ux';
+
+export type HeaderTab = { title: string; href: string; active: boolean };
+
+type LinkRenderer = (href: string, className: string, children: ComponentChildren) => ComponentChildren;
+
+/** The top bar shared by static Dory sites and runtime-loaded documentation. */
+export function DocsHeaderView({ name, logo, homeHref, tabs, renderLink, actions, docsLabel = 'Docs', sectionsLabel = 'Sections', homeClassName, embedded = false }: {
+  name: string;
+  logo?: string;
+  homeHref: string;
+  tabs: HeaderTab[];
+  renderLink: LinkRenderer;
+  actions?: ComponentChildren;
+  docsLabel?: string;
+  sectionsLabel?: string;
+  homeClassName?: string;
+  embedded?: boolean;
+}) {
+  return <header className="dory-topbar sticky top-0 z-50 flex h-14 shrink-0 items-stretch bg-[var(--sidebar)] text-white">
+    {renderLink(homeHref, homeClassName ?? 'flex w-60 shrink-0 items-center gap-2.5 px-4', <>
+      {logo && <img data-testid={embedded ? 'embedded-logo' : undefined} src={logo} alt="" className="h-7 w-7" />}
+      <span data-testid={embedded ? 'embedded-site-name' : undefined} className="font-heading text-lg font-bold tracking-tight text-white">{name}</span>
+      <Badge variant="outline" className="dory-docs-pill">{docsLabel}</Badge>
+    </>)}
+    <nav className="hidden md:flex items-stretch" aria-label={sectionsLabel}>
+      {tabs.map(tab => renderLink(tab.href, `dory-topbar-tab${tab.active ? ' active' : ''}`, tab.title))}
+    </nav>
+    <div className="ml-auto flex items-center gap-3 pr-4" data-testid="header-actions">{actions}</div>
+  </header>;
+}

package/src/ui/docs-navigation-view.tsx

@@ -0,0 +1,69 @@
+import classNames from 'classnames';
+import type { ComponentChildren } from 'preact';
+import { useEffect, useRef } from 'preact/hooks';
+import { Badge } from '@clidey/ux';
+import { DORY_REPO_URL, DoryMark } from './dory-mark';
+
+export type NavigationPage = { href: string; title: string; badge?: string; method?: string };
+export type NavigationGroup = { title: string; pages: NavigationPage[] };
+
+const methodTone: Record<string, string> = {
+  GET: 'text-[var(--sidebar-primary)]',
+  POST: 'text-[var(--highlight)]',
+  PUT: 'text-[#f4781c]',
+  PATCH: 'text-[#f4781c]',
+  DEL: 'text-[#ff6668]',
+  PUB: 'text-[#f4781c]',
+  SUB: 'text-[var(--sidebar-primary)]',
+  WS: 'text-[var(--sidebar-primary)]',
+};
+
+type PageLinkRenderer = (page: NavigationPage, className: string, active: boolean, children: ComponentChildren) => ComponentChildren;
+
+/** The navigation tree shared by static Dory sites and runtime-loaded documentation. */
+export function DocsNavigationView({ groups, activeHref, renderPageLink, versionLabel, versionSelect, languageSelect, ariaLabel = 'Documentation', versionCaption = 'Version', footerLabel = 'Built with Dory' }: {
+  groups: NavigationGroup[];
+  activeHref: string;
+  renderPageLink: PageLinkRenderer;
+  versionLabel?: string;
+  versionSelect?: ComponentChildren;
+  languageSelect?: ComponentChildren;
+  ariaLabel?: string;
+  versionCaption?: string;
+  footerLabel?: string;
+}) {
+  const navRef = useRef<HTMLElement>(null);
+  useEffect(() => {
+    const nav = navRef.current;
+    const container = nav?.parentElement;
+    const active = nav?.querySelector('a[aria-current="page"], button[aria-current="page"]');
+    if (!container || !active) return;
+    const item = active.getBoundingClientRect();
+    const viewport = container.getBoundingClientRect();
+    if (item.top < viewport.top) container.scrollTop += item.top - viewport.top;
+    else if (item.bottom > viewport.bottom) container.scrollTop += item.bottom - viewport.bottom;
+  }, [activeHref]);
+
+  return <nav ref={navRef} className="dory-sidebar flex min-h-full flex-col gap-6 text-[13px]" aria-label={ariaLabel}>
+    {versionLabel && <div className="relative flex items-center justify-between rounded-lg border border-white/10 bg-white/5 px-3 py-2.5">
+      <div><p className="dory-mono-label">{versionCaption}</p><p className="mt-0.5 text-sm font-semibold text-white">{versionLabel}</p></div>
+      {versionSelect}
+    </div>}
+    {languageSelect}
+    {groups.map((group, index) => <section key={`${group.title}-${index}`}>
+      <h3 className="dory-mono-label flex gap-2 px-2.5 !text-[var(--sidebar-primary)]">
+        <span>{String(index + 1).padStart(2, '0')}</span><span className="text-white/55">{group.title}</span>
+      </h3>
+      <ul role="list" className="mt-2 space-y-0.5">{group.pages.map(page => {
+        const isActive = activeHref === page.href;
+        const contents = <>
+          {page.method && <span className={classNames('dory-method', methodTone[page.method] ?? 'text-white/60')}>{page.method}</span>}
+          <span className="truncate">{page.title}</span>
+          {page.badge && <Badge variant="secondary" className="dory-badge">{page.badge}</Badge>}
+        </>;
+        return <li key={page.href}>{renderPageLink(page, classNames('dory-sidebar-link', { active: isActive }), isActive, contents)}</li>;
+      })}</ul>
+    </section>)}
+    <a href={DORY_REPO_URL} target="_blank" rel="noopener noreferrer" className="dory-sidebar-footer mt-auto flex items-center gap-2.5 border-t border-white/10 px-2.5 pt-4"><DoryMark className="h-4 w-4" /><span className="dory-mono-label">{footerLabel}</span></a>
+  </nav>;
+}

package/src/ui/docs-page-frame.tsx

@@ -0,0 +1,50 @@
+import type { ComponentChildren } from 'preact';
+import { cn } from '@clidey/ux';
+
+type DocsPageFrameProps = {
+  className?: string;
+  header: ComponentChildren;
+  sidebar?: ComponentChildren;
+  breadcrumb: ComponentChildren;
+  actions?: ComponentChildren;
+  title?: string;
+  lead?: string;
+  meta?: ComponentChildren;
+  content: ComponentChildren;
+  afterContent?: ComponentChildren;
+  toc?: ComponentChildren;
+  embedded?: boolean;
+  wide?: boolean;
+};
+
+/** The page structure shared by a Dory site and its sandboxed app viewer. */
+export function DocsPageFrame({ className, header, sidebar, breadcrumb, actions, title, lead, meta, content, afterContent, toc, embedded = false, wide = false }: DocsPageFrameProps) {
+  return <div className={cn('dory-shell flex min-h-screen w-full flex-col bg-[var(--sidebar)]', className)}>
+    {header}
+    <div className="flex flex-1">
+      {sidebar && <aside className="hidden w-60 shrink-0 lg:block">
+        <div className="sticky top-14 h-[calc(100vh-3.5rem)] overflow-y-auto px-3 pb-6 pt-4">
+          {sidebar}
+        </div>
+      </aside>}
+      <main className={cn('dory-main min-w-0 flex-1 bg-background text-foreground', embedded ? 'p-8' : 'px-6 py-10 sm:px-10 lg:px-12')}>
+        <div className="mx-auto flex w-full max-w-[66rem] justify-center gap-14">
+          <article className={cn('dory-article flex min-w-0 flex-1 flex-col', wide ? 'max-w-[66rem]' : 'max-w-[47rem]')}>
+            <div className="mb-6 flex min-h-9 flex-wrap items-center justify-between gap-4">
+              {breadcrumb}
+              {actions}
+            </div>
+            <header className="mb-10">
+              {title && <h1 className="dory-page-title">{title}</h1>}
+              {lead && <p className="dory-lead">{lead}</p>}
+            </header>
+            {meta}
+            <div className="flex-1 min-h-[calc(100vh-2rem)]">{content}</div>
+            {afterContent}
+          </article>
+          {toc}
+        </div>
+      </main>
+    </div>
+  </div>;
+}

package/src/ui/dory-mark.tsx

@@ -0,0 +1,9 @@
+const mark = "<svg width=\"22\" height=\"24\" viewBox=\"0 0 22 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M21.9941 4.99951C19.9947 3.00079 19.9947 3.00079 16.9956 0.00271368V4.99951H21.9941Z\" fill=\"#92BFFA\"/>\n<path d=\"M7.49782 3.91843C7.49782 4.5155 7.98183 4.99951 8.5789 4.99951H16.9951V0.00271606H8.5789C7.98183 0.00271606 7.49782 0.486733 7.49782 1.0838V3.91843Z\" fill=\"url(#paint0_linear_66_680)\"/>\n<path d=\"M21.9932 5.01123C22.0049 8.20987 21.9983 17.7036 21.9951 21.9995C21.9943 23.1041 21.0977 23.9995 19.9932 23.9995H2C0.895431 23.9995 3.87055e-07 23.1041 0 21.9995V8.59131C0 7.99426 0.48401 7.51028 1.08105 7.51025H3.91797C4.51481 7.51052 4.99902 7.99441 4.99902 8.59131V19.5024H16.9951V5.01123H21.9932Z\" fill=\"url(#paint1_linear_66_680)\"/>\n<ellipse cx=\"12.3217\" cy=\"14.276\" rx=\"1.2973\" ry=\"1.29647\" fill=\"#1967D2\"/>\n<path d=\"M5 0.00634813C5.55157 0.00730227 5.99805 0.454718 5.99805 1.00635V4.01221C5.99805 4.64068 6.29707 5.23179 6.80273 5.60498L7.46777 6.09619C7.81171 6.35003 8.22878 6.48682 8.65625 6.48682H14.4951C15.0472 6.48682 15.4949 6.93475 15.4951 7.48682V16.98C15.4951 17.5322 15.0474 17.98 14.4951 17.98H7.49805C6.94583 17.9799 6.49808 17.5322 6.49805 16.98V8.67139C6.49806 8.23724 6.35689 7.81407 6.0957 7.46729L5.58691 6.79248C5.21558 6.29954 4.63759 6.00515 4.02051 5.99561H1C0.447722 5.9956 0 5.54789 0 4.99561V1.00049C0.000165845 0.447951 0.448441 -4.60729e-05 1.00098 0.00048876L5 0.00634813Z\" fill=\"#FFC236\"/>\n<ellipse cx=\"12.9961\" cy=\"15.505\" rx=\"1\" ry=\"0.999359\" fill=\"#3630C4\"/>\n<defs>\n<linearGradient id=\"paint0_linear_66_680\" x1=\"10.9999\" y1=\"0.00271606\" x2=\"10.9999\" y2=\"23.9995\" gradientUnits=\"userSpaceOnUse\">\n<stop stop-color=\"#528FF4\"/>\n<stop offset=\"1\" stop-color=\"#92BFFA\"/>\n</linearGradient>\n<linearGradient id=\"paint1_linear_66_680\" x1=\"10.9999\" y1=\"0.00271606\" x2=\"10.9999\" y2=\"23.9995\" gradientUnits=\"userSpaceOnUse\">\n<stop stop-color=\"#528FF4\"/>\n<stop offset=\"1\" stop-color=\"#92BFFA\"/>\n</linearGradient>\n</defs>\n</svg>"
+
+/** Dory project page, linked from the "Built with Dory" and "Powered by Dory" credits. */
+export const DORY_REPO_URL = 'https://github.com/clidey/dory'
+
+/** Dory logo mark for the "Built with Dory" footer. */
+export function DoryMark({ className }: { className?: string }) {
+  return <img src={`data:image/svg+xml;utf8,${encodeURIComponent(mark)}`} alt="" className={className} />
+}

package/src/ui/header.tsx

@@ -1,110 +1,53 @@
-import classNames from 'classnames';
-import { useEffect, useMemo, useState } from 'preact/hooks';
+import type { ComponentChildren } from 'preact';
+import { useMemo } from 'preact/hooks';
 import { Link } from 'wouter-preact';
 import { usePathname } from '../components/hooks';
 import docsConfig from '../../docs/dory.json' with { type: 'json' };
 import type { DoryConfig } from '../types/config';
 import { MobileSearch, Search } from '../components/search';
-import { ALL_NAVIGATION } from '../components/store';
+import { getNavigationForPath } from '../components/store';
 import { MobileNavigation } from './mobile-navigation';
 import { ModeToggle } from '@clidey/ux';
 import { useIsEmbedded } from '../components/hooks';
 import { assetUrl } from '../utils/base-path';
+import { DocsHeaderView } from './docs-header-view';
 
 const config = docsConfig as DoryConfig;
 const isThemeForced = config.theme?.mode === 'dark' || config.theme?.mode === 'light';
 
-function TopLevelNavItem({ href, children, isActive }: { href: string; children: string; isActive?: boolean }) {
-  return (
-    <li>
-      <Link
-        to={href}
-        className={classNames(
-          "text-xs transition hover:opacity-80",
-          {
-            "text-brand-foreground": isActive,
-          },
-        )}
-      >
-        {children}
-      </Link>
-    </li>
-  );
-}
-
 /**
- * Site header with logo, top-level navigation, search, and theme toggle.
- *
- * SYNC NOTE: src/entry-server.tsx renders a static SSR copy of this header's
- * structure (the <header> block inside render()). If you change the markup
- * structure here, update entry-server.tsx to match or hydration will mismatch.
+ * Dark top bar: logo and site name with a DOCS pill, one underlined tab per
+ * navigation tab, search with a ⌘K hint, theme toggle and the mobile menu.
+ * With `ssr` the client-only widgets (search, toggle, menu) are left out and
+ * mount during hydration.
  */
-export function Header({ className }: { className?: string }) {
-  const [isScrolled, setIsScrolled] = useState(false);
+export function Header({ ssr = false }: { ssr?: boolean }) {
   const pathname = usePathname();
+  const navigation = getNavigationForPath(pathname);
   const isEmbedded = useIsEmbedded();
-
-  const { light, dark } = useMemo(() => {
-    return { light: assetUrl(config.logo.light), dark: assetUrl(config.logo.dark) };
-  }, []);
-
-  useEffect(() => {
-    function onScroll() {
-      setIsScrolled(window.scrollY > 0);
-    }
-    onScroll();
-    window.addEventListener('scroll', onScroll, { passive: true });
-    return () => {
-      window.removeEventListener('scroll', onScroll);
-    }
-  }, []);
+  const logo = useMemo(() => config.logo?.light ? assetUrl(config.logo.light) : '', []);
+  const renderLink = (href: string, className: string, children: ComponentChildren) =>
+    <Link key={href} href={href} className={className}>{children}</Link>;
 
   return (
-    <header
-      className={classNames(
-        'dory-header sticky top-0 z-50 flex flex-none flex-wrap items-center justify-between px-4 py-5 sm:px-6 lg:px-8 border-b',
-        className,
-        {
-          'backdrop-blur-sm': isScrolled,
-        },
-      )}
-      style={{ backgroundColor: 'var(--background)', borderColor: 'var(--border)' }}
-    >
-      <div className="relative flex justify-between gap-6 sm:gap-8 md:grow items-center w-full px-4">
-        <div className="flex items-center grow gap-2">
-          <img src={light} alt="logo" className="w-8 hidden dark:block" />
-          <img src={dark} alt="logo" className="w-8 block dark:hidden" />
-          <h1 className="text-base lg:text-2xl font-bold">{config.name}</h1>
-        </div>
-        <nav className="hidden md:block">
-          <ul role="list" className="flex items-center gap-8">
-            {ALL_NAVIGATION.map((tab) => {
-              const isActive = tab.groups.some(group =>
-                group.pages.some(page => page.href === pathname)
-              );
-              return (
-                <TopLevelNavItem
-                  key={tab.title}
-                  href={tab.groups[0].pages[0].href}
-                  isActive={isActive}
-                >
-                  {tab.title}
-                </TopLevelNavItem>
-              );
-            })}
-          </ul>
-        </nav>
-        <div className="hidden md:block md:h-5 md:w-px md:bg-zinc-900/10 md:dark:bg-white/15" />
-        <div className="flex items-center gap-3" data-testid="header-actions">
-          <MobileSearch />
-          <Search />
-          {
-            !isEmbedded && !isThemeForced &&
-            <ModeToggle data-testid="mode-toggle" />
-          }
-          <MobileNavigation />
-        </div>
-      </div>
-    </header>
+    <DocsHeaderView name={config.name} logo={logo} homeHref={navigation[0]?.groups[0]?.pages[0]?.href ?? '/'}
+      tabs={navigation.map(tab => ({ title: tab.title, href: tab.groups[0].pages[0].href, active: tab.groups.some(group => group.pages.some(page => page.href === pathname)) }))}
+      renderLink={renderLink}
+      actions={!ssr && (
+          <>
+            <div className="dory-topbar-search relative hidden lg:block">
+              <Search />
+              <kbd className="dory-kbd" aria-hidden="true">⌘K</kbd>
+            </div>
+            <div className="lg:hidden [&_[data-slot=search-input-wrapper]]:w-9 [&_[data-slot=search-input-wrapper]]:border-transparent [&_[data-slot=search-input-wrapper]]:bg-white/8 [&_[data-slot=search-input-wrapper]]:px-2.5 [&_svg]:mr-0 [&_svg]:text-white/70 [&_input]:hidden">
+              <MobileSearch />
+            </div>
+            {!isEmbedded && !isThemeForced && (
+              <span className="dory-mode"><ModeToggle data-testid="mode-toggle" /></span>
+            )}
+            <MobileNavigation />
+          </>
+        )}
+    />
   );
-}
+}