@fragments-sdk/viewer 0.2.1

package/src/shared/DocsHeaderBar.tsx

@@ -0,0 +1,129 @@
+'use client';
+
+import { Header, NavigationMenu } from '@fragments-sdk/ui';
+import type { ReactNode } from 'react';
+import { DocsSearchCommand } from './DocsSearchCommand';
+import type { DocsNavLinkRenderer, HeaderNavEntry, NavSection, SearchItem } from './types';
+import { isDropdown } from './types';
+
+interface DocsHeaderBarProps {
+  brand: ReactNode;
+  headerNav: HeaderNavEntry[];
+  mobileSections?: NavSection[];
+  currentPath: string;
+  searchItems: SearchItem[];
+  onSearchSelect: (item: SearchItem) => void;
+  renderLink?: DocsNavLinkRenderer;
+  isActive?: (href: string, currentPath: string) => boolean;
+  actions?: ReactNode;
+  showSkipLink?: boolean;
+  navAriaLabel?: string;
+}
+
+const defaultLinkRenderer: DocsNavLinkRenderer = ({ href, label, onClick }) => (
+  <a href={href} onClick={onClick}>
+    {label}
+  </a>
+);
+
+function defaultIsActive(href: string, currentPath: string): boolean {
+  return currentPath === href || currentPath.startsWith(`${href}/`);
+}
+
+export function DocsHeaderBar({
+  brand,
+  headerNav,
+  mobileSections = [],
+  currentPath,
+  searchItems,
+  onSearchSelect,
+  renderLink = defaultLinkRenderer,
+  isActive = defaultIsActive,
+  actions,
+  showSkipLink = true,
+  navAriaLabel = 'Primary navigation',
+}: DocsHeaderBarProps) {
+  return (
+    <Header aria-label="Documentation header">
+      <Header.Brand>{brand}</Header.Brand>
+      {showSkipLink ? <Header.SkipLink /> : null}
+
+      <NavigationMenu aria-label={navAriaLabel}>
+        <NavigationMenu.List>
+          {headerNav.map((entry) =>
+            isDropdown(entry) ? (
+              <NavigationMenu.Item key={entry.label} value={entry.label}>
+                <NavigationMenu.Trigger>{entry.label}</NavigationMenu.Trigger>
+                <NavigationMenu.Content>
+                  <div style={{ display: 'flex', flexDirection: 'column', padding: '4px', minWidth: '180px' }}>
+                    {entry.items.map((child) => (
+                      <NavigationMenu.Link
+                        key={child.href}
+                        href={child.href}
+                        active={isActive(child.href, currentPath)}
+                        asChild
+                      >
+                        {renderLink({ href: child.href, label: child.label })}
+                      </NavigationMenu.Link>
+                    ))}
+                  </div>
+                </NavigationMenu.Content>
+              </NavigationMenu.Item>
+            ) : (
+              <NavigationMenu.Item key={entry.href}>
+                <NavigationMenu.Link
+                  href={entry.href}
+                  active={isActive(entry.href, currentPath)}
+                  asChild
+                >
+                  {renderLink({ href: entry.href, label: entry.label })}
+                </NavigationMenu.Link>
+              </NavigationMenu.Item>
+            )
+          )}
+        </NavigationMenu.List>
+
+        <NavigationMenu.Viewport />
+
+        <NavigationMenu.MobileBrand>{brand}</NavigationMenu.MobileBrand>
+
+        <NavigationMenu.MobileContent>
+          {/* Render all headerNav items in the mobile drawer */}
+          <NavigationMenu.MobileSection>
+            {headerNav.map((entry) =>
+              isDropdown(entry) ? (
+                entry.items.map((child) => (
+                  <NavigationMenu.Link key={child.href} href={child.href} asChild>
+                    {renderLink({ href: child.href, label: child.label })}
+                  </NavigationMenu.Link>
+                ))
+              ) : (
+                <NavigationMenu.Link key={entry.href} href={entry.href} asChild>
+                  {renderLink({ href: entry.href, label: entry.label })}
+                </NavigationMenu.Link>
+              )
+            )}
+          </NavigationMenu.MobileSection>
+
+          {mobileSections.map((section) => (
+            <NavigationMenu.MobileSection key={section.title} label={section.title}>
+              {section.items.map((item) => (
+                <NavigationMenu.Link key={item.href} href={item.href} asChild>
+                  {renderLink({ href: item.href, label: item.label })}
+                </NavigationMenu.Link>
+              ))}
+            </NavigationMenu.MobileSection>
+          ))}
+        </NavigationMenu.MobileContent>
+      </NavigationMenu>
+
+      <Header.Spacer />
+
+      <Header.Search>
+        <DocsSearchCommand searchItems={searchItems} onSelect={onSearchSelect} />
+      </Header.Search>
+
+      <Header.Actions>{actions}</Header.Actions>
+    </Header>
+  );
+}

