@ouas/react

React SDK and Component Annotations for the OpenUI Adaptive Standard (OUAS).

This package provides the core developer utilities to annotate React components, define configurable fields, retrieve adaptive layout properties, and build polymorphic user interface components.

Installation

pnpm add @ouas/react
# or
npm install @ouas/react

Core Utilities

1. withOUAS (Higher-Order Component)

Wraps standard React components to register their adaptive parameters. It exposes their fields, slots, categorizations, and configurations to the static scanning CLI while safely routing runtime layout controls to the wrapped element.

2. useOUAS (React Hook)

A localized react hook that allows any component nested within an <OUASProvider /> to retrieve:

• The component's assigned layout state.
• The list of visible and hidden fields generated by the AI agent.
• Active layout variants and data properties.

API & Usage Examples

Annotating components with withOUAS

Wrap your component to declare which fields and variants are available for adaptation:

import React from 'react';
import { withOUAS } from '@ouas/react';

interface EmailRowProps {
  sender: string;
  subject?: string;
  preview?: string;
  priority?: 'high' | 'normal' | 'low';
}

function EmailRowComponent({ sender, subject, preview, priority }: EmailRowProps) {
  return (
    <div className="email-row">
      <div className="sender">{sender}</div>
      {subject && <div className="subject">{subject}</div>}
      {preview && <div className="preview">{preview}</div>}
      {priority && <span className={`badge ${priority}`}>{priority}</span>}
    </div>
  );
}

// Wrap the component with OUAS metadata
export const EmailRow = withOUAS(EmailRowComponent, {
  id: 'email-row',
  category: 'list-item',
  data_source: 'emails',
  variants: ['comfortable', 'compact'],
  fields: {
    sender: { type: 'string', required: true, label: 'Email sender name' },
    subject: { type: 'string', required: false, label: 'Email subject line' },
    preview: { type: 'string', required: false, label: 'Body message preview' },
    priority: { 
      type: 'enum', 
      required: false, 
      label: 'Priority badge',
      values: ['high', 'normal', 'low']
    }
  },
  slots: ['leading', 'trailing', 'actions']
});

Retrieving Active Adaptations with useOUAS

Inside components that need custom conditional rendering based on visible fields:

import React from 'react';
import { useOUAS } from '@ouas/react';

export function CustomHeader() {
  const { visibleFields, variant, theme } = useOUAS();

  return (
    <header style={{ color: theme?.accent_color || '#333' }}>
      <h2>Inbox ({variant === 'compact' ? 'Compact' : 'Detailed'})</h2>
      
      {visibleFields.includes('sender') && (
        <span className="info">Showing sender info</span>
      )}
    </header>
  );
}

License

MIT © OUAS Team