@aiquants/markdown-explorer 0.16.0 → 0.18.0
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 +121 -15
- package/README.md +47 -21
- package/dist/{EditSurface-DGMLY7Gh.js → EditSurface-B2bzY1b_.js} +3 -3
- package/dist/{EditSurface-CwKsTS11.cjs → EditSurface-BRuIjA9L.cjs} +1 -1
- package/dist/{ExplorerSplit-BLOaU5fE.cjs → ExplorerSplit-BE1VJuok.cjs} +1 -1
- package/dist/{ExplorerSplit-tUCp0XdJ.js → ExplorerSplit-qAKZsLZa.js} +3 -3
- package/dist/{MultiLayout-BBP2ajz8.cjs → MultiLayout-Bc6RYc3U.cjs} +1 -1
- package/dist/{MultiLayout-DYy66vcO.js → MultiLayout-rsmtFma5.js} +251 -247
- package/dist/NativeScrollBar-Dq3YeUVY.js +65 -0
- package/dist/NativeScrollBar-DqTkrnPZ.cjs +1 -0
- package/dist/{TreeLayout-CXX-rFO6.js → TreeLayout-BPa7NdeT.js} +3 -3
- package/dist/{TreeLayout-C8s5lBH_.cjs → TreeLayout-DXoEAcpD.cjs} +1 -1
- package/dist/core/geometry.d.cts +1 -1
- package/dist/core/geometry.d.ts +1 -1
- package/dist/core/labels.d.cts +11 -0
- package/dist/core/labels.d.ts +11 -0
- package/dist/{index-DTKGgaok.js → index-25s_q0vD.js} +829 -795
- package/dist/index-W3iAjkLb.cjs +13 -0
- package/dist/index.cjs +1 -1
- package/dist/index.js +2 -2
- package/dist/{location-G7psbmv_.js → location-B-m9scLf.js} +82 -82
- package/dist/{location-D85EXiPt.cjs → location-BVEN_Ihk.cjs} +1 -1
- package/dist/{merge-BkFru0eg.js → merge-B9jrWxMa.js} +1 -1
- package/dist/{merge-SRws1-Zj.cjs → merge-DuTAponF.cjs} +1 -1
- package/dist/server.cjs +1 -1
- package/dist/server.js +1 -1
- package/dist/styles/markdown-explorer.css +1 -1
- package/dist/{useSplitPersistence-DRjsPZdH.cjs → useSplitPersistence-Ba-v64n-.cjs} +1 -1
- package/dist/{useSplitPersistence-B1b5Lg5E.js → useSplitPersistence-Cc4tDxB4.js} +1 -1
- package/docs/behavior/dom-hooks.md +5 -2
- package/docs/behavior/layout.md +78 -33
- package/docs/behavior/localization.md +11 -5
- package/package.json +5 -5
- package/dist/NativeScrollBar-BkFg1EcW.cjs +0 -1
- package/dist/NativeScrollBar-Dazd542j.js +0 -59
- package/dist/index-DffJZ8-y.cjs +0 -13
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,87 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## Unreleased
|
|
4
|
+
|
|
5
|
+
### Breaking
|
|
6
|
+
|
|
7
|
+
- **The peer floors are `@aiquants/markdown` ^8.1.0 and `@aiquants/drag-drop-panels` ^0.12.0.** The viewer's controls
|
|
8
|
+
(its toolbar, the table of contents, a code block's copy button and a Mermaid diagram's controls, whose toolbar is a
|
|
9
|
+
row above the diagram) are 44 × 44 px targets under every pointer, and so are the panel headers' buttons and the
|
|
10
|
+
restore buttons of the bar of hidden panels.
|
|
11
|
+
- **A panel header has one move menu in place of its four move buttons.** Its button, Move the panel (the new label
|
|
12
|
+
`panelMove`), opens a menu of the moves the stage offers — to the previous or the next column, up and down, named by
|
|
13
|
+
`panelMovePreviousColumn`, `panelMoveNextColumn`, `panelMoveUp` and `panelMoveDown` as the buttons were; up and down
|
|
14
|
+
only on a stage of one column. A move the panel cannot make stays in the menu as `aria-disabled` and, chosen,
|
|
15
|
+
announces that the panel cannot make it (`panelMoveUnavailable`). After a move chosen in the menu the focus is on the
|
|
16
|
+
menu's button, also when the move rebuilt the panel in another column: the stage now tells a header control by its
|
|
17
|
+
action (`data-aqdd-panel-action`) when it gives the focus back, since the menu's button gets a new id with every
|
|
18
|
+
mount. The menu opens in the top layer, so a browser without the Popover API cannot open it (Alt + Shift + an arrow
|
|
19
|
+
still moves the panel there). A header shows at most five buttons; where the reader can hover they stay on the
|
|
20
|
+
title's row while the title keeps 5em, and on a device that cannot hover they take a row of their own below the
|
|
21
|
+
title. A host or a test that pressed a move button opens the menu (`data-aqdd-panel-action="move"`) and chooses an
|
|
22
|
+
item (`data-aqdd-panel-move`).
|
|
23
|
+
|
|
24
|
+
### Added
|
|
25
|
+
|
|
26
|
+
- **The `panelMove` label** (`Move the panel`, ja `パネルを移動`) names each panel header's move menu button.
|
|
27
|
+
|
|
28
|
+
### Changed
|
|
29
|
+
|
|
30
|
+
- **Every control of the explorer is a 44 × 44 px target under every pointer.** `--aqmx-control` is 2.75rem (44 px,
|
|
31
|
+
WCAG 2.2's enhanced target size) under a mouse and a pen as under a finger; a fine pointer had 2.125rem (34 px). So the
|
|
32
|
+
explorer's header (the source switch, the view switch and the tree's toolbar), the tree's rows and a folder's Try
|
|
33
|
+
again, the tree settings menu, the selection tray, the document bar (Source, Edit, Refresh document and the editor's
|
|
34
|
+
controls), the dialogs' buttons and the file views' toolbars are at least 44 × 44 px on a desktop too, as a new
|
|
35
|
+
end-to-end test measures at 1440 × 900 with a fine pointer; the tree's rows follow the token as before. The sheet's
|
|
36
|
+
toggle and close button read `--aqmx-control` as well, in place of the stylesheet's own `--aqmx-sheet-target`, which
|
|
37
|
+
is gone (it held the same 2.75rem), so a host's override of `--aqmx-control` sizes them too.
|
|
38
|
+
- **What stays coarse-only:** the body text's 16 px (`--aqmx-font-size-body: 1rem` under `(pointer: coarse)`, so Safari
|
|
39
|
+
on iOS does not zoom into a focused field) and the resize handles' bands (24 px and thin under a fine pointer, 44 px
|
|
40
|
+
under a coarse one; the arrow keys move them as well).
|
|
41
|
+
|
|
42
|
+
## 0.17.0 (2026-10-24) — `@aiquants/markdown` 8 and `@aiquants/drag-drop-panels` 0.11, no ResizeObserver loop reports from the scroll bar, and a collapse check that waits for the layout to settle
|
|
43
|
+
|
|
44
|
+
### Changed
|
|
45
|
+
|
|
46
|
+
- **Follows `@aiquants/markdown` 8.0.0 and `@aiquants/drag-drop-panels` 0.11.0.** The viewer's labels gain the ten new
|
|
47
|
+
Mermaid keys in English and Japanese, which the explorer passes to the viewer: the touch menu's name and its four items
|
|
48
|
+
(`viewerMermaidInteractionModeTouch`, `viewerMermaidModeNoneTouch`, `viewerMermaidModeZoomTouch`,
|
|
49
|
+
`viewerMermaidModePanTouch`, `viewerMermaidModeBothTouch`), the four pan buttons (`viewerMermaidPanUp`,
|
|
50
|
+
`viewerMermaidPanDown`, `viewerMermaidPanLeft`, `viewerMermaidPanRight`) and the name of the diagram's frame
|
|
51
|
+
(`viewerMermaidDiagram`); the Japanese catalog writes the viewer's `+` as `+` (`拡大縮小+移動`), in
|
|
52
|
+
`viewerMermaidModeBoth` and `viewerMermaidModeBothShift` too. A host without Tailwind CSS links
|
|
53
|
+
`@aiquants/markdown/styles/markdown.standalone.css` instead of `markdown.css` (the demo does), and a Tailwind v4 host
|
|
54
|
+
imports `markdown.css` in its Tailwind entry without `layer()`, adds
|
|
55
|
+
`@source "../node_modules/@aiquants/markdown/dist/**/*.js";` and declares the `dark` variant the viewer's utilities
|
|
56
|
+
follow, `@custom-variant dark (&:where(.dark, .dark *, [data-theme="dark"], [data-theme="dark"] *));` to match the
|
|
57
|
+
standalone sheet (Tailwind's own is the `prefers-color-scheme` media query), never loading both sheets (see
|
|
58
|
+
[Load the styles](README.md#5-load-the-styles)). The behavior docs and the tests follow drag-drop-panels 0.11.0's
|
|
59
|
+
panel headers: a stage of one column renders only Move up and Move down (Alt + Shift + ← / → announce that the move is
|
|
60
|
+
unavailable), a panel in the normal mode shows no drag-mode toggle where no fine pointer exists, and under a coarse
|
|
61
|
+
pointer the header buttons are 44 px targets on a line of their own below the title, rows 22 px apart and Close 22 px
|
|
62
|
+
from every other button; and a Mermaid diagram that fits its frame takes `touch-action: pan-x pan-y`, so a finger on it
|
|
63
|
+
scrolls the document. The peer floors are `@aiquants/markdown` ^8.0.0 and `@aiquants/drag-drop-panels` ^0.11.0.
|
|
64
|
+
|
|
65
|
+
### Fixed
|
|
66
|
+
|
|
67
|
+
- **A document no longer raises `ResizeObserver loop completed with undelivered notifications` while a Mermaid diagram
|
|
68
|
+
is drawn.** The scroll bar's store of the scroller's sizes notified React from inside its ResizeObserver callback, so
|
|
69
|
+
React rendered the bar synchronously in the microtasks of the browser's delivery of the observations, and that render
|
|
70
|
+
first ran the page's pending effects and updates — among them the viewer's effect that inserts a diagram's SVG. The
|
|
71
|
+
document's content grew after its observers had been notified, which the browser reports as a loop error (seen
|
|
72
|
+
intermittently on a phone in the single view). The bar now measures resizes of the scroller and its children, and
|
|
73
|
+
changes of its children, on the next animation frame (once however many arrive before it, cancelled when the bar
|
|
74
|
+
unmounts); a `scroll` event still updates it at once.
|
|
75
|
+
- **Switching Chrome DevTools' device toolbar between a desktop and a phone size no longer logs `the explorer collapsed
|
|
76
|
+
to 0px while lockDocumentScroll stops the page from scrolling`.** The check measured the explorer at the instant of
|
|
77
|
+
the mount and of every resize of its root or the window, and reported the first problem for the rest of the mount. A
|
|
78
|
+
resize can pass through intermediate viewports before it ends, and in one shorter than the host's own bars (a 30 px
|
|
79
|
+
one under a 44 px footer, for example) the explorer's root measures 0 px for a moment although its container has a
|
|
80
|
+
definite block size, so a layout that settled at full height left a false report. The explorer is now measured once
|
|
81
|
+
its root and the window have kept their size for one second after the mount or their last resize
|
|
82
|
+
(`PLACEMENT_SETTLE_MILLISECONDS`; every resize starts the wait over, and unmounting cancels it): an overflow or a
|
|
83
|
+
collapse that persists is still reported once per mount, a moment of one is not.
|
|
84
|
+
|
|
3
85
|
## 0.16.0 (2026-10-22) — folders that show their README, a resizable editor split, and fixes from a phone audit
|
|
4
86
|
|
|
5
87
|
### Added
|
|
@@ -284,12 +366,14 @@
|
|
|
284
366
|
|
|
285
367
|
- **Tap-scroll circle on the document**: in the tree and single views, markdown and text documents get a pointer scroll bar with the tree's tap-scroll circle (`@aiquants/virtualscroll`'s `ScrollBar`, one shared circle setting), driving the viewer's native scroller through `@aiquants/markdown`'s `renderScrollBar` seam: the native vertical scrollbar is hidden, the bar is hidden from assistive technology and has no Tab stops, and keyboard, wheel and touch scrolling are unchanged. Multi-view panels have none (the panel's area scrolls).
|
|
286
368
|
The bar's module loads on first use; if it fails to load (a chunk gone after a redeploy) or the bar throws, the slot stays empty, the document keeps its native scroller and the failure is reported with `console.error`, instead of the error reaching the route.
|
|
287
|
-
- **Tap-scroll circle on every scroller that needs one**: the same bar and circle (one shared component) now also drive, in the tree and single views, a zoomed image's canvas (its native horizontal scrollbar stays), a medium's and a file view's stage and the failure view, each laid out with `@aiquants/markdown`'s `HostedScrollArea`; in the multi view, each panel's scroll area, maximized or not (drag-drop-panels' `renderPanelScrollArea`; the bar is exempt from panel drags).
|
|
369
|
+
- **Tap-scroll circle on every scroller that needs one**: the same bar and circle (one shared component) now also drive, in the tree and single views, a zoomed image's canvas (its native horizontal scrollbar stays), a medium's and a file view's stage and the failure view, each laid out with `@aiquants/markdown`'s `HostedScrollArea`; in the multi view, each panel's scroll area, maximized or not (drag-drop-panels' `renderPanelScrollArea`; the bar is exempt from panel drags).
|
|
370
|
+
The stage gets the same bar without a circle (drag-drop-panels' `renderStageScrollBar`), in 8 px it adds to the inline end of its padding: a circle there would sit on the right-most panel next to that panel's own circle, and a gutter for it would cost the stage a column at common widths. A bar shows only while its content overflows. Inside a panel, the viewer and the image, media, file and failure views keep no bar of their own. Menus, popovers, nested horizontal scrollers and embedded frames (a PDF's included) get no circle.
|
|
288
371
|
Requires the `@aiquants/markdown` release that exports `HostedScrollArea` and the `@aiquants/drag-drop-panels` release with `renderPanelScrollArea`, `renderStageScrollBar`, `SCROLL_AREA_SELECTOR` and `NO_PANEL_DRAG_ATTRIBUTE`; the peer floors in the README follow those releases.
|
|
289
372
|
|
|
290
373
|
### Fixed
|
|
291
374
|
|
|
292
|
-
- **The tree's reveal checks where the row landed**: bringing the open document's row into the tree's view (the shown document, and the `revealDocument` setting, in the tree and multi views) is finished only when the drawn row is measured wholly inside the tree's scroll window; until then it tries again once per frame, and a row already inside is never scrolled.
|
|
375
|
+
- **The tree's reveal checks where the row landed**: bringing the open document's row into the tree's view (the shown document, and the `revealDocument` setting, in the tree and multi views) is finished only when the drawn row is measured wholly inside the tree's scroll window; until then it tries again once per frame, and a row already inside is never scrolled.
|
|
376
|
+
It stops trying after 8 tries in a row that bring the row no nearer, and starts again when the rows or the tree's area change before the row has been seen inside; the reader's input in the tree, the next document and Collapse all still end it.
|
|
293
377
|
Before, a reveal ended as soon as the tree's `scrollToPath` answered `true`, which says only that the row is in the list, not where the scroll landed: with a source that lists every folder at once (all the folders down to the document open in one render), a host saw the document's row left about 13 rows below the window.
|
|
294
378
|
|
|
295
379
|
## 0.3.0 (2026-10-08)
|
|
@@ -356,7 +440,8 @@ The first release: a Markdown document explorer for React Router 8 framework mod
|
|
|
356
440
|
Each source declares a `boundary` (`contains`, pure and synchronous, and an optional storage `confirm` answering `{ inside: false }` or `{ inside: true, readPath }`): its tree and children list only paths inside it, a children request reaches `children(context, path, readPath)` only after the named source's `contains` and `confirm` passed, and a document reaches `document(context, path, readPath)` only when the boundary of at least one source admits it (documents carry no source; a path no source contains is `forbidden` without a host or storage call).
|
|
357
441
|
The tree refresh reloads the tree and answers it (200, the same body as a tree request); refreshes arriving while a walk runs share one trailing walk that begins after them, every tree carries `loadedAt` (when its walk began), sources and the document port receive `refresh: true` for a refresh and for the document requests it triggers (`X-Markdown-Explorer: refresh`), and `onTreeRefreshed(key)` with `forgetTree(key)` let a multi-process host drop the other processes' copies of a refreshed tree
|
|
358
442
|
(the hook may return a promise, which the response does not wait for; a throw or that promise's rejection is logged, as is the rejection of a promise a broken `contains` answers).
|
|
359
|
-
- **Client half**: `<MarkdownExplorer>` with per-instance stale-while-revalidate stores, streamed first paint, lazily loaded tree and multi-panel views (a single-view page never downloads them), `shouldRevalidateExplorer` for the page route, `clearExplorerStorage` for sign-out (also from the dependency-free entry `@aiquants/markdown-explorer/storage`, for sign-out handlers that run on every page), and `lockDocumentScroll`,
|
|
443
|
+
- **Client half**: `<MarkdownExplorer>` with per-instance stale-while-revalidate stores, streamed first paint, lazily loaded tree and multi-panel views (a single-view page never downloads them), `shouldRevalidateExplorer` for the page route, `clearExplorerStorage` for sign-out (also from the dependency-free entry `@aiquants/markdown-explorer/storage`, for sign-out handlers that run on every page), and `lockDocumentScroll`,
|
|
444
|
+
which logs one `console.error` per mount when the explorer ends below the viewport or collapses because its container has no definite block size (it measures only rendered parts, so a collapsed explorer panel, a closed sheet or an explorer the host hides is never reported as collapsed).
|
|
360
445
|
The URL codec in the browser reads the shared configuration joined with the page data's source ids (`withExplorerSources`), so the browser learns the server's runtime sources from the page and no source id is built into the client. `onMathDiagnostics(path, diagnostics)` hands a markdown document's KaTeX diagnostics (`MarkdownMathDiagnostic` of `@aiquants/markdown`) to the host once the document rendered, never to the reader's console, through one stable function (a host passing a new function on every render receives each document's diagnostics once).
|
|
361
446
|
The tree's **Refresh** (a visible label that is also its accessible name) shows the tree the server's refresh answers, never replacing a tree with one of an earlier `loadedAt` (a seed or background answer that lands meanwhile never discards the reader's refresh; only a later refresh or a reader switch does), and then reads the documents again with the refresh header (each cached document once: the shown ones at once — one still loading as soon as its request settles —, the others when next opened), whether or not the tree reloaded;
|
|
362
447
|
a reloaded tree is announced (`treeRefreshed`), a failed reload keeps the tree under an alert naming the failure (`treeRefreshFailed`, `markdown-explorer-refresh-failure`), and the other sources' trees are fetched again in the background when the reader switches to them.
|
|
@@ -380,8 +465,10 @@ The first release: a Markdown document explorer for React Router 8 framework mod
|
|
|
380
465
|
(the host duties name what a document can still reach: credentialed same-origin GET requests through its images, media and frames without the reader's interaction and through its links once followed, and what a state-changing GET must refuse: a speculative request (`Sec-Purpose`) and any destination but a document or a same-origin script's `fetch`); a reader switch seen in a data response reloads the page data once, without cancelling a loader that is running.
|
|
381
466
|
The scope is a pseudonym (an HMAC of the principal key under `scopeSecret`); the sanitizer runs in worker threads with limits on size, nesting (checked by the sanitizer's own parser, parse5, as it builds the tree: an element placed deeper than 512 levels, or more elements than the input has characters, stops the parse) and time and a byte-bounded cache of outcomes,
|
|
382
467
|
admits at most `jobsPerScope` documents per reader (by default `multiView.maxPanels` + max(1, `workers` − 1) + 3, never less than `maxPanels`) and `maxQueuedJobs` waiting in all (by default four times `jobsPerScope`, never less than `maxPanels`), never runs one reader on every worker when there are two or more and hands a free worker to the reader running the fewest,
|
|
383
|
-
runs each worker in a bounded heap (`workerHeapMb`, a document that exhausts it is `too-large`) and refuses a document whose elements, attributes and comments exceed a node budget derived from the heap and `maxHtmlBytes` (81,920 by default) or that holds more than 4,096 comments (bounding jsdom's quadratic time for comments placed before `<html>` or after `</html>`), refuses before parsing any tag of more than 1,024 attributes (and `html`/`body` collecting more through repeated tags), bounds the attribute characters the parser materializes, copies included, by `maxHtmlBytes`,
|
|
384
|
-
|
|
468
|
+
runs each worker in a bounded heap (`workerHeapMb`, a document that exhausts it is `too-large`) and refuses a document whose elements, attributes and comments exceed a node budget derived from the heap and `maxHtmlBytes` (81,920 by default) or that holds more than 4,096 comments (bounding jsdom's quadratic time for comments placed before `<html>` or after `</html>`), refuses before parsing any tag of more than 1,024 attributes (and `html`/`body` collecting more through repeated tags), bounds the attribute characters the parser materializes, copies included, by `maxHtmlBytes`,
|
|
469
|
+
never answers sanitized HTML longer than four characters per byte of `maxHtmlBytes`, keeps the first outcome remembered for an input, sends a document to a worker only after the worker reports ready (so a crash while sanitizing is always cached as that document's `failed`), and never caches the failure of a worker that could not start,
|
|
470
|
+
keeps `data-*` only for the renderer's link, image and footnote contract, removes `data:` URLs everywhere and reduces iframes' `allow` and `referrerpolicy` to safe values; deny rules decode leniently, match every decoding level both whole and split on `\` as well as `/` (a literal `my-credentials\backup.json` is denied like `*credentials*.json`) and cover more credential files by default, every name starting with `.env` (`.envelope.md` included), and the backups and variants of `*.env` files (`*.env.*`, `*.env~*`, `*.env-*`, `*.env_*`, `*.env#*`, documents such as `deploy.env.md` included);
|
|
471
|
+
the file-system source opens files without following links and checks they are the files it validated;
|
|
385
472
|
fixed-position markup stays inside the document pane.
|
|
386
473
|
The data route refuses a React Router single-fetch request (`<dataPath>/<operation>.data`) with a `not-found` failure before authenticating or calling a source, since React Router would answer it by reading the whole response and dropping every header but `Set-Cookie`.
|
|
387
474
|
A markdown document listing more than `EXPLORER_MAX_HEADINGS` (10,000, exported) headings is refused as `too-large`: every listed heading travels with the document (the data response, the browser's document cache and the table of contents), and a parser can list headings its HTML never renders.
|
|
@@ -389,7 +476,8 @@ The first release: a Markdown document explorer for React Router 8 framework mod
|
|
|
389
476
|
the parsed tree kept beside each takes roughly as much again), with at most one walk of a tree at a time per cache key and no tree answered past its time to live (counted from its walk's start: a request after it waits for one new walk); tree and children entries the contract cannot carry (an empty name, a path the browser cannot address) are left out with their subtrees and logged instead of failing the listing;
|
|
390
477
|
the exported types `ExplorerPageLoaderResult` (named through React Router's public `data()`), `ExplorerLogger`, `ExplorerLogDetail`, `ExplorerOperation`, `ExplorerPathRules`, `HtmlSanitizerOptions`, `FileSystemSkippedEntry` and `FileSystemSkipReason`.
|
|
391
478
|
`createFileSystemSource` gains `walkConcurrency` (default 8), `cacheScope` (default `"principal"`) and `reportSkipped`, and previews only files with a known text extension or name.
|
|
392
|
-
- **Reading**: documents opened again within 55 s are used as they are and older ones revalidated in the background; nothing is fetched while React renders, so a loader value that missed its deadline renders as loading on the server and is fetched by the browser; the work behind a late tree or document keeps running for another `deferredTimeoutMs`, so the browser's data request can join it, and its `signal` then aborts (late notices, never fetched again, at once), because the page request's own signal never aborts after its response has finished;
|
|
479
|
+
- **Reading**: documents opened again within 55 s are used as they are and older ones revalidated in the background; nothing is fetched while React renders, so a loader value that missed its deadline renders as loading on the server and is fetched by the browser; the work behind a late tree or document keeps running for another `deferredTimeoutMs`, so the browser's data request can join it, and its `signal` then aborts (late notices, never fetched again, at once), because the page request's own signal never aborts after its response has finished;
|
|
480
|
+
a revalidated tree or document stays on screen and is replaced only by a different value; the tree's Refresh reads documents again instead of dropping them (a shown document stays on screen and is replaced only when it changed); shown documents are never evicted from the cache; a pane never suspends after its first commit (the shown document stays with a progress line and `aria-busy`);
|
|
393
481
|
tree rows and document links the pointer or the focus rests on for 89 ms are prefetched one request at a time.
|
|
394
482
|
The default document styles and alignment are `@aiquants/markdown`'s own (`DEFAULT_MARKDOWN_STYLES`, `CONTENT_ALIGNS` and `DEFAULT_CONTENT_ALIGN`, read from its React-free `@aiquants/markdown/viewer-settings`, which the server half loads too), with no copy in the explorer.
|
|
395
483
|
The document viewer's table of contents makes the explorer's own jump to the heading (`onHeadingSelect`): a closed `details` around it opens, the scroll is instant, the focus moves to the heading so the next Tab continues in its section, and a page view pushes the heading's hash through the router (nothing when the URL already names it), while a panel keeps its URL;
|
|
@@ -403,12 +491,24 @@ The first release: a Markdown document explorer for React Router 8 framework mod
|
|
|
403
491
|
settled at once under a host's `scroll-behavior: smooth`, and nothing moved and moved back when an element no taller than the scrollport already starts a scroller without scroll padding; one taller than the scrollport is always moved past and back, so a scroll padding is honoured for it too), after opening a closed `details` and showing a `hidden="until-found"` ancestor around the element as the browser does (an element that still has no box does not move its pane's own scroller) — and in a panel the stage then shows the element with the panel's header by the least distance,
|
|
404
492
|
as it shows the first heading the focus moves to after a link followed in place, so neither stays above the stage's view; a fragment-only link or a table-of-contents entry in a panel opens the panel's document at that section in the tree view in a new tab or a copied address; reading positions are kept per panel and document; a plain wheel over a long panel scrolls the stage while it can move and the panel after that, and Ctrl/⌘ + wheel scrolls the panel; `data-aqmx-visible-columns` sits on the stage; the panel-limit notice is spoken by the announcer only,
|
|
405
493
|
and inside the open sheet it spans the header with its whole text wrapped around the close button, which stays above it (one line covers exactly the header's band; more lines spill over the top of the sheet's body for its three seconds), without changing the header's size, so no tree row moves while it is shown or when it goes and the focused row stays visible;
|
|
406
|
-
panels also move without a drag, with the four move buttons of each panel's header or Alt + Shift + arrow keys (both `@aiquants/drag-drop-panels`'), mapped back like a drop, announced by the layout in the explorer's words and with the focus kept on the control that held it, and a shortcut that cannot move the panel is announced instead of being swallowed; the header's buttons show while the panel is hovered or one of them is focused, and always on a device that cannot hover; touch and pen drag a panel by a long-press on its header outside its buttons,
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
494
|
+
panels also move without a drag, with the four move buttons of each panel's header or Alt + Shift + arrow keys (both `@aiquants/drag-drop-panels`'), mapped back like a drop, announced by the layout in the explorer's words and with the focus kept on the control that held it, and a shortcut that cannot move the panel is announced instead of being swallowed; the header's buttons show while the panel is hovered or one of them is focused, and always on a device that cannot hover; touch and pen drag a panel by a long-press on its header outside its buttons,
|
|
495
|
+
which `@aiquants/drag-drop-panels` runs itself (the stage wires nothing for touch) and reports through the same `onColumnPanelsChange` as the move buttons, so a touch drop is mapped back, written and announced like a move, and the lift and a cancel (`touchcancel`, Escape, leaving the layout, a release where nothing would move) are announced too, while a swipe on a header or a finger on a panel's body only scrolls; a change of the visible column count keeps an image's zoom and returns the focus to the same zoom button,
|
|
496
|
+
and focus on an element made focusable only temporarily (the heading a followed link focused) returns to that element; Zoom in and Zoom out keep the focus at the zoom limits; a panel's document links carry the router's basename in their `href`.
|
|
497
|
+
While a panel is maximized everything of the explorer it covers is inert (the explorer and its handle or the sheet's bar, the other panels, drag-drop-panels' list of hidden panels), so Tab never leaves it for a hidden control; the host's own chrome is the host's to keep uncovered (`--aqdd-maximize-*`, which the demo binds to its header) or make inert while a maximized panel's frame carries `data-aqmx-maximized="true"`; a restore that removes the focused element (the viewer's toolbar or table of contents) hands the focus to the panel's frame;
|
|
498
|
+
the panel-limit notice sits in the open sheet's header (over it, never in flow, and inside the modal dialog, so presses land on it) and otherwise in the top layer at the stage's corner, above a maximized panel, or in place in browsers without the Popover API (which no longer crash the explorer at the limit), and it ends early when the focus moves onto an element it is painted over (a control painted above it, such as the sheet's close button, keeps it, so closing the sheet with that button moves the notice to the stage's corner);
|
|
499
|
+
a panel opened or closed from the sheet is announced once the URL it wrote has rendered, so the root's region speaks it after the sheet closes, toggles the router renders as one navigation are all announced, and picking a hidden panel's document closes the sheet like any other pick.
|
|
500
|
+
- **Accessibility**: tree rows expose the selection through `aria-selected` (the shown document by default, the gathered documents in Multiple, the open panels in the multi-panel view) and the shown document through `aria-current="page"` (also while documents are gathered), and the tree has its own name (`treeRegion`); the tree is one Tab stop — the row last focused by the keyboard, a press or a script, else the shown document's row — which Tab reaches through `@aiquants/directory-tree`'s stand-in stop while that row is outside the render window,
|
|
501
|
+
and the shown document's row is brought into the tree's view on load and when a link changes the shown document, without moving the focus; a panel's document region is named after its document, and the panel frame, which receives the focus in the multi view's hand-offs, is a `group` named after its document; the header's links name the view they open ("Open in the tree view", "Open in the multi-panel view"); the document region is not focusable, so the keyboard scrolls the document clicked in; controls and tree rows are one control high (34 px, 44 px under a coarse pointer),
|
|
502
|
+
the resize handle is a 24 px band (44 px under a coarse pointer), and the header wraps instead of cutting a control off;
|
|
503
|
+
the failure callout offers "Try again" only for `failed` and a page reload for `unauthorized`;
|
|
504
|
+
Reload keeps the focus while the tree reloads (`aria-disabled` and `aria-busy`, never `disabled`), Expand all and Collapse all are `aria-disabled` while unavailable (Expand all also while a press runs, with `aria-busy`), Zoom out is `aria-disabled` while a fitted image with a natural size is already at or below the smallest zoom level (1/φ² ≈ 38.2 %), following the pane's size, an image without a natural size (an SVG whose root has no absolute `width` and `height`) zooms relative to its fitted size, so Zoom in and Zoom out both act from Fit and the level is a percentage of that size,
|
|
505
|
+
the zoom level is a polite status read when it changes,
|
|
506
|
+
removing or clearing gathered documents moves the focus to the next document or the tree instead of dropping it, and a failed folder's Try again moves the focus to the folder's row before the children load again; every failed load of a lazy folder's children (an expansion, a restored expansion, Expand all or a retry that fails again) is announced once through the announcer, naming the folder (`foldersLoadFailedNamed`; folders whose loads fail within one animation frame are named together in one sentence, in the place of the first), and Try again is described by the failure text;
|
|
507
|
+
the announcer speaks every message posted within one animation frame, in order, joined as separate sentences (`announcementSequence`), never only the last, and starts empty in a new reader's explorer; it speaks through the root's live region, and through a live region inside the sheet while the sheet is open (the modal sheet hides the root's region), without speaking a message twice when the sheet opens or closes; the zoom level (`output`) and failure callouts (`role="alert"`) are live regions of their own; a failed folder's row keeps Try again wholly visible,
|
|
508
|
+
its focus ring included (drawn inside the button), at any width, text size and language: the failure text gives way first, then the folder's name down to 3em, then Try again's text down to its icon, then the rest of the name, so in the sheet at 320 px with 200 % text, two levels deep, the icon and part of the name stay; a multi-view panel's header keeps its drag-mode toggle, Hide, Maximize and Close buttons inside the panel at a phone width with 200 % text, and its title readable: the buttons wrap below the title when the title would get less than 6em,
|
|
509
|
+
and the custom drag mode's badge stays beside the title instead of under the buttons;
|
|
510
|
+
one guard at the explorer's root ignores every repeated keydown of a held Enter inside the explorer — on the controls it renders and on those other packages render inside it (the tree's rows, the panel headers' buttons, the document viewer's toolbar and its popups, the controls inside a document) — except on controls that opt in with `data-aqmx-key-repeat="allow"` (Zoom in and Zoom out, which keep stepping), and those receive only the repeats of a press that began on them while the focus stays there (a followed link or a Try again that focuses an image's Zoom out does not step it),
|
|
511
|
+
so one press no longer runs on through the remove button, menu item, menu button, sheet control or tree row that receives the focus, and no toggle or popup flips once per repeat; a held Space toggles a tree row once;
|
|
412
512
|
under forced colors the shown, open and gathered rows, checked settings and open toggles are drawn in `Highlight`, focus rings (the resize handle's included) in `Highlight`, unavailable buttons in `GrayText`, and the loading cues that are otherwise only a background stay visible (the progress line in `Highlight`, every loading skeleton — the tree's, the multi stage's and a pane's — in `GrayText`);
|
|
413
513
|
when a followed link, a back or forward navigation, a successful Try again or a background revalidation that removes the focused element replaces the content that holds the focus, the focus moves into the replacement (its fragment's target, first heading, scroller or first control) instead of falling to the page, and a jump within the shown document (a section link in any view, a page view's link to the hash its URL already has included, or Back and Forward between two of its sections, entries the browser made itself included) moves the focus to the section without scrolling again,
|
|
414
514
|
also when the browser's own fragment navigation dropped it from the link to the page, so Tab and Shift+Tab continue from there, while focus the reader moved away from the document region — to an element or into a frame outside it, or to the page by pressing outside the region, also after the focus had already fallen to the page or while it was in a frame inside the region —
|
|
@@ -417,8 +517,12 @@ The first release: a Markdown document explorer for React Router 8 framework mod
|
|
|
417
517
|
and every element of a document keeps the focus ring's extent as its scroll margin, so an element a fragment or the focus brings to a scroller's edge shows its whole ring,
|
|
418
518
|
as do tree rows (their ring drawn inside the row) and the viewer's toolbar buttons (placed a ring's extent below the clipping edge), every ring reading `--aqmx-focus-ring-width` and `--aqmx-focus-ring-offset`; a link to HTML's top of the document (`#top` in any ASCII case with no element of that id, or the empty `#`) takes a page view or a panel back to the document's start without moving the focus;
|
|
419
519
|
focus inside a multi-view panel returns to the same element (else the panel's frame) when a change of the visible column count or a move to another column rebuilds the panel; switching views with the header's link or the tray's Open in panels keeps the focus in the explorer (on the new view's link — the sheet's toggle on a narrow frame — or the first panel opened), whether or not the browser fires `focusout` when it removes the focused control; the tree's arrow keys, Home and End keep the focused row in view;
|
|
420
|
-
the content stays mounted when the frame crosses the sheet threshold, and focus on the explorer's side moves to the sheet's toggle or back to the tree; the sheet closes only on a press that started on its backdrop, and picks made while gathering documents (Multiple selection) keep it open, so the tray fills without reopening the sheet for each document; the gathered documents and the tree settings (kept in memory, saved to browser storage when it can be written) survive the explorer's move into or out of the sheet (a phone rotated),
|
|
421
|
-
|
|
520
|
+
the content stays mounted when the frame crosses the sheet threshold, and focus on the explorer's side moves to the sheet's toggle or back to the tree; the sheet closes only on a press that started on its backdrop, and picks made while gathering documents (Multiple selection) keep it open, so the tray fills without reopening the sheet for each document; the gathered documents and the tree settings (kept in memory, saved to browser storage when it can be written) survive the explorer's move into or out of the sheet (a phone rotated),
|
|
521
|
+
a tree drawn after the page hydrated starts from the reader's settings instead of drawing the defaults once, and focus on a tree row returns to the same row, as the tree's only Tab stop, when the frame widens past the threshold, also after a round trip (split, sheet, split); the selection tray shrinks and scrolls before the tree, which keeps at least three rows at any text size (WCAG 1.4.4).
|
|
522
|
+
an Escape the explorer or the document viewer handles (closing the sheet, the tree settings menu, or the viewer's table of contents, style or alignment menu) is marked handled (`preventDefault()`), which drag-drop-panels honours — also in framework mode, where React's root listener sits on the document —, so in a maximized panel the first Escape closes the menu and keeps the panel maximized and the next one restores it; a document that fails — in every view, multi-view panels included — is announced through the announcer (`documentFailed(name, title)`, spoken from the sheet while it is open,
|
|
523
|
+
a panel's once the URL it wrote has rendered), once for each failed attempt (a Try again that fails again is announced again, while a document visited again or a panel opened again does not repeat the cached failure it shows until its new fetch settles, nor announces a cached failure no pane showed that opening it fetches again — a prefetch older than 55 s, or any failure after the tree's reload button), and its callout is no alert; a host's `renderTreeFailure` view replaces only the callout, inside the element that keeps the tree failure's hooks;
|
|
524
|
+
the panel chrome and the stage's spacing are bound to the explorer's tokens through drag-drop-panels' `--aqdd-*` properties, so the headers' icons (3:1), titles and custom drag mode's badge (4.5:1), the restore buttons of the bar of hidden panels (4.5:1, also hovered) and the drop placeholders of a drag (4.5:1 text, also on the target, and a 3:1 dashed border against the stage) follow `theme` rather than a page's `dark` class; a panel's header keeps its title at least 6em wide and wraps the badge and buttons below it instead, every button inside the panel; and the stage scrolls in a `div`,
|
|
525
|
+
adding no `main` landmark inside a host's own.
|
|
422
526
|
- **Host guidance**: [Document images](docs/behavior/url-contract.md#document-images) states how a parser emits images (a relative image's document path in `data-asset-src` and no `src`, which the explorer writes; a missing target marked with `data-asset-exists="false"` for the viewer's labelled placeholder; author-written marks stripped; and why a `src` left as written loads an explorer page);
|
|
423
527
|
the README lists every `!important` declaration a host cannot override, the forced-colors ones included, and the `--aqdd-*` properties the stage binds to the explorer's tokens;
|
|
424
528
|
the README and [Security](docs/behavior/security.md#what-the-host-must-do) require code run before the data route's functions, and every resource route of the host, to refuse React Router single-fetch requests (`.data`) before authenticating or reading; `isAcceptableDocumentPath` is exported from the server entry with `MAX_DOCUMENT_PATH_LENGTH`;
|
|
@@ -433,4 +537,6 @@ The first release: a Markdown document explorer for React Router 8 framework mod
|
|
|
433
537
|
The browser accepts the `url` of those documents only root-relative on the page's origin and in visible ASCII.
|
|
434
538
|
- **Files the explorer cannot show**: the `file` document kind shows, in every view, the file header over a note (the label `fileNotShown`) with a download link; a `text` document carries its file's `url` and shows the file header (Open in a new tab, Download) above its preview. `failureDocument` returns `ExplorerFailureDocument`, exported as a type.
|
|
435
539
|
`createFileSystemSource` requires `pathPrefix` (`""` for a source over the whole root), refuses unknown option keys, answers a file of an unknown extension (and a text file whose preview holds a NUL) as a `file` document, reports `version` (`<size>-<mtimeNs>`) for every kind but Markdown, and serves every regular file its checks admit through its `asset` port, so its deny rules are the only filter of what downloads; the port opens a file only while it keeps the device, inode, size and modification time the checks saw (`not-found` otherwise).
|
|
436
|
-
- **Localization**: English and Japanese catalogs with strict per-key overrides, including every control of the document viewer (`viewer…`: its toolbar, the table of contents, the style and alignment menus and each Mermaid diagram's controls, which carry no `lang` of their own), the tree's row kinds and scroll bar strings passed to `@aiquants/directory-tree` (`treeEntryKindDirectory`, `treeEntryKindFile`, `treeScrollUp`, `treeScrollDown`, `treeScrollToTop`, `treeScrollToBottom`), the tree's name (`treeRegion`), the failed-folders announcement (`foldersLoadFailedNamed`,
|
|
540
|
+
- **Localization**: English and Japanese catalogs with strict per-key overrides, including every control of the document viewer (`viewer…`: its toolbar, the table of contents, the style and alignment menus and each Mermaid diagram's controls, which carry no `lang` of their own), the tree's row kinds and scroll bar strings passed to `@aiquants/directory-tree` (`treeEntryKindDirectory`, `treeEntryKindFile`, `treeScrollUp`, `treeScrollDown`, `treeScrollToTop`, `treeScrollToBottom`), the tree's name (`treeRegion`), the failed-folders announcement (`foldersLoadFailedNamed`,
|
|
541
|
+
a list of names in the language's list format), the joining of messages announced together (`announcementSequence`), the hide and show announcements (`panelHidden`, `panelShown`), and every string the multi view's `@aiquants/drag-drop-panels` layout shows, which carry no `lang` of their own: the panel headers' buttons and badge (`panelHide`, `panelMaximize`, `panelRestore`, `panelClose`, `panelSwitchToCustomDrag`, `panelSwitchToNormalDrag`, `panelCustomDragBadge`, `panelMovePreviousColumn`, `panelMoveNextColumn`, `panelMoveUp`, `panelMoveDown`), the move announcements,
|
|
542
|
+
a touch or pen drag's lift and cancel announcements, the columns' region names (`panelMoved`, `panelMoveUnavailable`, `panelDragStarted`, `panelDragCancelled` and `multiColumnRegion`, templates whose `{name}` placeholders the layout fills, listed in `MARKDOWN_EXPLORER_LABEL_TEMPLATES` and checked when the labels are resolved), the bar of hidden panels and a hidden panel's stand-in (`hiddenPanelsTitle`, `hiddenPanelBadge`, `hiddenPanelNotice`), an empty column (`multiColumnEmpty`) and the drop placeholders (`panelDropHere`).
|
package/README.md
CHANGED
|
@@ -32,18 +32,19 @@ revision, and is asked before an unsaved draft is lost (see [Editing](#editing))
|
|
|
32
32
|
A single-view (embedding) page never downloads the tree and multi-panel views, which load on demand.
|
|
33
33
|
- **Embeds and link cards** — with `embeds` in the configuration, a link alone in a paragraph shows its post or video from up to ten providers (YouTube, X, Instagram, Threads, TikTok, Bluesky, LinkedIn, Reddit, note and niconico) in a cross-origin frame, with no provider script in the page, or a link card the explorer's own data route reads (`{dataPath}/link-card`, through `@aiquants/markdown`'s link-card handler: internal addresses never become cards); the link itself always stays, under the frame, as the card or as the paragraph.
|
|
34
34
|
- **Secure by default** — Markdown HTML is sanitized on the server with an allow-list (scripts, event handlers, `srcdoc` and foreign iframes never reach the browser), and the document viewer applies its own on every render (a document keeps only the converter's class tokens, and ids only on headings, footnotes and `user-content-…` targets); document paths are validated, and deny rules hide environment files, keys and version-control metadata through up to three percent-decoding levels; tokens, principals, server paths and raw error messages never leave the server.
|
|
35
|
-
- **Multi-panel reading** — open documents as panels, rearrange them by dragging (on a touch screen or with a pen, after a long-press on a panel's header), with the move
|
|
35
|
+
- **Multi-panel reading** — open documents as panels, rearrange them by dragging (on a touch screen or with a pen, after a long-press on a panel's header), with the move menu in each panel's header, or with Alt + Shift + arrow keys, hide, maximize (Escape restores), and navigate inside a panel; the arrangement survives reloads, and a document reopened later returns to its column.
|
|
36
36
|
- **Accessible and localized** — named landmarks and controls, a keyboard-operable tree with one Tab stop on the shown document, keyboard-operable menus, panel headers and resize handle, polite announcements (spoken from the sheet while it is open), WCAG 2.2 enhanced contrast (7:1 for text) in light and dark; English (default) and Japanese built in — the tree's and the panel headers' strings included —, every string overridable.
|
|
37
37
|
|
|
38
38
|
## Requirements
|
|
39
39
|
|
|
40
40
|
- React 19.2.7 or later and React Router 8 in framework mode (route modules with `loader` / `headers`).
|
|
41
41
|
- Node.js 22.22 or later (the floor React Router 8 declares). The package ships ES modules and CommonJS; the CommonJS entries load the ESM-only `react-router` through `require(esm)`.
|
|
42
|
-
- The peer packages, at these versions or later within the caret ranges the package declares: `@aiquants/markdown` ^
|
|
43
|
-
|
|
42
|
+
- The peer packages, at these versions or later within the caret ranges the package declares: `@aiquants/markdown` ^8.1.0 (document rendering; its components' stylesheet without utilities, its controls' 44 px targets under every pointer,
|
|
43
|
+
its Mermaid labels, its math diagnostics, gantt sizing, embeds, link cards and their sizes, the React-free `@aiquants/markdown/embeds` the sanitizer worker loads and `@aiquants/markdown/source-lines` the editor and the sanitizer read, and the Node-only link-card handler of `@aiquants/markdown/server`, which needs Node.js 22.13 or later — below the explorer's own floor),
|
|
44
|
+
`@aiquants/directory-tree` ^4.1.1 (reveals of rows under the scroll bar's buttons), `@aiquants/drag-drop-panels` ^0.12.0 (the panel headers' move menu, named by the explorer's `panelMove`, their 44 px buttons under every pointer and the header arrangement the behavior docs follow), `@aiquants/resize-panels` ^2.2.0 (the source of each layout change, by which the tree pane's width is saved) and `@aiquants/virtualscroll` ^3.20.0.
|
|
44
45
|
The client depends on these floors, while a package manager may only warn about an older peer.
|
|
45
46
|
- A Markdown parser of your choice on the server that produces HTML and its headings (the explorer sanitizes the HTML before it is sent).
|
|
46
|
-
- Browsers: the multi view's panel-limit notice
|
|
47
|
+
- Browsers: the multi view's panel-limit notice and the panel headers' move menu use the Popover API (Chrome and Edge 114, Firefox 125, Safari 17 and later). In browsers without it (for example iOS 16), the notice is drawn in place at the stage's corner instead of in the top layer (while the sheet is open it spans the sheet's header, as in every browser), and the move menu does not open: Alt + Shift + an arrow moves a panel there.
|
|
47
48
|
That notice wraps around the sheet's close button with a logical float (`float: inline-end`, Chrome and Edge 118 and later); in browsers without logical floats (before Chrome and Edge 118, the Chromium versions without the Popover API included) a long notice runs partly under the close button.
|
|
48
49
|
|
|
49
50
|
## Installation
|
|
@@ -198,7 +199,7 @@ import dragDropPanels from "@aiquants/drag-drop-panels/styles/drag-drop-panels.s
|
|
|
198
199
|
import virtualscroll from "@aiquants/virtualscroll/styles/virtualscroll.standalone.css?url"
|
|
199
200
|
import directoryTree from "@aiquants/directory-tree/styles/directory-tree.standalone.css?url"
|
|
200
201
|
import katex from "@aiquants/markdown/styles/katex.min.css?url"
|
|
201
|
-
import markdown from "@aiquants/markdown/styles/markdown.css?url"
|
|
202
|
+
import markdown from "@aiquants/markdown/styles/markdown.standalone.css?url"
|
|
202
203
|
import githubMarkdown from "@aiquants/markdown/styles/github-markdown.css?url"
|
|
203
204
|
import zennContent from "@aiquants/markdown/styles/zenn-content.css?url"
|
|
204
205
|
import message from "@aiquants/markdown/styles/message.css?url"
|
|
@@ -232,23 +233,38 @@ body {
|
|
|
232
233
|
```
|
|
233
234
|
|
|
234
235
|
- `html` and `body` take the viewport's height (React Router's default root renders the page straight into `body`; give any element your own root puts between them `height: 100%` as well), and `margin: 0` keeps the page from ending below the viewport. The page is a flex column of that height, and the explorer's wrapper takes what the header leaves (`flex: 1`) and may be shorter than its content (`min-height: 0`).
|
|
235
|
-
- The `.standalone.css` builds suit hosts without Tailwind CSS. A Tailwind host loads the plain builds (`resize-panels.css`, `@aiquants/drag-drop-panels/css`, `virtualscroll.css`, `directory-tree.css`) and lets Tailwind scan the peers' `dist` with `@source`.
|
|
236
|
+
- The `.standalone.css` builds, `@aiquants/markdown/styles/markdown.standalone.css` among them, suit hosts without Tailwind CSS (or with Tailwind v3). A Tailwind v4 host loads the plain builds (`resize-panels.css`, `@aiquants/drag-drop-panels/css`, `virtualscroll.css`, `directory-tree.css`) and lets Tailwind scan the peers' `dist` with `@source`.
|
|
237
|
+
For `@aiquants/markdown` it links no components sheet (the document styles below are still linked): its Tailwind entry imports `markdown.css` without `layer()` (the sheet's link and link-card rules and the diagram's focus ring must stay outside every cascade layer), scans the package's build output so that its own build generates the utilities the document viewer uses (the path of `@source` is relative to the CSS file that declares it), and declares the `dark` variant those utilities follow.
|
|
238
|
+
Without a declaration Tailwind's `dark` is the `prefers-color-scheme` media query; declare the one that matches how your page signals dark mode. The one below is the standalone sheet's: a `.dark` ancestor, or the `[data-theme="dark"]` the viewer sets from its `theme`:
|
|
239
|
+
|
|
240
|
+
```css
|
|
241
|
+
/* app/app.css of a Tailwind v4 host */
|
|
242
|
+
@import "tailwindcss";
|
|
243
|
+
@import "@aiquants/markdown/styles/markdown.css";
|
|
244
|
+
@source "../node_modules/@aiquants/markdown/dist/**/*.js";
|
|
245
|
+
@custom-variant dark (&:where(.dark, .dark *, [data-theme="dark"], [data-theme="dark"] *));
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
Never load both `markdown.css` and `markdown.standalone.css`, nor `markdown.standalone.css` beside a Tailwind v4 build of the host: the standalone sheet's utilities would meet the host's own in the same cascade layer.
|
|
236
249
|
- A Tailwind host must fix the cascade-layer order before any package stylesheet names a layer: load its own stylesheet (whose `@import "tailwindcss"` declares `theme, base, components, utilities`) first, or `@import` the package stylesheets from it after `@import "tailwindcss"`. Otherwise the first package sheet puts `components` before `base`, and Tailwind's preflight resets the explorer's (and the peers') spacing and borders.
|
|
237
250
|
`markdown-explorer.css` itself declares `theme`, `base` and `components` in that order before any rule, which fixes the order whenever it is the first sheet to name a layer.
|
|
238
251
|
- `github-markdown.css` and `zenn-content.css` back the default document styles, and `github-markdown.css`
|
|
239
252
|
also draws GitHub alerts (`.markdown-alert`); `message.css` and `details.css` draw Zenn's message and
|
|
240
253
|
details containers (`aside.message`, `details.markdown-details`) under every document style; load these
|
|
241
|
-
two when your converter writes that markup (see [Documents](#documents)).
|
|
242
|
-
|
|
254
|
+
two when your converter writes that markup (see [Documents](#documents)). The `@aiquants/markdown` sheet
|
|
255
|
+
(`markdown.standalone.css`, or `markdown.css` in a Tailwind v4 host's build) also gives GitHub alerts a baseline
|
|
256
|
+
under the other document styles (None, Zenn).
|
|
243
257
|
`@aiquants/markdown/styles/katex.min.css` is KaTeX's own stylesheet, shipped with the fonts it points
|
|
244
258
|
to; load it when your documents contain math.
|
|
245
259
|
- Every explorer rule sits in `@layer components`, so your own unlayered rules (or a Tailwind host's utilities) override it — except a few declarations that are `!important` inside the layer, which no unlayered rule of yours can override:
|
|
246
260
|
the document viewer's transparent body background (so the region's `--aqmx-surface` shows through), the outward focus-ring offset of a document's links inside superscripts and subscripts (footnote references:
|
|
247
261
|
`github-markdown.css`, whose `.markdown-body` the viewer puts around the content of every document style, draws a link's ring 2 px inside its box, which on a footnote reference's one-glyph box paints over the glyph), the zero transitions of the resize handle and of the tree (whose fade `@aiquants/directory-tree` sets on the tree's root element) under `prefers-reduced-motion: reduce`, and, under forced colors, the resize handle's focus ring and the text and icon colour inside highlighted tree rows and checked tree settings.
|
|
248
262
|
This is the complete list. Change the rings through the `--aqmx-*` tokens they read (`--aqmx-focus-ring-width`, `--aqmx-focus-ring-offset`); the transitions and the forced-colors system colours read no token.
|
|
249
|
-
- The multi-panel view styles `@aiquants/drag-drop-panels`' chrome only through that package's neutral custom properties, bound with ordinary declarations on the stage to the explorer's tokens: the stage's block and inline padding and the column gap to `--aqmx-space-7` and `--aqmx-space-6`; the panels' surface and border (and those of the bar of hidden panels, an empty column and a hidden panel's stand-in during a drag) to `--aqmx-surface` and `--aqmx-border`; the panel titles (and the text of those parts) to `--aqmx-text`; the header buttons' icons to `--aqmx-text-muted`,
|
|
263
|
+
- The multi-panel view styles `@aiquants/drag-drop-panels`' chrome only through that package's neutral custom properties, bound with ordinary declarations on the stage to the explorer's tokens: the stage's block and inline padding and the column gap to `--aqmx-space-7` and `--aqmx-space-6`; the panels' surface and border (and those of the bar of hidden panels, an empty column and a hidden panel's stand-in during a drag) to `--aqmx-surface` and `--aqmx-border`; the panel titles (and the text of those parts) to `--aqmx-text`; the header buttons' icons to `--aqmx-text-muted`,
|
|
264
|
+
and on hover to `--aqmx-text` over `--aqmx-surface-sunken`; the custom drag mode's badge (and the pressed drag-mode toggle) to `--aqmx-warning-text` on `--aqmx-warning-surface`; the restore buttons of the bar of hidden panels to `--aqmx-surface` on `--aqmx-accent` (`--aqmx-info-text` while hovered); and the drop placeholders of a drag (text, icon and dashed border) to `--aqmx-accent` on `--aqmx-surface`, the placeholder a drop would land on to `--aqmx-accent-surface`.
|
|
250
265
|
So the panel chrome follows the explorer's `theme`, not a `dark` class of the page, and you restyle it by changing those tokens on the explorer (or by setting an `--aqdd-*` property yourself on an element inside the stage).
|
|
251
|
-
- A maximized multi-view panel covers the viewport inside `--aqdd-maximize-top`, `--aqdd-maximize-right`, `--aqdd-maximize-bottom` and `--aqdd-maximize-left` (all `0px` by default); bind them in your layout to keep your own header or menu visible. Everything of the explorer it covers (the explorer and its handle or the sheet's bar, and the other panels) is inert until the panel is restored.
|
|
266
|
+
- A maximized multi-view panel covers the viewport inside `--aqdd-maximize-top`, `--aqdd-maximize-right`, `--aqdd-maximize-bottom` and `--aqdd-maximize-left` (all `0px` by default); bind them in your layout to keep your own header or menu visible. Everything of the explorer it covers (the explorer and its handle or the sheet's bar, and the other panels) is inert until the panel is restored.
|
|
267
|
+
Your own chrome is not: whatever of it the panel covers stays in the Tab order and in the accessibility tree, so either bind the variables so the panel leaves it uncovered, or make it inert (or `visibility: hidden`) while a panel is maximized — the maximized panel's frame carries `data-aqmx-maximized="true"` (`:has([data-aqmx-panel-frame][data-aqmx-maximized="true"])`), and the URL carries `maximized`.
|
|
252
268
|
- The tree and single views' document bar touches the page's top inline-end corner, where a host may float a control of its own (a menu switch). The bar keeps `--aqmx-page-bar-inset-inline-end` (`0px` by default) free at the end of its button row, beside the focus ring's room, so its last button (Edit while a document is edited, Refresh document otherwise) never sits under that control. The explorer leaves the property undeclared, so a value set on `:root` (or any ancestor of the explorer) reaches the bar.
|
|
253
269
|
|
|
254
270
|
## Views and URLs
|
|
@@ -397,8 +413,9 @@ Every other link with an `href` reaches the explorer's link component with its `
|
|
|
397
413
|
The viewer keeps only its own class tokens and fragment targets of your HTML, whatever the sanitizer kept (see [Security](docs/behavior/security.md#the-viewers-allow-list)): a class token survives when it belongs to the markup below, to footnotes (`footnotes`, `footnote-ref`, `footnote-backref`), to formulas (`math`, `inline`, `display`) or to a code block's language (`language-*`),
|
|
398
414
|
and an `id` on a heading, on a footnote (`fnref:N` or `fnrefK:N` on a reference's `sup`, `fn:N` on a note's `li`, as goldmark writes them) or in the `user-content-` namespace (remark-gfm's footnote ids, which sit on the reference's link and the note). Write any other fragment target as a heading, a `user-content-…` id or `<a name>`.
|
|
399
415
|
So a footnote reference keeps its id, the target of its back-reference, and its `aria-describedby`, and a back-reference keeps its `aria-label`, in either markup. A formula is `<span class="math inline">\(…\)</span>`, or `<p><span class="math display">\[…\]</span></p>` for display math, which the viewer sets apart by the `display` token (a formula without it is typeset inline). A task list's `contains-task-list` and `task-list-item` classes are dropped, so its items keep their list markers.
|
|
400
|
-
Converters may also write GitHub alerts and Zenn's message and details containers; the sanitizer and the viewer keep their markup as written. An alert is `div.markdown-alert.markdown-alert-{type}` (`note`, `tip`, `important`, `warning` or `caution`) whose first child is `p.markdown-alert-title`, holding the type's Octicon as an inline `svg` (its `class`, `viewBox`, `version`, `width`, `height` and `aria-hidden`, and the `d` of its `path`) and then the title.
|
|
401
|
-
|
|
416
|
+
Converters may also write GitHub alerts and Zenn's message and details containers; the sanitizer and the viewer keep their markup as written. An alert is `div.markdown-alert.markdown-alert-{type}` (`note`, `tip`, `important`, `warning` or `caution`) whose first child is `p.markdown-alert-title`, holding the type's Octicon as an inline `svg` (its `class`, `viewBox`, `version`, `width`, `height` and `aria-hidden`, and the `d` of its `path`) and then the title.
|
|
417
|
+
A message is `aside.message` (with `alert`, `info` or `warning` added for those types) holding `span.message-symbol` (`aria-hidden="true"`) and `div.message-content`; a details is `details.markdown-details` holding its `summary` and `div.markdown-details-content`.
|
|
418
|
+
`github-markdown.css` draws the alerts under the GitHub document style and the `@aiquants/markdown` sheet (`markdown.standalone.css`, or `markdown.css` in a Tailwind v4 host's build) gives them a baseline under the others, and `message.css` and `details.css` draw the containers (see [Load the styles](#5-load-the-styles)). The demo's parser writes all three, and footnotes, task lists and formulas as the Go converter of `@aiquants/markdown` (goldmark) does.
|
|
402
419
|
Your parser resolves each link and each image; the rules are in [Document links](docs/behavior/url-contract.md#document-links) and [Document images](docs/behavior/url-contract.md#document-images) (a relative image carries its target's document path in `data-asset-src` and no `src`, and the explorer's sanitizer writes the `src`, the explorer's own asset URL;
|
|
403
420
|
a missing target gets `data-asset-exists="false"`, which the viewer shows as a labelled placeholder; a relative `src` left as written would resolve against the page URL and load an explorer page instead), and the demo's parser (`demo/app/markdown.server.ts` in the source repository) is a complete example.
|
|
404
421
|
The deny rules are checked on the document's path only: a parser that expands include directives (such as `<!-- @import "…" -->`) must apply them to every file it reads, or leave such directives unexpanded (`@aiquants/markdown`'s `parseMarkdown` leaves them unexpanded unless `resolveImports` is set, and applies the `deniedPathSegments` you give it, the explorer's rules, to every import, image and link target). The explorer serves the files of documents and embedded images itself (see [Serving files](#serving-files)).
|
|
@@ -638,7 +655,8 @@ Spread it into the configuration when your application has no sign-in: it provid
|
|
|
638
655
|
A canonical redirect keeps the fragment on a page load (the browser carries it across the loader's HTTP redirect) and on the explorer's own client-side replace (it appends the fragment), so loading `/docs#%E6%A6%82%E8%A6%81` ends on the tree view's URL with the same fragment.
|
|
639
656
|
A client-side navigation from another of your routes to a non-canonical URL loses its fragment, because React Router builds the redirected location from the loader's `Location` alone: link to the canonical URL that `explorerHref` writes, with the fragment appended. A multi-view URL ignores the hash: a panel's fragment-only link scrolls the panel instead.
|
|
640
657
|
- In a page view the explorer brings a fragment's element to the start of the pane's own scroller and moves every scroller around it only as far as needed (see [The document region](docs/behavior/layout.md#the-document-region)). Two scrolls it does not own can do more:
|
|
641
|
-
React Router's `<ScrollRestoration>` scrolls the element whose id is the URL's hash into view itself — page-wide, aligned to the start of every scroller, the page and your own scroll containers included — on a router navigation that carries a hash to a location it has saved no window offset for (a new history entry: it keys the offsets it saves by the location's key, or by your `getKey`), whenever that element is already in the page (a link to a section of the shown document, or an entry of the document viewer's table of contents, which the explorer follows as such a link).
|
|
658
|
+
React Router's `<ScrollRestoration>` scrolls the element whose id is the URL's hash into view itself — page-wide, aligned to the start of every scroller, the page and your own scroll containers included — on a router navigation that carries a hash to a location it has saved no window offset for (a new history entry: it keys the offsets it saves by the location's key, or by your `getKey`), whenever that element is already in the page (a link to a section of the shown document, or an entry of the document viewer's table of contents, which the explorer follows as such a link).
|
|
659
|
+
On Back or Forward to an entry it saved an offset for, it restores the window's offset instead, as it does for every entry the browser made itself (a fragment-only link) once it has left one, since React Router gives all of those the key `default`. The browser scrolls to the element itself for a fragment-only link and for the hash of a page it loads, and for a link to `#top` or `#` that names no element it scrolls the page itself to its top (HTML's top of the document is the viewport's).
|
|
642
660
|
They move nothing while the explorer fills a container that does not scroll (with `lockDocumentScroll`, for example); in a page that scrolls around a page view, leave `<ScrollRestoration>` off the explorer's routes if your scrollers must not move.
|
|
643
661
|
- For crawlers, render with `onAllReady` and `progressiveChunkSize: Number.POSITIVE_INFINITY`: even after every boundary is ready, React writes a boundary larger than 12.8 KB as a hidden segment that a script reveals, so a crawler that runs no script would see only the loading state.
|
|
644
662
|
- The explorer does not set the page title. React Router runs `meta` again on every navigation with the new `params` and `location`, but the loader data it receives stays that of the first paint (`shouldRevalidateExplorer` keeps the loader from running), so derive the title from `resolveExplorerLocation(withExplorerSources(config, sourceIds), params["*"], new URLSearchParams(location.search))` rather than from the loader data's documents (`sourceIds` from the loader data's `sources`, which a navigation does not change).
|
|
@@ -664,7 +682,8 @@ Spread it into the configuration when your application has no sign-in: it provid
|
|
|
664
682
|
|
|
665
683
|
The explorer fills its container's block size, so the container needs a definite block size: for example `height: 100dvh`, or a flex column of definite height whose item has `flex: 1` and `min-height: 0`. The quick start's `app.css` is such a container.
|
|
666
684
|
A container whose block size is auto or only a minimum (`html` and `body` at their default auto height included) does not size the explorer: the areas that fill the leftover height collapse to 0 px, or the explorer grows with its content.
|
|
667
|
-
With `lockDocumentScroll` the explorer must fill a container of definite block size inside the viewport; while the page is locked it logs one `console.error` per mount when the explorer ends below the viewport or a rendered part collapses (its root, the document region of the tree or single view, or the explorer's tree area is less than 1 px tall).
|
|
685
|
+
With `lockDocumentScroll` the explorer must fill a container of definite block size inside the viewport; while the page is locked it logs one `console.error` per mount when, once the layout has settled (no resize of the explorer's root or the window for one second), the explorer ends below the viewport or a rendered part collapses (its root, the document region of the tree or single view, or the explorer's tree area is less than 1 px tall). The intermediate viewports a resize can pass through — switching Chrome DevTools' device toolbar between a desktop and a phone size does — are not judged.
|
|
686
|
+
Hidden parts — a closed sheet, a collapsed explorer panel, an explorer the host hides — are not checked.
|
|
668
687
|
|
|
669
688
|
#### Tree settings
|
|
670
689
|
|
|
@@ -676,7 +695,8 @@ README: Mixed (the package default) keeps a folder's READMEs in the sort; First
|
|
|
676
695
|
Reveal the open document: see [Revealing the open document](#revealing-the-open-document). Selection: Single (the package default) selects the shown document or folder; Multiple gathers clicked documents in a tray that opens them as panels; Off shows no row as selected, not even the shown document.
|
|
677
696
|
The tray shrinks and scrolls before the tree does: the tree keeps at least three rows at any text size, the tray keeps its header row and scrolls the rest, and an explorer too short for both scrolls as a whole. Always expanded shows every folder whose contents are known as expanded; a lazy folder stays collapsed until the reader opens it, so the setting never loads folders by itself.
|
|
678
697
|
|
|
679
|
-
Call `clearExplorerStorage(storageNamespace)` when a reader signs out of a shared browser (it throws a `RangeError` for a malformed namespace instead of clearing the wrong keys). Import it from `@aiquants/markdown-explorer/storage`: that entry imports nothing (no React, no `@aiquants/markdown`), so a layout or root route that runs on every page can call it without loading the explorer; the root entry exports the same function.
|
|
698
|
+
Call `clearExplorerStorage(storageNamespace)` when a reader signs out of a shared browser (it throws a `RangeError` for a malformed namespace instead of clearing the wrong keys). Import it from `@aiquants/markdown-explorer/storage`: that entry imports nothing (no React, no `@aiquants/markdown`), so a layout or root route that runs on every page can call it without loading the explorer; the root entry exports the same function.
|
|
699
|
+
The explorer also clears the namespace by itself: on every page load, before anything reads it, when the reader recorded there is not the page's reader, and when a data response reports a different reader.
|
|
680
700
|
|
|
681
701
|
#### Expand all and Collapse all
|
|
682
702
|
|
|
@@ -760,11 +780,14 @@ export const draftConverter: ExplorerDraftConverter = {
|
|
|
760
780
|
}
|
|
761
781
|
```
|
|
762
782
|
|
|
763
|
-
- **The contract.** `convert(draft, signal)` receives the document's path as the explorer names it and the draft's text, and resolves to `{ kind: "preview", htmlContent, headings }` (unsanitized, without existence marks), a failure document (shown over the last rendering, as a failed preview is; more than `EXPLORER_MAX_HEADINGS` headings is `too-large`, as on the server), or `{ kind: "unavailable" }` when the converter cannot run, for which the server renders that draft. It rejects only with the signal's reason once the signal aborted.
|
|
783
|
+
- **The contract.** `convert(draft, signal)` receives the document's path as the explorer names it and the draft's text, and resolves to `{ kind: "preview", htmlContent, headings }` (unsanitized, without existence marks), a failure document (shown over the last rendering, as a failed preview is; more than `EXPLORER_MAX_HEADINGS` headings is `too-large`, as on the server), or `{ kind: "unavailable" }` when the converter cannot run, for which the server renders that draft. It rejects only with the signal's reason once the signal aborted.
|
|
784
|
+
Any other rejection, or an answer outside the contract, is a bug: the explorer reports it once on the console and treats it as `unavailable`.
|
|
764
785
|
- **Loading ahead.** `prepare()`, when given, is called when the reader is about to see the preview — they point at or focus Edit while the preview shows side by side and fits the pane, or point at or focus the view switch's Preview — so the worker and its WebAssembly (about 0.4 s to start in Chromium) load before the first draft. The explorer may call it many times: return at once and do the work once.
|
|
765
786
|
- **One draft at a time.** The explorer converts the first draft at once; a draft that arrives while another converts waits, and only the latest waiting draft is converted next (a WebAssembly call cannot be interrupted, so the running one is never aborted). It aborts the signal only when the preview goes away. A rendering is shown without `aria-busy`, through a React transition, so typing goes ahead of it.
|
|
766
787
|
- **The server's rules.** Each rendering is sanitized in the browser with the allow-list rules the server applies to every document (the same module, on a DOMPurify instance of the preview's own from `isomorphic-dompurify`'s browser build, part of the editing chunk), so the instant preview shows what the saved document will.
|
|
767
|
-
- **Which targets exist.** Only the server can tell whether an image or a linked document exists. The preview keeps a table of the marks the server answered (`data-asset-exists`, `data-doc-exists`, or none), seeded from the document's own rendering, and writes the known ones onto every rendering.
|
|
788
|
+
- **Which targets exist.** Only the server can tell whether an image or a linked document exists. The preview keeps a table of the marks the server answered (`data-asset-exists`, `data-doc-exists`, or none), seeded from the document's own rendering, and writes the known ones onto every rendering.
|
|
789
|
+
When a rendering names a target the table does not hold, the preview asks the data route's `preview` operation about the newest draft once the reader has paused for VERIFY_DELAY_MS (987 ms), one request at a time, learns the marks of the answer, remembers every asked target the answer left unmarked (or a failed answer did not reach) as having none, and renders the newest draft again.
|
|
790
|
+
So the server is asked about a target once, and a draft that adds no new image or link causes no request at all; a missing image the reader just added shows as a broken image until the answer lands, then as the viewer's missing-image placeholder.
|
|
768
791
|
- **The server tier.** Without a converter, and for a draft the converter answers `unavailable` (its WebAssembly could not load, for example), the server renders the draft once the reader has paused for SERVER_PREVIEW_DELAY_MS (610 ms); the last rendering stays on screen marked `aria-busy` meanwhile, and a newer draft aborts the request. The preview names the tier of what it shows in `data-aqmx-preview-tier` (`instant` or `server`).
|
|
769
792
|
- **Content Security Policy.** A page that sets `script-src` needs `'wasm-unsafe-eval'` in it for the WebAssembly, and `worker-src 'self'` (or a `script-src` covering the worker) for the same-origin worker.
|
|
770
793
|
|
|
@@ -788,7 +811,7 @@ The labels the layout fills with a value are templates with `{name}` placeholder
|
|
|
788
811
|
| Dialogs | centered over the visible part of the content pane, at least 21 px (`--aqmx-space-7`) from every edge of the viewport |
|
|
789
812
|
| Multi-view column minimum | 40ch at 1rem (the multi-column reading measure) |
|
|
790
813
|
| Multi-view panel height | between the stage height / φ³ and the stage height / φ, except that the panel's scroll area always keeps three lines of 1rem × φ text below the panel's header (where the header wraps that far, the panel is the header plus that floor) |
|
|
791
|
-
| Spacing, controls, durations | Fibonacci numbers (px written in rem; ms), except the pointer targets: 44 px (2.75rem) for every control under
|
|
814
|
+
| Spacing, controls, durations | Fibonacci numbers (px written in rem; ms), except the pointer targets: 44 px (2.75rem, `--aqmx-control`) for every control under every pointer (WCAG 2.2 enhanced target size), and the resize handle's 24 px under a fine pointer |
|
|
792
815
|
| Text sizes | 13, 16 and 21 px (0.8125, 1 and 1.3125rem) for body text, titles and display text; under a coarse pointer the body text is 16 px (1rem) as well; tree rows are in the body size |
|
|
793
816
|
|
|
794
817
|
The reader's own explorer width is remembered per view as a percentage, and only after the reader moves the handle: a drag that moved it (once, when it ends) or an arrow key that moved it, never a press that moved nothing or a change of the window. The editor's share beside the preview is remembered the same way. The document's column fills its pane; the viewer's alignment control appears only for a column a single-view embed narrows (`?width=` / `?maxWidth=`). See [Layout](docs/behavior/layout.md).
|
|
@@ -823,7 +846,8 @@ Every scroller of the explorer that the reader browses gets one pointer scroll b
|
|
|
823
846
|
- File bytes are served only by the explorer's `asset` operation, after the deny rules and the document admission, inline only for raster images, audio, video and PDF, always with `nosniff` and a `same-origin` resource policy, and with a sandboxing policy except for PDF, under which inline audio and video keep the URL's origin (`allow-same-origin`, no `allow-scripts`) (see [Serving files](#serving-files)).
|
|
824
847
|
- A Markdown document's source (the Source toggle) is read only by the explorer's `text` operation, through the same `asset` port after the same deny rules and admission, so it serves nothing the reader could not already download: at most `textMaxBytes` of the file's beginning, decoded as UTF-8 into JSON, which the browser shows as text and never interprets.
|
|
825
848
|
- Data responses are `private, no-store` JSON with `nosniff`, a sandboxing content security policy and `same-origin` resource policy, and the data route refuses React Router's single-fetch requests (`.data`), whose answers would carry none of those headers; the tree refresh, and a document request marked as triggered by a refresh (`X-Markdown-Explorer: refresh`, which makes the host skip its caches), require the custom request header and pass the shared cross-origin check of server routes (`@aiquants/request-isolation`).
|
|
826
|
-
- Editing writes only through the host's `edit` ports, after the deny rules and the same admission as a document. A save and a preview need the custom header `X-Markdown-Explorer: edit` and pass the shared cross-origin check, and their draft is read and checked (media type, `editMaxBytes`, UTF-8 without NUL) before any port is called; a grant's `href` must be root-relative and an external editor's `https:`; the preview is sanitized exactly as a document.
|
|
849
|
+
- Editing writes only through the host's `edit` ports, after the deny rules and the same admission as a document. A save and a preview need the custom header `X-Markdown-Explorer: edit` and pass the shared cross-origin check, and their draft is read and checked (media type, `editMaxBytes`, UTF-8 without NUL) before any port is called; a grant's `href` must be root-relative and an external editor's `https:`; the preview is sanitized exactly as a document.
|
|
850
|
+
A draft the host's browser converter renders (`draftConverter`) is sanitized in the browser with the same allow-list rules before it is shown, and never leaves the browser; only the existence marks come from the server's answers. The host checks in every port that the reader may edit the document, and writes only over the version the draft started from.
|
|
827
851
|
- Link cards are read by `@aiquants/markdown`'s handler behind a read-only authentication (no token refresh, no `Set-Cookie`; an authentication that carries headers is refused and logged), and its guards keep every internal address from becoming a card; see [Link cards](#link-cards).
|
|
828
852
|
- Each data response carries an opaque, pseudonymous scope (an HMAC of the principal key under `scopeSecret`); when it changes, the browser drops every cache and remembered path. Browser storage is also checked against the page's scope on every page load, before anything reads it.
|
|
829
853
|
|
|
@@ -838,10 +862,12 @@ Tests and host styling may rely on the `data-testid` and `data-aqmx-*` attribute
|
|
|
838
862
|
- One explorer per page: the drag-and-drop layout looks up its panels document-wide.
|
|
839
863
|
- Merges are line-based (node-diff3): changes on adjacent lines, or on the same line, conflict even when they would combine. A panel that is not maximized shows the editor or the preview, never both; maximize it to see them side by side.
|
|
840
864
|
- The browser applies the server sanitizer's allow-list rules and nesting limit (512 levels, which Chromium's own parser never exceeds), but not its other resource limits (parsed nodes, attributes, worker heap, time): the host's converter bounds a draft's HTML with `maxHtmlBytes` instead. The existence marks of a target the reader just added arrive about a second after they pause, so until then a new image that does not exist shows as a broken image, and a new link to a missing document as an ordinary link.
|
|
841
|
-
- A held Enter acts once on every control inside the explorer, those of other packages included (the tree's rows, the panel headers' buttons, the document viewer's toolbar and the controls inside a document), except Zoom in and Zoom out, which keep stepping while a press that began on them is held (see [Held keys](docs/behavior/layout.md#held-keys)): a press that hands the focus to them, such as following a link to an image, does not step them.
|
|
865
|
+
- A held Enter acts once on every control inside the explorer, those of other packages included (the tree's rows, the panel headers' buttons, the document viewer's toolbar and the controls inside a document), except Zoom in and Zoom out, which keep stepping while a press that began on them is held (see [Held keys](docs/behavior/layout.md#held-keys)): a press that hands the focus to them, such as following a link to an image, does not step them.
|
|
866
|
+
The repeated keydowns end at the explorer's root, so a keydown listener the host attaches outside the explorer for the bubbling phase does not receive them either.
|
|
842
867
|
- A loop row (a folder met again among its own ancestors) shows an expand glyph and `aria-expanded="false"` like any closed folder, because `@aiquants/directory-tree` has no row that cannot expand; it never opens. The 4 listings in flight are counted per explorer, not across browser tabs.
|
|
843
868
|
- Document kinds are the five above; `createFileSystemSource` previews only files with a known text extension or name as text and offers any other file as a `file` document (a download).
|
|
844
|
-
- HTML larger than `sanitizer.maxHtmlBytes` (4 MiB), placed deeper than 512 levels while it is parsed, making the parser create more elements than it has characters, more nodes than the worker's heap holds (81,920 elements, attributes and comments by default) or more than 4,096 comments, holding a tag with more than 1,024 attributes (counted before parsing for every `<` or `</` followed by a letter, so text in a script, a comment or an attribute value that looks like such a tag counts too), giving `html` or `body` more than 1,024 attributes through repeated tags,
|
|
869
|
+
- HTML larger than `sanitizer.maxHtmlBytes` (4 MiB), placed deeper than 512 levels while it is parsed, making the parser create more elements than it has characters, more nodes than the worker's heap holds (81,920 elements, attributes and comments by default) or more than 4,096 comments, holding a tag with more than 1,024 attributes (counted before parsing for every `<` or `</` followed by a letter, so text in a script, a comment or an attribute value that looks like such a tag counts too), giving `html` or `body` more than 1,024 attributes through repeated tags,
|
|
870
|
+
carrying attributes whose characters, counting every copy of a reopened formatting element, exceed `maxHtmlBytes`, sanitizing to HTML longer than four characters per byte of `maxHtmlBytes`, or not sanitized within `sanitizer.deadlineMs` (30 s) shows as `too-large`.
|
|
845
871
|
- All anonymous readers share one scope, so they share the admission budget as well as the running share: with `anonymousAccess`, the `jobsPerScope` documents running or waiting are counted for all visitors together, and panels beyond that budget come back `failed` until a reload or "Try again". For a public deployment, set `jobsPerScope` to the number of visitors expected to open a multi view at the same moment times `multiView.maxPanels`; `maxQueuedJobs` then defaults to four times that.
|
|
846
872
|
- Each sanitizer worker runs with `workerHeapMb` (512 MiB) of old generation and a fixed 32 MiB young generation, about 1.1 GiB for the default two workers. A process-wide `--max-old-space-size` (for example in `NODE_OPTIONS`) overrides the workers' old-generation limit, because V8 gives the flag precedence; the nesting guard's node budget still keeps every document it accepts within about `workerHeapMb`, but the hard stop at the limit no longer applies.
|
|
847
873
|
- The Top/Bottom buttons of the tree's pointer scroll bar (`@aiquants/virtualscroll`, hidden from assistive technology and kept out of the Tab order because the tree owns keyboard scrolling with its arrow keys, Home and End)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { jsx as L, jsxs as j, Fragment as ze } from "react/jsx-runtime";
|
|
2
2
|
import { useState as le, useRef as _, useLayoutEffect as N, useEffectEvent as fe, useEffect as Oe, useImperativeHandle as Fe, useMemo as ie, startTransition as Ge, useCallback as W, useId as Ue } from "react";
|
|
3
|
-
import { v as Y, g as ae, h as Ke, u as te, i as We, l as Xe, j as $e, k as qe, m as je, n as Ye, o as Je, p as Qe, E as Ze, q as et, s as tt, t as me, w as pe, A as rt, x as he, y as nt, z as ot, B as it, G as st } from "./index-
|
|
3
|
+
import { v as Y, g as ae, h as Ke, u as te, i as We, l as Xe, j as $e, k as qe, m as je, n as Ye, o as Je, p as Qe, E as Ze, q as et, s as tt, t as me, w as pe, A as rt, x as he, y as nt, z as ot, B as it, G as st } from "./index-25s_q0vD.js";
|
|
4
4
|
import { history as lt, historyKeymap as at, defaultKeymap as ct, historyField as ut } from "@codemirror/commands";
|
|
5
5
|
import { markdown as dt, markdownLanguage as ft } from "@codemirror/lang-markdown";
|
|
6
6
|
import { syntaxHighlighting as mt, HighlightStyle as pt } from "@codemirror/language";
|
|
@@ -14,8 +14,8 @@ import { d as At, f as Q, E as Mt } from "./dataRoute-CObbjNxG.js";
|
|
|
14
14
|
import { H as Ot, c as qt, M as Ct } from "./sanitizePolicy-DlrakwA4.js";
|
|
15
15
|
import It from "isomorphic-dompurify";
|
|
16
16
|
import { PanelGroup as Rt, Panel as ve, PanelResizeHandle as _t } from "@aiquants/resize-panels";
|
|
17
|
-
import { C as Nt, F as Pt, E as Dt, a as Vt, b as Z, d as Ht } from "./location-
|
|
18
|
-
import { u as Bt, a as zt } from "./useSplitPersistence-
|
|
17
|
+
import { C as Nt, F as Pt, E as Dt, a as Vt, b as Z, d as Ht } from "./location-B-m9scLf.js";
|
|
18
|
+
import { u as Bt, a as zt } from "./useSplitPersistence-Cc4tDxB4.js";
|
|
19
19
|
const Re = { history: ut }, Ft = pt.define([
|
|
20
20
|
{ tag: [C.heading1, C.heading2, C.heading3, C.heading4, C.heading5, C.heading6, C.heading], color: "var(--aqmx-syntax-heading)", fontWeight: "700" },
|
|
21
21
|
{ tag: C.strong, fontWeight: "700" },
|