@gtivr4/a1-design-system-react 0.1.0 → 0.2.3

package/src/components/page-nav/PageNav.jsx

@@ -0,0 +1,110 @@
+import { useEffect, useRef, useState } from "react";
+import { Card } from "../card/Card.jsx";
+import "./page-nav.css";
+
+export function PageNav({
+  sections = [],
+  label = "On this page",
+  className = "",
+  ...props
+}) {
+  const [activeId, setActiveId] = useState(sections[0]?.id ?? null);
+  const [progress, setProgress] = useState(0);
+  const intersectingIds = useRef(new Set());
+
+  // Reading progress: track document scroll position
+  useEffect(() => {
+    function update() {
+      const el = document.documentElement;
+      const total = el.scrollHeight - el.clientHeight;
+      setProgress(total > 0 ? (el.scrollTop / total) * 100 : 0);
+    }
+    window.addEventListener("scroll", update, { passive: true });
+    update();
+    return () => window.removeEventListener("scroll", update);
+  }, []);
+
+  // Active section: observe each section element entering/leaving the viewport
+  useEffect(() => {
+    if (!sections.length) return;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((entry) => {
+          if (entry.isIntersecting) {
+            intersectingIds.current.add(entry.target.id);
+          } else {
+            intersectingIds.current.delete(entry.target.id);
+          }
+        });
+        // Always pick the first match in document order so the active item
+        // reflects what the reader is seeing at the top of the viewport.
+        const first = sections.find((s) => intersectingIds.current.has(s.id));
+        if (first) setActiveId(first.id);
+      },
+      // -8% top offset keeps the active section stable once it clears the
+      // header; -88% bottom offset means only the top 12% of the viewport
+      // is treated as "current".
+      { rootMargin: "-8% 0px -88% 0px", threshold: 0 }
+    );
+
+    sections.forEach(({ id }) => {
+      const el = document.getElementById(id);
+      if (el) observer.observe(el);
+    });
+
+    return () => {
+      observer.disconnect();
+      intersectingIds.current.clear();
+    };
+  }, [sections]);
+
+  function handleClick(id) {
+    // Immediately highlight the clicked item — don't wait for the observer
+    setActiveId(id);
+    const el = document.getElementById(id);
+    if (!el) return;
+    el.scrollIntoView({ behavior: "smooth", block: "start" });
+  }
+
+  return (
+    <>
+      <Card className={["a1-page-nav", className].filter(Boolean).join(" ")} {...props}>
+        {/* Progress bar — spans full card width above padding */}
+        <div className="a1-page-nav__progress" aria-hidden="true">
+          <div
+            className="a1-page-nav__progress-fill"
+            style={{ width: `${progress.toFixed(1)}%` }}
+          />
+        </div>
+
+        <nav className="a1-page-nav__inner" aria-label={label}>
+          <p className="a1-page-nav__heading">{label}</p>
+          <ul className="a1-page-nav__list" role="list">
+            {sections.map(({ id, label: itemLabel, level = 1 }) => (
+              <li key={id} className="a1-page-nav__item">
+                <button
+                  type="button"
+                  className={[
+                    "a1-page-nav__link",
+                    level === 2 && "a1-page-nav__link--l2",
+                    activeId === id && "a1-page-nav__link--active",
+                  ]
+                    .filter(Boolean)
+                    .join(" ")}
+                  aria-current={activeId === id ? "location" : undefined}
+                  onClick={() => handleClick(id)}
+                >
+                  {itemLabel}
+                </button>
+              </li>
+            ))}
+          </ul>
+        </nav>
+      </Card>
+
+      {/* Reserves space for the fixed pill nav on mobile so content isn't hidden beneath it */}
+      <div className="a1-page-nav__spacer" aria-hidden="true" />
+    </>
+  );
+}

package/src/components/page-nav/page-nav.css

