@devxcrew/react-ui 0.0.0-stage → 0.1.7

package/src/features/interface-topology/use-interface-topology.ts

@@ -0,0 +1,178 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import type {
+  InterfaceTopologyController,
+  InterfaceTopologyDesk,
+  InterfaceTopologySection,
+} from './interface-topology.types';
+
+const labelsStorageKey = 'codexsun.ui.ito.labels-visible';
+
+export function useInterfaceTopology(desks: readonly InterfaceTopologyDesk[]): InterfaceTopologyController {
+  validateInterfaceTopologyDesks(desks);
+  const allSections = useMemo(() => desks.flatMap((desk) => desk.sections), [desks]);
+  const [scopeRootId, setScopeRootId] = useState<string | null>(null);
+  const scopedDesks = useMemo(
+    () =>
+      scopeRootId
+        ? desks
+            .map((desk) => ({
+              ...desk,
+              sections: desk.sections.filter(({ id }) => id === scopeRootId || id.startsWith(`${scopeRootId}.`)),
+            }))
+            .filter((desk) => desk.sections.length > 0)
+        : desks,
+    [desks, scopeRootId],
+  );
+  const firstDesk = scopedDesks[0];
+  const [activeDeskId, setActiveDeskId] = useState(firstDesk?.id ?? '');
+  const activeDesk = scopedDesks.find(({ id }) => id === activeDeskId) ?? firstDesk;
+  const sections = activeDesk?.sections ?? [];
+  const firstId = sections[0]?.id ?? '';
+  const [labelsVisible, setLabelsVisible] = useState(readLabelsVisibility);
+  const [open, setOpen] = useState(false);
+  const [highlighting, setHighlighting] = useState(false);
+  const [selected, setSelected] = useState(firstId);
+  const sectionIds = useMemo(
+    () => new Set(scopedDesks.flatMap((desk) => desk.sections.map(({ id }) => id))),
+    [scopedDesks],
+  );
+  const pageKey = scopedDesks
+    .map((desk) => `${desk.id}:${desk.sections.map(({ technicalName }) => technicalName).join('|')}`)
+    .join(';');
+
+  useEffect(() => setHighlighting(false), [pageKey]);
+  useEffect(() => {
+    if (!scopedDesks.some(({ id }) => id === activeDeskId)) setActiveDeskId(firstDesk?.id ?? '');
+  }, [activeDeskId, firstDesk?.id, scopedDesks]);
+  useEffect(() => {
+    if (!sections.some(({ id }) => id === selected)) setSelected(firstId);
+  }, [firstId, sections, selected]);
+
+  function inspect(id: string) {
+    const owner = scopedDesks.find((desk) => desk.sections.some((section) => section.id === id));
+    if (!owner) return;
+    setActiveDeskId(owner.id);
+    copyTechnicalName(id);
+    setSelected(id);
+    setHighlighting(true);
+    setOpen(true);
+  }
+
+  function copyTechnicalName(id: string) {
+    const section = allSections.find((candidate) => candidate.id === id);
+    if (section) copyText(section.technicalName);
+  }
+
+  function selectDesk(id: string) {
+    const desk = scopedDesks.find((candidate) => candidate.id === id);
+    if (!desk) return;
+    setActiveDeskId(id);
+    setSelected(desk.sections[0]?.id ?? '');
+    setHighlighting(false);
+  }
+
+  function toggleLabels() {
+    setLabelsVisible((current) => {
+      const next = !current;
+      persistLabelsVisibility(next);
+      return next;
+    });
+  }
+
+  const setScope = useCallback((rootId: string | null) => setScopeRootId(rootId), []);
+
+  return {
+    activeDeskId,
+    allSections,
+    close: () => setOpen(false),
+    copyTechnicalName,
+    desks: scopedDesks,
+    highlightClassName: () =>
+      'data-[ito-highlighted=true]:ring-2 data-[ito-highlighted=true]:ring-inset data-[ito-highlighted=true]:ring-violet-700',
+    highlighting,
+    inspect,
+    labelsVisible,
+    open,
+    regionProps: (id) => ({
+      'data-ito-highlighted': sectionIds.has(id) && highlighting && selected === id,
+      'data-ito-section': id,
+    }),
+    sections,
+    select: setSelected,
+    selectDesk,
+    setScope,
+    selected,
+    toggleHighlight: () => setHighlighting((current) => !current),
+    toggleLabels,
+    toggleOpen: () => setOpen((current) => !current),
+  };
+}
+
+export function validateInterfaceTopologyDesks(desks: readonly InterfaceTopologyDesk[]): void {
+  const deskIds = new Set<string>();
+  for (const desk of desks) {
+    if (deskIds.has(desk.id)) throw new Error(`Duplicate ITO desk id: ${desk.id}`);
+    deskIds.add(desk.id);
+  }
+  validateInterfaceTopologySections(desks.flatMap((desk) => desk.sections));
+}
+
+export function validateInterfaceTopologySections(sections: readonly InterfaceTopologySection[]): void {
+  const ids = new Set<string>();
+  const technicalNames = new Set<string>();
+
+  for (const section of sections) {
+    if (ids.has(section.id)) throw new Error(`Duplicate ITO id: ${section.id}`);
+    if (technicalNames.has(section.technicalName)) {
+      throw new Error(`Duplicate ITO technical name: ${section.technicalName}`);
+    }
+    if (!/^[a-z][a-zA-Z0-9]*\.[a-z][a-zA-Z0-9]*\.[a-z][a-zA-Z0-9]*$/.test(section.technicalName)) {
+      throw new Error(`ITO technical name must use section.block.control: ${section.technicalName}`);
+    }
+    ids.add(section.id);
+    technicalNames.add(section.technicalName);
+  }
+
+  for (const section of sections) {
+    const parentId = section.id.includes('.') ? section.id.slice(0, section.id.lastIndexOf('.')) : '';
+    if (parentId && !ids.has(parentId)) {
+      throw new Error(`ITO item ${section.id} is missing parent ${parentId}`);
+    }
+  }
+}
+
+function readLabelsVisibility() {
+  if (typeof window === 'undefined') return false;
+  try {
+    return window.localStorage.getItem(labelsStorageKey) === 'true';
+  } catch {
+    return false;
+  }
+}
+
+function persistLabelsVisibility(visible: boolean) {
+  try {
+    window.localStorage.setItem(labelsStorageKey, String(visible));
+  } catch {
+    // The session state still works when browser storage is unavailable.
+  }
+}
+
+function copyText(value: string) {
+  if (navigator.clipboard?.writeText) {
+    void navigator.clipboard.writeText(value).catch(() => fallbackCopy(value));
+    return;
+  }
+  fallbackCopy(value);
+}
+
+function fallbackCopy(value: string) {
+  const target = document.createElement('textarea');
+  target.value = value;
+  target.setAttribute('readonly', '');
+  target.className = 'fixed opacity-0';
+  document.body.append(target);
+  target.select();
+  document.execCommand('copy');
+  target.remove();
+}

