@ankhorage/zora 4.4.0 → 4.5.0

package/src/components/radio/RadioGroup.tsx

@@ -1,145 +1,117 @@
-import { Radio, useTheme } from '@ankhorage/surface';
+import { Radio } from '@ankhorage/surface';
 import React from 'react';
-import { View } from 'react-native';
+import { StyleSheet, View } from 'react-native';
 
 import { Stack } from '../../foundation';
 import { useZoraThemeRecipe } from '../../theme/useZoraThemeRecipe';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { Text } from '../text';
+import { RadioOptionControl } from './RadioOptionControl';
 import { resolveRadioGroupThemeRecipe } from './resolveRadioGroupThemeRecipe';
-import type { RadioGroupOption, RadioGroupProps } from './types';
+import type { RadioGroupProps } from './types';
 
-/***
- * Resolves the themed radio-group presentation within the active ZORA scope.
- */
+/*** Present one controlled single-choice group as inline radios or icon radio options. */
+export const RadioGroup = withZoraThemeScope(RadioGroupInner);
+
+/*** Resolve shared presentation once and preserve a single interaction boundary per option. */
 function RadioGroupInner<TValue extends string>({
   themeId: _themeId,
   mode: _mode,
-  value,
-  onValueChange,
-  options,
-  orientation = 'vertical',
-  gap,
-  presentation = 'inline',
-  color,
-  size,
-  invalid = false,
-  readOnly = false,
-  disabled = false,
-  testID,
-  interactionPolicy,
+  ...props
 }: RadioGroupProps<TValue>) {
-  const isHorizontal = orientation === 'horizontal';
+  const [localValue, setLocalValue] = React.useState(props.defaultValue);
+  const onValueChange = (next: TValue) => {
+    if (props.value === undefined) setLocalValue(next);
+    props.onValueChange?.(next);
+  };
+  const selectedProps = { ...props, value: props.value ?? localValue, onValueChange };
   const themeFields = useZoraThemeRecipe('RadioGroup');
-  const recipe = resolveRadioGroupThemeRecipe({ gap, color, size, themeFields });
+  const recipe = resolveRadioGroupThemeRecipe({ ...props, themeFields });
+  if (props.presentation !== 'card') return <RadioGroupInline {...selectedProps} {...recipe} />;
+  const columns =
+    props.columns ?? (props.orientation === 'horizontal' ? Math.max(1, props.options.length) : 1);
+  const rows = Array.from({ length: Math.ceil(props.options.length / columns) }, (_, index) =>
+    props.options.slice(index * columns, (index + 1) * columns),
+  );
+  return (
+    <View testID={props.testID} accessibilityRole="radiogroup">
+      <Stack gap={recipe.gap}>
+        {rows.map((options, index) => (
+          <Stack key={index} direction="row" gap={recipe.gap}>
+            {options.map((option) => (
+              <View key={option.value} style={styles.option}>
+                <RadioGroupItem {...selectedProps} {...recipe} option={option} />
+              </View>
+            ))}
+            {Array.from({ length: columns - options.length }, (_, slot) => (
+              <View key={`empty-${slot}`} style={styles.option} />
+            ))}
+          </Stack>
+        ))}
+      </Stack>
+    </View>
+  );
+}
 
