@sixthshift/design-system 0.2.1 → 0.4.0

package/src/components/Field/Field.tsx

@@ -1,28 +1,11 @@
 import { cn } from "@sixthshift/design-system/utils";
-import type { ReactNode } from "react";
+import * as React from "react";
 
-/**
- * The labelled identifier carve-out used by identity-disclosure surfaces
- * (Person Detail's Identifiers card, Calendar Event's per-source provenance).
- *
- * Field exists because identifiers (JIDs, external IDs, OAuth subs) are
- * *content* on these surfaces — they answer "what does PA know about this
- * contact?" The default value rendering is monospaced with `break-all`
- * because a raw JID is the canonical case and it must wrap inside the row.
- *
- * Sibling primitive — not a replacement: `MetricRow` (in `@sixthshift/design-system/metric-list`)
- * carries runtime metrics ("CPU: 12.5%"). Both are label/value pairs but the
- * value semantics differ: a metric is a short readable number; an identifier
- * is a long opaque string. Forcing `MetricRow` to do both would conflate the
- * two and break Identifiers-card wrapping.
- *
- * See: docs/engineering/explanation/concepts/identity-rendering.md
- */
 export type FieldProps = {
   /** The humane label for what the identifier identifies ("WhatsApp", "Email"). */
   label: string;
   /** The identifier itself. Rendered monospaced + breakable by default. */
-  children: ReactNode;
+  children: React.ReactNode;
   /**
    * `stacked` (default): label above, value below — best for long identifiers
    * that need horizontal room to wrap.
@@ -39,22 +22,38 @@ export type FieldProps = {
   className?: string;
 };
 
-export const Field = ({ label, children, layout = "stacked", mono = true, className }: FieldProps) => {
-  const valueClass = cn("text-fg-subtle text-xs", mono && "break-all font-mono");
+/**
+ * Read-only label/value pair for displaying an identifier on
+ * identity-disclosure surfaces — a contact's JIDs, external IDs, OAuth
+ * subjects. Not a form control: there is no input and nothing to submit.
+ *
+ * `layout="stacked"` (default) puts the label above the value, for long
+ * identifiers that need width to wrap; `layout="row"` puts label and value
+ * on one line with the value right-aligned. `mono` (default `true`) renders
+ * the value monospaced with `break-all`, since a raw identifier is the
+ * canonical case; set it `false` when the value is itself human-readable.
+ *
+ * Distinct from `FormField`, which is the label + input wrapper for
+ * interactive form controls. Both are label/value pairs, but this one is
+ * read-only: the value is a long opaque identifier, not an editable field.
+ */
+export const Field = React.forwardRef<HTMLDivElement, FieldProps>(({ label, children, layout = "stacked", mono = true, className }, ref) => {
+  const valueClass = cn("text-(--field-fg) text-xs", mono && "break-all font-mono");
 
   if (layout === "row") {
     return (
-      <div className={cn("flex items-baseline justify-between gap-3", className)}>
-        <span className="shrink-0 text-fg-subtle text-sm">{label}</span>
+      <div ref={ref} className={cn("field flex items-baseline justify-between gap-3", className)}>
+        <span className="shrink-0 text-(--field-fg) text-sm">{label}</span>
         <span className={cn(valueClass, "min-w-0 text-right")}>{children}</span>
       </div>
     );
   }
 
   return (
-    <div className={cn("flex flex-col gap-1", className)}>
-      <span className="text-fg-subtle text-xs uppercase tracking-wide">{label}</span>
+    <div ref={ref} className={cn("field flex flex-col gap-1", className)}>
+      <span className="text-(--field-fg) text-xs uppercase tracking-wide">{label}</span>
       <span className={valueClass}>{children}</span>
     </div>
   );
-};
+});
+Field.displayName = "Field";

package/src/components/FormField/FormField.tsx

@@ -16,6 +16,21 @@ export type FormFieldProps = React.HTMLAttributes<HTMLDivElement> & {
   required?: boolean;
 };
 
