tosijs-ui 1.17.0-beta.3 ā 1.17.0-beta.4
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 +22 -1
- package/dist/doc-browser.js +11 -1
- package/dist/doc-system/site/build-peers.d.ts +6 -0
- package/dist/doc-system/site/build-peers.js +43 -0
- package/dist/doc-system/site/docs.d.ts +4 -0
- package/dist/doc-system/site/docs.js +89 -5
- package/dist/doc-system/site/orchestrator.js +7 -0
- package/dist/iife.js +3 -3
- package/dist/iife.js.map +4 -4
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/llms.txt +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,27 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
## 1.17.0-beta.
|
|
3
|
+
## 1.17.0-beta.4
|
|
4
|
+
|
|
5
|
+
> Prerelease, published under the `beta` dist-tag: install with `tosijs-ui@beta`. `latest` stays
|
|
6
|
+
> on 1.16.41. Fixes from Learn 3D and from tosijs-native's first site build.
|
|
7
|
+
|
|
8
|
+
- **Every doc page can be scrolled by keyboard, and has a main landmark (#3575).** A page of
|
|
9
|
+
plain prose had nothing to tab to inside its scrolling content, so a keyboard user could not
|
|
10
|
+
scroll it, which axe reports as `scrollable-region-focusable` (Learn 3D: 71 of 126 pages). The
|
|
11
|
+
content scroller is now focusable, and it is the page's main landmark, which the doc site did not
|
|
12
|
+
have at all: a screen reader's "jump to main content" now works. A doc browser embedded in
|
|
13
|
+
another page stays focusable without claiming that page's main landmark.
|
|
14
|
+
- **`buildSite` says it needs `happy-dom` before it starts (#3600).** Without it, the build died
|
|
15
|
+
partway through with "Cannot find package 'happy-dom'" from a file inside tosijs-ui. It now
|
|
16
|
+
stops before writing anything and prints the install command. `happy-dom` stays an optional
|
|
17
|
+
peer: a project that only uses the components never needs it.
|
|
18
|
+
- **TJS's own doc comments, `/# ⦠#/`, become documentation (#3601).** In `.tjs` and `.ajs`
|
|
19
|
+
files they are read in source order with any `/*#` blocks. tjs-lang finds them, so its grammar
|
|
20
|
+
applies exactly; that needs a tjs-lang that exports `findDocCommentSpans` (requested). With an
|
|
21
|
+
older one, the build names each file whose `/#` comments it could not read, instead of
|
|
22
|
+
dropping the page silently. `.ajs` files are now scraped for `/*#` blocks too.
|
|
23
|
+
|
|
24
|
+
### 1.17.0-beta.3 (prerelease detail)
|
|
4
25
|
|
|
5
26
|
> Prerelease, published under the `beta` dist-tag: install with `tosijs-ui@beta`. `latest` stays
|
|
6
27
|
> on 1.16.41. beta.2 was staged and never published; its notes follow.
|
package/dist/doc-browser.js
CHANGED
|
@@ -1699,7 +1699,17 @@ export function createDocBrowser(options) {
|
|
|
1699
1699
|
// The sidenav has just introduced itself; give it the layout the doc asked for.
|
|
1700
1700
|
applyFullScreen();
|
|
1701
1701
|
},
|
|
1702
|
-
}, navContent,
|
|
1702
|
+
}, navContent,
|
|
1703
|
+
/*
|
|
1704
|
+
The page's main landmark, and focusable: a page of plain prose has nothing else to tab
|
|
1705
|
+
to, so a keyboard user could not scroll it at all (WCAG 2.1.1; axe
|
|
1706
|
+
scrollable-region-focusable, #3575). A role, not a <main>, so styles written against the
|
|
1707
|
+
div still apply. An embedded browser (`memory` routing) is part of someone else's page,
|
|
1708
|
+
so it does not claim that page's main landmark.
|
|
1709
|
+
*/
|
|
1710
|
+
div({
|
|
1711
|
+
...(routing === 'memory' ? {} : { role: 'main' }),
|
|
1712
|
+
tabindex: 0,
|
|
1703
1713
|
style: {
|
|
1704
1714
|
position: 'relative',
|
|
1705
1715
|
overflowY: 'scroll',
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The install command for each build peer that cannot be resolved, or none.
|
|
3
|
+
* `resolve` is injectable for tests.
|
|
4
|
+
*/
|
|
5
|
+
export declare function missingBuildPeers(moduleDir: string, resolve?: (name: string, from: string) => string): string[];
|
|
6
|
+
export declare function missingBuildPeersMessage(missing: string[]): string;
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/*
|
|
2
|
+
Optional peers a site BUILD cannot do without (#3600).
|
|
3
|
+
|
|
4
|
+
`happy-dom` is an optional peer of tosijs-ui because a project that only uses the components
|
|
5
|
+
never needs it, and npm installs a required peer whether or not it is used. But `buildSite`
|
|
6
|
+
does need it: the theme stylesheet is generated with tosijs imported under a DOM shim. Without
|
|
7
|
+
it the build died several steps in with "Cannot find package 'happy-dom'" from a file inside
|
|
8
|
+
tosijs-ui, which says nothing about whose job it is to install it. So the build checks first,
|
|
9
|
+
and says what to run.
|
|
10
|
+
*/
|
|
11
|
+
import { readFileSync } from 'fs';
|
|
12
|
+
import * as path from 'path';
|
|
13
|
+
import { tosijsUiDir } from './codemirror-copies.js';
|
|
14
|
+
/** What a site build requires, resolved from tosijs-ui's own location (where it is imported). */
|
|
15
|
+
const BUILD_PEERS = ['happy-dom'];
|
|
16
|
+
/**
|
|
17
|
+
* The install command for each build peer that cannot be resolved, or none.
|
|
18
|
+
* `resolve` is injectable for tests.
|
|
19
|
+
*/
|
|
20
|
+
export function missingBuildPeers(moduleDir, resolve = Bun.resolveSync) {
|
|
21
|
+
let ranges = {};
|
|
22
|
+
try {
|
|
23
|
+
const pkg = JSON.parse(readFileSync(path.join(tosijsUiDir(moduleDir), 'package.json'), 'utf8'));
|
|
24
|
+
ranges = pkg.peerDependencies ?? {};
|
|
25
|
+
}
|
|
26
|
+
catch {
|
|
27
|
+
// no manifest found: name the package without a range
|
|
28
|
+
}
|
|
29
|
+
return BUILD_PEERS.filter((name) => {
|
|
30
|
+
try {
|
|
31
|
+
resolve(name, moduleDir);
|
|
32
|
+
return false;
|
|
33
|
+
}
|
|
34
|
+
catch {
|
|
35
|
+
return true;
|
|
36
|
+
}
|
|
37
|
+
}).map((name) => (ranges[name] ? `${name}@${ranges[name]}` : name));
|
|
38
|
+
}
|
|
39
|
+
export function missingBuildPeersMessage(missing) {
|
|
40
|
+
return (`\nš Building a site needs ${missing.join(', ')}, an optional peer of tosijs-ui ` +
|
|
41
|
+
`(a project that only uses the components does not).\n` +
|
|
42
|
+
` bun add -d ${missing.map((m) => `'${m}'`).join(' ')}\n`);
|
|
43
|
+
}
|
|
@@ -143,5 +143,9 @@ export declare function parseFrontmatter(content: string): {
|
|
|
143
143
|
body: string;
|
|
144
144
|
};
|
|
145
145
|
export declare const SCRAPED_SOURCE_EXTENSIONS: string[];
|
|
146
|
+
type DocSpans = (source: string) => Array<[number, number]>;
|
|
147
|
+
/** Tests only: stand in for tjs-lang's scanner (`undefined` restores the lookup). */
|
|
148
|
+
export declare function setTjsDocCommentScanner(scan: DocSpans | null | undefined): void;
|
|
146
149
|
export declare function extractDocs(options: ExtractDocsOptions): Doc[];
|
|
147
150
|
export declare function saveDocsJSON(docs: Doc[], outputPath: string): void;
|
|
151
|
+
export {};
|
|
@@ -30,8 +30,13 @@ whatever metadata the doc declares (`pin`, `order`, `parent`, `layout`, `descrip
|
|
|
30
30
|
## What is collected
|
|
31
31
|
|
|
32
32
|
- **`.md` files**, whole. YAML frontmatter is read and removed.
|
|
33
|
-
- **`/*#` ⦠`*ā/` blocks** in `.ts`, `.tjs`, `.js` and `.css` files, as markdown. The
|
|
34
|
-
is the page title. A block counts only when `/*#` starts a line.
|
|
33
|
+
- **`/*#` ⦠`*ā/` blocks** in `.ts`, `.tjs`, `.ajs`, `.js` and `.css` files, as markdown. The
|
|
34
|
+
first heading is the page title. A block counts only when `/*#` starts a line.
|
|
35
|
+
- **TJS doc comments, `/#` ⦠`#/`**, in `.tjs` and `.ajs` files, in source order with any `/*#`
|
|
36
|
+
blocks. They are found by tjs-lang itself, so they follow its grammar exactly: multi-line, and
|
|
37
|
+
a doc comment nested inside one is quoted as part of it. This needs a tjs-lang that exports
|
|
38
|
+
`findDocCommentSpans`; with an older one, the build names each file whose `/#` comments it
|
|
39
|
+
could not read.
|
|
35
40
|
- **Files whose name starts with `_`** are skipped: use the prefix for drafts and fragments.
|
|
36
41
|
|
|
37
42
|
Metadata blocks (`<!--{ ⦠}-->` in markdown, `/*{ ⦠}*ā/` in code), nav order, sections and
|
|
@@ -40,6 +45,7 @@ which code fences run live are described under [Doc format](/doc-site-system/#do
|
|
|
40
45
|
/*{ "parent": "Documentation System", "order": 60, "description": "extractDocs() collects markdown files and doc comments from source code into one docs.json corpus, the input to the doc browser and static site." }*/
|
|
41
46
|
// TODO CLI options
|
|
42
47
|
import * as fs from 'fs';
|
|
48
|
+
import { createRequire } from 'module';
|
|
43
49
|
import * as path from 'path';
|
|
44
50
|
import { truncationWarnings, formatTruncationWarnings, } from './truncated-doc.js';
|
|
45
51
|
import { pinnedSort } from '../nav-tree.js';
|
|
@@ -230,9 +236,47 @@ ends it ā the same trap tosijs-ui#70 records for doc blocks, hit again while w
|
|
|
230
236
|
|
|
231
237
|
See `warnUnscrapedDocBlocks` below: a missing extension should never again be invisible.
|
|
232
238
|
*/
|
|
233
|
-
export const SCRAPED_SOURCE_EXTENSIONS = ['.ts', '.js', '.tjs', '.css'];
|
|
239
|
+
export const SCRAPED_SOURCE_EXTENSIONS = ['.ts', '.js', '.tjs', '.ajs', '.css'];
|
|
234
240
|
/** Files that look documented but are not scraped ā reported once at the end of a walk. */
|
|
235
241
|
const unscrapedDocBlocks = [];
|
|
242
|
+
/*
|
|
243
|
+
TJS's own doc comment, `/# ⦠#/` (#3601): multi-line, nestable, and the convention in `.tjs` and
|
|
244
|
+
`.ajs` sources. Its grammar belongs to tjs-lang, which finds the spans over a literal-masked view
|
|
245
|
+
(a raw scan reads a regex `/#/` and a later string `"#/"` as one comment). So this does not keep a
|
|
246
|
+
second copy: it asks the installed tjs-lang, and when that tjs-lang does not export the scanner,
|
|
247
|
+
the build names the files whose doc comments it could not read rather than dropping them.
|
|
248
|
+
*/
|
|
249
|
+
const TJS_DOC_EXTENSIONS = ['.tjs', '.ajs'];
|
|
250
|
+
// An opener at the start of a line that its own line does not close: a single-line `/# x #/` is
|
|
251
|
+
// a regex, never a doc comment.
|
|
252
|
+
const TJS_DOC_OPENER = /^[ \t]*\/#(?![^\n]*#\/)/m;
|
|
253
|
+
let tjsDocSpans;
|
|
254
|
+
function tjsDocCommentSpans() {
|
|
255
|
+
if (tjsDocSpans !== undefined)
|
|
256
|
+
return tjsDocSpans;
|
|
257
|
+
tjsDocSpans = null;
|
|
258
|
+
// The project's tjs-lang, the one its .tjs files are written for.
|
|
259
|
+
const projectModule = createRequire(path.resolve('package.json'));
|
|
260
|
+
for (const entry of ['tjs-lang/lang', 'tjs-lang']) {
|
|
261
|
+
try {
|
|
262
|
+
const found = projectModule(entry).findDocCommentSpans;
|
|
263
|
+
if (typeof found === 'function') {
|
|
264
|
+
tjsDocSpans = found;
|
|
265
|
+
break;
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
catch {
|
|
269
|
+
// not installed, or no such entry: try the next
|
|
270
|
+
}
|
|
271
|
+
}
|
|
272
|
+
return tjsDocSpans;
|
|
273
|
+
}
|
|
274
|
+
/** Tests only: stand in for tjs-lang's scanner (`undefined` restores the lookup). */
|
|
275
|
+
export function setTjsDocCommentScanner(scan) {
|
|
276
|
+
tjsDocSpans = scan;
|
|
277
|
+
}
|
|
278
|
+
/** `.tjs`/`.ajs` files with doc comments the installed tjs-lang could not read. */
|
|
279
|
+
const unreadTjsDocComments = [];
|
|
236
280
|
/**
|
|
237
281
|
* Does an UNSCRAPED file appear to carry a doc block?
|
|
238
282
|
*
|
|
@@ -385,9 +429,41 @@ walked) {
|
|
|
385
429
|
// before the slash). This keeps a `/*#` that appears inside a // comment,
|
|
386
430
|
// a string, or otherwise mid-line from being scraped as a spurious doc.
|
|
387
431
|
// m[1] is the block without its leading indentation.
|
|
388
|
-
const
|
|
432
|
+
const blocks = [
|
|
433
|
+
...content.matchAll(/^[ \t]*(\/\*#[\s\S]+?\*\/)/gm),
|
|
434
|
+
].map((m) => ({
|
|
435
|
+
at: m.index + m[0].length - m[1].length,
|
|
436
|
+
block: m[1],
|
|
437
|
+
}));
|
|
438
|
+
const docs = blocks.map(({ block }) => block.substring(3, block.length - 2).trim());
|
|
439
|
+
// TJS doc comments, in source order with any `/*#` blocks.
|
|
440
|
+
if (TJS_DOC_EXTENSIONS.includes(path.extname(file)) &&
|
|
441
|
+
TJS_DOC_OPENER.test(content)) {
|
|
442
|
+
const scan = tjsDocCommentSpans();
|
|
443
|
+
if (!scan) {
|
|
444
|
+
unreadTjsDocComments.push(path.relative(process.cwd(), filePath));
|
|
445
|
+
}
|
|
446
|
+
else {
|
|
447
|
+
const spans = scan(content);
|
|
448
|
+
// Outermost only: a nested doc comment is being quoted, not published.
|
|
449
|
+
const outer = spans.filter(([a, b]) => !spans.some(([c, d]) => c < a && b <= d));
|
|
450
|
+
const all = [
|
|
451
|
+
...blocks.map(({ at }, i) => ({ at, text: docs[i] })),
|
|
452
|
+
...outer.map(([a, b]) => ({
|
|
453
|
+
at: a,
|
|
454
|
+
// The span may or may not include its delimiters; the text never does.
|
|
455
|
+
text: content
|
|
456
|
+
.slice(a, b)
|
|
457
|
+
.replace(/^\/#/, '')
|
|
458
|
+
.replace(/#\/$/, '')
|
|
459
|
+
.trim(),
|
|
460
|
+
})),
|
|
461
|
+
].sort((x, y) => x.at - y.at);
|
|
462
|
+
docs.splice(0, docs.length, ...all.map((d) => d.text));
|
|
463
|
+
}
|
|
464
|
+
}
|
|
389
465
|
if (docs.length) {
|
|
390
|
-
const markdown = docs
|
|
466
|
+
const markdown = docs;
|
|
391
467
|
// A doc block that ended early drops the rest of the documentation silently, and
|
|
392
468
|
// turns the code after it back into source ā which surfaces as parse errors
|
|
393
469
|
// pointing at prose rather than at the delimiter responsible (#70).
|
|
@@ -444,6 +520,14 @@ walked) {
|
|
|
444
520
|
can act on without going looking. The fix is nearly always one entry in
|
|
445
521
|
SCRAPED_SOURCE_EXTENSIONS.
|
|
446
522
|
*/
|
|
523
|
+
if (unreadTjsDocComments.length) {
|
|
524
|
+
console.warn(`\nā ļø ${unreadTjsDocComments.length} file(s) have TJS doc comments (/# ⦠#/) that this ` +
|
|
525
|
+
`build cannot read, so they have no page from them:\n` +
|
|
526
|
+
unreadTjsDocComments.map((f) => ` ${f}`).join('\n') +
|
|
527
|
+
`\n Reading them needs findDocCommentSpans from tjs-lang, which the installed ` +
|
|
528
|
+
`tjs-lang does not export. Until it does, write those blocks as /*# ⦠*/.\n`);
|
|
529
|
+
unreadTjsDocComments.length = 0;
|
|
530
|
+
}
|
|
447
531
|
if (unscrapedDocBlocks.length) {
|
|
448
532
|
const list = unscrapedDocBlocks.map((f) => ` ${f}`).join('\n');
|
|
449
533
|
console.warn(`\nā ļø ${unscrapedDocBlocks.length} file(s) look documented but are not scraped, so ` +
|
|
@@ -31,6 +31,7 @@ export function registerSiteDialects(config) {
|
|
|
31
31
|
import { namedBooks, partitionByBook, DEFAULT_BOOK } from '../book-target.js';
|
|
32
32
|
import { EPUB_IMAGE_EXIT, attachCovers, listEpubVolumes, printCoverManifestUrl, VOLUME_MANIFEST, renderEpubDownloads, } from './epub-volumes.js';
|
|
33
33
|
import { buildSlugMap, pathForSlug } from '../routing.js';
|
|
34
|
+
import { missingBuildPeers, missingBuildPeersMessage } from './build-peers.js';
|
|
34
35
|
import { assetStampInputs, computeAssetStamp, missingStampInputWarning, } from './asset-stamp.js';
|
|
35
36
|
import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, } from 'fs';
|
|
36
37
|
import { tmpdir } from 'os';
|
|
@@ -416,6 +417,12 @@ export async function buildSite(config, opts = {}) {
|
|
|
416
417
|
}))) {
|
|
417
418
|
return false;
|
|
418
419
|
}
|
|
420
|
+
// A peer the build needs, checked before anything is deleted or written (#3600).
|
|
421
|
+
const missingPeers = missingBuildPeers(import.meta.dir);
|
|
422
|
+
if (missingPeers.length) {
|
|
423
|
+
console.error(missingBuildPeersMessage(missingPeers));
|
|
424
|
+
return false;
|
|
425
|
+
}
|
|
419
426
|
// Dependency-audit gate. Runs on the initial build only ā the dev server runs its
|
|
420
427
|
// own synchronous audit just before binding the port, and `opts.skipAudit` keeps
|
|
421
428
|
// watch rebuilds off the network. Fails the build (before the destructive rm -rf)
|