@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Chart/Chart.module.scss

@@ -1,5 +1,7 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+@use "../../recipes/representation" as representation;
+@use "../../recipes/typography" as typography;
 
 // Container
 .container {
@@ -37,66 +39,63 @@
 
 // Tooltip
 .tooltip {
+  @include representation.chart-tooltip;
+
   background: var(--fui-bg-elevated, $fui-bg-elevated);
-  border: 1px solid var(--fui-border, $fui-border);
+  border: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
   border-radius: var(--fui-radius-md, $fui-radius-md);
   box-shadow: var(--fui-shadow-md, $fui-shadow-md);
-  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
-  font-family: var(--fui-font-sans, $fui-font-sans);
 }
 
 .tooltipLabel {
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
-  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  @include typography.role("ui-standard");
+
   color: var(--fui-text-primary, $fui-text-primary);
-  margin-bottom: var(--fui-space-1, $fui-space-1);
+  margin-block-end: var(--fui-raw-space-4, 4px);
 }
 
 .tooltipItems {
   display: flex;
   flex-direction: column;
-  gap: calc(var(--fui-space-px, $fui-space-px) * 2);
+  gap: var(--_fui-chart-tooltip-item-gap);
 }
 
 .tooltipItem {
   display: flex;
   align-items: center;
-  gap: var(--fui-space-2, $fui-space-2);
+  gap: var(--_fui-chart-tooltip-item-gap);
   justify-content: space-between;
-  min-width: 100px;
 }
 
 .tooltipIndicator {
-  width: 8px;
-  height: 8px;
-  border-radius: var(--fui-radius-full, $fui-radius-full);
+  @include representation.chart-marker("dot");
+
   flex-shrink: 0;
 
   &.tooltipIndicatorLine {
-    width: 12px;
-    height: 2px;
+    @include representation.chart-marker("line");
+
     border-radius: var(--fui-radius-full, $fui-radius-full);
   }
 
   &.tooltipIndicatorDashed {
-    width: 12px;
-    height: 0;
-    border-top: 2px dashed;
+    @include representation.chart-marker("dashed");
+
+    box-sizing: border-box;
+    border-top: var(--fui-chart-marker-stroke, var(--fui-raw-space-2, 2px)) dashed;
     border-radius: 0;
   }
 }
 
 .tooltipItemLabel {
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
   color: var(--fui-text-secondary, $fui-text-secondary);
 }
 
 .tooltipItemValue {
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
   font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
   color: var(--fui-text-primary, $fui-text-primary);
   font-variant-numeric: tabular-nums;
-  margin-left: auto;
+  margin-inline-start: auto;
 }
 
 // Legend
@@ -105,24 +104,24 @@
   flex-wrap: wrap;
   align-items: center;
   justify-content: center;
-  gap: var(--fui-space-3, $fui-space-3);
-  padding-top: var(--fui-space-2, $fui-space-2);
+  gap: var(--fui-raw-space-12, 12px);
+  padding-block-start: var(--fui-raw-space-8, 8px);
 }
 
 .legendItem {
   display: flex;
   align-items: center;
-  gap: var(--fui-space-1, $fui-space-1);
+  gap: var(--fui-raw-space-4, 4px);
 }
 
 .legendDot {
-  width: 8px;
-  height: 8px;
-  border-radius: var(--fui-radius-full, $fui-radius-full);
+  @include representation.chart-marker("dot");
+
   flex-shrink: 0;
 }
 
 .legendLabel {
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  @include typography.role("ui-compact");
+
   color: var(--fui-text-secondary, $fui-text-secondary);
 }

package/src/components/Chart/index.tsx

@@ -1,8 +1,9 @@
-'use client';
+"use client";
 
