@ankhorage/zora 4.2.2 → 4.4.0

package/dist/pluginComposition.js

@@ -0,0 +1,153 @@
+/*** Report one deterministic plugin composition contract violation. */
+export class ZoraPluginCompositionError extends Error {
+    code;
+    packageName;
+    componentName;
+    constructor(args) {
+        super(args.message);
+        this.name = 'ZoraPluginCompositionError';
+        this.code = args.code;
+        this.packageName = args.packageName;
+        this.componentName = args.componentName;
+    }
+}
+/*** Compose a selected ZORA metadata set for authoring tools that must not load React Native runtime modules. */
+export function composeZoraPluginMetadata(plugins) {
+    const descriptors = sortPlugins(plugins);
+    const packages = new Set();
+    const componentOwners = new Map();
+    const componentMeta = new Map();
+    const extensionHosts = new Set();
+    const interactionPolicySupportedComponents = new Set();
+    for (const descriptor of descriptors) {
+        validateUniquePackage(descriptor, packages);
+        validateMetadata(descriptor);
+        for (const [componentName, meta] of sortedEntries(descriptor.componentMeta)) {
+            claimComponent(componentName, descriptor.packageName, componentOwners);
+            componentMeta.set(componentName, meta);
+        }
+        for (const componentName of descriptor.extensionHosts ?? [])
+            extensionHosts.add(componentName);
+        for (const componentName of descriptor.interactionPolicySupportedComponents ?? []) {
+            interactionPolicySupportedComponents.add(componentName);
+        }
+    }
+    for (const descriptor of descriptors) {
+        for (const placement of descriptor.placements ?? []) {
+            applyPlacement({ descriptor, placement, componentMeta, extensionHosts });
+        }
+    }
+    return {
+        componentMeta: Object.fromEntries(componentMeta),
+        bindableComponentMeta: Object.fromEntries(componentMeta),
+        packageManifests: descriptors.map(({ packageName, displayName, componentMeta }) => ({
+            packageName,
+            ...(displayName === undefined ? {} : { displayName }),
+            components: componentMeta,
+        })),
+        interactionPolicySupportedComponents: Object.fromEntries([...interactionPolicySupportedComponents]
+            .sort()
+            .map((componentName) => [componentName, true])),
+    };
+}
+/*** Compose a selected ZORA core/plugin descriptor set into one validated authoring/runtime catalog. */
+export function composeZoraPlugins(plugins) {
+    const descriptors = sortPlugins(plugins);
+    const componentRegistry = new Map();
+    for (const descriptor of descriptors) {
+        validateRuntime(descriptor);
+        for (const [componentName, component] of sortedEntries(descriptor.componentRegistry)) {
+            componentRegistry.set(componentName, component);
+        }
+    }
+    const metadataCatalog = composeZoraPluginMetadata(descriptors);
+    return { ...metadataCatalog, componentRegistry: Object.fromEntries(componentRegistry) };
+}
+function validateUniquePackage(descriptor, packages) {
+    if (packages.has(descriptor.packageName)) {
+        throw compositionError('duplicate-package', descriptor.packageName, `Duplicate ZORA plugin package '${descriptor.packageName}'.`);
+    }
+    packages.add(descriptor.packageName);
+}
+function validateMetadata(descriptor) {
+    for (const [componentName, meta] of sortedEntries(descriptor.componentMeta)) {
+        if (meta.name !== componentName) {
+            throw compositionError('invalid-component-meta', descriptor.packageName, `ZORA plugin '${descriptor.packageName}' metadata key '${componentName}' does not match meta.name '${meta.name}'.`, componentName);
+        }
+    }
+}
+function validateRuntime(descriptor) {
+    const componentMetaNames = new Set(Object.keys(descriptor.componentMeta));
+    const runtimeComponentNames = new Set(Object.keys(descriptor.componentRegistry));
+    for (const componentName of sortedKeys(descriptor.componentRegistry)) {
+        if (!componentMetaNames.has(componentName)) {
+            throw compositionError('missing-component-meta', descriptor.packageName, `ZORA plugin '${descriptor.packageName}' registers runtime component '${componentName}' without component metadata.`, componentName);
+        }
+    }
+    for (const [componentName, meta] of sortedEntries(descriptor.componentMeta)) {
+        if (meta.directManifestNode && !runtimeComponentNames.has(componentName)) {
+            throw compositionError('missing-runtime-component', descriptor.packageName, `ZORA plugin '${descriptor.packageName}' exposes direct manifest node '${componentName}' without a runtime component.`, componentName);
+        }
+    }
+    for (const componentName of descriptor.interactionPolicySupportedComponents ?? []) {
+        if (!runtimeComponentNames.has(componentName)) {
+            throw compositionError('invalid-interaction-policy-component', descriptor.packageName, `ZORA plugin '${descriptor.packageName}' declares interaction-policy support for unregistered component '${componentName}'.`, componentName);
+        }
+    }
+}
+function claimComponent(componentName, packageName, owners) {
+    const existingOwner = owners.get(componentName);
+    if (existingOwner) {
+        throw compositionError('duplicate-component', packageName, `ZORA component '${componentName}' is owned by both '${existingOwner}' and '${packageName}'.`, componentName);
+    }
+    owners.set(componentName, packageName);
+}
+function applyPlacement(args) {
+    const { descriptor, placement, componentMeta, extensionHosts } = args;
+    const childMeta = descriptor.componentMeta[placement.child];
+    if (!childMeta?.directManifestNode) {
+        throw compositionError('invalid-placement-child', descriptor.packageName, `ZORA plugin '${descriptor.packageName}' placement child '${placement.child}' is not an owned direct manifest node.`, placement.child);
+    }
+    for (const parentName of [...placement.parents].sort()) {
+        const parentMeta = componentMeta.get(parentName);
+        if (!parentMeta || !extensionHosts.has(parentName)) {
+            throw compositionError('invalid-placement-parent', descriptor.packageName, `ZORA plugin '${descriptor.packageName}' placement parent '${parentName}' is not a declared extension host.`, placement.child);
+        }
+        componentMeta.set(parentName, addAllowedChild(parentMeta, placement.child));
+    }
+}
+function addAllowedChild(meta, child) {
+    const allowedChildren = appendUnique(meta.allowedChildren, child);
+    const childrenSlot = meta.slots?.children;
+    return {
+        ...meta,
+        allowedChildren,
+        ...(childrenSlot
+            ? {
+                slots: {
+                    ...meta.slots,
+                    children: {
+                        ...childrenSlot,
+                        allowedChildren: appendUnique(childrenSlot.allowedChildren ?? [], child),
+                    },
+                },
+            }
+            : {}),
+    };
+}
+function appendUnique(values, value) {
+    return values.includes(value) ? values : [...values, value];
+}
+function sortedKeys(value) {
+    return Object.keys(value).sort();
+}
+function sortedEntries(value) {
+    return Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+}
+function sortPlugins(plugins) {
+    return [...plugins].sort((left, right) => left.packageName.localeCompare(right.packageName));
+}
+function compositionError(code, packageName, message, componentName) {
+    return new ZoraPluginCompositionError({ code, packageName, message, componentName });
+}
+//# sourceMappingURL=pluginComposition.js.map

