npm package: @openlearning/widget-framework
Description: Framework for building OpenLearning widgets with parent-window messaging and configuration management
Author: OpenLearning
Latest version: 1.2.5

# Widget Framework

A comprehensive framework for building OpenLearning widgets with reusable UI components, parent-window messaging, and configuration management.

## Features

- **Reusable UI Components**: Pre-built, accessible components following the OpenLearning design system
- **Parent Messaging**: Secure two-way communication between widgets and parent applications
- **Configuration Management**: Type-safe widget configuration and setup
- **TypeScript Support**: Full TypeScript support with comprehensive type definitions
- **Consistent Styling**: CSS-based theming with customizable color variables

## Installation

```bash
npm install @openlearning/widget-framework
```

## Quick Start

### 1. Create Your Widget Component

```typescript
import React from "react";
import { Button } from "@openlearning/widget-framework";
import "@openlearning/widget-framework/styles/button.css";

export function MyWidget() {
  return (
    <div>
      <h1>My First Widget</h1>
      <Button variant="round-filled">Get Started</Button>
    </div>
  );
}
```

### 2. Set Up the Learner View

```typescript
import { createLearnerEntry } from "@openlearning/widget-framework";
import MyWidget from "./MyWidget";

createLearnerEntry(MyWidget);
```

### 3. Set Up the Setup View

```typescript
import { createSetupEntry } from "@openlearning/widget-framework";
import MyWidgetSetup from "./MyWidgetSetup";

createSetupEntry(MyWidgetSetup, {
  // your default setup config
});
```

## Core Features

### UI Components

See [COMPONENTS.md](./COMPONENTS.md) for full component documentation.

### Development Tools

Use `DevApp` for development and testing:

```typescript
import { DevApp } from "@openlearning/widget-framework";

export default function App() {
  return (
    <DevApp
      LearnerViewComponent={MyLearnerWidget}
      SetupViewComponent={MySetupWidget}
      defaultConfig={{}}
    />
  );
}
```

## Project Setup

Define your widget project configuration:

```typescript
import { defineWidgetProject } from "@openlearning/widget-framework";

export const widgetConfig = defineWidgetProject({
  id: "my-widget", 
  name: "My Widget",
  version: "1.0.0",
  /* ... more config ... */
});
```

## Integration Guide

See [INTEGRATION_GUIDE.md](./INTEGRATION_GUIDE.md) for practical examples and common patterns.

## API Reference

### `createLearnerEntry(Component, defaultConfig?)`
Renders a component as the learner view of your widget.

**Parameters:**
- `Component` - Your LearnerView React component
- `defaultConfig` (optional) - Default configuration to use when no config exists

**Example:**
```typescript
createLearnerEntry(LearnerView, { /* your default config */ });
```

### `createSetupEntry(Component, defaultConfig)`
Renders a component as the setup/configuration view of your widget.

**Parameters:**
- `Component` - Your SetupView React component  
- `defaultConfig` - Default configuration to use when no config exists

## Internal APIs

### `useParentApi(defaultConfig?)`
Unified helper for setup data + parent messaging actions.

**Parameters:**
- `defaultConfig` (optional) - Used when init data has no config.

**Returns:**
- `setupData` - Current setup payload (or `null` until init)
- `sendReady()`
- `sendSet(name, value)`
- `sendResize(height)`
- `sendShare(attachments, thumbnail)`
- `sendComplete()`

### `useParentMessaging()`
Hook for parent-window communication.

**Signature:**
```typescript
useParentMessaging(onMessage: (message: ParentMessage) => void)
```

**Returns:** `{ sendMessage }`

### `DevApp(props)`
Development wrapper component for testing widget views.

### `defineWidgetProject(config)`
Defines widget project configuration.

### UI Components

#### Button

```typescript
import { Button } from "@openlearning/widget-framework";
import "@openlearning/widget-framework/styles/button.css";

<Button 
  variant="round-filled"
  size="medium"
  icon={<MyIcon />}
  iconPosition="left"
  isLoading={false}
  fullWidth={false}
  onClick={handleClick}
>
  Click Me
</Button>
```

## TypeScript Support

Full TypeScript support with type definitions:

```typescript
import { 
  Button,
  type ButtonProps,
  type LearnerViewProps,
  type WidgetConfigBase 
} from "@openlearning/widget-framework";
```

## Browser Support

- Chrome/Edge (latest 2 versions)
- Firefox (latest 2 versions)
- Safari (latest 2 versions)
- iOS Safari 12+
- Android 5+

## Contributing

Contributions are welcome! Please follow these guidelines:

1. Create a feature branch
2. Make your changes
3. Write tests for new functionality
4. Submit a pull request

## License

MIT

## Support

For issues, questions, or feature requests, please contact the OpenLearning team.