@@ -0,0 +1,167 @@
+/* ═══════════════════════════════════════════════════════════════════════════
+   PageNav — in-page navigation with reading progress bar
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+/* ── Card shell override ─────────────────────────────────────────────────── */
+
+.a1-page-nav.a1-card {
+  padding: 0;
+  overflow: hidden; /* clip progress bar to card border-radius */
+}
+
+/* ── Progress bar ────────────────────────────────────────────────────────── */
+
+.a1-page-nav__progress {
+  height: 3px;
+  background: var(--semantic-color-border-subtle);
+}
+
+.a1-page-nav__progress-fill {
+  height: 100%;
+  background: var(--semantic-color-action-background);
+  min-width: 0;
+  transition: width 80ms linear;
+}
+
+/* ── Inner layout ────────────────────────────────────────────────────────── */
+
+.a1-page-nav__inner {
+  padding: var(--base-spacing-16);
+}
+
+.a1-page-nav__heading {
+  margin: 0 0 var(--base-spacing-12) 0;
+  font-family: var(--component-paragraph-font-family);
+  font-size: var(--semantic-font-size-body-xs);
+  font-weight: 600;
+  color: var(--semantic-color-text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  line-height: 1;
+}
+
+.a1-page-nav__list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--base-spacing-2);
+}
+
+/* ── Nav links ───────────────────────────────────────────────────────────── */
+
+.a1-page-nav__link {
+  display: block;
+  width: 100%;
+  text-align: start;
+  padding: var(--base-spacing-6) var(--base-spacing-8);
+  border: none;
+  border-radius: var(--base-radius-md);
+  background: transparent;
+  cursor: pointer;
+  font-family: var(--component-paragraph-font-family);
+  font-size: var(--semantic-font-size-body-sm);
+  font-weight: 400;
+  color: var(--semantic-color-text-muted);
+  line-height: 1.4;
+  transition:
+    color var(--semantic-motion-duration-fast) var(--semantic-motion-easing-standard),
+    background var(--semantic-motion-duration-fast) var(--semantic-motion-easing-standard);
+}
+
+.a1-page-nav__link:hover {
+  color: var(--semantic-color-text-default);
+  background: var(--semantic-color-surface-raised);
+}
+
+.a1-page-nav__link:focus-visible {
+  outline: 2px solid var(--semantic-color-action-background);
+  outline-offset: -1px;
+}
+
+.a1-page-nav__link--active {
+  color: var(--semantic-color-action-background);
+  font-weight: 500;
+  background: var(--semantic-color-surface-panel);
+}
+
+/* Level-2 sub-items (indented, smaller) */
+.a1-page-nav__link--l2 {
+  padding-inline-start: var(--base-spacing-20);
+  font-size: var(--semantic-font-size-body-xs);
+}
+
+/* ── Spacer: hidden on desktop, used only when nav is fixed on mobile ──────── */
+
+.a1-page-nav__spacer {
+  display: none;
+}
+
+/* ── Responsive — fixed pill bar at top of viewport ─────────────────────── */
+/* The card lifts out of the aside and pins to the top of the screen.         */
+/* A spacer div below it reserves the equivalent height in the flow.          */
+
+@media (max-width: 768px) {
+  .a1-page-nav.a1-card {
+    position: fixed;
+    top: 0;
+    left: 0;
+    right: 0;
+    z-index: 200;
+    border-radius: 0;
+    border-inline: none;
+    border-block-start: none;
+    /* Crisp shadow to separate from page content scrolling beneath */
+    box-shadow: 0 1px 8px rgba(0, 0, 0, 0.08);
+  }
+
+  /* Spacer height = progress bar (3px) + inner padding (8+8px) + pill row (~35px) */
+  .a1-page-nav__spacer {
+    display: block;
+    height: 54px;
+  }
+
+  .a1-page-nav__heading {
+    display: none;
+  }
+
+  .a1-page-nav__inner {
+    padding: var(--base-spacing-8) var(--base-spacing-16);
+  }
+
+  .a1-page-nav__list {
+    flex-direction: row;
+    gap: var(--base-spacing-4);
+    overflow-x: auto;
+    scrollbar-width: none;
+    -webkit-overflow-scrolling: touch;
+    padding-block: var(--base-spacing-4);
+  }
+
+  .a1-page-nav__list::-webkit-scrollbar {
+    display: none;
+  }
+
+  .a1-page-nav__item {
+    flex-shrink: 0;
+  }
+
+  .a1-page-nav__link {
+    white-space: nowrap;
+    border-radius: 9999px;
+    border: 1px solid var(--semantic-color-border-subtle);
+    padding: var(--base-spacing-4) var(--base-spacing-12);
+    font-size: var(--semantic-font-size-body-xs);
+  }
+
+  .a1-page-nav__link--l2 {
+    padding-inline-start: var(--base-spacing-12);
+  }
+
+  .a1-page-nav__link--active {
+    background: var(--semantic-color-action-background);
+    color: #fff;
+    border-color: var(--semantic-color-action-background);
+  }
+}

