@ankhorage/zora 4.4.1 → 4.5.0

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;
 }

package/src/constants/keyboard.ts

@@ -0,0 +1,7 @@
+/** Shared arrow-key offsets; string keys also permit lookup of unrelated keyboard events. */
+export const DIRECTION_MODIFIERS: ReadonlyMap<string, number> = new Map([
+  ['ArrowRight', 1],
+  ['ArrowDown', 1],
+  ['ArrowLeft', -1],
+  ['ArrowUp', -1],
+]);

package/src/metadata/componentMeta.test.ts

@@ -210,6 +210,7 @@ describe('ZORA_COMPONENT_META invariants', () => {
       'value',
       'label',
       'description',
+      'iconSource',
       'disabled',
     ]);
     expect(radioGroup.bindings?.props?.value?.value).toEqual({ type: 'string' });