@gtivr4/a1-design-system-react 0.4.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtivr4/a1-design-system-react",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "React components for the A1 token-driven design system.",
   "type": "module",
   "main": "./src/index.js",
@@ -17,6 +17,7 @@
     "README.md",
     "guidelines/**/*.md",
     "src/**/*.css",
+    "src/**/*.d.ts",
     "src/**/*.jsx",
     "src/index.js",
     "!src/**/*.stories.jsx",

package/src/components/accordion/Accordion.d.ts

@@ -0,0 +1,20 @@
+import * as React from "react";
+
+export interface AccordionProps {
+  /** Trigger label text */
+  label: string;
+  /** Controlled open state */
+  open?: boolean;
+  /** Initial open state (uncontrolled). Default: false */
+  defaultOpen?: boolean;
+  /** Called with the next boolean when the trigger is clicked */
+  onChange?: (open: boolean) => void;
+  /** Size — affects trigger text size and padding. Default: "md" */
+  size?: "sm" | "md" | "lg";
+  /** Prevent the accordion from being toggled. Default: false */
+  disabled?: boolean;
+  className?: string;
+  children?: React.ReactNode;
+}
+
+export declare function Accordion(props: AccordionProps): React.ReactElement;

package/src/components/banner/Banner.d.ts

@@ -0,0 +1,19 @@
+import * as React from "react";
+
+export interface BannerProps {
+  /** Layout style. "inline" sits within content; "system" spans full width. Default: "inline" */
+  variant?: "inline" | "system";
+  /** Semantic status colour. Default: "neutral" */
+  status?: "neutral" | "info" | "success" | "warn" | "error";
+  /** Bold title text shown before the body */
+  title?: string;
+  /** Override the default status icon with any Material Symbols name */
+  icon?: string;
+  /** Action element (e.g. a Button) rendered at the trailing end */
+  action?: React.ReactNode;
+  /** Called when the dismiss button is clicked. Omit to hide the dismiss button. */
+  onDismiss?: () => void;
+  children?: React.ReactNode;
+}
+
+export declare function Banner(props: BannerProps): React.ReactElement;

package/src/components/bleed/Bleed.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+
+type SpacingToken = 1 | 2 | 4 | 6 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 64 | 96 | 128;
+
+export interface BleedProps extends React.HTMLAttributes<HTMLElement> {
+  /** Underlying element. Default: "div" */
+  as?: React.ElementType;
+  /** Base bleed amount applied to all axes when no axis-specific value is set. Default: 16 */
+  space?: SpacingToken | "none";
+  /** Block-axis (top/bottom) bleed override. Default: "none" */
+  block?: SpacingToken | "none";
+  /** Inline-axis (left/right) bleed override. Falls back to `space`. */
+  inline?: SpacingToken;
+  children?: React.ReactNode;
+}
+
+export declare function Bleed(props: BleedProps): React.ReactElement;

package/src/components/blockquote/Blockquote.d.ts

@@ -0,0 +1,23 @@
+import * as React from "react";
+
+export interface BlockquoteProps extends React.HTMLAttributes<HTMLElement> {
+  /**
+   * Visual style variant. Default: "border"
+   *
+   * border  — left accent border, subtle background
+   * filled  — filled neutral surface
+   * feature — large centered text with accent bar, for pullquotes
+   * minimal — no decoration, plain text
+   * accent  — filled action-colour background with inverse text
+   * pull    — centred editorial with curly quotes
+   * ruled   — top + bottom horizontal rules, centred
+   */
+  variant?: "border" | "filled" | "feature" | "minimal" | "accent" | "pull" | "ruled";
+  /** Attribution text rendered as a `<figcaption>` */
+  cite?: string;
+  /** URL that the cite text links to */
+  citeUrl?: string;
+  children?: React.ReactNode;
+}
+
+export declare function Blockquote(props: BlockquoteProps): React.ReactElement;

package/src/components/breadcrumb/Breadcrumb.d.ts

@@ -0,0 +1,22 @@
+import * as React from "react";
+
+export interface BreadcrumbItem {
+  label: string;
+  href?: string;
+  onClick?: () => void;
+}
+
+export interface BreadcrumbProps extends React.HTMLAttributes<HTMLElement> {
+  /**
+   * Ordered list of breadcrumb items.
+   * The last item is treated as the current page (non-interactive).
+   * All previous items render as links or buttons.
+   */
+  items?: BreadcrumbItem[];
+  /**
+   * Label for the back link shown in narrow containers. Defaults to "Back".
+   */
+  backLabel?: string;
+}
+
+export declare function Breadcrumb(props: BreadcrumbProps): React.ReactElement;