package/dist/pluginComposition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginComposition.js","sourceRoot":"","sources":["../src/pluginComposition.ts"],"names":[],"mappings":"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","sourcesContent":["import type { UiComponentMetaRegistry, UiComponentPackageManifest } from '@ankhorage/contracts';\n\nimport type { ZoraComponentMeta, ZoraComponentMetaRegistry } from './metadata/types';\nimport type { ZoraComponentRegistry } from './registry';\n\nexport type ZoraPluginCompositionErrorCode =\n  | 'duplicate-component'\n  | 'duplicate-package'\n  | 'invalid-component-meta'\n  | 'invalid-interaction-policy-component'\n  | 'invalid-placement-child'\n  | 'invalid-placement-parent'\n  | 'missing-component-meta'\n  | 'missing-runtime-component';\n\nexport interface ZoraPluginPlacement {\n  readonly child: string;\n  readonly parents: readonly string[];\n}\n\nexport interface ZoraPluginMetadata {\n  readonly packageName: string;\n  readonly displayName?: string;\n  readonly componentMeta: ZoraComponentMetaRegistry;\n  readonly extensionHosts?: readonly string[];\n  readonly placements?: readonly ZoraPluginPlacement[];\n  readonly interactionPolicySupportedComponents?: readonly string[];\n}\n\nexport interface ZoraPluginDescriptor extends ZoraPluginMetadata {\n  readonly componentRegistry: ZoraComponentRegistry;\n}\n\nexport interface ComposedZoraPluginMetadataCatalog {\n  readonly componentMeta: ZoraComponentMetaRegistry;\n  readonly bindableComponentMeta: UiComponentMetaRegistry;\n  readonly packageManifests: readonly UiComponentPackageManifest[];\n  readonly interactionPolicySupportedComponents: Readonly<Record<string, true>>;\n}\n\nexport interface ComposedZoraPluginCatalog extends ComposedZoraPluginMetadataCatalog {\n  readonly componentRegistry: ZoraComponentRegistry;\n}\n\n/*** Report one deterministic plugin composition contract violation. */\nexport class ZoraPluginCompositionError extends Error {\n  readonly code: ZoraPluginCompositionErrorCode;\n  readonly packageName: string;\n  readonly componentName?: string;\n\n  constructor(args: {\n    readonly code: ZoraPluginCompositionErrorCode;\n    readonly packageName: string;\n    readonly message: string;\n    readonly componentName?: string;\n  }) {\n    super(args.message);\n    this.name = 'ZoraPluginCompositionError';\n    this.code = args.code;\n    this.packageName = args.packageName;\n    this.componentName = args.componentName;\n  }\n}\n\n/*** Compose a selected ZORA metadata set for authoring tools that must not load React Native runtime modules. */\nexport function composeZoraPluginMetadata(\n  plugins: readonly ZoraPluginMetadata[],\n): ComposedZoraPluginMetadataCatalog {\n  const descriptors = sortPlugins(plugins);\n  const packages = new Set<string>();\n  const componentOwners = new Map<string, string>();\n  const componentMeta = new Map<string, ZoraComponentMeta>();\n  const extensionHosts = new Set<string>();\n  const interactionPolicySupportedComponents = new Set<string>();\n\n  for (const descriptor of descriptors) {\n    validateUniquePackage(descriptor, packages);\n    validateMetadata(descriptor);\n    for (const [componentName, meta] of sortedEntries(descriptor.componentMeta)) {\n      claimComponent(componentName, descriptor.packageName, componentOwners);\n      componentMeta.set(componentName, meta);\n    }\n    for (const componentName of descriptor.extensionHosts ?? []) extensionHosts.add(componentName);\n    for (const componentName of descriptor.interactionPolicySupportedComponents ?? []) {\n      interactionPolicySupportedComponents.add(componentName);\n    }\n  }\n\n  for (const descriptor of descriptors) {\n    for (const placement of descriptor.placements ?? []) {\n      applyPlacement({ descriptor, placement, componentMeta, extensionHosts });\n    }\n  }\n\n  return {\n    componentMeta: Object.fromEntries(componentMeta),\n    bindableComponentMeta: Object.fromEntries(componentMeta),\n    packageManifests: descriptors.map(({ packageName, displayName, componentMeta }) => ({\n      packageName,\n      ...(displayName === undefined ? {} : { displayName }),\n      components: componentMeta,\n    })),\n    interactionPolicySupportedComponents: Object.fromEntries(\n      [...interactionPolicySupportedComponents]\n        .sort()\n        .map((componentName) => [componentName, true]),\n    ),\n  };\n}\n\n/*** Compose a selected ZORA core/plugin descriptor set into one validated authoring/runtime catalog. */\nexport function composeZoraPlugins(\n  plugins: readonly ZoraPluginDescriptor[],\n): ComposedZoraPluginCatalog {\n  const descriptors = sortPlugins(plugins);\n  const componentRegistry = new Map<string, ZoraComponentRegistry[string]>();\n\n  for (const descriptor of descriptors) {\n    validateRuntime(descriptor);\n    for (const [componentName, component] of sortedEntries(descriptor.componentRegistry)) {\n      componentRegistry.set(componentName, component);\n    }\n  }\n  const metadataCatalog = composeZoraPluginMetadata(descriptors);\n\n  return { ...metadataCatalog, componentRegistry: Object.fromEntries(componentRegistry) };\n}\n\nfunction validateUniquePackage(descriptor: ZoraPluginMetadata, packages: Set<string>): void {\n  if (packages.has(descriptor.packageName)) {\n    throw compositionError(\n      'duplicate-package',\n      descriptor.packageName,\n      `Duplicate ZORA plugin package '${descriptor.packageName}'.`,\n    );\n  }\n  packages.add(descriptor.packageName);\n}\n\nfunction validateMetadata(descriptor: ZoraPluginMetadata): void {\n  for (const [componentName, meta] of sortedEntries(descriptor.componentMeta)) {\n    if (meta.name !== componentName) {\n      throw compositionError(\n        'invalid-component-meta',\n        descriptor.packageName,\n        `ZORA plugin '${descriptor.packageName}' metadata key '${componentName}' does not match meta.name '${meta.name}'.`,\n        componentName,\n      );\n    }\n  }\n}\n\nfunction validateRuntime(descriptor: ZoraPluginDescriptor): void {\n  const componentMetaNames = new Set(Object.keys(descriptor.componentMeta));\n  const runtimeComponentNames = new Set(Object.keys(descriptor.componentRegistry));\n  for (const componentName of sortedKeys(descriptor.componentRegistry)) {\n    if (!componentMetaNames.has(componentName)) {\n      throw compositionError(\n        'missing-component-meta',\n        descriptor.packageName,\n        `ZORA plugin '${descriptor.packageName}' registers runtime component '${componentName}' without component metadata.`,\n        componentName,\n      );\n    }\n  }\n  for (const [componentName, meta] of sortedEntries(descriptor.componentMeta)) {\n    if (meta.directManifestNode && !runtimeComponentNames.has(componentName)) {\n      throw compositionError(\n        'missing-runtime-component',\n        descriptor.packageName,\n        `ZORA plugin '${descriptor.packageName}' exposes direct manifest node '${componentName}' without a runtime component.`,\n        componentName,\n      );\n    }\n  }\n  for (const componentName of descriptor.interactionPolicySupportedComponents ?? []) {\n    if (!runtimeComponentNames.has(componentName)) {\n      throw compositionError(\n        'invalid-interaction-policy-component',\n        descriptor.packageName,\n        `ZORA plugin '${descriptor.packageName}' declares interaction-policy support for unregistered component '${componentName}'.`,\n        componentName,\n      );\n    }\n  }\n}\n\nfunction claimComponent(\n  componentName: string,\n  packageName: string,\n  owners: Map<string, string>,\n): void {\n  const existingOwner = owners.get(componentName);\n  if (existingOwner) {\n    throw compositionError(\n      'duplicate-component',\n      packageName,\n      `ZORA component '${componentName}' is owned by both '${existingOwner}' and '${packageName}'.`,\n      componentName,\n    );\n  }\n  owners.set(componentName, packageName);\n}\n\nfunction applyPlacement(args: {\n  descriptor: ZoraPluginMetadata;\n  placement: ZoraPluginPlacement;\n  componentMeta: Map<string, ZoraComponentMeta>;\n  extensionHosts: ReadonlySet<string>;\n}): void {\n  const { descriptor, placement, componentMeta, extensionHosts } = args;\n  const childMeta = descriptor.componentMeta[placement.child];\n  if (!childMeta?.directManifestNode) {\n    throw compositionError(\n      'invalid-placement-child',\n      descriptor.packageName,\n      `ZORA plugin '${descriptor.packageName}' placement child '${placement.child}' is not an owned direct manifest node.`,\n      placement.child,\n    );\n  }\n  for (const parentName of [...placement.parents].sort()) {\n    const parentMeta = componentMeta.get(parentName);\n    if (!parentMeta || !extensionHosts.has(parentName)) {\n      throw compositionError(\n        'invalid-placement-parent',\n        descriptor.packageName,\n        `ZORA plugin '${descriptor.packageName}' placement parent '${parentName}' is not a declared extension host.`,\n        placement.child,\n      );\n    }\n    componentMeta.set(parentName, addAllowedChild(parentMeta, placement.child));\n  }\n}\n\nfunction addAllowedChild(meta: ZoraComponentMeta, child: string): ZoraComponentMeta {\n  const allowedChildren = appendUnique(meta.allowedChildren, child);\n  const childrenSlot = meta.slots?.children;\n  return {\n    ...meta,\n    allowedChildren,\n    ...(childrenSlot\n      ? {\n          slots: {\n            ...meta.slots,\n            children: {\n              ...childrenSlot,\n              allowedChildren: appendUnique(childrenSlot.allowedChildren ?? [], child),\n            },\n          },\n        }\n      : {}),\n  };\n}\n\nfunction appendUnique(values: readonly string[], value: string): readonly string[] {\n  return values.includes(value) ? values : [...values, value];\n}\n\nfunction sortedKeys(value: Readonly<Record<string, unknown>>): string[] {\n  return Object.keys(value).sort();\n}\n\nfunction sortedEntries<T>(value: Readonly<Record<string, T>>): [string, T][] {\n  return Object.entries(value).sort(([left], [right]) => left.localeCompare(right));\n}\n\nfunction sortPlugins<T extends ZoraPluginMetadata>(plugins: readonly T[]): T[] {\n  return [...plugins].sort((left, right) => left.packageName.localeCompare(right.packageName));\n}\n\nfunction compositionError(\n  code: ZoraPluginCompositionErrorCode,\n  packageName: string,\n  message: string,\n  componentName?: string,\n): ZoraPluginCompositionError {\n  return new ZoraPluginCompositionError({ code, packageName, message, componentName });\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/zora",
   "type": "module",
-  "version": "4.2.2",
+  "version": "4.4.0",
   "description": "Opinionated React Native and React Native Web UI kit built on @ankhorage/surface.",
   "homepage": "https://github.com/ankhorage/zora#readme",
   "bugs": {
@@ -38,8 +38,8 @@
   },
   "dependencies": {
     "@ankhorage/color-theory": "^0.3.0",
-    "@ankhorage/contracts": "^11.0.0",
-    "@ankhorage/surface": "^3.4.1"
+    "@ankhorage/contracts": "^12.0.1",
+    "@ankhorage/surface": "^3.4.4"
   },
   "files": [
     "dist",
@@ -95,14 +95,14 @@
     "version-packages": "ankhorage-changeset version"
   },
   "devDependencies": {
-    "@ankhorage/devtools": "^1.10.4",
+    "@ankhorage/devtools": "^1.13.0",
     "@ankhorage/paradox": "^0.1.24",
     "@react-native-picker/picker": "2.11.4",
     "@react-native-vector-icons/fontawesome": "^13.1.3",
     "@react-native-vector-icons/fontawesome5": "^13.1.3",
     "@react-native-vector-icons/fontawesome6": "^13.1.3",
     "@react-native-vector-icons/ionicons": "^13.1.3",
-    "@types/bun": "^1.4.0",
+    "@types/bun": "^1.4.1",
     "@types/node": "^24.13.3",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",
@@ -116,5 +116,5 @@
     "react-native-web": "~0.21.0",
     "typescript": "~6.0.3"
   },
-  "packageManager": "bun@1.4.0"
+  "packageManager": "bun@1.4.2"
 }

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

