@dsbasko/cookbook-engine 0.1.0

package/src/components/Sidebar/Sidebar.module.css

@@ -0,0 +1,157 @@
+.sidebar {
+  width: var(--layout-sidebar-width);
+  /* Fixed viewport height so the flex parent doesn't stretch the column to
+     document height — otherwise the footer icons end up far below the fold. */
+  height: 100dvh;
+  align-self: flex-start;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-4) 0;
+  background-color: var(--bg-default);
+  border-right: 1px solid var(--bg-stroke);
+  position: sticky;
+  top: 0;
+  z-index: 10;
+}
+
+.nav {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+  width: 100%;
+  align-items: center;
+}
+
+.footer {
+  margin-top: auto;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+  width: 100%;
+  align-items: center;
+}
+
+.button {
+  width: 36px;
+  height: 36px;
+  display: grid;
+  place-items: center;
+  border: 1px solid transparent;
+  background: transparent;
+  color: var(--content-secondary);
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  transition:
+    color 120ms ease,
+    background-color 120ms ease,
+    border-color 120ms ease;
+}
+
+.button svg {
+  width: 18px;
+  height: 18px;
+}
+
+.button:hover {
+  background-color: var(--bg-subtle);
+  color: var(--content-primary);
+}
+
+.button:focus-visible {
+  outline: 2px solid var(--accent-main);
+  outline-offset: 2px;
+}
+
+.button[aria-current='page'],
+.button[aria-expanded='true'] {
+  color: var(--content-primary);
+  background-color: var(--bg-subtle);
+  border-color: var(--bg-stroke);
+}
+
+/* Mobile: the sidebar becomes a transparent top-of-viewport band carrying
+   two floating action buttons — settings on the left, program on the right.
+   Home and GitHub are demoted to inside the ProgramDrawer (they used to sit
+   in the bottom dock that this file replaces). A vertical gradient fades
+   the default background into transparency so the icons stay legible over
+   any prose without painting a solid stripe across the top. */
+@media (max-width: 1023px) {
+  .sidebar {
+    position: fixed;
+    inset: 0 0 auto 0;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: auto;
+    transform: none;
+    width: auto;
+    height: auto;
+    min-height: 0;
+    padding: max(env(safe-area-inset-top), var(--space-2)) var(--space-4) var(--space-6);
+    flex-direction: row;
+    justify-content: space-between;
+    align-items: flex-start;
+    gap: 0;
+    background: transparent;
+    border: 0;
+    border-radius: 0;
+    box-shadow: none;
+    backdrop-filter: none;
+    -webkit-backdrop-filter: none;
+    z-index: var(--z-header);
+    pointer-events: none;
+  }
+
+  .nav,
+  .footer {
+    flex-direction: row;
+    width: auto;
+    gap: var(--space-2);
+    margin: 0;
+    pointer-events: auto;
+  }
+
+  /* Settings (left) is the first visual slot, Program (right) the second.
+     Flex order flips .footer ahead of .nav without changing the JSX so
+     ARIA/focus order continues to read Home → Program → Settings → GitHub
+     on desktop. */
+  .footer {
+    order: 1;
+  }
+
+  .nav {
+    order: 2;
+  }
+
+  /* Hide Home (Link) and GitHub (anchor) on mobile — their destinations
+     live inside the program overlay now. .button is the shared FAB class,
+     and only Links/anchors carry it on these spots; the program <button>
+     stays visible. */
+  .nav > a.button,
+  .footer > a.button {
+    display: none;
+  }
+
+  .button {
+    width: 44px;
+    height: 44px;
+    border-radius: 999px;
+    background-color: var(--bg-surface);
+    border: 1px solid var(--bg-stroke);
+    box-shadow: var(--shadow-sm);
+  }
+
+  .button svg {
+    width: 20px;
+    height: 20px;
+  }
+
+  .button[aria-current='page'],
+  .button[aria-expanded='true'] {
+    background-color: var(--content-primary);
+    color: var(--bg-default);
+    border-color: var(--content-primary);
+  }
+}