package/src/components/button/Button.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  /** Underlying element or component to render. Default: "button" */
+  as?: React.ElementType;
+  /** Visual style. Default: "primary" */
+  variant?: "primary" | "secondary" | "tertiary" | "destructive" | "success";
+  /** Size. Default: "md" */
+  size?: "sm" | "md" | "lg";
+  /** Material Symbols icon name to show alongside the label */
+  icon?: string;
+  /** Whether the icon appears before or after the label. Default: "start" */
+  iconPosition?: "start" | "end";
+  children?: React.ReactNode;
+}
+
+export declare function Button(props: ButtonProps): React.ReactElement;

package/src/components/button-container/ButtonContainer.d.ts

@@ -0,0 +1,11 @@
+import * as React from "react";
+
+export interface ButtonContainerProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Horizontal alignment of buttons. Default: "start" */
+  align?: "start" | "center" | "end";
+  /** Default size passed to child Button elements that do not set their own size. */
+  size?: "sm" | "md" | "lg";
+  children?: React.ReactNode;
+}
+
+export declare function ButtonContainer(props: ButtonContainerProps): React.ReactElement;

package/src/components/calendar/Calendar.d.ts

@@ -0,0 +1,75 @@
+import * as React from "react";
+
+export interface CalendarMonth {
+  /** Full calendar year, e.g. 2026 */
+  year: number;
+  /** 1-indexed month: 1 = January … 12 = December */
+  month: number;
+}
+
+export interface CalendarProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Display mode.
+   * - `"scroll"` — renders all months vertically; parent container controls scrolling (default).
+   * - `"paginated"` — shows one month at a time with prev/next buttons and month/year selects.
+   */
+  variant?: "scroll" | "paginated";
+  /**
+   * Month to centre the scroll position on at mount (scroll) or the initial month shown (paginated).
+   * Accepts a `Date` object or `{ year, month }` (month is 1-indexed).
+   * Defaults to the current month.
+   */
+  initialMonth?: Date | CalendarMonth;
+  /**
+   * Total number of months to render. Only applies to `variant="scroll"`.
+   * Default: 13
+   */
+  monthsToShow?: number;
+  /**
+   * Highlight today's date with the action colour.
+   * Default: true
+   */
+  highlightToday?: boolean;
+  /**
+   * Apply a background tint to dates before today.
+   * Default: true
+   */
+  dimPast?: boolean;
+  /**
+   * Show a "Today" button in the paginated nav bar that jumps to the current month.
+   * Disabled automatically when already on the current month.
+   * Only applies to `variant="paginated"`.
+   * Default: false
+   */
+  todayButton?: boolean;
+  /**
+   * Enables date selection. When false (default), the calendar is display-only —
+   * no click handlers, hover effects, or keyboard interaction on day cells.
+   * Pass `selectedDate` or `defaultSelectedDate` alongside this prop.
+   * Default: false
+   */
+  selectable?: boolean;
+  /**
+   * The currently selected date (controlled). Pass `null` to clear the selection.
+   * Omit entirely to use uncontrolled mode with `defaultSelectedDate`.
+   */
+  selectedDate?: Date | null;
+  /**
+   * Initial selected date for uncontrolled mode. Ignored when `selectedDate` is provided.
+   */
+  defaultSelectedDate?: Date | null;
+  /**
+   * Called with the new `Date` whenever the user clicks a selectable day.
+   */
+  onChange?: (date: Date) => void;
+  /**
+   * Earliest selectable date (inclusive). Days before this are disabled.
+   */
+  minDate?: Date;
+  /**
+   * Latest selectable date (inclusive). Days after this are disabled.
+   */
+  maxDate?: Date;
+}
+
+export declare function Calendar(props: CalendarProps): React.ReactElement;

package/src/components/card/Card.d.ts

@@ -0,0 +1,31 @@
+import * as React from "react";
+
+export interface CardProps extends React.HTMLAttributes<HTMLElement> {
+  /** Underlying element. Default: "div" */
+  as?: React.ElementType;
+  /** Visual and semantic card variant. Navigation cards make the entire card interactive. Default: "default" */
+  variant?: "default" | "navigation";
+  /** Destination for navigation cards. When `variant="navigation"` is set, the card renders as an anchor by default. */
+  href?: string;
+  /** Remove the card border and background. Default: false */
+  bare?: boolean;
+  /** Material Symbols icon name. Used by `iconDisplay` to render the icon. */
+  icon?: string;
+  /**
+   * Controls how the icon is displayed.
+   * - `"default"` — small tokenised icon block above card content; scales with the card container (sm/md/lg).
+   * - `"hero"` — full-bleed coloured header area at the top of the card.
+   * - `"none"` — icon is not rendered.
+   * Default: `"default"` (when `icon` is provided).
+   */
+  iconDisplay?: "none" | "default" | "hero";
+  /**
+   * Background colour of the hero block when `iconDisplay="hero"`.
+   * Accepts a semantic colour role or any valid CSS colour value.
+   * Default: "action"
+   */
+  heroColor?: "action" | "neutral" | "info" | "success" | "warn" | "error" | (string & {});
+  children?: React.ReactNode;
+}
+
+export declare function Card(props: CardProps): React.ReactElement;

