Development Tools

/**
 * Only in development mode, display console warnings when certain conditions are met.
 * Note that all warnings except controlledUsage will only be shown on first render
 * (new controlledUsage warnings may be shown later due to prop changes).
 * @param options - Configuration object for different types of warnings
 */
function useWarnings<P extends {}>(options: IWarningOptions<P>): void;

interface IWarningOptions<P> {
  /** Name of the component */
  name: string;
  /** Current component props */
  props: P;
  /** Generic messages */
  other?: string[];
  /** Warns when props are required if a condition is met */
  conditionallyRequired?: {
    /** Props required when the condition is met */
    requiredProps: string[];
    /** Name of the prop that the condition is based on */
    conditionalPropName: string;
    /** Whether the condition is met */
    condition: boolean;
  }[];
  /** Warns when deprecated props are being used */
  deprecations?: ISettingsMap<P>;
  /** Warns when two props which are mutually exclusive are both being used */
  mutuallyExclusive?: ISettingsMap<P>;
  /** Check for and warn on controlled/uncontrolled component issues */
  controlledUsage?: Pick<
    IWarnControlledUsageParams<P>,
    'valueProp' | 'defaultValueProp' | 'onChangeProp' | 'readOnlyProp'
  >;
}

import { useWarnings } from "@fluentui/react-hooks";

// Basic component with prop validation
interface MyComponentProps {
  title?: string;
  isEnabled?: boolean;
  onClick?: () => void;
  deprecated?: boolean;
  newProp?: boolean;
}

function MyComponent(props: MyComponentProps) {
  const { title, isEnabled, onClick, deprecated, newProp } = props;

  useWarnings({
    name: 'MyComponent',
    props,
    other: [
      !title && 'MyComponent should have a title for accessibility'
    ].filter(Boolean),
    conditionallyRequired: [
      {
        requiredProps: ['onClick'],
        conditionalPropName: 'isEnabled',
        condition: !!isEnabled
      }
    ],
    deprecations: {
      deprecated: 'newProp'
    },
    mutuallyExclusive: {
      deprecated: 'newProp'
    }
  });

  return (
    <div>
      <h1>{title}</h1>
      {isEnabled && <button onClick={onClick}>Click me</button>}
    </div>
  );
}

// Controlled/Uncontrolled component validation
interface TextInputProps {
  value?: string;
  defaultValue?: string;
  onChange?: (value: string) => void;
  readOnly?: boolean;
}

function TextInput(props: TextInputProps) {
  const { value, defaultValue, onChange, readOnly } = props;

  useWarnings({
    name: 'TextInput',
    props,
    controlledUsage: {
      valueProp: 'value',
      defaultValueProp: 'defaultValue',
      onChangeProp: 'onChange',
      readOnlyProp: 'readOnly'
    }
  });

  const [internalValue, setInternalValue] = useState(defaultValue || '');
  const currentValue = value !== undefined ? value : internalValue;

  const handleChange = (newValue: string) => {
    if (value === undefined) {
      setInternalValue(newValue);
    }
    onChange?.(newValue);
  };

  return (
    <input
      value={currentValue}
      onChange={(e) => handleChange(e.target.value)}
      readOnly={readOnly}
    />
  );
}

// Complex validation example
interface DataTableProps {
  data?: any[];
  columns?: string[];
  sortable?: boolean;
  sortColumn?: string;
  onSort?: (column: string) => void;
  virtualizeRows?: boolean;
  rowHeight?: number;
  oldApi?: boolean;
  newApi?: boolean;
}

function DataTable(props: DataTableProps) {
  const { 
    data, 
    columns, 
    sortable, 
    sortColumn, 
    onSort,
    virtualizeRows,
    rowHeight,
    oldApi,
    newApi
  } = props;

  useWarnings({
    name: 'DataTable',
    props,
    other: [
      !data?.length && 'DataTable received empty data array',
      !columns?.length && 'DataTable should specify columns',
      virtualizeRows && !rowHeight && 'rowHeight is recommended when virtualizeRows is enabled'
    ].filter(Boolean),
    conditionallyRequired: [
      {
        requiredProps: ['sortColumn', 'onSort'],
        conditionalPropName: 'sortable',
        condition: !!sortable
      },
      {
        requiredProps: ['rowHeight'],
        conditionalPropName: 'virtualizeRows',
        condition: !!virtualizeRows
      }
    ],
    deprecations: {
      oldApi: 'newApi'
    },
    mutuallyExclusive: {
      oldApi: 'newApi'
    }
  });

  // Component implementation...
  return <div>DataTable component</div>;
}