@fragments-sdk/cli 0.8.1 → 0.9.1

package/src/viewer/vendor/shared/src/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>
+  );
+}

package/src/viewer/vendor/shared/src/VariantPreviewCard.module.scss

@@ -0,0 +1,122 @@
+// Shared variant preview card — used by docs and CLI viewer
+.card {
+  border: 1px solid var(--fui-border);
+  border-radius: var(--fui-radius-lg);
+  overflow: hidden;
+  background-color: var(--fui-bg-primary);
+}
+
+.highlighted {
+  border-color: var(--fui-color-accent);
+  box-shadow: 0 0 0 1px color-mix(in srgb, var(--fui-color-accent) 40%, transparent);
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--fui-space-4);
+  padding: var(--fui-space-2) var(--fui-space-4);
+  background-color: var(--fui-bg-primary);
+  border-bottom: 1px solid var(--fui-border);
+}
+
+.headerContent {
+  flex: 1;
+  min-width: 0;
+}
+
+.title {
+  font-size: var(--fui-font-size-sm);
+  font-weight: var(--fui-font-weight-semibold);
+  color: var(--fui-text-primary);
+  margin: 0;
+  line-height: 1.4;
+}
+
+.description {
+  font-size: var(--fui-font-size-xs);
+  color: var(--fui-text-tertiary);
+  margin: var(--fui-space-0-5) 0 0 0;
+  line-height: 1.4;
+}
+
+// Preview area with subtle dotted grid pattern
+.previewPanel {
+  position: relative;
+  min-height: 400px;
+  padding: var(--fui-space-4);
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  background-color: var(--fui-bg-primary);
+
+  // Subtle dotted grid pattern
+  background-image: radial-gradient(circle, var(--fui-border) 1px, transparent 1px);
+  background-size: 24px 24px;
+
+  > * {
+    width: 100%;
+    flex: 1;
+  }
+}
+
+// Code panel
+.codePanel {
+  background-color: var(--fui-bg-tertiary);
+  padding: 0 !important; // Override Tabs panel padding
+
+  // Override CodeBlock styles for embedded use
+  :global([class*="CodeBlock_container"]) {
+    border: none;
+    border-radius: 0;
+    margin: 0;
+  }
+
+  :global([class*="CodeBlock_wrapper"]) {
+    border-top-left-radius: 0;
+    border-top-right-radius: 0;
+    border: none;
+  }
+
+  :global([class*="CodeBlock_title"]) {
+    display: none;
+  }
+}
+
+.placeholder {
+  color: var(--fui-text-tertiary);
+  font-style: italic;
+  font-size: var(--fui-font-size-sm);
+}
+
+.headerActions {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-2);
+  flex-shrink: 0;
+}
+
+// Override Tabs styling for preview cards
+.card {
+  :global([class*="Tabs_root"]) {
+    display: flex;
+    flex-direction: column;
+  }
+
+  // Tabs list sits inline with header
+  :global([class*="Tabs_list"]) {
+    padding: 0;
+    border-bottom: none;
+    background-color: transparent;
+    flex-shrink: 0;
+  }
+
+  :global([class*="Tabs_listPills"]) {
+    margin: 0;
+  }
+
+  :global([class*="Tabs_panel"]) {
+    padding: 0;
+  }
+}

package/src/viewer/vendor/shared/src/VariantPreviewCard.module.scss.d.ts

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

package/src/viewer/vendor/shared/src/VariantPreviewCard.tsx