package/src/components/checkbox-group/CheckboxGroup.d.ts

@@ -0,0 +1,37 @@
+import * as React from "react";
+
+export interface CheckboxOption {
+  value: string;
+  label: string;
+  hint?: string;
+  disabled?: boolean;
+}
+
+export interface CheckboxGroupProps {
+  /** Group legend */
+  label?: string;
+  /** Helper text */
+  hint?: string;
+  /** Error message */
+  error?: string;
+  /** Size density. Inherits from parent `Fieldset` when omitted. Default: "default" */
+  size?: "comfortable" | "default" | "compact";
+  required?: boolean;
+  disabled?: boolean;
+  /** Render checkboxes side by side. Default: false */
+  inline?: boolean;
+  /** Input name attribute shared by all checkboxes */
+  name?: string;
+  /** Array of checkbox options */
+  options?: CheckboxOption[];
+  /** Controlled selected values */
+  value?: string[];
+  /** Default selected values (uncontrolled) */
+  defaultValue?: string[];
+  /** Called with the full updated array of selected values on change */
+  onChange?: (value: string[]) => void;
+  id?: string;
+  className?: string;
+}
+
+export declare function CheckboxGroup(props: CheckboxGroupProps): React.ReactElement;

package/src/components/choice-group/ChoiceGroup.d.ts

@@ -0,0 +1,68 @@
+import * as React from "react";
+
+export interface ChoiceGroupSection {
+  /** Section heading displayed above the section's tiles */
+  label: string;
+  /** Options in this section */
+  options: ChoiceOption[];
+}
+
+export interface ChoiceOption {
+  value: string;
+  label: string;
+  subtext?: string;
+  icon?: string;
+  disabled?: boolean;
+}
+
+export interface ChoiceGroupProps {
+  /** Group legend */
+  label?: string;
+  /** Helper text — hidden when error or success is present */
+  hint?: string;
+  /** Error message */
+  error?: string;
+  /** Success message — shown instead of hint when present, hidden if error is also present */
+  success?: string;
+  /** Tile size density — affects only padding and child element sizes. Default: "default" */
+  size?: "compact" | "default" | "comfortable";
+  /**
+   * Column count. Pass a number for a fixed count at all breakpoints, or a
+   * breakpoint object for responsive behaviour, e.g. `{ xs: 1, sm: 2, md: 3 }`.
+   * Omit (default) for automatic fill based on tile min-width.
+   */
+  columns?: number | Partial<Record<"xs" | "sm" | "md" | "lg" | "xl", number>>;
+  /**
+   * Allow multiple selections (checkbox semantics). When false, only one
+   * option may be selected at a time (radio semantics). Default: false
+   */
+  multiple?: boolean;
+  /**
+   * Place each tile's icon to the left of the label and subtext instead of
+   * above the content block. Has no effect on tiles with no icon. Default: false
+   */
+  inlineIcon?: boolean;
+  required?: boolean;
+  /** Input name attribute. Defaults to the group id. */
+  name?: string;
+  /** Flat list of options. Use sections instead for grouped options with headings. */
+  options?: ChoiceOption[];
+  /**
+   * Options divided into labeled sections with a divider between each group.
+   * When provided, options is ignored.
+   */
+  sections?: ChoiceGroupSection[];
+  /**
+   * Controlled value. String for single-select; string[] for multi-select.
+   * Pass undefined to use uncontrolled mode.
+   */
+  value?: string | string[] | null;
+  /** Default value for uncontrolled mode. Default: null / [] */
+  defaultValue?: string | string[] | null;
+  /** Called with the selected value (string or string[]) on change */
+  onChange?: (value: string | string[]) => void;
+  id?: string;
+  className?: string;
+}
+
+export declare function ChoiceGroup(props: ChoiceGroupProps): React.ReactElement;

package/src/components/circular-progress/CircularProgress.d.ts

