{ "version": "0.2.0-preview.1", "content_digest": "70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721", "status": "preview", "authority": { "repository": "cloakedinc/design", "path": "packages/design-system", "catalog": "packages/design-system/catalog.json", "status": "preview" }, "provenance": { "repo": "cloakedinc/automation", "commit": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "path": "packages/design-system", "imported_spec_status": "approved" }, "adaptations": [ { "id": "button-content-gap", "status": "preview", "description": "Use the specification's 4px content gap instead of the inherited 8px implementation gap." }, { "id": "keyboard-focus", "status": "preview", "description": "Add visible Button and Input keyboard focus and an overridable inset focus default for shared button resets, including FAQ cards and ListItem rows." }, { "id": "supporting-text-contrast", "status": "preview", "description": "Map light secondary text to the existing grey-04-strong primitive for readable helper text on white and cream." }, { "id": "danger-text-contrast", "status": "preview", "description": "Separate readable danger text/borders from destructive fills; preserve the primary danger-button fill and label pair." }, { "id": "preview-status", "status": "preview", "description": "Local components, specs and token adaptations await human sign-off; upstream approved status is provenance only." }, { "id": "motion-comparison-accessibility", "status": "preview", "description": "Preserve the original MotionShowcase comparisons while requiring explicit replay, responding to live reduced-motion changes, and keeping duration tracks usable on small screens." }, { "id": "list-item-ownership", "status": "preview", "description": "List owns listitem wrappers for its content rows, while section labels stay outside the row count and standalone rows retain their existing semantics." }, { "id": "card-delta-text-contrast", "status": "preview", "description": "Mix Card.Delta foregrounds from 60% existing tone solid and 40% primary text for readable contrast in both themes; preserve the four original tone fills." }, { "id": "carousel-keyboard-access", "status": "preview", "description": "Keep all native-scrolling carousel slide controls exposed to assistive technology and keyboard navigation; pause autoplay while focus is inside the carousel." } ], "id": "radiogroup", "name": "RadioGroup", "category": "Forms", "summary": "A controlled single-choice field that stacks labelled options as divider-separated selection rows.", "documentation": { "summary": "A controlled single-choice field that stacks labelled options as divider-separated selection rows.", "guidance": [ { "heading": "Overview", "body": "Manages a set of radios as one mutually-exclusive field — one `value`, labelled `options`, and\ngroup semantics (`role=\"radiogroup\"`). This is the control you reach for, not the bare `Radio`.\n\nOptions render as divider-separated `List.Item.Selection` rows with the control at the trailing\nedge, so a group reads as part of the surface it sits on. Rows are 80px with a `description` and\n64px without." }, { "heading": "When to use", "body": "Use `RadioGroup` for a single choice where every option should stay visible so seeing them all\naids the decision — best at 2–5 options. Pair it with `Field` for the label; only pass the\nstandalone aria props when used outside `Field`. Choosing between the neighbours:\n\n- The list is **long or space is tight**? Use `Select` — don't stack a dozen radios.\n- You need a **compact inline** 2–4 option switch (view/filter) rather than a labelled form field?\n Use `SegmentedControl`.\n- The user may pick **more than one** option? Use `Checkbox`." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.mdx", "status": "local-preview", "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification." }, "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "code": "import React from 'react';\nimport { cn } from '../../../utilities';\nimport type { HapticFeedback } from '../../../tokens/CdsHaptic';\nimport { ListItem } from '../../organization/ListItem/ListItem';\nimport { useFieldControl, type FieldControlProps } from '../../../hooks/FieldContext';\nimport styles from './RadioGroup.module.scss';\n\nexport interface RadioOption {\n value: string;\n label: string;\n /** Supporting copy shown beneath the label. */\n description?: string;\n /** Prevents this option from being selected. */\n disabled?: boolean;\n}\n\n/**\n * Props for `RadioGroup`. Selection is fully controlled — the group renders whatever\n * `value` says, so a change the app does not store back is dropped on the next render.\n */\nexport interface RadioGroupProps extends FieldControlProps {\n /** Value of the selected option; a value matching no option leaves the group unselected. */\n value: string;\n /** Options in display order. Dividers sit between rows, not after the last one. */\n options: RadioOption[];\n /** Called with the next value. Pressing the already-selected option does not call it. */\n onChange?: (value: string) => void;\n /** Prevents interaction with every option when true. */\n disabled?: boolean;\n /** Marks the group as required for assistive technology. */\n required?: boolean;\n /** Accessible name when no visible label is associated with the group. */\n ariaLabel?: string;\n /** Haptic feedback for value changes. Defaults to `true` (`selection`). */\n haptic?: HapticFeedback;\n className?: string;\n /** Test id for the group; each row derives `${testId}-${option.value}`. */\n testId?: string;\n}\n\n/**\n * Renders mutually exclusive choices as divider-separated selection rows. Options are\n * `List.Item.Selection` in single mode so the row treatment tracks the list surfaces.\n */\nexport function RadioGroup({\n value,\n options,\n onChange,\n disabled,\n required,\n ariaLabel,\n ariaDescribedBy,\n ariaLabelledBy,\n invalid,\n haptic = true,\n id,\n className,\n testId,\n}: RadioGroupProps) {\n // List.Item's semantic haptic is `light`; a radio wants `selection`, so resolve the\n // default here rather than letting the row's own default through.\n const optionHaptic = haptic === true ? 'selection' : haptic;\n const field = useFieldControl({ id, disabled, required, invalid, ariaDescribedBy, ariaLabelledBy });\n\n return (\n \n {options.map((option, index) => {\n const selected = value === option.value;\n\n return (\n !selected && onChange?.(option.value)}\n title={option.label}\n description={option.description}\n disabled={field.disabled || option.disabled}\n divider={index < options.length - 1}\n // Re-pressing the current option is a no-op, so it should not buzz either.\n haptic={selected ? false : optionHaptic}\n testId={testId ? `${testId}-${option.value}` : undefined}\n />\n );\n })}\n \n );\n}\n" }, "spec": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "RadioGroup", "status": "preview", "version": "3.0.0", "summary": "A controlled single-choice field that stacks labelled options as divider-separated selection rows." }, "parts": [ { "id": "group", "label": "Group", "description": "Owns the accessible radio-group name, validation, and required state." }, { "id": "option", "label": "Option row", "description": "Pressable full-width row carrying one option's copy and its selection control." }, { "id": "label", "label": "Option label", "description": "Names the option and provides the row's accessible name." }, { "id": "description", "label": "Option description", "description": "Optional supporting copy beneath the option label." }, { "id": "indicator", "label": "Selection indicator", "description": "Trailing control showing unselected or selected-dot state without duplicating semantics." }, { "id": "divider", "label": "Row divider", "description": "Hairline separating adjacent options; absent after the last option." } ], "allowedDesignChoices": { "variants": { "row": { "label": "Row", "description": "Each option is one full-width selection row on the list surface." } }, "sizes": {} }, "variants": [ { "id": "row", "label": "Row", "description": "Divider-separated single-choice rows with a trailing selection control.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [], "measurements": [ { "id": "row-min-height", "label": "Option row height", "kind": "at-least", "token": "--cds-size-80", "value": 80, "unit": "px", "appliesTo": [ "option", "description" ] }, { "id": "compact-row-min-height", "label": "Option row height without description", "kind": "at-least", "token": "--cds-size-64", "value": 64, "unit": "px", "appliesTo": [ "option" ] }, { "id": "row-inset", "label": "Option row inset", "kind": "exact", "token": "--cds-space-20", "value": 20, "unit": "px", "appliesTo": [ "option" ] }, { "id": "copy-to-control-gap", "label": "Copy-to-control gap", "kind": "exact", "token": "--cds-space-24", "value": 24, "unit": "px", "appliesTo": [ "option", "indicator" ] }, { "id": "indicator-diameter", "label": "Selection indicator diameter", "kind": "exact", "token": "--cds-size-32", "value": 32, "unit": "px", "appliesTo": [ "indicator" ] } ], "layout": { "alignment": "Copy fills the leading column and the selection control pins to the trailing edge, both vertically centered.", "flow": "Options stack full-width with a hairline between adjacent rows and none after the last.", "notes": [ "Keep option rows flush to the surface; do not wrap them in per-option cards or radii.", "Use Select when the choice list is too long to keep visible." ] }, "typographyAndColor": { "typography": [ { "label": "Option label", "description": "Use body text for the option name.", "token": "--cds-type-body-size" }, { "label": "Option description", "description": "Use body-small secondary text for supporting copy.", "token": "--cds-type-body-small-size" } ], "colors": [ { "label": "Row surface", "description": "Use the list row surface for every option, selected or not.", "token": "--cds-bg-surface" }, { "label": "Row divider", "description": "Use the shared divider hairline between adjacent options.", "token": "--cds-divider" }, { "label": "Selected indicator", "description": "Use the theme-aware bold fill for the chosen option's control.", "token": "--cds-bg-bold" }, { "label": "Option copy", "description": "Use primary and secondary text emphasis by copy hierarchy.", "token": "--cds-text-primary" } ] }, "states": [ { "id": "unselected", "label": "Unselected", "description": "Shows the neutral empty indicator with no row treatment change." }, { "id": "selected", "label": "Selected", "description": "Fills the trailing indicator and shows the dot; the row itself is unchanged." }, { "id": "option-disabled", "label": "Option disabled", "description": "Dims one row and blocks its press while leaving the rest selectable." }, { "id": "group-disabled", "label": "Group disabled", "description": "Dims and blocks every option in the group." }, { "id": "invalid", "label": "Invalid", "description": "Exposes group-level invalid and described-by relationships supplied by Field." } ], "behavior": [ { "label": "Single selection", "description": "Emit a new option value only when it differs from the controlled value." }, { "label": "Disabled options", "description": "Never emit changes for a disabled option or disabled group." }, { "label": "Row press target", "description": "Treat the whole row as the press target, not just the selection control." } ], "accessibility": [ { "label": "Group name", "description": "Associate a visible Field label or provide an accessible group name." }, { "label": "Option semantics", "description": "Expose each option as a radio whose accessible name is its label and whose description is announced when present." }, { "label": "Validation", "description": "Expose required, invalid, and described-by state on the group without duplicating it on decorative indicators." } ], "contentAdaptation": [ { "label": "Option count", "description": "Keep groups to a short visible set; use Select for long lists." }, { "label": "Descriptions", "description": "Use concise descriptions to clarify consequences, not repeat option labels; omitting them tightens the row." } ], "motionHaptics": { "motion": [ { "label": "Selection state", "description": "Change only the indicator fill and dot; option content must not move." } ], "haptics": [ { "label": "Selection feedback", "description": "Request the selection haptic after a new enabled value is chosen, and none when the current value is re-pressed." } ] }, "platformDifferences": [ { "platforms": [ "web" ], "description": "Web renders each option as a button with radio semantics rather than a native radio input; native platforms map the same option content to their radio accessibility controls.", "rationale": "The row is the press target on every platform, and the shared row treatment matters more here than native input chrome the design hides anyway." } ] }, "spec_source": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.spec.json", "guidance_source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.mdx", "code": "import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';\nimport { ComponentSpec } from '../../../../.storybook/blocks';\nimport * as Stories from './RadioGroup.stories';\nimport radioGroupSpec from './RadioGroup.spec.json';\n\n\n\n# RadioGroup\n\nManages a set of radios as one mutually-exclusive field — one `value`, labelled `options`, and\ngroup semantics (`role=\"radiogroup\"`). This is the control you reach for, not the bare `Radio`.\n\nOptions render as divider-separated `List.Item.Selection` rows with the control at the trailing\nedge, so a group reads as part of the surface it sits on. Rows are 80px with a `description` and\n64px without.\n\n\n\n## When to use\n\nUse `RadioGroup` for a single choice where every option should stay visible so seeing them all\naids the decision — best at 2–5 options. Pair it with `Field` for the label; only pass the\nstandalone aria props when used outside `Field`. Choosing between the neighbours:\n\n- The list is **long or space is tight**? Use `Select` — don't stack a dozen radios.\n- You need a **compact inline** 2–4 option switch (view/filter) rather than a labelled form field?\n Use `SegmentedControl`.\n- The user may pick **more than one** option? Use `Checkbox`.\n\n\n\n\n\n## Design Guidelines\n\n\n\n## Props\n\n\n" }, "props": [ { "name": "value", "type": "string", "declared_type": "string", "required": true, "description": "Value of the selected option; a value matching no option leaves the group unselected.", "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 23 } }, { "name": "options", "type": "RadioOption[]", "declared_type": "RadioOption[]", "required": true, "description": "Options in display order. Dividers sit between rows, not after the last one.", "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 25 } }, { "name": "onChange", "type": "((value: string) => void) | undefined", "declared_type": "(value: string) => void", "required": false, "description": "Called with the next value. Pressing the already-selected option does not call it.", "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 27 } }, { "name": "disabled", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Prevents interaction with every option when true.", "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 29 }, "values": [ false, true ], "values_complete": true }, { "name": "required", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Marks the group as required for assistive technology.", "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 31 }, "values": [ false, true ], "values_complete": true }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible name when no visible label is associated with the group.", "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 33 } }, { "name": "haptic", "type": "HapticFeedback | undefined", "declared_type": "HapticFeedback", "required": false, "description": "Haptic feedback for value changes. Defaults to `true` (`selection`).", "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 35 }, "values": [ "error", "heavy", "light", "medium", "selection", "success", "warning", false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 36 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Test id for the group; each row derives `${testId}-${option.value}`.", "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 38 } }, { "name": "id", "type": "string | undefined", "declared_type": "string", "required": false, "description": "DOM id the control renders, which the Field's label points at.", "source": { "path": "packages/design-system/src/hooks/FieldContext.ts", "line": 22 } }, { "name": "invalid", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Paints the invalid treatment and announces the control as invalid. A Field supplies\nthis from its own `error`; set it directly only for a control with no Field around it.", "source": { "path": "packages/design-system/src/hooks/FieldContext.ts", "line": 31 }, "values": [ false, true ], "values_complete": true }, { "name": "ariaDescribedBy", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Ids of the helper or error copy describing the control, supplied by a parent Field.", "source": { "path": "packages/design-system/src/hooks/FieldContext.ts", "line": 33 } }, { "name": "ariaLabelledBy", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Id of the visible label naming the control, supplied by a parent Field.", "source": { "path": "packages/design-system/src/hooks/FieldContext.ts", "line": 35 } } ], "prop_shapes": {}, "examples": [], "tokens": [ { "name": "--cds-size-80", "light": "80px", "dark": "80px" }, { "name": "--cds-size-64", "light": "64px", "dark": "64px" }, { "name": "--cds-space-20", "light": "20px", "dark": "20px" }, { "name": "--cds-space-24", "light": "24px", "dark": "24px" }, { "name": "--cds-size-32", "light": "32px", "dark": "32px" }, { "name": "--cds-type-body-size", "light": "1rem", "dark": "1rem" }, { "name": "--cds-type-body-small-size", "light": "0.875rem", "dark": "0.875rem" }, { "name": "--cds-bg-surface", "light": "#ffffff", "dark": "#1b1b18" }, { "name": "--cds-divider", "light": "#e0ddd6", "dark": "#ffffff1a" }, { "name": "--cds-bg-bold", "light": "#0b0b0a", "dark": "#ffffff" }, { "name": "--cds-text-primary", "light": "#141410", "dark": "#f3f1ed" } ], "visual_reference": { "stories": [ { "id": "cloaked-design-system-forms-radiogroup--playground", "name": "Playground", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "Playground", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--playground&viewMode=story" }, { "id": "cloaked-design-system-forms-radiogroup--with-field", "name": "With Field", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "WithField", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--with-field&viewMode=story" }, { "id": "cloaked-design-system-forms-radiogroup--label-only", "name": "Label Only", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "LabelOnly", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--label-only&viewMode=story" }, { "id": "cloaked-design-system-forms-radiogroup--with-disabled-option", "name": "With Disabled Option", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "WithDisabledOption", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--with-disabled-option&viewMode=story" }, { "id": "cloaked-design-system-forms-radiogroup--disabled", "name": "Disabled", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "Disabled", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--disabled&viewMode=story" }, { "id": "cloaked-design-system-forms-radiogroup--state-matrix", "name": "State Matrix", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "StateMatrix", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--state-matrix&viewMode=story" }, { "id": "cloaked-design-system-forms-radiogroup--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--dark-theme&viewMode=story" } ], "name": "RadioGroup", "id": "radiogroup", "category": "Forms" }, "stories": [ { "id": "cloaked-design-system-forms-radiogroup--playground", "name": "Playground", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "Playground", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--playground&viewMode=story" }, { "id": "cloaked-design-system-forms-radiogroup--with-field", "name": "With Field", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "WithField", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--with-field&viewMode=story" }, { "id": "cloaked-design-system-forms-radiogroup--label-only", "name": "Label Only", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "LabelOnly", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--label-only&viewMode=story" }, { "id": "cloaked-design-system-forms-radiogroup--with-disabled-option", "name": "With Disabled Option", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "WithDisabledOption", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--with-disabled-option&viewMode=story" }, { "id": "cloaked-design-system-forms-radiogroup--disabled", "name": "Disabled", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "Disabled", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--disabled&viewMode=story" }, { "id": "cloaked-design-system-forms-radiogroup--state-matrix", "name": "State Matrix", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "StateMatrix", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--state-matrix&viewMode=story" }, { "id": "cloaked-design-system-forms-radiogroup--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Forms/RadioGroup", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "source_digest": "9583a099fbb19fada426e96d6a93f6b9f97bd87d0c1a0646d73816d189eae837", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-radiogroup--dark-theme&viewMode=story" } ], "stories_source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.stories.tsx", "code": "import React from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { VStack } from '../../layout/VStack/VStack';\nimport { disabledControl, hapticArgType } from '../../../storybook/controlOptions';\nimport { Field } from '../Field/Field';\nimport { RadioGroup } from './RadioGroup';\n\nconst VOICE_OPTIONS = [\n { value: 'ash', label: 'Ash', description: 'Warm and even' },\n { value: 'alloy', label: 'Alloy', description: 'Bright and direct' },\n { value: 'ballad', label: 'Ballad', description: 'Soft and unhurried' },\n { value: 'coral', label: 'Coral', description: 'Friendly and upbeat' },\n];\n\nconst FREQUENCY_OPTIONS = [\n { value: 'daily', label: 'Daily' },\n { value: 'weekly', label: 'Weekly' },\n { value: 'off', label: 'Off' },\n];\n\nconst SHIMMER_OPTION = { value: 'shimmer', label: 'Shimmer', description: 'Coming soon', disabled: true };\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Forms/RadioGroup',\n component: RadioGroup,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'A single-choice control that keeps every `RadioOption` visible at once. Options render as ' +\n 'divider-separated `List.Item.Selection` rows with the control at the trailing edge, so a group ' +\n 'sits flush on the surface rather than as stacked cards. Use it when the list is short (2–5 ' +\n 'options) and seeing all choices aids the decision; reach for `Select` when the list is long or ' +\n 'space is tight. Each option can carry a `description`, and individual options or the whole ' +\n 'group can be `disabled`. Pair with `Field` for a label; only pass the standalone aria props ' +\n 'when used outside `Field`. Each row derives its test id from the group `testId` plus the ' +\n 'option value.',\n },\n },\n },\n args: {\n value: 'ash',\n ariaLabel: 'Assistant voice',\n options: VOICE_OPTIONS,\n testId: 'radio-group-story',\n },\n argTypes: {\n options: {\n ...disabledControl,\n description: 'The `RadioOption[]`; each has a `value`, `label`, optional `description`.',\n },\n onChange: { ...disabledControl, description: 'Called with the newly selected option `value`.' },\n haptic: { ...hapticArgType, description: 'Haptic fired on selection. Defaults to `true` (`selection`).' },\n value: { control: 'text', description: 'Currently selected option `value`.' },\n disabled: { control: 'boolean', description: 'Disables every option in the group.' },\n required: { control: 'boolean', description: 'Marks the group required for assistive technology.' },\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Playground: Story = {};\n\nexport const WithField: Story = {\n parameters: {\n docs: { description: { story: 'Wrapped in `Field` so the label and aria wiring come from the field.' } },\n },\n render: () => (\n \n \n \n ),\n};\n\nexport const LabelOnly: Story = {\n parameters: {\n docs: {\n description: {\n story: 'Without descriptions the row tightens from 80px to 64px, so short groups stay compact.',\n },\n },\n },\n args: {\n value: 'weekly',\n ariaLabel: 'Notification frequency',\n options: FREQUENCY_OPTIONS,\n testId: 'radio-group-label-only',\n },\n};\n\nexport const WithDisabledOption: Story = {\n parameters: {\n docs: { description: { story: 'A single option disabled while the rest of the group stays selectable.' } },\n },\n args: {\n options: [SHIMMER_OPTION, ...VOICE_OPTIONS],\n testId: 'radio-group-disabled-option',\n },\n};\n\nexport const Disabled: Story = {\n parameters: { docs: { description: { story: 'The whole group disabled.' } } },\n args: { value: 'ash', disabled: true, testId: 'radio-group-disabled' },\n};\n\nexport const StateMatrix: Story = {\n parameters: {\n docs: { description: { story: 'Described, label-only, one-disabled-option, and fully-disabled groups.' } },\n },\n render: () => (\n \n \n \n \n \n \n ),\n};\n\nexport const DarkTheme: Story = {\n globals: { theme: 'dark' },\n parameters: { docs: { description: { story: 'Row, divider, and control tokens on the dark theme.' } } },\n render: () => (\n \n ),\n};\n" }, "links": { "human": "/component-radiogroup", "json": "/data/components/radiogroup.json", "markdown": "/data/components/radiogroup.md", "storybook": "/storybook/?path=/story/cloaked-design-system-forms-radiogroup--playground" }, "contract_status": "preview", "contract_kind": "source-derived", "approval": "required", "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "RadioGroup", "public_path": "RadioGroup", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "RadioGroup", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 45 }, "props_type": "RadioGroupProps", "props": [ { "name": "value", "type": "string", "declared_type": "string", "required": true, "description": "Value of the selected option; a value matching no option leaves the group unselected.", "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 23 } }, { "name": "options", "type": "RadioOption[]", "declared_type": "RadioOption[]", "required": true, "description": "Options in display order. Dividers sit between rows, not after the last one.", "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 25 } }, { "name": "onChange", "type": "((value: string) => void) | undefined", "declared_type": "(value: string) => void", "required": false, "description": "Called with the next value. Pressing the already-selected option does not call it.", "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 27 } }, { "name": "disabled", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Prevents interaction with every option when true.", "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 29 }, "values": [ false, true ], "values_complete": true }, { "name": "required", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Marks the group as required for assistive technology.", "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 31 }, "values": [ false, true ], "values_complete": true }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible name when no visible label is associated with the group.", "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 33 } }, { "name": "haptic", "type": "HapticFeedback | undefined", "declared_type": "HapticFeedback", "required": false, "description": "Haptic feedback for value changes. Defaults to `true` (`selection`).", "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 35 }, "values": [ "error", "heavy", "light", "medium", "selection", "success", "warning", false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 36 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Test id for the group; each row derives `${testId}-${option.value}`.", "source": { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 38 } }, { "name": "id", "type": "string | undefined", "declared_type": "string", "required": false, "description": "DOM id the control renders, which the Field's label points at.", "source": { "path": "packages/design-system/src/hooks/FieldContext.ts", "line": 22 } }, { "name": "invalid", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Paints the invalid treatment and announces the control as invalid. A Field supplies\nthis from its own `error`; set it directly only for a control with no Field around it.", "source": { "path": "packages/design-system/src/hooks/FieldContext.ts", "line": 31 }, "values": [ false, true ], "values_complete": true }, { "name": "ariaDescribedBy", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Ids of the helper or error copy describing the control, supplied by a parent Field.", "source": { "path": "packages/design-system/src/hooks/FieldContext.ts", "line": 33 } }, { "name": "ariaLabelledBy", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Id of the visible label naming the control, supplied by a parent Field.", "source": { "path": "packages/design-system/src/hooks/FieldContext.ts", "line": 35 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 8, "name": "RadioOption", "code": "export interface RadioOption {\n value: string;\n label: string;\n /** Supporting copy shown beneath the label. */\n description?: string;\n /** Prevents this option from being selected. */\n disabled?: boolean;\n}" }, { "path": "packages/design-system/src/components/forms/RadioGroup/RadioGroup.tsx", "line": 21, "name": "RadioGroupProps", "code": "export interface RadioGroupProps extends FieldControlProps {\n /** Value of the selected option; a value matching no option leaves the group unselected. */\n value: string;\n /** Options in display order. Dividers sit between rows, not after the last one. */\n options: RadioOption[];\n /** Called with the next value. Pressing the already-selected option does not call it. */\n onChange?: (value: string) => void;\n /** Prevents interaction with every option when true. */\n disabled?: boolean;\n /** Marks the group as required for assistive technology. */\n required?: boolean;\n /** Accessible name when no visible label is associated with the group. */\n ariaLabel?: string;\n /** Haptic feedback for value changes. Defaults to `true` (`selection`). */\n haptic?: HapticFeedback;\n className?: string;\n /** Test id for the group; each row derives `${testId}-${option.value}`. */\n testId?: string;\n}" }, { "path": "packages/design-system/src/hooks/FieldContext.ts", "line": 20, "name": "FieldControlProps", "code": "export interface FieldControlProps {\n /** DOM id the control renders, which the Field's label points at. */\n id?: string;\n /** Blocks interaction and dims the control. */\n disabled?: boolean;\n /** Marks the control required for native form semantics. */\n required?: boolean;\n /**\n * Paints the invalid treatment and announces the control as invalid. A Field supplies\n * this from its own `error`; set it directly only for a control with no Field around it.\n */\n invalid?: boolean;\n /** Ids of the helper or error copy describing the control, supplied by a parent Field. */\n ariaDescribedBy?: string;\n /** Id of the visible label naming the control, supplied by a parent Field. */\n ariaLabelledBy?: string;\n}" }, { "path": "packages/design-system/src/tokens/CdsHaptic.ts", "line": 6, "name": "HapticFeedback", "code": "export type HapticFeedback = boolean | HapticType;" }, { "path": "packages/design-system/src/tokens/HapticType.ts", "line": 2, "name": "HapticType", "code": "export type HapticType = 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'selection';" } ], "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source." }, "platforms": { "implemented": [ "web" ], "native": "Imported design guidance only; no native implementation or parity verification in this preview.", "react": { "implementation": "local", "status": "preview", "parity": "web-reference" }, "vue": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "swift": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "kotlin": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" } }, "missing_facts": [ { "code": "human-review-pending", "detail": "This local preview has no recorded human design or engineering sign-off." }, { "code": "platform-parity-unverified", "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified." }, { "code": "figma-mapping-unverified", "detail": "No current component-level Figma node and immutable revision have been verified for this contract." } ], "review": { "local_status": "not-reviewed", "source_approval": null, "imported_spec_status": "approved", "spec_origin": "imported-adapted", "local_spec_source_status": "approved", "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract." } }