@assistant-ui/docs-theme 0.0.0 → 0.0.3

package/src/site/layout.tsx

@@ -0,0 +1,33 @@
+import type { ReactNode } from "react";
+import { DOCS_SIDEBAR_WIDTH } from "./constants";
+
+export function DocsShell({ children }: { children: ReactNode }): ReactNode {
+  return (
+    <div
+      className="docs-shell"
+      style={
+        {
+          "--sidebar-width": `${DOCS_SIDEBAR_WIDTH}px`,
+        } as React.CSSProperties
+      }
+    >
+      {children}
+    </div>
+  );
+}
+
+export function DocsContent({ children }: { children: ReactNode }): ReactNode {
+  return (
+    <div
+      data-docs-content=""
+      className="@container md:ml-(--sidebar-width)"
+      style={
+        {
+          "--sidebar-width": `${DOCS_SIDEBAR_WIDTH}px`,
+        } as React.CSSProperties
+      }
+    >
+      {children}
+    </div>
+  );
+}

package/src/site/page.tsx

@@ -0,0 +1,38 @@
+import type { ComponentProps, ReactNode } from "react";
+import { cn } from "./utils";
+
+export function DocsPageShell({
+  toc,
+  footer,
+  children,
+  mainProps,
+}: {
+  toc?: ReactNode;
+  footer?: ReactNode;
+  children: ReactNode;
+  mainProps?: Omit<ComponentProps<"main">, "children">;
+}) {
+  return (
+    <div className="docs-layout">
+      <main
+        {...mainProps}
+        className={cn(
+          "mx-auto w-full max-w-(--docs-article-width) justify-self-center px-4 pt-4 pb-10 md:px-6",
+          mainProps?.className,
+        )}
+      >
+        {children}
+      </main>
+      {toc}
+      {footer && (
+        <footer className="mx-auto w-full max-w-(--docs-article-width) justify-self-center px-4 pb-10 md:px-6">
+          <div className="border-t pt-6">{footer}</div>
+        </footer>
+      )}
+    </div>
+  );
+}
+
+export function DocsBody({ className, ...props }: ComponentProps<"article">) {
+  return <article {...props} className={cn("docs-prose prose", className)} />;
+}

package/src/site/pager.tsx

@@ -0,0 +1,54 @@
+import Link from "next/link";
+import type { ReactNode } from "react";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+
+const pagerLabel = (direction: "Previous" | "Next", name: ReactNode) =>
+  typeof name === "string" && name !== ""
+    ? `${direction}: ${name}`
+    : `${direction} page`;
+
+export function DocsPagerNavigation({
+  previous,
+  next,
+  children,
+}: {
+  previous?: { url: string; name?: ReactNode } | undefined;
+  next?: { url: string; name?: ReactNode } | undefined;
+  children?: ReactNode;
+}) {
+  const buttonClass =
+    "flex size-7 items-center justify-center rounded-md bg-muted/50 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground sm:size-8";
+  const disabledClass =
+    "flex size-7 items-center justify-center rounded-md bg-muted/30 text-muted-foreground/40 cursor-not-allowed sm:size-8";
+  return (
+    <div className="flex items-center gap-1">
+      {previous ? (
+        <Link
+          href={previous.url}
+          className={buttonClass}
+          aria-label={pagerLabel("Previous", previous.name)}
+        >
+          <ChevronLeft className="size-4" />
+        </Link>
+      ) : (
+        <div className={disabledClass}>
+          <ChevronLeft className="size-4" />
+        </div>
+      )}
+      {next ? (
+        <Link
+          href={next.url}
+          className={buttonClass}
+          aria-label={pagerLabel("Next", next.name)}
+        >
+          <ChevronRight className="size-4" />
+        </Link>
+      ) : (
+        <div className={disabledClass}>
+          <ChevronRight className="size-4" />
+        </div>
+      )}
+      {children}
+    </div>
+  );
+}

package/src/site/sidebar-navigation.test.tsx