@@ -0,0 +1,37 @@
+import * as React from "react";
+
+export interface CircularProgressProps {
+  /**
+   * Current value. Combined with max to compute the filled arc length.
+   * Ignored when indeterminate is true. Default: 0
+   */
+  value?: number;
+  /**
+   * Maximum value. Default: 100
+   */
+  max?: number;
+  /**
+   * Circle diameter. xs renders the smallest ring (no inner content — children
+   * are placed inline after the ring instead). Default: "md"
+   */
+  size?: "xs" | "sm" | "md" | "lg";
+  /**
+   * Shows a continuously rotating arc instead of a value-based fill.
+   * Removes aria-valuenow so assistive technology announces an indeterminate
+   * state. Default: false
+   */
+  indeterminate?: boolean;
+  /**
+   * Content centered inside the ring for sm / md / lg sizes.
+   * For xs, children are rendered inline after the ring.
+   * Always pass aria-label on the root element for an accessible name since
+   * this content receives aria-hidden="true".
+   */
+  children?: React.ReactNode;
+  /** Additional CSS class names applied to the root element. */
+  className?: string;
+}
+
+export declare function CircularProgress(
+  props: CircularProgressProps & React.HTMLAttributes<HTMLDivElement>
+): React.ReactElement;

package/src/components/circular-progress/CircularProgress.jsx

