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 CHANGED
@@ -1,6 +1,27 @@
1
1
  # Changelog
2
2
 
3
- ## 1.17.0-beta.3
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.
@@ -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, div({
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 first heading
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 docs = [...content.matchAll(/^[ \t]*(\/\*#[\s\S]+?\*\/)/gm)].map((m) => m[1]);
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.map((s) => s.substring(3, s.length - 2).trim());
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)