@ankhorage/zora 7.0.0 → 9.0.0

package/src/features/form/radio/radioMeta.ts

@@ -0,0 +1,214 @@
+import { ZORA_COLORS } from '../../../internal/colorModel';
+import type { ZoraComponentMeta } from '../../../metadata';
+
+const themeAuthoring = {
+  authority: 'theme',
+  scope: 'component',
+  allowInstanceOverride: true,
+} as const;
+
+export const radioMeta = {
+  name: 'Radio',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: { label: 'Radio', defaultProps: { label: 'Option', checked: false } },
+  props: {
+    label: { type: 'string', category: 'Content', label: 'Label' },
+    checked: { type: 'boolean', category: 'State', label: 'Checked', default: false },
+    disabled: { type: 'boolean', category: 'State', label: 'Disabled', default: false },
+  },
+} as const satisfies ZoraComponentMeta;
+
+export const radioGroupMeta = {
+  name: 'RadioGroup',
+  category: 'component',
+  description:
+    'Single-choice group with inline or card presentation while preserving radio semantics.',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Radio button group',
+    defaultProps: {
+      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: 'card',
+      invalid: false,
+      readOnly: false,
+      disabled: false,
+    },
+  },
+  bindings: {
+    props: {
+      value: {
+        label: 'Value',
+        description: 'Currently selected option value.',
+        value: { type: 'string' },
+        acceptsFallback: true,
+        acceptsTransforms: true,
+      },
+      disabled: {
+        label: 'Disabled',
+        description: 'Whether the complete radio group is disabled.',
+        value: { type: 'boolean' },
+        acceptsFallback: true,
+        acceptsTransforms: true,
+      },
+    },
+    events: {
+      valueChange: {
+        label: 'Value change',
+        description: 'Runs when the selected radio value changes.',
+        payload: {
+          eventType: 'radioGroup.valueChange',
+          fields: [{ path: 'value', type: 'string', label: 'Value' }],
+        },
+      },
+    },
+  },
+  events: {
+    valueChange: {
+      label: 'Value change',
+      eventType: 'radioGroup.valueChange',
+      description: 'Emitted when the selected radio value changes.',
+      payloadFields: [{ path: 'value', type: 'string', label: 'Value' }],
+    },
+  },
+  props: {
+    defaultValue: {
+      type: 'string',
+      category: 'State',
+      label: 'Initial value',
+      authoring: { authority: 'instance' },
+    },
+    value: {
+      type: 'string',
+      category: 'State',
+      label: 'Value',
+      authoring: { authority: 'instance' },
+    },
+    options: {
+      type: 'array',
+      category: 'Content',
+      label: 'Options',
+      itemSchema: [
+        {
+          key: 'value',
+          schema: {
+            type: 'string',
+            category: 'Content',
+            label: 'Value',
+          },
+        },
+        {
+          key: 'label',
+          schema: {
+            type: 'string',
+            category: 'Content',
+            label: 'Label',
+          },
+        },
+        {
+          key: 'description',
+          schema: {
+            type: 'string',
+            category: 'Content',
+            label: 'Description',
+          },
+        },
+        {
+          key: 'iconSource',
+          schema: { type: 'media', category: 'Content', label: 'Icon', mediaKinds: ['image'] },
+        },
+        {
+          key: 'disabled',
+          schema: {
+            type: 'boolean',
+            category: 'State',
+            label: 'Disabled',
+            default: false,
+          },
+        },
+      ],
+      authoring: { authority: 'instance' },
+    },
+    orientation: {
+      type: 'enum',
+      category: 'Layout',
+      label: 'Orientation',
+      enum: ['horizontal', 'vertical'],
+      default: 'vertical',
+      authoring: { authority: 'instance' },
+    },
+    gap: {
+      type: 'enum',
+      category: 'Layout',
+      label: 'Gap',
+      enum: ['xs', 's', 'm', 'l'],
+      authoring: themeAuthoring,
+    },
+    presentation: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Presentation',
+      enum: ['inline', 'card'],
+      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',
+      label: 'Color',
+      enum: [...ZORA_COLORS],
+      authoring: themeAuthoring,
+    },
+    size: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Size',
+      enum: ['s', 'm', 'l'],
+      authoring: themeAuthoring,
+    },
+    invalid: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Invalid',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+    readOnly: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Read only',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+    disabled: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Disabled',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/form/radio/themeRecipeMeta.ts

