@kolkrabbi/kol-framework 0.1.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kolkrabbi/kol-framework",
+  "version": "0.1.0",
+  "description": "KOL app shell — sidenav, layout, theme toggle, footer, heroes + brand color layer. SideNav takes nav data as props so the tree stays app-local.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./kol-framework.css": "./kol-framework.css",
+    "./kol-brand-color.css": "./kol-brand-color.css"
+  },
+  "files": [
+    "src",
+    "*.css",
+    "README.md"
+  ],
+  "keywords": [
+    "kol",
+    "kolkrabbi",
+    "design-system",
+    "react",
+    "app-shell"
+  ],
+  "dependencies": {
+    "@kolkrabbi/kol-component": "0.1.0",
+    "@kolkrabbi/kol-loader": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18.3.0 || ^19.0.0",
+    "react-dom": "^18.3.0 || ^19.0.0",
+    "react-router-dom": "^6.0.0 || ^7.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kolkrabbi/kol-design-system.git",
+    "directory": "packages/framework"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/AppShell.jsx

@@ -0,0 +1,46 @@
+import { useEffect, useState } from 'react'
+import { Outlet, useLocation } from 'react-router-dom'
+import SideNav from './SideNav.jsx'
+import { Icon } from '@kolkrabbi/kol-loader'
+import { ModalProvider } from '@kolkrabbi/kol-component'
+
+export default function AppShell({ navTree = [], getActivePage }) {
+  const [drawerOpen, setDrawerOpen] = useState(false)
+  const { pathname } = useLocation()
+
+  useEffect(() => { setDrawerOpen(false) }, [pathname])
+
+  useEffect(() => {
+    if (!drawerOpen) return
+    const onKey = (e) => { if (e.key === 'Escape') setDrawerOpen(false) }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [drawerOpen])
+
+  return (
+    <ModalProvider>
+      <div className="kol-brand-layout" data-drawer-open={drawerOpen ? 'true' : undefined}>
+        <button
+          type="button"
+          className="kol-sidenav-hamburger md:hidden fixed top-3 left-3 z-30 w-10 h-10 inline-flex items-center justify-center rounded-full bg-surface-primary border border-fg-08 text-emphasis"
+          aria-label={drawerOpen ? 'Close menu' : 'Open menu'}
+          aria-expanded={drawerOpen}
+          onClick={() => setDrawerOpen((v) => !v)}
+        >
+          <Icon name={drawerOpen ? 'x' : 'menu'} size={18} />
+        </button>
+
+        <div
+          className="kol-sidenav-backdrop fixed inset-0 z-20 bg-black/50 opacity-0 pointer-events-none transition-opacity duration-200 md:hidden"
+          onClick={() => setDrawerOpen(false)}
+          aria-hidden="true"
+        />
+
+        <SideNav navTree={navTree} getActivePage={getActivePage} drawerOpen={drawerOpen} onCloseDrawer={() => setDrawerOpen(false)} />
+        <div className="min-w-0">
+          <Outlet />
+        </div>
+      </div>
+    </ModalProvider>
+  )
+}

package/src/BrandHero.jsx

@@ -0,0 +1,14 @@
+export default function BrandHero({ id = 'hero', label, title, lede, mark }) {
+  return (
+    <section id={id} className="kol-page-hero">
+      {label && <p className="kol-prose-label">{label}</p>}
+      <div className="flex items-center gap-12 flex-wrap">
+        {mark}
+        <div className="flex-1 min-w-[280px]">
+          <h1 className="kol-prose-display">{title}</h1>
+          {lede && <p className="kol-prose-lede max-w-[60ch]">{lede}</p>}
+        </div>
+      </div>
+    </section>
+  )
+}

package/src/Layout.jsx

@@ -0,0 +1,20 @@
+import { Outlet, useLocation } from 'react-router-dom'
+import ScrollToTop from './ScrollToTop'
+import { ExitPreview } from '@kolkrabbi/kol-component'
+
+const clientSurfacePatterns = [/^\/site/]
+
+export default function Layout() {
+  const { pathname } = useLocation()
+  const isClientSiteRoute = clientSurfacePatterns.some((re) => re.test(pathname))
+
+  return (
+    <div className="min-h-dvh flex flex-col">
+      <ScrollToTop />
+      <main className="flex-1 min-w-0">
+        <Outlet />
+      </main>
+      {isClientSiteRoute && <ExitPreview />}
+    </div>
+  )
+}

package/src/PageSection.jsx

@@ -0,0 +1,24 @@
+import { Divider } from '@kolkrabbi/kol-component'
+
+export default function PageSection({ id, label, title, body, children, className = '', fullbleed = false, divider = false }) {
+  const hasHead = label || title || body
+  const cls = [
+    'kol-page',
+    'kol-page-section',
+    fullbleed && 'kol-page--fullbleed',
+    className,
+  ].filter(Boolean).join(' ')
+  return (
+    <section id={id} className={cls}>
+      {divider && <Divider className="kol-page-section-divider" />}
+      {hasHead && (
+        <header className={fullbleed ? 'max-w-[960px]' : 'max-w-[720px]'}>
+          {label && <p  className="kol-prose-label">{label}</p>}
+          {title && <h2 className="kol-prose-title">{title}</h2>}
+          {body  && <p  className="kol-prose-lede">{body}</p>}
+        </header>
+      )}
+      {children}
+    </section>
+  )
+}

package/src/PortalFooter.jsx

@@ -0,0 +1,22 @@
+export default function PortalFooter() {
+  const year = new Date().getFullYear()
+  return (
+    <footer className="kol-portal-footer">
+      <a
+        href="https://kolkrabbi.io"
+        target="_blank"
+        rel="noopener"
+        aria-label="Kolkrabbi Vinnustofa"
+      >
+        <img src="/favicon/favicon.svg" alt="" width="32" height="32" />
+      </a>
+      <p className="kol-helper-12 text-meta">
+        <a href="https://kolkrabbi.io" target="_blank" rel="noopener" className="hover:text-strong">
+          Kolkrabbi Vinnustofa
+        </a>
+        {' · '}
+        {year}
+      </p>
+    </footer>
+  )
+}

package/src/ScrollToTop.jsx

@@ -0,0 +1,17 @@
+import { useEffect } from 'react'
+import { useLocation } from 'react-router-dom'
+
+export default function ScrollToTop() {
+  const { pathname, hash } = useLocation()
+
+  useEffect(() => {
+    if (hash) {
+      const el = document.getElementById(hash.slice(1))
+      if (el) el.scrollIntoView({ behavior: 'smooth', block: 'start' })
+      return
+    }
+    window.scrollTo({ top: 0, left: 0, behavior: 'instant' })
+  }, [pathname, hash])
+
+  return null
+}

package/src/SideNav.jsx

@@ -0,0 +1,205 @@
+import { useEffect, useState } from 'react'
+import { Link, NavLink, useLocation } from 'react-router-dom'
+import { Icon } from '@kolkrabbi/kol-loader'
+import ThemeToggle from './ThemeToggle'
+import { useScrollSpy } from '@kolkrabbi/kol-component'
+
+/* Walk the active page's children and return all leaf section ids (for scroll-spy). */
+function collectSectionIds(node) {
+  if (!node?.children) return []
+  const ids = []
+  const walk = (children) => {
+    for (const c of children) {
+      if (c.id && !c.to) ids.push(c.id)
+      if (c.children) walk(c.children)
+    }
+  }
+  walk(node.children)
+  return ids
+}
+
+const linkBase = 'kol-sidenav-link kol-helper-10 block relative py-[4px] no-underline transition-colors duration-150'
+const linkCls = `${linkBase} text-body hover:text-emphasis`
+const linkActiveCls = `${linkBase} is-active`
+
+/* Walk the children tree; return true if any leaf matches activeSectionId. */
+function hasActiveDescendant(children, activeSectionId) {
+  if (!activeSectionId) return false
+  for (const c of children ?? []) {
+    if (c.id === activeSectionId) return true
+    if (c.children && hasActiveDescendant(c.children, activeSectionId)) return true
+  }
+  return false
+}
+
+const leafStyle = (indent) => ({
+  paddingLeft: indent,
+  '--kol-sidenav-dot-left': `${indent - 14}px`,
+})
+
+function SectionLeaf({ leaf, basePath, isActive, indent }) {
+  return (
+    <li>
+      <Link
+        to={`${basePath}#${leaf.id}`}
+        className={isActive ? linkActiveCls : linkCls}
+        style={leafStyle(indent)}
+      >
+        {leaf.label}
+      </Link>
+    </li>
+  )
+}
+
+function RouteLeaf({ leaf, indent }) {
+  return (
+    <li>
+      <NavLink
+        to={leaf.to}
+        end
+        className={({ isActive }) => (isActive ? linkActiveCls : linkCls)}
+        style={leafStyle(indent)}
+      >
+        {leaf.label}
+      </NavLink>
+    </li>
+  )
+}
+
+function GroupNode({ group, basePath, activeSectionId, indent }) {
+  const isAncestor = hasActiveDescendant(group.children, activeSectionId)
+  return (
+    <li>
+      <div
+        className={`kol-sidenav-group kol-helper-10 uppercase ${isAncestor ? 'text-emphasis' : 'text-subtle'}`}
+        style={{ paddingLeft: indent }}
+      >
+        {group.label}
+      </div>
+      <ul className="kol-sidenav-list">
+        {group.children.map((child, i) => (
+          <ChildNode
+            key={child.id ?? child.to ?? `g-${i}`}
+            child={child}
+            basePath={basePath}
+            activeSectionId={activeSectionId}
+            indent={indent + 12}
+          />
+        ))}
+      </ul>
+    </li>
+  )
+}
+
+function ChildNode({ child, basePath, activeSectionId, indent }) {
+  if (child.children) {
+    return <GroupNode group={child} basePath={basePath} activeSectionId={activeSectionId} indent={indent} />
+  }
+  if (child.to) {
+    return <RouteLeaf leaf={child} indent={indent} />
+  }
+  if (child.id) {
+    return (
+      <SectionLeaf
+        leaf={child}
+        basePath={basePath}
+        isActive={activeSectionId === child.id}
+        indent={indent}
+      />
+    )
+  }
+  return null
+}
+
+export default function SideNav({ drawerOpen = false, onCloseDrawer, navTree = [], getActivePage }) {
+  const { pathname } = useLocation()
+  const activePage = getActivePage?.(pathname)
+  const sectionIds = activePage ? collectSectionIds(activePage) : []
+  const onPageRoot = activePage && pathname === activePage.to
+  const activeSectionId = useScrollSpy(onPageRoot ? sectionIds : [])
+
+  const isEditor = pathname.startsWith('/editor/')
+  const [collapsed, setCollapsed] = useState(isEditor)
+
+  useEffect(() => {
+    const root = document.documentElement
+    if (collapsed) root.setAttribute('data-sidenav', 'collapsed')
+    else root.removeAttribute('data-sidenav')
+  }, [collapsed])
+
+  /* /editor → collapsed. Anywhere else → expanded. Manual chevron toggle
+   * works for the session but doesn't persist across navigation. */
+  useEffect(() => {
+    setCollapsed(isEditor)
+  }, [isEditor])
+
+  return (
+    <aside
+      className={`kol-sidenav sticky top-0 self-start h-dvh flex flex-col border-r border-fg-08 z-20 bg-surface-primary${collapsed ? ' is-collapsed' : ''}${drawerOpen ? ' is-drawer-open' : ''}`}
+    >
+      <button
+        type="button"
+        className="kol-sidenav-toggle absolute top-5 right-[-12px] z-[2] w-6 h-6 inline-flex items-center justify-center bg-[var(--kol-surface-primary)] border border-[var(--kol-border-default)] rounded-full p-0 cursor-pointer text-[14px] leading-none transition-colors duration-150 text-meta hover:text-emphasis hover:border-fg-24"
+        aria-label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
+        title={collapsed ? 'Expand' : 'Collapse'}
+        onClick={() => setCollapsed((v) => !v)}
+      >
+        <Icon name={collapsed ? 'chevron-right' : 'chevron-left'} size={12} />
+      </button>
+
+      <div className="kol-sidenav-scroll flex-1 flex flex-col justify-between overflow-y-auto pt-4 pb-4 [scrollbar-width:thin]">
+        <ul className="kol-sidenav-tree flex flex-col gap-[2px]">
+          {navTree.map((page) => {
+            const isActivePage = activePage?.id === page.id
+            return (
+              <li key={page.id}>
+                <NavLink
+                  to={page.to}
+                  end={page.to === '/'}
+                  className={({ isActive }) =>
+                    `kol-sidenav-hop kol-helper-12 relative flex items-center gap-3 py-2 pr-10 pl-6 no-underline${isActive ? ' is-active' : ''}`
+                  }
+                >
+                  <span className="kol-sidenav-hop-icon inline-flex items-center justify-center w-5 h-5 shrink-0" aria-hidden="true">
+                    <Icon name={page.icon} size={16} />
+                  </span>
+                  <span className="kol-sidenav-hop-label flex-1 min-w-0">{page.label}</span>
+                </NavLink>
+
+                {isActivePage && page.children && (
+                  <ul className="kol-sidenav-list mb-2 flex flex-col gap-2">
+                    {page.children.map((child, i) => (
+                      <ChildNode
+                        key={child.id ?? child.to ?? `g-${i}`}
+                        child={child}
+                        basePath={page.to}
+                        activeSectionId={activeSectionId}
+                        indent={56}
+                      />
+                    ))}
+                  </ul>
+                )}
+              </li>
+            )
+          })}
+        </ul>
+
+        <div className="flex flex-col">
+          <ThemeToggle variant="hop-bare" />
+        </div>
+      </div>
+
+      <div className="kol-sidenav-footer flex items-center pl-6 pr-4 h-14 border-t border-fg-08 min-w-0">
+        <a
+          href="https://kolkrabbi.io"
+          target="_blank"
+          rel="noopener"
+          className="kol-helper-10 !font-normal no-underline group whitespace-nowrap overflow-hidden text-ellipsis min-w-0"
+        >
+          <span className="text-body group-hover:text-emphasis">Kolkrabbi Vinnustofa</span>
+          <span className="text-meta group-hover:text-emphasis"> · {new Date().getFullYear()}</span>
+        </a>
+      </div>
+    </aside>
+  )
+}

package/src/SubPageHero.jsx

@@ -0,0 +1,27 @@
+import { Link } from 'react-router-dom'
+
+export default function SubPageHero({ backTo, backLabel, label, title, lede }) {
+  return (
+    <section className="kol-page-hero" id="hero">
+      {backTo && (
+        <Link
+          to={backTo}
+          className="kol-back-link kol-helper-12 uppercase tracking-widest text-body hover:text-emphasis no-underline"
+        >
+          {backLabel}
+        </Link>
+      )}
+      {label && (
+        <p className="kol-helper-12 uppercase tracking-widest text-meta m-0 mb-4">
+          {label}
+        </p>
+      )}
+      <div className="flex-1 min-w-[280px]">
+        <h1 className="kol-sans-display-01 text-auto m-0 mb-6">{title}</h1>
+        {lede && (
+          <p className="kol-sans-body-01 text-body m-0 max-w-[60ch]">{lede}</p>
+        )}
+      </div>
+    </section>
+  )
+}

package/src/ThemeToggle.jsx

@@ -0,0 +1,95 @@
+import { useEffect, useState } from 'react'
+import { Icon } from '@kolkrabbi/kol-loader'
+
+const STORAGE_KEY = 'kol-theme'
+
+function getInitialTheme() {
+  if (typeof document === 'undefined') return 'dark'
+  return document.documentElement.dataset.theme === 'light' ? 'light' : 'dark'
+}
+
+/**
+ * Theme toggle — horizontal icon-swap button.
+ *
+ * Variants:
+ *   icon     — minimal 32×32 icon-only button (no container chrome). For
+ *              top-bar / nav-bar use where the toggle sits inline with other
+ *              icon buttons.
+ *   hop      — full-width labeled Button-primary-styled sidenav row
+ *              (bg-fg-04, on-primary text). For sidenav rows where it pairs
+ *              with other Button-primary "hop" entries.
+ *   hop-bare — same shape + padding as hop, but fully transparent (no rest
+ *              bg, no hover bg). For sidenav rows where the row should read
+ *              as plain text + icon, not a button.
+ *
+ * Self-contained: owns theme state, writes `data-theme` to <html>, persists
+ * to localStorage under `kol-theme`. The icon-swap animation slides a pair
+ * of half-split theme-toggle icons horizontally — the `theme-toggle` SVG is
+ * designed as a split circle, so the slide produces a visible light/dark flip.
+ */
+export default function ThemeToggle({ variant = 'icon', className = '' }) {
+  const [theme, setTheme] = useState(getInitialTheme)
+
+  useEffect(() => {
+    document.documentElement.dataset.theme = theme
+    try { localStorage.setItem(STORAGE_KEY, theme) } catch { /* storage blocked */ }
+  }, [theme])
+
+  const isDark = theme === 'dark'
+  const next = isDark ? 'light' : 'dark'
+  const handleToggle = () => setTheme(next)
+
+  const iconSwap = (size) => (
+    <span
+      className="relative inline-block overflow-hidden"
+      style={{ width: size, height: size }}
+      aria-hidden="true"
+    >
+      <span
+        className="flex transition-transform duration-500 ease-in-out"
+        style={{ width: size * 2, transform: isDark ? 'translateX(0)' : `translateX(-${size}px)` }}
+      >
+        <Icon name="theme-toggle" size={size} />
+        <Icon name="theme-toggle" size={size} />
+      </span>
+    </span>
+  )
+
+  if (variant === 'hop' || variant === 'hop-bare') {
+    const bare = variant === 'hop-bare'
+    const chromeCls = bare
+      ? 'w-full inline-flex items-center justify-start gap-2 py-1.5 px-6 kol-mono-14 bg-transparent text-emphasis transition-colors'
+      : 'kol-btn kol-btn-primary kol-btn-md kol-mono-14 w-full justify-start gap-2'
+    return (
+      <button
+        type="button"
+        onClick={handleToggle}
+        aria-label={`Switch to ${next} mode`}
+        className={`${chromeCls} ${className}`.trim()}
+      >
+        <span className="inline-flex items-center justify-center shrink-0" aria-hidden="true">
+          {iconSwap(16)}
+        </span>
+        {/* kol-sidenav-hop-label keeps the responsive label-hide rule firing
+         * at narrow viewports without subjecting the button to the muted
+         * sidenav-hop text-color override. */}
+        <span className="kol-sidenav-hop-label flex-1 min-w-0 text-left">
+          {isDark ? 'Dark mode' : 'Light mode'}
+        </span>
+      </button>
+    )
+  }
+
+  // variant === 'icon' (default)
+  return (
+    <button
+      type="button"
+      onClick={handleToggle}
+      aria-label={`Switch to ${next} mode`}
+      title={`Switch to ${next} mode`}
+      className={`inline-flex items-center justify-center w-8 h-8 p-0 bg-transparent border-0 cursor-pointer text-emphasis hover:opacity-80 transition-opacity duration-300 ${className}`.trim()}
+    >
+      {iconSwap(18)}
+    </button>
+  )
+}

package/src/index.js

@@ -0,0 +1,18 @@
+/**
+ * @kol/framework — shared KOL app shell.
+ *
+ * Site chrome (sidenav, layout, theme toggle, footer, heroes) consumed across
+ * apps. SideNav takes its nav data as props (navTree + getActivePage) so the
+ * tree stays app-local. CSS lives in src/styles: kol-framework.css
+ * and kol-brand-color.css.
+ */
+
+export { default as AppShell } from './AppShell.jsx'
+export { default as SideNav } from './SideNav.jsx'
+export { default as ThemeToggle } from './ThemeToggle.jsx'
+export { default as Layout } from './Layout.jsx'
+export { default as PageSection } from './PageSection.jsx'
+export { default as PortalFooter } from './PortalFooter.jsx'
+export { default as ScrollToTop } from './ScrollToTop.jsx'
+export { default as BrandHero } from './BrandHero.jsx'
+export { default as SubPageHero } from './SubPageHero.jsx'