@ankhorage/zora 4.2.2 → 4.4.0

package/src/corePlugin.ts

@@ -0,0 +1,9 @@
+import { ZORA_CORE_PLUGIN_METADATA } from './corePluginMetadata';
+import type { ZoraPluginDescriptor } from './pluginComposition';
+import { ZORA_COMPONENT_REGISTRY } from './registry';
+
+/*** Describe the complete ZORA core runtime and authoring surface through the public plugin contract. */
+export const ZORA_CORE_PLUGIN: ZoraPluginDescriptor = {
+  ...ZORA_CORE_PLUGIN_METADATA,
+  componentRegistry: ZORA_COMPONENT_REGISTRY,
+};

package/src/corePluginMetadata.ts

@@ -0,0 +1,44 @@
+import type { UiComponentMetaRegistry } from '@ankhorage/contracts';
+
+import { ZORA_BINDABLE_COMPONENT_META } from './metadata/bindableComponentMeta';
+import { ZORA_COMPONENT_META } from './metadata/componentMeta';
+import type { ZoraComponentMetaRegistry } from './metadata/types';
+import type { ZoraPluginMetadata } from './pluginComposition';
+
+const CORE_EXTENSION_HOSTS = [
+  'Box',
+  'Card',
+  'Container',
+  'Grid',
+  'MessageBubble',
+  'Notice',
+  'Panel',
+  'PostCard',
+  'Screen',
+  'ScreenSection',
+  'Stack',
+] as const;
+
+export const ZORA_CORE_PLUGIN_METADATA: ZoraPluginMetadata = {
+  packageName: '@ankhorage/zora',
+  displayName: 'ZORA',
+  componentMeta: mergeBindableMeta(ZORA_COMPONENT_META, ZORA_BINDABLE_COMPONENT_META),
+  extensionHosts: CORE_EXTENSION_HOSTS,
+};
+
+function mergeBindableMeta(
+  componentMeta: ZoraComponentMetaRegistry,
+  bindableMeta: UiComponentMetaRegistry,
+): ZoraComponentMetaRegistry {
+  const bindingsByComponent = new Map(
+    Object.entries(bindableMeta).map(([componentName, meta]) => [componentName, meta.bindings]),
+  );
+  return Object.fromEntries(
+    Object.entries(componentMeta).map(([componentName, meta]) => [
+      componentName,
+      bindingsByComponent.get(componentName)
+        ? { ...meta, bindings: bindingsByComponent.get(componentName) }
+        : meta,
+    ]),
+  );
+}

package/src/index.ts

@@ -156,6 +156,8 @@ export type { ToastOptions, ToastProps, ToastProviderProps, ToastStatus } from '
 export { Toast, ToastProvider, useToast } from './components/toast';
 export type { ToolbarActionProps, ToolbarPosition, ToolbarProps } from './components/toolbar';
 export { Toolbar, ToolbarAction } from './components/toolbar';
