@keyfunc/keybricks-ds 1.0.0

package/components/navigation/Breadcrumb.jsx

@@ -0,0 +1,120 @@
+import React from "react";
+import { Icon } from "../icons/Icon.jsx";
+
+function Crumb({ label, last, hovered, onSelect }) {
+  const [hover, setHover] = React.useState(false);
+  const on = (hover || hovered) && !last;
+  return (
+    <span role={last ? undefined : "button"} tabIndex={last ? undefined : 0}
+      onClick={() => !last && onSelect && onSelect(label)}
+      onKeyDown={(e) => { if (!last && (e.key === "Enter" || e.key === " ")) { e.preventDefault(); onSelect && onSelect(label); } }}
+      onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}
+      style={{ fontFamily: "var(--font-sans)", fontSize: "var(--text-sm)", lineHeight: "var(--leading-sm)", color: last || on ? "var(--text-heading)" : "var(--text-secondary)", fontWeight: last ? "var(--weight-medium)" : "var(--weight-regular)", cursor: last ? "default" : "pointer", borderRadius: "var(--radius-sm)", transition: "var(--t-hover)" }}>{label}</span>
+  );
+}
+
+function Sep() {
+  return <span style={{ color: "var(--text-muted)", display: "inline-flex" }}><Icon name="chevron-right" size={13} /></span>;
+}
+
+/** Overflow crumb: an ellipsis button that drops down the levels hidden by collapsing. */
+function Overflow({ items, onSelect }) {
+  const [open, setOpen] = React.useState(false);
+  const [hover, setHover] = React.useState(false);
+  const root = React.useRef(null);
+  React.useEffect(() => {
+    if (!open) return;
+    const h = (e) => { if (root.current && !root.current.contains(e.target)) setOpen(false); };
+    document.addEventListener("mousedown", h);
+    return () => document.removeEventListener("mousedown", h);
+  }, [open]);
+  return (
+    <span ref={root} style={{ position: "relative", display: "inline-flex" }}>
+      <span role="button" tabIndex={0} aria-label={`Show ${items.length} hidden levels`} aria-expanded={open}
+        onClick={() => setOpen(!open)}
+        onKeyDown={(e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); setOpen(!open); } if (e.key === "Escape") setOpen(false); }}
+        onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}
+        style={{ display: "inline-flex", alignItems: "center", justifyContent: "center", width: 20, height: 18, borderRadius: "var(--radius-sm)", cursor: "pointer", color: open || hover ? "var(--text-heading)" : "var(--text-muted)", background: open ? "var(--bg-active)" : hover ? "var(--bg-hover)" : "transparent", transition: "var(--t-hover)" }}>
+        <Icon name="ellipsis" size={14} />
+      </span>
+      {open ? (
+        <span style={{ position: "absolute", top: "calc(100% + 5px)", left: 0, zIndex: "var(--z-menu)", minWidth: 168, maxWidth: 260, background: "var(--bg-surface)", border: "1px solid var(--border-card)", borderRadius: "var(--radius-md)", boxShadow: "var(--shadow-menu)", padding: 4, display: "flex", flexDirection: "column" }}>
+          {items.map((it, i) => <OverflowItem key={it} label={it} depth={i} onSelect={(l) => { setOpen(false); onSelect && onSelect(l); }} />)}
+        </span>
+      ) : null}
+    </span>
+  );
+}
+
+function OverflowItem({ label, depth, onSelect }) {
+  const [hover, setHover] = React.useState(false);
+  return (
+    <span role="menuitem" tabIndex={0} onClick={() => onSelect(label)}
+      onKeyDown={(e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); onSelect(label); } }}
+      onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}
+      style={{ display: "flex", alignItems: "center", gap: 6, padding: "6px 9px", paddingLeft: 9 + depth * 12, borderRadius: "var(--radius-sm)", cursor: "pointer", background: hover ? "var(--bg-hover)" : "transparent", fontFamily: "var(--font-sans)", fontSize: "var(--text-sm)", lineHeight: "var(--leading-sm)", color: "var(--text-heading)", whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis", transition: "var(--t-hover)" }}>
+      {depth > 0 ? <span style={{ color: "var(--text-muted)", display: "inline-flex", flexShrink: 0 }}><Icon name="chevron-right" size={11} /></span> : null}
+      {label}
+    </span>
+  );
+}
+
+/** Breadcrumb trail — 12px, chevron separators, last crumb in heading color. Clickable crumbs darken on hover and carry press + keyboard focus from the global interaction layer. Trails longer than `maxItems` collapse to first · … · last two, with the hidden levels in a dropdown on the ellipsis. */
+export function Breadcrumb({ items = [], onSelect, maxItems = 4, hoveredIndex, style }) {
+  const collapse = items.length > maxItems && maxItems >= 3;
+  const tailCount = maxItems - 2;
+  const head = collapse ? items.slice(0, 1) : items;
+  const hidden = collapse ? items.slice(1, items.length - tailCount) : [];
+  const tail = collapse ? items.slice(items.length - tailCount) : [];
+  const lastLabel = items[items.length - 1];
+  return (
+    <nav style={{ display: "flex", alignItems: "center", gap: 4, ...style }}>
+      {head.map((it, i) => (
+        <React.Fragment key={it}>
+          {i > 0 ? <Sep /> : null}
+          <Crumb label={it} last={it === lastLabel} hovered={hoveredIndex === i} onSelect={onSelect} />
+        </React.Fragment>
+      ))}
+      {collapse ? (
+        <React.Fragment>
+          <Sep />
+          <Overflow items={hidden} onSelect={onSelect} />
+          {tail.map((it) => (
+            <React.Fragment key={it}>
+              <Sep />
+              <Crumb label={it} last={it === lastLabel} onSelect={onSelect} />
+            </React.Fragment>
+          ))}
+        </React.Fragment>
+      ) : null}
+    </nav>
+  );
+}
+
+/** Theme toggle — flips <html data-theme> and persists to localStorage("kb-theme"). Pass `dark`+`onToggle` to control it externally. */
+export function ThemeToggle({ size = 34, dark: darkProp, onToggle, style }) {
+  const controlled = darkProp != null;
+  const [darkState, setDark] = React.useState(() => (typeof document !== "undefined" && document.documentElement.dataset.theme === "dark"));
+  const dark = controlled ? darkProp : darkState;
+  React.useEffect(() => {
+    if (controlled || typeof document === "undefined") return;
+    document.documentElement.dataset.theme = dark ? "dark" : "light";
+    try { localStorage.setItem("kb-theme", dark ? "dark" : "light"); } catch (e) {}
+  }, [dark, controlled]);
+  const [hover, setHover] = React.useState(false);
+  return (
+    <button type="button" aria-label={dark ? "Switch to light mode" : "Switch to dark mode"} onClick={() => (controlled ? onToggle && onToggle(!dark) : setDark(!dark))}
+      onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}
+      style={{ width: size, height: size, borderRadius: "var(--radius-md)", border: "none", cursor: "pointer", display: "inline-flex", alignItems: "center", justifyContent: "center", background: hover ? "var(--bg-hover)" : "transparent", color: "var(--text-body)", padding: 0, transition: "var(--t-hover)", ...style }}>
+      <Icon name={dark ? "sparkles" : "moon"} size={18} />
+    </button>
+  );
+}
+
+/** Reads the persisted theme and applies it before first paint. Call once at app start. */
+export function applyStoredTheme() {
+  if (typeof document === "undefined") return;
+  let t = "light";
+  try { t = localStorage.getItem("kb-theme") || "light"; } catch (e) {}
+  document.documentElement.dataset.theme = t;
+}

