### Install Melony Package

Source: https://github.com/ddaras/melony/blob/main/packages/melony-core/README.md

This command installs the Melony npm package, which is the first step to integrating Melony into your project. It ensures all necessary files and dependencies are downloaded and available for use.

```bash
npm install melony
```

--------------------------------

### Melony Component Syntax Example (HTML)

Source: https://github.com/ddaras/melony/blob/main/packages/melony-core/README.md

This HTML example showcases a Melony Card component used for a user profile. It includes layout components like Row and Col, content components like Image and Text, and an interactive Button with an associated action, adhering to Melony's HTML-like syntax.

```html
<card title="User Profile">
  <row gap="md" align="center">
    <image src="https://example.com/avatar.jpg" alt="Avatar" size="md" />
    <col gap="sm">
      <text value="John Doe" size="lg" weight="bold" />
      <text value="Software Engineer" color="muted" />
    </col>
  </row>
  
  <button
    label="Edit Profile"
    variant="primary"
    onClickAction='{"type": "edit-profile", "payload": {"id": 123}}'
  />
</card>
```

--------------------------------

### Melony Component Syntax Example (HTML-like)

Source: https://github.com/ddaras/melony/blob/main/README.md

Illustrates Melony's HTML-like syntax for building user interfaces. This example shows a 'card' component containing 'row', 'image', 'col', 'text', and 'button' components, demonstrating layout and interactive elements. This syntax is used for both built-in and custom widgets.

```html
<card title="User Profile">
  <row gap="md" align="center">
    <image src="https://example.com/avatar.jpg" alt="Avatar" size="md" />
    <col gap="sm">
      <text value="John Doe" size="lg" weight="bold" />
      <text value="Software Engineer" color="muted" />
    </col>
  </row>
  
  <button
    label="Edit Profile"
    variant="primary"
    onClickAction='{"type": "edit-profile", "payload": {"id": 123}}'
  />
</card>

```

--------------------------------

### Interactive Documentation with MelonyMarkdown

Source: https://github.com/ddaras/melony/blob/main/SEPARATION-SUMMARY.md

Renders API documentation with embedded interactive examples using `MelonyMarkdown`. This example shows how markdown content can include custom HTML-like tags for elements such as 'card', 'text', and 'button', enabling rich, interactive documentation pages.

```tsx
<MelonyMarkdown>
  {`
    # API Documentation
    
    Here's how to use our API:
    
    <card title="Example Request">
      <text value="GET /api/users" />
      <button value="Try it" variant="primary" />
    </card>
  `}
</MelonyMarkdown>
```

--------------------------------

### Quick Start: Define and Export Weather Widget

Source: https://github.com/ddaras/melony/blob/main/README.md

This TypeScript snippet defines a simplified 'weather-card' widget and exports it. This is part of the quick start guide, demonstrating the initial step of defining custom widgets.

```typescript
// widgets/weather-widget.ts
import { defineWidget } from "melony/builder";
import { z } from "zod";

export const weatherWidget = defineWidget({
  type: "weather-card",
  name: "Weather Card",
  description: "Shows weather info for a city",
  schema: z.object({
    type: z.literal("weather-card"),
    city: z.string(),
    temperature: z.number(),
    condition: z.string(),
  }),
  template: `
    <card title="Weather in {{city}}">
      <row gap="md">
        <text value="{{temperature}}°F" size="xl" />
        <badge label="{{condition}}" />
      </row>
    </card>
  `.trim()
});
```

--------------------------------

### Configure AI with Melony UI Guide (TypeScript/JavaScript)

Source: https://github.com/ddaras/melony/blob/main/packages/melony-core/README.md

This code snippet demonstrates how to configure an AI model, specifically using OpenAI with the ai-sdk, to understand and generate Melony UI components. It involves importing the MELONY_UI_GUIDE system prompt and passing it to the streamText function.

```tsx
import { MELONY_UI_GUIDE } from "melony/server";
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model: openai("gpt-4"),
    system: MELONY_UI_GUIDE, // Teaches AI to use Melony components
    messages,
  });

  return result.toDataStreamResponse();
}
```

--------------------------------

### Generate AI Training Prompts for Custom Widgets with Melony

Source: https://context7.com/ddaras/melony/llms.txt

The `generateWidgetSystemPrompt` function creates a detailed system prompt for LLMs, outlining available custom widgets, their schemas, examples, and usage patterns. This facilitates effective AI-driven widget utilization.

```typescript
import { generateWidgetSystemPrompt } from "melony/builder";
import { weatherWidget } from "./widgets/weather";

const customWidgets = [weatherWidget];
const systemPrompt = generateWidgetSystemPrompt(customWidgets);

// Returns formatted prompt:
// ## Custom Widgets
//
// The following custom widgets are available for use:
//
// ### weather-card Widget
// **Description:** Displays current weather information for a city
// **Props:**
// | Prop | Type | Required | Default | Description |
// |------|------|----------|---------|-------------|
// | `city` | `string` | ✓ | | City name |
// | `temperature` | `number` | ✓ | | Temperature in Fahrenheit |
// ...
```

--------------------------------

### generateWidgetSystemPrompt - Generate AI Training Prompts

Source: https://context7.com/ddaras/melony/llms.txt

This function generates a system prompt that can be used to train Large Language Models (LLMs). The prompt includes detailed information about available custom widgets, their schemas, and usage examples.