package/src/components/Sidebar/Sidebar.tsx

@@ -0,0 +1,63 @@
+'use client';
+
+import Link from 'next/link';
+import { usePathname } from 'next/navigation';
+import { SettingsToggle } from '@/components/SettingsToggle';
+import { stripLangFromPath } from '@/lib/lang';
+import { useLang, useT } from '@/lib/use-i18n';
+import { HomeIcon, ProgramIcon, GitHubIcon } from './icons';
+import styles from './Sidebar.module.css';
+
+type SidebarProps = {
+  onProgramClick: () => void;
+  isProgramOpen: boolean;
+  repoUrl: string;
+};
+
+export function Sidebar({ onProgramClick, isProgramOpen, repoUrl }: SidebarProps) {
+  const pathname = usePathname() ?? '/';
+  const lang = useLang();
+  const { rest } = stripLangFromPath(pathname);
+  const isHome = rest === '/' || pathname === '/';
+  const t = useT();
+  return (
+    <aside className={styles.sidebar} aria-label={t.sidebarLabel}>
+      <nav className={styles.nav} aria-label={t.navMainLabel}>
+        <Link
+          href={`/${lang}`}
+          className={styles.button}
+          aria-label={t.home}
+          title={t.home}
+          aria-current={isHome ? 'page' : undefined}
+        >
+          <HomeIcon />
+        </Link>
+        <button
+          type="button"
+          className={styles.button}
+          aria-label={t.programCourse}
+          title={t.programCourse}
+          aria-haspopup="dialog"
+          aria-expanded={isProgramOpen}
+          onClick={onProgramClick}
+        >
+          <ProgramIcon />
+        </button>
+      </nav>
+
+      <div className={styles.footer}>
+        <SettingsToggle repoUrl={repoUrl} />
+        <a
+          className={styles.button}
+          href={repoUrl}
+          target="_blank"
+          rel="noreferrer noopener"
+          aria-label={t.githubRepo}
+          title={t.githubRepo}
+        >
+          <GitHubIcon />
+        </a>
+      </div>
+    </aside>
+  );
+}

package/src/components/Sidebar/icons/GitHubIcon.tsx

@@ -0,0 +1,17 @@
+import type { SVGProps } from 'react';
+
+export function GitHubIcon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="currentColor"
+      aria-hidden="true"
+      focusable="false"
+      {...props}
+    >
+      <path d="M12 2a10 10 0 0 0-3.16 19.49c.5.09.68-.22.68-.48v-1.7c-2.78.6-3.37-1.34-3.37-1.34-.45-1.16-1.11-1.47-1.11-1.47-.91-.62.07-.61.07-.61 1 .07 1.53 1.03 1.53 1.03.89 1.53 2.34 1.09 2.91.83.09-.65.35-1.09.63-1.34-2.22-.25-4.55-1.11-4.55-4.94 0-1.09.39-1.98 1.03-2.68-.1-.25-.45-1.27.1-2.65 0 0 .84-.27 2.75 1.02a9.5 9.5 0 0 1 5 0c1.91-1.29 2.75-1.02 2.75-1.02.55 1.38.2 2.4.1 2.65.64.7 1.03 1.59 1.03 2.68 0 3.84-2.34 4.69-4.57 4.93.36.31.68.92.68 1.85v2.74c0 .27.18.58.69.48A10 10 0 0 0 12 2z" />
+    </svg>
+  );
+}

package/src/components/Sidebar/icons/HomeIcon.tsx

@@ -0,0 +1,22 @@
+import type { SVGProps } from 'react';
+
+export function HomeIcon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.6"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      focusable="false"
+      {...props}
+    >
+      <path d="M3 12 12 4l9 8" />
+      <path d="M5 10v10h14V10" />
+    </svg>
+  );
+}

package/src/components/Sidebar/icons/LanguageIcon.tsx