@@ -0,0 +1,28 @@
+import { ZORA_COLORS } from '../../../internal/colorModel';
+import type { ZoraThemeRecipeMeta } from '../../../metadata/themeRecipeTypes';
+
+export const radioGroupThemeRecipeMeta = {
+  name: 'RadioGroup',
+  kind: 'component',
+  description: 'Maps shared selection-control presentation choices into RadioGroup defaults.',
+  fields: {
+    gap: {
+      type: 'choice',
+      label: 'Gap',
+      options: ['xs', 's', 'm', 'l'],
+      default: 's',
+    },
+    color: {
+      type: 'choice',
+      label: 'Color',
+      options: ZORA_COLORS,
+      default: 'primary',
+    },
+    size: {
+      type: 'choice',
+      label: 'Size',
+      options: ['s', 'm', 'l'],
+      default: 'm',
+    },
+  },
+} as const satisfies ZoraThemeRecipeMeta;

package/src/features/form/radio/utils/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/features/form/radio/utils/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/features/form/radio/utils/resolveRadioGroupThemeRecipe.ts

@@ -0,0 +1,45 @@
+import type { ThemeRecipeOverrideValue } from '@ankhorage/contracts';
+
+import type { ZoraColor } from '../../../../internal/colorModel';
+import type { RadioGroupProps } from '../../../../types/radio';
+
+type RadioGroupGap = NonNullable<RadioGroupProps<string>['gap']>;
+type RadioGroupSize = NonNullable<RadioGroupProps<string>['size']>;
+
+/***
+ * Resolves RadioGroup presentation props from instance overrides and the active theme recipe.
+ */
+export function resolveRadioGroupThemeRecipe(input: {
+  readonly gap?: RadioGroupGap;
+  readonly color?: ZoraColor;
+  readonly size?: RadioGroupSize;
+  readonly themeFields: Readonly<Record<string, ThemeRecipeOverrideValue>>;
+}) {
+  return {
+    gap: input.gap ?? readGap(input.themeFields.gap) ?? 's',
+    color: input.color ?? readColor(input.themeFields.color) ?? 'primary',
+    size: input.size ?? readSize(input.themeFields.size) ?? 'm',
+  } as const;
+}
+
+/*** Reads a valid RadioGroup gap from a theme recipe value. */
+function readGap(value: ThemeRecipeOverrideValue | undefined): RadioGroupGap | undefined {
+  if (value === 'xs' || value === 's' || value === 'm' || value === 'l') return value;
+  return undefined;
+}
+
+/*** Reads a valid ZORA color from a theme recipe value. */
+function readColor(value: ThemeRecipeOverrideValue | undefined): ZoraColor | undefined {
+  if (value === 'primary' || value === 'secondary' || value === 'tertiary') return value;
+  if (value === 'quaternary' || value === 'neutral' || value === 'danger') return value;
+  if (value === 'success' || value === 'warning' || value === 'error' || value === 'info') {
+    return value;
+  }
+  return undefined;
+}
+
+/*** Reads a valid RadioGroup control size from a theme recipe value. */
+function readSize(value: ThemeRecipeOverrideValue | undefined): RadioGroupSize | undefined {
+  if (value === 's' || value === 'm' || value === 'l') return value;
+  return undefined;
+}

package/src/features/form/radio/utils/resolveRadioOptionColors.ts