+/*** Preserve ordinary radio wrapping independently of the icon-option grid. */
+function RadioGroupInline<TValue extends string>(props: RadioGroupProps<TValue>) {
   return (
-    <View
-      testID={testID}
-      accessibilityRole="radiogroup"
-      style={{
-        flexDirection: isHorizontal ? 'row' : 'column',
-        flexWrap: isHorizontal ? 'wrap' : 'nowrap',
-      }}
-    >
+    <View testID={props.testID} accessibilityRole="radiogroup">
       <Stack
-        direction={isHorizontal ? 'row' : 'column'}
-        gap={recipe.gap}
-        wrap={isHorizontal ? 'wrap' : 'nowrap'}
+        direction={props.orientation === 'horizontal' ? 'row' : 'column'}
+        gap={props.gap}
+        wrap="wrap"
       >
-        {options.map((option) => (
-          <RadioGroupItem
-            key={option.value}
-            option={option}
-            checked={value === option.value}
-            disabled={disabled || option.disabled === true}
-            invalid={invalid}
-            readOnly={readOnly}
-            size={recipe.size}
-            color={recipe.color}
-            orientation={orientation}
-            presentation={presentation}
-            onSelect={onValueChange}
-            interactionPolicy={interactionPolicy}
-          />
+        {props.options.map((option) => (
+          <RadioGroupItem key={option.value} {...props} option={option} />
         ))}
       </Stack>
     </View>
   );
 }
 
-/***
- * Renders a group of radio options for selecting a single value.
- */
-export const RadioGroup = withZoraThemeScope(RadioGroupInner);
-
-/***
- * Renders one option through the single Surface Radio interaction boundary.
- */
-function RadioGroupItem<TValue extends string>({
-  option,
-  checked,
-  disabled,
-  invalid,
-  readOnly,
-  size,
-  color,
-  orientation,
-  presentation,
-  onSelect,
-  interactionPolicy,
-}: {
-  option: RadioGroupOption<TValue>;
-  checked: boolean;
-  disabled: boolean;
-  invalid: boolean;
-  readOnly: boolean;
-  size: NonNullable<RadioGroupProps<TValue>['size']>;
-  color: NonNullable<RadioGroupProps<TValue>['color']>;
-  orientation: NonNullable<RadioGroupProps<TValue>['orientation']>;
-  presentation: NonNullable<RadioGroupProps<TValue>['presentation']>;
-  onSelect: (value: TValue) => void;
-  interactionPolicy: RadioGroupProps<TValue>['interactionPolicy'];
-}) {
-  const { theme } = useTheme();
-  const passive = interactionPolicy === 'passive';
-  const isCard = presentation === 'card';
-
+/*** Delegate icon options to their composed radio boundary and ordinary options to Surface Radio. */
+function RadioGroupItem<TValue extends string>(
+  props: RadioGroupProps<TValue> & {
+    option: RadioGroupProps<TValue>['options'][number];
+  },
+) {
+  const { option, value, onValueChange, interactionPolicy, color, size } = props;
+  const checked = value === option.value;
+  const inactive = props.disabled === true || option.disabled === true;
+  const readOnly = props.readOnly === true;
+  const invalid = props.invalid === true;
+  const onSelect = () => {
+    if (!inactive && !readOnly && interactionPolicy !== 'passive' && !checked)
+      onValueChange?.(option.value);
+  };
+  if (props.presentation === 'card') {
+    return (
+      <RadioOptionControl
+        {...props}
+        checked={checked}
+        disabled={inactive}
+        readOnly={readOnly}
+        invalid={invalid}
+        layout={props.contentOrientation ?? 'horizontal'}
+        onSelect={onSelect}
+      />
+    );
+  }
   return (
     <Radio
-      interactionPolicy={interactionPolicy}
       checked={checked}
-      disabled={disabled}
-      invalid={invalid}
+      disabled={inactive}
       readOnly={readOnly}
-      size={size}
+      invalid={invalid}
+      interactionPolicy={interactionPolicy}
       color={color}
+      size={size}
       testID={option.testID}
-      bg={
-        isCard
-          ? checked
-            ? theme.semantics.selection.background
-            : theme.semantics.surface.default
-          : undefined
-      }
-      borderColor={
-        isCard
-          ? checked
-            ? theme.semantics.selection.border
-            : theme.semantics.border.default
-          : undefined
-      }
-      borderWidth={isCard ? 1 : undefined}
-      p={isCard ? 'm' : undefined}
-      radius={isCard ? 'l' : undefined}
-      width={isCard && orientation === 'vertical' ? '100%' : undefined}
-      onCheckedChange={(nextChecked) => {
-        if (passive) return;
-        if (nextChecked) onSelect(option.value);
-      }}
+      onCheckedChange={onSelect}
     >
       <Stack gap="xs">
-        <Text weight={isCard ? 'semiBold' : undefined}>{option.label}</Text>
+        <Text>{option.label}</Text>
         {option.description ? (
           <Text emphasis="muted" variant="caption">
             {option.description}
@@ -149,3 +121,5 @@ function RadioGroupItem<TValue extends string>({
     </Radio>
   );
 }
+
+const styles = StyleSheet.create({ option: { flex: 1, minWidth: 0 } });

package/src/components/radio/RadioOptionControl.tsx

@@ -0,0 +1,192 @@
+import { useTheme } from '@ankhorage/surface';
+import React from 'react';
+import { Platform, Pressable, StyleSheet, View } from 'react-native';
+
+import { Icon } from '../icon';
+import { Text } from '../text';
+import {
+  handleRadioOptionKeyDown,
+  type RadioOptionKeyboardTarget,
+} from './handleRadioOptionKeyDown';
+import { resolveRadioOptionColors } from './resolveRadioOptionColors';
+import type { RadioGroupProps } from './types';
+
+/*** Render a selectable icon radio option with one accessible radio target and a trailing check. */
+export function RadioOptionControl<TValue extends string>(props: RadioOptionControlProps<TValue>) {
+  const { theme } = useTheme();
+  const { option, checked, disabled, readOnly, interactionPolicy, onSelect } = props;
+  const colors = resolveRadioOptionColors(theme, props);
+  const [focused, setFocused] = React.useState(false);
+  const keyboardProps =
+    Platform.OS === 'web' && !readOnly && !disabled && interactionPolicy !== 'passive'
+      ? {
+          onKeyDown: (event: React.KeyboardEvent<RadioOptionKeyboardTarget>) =>
+            handleRadioOptionKeyDown(event, onSelect),
+        }
+      : {};
+  const controlStyle = {
+    flex: 1,
+    width: '100%' as const,
+    minHeight: props.size === 'l' ? 84 : 44,
+    borderWidth: checked || focused ? 2 : 1,
+    borderColor: focused ? theme.semantics.border.focus : checked ? colors.accent : colors.border,
+    borderRadius: theme.radii.l,
+    backgroundColor: colors.surface,
+  };
+  return (
+    <Pressable
+      {...keyboardProps}
+      accessibilityRole="radio"
+      accessibilityState={{ checked, disabled }}
+      aria-checked={checked}
+      aria-disabled={disabled}
+      aria-readonly={readOnly}
+      disabled={disabled}
+      onPress={readOnly || interactionPolicy === 'passive' ? undefined : onSelect}
+      onFocus={() => setFocused(true)}
+      onBlur={() => setFocused(false)}
+      testID={option.testID}
+      style={controlStyle}
+    >
+      {(state) => <RadioOptionControlBody {...props} pressed={state.pressed} />}
+    </Pressable>
+  );
+}
+
+/*** Arrange the icon, label and passive indicator within the native radio press target. */
+function RadioOptionControlBody<TValue extends string>(
+  props: RadioOptionControlProps<TValue> & { pressed: boolean },
+) {
+  const { theme } = useTheme();
+  const colors = resolveRadioOptionColors(theme, props);
+  const contentStyle = {
+    padding: props.size === 's' ? theme.spacing.s : props.size === 'm' ? 12 : theme.spacing.m,
+    gap:
+      props.layout === 'vertical' || !props.option.iconSource ? theme.spacing.s : theme.spacing.m,
+    ...(!props.option.iconSource ? { flexDirection: 'row-reverse' as const } : {}),
+    opacity: props.disabled ? 0.5 : props.pressed ? 0.7 : 1,
+  };
+  return (
+    <View
+      style={[
+        styles.content,
+        props.layout === 'vertical' ? styles.vertical : styles.horizontal,
+        contentStyle,
+      ]}
+    >
+      <RadioOptionControlContent {...props} />
+      {props.option.iconSource || props.checked ? (
+        <View style={props.layout === 'vertical' ? styles.corner : undefined}>
+          <RadioOptionControlIndicator
+            checked={props.checked}
+            accent={colors.accent}
+            onAccent={colors.onAccent}
+          />
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
+interface RadioOptionControlProps<TValue extends string> extends Pick<
+  RadioGroupProps<TValue>,
+  'color' | 'size' | 'interactionPolicy'
+> {
+  option: RadioGroupProps<TValue>['options'][number];
+  checked: boolean;
+  disabled: boolean;
+  readOnly: boolean;
+  invalid: boolean;
+  layout: 'horizontal' | 'vertical';
+  onSelect: () => void;
+}
+
+/*** Keep decoration passive while allowing labels to wrap at narrow widths and large text sizes. */
+function RadioOptionControlContent<TValue extends string>({
+  option,
+  layout,
+  size,
+  color,
+  invalid,
+  disabled,
+}: RadioOptionControlProps<TValue>) {
+  const { theme } = useTheme();
+  const colors = resolveRadioOptionColors(theme, { color, invalid, disabled });
+  return (
+    <>
+      {option.iconSource ? (
+        <View accessibilityElementsHidden importantForAccessibility="no-hide-descendants">
+          <Icon source={option.iconSource} size={size === 'l' ? 36 : 28} color={colors.accent} />
+        </View>
+      ) : null}
+      <View style={layout === 'horizontal' ? styles.label : styles.centerLabel}>
+        <Text
+          variant={size === 'l' ? 'body' : 'bodySmall'}
+          weight="semiBold"
+          align={layout === 'vertical' || !option.iconSource ? 'center' : 'left'}
+        >
+          {option.label}
+        </Text>
+        {option.description ? (
+          <Text
+            emphasis="muted"
+            variant="bodySmall"
+            align={layout === 'vertical' || !option.iconSource ? 'center' : 'left'}
+          >
+            {option.description}
+          </Text>
+        ) : null}
+      </View>
+    </>
+  );
+}
+
+/*** Draw a passive check using themed geometry without requiring an application media asset. */
+function RadioOptionControlIndicator({
+  checked,
+  accent,
+  onAccent,
+}: {
+  checked: boolean;
+  accent: string;
+  onAccent: string;
+}) {
+  const indicatorStyle = { backgroundColor: checked ? accent : 'transparent' };
+  return (
+    <View
+      accessibilityElementsHidden
+      importantForAccessibility="no-hide-descendants"
+      style={[styles.indicator, indicatorStyle]}
+    >
+      {checked ? <View style={[styles.check, { borderColor: onAccent }]} /> : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  content: { gap: 16, flex: 1, minWidth: 0 },
+  horizontal: { flexDirection: 'row', alignItems: 'center' },
+  vertical: {
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingTop: 24,
+  },
+  label: { flex: 1, minWidth: 0, gap: 4 },
+  centerLabel: { alignSelf: 'stretch', gap: 4 },
+  corner: { position: 'absolute', right: 8, top: 8 },
+  indicator: {
+    width: 24,
+    height: 24,
+    borderRadius: 12,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  check: {
+    width: 7,
+    height: 12,
+    borderRightWidth: 2.5,
+    borderBottomWidth: 2.5,
+    transform: [{ rotate: '45deg' }, { translateY: -2 }],
+  },
+});

package/src/components/radio/handleRadioOptionKeyDown.test.ts

@@ -0,0 +1,47 @@
+import { expect, test } from 'bun:test';
+import type { KeyboardEvent } from 'react';
+
+import { DIRECTION_MODIFIERS } from '../../constants/keyboard';
+import {
+  handleRadioOptionKeyDown,
+  type RadioOptionKeyboardTarget,
+} from './handleRadioOptionKeyDown';
+
+test('Space selects the focused radio and prevents page scrolling', () => {
+  let selected = 0;
+  let prevented = 0;
+  handleRadioOptionKeyDown(
+    { key: ' ', preventDefault: () => prevented++ } as KeyboardEvent<RadioOptionKeyboardTarget>,
+    () => selected++,
+  );
+  expect(selected).toBe(1);
+  expect(prevented).toBe(1);
+});
+
+for (const [key, direction] of DIRECTION_MODIFIERS) {
+  test(`${key} wraps and skips disabled radio options`, () => {
+    const activated: number[] = [];
+    const focused: number[] = [];
+    let prevented = 0;
+    const options: RadioOptionKeyboardTarget[] = [0, 1, 2, 3].map((index) => ({
+      closest: () => ({ querySelectorAll: () => options }),
+      getAttribute: () => (index === 1 ? 'true' : 'false'),
+      focus: () => focused.push(index),
+      click: () => activated.push(index),
+    }));
+    for (const currentTarget of [options[0], options[2], options[3]]) {
+      handleRadioOptionKeyDown(
+        {
+          key,
+          currentTarget,
+          preventDefault: () => prevented++,
+        } as KeyboardEvent<RadioOptionKeyboardTarget>,
+        () => undefined,
+      );
+    }
+    const expected = direction === 1 ? [2, 3, 0] : [3, 0, 2];
+    expect(focused).toEqual(expected);
+    expect(activated).toEqual(expected);
+    expect(prevented).toBe(3);
+  });
+}

package/src/components/radio/handleRadioOptionKeyDown.ts

@@ -0,0 +1,37 @@
+import type { KeyboardEvent } from 'react';
+
+import { DIRECTION_MODIFIERS } from '../../constants/keyboard';
+
+/*** Support Space and directional navigation for web radio options without affecting native presses. */
+export function handleRadioOptionKeyDown(
+  event: KeyboardEvent<RadioOptionKeyboardTarget>,
+  select: () => void,
+): void {
+  if (event.key === ' ') {
+    event.preventDefault();
+    select();
+    return;
+  }
+  const direction = DIRECTION_MODIFIERS.get(event.key);
+  if (direction === undefined) return;
+  const group = event.currentTarget.closest('[role="radiogroup"]');
+  const options = Array.from(group?.querySelectorAll('[role="radio"]') ?? []).filter(
+    (option) => option.getAttribute('aria-disabled') !== 'true',
+  );
+  const index = options.indexOf(event.currentTarget);
+  if (index < 0 || options.length === 0) return;
+  event.preventDefault();
+  const next = options.at((index + direction + options.length) % options.length);
+  next?.focus();
+  next?.click();
+}
+
+/** Minimal web target contract keeps the native build independent of DOM ambient libraries. */
+export interface RadioOptionKeyboardTarget {
+  closest(
+    selector: string,
+  ): { querySelectorAll(selector: string): ArrayLike<RadioOptionKeyboardTarget> } | null;
+  getAttribute(name: string): string | null;
+  focus(): void;
+  click(): void;
+}

package/src/components/radio/meta.ts

@@ -24,16 +24,16 @@ export const radioGroupMeta = {
   directManifestNode: true,
   allowedChildren: [],
   blueprint: {
-    label: 'Radio group',
+    label: 'Radio button group',
     defaultProps: {
-      value: 'option-b',
+      defaultValue: 'option-b',
       options: [
         { value: 'option-a', label: 'First option', description: 'Supporting detail' },
         { value: 'option-b', label: 'Second option', description: 'Supporting detail' },
         { value: 'option-c', label: 'Third option', description: 'Supporting detail' },
       ],
       orientation: 'vertical',
-      presentation: 'inline',
+      presentation: 'card',
       invalid: false,
       readOnly: false,
       disabled: false,
@@ -76,6 +76,12 @@ export const radioGroupMeta = {
     },
   },
   props: {
+    defaultValue: {
+      type: 'string',
+      category: 'State',
+      label: 'Initial value',
+      authoring: { authority: 'instance' },
+    },
     value: {
       type: 'string',
       category: 'State',
@@ -111,6 +117,10 @@ export const radioGroupMeta = {
             label: 'Description',
           },
         },
+        {
+          key: 'iconSource',
+          schema: { type: 'media', category: 'Content', label: 'Icon', mediaKinds: ['image'] },
+        },
         {
           key: 'disabled',
           schema: {
@@ -146,6 +156,21 @@ export const radioGroupMeta = {
       default: 'inline',
       authoring: { authority: 'instance' },
     },
+    contentOrientation: {
+      type: 'enum',
+      category: 'Layout',
+      label: 'Option content orientation',
+      enum: ['horizontal', 'vertical'],
+      default: 'horizontal',
+      authoring: { authority: 'instance' },
+    },
+    columns: {
+      type: 'enum',
+      category: 'Layout',
+      label: 'Option columns',
+      enum: [1, 2, 3, 4],
+      authoring: { authority: 'instance' },
+    },
     color: {
       type: 'enum',
       category: 'Style',

package/src/components/radio/resolveRadioOptionColors.test.ts

@@ -0,0 +1,29 @@
+import { createTheme } from '@ankhorage/surface/theme';
+import { expect, test } from 'bun:test';
+
+import { resolveRadioOptionColors } from './resolveRadioOptionColors';
+
+const source = {
+  id: 'radio',
+  name: 'Radio',
+  light: { primaryColor: '#0060FF', harmony: 'monochromatic' as const },
+  dark: { primaryColor: '#0060FF', harmony: 'monochromatic' as const },
+};
+
+for (const mode of ['light', 'dark'] as const) {
+  test(`radio selection preserves role contrast and field states in ${mode} mode`, () => {
+    const theme = createTheme(source, mode);
+    const selected = resolveRadioOptionColors(theme, { color: 'secondary' });
+    expect(selected.accent).toBe(theme.semantics.secondary.base);
+    expect(selected.onAccent).toBe(theme.semantics.secondary.onSolidText);
+    const invalid = resolveRadioOptionColors(theme, { color: 'secondary', invalid: true });
+    expect(invalid.accent).toBe(theme.semantics.error.base);
+    const disabled = resolveRadioOptionColors(theme, {
+      color: 'secondary',
+      invalid: true,
+      disabled: true,
+    });
+    expect(disabled.accent).toBe(theme.semantics.content.disabled);
+    expect(disabled.surface).toBe(theme.semantics.surface.disabled);
+  });
+}

package/src/components/radio/resolveRadioOptionColors.ts

@@ -0,0 +1,37 @@
+import type { RoleSemantics, SurfaceTheme } from '@ankhorage/surface';
+
+import type { RadioGroupProps } from './types';
+
+/*** Resolve selection-card decoration from the requested semantic role and field state. */
+export function resolveRadioOptionColors(
+  theme: SurfaceTheme,
+  {
+    color = 'primary',
+    invalid,
+    disabled,
+  }: Pick<RadioGroupProps<string>, 'color' | 'invalid' | 'disabled'>,
+) {
+  const roles = new Map<string, RoleSemantics>([
+    ['primary', theme.semantics.action.primary],
+    ['secondary', theme.semantics.secondary],
+    ['tertiary', theme.semantics.accent],
+    ['quaternary', theme.semantics.highlight],
+    ['neutral', theme.semantics.action.neutral],
+    ['danger', theme.semantics.action.danger],
+    ['error', theme.semantics.error],
+    ['success', theme.semantics.success],
+    ['warning', theme.semantics.warning],
+    ['info', theme.semantics.info],
+  ]);
+  const role = roles.get(invalid ? 'error' : color) ?? theme.semantics.action.primary;
+  return {
+    accent: disabled ? theme.semantics.content.disabled : role.base,
+    onAccent: disabled ? theme.semantics.surface.disabled : role.onSolidText,
+    border: disabled
+      ? theme.semantics.border.subtle
+      : invalid
+        ? role.outline
+        : theme.semantics.border.default,
+    surface: disabled ? theme.semantics.surface.disabled : theme.semantics.surface.default,
+  };
+}

package/src/components/radio/types.ts

@@ -2,6 +2,7 @@ import type { RadioProps as SurfaceRadioProps } from '@ankhorage/surface';
 import type React from 'react';
 
 import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+import type { IconProps } from '../icon';
 
 export interface RadioProps extends ZoraBaseProps, Omit<SurfaceRadioProps, 'mode' | 'themeId'> {}
 
@@ -9,6 +10,8 @@ export interface RadioGroupOption<TValue extends string> {
   value: TValue;
   label: React.ReactNode;
   description?: React.ReactNode;
+  /** SVG media is resolved by the consuming runtime before rendering. */
+  iconSource?: Extract<IconProps, { source: unknown }>['source'];
   disabled?: boolean;
   testID?: string;
 }
@@ -20,10 +23,15 @@ export interface RadioGroupProps<TValue extends string>
       Omit<SurfaceRadioProps, 'mode' | 'themeId'>,
       'color' | 'size' | 'invalid' | 'readOnly' | 'disabled'
     > {
-  value: TValue;
-  onValueChange: (value: TValue) => void;
+  value?: TValue;
+  defaultValue?: TValue;
+  onValueChange?: (value: TValue) => void;
   options: readonly RadioGroupOption<TValue>[];
   orientation?: 'horizontal' | 'vertical';
   gap?: 'xs' | 's' | 'm' | 'l';
   presentation?: 'inline' | 'card';
+  /** Arrangement inside a selection card, independent of the group direction. */
+  contentOrientation?: 'horizontal' | 'vertical';
+  /** Equal-width card columns; omitted columns follow orientation. */
+  columns?: 1 | 2 | 3 | 4;
 }