```APIDOC
## generateWidgetSystemPrompt - Generate AI Training Prompts

### Description
Generates a comprehensive system prompt that teaches LLMs about available custom widgets, including schemas, examples, and usage patterns.

### Method
`generateWidgetSystemPrompt(widgets: CompiledWidget[])`

### Parameters
- **widgets** (Array<CompiledWidget>) - Required - An array of compiled widget definitions.

### Request Example
```typescript
import { generateWidgetSystemPrompt } from "melony/builder";
import { weatherWidget } from "./widgets/weather";

const customWidgets = [weatherWidget];
const systemPrompt = generateWidgetSystemPrompt(customWidgets);
```

### Response
Returns a formatted string representing the system prompt for AI training.
```

--------------------------------

### AI-Generated Widget Usage Example

Source: https://github.com/ddaras/melony/blob/main/README.md

Illustrates how an AI might generate a Melony widget in HTML-like syntax. This showcases the output of the AI composition process, where defined widgets are instantiated with specific properties.

```html
<!-- AI generates this based on user context -->
<widget 
  type="weather-card" 
  city="New York" 
  temperature="68" 
  condition="Sunny" 
  humidity="45" 
/>
```

--------------------------------

### Example Melony Component Structure (HTML)

Source: https://github.com/ddaras/melony/blob/main/packages/melony-core/README.md

This HTML snippet illustrates a Melony Card component containing various elements like text, badges, and buttons. It demonstrates how to structure UI elements using Melony's HTML-like tags and how to define actions using the onClickAction prop.

```html
<card title="Weather Forecast">
  <row gap="md">
    <text value="San Francisco" size="lg" weight="bold" />
    <badge label="72°F" variant="success" />
  </row>
  <text value="Sunny with clear skies" />
  <button
    label="Get Detailed Forecast"
    variant="primary"
    onClickAction='{"type": "fetch-forecast", "payload": {"city": "SF"}}'
  />
</card>
```

--------------------------------

### MelonyWidget Usage Example: ComponentDef Input (JSX)

Source: https://github.com/ddaras/melony/blob/main/SEPARATION-SUMMARY.md

Illustrates using the MelonyWidget component with a structured ComponentDef object. This provides a more programmatic way to define widget hierarchies and their properties.

```jsx
<MelonyWidget>
  {{
    component: "Card",
    props: { title: "Hello" },
    children: [{ component: "Text", props: { value: "World" } }]
  }}
</MelonyWidget>
```

--------------------------------

### defineWidget - Create Type-Safe Custom Widgets

Source: https://context7.com/ddaras/melony/llms.txt

The `defineWidget` API allows developers to create type-safe widget definitions. These definitions include a Zod schema for validation, a template for rendering, and examples for AI prompt generation.

```APIDOC
## defineWidget - Create Type-Safe Custom Widgets

### Description
Creates a compiled widget definition with Zod schema validation, template rendering, and AI prompt generation. Returns a CompiledWidget that can be registered with MelonyProvider.

### Method
`defineWidget()`

### Parameters
This function accepts a single configuration object with the following properties:

- **type** (string) - Required - A unique identifier for the widget.
- **name** (string) - Required - A human-readable name for the widget.
- **description** (string) - Required - A description of the widget's purpose.
- **schema** (ZodObject) - Required - A Zod schema defining the widget's props and their types.
- **template** (string) - Required - An HTML-like template string for rendering the widget. Uses Handlebars syntax for dynamic values (e.g., `{{cityName}}`).
- **examples** (Array<Object>) - Optional - An array of example widget instances to aid AI prompt generation.

### Request Example
```typescript
import { defineWidget } from "melony/builder";
import { z } from "zod";

const weatherWidget = defineWidget({
  type: "weather-card",
  name: "Weather Card",
  description: "Displays current weather information for a city",
  schema: z.object({
    type: z.literal("weather-card"),
    city: z.string().describe("City name"),
    temperature: z.number().describe("Temperature in Fahrenheit"),
    condition: z.string().describe("Weather condition"),
    humidity: z.number().optional().describe("Humidity percentage"),
  }),
  template: `
    <card title="Weather in {{city}}">
      <row gap="md" align="center">
        <text value="{{temperature}}°F" size="xl" weight="bold" />
        <badge label="{{condition}}" variant="primary" />
      </row>
      {{#humidity}}
        <text value="Humidity: {{humidity}}%" color="muted" />
      {{/humidity}}
    </card>
  `,
  examples: [
    {
      type: "weather-card",
      city: "San Francisco",
      temperature: 72,
      condition: "Partly Cloudy",
      humidity: 65
    }
  ]
});
```

### Response
Returns a `CompiledWidget` object.
```

--------------------------------

### Define Basic Widget with Melony

Source: https://github.com/ddaras/melony/blob/main/README.md

Demonstrates the basic usage of `defineWidget()` to create a 'weather-card' widget. It includes a Zod schema for type safety, a Handlebars-style template for rendering, and example data for AI training. This function is central to Melony's widget-first approach.

