@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.
- package/CHANGELOG.md +70 -1
- package/README.md +21 -13
- package/bin/create-nodexui-app.mjs +13 -4
- package/bin/docs.mjs +340 -0
- package/dist/nodexui.apidoc.esm.js +45 -29
- package/dist/nodexui.apidoc.min.js +45 -29
- package/dist/nodexui.esm.js +38 -27
- package/dist/nodexui.min.css +1 -1
- package/dist/nodexui.min.js +61 -50
- package/dist/nodexui.pwa.esm.js +9 -5
- package/dist/nodexui.qr.esm.js +3 -3
- package/dist/nodexui.qr.min.js +3 -3
- package/dist/nodexui.registry.json +30 -15
- package/dist/nodexui.templates.xml +22 -6
- package/dist/nodexui.vite.esm.js +12 -8
- package/dist/runtime/lazy/apidoc.logic.js +19 -19
- package/dist/types/index.d.ts +297 -0
- package/dist/types/qr.d.ts +63 -1
- package/docs/analytics.md +6 -8
- package/docs/base-ui-skill.md +1 -1
- package/docs/blocks.md +4 -4
- package/docs/components/chart.md +1 -1
- package/docs/components/data-table.md +49 -5
- package/docs/components/doc-viewer.md +68 -0
- package/docs/components/markdown.md +27 -2
- package/docs/components/readme.md +85 -0
- package/docs/i18n.md +1 -1
- package/docs/icons.md +1 -1
- package/docs/index.md +132 -0
- package/docs/installation.md +2 -2
- package/docs/owl-components.md +1 -1
- package/docs/qr.md +44 -3
- package/docs/readme.md +26 -0
- package/docs/theming.md +2 -2
- package/docs/usage-guide.md +5 -5
- package/package.json +10 -8
- package/dist/nodexui.block-viewer.esm.js +0 -46
- /package/dist/runtime/mermaid/{mermaid.esm.min.mjs → mermaid.esm.min.js} +0 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,7 +2,76 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to Nodex UI are documented in this file. Nodex UI follows [Semantic Versioning](https://semver.org/).
|
|
4
4
|
|
|
5
|
-
## [
|
|
5
|
+
## [Unreleased]
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
- `nodexui/qr`: `decodeVietQr` (inverse of `buildVietQr`) and `parseQr` (tells VietQR / EMV MPM / EMV CPM / plain text apart and parses it), so `parseQr(decodeQr(pixels, w, h))` reads any of them from a camera frame
|
|
9
|
+
- `nodexui/qr`: EMV QR codec for both modes, ported from `mvallim/emv-qrcode` (no dependency): `decodeMpm` / `encodeMpm` for merchant-presented codes (VietQR, ... text TLV + CRC-16) and `decodeCpm` / `encodeCpm` for consumer-presented codes (BER-TLV in base64). The Examples QR page has a "Read a QR (VietQR / EMV)" panel and `docs/qr.md` shows `encodeMpm` feeding `QRCard`
|
|
10
|
+
|
|
11
|
+
### Breaking
|
|
12
|
+
- `DataTable` no longer falls back to built-in demo data. Omitting `columns`/`rows` (or passing an empty `rows`) now renders no columns and the `emptyLabel` row instead of the shadcn payments demo (`ken99@example.com`, ...), `selectable` defaults to `false`, and `rowActions` defaults to none. The `filterPlaceholder` default is now `Filter rows...` (it was `Filter emails...`, which the docs already described as `Filter rows...`). Pass your own `columns`, `rows` and, if wanted, `selectable`/`rowActions`. The static `b-ui="data-table"` markup is unchanged
|
|
13
|
+
|
|
14
|
+
### Fixed
|
|
15
|
+
- Service worker built by `buildServiceWorker`: a new `version.json` value is now remembered only after the re-cache succeeds, so a failed re-cache (offline mid-update) is retried on the next check instead of leaving the caches wiped
|
|
16
|
+
- Static dialogs/sheets (`createModal`): calling `open()` on an already open modal no longer overwrites the element focus returns to on close
|
|
17
|
+
- `ApiDoc` Try It: when several code-sample requests overlapped (typing in a field, switching language), a slower older one could overwrite the newest sample
|
|
18
|
+
- `Markdown` mermaid: a diagram finishing after the content was re-rendered no longer writes into a detached block
|
|
19
|
+
|
|
20
|
+
### Changed
|
|
21
|
+
- `DataTable` computes the filtered and sorted rows once per render (it re-sorted about 12 times per render) and sorts with one shared `Intl.Collator`
|
|
22
|
+
- `ApiDoc` looks operations up by id in a `Map`
|
|
23
|
+
- `decodeQr`: frames above about 2.1M pixels are box-averaged down before decoding, and the locator allocates less (typed arrays reused between frames, no per-row slices, bounded finder candidate list)
|
|
24
|
+
- Internal: the legacy docs-fence converters moved to `markdown.preview-converters.js` (the three public names are still exported from `markdown.behavior.js`); prop alias reads use `propValue`; `Sidebar` shares one mobile media query; two duplicate `qr copy.js` / `qr-matrix copy.js` files removed
|
|
25
|
+
|
|
26
|
+
## [v1.3.6]
|
|
27
|
+
|
|
28
|
+
### Added
|
|
29
|
+
- TypeScript in the library source: `.ts` files can sit beside `.js` in `src/` and `test/`. The build, Vitest and ESLint handle them (`typescript-eslint`), `<name>.component.ts` opts a component into `dist/nodexui.templates.xml`, and the new `tsconfig.json` with `npm run typecheck` runs `tsc`. No existing file was converted and the published API is unchanged
|
|
30
|
+
- `dist/types/index.d.ts` now types the Owl facade (`Component`, `mount`, `xml`, `useState`, `useRef`, lifecycle hooks, `App`, ...) and every component class (`Button`, `Card`, ...), so `class Root extends Component` and `mount(Root, el)` type-check in TypeScript consumers. Generated by `scripts/build.mjs`; the component list follows `src/components/index.js`
|
|
31
|
+
- `tsconfig.json` now has `checkJs` on, so `npm run typecheck` type-checks every hand-written `.js` file in `src/` (vendored `*.min.js` and generated files are skipped via `.d.ts` stubs/excludes). `src/types/owl.d.ts` types the vendored Owl; the few spots tsc flagged got JSDoc casts. Two legacy files opt out with `@ts-nocheck`: the classic-script `apidoc/js/app.js` and the `shims/events.js` polyfill
|
|
32
|
+
|
|
33
|
+
### Changed
|
|
34
|
+
- Docs, README, `emvhub`, `qr-page`, `momo_demo` and `examples` pin `nodexui@1.3.6`; the `emvhub`, `qr-page` and `momo_demo` service-worker caches are bumped
|
|
35
|
+
|
|
36
|
+
## [v1.3.5]
|
|
37
|
+
|
|
38
|
+
### Added
|
|
39
|
+
- `Markdown` MDX-style authoring: pure Nodex UI tags written directly in the prose (`<Badge>New</Badge>`, block or inline), `import` lines (component classes become tags, other exports become handlers/values) and `export const name = <JSON>` (seeds a `state` shared by every tag in the document). A ` ```base-ui-render ` fence shows only the live component, without the source pane. Always on; `nodexUi="false"` turns it off for untrusted Markdown
|
|
40
|
+
|
|
41
|
+
## [v1.3.4]
|
|
42
|
+
|
|
43
|
+
### Added
|
|
44
|
+
- `DocViewer` component: a Markdown folder viewer (`MarkdownTree` sidebar + `Markdown` content) driven by a `tree.json` manifest; props `tree`, `root`, `base`, `path`, `hashPrefix`, `part`, `include`, `exclude`, `filter`, `formatLabel`, `toHash`/`fromHash`, `onNavigate`. Page: `docs/components/doc-viewer.md`
|
|
45
|
+
- `MarkdownTree` props `include` (ordered paths), `exclude`, `filter` and `formatLabel(node)`
|
|
46
|
+
- `create-nodexui-app docs [folder]` writes the root `index.md`, a `readme.md` per folder and `tree.json`; `--restructure [--write]` renames to kebab-case, fixes links and adds missing `title`/`sidebar_position`; `--check` exits 1 when the files are stale
|
|
47
|
+
|
|
48
|
+
### Changed
|
|
49
|
+
- Docs: folders have `readme.md` indexes and a single `docs/tree.json` replaces `docs/v2/tree.json`; the old devtools pages and screenshots under `docs/v2/tools/` are removed
|
|
50
|
+
- Examples app: the Docs and Concept tabs use `DocViewer`; the `owl-framework` tab is renamed `concept`
|
|
51
|
+
|
|
52
|
+
## [v1.3.3]
|
|
53
|
+
|
|
54
|
+
### Changed
|
|
55
|
+
- Internal simplification of `src/`: tabs, dropdown-menu, Markdown and text-editor mounting code split into small module-level functions (no behaviour or API change); the two editors share `src/runtime/base/editor-attrs.js`
|
|
56
|
+
- Standalone ApiDoc viewer scripts (`src/components/apidoc/js/openapi.js`, `snippet.js`) are now generated from `apidoc.openapi.js` and `apidoc.snippet.js` (`scripts/sync-apidoc-viewer.mjs`, run by `npm run build` and checked by `npm run lint`), so the viewer gets the same schema merging and security-scheme handling as the component
|
|
57
|
+
- Removed 27 unused selectors from `apidoc.css`
|
|
58
|
+
- Block stylesheets moved from `examples/components/block-gallery/blocks/` to `src/blocks/` (still bundled into `dist/nodexui.min.css`); block templates live in `examples/components/blocks/`
|
|
59
|
+
- Examples app mirrors the `nodex-ui.github.io` site root; the library source (local `dist/` or the CDN) is chosen in one file, `examples/nodexui.config.js`; new `make sync-site` copies `examples/` and `docs/` to the site checkout
|
|
60
|
+
- Docs, README, `emvhub`, `qr-page`, `momo_demo` and `examples` pin `nodexui@1.3.3`
|
|
61
|
+
|
|
62
|
+
## [v1.3.2]
|
|
63
|
+
|
|
64
|
+
### Changed
|
|
65
|
+
- Generated service workers (`nodexui/pwa`) fetch with `cache: "no-cache"`, so a deploy is picked up without a stale HTTP-cache hit
|
|
66
|
+
- Examples app: blocks, analytics, apidoc, i18n, QR and charts are now components under `examples/components/` (the block gallery samples are `.xml` templates in `examples/components/block-gallery/blocks/`); `create-nodexui-app` starter comments point at the new paths
|
|
67
|
+
- Vendored Mermaid bundle renamed `src/runtime/mermaid/mermaid.esm.min.mjs` to `mermaid.esm.min.js`
|
|
68
|
+
- Examples PWA branding: new logo set (favicon, PWA, Android, iOS and Windows icons), updated manifest and service worker
|
|
69
|
+
- Docs, README, `emvhub`, `qr-page` and `examples` pin `nodexui@1.3.2`
|
|
70
|
+
|
|
71
|
+
### Fixed
|
|
72
|
+
- Analytics component CSS classes are prefixed `b-analytics-` to pass the release guard
|
|
73
|
+
|
|
74
|
+
## [v1.3.1]
|
|
6
75
|
|
|
7
76
|
### Added
|
|
8
77
|
- `QRCard` component: a centred card with a scannable QR code, title and description. Pass `qrContent` (the string to encode) or a ready-made `matrix` from `qrMatrix()`
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
**Nodex UI** is an HTML-first, framework-independent UI component library for the web. It ships its own styling and behavior, loads straight from a CDN or npm, and needs no build step. Use it as **Nodex components** (`<Button/>`-style imports in your own application) or as the static `b-ui` markup adapter for plain HTML, server-rendered pages and CMS pages.
|
|
4
4
|
|
|
5
|
-
- npm package: [`nodexui`](https://www.npmjs.com/package/nodexui) · current version **1.3.
|
|
5
|
+
- npm package: [`nodexui`](https://www.npmjs.com/package/nodexui) or [`@thebase/ui`](https://www.npmjs.com/package/@thebase/ui) · current version **1.3.6**
|
|
6
6
|
- Website, live demos and docs: <https://ui.thebase.vn>
|
|
7
7
|
- Release history: [CHANGELOG.md](CHANGELOG.md)
|
|
8
8
|
|
|
@@ -21,6 +21,10 @@
|
|
|
21
21
|
```sh
|
|
22
22
|
npm install nodexui
|
|
23
23
|
```
|
|
24
|
+
or
|
|
25
|
+
```sh
|
|
26
|
+
npm install @thebase/ui
|
|
27
|
+
```
|
|
24
28
|
|
|
25
29
|
```js
|
|
26
30
|
import { Component, mount, xml } from "nodexui";
|
|
@@ -32,7 +36,7 @@ Subpath exports: `nodexui/analytics`, `nodexui/i18n`, `nodexui/qr`, `nodexui/api
|
|
|
32
36
|
|
|
33
37
|
### CDN (Nodex components)
|
|
34
38
|
|
|
35
|
-
Both APIs load from jsDelivr or unpkg. The snippets use `@latest` for readability; pin an exact version (`@1.3.
|
|
39
|
+
Both APIs load from jsDelivr or unpkg. The snippets use `@latest` for readability; pin an exact version (`@1.3.6`, or `@1` for non-breaking updates) on any production page.
|
|
36
40
|
|
|
37
41
|
```html
|
|
38
42
|
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/nodexui@latest/dist/nodexui.min.css">
|
|
@@ -88,22 +92,22 @@ Colour tokens, `--base-radius` and `--b-overlay` live in the downloadable `nodex
|
|
|
88
92
|
|
|
89
93
|
| Service | Import | What it is |
|
|
90
94
|
| --- | --- | --- |
|
|
91
|
-
| **Analytics** | `nodexui/analytics`, `dist/nodexui.analytics.min.js` | Cookieless, standalone (about 5.6 KB min). Nothing is collected until `init()` is called. Covers pageviews (including SPA), engagement, outbound links, downloads and forms. See [Analytics](docs/analytics.md) and [`examples/analytics/`](examples/analytics/). |
|
|
92
|
-
| **i18n** | `nodexui/i18n`, `dist/nodexui.i18n.min.js` | Gettext-style `.po` catalogs, no runtime dependencies. See [i18n](docs/i18n.md) and [`examples/i18n/`](examples/i18n/). |
|
|
93
|
-
| **QR / VietQR** | `nodexui/qr`, `dist/nodexui.qr.min.js` | QR code SVG/matrix generator plus the VietQR payment payload builder, standalone. See [QR](docs/qr.md) and [`examples/qr/`](examples/qr/). |
|
|
94
|
-
| **ApiDoc** | `nodexui/apidoc` | Renders an OpenAPI 3 JSON file as browsable docs with a Try It panel and 17 code-sample languages. See [ApiDoc](docs/components/apidoc.md) and [`examples/apidoc/`](examples/apidoc/). |
|
|
95
|
+
| **Analytics** | `nodexui/analytics`, `dist/nodexui.analytics.min.js` | Cookieless, standalone (about 5.6 KB min). Nothing is collected until `init()` is called. Covers pageviews (including SPA), engagement, outbound links, downloads and forms. See [Analytics](docs/analytics.md) and [`examples/components/analytics/`](examples/components/analytics/). |
|
|
96
|
+
| **i18n** | `nodexui/i18n`, `dist/nodexui.i18n.min.js` | Gettext-style `.po` catalogs, no runtime dependencies. See [i18n](docs/i18n.md) and [`examples/components/i18n/`](examples/components/i18n/). |
|
|
97
|
+
| **QR / VietQR** | `nodexui/qr`, `dist/nodexui.qr.min.js` | QR code SVG/matrix generator plus the VietQR payment payload builder, standalone. See [QR](docs/qr.md) and the **QR** tab ([`examples/components/qr/`](examples/components/qr/)). |
|
|
98
|
+
| **ApiDoc** | `nodexui/apidoc` | Renders an OpenAPI 3 JSON file as browsable docs with a Try It panel and 17 code-sample languages. See [ApiDoc](docs/components/apidoc.md) and the **API docs** tab ([`examples/components/apidoc/`](examples/components/apidoc/)). |
|
|
95
99
|
| **PWA toolkit** | `nodexui/pwa`, `nodexui/vite` | `buildManifest`, `buildServiceWorker` and the `nodexuiPwa()` Vite plugin. |
|
|
96
100
|
|
|
97
101
|
```html
|
|
98
102
|
<script type="module">
|
|
99
|
-
import { init, track } from "https://cdn.jsdelivr.net/npm/nodexui@1.3.
|
|
103
|
+
import { init, track } from "https://cdn.jsdelivr.net/npm/nodexui@1.3.6/dist/nodexui.analytics.esm.js";
|
|
100
104
|
init({ backendUrl: "https://stats.example.com" }); // events POST to <backendUrl>/api/event
|
|
101
105
|
track("Signup", { props: { plan: "pro" } });
|
|
102
106
|
</script>
|
|
103
107
|
```
|
|
104
108
|
|
|
105
109
|
```js
|
|
106
|
-
import { init, t, loadCatalog } from "https://cdn.jsdelivr.net/npm/nodexui@1.3.
|
|
110
|
+
import { init, t, loadCatalog } from "https://cdn.jsdelivr.net/npm/nodexui@1.3.6/dist/nodexui.i18n.esm.js";
|
|
107
111
|
init({ languages: [{ code: "en", label: "English" }, { code: "vi", label: "Tiếng Việt" }] });
|
|
108
112
|
await loadCatalog(import.meta.url); // fetches ./i18n/vi.po when Vietnamese is picked
|
|
109
113
|
console.log(t("Hello {name}", { name: "An" }));
|
|
@@ -135,7 +139,7 @@ Nodex UI follows [Semantic Versioning](https://semver.org/) from **1.3.0**. The
|
|
|
135
139
|
|
|
136
140
|
**Major** releases remove or rename any of the above (listed under **Breaking** in the CHANGELOG with a migration note), **minor** releases add components, props, variants, tokens or icons, and **patch** releases fix bugs without changing the API. Names prefixed `_`, undocumented internals, `docs/` and `examples/` sources, and the authoring helpers in [Component Authoring](docs/component-authoring.md) are not public API. Deprecated APIs keep working until the next major and are flagged in the CHANGELOG first.
|
|
137
141
|
|
|
138
|
-
Pin an exact version (`@1.3.
|
|
142
|
+
Pin an exact version (`@1.3.6`) for byte-identical output, or the major range (`@1` on jsDelivr/unpkg, `^1.3.6` in npm) to receive non-breaking updates. Avoid `@latest` in production.
|
|
139
143
|
|
|
140
144
|
## Documentation
|
|
141
145
|
|
|
@@ -148,7 +152,7 @@ Pin an exact version (`@1.3.1`) for byte-identical output, or the major range (`
|
|
|
148
152
|
- [Component reference](docs/components/button.md): usage, attributes, events and accessibility per component.
|
|
149
153
|
- [Component Authoring](docs/component-authoring.md): the `src/components/<name>/` contract (repo only, not published).
|
|
150
154
|
|
|
151
|
-
`docs/*.md` and `docs/components/` also ship in the npm package, so the raw Markdown is reachable from a CDN, for example `https://cdn.jsdelivr.net/npm/nodexui@1.3.
|
|
155
|
+
`docs/*.md` and `docs/components/` also ship in the npm package, so the raw Markdown is reachable from a CDN, for example `https://cdn.jsdelivr.net/npm/nodexui@1.3.6/docs/usage-guide.md`. `docs/v2/` and `docs/component-authoring.md` are not published.
|
|
152
156
|
|
|
153
157
|
## Development
|
|
154
158
|
|
|
@@ -158,15 +162,19 @@ npm run build
|
|
|
158
162
|
npm run dev
|
|
159
163
|
```
|
|
160
164
|
|
|
161
|
-
Open `examples/index.html` through the dev server. It is the single shell for docs, the component gallery, blocks, icons and charts, routed by hash (`#/docs`, `#/components`, `#/blocks`, `#/icons`, `#/chart`). Standalone demos: `examples/apidoc/`, `examples/analytics/` and `momo_demo/` (static `b-ui` admin page).
|
|
165
|
+
Open `examples/index.html` through the dev server. It is the single shell for docs, the component gallery, blocks, icons and charts, routed by hash (`#/docs`, `#/components`, `#/blocks`, `#/icons`, `#/chart`). Standalone demos: `examples/apidoc/`, `examples/components/analytics/` and `momo_demo/` (static `b-ui` admin page).
|
|
166
|
+
|
|
167
|
+
Library sources in `src/` may be written in TypeScript (`.ts` beside `.js`); the build, Vitest and ESLint handle both. See [Component Authoring](docs/component-authoring.md#typescript).
|
|
162
168
|
|
|
163
169
|
Lucide's full SVG set is built in: `<span b-icon="search"></span>` in HTML or `thebase.icons.lucide.url("search")` from JavaScript. Builds publish the SVGs to `dist/icons/lucide/` and an index at `dist/icons/lucide.json`.
|
|
164
170
|
|
|
165
171
|
| Script | Purpose |
|
|
166
172
|
| --- | --- |
|
|
167
173
|
| `npm run dev` | Static server for examples and built `dist/` assets |
|
|
168
|
-
| `npm run build` | Build CDN and npm artifacts into `dist/` |
|
|
169
|
-
| `
|
|
174
|
+
| `npm run build` | Build CDN and npm artifacts into `dist/` (first regenerates the standalone ApiDoc viewer scripts) |
|
|
175
|
+
| `make sync-site` | Copy `examples/` and `docs/` to the `nodex-ui.github.io` checkout |
|
|
176
|
+
| `npm run lint` | JavaScript, TypeScript and CSS policy checks, plus a check that the standalone ApiDoc viewer scripts match their module sources |
|
|
177
|
+
| `npm run typecheck` | `tsc` type check of the TypeScript sources (`src/**/*.ts`, `test/**/*.ts`) |
|
|
170
178
|
| `npm run test` | Runtime tests |
|
|
171
179
|
| `npm publish` | Runs `prepublishOnly` (lint, test, build) first |
|
|
172
180
|
|
|
@@ -181,7 +181,7 @@ await mountPage(${componentName}, pageTemplates);
|
|
|
181
181
|
|
|
182
182
|
/** Builds a 4-page Vite + Nodex UI starter (landing, login, signup, an authenticated home shell) for a
|
|
183
183
|
* project named `appName` — each page is its own Owl root mounted by its own HTML entry, composed
|
|
184
|
-
* from the same blocks as `examples/blocks/login-03.
|
|
184
|
+
* from the same blocks as `examples/components/block-gallery/blocks/login-03.xml`, `signup-03.xml` and `sidebar-02.xml`. */
|
|
185
185
|
function buildStarterFiles(appName, nodexuiVersion) {
|
|
186
186
|
const title = toTitle(appName);
|
|
187
187
|
|
|
@@ -332,7 +332,7 @@ export class Landing extends Component {
|
|
|
332
332
|
"src/login/Login.js": `import { Component } from "nodexui";
|
|
333
333
|
import { Button, Card, CardBody, Field, FieldGroup, Icon, Input, Label } from "nodexui";
|
|
334
334
|
|
|
335
|
-
/** Login page (ported from examples/blocks/login-03.
|
|
335
|
+
/** Login page (ported from examples/components/block-gallery/blocks/login-03.xml): email/password card, redirects home on submit. */
|
|
336
336
|
export class Login extends Component {
|
|
337
337
|
static template = "app.Login";
|
|
338
338
|
static components = { Button, Card, CardBody, Field, FieldGroup, Icon, Input, Label };
|
|
@@ -383,7 +383,7 @@ export class Login extends Component {
|
|
|
383
383
|
"src/signup/Signup.js": `import { Component } from "nodexui";
|
|
384
384
|
import { Button, Card, CardBody, Field, FieldGroup, Icon, Input, Label } from "nodexui";
|
|
385
385
|
|
|
386
|
-
/** Signup page (ported from examples/blocks/signup-03.
|
|
386
|
+
/** Signup page (ported from examples/components/block-gallery/blocks/signup-03.xml): single email field, sends the user to login after submit. */
|
|
387
387
|
export class Signup extends Component {
|
|
388
388
|
static template = "app.Signup";
|
|
389
389
|
static components = { Button, Card, CardBody, Field, FieldGroup, Icon, Input, Label };
|
|
@@ -432,7 +432,7 @@ import {
|
|
|
432
432
|
SidebarGroupCollapsible, SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarTrigger,
|
|
433
433
|
} from "nodexui";
|
|
434
434
|
|
|
435
|
-
/** Authenticated home shell (ported from examples/blocks/sidebar-02.
|
|
435
|
+
/** Authenticated home shell (ported from examples/components/block-gallery/blocks/sidebar-02.xml): collapsible sidebar nav
|
|
436
436
|
* + sticky header, reached after login/signup; owns the sidebar's collapsed/expanded state. */
|
|
437
437
|
export class Home extends Component {
|
|
438
438
|
static template = "app.Home";
|
|
@@ -739,6 +739,14 @@ Usage:
|
|
|
739
739
|
Generate manifest.webmanifest + sw.js in [path] (default ".") from a
|
|
740
740
|
nodexui.pwa.config.js config file (default name, override with --config).
|
|
741
741
|
Also copies the default logo/favicon set into [path]/icons/ (existing files kept).
|
|
742
|
+
|
|
743
|
+
create-nodexui-app docs [folder] [--restructure [--write]] [--check]
|
|
744
|
+
[--title <t>] [--description <d>] [--root-group <g>] [--out <file>]
|
|
745
|
+
Prepare a Markdown folder (default ./docs) for the DocViewer component: writes the
|
|
746
|
+
root index.md, a readme.md in every folder, and tree.json (--out to move it).
|
|
747
|
+
--restructure first plans kebab-case renames (links fixed), adds missing
|
|
748
|
+
title/sidebar_position frontmatter and lowercases README.md; it only prints the
|
|
749
|
+
plan until --write is added. --check exits 1 when the index files are stale.
|
|
742
750
|
`);
|
|
743
751
|
}
|
|
744
752
|
|
|
@@ -748,4 +756,5 @@ if (command === "create") cmdCreate(rest);
|
|
|
748
756
|
else if (command === "convert") cmdConvert(rest);
|
|
749
757
|
else if (command === "init") cmdInit(rest);
|
|
750
758
|
else if (command === "pwa") await cmdPwa(rest);
|
|
759
|
+
else if (command === "docs") (await import("./docs.mjs")).cmdDocs(rest);
|
|
751
760
|
else printHelp();
|
package/bin/docs.mjs
ADDED
|
@@ -0,0 +1,340 @@
|
|
|
1
|
+
import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmdirSync, statSync, writeFileSync } from "node:fs";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
|
|
4
|
+
const START = "<!-- docs-index:start (auto-generated; edit documents, not this block) -->";
|
|
5
|
+
const END = "<!-- docs-index:end -->";
|
|
6
|
+
const DEFAULT_DESCRIPTION = "Document index for AI agents. Fetch only the pages you need. Links are relative to this file.";
|
|
7
|
+
|
|
8
|
+
// Makes a path use forward slashes on every platform.
|
|
9
|
+
function posix(file) {
|
|
10
|
+
return file.split(path.sep).join("/");
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
// True for Markdown files (any letter case of the extension).
|
|
14
|
+
function isMarkdown(name) {
|
|
15
|
+
return name.toLowerCase().endsWith(".md");
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
// True for the folder's default document, `readme.md` in any letter case.
|
|
19
|
+
function isReadme(name) {
|
|
20
|
+
return name.toLowerCase() === "readme.md";
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
// Lists a folder's visible entries (no dotfiles, no tree.json), sorted by name.
|
|
24
|
+
function entriesOf(dir) {
|
|
25
|
+
return readdirSync(dir, { withFileTypes: true })
|
|
26
|
+
.filter((entry) => !entry.name.startsWith(".") && entry.name !== "tree.json")
|
|
27
|
+
.sort((a, b) => a.name.localeCompare(b.name));
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
// Reads the flat `key: value` frontmatter block of a document; numbers and booleans are converted, the rest of the text is `body`.
|
|
31
|
+
function parseFrontmatter(source) {
|
|
32
|
+
const match = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?/.exec(source);
|
|
33
|
+
const data = {};
|
|
34
|
+
for (const line of match ? match[1].split(/\r?\n/) : []) {
|
|
35
|
+
const colon = line.indexOf(":");
|
|
36
|
+
if (colon < 1 || line.trim().startsWith("#")) continue;
|
|
37
|
+
const value = line.slice(colon + 1).trim().replace(/^(["'])(.*)\1$/, "$2");
|
|
38
|
+
data[line.slice(0, colon).trim()] = value === "true" ? true : value === "false" ? false : /^-?\d+(\.\d+)?$/.test(value) ? Number(value) : value;
|
|
39
|
+
}
|
|
40
|
+
return { data, body: match ? source.slice(match[0].length) : source };
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
// Picks the first plain paragraph after the title, stripped of Markdown and cut at 160 characters, as the page summary.
|
|
44
|
+
function firstParagraph(body) {
|
|
45
|
+
let fence = false;
|
|
46
|
+
const lines = [];
|
|
47
|
+
for (const raw of body.replace(/^#\s+.+$/m, "").split("\n")) {
|
|
48
|
+
const line = raw.trim();
|
|
49
|
+
if (line.startsWith("```")) { fence = !fence; continue; }
|
|
50
|
+
if (fence) continue;
|
|
51
|
+
if (!line || /^(#|\||>|-|\*|\d+\.|<|!\[)/.test(line)) { if (lines.length) break; continue; }
|
|
52
|
+
lines.push(line);
|
|
53
|
+
}
|
|
54
|
+
const text = lines.join(" ").replace(/\[([^\]]+)\]\([^)]*\)/g, "$1").replace(/[`*_]/g, "");
|
|
55
|
+
return text.length > 160 ? `${text.slice(0, 157).trimEnd()}...` : text;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
// Reads a document's title (frontmatter, else first heading, else file name), summary and frontmatter.
|
|
59
|
+
function describeDocument(file) {
|
|
60
|
+
const { data, body } = parseFrontmatter(readFileSync(file, "utf8"));
|
|
61
|
+
return {
|
|
62
|
+
meta: data,
|
|
63
|
+
title: String(data.title ?? /^#\s+(.+)$/m.exec(body)?.[1].trim() ?? path.basename(file, path.extname(file))),
|
|
64
|
+
description: String(data.description ?? firstParagraph(body)),
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
// Orders documents by frontmatter `sidebar_position` (unnumbered last), then by file name.
|
|
69
|
+
function compareDocuments(a, b) {
|
|
70
|
+
const hasA = typeof a.meta?.sidebar_position === "number";
|
|
71
|
+
const hasB = typeof b.meta?.sidebar_position === "number";
|
|
72
|
+
if (hasA && hasB && a.meta.sidebar_position !== b.meta.sidebar_position) return a.meta.sidebar_position - b.meta.sidebar_position;
|
|
73
|
+
if (hasA !== hasB) return hasA ? -1 : 1;
|
|
74
|
+
return a.name.localeCompare(b.name);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
// Builds the `{ name, type, path, children, meta }` tree DocViewer reads; paths are relative to `cwd` (where the site serves them from).
|
|
78
|
+
function buildTree(dir, cwd) {
|
|
79
|
+
const entries = entriesOf(dir);
|
|
80
|
+
const children = entries.filter((entry) => entry.isDirectory()).map((entry) => buildTree(path.join(dir, entry.name), cwd));
|
|
81
|
+
const files = entries
|
|
82
|
+
.filter((entry) => entry.isFile() && isMarkdown(entry.name))
|
|
83
|
+
.map((entry) => {
|
|
84
|
+
const file = path.join(dir, entry.name);
|
|
85
|
+
const { meta, title, description } = describeDocument(file);
|
|
86
|
+
return { name: entry.name, type: "file", path: posix(path.relative(cwd, file)), title, description, meta };
|
|
87
|
+
});
|
|
88
|
+
return { name: path.basename(dir), type: "dir", path: posix(path.relative(cwd, dir)), children: [...children, ...files.sort(compareDocuments)] };
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
// True when the folder, or any folder below it, holds a Markdown document.
|
|
92
|
+
function hasDocuments(dir) {
|
|
93
|
+
return entriesOf(dir).some((entry) => (entry.isFile() ? isMarkdown(entry.name) : hasDocuments(path.join(dir, entry.name))));
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
// Lists `{ dir, files }` groups (root first, then folders) of the documents the root index links to.
|
|
97
|
+
function collectGroups(root, dir, rel = "") {
|
|
98
|
+
const entries = entriesOf(dir);
|
|
99
|
+
const files = entries
|
|
100
|
+
.filter((entry) => entry.isFile() && isMarkdown(entry.name) && !isReadme(entry.name) && !(rel === "" && entry.name === "index.md"))
|
|
101
|
+
.map((entry) => entry.name);
|
|
102
|
+
const groups = files.length ? [{ dir: rel, files }] : [];
|
|
103
|
+
for (const entry of entries.filter((item) => item.isDirectory())) {
|
|
104
|
+
groups.push(...collectGroups(root, path.join(dir, entry.name), rel ? `${rel}/${entry.name}` : entry.name));
|
|
105
|
+
}
|
|
106
|
+
return groups;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
// Renders `- [Title](link): summary` for one document.
|
|
110
|
+
function indexLine(file, link) {
|
|
111
|
+
const { title, description } = describeDocument(file);
|
|
112
|
+
return `- [${title}](${link})${description ? `: ${description}` : ""}`;
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
// Builds the machine-owned block of the root `index.md`: one section per folder.
|
|
116
|
+
function rootIndexBlock(root, rootGroup) {
|
|
117
|
+
const out = [];
|
|
118
|
+
for (const group of collectGroups(root, root)) {
|
|
119
|
+
out.push(`## ${group.dir === "" ? rootGroup : group.dir}`);
|
|
120
|
+
for (const name of group.files) {
|
|
121
|
+
const link = group.dir ? `${group.dir}/${name}` : name;
|
|
122
|
+
out.push(indexLine(path.join(root, link), link));
|
|
123
|
+
}
|
|
124
|
+
out.push("");
|
|
125
|
+
}
|
|
126
|
+
return `${START}\n\n${out.join("\n").trimEnd()}\n\n${END}`;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
// Builds the machine-owned block of one folder's readme: its documents, then its sub-folders.
|
|
130
|
+
function readmeBlock(root, dir, folders) {
|
|
131
|
+
const docs = entriesOf(dir).filter((entry) => entry.isFile() && isMarkdown(entry.name) && !isReadme(entry.name) && !(dir === root && entry.name === "index.md"));
|
|
132
|
+
const out = docs.length ? ["## Documents", ...docs.map((entry) => indexLine(path.join(dir, entry.name), entry.name))] : [];
|
|
133
|
+
if (docs.length && folders.length) out.push("");
|
|
134
|
+
if (folders.length) out.push("## Folders", ...folders.map((name) => `- [${name}](${name}/readme.md)`));
|
|
135
|
+
return `${START}\n\n${out.join("\n")}\n\n${END}`;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
// Swaps `generated` into the marker block of `file` (appending the block or creating the file from `head` when needed); reports whether it changed, or only warns in `check` mode.
|
|
139
|
+
function upsert(file, generated, head, { check, cwd }) {
|
|
140
|
+
const current = existsSync(file) ? readFileSync(file, "utf8") : null;
|
|
141
|
+
let next = `${head}${generated}\n`;
|
|
142
|
+
if (current?.includes(START) && current.includes(END)) next = current.slice(0, current.indexOf(START)) + generated + current.slice(current.indexOf(END) + END.length);
|
|
143
|
+
else if (current) next = `${current.trimEnd()}\n\n${generated}\n`;
|
|
144
|
+
if (next === current) return;
|
|
145
|
+
if (check) {
|
|
146
|
+
console.error(`stale: ${posix(path.relative(cwd, file))}`);
|
|
147
|
+
process.exitCode = 1;
|
|
148
|
+
return;
|
|
149
|
+
}
|
|
150
|
+
writeFileSync(file, next);
|
|
151
|
+
console.log(`wrote ${posix(path.relative(cwd, file))}`);
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
// Writes the readme of `dir` and of every sub-folder that holds documents, so any folder URL opens something.
|
|
155
|
+
function writeReadmes(root, dir, options) {
|
|
156
|
+
const folders = entriesOf(dir).filter((entry) => entry.isDirectory() && hasDocuments(path.join(dir, entry.name))).map((entry) => entry.name);
|
|
157
|
+
for (const name of folders) writeReadmes(root, path.join(dir, name), options);
|
|
158
|
+
const existing = readdirSync(dir).find(isReadme) ?? "readme.md";
|
|
159
|
+
const title = dir === root ? options.title : path.basename(dir);
|
|
160
|
+
const head = `# ${title}\n\n> Index of the documents in this folder. Opened by default when a folder path or a missing document is requested.\n\n`;
|
|
161
|
+
upsert(path.join(dir, existing), readmeBlock(root, dir, folders), head, options);
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
// Writes the root index.md, every folder readme.md and tree.json for the folder.
|
|
165
|
+
function generateIndex(root, options) {
|
|
166
|
+
const intro = `# ${options.title}\n\n> ${options.description}\n\n`;
|
|
167
|
+
upsert(path.join(root, "index.md"), rootIndexBlock(root, options.rootGroup), intro, options);
|
|
168
|
+
writeReadmes(root, root, options);
|
|
169
|
+
if (options.check) return;
|
|
170
|
+
writeFileSync(options.out, `${JSON.stringify(buildTree(root, options.cwd), null, 2)}\n`);
|
|
171
|
+
console.log(`wrote ${posix(path.relative(options.cwd, options.out))}`);
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
// Turns a name into a clean URL-safe kebab-case one (accents removed); keeps the original when nothing Latin is left.
|
|
175
|
+
function kebabName(name, keepExtension) {
|
|
176
|
+
const ext = keepExtension ? path.extname(name) : "";
|
|
177
|
+
const base = path.basename(name, ext).normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/đ/gi, "d");
|
|
178
|
+
const clean = base.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
|
|
179
|
+
return clean ? clean + ext.toLowerCase() : name;
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
// Plans every folder and Markdown file rename below `oldDir` (other files keep their name); a clash with a sibling keeps the original name and is warned about.
|
|
183
|
+
function planFolder(oldDir, newDir, plan) {
|
|
184
|
+
const entries = entriesOf(oldDir);
|
|
185
|
+
const wanted = entries.map((entry) => (entry.isDirectory() || isMarkdown(entry.name) ? kebabName(entry.name, entry.isFile()) : entry.name));
|
|
186
|
+
entries.forEach((entry, index) => {
|
|
187
|
+
const clash = wanted.some((name, other) => other !== index && name === wanted[index]) || entries.some((other) => other !== entry && other.name === wanted[index]);
|
|
188
|
+
if (clash) plan.warnings.push(`${posix(path.join(oldDir, entry.name))}: "${wanted[index]}" is taken, keeping the name`);
|
|
189
|
+
const from = path.join(oldDir, entry.name);
|
|
190
|
+
const to = path.join(newDir, clash ? entry.name : wanted[index]);
|
|
191
|
+
plan.moves.set(from, to);
|
|
192
|
+
if (!entry.isDirectory()) return;
|
|
193
|
+
plan.dirs.add(from);
|
|
194
|
+
planFolder(from, to, plan);
|
|
195
|
+
});
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
// Decodes `%20`-style escapes in a link, leaving it as written when it is not valid escaping.
|
|
199
|
+
function decodeLink(text) {
|
|
200
|
+
try {
|
|
201
|
+
return decodeURIComponent(text);
|
|
202
|
+
} catch {
|
|
203
|
+
return text;
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
// Computes the new relative form of one link when its target (or the file holding it) moved; returns the link unchanged otherwise.
|
|
208
|
+
function retarget(url, oldFile, newFile, moves) {
|
|
209
|
+
if (/^([a-z][a-z0-9+.-]*:|\/|#)/i.test(url)) return url;
|
|
210
|
+
const [, target, rest] = /^([^#?]*)(.*)$/.exec(url);
|
|
211
|
+
const resolved = path.resolve(path.dirname(oldFile), decodeLink(target));
|
|
212
|
+
const moved = moves.get(resolved.replace(/[\\/]$/, ""));
|
|
213
|
+
if (!moved || (moved === resolved && newFile === oldFile)) return url;
|
|
214
|
+
let relative = posix(path.relative(path.dirname(newFile), moved)).split("/").map(encodeURIComponent).join("/");
|
|
215
|
+
if (target.startsWith("./") && !relative.startsWith(".")) relative = `./${relative}`;
|
|
216
|
+
return relative + (target.endsWith("/") ? "/" : "") + rest;
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
// Rewrites the relative links, images and reference definitions of a document so they still point at renamed files.
|
|
220
|
+
function rewriteLinks(source, oldFile, newFile, moves) {
|
|
221
|
+
const fix = (url) => retarget(url, oldFile, newFile, moves);
|
|
222
|
+
return source
|
|
223
|
+
.replace(/(\]\(\s*)(?:<([^>]+)>|([^)\s]+))/g, (all, open, angled, plain) => open + (angled === undefined ? fix(plain) : `<${fix(angled)}>`))
|
|
224
|
+
.replace(/^(\s*\[[^\]]+\]:\s*)(\S+)/gm, (all, open, url) => open + fix(url));
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
// Quotes a frontmatter value only when plain text could be misread.
|
|
228
|
+
function frontmatterValue(value) {
|
|
229
|
+
return /[:#'"[\]{}&*!|>%@`]|^\s|\s$/.test(value) ? JSON.stringify(value.replace(/"/g, "")) : value;
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
// Adds missing keys to a document's frontmatter block, creating the block when there is none.
|
|
233
|
+
function addFrontmatter(source, keys) {
|
|
234
|
+
const lines = Object.entries(keys).map(([key, value]) => `${key}: ${frontmatterValue(String(value))}`);
|
|
235
|
+
const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(source);
|
|
236
|
+
if (!block) return `---\n${lines.join("\n")}\n---\n\n${source}`;
|
|
237
|
+
return `${block[0].replace(/\r?\n---$/, "")}\n${lines.join("\n")}\n---${source.slice(block[0].length)}`;
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
// Turns a file name into a readable title (`user-guide.md` -> `User Guide`).
|
|
241
|
+
function humanize(name) {
|
|
242
|
+
return path.basename(name, path.extname(name)).replace(/[_-]+/g, " ").replace(/\b\w/g, (letter) => letter.toUpperCase());
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
// True for documents the index step owns (folder readmes and the root index.md), which get no frontmatter edits.
|
|
246
|
+
function isGenerated(root, file) {
|
|
247
|
+
return isReadme(path.basename(file)) || (path.basename(file) === "index.md" && path.dirname(file) === root);
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
// Works out every document edit (link fixes, then missing `title` and `sidebar_position`) as `from -> { content, notes }`.
|
|
251
|
+
function planEdits(root, plan) {
|
|
252
|
+
const edits = new Map();
|
|
253
|
+
const sources = new Map();
|
|
254
|
+
for (const [from, to] of plan.moves) {
|
|
255
|
+
if (plan.dirs.has(from) || !isMarkdown(from)) continue;
|
|
256
|
+
const original = readFileSync(from, "utf8");
|
|
257
|
+
const linked = rewriteLinks(original, from, to, plan.moves);
|
|
258
|
+
sources.set(from, linked);
|
|
259
|
+
if (linked !== original) edits.set(from, { content: linked, notes: ["links"] });
|
|
260
|
+
}
|
|
261
|
+
const folders = new Map();
|
|
262
|
+
for (const [from, to] of plan.moves) {
|
|
263
|
+
if (!sources.has(from) || isGenerated(root, to)) continue;
|
|
264
|
+
folders.set(path.dirname(to), [...(folders.get(path.dirname(to)) ?? []), from]);
|
|
265
|
+
}
|
|
266
|
+
for (const files of folders.values()) {
|
|
267
|
+
let next = Math.max(0, ...files.map((from) => parseFrontmatter(sources.get(from)).data.sidebar_position).filter(Number.isFinite));
|
|
268
|
+
for (const from of files.sort((a, b) => plan.moves.get(a).localeCompare(plan.moves.get(b)))) {
|
|
269
|
+
const { data, body } = parseFrontmatter(sources.get(from));
|
|
270
|
+
const keys = {};
|
|
271
|
+
if (data.title === undefined) keys.title = /^#\s+(.+)$/m.exec(body)?.[1].trim() ?? humanize(plan.moves.get(from));
|
|
272
|
+
if (data.sidebar_position === undefined) keys.sidebar_position = ++next;
|
|
273
|
+
if (!Object.keys(keys).length) continue;
|
|
274
|
+
const edit = edits.get(from) ?? { notes: [] };
|
|
275
|
+
edits.set(from, { content: addFrontmatter(sources.get(from), keys), notes: [...edit.notes, `+${Object.keys(keys).join(" +")}`] });
|
|
276
|
+
}
|
|
277
|
+
}
|
|
278
|
+
return edits;
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
// Prints what `--restructure` would do, one line per change.
|
|
282
|
+
function printPlan(plan, edits, cwd) {
|
|
283
|
+
const show = (file) => posix(path.relative(cwd, file));
|
|
284
|
+
for (const [from, to] of plan.moves) if (from !== to) console.log(`rename ${show(from)} -> ${show(to)}`);
|
|
285
|
+
for (const [from, { notes }] of edits) console.log(`edit ${show(plan.moves.get(from))} (${notes.join(", ")})`);
|
|
286
|
+
for (const warning of plan.warnings) console.warn(`warn ${warning}`);
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
// Moves the files, writes the edited documents and removes folders the renames left empty.
|
|
290
|
+
function applyPlan(plan, edits) {
|
|
291
|
+
for (const [from, to] of plan.moves) {
|
|
292
|
+
if (plan.dirs.has(from)) continue;
|
|
293
|
+
mkdirSync(path.dirname(to), { recursive: true });
|
|
294
|
+
if (from !== to) renameSync(from, to);
|
|
295
|
+
if (edits.has(from)) writeFileSync(to, edits.get(from).content);
|
|
296
|
+
}
|
|
297
|
+
const emptied = [...plan.dirs].filter((dir) => plan.moves.get(dir) !== dir).sort((a, b) => b.length - a.length);
|
|
298
|
+
for (const dir of emptied) if (existsSync(dir) && readdirSync(dir).length === 0) rmdirSync(dir);
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
// Reads the command line flags into options, with defaults.
|
|
302
|
+
function parseOptions(argv, cwd) {
|
|
303
|
+
const value = (flag) => (argv.includes(flag) ? argv[argv.indexOf(flag) + 1] : undefined);
|
|
304
|
+
const valueFlags = ["--title", "--description", "--root-group", "--out"];
|
|
305
|
+
const folder = argv.find((arg, index) => !arg.startsWith("--") && !valueFlags.includes(argv[index - 1])) ?? "docs";
|
|
306
|
+
const root = path.resolve(cwd, folder);
|
|
307
|
+
return {
|
|
308
|
+
cwd,
|
|
309
|
+
root,
|
|
310
|
+
check: argv.includes("--check"),
|
|
311
|
+
restructure: argv.includes("--restructure"),
|
|
312
|
+
write: argv.includes("--write"),
|
|
313
|
+
title: value("--title") ?? path.basename(root),
|
|
314
|
+
description: value("--description") ?? DEFAULT_DESCRIPTION,
|
|
315
|
+
rootGroup: value("--root-group") ?? "Guides",
|
|
316
|
+
out: path.resolve(cwd, value("--out") ?? path.join(folder, "tree.json")),
|
|
317
|
+
};
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
/** `docs` command: prepares a Markdown folder for DocViewer. With `--restructure` it first plans (and with `--write` applies) kebab-case renames, link fixes and missing frontmatter; then it writes index.md, folder readmes and tree.json. */
|
|
321
|
+
export function cmdDocs(argv, cwd = process.cwd()) {
|
|
322
|
+
const options = parseOptions(argv, cwd);
|
|
323
|
+
if (!existsSync(options.root) || !statSync(options.root).isDirectory()) {
|
|
324
|
+
console.error(`Usage: create-nodexui-app docs [folder] [--restructure [--write]] [--check] [--title T] [--description D] [--root-group G] [--out file]\nnot a directory: ${options.root}`);
|
|
325
|
+
process.exitCode = 2;
|
|
326
|
+
return;
|
|
327
|
+
}
|
|
328
|
+
if (options.restructure) {
|
|
329
|
+
const plan = { moves: new Map(), dirs: new Set(), warnings: [] };
|
|
330
|
+
planFolder(options.root, options.root, plan);
|
|
331
|
+
const edits = planEdits(options.root, plan);
|
|
332
|
+
printPlan(plan, edits, options.cwd);
|
|
333
|
+
if (!options.write) {
|
|
334
|
+
console.log("Dry run: re-run with --write to apply these changes (then the index files are generated).");
|
|
335
|
+
return;
|
|
336
|
+
}
|
|
337
|
+
applyPlan(plan, edits);
|
|
338
|
+
}
|
|
339
|
+
generateIndex(options.root, options);
|
|
340
|
+
}
|