@@ -0,0 +1,37 @@
+import type { RoleSemantics, SurfaceTheme } from '@ankhorage/surface';
+
+import type { RadioGroupProps } from '../../../../types/radio';
+
+/*** 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/features/form/text-input/adapters/inbound/TextInput.tsx

@@ -0,0 +1,68 @@
+import * as Surface from '@ankhorage/surface';
+import React from 'react';
+
+import { resolveIconSize } from '../../../../../internal/recipes';
+import { useZoraTheme } from '../../../../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../../../../theme/withZoraThemeScope';
+import type { TextInputProps } from '../../../../../types/text-input';
+import { IconButton } from '../../../../button/public';
+
+function TextInputInner({
+  themeId: _themeId,
+  mode: _mode,
+  size = 'l',
+  leadingIcon,
+  trailingIcon,
+  trailingAction,
+  disabled,
+  readOnly,
+  interactionPolicy,
+  ...props
+}: TextInputProps) {
+  const { theme } = useZoraTheme();
+  const iconSize = resolveIconSize(size);
+  const iconColor = theme.semantics.content.muted;
+
+  return (
+    <Surface.TextInput
+      {...props}
+      disabled={disabled}
+      interactionPolicy={interactionPolicy}
+      leadingAccessory={
+        leadingIcon ? (
+          <Surface.Icon {...leadingIcon} color={iconColor} size={iconSize} />
+        ) : undefined
+      }
+      readOnly={readOnly}
+      size={size}
+      trailingAccessory={
+        trailingAction ? (
+          <IconButton
+            icon={trailingAction.icon}
+            interactionPolicy={interactionPolicy}
+            label={trailingAction.label}
+            disabled={disabled ?? readOnly}
+            variant="ghost"
+            size={size === 'l' ? 'm' : size}
+            color="neutral"
+            onPress={trailingAction.onPress}
+          />
+        ) : trailingIcon ? (
+          <Surface.Icon {...trailingIcon} color={iconColor} size={iconSize} />
+        ) : undefined
+      }
+    />
+  );
+}
+
+/***
+ * Theme-aware text input with semantic sizing and optional leading/trailing icon slots.
+ *
+ * Use `TextInput` for single-line, multiline, and password form controls with ZORA styling.
+ *
+ * @example Search input
+ * ```tsx
+ * <TextInput placeholder="Search" leadingIcon={{ name: 'search-outline' }} />
+ * ```
+ */
+export const TextInput = withZoraThemeScope(TextInputInner);

package/src/features/form/text-input/public.ts

@@ -0,0 +1,2 @@
+export type { TextInputProps, TextInputTrailingAction } from '../../../types/text-input';
+export { TextInput } from './adapters/inbound/TextInput';

package/src/features/form/text-input/textInputMeta.ts

@@ -0,0 +1,58 @@
+import type { ZoraComponentMeta } from '../../../metadata';
+
+export const textInputMeta = {
+  name: 'TextInput',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Text input',
+    defaultProps: {
+      placeholder: 'Enter text…',
+      value: '',
+    },
+  },
+  props: {
+    placeholder: {
+      type: 'string',
+      category: 'Content',
+      label: 'Placeholder',
+    },
+    value: {
+      type: 'string',
+      category: 'Content',
+      label: 'Value',
+      default: '',
+    },
+    size: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Size',
+      enum: ['s', 'm', 'l'],
+    },
+    disabled: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Disabled',
+      default: false,
+    },
+    readOnly: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Read-only',
+      default: false,
+    },
+    multiline: {
+      type: 'boolean',
+      category: 'Layout',
+      label: 'Multiline',
+      default: false,
+    },
+    secureTextEntry: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Secure text entry',
+      default: false,
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/icon/adapters/inbound/Icon.tsx

@@ -0,0 +1,18 @@
+import { Icon as SurfaceIcon } from '@ankhorage/surface';
+import React from 'react';
+
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { IconProps } from '../../../../types/icon';
+
+/*** Adapts the themed Surface Icon primitive to ZORA scope and interaction props. */
+export const Icon = withZoraThemeScope(IconInner);
+
+/*** Forwards presentation props to the published Surface boundary. */
+function IconInner({
+  themeId: _themeId,
+  mode: _mode,
+  interactionPolicy: _interactionPolicy,
+  ...props
+}: IconProps) {
+  return <SurfaceIcon {...props} />;
+}

package/src/features/icon/public.ts

@@ -0,0 +1,2 @@
+export type { IconProps } from '../../types/icon';
+export { Icon } from './adapters/inbound/Icon';

package/src/features/icon/utils/meta.test.ts

@@ -0,0 +1,22 @@
+import { expect, test } from 'bun:test';
+
+import { ZORA_COMPONENT_META } from '../../../metadata/componentMeta';
+
+test('permits media-backed Icon and Image content in ordinary screen containers', () => {
+  const icon = ZORA_COMPONENT_META.Icon;
+  expect(icon.directManifestNode).toBe(true);
+  expect(icon.allowedChildren).toEqual([]);
+  expect(icon.props.source).toMatchObject({ type: 'media', mediaKinds: ['image'] });
+  for (const container of [
+    ZORA_COMPONENT_META.Box,
+    ZORA_COMPONENT_META.Stack,
+    ZORA_COMPONENT_META.Grid,
+    ZORA_COMPONENT_META.Container,
+    ZORA_COMPONENT_META.Card,
+    ZORA_COMPONENT_META.Screen,
+    ZORA_COMPONENT_META.ScreenSection,
+  ]) {
+    expect(container.allowedChildren).toContain('Icon');
+    expect(container.allowedChildren).toContain('Image');
+  }
+});