@@ -0,0 +1,31 @@
+import { expect, test } from 'bun:test';
+
+import { resolveRadioGroupThemeRecipe } from './resolveRadioGroupThemeRecipe';
+
+test('resolves RadioGroup theme defaults while preserving instance overrides', () => {
+  expect(resolveRadioGroupThemeRecipe({ themeFields: {} })).toEqual({
+    gap: 's',
+    color: 'primary',
+    size: 'm',
+  });
+
+  expect(
+    resolveRadioGroupThemeRecipe({
+      gap: 'l',
+      color: 'danger',
+      size: 's',
+      themeFields: { gap: 'xs', color: 'secondary', size: 'l' },
+    }),
+  ).toEqual({ gap: 'l', color: 'danger', size: 's' });
+});
+
+test('card presentation stays on the RadioGroup and Surface Radio semantic path', async () => {
+  const source = await Bun.file('src/components/radio/RadioGroup.tsx').text();
+
+  expect(source).toContain('accessibilityRole="radiogroup"');
+  expect(source).toContain('checked={value === option.value}');
+  expect(source).toContain('<Radio');
+  expect(source).toContain("const isCard = presentation === 'card';");
+  expect(source).not.toContain('<Button');
+  expect(source).not.toContain('SelectableItem');
+});

package/src/components/radio/RadioGroup.tsx