package/src/shared/DocsPageAsideHost.tsx

@@ -0,0 +1,89 @@
+'use client';
+
+import { createPortal } from 'react-dom';
+import * as React from 'react';
+
+interface DocsPageAsideContextValue {
+  asideVisible: boolean;
+  setAsideVisible: (visible: boolean) => void;
+  asideWidth: string;
+  setAsideWidth: (width: string) => void;
+  asideContainer: HTMLDivElement | null;
+  setAsideContainer: (container: HTMLDivElement | null) => void;
+}
+
+const DocsPageAsideContext = React.createContext<DocsPageAsideContextValue | null>(null);
+
+export function DocsPageAsideProvider({
+  children,
+  defaultWidth = '320px',
+}: {
+  children: React.ReactNode;
+  defaultWidth?: string;
+}) {
+  const [asideVisible, setAsideVisible] = React.useState(false);
+  const [asideWidth, setAsideWidth] = React.useState(defaultWidth);
+  const [asideContainer, setAsideContainer] = React.useState<HTMLDivElement | null>(null);
+
+  return (
+    <DocsPageAsideContext.Provider
+      value={{
+        asideVisible,
+        setAsideVisible,
+        asideWidth,
+        setAsideWidth,
+        asideContainer,
+        setAsideContainer,
+      }}
+    >
+      {children}
+    </DocsPageAsideContext.Provider>
+  );
+}
+
+export function useDocsPageAside() {
+  const context = React.useContext(DocsPageAsideContext);
+  if (!context) {
+    throw new Error('useDocsPageAside must be used within DocsPageAsideProvider');
+  }
+  return context;
+}
+
+export function DocsPageAsidePortal({ children, width = '320px' }: { children: React.ReactNode; width?: string }) {
+  const { setAsideVisible, setAsideWidth, asideContainer } = useDocsPageAside();
+
+  React.useLayoutEffect(() => {
+    setAsideVisible(true);
+    setAsideWidth(width);
+
+    return () => {
+      setAsideVisible(false);
+    };
+  }, [setAsideVisible, setAsideWidth, width]);
+
+  if (!asideContainer) {
+    return null;
+  }
+
+  return createPortal(children, asideContainer);
+}
+
+interface DocsPageAsideHostProps {
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+export function DocsPageAsideHost({ className, style }: DocsPageAsideHostProps) {
+  const { setAsideContainer } = useDocsPageAside();
+
+  const asideContainerCallback = React.useCallback(
+    (node: HTMLDivElement | null) => {
+      setAsideContainer(node);
+    },
+    [setAsideContainer]
+  );
+
+  return (
+    <div ref={asideContainerCallback} className={className} style={{ height: '100%', ...style }} />
+  );
+}

package/src/shared/DocsPageShell.tsx

@@ -0,0 +1,124 @@
+'use client';
+
+import { AppShell } from '@fragments-sdk/ui';
+import type { ReactNode } from 'react';
+import { DocsPageAsideHost, DocsPageAsideProvider, useDocsPageAside } from './DocsPageAsideHost';
+
+type SidebarCollapsible = 'offcanvas' | 'icon' | 'none';
+
+interface DocsPageShellProps {
+  header: ReactNode;
+  sidebar: ReactNode;
+  children: ReactNode;
+  sidebarWidth?: string;
+  sidebarCollapsible?: SidebarCollapsible;
+  sidebarDefaultCollapsed?: boolean;
+  sidebarAriaLabel?: string;
+  mainId?: string;
+  mainAriaLabel?: string;
+  mainPadding?: 'none' | 'sm' | 'md' | 'lg';
+  mainClassName?: string;
+  aside?: ReactNode;
+  asideWidth?: string;
+  useAsidePortal?: boolean;
+}
+
+function DocsPageShellInner({
+  header,
+  sidebar,
+  children,
+  sidebarWidth = '260px',
+  sidebarCollapsible = 'offcanvas',
+  sidebarDefaultCollapsed,
+  sidebarAriaLabel = 'Documentation sidebar',
+  mainId = 'main-content',
+  mainAriaLabel = 'Documentation content',
+  mainPadding = 'lg',
+  mainClassName,
+  aside,
+  asideWidth = '320px',
+  useAsidePortal = false,
+}: DocsPageShellProps) {
+  return (
+    <AppShell>
+      <AppShell.Header>{header}</AppShell.Header>
+
+      <AppShell.Sidebar
+        width={sidebarWidth}
+        collapsible={sidebarCollapsible}
+        defaultCollapsed={sidebarDefaultCollapsed}
+        aria-label={sidebarAriaLabel}
+      >
+        {sidebar}
+      </AppShell.Sidebar>
+
+      <AppShell.Main
+        id={mainId}
+        aria-label={mainAriaLabel}
+        padding={mainPadding}
+        className={mainClassName}
+      >
+        {children}
+      </AppShell.Main>
+
+      {useAsidePortal ? <DocsPageAsideHost /> : null}
+      {!useAsidePortal && aside ? <AppShell.Aside width={asideWidth}>{aside}</AppShell.Aside> : null}
+    </AppShell>
+  );
+}
+
+function DocsPageShellPortalInner({
+  header,
+  sidebar,
+  children,
+  sidebarWidth = '260px',
+  sidebarCollapsible = 'offcanvas',
+  sidebarDefaultCollapsed,
+  sidebarAriaLabel = 'Documentation sidebar',
+  mainId = 'main-content',
+  mainAriaLabel = 'Documentation content',
+  mainPadding = 'lg',
+  mainClassName,
+}: DocsPageShellProps) {
+  const { asideVisible, asideWidth } = useDocsPageAside();
+
+  return (
+    <AppShell>
+      <AppShell.Header>{header}</AppShell.Header>
+
+      <AppShell.Sidebar
+        width={sidebarWidth}
+        collapsible={sidebarCollapsible}
+        defaultCollapsed={sidebarDefaultCollapsed}
+        aria-label={sidebarAriaLabel}
+      >
+        {sidebar}
+      </AppShell.Sidebar>
+
+      <AppShell.Main
+        id={mainId}
+        aria-label={mainAriaLabel}
+        padding={mainPadding}
+        className={mainClassName}
+      >
+        {children}
+      </AppShell.Main>
+
+      <AppShell.Aside width={asideWidth} visible={asideVisible} aria-label="On-page controls">
+        <DocsPageAsideHost />
+      </AppShell.Aside>
+    </AppShell>
+  );
+}
+
+export function DocsPageShell(props: DocsPageShellProps) {
+  if (props.useAsidePortal) {
+    return (
+      <DocsPageAsideProvider defaultWidth={props.asideWidth}>
+        <DocsPageShellPortalInner {...props} />
+      </DocsPageAsideProvider>
+    );
+  }
+
+  return <DocsPageShellInner {...props} />;
+}

package/src/shared/DocsSearchCommand.tsx

@@ -0,0 +1,99 @@
+'use client';
+
+import { Command, Dialog, Button, Text, Stack } from '@fragments-sdk/ui';
+import { useEffect, useMemo, useState, useCallback } from 'react';
+import type { SearchItem } from './types';
+
+interface DocsSearchCommandProps {
+  searchItems: SearchItem[];
+  onSelect: (item: SearchItem) => void;
+  placeholder?: string;
+  maxResults?: number;
+}
+
+export function DocsSearchCommand({
+  searchItems,
+  onSelect,
+  placeholder = 'Search docs...',
+  maxResults = 9999,
+}: DocsSearchCommandProps) {
+  const [open, setOpen] = useState(false);
+
+  // Cmd+K / Ctrl+K to open
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if ((event.metaKey || event.ctrlKey) && event.key === 'k') {
+        event.preventDefault();
+        setOpen((prev) => !prev);
+      }
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, []);
+
+  // Group items by section
+  const grouped = useMemo(() => {
+    const map = new Map<string, SearchItem[]>();
+    for (const item of searchItems) {
+      const section = item.section || 'Navigation';
+      if (!map.has(section)) map.set(section, []);
+      map.get(section)!.push(item);
+    }
+    return map;
+  }, [searchItems]);
+
+  const handleSelect = useCallback(
+    (item: SearchItem) => {
+      setOpen(false);
+      onSelect(item);
+    },
+    [onSelect],
+  );
+
+  return (
+    <>
+      <Button
+        variant="secondary"
+        size="sm"
+        onClick={() => setOpen(true)}
+        aria-label="Search documentation"
+        style={{ minWidth: 160, justifyContent: 'space-between' }}
+      >
+        <Text size="sm" color="secondary">Search...</Text>
+        <Text size="xs" color="secondary" font="mono">⌘K</Text>
+      </Button>
+
+      <Dialog open={open} onOpenChange={setOpen}>
+        <Dialog.Content size="sm" style={{ padding: 0, overflow: 'hidden' }}>
+          <Command
+            filter={(value, search) => {
+              if (value.toLowerCase().includes(search.toLowerCase())) return 1;
+              return 0;
+            }}
+          >
+            <Command.Input placeholder={placeholder} />
+            <Command.List>
+              <Command.Empty>No results found.</Command.Empty>
+              {[...grouped.entries()].map(([section, items]) => (
+                <Command.Group key={section} heading={section}>
+                  {items.slice(0, maxResults).map((item) => (
+                    <Command.Item
+                      key={`${item.section}:${item.href}`}
+                      value={`${item.label} ${item.section}`}
+                      onItemSelect={() => handleSelect(item)}
+                    >
+                      <Stack direction="row" align="center" justify="between" style={{ width: '100%' }}>
+                        <Text size="sm">{item.label}</Text>
+                      </Stack>
+                    </Command.Item>
+                  ))}
+                </Command.Group>
+              ))}
+            </Command.List>
+          </Command>
+        </Dialog.Content>
+      </Dialog>
+    </>
+  );
+}