```typescript
import {
  defineWidget
} from "melony/builder";
import { z } from "zod";

const weatherWidget = defineWidget({
  type: "weather-card",
  name: "Weather Card",
  description: "Displays current weather information for a city",
  
  // Zod schema for type safety
  schema: z.object({
    type: z.literal("weather-card"),
    city: z.string().describe("City name"),
    temperature: z.number().describe("Temperature in Fahrenheit"),
    condition: z.string().describe("Weather condition"),
    humidity: z.number().optional().describe("Humidity percentage"),
  }),
  
  // Simple template string with handlebars-style syntax
  template: `
    <card title="Weather in {{city}}">
      <row gap="md" align="center">
        <text value="{{temperature}}°F" size="xl" weight="bold" />
        <badge label="{{condition}}" variant="primary" />
      </row>
      {{#humidity}}
        <text value="Humidity: {{humidity}}%" color="muted" />
      {{/humidity}}
    </card>
  `.trim(),
  
  // Example data for AI training
  examples: [
    {
      city: "San Francisco",
      temperature: 72,
      condition: "Partly Cloudy",
      humidity: 65
    }
  ]
});
```

--------------------------------

### MelonyMarkdown Usage Example (JSX)

Source: https://github.com/ddaras/melony/blob/main/SEPARATION-SUMMARY.md

Shows how to use the MelonyMarkdown component to render a mix of markdown text and embedded widgets. It allows passing custom widgets and action handlers.

```jsx
<MelonyMarkdown onAction={handleAction} widgets={customWidgets}>
  {`
    # Hello World
    
    This is markdown text.
    
    <card title="Weather">
      <text value="72°F" />
    </card>
    
    More markdown here.
  `}
</MelonyMarkdown>
```

--------------------------------

### Defining Actions with JSON Strings in Melony (HTML)

Source: https://github.com/ddaras/melony/blob/main/packages/melony-core/README.md

These HTML examples demonstrate how to attach actions to Melony components like Button and Input using the `onClickAction` and `onChangeAction` props respectively. Actions are defined as JSON strings, specifying the action type and optional payload.

```html
<button
  label="Click Me"
  onClickAction='{"type": "button-click", "payload": {"value": 42}}'
/>

<input 
  label="Email" 
  onChangeAction='{"type": "email-changed"}' 
/>
```

--------------------------------

### MelonyWidget Usage Example: String Input (JSX)

Source: https://github.com/ddaras/melony/blob/main/SEPARATION-SUMMARY.md

Demonstrates how to use the MelonyWidget component with a string containing widget tags. This is a common way to embed declarative widget structures within a React application.

```jsx
<MelonyWidget onAction={handleAction}>
  {"<card title='Hello'><text value='World' /></card>"}
</MelonyWidget>
```

--------------------------------

### Define Advanced Melony Widget with Zod Schema (TypeScript)

Source: https://context7.com/ddaras/melony/llms.txt

Demonstrates how to define a complex Melony widget using `defineWidget`. It includes a Zod schema for data validation, a template for rendering with Handlebars-like syntax, and example data. This allows for dynamic and interactive UI elements with nested data structures.

```typescript
import { defineWidget } from "melony/builder";
import { z } from "zod";

const taskListWidget = defineWidget({
  type: "task-list",
  name: "Task List",
  description: "Interactive task list with completion tracking",
  schema: z.object({
    type: z.literal("task-list"),
    title: z.string().describe("List title"),
    tasks: z.array(z.object({
      id: z.string(),
      title: z.string(),
      completed: z.boolean(),
      priority: z.enum(["low", "medium", "high"]).optional(),
      assignee: z.string().optional()
    })).describe("Array of tasks")
  }),
  template: `
    <card title="{{title}}">
      {{#tasks}}
        <row gap="sm" align="center" justify="between">
          <row gap="sm" align="center">
            <checkbox
              checked="{{completed}}"
              onChangeAction='{"type":"toggle-task","payload":{"taskId":"{{id}}"}}'
            />
            <col gap="xs">
              <text value="{{title}}" weight="{{completed ? 'normal' : 'bold'}}" />
              {{#assignee}}
                <text value="Assigned to: {{assignee}}" size="sm" color="muted" />
              {{/assignee}}
            </col>
          </row>
          {{#priority}}
            <badge
              label="{{priority}}"
              variant="{{priority === 'high' ? 'danger' : 'secondary'}}"
            />
          {{/priority}}
        </row>
      {{/tasks}}
      <button
        label="Add Task"
        variant="primary"
        onClickAction='{"type":"add-task","payload":{"listTitle":"{{title}}"}}'
      />
    </card>
  `.trim(),
  examples: [{
    type: "task-list",
    title: "Sprint Tasks",
    tasks: [
      { id: "1", title: "Design API", completed: true, priority: "high", assignee: "Alice" },
      { id: "2", title: "Write tests", completed: false, priority: "medium" }
    ]
  }]
});

// AI generates widget with nested data and conditional rendering

```

--------------------------------

### Schema Design with Zod in TypeScript

Source: https://github.com/ddaras/melony/blob/main/README.md

Shows how to design widget schemas using Zod in TypeScript for Melony. It emphasizes providing detailed descriptions for AI understanding and using examples for AI training. The schema defines properties like `type`, `city`, `temperature`, `unit`, and `showDetails` with appropriate types and constraints.

```typescript
// ✅ Good: Detailed descriptions for AI
const schema = z.object({
  type: z.literal("weather-card"),
  city: z.string().describe("City name for weather lookup"),
  temperature: z.number().describe("Temperature in Fahrenheit"), 
  unit: z.enum(["F", "C"]).default("F").describe("Temperature unit"),
  showDetails: z.boolean().optional().describe("Show detailed weather info")
});

// ✅ Good: Use examples for AI training
const examples = [
  { city: "New York", temperature: 72, unit: "F", showDetails: true },
  { city: "London", temperature: 18, unit: "C", showDetails: false }
];
```

--------------------------------

### AI Generated Weather Widget (HTML)

Source: https://github.com/ddaras/melony/blob/main/README.md

Demonstrates how an AI can automatically generate a weather widget based on user context. This example shows a 'weather-card' widget with city, temperature, and condition. It also includes a 'card' with built-in components like 'text' and 'button' for additional information and actions.

```html
<!-- AI chooses the right widget based on context -->
<widget 
  type="weather-card" 
  city="Seattle" 
  temperature="65" 
  condition="Rainy" 
/>

<!-- Plus built-in components for additional content -->
<card title="Weather Tips">
  <text value="Don't forget your umbrella!" />
  <button 
    label="Get 7-Day Forecast"
    onClickAction='{"type": "fetch-forecast", "payload": {"city": "Seattle"}}'
  />
</card>

```

--------------------------------

### Server-Side AI Integration with Vercel AI SDK (TypeScript)

Source: https://context7.com/ddaras/melony/llms.txt

Configures AI models using Melony system prompts for widget-aware response generation. It leverages MELONY_UI_GUIDE for built-in components and custom widget prompts. This snippet demonstrates setting up a system prompt with custom widgets and integrating with the Vercel AI SDK for streaming text responses.

```typescript
import { MELONY_UI_GUIDE, generateWidgetSystemPrompt } from "melony/server";
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";
import { weatherWidget, taskListWidget } from "./widgets";

const customWidgets = [weatherWidget, taskListWidget];

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model: openai("gpt-4"),
    system: [
      MELONY_UI_GUIDE,
      generateWidgetSystemPrompt(customWidgets),
      "You are a helpful assistant. Use Melony components to create rich, interactive UIs."
    ].join("\n\n"),
    messages,
  });

  return result.toDataStreamResponse();
}

// AI learns to generate: <card title="Tasks"><widget type="task-list" tasks='[...]' /></card>
```

--------------------------------

### MelonyProvider - Root Context Provider

Source: https://context7.com/ddaras/melony/llms.txt

The `MelonyProvider` is the root context provider for the Melony library. It must wrap all Melony UI components and provides access to widget schemas, theme configuration, and action handling.

```APIDOC
## MelonyProvider - Root Context Provider

### Description
Provides widget schemas, theme configuration, and action handling to all Melony components. Must wrap all Melony UI components.

### Component
`<MelonyProvider>`

### Props
- **widgets** (Array<CompiledWidget>) - Required - An array of compiled widget definitions.
- **onAction** (function) - Optional - A callback function to handle custom actions dispatched by widgets. It receives an `action` object with `type` and `payload`.
- **theme** (Object) - Optional - A theme configuration object to customize the appearance of Melony components. Supports nested properties like `colors`.
  - **colors** (Object) - Optional - Defines color palettes for the theme.
    - **primary** (string) - Optional - The primary color.
    - **secondary** (string) - Optional - The secondary color.

### Request Example
```tsx
import { MelonyProvider } from "melony";
import { weatherWidget } from "./widgets/weather";

const customWidgets = [weatherWidget];

function App() {
  const handleAction = (action) => {
    console.log("Action:", action.type, action.payload);
    if (action.type === "fetch-forecast") {
      fetchWeatherForecast(action.payload.city);
    }
  };

  return (
    <MelonyProvider
      widgets={customWidgets}
      onAction={handleAction}
      theme={{
        colors: {
          primary: "#007bff",
          secondary: "#6c757d"
        }
      }}
    >
      <ChatInterface />
    </MelonyProvider>
  );
}
```
```

--------------------------------

### Integrate Melony UI with MelonyProvider

Source: https://context7.com/ddaras/melony/llms.txt

The `MelonyProvider` component serves as the root context provider for Melony applications. It manages widget schemas, theme configurations, and action handling, requiring it to wrap all other Melony UI components to ensure proper functionality.

```tsx
import { MelonyProvider } from "melony";
import { weatherWidget } from "./widgets/weather";

const customWidgets = [weatherWidget];

function App() {
  const handleAction = (action) => {
    console.log("Action:", action.type, action.payload);
    if (action.type === "fetch-forecast") {
      fetchWeatherForecast(action.payload.city);
    }
  };

  return (
    <MelonyProvider
      widgets={customWidgets}
      onAction={handleAction}
      theme={{
        colors: {
          primary: "#007bff",
          secondary: "#6c757d"
        }
      }}
    >
      <ChatInterface />
    </MelonyProvider>
  );
}
```

--------------------------------

### Melony Architecture Overview Flow (Diagram)

Source: https://github.com/ddaras/melony/blob/main/SEPARATION-SUMMARY.md

Illustrates the data flow within the Melony rendering system, showing how user input is processed by MelonyMarkdown, parsed, and then potentially rendered by MelonyWidget or as plain markdown.

```text
User Input (Markdown + Widgets)
        ↓
  MelonyMarkdown
        ↓
   MelonyParser
        ↓
[string, ComponentDef, string, ComponentDef]
        ↓
   ┌────┴────┐
   ↓         ↓
Markdown  MelonyWidget
 (text)      ↓
         renderComponent
             ↓
       React Components
```

--------------------------------

### Dynamic Widget Generation with MelonyWidget

Source: https://github.com/ddaras/melony/blob/main/SEPARATION-SUMMARY.md

Demonstrates dynamic creation of UI widgets using `MelonyWidget` and a `ComponentDef` structure. The `ComponentDef` defines a 'Card' component with a title and maps an array of items to 'Text' components as children, showcasing flexible UI composition.

```tsx
const widget: ComponentDef = {
  component: "Card",
  props: { title: data.title },
  children: data.items.map(item => ({
    component: "Text",
    props: { value: item.name }
  }))
};

<MelonyWidget>{widget}</MelonyWidget>
```

--------------------------------

### Organize Widgets by Domain in TypeScript

Source: https://github.com/ddaras/melony/blob/main/README.md

Demonstrates a best practice for organizing Melony widgets by their domain using TypeScript. It shows a recommended file structure for grouping related widget definitions (e.g., weather, user) into separate directories, promoting maintainability and scalability.

```typescript
// ✅ Good: Descriptive type names
const weatherWidget = defineWidget({
  type: "weather-card",  // kebab-case, descriptive
  name: "Weather Card",  // Human-readable name
  // ...
});

// ✅ Good: Organize widgets by domain
// widgets/weather/
//   ├── weather-card.ts
//   ├── forecast-list.ts
//   └── index.ts

// widgets/user/
//   ├── user-profile.ts
//   ├── user-list.ts
//   └── index.ts
```

--------------------------------

### MelonyMarkdown - Markdown with Embedded Widgets

Source: https://context7.com/ddaras/melony/llms.txt

The `MelonyMarkdown` component renders markdown content while intelligently parsing and rendering embedded Melony components as interactive React elements. It supports GitHub Flavored Markdown and progressive rendering for streaming responses.

```APIDOC
## MelonyMarkdown - Markdown with Embedded Widgets

### Description
Renders markdown content with embedded Melony components parsed and rendered as interactive React components. Supports GitHub Flavored Markdown and progressive rendering.

### Component
`<MelonyMarkdown>`

### Props
This component accepts standard markdown content as its children.

### Request Example
```tsx
import { MelonyMarkdown } from "melony";
import { useChat } from "ai/react";

export default function Chat() {
  const { messages } = useChat({ api: "/api/chat" });

  return (
    <div>
      {messages.map((message) => (
        <div key={message.id}>
          {message.role === "assistant" ? (
            <MelonyMarkdown>
              {message.content}
            </MelonyMarkdown>
          ) : (
            <p>{message.content}</p>
          )}
        </div>
      ))}
    </div>
  );
}
```

### Input Example
`The weather is nice! <card title='Today'><text value='Sunny, 75°F' /></card>`

### Output Example
Renders markdown text followed by an interactive Card component.
```

--------------------------------

### Register Custom Widgets for AI in Server Prompt

Source: https://github.com/ddaras/melony/blob/main/README.md

Shows how to register custom widgets (like `weatherWidget`) with the Melony AI system prompt on the server-side. It uses `generateWidgetSystemPrompt` to create prompts for the LLM, enabling contextual widget generation.

```typescript
import { MELONY_UI_GUIDE, generateWidgetSystemPrompt } from "melony/server";
import { weatherWidget } from "./widgets/weather-widget";
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";

const customWidgets = [weatherWidget];

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model: openai("gpt-4"),
    system: [
      MELONY_UI_GUIDE, // Built-in components
      generateWidgetSystemPrompt(customWidgets) // Your custom widgets
    ].join("\n\n"),
    messages,
  });

  return result.toDataStreamResponse();
}
```

--------------------------------

### Parse HTML-Like Widget Syntax with MelonyParser (TypeScript)

Source: https://context7.com/ddaras/melony/llms.txt

Converts HTML-like component tags into structured ComponentDef objects. This parser handles progressive parsing during streaming, making it suitable for dynamic content generation. It can be initialized with a list of known widgets.

```typescript
import { MelonyParser } from "melony";

const parser = new MelonyParser([weatherWidget]);

const markup = `
  <card title="Dashboard">
    <row gap="md">
      <text value="Welcome!" size="lg" />
      <badge label="New" variant="primary" />
    </row>
  </card>
`;

const blocks = parser.parseContentAsBlocks(markup);
// Returns: [ComponentDef { component: "Card", props: {...}, children: [...] }]

// Handles incomplete tags during streaming
const incomplete = '<card title="Loading...';
const blocksWithLoading = parser.parseContentAsBlocks(incomplete);
// Adds loading indicator for incomplete tags
```

--------------------------------

### Type-Safe Widget Definition in TypeScript

Source: https://github.com/ddaras/melony/blob/main/README.md

Demonstrates how to create type-safe widget definitions using Melony's TypeScript support. It shows the `defineWidget` function, schema definition with Zod, and how the `builder` function receives type-safe props, providing full IntelliSense for widget properties.

```typescript
import type {
  WidgetDefinition,
  CompiledWidget,
  MelonyTheme,
  Action,
  ActionHandler,
  ComponentDef,
} from "melony";
import { defineWidget, card, text } from "melony/builder";

// Type-safe widget definition
const widget: WidgetDefinition<z.ZodObject({
  type: z.ZodLiteral<"my-widget">;
  title: z.ZodString;
}
>> = defineWidget({
  type: "my-widget",
  schema: z.object({
    type: z.literal("my-widget"),
    title: z.string(),
  }),
  builder: (props) => {
    // TypeScript knows props.title is string with full IntelliSense
    return card({ title: props.title }, [
      text({ value: "Widget content" })
    ]);
  }
});
```

--------------------------------

### Define Data-Driven Task List Widget (TypeScript)

Source: https://github.com/ddaras/melony/blob/main/README.md

Defines a data-driven task list widget using Melony's `defineWidget`. It accepts a title and an array of tasks, displaying their completion status and priority. Includes schema validation and a template for rendering the list. Dependencies include `melony/builder` and `zod`.

```typescript
import { defineWidget } from "melony/builder";

const taskListWidget = defineWidget({
  type: "task-list",
  description: "Displays a list of tasks with completion status",
  schema: z.object({
    type: z.literal("task-list"),
    title: z.string(),
    tasks: z.array(z.object({
      id: z.string(),
      title: z.string(),
      completed: z.boolean(),
      priority: z.enum(["low", "medium", "high"])
    }))
  }),
  template: `
    <card title="{{title}}">
      {{#tasks}}
        <row gap="sm" align="center">
          <checkbox 
            checked="{{completed}}" 
            onChangeAction='{"type": "toggle-task", "payload": {"taskId": "{{id}}"}}' />
          <text value="{{title}}" />
          {{#priority}}
            <badge label="{{priority}}" variant="secondary" />
          {{/priority}}
        </row>
      {{/tasks}}
    </card>
  `
});

```

--------------------------------

### Render Markdown with Embedded Widgets using MelonyMarkdown

Source: https://context7.com/ddaras/melony/llms.txt

The `MelonyMarkdown` component renders markdown content while intelligently parsing and rendering embedded Melony components as interactive React components. It supports GitHub Flavored Markdown and progressive rendering for dynamic content delivery.

```tsx
import { MelonyMarkdown } from "melony";
import { useChat } from "ai/react";

export default function Chat() {
  const { messages } = useChat({ api: "/api/chat" });

  return (
    <div>
      {messages.map((message) => (
        <div key={message.id}>
          {message.role === "assistant" ? (
            <MelonyMarkdown>
              {message.content}
            </MelonyMarkdown>
          ) : (
            <p>{message.content}</p>
          )}
        </div>
      ))}
    </div>
  );
}

// Input: "The weather is nice! <card title='Today'><text value='Sunny, 75°F' /></card>"
// Output: Renders markdown text followed by interactive Card component
```

--------------------------------

### Builder Functions for Conditional Rendering in TypeScript

Source: https://github.com/ddaras/melony/blob/main/README.md

Illustrates the use of builder functions in Melony for creating components with conditional rendering logic in TypeScript. It demonstrates using `ifBlock` for conditional display and leveraging JavaScript expressions for more complex conditional logic within the builder function.

```typescript
// ✅ Good: Clean function syntax with conditional rendering
builder: (props) => {
  return card({ title: `Weather in ${props.city}` }, [
    // Always include core content
    text({ value: `${props.temperature}°${props.unit}` }),
    
    // Conditional content with ifBlock
    ifBlock({ condition: "!!showDetails" }, [
      text({ value: "Detailed forecast available" })
    ]),
    
    // Or use conditional JavaScript for complex logic
    ...(props.showDetails && props.forecast ? [
      row({ gap: "sm" }, [
        text({ value: "Tomorrow:", weight: "bold" }),
        text({ value: props.forecast.tomorrow })
      ])
    ] : [])
  ]);
}
```

--------------------------------

### Pure Widget Dashboard with MelonyWidget

Source: https://github.com/ddaras/melony/blob/main/SEPARATION-SUMMARY.md

Creates a dashboard composed entirely of widgets. MelonyWidget is used here to render a `widgetDefinition`, which likely describes the structure and content of the dashboard's widgets. An `onAction` prop is provided for handling events within the widgets.

```tsx
<MelonyWidget onAction={handleAction}>
  {widgetDefinition}
</MelonyWidget>
```

--------------------------------

### Melony Built-in UI Components (TypeScript)

Source: https://context7.com/ddaras/melony/llms.txt

Provides pre-built React components for common UI patterns like cards, forms, charts, lists, and images. These components utilize HTML-like syntax and integrate with the Melony action system for interactivity. They are ready to use for building user interfaces.

```typescript
// Layout Components
<card title="Dashboard" subtitle="Overview">
  <row gap="md" align="center" justify="between">
    <col gap="sm">
      <text value="Sales" size="lg" weight="bold" />
      <text value="$125,430" size="xl" color="primary" />
    </col>
    <badge label="+12%" variant="success" />
  </row>
</card>

// Form Components
<card title="User Registration">
  <form onSubmitAction='{"type":"register","payload":{"source":"web"}}'>
    <input
      label="Email"
      inputType="email"
      name="email"
      placeholder="user@example.com"
      onChangeAction='{"type":"validate-email"}'
    />
    <select
      label="Role"
      name="role"
      options='[{"label":"User","value":"user"},{"label":"Admin","value":"admin"}]'
    />
    <radiogroup
      label="Plan"
      name="plan"
      orientation="horizontal"
      options='[{"label":"Free","value":"free"},{"label":"Pro","value":"pro"}]'
    />
    <textarea
      label="Bio"
      name="bio"
      rows="4"
      placeholder="Tell us about yourself"
    />
    <checkbox label="Agree to terms" name="terms" />
    <button label="Sign Up" variant="primary" fullWidth="true" />
  </form>
</card>

// Data Visualization
<card title="Revenue Chart">
  <chart
    chartType="line"
    showValues="true"
    showGrid="true"
    data='[
      {"label":"Jan","value":4500},
      {"label":"Feb","value":5200},
      {"label":"Mar","value":6100}
    ]'
  />
</card>

// Interactive Lists
<card title="Notifications">
  <list>
    <listitem gap="md" align="center" onClickAction='{"type":"view","payload":{"id":"1"}}'>
      <icon name="Info" color="primary" />
      <col gap="xs">
        <text value="New message" weight="bold" />
        <text value="You have 3 unread messages" size="sm" color="muted" />
      </col>
    </listitem>
  </list>
</card>

// Images and Icons
<row gap="md" align="center">
  <image src="https://example.com/avatar.jpg" alt="User" size="md" />
  <icon name="Check" size="lg" color="success" />
</row>
```

--------------------------------

### Define Interactive User Profile Widget (TypeScript)

Source: https://github.com/ddaras/melony/blob/main/README.md

Defines an interactive user profile widget using Melony's `defineWidget` function. It includes a schema for user data and a template for rendering a profile card with editable and message buttons. Dependencies include `melony/builder` and `zod` (for schema definition).

```typescript
import { defineWidget } from "melony/builder";

const userProfileWidget = defineWidget({
  type: "user-profile",
  description: "Interactive user profile card with actions",
  schema: z.object({
    type: z.literal("user-profile"),
    userId: z.string(),
    name: z.string(),
    email: z.string(),
    avatar: z.string().optional(),
    role: z.enum(["admin", "user", "moderator"]),
  }),
  template: `
    <card title="User Profile">
      <row gap="md" align="center">
        {{#avatar}}
          <image src="{{avatar}}" alt="Avatar" size="md" />
        {{/avatar}}
        <col gap="sm">
          <text value="{{name}}" size="lg" weight="bold" />
          <text value="{{email}}" color="muted" />
          <badge label="{{role}}" variant="secondary" />
        </col>
      </row>
      <row gap="sm">
        <button 
          label="Edit Profile" 
          variant="primary"
          onClickAction='{"type": "edit-user", "payload": {"userId": "{{userId}}"}}' />
        <button 
          label="Send Message" 
          variant="secondary"
          onClickAction='{"type": "send-message", "payload": {"userId": "{{userId}}", "name": "{{name}}"}}' />
      </row>
    </card>
  `
});

```

--------------------------------

### Melony TypeScript Type Imports

Source: https://github.com/ddaras/melony/blob/main/packages/melony-core/README.md

This code snippet shows how to import specific types from the 'melony' library for use in TypeScript projects. These types include those for theming, actions, action handlers, and component definitions, aiding in type-safe development.

```tsx
import type {
  MelonyTheme,
  Action,
  ActionHandler,
  ComponentDef,
} from "melony";
```

--------------------------------

### Render Widgets with MelonyWidget (React)

Source: https://context7.com/ddaras/melony/llms.txt

Renders widget syntax directly using the MelonyWidget component. This is useful for content that is entirely widget-based or when markdown processing is not required. It takes a string of widget markup as its child.

```tsx
import { MelonyWidget } from "melony";

function WeatherDisplay({ widgetData }) {
  const widgetMarkup = `
    <widget
      type="weather-card"
      city="${widgetData.city}"
      temperature="${widgetData.temp}"
      condition="${widgetData.condition}"
    />
  `;

  return <MelonyWidget>{widgetMarkup}</MelonyWidget>;
}
```

--------------------------------

### Define Type-Safe Custom Widgets with Melony

Source: https://context7.com/ddaras/melony/llms.txt

The `defineWidget` API creates compiled widget definitions including Zod schema validation, template rendering, and AI prompt generation. It returns a `CompiledWidget` suitable for registration with `MelonyProvider`. This function is essential for extending Melony's component library.

```typescript
import { defineWidget } from "melony/builder";
import { z } from "zod";

const weatherWidget = defineWidget({
  type: "weather-card",
  name: "Weather Card",
  description: "Displays current weather information for a city",
  schema: z.object({
    type: z.literal("weather-card"),
    city: z.string().describe("City name"),
    temperature: z.number().describe("Temperature in Fahrenheit"),
    condition: z.string().describe("Weather condition"),
    humidity: z.number().optional().describe("Humidity percentage"),
  }),
  template: `
    <card title="Weather in {{city}}">
      <row gap="md" align="center">
        <text value="{{temperature}}°F" size="xl" weight="bold" />
        <badge label="{{condition}}" variant="primary" />
      </row>
      {{#humidity}}
        <text value="Humidity: {{humidity}}%" color="muted" />
      {{/humidity}}
    </card>
  `.trim(),
  examples: [
    {
      type: "weather-card",
      city: "San Francisco",
      temperature: 72,
      condition: "Partly Cloudy",
      humidity: 65
    }
  ]
});

// AI generates: <widget type="weather-card" city="Seattle" temperature="65" condition="Rainy" humidity="85" />
```

--------------------------------

### AI Chat with MelonyMarkdown

Source: https://github.com/ddaras/melony/blob/main/SEPARATION-SUMMARY.md

Renders AI-generated streamed responses within a mixed content environment. It utilizes MelonyMarkdown to handle both text and embedded widgets, with an `onAction` prop for handling user interactions and a `widgets` prop for passing custom components.

```tsx
<MelonyMarkdown onAction={handleAction} widgets={[...]}>
  {aiStreamedResponse}
</MelonyMarkdown>
```

--------------------------------

### Handling User Actions in Melony (TypeScript/JavaScript)

Source: https://github.com/ddaras/melony/blob/main/packages/melony-core/README.md

This TypeScript/JavaScript code defines a function `handleAction` that processes actions triggered by user interactions within Melony components. It uses a switch statement to differentiate between action types like 'edit-profile' and 'submit-form', logging relevant payload data.

```tsx
const handleAction = (action) => {
  const { type, payload } = action;
  
  switch (type) {
    case "edit-profile":
      console.log("Editing profile:", payload.id);
      break;
    case "submit-form":
      console.log("Form data:", payload);
      break;
  }
};
```

--------------------------------

### Template Engine for Handlebars-Style Templating (TypeScript)

Source: https://context7.com/ddaras/melony/llms.txt

Processes template strings with variable interpolation, conditionals, and array iteration, similar to Handlebars. This is used internally by widget templates to dynamically generate markup. It takes a template string and a context object for rendering.

```typescript
import { TemplateEngine } from "melony";

const template = `
  <card title="{{title}}">
    {{#items}}
      <text value="{{name}} - ${{price}}" />
      {{#onSale}}
        <badge label="Sale!" variant="success" />
      {{/onSale}}
    {{/items}}
    {{#!items}}
      <text value="No items available" />
    {{/!items}}
  </card>
`;

const context = {
  title: "Products",
  items: [
    { name: "Widget", price: 29.99, onSale: true },
    { name: "Gadget", price: 49.99, onSale: false }
  ]
};

const rendered = TemplateEngine.render(template, context);
// Outputs widget markup with values substituted, sale badge shown for first item only
```

--------------------------------

### Render Streaming Responses with Melony (React/TypeScript)

Source: https://github.com/ddaras/melony/blob/main/packages/melony-core/README.md

This React component utilizes the useChat hook from the 'ai/react' library to fetch messages from a chat API. It then renders these messages, using MelonyMarkdown for assistant responses, within a MelonyProvider that handles user actions.

```tsx
"use client";
import { useChat } from "ai/react";
import { MelonyProvider, MelonyMarkdown } from "melony";

export default function Chat() {
  const { messages } = useChat({ api: "/api/chat" });

  return (
    <MelonyProvider onAction={handleAction}>
      {messages.map((message) => (
        <div key={message.id}>
          {message.role === "assistant" ? (
            <MelonyMarkdown>{message.content}</MelonyMarkdown>
          ) : (
            <p>{message.content}</p>
          )}
        </div>
      ))}
    </MelonyProvider>
  );
}

const handleAction = (action) => {
  console.log("Action:", action.type, action.payload);
};
```

--------------------------------

### MelonyWidget Props Interface (TypeScript)

Source: https://github.com/ddaras/melony/blob/main/SEPARATION-SUMMARY.md

Defines the properties accepted by the MelonyWidget component. It handles widget rendering and accepts either raw widget tags as a string or structured ComponentDef objects. It supports theming, actions, parsing, and context.

```typescript
interface MelonyWidgetProps {
  className?: string;
  children?: string | ComponentDef;
  style?: React.CSSProperties;
  theme?: MelonyTheme;
  onAction?: ActionHandler;
  parser?: MelonyParser;
  widgets?: WidgetTemplate[];
  context?: Record<string, any>;
}
```

--------------------------------

### Render Chat with Custom Widgets (React/TypeScript)

Source: https://github.com/ddaras/melony/blob/main/README.md

Renders a chat interface using MelonyProvider and custom widgets. It utilizes the `ai/react` hook for chat messages and maps them to MelonyMarkdown for assistant messages or paragraphs for user messages. Dependencies include `ai/react` and `melony`.

```tsx
"use client";
import { useChat } from "ai/react";
import { MelonyProvider, MelonyMarkdown } from "melony";
import { weatherWidget } from "./widgets/weather-widget";

const customWidgets = [weatherWidget];

export default function Chat() {
  const { messages } = useChat({ api: "/api/chat" });

  return (
    <MelonyProvider 
      widgets={customWidgets} 
      onAction={handleAction}
    >
      {messages.map((message) => (
        <div key={message.id}>
          {message.role === "assistant" ? (
            <MelonyMarkdown>{message.content}</MelonyMarkdown>
          ) : (
            <p>{message.content}</p>
          )}
        </div>
      ))}
    </MelonyProvider>
  );
}

const handleAction = (action) => {
  console.log("Action:", action.type, action.payload);
};

```

--------------------------------

### MelonyMarkdown Props Interface (TypeScript)

Source: https://github.com/ddaras/melony/blob/main/SEPARATION-SUMMARY.md

Defines the properties for the MelonyMarkdown component. It renders markdown content and can embed widgets. It accepts markdown as children and supports custom components, theming, actions, parsing, and context.

```typescript
interface MarkdownProps {
  className?: string;
  children: string | undefined | null;
  components?: Partial<Components>;
  style?: React.CSSProperties;
  theme?: MelonyTheme;
  onAction?: ActionHandler;
  parser?: MelonyParser;
  widgets?: WidgetTemplate[];
  context?: Record<string, any>;
}
```

--------------------------------

### Subscribe to Component Actions with useAction (React)

Source: https://context7.com/ddaras/melony/llms.txt

A React hook that subscribes to specific action types dispatched from interactive components. It is used for handling user interactions like button clicks or form submissions. The hook takes an action type, a callback function, and a dependency array.

```tsx
import { useAction } from "melony";
import { useState } from "react";

function ChatInterface() {
  const [selectedCity, setSelectedCity] = useState(null);

  useAction("fetch-forecast", (payload) => {
    console.log("Fetching forecast for:", payload.city);
    setSelectedCity(payload.city);
    fetchWeatherData(payload.city);
  }, []);

  useAction("submit-feedback", async (payload) => {
    await sendFeedback(payload);
    alert("Thank you for your feedback!");
  }, []);

  return <div>Selected city: {selectedCity}</div>;
}

// Triggered by: <button label="Get Forecast" onClickAction='{"type":"fetch-forecast","payload":{"city":"NYC"}}' />
```

--------------------------------

### Programmatic Action Dispatch with useActionDispatch (React)

Source: https://context7.com/ddaras/melony/llms.txt

A React hook that provides a dispatch function to trigger actions programmatically from within React components. This allows for decoupling UI events from action handling logic. The dispatch function takes an action object with a type and payload.

```tsx
import { useActionDispatch } from "melony";

function WeatherControls() {
  const dispatch = useActionDispatch();

  const handleRefresh = () => {
    dispatch({
      type: "refresh-weather",
      payload: { timestamp: Date.now() }
    });
  };

  const handleCitySelect = (city) => {
    dispatch({
      type: "fetch-forecast",
      payload: { city }
    });
  };

  return (
    <div>
      <button onClick={handleRefresh}>Refresh</button>
      <button onClick={() => handleCitySelect("Seattle")}>Seattle Weather</button>
    </div>
  );
}
```