Skip to content

Commit 066f845

Browse files
druid-infraLugh (Druid Bot)
druid-infra
and
Lugh (Druid Bot)
authored
docs: Add DruidUI framework documentation (#27)
* docs: Add comprehensive DruidUI framework documentation - Explain WebAssembly SPA framework architecture - Detail sandboxing benefits and use cases - Provide quick start guide and examples - Document component model and rendering - Cover extension system for custom APIs - Include multi-language support roadmap - Add migration guides from React/Vue - Performance metrics and best practices * fix: Remove broken links and escape HTML entities - Remove non-existent file references (api-reference, extensions, deployment) - Replace < with &lt; in markdown - Fixes MDX compilation and broken link errors * docs: Add Mithril.js comparison and npm package documentation - Add detailed Mithril.js comparison in introduction - Create comprehensive @druid-ui/component package docs - Create @druid-ui/build package docs with CLI and API reference - Add packages category for NPM package documentation * docs: Complete NPM package documentation for DruidUI - Add create-druid-ui package docs (scaffolding tool) - Add @druid-ui/vite package docs (Vite plugin, HMR) - Add @druid-ui/host package docs (browser runtime) - All 5 NPM packages now fully documented - Comprehensive API references, examples, troubleshooting - Build passing successfully * docs: Remove Migration Guide from DruidUI documentation - Removed entire Migration Guide section (React, Vue examples) - Keep documentation focused on DruidUI itself - Users can figure out migration on their own * docs: Cut DruidUI docs by 50%+ - keep only essentials --------- Co-authored-by: Lugh (Druid Bot) <lugh@druid.gg>
1 parent 6d4c871 commit 066f845

8 files changed

Lines changed: 684 additions & 0 deletions

File tree

‎docs/druid-ui/_category_.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"label": "DruidUI Framework",
3+
"position": 6,
4+
"collapsed": false
5+
}

