@helloimjolopez-pathway/pathway-components 0.6.2 → 0.7.0

package/components/radio/radio-demo.jsx

@@ -0,0 +1,175 @@
+/**
+ * Radio's standalone demo. Imports the real module, so there is nothing here
+ * that can fall out of step with the shipped component: see
+ * components/_demo/harness.jsx for why the newer demos are generated.
+ */
+import React, { useState } from "react";
+import { DemoChrome, mount } from "../_demo/harness.jsx";
+import { RadioGroup, Radio, RadioMark, SIZES, ORIENTATIONS } from "./radio.jsx";
+import { Button } from "../button/button.jsx";
+
+const U = (n) => `var(--semantic-layout-units-${n})`;
+const C = (n) => `var(--semantic-color-${n})`;
+const Y = (n) => `var(--semantic-type-${n})`;
+
+const label = { fontSize: Y("font-size-xs"), lineHeight: Y("line-height-xs-single"), color: C("foreground-static-neutral-subtle") };
+const card = {
+  background: C("fill-surface-elevated"), border: `1px solid ${C("stroke-static-neutral-base")}`,
+  borderRadius: U("cornerradius-large"), padding: U("padding-relaxed"),
+  display: "flex", flexDirection: "column", gap: U("gap-base"), minWidth: 0,
+};
+const h2 = { margin: 0, fontSize: Y("font-size-m"), lineHeight: Y("line-height-m-single"), fontWeight: Y("weight-semibold"), color: C("foreground-static-neutral-bold") };
+
+const TYPES = ["Unselected", "Selected", "Error Unselected", "Error Selected"];
+const STATES = ["Active", "Hover", "Focused", "Pressed", "Disabled"];
+
+function Pick({ list, value, onPick }) {
+  return (
+    <div style={{ display: "flex", gap: U("gap-xtight"), flexWrap: "wrap" }}>
+      {list.map((x) => <Button key={x} size="S" buttonStyle={x === value ? "Fill" : "Outlined"} type="Secondary" text={x} onClick={() => onPick(x)} />)}
+    </div>
+  );
+}
+
+function InContext() {
+  const [contact, setContact] = useState(null);
+  const [tried, setTried] = useState(false);
+  const error = tried && !contact;
+  return (
+    <section style={card}>
+      <h2 style={h2}>Set up a recurring gift</h2>
+      <span style={label}>Press Save gift without picking how to reach Ana. Tab into a group and use the arrow keys.</span>
+      <RadioGroup label="Frequency" helpText="The first gift is taken on the start date." defaultValue="monthly" name="frequency">
+        <Radio value="once" text="One time" />
+        <Radio value="weekly" text="Weekly" />
+        <Radio value="biweekly" text="Every two weeks" />
+        <Radio value="monthly" text="Monthly" />
+      </RadioGroup>
+      <RadioGroup label="Statement delivery" orientation="Horizontal" defaultValue="email" name="statement">
+        <Radio value="email" text="Email" />
+        <Radio value="mail" text="Mail" />
+        <Radio value="sms" text="Text message" disabled />
+      </RadioGroup>
+      <RadioGroup label="Best way to reach Ana" required name="contact" value={contact} onChange={setContact}
+        error={error} errorMessage="Choose how to reach Ana">
+        <Radio value="phone" text="Phone" />
+        <Radio value="email" text="Email" />
+        <Radio value="none" text="Don’t contact" />
+      </RadioGroup>
+      <div><Button text="Save gift" type="Primary" buttonStyle="Fill" onClick={() => setTried(true)} /></div>
+    </section>
+  );
+}
+
+function Playground() {
+  const [size, setSize] = useState("Base");
+  const [orientation, setOrientation] = useState("Vertical");
+  const [state, setState] = useState("Default");
+  const [required, setRequired] = useState("off");
+  return (
+    <section style={card}>
+      <h2 style={h2}>Playground</h2>
+      <div style={{ display: "flex", gap: U("gap-relaxed"), flexWrap: "wrap" }}>
+        <div><div style={label}>Size</div><Pick list={SIZES} value={size} onPick={setSize} /></div>
+        <div><div style={label}>Orientation</div><Pick list={ORIENTATIONS} value={orientation} onPick={setOrientation} /></div>
+        <div><div style={label}>State</div><Pick list={["Default", "Error", "Disabled"]} value={state} onPick={setState} /></div>
+        <div><div style={label}>Required</div><Pick list={["off", "on"]} value={required} onPick={setRequired} /></div>
+      </div>
+      <RadioGroup label="Gift type" size={size} orientation={orientation} required={required === "on"}
+        error={state === "Error"} errorMessage="Choose a gift type" disabled={state === "Disabled"}
+        helpText="You can change this later.">
+        <Radio value="one" text="One-time gift" />
+        <Radio value="recurring" text="Recurring gift" />
+        <Radio value="pledge" text="Pledge payment" />
+      </RadioGroup>
+    </section>
+  );
+}
+
+function Matrix() {
+  return (
+    <section style={card}>
+      <h2 style={h2}>Every Type, State and Size</h2>
+      <div style={{ overflowX: "auto" }}>
+        <table style={{ borderCollapse: "collapse", fontSize: Y("font-size-xs"), color: C("foreground-static-neutral-subtle") }}>
+          <thead><tr><th />{STATES.map((s) => <th key={s} style={{ padding: U("padding-xtight"), textAlign: "left", fontWeight: Y("weight-medium") }}>{s}</th>)}</tr></thead>
+          <tbody>
+            {SIZES.flatMap((size) => TYPES.map((t) => (
+              <tr key={size + t}>
+                <th style={{ padding: U("padding-xtight"), textAlign: "left", fontWeight: Y("weight-medium") }}>{t}, {size}</th>
+                {STATES.map((s) => (
+                  <td key={s} style={{ padding: U("padding-xtight") }}>
+                    <RadioGroup label={`${t}, ${s}, ${size}`} showLabel={false} size={size} error={t.startsWith("Error")}
+                      value={t.endsWith("Selected") && !t.endsWith("Unselected") ? "x" : null} onChange={() => {}}>
+                      <Radio value="x" text="Label" disabled={s === "Disabled"} forceState={["Hover", "Focused", "Pressed"].includes(s) ? s : undefined} />
+                    </RadioGroup>
+                  </td>
+                ))}
+              </tr>
+            )))}
+          </tbody>
+        </table>
+      </div>
+    </section>
+  );
+}
+
+function Content() {
+  return (
+    <section style={card}>
+      <h2 style={h2}>Long and translated labels</h2>
+      <div style={{ display: "flex", gap: U("gap-relaxed"), flexWrap: "wrap", alignItems: "flex-start" }}>
+        <RadioGroup label="Gift acknowledgement" defaultValue="letter">
+          <Radio value="email" text="Send a thank-you email" />
+          <Radio value="letter" text="Send a printed thank-you letter with the year-end giving statement, and copy the primary contact" />
+          <Radio value="none" text="Don’t acknowledge" />
+        </RadioGroup>
+        <RadioGroup label="Frecuencia" helpText="La primera donación se cobra en la fecha de inicio." defaultValue="m">
+          <Radio value="o" text="Una vez" />
+          <Radio value="w" text="Cada semana" />
+          <Radio value="b" text="Cada dos semanas" />
+          <Radio value="m" text="Cada mes" />
+        </RadioGroup>
+      </div>
+    </section>
+  );
+}
+
+function InMenu() {
+  const options = ["Date, newest first", "Amount, largest first", "Donor name, A to Z"];
+  const [picked, setPicked] = useState(options[0]);
+  return (
+    <section style={card}>
+      <h2 style={h2}>RadioMark inside a menu</h2>
+      <span style={label}>The Menu owns the menuitemradio role and draws RadioMark (Base) as its leading visual.</span>
+      <div role="menu" aria-label="Sort by" style={{ display: "flex", flexDirection: "column", width: 280,
+        borderRadius: U("cornerradius-base"), border: `1px solid ${C("stroke-static-neutral-base")}`, background: C("fill-surface-elevated") }}>
+        {options.map((o) => (
+          <div key={o} role="menuitemradio" aria-checked={picked === o} tabIndex={0}
+            onClick={() => setPicked(o)} onKeyDown={(e) => { if (e.key === " " || e.key === "Enter") { e.preventDefault(); setPicked(o); } }}
+            style={{ display: "flex", alignItems: "center", cursor: "pointer", fontSize: Y("font-size-s"), color: C("foreground-static-neutral-base") }}>
+            <RadioMark selected={picked === o} />{o}
+          </div>
+        ))}
+      </div>
+    </section>
+  );
+}
+
+function App() {
+  return (
+    <DemoChrome title="Radio"
+      blurb={"Pick exactly one option from a short list people can see all at once. Base on desktop, Large on touch. " +
+             "Tab lands on the picked option, arrows move and pick, Space picks. The focus ring shows for the keyboard only."}>
+      <div style={{ display: "flex", flexDirection: "column", gap: U("gap-relaxed") }}>
+        <InContext />
+        <Playground />
+        <Matrix />
+        <Content />
+        <InMenu />
+      </div>
+    </DemoChrome>
+  );
+}
+
+mount(<App />);