@@ -0,0 +1,85 @@
+import "./circular-progress.css";
+
+const SIZES = ["xs", "sm", "md", "lg"];
+
+// SVG uses a 100×100 viewBox with a 10-unit stroke so the ring scales
+// proportionally when the container size changes via CSS.
+const VIEWBOX = 100;
+const STROKE  = 10;
+const R       = (VIEWBOX - STROKE) / 2;       // 45
+const CIRC    = 2 * Math.PI * R;              // ≈ 282.74
+const ARC     = CIRC * 0.25;                  // 25% arc for indeterminate
+
+export function CircularProgress({
+  value         = 0,
+  max           = 100,
+  size          = "md",
+  indeterminate = false,
+  children,
+  className     = "",
+  ...props
+}) {
+  const resolvedSize = SIZES.includes(size) ? size : "md";
+  const hasInner     = resolvedSize !== "xs";
+
+  const pct        = Math.min(1, Math.max(0, max > 0 ? value / max : 0));
+  const dashArray  = indeterminate ? `${ARC} ${CIRC - ARC}` : CIRC;
+  const dashOffset = indeterminate ? 0 : CIRC * (1 - pct);
+
+  const classes = [
+    "a1-circular-progress",
+    resolvedSize !== "md" && `a1-circular-progress--${resolvedSize}`,
+    indeterminate && "a1-circular-progress--indeterminate",
+    className,
+  ].filter(Boolean).join(" ");
+
+  return (
+    <div
+      className={classes}
+      role="progressbar"
+      aria-valuenow={indeterminate ? undefined : value}
+      aria-valuemin={0}
+      aria-valuemax={max}
+      {...props}
+    >
+      <div className="a1-circular-progress__ring">
+        <svg
+          className="a1-circular-progress__svg"
+          viewBox={`0 0 ${VIEWBOX} ${VIEWBOX}`}
+          aria-hidden="true"
+        >
+          <circle
+            className="a1-circular-progress__track"
+            cx={VIEWBOX / 2}
+            cy={VIEWBOX / 2}
+            r={R}
+            fill="none"
+            strokeWidth={STROKE}
+          />
+          <circle
+            className="a1-circular-progress__fill"
+            cx={VIEWBOX / 2}
+            cy={VIEWBOX / 2}
+            r={R}
+            fill="none"
+            strokeWidth={STROKE}
+            strokeDasharray={dashArray}
+            strokeDashoffset={dashOffset}
+            strokeLinecap="round"
+            transform={`rotate(-90 ${VIEWBOX / 2} ${VIEWBOX / 2})`}
+          />
+        </svg>
+        {hasInner && children && (
+          <div className="a1-circular-progress__inner" aria-hidden="true">
+            {children}
+          </div>
+        )}
+      </div>
+      {!hasInner && children && (
+        <div className="a1-circular-progress__after">
+          {children}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/circular-progress/circular-progress.css

@@ -0,0 +1,104 @@
+/* ─── CircularProgress ───────────────────────────────────────────────────────── */
+
+.a1-circular-progress {
+  --a1-cp-size:    var(--component-circular-progress-md-size);
+  --a1-cp-track:   var(--component-circular-progress-track-color);
+  --a1-cp-fill:    var(--component-circular-progress-fill-color);
+  --a1-cp-gap:     var(--component-circular-progress-gap);
+
+  display: inline-flex;
+  align-items: center;
+  gap: var(--a1-cp-gap);
+}
+
+/* ─── Sizes ──────────────────────────────────────────────────────────────────── */
+
+.a1-circular-progress--xs { --a1-cp-size: var(--component-circular-progress-xs-size); }
+.a1-circular-progress--sm { --a1-cp-size: var(--component-circular-progress-sm-size); }
+/* md is the default — no modifier needed */
+.a1-circular-progress--lg { --a1-cp-size: var(--component-circular-progress-lg-size); }
+
+/* ─── Ring (SVG + optional inner content) ────────────────────────────────────── */
+
+.a1-circular-progress__ring {
+  flex-shrink: 0;
+  position: relative;
+  width:  var(--a1-cp-size);
+  height: var(--a1-cp-size);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+/* ─── SVG ────────────────────────────────────────────────────────────────────── */
+
+.a1-circular-progress__svg {
+  position: absolute;
+  inset: 0;
+  width:  100%;
+  height: 100%;
+  overflow: visible;
+}
+
+/* ─── Track ──────────────────────────────────────────────────────────────────── */
+
+.a1-circular-progress__track {
+  stroke: var(--a1-cp-track);
+}
+
+/* ─── Fill ───────────────────────────────────────────────────────────────────── */
+
+.a1-circular-progress__fill {
+  stroke: var(--a1-cp-fill);
+  transition: stroke-dashoffset var(--semantic-motion-duration-normal) var(--semantic-motion-easing-standard);
+}
+
+/* ─── Inner content (sm / md / lg) ──────────────────────────────────────────── */
+
+/* position: relative sits above the absolute SVG inside the flex __ring */
+.a1-circular-progress__inner {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  /* 80% keeps content within the inner edge of the 10 %-wide viewBox stroke */
+  max-width: 80%;
+  overflow: hidden;
+}
+
+/* ─── After content (xs only, rendered after the ring in DOM order) ─────────── */
+
+.a1-circular-progress__after {
+  font-family: var(--component-paragraph-font-family);
+  font-size: var(--semantic-font-size-body-sm);
+  color: var(--semantic-color-text-default);
+  line-height: var(--semantic-font-line-height-body);
+}
+
+/* ─── Indeterminate (spin) ───────────────────────────────────────────────────── */
+
+.a1-circular-progress--indeterminate .a1-circular-progress__svg {
+  animation: a1-cp-spin var(--component-circular-progress-indeterminate-duration) linear infinite;
+  transform-origin: center;
+}
+
+.a1-circular-progress--indeterminate .a1-circular-progress__fill {
+  transition: none;
+}
+
+@keyframes a1-cp-spin {
+  to { transform: rotate(360deg); }
+}
+
+/* ─── Reduced motion ─────────────────────────────────────────────────────────── */
+
+@media (prefers-reduced-motion: reduce) {
+  .a1-circular-progress--indeterminate .a1-circular-progress__svg {
+    animation: none;
+  }
+  .a1-circular-progress__fill {
+    transition: none;
+  }
+}

package/src/components/cluster/Cluster.d.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+
+type SpacingToken = 1 | 2 | 4 | 6 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 64 | 96 | 128;
+
+export interface ClusterProps extends React.HTMLAttributes<HTMLElement> {
+  /** Underlying element. Default: "div" */
+  as?: React.ElementType;
+  /** Gap applied to both row and column. Default: 8 */
+  gap?: SpacingToken;
+  /** Row gap override */
+  rowGap?: SpacingToken;
+  /** Column gap override */
+  columnGap?: SpacingToken;
+  /** Align-items. Default: "center" */
+  align?: "start" | "center" | "end" | "stretch" | "baseline";
+  /** Justify-content. Default: "start" */
+  justify?: "start" | "center" | "end" | "between" | "around" | "evenly";
+  children?: React.ReactNode;
+}
+
+export declare function Cluster(props: ClusterProps): React.ReactElement;

package/src/components/code/Code.d.ts

@@ -0,0 +1,15 @@
+import * as React from "react";
+
+export interface CodeProps extends React.HTMLAttributes<HTMLElement> {
+  /** Code presentation. Inline keeps minimal padding for prose; block renders a preformatted block. Default: "inline" */
+  variant?: "inline" | "block";
+  /** Allow long inline snippets or block code to wrap. Default: false */
+  wrapping?: boolean;
+  /** Show a small tertiary copy button at the bottom-left of the code block. Default: false */
+  copyCode?: boolean;
+  /** Text copied to the clipboard. Defaults to the rendered text children. */
+  copyText?: string;
+  children?: React.ReactNode;
+}
+
+export declare function Code(props: CodeProps): React.ReactElement;