@@ -0,0 +1,92 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, expect, it, vi } from "vitest";
+import { DocsSidebarNavigation } from "./sidebar-navigation";
+import type { DocsFolder } from "./tree";
+
+const sections: DocsFolder[] = [
+  {
+    type: "folder",
+    $id: "start",
+    name: "Getting started",
+    children: [
+      { type: "page", $id: "intro", name: "Overview", url: "/docs" },
+      {
+        type: "folder",
+        $id: "install",
+        name: "Install",
+        index: { type: "page", name: "Install", url: "/docs/install" },
+        children: [
+          {
+            type: "page",
+            $id: "next",
+            name: "Next.js",
+            url: "/docs/install/next",
+          },
+          { type: "page", $id: "vue", name: "Vue", url: "/docs/install/vue" },
+        ],
+      },
+    ],
+  },
+  {
+    type: "folder",
+    $id: "guides",
+    name: "Guides",
+    children: [
+      { type: "page", $id: "tools", name: "Tools", url: "/docs/tools" },
+    ],
+  },
+];
+
+afterEach(() => vi.unstubAllGlobals());
+
+it("opens the active hierarchy, filters host-specific pages, and follows route changes after manual collapse", async () => {
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  const container = document.createElement("div");
+  document.body.append(container);
+  const root = createRoot(container);
+  const onNavigate = vi.fn();
+  const render = (pathname: string, activeSectionId: string) =>
+    act(async () => {
+      root.render(
+        <DocsSidebarNavigation
+          sections={sections}
+          pathname={pathname}
+          activeSectionId={activeSectionId}
+          isVisible={(node) => node.$id !== "vue"}
+          onNavigate={onNavigate}
+        />,
+      );
+    });
+  try {
+    await render("/docs/install/next", "start");
+    expect(container.querySelector('[data-active="true"]')?.textContent).toBe(
+      "Next.js",
+    );
+    expect(container.textContent).not.toContain("Vue");
+    expect(container.querySelector('a[href="/docs/tools"]')).toBeNull();
+    const section = container.querySelector<HTMLButtonElement>("button")!;
+    await act(async () => section.click());
+    expect(section.getAttribute("aria-expanded")).toBe("false");
+    await render("/docs/install", "start");
+    expect(section.getAttribute("aria-expanded")).toBe("true");
+    expect(container.querySelector('[data-active="true"]')?.textContent).toBe(
+      "Install",
+    );
+    await render("/docs/tools", "guides");
+    expect(
+      container.querySelectorAll("button")[1]?.getAttribute("aria-expanded"),
+    ).toBe("true");
+    const link = container.querySelector<HTMLAnchorElement>(
+      'a[href="/docs/tools"]',
+    )!;
+    link.addEventListener("click", (event) => event.preventDefault());
+    await act(async () => link.click());
+    expect(onNavigate).toHaveBeenCalledOnce();
+  } finally {
+    await act(async () => root.unmount());
+    container.remove();
+  }
+});

package/src/site/sidebar-navigation.tsx

