@usefragments/ui 1.0.0

package/src/components/Chart/index.tsx

@@ -0,0 +1,365 @@
+'use client';
+
+import * as React from 'react';
+import { mergeAriaIds } from '../../utils/aria';
+import styles from './Chart.module.scss';
+
+// ============================================
+// Types (self-owned — no external dependency for types)
+// ============================================
+
+export type ChartConfig = Record<
+  string,
+  {
+    label: string;
+    color: string;
+    icon?: React.ComponentType<Record<string, unknown>>;
+  }
+>;
+
+export interface ChartContainerProps extends React.HTMLAttributes<HTMLDivElement> {
+  config: ChartConfig;
+  children: React.ReactElement;
+  /** Non-visual summary announced to assistive technology users */
+  summary?: string;
+  /** Optional accessible data table or textual fallback */
+  dataTable?: React.ReactNode;
+}
+
+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;
+  }[];
+}
+
+// Internal-only type for recharts Legend props
+type RechartsLegendProps = Record<string, unknown>;
+
+// ============================================
+// Lazy-loaded dependencies (recharts)
+// ============================================
+
+let _RechartsTooltip: React.ComponentType<Record<string, unknown>> | null = null;
+let _RechartsLegend: React.ComponentType<Record<string, unknown>> | null = null;
+let _chartLoaded = false;
+let _chartFailed = false;
+
+function loadChartDeps() {
+  if (_chartLoaded) return;
+  _chartLoaded = true;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const rc = require('recharts');
+    _RechartsTooltip = rc.Tooltip as React.ComponentType<Record<string, unknown>>;
+    _RechartsLegend = rc.Legend as React.ComponentType<Record<string, unknown>>;
+  } catch {
+    _chartFailed = true;
+  }
+}
+
+
+// ============================================
+// 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,
+  summary,
+  dataTable,
+  'aria-label': ariaLabel,
+  'aria-describedby': ariaDescribedBy,
+  ...htmlProps
+}: ChartContainerProps) {
+  const chartId = React.useId();
+  const summaryId = summary ? `chart-summary-${chartId}` : undefined;
+  const dataTableId = dataTable ? `chart-data-${chartId}` : undefined;
+
+  // 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 sizing props into the chart child (recharts API).
+  // Only pass `responsive` for custom component types to avoid leaking the
+  // prop to intrinsic DOM nodes in test/demo usage.
+  const chartChildProps: Record<string, unknown> = {
+    width: '100%',
+    height: '100%',
+  };
+
+  if (typeof children.type !== 'string') {
+    chartChildProps.responsive = true;
+  }
+
+  const chartChild = React.cloneElement(
+    children as React.ReactElement<Record<string, unknown>>,
+    chartChildProps
+  );
+
+  return (
+    <ChartConfigContext.Provider value={config}>
+      <div
+        {...htmlProps}
+        className={rootClasses}
+        style={{ ...cssVars, ...style }}
+        role="img"
+        aria-label={ariaLabel || 'Chart'}
+        aria-describedby={mergeAriaIds(
+          ariaDescribedBy,
+          summaryId,
+          dataTableId
+        )}
+      >
+        {chartChild}
+        {summaryId && (
+          <span id={summaryId} className={styles.srOnly}>
+            {summary}
+          </span>
+        )}
+        {dataTableId && (
+          <div id={dataTableId} className={styles.srOnly}>
+            {dataTable}
+          </div>
+        )}
+      </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 = {
+  indicator?: 'dot' | 'line' | 'dashed';
+  hideLabel?: boolean;
+  hideIndicator?: boolean;
+  labelFormatter?: ChartTooltipContentProps['labelFormatter'];
+  valueFormatter?: ChartTooltipContentProps['valueFormatter'];
+  content?: React.ReactNode | ((tooltipProps: Record<string, unknown>) => React.ReactNode);
+  [key: string]: unknown;
+};
+
+export function ChartTooltip({
+  indicator,
+  hideLabel,
+  hideIndicator,
+  labelFormatter,
+  valueFormatter,
+  content,
+  ...props
+}: ChartTooltipProps) {
+  loadChartDeps();
+
+  const defaultContent = React.useCallback(
+
+    (tooltipProps: Record<string, unknown>) => (
+      <ChartTooltipContent
+        {...(tooltipProps as ChartTooltipContentProps)}
+        indicator={indicator}
+        hideLabel={hideLabel}
+        hideIndicator={hideIndicator}
+        labelFormatter={labelFormatter}
+        valueFormatter={valueFormatter}
+      />
+    ),
+    [indicator, hideLabel, hideIndicator, labelFormatter, valueFormatter],
+  );
+
+  if (_chartFailed || !_RechartsTooltip) {
+    if (_chartFailed && process.env.NODE_ENV === 'development') {
+      console.warn(
+        '[@usefragments/ui] Chart: recharts is not installed. ' +
+        'Install it with: npm install recharts'
+      );
+    }
+    return null;
+  }
+
+  const RechartsTooltipComponent = _RechartsTooltip;
+
+  return (
+    <RechartsTooltipComponent
+      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 = RechartsLegendProps & {
+  content?: React.ReactNode | ((legendProps: Record<string, unknown>) => React.ReactNode);
+};
+
+export function ChartLegend({ content, ...props }: ChartLegendProps) {
+  loadChartDeps();
+
+  const defaultContent = (legendProps: Record<string, unknown>) => (
+    <ChartLegendContent {...(legendProps as ChartLegendContentProps)} />
+  );
+
+  if (_chartFailed || !_RechartsLegend) {
+    if (_chartFailed && process.env.NODE_ENV === 'development') {
+      console.warn(
+        '[@usefragments/ui] Chart: recharts is not installed. ' +
+        'Install it with: npm install recharts'
+      );
+    }
+    return null;
+  }
+
+  const RechartsLegendComponent = _RechartsLegend;
+
+  return (
+    <RechartsLegendComponent
+      content={content ?? defaultContent}
+      {...props}
+    />
+  );
+}
+
+export const Chart = Object.assign(ChartContainer, {
+  Root: ChartContainer,
+  Tooltip: ChartTooltip,
+  TooltipContent: ChartTooltipContent,
+  Legend: ChartLegend,
+  LegendContent: ChartLegendContent,
+});

package/src/components/Checkbox/Checkbox.contract.json

@@ -0,0 +1,256 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Checkbox",
+  "description": "Binary toggle for form fields. Use for options that require explicit submission, unlike Switch which takes effect immediately.",
+  "category": "forms",
+  "tags": [
+    "checkbox",
+    "form",
+    "boolean",
+    "selection",
+    "input"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Checkbox/index.tsx",
+  "exportName": "Checkbox",
+  "propsSummary": [
+    "checked: boolean",
+    "defaultChecked: boolean",
+    "onCheckedChange: function",
+    "onChange: function",
+    "indeterminate: boolean (default: false)",
+    "disabled: boolean (default: false)",
+    "required: boolean (default: false)",
+    "size: sm|md|lg (default: md)",
+    "label: string",
+    "helperText: string",
+    "description: string",
+    "name: string",
+    "value: string",
+    "id: string",
+    "controlClassName: string",
+    "contentClassName: string",
+    "aria-label: string",
+    "aria-labelledby: string",
+    "aria-describedby: string"
+  ],
+  "props": {
+    "checked": {
+      "type": "boolean",
+      "description": "Controlled checked state",
+      "required": false
+    },
+    "defaultChecked": {
+      "type": "boolean",
+      "description": "Default checked state (uncontrolled)",
+      "required": false
+    },
+    "onCheckedChange": {
+      "type": "function",
+      "description": "Called when checked state changes",
+      "required": false
+    },
+    "onChange": {
+      "type": "function",
+      "description": "Alias for onCheckedChange: (checked: boolean) => void",
+      "required": false
+    },
+    "indeterminate": {
+      "type": "boolean",
+      "description": "Indeterminate state (partial selection)",
+      "default": "false",
+      "required": false
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Disable the checkbox",
+      "default": "false",
+      "required": false
+    },
+    "required": {
+      "type": "boolean",
+      "description": "Whether the checkbox is required",
+      "default": "false",
+      "required": false
+    },
+    "size": {
+      "type": "enum",
+      "description": "Checkbox size",
+      "default": "md",
+      "required": false,
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Visual variant. 'default' is the inline checkbox, 'card' renders as a full-width clickable card with the checkbox tucked inside.",
+      "default": "default",
+      "required": false,
+      "values": [
+        "default",
+        "card"
+      ]
+    },
+    "label": {
+      "type": "string",
+      "description": "Label text",
+      "required": false
+    },
+    "helperText": {
+      "type": "string",
+      "description": "Helper text shown below the label (preferred)",
+      "required": false
+    },
+    "description": {
+      "type": "string",
+      "description": "Deprecated alias for helperText",
+      "required": false
+    },
+    "name": {
+      "type": "string",
+      "description": "Name attribute for form submission",
+      "required": false
+    },
+    "value": {
+      "type": "string",
+      "description": "Value attribute for form submission",
+      "required": false
+    },
+    "id": {
+      "type": "string",
+      "description": "ID for the checkbox input",
+      "required": false
+    },
+    "controlClassName": {
+      "type": "string",
+      "description": "Class name for the checkbox control element (stable styling target)",
+      "required": false
+    },
+    "contentClassName": {
+      "type": "string",
+      "description": "Class name for the label/description content wrapper",
+      "required": false
+    },
+    "aria-label": {
+      "type": "string",
+      "description": "Accessible label for icon-only mode",
+      "required": false
+    },
+    "aria-labelledby": {
+      "type": "string",
+      "description": "Accessible labelled-by relationship for icon-only mode",
+      "required": false
+    },
+    "aria-describedby": {
+      "type": "string",
+      "description": "Accessible described-by relationship",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Form fields requiring explicit submission",
+      "Multi-select from a list of options",
+      "Terms and conditions acceptance",
+      "Filter or preference checklists"
+    ],
+    "whenNot": [
+      "Immediate effect settings (use Switch)",
+      "Single selection from options (use RadioGroup)",
+      "Selecting from many options (use Select)"
+    ],
+    "guidelines": [
+      "Always include a visible label",
+      "Use helperText for additional context when needed",
+      "Group related checkboxes visually",
+      "Use indeterminate state for parent/child relationships"
+    ],
+    "accessibility": [
+      "Proper label association",
+      "Keyboard accessible (Space to toggle)",
+      "Visible focus indicator",
+      "Indeterminate state properly announced"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic checkbox with label",
+      "code": "<StatefulCheckbox label=\"Accept terms and conditions\" />"
+    },
+    {
+      "name": "With Helper Text",
+      "description": "Checkbox with helper text",
+      "code": "<StatefulCheckbox\n  label=\"Email notifications\"\n  helperText=\"Receive email updates about your account activity\"\n/>"
+    },
+    {
+      "name": "Checked",
+      "description": "Pre-checked checkbox",
+      "code": "<StatefulCheckbox defaultChecked label=\"Subscribe to newsletter\" />"
+    },
+    {
+      "name": "Indeterminate",
+      "description": "Partial selection state",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Checkbox indeterminate label=\"Select all\" />\n  <div style={{ marginLeft: '24px', display: 'flex', flexDirection: 'column', gap: '8px' }}>\n    <StatefulCheckbox defaultChecked label=\"Option 1\" />\n    <StatefulCheckbox label=\"Option 2\" />\n    <StatefulCheckbox defaultChecked label=\"Option 3\" />\n  </div>\n</div>"
+    },
+    {
+      "name": "Sizes",
+      "description": "Available size options",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>\n  <StatefulCheckbox size=\"sm\" label=\"Small checkbox\" />\n  <StatefulCheckbox size=\"md\" label=\"Medium checkbox\" />\n  <StatefulCheckbox size=\"lg\" label=\"Large checkbox\" />\n</div>"
+    },
+    {
+      "name": "Disabled",
+      "description": "Non-interactive states",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Checkbox disabled label=\"Disabled unchecked\" />\n  <Checkbox disabled checked label=\"Disabled checked\" />\n</div>"
+    },
+    {
+      "name": "Custom Styling Targets",
+      "description": "Use explicit class targets for control vs content styling",
+      "code": "<Checkbox\n  label=\"Styled checkbox\"\n  helperText=\"Control and content wrappers can be targeted independently\"\n  controlClassName=\"demo-checkbox-control\"\n  contentClassName=\"demo-checkbox-content\"\n/>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Switch",
+      "relationship": "alternative",
+      "note": "Use Switch for immediate-effect settings"
+    },
+    {
+      "component": "Input",
+      "relationship": "sibling",
+      "note": "Checkbox handles boolean; Input handles text"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "checked: boolean - controlled checked state",
+      "onCheckedChange: (checked) => void - change handler",
+      "onChange: (checked) => void - alias for onCheckedChange",
+      "indeterminate: boolean - partial selection state",
+      "label: string - checkbox label",
+      "helperText: string - helper text (preferred)",
+      "description: string - deprecated alias for helperText",
+      "controlClassName/contentClassName - explicit styling targets for control and content"
+    ],
+    "a11yRules": [
+      "A11Y_CHECKBOX_LABEL",
+      "A11Y_CHECKBOX_FOCUS",
+      "A11Y_TARGET_SIZE_MIN"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:52.226Z"
+  }
+}