# MeoNode UI Documentation

> **MeoNode UI**: The Type-Safe Future of React Without JSX.
> React without JSX. Pure, functional, composable.

## Project Overview

MeoNode UI is a production-ready component library that replaces JSX with function-based composition. It offers direct CSS-in-props styling, automatic Context-based theming, and granular memoization—all fully typed with TypeScript. It is compatible with React Server Components (RSC) and integrates seamlessly with Next.js and Vite.

## Core Documentation Map

- **Docs Home**: [https://ui.meonode.com/docs/getting-started/overview](https://ui.meonode.com/docs/getting-started/overview)
- **Why Without JSX?**: [https://ui.meonode.com/docs/getting-started/why-without-jsx](https://ui.meonode.com/docs/getting-started/why-without-jsx)
  - _Key concept_: Explains the philosophy, performance benefits (no build step), type safety, and **unified styling/theming** advantages of avoiding JSX.

### Getting Started

- **Installation**: [https://ui.meonode.com/docs/getting-started/installation](https://ui.meonode.com/docs/getting-started/installation)
  - `npm install @meonode/ui react react-dom`
- **Usage Guide**: [https://ui.meonode.com/docs/getting-started/usage](https://ui.meonode.com/docs/getting-started/usage)
  - Covers `Node()` factory, Container nodes (`Column`, `Row`), and Text-first nodes (`H1`, `Button`).
- **Release Notes**: [https://ui.meonode.com/docs/getting-started/release-notes](https://ui.meonode.com/docs/getting-started/release-notes)
  - History of features, enhancements, and bug fixes (e.g., v1.2.0 Stack-Based Portal System).

### Core Systems

- **Styling**: [https://ui.meonode.com/docs/getting-started/styling](https://ui.meonode.com/docs/getting-started/styling)
  - Direct props: `Div({ backgroundColor: 'red' })`
  - `css` prop: For pseudo-classes, media queries, and animations.
- **Theming**: [https://ui.meonode.com/docs/getting-started/theming](https://ui.meonode.com/docs/getting-started/theming)
  - **New in v0.3+**: Context-based system.
  - Usage: `color: 'theme.primary.content'`.
  - Requires `ThemeProvider` and `system` object structure.
- **Portal System**: [https://ui.meonode.com/docs/getting-started/portal-system](https://ui.meonode.com/docs/getting-started/portal-system)
  - **New in v1.2.0**: robust, stack-based solution for managing overlays like modals, drawers, and tooltips.
  - Key components: `PortalProvider`, `PortalHost`.
  - hook: `usePortal` with auto-sync data capabilities.

### API Reference

- **Components**: [https://ui.meonode.com/docs/components](https://ui.meonode.com/docs/components)
  - **Layout**: `Div`, `Container`, `Root`, `Column`, `Row`, `Grid`, `Center`, `Fixed`, `Relative`, `Absolute`, `Sticky`.
  - **Typography**: `H1`-`H6`, `P`, `Text`, `Span`, `Strong`, `Em`, `Code`, `Pre`.
  - **Forms**: `Form`, `Input`, `Button`, `Textarea`, `Select`, `Label`.
  - **Media**: `Img`, `Video`, `Audio`, `Canvas`, `Iframe`.
  - **Structure**: `Nav`, `Main`, `Header`, `Footer`, `Section`, `Article`.
  - **Tables**: `Table`, `Thead`, `Tbody`, `Tr`, `Th`, `Td`.
  - **SVG**: Wrappers for standard SVG elements (e.g., `Svg`, `SvgPath`, `SvgCircle`).
  - **HOCs**: `Component` factory for standard React components.

- **Hooks**: [https://ui.meonode.com/docs/hooks](https://ui.meonode.com/docs/hooks)
  - `useTheme`: Access and update theme context (`const { theme, setTheme } = useTheme()`).
  - `usePortal`: Interaction with the portal system (`portal.open`, `portal.close`, `portal.updateData`).
  - `useDataChannel`: High-performance data channel subscription for frequent updates without re-renders.

### Advanced Guide

- **Rules & Patterns**: [https://ui.meonode.com/docs/getting-started/rules-and-patterns](https://ui.meonode.com/docs/getting-started/rules-and-patterns)
  - **Golden Rule**: Never call hook-using components conditionally. Use `Node(Component)` or inline `() => Component()`.
  - **HMR**: Use `.tsx` extension and `Node()` wrapping for proper Hot Module Replacement.
- **FAQ**: [https://ui.meonode.com/docs/getting-started/faq](https://ui.meonode.com/docs/getting-started/faq)

### Framework Integration

- **Next.js**: [https://ui.meonode.com/docs/getting-started/framework-integration/nextjs](https://ui.meonode.com/docs/getting-started/framework-integration/nextjs)
  - Fully supports App Router and RSC.
  - Setup `StyleRegistry` for Emotion CSS SSR.
- **Vite**: [https://ui.meonode.com/docs/getting-started/framework-integration/vite](https://ui.meonode.com/docs/getting-started/framework-integration/vite)
  - Standard React + TS setup.

### Library Integration

- **Material UI (@meonode/mui)**: [https://ui.meonode.com/docs/mui-integration](https://ui.meonode.com/docs/mui-integration)
  - **Pre-wrapped MUI components** for MeoNode's function-based architecture
  - **Zero manual wrapping** - all components ready to import and use
  - **Complete coverage**: Core Material-UI + all MUI X packages
  
  **Available Packages:**
  - `@meonode/mui` - All core Material-UI components (Button, TextField, Card, Grid, etc.)
  - `@meonode/mui/lab` - Experimental components (Masonry, etc.)
  - `@meonode/mui/x-data-grid` - DataGrid component (+ pro/premium tiers)
  - `@meonode/mui/x-tree-view` - TreeView components (+ pro tier)
  - `@meonode/mui/x-date-pickers` - Date/time picker components
  - `@meonode/mui/x-charts` - Chart components (+ pro tier)

## Code Examples

### Basic Component

```typescript
import { Column, H1, Button } from '@meonode/ui'

const App = () =>
  Column({
    padding: 'theme.spacing.lg',
    gap: 12,
    children: [
      H1('Hello World', { color: 'theme.primary' }),
      Button('Click Me', {
        onClick: () => alert('Clicked!'),
        backgroundColor: 'theme.secondary',
        color: 'white'
      })
    ]
  }).render()
```

### Conditional Rendering (The Right Way)

```typescript
import { Node } from '@meonode/ui'

// Correct: Wrap hook-using components in Node() or closure
show && Node(MyComponent, { id: 1 })
// OR
show && (() => MyComponent({ id: 1 }))
```

### Theming Setup

```typescript
const theme = {
  mode: 'light',
  system: {
    primary: { default: '#0070f3', content: '#fff' },
    // ...
  }
}
```