-import * as React from 'react';
-import { mergeAriaIds } from '../../utils/aria';
-import styles from './Chart.module.scss';
+import * as React from "react";
+import { mergeAriaIds } from "../../utils/aria";
+import styles from "./Chart.module.scss";
+import { isDevelopmentBuild } from "../../utils/env";
 
 // ============================================
 // Types (self-owned — no external dependency for types)
@@ -36,10 +37,10 @@ export interface ChartTooltipContentProps {
     payload?: Record<string, unknown>;
   }[];
   label?: string;
-  indicator?: 'dot' | 'line' | 'dashed';
+  indicator?: "dot" | "line" | "dashed";
   hideLabel?: boolean;
   hideIndicator?: boolean;
-  labelFormatter?: (label: string, payload: ChartTooltipContentProps['payload']) => React.ReactNode;
+  labelFormatter?: (label: string, payload: ChartTooltipContentProps["payload"]) => React.ReactNode;
   valueFormatter?: (value: number | string) => string;
 }
 
@@ -69,15 +70,15 @@ function loadChartDeps(): Promise<void> {
   if (!_chartLoadPromise) {
     _chartLoadPromise = (async () => {
       try {
-        const rc = await import('recharts');
+        const rc = await import("recharts");
         _RechartsTooltip = rc.Tooltip as unknown as React.ComponentType<Record<string, unknown>>;
         _RechartsLegend = rc.Legend as unknown as React.ComponentType<Record<string, unknown>>;
       } catch {
         _chartFailed = true;
-        if (process.env.NODE_ENV === 'development') {
+        if (isDevelopmentBuild()) {
           console.warn(
-            '[@usefragments/ui] Chart: recharts is not installed. ' +
-            'Install it with: npm install recharts'
+            "[@usefragments/ui] Chart: recharts is not installed. " +
+              "Install it with: npm install recharts"
           );
         }
       }
@@ -102,7 +103,6 @@ function useChartDeps(): boolean {
   return _RechartsTooltip !== null;
 }
 
-
 // ============================================
 // Context
 // ============================================
@@ -112,7 +112,7 @@ 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>');
+    throw new Error("useChartConfig must be used within a <ChartContainer>");
   }
   return ctx;
 }
@@ -128,11 +128,39 @@ export function ChartContainer({
   style,
   summary,
   dataTable,
-  'aria-label': ariaLabel,
-  'aria-describedby': ariaDescribedBy,
+  "aria-label": ariaLabel,
+  "aria-describedby": ariaDescribedBy,
   ...htmlProps
 }: ChartContainerProps) {
   const chartId = React.useId();
+  const frameRef = React.useRef<HTMLDivElement | null>(null);
+  // Recharts only lays a chart out once it knows a pixel box. Percentage
+  // sizing leaves the first paint blank until something else happens to
+  // resize the window, so the container measures its own frame and hands the
+  // chart real numbers — re-measured whenever the frame changes.
+  const [frame, setFrame] = React.useState<{ width: number; height: number } | null>(null);
+
+  React.useEffect(() => {
+    const element = frameRef.current;
+    if (!element || typeof ResizeObserver === "undefined") return;
+
+    const measure = () => {
+      const rect = element.getBoundingClientRect();
+      const width = Math.round(rect.width);
+      const height = Math.round(rect.height);
+      setFrame((current) =>
+        current && current.width === width && current.height === height
+          ? current
+          : { width, height }
+      );
+    };
+
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, []);
+
   const summaryId = summary ? `chart-summary-${chartId}` : undefined;
   const dataTableId = dataTable ? `chart-data-${chartId}` : undefined;
 
@@ -145,17 +173,17 @@ export function ChartContainer({
     return vars;
   }, [config]);
 
-  const rootClasses = [styles.container, className].filter(Boolean).join(' ');
+  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%',
-  };
+  const measured = frame !== null && frame.width > 0 && frame.height > 0;
+  const chartChildProps: Record<string, unknown> = measured
+    ? { width: frame.width, height: frame.height }
+    : { width: "100%", height: "100%" };
 
-  if (typeof children.type !== 'string') {
+  if (!measured && typeof children.type !== "string") {
     chartChildProps.responsive = true;
   }
 
@@ -168,15 +196,12 @@ export function ChartContainer({
     <ChartConfigContext.Provider value={config}>
       <div
         {...htmlProps}
+        ref={frameRef}
         className={rootClasses}
         style={{ ...cssVars, ...style }}
         role="img"
-        aria-label={ariaLabel || 'Chart'}
-        aria-describedby={mergeAriaIds(
-          ariaDescribedBy,
-          summaryId,
-          dataTableId
-        )}
+        aria-label={ariaLabel || "Chart"}
+        aria-describedby={mergeAriaIds(ariaDescribedBy, summaryId, dataTableId)}
       >
         {chartChild}
         {summaryId && (
@@ -202,7 +227,7 @@ export function ChartTooltipContent({
   active,
   payload,
   label,
-  indicator = 'dot',
+  indicator = "dot",
   hideLabel = false,
   hideIndicator = false,
   labelFormatter,
@@ -212,15 +237,11 @@ export function ChartTooltipContent({
 
   if (!active || !payload?.length) return null;
 
-  const formattedLabel = labelFormatter
-    ? labelFormatter(String(label), payload)
-    : label;
+  const formattedLabel = labelFormatter ? labelFormatter(String(label), payload) : label;
 
   return (
     <div className={styles.tooltip}>
-      {!hideLabel && formattedLabel && (
-        <div className={styles.tooltipLabel}>{formattedLabel}</div>
-      )}
+      {!hideLabel && formattedLabel && <div className={styles.tooltipLabel}>{formattedLabel}</div>}
       <div className={styles.tooltipItems}>
         {payload.map((entry, i) => {
           const key = String(entry.dataKey ?? entry.name ?? i);
@@ -229,20 +250,25 @@ export function ChartTooltipContent({
           const color = entry.color ?? configEntry?.color;
           const displayValue = valueFormatter
             ? valueFormatter(entry.value ?? 0)
-            : String(entry.value ?? '');
+            : String(entry.value ?? "");
 
           const indicatorClass = [
             styles.tooltipIndicator,
-            indicator === 'line' && styles.tooltipIndicatorLine,
-            indicator === 'dashed' && styles.tooltipIndicatorDashed,
-          ].filter(Boolean).join(' ');
+            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 }}
+                  style={{
+                    backgroundColor: indicator === "dashed" ? undefined : color,
+                    borderColor: color,
+                  }}
                 />
               )}
               <span className={styles.tooltipItemLabel}>{displayLabel}</span>
@@ -260,11 +286,11 @@ export function ChartTooltipContent({
 // ============================================
 
 type ChartTooltipProps = {
-  indicator?: 'dot' | 'line' | 'dashed';
+  indicator?: "dot" | "line" | "dashed";
   hideLabel?: boolean;
   hideIndicator?: boolean;
-  labelFormatter?: ChartTooltipContentProps['labelFormatter'];
-  valueFormatter?: ChartTooltipContentProps['valueFormatter'];
+  labelFormatter?: ChartTooltipContentProps["labelFormatter"];
+  valueFormatter?: ChartTooltipContentProps["valueFormatter"];
   content?: React.ReactNode | ((tooltipProps: Record<string, unknown>) => React.ReactNode);
   [key: string]: unknown;
 };
@@ -281,7 +307,6 @@ export function ChartTooltip({
   const chartReady = useChartDeps();
 
   const defaultContent = React.useCallback(
-
     (tooltipProps: Record<string, unknown>) => (
       <ChartTooltipContent
         {...(tooltipProps as ChartTooltipContentProps)}
@@ -292,7 +317,7 @@ export function ChartTooltip({
         valueFormatter={valueFormatter}
       />
     ),
-    [indicator, hideLabel, hideIndicator, labelFormatter, valueFormatter],
+    [indicator, hideLabel, hideIndicator, labelFormatter, valueFormatter]
   );
 
   // Nothing until recharts resolves; nothing at all if it is not installed.
@@ -304,7 +329,7 @@ export function ChartTooltip({
 
   return (
     <RechartsTooltipComponent
-      cursor={{ stroke: 'var(--fui-border)' }}
+      cursor={{ stroke: "var(--fui-border)" }}
       content={content ?? defaultContent}
       {...props}
     />
@@ -323,17 +348,14 @@ export function ChartLegendContent({ payload }: ChartLegendContentProps) {
   return (
     <div className={styles.legend}>
       {payload.map((entry) => {
-        const key = String(entry.dataKey ?? entry.value ?? '');
+        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.legendDot} style={{ backgroundColor: color }} />
             <span className={styles.legendLabel}>{label}</span>
           </div>
         );
@@ -363,12 +385,7 @@ export function ChartLegend({ content, ...props }: ChartLegendProps) {
 
   const RechartsLegendComponent = _RechartsLegend;
 
-  return (
-    <RechartsLegendComponent
-      content={content ?? defaultContent}
-      {...props}
-    />
-  );
+  return <RechartsLegendComponent content={content ?? defaultContent} {...props} />;
 }
 
 export const Chart = Object.assign(ChartContainer, {

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

@@ -1,8 +1,8 @@
 {
   "$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",
+  "description": "Selects options that take effect when a form is submitted.",
+  "category": "inputs",
   "tags": ["checkbox", "form", "boolean", "selection", "input"],
   "status": "stable",
   "sourcePath": "src/components/Checkbox/index.tsx",
@@ -139,63 +139,63 @@
   },
   "usage": {
     "when": [
-      "Form fields requiring explicit submission",
-      "Multi-select from a list of options",
-      "Terms and conditions acceptance",
-      "Filter or preference checklists"
+      "Choices that apply only once the form is submitted",
+      "Picking several items from a list",
+      "Accepting terms",
+      "Filter and preference lists"
     ],
     "whenNot": [
-      "Immediate effect settings (use Switch)",
-      "Single selection from options (use RadioGroup)",
-      "Selecting from many options (use Select)"
+      "Settings that apply instantly (use Switch)",
+      "One choice from a few (use RadioGroup)",
+      "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"
+      "Always show a label",
+      "Add helperText when the consequence is not obvious",
+      "Keep related boxes together",
+      "Use indeterminate for a parent whose children are partly checked"
     ],
     "accessibility": [
-      "Proper label association",
-      "Keyboard accessible (Space to toggle)",
-      "Visible focus indicator",
-      "Indeterminate state properly announced"
+      "Label is tied to the box",
+      "Space toggles it",
+      "Focus ring stays visible",
+      "Indeterminate is announced as mixed"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic checkbox with label",
+      "description": "One box, one label, off to start.",
       "code": "<StatefulCheckbox label=\"Accept terms and conditions\" />"
     },
     {
       "name": "With Helper Text",
-      "description": "Checkbox with helper text",
+      "description": "Second line spells out what opting in does.",
       "code": "<StatefulCheckbox\n  label=\"Email notifications\"\n  helperText=\"Receive email updates about your account activity\"\n/>"
     },
     {
       "name": "Checked",
-      "description": "Pre-checked checkbox",
+      "description": "Starts on.",
       "code": "<StatefulCheckbox defaultChecked label=\"Subscribe to newsletter\" />"
     },
     {
       "name": "Indeterminate",
-      "description": "Partial selection state",
+      "description": "A dash on the parent means only some children are on.",
       "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",
+      "description": "Three box sizes: sm, md, lg.",
       "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",
+      "description": "Locked in both positions, on and off.",
       "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",
+      "description": "controlClassName styles the box, contentClassName the text.",
       "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/>"
     }
   ],