@@ -0,0 +1,24 @@
+import type { SVGProps } from 'react';
+
+export function LanguageIcon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.6"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      focusable="false"
+      {...props}
+    >
+      <circle cx="12" cy="12" r="9" />
+      <path d="M3 12h18" />
+      <path d="M12 3a14 14 0 0 1 0 18" />
+      <path d="M12 3a14 14 0 0 0 0 18" />
+    </svg>
+  );
+}

package/src/components/Sidebar/icons/ProgramIcon.tsx

@@ -0,0 +1,23 @@
+import type { SVGProps } from 'react';
+
+export function ProgramIcon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.6"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      focusable="false"
+      {...props}
+    >
+      <path d="M4 6h16" />
+      <path d="M4 12h16" />
+      <path d="M4 18h10" />
+    </svg>
+  );
+}

package/src/components/Sidebar/icons/SettingsIcon.tsx

@@ -0,0 +1,26 @@
+import type { SVGProps } from 'react';
+
+export function SettingsIcon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      width="18"
+      height="18"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.6"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      focusable="false"
+      {...props}
+    >
+      <path d="M4 6h7M15 6h5" />
+      <path d="M4 12h3M11 12h9" />
+      <path d="M4 18h12M20 18h0" />
+      <circle cx="13" cy="6" r="2" />
+      <circle cx="9" cy="12" r="2" />
+      <circle cx="18" cy="18" r="2" />
+    </svg>
+  );
+}

package/src/components/Sidebar/icons/ThemeIcon.tsx

@@ -0,0 +1,22 @@
+import type { SVGProps } from 'react';
+
+export function ThemeIcon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.6"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      focusable="false"
+      {...props}
+    >
+      <circle cx="12" cy="12" r="4" />
+      <path d="M12 2v2M12 20v2M2 12h2M20 12h2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4" />
+    </svg>
+  );
+}

package/src/components/Sidebar/icons/index.ts

@@ -0,0 +1,6 @@
+export { HomeIcon } from './HomeIcon';
+export { ProgramIcon } from './ProgramIcon';
+export { ThemeIcon } from './ThemeIcon';
+export { GitHubIcon } from './GitHubIcon';
+export { LanguageIcon } from './LanguageIcon';
+export { SettingsIcon } from './SettingsIcon';

package/src/components/Sidebar/index.ts

@@ -0,0 +1 @@
+export { Sidebar } from './Sidebar';

package/src/components/ThemeProvider/ThemeProvider.tsx