package/components/navigation/Breadcrumb.vue

@@ -0,0 +1,94 @@
+<script setup>
+import { ref, computed, watch, onUnmounted } from 'vue'
+import Icon from '../icons/Icon.vue'
+// Breadcrumb trail — 12px, chevron separators, last crumb in heading color.
+// Clickable crumbs darken on hover (no underline) and carry press + keyboard focus from the global interaction layer.
+// Trails longer than maxItems collapse to first · … · last two, with the hidden levels in a dropdown on the ellipsis.
+const props = defineProps({ items: { type: Array, default: () => [] }, maxItems: { type: Number, default: 4 }, hoveredIndex: { type: Number, default: null }, style: Object })
+const emit = defineEmits(['select'])
+const hover = ref(-1)
+const ovHover = ref(false)
+const menuHover = ref(-1)
+const open = ref(false)
+const root = ref(null)
+const collapse = computed(() => props.items.length > props.maxItems && props.maxItems >= 3)
+const tailCount = computed(() => props.maxItems - 2)
+const head = computed(() => collapse.value ? props.items.slice(0, 1) : props.items)
+const hidden = computed(() => collapse.value ? props.items.slice(1, props.items.length - tailCount.value) : [])
+const tail = computed(() => collapse.value ? props.items.slice(props.items.length - tailCount.value) : [])
+const lastLabel = computed(() => props.items[props.items.length - 1])
+const isLast = (it) => it === lastLabel.value
+const on = (i, it) => (hover.value === i || props.hoveredIndex === i) && !isLast(it)
+function pick(it) { if (!isLast(it)) emit('select', it) }
+function pickHidden(it) { open.value = false; emit('select', it) }
+function onDoc(e) { if (root.value && !root.value.contains(e.target)) open.value = false }
+watch(open, (v) => { if (v) document.addEventListener('mousedown', onDoc); else document.removeEventListener('mousedown', onDoc) })
+onUnmounted(() => document.removeEventListener('mousedown', onDoc))
+const crumbStyle = (i, it) => ({ fontFamily: 'var(--font-sans)', fontSize: 'var(--text-sm)', lineHeight: 'var(--leading-sm)', color: isLast(it) || on(i, it) ? 'var(--text-heading)' : 'var(--text-secondary)', fontWeight: isLast(it) ? 'var(--weight-medium)' : 'var(--weight-regular)', cursor: isLast(it) ? 'default' : 'pointer', borderRadius: 'var(--radius-sm)', transition: 'var(--t-hover)' })
+</script>
+<template>
+  <nav :style="{ display: 'flex', alignItems: 'center', gap: 4, ...style }">
+    <template v-for="(it, i) in head" :key="it">
+      <span v-if="i > 0" style="color:var(--text-muted);display:inline-flex"><Icon name="chevron-right" :size="13" /></span>
+      <span :role="isLast(it) ? undefined : 'button'" :tabindex="isLast(it) ? undefined : 0"
+        @click="pick(it)" @keydown.enter.prevent="pick(it)" @keydown.space.prevent="pick(it)"
+        @mouseenter="hover = i" @mouseleave="hover = -1" :style="crumbStyle(i, it)">{{ it }}</span>
+    </template>
+    <template v-if="collapse">
+      <span style="color:var(--text-muted);display:inline-flex"><Icon name="chevron-right" :size="13" /></span>
+      <span ref="root" style="position:relative;display:inline-flex">
+        <span role="button" tabindex="0" :aria-label="`Show ${hidden.length} hidden levels`" :aria-expanded="open"
+          @click="open = !open" @keydown.enter.prevent="open = !open" @keydown.space.prevent="open = !open" @keydown.esc="open = false"
+          @mouseenter="ovHover = true" @mouseleave="ovHover = false"
+          :style="{ display: 'inline-flex', alignItems: 'center', justifyContent: 'center', width: '20px', height: '18px', borderRadius: 'var(--radius-sm)', cursor: 'pointer', color: open || ovHover ? 'var(--text-heading)' : 'var(--text-muted)', background: open ? 'var(--bg-active)' : ovHover ? 'var(--bg-hover)' : 'transparent', transition: 'var(--t-hover)' }">
+          <Icon name="ellipsis" :size="14" />
+        </span>
+        <span v-if="open" style="position:absolute;top:calc(100% + 5px);left:0;z-index:var(--z-menu);min-width:168px;max-width:260px;background:var(--bg-surface);border:1px solid var(--border-card);border-radius:var(--radius-md);box-shadow:var(--shadow-menu);padding:4px;display:flex;flex-direction:column">
+          <span v-for="(h, hi) in hidden" :key="h" role="menuitem" tabindex="0"
+            @click="pickHidden(h)" @keydown.enter.prevent="pickHidden(h)" @keydown.space.prevent="pickHidden(h)"
+            @mouseenter="menuHover = hi" @mouseleave="menuHover = -1"
+            :style="{ display: 'flex', alignItems: 'center', gap: '6px', padding: '6px 9px', paddingLeft: (9 + hi * 12) + 'px', borderRadius: 'var(--radius-sm)', cursor: 'pointer', background: menuHover === hi ? 'var(--bg-hover)' : 'transparent', fontFamily: 'var(--font-sans)', fontSize: 'var(--text-sm)', lineHeight: 'var(--leading-sm)', color: 'var(--text-heading)', whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis', transition: 'var(--t-hover)' }">
+            <span v-if="hi > 0" style="color:var(--text-muted);display:inline-flex;flex-shrink:0"><Icon name="chevron-right" :size="11" /></span>{{ h }}
+          </span>
+        </span>
+      </span>
+      <template v-for="it in tail" :key="it">
+        <span style="color:var(--text-muted);display:inline-flex"><Icon name="chevron-right" :size="13" /></span>
+        <span :role="isLast(it) ? undefined : 'button'" :tabindex="isLast(it) ? undefined : 0"
+          @click="pick(it)" @keydown.enter.prevent="pick(it)" @keydown.space.prevent="pick(it)"
+          :style="crumbStyle(-1, it)">{{ it }}</span>
+      </template>
+    </template>
+  </nav>
+</template>
+
+<!-- ThemeToggle — flips <html data-theme> and persists to localStorage("kb-theme"). Pass `dark` (v-model) to control it externally. -->
+<!--
+<script setup name="ThemeToggle">
+import { ref, computed, watch, onMounted } from 'vue'
+import Icon from '../icons/Icon.vue'
+const props = defineProps({ size: { type: Number, default: 34 }, dark: { type: Boolean, default: null }, style: Object })
+const emit = defineEmits(['update:dark'])
+const darkState = ref(false)
+const dark = computed(() => props.dark != null ? props.dark : darkState.value)
+const hover = ref(false)
+onMounted(() => { darkState.value = document.documentElement.dataset.theme === 'dark' })
+watch(dark, (v) => { if (props.dark != null) return; document.documentElement.dataset.theme = v ? 'dark' : 'light'; try { localStorage.setItem('kb-theme', v ? 'dark' : 'light') } catch (e) {} })
+function toggle() { if (props.dark != null) emit('update:dark', !dark.value); else darkState.value = !darkState.value }
+</script>
+<template>
+  <button type="button" :aria-label="dark ? 'Switch to light mode' : 'Switch to dark mode'" @click="toggle" @mouseenter="hover = true" @mouseleave="hover = false"
+    :style="{ width: size, height: size, borderRadius: 'var(--radius-md)', border: 'none', cursor: 'pointer', display: 'inline-flex', alignItems: 'center', justifyContent: 'center', background: hover ? 'var(--bg-hover)' : 'transparent', color: 'var(--text-body)', padding: 0, transition: 'var(--t-hover)', ...style }">
+    <Icon :name="dark ? 'sparkles' : 'moon'" :size="18" />
+  </button>
+</template>
+-->
+
+<!-- applyStoredTheme() — reads the persisted theme and applies it before first paint. Call once at app start (main.js): -->
+<!--
+export function applyStoredTheme() {
+  let t = 'light'
+  try { t = localStorage.getItem('kb-theme') || 'light' } catch (e) {}
+  document.documentElement.dataset.theme = t
+}
+-->