+/**
+ * Wraps a form control with a label, optional description, and optional
+ * validation feedback — the composition point for `Input`, `Textarea`,
+ * `Select` and similar controls inside a form.
+ *
+ * Generates an `id` (or uses the one passed in) and clones it, plus
+ * `aria-describedby` (pointing at the description and/or feedback text) and
+ * `aria-invalid` (when `feedback.intent` is `"danger"`), onto its child —
+ * so the wrapped control does not need those wired by hand. It expects a
+ * single child control: the same id and aria attributes get cloned onto
+ * every child if more than one is passed.
+ *
+ * Distinct from `Field`, which displays a read-only label/value pair rather
+ * than wrapping an interactive control.
+ */
 const FormField = React.forwardRef<HTMLDivElement, FormFieldProps>(({ className, label, description, feedback, required, children, id, ...props }, ref) => {
   const generatedId = React.useId();
   const fieldId = id ?? generatedId;

package/src/components/HoverCard/HoverCard.tsx

@@ -77,6 +77,12 @@ type HoverCardComponent = typeof HoverCardRoot & {
   Content: typeof HoverCardContent;
 };
 
+/**
+ * NOTE: Storybook shows the copy in HoverCard.stories.tsx
+ * (`parameters.docs.description.component`), not this comment. react-docgen
+ * cannot extract a description from this declaration shape, so keeping a
+ * second copy here would only drift. Edit the stories file.
+ */
 export const HoverCard: HoverCardComponent = Object.assign(HoverCardRoot, {
   Trigger: HoverCardTrigger,
   Content: HoverCardContent,

package/src/components/Input/Input.tsx

@@ -6,20 +6,35 @@ export type InputProps = React.InputHTMLAttributes<HTMLInputElement> & {
   iconRight?: React.ReactNode;
 };
 
-const iconSlotStyles = `absolute top-1/2 -translate-y-1/2 text-fg-subtle
+const iconSlotStyles = `absolute top-1/2 -translate-y-1/2 text-(--input-icon-fg)
   [&_svg]:h-4 [&_svg]:w-4
   [&_button]:flex [&_button]:cursor-pointer [&_button]:appearance-none
   [&_button]:border-0 [&_button]:bg-transparent`;
 
+/**
+ * Single-line text input for free-form text entry.
+ *
+ * Renders a plain `<input>` unless `iconLeft` or `iconRight` is supplied, in
+ * which case it wraps the input in a relatively positioned container so an
+ * icon — or an icon-styled button, as `SearchInput` uses for its clear
+ * button — can sit inside the field's padding without affecting layout.
+ *
+ * Controlled or uncontrolled exactly like a native input (`value`/`onChange`
+ * or `defaultValue`), and `type` is forwarded as-is, so `type="password"`,
+ * `type="number"`, etc. all work.
+ *
+ * Meant to be wrapped by `FormField` for label, description and validation
+ * wiring, or by `SearchInput` for a search affordance.
+ */
 const Input = React.forwardRef<HTMLInputElement, InputProps>(({ className, type, iconLeft, iconRight, ...props }, ref) => {
   if (iconLeft || iconRight) {
     return (
-      <div className={cn("relative h-9 w-full text-sm", className)}>
+      <div className={cn("input relative h-9 w-full text-sm", className)}>
         {iconLeft && <span className={cn(iconSlotStyles, "left-3")}>{iconLeft}</span>}
         <input
           type={type}
           className={cn(
-            `flex h-full w-full rounded-md border border-border-normal bg-bg-normal py-1 text-[length:inherit] shadow-xs transition-colors file:border-0 file:bg-bg-normal file:font-medium file:text-fg-normal file:text-sm placeholder:text-fg-subtle focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50`,
+            `input border-(color:--input-border) focus-visible:ring-(color:--input-ring) flex h-full w-full rounded-md border bg-(--input-bg) py-1 text-[length:inherit] shadow-xs transition-colors file:border-0 file:bg-(--input-file-bg) file:font-medium file:text-(--input-file-fg) file:text-sm placeholder:text-(--input-placeholder-fg) focus-visible:outline-hidden focus-visible:ring-2 disabled:cursor-not-allowed disabled:opacity-50`,
             iconLeft ? "pl-9" : "pl-3",
             iconRight ? "pr-9" : "pr-3"
           )}
@@ -35,7 +50,7 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(({ className, type,
     <input
       type={type}
       className={cn(
-        `flex h-9 w-full rounded-md border border-border-normal bg-bg-normal px-3 py-1 text-sm shadow-xs transition-colors file:border-0 file:bg-bg-normal file:font-medium file:text-fg-normal file:text-sm placeholder:text-fg-subtle focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50`,
+        `input border-(color:--input-border) focus-visible:ring-(color:--input-ring) flex h-9 w-full rounded-md border bg-(--input-bg) px-3 py-1 text-sm shadow-xs transition-colors file:border-0 file:bg-(--input-file-bg) file:font-medium file:text-(--input-file-fg) file:text-sm placeholder:text-(--input-placeholder-fg) focus-visible:outline-hidden focus-visible:ring-2 disabled:cursor-not-allowed disabled:opacity-50`,
         className
       )}
       ref={ref}

package/src/components/LineChart/LineChart.tsx

@@ -1,6 +1,6 @@
 import { Tooltip } from "@sixthshift/design-system/tooltip";
 import { cn } from "@sixthshift/design-system/utils";
-import type * as React from "react";
+import * as React from "react";
 
 export type LineChartDataPoint = {
   label: string;
@@ -96,156 +96,179 @@ function buildPath(points: { x: number; y: number }[], interpolation: Interpolat
   return parts.join(" ");
 }
 
-export const LineChart = ({
-  series,
-  height = 200,
-  showGrid = true,
-  showAxes = true,
-  showDots = true,
-  showLabels = true,
-  showValues = false,
-  interpolation = "monotone",
-  fillArea = false,
-  yMin: yMinProp,
-  yMax: yMaxProp,
-  yTicks = 4,
-  showTooltip = false,
-  formatTooltip,
-  formatValue = (v) => String(v),
-  className,
-  ...rest
-}: LineChartProps) => {
-  const allValues = series.flatMap((s) => s.data.map((d) => d.value));
-  // Math.min() of an empty list is Infinity, which propagates NaN through the
-  // whole scale. Fall back to a plain 0-1 axis when there is no data.
-  const rawMin = yMinProp ?? (allValues.length > 0 ? Math.min(...allValues) : 0);
-  const rawMax = yMaxProp ?? (allValues.length > 0 ? Math.max(...allValues) : 1);
-  const scale = niceScale(rawMin, rawMax, yTicks);
-
-  const labelSet = new Set<string>();
-  for (const s of series) {
-    for (const d of s.data) {
-      labelSet.add(d.label);
+/**
+ * Multi-series line chart, rendered as a single responsive SVG (a `viewBox`,
+ * no fixed pixel size) with one `<path>` per series, plus optional grid
+ * lines, axes, dots, and per-point value labels.
+ *
+ * Colour is per-series: pass a CSS color string via `color` on a
+ * `LineChartSeries` (typically a `var(--fg-*)` token), or omit it to cycle
+ * through the same default palette `BarChart` uses. The y-axis scale is
+ * computed from the data into "nice" round ticks unless `yMin`/`yMax`/
+ * `yTicks` override it.
+ *
+ * The chart has a single static accessible name — `<title>Line
+ * chart</title>` behind `role="img"` — regardless of what's plotted; it does
+ * not describe the series or values. `showTooltip` overlays a `Tooltip` at
+ * each data point, but the trigger is a plain, unfocusable `<span>`, so it
+ * only responds to mouse hover, not keyboard.
+ */
+export const LineChart = React.forwardRef<HTMLDivElement, LineChartProps>(
+  (
+    {
+      series,
+      height = 200,
+      showGrid = true,
+      showAxes = true,
+      showDots = true,
+      showLabels = true,
+      showValues = false,
+      interpolation = "monotone",
+      fillArea = false,
+      yMin: yMinProp,
+      yMax: yMaxProp,
+      yTicks = 4,
+      showTooltip = false,
+      formatTooltip,
+      formatValue = (v) => String(v),
+      className,
+      ...rest
+    }: LineChartProps,
+    ref
+  ) => {
+    const allValues = series.flatMap((s) => s.data.map((d) => d.value));
+    // Math.min() of an empty list is Infinity, which propagates NaN through the
+    // whole scale. Fall back to a plain 0-1 axis when there is no data.
+    const rawMin = yMinProp ?? (allValues.length > 0 ? Math.min(...allValues) : 0);
+    const rawMax = yMaxProp ?? (allValues.length > 0 ? Math.max(...allValues) : 1);
+    const scale = niceScale(rawMin, rawMax, yTicks);
+
+    const labelSet = new Set<string>();
+    for (const s of series) {
+      for (const d of s.data) {
+        labelSet.add(d.label);
+      }
     }
-  }
-  const labels = [...labelSet];
-  const labelCount = labels.length;
-  const labelIndex = new Map(labels.map((l, i) => [l, i]));
+    const labels = [...labelSet];
+    const labelCount = labels.length;
+    const labelIndex = new Map(labels.map((l, i) => [l, i]));
 
-  const padding = showAxes ? PADDING : PADDING_NO_AXES;
-  const viewWidth = 600;
-  const chartW = viewWidth - padding.left - padding.right;
-  const chartH = height - padding.top - padding.bottom;
+    const padding = showAxes ? PADDING : PADDING_NO_AXES;
+    const viewWidth = 600;
+    const chartW = viewWidth - padding.left - padding.right;
+    const chartH = height - padding.top - padding.bottom;
 
-  const xStep = labelCount > 1 ? chartW / (labelCount - 1) : 0;
+    const xStep = labelCount > 1 ? chartW / (labelCount - 1) : 0;
 
-  function toX(i: number) {
-    return padding.left + i * xStep;
-  }
+    function toX(i: number) {
+      return padding.left + i * xStep;
+    }
 
-  function toY(v: number) {
-    const ratio = (v - scale.min) / (scale.max - scale.min);
-    return padding.top + chartH - ratio * chartH;
-  }
+    function toY(v: number) {
+      const ratio = (v - scale.min) / (scale.max - scale.min);
+      return padding.top + chartH - ratio * chartH;
+    }
 
-  const yTickValues: number[] = [];
-  for (let v = scale.min; v <= scale.max + scale.step * 0.01; v += scale.step) {
-    yTickValues.push(Math.round(v * 1e6) / 1e6);
-  }
+    const yTickValues: number[] = [];
+    for (let v = scale.min; v <= scale.max + scale.step * 0.01; v += scale.step) {
+      yTickValues.push(Math.round(v * 1e6) / 1e6);
+    }
 
-  function tooltipText(point: LineChartDataPoint, seriesName?: string) {
-    if (formatTooltip) return formatTooltip(point, seriesName);
-    const prefix = seriesName ? `${seriesName}: ` : `${point.label}: `;
-    return `${prefix}${formatValue(point.value)}`;
-  }
+    function tooltipText(point: LineChartDataPoint, seriesName?: string) {
+      if (formatTooltip) return formatTooltip(point, seriesName);
+      const prefix = seriesName ? `${seriesName}: ` : `${point.label}: `;
+      return `${prefix}${formatValue(point.value)}`;
+    }
+
+    return (
+      <div ref={ref} {...rest} className={cn("relative w-full", className)}>
+        <svg viewBox={`0 0 ${viewWidth} ${height}`} className="w-full" preserveAspectRatio="xMidYMid meet" role="img">
+          <title>Line chart</title>
+          {showGrid &&
+            yTickValues.map((v) => (
+              <line
+                key={`grid-${v}`}
+                x1={padding.left}
+                y1={toY(v)}
+                x2={viewWidth - padding.right}
+                y2={toY(v)}
+                className="stroke-border-subtle"
+                strokeWidth={1}
+                strokeDasharray="4 4"
+              />
+            ))}
 
-  return (
-    <div {...rest} className={cn("relative w-full", className)}>
-      <svg viewBox={`0 0 ${viewWidth} ${height}`} className="w-full" preserveAspectRatio="xMidYMid meet" role="img">
-        <title>Line chart</title>
-        {showGrid &&
-          yTickValues.map((v) => (
-            <line
-              key={`grid-${v}`}
-              x1={padding.left}
-              y1={toY(v)}
-              x2={viewWidth - padding.right}
-              y2={toY(v)}
-              className="stroke-border-subtle"
-              strokeWidth={1}
-              strokeDasharray="4 4"
-            />
-          ))}
-
-        {showAxes && (
-          <>
-            <line x1={padding.left} y1={padding.top} x2={padding.left} y2={padding.top + chartH} className="stroke-border-normal" strokeWidth={1} />
-            <line
-              x1={padding.left}
-              y1={padding.top + chartH}
-              x2={viewWidth - padding.right}
-              y2={padding.top + chartH}
-              className="stroke-border-normal"
-              strokeWidth={1}
-            />
-            {yTickValues.map((v) => (
-              <text key={`ytick-${v}`} x={padding.left - 8} y={toY(v)} textAnchor="end" dominantBaseline="middle" className="fill-fg-subtle" fontSize={11}>
-                {formatValue(v)}
+          {showAxes && (
+            <>
+              <line x1={padding.left} y1={padding.top} x2={padding.left} y2={padding.top + chartH} className="stroke-border-normal" strokeWidth={1} />
+              <line
+                x1={padding.left}
+                y1={padding.top + chartH}
+                x2={viewWidth - padding.right}
+                y2={padding.top + chartH}
+                className="stroke-border-normal"
+                strokeWidth={1}
+              />
+              {yTickValues.map((v) => (
+                <text key={`ytick-${v}`} x={padding.left - 8} y={toY(v)} textAnchor="end" dominantBaseline="middle" className="fill-fg-subtle" fontSize={11}>
+                  {formatValue(v)}
+                </text>
+              ))}
+            </>
+          )}
+
+          {showLabels &&
+            labels.map((label, i) => (
+              <text key={`xlabel-${label}`} x={toX(i)} y={height - 4} textAnchor="middle" className="fill-fg-subtle" fontSize={11}>
+                {label}
               </text>
             ))}
-          </>
-        )}
-
-        {showLabels &&
-          labels.map((label, i) => (
-            <text key={`xlabel-${label}`} x={toX(i)} y={height - 4} textAnchor="middle" className="fill-fg-subtle" fontSize={11}>
-              {label}
-            </text>
-          ))}
-
-        {series.map((s, si) => {
-          const color = s.color ?? SERIES_COLORS[si % SERIES_COLORS.length];
-          const points = s.data.map((d) => ({ x: toX(labelIndex.get(d.label)!), y: toY(d.value) }));
-          const path = buildPath(points, interpolation);
-
-          return (
-            <g key={s.name ?? si}>
-              {fillArea && path && (
-                <path
-                  d={`${path} L ${points[points.length - 1]!.x} ${padding.top + chartH} L ${points[0]!.x} ${padding.top + chartH} Z`}
-                  fill={color}
-                  opacity={0.1}
-                />
-              )}
-              {path && <path d={path} fill="none" stroke={color} strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" />}
-              {showDots && points.map((p, pi) => <circle key={`dot-${s.data[pi]!.label}`} cx={p.x} cy={p.y} r={3} fill={color} />)}
-              {showValues &&
-                points.map((p, vi) => (
-                  <text key={`val-${s.data[vi]!.label}`} x={p.x} y={p.y - 10} textAnchor="middle" className="fill-fg-normal" fontSize={10} fontWeight={600}>
-                    {formatValue(s.data[vi]!.value)}
-                  </text>
-                ))}
-            </g>
-          );
-        })}
-      </svg>
-
-      {showTooltip &&
-        series.map((s, si) =>
-          s.data.map((d) => {
-            const xPct = (toX(labelIndex.get(d.label)!) / viewWidth) * 100;
-            const yPct = (toY(d.value) / height) * 100;
+
+          {series.map((s, si) => {
+            const color = s.color ?? SERIES_COLORS[si % SERIES_COLORS.length];
+            const points = s.data.map((d) => ({ x: toX(labelIndex.get(d.label)!), y: toY(d.value) }));
+            const path = buildPath(points, interpolation);
 
             return (
-              <Tooltip key={`tip-${s.name ?? si}-${d.label}`} delayShow={0}>
-                <Tooltip.Trigger asChild>
-                  <span className="absolute block -translate-x-1/2 -translate-y-1/2" style={{ left: `${xPct}%`, top: `${yPct}%`, width: 16, height: 16 }} />
-                </Tooltip.Trigger>
-                <Tooltip.Body>{tooltipText(d, s.name)}</Tooltip.Body>
-              </Tooltip>
+              <g key={s.name ?? si}>
+                {fillArea && path && (
+                  <path
+                    d={`${path} L ${points[points.length - 1]!.x} ${padding.top + chartH} L ${points[0]!.x} ${padding.top + chartH} Z`}
+                    fill={color}
+                    opacity={0.1}
+                  />
+                )}
+                {path && <path d={path} fill="none" stroke={color} strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" />}
+                {showDots && points.map((p, pi) => <circle key={`dot-${s.data[pi]!.label}`} cx={p.x} cy={p.y} r={3} fill={color} />)}
+                {showValues &&
+                  points.map((p, vi) => (
+                    <text key={`val-${s.data[vi]!.label}`} x={p.x} y={p.y - 10} textAnchor="middle" className="fill-fg-normal" fontSize={10} fontWeight={600}>
+                      {formatValue(s.data[vi]!.value)}
+                    </text>
+                  ))}
+              </g>
             );
-          })
-        )}
-    </div>
-  );
-};
+          })}
+        </svg>
+
+        {showTooltip &&
+          series.map((s, si) =>
+            s.data.map((d) => {
+              const xPct = (toX(labelIndex.get(d.label)!) / viewWidth) * 100;
+              const yPct = (toY(d.value) / height) * 100;
+
+              return (
+                <Tooltip key={`tip-${s.name ?? si}-${d.label}`} delayShow={0}>
+                  <Tooltip.Trigger asChild>
+                    <span className="absolute block -translate-x-1/2 -translate-y-1/2" style={{ left: `${xPct}%`, top: `${yPct}%`, width: 16, height: 16 }} />
+                  </Tooltip.Trigger>
+                  <Tooltip.Body>{tooltipText(d, s.name)}</Tooltip.Body>
+                </Tooltip>
+              );
+            })
+          )}
+      </div>
+    );
+  }
+);
+LineChart.displayName = "LineChart";

package/src/components/Markdown/Markdown.tsx

@@ -2,6 +2,7 @@ import { Body } from "@sixthshift/design-system/body";
 import { Emphasis } from "@sixthshift/design-system/emphasis";
 import { Heading } from "@sixthshift/design-system/heading";
 import { cn } from "@sixthshift/design-system/utils";
+import * as React from "react";
 import ReactMarkdown from "react-markdown";
 
 export type MarkdownProps = {
@@ -9,8 +10,25 @@ export type MarkdownProps = {
   className?: string;
 };
 
-export const Markdown = ({ children, className }: MarkdownProps) => (
-  <div className={cn("flex flex-col", className)}>
+/**
+ * Renders a markdown string through the design system's own typography
+ * components (`Heading`, `Body`, `Emphasis`) rather than raw HTML tags, so
+ * markdown content picks up the same type ramp as everything else.
+ *
+ * Built for short, chat/assistant-style content rather than full documents:
+ * it covers headings, paragraphs, emphasis, links, lists, and code, but
+ * heading levels are compressed — `#` renders as `Heading as="h3"`, `##` as
+ * `Heading as="h4"`, and `###` as inline `Emphasis` rather than a heading at
+ * all — and `h4`+ and tables aren't specially handled: there's no
+ * `remark-gfm`, so GFM table syntax doesn't render as a table. Raw HTML
+ * embedded in the source is not rendered.
+ *
+ * `react-markdown` is an optional peer dependency of this package — a
+ * consuming app that imports `Markdown` without installing it will fail at
+ * runtime.
+ */
+export const Markdown = React.forwardRef<HTMLDivElement, MarkdownProps>(({ children, className }, ref) => (
+  <div ref={ref} className={cn("flex flex-col", className)}>
     <ReactMarkdown
       components={{
         h1: ({ children }) => <Heading as="h3">{children}</Heading>,
@@ -36,5 +54,5 @@ export const Markdown = ({ children, className }: MarkdownProps) => (
       {children}
     </ReactMarkdown>
   </div>
-);
+));
 Markdown.displayName = "Markdown";