+export { ZORA_CORE_PLUGIN } from './corePlugin';
+export { ZORA_CORE_PLUGIN_METADATA } from './corePluginMetadata';
 export type {
   BoxProps,
   CenterProps,
@@ -398,6 +400,19 @@ export type { ZoraDrawerContentProps } from './patterns/zora-drawer-content';
 export { ZoraDrawerContent } from './patterns/zora-drawer-content';
 export type { ZoraTabBarProps } from './patterns/zora-tab-bar';
 export { ZoraTabBar } from './patterns/zora-tab-bar';
+export type {
+  ComposedZoraPluginCatalog,
+  ComposedZoraPluginMetadataCatalog,
+  ZoraPluginCompositionErrorCode,
+  ZoraPluginDescriptor,
+  ZoraPluginMetadata,
+  ZoraPluginPlacement,
+} from './pluginComposition';
+export {
+  composeZoraPluginMetadata,
+  composeZoraPlugins,
+  ZoraPluginCompositionError,
+} from './pluginComposition';
 export type { ZoraComponentRegistry } from './registry';
 export { ZORA_COMPONENT_REGISTRY } from './registry';
 export * from './theme';

package/src/metadata/componentMeta.test.ts

@@ -126,6 +126,7 @@ describe('ZORA_COMPONENT_META invariants', () => {
       'EmptyState',
       'Hero',
       'Button',
+      'RadioGroup',
       'ThemeModeToggle',
       'Input',
       'Textarea',
@@ -198,6 +199,26 @@ describe('ZORA_COMPONENT_META invariants', () => {
     expect(ZORA_COMPONENT_META.Image.props.alt?.authoring).toEqual({ authority: 'instance' });
   });
 
+  test('RadioGroup is a direct manifest leaf with card presentation and normalized value events', () => {
+    const radioGroup = ZORA_COMPONENT_META.RadioGroup;
+
+    expect(radioGroup.directManifestNode).toBe(true);
+    expect(radioGroup.allowedChildren).toEqual([]);
+    expect(radioGroup.props.presentation?.enum).toEqual(['inline', 'card']);
+    expect(radioGroup.props.options?.type).toBe('array');
+    expect(radioGroup.props.options?.itemSchema?.map((item) => item.key)).toEqual([
+      'value',
+      'label',
+      'description',
+      'disabled',
+    ]);
+    expect(radioGroup.bindings?.props?.value?.value).toEqual({ type: 'string' });
+    expect(radioGroup.events?.valueChange?.eventType).toBe('radioGroup.valueChange');
+    expect(radioGroup.events?.valueChange?.payloadFields).toEqual([
+      { path: 'value', type: 'string', label: 'Value' },
+    ]);
+  });
+
   test('ThemeModeToggle is a direct manifest leaf with serializable defaults', () => {
     expect(ZORA_COMPONENT_META.ThemeModeToggle.directManifestNode).toBe(true);
     expect(ZORA_COMPONENT_META.ThemeModeToggle.allowedChildren).toEqual([]);

package/src/metadata/index.ts

@@ -1,3 +1,10 @@
+export { ZORA_CORE_PLUGIN_METADATA } from '../corePluginMetadata';
+export type {
+  ComposedZoraPluginMetadataCatalog,
+  ZoraPluginMetadata,
+  ZoraPluginPlacement,
+} from '../pluginComposition';
+export { composeZoraPluginMetadata, ZoraPluginCompositionError } from '../pluginComposition';
 export type { ZoraBindableComponentType } from './bindableComponentMeta';
 export { ZORA_BINDABLE_COMPONENT_META } from './bindableComponentMeta';
 export { ZORA_COMPONENT_META } from './componentMeta';

package/src/metadata/themeRecipeMeta.test.ts

@@ -11,6 +11,7 @@ describe('ZORA_THEME_RECIPE_META', () => {
       'Button',
       'Card',
       'Heading',
+      'RadioGroup',
       'Text',
       'Panel',
     ]);
@@ -50,6 +51,9 @@ describe('ZORA_THEME_RECIPE_META', () => {
   test('keeps recipe defaults aligned with existing runtime behavior', () => {
     expect(ZORA_THEME_RECIPE_META.Button?.fields.size?.default).toBe('l');
     expect(ZORA_THEME_RECIPE_META.Card?.fields.padding?.default).toBeUndefined();
+    expect(ZORA_THEME_RECIPE_META.RadioGroup?.fields.gap?.default).toBe('s');
+    expect(ZORA_THEME_RECIPE_META.RadioGroup?.fields.color?.default).toBe('primary');
+    expect(ZORA_THEME_RECIPE_META.RadioGroup?.fields.size?.default).toBe('m');
     expect(ZORA_THEME_RECIPE_META.Text?.fields.weight?.default).toBeUndefined();
     expect(ZORA_THEME_RECIPE_META.Heading?.fields.size?.default).toBeUndefined();
   });

package/src/metadata/themeRecipeMeta.ts

@@ -1,6 +1,7 @@
 import { buttonThemeRecipeMeta } from '../components/button/themeRecipeMeta';
 import { cardThemeRecipeMeta } from '../components/card/themeRecipeMeta';
 import { headingThemeRecipeMeta } from '../components/heading/themeRecipeMeta';
+import { radioGroupThemeRecipeMeta } from '../components/radio/themeRecipeMeta';
 import { textThemeRecipeMeta } from '../components/text/themeRecipeMeta';
 import { panelThemeRecipeMeta } from '../patterns/panel/themeRecipeMeta';
 import type { ZoraThemeRecipeMetaRegistry } from './themeRecipeTypes';
@@ -9,6 +10,7 @@ export const ZORA_THEME_RECIPE_META: ZoraThemeRecipeMetaRegistry = {
   Button: buttonThemeRecipeMeta,
   Card: cardThemeRecipeMeta,
   Heading: headingThemeRecipeMeta,
+  RadioGroup: radioGroupThemeRecipeMeta,
   Text: textThemeRecipeMeta,
   Panel: panelThemeRecipeMeta,
 };

package/src/metadata/types.ts

@@ -2,6 +2,7 @@ import type {
   ComponentEventDtoKind,
   ComponentRequirements,
   MediaAssetKind,
+  UiComponentBindingMeta,
   UiComponentPropType,
 } from '@ankhorage/contracts';
 
@@ -86,6 +87,7 @@ export interface ZoraComponentMeta {
   description?: string;
   directManifestNode: boolean;
   allowedChildren: readonly string[];
+  bindings?: UiComponentBindingMeta;
   manifestPolicy?: ZoraComponentManifestPolicy;
   requirements?: ComponentRequirements;
   blueprint?: ZoraComponentBlueprint;

package/src/pluginComposition.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { ZoraComponentMeta } from './metadata';
+import {
+  composeZoraPlugins,
+  ZoraPluginCompositionError,
+  type ZoraPluginDescriptor,
+} from './pluginComposition';
+
+const pluginLeafMeta: ZoraComponentMeta = {
+  name: 'PluginLeaf',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: { label: 'Plugin leaf' },
+  bindings: {
+    props: {
+      value: { value: { type: 'string' } },
+    },
+  },
+  props: {
+    value: { type: 'string', category: 'Content', authoring: { authority: 'instance' } },
+  },
+};
+
+const PluginLeaf = () => null;
+
+const Host = () => null;
+
+const core = {
+  packageName: '@example/core',
+  componentRegistry: { Host },
+  componentMeta: {
+    Host: {
+      name: 'Host',
+      category: 'layout',
+      directManifestNode: true,
+      allowedChildren: [],
+      props: {},
+    },
+  },
+  extensionHosts: ['Host'],
+} satisfies ZoraPluginDescriptor;
+
+const plugin = {
+  packageName: '@example/zora-plugin',
+  displayName: 'Example plugin',
+  componentRegistry: { PluginLeaf },
+  componentMeta: { PluginLeaf: pluginLeafMeta },
+  placements: [{ child: 'PluginLeaf', parents: ['Host'] }],
+} satisfies ZoraPluginDescriptor;
+
+describe('composeZoraPlugins', () => {
+  test('composes runtime, authoring, binding, package, and placement projections', () => {
+    const catalog = composeZoraPlugins([core, plugin]);
+
+    expect(catalog.componentRegistry.PluginLeaf).toBe(PluginLeaf);
+    expect(catalog.componentMeta.PluginLeaf).toBe(pluginLeafMeta);
+    expect(catalog.bindableComponentMeta.PluginLeaf?.bindings).toEqual(pluginLeafMeta.bindings);
+    expect(catalog.componentMeta.Host.allowedChildren).toContain('PluginLeaf');
+    expect(catalog.packageManifests.map((entry) => entry.packageName)).toEqual([
+      '@example/core',
+      '@example/zora-plugin',
+    ]);
+  });
+
+  test('is deterministic regardless of plugin input order', () => {
+    const Alpha = () => null;
+    const alpha = createPlugin('@example/alpha', 'Alpha', Alpha);
+    const beta = createPlugin('@example/beta', 'Beta', () => null);
+
+    expect(Object.keys(composeZoraPlugins([core, beta, alpha]).componentMeta)).toEqual(
+      Object.keys(composeZoraPlugins([alpha, core, beta]).componentMeta),
+    );
+  });
+
+  test('rejects duplicate component ownership with a stable diagnostic code', () => {
+    const duplicate = createPlugin('@example/duplicate', 'Host', () => null);
+
+    expect(() => composeZoraPlugins([core, duplicate])).toThrow(ZoraPluginCompositionError);
+    try {
+      composeZoraPlugins([core, duplicate]);
+    } catch (error) {
+      expect(error).toMatchObject({
+        code: 'duplicate-component',
+        packageName: '@example/duplicate',
+        componentName: 'Host',
+      });
+    }
+  });
+
+  test('rejects runtime and metadata mismatches', () => {
+    const invalid = {
+      ...plugin,
+      packageName: '@example/invalid',
+      componentMeta: {},
+    } satisfies ZoraPluginDescriptor;
+
+    expectCompositionError(invalid, 'missing-component-meta');
+  });
+
+  test('rejects placement into components that did not opt in as extension hosts', () => {
+    const invalid = {
+      ...plugin,
+      packageName: '@example/invalid-placement',
+      placements: [{ child: 'PluginLeaf', parents: ['PluginLeaf'] }],
+    } satisfies ZoraPluginDescriptor;
+
+    expectCompositionError(invalid, 'invalid-placement-parent');
+  });
+});
+
+function createPlugin(
+  packageName: string,
+  componentName: string,
+  component: ZoraPluginDescriptor['componentRegistry'][string],
+): ZoraPluginDescriptor {
+  return {
+    packageName,
+    componentRegistry: { [componentName]: component },
+    componentMeta: {
+      [componentName]: {
+        ...pluginLeafMeta,
+        name: componentName,
+      },
+    },
+  };
+}
+
+function expectCompositionError(
+  descriptor: ZoraPluginDescriptor,
+  code: ZoraPluginCompositionError['code'],
+): void {
+  try {
+    composeZoraPlugins([core, descriptor]);
+    throw new Error('Expected plugin composition to fail.');
+  } catch (error) {
+    expect(error).toBeInstanceOf(ZoraPluginCompositionError);
+    expect(error).toMatchObject({ code });
+  }
+}

package/src/pluginComposition.ts

@@ -0,0 +1,278 @@
+import type { UiComponentMetaRegistry, UiComponentPackageManifest } from '@ankhorage/contracts';
+
+import type { ZoraComponentMeta, ZoraComponentMetaRegistry } from './metadata/types';
+import type { ZoraComponentRegistry } from './registry';
+
+export type ZoraPluginCompositionErrorCode =
+  | 'duplicate-component'
+  | 'duplicate-package'
+  | 'invalid-component-meta'
+  | 'invalid-interaction-policy-component'
+  | 'invalid-placement-child'
+  | 'invalid-placement-parent'
+  | 'missing-component-meta'
+  | 'missing-runtime-component';
+
+export interface ZoraPluginPlacement {
+  readonly child: string;
+  readonly parents: readonly string[];
+}
+
+export interface ZoraPluginMetadata {
+  readonly packageName: string;
+  readonly displayName?: string;
+  readonly componentMeta: ZoraComponentMetaRegistry;
+  readonly extensionHosts?: readonly string[];
+  readonly placements?: readonly ZoraPluginPlacement[];
+  readonly interactionPolicySupportedComponents?: readonly string[];
+}
+
+export interface ZoraPluginDescriptor extends ZoraPluginMetadata {
+  readonly componentRegistry: ZoraComponentRegistry;
+}
+
+export interface ComposedZoraPluginMetadataCatalog {
+  readonly componentMeta: ZoraComponentMetaRegistry;
+  readonly bindableComponentMeta: UiComponentMetaRegistry;
+  readonly packageManifests: readonly UiComponentPackageManifest[];
+  readonly interactionPolicySupportedComponents: Readonly<Record<string, true>>;
+}
+
+export interface ComposedZoraPluginCatalog extends ComposedZoraPluginMetadataCatalog {
+  readonly componentRegistry: ZoraComponentRegistry;
+}
+
+/*** Report one deterministic plugin composition contract violation. */
+export class ZoraPluginCompositionError extends Error {
+  readonly code: ZoraPluginCompositionErrorCode;
+  readonly packageName: string;
+  readonly componentName?: string;
+
+  constructor(args: {
+    readonly code: ZoraPluginCompositionErrorCode;
+    readonly packageName: string;
+    readonly message: string;
+    readonly componentName?: string;
+  }) {
+    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: readonly ZoraPluginMetadata[],
+): ComposedZoraPluginMetadataCatalog {
+  const descriptors = sortPlugins(plugins);
+  const packages = new Set<string>();
+  const componentOwners = new Map<string, string>();
+  const componentMeta = new Map<string, ZoraComponentMeta>();
+  const extensionHosts = new Set<string>();
+  const interactionPolicySupportedComponents = new Set<string>();
+
+  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: readonly ZoraPluginDescriptor[],
+): ComposedZoraPluginCatalog {
+  const descriptors = sortPlugins(plugins);
+  const componentRegistry = new Map<string, ZoraComponentRegistry[string]>();
+
+  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: ZoraPluginMetadata, packages: Set<string>): void {
+  if (packages.has(descriptor.packageName)) {
+    throw compositionError(
+      'duplicate-package',
+      descriptor.packageName,
+      `Duplicate ZORA plugin package '${descriptor.packageName}'.`,
+    );
+  }
+  packages.add(descriptor.packageName);
+}
+
+function validateMetadata(descriptor: ZoraPluginMetadata): void {
+  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: ZoraPluginDescriptor): void {
+  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: string,
+  packageName: string,
+  owners: Map<string, string>,
+): void {
+  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: {
+  descriptor: ZoraPluginMetadata;
+  placement: ZoraPluginPlacement;
+  componentMeta: Map<string, ZoraComponentMeta>;
+  extensionHosts: ReadonlySet<string>;
+}): void {
+  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: ZoraComponentMeta, child: string): ZoraComponentMeta {
+  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: readonly string[], value: string): readonly string[] {
+  return values.includes(value) ? values : [...values, value];
+}
+
+function sortedKeys(value: Readonly<Record<string, unknown>>): string[] {
+  return Object.keys(value).sort();
+}
+
+function sortedEntries<T>(value: Readonly<Record<string, T>>): [string, T][] {
+  return Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+}
+
+function sortPlugins<T extends ZoraPluginMetadata>(plugins: readonly T[]): T[] {
+  return [...plugins].sort((left, right) => left.packageName.localeCompare(right.packageName));
+}
+
+function compositionError(
+  code: ZoraPluginCompositionErrorCode,
+  packageName: string,
+  message: string,
+  componentName?: string,
+): ZoraPluginCompositionError {
+  return new ZoraPluginCompositionError({ code, packageName, message, componentName });
+}