@@ -0,0 +1,68 @@
+'use client';
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useState,
+  type ReactNode,
+} from 'react';
+import {
+  applyResolvedTheme,
+  readStoredPreference,
+  THEME_STORAGE_KEY,
+  type ResolvedTheme,
+  type ThemePreference,
+} from '@/lib/theme';
+
+type ThemeContextValue = {
+  preference: ThemePreference;
+  resolvedTheme: ResolvedTheme;
+  setPreference: (next: ThemePreference) => void;
+};
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const [preference, setPreferenceState] = useState<ThemePreference>('light');
+
+  useEffect(() => {
+    setPreferenceState(readStoredPreference());
+  }, []);
+
+  useEffect(() => {
+    function handleStorage(event: StorageEvent) {
+      if (event.key !== THEME_STORAGE_KEY) return;
+      const next = readStoredPreference();
+      setPreferenceState(next);
+      applyResolvedTheme(next);
+    }
+    window.addEventListener('storage', handleStorage);
+    return () => window.removeEventListener('storage', handleStorage);
+  }, []);
+
+  const setPreference = useCallback((next: ThemePreference) => {
+    setPreferenceState(next);
+    try {
+      window.localStorage.setItem(THEME_STORAGE_KEY, next);
+    } catch {
+      /* ignore */
+    }
+    applyResolvedTheme(next);
+  }, []);
+
+  return (
+    <ThemeContext.Provider value={{ preference, resolvedTheme: preference, setPreference }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+export function useTheme(): ThemeContextValue {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) {
+    throw new Error('useTheme must be used inside <ThemeProvider>');
+  }
+  return ctx;
+}

package/src/components/ThemeProvider/index.ts

@@ -0,0 +1 @@
+export { ThemeProvider, useTheme } from './ThemeProvider';

package/src/components/Toc/Toc.module.css

@@ -0,0 +1,78 @@
+.toc {
+  font-size: 13px;
+  line-height: var(--line-height-snug);
+  color: var(--content-tertiary);
+}
+
+.heading {
+  margin: 0 0 var(--space-3) 0;
+  font-family: var(--font-mono), ui-monospace, monospace;
+  font-size: 12px;
+  font-weight: var(--font-weight-regular);
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--content-tertiary);
+}
+
+.list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+}
+
+.item {
+  margin: 0;
+  padding: 0;
+}
+
+.item[data-depth='3'] {
+  padding-left: var(--space-3);
+}
+
+.link {
+  display: grid;
+  grid-template-columns: 16px 1fr;
+  align-items: center;
+  gap: var(--space-2);
+  padding: 6px 0;
+  text-decoration: none;
+  color: var(--content-tertiary);
+  font-size: 13px;
+  line-height: 1.35;
+  transition: color 120ms ease;
+}
+
+.link:hover {
+  color: var(--content-secondary);
+}
+
+.marker {
+  width: 8px;
+  height: 1px;
+  background: var(--bg-stroke-strong);
+  transition: width 180ms ease, height 180ms ease, background-color 180ms ease;
+}
+
+.label {
+  min-width: 0;
+}
+
+.item[data-active='true'] > .link {
+  color: var(--content-primary);
+  font-weight: var(--font-weight-semibold);
+}
+
+.item[data-active='true'] .marker {
+  width: 14px;
+  height: 2px;
+  background: var(--accent-main);
+}
+
+.link:focus-visible {
+  outline: 2px solid var(--accent-main);
+  outline-offset: 2px;
+  border-radius: var(--radius-sm);
+}

package/src/components/Toc/Toc.tsx

@@ -0,0 +1,92 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import type { TocEntry } from '@/lib/extract-toc';
+import { useT } from '@/lib/use-i18n';
+import styles from './Toc.module.css';
+
+type TocProps = {
+  entries: TocEntry[];
+};
+
+const OBSERVER_OPTIONS: IntersectionObserverInit = {
+  // Trigger when a heading enters the top quarter of the viewport.
+  rootMargin: '-80px 0px -70% 0px',
+  threshold: [0, 1],
+};
+
+export function Toc({ entries }: TocProps) {
+  const t = useT();
+  const [activeSlug, setActiveSlug] = useState<string | null>(
+    entries.length > 0 ? entries[0].slug : null,
+  );
+
+  useEffect(() => {
+    if (entries.length === 0) return;
+    if (typeof window === 'undefined' || typeof IntersectionObserver === 'undefined') {
+      return;
+    }
+
+    const elements = entries
+      .map((entry) => document.getElementById(entry.slug))
+      .filter((el): el is HTMLElement => el !== null);
+
+    if (elements.length === 0) return;
+
+    const visibleSlugs = new Set<string>();
+    const observer = new IntersectionObserver((records) => {
+      for (const r of records) {
+        if (r.isIntersecting) visibleSlugs.add(r.target.id);
+        else visibleSlugs.delete(r.target.id);
+      }
+      const firstVisible = entries.find((e) => visibleSlugs.has(e.slug));
+      if (firstVisible) {
+        setActiveSlug(firstVisible.slug);
+      }
+    }, OBSERVER_OPTIONS);
+
+    for (const el of elements) observer.observe(el);
+    return () => observer.disconnect();
+  }, [entries]);
+
+  if (entries.length === 0) return null;
+
+  const handleClick = (slug: string) => (event: React.MouseEvent<HTMLAnchorElement>) => {
+    const target = document.getElementById(slug);
+    if (!target) return;
+    event.preventDefault();
+    target.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    if (typeof window !== 'undefined' && window.history?.replaceState) {
+      window.history.replaceState(null, '', `#${slug}`);
+    }
+    setActiveSlug(slug);
+  };
+
+  return (
+    <nav className={styles.toc} aria-label={t.tocLabel}>
+      <p className={styles.heading}>/ contents</p>
+      <ol className={styles.list}>
+        {entries.map((entry) => {
+          const isActive = entry.slug === activeSlug;
+          return (
+            <li
+              key={entry.slug}
+              className={styles.item}
+              data-depth={entry.depth}
+              data-active={isActive ? 'true' : 'false'}
+            >
+              <a
+                href={`#${entry.slug}`}
+                className={styles.link}
+                onClick={handleClick(entry.slug)}
+              >
+                <span className={styles.marker} aria-hidden="true" />
+                <span className={styles.label}>{entry.text}</span>
+              </a>
+            </li>
+          );
+        })}
+      </ol>
+    </nav>
+  );
+}