package/src/components/paragraph/Paragraph.jsx

@@ -2,25 +2,58 @@ import "./paragraph.css";
 
 const sizes = ["xs", "sm", "md", "lg", "xl"];
 const colors = ["default", "muted"];
+const breakpoints = ["xs", "sm", "md", "lg", "xl"];
+const textWraps = ["balance"];
+const aligns = ["left", "center", "right"];
+
+function isResponsiveSize(size) {
+  return size && typeof size === "object" && !Array.isArray(size);
+}
+
+function resolveBaseSize(size) {
+  if (!isResponsiveSize(size)) return sizes.includes(size) ? size : "md";
+  return sizes.includes(size.xs) ? size.xs : "md";
+}
+
+function getResponsiveSizeStyle(size) {
+  if (!isResponsiveSize(size)) return {};
+  return breakpoints.slice(1).reduce((style, bp) => {
+    if (sizes.includes(size[bp])) {
+      style[`--a1-paragraph-size-${bp}`] = `var(--semantic-font-size-body-${size[bp]})`;
+    }
+    return style;
+  }, {});
+}
 
 export function Paragraph({
   as: Component = "p",
   size = "md",
   color = "default",
+  textWrap,
+  align,
   className = "",
+  style,
   ...props
 }) {
-  const resolvedSize = sizes.includes(size) ? size : "md";
+  const resolvedSize = resolveBaseSize(size);
   const resolvedColor = colors.includes(color) ? color : "default";
+  const resolvedTextWrap = textWraps.includes(textWrap) ? textWrap : null;
+  const resolvedAlign = aligns.includes(align) ? align : null;
+  const responsiveStyle = getResponsiveSizeStyle(size);
+  const resolvedStyle = Object.keys(responsiveStyle).length
+    ? { ...responsiveStyle, ...style }
+    : style;
 
   const classes = [
     "a1-paragraph",
     `a1-paragraph--${resolvedSize}`,
     resolvedColor !== "default" && `a1-paragraph--${resolvedColor}`,
+    resolvedTextWrap && `a1-paragraph--wrap-${resolvedTextWrap}`,
+    resolvedAlign && `a1-paragraph--align-${resolvedAlign}`,
     className
   ]
     .filter(Boolean)
     .join(" ");
 
-  return <Component className={classes} {...props} />;
+  return <Component className={classes} style={resolvedStyle} {...props} />;
 }

package/src/components/paragraph/paragraph.css

@@ -1,12 +1,36 @@
 .a1-paragraph {
   margin: 0;
   font-family: var(--component-paragraph-font-family);
-  font-size: var(--a1-paragraph-size);
+  font-size: var(--a1-paragraph-responsive-size, var(--a1-paragraph-size));
   font-weight: var(--component-paragraph-font-weight);
   line-height: var(--component-paragraph-font-line-height);
   color: var(--a1-paragraph-color, var(--semantic-color-text-default));
 }
 
+@media (--bp-sm-up) {
+  .a1-paragraph {
+    --a1-paragraph-responsive-size: var(--a1-paragraph-size-sm, var(--a1-paragraph-size));
+  }
+}
+
+@media (--bp-md-up) {
+  .a1-paragraph {
+    --a1-paragraph-responsive-size: var(--a1-paragraph-size-md, var(--a1-paragraph-size-sm, var(--a1-paragraph-size)));
+  }
+}
+
+@media (--bp-lg-up) {
+  .a1-paragraph {
+    --a1-paragraph-responsive-size: var(--a1-paragraph-size-lg, var(--a1-paragraph-size-md, var(--a1-paragraph-size-sm, var(--a1-paragraph-size))));
+  }
+}
+
+@media (--bp-xl) {
+  .a1-paragraph {
+    --a1-paragraph-responsive-size: var(--a1-paragraph-size-xl, var(--a1-paragraph-size-lg, var(--a1-paragraph-size-md, var(--a1-paragraph-size-sm, var(--a1-paragraph-size)))));
+  }
+}
+
 .a1-paragraph--xs { --a1-paragraph-size: var(--semantic-font-size-body-xs); }
 .a1-paragraph--sm { --a1-paragraph-size: var(--semantic-font-size-body-sm); }
 .a1-paragraph--md { --a1-paragraph-size: var(--semantic-font-size-body-md); }
@@ -14,3 +38,16 @@
 .a1-paragraph--xl { --a1-paragraph-size: var(--semantic-font-size-body-xl); }
 
 .a1-paragraph--muted { --a1-paragraph-color: var(--semantic-color-text-muted); }