@@ -0,0 +1,134 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import { CodeBlock, Tabs } from '@fragments-sdk/ui';
+import styles from './VariantPreviewCard.module.scss';
+
+/** Detect auto-generated descriptions like "Alternative Layout variant" or "Default ActionMenu" */
+function isGenericVariantDescription(name: string, description: string): boolean {
+  const lower = description.toLowerCase().trim();
+  const nameLower = name.toLowerCase().trim();
+  return (
+    lower === `${nameLower} variant` ||
+    lower === `default ${nameLower}` ||
+    lower === nameLower ||
+    // "Default SomeComponent" — "Default" followed by a PascalCase component name
+    /^default [a-z][a-z0-9]*$/i.test(description.trim())
+  );
+}
+
+export interface VariantPreviewCardProps {
+  name: string;
+  description?: string;
+  code?: string;
+  children: ReactNode;
+  isLoading?: boolean;
+  error?: string | null;
+  defaultTab?: 'preview' | 'code';
+  highlight?: boolean;
+  id?: string;
+  headerActions?: ReactNode;
+  className?: string;
+}
+
+export function VariantPreviewCard({
+  name,
+  description,
+  code,
+  children,
+  isLoading,
+  error,
+  defaultTab = 'preview',
+  highlight,
+  id,
+  headerActions,
+  className,
+}: VariantPreviewCardProps) {
+  const cardClassName = [
+    styles.card,
+    highlight && styles.highlighted,
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  const hasPreview = !!children;
+  const hasCode = typeof code === 'string' && code.length > 0;
+
+  // No preview, code only — render without tabs
+  if (!hasPreview && hasCode) {
+    return (
+      <div className={cardClassName} id={id}>
+        <div className={styles.header}>
+          <div className={styles.headerContent}>
+            <h3 className={styles.title}>{name}</h3>
+            {description && !isGenericVariantDescription(name, description) && <p className={styles.description}>{description}</p>}
+          </div>
+          {headerActions && <div className={styles.headerActions}>{headerActions}</div>}
+        </div>
+        <div className={styles.codePanel}>
+          <CodeBlock code={code} language="tsx" />
+        </div>
+      </div>
+    );
+  }
+
+  // No code — render preview only, no tabs
+  if (!hasCode) {
+    return (
+      <div className={cardClassName} id={id}>
+        <div className={styles.header}>
+          <div className={styles.headerContent}>
+            <h3 className={styles.title}>{name}</h3>
+            {description && !isGenericVariantDescription(name, description) && <p className={styles.description}>{description}</p>}
+          </div>
+          {headerActions && <div className={styles.headerActions}>{headerActions}</div>}
+        </div>
+        <div className={styles.previewPanel}>
+          {isLoading ? (
+            <div className={styles.placeholder}>Loading preview...</div>
+          ) : error ? (
+            <div className={styles.placeholder}>Preview error: {error}</div>
+          ) : (
+            children
+          )}
+        </div>
+      </div>
+    );
+  }
+
+  // Both preview and code — render with tabs
+  return (
+    <div className={cardClassName} id={id}>
+      <Tabs defaultValue={defaultTab}>
+        <div className={styles.header}>
+          <div className={styles.headerContent}>
+            <h3 className={styles.title}>{name}</h3>
+            {description && !isGenericVariantDescription(name, description) && <p className={styles.description}>{description}</p>}
+          </div>
+          <div className={styles.headerActions}>
+            {headerActions}
+            <Tabs.List variant="pills">
+              <Tabs.Tab value="preview">Preview</Tabs.Tab>
+              <Tabs.Tab value="code">Code</Tabs.Tab>
+            </Tabs.List>
+          </div>
+        </div>
+
+        <Tabs.Panel value="preview" className={styles.previewPanel}>
+          {isLoading ? (
+            <div className={styles.placeholder}>Loading preview...</div>
+          ) : error ? (
+            <div className={styles.placeholder}>Preview error: {error}</div>
+          ) : (
+            children
+          )}
+        </Tabs.Panel>
+
+        <Tabs.Panel value="code" className={styles.codePanel}>
+          <CodeBlock code={code} language="tsx" />
+        </Tabs.Panel>
+      </Tabs>
+    </div>
+  );
+}

package/src/viewer/vendor/shared/src/docs-data/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Docs data — single source of truth for content shared across
+ * READMEs, docs pages, and MCP tool descriptions.
+ *
+ * Follows the same pattern as `cli-commands/index.ts`.
+ */
+
+export {
+  NEUTRAL_PALETTES,
+  DENSITY_PRESETS,
+  RADIUS_STYLES,
+  SEED_DEFAULTS,
+  type PaletteDef,
+  type DensityDef,
+  type RadiusDef,
+} from './palettes.js';
+
+export {
+  SCSS_SETUP_MINIMAL,
+  SCSS_SETUP_FULL,
+  USE_THEME_EXAMPLE,
+  USE_THEME_RETURN_SHAPE,
+  PROVIDER_SETUP_EXAMPLE,
+  MIXIN_IMPORT,
+  STYLES_IMPORT_JS,
+  STYLES_IMPORT_SCSS,
+} from './setup-examples.js';
+
+export {
+  MCP_CONFIGS,
+  type McpConfigDef,
+} from './mcp-configs.js';

package/src/viewer/vendor/shared/src/docs-data/mcp-configs.ts

@@ -0,0 +1,72 @@
+/**
+ * MCP server configuration examples per AI tool.
+ *
+ * Single source of truth for all READMEs and docs pages
+ * that show how to configure the Fragments MCP server.
+ */
+
+export interface McpConfigDef {
+  /** AI tool name (e.g., "Claude Code", "Cursor") */
+  tool: string;
+  /** Config file path */
+  filePath: string;
+  /** JSON config string (with comment header) */
+  config: string;
+}
+
+const npxArgs = `["-y", "@fragments-sdk/mcp@latest"]`;
+
+export const MCP_CONFIGS: McpConfigDef[] = [
+  {
+    tool: 'Claude Code',
+    filePath: '.mcp.json',
+    config: `// .mcp.json (project root)
+{
+  "mcpServers": {
+    "fragments": {
+      "command": "npx",
+      "args": ${npxArgs}
+    }
+  }
+}`,
+  },
+  {
+    tool: 'Cursor',
+    filePath: '.cursor/mcp.json',
+    config: `// .cursor/mcp.json
+{
+  "mcpServers": {
+    "fragments": {
+      "command": "npx",
+      "args": ${npxArgs}
+    }
+  }
+}`,
+  },
+  {
+    tool: 'VS Code',
+    filePath: '.vscode/mcp.json',
+    config: `// .vscode/mcp.json
+{
+  "servers": {
+    "fragments": {
+      "command": "npx",
+      "args": ${npxArgs}
+    }
+  }
+}`,
+  },
+  {
+    tool: 'Windsurf',
+    filePath: '~/.codeium/windsurf/mcp_config.json',
+    config: `// ~/.codeium/windsurf/mcp_config.json
+{
+  "mcpServers": {
+    "fragments": {
+      "command": "npx",
+      "args": ${npxArgs}
+    }
+  }
+}`,
+  },
+];

package/src/viewer/vendor/shared/src/docs-data/palettes.ts

@@ -0,0 +1,75 @@
+/**
+ * Design token seed definitions — single source of truth.
+ *
+ * Values must match libs/ui/src/tokens/_seeds.scss exactly.
+ * READMEs, docs pages, and MCP tool descriptions are generated from these.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PaletteDef {
+  name: string;
+  description: string;
+}
+
+export interface DensityDef {
+  readonly name: string;
+  readonly baseUnit: string;
+  readonly description: string;
+}
+
+export interface RadiusDef {
+  readonly name: string;
+  readonly description: string;
+}
+
+// ---------------------------------------------------------------------------
+// Neutral Palettes (must match _seeds.scss:27)
+// ---------------------------------------------------------------------------
+
+export const NEUTRAL_PALETTES: PaletteDef[] = [
+  { name: 'stone', description: 'Cool gray neutrals (balanced, professional) — default' },
+  { name: 'ice', description: 'Cool blue-tinted grays (crisp, technical)' },
+  { name: 'earth', description: 'Warm brown-tinted grays (natural, grounded)' },
+  { name: 'sand', description: 'Warm tan-tinted grays (organic, approachable)' },
+  { name: 'fire', description: 'Warm red-tinted grays (bold, energetic)' },
+];
+
+// ---------------------------------------------------------------------------
+// Density Presets (must match _seeds.scss:32)
+// ---------------------------------------------------------------------------
+
+export const DENSITY_PRESETS: readonly DensityDef[] = [
+  { name: 'compact', baseUnit: '6px', description: 'Tighter spacing, smaller elements' },
+  { name: 'default', baseUnit: '7px', description: 'Balanced, standard appearance' },
+  { name: 'relaxed', baseUnit: '8px', description: 'More spacious layout' },
+] as const;
+
+// ---------------------------------------------------------------------------
+// Radius Styles (must match _seeds.scss:37)
+// ---------------------------------------------------------------------------
+
+export const RADIUS_STYLES: readonly RadiusDef[] = [
+  { name: 'sharp', description: 'No rounding (technical, precise)' },
+  { name: 'subtle', description: 'Minimal rounding (modern minimal)' },
+  { name: 'default', description: 'Balanced rounding' },
+  { name: 'rounded', description: 'More prominent (friendly)' },
+  { name: 'pill', description: 'Maximum rounding (playful, soft)' },
+] as const;
+
+// ---------------------------------------------------------------------------
+// Seed Defaults (must match _seeds.scss)
+// ---------------------------------------------------------------------------
+
+export const SEED_DEFAULTS = {
+  brand: '#18181b',
+  neutral: 'stone',
+  density: 'default',
+  radiusStyle: 'default',
+  danger: '#ef4444',
+  success: '#22c55e',
+  warning: '#f59e0b',
+  info: '#3b82f6',
+} as const;

package/src/viewer/vendor/shared/src/docs-data/setup-examples.ts

@@ -0,0 +1,55 @@
+/**
+ * Correct code examples for setup documentation.
+ *
+ * These are the canonical snippets used across READMEs and docs pages.
+ * If you change a pattern here, all generated docs update automatically.
+ */
+
+// ---------------------------------------------------------------------------
+// SCSS Setup
+// ---------------------------------------------------------------------------
+
+/** Minimal SCSS setup — @use with() syntax, not standalone variables */
+export const SCSS_SETUP_MINIMAL = `@use '@fragments-sdk/ui/styles' with (
+  $fui-brand: #0066ff
+);`;
+
+/** Full SCSS setup with all seeds */
+export const SCSS_SETUP_FULL = `@use '@fragments-sdk/ui/styles' with (
+  $fui-brand: #0066ff,
+  $fui-neutral: "ice",
+  $fui-density: "compact",
+  $fui-radius-style: "rounded"
+);`;
+
+// ---------------------------------------------------------------------------
+// Theme API
+// ---------------------------------------------------------------------------
+
+/** Correct useTheme() API — mode/setMode, NOT theme/setTheme */
+export const USE_THEME_EXAMPLE = `const { mode, setMode } = useTheme();`;
+
+/** Full useTheme return shape */
+export const USE_THEME_RETURN_SHAPE = `interface UseThemeReturn {
+  mode: ThemeMode;
+  setMode: (mode: ThemeMode) => void;
+  resolvedMode: 'light' | 'dark';
+  systemPreference: 'light' | 'dark';
+  toggleMode: () => void;
+}`;
+
+/** Canonical ThemeProvider prop — defaultMode, NOT defaultTheme */
+export const PROVIDER_SETUP_EXAMPLE = `<ThemeProvider defaultMode="system">`;
+
+// ---------------------------------------------------------------------------
+// Import Paths
+// ---------------------------------------------------------------------------
+
+/** Correct mixin import path (NOT /tokens) */
+export const MIXIN_IMPORT = `@use '@fragments-sdk/ui/mixins' as *;`;
+
+/** Correct styles import — JS side */
+export const STYLES_IMPORT_JS = `import '@fragments-sdk/ui/styles';`;
+
+/** Correct styles import — SCSS side */
+export const STYLES_IMPORT_SCSS = `@use '@fragments-sdk/ui/styles'`;

package/src/viewer/vendor/shared/src/index.ts

@@ -24,3 +24,11 @@ export type {
   HeaderNavDropdown,
 } from './types';
 export { isDropdown } from './types';
+
+export { VariantPreviewCard } from './VariantPreviewCard';
+export type { VariantPreviewCardProps } from './VariantPreviewCard';
+
+export { PropsTable } from './PropsTable';
+export { ComponentDocContent } from './ComponentDocContent';
+export type { ComponentDocContentProps } from './ComponentDocContent';
+export type { DocProp } from './types';

package/src/viewer/vendor/shared/src/types.ts

@@ -39,3 +39,15 @@ export type HeaderNavEntry = HeaderNavLink | HeaderNavDropdown;
 export function isDropdown(entry: HeaderNavEntry): entry is HeaderNavDropdown {
   return 'items' in entry;
 }
+
+/**
+ * Prop documentation type for shared PropsTable / ComponentDocContent.
+ * Intentionally simple — consumers map their richer types into this shape.
+ */
+export interface DocProp {
+  type: string;
+  description: string;
+  required?: boolean;
+  default?: unknown;
+  values?: string[];
+}