# XWUIPage

A **block-based page/document surface** - the Notion/Obsidian paradigm as one
XWUI component. A page is an ordered list of typed blocks; XWUIPage renders
them in **view** mode or makes the whole document editable in **edit** mode
(insert via searchable menu or `/`, drag-reorder, duplicate/delete/turn-into,
inline editing per block).

## Block modes

| Mode | Backed by | Edit support |
|------|-----------|--------------|
| `markdown` | XWUIMarkdown | inline text editor |
| `quote` | XWUIMarkdown blockquote | inline text editor |
| `callout` | XWUIAlert | text + variant picker |
| `code` | **XWUIScriptEditor** | full editor (`view`/`edit`) |
| `diagram` | **XWUIDiagram** | node/edge editing, persisted as JSON |
| `table` | XWUITable | - (JSON source) |
| `example` | XWUIPreviewerXWCode | - (docs live demo) |
| `image` | XWUIImage | URL / alt / caption fields |
| `gallery` | XWUIImageList | - |
| `toggle` | native `<details>` + nested blocks | label + nested blocks |
| `tabs` | tab strip + nested blocks | - |
| `columns` | CSS grid + nested blocks | - |
| `todo` | native checkable list | check / relabel / add / remove |
| `divider` | `<hr>` | - |
| `math` | **XWUIMath** (native MathML) | source + live preview |
| `chart` | XWUIChart (lazy-loaded) | - |

## Diagram text DSL

Author flowcharts as text - parsed by the component, rendered and edited by
XWUIDiagram (no Mermaid):

```
Start -> Validate: submit
Validate -> Save: ok
Validate -> Start: errors
Save -> Done
```

## Two modes

```ts
const page = new XWUIPage(el, { blocks }, {
  mode: 'edit',                       // or 'view'
  onChange: (blocks) => save(blocks), // serialized document on every change
});
page.toggleMode();                    // flip view ↔ edit
page.getDocument();                   // → blocks JSON (round-trips losslessly)
```

Every block accepts inline `content` or a `src` URL (resolved through the
pluggable `resolve()` - live server or static bundle with one swap). The
document is schema-validated JSON, so an agent can author or edit a whole page
as data (AI-native).

## Host integration hooks

Embedding XWUIPage inside a larger app (a docs site, an SPA) sometimes needs to
own behavior XWUIPage would otherwise handle itself:

- `onAnchorNavigate?(id, e)` - claim a heading/TOC/in-content `#id` link click
  before the default scroll + `history.replaceState`. Return `true` when the
  host's own router already handled it (e.g. hash-based SPA routing, where
  XWUIPage's replaceState would otherwise clobber the route).
- `onRenderCodeFence?({ source, lang, pre })` - swap a rendered markdown code
  fence for host-branded chrome (syntax highlighting, copy button). Return an
  element to replace it with, or nothing to keep the default `<pre><code>`.
- `autosizePreviews` - size each `example` block's preview iframe to its
  rendered content height instead of the previewer's default.
- `XWUIPageMarkdownBlock.trimToIntro` - drop a leading `# Title` and
  everything from the first `##`+ heading, keeping only the lead paragraph(s)
  (e.g. a short hero intro from a .md whose full body renders elsewhere).

## Migration

`XWUIPageDocs` is the deprecated alias of this component - old imports and the
`<xwui-page-docs>` element keep working unchanged.

## Product spec sheet

A read-only product page with an image hero, an inline-JSON spec table, a warning callout and a code snippet, plus a floating table of contents.

```example
file: examples/ProductSpecSheet.ts
html: examples/ProductSpecSheet.html
title: Product spec sheet
description: View-mode product sheet with image, table, callout and code blocks and a floating TOC.
```

## Lazy long-read article

A long-form article whose heavy diagram and chart blocks mount only as they scroll into view via `lazy` + `lazyRootMargin`.

```example
file: examples/LazyLongRead.ts
html: examples/LazyLongRead.html
title: Lazy long-read article
description: View-mode article with lazy-mounted diagram and chart blocks.
```