@fragments-sdk/viewer 0.2.1 → 0.2.3

package/src/components/SkeletonLoader.tsx

@@ -14,7 +14,6 @@ export function AppSkeleton() {
     <div
       style={{
         display: 'grid',
-        minHeight: '100vh',
         minHeight: '100dvh',
         gridTemplateRows: '56px 1fr',
         gridTemplateColumns: '260px 1fr 240px',

package/src/components/TokenStylePanel.tsx

@@ -332,7 +332,7 @@ export function TokenStylePanel({
       <Stack direction="row" align="center" gap="sm">
         {tokenData && (
           <Badge
-            variant={compliancePercent >= 80 ? 'success' : compliancePercent >= 50 ? 'warning' : 'danger'}
+            variant={compliancePercent >= 80 ? 'success' : compliancePercent >= 50 ? 'warning' : 'error'}
           >
             {compliancePercent}% token compliance
           </Badge>
@@ -343,7 +343,7 @@ export function TokenStylePanel({
         </Badge>
 
         {hardcodedCount > 0 && (
-          <Badge variant="danger">
+          <Badge variant="error">
             {hardcodedCount} hardcoded
           </Badge>
         )}
@@ -414,7 +414,7 @@ export function TokenStylePanel({
                       {prop.rendered}
                     </span>
                     {prop.isHardcoded && (
-                      <Badge variant="danger">HC</Badge>
+                      <Badge variant="error">HC</Badge>
                     )}
                   </div>
                 </td>

package/src/components/TopToolbar.tsx

@@ -32,7 +32,7 @@ interface TopToolbarProps {
   figmaUrl?: string;
   searchQuery: string;
   onSearchChange: (value: string) => void;
-  searchInputRef: RefObject<HTMLInputElement>;
+  searchInputRef: RefObject<HTMLInputElement | null>;
 }
 
 export function TopToolbar({

package/src/components/VariantMatrix.tsx

@@ -33,6 +33,10 @@ interface VariantMatrixProps {
   previewTheme: "light" | "dark";
   /** Whether to use iframe isolation */
   useIframeIsolation?: boolean;
+  /** Variant index currently focused in the main viewer */
+  activeVariantIndex?: number;
+  /** Args overrides to apply to the focused variant only */
+  variantArgsOverrides?: Record<string, unknown>;
   /** Callback when a variant is clicked to focus on it */
   onSelectVariant?: (index: number) => void;
 }
@@ -63,6 +67,8 @@ export function VariantMatrix({
   zoom,
   previewTheme,
   useIframeIsolation = true,
+  activeVariantIndex,
+  variantArgsOverrides,
   onSelectVariant,
 }: VariantMatrixProps) {
   const [gridSize, setGridSize] = useState<GridSize>("medium");
@@ -173,6 +179,7 @@ export function VariantMatrix({
                           isHovered={hoveredIndex === index}
                           onHover={() => setHoveredIndex(index)}
                           onLeave={() => setHoveredIndex(null)}
+                          argsOverrides={index === activeVariantIndex ? variantArgsOverrides : undefined}
                           onClick={() => onSelectVariant?.(index)}
                         />
                       );
@@ -204,6 +211,7 @@ export function VariantMatrix({
                 isHovered={hoveredIndex === index}
                 onHover={() => setHoveredIndex(index)}
                 onLeave={() => setHoveredIndex(null)}
+                argsOverrides={index === activeVariantIndex ? variantArgsOverrides : undefined}
                 onClick={() => onSelectVariant?.(index)}
               />
             ))}
@@ -226,6 +234,7 @@ interface VariantCardProps {
   isHovered: boolean;
   onHover: () => void;
   onLeave: () => void;
+  argsOverrides?: Record<string, unknown>;
   onClick: () => void;
 }
 
@@ -241,6 +250,7 @@ function VariantCard({
   isHovered,
   onHover,
   onLeave,
+  argsOverrides,
   onClick,
 }: VariantCardProps) {
   return (
@@ -355,7 +365,7 @@ function VariantCard({
                   </Text>
                 }
               >
-                <FragmentRenderer variant={variant}>
+                <FragmentRenderer variant={variant} argsOverrides={argsOverrides}>
                   {(content, isLoading, error) => {
                     if (isLoading) {
                       return (

package/src/components/ViewerHeader.tsx

@@ -17,7 +17,7 @@ interface ViewerHeaderProps {
   showHealth: boolean;
   searchQuery: string;
   onSearchChange: (value: string) => void;
-  searchInputRef: RefObject<HTMLInputElement>;
+  searchInputRef: RefObject<HTMLInputElement | null>;
 }
 
 export function ViewerHeader({

package/src/components/WebMCPDevTools.tsx

@@ -151,7 +151,7 @@ export function WebMCPDevTools() {
               <>
                 <Select
                   value={selectedTool}
-                  onValueChange={setSelectedTool}
+                  onValueChange={(value) => setSelectedTool(value ?? "")}
                   placeholder="Select a tool"
                 >
                   <Select.Trigger />
@@ -246,7 +246,7 @@ export function WebMCPDevTools() {
           <Stack direction="column" gap="md" style={{ paddingTop: "12px" }}>
             <Select
               value={selectedTool}
-              onValueChange={setSelectedTool}
+              onValueChange={(value) => setSelectedTool(value ?? "")}
               placeholder="Select a tool"
             >
               <Select.Trigger />

package/src/entry.tsx

@@ -1,5 +1,6 @@
 import { createRoot, type Root } from "react-dom/client";
 import { Component, type ReactNode, type ErrorInfo } from "react";
+import type { FragmentDefinition, FragmentsConfig } from "@fragments-sdk/core";
 import { App } from "./components/App.js";
 import { ThemeProvider } from "./components/ThemeProvider.js";
 import { ToastProvider } from "./components/Toast.js";
@@ -134,9 +135,9 @@ declare global {
   interface Window {
     __FRAGMENTS__?: Array<{
       path: string;
-      fragment: import("../core/index.js").FragmentDefinition;
+      fragment: FragmentDefinition;
     }>;
-    __FRAGMENTS_CONFIG__?: import("../core/index.js").FragmentsConfig;
+    __FRAGMENTS_CONFIG__?: FragmentsConfig;
     __FRAGMENTS_PACKAGE_NAME__?: string | null;
     __FRAGMENTS_ERROR__?: string;
   }
@@ -144,7 +145,7 @@ declare global {
 
 type FragmentItem = {
   path: string;
-  fragment: import("../core/index.js").FragmentDefinition;
+  fragment: FragmentDefinition;
 };
 
 // Initialize fragments from window or empty array
@@ -309,13 +310,10 @@ if (rootElement) {
 }
 
 // HMR support for entry file and a11y invalidation
-// @ts-expect-error Vite HMR types
 if (import.meta.hot) {
-  // @ts-expect-error Vite HMR types
   import.meta.hot.accept();
 
   // Subscribe to a11y invalidation events from Vite plugin
-  // @ts-expect-error Vite HMR types
   import.meta.hot.on("fragments:a11y-invalidate", (data: {
     components: string[];
     file: string;

package/src/hooks/useAppState.ts

@@ -5,7 +5,7 @@
 
 import { useReducer, useCallback, useMemo } from 'react';
 
-export type ActivePanel = 'styles' | 'accessibility' | 'interactions' | 'graph' | 'performance';
+export type ActivePanel = 'styles' | 'controls' | 'accessibility' | 'interactions' | 'graph' | 'performance';
 
 interface AppUIState {
   activePanel: ActivePanel;

package/src/preview-frame-entry.tsx

@@ -18,8 +18,6 @@ if (rootElement) {
 }
 
 // HMR support
-// @ts-expect-error Vite HMR types
 if (import.meta.hot) {
-  // @ts-expect-error Vite HMR types
   import.meta.hot.accept();
 }

package/src/shared/DocsHeaderBar.module.scss

@@ -0,0 +1,174 @@
+// ============================================
+// Mega-Menu Grid
+// ============================================
+
+.megaMenuGrid {
+  display: grid;
+  gap: 0; // divider handles visual separation
+  padding: var(--fui-space-5) var(--fui-space-5);
+  min-width: 540px;
+}
+
+// ============================================
+// Sections & Divider
+// ============================================
+
+.megaMenuSection {
+  display: flex;
+  flex-direction: column;
+  padding: 0 var(--fui-space-2);
+
+  &:first-child {
+    padding-left: 0;
+  }
+
+  &:last-child {
+    padding-right: 0;
+  }
+}
+
+.megaMenuDivider {
+  width: 1px;
+  background-color: var(--fui-border-default);
+  align-self: stretch;
+}
+
+.megaMenuSectionTitle {
+  font-size: 0.714rem; // ~10px — smaller than xs for strong hierarchy
+  font-weight: var(--fui-font-weight-semibold);
+  color: var(--fui-text-tertiary);
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  padding: var(--fui-space-0-5) var(--fui-space-2) var(--fui-space-2);
+}
+
+// ============================================
+// Menu Items (overrides NavigationMenu .link)
+// Specificity: .megaMenuSection .megaMenuItem = 0,2,0
+// NavigationMenu .link = 0,1,0 — we always win
+// ============================================
+
+.megaMenuSection .megaMenuItem {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-3);
+  padding: var(--fui-space-1) var(--fui-space-2);
+  border-radius: var(--fui-radius-md);
+  text-decoration: none;
+  white-space: normal;
+  min-height: auto;
+  color: inherit;
+  transition: background-color 150ms ease, color 150ms ease;
+
+  &:hover {
+    background-color: var(--fui-bg-hover);
+
+    .megaMenuItemDesc {
+      color: var(--fui-text-secondary);
+    }
+
+    .packageLogo {
+      transform: translateY(-1px);
+      box-shadow:
+        inset 0 1px 0 rgba(255, 255, 255, 0.2),
+        0 3px 8px -2px rgba(0, 0, 0, 0.4),
+        0 0 0 1px rgba(255, 255, 255, 0.08);
+    }
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--fui-color-accent, #6366f1);
+    outline-offset: -2px;
+    border-radius: var(--fui-radius-md);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+
+    &:hover .packageLogo {
+      transform: none;
+    }
+  }
+}
+
+// Active state (current page) — override NavigationMenu .linkActive too
+.megaMenuSection .megaMenuItemActive {
+  background-color: var(--fui-bg-secondary);
+
+  &:hover {
+    background-color: var(--fui-bg-secondary);
+  }
+}
+
+// ============================================
+// Item Internals
+// ============================================
+
+.megaMenuItemBody {
+  display: flex;
+  flex-direction: column;
+  gap: 2px; // tight coupling of title + description
+  min-width: 0;
+}
+
+.megaMenuItemTitle {
+  font-size: var(--fui-font-size-sm);
+  font-weight: var(--fui-font-weight-medium);
+  color: var(--fui-text-primary);
+  line-height: 1.3;
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-1);
+}
+
+.megaMenuItemDesc {
+  font-size: var(--fui-font-size-xs);
+  color: var(--fui-text-tertiary);
+  line-height: 1.4;
+  transition: color 150ms ease;
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
+}
+
+// ============================================
+// Badge — tiny subordinate pill
+// ============================================
+
+.megaMenuBadge {
+  display: inline-flex;
+  align-items: center;
+  font-size: 9px;
+  font-weight: var(--fui-font-weight-semibold);
+  color: var(--fui-text-tertiary);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  line-height: 1;
+  padding: 2px 5px;
+  border-radius: var(--fui-radius-full);
+  border: 1px solid var(--fui-border-default);
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+
+// ============================================
+// Package Logo (wave gradient + abbreviation)
+// ============================================
+
+.packageLogo {
+  flex-shrink: 0;
+  width: 36px;
+  height: 36px;
+  border-radius: var(--fui-radius-md);
+  overflow: hidden;
+  box-shadow:
+    inset 0 1px 0 rgba(255, 255, 255, 0.15),
+    0 2px 6px -1px rgba(0, 0, 0, 0.3),
+    0 0 0 1px rgba(255, 255, 255, 0.06);
+  transition: box-shadow 150ms ease, transform 150ms ease;
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
+}

package/src/shared/DocsHeaderBar.tsx

@@ -1,10 +1,11 @@
 'use client';
 
 import { Header, NavigationMenu } from '@fragments-sdk/ui';
-import type { ReactNode } from 'react';
+import { Fragment, useId, type ReactNode } from 'react';
 import { DocsSearchCommand } from './DocsSearchCommand';
 import type { DocsNavLinkRenderer, HeaderNavEntry, NavSection, SearchItem } from './types';
-import { isDropdown } from './types';
+import { isDropdown, isMegaMenu } from './types';
+import megaStyles from './DocsHeaderBar.module.scss';
 
 interface DocsHeaderBarProps {
   brand: ReactNode;
@@ -20,9 +21,9 @@ interface DocsHeaderBarProps {
   navAriaLabel?: string;
 }
 
-const defaultLinkRenderer: DocsNavLinkRenderer = ({ href, label, onClick }) => (
-  <a href={href} onClick={onClick}>
-    {label}
+const defaultLinkRenderer: DocsNavLinkRenderer = ({ href, label, onClick, className, children }) => (
+  <a href={href} onClick={onClick} className={className}>
+    {children ?? label}
   </a>
 );
 
@@ -30,6 +31,54 @@ function defaultIsActive(href: string, currentPath: string): boolean {
   return currentPath === href || currentPath.startsWith(`${href}/`);
 }
 
+function PackageLogo({ abbr, gradient }: { abbr: string; gradient: [string, string] }) {
+  const gradientId = `pkg-grad-${abbr}-${useId().replace(/[:]/g, '')}`;
+  return (
+    <svg
+      className={megaStyles.packageLogo}
+      viewBox="0 0 36 36"
+      width={36}
+      height={36}
+      aria-hidden
+    >
+      <defs>
+        <linearGradient id={gradientId} x1="0" y1="0" x2="1" y2="1">
+          <stop offset="0%" stopColor={gradient[0]} />
+          <stop offset="100%" stopColor={gradient[1]} />
+        </linearGradient>
+      </defs>
+      <rect width="36" height="36" rx="2" fill={`url(#${gradientId})`} />
+      <path
+        d="M0 25 Q9 18 18 25 Q27 32 36 25 L36 36 L0 36 Z"
+        fill="white"
+        fillOpacity={0.15}
+      />
+      <path
+        d="M0 30 Q9 23 18 30 Q27 37 36 30 L36 36 L0 36 Z"
+        fill="white"
+        fillOpacity={0.1}
+      />
+      <text
+        x="18"
+        y="19"
+        textAnchor="middle"
+        dominantBaseline="central"
+        fill="white"
+        fontSize="12"
+        fontWeight="700"
+        fontFamily="'Geist Mono', 'SF Mono', SFMono-Regular, ui-monospace, monospace"
+        letterSpacing="-0.02em"
+      >
+        {abbr}
+      </text>
+    </svg>
+  );
+}
+
+function MegaMenuBadge({ text }: { text: string }) {
+  return <span className={megaStyles.megaMenuBadge}>{text}</span>;
+}
+
 export function DocsHeaderBar({
   brand,
   headerNav,
@@ -51,7 +100,78 @@ export function DocsHeaderBar({
       <NavigationMenu aria-label={navAriaLabel}>
         <NavigationMenu.List>
           {headerNav.map((entry) =>
-            isDropdown(entry) ? (
+            isMegaMenu(entry) ? (
+              <NavigationMenu.Item key={entry.label} value={entry.label}>
+                <NavigationMenu.Trigger>{entry.label}</NavigationMenu.Trigger>
+                <NavigationMenu.Content>
+                  <div
+                    className={megaStyles.megaMenuGrid}
+                    data-columns={entry.sections.length}
+                    style={{
+                      gridTemplateColumns: entry.sections
+                        .map((_, i) => {
+                          const parts: string[] = [];
+                          if (i > 0) parts.push('1px'); // divider column
+                          parts.push('1fr');
+                          return parts.join(' ');
+                        })
+                        .join(' '),
+                    }}
+                  >
+                    {entry.sections.map((section, sectionIdx) => (
+                      <Fragment key={section.title}>
+                        {sectionIdx > 0 && <div className={megaStyles.megaMenuDivider} />}
+                        <div className={megaStyles.megaMenuSection}>
+                          <div className={megaStyles.megaMenuSectionTitle}>{section.title}</div>
+                          {section.items.map((item) => {
+                            const active = isActive(item.href, currentPath);
+                            const className = [
+                              megaStyles.megaMenuItem,
+                              active ? megaStyles.megaMenuItemActive : '',
+                            ]
+                              .filter(Boolean)
+                              .join(' ');
+
+                            return (
+                              <NavigationMenu.Link
+                                key={item.href}
+                                href={item.href}
+                                active={active}
+                                asChild
+                              >
+                                {renderLink({
+                                  href: item.href,
+                                  label: item.label,
+                                  className,
+                                  children: (
+                                    <>
+                                      {item.abbr && item.gradient ? (
+                                        <PackageLogo abbr={item.abbr} gradient={item.gradient} />
+                                      ) : null}
+                                      <span className={megaStyles.megaMenuItemBody}>
+                                        <span className={megaStyles.megaMenuItemTitle}>
+                                          {item.label}
+                                          {item.badge ? <MegaMenuBadge text={item.badge} /> : null}
+                                        </span>
+                                        {item.description ? (
+                                          <span className={megaStyles.megaMenuItemDesc}>
+                                            {item.description}
+                                          </span>
+                                        ) : null}
+                                      </span>
+                                    </>
+                                  ),
+                                })}
+                              </NavigationMenu.Link>
+                            );
+                          })}
+                        </div>
+                      </Fragment>
+                    ))}
+                  </div>
+                </NavigationMenu.Content>
+              </NavigationMenu.Item>
+            ) : isDropdown(entry) ? (
               <NavigationMenu.Item key={entry.label} value={entry.label}>
                 <NavigationMenu.Trigger>{entry.label}</NavigationMenu.Trigger>
                 <NavigationMenu.Content>
@@ -88,23 +208,38 @@ export function DocsHeaderBar({
         <NavigationMenu.MobileBrand>{brand}</NavigationMenu.MobileBrand>
 
         <NavigationMenu.MobileContent>
-          {/* Render all headerNav items in the mobile drawer */}
+          {/* Top-level nav items (skip mega-menus — they get their own sections below) */}
           <NavigationMenu.MobileSection>
-            {headerNav.map((entry) =>
-              isDropdown(entry) ? (
-                entry.items.map((child) => (
+            {headerNav.flatMap((entry) => {
+              if (isMegaMenu(entry)) return [];
+              if (isDropdown(entry)) {
+                return entry.items.map((child) => (
                   <NavigationMenu.Link key={child.href} href={child.href} asChild>
                     {renderLink({ href: child.href, label: child.label })}
                   </NavigationMenu.Link>
-                ))
-              ) : (
+                ));
+              }
+              return [(
                 <NavigationMenu.Link key={entry.href} href={entry.href} asChild>
                   {renderLink({ href: entry.href, label: entry.label })}
                 </NavigationMenu.Link>
-              )
-            )}
+              )];
+            })}
           </NavigationMenu.MobileSection>
 
+          {/* Mega-menu sections with labels */}
+          {headerNav.filter(isMegaMenu).flatMap((entry) =>
+            entry.sections.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>
+            ))
+          )}
+
           {mobileSections.map((section) => (
             <NavigationMenu.MobileSection key={section.title} label={section.title}>
               {section.items.map((item) => (

package/src/shared/DocsSidebarNav.tsx

@@ -18,9 +18,9 @@ function defaultIsActive(href: string, currentPath: string): boolean {
   return currentPath === href;
 }
 
-const defaultLinkRenderer: DocsNavLinkRenderer = ({ href, label, onClick }) => (
-  <a href={href} onClick={onClick}>
-    {label}
+const defaultLinkRenderer: DocsNavLinkRenderer = ({ href, label, onClick, className, children }) => (
+  <a href={href} onClick={onClick} className={className}>
+    {children ?? label}
   </a>
 );
 

package/src/shared/index.ts

@@ -22,8 +22,11 @@ export type {
   HeaderNavEntry,
   HeaderNavLink,
   HeaderNavDropdown,
+  MegaMenuItem,
+  MegaMenuSection,
+  HeaderNavMegaMenu,
 } from './types';
-export { isDropdown } from './types';
+export { isDropdown, isMegaMenu } from './types';
 
 export { VariantPreviewCard } from './VariantPreviewCard';
 export type { VariantPreviewCardProps } from './VariantPreviewCard';

package/src/shared/types.ts

@@ -1,4 +1,4 @@
-import type { ReactElement } from 'react';
+import type { ReactElement, ReactNode } from 'react';
 
 export interface NavItem {
   label: string;
@@ -20,6 +20,8 @@ export interface DocsNavLinkRenderProps {
   href: string;
   label: string;
   onClick?: () => void;
+  className?: string;
+  children?: ReactNode;
 }
 
 export type DocsNavLinkRenderer = (props: DocsNavLinkRenderProps) => ReactElement;
@@ -34,10 +36,34 @@ export interface HeaderNavDropdown {
   items: NavItem[];
 }
 
-export type HeaderNavEntry = HeaderNavLink | HeaderNavDropdown;
+export interface MegaMenuItem extends NavItem {
+  description?: string;
+  /** Two-letter abbreviation for the package logo (e.g. "CL", "MC") */
+  abbr?: string;
+  /** Gradient color pair for the package logo [from, to] */
+  gradient?: [string, string];
+  /** Optional badge text (e.g. "Coming Soon") */
+  badge?: string;
+}
+
+export interface MegaMenuSection {
+  title: string;
+  items: MegaMenuItem[];
+}
+
+export interface HeaderNavMegaMenu {
+  label: string;
+  sections: MegaMenuSection[];
+}
+
+export type HeaderNavEntry = HeaderNavLink | HeaderNavDropdown | HeaderNavMegaMenu;
 
 export function isDropdown(entry: HeaderNavEntry): entry is HeaderNavDropdown {
-  return 'items' in entry;
+  return 'items' in entry && !('sections' in entry);
+}
+
+export function isMegaMenu(entry: HeaderNavEntry): entry is HeaderNavMegaMenu {
+  return 'sections' in entry;
 }
 
 /**

package/src/style-utils.ts

@@ -218,7 +218,7 @@ import type {
   TokenFix,
   TokenUsageSummary,
   DesignToken,
-} from "../core/index.js";
+} from "@fragments-sdk/core";
 
 /**
  * Enhanced style diff result with token information

package/src/webmcp/runtime-tools.ts

@@ -93,7 +93,7 @@ export function createRuntimeWebMCPTools(options: RuntimeToolsOptions = {}): Web
 
             const entry: { name: string; value: string; computed?: string; category?: string } = {
               name: token.name,
-              value: token.value,
+              value: String(token.value),
               category: cat,
             };