package/src/components/Toc/index.ts

@@ -0,0 +1 @@
+export { Toc } from './Toc';

package/src/components/TranslationBanner/TranslationBanner.module.css

@@ -0,0 +1,32 @@
+.banner {
+  margin: 0 0 var(--space-6);
+  padding: var(--space-4) var(--space-5);
+  border-left: 3px solid var(--accent-notice);
+  border-radius: var(--radius-md);
+  background-color: var(--accent-notice-soft);
+  color: var(--content-primary);
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  margin-bottom: var(--space-2);
+  color: var(--accent-notice);
+  font-weight: var(--font-weight-semibold);
+}
+
+.icon {
+  flex-shrink: 0;
+}
+
+.title {
+  font-size: var(--font-size-sm);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.body {
+  margin: 0;
+  color: var(--content-primary);
+}

package/src/components/TranslationBanner/TranslationBanner.tsx

@@ -0,0 +1,40 @@
+import { getDict } from '@/lib/i18n';
+import type { Lang } from '@/lib/lang';
+import styles from './TranslationBanner.module.css';
+
+type TranslationBannerProps = {
+  lang: Lang;
+};
+
+export function TranslationBanner({ lang }: TranslationBannerProps) {
+  const t = getDict(lang);
+  return (
+    <aside
+      className={styles.banner}
+      data-translation-banner
+      role="note"
+      aria-label={t.translationFallbackTitle}
+    >
+      <header className={styles.header}>
+        <GlobeIcon className={styles.icon} aria-hidden="true" />
+        <span className={styles.title}>{t.translationFallbackTitle}</span>
+      </header>
+      <p className={styles.body}>{t.translationFallbackBody}</p>
+    </aside>
+  );
+}
+
+function GlobeIcon(props: React.SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      viewBox="0 0 16 16"
+      width="16"
+      height="16"
+      fill="currentColor"
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path d="M8 0a8 8 0 1 0 0 16A8 8 0 0 0 8 0Zm5.93 7.25h-2.486a13.18 13.18 0 0 0-.66-3.61 6.52 6.52 0 0 1 3.146 3.61ZM8 1.5c.78 0 1.86 1.5 2.32 4.25H5.68C6.14 3 7.22 1.5 8 1.5ZM1.55 8.75H4.05c.06 1.23.28 2.44.65 3.61A6.52 6.52 0 0 1 1.55 8.75Zm0-1.5a6.52 6.52 0 0 1 3.15-3.61c-.37 1.17-.59 2.38-.65 3.61H1.55Zm4.13 1.5h4.64C9.86 11.5 8.78 13 8 13s-1.86-1.5-2.32-3.25Zm0-1.5c.46-2.75 1.54-4.25 2.32-4.25s1.86 1.5 2.32 4.25H5.68Zm5.76 4.86c.37-1.17.59-2.38.66-3.61h2.49a6.52 6.52 0 0 1-3.15 3.61Z" />
+    </svg>
+  );
+}

package/src/components/TranslationBanner/index.ts

@@ -0,0 +1 @@
+export { TranslationBanner } from './TranslationBanner';