+
+/* Text wrap */
+.a1-paragraph--wrap-balance { text-wrap: balance; }
+
+/* Alignment */
+.a1-paragraph--align-left   { text-align: start;  }
+.a1-paragraph--align-center { text-align: center; }
+.a1-paragraph--align-right  { text-align: end;    }
+
+.a1-paragraph + .a1-paragraph,
+.a1-paragraph + .a1-heading {
+  margin-top: 1.5em;
+}

package/src/components/radio-group/RadioGroup.jsx

@@ -0,0 +1,121 @@
+import { useId, useState, useContext } from "react";
+import { useLabel } from "../labels/Labels.jsx";
+import { MessageBadge } from "../message/Message.jsx";
+import { FieldsetContext } from "../fieldset/FieldsetContext.js";
+import "./radio-group.css";
+
+const SIZES = ["comfortable", "default", "compact"];
+
+export function RadioGroup({
+  label,
+  hint,
+  error,
+  size,
+  required     = false,
+  disabled     = false,
+  inline       = false,
+  name,
+  options      = [],
+  value,
+  defaultValue = null,
+  onChange,
+  id: providedId,
+  className    = "",
+  ...props
+}) {
+  const ctx    = useContext(FieldsetContext);
+  const autoId = useId();
+  const id     = providedId ?? autoId;
+  const hintId  = `${id}-hint`;
+  const errorId = `${id}-error`;
+
+  const resolvedSize = SIZES.includes(size) ? size : (ctx?.size ?? "default");
+
+  const [internalValue, setInternalValue] = useState(defaultValue);
+  // value === undefined → uncontrolled; null → controlled with nothing selected
+  const currentValue = value !== undefined ? value : internalValue;
+
+  function handleChange(optionValue) {
+    if (value === undefined) setInternalValue(optionValue);
+    onChange?.(optionValue);
+  }
+
+  const classes = [
+    "a1-radio-group",
+    `a1-radio-group--${resolvedSize}`,
+    inline   && "a1-radio-group--inline",
+    error    && "a1-radio-group--error",
+    required && "a1-radio-group--required",
+    disabled && "a1-radio-group--disabled",
+    className,
+  ].filter(Boolean).join(" ");
+
+  const describedBy = [error ? errorId : hint ? hintId : null]
+    .filter(Boolean).join(" ") || undefined;
+
+  const requiredText = useLabel("field.required", "Required");
+
+  // Fall back to the group id so all radios share a name and behave as a group
+  const groupName = name ?? id;
+
+  return (
+    <fieldset className={classes} aria-describedby={describedBy} {...props}>
+      {label && (
+        <legend className="a1-radio-group__legend">
+          <span className="a1-radio-group__legend-inner">
+            {label}
+            {required && resolvedSize === "comfortable" ? (
+              <MessageBadge status="info" subtle>{requiredText}</MessageBadge>
+            ) : required ? (
+              <span className="a1-field__asterisk" aria-hidden="true"> *</span>
+            ) : null}
+          </span>
+        </legend>
+      )}
+      {hint && !error && (
+        <p className="a1-radio-group__message a1-radio-group__message--hint" id={hintId}>
+          {hint}
+        </p>
+      )}
+      <div className="a1-radio-group__items">
+        {options.map((option) => {
+          const isChecked  = currentValue === option.value;
+          const isDisabled = disabled || option.disabled;
+          const itemId     = `${id}-${option.value}`;
+
+          return (
+            <label
+              key={option.value}
+              className={[
+                "a1-radio-item",
+                isDisabled && "a1-radio-item--disabled",
+              ].filter(Boolean).join(" ")}
+            >
+              <input
+                type="radio"
+                id={itemId}
+                className="a1-radio-item__input"
+                name={groupName}
+                value={option.value}
+                checked={isChecked}
+                disabled={isDisabled}
+                onChange={() => handleChange(option.value)}
+              />
+              <span className="a1-radio-item__content">
+                <span className="a1-radio-item__label">{option.label}</span>
+                {option.hint && (
+                  <span className="a1-radio-item__hint">{option.hint}</span>
+                )}
+              </span>
+            </label>
+          );
+        })}
+      </div>
+      {error && (
+        <p className="a1-radio-group__message a1-radio-group__message--error" id={errorId} role="alert">
+          {error}
+        </p>
+      )}
+    </fieldset>
+  );
+}