@@ -0,0 +1,267 @@
+"use client";
+
+import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import Link from "next/link";
+import type { DocsNode, DocsFolder } from "./tree";
+import { findActivePath } from "./tree";
+import { ChevronDown } from "lucide-react";
+import { AnimatePresence, domAnimation, LazyMotion } from "motion/react";
+import * as m from "motion/react-m";
+import { cn } from "./utils";
+
+function SectionItem({
+  item,
+  onNavigate,
+  pathname,
+  activePath,
+  isVisible,
+}: {
+  item: DocsNode;
+  onNavigate: () => void;
+  pathname: string;
+  activePath: ReadonlySet<DocsNode>;
+  isVisible: (node: DocsNode) => boolean;
+}) {
+  if (!isVisible(item)) return null;
+
+  if (item.type === "separator") {
+    return (
+      <p className="text-muted-foreground mt-4 mb-1 px-2 text-xs font-medium first:mt-1">
+        {item.name}
+      </p>
+    );
+  }
+
+  if (item.type === "folder") {
+    const isActive = item.index && pathname === item.index.url;
+    const containsActive = activePath.has(item);
+    const hasChildren = item.children.length > 0;
+
+    return (
+      <div>
+        {item.index ? (
+          <Link
+            href={item.index.url}
+            onClick={onNavigate}
+            data-active={isActive ? "true" : "false"}
+            className={cn(
+              "flex items-center gap-2 rounded-md px-2 py-1.5 text-[13px] transition-colors duration-150",
+              isActive
+                ? "bg-accent/20 text-foreground dark:bg-accent/50 font-medium"
+                : "text-muted-foreground hover:bg-accent/30 hover:text-foreground/90 dark:hover:bg-accent/40",
+            )}
+          >
+            {item.icon}
+            <span className="truncate">{item.name}</span>
+          </Link>
+        ) : (
+          <p className="text-muted-foreground mt-3 mb-1 flex items-center gap-2 px-2 text-xs font-medium first:mt-1">
+            {item.icon}
+            {item.name}
+          </p>
+        )}
+        {hasChildren && (containsActive || !item.index) && (
+          <div className="border-border/50 ml-2 flex flex-col gap-0.5 border-l pl-2">
+            {item.children.map((child) => (
+              <SectionItem
+                key={child.$id}
+                item={child}
+                onNavigate={onNavigate}
+                pathname={pathname}
+                activePath={activePath}
+                isVisible={isVisible}
+              />
+            ))}
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  const isActive = pathname === item.url;
+  return (
+    <Link
+      href={item.url}
+      onClick={onNavigate}
+      data-active={isActive ? "true" : "false"}
+      className={cn(
+        "flex items-center gap-2 rounded-md px-2 py-1.5 text-[13px] transition-colors duration-150",
+        isActive
+          ? "bg-accent/20 text-foreground dark:bg-accent/50 font-medium"
+          : "text-muted-foreground hover:bg-accent/30 hover:text-foreground/90 dark:hover:bg-accent/40",
+      )}
+    >
+      {item.icon}
+      <span className="truncate">{item.name}</span>
+    </Link>
+  );
+}
+
+function SidebarSection({
+  folder,
+  isOpen,
+  onToggle,
+  onNavigate,
+  pathname,
+  activePath,
+  isVisible,
+}: {
+  folder: DocsFolder;
+  isOpen: boolean;
+  onToggle: () => void;
+  onNavigate: () => void;
+  pathname: string;
+  activePath: ReadonlySet<DocsNode>;
+  isVisible: (node: DocsNode) => boolean;
+}) {
+  const isActive = folder.index && pathname === folder.index.url;
+
+  return (
+    <div>
+      <button
+        type="button"
+        onClick={onToggle}
+        aria-expanded={isOpen}
+        className={cn(
+          "hover:bg-accent/30 dark:hover:bg-accent/40 flex w-full items-center gap-2 rounded-md px-2 py-2 text-left text-[13px] transition-colors duration-150",
+          isActive || isOpen
+            ? "text-foreground font-medium"
+            : "text-muted-foreground/90",
+        )}
+      >
+        <span className="text-muted-foreground flex size-4 shrink-0 items-center justify-center">
+          {folder.icon}
+        </span>
+        <span className="flex-1 truncate">{folder.name}</span>
+        <ChevronDown
+          className={cn(
+            "text-muted-foreground/60 size-3.5 shrink-0 transition-transform duration-200",
+            !isOpen && "-rotate-90",
+          )}
+        />
+      </button>
+      <AnimatePresence initial={false}>
+        {isOpen && (
+          <m.div
+            initial={{ height: 0, opacity: 0 }}
+            animate={{ height: "auto", opacity: 1 }}
+            exit={{ height: 0, opacity: 0 }}
+            transition={{ duration: 0.22, ease: [0.16, 1, 0.3, 1] }}
+            className="overflow-hidden"
+          >
+            <div className="border-border/50 mt-0.5 mb-1 ml-4 flex flex-col gap-0.5 border-l pl-2">
+              {folder.children.map((child) => (
+                <SectionItem
+                  key={child.$id}
+                  item={child}
+                  onNavigate={onNavigate}
+                  pathname={pathname}
+                  activePath={activePath}
+                  isVisible={isVisible}
+                />
+              ))}
+            </div>
+          </m.div>
+        )}
+      </AnimatePresence>
+    </div>
+  );
+}
+
+const visible = () => true;
+
+export function DocsSidebarNavigation({
+  sections,
+  pathname,
+  activeSectionId,
+  isVisible = visible,
+  onNavigate,
+  banner,
+  footer,
+  platform,
+}: {
+  sections: readonly DocsFolder[];
+  pathname: string;
+  activeSectionId: string | null;
+  isVisible?: (node: DocsNode) => boolean;
+  onNavigate: () => void;
+  banner?: ReactNode;
+  footer?: ReactNode;
+  platform?: string;
+}) {
+  const navRef = useRef<HTMLElement>(null);
+  const activePath = useMemo(
+    () => new Set(findActivePath(sections, pathname)),
+    [sections, pathname],
+  );
+
+  const [openSectionId, setOpenSectionId] = useState<string | null>(
+    activeSectionId,
+  );
+
+  const [sectionScope, setSectionScope] = useState({
+    activeSectionId,
+    pathname,
+  });
+
+  if (
+    sectionScope.activeSectionId !== activeSectionId ||
+    sectionScope.pathname !== pathname
+  ) {
+    setSectionScope({ activeSectionId, pathname });
+    if (activeSectionId) setOpenSectionId(activeSectionId);
+  }
+
+  useEffect(() => {
+    if (openSectionId !== activeSectionId) return;
+    const timer = setTimeout(() => {
+      const nav = navRef.current;
+      if (!nav) return;
+      const active = nav.querySelector<HTMLElement>("[data-active='true']");
+      if (!active) return;
+      const navRect = nav.getBoundingClientRect();
+      const elRect = active.getBoundingClientRect();
+      if (elRect.top < navRect.top || elRect.bottom > navRect.bottom) {
+        active.scrollIntoView({ block: "center", behavior: "smooth" });
+      }
+    }, 260);
+    return () => clearTimeout(timer);
+  }, [pathname, openSectionId, activeSectionId]);
+
+  return (
+    <div className="flex h-full flex-col">
+      {banner && <div className="shrink-0 px-3 pt-4 lg:hidden">{banner}</div>}
+      <nav
+        aria-label="Docs"
+        ref={navRef}
+        data-docs-platform={platform}
+        className={cn(
+          "sidebar-tree-content flex min-h-0 flex-1 flex-col gap-0.5 overflow-x-hidden overflow-y-auto px-3 pt-2 pb-4 lg:pt-4",
+        )}
+      >
+        <LazyMotion features={domAnimation}>
+          {sections.map((section) => (
+            <SidebarSection
+              key={section.$id}
+              folder={section}
+              isOpen={openSectionId === section.$id}
+              onToggle={() => {
+                const id = section.$id ?? null;
+                setOpenSectionId(openSectionId !== id ? id : null);
+              }}
+              onNavigate={onNavigate}
+              pathname={pathname}
+              activePath={activePath}
+              isVisible={isVisible}
+            />
+          ))}
+        </LazyMotion>
+      </nav>
+      {footer && (
+        <div className="border-border/50 flex shrink-0 items-center gap-1 border-t px-3 py-2">
+          {footer}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/site/sidebar.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useState,
+  useSyncExternalStore,
+  type ReactNode,
+} from "react";
+import { cn } from "./utils";
+import { DOCS_SIDEBAR_WIDTH } from "./constants";
+
+export const DOCS_SIDEBAR_ID = "docs-sidebar";
+
+const subscribeToViewport = (onChange: () => void) => {
+  const viewport = window.matchMedia("(max-width: 767px)");
+  viewport.addEventListener("change", onChange);
+  return () => viewport.removeEventListener("change", onChange);
+};
+const isMobileViewport = () => window.innerWidth < 768;
+const serverViewport = () => false;
+
+interface DocsSidebarContextValue {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  toggle: () => void;
+}
+
+const DocsSidebarContext = createContext<DocsSidebarContextValue | null>(null);
+
+export function useDocsSidebar() {
+  const ctx = useContext(DocsSidebarContext);
+  if (!ctx) {
+    throw new Error("useDocsSidebar must be used within DocsSidebarProvider");
+  }
+  return ctx;
+}
+
+export function DocsSidebarProvider({ children }: { children: ReactNode }) {
+  const [open, setOpen] = useState(false);
+  const toggle = useCallback(() => setOpen((prev) => !prev), []);
+
+  return (
+    <DocsSidebarContext.Provider value={{ open, setOpen, toggle }}>
+      {children}
+    </DocsSidebarContext.Provider>
+  );
+}
+
+export function DocsSidebar({ children }: { children: ReactNode }) {
+  const { open } = useDocsSidebar();
+  const isMobile = useSyncExternalStore(
+    subscribeToViewport,
+    isMobileViewport,
+    serverViewport,
+  );
+
+  return (
+    <aside
+      id={DOCS_SIDEBAR_ID}
+      inert={!open && isMobile}
+      className={cn(
+        "bg-background fixed inset-x-0 top-12 bottom-0 z-40 transition-[opacity,visibility] duration-200",
+        open ? "opacity-100" : "pointer-events-none opacity-0 max-md:invisible",
+        "md:pointer-events-auto md:visible md:right-auto md:left-0 md:z-30 md:w-(--sidebar-width) md:opacity-100",
+      )}
+      style={
+        {
+          "--sidebar-width": `${DOCS_SIDEBAR_WIDTH}px`,
+        } as React.CSSProperties
+      }
+    >
+      {children}
+    </aside>
+  );
+}