Skip to content

Commit ec81aed

Browse files
committed
docs(usage): document el helper and type namespace 🍷
- Add API table row and section Helper (el) with example and el.root, el.node, tag aliases - Document default export as callable with create, render, el and Types namespace import - Add Schema2UIDefaultExport to type reference and update tests list
1 parent 0619d1d commit ec81aed

File tree

1 file changed

+37
-7
lines changed

1 file changed

+37
-7
lines changed

USAGE.md

Lines changed: 37 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ API, node shape, layout and style — create schema from definition, render to D
77
- [Quick Start](#quick-start)
88
- [Flow Overview](#flow-overview)
99
- [API Overview](#api-overview)
10+
- [Helper (el)](#helper-el)
1011
- [Node Shape](#node-shape)
1112
- [Layout and Style](#layout-and-style)
1213
- [Void Tags and Special Elements](#void-tags-and-special-elements)
@@ -41,12 +42,40 @@ render(schema, document.getElementById('app'))
4142

4243
## API Overview
4344

44-
| Function / export | Returns | Description |
45-
| :----------------------------------------------------- | :------- | :--------------------------------------------- |
46-
| [`create(definition)`](#createdefinition) | `Schema` | Validate and freeze definition; return schema. |
47-
| [`render(schema, container)`](#renderschema-container) | `void` | Build DOM from schema and append to container. |
45+
| Function / export | Returns | Description |
46+
| :----------------------------------------------------- | :-------- | :--------------------------------------------- |
47+
| [`create(definition)`](#createdefinition) | `Schema` | Validate and freeze definition; return schema. |
48+
| [`render(schema, container)`](#renderschema-container) | `void` | Build DOM from schema and append to container. |
49+
| `el` | namespace | Helper: `el.root`, `el.node`, `el.div`, etc. |
4850

49-
Named exports: `create`, `render`, and all types from `Types` (re-exported). Default export: `{ create, render }`.
51+
Named exports: `create`, `render`, `el`, and `Types` (re-exported). Default export: callable; calling it returns `{ create, render, el }`, and the callable itself has `.create`, `.render`, `.el` for direct use (e.g. `import Schema2UI from '@neabyte/schema2ui'` then `Schema2UI().create(...)` or `Schema2UI.create(...)`).
52+
53+
## Helper (el)
54+
55+
Use the `el` namespace to build definitions with less boilerplate. Same flow: `create(el.root(...))` → schema → `render(schema, container)`.
56+
57+
```typescript
58+
// 1. Import create, render, and the el helper
59+
import { create, render, el } from '@neabyte/schema2ui'
60+
61+
// 2. Build definition with el.root(...), pass to create() to get frozen schema (tag aliases: el.header, el.main, el.h1, el.a)
62+
const schema = create(
63+
el.root(
64+
el.header(
65+
{ id: 'header', layout: { width: '100%', height: 56 }, style: { fill: '#1a1a2e' } },
66+
el.h1({ id: 'title', style: { font: '20px sans-serif', fill: '#eee' } }, 'Hello')
67+
),
68+
el.main({ layout: { width: '100%', flex: 1 } }, el.a({ attrs: { href: '/' } }, 'Home'))
69+
)
70+
)
71+
72+
// 3. Render schema into the container element
73+
render(schema, document.getElementById('app'))
74+
```
75+
76+
- **`el.root()`** — returns `Definition` with empty `root: []`. **`el.root(n1, n2, ...)`** or **`el.root([n1, n2])`** — returns `Definition` for `create()`.
77+
- **`el.node(type, propsOrContent?, ...rest)`** — generic factory (e.g. custom elements). Second arg: optional props object, text content, or first child; `rest`: more children or content. Content (string) and children cannot be mixed. Void tags must not have content or children.
78+
- **Tag aliases**`el.div`, `el.span`, `el.main`, `el.header`, `el.h1`, `el.a`, `el.table`, `el.img`, `el.template`, etc. (container + void from `Constant.tagAliases`). Container tags accept props, content (string), or children (nodes). Void tags (img, br, input, …) accept props only.
5079

5180
## Node Shape
5281

@@ -98,16 +127,17 @@ Build DOM from `schema.root` and append each resulting node into `container`. Us
98127

99128
## Type Reference
100129

101-
Types are re-exported from the package: `import type { Attrs, Definition, Layout, Node, Schema, Style } from '@neabyte/schema2ui'`.
130+
Types are re-exported under the `Types` namespace: `import type * as Types from '@neabyte/schema2ui'` then use `Types.Node`, `Types.Schema`, `Types.Attrs`, etc.
102131

103132
- **Definition:** `{ root: readonly Node[] }` — Input to `create`.
104133
- **Schema:** `{ readonly root: readonly Node[] }` — Output of `create`; frozen.
105134
- **Node:** Object with `type` (string) and optional `id`, `layout`, `style`, `attrs`, `content`, `src`, `alt`, `children` (readonly array of Node). Void tags must not have `children`.
106135
- **Layout:** Optional `width`, `height`, `x`, `y`, `flex`, `gap` — each `number | string`.
107136
- **Style:** Optional `border`, `borderRadius`, `boxShadow`, `color`, `fill`, `font`, `margin`, `opacity`, `padding`, `stroke`, `transition` — each `string`.
108137
- **Attrs:** `Record<string, string | number | boolean>` — HTML attributes. Special handling for `class`/`className`, `style` (string), `value`, `checked`, `disabled` on form elements.
138+
- **Schema2UIDefault:** `{ create, render }` — shape returned when calling the default export. **Schema2UIDefaultExport:** callable with `.create`, `.render`, `.el`; calling it returns `Schema2UIDefault & { el: El }`.
109139

110140
## Reference
111141

112142
- [README](README.md) — Installation and quick start.
113-
- Tests under `tests/` — Create, Constant, Validator, Render.
143+
- Tests under `tests/`Constant, Create, Helper, Index, Render, Validator.

0 commit comments

Comments
 (0)