‎docs/druid-ui/introduction.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
---
2+
sidebar_position: 1
3+
title: DruidUI
4+
description: WebAssembly framework for sandboxed UIs
5+
---
6+
7+
# DruidUI
8+
9+
DruidUI is a React-like framework that compiles to **WebAssembly** for building sandboxed user interfaces. Use it when you need to run untrusted UI code safely.
10+
11+
## Why WebAssembly?
12+
13+
Traditional approaches can't provide true sandboxing:
14+
- **JavaScript** - Can access all browser APIs
15+
- **iframes** - Limited state sharing, poor UX
16+
17+
**WebAssembly** provides complete isolation - code can only access explicitly granted functions.
18+
19+
## Quick Start
20+
21+
```bash
22+
npx create-druid-ui my-app
23+
cd my-app
24+
npm install
25+
npm run dev
26+
```
27+
28+
### Hello World
29+
30+
```tsx
31+
import { createComponent, Context } from '@druid-ui/component';
32+
33+
let count = 0;
34+
35+
export const component = createComponent((ctx: Context) => {
36+
return (
37+
<main>
38+
<h1>Hello Druid!</h1>
39+
<button onClick={() => { count++; }}>
40+
Clicked {count} times
41+
</button>
42+
</main>
43+
);
44+
});
45+
```
46+
47+
### Build & Deploy
48+
49+
```bash
50+
# Build to WASM
51+
npm run build # → dist/component.wasm
52+
53+
# Add to scroll
54+
ui:
55+
- name: dashboard
56+
path: ui/dashboard.wasm
57+
route: /admin
58+
```
59+
60+
## Core Concepts
61+
62+
### Functional Components
63+
64+
Similar to [React](https://react.dev) and [Mithril.js](https://mithril.js.org/):
65+
66+
- JSX/TSX syntax
67+
- Every event triggers full rerender (no complex diffing)
68+
- Module-level state (no hooks)
69+
70+
```tsx
71+
let items = ['todo 1', 'todo 2'];
72+
73+
export const component = createComponent(() => {
74+
return (
75+
<ul>
76+
{items.map(item => <li>{item}</li>)}
77+
</ul>
78+
);
79+
});
80+
```
81+
82+
### Context
83+
84+
Access route data via context:
85+
86+
```tsx
87+
export const component = createComponent((ctx: Context) => {
88+
return (
89+
<div>
90+
<p>Path: {ctx.path}</p>
91+
<p>User ID: {ctx.params.userId}</p>
92+
</div>
93+
);
94+
});
95+
```
96+
97+
### Shadow DOM
98+
99+
Each component renders in isolated Shadow DOM - styles can't leak in/out.
100+
101+
## Development Workflow
102+
103+
### Raw Mode (Fast)
104+
105+
Develop without WASM overhead:
106+
107+
```html
108+
<druid-ui no-sandbox src="/src/index.tsx"></druid-ui>
109+
```
110+
111+
- Instant hot reload
112+
- Normal browser debugging
113+
- Not sandboxed (dev only!)
114+
115+
### Sandbox Mode (Production)
116+
117+
Full WASM sandboxing:
118+
119+
```bash
120+
npm run build
121+
npm run preview
122+
```
123+
124+
- True isolation
125+
- Production-ready
126+
- Slower iteration
127+
128+
## Extension System
129+
130+
By default, WASM can only call `d()`, `log()`, and `rerender()`. Add custom APIs via extensions:
131+
132+
**1. Define interface (WIT):**
133+
134+
```wit
135+
package my:api;
136+
137+
interface fetch {
138+
get-data: func(url: string) -> string;
139+
}
140+
```
141+
142+
**2. Implement in host:**
143+
144+
```js
145+
druidElement.extensionObject = {
146+
'my:api/fetch': {
147+
getData: async (url) => {
148+
const res = await fetch(url);
149+
return res.text();
150+
}
151+
}
152+
};
153+
```
154+
155+
**3. Use in component:**
156+
157+
```tsx
158+
import { getData } from 'my:api/fetch';
159+
160+
const data = await getData('/api/status');
161+
```
162+
163+
See [package documentation](./packages/component.md) for full API reference.
164+
165+
## Multi-Language Support
166+
167+
**Current:** JavaScript/TypeScript ✅
168+
169+
**Planned:** Rust, C++ (waiting for WebAssembly Component Model maturity)
170+
171+
## Limitations
172+
173+
- No async/await yet (use callback workaround)
174+
- Full rerenders on every event (less efficient than React)
175+
- JavaScript only for now
176+
- No SSR
177+
178+
## Learn More
179+
180+
- [NPM Packages](./packages/component.md) - API reference
181+
- [Examples](https://github.com/highcard-dev/druid-ui/tree/main/examples)
182+
- [Source Code](https://github.com/highcard-dev/druid-ui)

‎docs/druid-ui/packages/_category_.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"label": "NPM Packages",
3+
"position": 10,
4+
"collapsed": false
5+
}

‎docs/druid-ui/packages/build.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
sidebar_position: 3
3+
title: "@druid-ui/build"
4+
description: Build tools for compiling to WASM
5+
---
6+
7+
# @druid-ui/build
8+
9+
Build tools and CLI for compiling DruidUI components to WebAssembly.
10+
11+
## Installation
12+
13+
```bash
14+
npm install --save-dev @druid-ui/build
15+
```
16+
17+
## CLI Commands
18+
19+
### `druid-ui-build`
20+
21+
Compile TypeScript/JSX to WASM:
22+
23+
```bash
24+
druid-ui-build <input> [options]
25+
26+
Options:
27+
--out <file> Output WASM file (default: dist/component.wasm)
28+
--wit <dir> WIT directory (default: wit)
29+
--world <name> World name (default: druid-ui)
30+
```
31+
32+
**Example:**
33+
34+
```bash
35+
druid-ui-build src/index.tsx --out build/app.wasm
36+
```
37+
38+
### `druid-ui-gen-types`
39+
40+
Generate TypeScript types from WIT files:
41+
42+
```bash
43+
druid-ui-gen-types <world> [options]
44+
45+
Options:
46+
--wit-dir <dir> WIT directory (default: wit)
47+
--out-dir <dir> Output directory (default: types)
48+
```
49+
50+
**Example:**
51+
52+
```bash
53+
druid-ui-gen-types druid-ui --out-dir generated
54+
```
55+
56+
## Programmatic API
57+
58+
```typescript
59+
import { buildComponent, generateTypes } from '@druid-ui/build';
60+
61+
// Build component
62+
await buildComponent({
63+
entry: 'src/index.tsx',
64+
output: 'dist/component.wasm',
65+
witDir: 'wit',
66+
world: 'druid-ui'
67+
});
68+
69+
// Generate types
70+
await generateTypes({
71+
world: 'druid-ui',
72+
witDir: 'wit',
73+
outDir: 'types'
74+
});
75+
```
76+
77+
## Package Scripts
78+
79+
```json
80+
{
81+
"scripts": {
82+
"build": "druid-ui-build src/index.tsx",
83+
"gen-types": "druid-ui-gen-types druid-ui",
84+
"dev": "vite"
85+
}
86+
}
87+
```
88+
89+
## See Also
90+
91+
- [@druid-ui/component](./component.md)
92+
- [@druid-ui/vite](./vite.md)

0 commit comments

Comments
 (0)