AI & Advanced Components

/**
 * AI label component for indicating AI-generated content
 */
interface AILabelProps {
  /** Label children */
  children?: React.ReactNode;
  /** CSS class name */
  className?: string;
  /** AI label kind */
  kind?: "default" | "inline";
  /** Label size */
  size?: "mini" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl";
  /** AI label text */
  textLabel?: string;
  /** Custom AI text */
  aiText?: string;
  /** Custom AI text with dash */
  aiTextLabel?: string;
  /** Revert to Slug behavior */
  revertActive?: boolean;
  /** Auto align */
  autoAlign?: boolean;
  /** Alignment */
  align?: 
    | "top"
    | "top-left" 
    | "top-right"
    | "bottom"
    | "bottom-left"
    | "bottom-right"
    | "left"
    | "left-bottom"
    | "left-top"
    | "right"
    | "right-bottom"
    | "right-top";
}

/**
 * AI label content container
 */
interface AILabelContentProps {
  /** Content children */
  children: React.ReactNode;
  /** CSS class name */
  className?: string;
}

/**
 * AI label actions container
 */
interface AILabelActionsProps {
  /** Action children */
  children: React.ReactNode;
  /** CSS class name */
  className?: string;
}

import { AILabel, AILabelContent, AILabelActions, Button, Link } from "@carbon/react";

// Basic AI label
<AILabel size="md" textLabel="AI Generated">
  <AILabelContent>
    <p>This content was generated using artificial intelligence.</p>
    <AILabelActions>
      <Button size="sm" kind="ghost">Learn more</Button>
      <Link href="/ai-policy">AI Policy</Link>
    </AILabelActions>
  </AILabelContent>
</AILabel>

// Inline AI label
<p>
  This summary was created by{" "}
  <AILabel kind="inline" size="sm" textLabel="AI">
    <AILabelContent>
      <p>Generated using GPT-4 based on the provided content.</p>
    </AILabelContent>
  </AILabel>{" "}
  based on your document.
</p>

// AI label with custom positioning
<AILabel 
  size="lg"
  align="bottom-right"
  textLabel="AI Enhanced"
>
  <AILabelContent>
    <h4>Smart Recommendations</h4>
    <p>These suggestions are powered by machine learning algorithms.</p>
    <AILabelActions>
      <Button size="sm">Accept all</Button>
      <Button size="sm" kind="ghost">Customize</Button>
    </AILabelActions>
  </AILabelContent>
</AILabel>

/**
 * AI skeleton text component
 */
interface AISkeletonTextProps {
  /** Number of lines */
  lineCount?: number;
  /** Paragraph mode */
  paragraph?: boolean;
  /** Text width */
  width?: string;
  /** Heading mode */
  heading?: boolean;
  /** CSS class name */
  className?: string;
}

/**
 * AI skeleton icon component
 */
interface AISkeletonIconProps {
  /** Icon size */
  size?: number;
  /** CSS class name */
  className?: string;
  /** Custom style */
  style?: React.CSSProperties;
}

/**
 * AI skeleton placeholder component
 */
interface AISkeletonPlaceholderProps {
  /** CSS class name */
  className?: string;
  /** Custom style */
  style?: React.CSSProperties;
}

import { AISkeletonText, AISkeletonIcon, AISkeletonPlaceholder } from "@carbon/react";

// AI skeleton text
<AISkeletonText lineCount={3} paragraph />

// AI skeleton for headings
<AISkeletonText heading width="60%" />

// AI skeleton icon
<AISkeletonIcon size={32} />

// AI skeleton placeholder
<AISkeletonPlaceholder style={{ height: '200px', width: '100%' }} />

// Complete AI loading state
<div>
  <AISkeletonText heading width="40%" />
  <AISkeletonText lineCount={4} paragraph />
  <div style={{ display: 'flex', gap: '1rem', marginTop: '1rem' }}>
    <AISkeletonIcon size={24} />
    <AISkeletonText width="30%" />
  </div>
</div>

/**
 * Chat button component for conversational interfaces
 */
interface ChatButtonProps {
  /** Button children */
  children?: React.ReactNode;
  /** Disabled state */
  disabled?: boolean;
  /** Button kind */
  kind?: "primary" | "secondary" | "tertiary" | "ghost";
  /** Button size */
  size?: "sm" | "md" | "lg";
  /** Is quick action button */
  isQuickAction?: boolean;
  /** Is selected state */
  isSelected?: boolean;
  /** Click handler */
  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
  /** CSS class name */
  className?: string;
}

/**
 * Chat button skeleton loading state
 */
interface ChatButtonSkeletonProps {
  /** Button size */
  size?: "sm" | "md" | "lg";
  /** CSS class name */
  className?: string;
}

import { ChatButton, ChatButtonSkeleton } from "@carbon/react";
import { Send, Microphone, Attachment } from "@carbon/react/icons";