package/components/navigation/DocTree.d.ts

@@ -0,0 +1,18 @@
+import * as React from "react";
+/** Secondary 240px documents panel: header, search, 30px tree rows with hued doc icons. */
+export interface DocTreeItem {
+  label: string;
+  kind?: "folder" | "doc";
+  /** Doc icon hue: orange | green | purple | blue | teal | gray */
+  hue?: string;
+  /** Override glyph */
+  icon?: string;
+}
+export interface DocTreeProps {
+  title?: string;
+  items?: DocTreeItem[];
+  active?: string;
+  onSelect?: (label: string) => void;
+  style?: React.CSSProperties;
+}
+export declare function DocTree(props: DocTreeProps): JSX.Element;

package/components/navigation/DocTree.jsx

@@ -0,0 +1,37 @@
+import React from "react";
+import { Icon } from "../icons/Icon.jsx";
+import { IconButton } from "../buttons/IconButton.jsx";
+import { SearchInput } from "../forms/SearchInput.jsx";
+
+const docHues = { orange: "var(--cat-transform)", green: "var(--cat-source)", purple: "var(--cat-merge)", blue: "var(--info-fg)", teal: "var(--cat-output)", gray: "var(--text-muted)" };
+
+/** Secondary documents panel — 240px: title header, search row, 30px tree items. items: [{label, kind:"folder"|"doc", hue, icon}]. */
+export function DocTree({ title = "Documents", items = [], active, onSelect, style }) {
+  return (
+    <div style={{ width: "var(--sidebar-w)", background: "var(--bg-surface)", borderRight: "1px solid var(--border-card)", display: "flex", flexDirection: "column", boxSizing: "border-box", flexShrink: 0, ...style }}>
+      <div style={{ height: "var(--topbar-h)", borderBottom: "1px solid var(--border-card)", display: "flex", alignItems: "center", justifyContent: "space-between", padding: "0 12px 0 16px", boxSizing: "border-box", flexShrink: 0 }}>
+        <span style={{ fontFamily: "var(--font-sans)", fontWeight: "var(--weight-medium)", fontSize: "var(--text-md)", lineHeight: "var(--leading-md)", letterSpacing: "var(--tracking-md)", color: "var(--text-heading)" }}>{title}</span>
+        <IconButton icon="chevron-right" size="md" muted />
+      </div>
+      <div style={{ padding: "12px 16px 8px", borderBottom: "1px solid var(--border-subtle)" }}>
+        <SearchInput bare placeholder="Search..." style={{ gap: 8 }} />
+      </div>
+      <div style={{ padding: 8, display: "flex", flexDirection: "column", gap: 2, overflowY: "auto" }}>
+        {items.map((it) => {
+          const is = active === it.label;
+          return (
+            <div key={it.label} role="treeitem" tabIndex={0} onClick={() => onSelect && onSelect(it.label)}
+              style={{ height: "var(--h-tree-item)", borderRadius: "var(--radius-md)", display: "flex", alignItems: "center", gap: 8, padding: "6px 8px", boxSizing: "border-box", cursor: "pointer", background: is ? "var(--bg-active)" : "transparent" }}
+              onMouseEnter={(e) => { if (!is) e.currentTarget.style.background = "var(--bg-hover)"; }}
+              onMouseLeave={(e) => { if (!is) e.currentTarget.style.background = "transparent"; }}>
+              <span style={{ color: it.kind === "folder" ? "var(--text-muted)" : docHues[it.hue || "gray"], display: "inline-flex" }}>
+                <Icon name={it.icon || (it.kind === "folder" ? "folder" : "file-text")} size={16} />
+              </span>
+              <span style={{ fontFamily: "var(--font-sans)", fontSize: "var(--text-sm)", lineHeight: "var(--leading-sm)", color: "var(--text-heading)", whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }}>{it.label}</span>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

package/components/navigation/DocTree.vue

@@ -0,0 +1,25 @@
+<script setup>
+import Icon from '../icons/Icon.vue'
+import IconButton from '../buttons/IconButton.vue'
+import SearchInput from '../forms/SearchInput.vue'
+const docHues = { orange: 'var(--cat-transform)', green: 'var(--cat-source)', purple: 'var(--cat-merge)', blue: 'var(--info-fg)', teal: 'var(--cat-output)', gray: 'var(--text-muted)' }
+// Secondary documents panel — 240px: title header, search row, 30px tree items. items: [{label, kind:"folder"|"doc", hue, icon}].
+defineProps({ title: { type: String, default: 'Documents' }, items: { type: Array, default: () => [] }, active: String, style: Object })
+const emit = defineEmits(['select'])
+</script>
+<template>
+  <div :style="{ width: 'var(--sidebar-w)', background: 'var(--bg-surface)', borderRight: '1px solid var(--border-card)', display: 'flex', flexDirection: 'column', boxSizing: 'border-box', flexShrink: 0, ...style }">
+    <div style="height:var(--topbar-h);border-bottom:1px solid var(--border-card);display:flex;align-items:center;justify-content:space-between;padding:0 12px 0 16px;box-sizing:border-box;flex-shrink:0">
+      <span style="font-family:var(--font-sans);font-weight:var(--weight-medium);font-size:var(--text-md);line-height:var(--leading-md);letter-spacing:var(--tracking-md);color:var(--text-heading)">{{ title }}</span>
+      <IconButton icon="chevron-right" size="md" muted />
+    </div>
+    <div style="padding:12px 16px 8px;border-bottom:1px solid var(--border-subtle)"><SearchInput bare placeholder="Search..." style="gap:8px" /></div>
+    <div style="padding:8px;display:flex;flex-direction:column;gap:2px;overflow-y:auto">
+      <div v-for="it in items" :key="it.label" @click="emit('select', it.label)"
+        :style="{ height: 'var(--h-tree-item)', borderRadius: 'var(--radius-md)', display: 'flex', alignItems: 'center', gap: 8, padding: '6px 8px', boxSizing: 'border-box', cursor: 'pointer', background: active === it.label ? 'var(--bg-active)' : 'transparent' }">
+        <span :style="{ color: it.kind === 'folder' ? 'var(--text-muted)' : docHues[it.hue || 'gray'], display: 'inline-flex' }"><Icon :name="it.icon || (it.kind === 'folder' ? 'folder' : 'file-text')" :size="16" /></span>
+        <span style="font-family:var(--font-sans);font-size:var(--text-sm);line-height:var(--leading-sm);color:var(--text-heading);white-space:nowrap;overflow:hidden;text-overflow:ellipsis">{{ it.label }}</span>
+      </div>
+    </div>
+  </div>
+</template>

package/components/navigation/Sidebar.d.ts

@@ -0,0 +1,29 @@
+import * as React from "react";
+/**
+ * App sidebar — 240px expanded / 64px icon rail. Logo header, nav, expandable sections, pinned footer.
+ * @startingPoint section="Chrome" subtitle="240px app sidebar with icon-rail collapse" viewport="240x600"
+ */
+export interface SidebarItem {
+  icon: string;
+  label: string;
+  children?: SidebarItem[];
+  /** Expand this section initially */
+  open?: boolean;
+}
+export interface SidebarProps {
+  items?: SidebarItem[];
+  footerItems?: SidebarItem[];
+  /** Active item label */
+  active?: string;
+  onSelect?: (label: string) => void;
+  collapsed?: boolean;
+  /** Renders the "Collapse" item */
+  onToggleCollapse?: () => void;
+  logo?: string;
+  brand?: string;
+  height?: number | string;
+  style?: React.CSSProperties;
+}
+export declare function Sidebar(props: SidebarProps): JSX.Element;
+/** The product's real nav model. */
+export declare const KEYBRICKS_NAV: SidebarItem[];

package/components/navigation/Sidebar.jsx

@@ -0,0 +1,75 @@
+import React from "react";
+import { Icon } from "../icons/Icon.jsx";
+
+function NavItem({ icon, label, active, indent, collapsed, badge, onClick }) {
+  const [hover, setHover] = React.useState(false);
+  return (
+    <div role="button" tabIndex={0} onClick={onClick} onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}
+      style={{ height: indent ? "var(--h-subnav-item)" : "var(--h-nav-item)", borderRadius: "var(--radius-md)", display: "flex", alignItems: "center", justifyContent: collapsed ? "center" : "flex-start", gap: 10, padding: collapsed ? "8px 10px" : indent ? "6px 10px" : "8px 10px", boxSizing: "border-box", cursor: "pointer", background: active ? "var(--bg-active)" : hover ? "var(--bg-hover)" : "transparent", color: active ? "var(--text-heading)" : "var(--text-body)", transition: "var(--t-hover)" }}>
+      <Icon name={icon} size={indent ? 14 : 16} />
+      {!collapsed ? <span style={{ fontFamily: "var(--font-sans)", fontWeight: "var(--weight-medium)", fontSize: "var(--text-base)", lineHeight: "var(--leading-base)", letterSpacing: "var(--tracking-base)", whiteSpace: "nowrap", flex: 1 }}>{label}</span> : null}
+      {!collapsed && badge ? badge : null}
+    </div>
+  );
+}
+
+/**
+ * Keybricks app sidebar — 240px (collapsed: 64px icon rail). White, hairline right border.
+ * items: [{icon,label,children:[{icon,label}]}]; active by label; footer items pinned.
+ */
+export function Sidebar({ items = [], footerItems = [{ icon: "circle-help", label: "Help" }, { icon: "settings", label: "Settings" }, { icon: "moon", label: "Dark Mode" }], active, onSelect, collapsed = false, onToggleCollapse, logo = "assets/keybricks-logo.png", brand = "Keybricks", height = "100%", style }) {
+  const [openSections, setOpen] = React.useState(() => items.filter((i) => i.children && (i.open || (i.children.some((c) => c.label === active)))).map((i) => i.label));
+  const toggleSection = (l) => setOpen(openSections.includes(l) ? openSections.filter((x) => x !== l) : [...openSections, l]);
+  return (
+    <aside style={{ width: collapsed ? "var(--rail-w)" : "var(--sidebar-w)", height, background: "var(--bg-surface)", borderRight: "1px solid var(--border-card)", display: "flex", flexDirection: "column", boxSizing: "border-box", flexShrink: 0, transition: "width .15s ease", ...style }}>
+      <div style={{ height: "var(--topbar-h)", borderBottom: "1px solid var(--border-card)", display: "flex", alignItems: "center", gap: 10, padding: "0 16px", boxSizing: "border-box", justifyContent: collapsed ? "center" : "flex-start", flexShrink: 0 }}>
+        <img src={logo} alt="" style={{ width: 24, height: 24, objectFit: "contain" }} />
+        {!collapsed ? <span style={{ fontFamily: "var(--font-sans)", fontWeight: "var(--weight-semibold)", fontSize: "var(--text-lg)", lineHeight: "var(--leading-lg)", letterSpacing: "-.609px", color: "var(--text-primary)" }}>{brand}</span> : null}
+      </div>
+      <nav style={{ flex: 1, overflowY: "auto", padding: 8, display: "flex", flexDirection: "column", gap: 0 }}>
+        {onToggleCollapse ? <NavItem icon="panel-left" label="Collapse" collapsed={collapsed} onClick={onToggleCollapse} /> : null}
+        {items.map((it) => it.children ? (
+          <div key={it.label}>
+            <div onClick={() => toggleSection(it.label)} style={{ height: "var(--h-subnav-item)", display: "flex", alignItems: "center", gap: 10, padding: collapsed ? "6px 10px" : "6px 10px", justifyContent: collapsed ? "center" : "flex-start", cursor: "pointer", color: "var(--text-body)", borderRadius: "var(--radius-md)", boxSizing: "border-box" }}>
+              <Icon name={it.icon} size={16} />
+              {!collapsed ? <><span style={{ fontFamily: "var(--font-sans)", fontWeight: "var(--weight-medium)", fontSize: "var(--text-base)", letterSpacing: "var(--tracking-base)", flex: 1 }}>{it.label}</span><Icon name={openSections.includes(it.label) ? "chevron-up" : "chevron-down"} size={14} /></> : null}
+            </div>
+            {!collapsed && openSections.includes(it.label) ? (
+              <div style={{ marginLeft: 24, display: "flex", flexDirection: "column", gap: 2, paddingTop: 2 }}>
+                {it.children.map((c) => <NavItem key={c.label} icon={c.icon} label={c.label} indent active={active === c.label} onClick={() => onSelect && onSelect(c.label)} />)}
+              </div>
+            ) : null}
+          </div>
+        ) : (
+          <NavItem key={it.label} icon={it.icon} label={it.label} collapsed={collapsed} active={active === it.label} onClick={() => onSelect && onSelect(it.label)} />
+        ))}
+      </nav>
+      <div style={{ borderTop: "1px solid var(--border-card)", padding: 8, display: "flex", flexDirection: "column", flexShrink: 0 }}>
+        {footerItems.map((f) => <NavItem key={f.label} icon={f.icon} label={f.label} collapsed={collapsed} onClick={() => onSelect && onSelect(f.label)} />)}
+      </div>
+    </aside>
+  );
+}
+
+/** Default Keybricks nav model (Home dashboard). */
+export const KEYBRICKS_NAV = [
+  { icon: "house", label: "Home" },
+  { icon: "file-text", label: "Documents" },
+  { icon: "layout-grid", label: "Business Intelligence" },
+  { icon: "database", label: "Data Integration" },
+  { icon: "scale", label: "Reconciliation" },
+  { icon: "network", label: "Consolidation" },
+  {
+    icon: "folder-cog", label: "Management", children: [
+      { icon: "box", label: "Modeling" },
+      { icon: "workflow", label: "Workflow" },
+      { icon: "shield", label: "Security Management" },
+      { icon: "refresh-cw", label: "System Migration" },
+      { icon: "chart-column", label: "Business Logic" },
+      { icon: "list-todo", label: "Tasks Management" },
+      { icon: "circle-check", label: "Validation Rules" },
+      { icon: "settings-2", label: "Control Center" },
+      { icon: "network", label: "Reconciliation" },
+    ],
+  },
+];

package/components/navigation/Sidebar.vue

@@ -0,0 +1,54 @@
+<script setup>
+import { ref } from 'vue'
+import Icon from '../icons/Icon.vue'
+
+/**
+ * Keybricks app sidebar — 240px (collapsed: 64px icon rail). White, hairline right border.
+ * items: [{icon,label,children:[{icon,label}]}]; active by label; footer items pinned.
+ */
+const props = defineProps({
+  items: { type: Array, default: () => [] },
+  footerItems: { type: Array, default: () => [{ icon: 'circle-help', label: 'Help' }, { icon: 'settings', label: 'Settings' }, { icon: 'moon', label: 'Dark Mode' }] },
+  active: String, collapsed: { type: Boolean, default: false },
+  logo: { type: String, default: 'assets/keybricks-logo.png' }, brand: { type: String, default: 'Keybricks' },
+  height: { type: [String, Number], default: '100%' }, style: Object, canCollapse: Boolean,
+})
+const emit = defineEmits(['select', 'toggleCollapse'])
+const openSections = ref(props.items.filter(i => i.children && (i.open || i.children.some(c => c.label === props.active))).map(i => i.label))
+function toggleSection(l) { openSections.value = openSections.value.includes(l) ? openSections.value.filter(x => x !== l) : [...openSections.value, l] }
+function itemStyle(active, indent) { return { height: indent ? 'var(--h-subnav-item)' : 'var(--h-nav-item)', borderRadius: 'var(--radius-md)', display: 'flex', alignItems: 'center', gap: 10, padding: indent ? '6px 10px' : '8px 10px', boxSizing: 'border-box', cursor: 'pointer', background: active ? 'var(--bg-active)' : 'transparent', color: active ? 'var(--text-heading)' : 'var(--text-body)', transition: 'var(--t-hover)' } }
+</script>
+<template>
+  <aside :style="{ width: collapsed ? 'var(--rail-w)' : 'var(--sidebar-w)', height, background: 'var(--bg-surface)', borderRight: '1px solid var(--border-card)', display: 'flex', flexDirection: 'column', boxSizing: 'border-box', flexShrink: 0, transition: 'width .15s ease', ...style }">
+    <div :style="{ height: 'var(--topbar-h)', borderBottom: '1px solid var(--border-card)', display: 'flex', alignItems: 'center', gap: 10, padding: '0 16px', boxSizing: 'border-box', justifyContent: collapsed ? 'center' : 'flex-start', flexShrink: 0 }">
+      <img :src="logo" alt="" style="width:24px;height:24px;object-fit:contain" />
+      <span v-if="!collapsed" style="font-family:var(--font-sans);font-weight:var(--weight-semibold);font-size:var(--text-lg);line-height:var(--leading-lg);letter-spacing:-.609px;color:var(--text-primary)">{{ brand }}</span>
+    </div>
+    <nav style="flex:1;overflow-y:auto;padding:8px;display:flex;flex-direction:column;gap:0">
+      <div v-if="canCollapse" role="button" tabindex="0" @click="emit('toggleCollapse')" :style="itemStyle(false, false)"><Icon name="panel-left" :size="16" /><span v-if="!collapsed" style="font-family:var(--font-sans);font-weight:var(--weight-medium);font-size:var(--text-base);line-height:var(--leading-base);letter-spacing:var(--tracking-base);white-space:nowrap;flex:1">Collapse</span></div>
+      <template v-for="it in items" :key="it.label">
+        <div v-if="it.children">
+          <div role="button" tabindex="0" @click="toggleSection(it.label)" :style="{ height: 'var(--h-subnav-item)', display: 'flex', alignItems: 'center', gap: 10, padding: '6px 10px', justifyContent: collapsed ? 'center' : 'flex-start', cursor: 'pointer', color: 'var(--text-body)', borderRadius: 'var(--radius-md)', boxSizing: 'border-box' }">
+            <Icon :name="it.icon" :size="16" />
+            <template v-if="!collapsed"><span style="font-family:var(--font-sans);font-weight:var(--weight-medium);font-size:var(--text-base);letter-spacing:var(--tracking-base);flex:1">{{ it.label }}</span><Icon :name="openSections.includes(it.label) ? 'chevron-up' : 'chevron-down'" :size="14" /></template>
+          </div>
+          <div v-if="!collapsed && openSections.includes(it.label)" style="margin-left:24px;display:flex;flex-direction:column;gap:2px;padding-top:2px">
+            <div v-for="c in it.children" :key="c.label" role="button" tabindex="0" @click="emit('select', c.label)" :style="itemStyle(active === c.label, true)"><Icon :name="c.icon" :size="14" /><span style="font-family:var(--font-sans);font-weight:var(--weight-medium);font-size:var(--text-base);line-height:var(--leading-base);letter-spacing:var(--tracking-base);white-space:nowrap;flex:1">{{ c.label }}</span></div>
+          </div>
+        </div>
+        <div v-else role="button" tabindex="0" @click="emit('select', it.label)" :style="itemStyle(active === it.label, false)"><Icon :name="it.icon" :size="16" /><span v-if="!collapsed" style="font-family:var(--font-sans);font-weight:var(--weight-medium);font-size:var(--text-base);line-height:var(--leading-base);letter-spacing:var(--tracking-base);white-space:nowrap;flex:1">{{ it.label }}</span></div>
+      </template>
+    </nav>
+    <div style="border-top:1px solid var(--border-card);padding:8px;display:flex;flex-direction:column;flex-shrink:0">
+      <div v-for="f in footerItems" :key="f.label" role="button" tabindex="0" @click="emit('select', f.label)" :style="itemStyle(false, false)"><Icon :name="f.icon" :size="16" /><span v-if="!collapsed" style="font-family:var(--font-sans);font-weight:var(--weight-medium);font-size:var(--text-base);line-height:var(--leading-base);letter-spacing:var(--tracking-base);white-space:nowrap;flex:1">{{ f.label }}</span></div>
+    </div>
+  </aside>
+</template>
+
+<!-- KEYBRICKS_NAV — default Keybricks nav model (Home dashboard), same shape as Sidebar.jsx's export, for reference:
+export const KEYBRICKS_NAV = [
+  { icon: 'house', label: 'Home' }, { icon: 'file-text', label: 'Documents' },
+  { icon: 'layout-grid', label: 'Business Intelligence' }, { icon: 'database', label: 'Data Integration' },
+  { icon: 'scale', label: 'Reconciliation' }, { icon: 'network', label: 'Consolidation' },
+  { icon: 'folder-cog', label: 'Management', children: [ ... ] },
+] -->

package/components/navigation/TopBar.d.ts

@@ -0,0 +1,27 @@
+import * as React from "react";
+/** 56px top bar with bare search + bell + dark AI Assistant button. */
+export interface TopBarProps {
+  placeholder?: string;
+  /** Replaces the default bell + AI Assistant pair */
+  actions?: React.ReactNode;
+  /** Receives the new search string */
+  onSearch?: (value: string) => void;
+  style?: React.CSSProperties;
+}
+export declare function TopBar(props: TopBarProps): JSX.Element;
+/** Editor toolbar: back, 14px/600 title, "• Editing", right actions. */
+export interface PageToolbarProps {
+  title?: string;
+  status?: string;
+  actions?: React.ReactNode;
+  onBack?: () => void;
+  style?: React.CSSProperties;
+}
+export declare function PageToolbar(props: PageToolbarProps): JSX.Element;
+/** 15px/500 page title + muted subtitle. */
+export interface PageHeadingProps {
+  title?: string;
+  subtitle?: string;
+  style?: React.CSSProperties;
+}
+export declare function PageHeading(props: PageHeadingProps): JSX.Element;

package/components/navigation/TopBar.jsx

@@ -0,0 +1,44 @@
+import React from "react";
+import { Icon } from "../icons/Icon.jsx";
+import { IconButton } from "../buttons/IconButton.jsx";
+import { Button } from "../buttons/Button.jsx";
+import { SearchInput } from "../forms/SearchInput.jsx";
+
+/** 56px top bar: bare search left, bell + dark AI Assistant button right. */
+export function TopBar({ placeholder = "Search documents, workflows, data...", actions, onSearch, style }) {
+  return (
+    <header style={{ height: "var(--topbar-h)", background: "var(--bg-surface)", borderBottom: "1px solid var(--border-card)", display: "flex", alignItems: "center", justifyContent: "space-between", padding: "0 24px", boxSizing: "border-box", flexShrink: 0, ...style }}>
+      <SearchInput bare placeholder={placeholder} onChange={onSearch} style={{ width: 576, maxWidth: "48%" }} />
+      <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
+        {actions || (<>
+          <IconButton icon="bell" size="lg" />
+          <Button variant="dark" icon="sparkles">AI Assistant</Button>
+        </>)}
+      </div>
+    </header>
+  );
+}
+
+/** Editor toolbar: back chevron, 14px/600 title, "• Editing" status, right action slot. */
+export function PageToolbar({ title, status = "• Editing", actions, onBack, style }) {
+  return (
+    <div style={{ height: "var(--topbar-h)", background: "var(--bg-surface)", borderBottom: "1px solid var(--border-card)", display: "flex", alignItems: "center", justifyContent: "space-between", padding: "0 16px", boxSizing: "border-box", flexShrink: 0, ...style }}>
+      <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
+        {onBack ? <IconButton icon="chevron-left" size="md" onClick={onBack} /> : null}
+        <span style={{ fontFamily: "var(--font-sans)", fontWeight: "var(--weight-semibold)", fontSize: "var(--text-md)", lineHeight: "var(--leading-md)", letterSpacing: "var(--tracking-md)", color: "var(--text-heading)" }}>{title}</span>
+        {status ? <span style={{ fontFamily: "var(--font-sans)", fontSize: "var(--text-sm)", lineHeight: "var(--leading-sm)", color: "var(--text-muted)", marginLeft: 6 }}>{status}</span> : null}
+      </div>
+      <div style={{ display: "flex", alignItems: "center", gap: 8 }}>{actions}</div>
+    </div>
+  );
+}
+
+/** Page heading block: 15px/500 title + 13px muted subtitle (System Migration pages). */
+export function PageHeading({ title, subtitle, style }) {
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: 4, ...style }}>
+      <span style={{ fontFamily: "var(--font-sans)", fontWeight: "var(--weight-medium)", fontSize: "var(--text-lg)", lineHeight: "var(--leading-lg)", letterSpacing: "var(--tracking-lg)", color: "var(--text-primary)" }}>{title}</span>
+      {subtitle ? <span style={{ fontFamily: "var(--font-sans)", fontSize: "var(--text-base)", lineHeight: "var(--leading-base)", letterSpacing: "var(--tracking-base)", color: "var(--text-secondary)" }}>{subtitle}</span> : null}
+    </div>
+  );
+}

package/components/navigation/TopBar.vue

@@ -0,0 +1,51 @@
+<script setup>
+import IconButton from '../buttons/IconButton.vue'
+import Button from '../buttons/Button.vue'
+import SearchInput from '../forms/SearchInput.vue'
+// 56px top bar: bare search left, bell + dark AI Assistant button right.
+defineProps({ placeholder: { type: String, default: 'Search documents, workflows, data...' }, style: Object })
+const emit = defineEmits(['search'])
+</script>
+<template>
+  <header :style="{ height: 'var(--topbar-h)', background: 'var(--bg-surface)', borderBottom: '1px solid var(--border-card)', display: 'flex', alignItems: 'center', justifyContent: 'space-between', padding: '0 24px', boxSizing: 'border-box', flexShrink: 0, ...style }">
+    <SearchInput bare :placeholder="placeholder" @update:modelValue="v => emit('search', v)" style="width:576px;max-width:48%" />
+    <div style="display:flex;align-items:center;gap:8px">
+      <slot name="actions">
+        <IconButton icon="bell" size="lg" />
+        <Button variant="dark" icon="sparkles">AI Assistant</Button>
+      </slot>
+    </div>
+  </header>
+</template>
+
+<!-- PageToolbar — editor toolbar: back chevron, 14px/600 title, "• Editing" status, right action slot. -->
+<!--
+<script setup name="PageToolbar">
+import IconButton from '../buttons/IconButton.vue'
+defineProps({ title: String, status: { type: String, default: '• Editing' }, showBack: Boolean, style: Object })
+const emit = defineEmits(['back'])
+</script>
+<template>
+  <div :style="{ height: 'var(--topbar-h)', background: 'var(--bg-surface)', borderBottom: '1px solid var(--border-card)', display: 'flex', alignItems: 'center', justifyContent: 'space-between', padding: '0 16px', boxSizing: 'border-box', flexShrink: 0, ...style }">
+    <div style="display:flex;align-items:center;gap:8px">
+      <IconButton v-if="showBack" icon="chevron-left" size="md" @click="emit('back')" />
+      <span style="font-family:var(--font-sans);font-weight:var(--weight-semibold);font-size:var(--text-md);line-height:var(--leading-md);letter-spacing:var(--tracking-md);color:var(--text-heading)">{{ title }}</span>
+      <span v-if="status" style="font-family:var(--font-sans);font-size:var(--text-sm);line-height:var(--leading-sm);color:var(--text-muted);margin-left:6px">{{ status }}</span>
+    </div>
+    <div style="display:flex;align-items:center;gap:8px"><slot name="actions" /></div>
+  </div>
+</template>
+-->
+
+<!-- PageHeading — page heading block: 15px/500 title + 13px muted subtitle. -->
+<!--
+<script setup name="PageHeading">
+defineProps({ title: String, subtitle: String, style: Object })
+</script>
+<template>
+  <div :style="{ display: 'flex', flexDirection: 'column', gap: 4, ...style }">
+    <span style="font-family:var(--font-sans);font-weight:var(--weight-medium);font-size:var(--text-lg);line-height:var(--leading-lg);letter-spacing:var(--tracking-lg);color:var(--text-primary)">{{ title }}</span>
+    <span v-if="subtitle" style="font-family:var(--font-sans);font-size:var(--text-base);line-height:var(--leading-base);letter-spacing:var(--tracking-base);color:var(--text-secondary)">{{ subtitle }}</span>
+  </div>
+</template>
+-->