@@ -1,12 +1,17 @@
-import { Radio } from '@ankhorage/surface';
+import { Radio, useTheme } from '@ankhorage/surface';
 import React from 'react';
 import { View } from 'react-native';
 
 import { Stack } from '../../foundation';
+import { useZoraThemeRecipe } from '../../theme/useZoraThemeRecipe';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { Text } from '../text';
+import { resolveRadioGroupThemeRecipe } from './resolveRadioGroupThemeRecipe';
 import type { RadioGroupOption, RadioGroupProps } from './types';
 
+/***
+ * Resolves the themed radio-group presentation within the active ZORA scope.
+ */
 function RadioGroupInner<TValue extends string>({
   themeId: _themeId,
   mode: _mode,
@@ -14,9 +19,10 @@ function RadioGroupInner<TValue extends string>({
   onValueChange,
   options,
   orientation = 'vertical',
-  gap = 's',
-  color = 'primary',
-  size = 'm',
+  gap,
+  presentation = 'inline',
+  color,
+  size,
   invalid = false,
   readOnly = false,
   disabled = false,
@@ -24,6 +30,8 @@ function RadioGroupInner<TValue extends string>({
   interactionPolicy,
 }: RadioGroupProps<TValue>) {
   const isHorizontal = orientation === 'horizontal';
+  const themeFields = useZoraThemeRecipe('RadioGroup');
+  const recipe = resolveRadioGroupThemeRecipe({ gap, color, size, themeFields });
 
   return (
     <View
@@ -36,7 +44,7 @@ function RadioGroupInner<TValue extends string>({
     >
       <Stack
         direction={isHorizontal ? 'row' : 'column'}
-        gap={gap}
+        gap={recipe.gap}
         wrap={isHorizontal ? 'wrap' : 'nowrap'}
       >
         {options.map((option) => (
@@ -47,8 +55,10 @@ function RadioGroupInner<TValue extends string>({
             disabled={disabled || option.disabled === true}
             invalid={invalid}
             readOnly={readOnly}
-            size={size}
-            color={color}
+            size={recipe.size}
+            color={recipe.color}
+            orientation={orientation}
+            presentation={presentation}
             onSelect={onValueChange}
             interactionPolicy={interactionPolicy}
           />
@@ -63,6 +73,9 @@ function RadioGroupInner<TValue extends string>({
  */
 export const RadioGroup = withZoraThemeScope(RadioGroupInner);
 
+/***
+ * Renders one option through the single Surface Radio interaction boundary.
+ */
 function RadioGroupItem<TValue extends string>({
   option,
   checked,
@@ -71,6 +84,8 @@ function RadioGroupItem<TValue extends string>({
   readOnly,
   size,
   color,
+  orientation,
+  presentation,
   onSelect,
   interactionPolicy,
 }: {
@@ -81,10 +96,14 @@ function RadioGroupItem<TValue extends string>({
   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';
 
   return (
     <Radio
@@ -96,13 +115,31 @@ function RadioGroupItem<TValue extends string>({
       size={size}
       color={color}
       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);
       }}
     >
       <Stack gap="xs">
-        <Text>{option.label}</Text>
+        <Text weight={isCard ? 'semiBold' : undefined}>{option.label}</Text>
         {option.description ? (
           <Text emphasis="muted" variant="caption">
             {option.description}

package/src/components/radio/meta.ts

@@ -1,19 +1,185 @@
+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: false,
   allowedChildren: [],
-  note: 'Form control component; not represented as a manifest node in v1.',
+  note: 'Composition-level radio control; author repeated single-choice UI through RadioGroup.',
   props: {},
 } as const satisfies ZoraComponentMeta;
 
 export const radioGroupMeta = {
   name: 'RadioGroup',
   category: 'component',
-  directManifestNode: false,
+  description:
+    'Single-choice group with inline or card presentation while preserving radio semantics.',
+  directManifestNode: true,
   allowedChildren: [],
-  note: 'Form control component; not represented as a manifest node in v1.',
-  props: {},
+  blueprint: {
+    label: 'Radio group',
+    defaultProps: {
+      value: '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',
+      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: {
+    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: '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' },
+    },
+    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/components/radio/resolveRadioGroupThemeRecipe.ts

@@ -0,0 +1,45 @@
+import type { ThemeRecipeOverrideValue } from '@ankhorage/contracts';
+
+import type { ZoraColor } from '../../internal/colorModel';
+import type { RadioGroupProps } from './types';
+
+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/components/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/components/radio/types.ts

@@ -25,4 +25,5 @@ export interface RadioGroupProps<TValue extends string>
   options: readonly RadioGroupOption<TValue>[];
   orientation?: 'horizontal' | 'vertical';
   gap?: 'xs' | 's' | 'm' | 'l';
+  presentation?: 'inline' | 'card';
 }