// Basic chat button
<ChatButton
  kind="primary"
  onClick={() => sendMessage()}
  disabled={!message.trim()}
>
  <Send />
  Send
</ChatButton>

// Quick action chat buttons
<div style={{ display: 'flex', gap: '0.5rem' }}>
  <ChatButton
    isQuickAction
    size="sm"
    onClick={() => attachFile()}
  >
    <Attachment />
  </ChatButton>
  <ChatButton
    isQuickAction
    size="sm"
    onClick={() => startRecording()}
    isSelected={isRecording}
  >
    <Microphone />
  </ChatButton>
</div>

// Loading state
<ChatButtonSkeleton size="md" />

// Chat button variations
<div style={{ display: 'flex', gap: '1rem', flexDirection: 'column' }}>
  <ChatButton kind="primary">Send message</ChatButton>
  <ChatButton kind="secondary">Save draft</ChatButton>
  <ChatButton kind="ghost">Cancel</ChatButton>
</div>

/**
 * Combo button - button with dropdown actions
 */
interface ComboButtonProps {
  /** Primary action text */
  children: React.ReactNode;
  /** Menu items */
  menu: React.ReactNode;
  /** Primary action handler */
  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
  /** Button disabled */
  disabled?: boolean;
  /** Button size */
  size?: "sm" | "md" | "lg";
  /** Button kind */
  kind?: "primary" | "secondary" | "tertiary" | "ghost";
  /** Menu alignment */
  menuAlignment?: "top" | "bottom";
  /** Primary button tooltip */
  primaryButtonTooltip?: string;
  /** Menu button tooltip */
  menuButtonTooltip?: string;
}

/**
 * Contained list component for grouped items
 */
interface ContainedListProps {
  /** List children */
  children: React.ReactNode;
  /** List label */
  label?: string;
  /** List kind */
  kind?: "on-page" | "disclosed";
  /** Size variant */
  size?: "sm" | "md" | "lg";
  /** Action */
  action?: React.ReactNode;
  /** CSS class name */
  className?: string;
}

/**
 * Icon button specialized for icons only
 */
interface IconButtonProps extends React.ComponentPropsWithoutRef<"button"> {
  /** Icon children */
  children: React.ReactNode;
  /** Button label for accessibility */
  label: string;
  /** Button kind */
  kind?: "primary" | "secondary" | "tertiary" | "ghost";
  /** Button size */
  size?: "sm" | "md" | "lg";
  /** Button disabled */
  disabled?: boolean;
  /** Align */
  align?: 
    | "top"
    | "top-left" 
    | "top-right"
    | "bottom"
    | "bottom-left"
    | "bottom-right"
    | "left"
    | "right";
}

/**
 * Layout component for page structure
 */
interface LayoutProps {
  /** Layout children */
  children: React.ReactNode;
  /** Layout size */
  size?: "sm" | "md" | "lg" | "xl" | "2xl";
  /** Layout density */
  density?: "condensed" | "normal";
  /** CSS class name */
  className?: string;
}

/**
 * Text component with advanced typography
 */
interface TextProps {
  /** Text children */
  children: React.ReactNode;
  /** Element to render */
  as?: "p" | "span" | "div" | "label" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
  /** Text size */
  size?: "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
  /** Font weight */
  weight?: "light" | "normal" | "semibold" | "bold";
  /** Text color */
  color?: "primary" | "secondary" | "inverse" | "disabled";
  /** CSS class name */
  className?: string;
}

import { 
  ComboButton, 
  ContainedList, 
  IconButton, 
  Layout, 
  Text,
  Menu,
  MenuItem
} from "@carbon/react";
import { Save, Download, Share, Add } from "@carbon/react/icons";

// Combo button
<ComboButton
  onClick={() => saveDocument()}
  menu={
    <Menu>
      <MenuItem>Save as...</MenuItem>
      <MenuItem>Save template</MenuItem>
      <MenuItem>Auto-save settings</MenuItem>
    </Menu>
  }
>
  Save
</ComboButton>

// Contained list
<ContainedList
  label="Recent documents"
  kind="on-page"
  action={<IconButton label="Add document"><Add /></IconButton>}
>
  <div>Document 1.pdf</div>
  <div>Document 2.docx</div>
  <div>Document 3.txt</div>
</ContainedList>

// Icon buttons
<div style={{ display: 'flex', gap: '0.5rem' }}>
  <IconButton label="Download file" kind="ghost">
    <Download />
  </IconButton>
  <IconButton label="Share document" kind="ghost">
    <Share />
  </IconButton>
</div>

// Layout component
<Layout size="lg" density="normal">
  <header>Header content</header>
  <main>Main content area</main>
  <aside>Sidebar content</aside>
</Layout>

