@fragments-sdk/ui 0.4.0 → 0.5.0

package/src/components/Chart/index.tsx

@@ -0,0 +1,267 @@
+'use client';
+
+import * as React from 'react';
+import {
+  Tooltip as RechartsTooltip,
+  Legend as RechartsLegend,
+} from 'recharts';
+import type { Props as RechartsLegendProps } from 'recharts/types/component/Legend';
+import styles from './Chart.module.scss';
+import '../../styles/globals.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export type ChartConfig = Record<
+  string,
+  {
+    label: string;
+    color: string;
+    icon?: React.ComponentType;
+  }
+>;
+
+export interface ChartContainerProps extends React.HTMLAttributes<HTMLDivElement> {
+  config: ChartConfig;
+  children: React.ReactElement;
+}
+
+export interface ChartTooltipContentProps {
+  active?: boolean;
+  payload?: readonly {
+    name?: string;
+    value?: number | string;
+    dataKey?: string | number;
+    color?: string;
+    payload?: Record<string, unknown>;
+  }[];
+  label?: string;
+  indicator?: 'dot' | 'line' | 'dashed';
+  hideLabel?: boolean;
+  hideIndicator?: boolean;
+  labelFormatter?: (label: string, payload: ChartTooltipContentProps['payload']) => React.ReactNode;
+  valueFormatter?: (value: number | string) => string;
+}
+
+export interface ChartLegendContentProps {
+  payload?: readonly {
+    value?: string;
+    dataKey?: string | number;
+    color?: string;
+  }[];
+}
+
+// ============================================
+// Context
+// ============================================
+
+const ChartConfigContext = React.createContext<ChartConfig | null>(null);
+
+export function useChartConfig() {
+  const ctx = React.useContext(ChartConfigContext);
+  if (!ctx) {
+    throw new Error('useChartConfig must be used within a <ChartContainer>');
+  }
+  return ctx;
+}
+
+// ============================================
+// ChartContainer
+// ============================================
+
+export function ChartContainer({
+  config,
+  children,
+  className,
+  style,
+  ...htmlProps
+}: ChartContainerProps) {
+  // Build CSS custom properties from config (--chart-<key>)
+  const cssVars = React.useMemo(() => {
+    const vars: Record<string, string> = {};
+    Object.entries(config).forEach(([key, val]) => {
+      vars[`--chart-${key}`] = val.color;
+    });
+    return vars;
+  }, [config]);
+
+  const rootClasses = [styles.container, className].filter(Boolean).join(' ');
+
+  // Inject responsive + width/height into the chart child (recharts v3 API)
+  const chartChild = React.cloneElement(children as React.ReactElement<Record<string, unknown>>, {
+    responsive: true,
+    width: '100%',
+    height: '100%',
+  });
+
+  return (
+    <ChartConfigContext.Provider value={config}>
+      <div
+        {...htmlProps}
+        className={rootClasses}
+        style={{ ...cssVars, ...style }}
+      >
+        {chartChild}
+      </div>
+    </ChartConfigContext.Provider>
+  );
+}
+
+// ============================================
+// ChartTooltipContent
+// ============================================
+
+export function ChartTooltipContent({
+  active,
+  payload,
+  label,
+  indicator = 'dot',
+  hideLabel = false,
+  hideIndicator = false,
+  labelFormatter,
+  valueFormatter,
+}: ChartTooltipContentProps) {
+  const config = React.useContext(ChartConfigContext);
+
+  if (!active || !payload?.length) return null;
+
+  const formattedLabel = labelFormatter
+    ? labelFormatter(String(label), payload)
+    : label;
+
+  return (
+    <div className={styles.tooltip}>
+      {!hideLabel && formattedLabel && (
+        <div className={styles.tooltipLabel}>{formattedLabel}</div>
+      )}
+      <div className={styles.tooltipItems}>
+        {payload.map((entry, i) => {
+          const key = String(entry.dataKey ?? entry.name ?? i);
+          const configEntry = config?.[key];
+          const displayLabel = configEntry?.label ?? entry.name ?? key;
+          const color = entry.color ?? configEntry?.color;
+          const displayValue = valueFormatter
+            ? valueFormatter(entry.value ?? 0)
+            : String(entry.value ?? '');
+
+          const indicatorClass = [
+            styles.tooltipIndicator,
+            indicator === 'line' && styles.tooltipIndicatorLine,
+            indicator === 'dashed' && styles.tooltipIndicatorDashed,
+          ].filter(Boolean).join(' ');
+
+          return (
+            <div key={key} className={styles.tooltipItem}>
+              {!hideIndicator && (
+                <span
+                  className={indicatorClass}
+                  style={{ backgroundColor: indicator === 'dashed' ? undefined : color, borderColor: color }}
+                />
+              )}
+              <span className={styles.tooltipItemLabel}>{displayLabel}</span>
+              <span className={styles.tooltipItemValue}>{displayValue}</span>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+// ============================================
+// ChartTooltip (thin wrapper)
+// ============================================
+
+type ChartTooltipProps = Omit<React.ComponentProps<typeof RechartsTooltip>, 'content'> & {
+  indicator?: 'dot' | 'line' | 'dashed';
+  hideLabel?: boolean;
+  hideIndicator?: boolean;
+  labelFormatter?: ChartTooltipContentProps['labelFormatter'];
+  valueFormatter?: ChartTooltipContentProps['valueFormatter'];
+  content?: React.ComponentProps<typeof RechartsTooltip>['content'];
+};
+
+export function ChartTooltip({
+  indicator,
+  hideLabel,
+  hideIndicator,
+  labelFormatter,
+  valueFormatter,
+  content,
+  ...props
+}: ChartTooltipProps) {
+  const defaultContent = React.useCallback(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (tooltipProps: any) => (
+      <ChartTooltipContent
+        {...tooltipProps}
+        indicator={indicator}
+        hideLabel={hideLabel}
+        hideIndicator={hideIndicator}
+        labelFormatter={labelFormatter}
+        valueFormatter={valueFormatter}
+      />
+    ),
+    [indicator, hideLabel, hideIndicator, labelFormatter, valueFormatter],
+  );
+
+  return (
+    <RechartsTooltip
+      cursor={{ stroke: 'var(--fui-border)' }}
+      content={content ?? defaultContent}
+      {...props}
+    />
+  );
+}
+
+// ============================================
+// ChartLegendContent
+// ============================================
+
+export function ChartLegendContent({ payload }: ChartLegendContentProps) {
+  const config = React.useContext(ChartConfigContext);
+
+  if (!payload?.length) return null;
+
+  return (
+    <div className={styles.legend}>
+      {payload.map((entry) => {
+        const key = String(entry.dataKey ?? entry.value ?? '');
+        const configEntry = config?.[key];
+        const label = configEntry?.label ?? entry.value ?? key;
+        const color = entry.color ?? configEntry?.color;
+
+        return (
+          <div key={key} className={styles.legendItem}>
+            <span
+              className={styles.legendDot}
+              style={{ backgroundColor: color }}
+            />
+            <span className={styles.legendLabel}>{label}</span>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+// ============================================
+// ChartLegend (thin wrapper)
+// ============================================
+
+type ChartLegendProps = Omit<RechartsLegendProps, 'content'> & {
+  content?: RechartsLegendProps['content'];
+};
+
+export function ChartLegend({ content, ...props }: ChartLegendProps) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const defaultContent = (legendProps: any) => <ChartLegendContent {...legendProps} />;
+
+  return (
+    <RechartsLegend
+      content={content ?? defaultContent}
+      {...props}
+    />
+  );
+}

package/src/components/Checkbox/Checkbox.fragment.tsx

@@ -1,6 +1,6 @@
 import React, { useState } from 'react';
 import { defineSegment } from '@fragments/core';
-import { Checkbox } from './index.js';
+import { Checkbox } from '.';
 
 // Stateful wrapper for interactive demos
 function StatefulCheckbox(props: React.ComponentProps<typeof Checkbox>) {

package/src/components/CodeBlock/CodeBlock.fragment.tsx

@@ -1,16 +1,16 @@
 import React from 'react';
 import { defineSegment } from '@fragments/core';
-import { CodeBlock } from './index.js';
+import { CodeBlock } from '.';
 
 export default defineSegment({
   component: CodeBlock,
 
   meta: {
     name: 'CodeBlock',
-    description: 'Syntax-highlighted code display with copy functionality',
-    category: 'content',
+    description: 'Syntax-highlighted code display with copy functionality, theming, diff view, and collapsible sections',
+    category: 'display',
     status: 'stable',
-    tags: ['code', 'syntax', 'highlighting', 'documentation', 'developer'],
+    tags: ['code', 'syntax', 'highlighting', 'documentation', 'developer', 'diff'],
   },
 
   usage: {
@@ -19,6 +19,8 @@ export default defineSegment({
       'Showing installation commands',
       'Presenting configuration snippets',
       'Teaching programming concepts',
+      'Showing code diffs or changes',
+      'Displaying long code files with collapse functionality',
     ],
     whenNot: [
       'User-editable code (use code editor)',
@@ -31,12 +33,17 @@ export default defineSegment({
       'Use title prop for external labels above the code block',
       'Enable line numbers for longer code samples',
       'Use highlightLines to draw attention to key lines',
+      'Use addedLines/removedLines for diff highlighting',
+      'Set maxHeight for very long code blocks to prevent layout issues',
+      'Use collapsible for code samples that users may want to skim',
+      'Choose a theme that matches your documentation style',
       'Keep code examples concise and focused',
     ],
     accessibility: [
       'Code is presented in a semantic pre/code structure',
       'Copy button has appropriate aria-label',
       'Keyboard accessible copy functionality',
+      'Collapse button has aria-expanded state',
     ],
   },
 
@@ -48,10 +55,26 @@ export default defineSegment({
     },
     language: {
       type: 'enum',
-      values: ['tsx', 'typescript', 'javascript', 'bash', 'css', 'scss', 'json', 'html'],
+      values: [
+        'tsx', 'typescript', 'javascript', 'jsx', 'bash', 'shell',
+        'css', 'scss', 'sass', 'json', 'html', 'xml', 'markdown', 'md',
+        'yaml', 'yml', 'python', 'py', 'ruby', 'go', 'rust', 'java',
+        'kotlin', 'swift', 'c', 'cpp', 'csharp', 'php', 'sql', 'graphql',
+        'diff', 'plaintext',
+      ],
       default: 'tsx',
       description: 'Programming language for syntax highlighting',
     },
+    theme: {
+      type: 'enum',
+      values: [
+        'synthwave-84', 'github-dark', 'github-light', 'one-dark-pro',
+        'dracula', 'nord', 'monokai', 'vitesse-dark', 'vitesse-light',
+        'min-dark', 'min-light',
+      ],
+      default: 'synthwave-84',
+      description: 'Syntax highlighting theme',
+    },
     showCopy: {
       type: 'boolean',
       default: true,
@@ -65,15 +88,56 @@ export default defineSegment({
       type: 'string',
       description: 'Optional filename shown in header bar inside code block',
     },
+    caption: {
+      type: 'string',
+      description: 'Optional caption displayed below the code block',
+    },
     showLineNumbers: {
       type: 'boolean',
       default: false,
       description: 'Whether to display line numbers',
     },
+    startLineNumber: {
+      type: 'number',
+      default: 1,
+      description: 'Starting line number (useful for code excerpts)',
+    },
     highlightLines: {
       type: 'array',
       description: 'Lines to highlight (e.g., [1, 3, "5-7"])',
     },
+    addedLines: {
+      type: 'array',
+      description: 'Lines marked as added in diff view (e.g., [2, "4-6"])',
+    },
+    removedLines: {
+      type: 'array',
+      description: 'Lines marked as removed in diff view (e.g., [1, 3])',
+    },
+    wordWrap: {
+      type: 'boolean',
+      default: false,
+      description: 'Enable word wrapping for long lines',
+    },
+    maxHeight: {
+      type: 'number',
+      description: 'Maximum height in pixels (enables scrolling)',
+    },
+    collapsible: {
+      type: 'boolean',
+      default: false,
+      description: 'Allow collapsing/expanding the code block',
+    },
+    defaultCollapsed: {
+      type: 'boolean',
+      default: false,
+      description: 'Initial collapsed state (only applies when collapsible is true)',
+    },
+    collapsedLines: {
+      type: 'number',
+      default: 5,
+      description: 'Number of lines to show when collapsed',
+    },
     className: {
       type: 'string',
       description: 'Additional CSS class name',
@@ -96,12 +160,22 @@ export default defineSegment({
   contract: {
     propsSummary: [
       'code: string - required code content',
-      'language: tsx|typescript|javascript|bash|css|scss|json|html',
+      'language: tsx|typescript|javascript|jsx|bash|shell|css|scss|sass|json|html|xml|markdown|md|yaml|yml|python|py|ruby|go|rust|java|kotlin|swift|c|cpp|csharp|php|sql|graphql|diff|plaintext',
+      'theme: synthwave-84|github-dark|github-light|one-dark-pro|dracula|nord|monokai|vitesse-dark|vitesse-light|min-dark|min-light',
       'showCopy: boolean (default: true)',
       'title: string - optional external label',
       'filename: string - optional filename in header bar',
+      'caption: string - optional footer caption',
       'showLineNumbers: boolean (default: false)',
+      'startLineNumber: number (default: 1)',
       'highlightLines: (number | string)[] - lines to emphasize',
+      'addedLines: (number | string)[] - diff added lines',
+      'removedLines: (number | string)[] - diff removed lines',
+      'wordWrap: boolean (default: false)',
+      'maxHeight: number - max height with scrolling',
+      'collapsible: boolean (default: false)',
+      'defaultCollapsed: boolean (default: false)',
+      'collapsedLines: number (default: 5)',
     ],
     scenarioTags: [
       'documentation.code',
@@ -152,6 +226,17 @@ function App() {
 <CodeBlock title="Installation" code="npm install @fragments-sdk/ui" language="bash" />
       ),
     },
+    {
+      name: 'With Caption',
+      description: 'Code block with footer caption',
+      render: () => (
+<CodeBlock
+  code={`const API_URL = process.env.NEXT_PUBLIC_API_URL;`}
+  language="typescript"
+  caption="Environment variables must be prefixed with NEXT_PUBLIC_ to be available in the browser."
+/>
+      ),
+    },
     {
       name: 'With Line Numbers',
       description: 'Shows line numbers for reference',
@@ -161,6 +246,24 @@ const name = "World";
 console.log(\`\${greeting}, \${name}!\`);`} language="typescript" showLineNumbers />
       ),
     },
+    {
+      name: 'Custom Start Line',
+      description: 'Shows code excerpt starting from a specific line number',
+      render: () => (
+<CodeBlock
+  code={`  return (
+    <button onClick={() => setCount(c => c + 1)}>
+      Count: {count}
+    </button>
+  );
+}`}
+  language="tsx"
+  showLineNumbers
+  startLineNumber={15}
+  caption="Lines 15-20 from Counter.tsx"
+/>
+      ),
+    },
     {
       name: 'With Highlighted Lines',
       description: 'Emphasizes specific lines of code',
@@ -178,6 +281,162 @@ function Counter() {
 }`} language="tsx" showLineNumbers highlightLines={[4, '7-9']} />
       ),
     },
+    {
+      name: 'Diff View',
+      description: 'Shows added and removed lines in a diff-like format',
+      render: () => (
+<CodeBlock
+  code={`import { useState } from 'react';
+import { useCallback } from 'react';
+
+function Counter() {
+  const [count, setCount] = useState(0);
+  const increment = () => setCount(c => c + 1);
+  const increment = useCallback(() => setCount(c => c + 1), []);
+
+  return <button onClick={increment}>Count: {count}</button>;
+}`}
+  language="tsx"
+  showLineNumbers
+  removedLines={[6]}
+  addedLines={[2, 7]}
+/>
+      ),
+    },
+    {
+      name: 'GitHub Dark Theme',
+      description: 'Using the GitHub Dark theme',
+      render: () => (
+<CodeBlock
+  code={`async function fetchUser(id: string) {
+  const response = await fetch(\`/api/users/\${id}\`);
+  return response.json();
+}`}
+  language="typescript"
+  theme="github-dark"
+/>
+      ),
+    },
+    {
+      name: 'GitHub Light Theme',
+      description: 'Using the GitHub Light theme for light backgrounds',
+      render: () => (
+<CodeBlock
+  code={`def fibonacci(n):
+    if n <= 1:
+        return n
+    return fibonacci(n - 1) + fibonacci(n - 2)`}
+  language="python"
+  theme="github-light"
+/>
+      ),
+    },
+    {
+      name: 'Dracula Theme',
+      description: 'Using the popular Dracula theme',
+      render: () => (
+<CodeBlock
+  code={`fn main() {
+    println!("Hello, Rust!");
+}`}
+  language="rust"
+  theme="dracula"
+/>
+      ),
+    },
+    {
+      name: 'Word Wrap',
+      description: 'Long lines wrap instead of scrolling horizontally',
+      render: () => (
+<CodeBlock
+  code={`const longString = "This is a very long string that would normally cause horizontal scrolling, but with word wrap enabled it will break to the next line instead.";`}
+  language="typescript"
+  wordWrap
+/>
+      ),
+    },
+    {
+      name: 'Max Height with Scroll',
+      description: 'Constrains height with scrollable content',
+      render: () => (
+<CodeBlock
+  code={`// This code block has a maximum height
+function processItems(items: string[]) {
+  const results = [];
+  for (const item of items) {
+    if (item.startsWith('_')) {
+      continue;
+    }
+    const processed = item.trim().toLowerCase();
+    if (processed.length > 0) {
+      results.push(processed);
+    }
+  }
+  return results;
+}
+
+export default processItems;`}
+  language="typescript"
+  maxHeight={150}
+  showLineNumbers
+/>
+      ),
+    },
+    {
+      name: 'Collapsible',
+      description: 'Long code that can be expanded/collapsed',
+      render: () => (
+<CodeBlock
+  code={`import React, { useState, useEffect } from 'react';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  avatar?: string;
+}
+
+export function UserProfile({ userId }: { userId: string }) {
+  const [user, setUser] = useState<User | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    async function fetchUser() {
+      try {
+        setLoading(true);
+        const response = await fetch(\`/api/users/\${userId}\`);
+        if (!response.ok) throw new Error('Failed to fetch');
+        const data = await response.json();
+        setUser(data);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Unknown error');
+      } finally {
+        setLoading(false);
+      }
+    }
+    fetchUser();
+  }, [userId]);
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error}</div>;
+  if (!user) return null;
+
+  return (
+    <div>
+      <h1>{user.name}</h1>
+      <p>{user.email}</p>
+    </div>
+  );
+}`}
+  language="tsx"
+  showLineNumbers
+  collapsible
+  defaultCollapsed
+  collapsedLines={8}
+/>
+      ),
+    },
     {
       name: 'JSON',
       description: 'Configuration file example',