package/src/shared/DocsSidebarNav.tsx

@@ -0,0 +1,66 @@
+'use client';
+
+import { Sidebar } from '@fragments-sdk/ui';
+import type { ReactNode } from 'react';
+import type { DocsNavLinkRenderer, NavSection } from './types';
+
+interface DocsSidebarNavProps {
+  sections: NavSection[];
+  currentPath: string;
+  renderLink?: DocsNavLinkRenderer;
+  onNavigate?: () => void;
+  isActive?: (href: string, currentPath: string) => boolean;
+  footer?: ReactNode;
+  ariaLabel?: string;
+}
+
+function defaultIsActive(href: string, currentPath: string): boolean {
+  return currentPath === href;
+}
+
+const defaultLinkRenderer: DocsNavLinkRenderer = ({ href, label, onClick }) => (
+  <a href={href} onClick={onClick}>
+    {label}
+  </a>
+);
+
+export function DocsSidebarNav({
+  sections,
+  currentPath,
+  renderLink = defaultLinkRenderer,
+  onNavigate,
+  isActive = defaultIsActive,
+  footer,
+  ariaLabel = 'Navigation',
+}: DocsSidebarNavProps) {
+  return (
+    <>
+      <Sidebar.Nav aria-label={ariaLabel}>
+        {sections.map((section) => (
+          <Sidebar.Section
+            key={section.title}
+            label={section.title}
+            collapsible={section.collapsible}
+            defaultOpen={section.defaultOpen}
+          >
+            {section.items.map((item) => (
+              <Sidebar.Item
+                key={item.href}
+                active={isActive(item.href, currentPath)}
+                asChild
+              >
+                {renderLink({
+                  href: item.href,
+                  label: item.label,
+                  onClick: onNavigate,
+                })}
+              </Sidebar.Item>
+            ))}
+          </Sidebar.Section>
+        ))}
+      </Sidebar.Nav>
+
+      <Sidebar.Footer>{footer}</Sidebar.Footer>
+    </>
+  );
+}

