@scalewing/react 1.14.0 → 1.15.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @scalewing/react
 
+## 1.15.0
+
+### Minor Changes
+
+- c0a1c95: `RadioGroup` options take a `description` (`docs/requests/teisoro-radio-group.md`, 2026-09-29 follow-up, Teisoro F-007-S05 task 1365). `RadioGroupOption.description?: ReactNode` is secondary text for that option: a muted caption at the row's inline end while it fits beside the label, and a second line under the label text when it does not or below `md` (new generated classes `sw-radio-group-body` and `sw-radio-group-option-description`). It is the radio's accessible description (`aria-describedby`), the radio's name stays its `label` text (`aria-labelledby` on the label text), and a press on it chooses the option. It may hold phrasing content such as a `Badge`, nothing interactive; a taller description grows the row downward and the label stays on the radio's line. `undefined`, `null`, booleans and `''` are no description; `0` and a component that renders nothing are one. An option with a description fills the group's width. Without `description` nothing changes. No new dependencies.
+
 ## 1.14.0
 
 ### Minor Changes

package/README.md

@@ -152,6 +152,30 @@ A `Button` that toggles something passes `aria-pressed`. The pressed button gets
 />
 ```
 
+An option's optional `description` (a `ReactNode`) is secondary text for that option alone, such as its history. It is a muted caption after the label, at the row's inline end, while the two fit on one line; when they do not, and always below the `md` breakpoint, it wraps to a second line that starts under the label text, not under the radio. The label keeps the first line. An option with a description fills the group's width. The description is the radio's accessible description (`aria-describedby` on that option's input), while its name stays the `label` text, and a press on it chooses the option as the label does. A disabled option fades its description with the rest of the option. It may hold phrasing content such as a small `Badge`, but nothing interactive, because it sits inside the option's `<label>`. A description taller than the label, such as a default-size `Badge`, grows the row downward; the label stays on the radio's line. `undefined`, `null`, `false`, `true` and `''` are no description. Any other node is one, including `0` and a component that renders nothing, so pass `undefined` when there is nothing to say. The group's own `description` still describes the whole group.
+
+```tsx
+<RadioGroup
+  legend="Sighting source"
+  onChange={setSource}
+  options={[
+    {
+      value: 'observer',
+      label: 'Field observer',
+      icon: <User />,
+      description: <Badge size="sm">Most recent</Badge>,
+    },
+    {
+      value: 'camera',
+      label: 'Camera trap',
+      icon: <Camera />,
+      description: '2 sightings · last Sep 13, 2026',
+    },
+  ]}
+  value={source}
+/>
+```
+
 `SegmentedControl` is one exclusive choice shown as a track of segments (`role="radiogroup"`), named by `aria-label` or `aria-labelledby`, with a controlled `value` and `onChange`; `variant="filled"` gives every segment the same width and fills the selection with the accent, and `disabled` keeps the choice visible but inert. `error` puts a message under the track (`sw-field-error`), links it to the group by `aria-describedby` and sets `aria-invalid` and a danger outline on the group (`Mark` in forced colors); as `Field`'s it is announced politely from a live region that is always there, never as an alert, and an empty string is no error. `required` sets `aria-required` on the group; since the control has no label of its own, the element that labels it shows the mark. The track sits in a `.sw-segmented-field` wrapper that holds the message and takes the track's place in the layout, so a `ref` still reaches the `radiogroup`. `error` is for a control in a `Stack` or block layout, where the track keeps its width and the message wraps under it. While it shows a message the field is at least 24ch wide, capped at its container, so a short compact track does not squeeze the message into a column. In an `Inline` the field therefore grows and the rest of the row moves, while the track keeps its labels' width.
 
 ```tsx

package/dist/components/RadioGroup.d.ts

