@nodex.ui/core 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  # Markdown
2
2
 
3
- Use `b-ui="markdown"` (or the pure Nodex UI `Markdown` component) to render Markdown or mount an editable Markdown document. Read-only parsing uses the vendored `src/runtime/marked/marked.min.js` (marked v15). Fenced ` ```mermaid ` code blocks render as inline SVG via `src/runtime/mermaid/mermaid.esm.min.mjs`. Fenced ` ```base-ui ` code blocks render as a live Nodex UI preview through the page's global static runtime (`window.thebase`, e.g. `dist/nodexui.min.js`).
3
+ Use `b-ui="markdown"` (or the pure Nodex UI `Markdown` component) to render Markdown or mount an editable Markdown document. Read-only parsing uses the vendored `src/runtime/marked/marked.min.js` (marked v15). Fenced ` ```mermaid ` code blocks render as inline SVG via `src/runtime/mermaid/mermaid.esm.min.js`. Fenced ` ```base-ui ` code blocks render as a live Nodex UI preview through the page's global static runtime (`window.thebase`, e.g. `dist/nodexui.min.js`).
4
4
 
5
5
  Editable mode lazy-loads `dist/runtime/milkdown/milkdown-editor.js`, which bundles Milkdown, Yjs, and y-webrtc only when `b-att-editable="true"` / `editable="true"` is used. The editor runtime enables CommonMark, GFM, history, clipboard, cursor, listener, indent, upload, block handle, tooltip, slash, streaming, and diff plugins. Collaborative mode uses Milkdown's Yjs-aware collab undo/redo instead of the plain history stack.
6
6
 
@@ -93,9 +93,33 @@ A fenced ` ```base-ui ` block renders as a live component, not a code sample:
93
93
  </div>
94
94
  ````
95
95
 
96
+ ## MDX-style components in prose
97
+
98
+ Pure Nodex UI tags can be written straight in a Markdown file, like MDX with React. A tag that starts with a capital letter is lifted out of the source before Markdown is parsed (so `onClick` keeps its casing) and mounted as a real component. A tag alone on its line becomes a block; a tag inside a sentence stays inline.
99
+
100
+ ````md
101
+ export const count = 2
102
+
103
+ import { bump } from "./counter.js"
104
+ import Chart from "./chart.component.js"
105
+
106
+ Total <Badge><t t-esc="state.count"/></Badge> items.
107
+
108
+ <Button onClick="bump">Add one</Button>
109
+
110
+ <Chart/>
111
+ ````
112
+
113
+ - Tag syntax is the Nodex template syntax (`'quoted'` string props, `t-esc`, `t-on-*`), not JSX: write `<t t-esc="state.count"/>`, not `{count}`. Children are template markup, not Markdown.
114
+ - `export const name = <JSON>` seeds `state.name`. The `state` is shared by every tag in the document, so the Badge above updates when the Button changes it. Only JSON is accepted; nothing in the `.md` is evaluated.
115
+ - `import X from "./x.js"` and `import { a, b as c } from "./x.js"` (one line each). Relative paths resolve against `src` (else the page) and must stay on the same origin; a bare name goes through the page's import map. An export with `static template` (a component class) becomes a usable tag; any other export (a function, a value) is available to the tags as `this.<name>` / `<name>`, with `this.state` for handlers.
116
+ - Tags inside inline code, fenced code and `List<String>`-style text that never closes are left alone.
117
+ - A ` ```base-ui-render ` fence mounts like ` ```base-ui ` but shows only the live component, with no source pane.
118
+ - Tags run author code (handlers, imports), so `nodexUi="false"` turns all of this off for Markdown you do not trust.
119
+
96
120
  ## Options and attributes
97
121
 
98
- - `b-att-src` / `src` — fetch a remote Markdown file instead of using inline content.
122
+ - `b-att-src` / `src` — fetch a remote Markdown file instead of using inline content. A folder URL (trailing `/`) or a missing document falls back to that folder's `readme.md` (or `README.md`), the folder's default document.
99
123
  - `b-att-content` / `content` — a static `<script type="text/markdown">` child (or a `<template>`), `b-att-content`, or the element's own text content supplies the Markdown source when no `src` is set.
100
124
  - `b-att-mermaid` / `mermaid` — set to `"false"` to skip mermaid diagram rendering (defaults to enabled). Diagrams use mermaid's dark theme when the nearest `data-bs-theme` (else the system preference) is dark.
101
125
  - `b-att-base-ui` / `nodexUi` — set to `"false"` to skip live-mounting fenced ` ```base-ui ` blocks; they render as plain code instead (defaults to enabled).