package/components/radio/radio.jsx

@@ -0,0 +1,322 @@
+/**
+ * Radio and RadioGroup, Pathway Design System
+ *
+ * Importable React component module. Source of truth for the Radio
+ * implementation; the standalone demo (radio.html), the Storybook stories and
+ * the <pathway-radio-group> web component all consume this.
+ *
+ * Pick exactly one option from a short list people can see all at once. Each
+ * option is a Radio (ring, dot when picked, label). A RadioGroup holds the
+ * options with one label, the Required asterisk, and help text or an error.
+ * Not for several choices (Checkbox), on or off (Switch), long lists (Input,
+ * Type Select) or filtering a view (Select (filter)).
+ *
+ * Built on React Aria Components RadioGroup and Radio, the same primitive as
+ * the Menu and the Input (WAI-ARIA radio group: Tab lands on the picked
+ * option, arrows move and pick, Space picks).
+ *
+ * Figma properties to props:
+ *   Radio Type (Unselected, Selected, Error *)  selection from the group value; Error from group `error`
+ *   Radio State (Active, Hover, Focused, Pressed, Disabled)  runtime; Disabled is `disabled`
+ *   Radio Size (Base, Large)                    `size` (on the group, or per Radio)
+ *   Radio Show Text, Text                       `showText`, `text` (or children)
+ *   RadioGroup Orientation (Vertical, Horizontal)  `orientation`
+ *   RadioGroup State (Default, Error, Disabled)    `error` + `errorMessage`, `disabled`
+ *   RadioGroup Label, Required, Show Label, Show Help Text  `label`, `required`, `showLabel`, `helpText`
+ *   RadioGroup Options slot                     children (Radio elements)
+ *
+ * Spec:  components/radio/radio-spec.md
+ * Figma: https://www.figma.com/design/3sw45aVcngFAmpbP6cfrXP/?node-id=40002974-83004 (Radio)
+ *        https://www.figma.com/design/3sw45aVcngFAmpbP6cfrXP/?node-id=40019964-292 (RadioGroup)
+ */
+
+import React, { createContext, useContext, useEffect } from "react";
+import { RadioGroup as RACRadioGroup, Radio as RACRadio, Label, Text } from "react-aria-components";
+
+// ─── TOKEN HELPERS ────────────────────────────────────────────────────────────
+// SC = semantic-color (themes/*.css), SL = semantic-layout-units (layout.css),
+// CL = contextual-layout-units (layout-contextual.css), ST = semantic-type
+// (type.css), M = motion (motion.css). Modeless names only.
+const SC = (p) => `var(--semantic-color-${p})`;
+const SL = (p) => `var(--semantic-layout-units-${p})`;
+const CL = (p) => `var(--contextual-layout-units-${p})`;
+const ST = (p) => `var(--semantic-type-${p})`;
+const M = (p) => `var(--motion-${p})`;
+
+export const SIZES = ["Base", "Large"];
+export const ORIENTATIONS = ["Vertical", "Horizontal"];
+
+// ─── COLOUR TOKENS ────────────────────────────────────────────────────────────
+// Per state, exactly as Figma binds them (spec §3).
+export const T = {
+  ring:            SC("stroke-action-secondary-rest"),
+  ringHover:       SC("stroke-action-secondary-hover"),
+  ringPressed:     SC("stroke-action-secondary-pressed"),
+  ringOn:          SC("stroke-action-primary-strong-rest"),
+  ringOnHover:     SC("stroke-action-primary-strong-hover"),
+  ringOnPressed:   SC("stroke-action-primary-strong-pressed"),
+  ringError:       SC("stroke-action-status-negative-rest"),
+  ringErrorHover:  SC("stroke-action-status-negative-hover"),
+  ringErrorPressed: SC("stroke-action-status-negative-pressed"),
+  ringDisabled:    SC("stroke-action-disabled"),
+  dot:             SC("fill-action-primary-strong-rest"),
+  dotHover:        SC("fill-action-primary-strong-hover"),
+  dotPressed:      SC("fill-action-primary-strong-pressed"),
+  dotError:        SC("fill-action-status-negative-strong-rest"),
+  dotErrorHover:   SC("fill-action-status-negative-strong-hover"),
+  dotErrorPressed: SC("fill-action-status-negative-strong-pressed"),
+  dotDisabled:     SC("fill-action-disabled"),
+  layerHover:      SC("fill-action-selection-hover"),
+  layerPressed:    SC("fill-action-selection-selected"),
+  focusFill:       SC("fill-surface-elevated"),
+  focusRing:       SC("stroke-focusring-base"),
+  label:           SC("foreground-static-neutral-base"),
+  labelDisabled:   SC("foreground-action-disabled"),
+  groupLabel:      SC("foreground-action-secondary-rest"),
+  groupLabelError: SC("foreground-action-status-negative-on-subtle-hover"),
+  required:        SC("foreground-static-negative-on-subtle"),
+  help:            SC("foreground-action-secondary-rest"),
+  helpError:       SC("foreground-static-negative-on-subtle"),
+  helpErrorIcon:   SC("fill-action-status-negative-strong-rest"),
+};
+
+// ─── LAYOUT ───────────────────────────────────────────────────────────────────
+// Ring, dot and the label max width are measurements, not tokens (CLAUDE.md §5).
+export const L = {
+  target:      SL("accessibility-touch-target-aa-width"),   // 44, the press area and the control column
+  targetH:     SL("accessibility-touch-target-aa-height"),
+  ringWidth:   CL("selection-controls-borderwidth"),        // 0.75 (G3)
+  radius:      SL("cornerradius-full"),
+  controlGap:  SL("gap-xxtight"),     // control column to label; label row to options; options to help text
+  requiredGap: SL("gap-xxxtight"),    // label to asterisk
+  rowGap:      SL("gap-base"),        // between options, Horizontal
+  labelEnd:    SL("padding-base"),    // after the option label
+  labelBlock:  { Base: SL("padding-tight"), Large: SL("padding-xtight") },  // Large: G2
+  helpGap:     SL("gap-tight"),       // help icon to text
+  helpIconTop: SL("borderwidth-base"),
+  ring:        { Base: 20, Large: 24 },
+  dot:         { Base: 10, Large: 12 },
+  labelMax:    480,
+  helpMax:     360,
+  helpIcon:    16,
+};
+
+// ─── TYPE ─────────────────────────────────────────────────────────────────────
+// Figma text styles bind the primitive tracking. Figma Letter Spacing/Wide is
+// 0.3 (semantic `spacious`), Standard is 0.1 (semantic `wide`), ExtraWide is
+// 0.6 (semantic `extraspacious`). Spec §3.7.
+export const TYPE = {
+  Base:  { fontSize: ST("font-size-s"), lineHeight: ST("line-height-s-single"), letterSpacing: ST("letter-spacing-spacious") },
+  Large: { fontSize: ST("font-size-r"), lineHeight: ST("line-height-r-single"), letterSpacing: ST("letter-spacing-wide") },
+  group: { fontSize: ST("font-size-s"), lineHeight: ST("line-height-s-single"), letterSpacing: ST("letter-spacing-spacious"), fontWeight: ST("weight-medium") },
+  help:  { fontSize: ST("font-size-xs"), lineHeight: ST("line-height-xs-single"), letterSpacing: ST("letter-spacing-extraspacious") },
+};
+
+const CSS = `
+.pw-radio-group{display:flex;flex-direction:column;align-items:flex-start;gap:${L.controlGap};min-width:0;
+  font-family:${ST("family-brand")},sans-serif}
+.pw-radio-group__label{display:inline-flex;gap:${L.requiredGap};color:${T.groupLabel};
+  font-size:${TYPE.group.fontSize};line-height:${TYPE.group.lineHeight};letter-spacing:${TYPE.group.letterSpacing};font-weight:${TYPE.group.fontWeight}}
+.pw-radio-group__required{color:${T.required}}
+.pw-radio-group[data-invalid] .pw-radio-group__label{color:${T.groupLabelError}}
+.pw-radio-group[data-disabled] .pw-radio-group__label,.pw-radio-group[data-disabled] .pw-radio-group__required{color:${T.labelDisabled}}
+.pw-radio-group__options{display:flex;flex-direction:column;max-width:100%}
+.pw-radio-group[data-orientation=horizontal] .pw-radio-group__options{flex-direction:row;flex-wrap:wrap;column-gap:${L.rowGap}}
+.pw-radio-group__help{display:flex;align-items:center;gap:${L.helpGap};max-width:${L.helpMax}px;color:${T.help};
+  font-size:${TYPE.help.fontSize};line-height:${TYPE.help.lineHeight};letter-spacing:${TYPE.help.letterSpacing};font-weight:${ST("weight-regular")}}
+.pw-radio-group__help[data-error]{color:${T.helpError};font-weight:${ST("weight-semibold")}}
+.pw-radio-group__help-icon{flex:none;display:inline-flex;padding-top:${L.helpIconTop};color:${T.helpErrorIcon}}
+.pw-radio-group__help-icon .material-symbols-rounded{font-family:"Material Symbols Rounded";font-size:${L.helpIcon}px;line-height:1;
+  font-variation-settings:'FILL' 1,'wght' 400,'GRAD' 0,'opsz' 24}
+
+.pw-radio{display:flex;align-items:flex-start;gap:${L.controlGap};box-sizing:border-box;width:fit-content;max-width:100%;
+  min-width:${L.target};min-height:${L.targetH};cursor:pointer;outline:none;-webkit-tap-highlight-color:transparent;
+  font-family:${ST("family-brand")},sans-serif}
+.pw-radio[data-disabled]{cursor:not-allowed}
+.pw-radio__control{flex:none;display:inline-grid;place-items:center;width:${L.target};height:${L.targetH};border-radius:${L.radius};
+  transition:background-color ${M("duration-2")} ${M("easing-standard")}}
+.pw-radio__mark{box-sizing:border-box;display:inline-grid;place-items:center;width:${L.ring.Base}px;height:${L.ring.Base}px;
+  border-radius:${L.radius};border:${L.ringWidth} solid ${T.ring};background:transparent;
+  transition:border-color ${M("duration-2")} ${M("easing-standard")},background-color ${M("duration-2")} ${M("easing-standard")}}
+.pw-radio__dot{width:${L.dot.Base}px;height:${L.dot.Base}px;border-radius:${L.radius};background:${T.dot};transform:scale(0);
+  transition:transform ${M("duration-3")} ${M("easing-burst")},background-color ${M("duration-2")} ${M("easing-standard")}}
+.pw-radio[data-size=Large] .pw-radio__mark{width:${L.ring.Large}px;height:${L.ring.Large}px}
+.pw-radio[data-size=Large] .pw-radio__dot{width:${L.dot.Large}px;height:${L.dot.Large}px}
+.pw-radio__label{box-sizing:border-box;min-width:0;max-width:${L.labelMax}px;overflow-wrap:anywhere;color:${T.label};
+  padding:${L.labelBlock.Base} ${L.labelEnd} ${L.labelBlock.Base} 0;
+  font-size:${TYPE.Base.fontSize};line-height:${TYPE.Base.lineHeight};letter-spacing:${TYPE.Base.letterSpacing};font-weight:${ST("weight-regular")}}
+.pw-radio[data-size=Large] .pw-radio__label{padding-block:${L.labelBlock.Large};
+  font-size:${TYPE.Large.fontSize};line-height:${TYPE.Large.lineHeight};letter-spacing:${TYPE.Large.letterSpacing}}
+
+.pw-radio[data-selected] .pw-radio__mark{border-color:${T.ringOn}}
+.pw-radio[data-selected] .pw-radio__dot{transform:scale(1)}
+
+.pw-radio:not([data-disabled]):is([data-hovered],[data-force=Hover]) .pw-radio__control{background:${T.layerHover}}
+.pw-radio:not([data-disabled]):is([data-pressed],[data-force=Pressed]) .pw-radio__control{background:${T.layerPressed}}
+.pw-radio:not([data-disabled]):is([data-hovered],[data-force=Hover]) .pw-radio__mark{border-color:${T.ringHover}}
+.pw-radio:not([data-disabled]):is([data-pressed],[data-force=Pressed]) .pw-radio__mark{border-color:${T.ringPressed}}
+.pw-radio[data-selected]:not([data-disabled]):is([data-hovered],[data-force=Hover]) .pw-radio__mark{border-color:${T.ringOnHover}}
+.pw-radio[data-selected]:not([data-disabled]):is([data-hovered],[data-force=Hover]) .pw-radio__dot{background:${T.dotHover}}
+.pw-radio[data-selected]:not([data-disabled]):is([data-pressed],[data-force=Pressed]) .pw-radio__mark{border-color:${T.ringOnPressed}}
+.pw-radio[data-selected]:not([data-disabled]):is([data-pressed],[data-force=Pressed]) .pw-radio__dot{background:${T.dotPressed}}
+
+.pw-radio[data-invalid] .pw-radio__mark{border-color:${T.ringError}}
+.pw-radio[data-invalid] .pw-radio__dot{background:${T.dotError}}
+.pw-radio[data-invalid]:not([data-disabled]):is([data-hovered],[data-force=Hover]) .pw-radio__mark{border-color:${T.ringErrorHover}}
+.pw-radio[data-invalid]:not([data-disabled]):is([data-hovered],[data-force=Hover]) .pw-radio__dot{background:${T.dotErrorHover}}
+.pw-radio[data-invalid]:not([data-disabled]):is([data-pressed],[data-force=Pressed]) .pw-radio__mark{border-color:${T.ringErrorPressed}}
+.pw-radio[data-invalid]:not([data-disabled]):is([data-pressed],[data-force=Pressed]) .pw-radio__dot{background:${T.dotErrorPressed}}
+
+.pw-radio[data-disabled] .pw-radio__mark{border-color:${T.ringDisabled}}
+.pw-radio[data-disabled] .pw-radio__dot{background:${T.dotDisabled}}
+.pw-radio[data-disabled] .pw-radio__label{color:${T.labelDisabled}}
+
+.pw-radio:is([data-focus-visible],[data-force=Focused]) .pw-radio__mark{background:${T.focusFill};
+  outline:${CL("focusring-width")} solid ${T.focusRing};outline-offset:${CL("focusring-offset")}}
+
+.pw-radio-mark{display:inline-grid;place-items:center;width:${L.target};height:${L.targetH};flex:none}
+
+@media (prefers-reduced-motion: reduce){.pw-radio__control,.pw-radio__mark,.pw-radio__dot{transition:none}}
+`;
+
+let injected = false;
+function useStyles() {
+  useEffect(() => {
+    if (injected || typeof document === "undefined" || document.getElementById("pw-radio-css")) { injected = true; return; }
+    const el = document.createElement("style");
+    el.id = "pw-radio-css";
+    el.textContent = CSS;
+    document.head.appendChild(el);
+    injected = true;
+  }, []);
+}
+
+const RadioGroupContext = createContext({ size: "Base" });
+
+// ─── RADIOGROUP ───────────────────────────────────────────────────────────────
+
+/**
+ * RadioGroup
+ *
+ * @param {string}   label          - Group label. Always required: it names the radiogroup
+ * @param {boolean}  showLabel      - Figma Show Label. false keeps the label as the accessible name only
+ * @param {boolean}  required       - Figma Required. Adds the asterisk and aria-required
+ * @param {string}   helpText       - Figma Show Help Text. Help text under the options
+ * @param {boolean}  error          - Figma State=Error. Every option takes its Error type
+ * @param {string}   errorMessage   - Replaces the help text while `error` is set. Says what to do
+ * @param {boolean}  disabled       - Figma State=Disabled
+ * @param {"Vertical"|"Horizontal"} orientation - Figma Orientation
+ * @param {"Base"|"Large"} size     - Radio Size for every option. Large on touch layouts
+ * @param {string}   value          - Controlled value
+ * @param {string}   defaultValue   - Uncontrolled starting value
+ * @param {function} onChange       - (value: string) => void
+ * @param {string}   name           - Form field name
+ */
+export function RadioGroup({
+  label,
+  showLabel = true,
+  required = false,
+  helpText,
+  error = false,
+  errorMessage,
+  disabled = false,
+  orientation = "Vertical",
+  size = "Base",
+  value,
+  defaultValue,
+  onChange,
+  name,
+  className = "",
+  children,
+  ...rest
+}) {
+  useStyles();
+  const showError = error && errorMessage;
+  return (
+    <RACRadioGroup
+      {...rest}
+      name={name}
+      value={value}
+      defaultValue={defaultValue}
+      onChange={onChange}
+      isInvalid={error}
+      isRequired={required}
+      isDisabled={disabled}
+      orientation={orientation === "Horizontal" ? "horizontal" : "vertical"}
+      aria-label={showLabel ? undefined : label}
+      data-size={size}
+      className={`pw-radio-group${className ? ` ${className}` : ""}`}
+    >
+      {showLabel && label && (
+        <Label className="pw-radio-group__label">
+          {label}
+          {required && <span className="pw-radio-group__required" aria-hidden="true">*</span>}
+        </Label>
+      )}
+      <RadioGroupContext.Provider value={{ size }}>
+        <div className="pw-radio-group__options">{children}</div>
+      </RadioGroupContext.Provider>
+      {showError ? (
+        <Text slot="errorMessage" className="pw-radio-group__help" data-error="">
+          <span className="pw-radio-group__help-icon" aria-hidden="true"><span className="material-symbols-rounded">error</span></span>
+          <span>{errorMessage}</span>
+        </Text>
+      ) : helpText ? (
+        <Text slot="description" className="pw-radio-group__help">{helpText}</Text>
+      ) : null}
+    </RACRadioGroup>
+  );
+}
+
+// ─── RADIOMARK ────────────────────────────────────────────────────────────────
+
+/**
+ * RadioMark: the drawn control alone (44 column, ring, dot), for a host that
+ * owns the radio role itself, such as a Menu item (PopoverMenu.Item.Leading
+ * Type=Radio). Never interactive on its own.
+ */
+export function RadioMark({ selected = false, error = false, disabled = false, size = "Base" }) {
+  useStyles();
+  return (
+    <span className="pw-radio pw-radio-mark" aria-hidden="true" data-size={size}
+      data-selected={selected || undefined} data-invalid={error || undefined} data-disabled={disabled || undefined}>
+      <span className="pw-radio__control"><span className="pw-radio__mark"><span className="pw-radio__dot" /></span></span>
+    </span>
+  );
+}
+
+// ─── RADIO ────────────────────────────────────────────────────────────────────
+
+/**
+ * Radio: one option. Must sit inside a RadioGroup.
+ *
+ * @param {string}   value        - The value the group takes when this is picked
+ * @param {string}   text         - Figma Text. The label (children work too)
+ * @param {boolean}  showText     - Figma Show Text. false needs `aria-label`
+ * @param {"Base"|"Large"} size   - Overrides the group's size
+ * @param {boolean}  disabled     - Figma State=Disabled for this option only
+ * @param {"Hover"|"Focused"|"Pressed"} forceState - Documentation only: hold a state for state matrices
+ */
+export function Radio({ value, text, children, showText = true, size, disabled = false, forceState, className = "", ...rest }) {
+  useStyles();
+  const group = useContext(RadioGroupContext);
+  const s = size || group.size || "Base";
+  const content = children ?? text;
+  return (
+    <RACRadio
+      {...rest}
+      value={value}
+      isDisabled={disabled}
+      data-size={s}
+      data-force={forceState}
+      className={`pw-radio${className ? ` ${className}` : ""}`}
+    >
+      <span className="pw-radio__control" aria-hidden="true">
+        <span className="pw-radio__mark"><span className="pw-radio__dot" /></span>
+      </span>
+      {showText && content != null && content !== "" && <span className="pw-radio__label">{content}</span>}
+    </RACRadio>
+  );
+}
+
+export default RadioGroup;