@@ -1,15 +1,5 @@
-import { type ReactNode } from 'react';
-export type RadioGroupOption = {
-    value: string;
-    label: string;
-    disabled?: boolean;
-    /**
-     * A decorative glyph between the radio and the label, such as a person or
-     * a building for the kind of check. It is `aria-hidden` and drawn in the
-     * text color: the option's accessible name stays its `label` text.
-     */
-    icon?: ReactNode;
-};
+import { type RadioGroupOption } from './radio-group/RadioGroupOptionLabel.js';
+export type { RadioGroupOption };
 export type RadioGroupProps = {
     legend: string;
     value: string;

package/dist/components/RadioGroup.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId } from 'react';
 import { FieldErrorRegion } from './FieldErrorRegion.js';
+import { RadioGroupOptionLabel, } from './radio-group/RadioGroupOptionLabel.js';
 export function RadioGroup({ legend, value, onChange, options, required = false, disabled = false, description, error, }) {
     const name = useId();
     const descriptionId = useId();
@@ -19,10 +20,8 @@ export function RadioGroup({ legend, value, onChange, options, required = false,
         throw new RangeError('options must have unique values');
     if (value !== '' && !values.includes(value))
         throw new RangeError('value must match an option or be empty');
-    return (_jsxs("fieldset", { "aria-describedby": describedBy || undefined, "aria-invalid": Boolean(error), className: "sw-radio-group", disabled: disabled, children: [_jsx("legend", { className: "sw-radio-group-legend", children: legend }), description ? (_jsx("span", { className: "sw-radio-group-description", id: descriptionId, children: description })) : null, _jsx("span", { className: "sw-radio-group-options", children: options.map((option) => (_jsxs("label", { className: "sw-radio-group-option", children: [_jsxs("span", { className: "sw-radio-group-control", children: [_jsx("input", { checked: value === option.value, className: "sw-radio-group-input", disabled: option.disabled, name: name, onChange: (event) => {
-                                        if (!disabled &&
-                                            !option.disabled &&
-                                            event.currentTarget.checked)
-                                            onChange(option.value);
-                                    }, required: required, type: "radio", value: option.value }), _jsx("span", { "aria-hidden": "true", className: "sw-radio-group-mark" })] }), option.icon ? (_jsx("span", { "aria-hidden": "true", className: "sw-radio-group-icon", children: option.icon })) : null, _jsx("span", { className: "sw-radio-group-text", children: option.label })] }, option.value))) }), _jsx(FieldErrorRegion, { className: "sw-radio-group-error", id: errorId, message: error })] }));
+    return (_jsxs("fieldset", { "aria-describedby": describedBy || undefined, "aria-invalid": Boolean(error), className: "sw-radio-group", disabled: disabled, children: [_jsx("legend", { className: "sw-radio-group-legend", children: legend }), description ? (_jsx("span", { className: "sw-radio-group-description", id: descriptionId, children: description })) : null, _jsx("span", { className: "sw-radio-group-options", children: options.map((option) => (_jsx(RadioGroupOptionLabel, { checked: value === option.value, name: name, onSelect: () => {
+                        if (!disabled && !option.disabled)
+                            onChange(option.value);
+                    }, option: option, required: required }, option.value))) }), _jsx(FieldErrorRegion, { className: "sw-radio-group-error", id: errorId, message: error })] }));
 }

package/dist/components/radio-group/RadioGroupOptionLabel.d.ts

@@ -0,0 +1,39 @@
+import { type ReactNode } from 'react';
+export type RadioGroupOption = {
+    value: string;
+    label: string;
+    disabled?: boolean;
+    /**
+     * A decorative glyph between the radio and the label, such as a person or
+     * a building for the kind of check. It is `aria-hidden` and drawn in the
+     * text color: the option's accessible name stays its `label` text.
+     */
+    icon?: ReactNode;
+    /**
+     * Secondary text for this option, such as its history: a muted caption at
+     * the row's inline end, or on a second line under the label when the row
+     * is narrower than md or the two do not fit. It is the radio's accessible
+     * description (`aria-describedby`), never part of its name, and a press on
+     * it chooses the option. It may hold phrasing content such as a `Badge`,
+     * but nothing interactive: it sits inside the option's `<label>`.
+     * `undefined`, `null`, `false`, `true` and `''` are no description; any
+     * other node, `0` or a component that renders nothing included, is one,
+     * so pass `undefined` when there is nothing to say.
+     */
+    description?: ReactNode;
+};
+type RadioGroupOptionLabelProps = {
+    option: RadioGroupOption;
+    name: string;
+    checked: boolean;
+    required: boolean;
+    onSelect: () => void;
+};
+/**
+ * One option of a RadioGroup: the native radio and its mark, the optional
+ * glyph, and the label. With a description, the label and the description
+ * share a wrapping body, and the radio is named by the label text alone and
+ * described by the description.
+ */
+export declare function RadioGroupOptionLabel({ option, name, checked, required, onSelect, }: RadioGroupOptionLabelProps): import("react").JSX.Element;
+export {};

package/dist/components/radio-group/RadioGroupOptionLabel.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+/** Whether React renders something for a description: not nothing, a boolean or ''. */
+function hasDescription(description) {
+    return (description !== undefined &&
+        description !== null &&
+        typeof description !== 'boolean' &&
+        description !== '');
+}
+/**
+ * One option of a RadioGroup: the native radio and its mark, the optional
+ * glyph, and the label. With a description, the label and the description
+ * share a wrapping body, and the radio is named by the label text alone and
+ * described by the description.
+ */
+export function RadioGroupOptionLabel({ option, name, checked, required, onSelect, }) {
+    const id = useId();
+    const textId = `${id}-text`;
+    const descriptionId = `${id}-description`;
+    const described = hasDescription(option.description);
+    const text = (_jsx("span", { className: "sw-radio-group-text", id: described ? textId : undefined, children: option.label }));
+    return (_jsxs("label", { className: "sw-radio-group-option", children: [_jsxs("span", { className: "sw-radio-group-control", children: [_jsx("input", { "aria-describedby": described ? descriptionId : undefined, "aria-labelledby": described ? textId : undefined, checked: checked, className: "sw-radio-group-input", disabled: option.disabled, name: name, onChange: (event) => {
+                            if (event.currentTarget.checked)
+                                onSelect();
+                        }, required: required, type: "radio", value: option.value }), _jsx("span", { "aria-hidden": "true", className: "sw-radio-group-mark" })] }), option.icon ? (_jsx("span", { "aria-hidden": "true", className: "sw-radio-group-icon", children: option.icon })) : null, described ? (_jsxs("span", { className: "sw-radio-group-body", children: [text, _jsx("span", { className: "sw-radio-group-option-description", id: descriptionId, children: option.description })] })) : (text)] }));
+}

package/dist/css/css-radio-group.js

@@ -1,4 +1,5 @@
 import { typographyVariants } from '@scalewing/tokens';
+import { breakpointQuery } from './breakpoints.js';
 const label = typographyVariants.label;
 const caption = typographyVariants.caption;
 export function cssRadioGroupClasses() {
@@ -118,6 +119,8 @@ export function cssRadioGroupClasses() {
   min-width: 0;
 }
 
+${optionDescriptionRules()}
+
 .sw-radio-group-description,
 .sw-radio-group-error {
   font-family: var(--sw-font-sans);
@@ -141,6 +144,57 @@ export function cssRadioGroupClasses() {
   .sw-radio-group[aria-invalid='true'] .sw-radio-group-mark { border-color: CanvasText; }
 }`;
 }
+/**
+ * An option with a description fills the group's width. Its label and
+ * description share a wrapping body: the label grows, so the description sits
+ * at the row's inline end while both fit, and wraps to its own line, starting
+ * under the label text, when they do not. The label keeps the row first.
+ * Below md the description always takes its own line. The radio and glyph
+ * sit on the label's line, which starts where a one-line option centers it.
+ * Items align to the line's start, not a shared baseline, so a description
+ * taller than the label (a default-size Badge) grows the row downward and
+ * never pushes the label off the radio's line; a caption line is centred
+ * on the label's line box.
+ */
+function optionDescriptionRules() {
+    return `.sw-radio-group-option:has(> .sw-radio-group-body) {
+  align-items: flex-start;
+  box-sizing: border-box;
+  padding-block-start: calc((var(--sw-control-md-min-height) - var(--sw-space-5)) / 2);
+  width: 100%;
+}
+
+.sw-radio-group-option:has(> .sw-radio-group-body) > .sw-radio-group-icon {
+  min-height: var(--sw-space-5);
+}
+
+.sw-radio-group-body {
+  align-items: flex-start;
+  column-gap: var(--sw-space-3);
+  display: flex;
+  flex: 1 1 0;
+  flex-wrap: wrap;
+  min-width: 0;
+  padding-block-start: calc((var(--sw-space-5) - ${label.lineHeight}px) / 2);
+}
+
+.sw-radio-group-body > .sw-radio-group-text { flex: 1 1 auto; }
+
+.sw-radio-group-option-description {
+  color: var(--sw-color-muted);
+  flex: 0 1 auto;
+  font-family: var(--sw-font-sans);
+  font-size: ${caption.fontSize}px;
+  font-weight: ${caption.fontWeight};
+  line-height: ${caption.lineHeight}px;
+  margin-block-start: calc((${label.lineHeight}px - ${caption.lineHeight}px) / 2);
+  min-width: 0;
+}
+
+@media ${breakpointQuery('below', 'md')} {
+  .sw-radio-group-option-description { flex-basis: 100%; }
+}`;
+}
 export function radioGroupClassCatalog() {
     return [
         'sw-radio-group',
@@ -152,6 +206,8 @@ export function radioGroupClassCatalog() {
         'sw-radio-group-mark',
         'sw-radio-group-icon',
         'sw-radio-group-text',
+        'sw-radio-group-body',
+        'sw-radio-group-option-description',
         'sw-radio-group-description',
         'sw-radio-group-error',
     ];

package/dist/styles.css

@@ -1125,6 +1125,44 @@ body {
   min-width: 0;
 }
 
+.sw-radio-group-option:has(> .sw-radio-group-body) {
+  align-items: flex-start;
+  box-sizing: border-box;
+  padding-block-start: calc((var(--sw-control-md-min-height) - var(--sw-space-5)) / 2);
+  width: 100%;
+}
+
+.sw-radio-group-option:has(> .sw-radio-group-body) > .sw-radio-group-icon {
+  min-height: var(--sw-space-5);
+}
+
+.sw-radio-group-body {
+  align-items: flex-start;
+  column-gap: var(--sw-space-3);
+  display: flex;
+  flex: 1 1 0;
+  flex-wrap: wrap;
+  min-width: 0;
+  padding-block-start: calc((var(--sw-space-5) - 20px) / 2);
+}
+
+.sw-radio-group-body > .sw-radio-group-text { flex: 1 1 auto; }
+
+.sw-radio-group-option-description {
+  color: var(--sw-color-muted);
+  flex: 0 1 auto;
+  font-family: var(--sw-font-sans);
+  font-size: 13px;
+  font-weight: 400;
+  line-height: 18px;
+  margin-block-start: calc((20px - 18px) / 2);
+  min-width: 0;
+}
+
+@media not all and (min-width: 48rem) {
+  .sw-radio-group-option-description { flex-basis: 100%; }
+}
+
 .sw-radio-group-description,
 .sw-radio-group-error {
   font-family: var(--sw-font-sans);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalewing/react",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "Scalewing DOM components and package-owned CSS utilities.",
   "type": "module",
   "license": "MIT",