@@ -104,6 +128,7 @@ A fenced ` ```base-ui ` block renders as a live component, not a code sample:
104
128
  - `b-att-room` / `room` — y-webrtc room name for collaborative sessions (defaults to `b-markdown`).
105
129
  - `b-att-password` / `password` — optional y-webrtc room password.
106
130
  - `b-att-signaling` / `signaling` — comma-separated signaling URLs for the static API, or an array prop for Nodex.
131
+ - `tree` + `onNavigate` (Nodex only) — `tree` is the URL of a `tree.json` manifest written by `scripts/doc-folder-tree.mjs` (for example `/docs/tree.json`); with `onNavigate(path, hash)`, a click on a relative link is resolved against `src`, looked up in the manifest, and handed to `onNavigate` when found. Links not in the tree keep the browser default.
107
132
 
108
133
  See `dist/nodexui.registry.json` for the full attribute list.
109
134
 
@@ -0,0 +1,85 @@
1
+ # components
2
+
3
+ > Index of the documents in this folder. Opened by default when a folder path or a missing document is requested.
4
+
5
+ <!-- docs-index:start (auto-generated; edit documents, not this block) -->
6
+
7
+ ## Documents
8
+ - [Accordion](accordion.md): Use b-ui="accordion" for grouped disclosure panels.
9
+ - [Alert Dialog](alert-dialog.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
10
+ - [Alert](alert.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
11
+ - [ApiDoc](apidoc.md): Use b-ui="apidoc" (or the pure Nodex UI ApiDoc component) to render an OpenAPI 3.0+ JSON document as browsable API documentation: a grouped sidebar, per-oper...
12
+ - [Aspect Ratio](aspect-ratio.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
13
+ - [Attachment](attachment.md): Use b-ui="attachment" for a CDN-ready attachment card with media, metadata, upload state, and actions.
14
+ - [Avatar](avatar.md): Use b-ui="avatar" for a CDN-ready avatar component.
15
+ - [Badge](badge.md): Small status label for counts, states, and metadata.
16
+ - [Block Viewer](block-viewer.md): BlockViewer is the page-root component used by Nodex UI block gallery detail pages (examples/blocks/.html). It reads a title/description from document.body.d...
17
+ - [Breadcrumb](breadcrumb.md): Displays the path to the current resource using a hierarchy of links.
18
+ - [Bubble](bubble.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
19
+ - [Button Group](button-group.md): Groups related buttons while preserving native button semantics.
20
+ - [Button](button.md): Use b-ui="button" on a native button or link.
21
+ - [Calendar](calendar.md): Use b-ui="calendar" for a CDN-ready calendar component.
22
+ - [Card](card.md): Card, CardHeader, CardBody, CardFooter, CardTitle, and CardDescription each accept className (String, optional) and render their default slot as-is. Card add...
23
+ - [Carousel](carousel.md): Use b-ui="carousel" for a CDN-ready carousel component.
24
+ - [Chart](chart.md): Use b-ui="chart" for a CDN-ready chart component styled after the current shadcn chart pages.
25
+ - [Checkbox](checkbox.md): Native checkbox input or label wrapper.
26
+ - [Clipboard Button](clipboard-button.md): Use b-ui="clipboard-button" on a native button to copy specific data to the clipboard. Built on the same variant/size classes and built-in .btn styling as Bu...
27
+ - [Code Editor](code-editor.md): A dependency-free code box with line numbers, syntax colouring, Tab/Shift+Tab indent, Enter auto-indent and Format, Copy and Edit/View buttons. Pure Nodex UI...
28
+ - [Collapsible](collapsible.md): Use b-ui="collapsible" for a single disclosure region.
29
+ - [Combobox](combobox.md): Use b-ui="combobox" for a CDN-ready combobox component.
30
+ - [Command](command.md): Use b-ui="command" for a CDN-ready command component.
31
+ - [Context Menu](context-menu.md): Use b-ui="context-menu" for a CDN-ready context menu component.
32
+ - [Data Table](data-table.md): Use b-ui="data-table" for a CDN-ready data table component.
33
+ - [Date Picker](date-picker.md): Use b-ui="date-picker" for a CDN-ready date picker component.
34
+ - [Dialog](dialog.md): DialogContent also accepts showCloseButton (default true) to render the shadcn-style top-right close control; pass false to hide it. DialogTrigger, DialogCon...
35
+ - [Direction](direction.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
36
+ - [DocViewer](doc-viewer.md): Renders a whole Markdown folder: a navigation tree beside the selected document. It combines MarkdownTree (sidebar) and Markdown (content), the same pattern...
37
+ - [Drawer](drawer.md): DrawerContent is driven by a real bootstrap.Offcanvas instance bound to its own root (rendered as .offcanvas.offcanvas-bottom, permanently mounted rather tha...
38
+ - [Dropdown Menu](dropdown-menu.md): Displays a menu to the user, such as a set of actions or functions, triggered by a button.
39
+ - [Empty](empty.md): Use b-ui="empty" for an accessible empty state. The component mirrors shadcn's Base Empty composition: header, media, title, description, and content.
40
+ - [Field](field.md): Combine labels, controls, and help text to compose accessible form fields and grouped inputs.
41
+ - [Form](form.md): Build an accessible Bug Report form with Nodex UI Field layout, Nodex UI Button actions, and Nodex t-model input bindings.
42
+ - [Hover Card](hover-card.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
43
+ - [Icon](icon.md): Nodex UI includes the full Lucide SVG icon set as a built-in CDN icon library.
44
+ - [Input Otp](input-otp.md): Use b-ui="input-otp" for a CDN-ready input otp component.
45
+ - [Input](input.md): Use b-ui="input" on a native input element.
46
+ - [Item](item.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
47
+ - [Kbd](kbd.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
48
+ - [Label](label.md): Form label with consistent spacing and optional required marker.
49
+ - [Markdown](markdown.md): Use b-ui="markdown" (or the pure Nodex UI Markdown component) to render Markdown or mount an editable Markdown document. Read-only parsing uses the vendored...
50
+ - [Marker](marker.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
51
+ - [Menubar](menubar.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
52
+ - [Message Scroller](message-scroller.md): Use b-ui="message-scroller" for a CDN-ready message scroller component.
53
+ - [Message](message.md): Use b-ui="message" for a CDN-ready message component.
54
+ - [Native Select](native-select.md): Browser-native select control with standard styling.
55
+ - [Navigation Menu](navigation-menu.md): Use b-ui="navigation-menu" for horizontal site or app navigation.
56
+ - [Pagination](pagination.md): Use b-ui="pagination" on a nav containing a list of links or buttons.
57
+ - [Popover](popover.md): Use b-ui="popover" with trigger and content nodes.
58
+ - [Progress](progress.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
59
+ - [Pwa](pwa.md): Use b-ui="pwa" for a bottom-anchored install/permission prompt (an "Add to Home Screen" or "Allow notifications" sheet). Pwa is presentational only — it owns...
60
+ - [QR Card](qr-card.md): A centred card with a QR code, a title and a description, built from the Card parts (Card, CardBody, CardHeader, CardTitle, CardDescription). Give it qrConte...
61
+ - [Questionnaire](questionnaire.md): Use b-ui="questionnaire" for a CDN-ready questionnaire component.
62
+ - [Radio Group](radio-group.md): Native radio input or label wrapper.
63
+ - [Resizable](resizable.md): Use b-ui="resizable" for a CDN-ready resizable component.
64
+ - [Scroll Area](scroll-area.md): Use b-ui="scroll-area" for a CDN-ready scroll area component.
65
+ - [Select](select.md): Set useTip="1" to move supportingText into a tooltip: a question-mark icon appears right after the label, in the same label box, and the text shows on hover...
66
+ - [Separator](separator.md): Visual divider with separator semantics.
67
+ - [Sheet](sheet.md): Use b-ui="sheet" for offcanvas panels.
68
+ - [Shell](shell.md): Use b-ui="shell" for a collapsible app shell: a desktop-collapsible/mobile off-canvas sidebar next to a sticky header and scrollable content region.
69
+ - [Sidebar](sidebar.md): Use b-ui="sidebar" for app navigation panels. The component mirrors shadcn's composable Sidebar parts: header, content, footer, groups, menu rows, actions, n...
70
+ - [Skeleton](skeleton.md): Loading placeholder for content that is not ready yet.
71
+ - [Slider](slider.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
72
+ - [Spinner](spinner.md): Inline loading indicator using built-in spinner classes.
73
+ - [Switch](switch.md): Checkbox-backed switch control using role="switch".
74
+ - [Table](table.md): Native table styling for static or server-rendered data.
75
+ - [Tabs](tabs.md): Matches shadcn/the built-in Tabs: TabsList renders as a segmented pill control on a muted background by default, or a transparent underline list via variant=...
76
+ - [Text Editor](text-editor.md): Use b-ui="text-editor" (or the pure Nodex UI TextEditor component) for WYSIWYG rich-text editing backed by Milkdown (ProseMirror + a Markdown-aware schema, v...
77
+ - [Textarea](textarea.md): Native multiline text input with Nodex UI and built-in styling.
78
+ - [Theme Button](theme-button.md): Use b-ui="theme-button" for an icon-only light/dark theme toggle.
79
+ - [Toast](toast.md): Use b-ui="toast" for transient status messages.
80
+ - [Toggle Group](toggle-group.md): Use b-ui="toggle-group" for a CDN-ready toggle group component.
81
+ - [Toggle](toggle.md): Use b-ui="toggle" for a CDN-ready toggle component.
82
+ - [Tooltip](tooltip.md): Use b-ui="tooltip" with either b-att-content or a tooltip content child.
83
+ - [Typography](typography.md): Small text helpers for plain content.
84
+
85
+ <!-- docs-index:end -->
package/docs/i18n.md CHANGED
@@ -3,7 +3,7 @@
3
3
  Instructions for adding translations to a page or app with Nodex UI i18n service (`nodexui/i18n`). It is optional and standalone: no framework or component runtime, and it is not part of the main bundles.
4
4
 
5
5
  - **Audience:** developers adding a language switcher or translating an existing page.
6
- - **Runnable example:** `examples/i18n/` (open `/examples/i18n/` from `npm run dev`).
6
+ - **Runnable example:** `examples/components/i18n/` (the **i18n** tab of the examples app; open `/examples/index.html#/i18n` from `npm run dev`).
7
7
  - **Real-world use:** `emvhub/i18n.js` and the `i18n/*.po` folders beside each emvhub module; the examples app does the same in `examples/i18n.js` and `examples/components/*/i18n/` (English and Vietnamese). Update catalogs with `node scripts/emvhub-i18n.mjs extract [--site=emvhub|examples/components] [newLang]`.