// Text component
<div>
  <Text as="h1" size="2xl" weight="bold">
    Main Heading
  </Text>
  <Text as="p" size="md" color="secondary">
    Supporting text with secondary color
  </Text>
  <Text as="span" size="sm" weight="semibold">
    Small bold text
  </Text>
</div>

/**
 * Feature flags provider
 */
interface FeatureFlagsProps {
  /** Flag children */
  children: React.ReactNode;
  /** Feature flags object */
  flags?: Record<string, boolean>;
}

/**
 * Feature flag hook for checking individual flags
 */
function useFeatureFlag(flag: string): boolean;

/**
 * Feature flags hook for accessing all flags
 */
function useFeatureFlags(): Record<string, boolean>;

import { FeatureFlags, useFeatureFlag, useFeatureFlags } from "@carbon/react";

// Feature flags provider
<FeatureFlags
  flags={{
    'new-dashboard': true,
    'advanced-search': false,
    'beta-features': true
  }}
>
  <App />
</FeatureFlags>

// Using feature flags in components
function Dashboard() {
  const newDashboardEnabled = useFeatureFlag('new-dashboard');
  const allFlags = useFeatureFlags();
  
  return (
    <div>
      {newDashboardEnabled ? (
        <NewDashboard />
      ) : (
        <LegacyDashboard />
      )}
      
      {allFlags['beta-features'] && (
        <BetaFeaturePanel />
      )}
    </div>
  );
}

/**
 * Error boundary component for catching React errors
 */
interface ErrorBoundaryProps {
  /** Children to protect */
  children: React.ReactNode;
  /** Fallback UI when error occurs */
  fallback?: React.ComponentType<{ error: Error; errorInfo: any }>;
  /** Error handler */
  onError?: (error: Error, errorInfo: any) => void;
  /** CSS class name */
  className?: string;
}

import { ErrorBoundary } from "@carbon/react";

// Basic error boundary
<ErrorBoundary
  fallback={({ error }) => (
    <div>
      <h2>Something went wrong</h2>
      <p>{error.message}</p>
    </div>
  )}
  onError={(error, errorInfo) => {
    console.error('Error caught by boundary:', error, errorInfo);
  }}
>
  <MyComponent />
</ErrorBoundary>

// Custom error boundary with reporting
<ErrorBoundary
  fallback={({ error }) => (
    <Notification
      kind="error"
      title="Application Error"
      subtitle="Please refresh the page or contact support if the problem persists"
    />
  )}
  onError={(error, errorInfo) => {
    // Send error to monitoring service
    errorReportingService.captureException(error, {
      extra: errorInfo
    });
  }}
>
  <CriticalComponent />
</ErrorBoundary>

/**
 * Icon indicator for status or information
 */
interface IconIndicatorProps {
  /** Indicator kind */
  kind?: "unknown" | "draft" | "in-progress" | "incomplete" | "success" | "warning" | "error";
  /** Icon size */
  size?: "sm" | "md" | "lg";
  /** CSS class name */
  className?: string;
}

/**
 * Shape indicator for geometric status representation
 */
interface ShapeIndicatorProps {
  /** Indicator kind */
  kind?: "unknown" | "draft" | "in-progress" | "incomplete" | "success" | "warning" | "error";
  /** Shape size */
  size?: "sm" | "md" | "lg";
  /** CSS class name */
  className?: string;
}

import { IconIndicator, ShapeIndicator } from "@carbon/react";

// Icon indicators
<div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
  <IconIndicator kind="success" size="md" />
  <span>Task completed</span>
</div>

<div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
  <IconIndicator kind="warning" size="md" />
  <span>Action required</span>
</div>

<div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
  <IconIndicator kind="error" size="md" />
  <span>Failed to process</span>
</div>

// Shape indicators
<div style={{ display: 'flex', gap: '0.5rem', alignItems: 'center' }}>
  <ShapeIndicator kind="in-progress" size="sm" />
  <span>In Progress</span>
</div>

// Status list with indicators
<ul>
  <li>
    <ShapeIndicator kind="success" size="sm" />
    Database connection: OK
  </li>
  <li>
    <ShapeIndicator kind="warning" size="sm" />
    Memory usage: 85%
  </li>
  <li>
    <ShapeIndicator kind="error" size="sm" />
    Authentication: Failed
  </li>
</ul>

/**
 * Layer context for nested component styling
 */
interface LayerProps {
  /** Layer children */
  children: React.ReactNode;
  /** Layer level (0-2) */
  level?: number;
  /** CSS class name */
  className?: string;
}

/**
 * Layout direction provider
 */
interface LayoutDirectionProps {
  /** Direction children */
  children: React.ReactNode;
  /** Text direction */
  dir?: "ltr" | "rtl" | "auto";
  /** CSS class name */
  className?: string;
}

/**
 * Layout direction hook
 */
function useLayoutDirection(): {
  direction: "ltr" | "rtl";
  isRtl: boolean;
};