package/src/hooks/use-mobile.ts

@@ -0,0 +1,19 @@
+import * as React from 'react'
+
+const MOBILE_BREAKPOINT = 768
+
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    }
+    mql.addEventListener('change', onChange)
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    return () => mql.removeEventListener('change', onChange)
+  }, [])
+
+  return !!isMobile
+}

package/src/hooks/use-scroll-follow.ts

@@ -0,0 +1,22 @@
+import { useEffect, useRef } from 'react'
+
+/** Follow updates only while the reader remains near the end of the scroll viewport. */
+export function useScrollFollow(update: unknown, resetKey: unknown) {
+  const endRef = useRef<HTMLDivElement>(null)
+  const following = useRef(true)
+  useEffect(() => {
+    const viewport = endRef.current?.closest<HTMLElement>('[data-slot="scroll-area-viewport"]')
+    if (!viewport) return
+    following.current = true
+    endRef.current?.scrollIntoView({ block: 'end' })
+    const onScroll = () => {
+      following.current = viewport.scrollHeight - viewport.scrollTop - viewport.clientHeight < 80
+    }
+    viewport.addEventListener('scroll', onScroll, { passive: true })
+    return () => viewport.removeEventListener('scroll', onScroll)
+  }, [resetKey])
+  useEffect(() => {
+    if (following.current) endRef.current?.scrollIntoView({ block: 'end' })
+  }, [update])
+  return endRef
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export { cn } from "./lib/utils";
+export { PdfProvider, type PdfDocumentSource, type PdfShareChannel } from "./providers/pdf-provider";
+export { designTokens } from "./tokens/index";
+export { MainWorkspace, type MainWorkspaceProps, type MdiNavigationSection } from "./layouts/main-workspace";
+export { Mdi, type MdiProps } from "./layouts/mdi";
+export { DocumentationWorkspace, type DocumentationWorkspaceProps } from "./layouts/documentation-workspace";
+export {
+  WorkspaceApplicationHeader,
+  type WorkspaceApplicationHeaderProps,
+} from "./blocks/workspace";
+export { useMdiTopology, type MdiNavigationItem } from "./layouts/main-workspace";

package/src/layouts/README.md

@@ -0,0 +1,65 @@
+# UI Layouts
+
+Layouts are shared application frames. They own reusable navigation chrome and content boundaries,
+but they do not own product routes, business entities, persistence, or workflows.
+
+## Layout boundaries
+
+- `main-workspace` is the shared shell for desktop application workspaces.
+- `mdi` is a plain centered-label surface for layout previews and empty states.
+- `documentation-workspace` applies Docs defaults to `main-workspace`.
+- `agent-workspace` adds activity rails inside `main-workspace`.
+- `site-header`, `ecommerce-header`, and `blog-header` are standalone page headers. Do not compose
+  them into `main-workspace`.
+
+Each layout folder exports one public component through `index.ts`. Keep its internal parts in the
+same folder. Name internal parts after their visible job, such as `ecommerce-search` or
+`ecommerce-navigation`.
+
+- `main-workspace` provides the CODEXSUN multiple-document application frame. Its public parts
+  include the top menu, application switcher, profile menu, shadcn sidebar, status bar, and feature
+  settings screen. Pass application-owned navigation data and workspace content through the public
+  layout contract. Applications can provide a controlled search value and change callback; the
+  layout renders the field but does not own search state or result behavior.
+
+  When an application omits `children`, MDI leaves the workspace canvas empty.
+
+- `agent-workspace` provides a fixed Primary Activity Rail, a center Workspace Canvas, and a fixed
+  Secondary Utility Rail. Applications supply typed icon items and actions.
+
+Pass `agentWorkspace` to `MainWorkspace` to connect the Agent Workspace inside the shared shell. The
+built-in feature settings show one visibility switch for each activity rail. MDI places the Primary
+Activity Rail before the default sidebar and keeps the utility rail rightmost.
+
+Applications can replace the standard primary action and navigation area with `sidebarContent`. They
+can replace the footer with a React node or pass `null` to remove it. An omitted `sidebarFooter`
+keeps the shared Feature settings footer. The MDI shell continues to own sidebar sizing, collapse
+behavior, and the rail toggle.
+
+An application can map a parent ITO group to the complete area below the command bar with
+`deskRegionId`. Its workspace and sidebar regions can then be registered as child components of that
+desk.
+
+Feature visibility is stored per `applicationId`. The shared feature settings screen can toggle the
+top menu, notifications, application switcher, profile menu, and bottom status bar. Product routes
+and workflows remain app-owned.
+
+Applications can pass `statusEnd` to place compact metadata at the right edge of the status bar. The
+application owns the content and its text style.
+
+`MainWorkspace` binds `@devxcrew/react-ui/theme` for every application. The appearance control changes
+light, dark, or system mode and the shared accent composition. Applications must use semantic tokens
+instead of storing their own shell theme.
+
+`MainWorkspace` also sets the browser document title from `applicationName`. Shared templates and
+application routes must not replace this title.
+
+Applications import layouts through their public `@devxcrew/react-ui/layouts/*` entry points.
+
+The default MDI application catalog links Platform, UI, Docs, and Zetro. It uses the documented
+local ports when the current host is localhost or `127.0.0.1`. Applications can provide `apps` to
+replace these destinations for a deployed environment.
+
+The ITO inspector shows a shadcn Select only when the current page supplies more than one desk.
+`showMdiOverview` adds the shared MDI Overview desk. A normal application desk contains only
+app-owned regions and does not show the desk selector.

package/src/layouts/agent-workspace/agent-activity-rail.tsx

@@ -0,0 +1,101 @@
+import { cn } from '@devxcrew/react-ui/lib/utils'
+import { Button } from '@devxcrew/react-ui/components/button'
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '@devxcrew/react-ui/components/tooltip'
+
+import type { AgentWorkspaceRail, AgentWorkspaceRailItem } from './agent-workspace.types'
+
+type AgentActivityRailProps = {
+  rail: AgentWorkspaceRail
+  side: 'left' | 'right'
+  visible: boolean
+}
+
+export function AgentActivityRail({ rail, side, visible }: AgentActivityRailProps) {
+  return (
+    <TooltipProvider>
+      <aside
+        aria-hidden={!visible}
+        aria-label={rail.label}
+        className={cn(
+          'relative z-20 h-full shrink-0 overflow-hidden bg-sidebar transition-[width,opacity,border-color] duration-200 motion-reduce:transition-none',
+          visible
+            ? cn('w-14 border-border opacity-100', side === 'left' ? 'border-r' : 'border-l')
+            : 'pointer-events-none w-0 border-0 opacity-0',
+        )}
+      >
+        {visible ? (
+          <div className="flex h-full w-14 flex-col items-center gap-2 px-2 py-3">
+            <RailItems items={rail.items} side={side} />
+            {rail.footerItems?.length ? (
+              <div className="flex min-h-0 flex-1 flex-col justify-end">
+                <RailItems items={rail.footerItems} side={side} />
+              </div>
+            ) : null}
+          </div>
+        ) : null}
+      </aside>
+    </TooltipProvider>
+  )
+}
+
+function RailItems({
+  items,
+  side,
+}: {
+  items: readonly AgentWorkspaceRailItem[]
+  side: 'left' | 'right'
+}) {
+  return (
+    <nav
+      className="flex flex-col gap-2"
+      aria-label={side === 'left' ? 'Primary tools' : 'Secondary tools'}
+    >
+      {items.map((item) => (
+        <RailAction item={item} key={item.id} side={side} />
+      ))}
+    </nav>
+  )
+}
+
+function RailAction({ item, side }: { item: AgentWorkspaceRailItem; side: 'left' | 'right' }) {
+  const Icon = item.icon
+
+  return (
+    <Tooltip>
+      <TooltipTrigger
+        render={
+          <Button
+            aria-label={item.label}
+            aria-current={item.active ? 'page' : undefined}
+            className={cn(
+              'relative hover:translate-y-0 active:translate-y-0 motion-reduce:transition-none',
+              item.active &&
+                'bg-sidebar-accent text-sidebar-accent-foreground ring-1 ring-sidebar-border before:absolute before:inset-y-2 before:-left-1.5 before:w-0.5 before:rounded-full before:bg-primary hover:bg-sidebar-accent',
+            )}
+            disabled={item.disabled}
+            size="icon"
+            variant={item.active ? 'secondary' : 'ghost'}
+            onClick={item.onSelect}
+          />
+        }
+      >
+        <Icon />
+        {item.badge !== undefined ? <RailBadge value={item.badge} /> : null}
+      </TooltipTrigger>
+      <TooltipContent side={side === 'left' ? 'right' : 'left'}>{item.label}</TooltipContent>
+    </Tooltip>
+  )
+}
+
+function RailBadge({ value }: { value: number | string }) {
+  return (
+    <span className="absolute top-0.5 right-0.5 grid min-h-3.5 min-w-3.5 place-items-center rounded-full bg-primary px-1 text-[10px] leading-none font-semibold text-primary-foreground">
+      {value}
+    </span>
+  )
+}

package/src/layouts/agent-workspace/agent-workspace.tsx

@@ -0,0 +1,27 @@
+import { cn } from '@devxcrew/react-ui/lib/utils'
+
+import { AgentActivityRail } from './agent-activity-rail'
+import type { AgentWorkspaceProps } from './agent-workspace.types'
+
+export function AgentWorkspace({
+  canvasClassName,
+  children,
+  className,
+  primaryRail,
+  secondaryRail,
+  showPrimaryRail = true,
+  showSecondaryRail = true,
+}: AgentWorkspaceProps) {
+  return (
+    <section
+      aria-label="Agent workspace"
+      className={cn('flex size-full min-h-0 min-w-0 overflow-hidden bg-background', className)}
+    >
+      <AgentActivityRail rail={primaryRail} side="left" visible={showPrimaryRail} />
+      <div className={cn('relative min-h-0 min-w-0 flex-1 overflow-hidden', canvasClassName)}>
+        {children}
+      </div>
+      <AgentActivityRail rail={secondaryRail} side="right" visible={showSecondaryRail} />
+    </section>
+  )
+}

package/src/layouts/agent-workspace/agent-workspace.types.ts

@@ -0,0 +1,28 @@
+import type { LucideIcon } from 'lucide-react'
+import type { ReactNode } from 'react'
+
+export type AgentWorkspaceRailItem = {
+  active?: boolean
+  badge?: number | string
+  disabled?: boolean
+  icon: LucideIcon
+  id: string
+  label: string
+  onSelect?: () => void
+}
+
+export type AgentWorkspaceRail = {
+  footerItems?: readonly AgentWorkspaceRailItem[]
+  items: readonly AgentWorkspaceRailItem[]
+  label: string
+}
+
+export type AgentWorkspaceProps = {
+  canvasClassName?: string
+  children?: ReactNode
+  className?: string
+  primaryRail: AgentWorkspaceRail
+  secondaryRail: AgentWorkspaceRail
+  showPrimaryRail?: boolean
+  showSecondaryRail?: boolean
+}

package/src/layouts/agent-workspace/index.ts

@@ -0,0 +1,7 @@
+export { AgentWorkspace } from './agent-workspace'
+export { AgentActivityRail } from './agent-activity-rail'
+export type {
+  AgentWorkspaceProps,
+  AgentWorkspaceRail,
+  AgentWorkspaceRailItem,
+} from './agent-workspace.types'

package/src/layouts/blog-header/blog-header-types.ts

@@ -0,0 +1,25 @@
+import type { ReactNode } from 'react'
+
+export type BlogTopicTag = {
+  readonly active?: boolean
+  readonly href: string
+  readonly id: string
+  readonly label: string
+  readonly postCount?: number
+}
+
+export type BlogHeaderProps = {
+  readonly backToStoreHref?: string
+  readonly backToStoreLabel?: string
+  readonly brand: {
+    readonly badge?: string
+    readonly href?: string
+    readonly logo?: ReactNode
+    readonly title: string
+  }
+  readonly className?: string
+  readonly onNewsletterClick?: () => void
+  readonly onSearch?: (query: string) => void
+  readonly readingProgress?: number
+  readonly topics?: readonly BlogTopicTag[]
+}

package/src/layouts/blog-header/blog-header.tsx

@@ -0,0 +1,172 @@
+import { useState, useEffect } from 'react'
+import { ArrowLeftIcon, BookOpenIcon, MailIcon, SearchIcon, XIcon } from 'lucide-react'
+import { cn } from '../../lib/utils'
+import { Button } from '../../components/button'
+import { Badge } from '../../components/badge'
+import type { BlogHeaderProps } from './blog-header-types'
+
+export function BlogHeader({
+  backToStoreHref = '/',
+  backToStoreLabel = 'Back to Store',
+  brand,
+  className,
+  onNewsletterClick,
+  onSearch,
+  readingProgress: explicitProgress,
+  topics = [
+    { active: true, href: '#all', id: 'all', label: 'All Stories' },
+    { href: '#engineering', id: 'engineering', label: 'Engineering' },
+    { href: '#product-design', id: 'product-design', label: 'Product Design' },
+    { href: '#architecture', id: 'architecture', label: 'Architecture' },
+    { href: '#guides', id: 'guides', label: 'Guides & Case Studies' },
+  ],
+}: BlogHeaderProps) {
+  const [scrollProgress, setScrollProgress] = useState(0)
+  const [searchQuery, setSearchQuery] = useState('')
+  const [showSearch, setShowSearch] = useState(false)
+
+  useEffect(() => {
+    if (explicitProgress !== undefined) return
+
+    const handleScroll = () => {
+      const totalHeight = document.documentElement.scrollHeight - window.innerHeight
+      if (totalHeight <= 0) {
+        setScrollProgress(0)
+        return
+      }
+      const currentProgress = (window.scrollY / totalHeight) * 100
+      setScrollProgress(Math.min(100, Math.max(0, currentProgress)))
+    }
+
+    window.addEventListener('scroll', handleScroll, { passive: true })
+    return () => window.removeEventListener('scroll', handleScroll)
+  }, [explicitProgress])
+
+  const progress = explicitProgress !== undefined ? explicitProgress : scrollProgress
+
+  return (
+    <header
+      className={cn(
+        'sticky top-0 z-40 w-full border-b border-border/80 bg-background/95 backdrop-blur-md',
+        className,
+      )}
+    >
+      {/* 1. Scroll / Reading Progress Line */}
+      <div className="absolute top-0 left-0 right-0 h-1 bg-muted/40">
+        <div
+          className="h-full bg-primary transition-all duration-150"
+          style={{ width: `${progress}%` }}
+        />
+      </div>
+
+      {/* 2. Top Bridge & Brand Bar */}
+      <div className="mx-auto flex max-w-7xl items-center justify-between gap-4 px-4 py-3">
+        {/* Back to Store link + Brand */}
+        <div className="flex items-center gap-4">
+          <a
+            href={backToStoreHref}
+            className="flex items-center gap-1.5 text-xs font-semibold text-muted-foreground hover:text-foreground transition-colors"
+          >
+            <ArrowLeftIcon className="size-3.5" />
+            <span>{backToStoreLabel}</span>
+          </a>
+
+          <div className="h-4 w-px bg-border/80 hidden sm:block" />
+
+          <a href={brand.href ?? '/blog'} className="flex items-center gap-2">
+            {brand.logo ?? <BookOpenIcon className="size-5 text-primary" />}
+            <div className="flex items-baseline gap-2">
+              <span className="text-lg font-bold tracking-tight text-foreground">
+                {brand.title}
+              </span>
+              {brand.badge && (
+                <Badge variant="secondary" className="text-[10px] font-semibold py-0">
+                  {brand.badge}
+                </Badge>
+              )}
+            </div>
+          </a>
+        </div>
+
+        {/* Search & Newsletter CTA */}
+        <div className="flex items-center gap-2">
+          {showSearch ? (
+            <div className="flex items-center rounded-lg border border-input bg-muted/30 px-2.5 py-1">
+              <SearchIcon className="size-3.5 text-muted-foreground mr-1.5" />
+              <input
+                type="text"
+                value={searchQuery}
+                onChange={(e) => setSearchQuery(e.target.value)}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter') onSearch?.(searchQuery)
+                }}
+                placeholder="Search articles..."
+                className="w-36 sm:w-48 bg-transparent text-xs placeholder:text-muted-foreground focus:outline-none"
+                autoFocus
+              />
+              <button
+                type="button"
+                onClick={() => setShowSearch(false)}
+                className="text-muted-foreground hover:text-foreground ml-1"
+              >
+                <XIcon className="size-3.5" />
+              </button>
+            </div>
+          ) : (
+            <Button
+              size="sm"
+              variant="ghost"
+              className="h-8 gap-1.5 text-xs text-muted-foreground hover:text-foreground"
+              onClick={() => setShowSearch(true)}
+            >
+              <SearchIcon className="size-4" />
+              <span className="hidden sm:inline">Search</span>
+            </Button>
+          )}
+
+          <Button
+            size="sm"
+            variant="default"
+            className="h-8 gap-1.5 text-xs font-medium"
+            onClick={onNewsletterClick}
+          >
+            <MailIcon className="size-3.5" />
+            <span>Subscribe</span>
+          </Button>
+        </div>
+      </div>
+
+      {/* 3. Topics Strip */}
+      {topics.length > 0 && (
+        <div className="border-t border-border/40 bg-muted/15 px-4 py-1.5">
+          <div className="mx-auto flex max-w-7xl items-center gap-1.5 overflow-x-auto no-scrollbar">
+            {topics.map((t) => (
+              <a
+                key={t.id}
+                href={t.href}
+                className={cn(
+                  'flex items-center gap-1 rounded-full px-3 py-1 text-xs font-medium transition-all',
+                  t.active
+                    ? 'bg-primary text-primary-foreground font-semibold shadow-xs'
+                    : 'text-muted-foreground hover:bg-muted hover:text-foreground',
+                )}
+              >
+                <span>{t.label}</span>
+                {t.postCount !== undefined && (
+                  <span
+                    className={cn(
+                      'text-[10px] opacity-75',
+                      t.active ? 'text-primary-foreground' : 'text-muted-foreground',
+                    )}
+                  >
+                    ({t.postCount})
+                  </span>
+                )}
+              </a>
+            ))}
+          </div>
+        </div>
+      )}
+    </header>
+  )
+}

package/src/layouts/blog-header/index.ts

@@ -0,0 +1,2 @@
+export * from './blog-header'
+export * from './blog-header-types'

package/src/layouts/documentation-workspace/README.md

@@ -0,0 +1,8 @@
+# Documentation Workspace
+
+`DocumentationWorkspace` is the shared MDI shell for documentation and knowledge applications. It
+supplies Docs identity, search, sidebar persistence, status, and workspace defaults while the owning
+application supplies navigation, content, settings, topology, and data loading.
+
+Import it from `@devxcrew/react-ui/layouts/documentation-workspace`. Do not put document persistence,
+repository discovery, editing, or application routes in this package layout.