8
8
 
9
9
  ## 1. How it works
package/docs/icons.md CHANGED
@@ -22,7 +22,7 @@ Load the normal Nodex UI assets. No separate icon script is required.
22
22
  <script src="https://cdn.jsdelivr.net/npm/nodexui@latest/dist/nodexui.min.js" defer></script>
23
23
  ```
24
24
 
25
- `https://unpkg.com/nodexui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.3.1`, or `@1` to take only non-breaking updates) instead of `@latest` for production. `b-icon` also works with the [pure Nodex UI `Icon` component](components/icon.md) — the recommended API in an application; the classic script above is for pages using the static `b-ui` API.
25
+ `https://unpkg.com/nodexui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.3.6`, or `@1` to take only non-breaking updates) instead of `@latest` for production. `b-icon` also works with the [pure Nodex UI `Icon` component](components/icon.md) — the recommended API in an application; the classic script above is for pages using the static `b-ui` API.
26
26
 
27
27
  The build publishes every Lucide SVG to `dist/icons/lucide/` and writes the generated icon manifest to `dist/icons/lucide.json`.
28
28
 
package/docs/index.md ADDED
@@ -0,0 +1,132 @@
1
+ # Nodex UI Documentation Index
2
+
3
+ > Nodex UI (`nodexui`) is a component library built on Owl + Bootstrap 5 with shadcn-aligned tokens. It offers two APIs: static `b-ui="..."` markup and pure Nodex UI (Owl) components. Start with `usage-guide.md`; fetch only the pages you need.
4
+
5
+ This file is the single entry point for AI agents. Every link is **relative to this file**, so resolve it against this file's own URL (for example, `components/button.md` next to `https://raw.githubusercontent.com/<owner>/<repo>/<branch>/docs/index.md`). Pages are grouped by folder below; `v2/` is the upstream Owl framework reference. Regenerate with `npm run generate:docs-index`.
6
+
7
+ <!-- docs-index:start (auto-generated; edit documents, not this block) -->
8
+
9
+ ## Guides
10
+ - [Analytics](analytics.md): Nodex UI ships a cookieless web-analytics service, ported from @plausible-analytics/tracker 0.4.6 (MIT; notice in LICENSE). Nothing is collected until the pa...
11
+ - [Skill for AI](base-ui-skill.md): Nodex UI skill teaches an AI coding agent how to build apps and components with NodexUI: scaffolding a PWA, emitting real components and icons, and packaging...
12
+ - [Blocks](blocks.md): Nodex UI blocks are static HTML compositions styled by the same shadcn-aligned tokens as the component library. They are based on the public shadcn/ui blocks...
13
+ - [Component Authoring](component-authoring.md): Nodex UI exposes two intentional public APIs from the same component source folder. Both must share styling, accessibility semantics, and — where practical —...
14
+ - [i18n service](i18n.md): Instructions for adding translations to a page or app with Nodex UI i18n service (nodexui/i18n). It is optional and standalone: no framework or component run...
15
+ - [Built-in Icons](icons.md): Nodex UI ships the full Lucide icon set as a built-in CDN-ready icon library. Icons use the b-icon attribute, render as CSS masks, and inherit currentColor f...
16
+ - [Installation](installation.md): See the Usage Guide for the end-to-end integration path (choosing an API, install, theming, verification). This page covers install mechanics only.
17
+ - [Nodex UI Component](owl-components.md): See the Usage Guide for when to reach for this API versus the static b-ui one. This page covers the pure Nodex UI API only.
18
+ - [QR](qr.md): Nodex UI ships a standalone QR service: a QR code generator and the VietQR (Napas/EMV) payment payload builder. It wraps @thebeanfamily/vietqr, which bundles...
19
+ - [Registry](registry.md): Every release publishes dist/nodexui.registry.json. The registry lists package metadata, CDN paths, build files, themes, and per-component metadata (type, de...
20
+ - [Runtime API](runtime-api.md): Nodex UI exposes one browser global: window.thebase. window.NodexUI still points to the same object as a deprecated alias for 1.x pages; it will be removed i...
21
+ - [Theming](theming.md): Set the theme on html or a subtree:
22
+ - [Usage Guide — Integrating Nodex UI Into a Project](usage-guide.md): This is the single entry point for adding Nodex UI to a consumer project (a static page, a Base HUB website page, a server-rendered app, or your own applicat...
23
+
24
+ ## components
25
+ - [Accordion](components/accordion.md): Use b-ui="accordion" for grouped disclosure panels.
26
+ - [Alert Dialog](components/alert-dialog.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
27
+ - [Alert](components/alert.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
28
+ - [ApiDoc](components/apidoc.md): Use b-ui="apidoc" (or the pure Nodex UI ApiDoc component) to render an OpenAPI 3.0+ JSON document as browsable API documentation: a grouped sidebar, per-oper...
29
+ - [Aspect Ratio](components/aspect-ratio.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
30
+ - [Attachment](components/attachment.md): Use b-ui="attachment" for a CDN-ready attachment card with media, metadata, upload state, and actions.
31
+ - [Avatar](components/avatar.md): Use b-ui="avatar" for a CDN-ready avatar component.
32
+ - [Badge](components/badge.md): Small status label for counts, states, and metadata.
33
+ - [Block Viewer](components/block-viewer.md): BlockViewer is the page-root component used by Nodex UI block gallery detail pages (examples/blocks/.html). It reads a title/description from document.body.d...
34
+ - [Breadcrumb](components/breadcrumb.md): Displays the path to the current resource using a hierarchy of links.
35
+ - [Bubble](components/bubble.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
36
+ - [Button Group](components/button-group.md): Groups related buttons while preserving native button semantics.
37
+ - [Button](components/button.md): Use b-ui="button" on a native button or link.
38
+ - [Calendar](components/calendar.md): Use b-ui="calendar" for a CDN-ready calendar component.
39
+ - [Card](components/card.md): Card, CardHeader, CardBody, CardFooter, CardTitle, and CardDescription each accept className (String, optional) and render their default slot as-is. Card add...
40
+ - [Carousel](components/carousel.md): Use b-ui="carousel" for a CDN-ready carousel component.
41
+ - [Chart](components/chart.md): Use b-ui="chart" for a CDN-ready chart component styled after the current shadcn chart pages.
42
+ - [Checkbox](components/checkbox.md): Native checkbox input or label wrapper.
43
+ - [Clipboard Button](components/clipboard-button.md): Use b-ui="clipboard-button" on a native button to copy specific data to the clipboard. Built on the same variant/size classes and built-in .btn styling as Bu...
44
+ - [Code Editor](components/code-editor.md): A dependency-free code box with line numbers, syntax colouring, Tab/Shift+Tab indent, Enter auto-indent and Format, Copy and Edit/View buttons. Pure Nodex UI...
45
+ - [Collapsible](components/collapsible.md): Use b-ui="collapsible" for a single disclosure region.
46
+ - [Combobox](components/combobox.md): Use b-ui="combobox" for a CDN-ready combobox component.
47
+ - [Command](components/command.md): Use b-ui="command" for a CDN-ready command component.
48
+ - [Context Menu](components/context-menu.md): Use b-ui="context-menu" for a CDN-ready context menu component.
49
+ - [Data Table](components/data-table.md): Use b-ui="data-table" for a CDN-ready data table component.
50
+ - [Date Picker](components/date-picker.md): Use b-ui="date-picker" for a CDN-ready date picker component.
51
+ - [Dialog](components/dialog.md): DialogContent also accepts showCloseButton (default true) to render the shadcn-style top-right close control; pass false to hide it. DialogTrigger, DialogCon...
52
+ - [Direction](components/direction.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
53
+ - [DocViewer](components/doc-viewer.md): Renders a whole Markdown folder: a navigation tree beside the selected document. It combines MarkdownTree (sidebar) and Markdown (content), the same pattern...
54
+ - [Drawer](components/drawer.md): DrawerContent is driven by a real bootstrap.Offcanvas instance bound to its own root (rendered as .offcanvas.offcanvas-bottom, permanently mounted rather tha...
55
+ - [Dropdown Menu](components/dropdown-menu.md): Displays a menu to the user, such as a set of actions or functions, triggered by a button.
56
+ - [Empty](components/empty.md): Use b-ui="empty" for an accessible empty state. The component mirrors shadcn's Base Empty composition: header, media, title, description, and content.
57
+ - [Field](components/field.md): Combine labels, controls, and help text to compose accessible form fields and grouped inputs.
58
+ - [Form](components/form.md): Build an accessible Bug Report form with Nodex UI Field layout, Nodex UI Button actions, and Nodex t-model input bindings.
59
+ - [Hover Card](components/hover-card.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
60
+ - [Icon](components/icon.md): Nodex UI includes the full Lucide SVG icon set as a built-in CDN icon library.
61
+ - [Input Otp](components/input-otp.md): Use b-ui="input-otp" for a CDN-ready input otp component.
62
+ - [Input](components/input.md): Use b-ui="input" on a native input element.
63
+ - [Item](components/item.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
64
+ - [Kbd](components/kbd.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
65
+ - [Label](components/label.md): Form label with consistent spacing and optional required marker.
66
+ - [Markdown](components/markdown.md): Use b-ui="markdown" (or the pure Nodex UI Markdown component) to render Markdown or mount an editable Markdown document. Read-only parsing uses the vendored...
67
+ - [Marker](components/marker.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
68
+ - [Menubar](components/menubar.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
69
+ - [Message Scroller](components/message-scroller.md): Use b-ui="message-scroller" for a CDN-ready message scroller component.
70
+ - [Message](components/message.md): Use b-ui="message" for a CDN-ready message component.
71
+ - [Native Select](components/native-select.md): Browser-native select control with standard styling.
72
+ - [Navigation Menu](components/navigation-menu.md): Use b-ui="navigation-menu" for horizontal site or app navigation.
73
+ - [Pagination](components/pagination.md): Use b-ui="pagination" on a nav containing a list of links or buttons.
74
+ - [Popover](components/popover.md): Use b-ui="popover" with trigger and content nodes.
75
+ - [Progress](components/progress.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
76
+ - [Pwa](components/pwa.md): Use b-ui="pwa" for a bottom-anchored install/permission prompt (an "Add to Home Screen" or "Allow notifications" sheet). Pwa is presentational only — it owns...
77
+ - [QR Card](components/qr-card.md): A centred card with a QR code, a title and a description, built from the Card parts (Card, CardBody, CardHeader, CardTitle, CardDescription). Give it qrConte...
78
+ - [Questionnaire](components/questionnaire.md): Use b-ui="questionnaire" for a CDN-ready questionnaire component.
79
+ - [Radio Group](components/radio-group.md): Native radio input or label wrapper.
80
+ - [Resizable](components/resizable.md): Use b-ui="resizable" for a CDN-ready resizable component.
81
+ - [Scroll Area](components/scroll-area.md): Use b-ui="scroll-area" for a CDN-ready scroll area component.
82
+ - [Select](components/select.md): Set useTip="1" to move supportingText into a tooltip: a question-mark icon appears right after the label, in the same label box, and the text shows on hover...
83
+ - [Separator](components/separator.md): Visual divider with separator semantics.
84
+ - [Sheet](components/sheet.md): Use b-ui="sheet" for offcanvas panels.
85
+ - [Shell](components/shell.md): Use b-ui="shell" for a collapsible app shell: a desktop-collapsible/mobile off-canvas sidebar next to a sticky header and scrollable content region.
86
+ - [Sidebar](components/sidebar.md): Use b-ui="sidebar" for app navigation panels. The component mirrors shadcn's composable Sidebar parts: header, content, footer, groups, menu rows, actions, n...
87
+ - [Skeleton](components/skeleton.md): Loading placeholder for content that is not ready yet.
88
+ - [Slider](components/slider.md): See Nodex UI Component for how to load nodexui and dist/nodexui.templates.xml.
89
+ - [Spinner](components/spinner.md): Inline loading indicator using built-in spinner classes.
90
+ - [Switch](components/switch.md): Checkbox-backed switch control using role="switch".
91
+ - [Table](components/table.md): Native table styling for static or server-rendered data.
92
+ - [Tabs](components/tabs.md): Matches shadcn/the built-in Tabs: TabsList renders as a segmented pill control on a muted background by default, or a transparent underline list via variant=...
93
+ - [Text Editor](components/text-editor.md): Use b-ui="text-editor" (or the pure Nodex UI TextEditor component) for WYSIWYG rich-text editing backed by Milkdown (ProseMirror + a Markdown-aware schema, v...
94
+ - [Textarea](components/textarea.md): Native multiline text input with Nodex UI and built-in styling.
95
+ - [Theme Button](components/theme-button.md): Use b-ui="theme-button" for an icon-only light/dark theme toggle.
96
+ - [Toast](components/toast.md): Use b-ui="toast" for transient status messages.
97
+ - [Toggle Group](components/toggle-group.md): Use b-ui="toggle-group" for a CDN-ready toggle group component.
98
+ - [Toggle](components/toggle.md): Use b-ui="toggle" for a CDN-ready toggle component.
99
+ - [Tooltip](components/tooltip.md): Use b-ui="tooltip" with either b-att-content or a tooltip content child.
100
+ - [Typography](components/typography.md): Small text helpers for plain content.
101
+
102
+ ## v2/learning
103
+ - [🦉 How to test Components 🦉](v2/learning/how_to_test.md): It is a good practice to test applications and components to ensure that they behave as expected. There are many ways to test a user interface: manual testin...
104
+ - [🦉 How to start an Owl project 🦉](v2/learning/quick_start.md): Each software project has its specific needs. Many of these needs can be solved with some tooling: webpack, gulp, css preprocessor, bundlers, transpilers, ...
105
+ - [🦉 OWL Tutorial: TodoApp 🦉](v2/learning/tutorial_todoapp.md): For this tutorial, we will build a very simple Todo list application. The app should satisfy the following requirements:
106
+
107
+ ## v2/miscellaneous
108
+ - [🦉 Notes On Owl Architecture 🦉](v2/miscellaneous/architecture.md): We explain here how Owl is designed
109
+ - [Comparison with Vue/React](v2/miscellaneous/comparison.md): OWL, React and Vue have the same main feature: they allow developers to build declarative user interfaces. To do that, all these frameworks uses a virtual do...
110
+ - [🦉 Notes On Owl Compiled Templates 🦉](v2/miscellaneous/compiled_template.md): This page will explain what an Owl compiled template look like. This is a technical document intended for developers interested in understanding how Owl work...
111
+ - [🦉 Why Owl ? 🦉](v2/miscellaneous/why_owl.md): The common wisdom is that one should not reinvent the wheel, because that would waste effort and resources. It is certainly true in many cases. A javascript...
112
+
113
+ ## v2/reference
114
+ - [🦉 App 🦉](v2/reference/app.md): Every Owl application has a root element, a set of templates, an environment and possibly a few other settings. The App class is a simple class that represen...
115
+ - [🦉 Owl Component 🦉](v2/reference/component.md): An Owl component is a small class which represents some part of the user interface. It is part of a component tree, and has an environment (env), which is pr...
116
+ - [🦉 Concurrency Model 🦉](v2/reference/concurrency_model.md): Owl was designed from the very beginning with asynchronous components. This comes from the willStart and the willUpdateProps lifecycle hooks. With these asyn...
117
+ - [🦉 Environment 🦉](v2/reference/environment.md): An environment is a shared object given to all components in a tree. It is not used by Owl itself, but it is useful for application developers to provide a s...
118
+ - [🦉 Error Handling 🦉](v2/reference/error_handling.md): By default, whenever an error occurs in the rendering of an Owl application, we destroy the whole application. Otherwise, we cannot offer any guarantee on th...
119
+ - [🦉 Event Handling 🦉](v2/reference/event_handling.md): In a component's template, it is useful to be able to register handlers on DOM elements to some specific events. This is what makes a template alive. This is...
120
+ - [🦉 Hooks 🦉](v2/reference/hooks.md): Hooks were popularised by React as a way to solve the following issues:
121
+ - [🦉 Form Input Bindings 🦉](v2/reference/input_bindings.md): It is very common to need to be able to read the value out of an html input (or textarea, or select) in order to use it (note: it does not need to be in a fo...
122
+ - [🦉 Portal 🦉](v2/reference/portal.md): It is sometimes useful to be able to render some content outside the boundaries of a component. To do that, Owl provides a special directive: t-portal:
123
+ - [🦉 Precompiling templates 🦉](v2/reference/precompiling_templates.md): Owl is designed to be used by the Odoo javascript framework. Since Odoo handles its assets in its own non standard way, it was decided/assumed that Owl would...
124
+ - [🦉 Props 🦉](v2/reference/props.md): In Owl, props (short for properties) is an object which contains every piece of data given to a component by its parent.
125
+ - [🦉 Reactivity 🦉](v2/reference/reactivity.md): Reactivity is a big topic in javascript frameworks. The goal is to provide a simple way to manipulate state, in such a way that the interface updates automat...
126
+ - [🦉 References 🦉](v2/reference/refs.md): The useRef hook is useful when we need a way to interact with some inside part of a component, rendered by Owl. It can work either on a DOM node, or on a com...
127
+ - [🦉 Slots 🦉](v2/reference/slots.md): Owl is a template based component system. There is therefore a need to be able to make generic components. For example, imagine a generic Navbar component, w...
128
+ - [🦉 Templates 🦉](v2/reference/templates.md): Owl templates are describe using the QWeb specification. It is based on the XML format, and used mostly to generate HTML. In OWL, QWeb templates are compiled...
129
+ - [🦉 Translations 🦉](v2/reference/translations.md): If properly setup, Owl can translate all rendered templates. To do so, it needs a translate function, which takes
130
+ - [🦉 Utils 🦉](v2/reference/utils.md): Owl export a few useful utility functions, to help with common issues. Those functions are all available in the owl.utils namespace.
131
+
132
+ <!-- docs-index:end -->
@@ -4,7 +4,7 @@ See the [Usage Guide](usage-guide.md) for the end-to-end integration path (choos
4
4
 
5
5
  Nodex UI is distributed as one CSS file and one JavaScript file for browser use. `dist/nodexui.min.js` is fully self-contained: the JS bundle (Popper.js included) and the Nodex runtime are embedded ahead of Nodex UI's own code, in load order (JS bundle, then runtime, then Nodex UI) — nothing else needs to load first. Both install paths below load this same file; the Nodex UI component API is the recommended way to consume Nodex UI in an application, with the base static markup (`b-ui`) API available as a lighter-weight alternative for non-component pages.
6
6
 
7
- The snippets below use the `@latest` tag for readability. Pin an exact version instead (e.g. `@1.3.1`, or `@1` to take only non-breaking updates) for any production page — `@latest` can silently change what your page loads the moment a new version is published.
7
+ The snippets below use the `@latest` tag for readability. Pin an exact version instead (e.g. `@1.3.6`, or `@1` to take only non-breaking updates) for any production page — `@latest` can silently change what your page loads the moment a new version is published.
8
8
 
9
9
  ## Nodex UI component install (recommended)
10
10
 
@@ -41,7 +41,7 @@ For static HTML, a server-rendered page, or a Base HUB website page that has no
41
41
 
42
42
  base is the bundled baseline CSS framework, and its JS bundle now drives Nodex UI's interactive components directly.
43
43
 
44
- `nodexui` is published on npm, so [unpkg](https://unpkg.com/nodexui@latest/) mirrors the same files as an alternative CDN (`https://unpkg.com/nodexui@latest/dist/nodexui.min.css` / `nodexui.min.js`) if jsDelivr is unreachable in your environment. Pin an exact version (e.g. `@1.3.1`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
44
+ `nodexui` is published on npm, so [unpkg](https://unpkg.com/nodexui@latest/) mirrors the same files as an alternative CDN (`https://unpkg.com/nodexui@latest/dist/nodexui.min.css` / `nodexui.min.js`) if jsDelivr is unreachable in your environment. Pin an exact version (e.g. `@1.3.6`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
45
45
 
46
46
  For npm/self-hosted usage:
47
47
 
@@ -53,7 +53,7 @@ Everything — the static `b-ui` runtime, the Nodex runtime, every Nodex UI comp
53
53
  </script>
54
54
  ```
55
55
 
56
- `https://unpkg.com/nodexui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable — swap the host in each URL above. For a self-hosted build, replace the CDN host with your own served path (e.g. `/dist/nodexui.esm.js`). These snippets use `@latest` for readability; pin an exact version (e.g. `@1.3.1`, or `@1` to take only non-breaking updates) in production so a new release can't change what your page loads.
56
+ `https://unpkg.com/nodexui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable — swap the host in each URL above. For a self-hosted build, replace the CDN host with your own served path (e.g. `/dist/nodexui.esm.js`). These snippets use `@latest` for readability; pin an exact version (e.g. `@1.3.6`, or `@1` to take only non-breaking updates) in production so a new release can't change what your page loads.
57
57
 
58
58
  No `@odoo/owl` import appears anywhere in that snippet — `nodexui` is the only Nodex entry point Nodex UI components and consumer apps need. Because `nodexui`, `nodexui`, and `nodexui` all point at the exact same `dist/nodexui.esm.js` URL, the browser fetches and evaluates it once and every key shares the same module instance — no separate classic `<script>` needs to load first to set up a shared global.
59
59
 
package/docs/qr.md CHANGED
@@ -12,11 +12,11 @@ document.querySelector("#qr").innerHTML = qrSvg(payload, { ecc: "M", margin: 2,
12
12
  ```html
13
13
  <!-- ES module from the CDN (or map it as "nodexui/qr" in an import map) -->
14
14
  <script type="module">
15
- import { qrSvg } from "https://cdn.jsdelivr.net/npm/nodexui@1.3.1/dist/nodexui.qr.esm.js";
15
+ import { qrSvg } from "https://cdn.jsdelivr.net/npm/nodexui@1.3.6/dist/nodexui.qr.esm.js";
16
16
  </script>
17
17
 
18
18
  <!-- Classic script tag: sets window.thebase.qr -->
19
- <script src="https://cdn.jsdelivr.net/npm/nodexui@1.3.1/dist/nodexui.qr.min.js"></script>
19
+ <script src="https://cdn.jsdelivr.net/npm/nodexui@1.3.6/dist/nodexui.qr.min.js"></script>
20
20
  ```
21
21
 
22
22
  Types ship as `dist/types/qr.d.ts`.
@@ -26,11 +26,52 @@ Types ship as `dist/types/qr.d.ts`.
26
26
  | Export | What it does |
27
27
  | --- | --- |
28
28
  | `qrSvg(text, options?)` | Standalone SVG string. Options: `ecc` (`"L"`, `"M"`, `"Q"`, `"H"`; default `"M"`), `fg`, `bg`, `transparent`, `margin` (modules), `label` (adds `role="img"` and `aria-label`). Throws if the text does not fit a QR code. |
29
+ | `decodeQr(data, width, height)` | Reads one QR code from RGBA pixels (e.g. `ctx.getImageData(0, 0, w, h).data`). Returns the text or `null`. Pure JS, so it also works where `BarcodeDetector` is missing (desktop Chromium). |
30
+ | `decodeMpm(text)` / `encodeMpm(mpm)` | EMV **merchant-presented** codes (VietQR, PromptPay, ...): text records `ID(2) LEN(2) VALUE` ending in a CRC-16 (tag 63). `decodeMpm` returns named fields (`merchantName`, `transactionAmount`, `additionalDataField.purposeTransaction`, ...); accounts 02-25 stay raw strings, 26-51, `unreserved` (80-99) and `additionalDataField.paymentSystemSpecific` (50-99) are `{ globallyUniqueIdentifier, data: { "01": ... } }`. `encodeMpm` takes the same shape, defaults the payload format to `"01"` and computes the CRC. Throws `Checksum validation failed.` on a bad CRC and `Invalid EMV QR: ...` on a repeated tag, a truncated value, a tag outside its allowed range or a value over 99 characters. |
31
+ | `decodeCpm(input)` / `encodeCpm(cpm, { format })` | EMV **consumer-presented** codes: BER-TLV bytes carried as base64 (`decodeCpm` also takes a `Uint8Array`; `encodeCpm(cpm, { format: "bytes" })` returns one). Shape: `{ payloadFormatIndicator: "CPV01", applicationTemplates: [...], commonDataTemplate }`; an application template may nest `applicationSpecificTransparentTemplate` and the common one `commonDataTransparentTemplate`. Text fields (`applicationLabel`, `cardholderName`, `languagePreference`, `issuerUrl`, `paymentAccountReference`) are strings; `applicationPan` is digits (odd length padded with `F`); `tokenRequestorId`, `last4DigitsOfPan`, `applicationTransactionCounter` are digits (odd length padded with a leading `0`); the other fields are hex bytes. Unknown tags go in `other` as `{ hexTag: hexValue }`. |
32
+ | `decodeVietQr(text)` | Inverse of `buildVietQr`: returns `{ bank, account, holder, amount, purpose, dynamic, service }` (`service` is `"account"`, `"card"` or the raw code). Throws if the code is not VietQR (no Napas block `A000000727`). |
33
+ | `parseQr(text)` | Use on scanned text of unknown kind: returns `{ type: "vietqr", vietqr, mpm }`, `{ type: "mpm", mpm }`, `{ type: "cpm", cpm }` or `{ type: "text", text }`. Text starting `000201` must be a valid merchant code, so a bad CRC throws instead of passing as text. |
29
34
  | `qrMatrix(text, { ecc })` | `{ size, isDark(row, col) }` for custom renderers (canvas, PNG, ...). |
30
35
  | `buildVietQr({ bank, account, holder, amount, purpose, dynamic })` | VietQR payment string. `bank` is the bank BIN, `amount` is VND, `dynamic` marks a single-use code. Accents in `holder` and `purpose` are removed. |
31
36
  | `stripAccents(text)` | Removes Vietnamese accents. |
32
37
  | `qrcode`, `VIETQR`, `SERVICE_CODE`, `CURRENCY` | Low-level objects from `@thebeanfamily/vietqr`. `qrcode` is the `qrcode(typeNumber, ecc)` generator with UTF-8 already enabled. |
33
38
 
39
+ ### What you can do
40
+
41
+ | Goal | Call |
42
+ | --- | --- |
43
+ | Make a VietQR | `buildVietQr(...)` then `qrSvg(...)` |
44
+ | Make an EMV merchant (MPM) or consumer (CPM) QR | `encodeMpm(...)` / `encodeCpm(...)` then `qrSvg(...)` |
45
+ | Read a VietQR, EMV MPM or CPM from a camera frame | `parseQr(decodeQr(rgba, width, height))` |
46
+ | Read one when you already have the text | `decodeVietQr(text)`, `decodeMpm(text)` or `decodeCpm(text)` |
47
+
48
+ `buildVietQr` only writes the amount into dynamic codes (`dynamic: true`); a static code has no amount.
49
+
50
+ ### EMV codes in a Nodex UI component
51
+
52
+ `encodeMpm` / `decodeMpm` work with `QRCard`: build the payload in the component and pass it as `qrContent`.
53
+
54
+ ```js
55
+ import { Component, QRCard, xml } from "nodexui";
56
+ import { decodeMpm, encodeMpm } from "nodexui/qr";
57
+
58
+ class PayCard extends Component {
59
+ static components = { QRCard };
60
+ static template = xml`<QRCard qrContent="payload" title="'Scan to pay'" description="decoded.merchantName"/>`;
61
+
62
+ payload = encodeMpm({
63
+ pointOfInitiationMethod: "12",
64
+ merchantAccountInformation: { "26": { globallyUniqueIdentifier: "A000000727", data: { "01": "0011001932418" } } },
65
+ transactionCurrency: "704",
66
+ transactionAmount: "50000",
67
+ countryCode: "VN",
68
+ merchantName: "SHOP",
69
+ merchantCity: "HANOI",
70
+ });
71
+ decoded = decodeMpm(this.payload);
72
+ }
73
+ ```
74
+
34
75
  Text is encoded as UTF-8, so Vietnamese text scans correctly.
35
76
 
36
- See [`examples/qr/`](../examples/qr/) for a working page, plus the `emvhub` QR tool and `qr-page` app.
77
+ See the **QR** tab of the examples app ([`examples/components/qr/`](../examples/components/qr/)) for a working example, plus the `emvhub` QR tool and `qr-page` app.
package/docs/readme.md ADDED
@@ -0,0 +1,26 @@
1
+ # Nodex UI Documentation Index
2
+
3
+ > Index of the documents in this folder. Opened by default when a folder path or a missing document is requested.
4
+
5
+ <!-- docs-index:start (auto-generated; edit documents, not this block) -->
6
+
7
+ ## Documents
8
+ - [Analytics](analytics.md): Nodex UI ships a cookieless web-analytics service, ported from @plausible-analytics/tracker 0.4.6 (MIT; notice in LICENSE). Nothing is collected until the pa...
9
+ - [Skill for AI](base-ui-skill.md): Nodex UI skill teaches an AI coding agent how to build apps and components with NodexUI: scaffolding a PWA, emitting real components and icons, and packaging...
10
+ - [Blocks](blocks.md): Nodex UI blocks are static HTML compositions styled by the same shadcn-aligned tokens as the component library. They are based on the public shadcn/ui blocks...
11
+ - [Component Authoring](component-authoring.md): Nodex UI exposes two intentional public APIs from the same component source folder. Both must share styling, accessibility semantics, and — where practical —...
12
+ - [i18n service](i18n.md): Instructions for adding translations to a page or app with Nodex UI i18n service (nodexui/i18n). It is optional and standalone: no framework or component run...
13
+ - [Built-in Icons](icons.md): Nodex UI ships the full Lucide icon set as a built-in CDN-ready icon library. Icons use the b-icon attribute, render as CSS masks, and inherit currentColor f...
14
+ - [Installation](installation.md): See the Usage Guide for the end-to-end integration path (choosing an API, install, theming, verification). This page covers install mechanics only.
15
+ - [Nodex UI Component](owl-components.md): See the Usage Guide for when to reach for this API versus the static b-ui one. This page covers the pure Nodex UI API only.
16
+ - [QR](qr.md): Nodex UI ships a standalone QR service: a QR code generator and the VietQR (Napas/EMV) payment payload builder. It wraps @thebeanfamily/vietqr, which bundles...
17
+ - [Registry](registry.md): Every release publishes dist/nodexui.registry.json. The registry lists package metadata, CDN paths, build files, themes, and per-component metadata (type, de...
18
+ - [Runtime API](runtime-api.md): Nodex UI exposes one browser global: window.thebase. window.NodexUI still points to the same object as a deprecated alias for 1.x pages; it will be removed i...
19
+ - [Theming](theming.md): Set the theme on html or a subtree:
20
+ - [Usage Guide — Integrating Nodex UI Into a Project](usage-guide.md): This is the single entry point for adding Nodex UI to a consumer project (a static page, a Base HUB website page, a server-rendered app, or your own applicat...
21
+
22
+ ## Folders
23
+ - [components](components/readme.md)
24
+ - [v2](v2/readme.md)
25
+
26
+ <!-- docs-index:end -->
package/docs/theming.md CHANGED
@@ -22,7 +22,7 @@ thebase.theme.set({ primary: "#0057d8", radius: "0.5rem" });
22
22
  3. Load them after Nodex UI stylesheet:
23
23
 
24
24
  ```html
25
- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/nodexui@1.3.1/dist/nodexui.min.css">
25
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/nodexui@1.3.6/dist/nodexui.min.css">
26
26
  <link rel="stylesheet" href="/css/nodexui-light.css">
27
27
  <link rel="stylesheet" href="/css/nodexui-dark.css">
28
28
  ```
@@ -68,7 +68,7 @@ For a reusable theme toggle with persistence, URL override, button-label sync, a
68
68
  </script>
69
69
  ```
70
70
 
71
- `https://unpkg.com/nodexui@latest/dist/nodexui.esm.js` mirrors the same file as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.3.1`, or `@1` to take only non-breaking updates) instead of `@latest` for production. Npm/bundler consumers can import the same API from `nodexui`.
71
+ `https://unpkg.com/nodexui@latest/dist/nodexui.esm.js` mirrors the same file as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.3.6`, or `@1` to take only non-breaking updates) instead of `@latest` for production. Npm/bundler consumers can import the same API from `nodexui`.
72
72
 
73
73
  For a ready-made icon button, use Nodex UI component instead of wiring your own click handler:
74
74
 
@@ -32,7 +32,7 @@ Save this as an `.html` file and open it — no build step, no server required.
32
32
  </html>
33
33
  ```
34
34
 
35
- `https://cdn.jsdelivr.net/npm/nodexui@latest/dist/...` is the real jsDelivr URL for the published `nodexui` npm package's `latest` tag, used here for a copy-paste-and-go quick start. Pin an exact version instead (e.g. `@1.3.1`, or `@1` to take only non-breaking updates) for production, so a new release can't change what your page loads. See [Installation](installation.md) for jsDelivr/unpkg/npm/self-hosted paths.
35
+ `https://cdn.jsdelivr.net/npm/nodexui@latest/dist/...` is the real jsDelivr URL for the published `nodexui` npm package's `latest` tag, used here for a copy-paste-and-go quick start. Pin an exact version instead (e.g. `@1.3.6`, or `@1` to take only non-breaking updates) for production, so a new release can't change what your page loads. See [Installation](installation.md) for jsDelivr/unpkg/npm/self-hosted paths.
36
36
 
37
37
  The static bundle calls `thebase.mountAll()` automatically on `DOMContentLoaded`, so initial `[b-ui]` and `[b-icon]` markup mounts without an extra script. Call `thebase.mountAll(root)` yourself only after injecting new markup or when mounting a specific fragment. If the consumer is itself an application, use [step 2](#2-install-pure-owl-api--recommended) instead — that's the recommended path.
38
38
 
@@ -61,7 +61,7 @@ Both APIs come from the same package and the same CSS file, and can be mixed on
61
61
  </script>
62
62
  ```
63
63
 
64
- `https://unpkg.com/nodexui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable — swap the host in each URL above. Pin an exact version (e.g. `@1.3.1`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
64
+ `https://unpkg.com/nodexui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable — swap the host in each URL above. Pin an exact version (e.g. `@1.3.6`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
65
65
 
66
66
  ```html
67
67
  <script type="module">
@@ -101,7 +101,7 @@ Two rules that account for most integration failures — see [Nodex UI Component
101
101
  <script src="https://cdn.jsdelivr.net/npm/nodexui@latest/dist/nodexui.min.js" defer></script>
102
102
  ```
103
103
 
104
- `https://unpkg.com/nodexui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.3.1`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
104
+ `https://unpkg.com/nodexui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.3.6`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
105
105
 
106
106
  **Option B — npm (bundler-based apps: Vite, webpack, etc.):**
107
107
 
@@ -118,7 +118,7 @@ import "nodexui"; // side-effect import: registers window.thebase and auto-mount
118
118
 
119
119
  Rule that applies to both options:
120
120
 
121
- - Production pages must use a pinned version (e.g. `nodexui@1.3.1` or `nodexui@1`), never `@latest`.
121
+ - Production pages must use a pinned version (e.g. `nodexui@1.3.6` or `nodexui@1`), never `@latest`.
122
122
 
123
123
  Mount markup:
124
124
 
@@ -217,7 +217,7 @@ export default {
217
217
  },
218
218
  serviceWorker: {
219
219
  cacheName: "my-app-cache-v1",
220
- cdnVersion: "1.3.1", // pin to match the importmap in index.html
220
+ cdnVersion: "1.3.6", // pin to match the importmap in index.html
221
221
  appFiles: ["/app.css", "/app.js", "/app.xml", "/favicon.svg", "/icons/icon-192.png", "/icons/icon-512.png"],
222
222
  },
223
223
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nodex.ui/core",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "Nodex UI — an HTML-first, CDN-installable UI component library.",
5
5
  "type": "module",
6
6
  "main": "./dist/nodexui.min.js",
@@ -41,9 +41,6 @@
41
41
  "import": "./dist/nodexui.apidoc.esm.js",
42
42
  "default": "./dist/nodexui.apidoc.min.js"
43
43
  },
44
- "./block-viewer": {
45
- "import": "./dist/nodexui.block-viewer.esm.js"
46
- },
47
44
  "./pwa": {
48
45
  "types": "./dist/types/pwa.d.ts",
49
46
  "import": "./dist/nodexui.pwa.esm.js"
@@ -56,6 +53,7 @@
56
53
  },
57
54
  "files": [
58
55
  "bin/create-nodexui-app.mjs",
56
+ "bin/docs.mjs",
59
57
  "dist/nodexui.min.css",
60
58
  "dist/nodexui.esm.js",
61
59
  "dist/nodexui.min.js",
@@ -68,7 +66,6 @@
68
66
  "dist/nodexui.qr.min.js",
69
67
  "dist/nodexui.apidoc.esm.js",
70
68
  "dist/nodexui.apidoc.min.js",
71
- "dist/nodexui.block-viewer.esm.js",
72
69
  "dist/nodexui.pwa.esm.js",
73
70
  "dist/nodexui.vite.esm.js",
74
71
  "dist/nodexui.templates.xml",
@@ -88,11 +85,13 @@
88
85
  ],
89
86
  "scripts": {
90
87
  "dev": "node scripts/serve.mjs",
91
- "build": "node scripts/build.mjs",
92
- "lint": "eslint . && node scripts/check-css.mjs && node scripts/check-release-guards.mjs",
88
+ "build": "node scripts/sync-apidoc-viewer.mjs && node scripts/build.mjs",
89
+ "lint": "eslint . && node scripts/check-css.mjs && node scripts/check-release-guards.mjs && node scripts/sync-apidoc-viewer.mjs --check",
90
+ "typecheck": "tsc -p tsconfig.json",
93
91
  "test": "vitest run",
94
92
  "generate:icons": "node scripts/generate-icon-components.mjs",
95
- "generate:docs-tree": "node scripts/generate-docs-tree.mjs docs/v2",
93
+ "generate:docs-tree": "node scripts/doc-folder-tree.mjs docs",
94
+ "generate:docs-index": "node scripts/doc-folder-index.mjs docs --readmes --title \"Nodex UI Documentation Index\" --root-group Guides",
96
95
  "publish:nodexui": "node scripts/publish-alias.mjs nodexui",
97
96
  "prepublishOnly": "npm run lint && npm run test && npm run build"
98
97
  },
@@ -122,11 +121,14 @@
122
121
  "@milkdown/plugin-emoji": "^7.22.1",
123
122
  "@playwright/test": "^1.62.1",
124
123
  "@thebeanfamily/vietqr": "^0.0.2",
124
+ "@types/node": "^26.6.6",
125
125
  "esbuild": "^0.28.2",
126
126
  "eslint": "^10.8.1",
127
127
  "jsdom": "^30.0.1",
128
128
  "lucide-static": "^1.31.0",
129
129
  "mermaid": "^11.17.0",
130
+ "typescript": "^6.0.3",
131
+ "typescript-eslint": "^8.73.0",
130
132
  "vite": "^8.2.1",
131
133
  "vitest": "^4.1.10",
132
134
  "y-protocols": "^1.0.7",