package/src/shared/PropsTable.module.scss

@@ -0,0 +1,68 @@
+.container {
+  margin: 1.5rem 0;
+  overflow-x: auto;
+}
+
+.empty {
+  color: var(--fui-text-tertiary);
+  font-style: italic;
+}
+
+.table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.875rem;
+
+  th, td {
+    text-align: left;
+    padding: 0.75rem;
+    border-bottom: 1px solid var(--fui-border);
+  }
+
+  th {
+    font-weight: var(--fui-font-weight-semibold);
+    color: var(--fui-text-secondary);
+    background-color: var(--fui-bg-secondary);
+  }
+
+  td {
+    vertical-align: top;
+  }
+}
+
+.propName {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+
+  code {
+    font-weight: var(--fui-font-weight-semibold);
+  }
+}
+
+.type {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.values {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem;
+}
+
+.value {
+  font-size: 0.75rem;
+  background-color: var(--fui-bg-tertiary);
+  padding: 0.125rem 0.375rem;
+  border-radius: var(--fui-radius-sm);
+}
+
+.default {
+  color: var(--fui-color-accent);
+}
+
+.noDefault {
+  color: var(--fui-text-tertiary);
+}

package/src/shared/PropsTable.module.scss.d.ts

@@ -0,0 +1,2 @@
+declare const styles: Record<string, string>;
+export default styles;

package/src/shared/PropsTable.tsx

@@ -0,0 +1,76 @@
+'use client';
+
+import { Badge } from '@fragments-sdk/ui';
+import type { DocProp } from './types';
+import styles from './PropsTable.module.scss';
+
+/** Detect auto-generated descriptions like "variant prop" */
+function isGenericPropDescription(name: string, description: string): boolean {
+  const lower = description.toLowerCase().trim();
+  return lower === `${name.toLowerCase()} prop` || lower === `${name.toLowerCase()} property`;
+}
+
+interface PropsTableProps {
+  props: Record<string, DocProp>;
+}
+
+export function PropsTable({ props }: PropsTableProps) {
+  const propEntries = Object.entries(props);
+
+  if (propEntries.length === 0) {
+    return <p className={styles.empty}>No props documented</p>;
+  }
+
+  return (
+    <div className={styles.container}>
+      <table className={styles.table}>
+        <thead>
+          <tr>
+            <th>Prop</th>
+            <th>Type</th>
+            <th>Default</th>
+            <th>Description</th>
+          </tr>
+        </thead>
+        <tbody>
+          {propEntries.map(([name, prop]) => (
+            <tr key={name}>
+              <td>
+                <span className={styles.propName}>
+                  <code>{name}</code>
+                  {prop.required && (
+                    <Badge size="sm" variant="error">
+                      Required
+                    </Badge>
+                  )}
+                </span>
+              </td>
+              <td>
+                <span className={styles.type}>
+                  <code>{prop.type}</code>
+                  {prop.values && (
+                    <span className={styles.values}>
+                      {prop.values.map((v) => (
+                        <code key={v} className={styles.value}>
+                          {v}
+                        </code>
+                      ))}
+                    </span>
+                  )}
+                </span>
+              </td>
+              <td>
+                {prop.default !== undefined ? (
+                  <code className={styles.default}>{String(prop.default)}</code>
+                ) : (
+                  <span className={styles.noDefault}>Not set</span>
+                )}
+              </td>
+              <td>{prop.description && !isGenericPropDescription(name, prop.description) ? prop.description : '—'}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}