@aiquants/markdown-explorer 0.33.0 → 0.35.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 +795 -0
- package/README.md +119 -55
- package/dist/EditSurface-CLG70Vnn.cjs +6 -0
- package/dist/EditSurface-D2j1kCEE.js +990 -0
- package/dist/ExplorerSplit-CfP1smbT.js +1589 -0
- package/dist/ExplorerSplit-D_0VohOv.cjs +2 -0
- package/dist/{MultiLayout-DYNGlNy0.js → MultiLayout-BeJ5Lubb.js} +291 -290
- package/dist/MultiLayout-CxV5SI7f.cjs +1 -0
- package/dist/NativeScrollBar-BM5NULzg.js +62 -0
- package/dist/NativeScrollBar-RWXpVhbI.cjs +1 -0
- package/dist/TreeLayout-AxLw-36S.js +103 -0
- package/dist/TreeLayout-Bg2YH-EY.cjs +1 -0
- package/dist/client/MarkdownExplorer.d.cts +14 -1
- package/dist/client/MarkdownExplorer.d.ts +14 -1
- package/dist/client/edit/lineEndings.d.cts +4 -0
- package/dist/client/edit/lineEndings.d.ts +4 -0
- package/dist/client/hostContract.d.cts +67 -0
- package/dist/client/hostContract.d.ts +67 -0
- package/dist/core/config.d.cts +7 -0
- package/dist/core/config.d.ts +7 -0
- package/dist/core/contracts.d.cts +10 -4
- package/dist/core/contracts.d.ts +10 -4
- package/dist/core/draftAnswer.d.cts +23 -0
- package/dist/core/draftAnswer.d.ts +23 -0
- package/dist/core/geometry.d.cts +1 -0
- package/dist/core/geometry.d.ts +1 -0
- package/dist/core/labels.d.cts +78 -0
- package/dist/core/labels.d.ts +78 -0
- package/dist/core/location.d.cts +3 -2
- package/dist/core/location.d.ts +3 -2
- package/dist/core/ownUrls.d.cts +15 -0
- package/dist/core/ownUrls.d.ts +15 -0
- package/dist/core/treeSettings.d.cts +3 -2
- package/dist/core/treeSettings.d.ts +3 -2
- package/dist/core/viewSettings.d.cts +5 -1
- package/dist/core/viewSettings.d.ts +5 -1
- package/dist/describeValue-CLlVRO8d.js +17 -0
- package/dist/describeValue-Ccvhbt36.cjs +1 -0
- package/dist/explorerCore-DLpDuSev.js +998 -0
- package/dist/explorerCore-DYrxS9ez.cjs +1 -0
- package/dist/index-C1YMH-yI.js +5816 -0
- package/dist/index-LQWQfpAf.cjs +18 -0
- package/dist/index.cjs +1 -1
- package/dist/index.d.cts +7 -4
- package/dist/index.d.ts +7 -4
- package/dist/index.js +47 -42
- package/dist/licenses/@heroicons/react/LICENSE +21 -0
- package/dist/licenses/entities/LICENSE +11 -0
- package/dist/licenses/parse5/LICENSE +19 -0
- package/dist/location--KvTA0Ri.js +726 -0
- package/dist/location-D8DyDkuA.cjs +1 -0
- package/dist/lru-DC8GBmkX.js +39 -0
- package/dist/lru-SGmUyBQU.cjs +1 -0
- package/dist/{merge-D7L_pINl.js → merge-Bb_HpPhe.js} +1 -1
- package/dist/{merge-DZI4pkWI.cjs → merge-DQUYEGCx.cjs} +1 -1
- package/dist/nestingGuardWorker.js +5511 -0
- package/dist/ownUrls-B259RGgd.cjs +1 -0
- package/dist/ownUrls-Dh5g6ZJi.js +370 -0
- package/dist/sanitizeJob-BYRk17nr.js +21 -0
- package/dist/sanitizeJob-Cs9o3Vpl.cjs +1 -0
- package/dist/sanitizePolicy-CEMdaLUB.js +139 -0
- package/dist/sanitizePolicy-CiQfnxyd.cjs +2 -0
- package/dist/sanitizeWorker.cjs +1 -1
- package/dist/sanitizeWorker.js +134 -139
- package/dist/sanitizerService-BY4CPCoA.cjs +1 -0
- package/dist/sanitizerService-KWXv7bPm.js +240 -0
- package/dist/server/assetResponse.d.cts +60 -0
- package/dist/server/assetResponse.d.ts +60 -0
- package/dist/server/browser/browserPlatform.d.cts +12 -0
- package/dist/server/browser/browserPlatform.d.ts +12 -0
- package/dist/server/createMarkdownExplorer.d.cts +0 -10
- package/dist/server/createMarkdownExplorer.d.ts +0 -10
- package/dist/server/explorerCore.d.cts +12 -0
- package/dist/server/explorerCore.d.ts +12 -0
- package/dist/server/fileSystemSource.d.cts +1 -0
- package/dist/server/fileSystemSource.d.ts +1 -0
- package/dist/server/inProcessFetch.d.cts +5 -0
- package/dist/server/inProcessFetch.d.ts +5 -0
- package/dist/server/platform.d.cts +18 -0
- package/dist/server/platform.d.ts +18 -0
- package/dist/server/ports.d.cts +36 -5
- package/dist/server/ports.d.ts +36 -5
- package/dist/server/sanitizeProtocol.d.cts +3 -0
- package/dist/server/sanitizeProtocol.d.ts +3 -0
- package/dist/server/sanitizer.d.cts +5 -40
- package/dist/server/sanitizer.d.ts +5 -40
- package/dist/server/sanitizerOptions.d.cts +24 -0
- package/dist/server/sanitizerOptions.d.ts +24 -0
- package/dist/server/sanitizerService.d.cts +41 -0
- package/dist/server/sanitizerService.d.ts +41 -0
- package/dist/server/{workerPool.d.cts → workerJobs.d.cts} +0 -16
- package/dist/server/{workerPool.d.ts → workerJobs.d.ts} +0 -16
- package/dist/server.cjs +1 -1
- package/dist/server.d.cts +3 -1
- package/dist/server.d.ts +3 -1
- package/dist/server.js +270 -1343
- package/dist/serverBrowser.cjs +1 -0
- package/dist/serverBrowser.d.cts +1 -0
- package/dist/serverBrowser.d.ts +1 -0
- package/dist/serverBrowser.js +120 -0
- package/dist/serverCore.cjs +1 -0
- package/dist/serverCore.d.cts +14 -0
- package/dist/serverCore.d.ts +14 -0
- package/dist/serverCore.js +46 -0
- package/dist/storage-BpYsprog.cjs +1 -0
- package/dist/{storage-CmGHg7OA.js → storage-D1uSw-xj.js} +19 -18
- package/dist/storage.cjs +1 -1
- package/dist/storage.js +1 -1
- package/dist/styles/markdown-explorer.css +1 -1
- package/dist/tapScrollCircle-BEydRn0y.js +14 -0
- package/dist/tapScrollCircle-DdX0Wri0.cjs +1 -0
- package/dist/testing.cjs +1 -0
- package/dist/testing.d.cts +6 -0
- package/dist/testing.d.ts +6 -0
- package/dist/testing.js +4 -0
- package/dist/useSplitPersistence-B2Fj508K.cjs +1 -0
- package/dist/useSplitPersistence-Fkqak8G8.js +44 -0
- package/docs/behavior/dom-hooks.md +14 -3
- package/docs/behavior/hosting.md +123 -0
- package/docs/behavior/layout.md +69 -19
- package/docs/behavior/localization.md +28 -10
- package/docs/behavior/security.md +34 -14
- package/docs/behavior/url-contract.md +13 -6
- package/package.json +54 -16
- package/dist/EditSurface-BPqqykro.cjs +0 -6
- package/dist/EditSurface-CWq35IWQ.js +0 -972
- package/dist/ExplorerSplit-BRY4uy6x.js +0 -1493
- package/dist/ExplorerSplit-CQxr6b0v.cjs +0 -1
- package/dist/MultiLayout-TXbet9k3.cjs +0 -1
- package/dist/NativeScrollBar-BsWdvkHa.js +0 -64
- package/dist/NativeScrollBar-UpjxjLlB.cjs +0 -1
- package/dist/TreeLayout-BQEgZhz9.js +0 -72
- package/dist/TreeLayout-C0O1OGi4.cjs +0 -1
- package/dist/dataRoute-DLhQfdoW.js +0 -298
- package/dist/dataRoute-DwYtgyt6.cjs +0 -1
- package/dist/index-CO-RgTml.js +0 -4912
- package/dist/index-DSkK8iLE.cjs +0 -15
- package/dist/location-BxiJRTyw.cjs +0 -1
- package/dist/location-perTmwct.js +0 -663
- package/dist/sanitizePolicy-By0tKOpZ.js +0 -98
- package/dist/sanitizePolicy-T5T-3vV5.cjs +0 -1
- package/dist/storage-DM0EvkVf.cjs +0 -1
- package/dist/tapScrollCircle-CRKZremf.js +0 -12
- package/dist/tapScrollCircle-Cbf17x8g.cjs +0 -1
- package/dist/useSplitPersistence-Du01PHNg.js +0 -42
- package/dist/useSplitPersistence-pPmE4GTT.cjs +0 -1
package/docs/behavior/layout.md
CHANGED
|
@@ -6,9 +6,11 @@ This page is part of the host-facing contract of `@aiquants/markdown-explorer`;
|
|
|
6
6
|
|
|
7
7
|
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` (in a fresh React Router app, with `html` and `body` at `height: 100%`).
|
|
8
8
|
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, depending on the host's structure.
|
|
9
|
-
|
|
9
|
+
The explorer takes its inline size from its container too, never from its content: the split's frame is a size container in the inline axis (it lays itself out from its own width, from the first paint), so a container that shrinks to fit its content — an absolutely positioned or fixed box without a width, `width: fit-content` or `max-content`, a float, an `auto` grid track with `justify-content: start` — sizes the explorer to 0 px. Give such a container a width; a block container and a stretched flex or grid item already have one.
|
|
10
|
+
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 root element, naming either the overflow (the explorer ends more than 1 px below the viewport) or the collapse (its root, the document region of the tree or single view, or the explorer's tree area is rendered but less than 1 px tall), and what to give the container.
|
|
11
|
+
Each root element is checked once the layout has settled, when the explorer's root and the window have kept their size for one second after the root attached or after the last resize of either; a frame that differs per view recreates the root, which is checked afresh.
|
|
10
12
|
A resize can pass through intermediate viewports before it ends (switching Chrome DevTools' device toolbar between a desktop and a phone size does), and one shorter than the host's own bars collapses the explorer for a moment; the explorer is judged only after the layout has settled, so such a moment is not reported, while a container without a definite block size, which keeps the explorer misplaced, still is.
|
|
11
|
-
Only rendered parts are measured: a part with no layout box (`display: none` on it or an ancestor — a closed sheet, an explorer panel
|
|
13
|
+
Only rendered parts are measured: a part with no layout box (`display: none` on it or an ancestor — a closed sheet, an explorer panel a drag holds collapsed, an explorer the host hides) is hidden, not collapsed, and is never reported.
|
|
12
14
|
|
|
13
15
|
## The split
|
|
14
16
|
|
|
@@ -23,19 +25,37 @@ The tree and multi-panel views split the frame into the explorer and the content
|
|
|
23
25
|
| Sheet threshold | 13rem × φ² (≈ 544.6 px at a 16 px root) | Below it the minimum explorer would pass the golden section, so the explorer leaves the split and opens as a sheet |
|
|
24
26
|
| Handle | A band 24 px wide under a fine pointer and one control wide, 44 px, under a coarse one (`(pointer: coarse)`); a 5 × 34 px grip around a 2 × 21 px bar | WCAG 2.2 target size (minimum for a fine pointer, which keeps the handle thin, and enhanced for a coarse one); the arrow keys move the handle as well. The band itself is the target, and each side keeps half of it clear (below): a wider invisible hit area would cover the tree's scroll bar beside it. The grip is Fibonacci |
|
|
25
27
|
|
|
26
|
-
- The root font size is measured in the browser (through a 1rem probe, so a text-only zoom is followed as well)
|
|
27
|
-
- The server
|
|
28
|
+
- The root font size is measured in the browser (through a 1rem probe, so a text-only zoom is followed as well).
|
|
29
|
+
- The server knows neither the frame's width, nor the root font size, nor the pointer, so it renders the split with the explorer open beside the content (or closed to its rail, by the display settings), and the frame carries `data-aqmx-measured="false"` until the first layout after hydration has measured it. Meanwhile the stylesheet lays the frame out as the measure will, from the frame's own width (a container query in rem, so the reader's font size counts as well):
|
|
30
|
+
narrower than 13rem × φ², the explorer, its handle and the rail are hidden, the content takes the whole width, the tree view's document bar wears the sheet bar's look with the toggle's lane at its start, and a frame without that bar keeps one bar's room above the split, where the sheet's bar comes; wider, the explorer keeps its 13rem floor.
|
|
31
|
+
The handle's band (below) follows `(pointer: coarse)` in the stylesheet (`--aqmx-split-handle-size`). So the explorer, the rail, the content's panel and the document bar keep their places when the page hydrates; only the handle, which takes no room, widens then under a coarse pointer.
|
|
32
|
+
The document viewer keeps its text in place too: its bar's slot is as wide as the bar from the first paint (`--aqmx-scroll-bar-slot-size`: 8 px under a fine pointer, 0 under a coarse one, where the bar lies over the text's end), though the bars' module loads only after the page, and a viewer that starts its region reserves the band its toolbar covers before it measures the toolbar (see the toolbar under [The document region](#the-document-region)), so the text neither narrows when its bar appears nor moves down when the toolbar is measured.
|
|
33
|
+
The tree's bar, which the server draws for a fine pointer (with its arrows and an always-shown circle), stays hidden in its place under a coarse pointer until hydration draws it without them (below).
|
|
28
34
|
- The handle takes no room of its own: it lies over the boundary, half on each side, and each side keeps that half clear (the explorer ends, and the content starts, half the band away from the boundary), so the band covers neither the tree's scroll bar nor the content's edge.
|
|
29
35
|
- At 1920 px, with a 16 px root and a fine pointer, the tree view gives the explorer 1920/φ³ ≈ 453.3 px, 12 px of which it keeps clear beside the 24 px handle. The multi-panel view gives it 1920/φ⁴ ≈ 280.1 px and the stage ≈ 1639.9 px; less the 12 px it keeps clear and 13 px of padding at each side, the column track is ≈ 1601.9 px,
|
|
30
36
|
so the stage shows ⌊(1601.9 + 13) / (384 + 13)⌋ = 4 columns of (1601.9 − 3 × 13) / 4 ≈ 390.7 px, each wider than the 40ch measure (≈ 384 px with a common UI font, whose `0` is about 0.6em wide). At 1280 px the multi-panel explorer stays at its 13rem floor (1280/φ⁴ ≈ 186.7 px is less than 208 px) and the stage shows two columns.
|
|
31
37
|
- The reader's width is remembered per view, as a percentage of the split, in the display-settings cookie (see [URL contract](url-contract.md#display-settings)). It is written only after the reader moves the handle — at the end of a drag, or when the arrow keys are released (or the handle loses focus) after they moved it, 233 ms later in both cases — never because the window was resized, so a narrow window does not overwrite the width chosen on a wide one.
|
|
32
|
-
- The handle is a focusable `separator` (named by `resizeExplorer`) from `@aiquants/resize-panels`: Left and Right move it by 10 px (50 px with Shift), pressing past the minimum
|
|
38
|
+
- The handle is a focusable `separator` (named by `resizeExplorer`) from `@aiquants/resize-panels`: Left and Right move it by 10 px (50 px with Shift), and pressing past the minimum closes the explorer (see [Closing the explorer](#closing-the-explorer)), which its rail opens again at its previous width. Only keys that moved the handle by the time they were released count as the reader's choice.
|
|
39
|
+
|
|
40
|
+
## Closing the explorer
|
|
41
|
+
|
|
42
|
+
In the tree and multi-panel views the reader can close the explorer, which gives the content the whole frame but a rail:
|
|
43
|
+
|
|
44
|
+
- Three ways lead to the same closed state: the close button at the end of the explorer's first line, where the sheet has its own (named by `hideExplorer`, «Close the explorer» / 「エクスプローラーを閉じる」, a 44 px target under every pointer); the handle dragged to the split's edge and released there (dragged back before the release, the explorer stays open; while the drag holds it collapsed it stays mounted but is not displayed, so its tree lists nothing); and the arrow keys pressed past the minimum.
|
|
45
|
+
- Closed, the explorer and its handle leave the split, and a rail 55 px wide (`--aqmx-space-9`: the sheet's bar turned 90°, a 44 px toggle between 5 px of padding on each side, and a 1 px border) holds the explorer's side. Its toggle (named by `showExplorer`, with `aria-expanded="false"`) opens the explorer again at the width the reader last chose.
|
|
46
|
+
- The choice is remembered per view in the display-settings cookie (`treeExplorerHidden`, `multiExplorerHidden`; see [URL contract](url-contract.md#display-settings)), so the server renders the rail on the first paint and a reload keeps it. Below the sheet threshold the explorer is a sheet, which starts closed whatever the choice says; widening the frame out of the sheet follows the choice.
|
|
47
|
+
- Focus on the explorer's side follows the explorer: closing it moves the focus to the rail's toggle, and opening it moves the focus to the explorer's close button, so a round trip returns to the button pressed first; with the explorer closed, crossing the sheet threshold moves the focus between the rail's toggle and the sheet's toggle. Focus in the content stays where it is.
|
|
48
|
+
- While a maximized panel or document covers the page, the rail is inert, like the rest of the explorer's side.
|
|
33
49
|
|
|
34
50
|
## The sheet on narrow frames
|
|
35
51
|
|
|
36
52
|
When the frame is narrower than 13rem × φ² — a phone, or a narrow window — the explorer leaves the split:
|
|
37
53
|
|
|
38
|
-
- The content takes the whole width under a bar with a visible toggle (named by `showExplorer`, a 44 px target under every pointer, with `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`). It stays mounted across the change, so the document keeps its scroll position and focus.
|
|
54
|
+
- The content takes the whole width under a bar 55 px high (`--aqmx-space-9`: a 44 px control between 5 px of padding, and a 1 px border) with a visible toggle (named by `showExplorer`, a 44 px target under every pointer, with `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`). It stays mounted across the change, so the document keeps its scroll position and focus.
|
|
55
|
+
- In the tree view, while a document is shown, the sheet's bar and the document's bar are one bar: the sheet's bar lies over the start of the document's bar (`data-aqmx-sheet-bar-merged="true"` on the sheet's bar), and the document's bar takes the sheet's look —
|
|
56
|
+
its height, border and surface, and its labelled buttons (Source, Edit, Refresh document and the editor's controls) showing their icons only, their labels kept as their accessible names beside the tooltips they always have — with a lane at its start that the toggle lies over (`data-aqmx-sheet-bar="merged"` on the document's bar).
|
|
57
|
+
Both bars keep their places in the DOM, so the toggle stays the same element, first in the Tab order, with the same name; while the bars are one it shows its label as its tooltip. The empty state and a folder without a README have no document bar, and the sheet's bar stands alone above the content.
|
|
58
|
+
While the document is maximized (see [The maximized document](#the-maximized-document)) the document's bar keeps the sheet's look without the lane (`data-aqmx-sheet-bar="covering"`), since the toggle lies inert under the cover, so nothing below the bar moves when the document is maximized or restored. A multi-view panel's bar never takes the sheet's look.
|
|
39
59
|
- The toggle opens the explorer as a modal sheet over the content: a native `dialog` named by `explorerRegion`, at most 21rem wide (13rem × φ ≈ 21rem) and leaving 3.4375rem of the content visible beside it (55 px at 16 px text, 110 px at 200 %). The sheet has no header row of its own: its close button (named by `hideExplorer`, 44 px under every pointer) sits at the end of the explorer's first line, beside the source switch, or beside the header's actions when there is one source; that line leaves it the room and takes its height.
|
|
40
60
|
Focus moves to the close button, and the rest of the page is inert while it is open — the explorer's root live region included, so the sheet holds a live region of its own that speaks the explorer's announcements while it is open (see [Announcements](#announcements)).
|
|
41
61
|
- Escape, the close button, a press on the backdrop that also started there (a press that starts inside the sheet and is released over the backdrop does not close it) and any navigation that keeps the tree's source (choosing a document, opening a selection) close it, and focus returns to the toggle. Switching the source keeps it open.
|
|
@@ -44,6 +64,19 @@ When the frame is narrower than 13rem × φ² — a phone, or a narrow window
|
|
|
44
64
|
- Focus on the explorer's side (the tree, the handle, the toggle or the open sheet) is handed over when the mode changes: to the sheet's toggle when the frame narrows past the threshold; when it widens past it, once the rebuilt tree has drawn its rows, to the tree row the reader was on (found by its path in the rebuilt tree), else the tree's tab-stop row, else the tree's stand-in stop (see [The tree](#the-tree)), which brings that row into view and hands it the focus, else the handle.
|
|
45
65
|
The row is remembered from the reader's own focus moves only, so a round trip (split, sheet, split) without touching anything returns to the same row, while a later focus move by the reader (opening the sheet, say) replaces it. A row the rebuilt tree has not rendered (far down a long tree) falls back to the tab-stop row. The row that takes the focus becomes the tree's only Tab stop, so Shift+Tab from it leaves the tree at once. Focus elsewhere stays where it is.
|
|
46
66
|
|
|
67
|
+
## The maximized document
|
|
68
|
+
|
|
69
|
+
In the tree view the document can take the whole page:
|
|
70
|
+
|
|
71
|
+
- The document's bar ends with Maximize, icon-only and named and titled for what a press does: `documentMaximize` («Maximize the document» / 「文書を最大化」), and while the document is maximized `documentRestore` («Restore the document to its size» / 「文書を元のサイズに戻す」). Its name says what the next press does, so it carries no pressed state, and it is the same element in every state, reading or editing, so the focus stays on it. The single view, whose frame is the page already, and a multi-view panel, which its header maximizes, have no such button.
|
|
72
|
+
- A press replaces the URL with the same location maximized (`maximized=true`) or restored, without a new history entry, keeping the scroll and leaving the fragment behind, so a reload, a shared link and Back and Forward keep it (see [URL contract](url-contract.md#shape)). It reads nothing again and renders no document anew.
|
|
73
|
+
Each press is announced (`documentMaximized`, `documentRestored`, named after the last segment of the shown document's path, or of the folder's whose README shows), because the button's name changes under the focus, which assistive technology does not reliably speak.
|
|
74
|
+
- Maximized, the document's column (`data-aqmx-maximized="true"`) covers the page inside the explorer's maximize insets (`--aqmx-maximize-top`, `-right`, `-bottom` and `-left`, 0px by default), the insets a maximized panel covers inside as well, so a host binds one set for both views; the split's frame carries `data-aqmx-content-covers-page="true"`, and the explorer's side underneath — the explorer and its handle, the rail, or the sheet's bar — is inert. The host's own chrome is not the explorer's to make inert, as for a maximized panel (see [The multi-panel stage](#the-multi-panel-stage)).
|
|
75
|
+
- Escape restores the document by the rule a maximized panel's Escape follows: an Escape another handler marked handled (`preventDefault()`), one that belongs to an input method's composition, and one the browser turns into a close request for a layer above the page (while a modal dialog — a block's full screen among them —, a non-modal dialog whose `closedby` takes close requests or a popover the browser closes on Escape is open) are left alone, and the Escape it uses is marked handled. An Escape pressed inside a document's table, diagram or image block
|
|
76
|
+
restores the document: a block keeps its toolbar in a non-modal dialog that the browser leaves open on Escape.
|
|
77
|
+
- The column covers the page while there is a document to show, its failure view included, and while a maximized folder looks for its README, so a maximized address never flashes the explorer while it loads; a folder without a README to show, and the empty state, have no bar and cover nothing.
|
|
78
|
+
- The maximize stays with the document through a source switch, the reveal's move to the source that holds the document, and the document links and table-of-contents entries it follows, which read it at the moment of the click (their hrefs never carry it, so a maximize renders no link anew); a pick in the tree shows the next document at its size.
|
|
79
|
+
|
|
47
80
|
## The tree
|
|
48
81
|
|
|
49
82
|
- **One Tab stop.** The tree is one stop in the Tab order: the row the reader last focused — with the keyboard, a press or a script — while it holds the focus or as long as the shown document has not changed since, else the shown document's row, else the first row (`@aiquants/directory-tree`'s roving tab index). Shift+Tab from any row leaves the tree, and Tab comes back to the same row. While that row is outside the tree's render window (far down a long tree, or at a large text size), the tree puts a stand-in stop in its place, outside the `tree` role (`data-directory-tree-tab-stop`):
|
|
@@ -52,14 +85,16 @@ When the frame is narrower than 13rem × φ² — a phone, or a narrow window
|
|
|
52
85
|
- **The shown document's row.** In the tree view, with Selection set to Single or Multiple, the shown document's row carries `aria-current="page"` (none with Selection Off, and none in the multi view, whose open panels are the selected rows). While the reader gathers documents (Multiple), the gathered rows carry `aria-selected="true"` and the current row moves with the shown document alone.
|
|
53
86
|
On load, and whenever the shown document changes while the focus is outside the tree (a document link, Back or Forward), its row is brought into the tree's view by the least distance, without moving the focus, and kept there whenever the tree's area changes size (the explorer's layout settling, the tray growing or shrinking, the sheet opening on a tree it hid) until the reader presses, wheels, touches, types or moves the focus inside the tree.
|
|
54
87
|
A row the tree does not list (inside a collapsed folder) is left alone, and a document opened from the tree does not move the tree: the pressed row stays where it was, also when it was only partly visible.
|
|
88
|
+
- **The first row it showed.** While a tree is away — the explorer closed, the sheet closed, or the frame between the split and the sheet — the split keeps, per source, the row the tree showed first and how far that row was hidden above the tree's top, and the tree it rebuilds starts there, at the same height, from its first paint (`@aiquants/directory-tree` applies the expansion from the first render of a mount, so a row inside an open folder is in the list the tree starts from). The shown document's row then moves the tree only when it lies outside the
|
|
89
|
+
tree's view (see the previous item). The split keeps the rows while it is mounted, so a reload starts the tree afresh.
|
|
55
90
|
- **Loading follows what is shown open.** A lazy folder's listing is asked for while some tree shows the folder open, whatever opened it, at most 4 at a time per explorer. Bulk work — Expand all, a remembered expansion restored on load, a recursive double click — uses at most 3 of them, so a folder the reader opens (a click, Enter or ArrowRight) or retries goes ahead of every queued bulk listing and starts at once on the slot kept for the reader, unless another folder the reader opened is using it (a listing in flight is never interrupted).
|
|
56
91
|
Each source has its own queues and the sources are served in turn, so one source's bulk work never holds back another's.
|
|
57
92
|
Queues follow the order on screen (the tree's sort order), not the source's listing order.
|
|
58
93
|
A listing no tree wants any more is cancelled when the current task ends — a queued one is never sent, one in flight is aborted and frees its slot at once — and the folder goes back to not loaded: no failure, no Try again, no announcement and no loading pulse (`data-aqmx-children="loading"` is left only on folders some tree still wants).
|
|
59
|
-
That happens when the reader collapses the folder or one of its ancestors, uses Collapse all (at the click), switches the source, closes the sheet or
|
|
94
|
+
That happens when the reader collapses the folder or one of its ancestors, uses Collapse all (at the click), switches the source, closes the sheet or the explorer, or holds the explorer panel collapsed in a drag, when the explorer or the pane unmounts, and when a refresh, a seed or a reader change replaces the tree (a refresh lists the folders still shown open again). Opening the folder again asks for it again. Nothing is listed while the explorer is mounted but hidden (a closed sheet, an explorer panel a drag holds collapsed), not even on its first render.
|
|
60
95
|
- **Expand all.** Each press opens every folder and keeps opening the folders inside as their listings land, until the tree is fully open or the press's budget (`expandAll` in the configuration) runs out: at most `maxFolders` listings (500 by default), and a folder whose contents are not known yet only down to `maxDepth` levels (16 by default, the top level being 1). Folders whose contents are known — loaded, or listed by the source up front — always open, as do folders loading or failed.
|
|
61
96
|
A press walks the tree level by level, siblings in the tree's order, so its bulk listings run roughly level by level (a listing that lands early can let a deeper level start while a slower, shallower one is still in flight).
|
|
62
|
-
A folder the reader closes during a press stays closed, and the press does not walk into it. The folders a press opened join the tree's remembered expansion (per source, in browser storage), so a reload lists them again as bulk work, without opening anything beyond them and without an announcement. Hiding the explorer pauses a running press, which continues once the explorer is shown again;
|
|
97
|
+
A folder the reader closes during a press stays closed, and the press does not walk into it. The folders a press opened join the tree's remembered expansion (per source, in browser storage), so a reload lists them again as bulk work, without opening anything beyond them and without an announcement. Hiding the explorer (the sheet closed, or its panel held collapsed by a drag) pauses a running press, which continues once the explorer is shown again; closing the explorer removes its pane and ends the press with it, as a view switch does;
|
|
63
98
|
Collapse all, a source switch and a tree with no rows to show (failed, empty or cleared) end it silently.
|
|
64
99
|
While a change of the expansion is pending (folders open and close in a React transition), the tree is marked busy (`aria-busy` on the tree) and shows the progress cursor, and nothing in it is dimmed. A running press does not mark it: each level's change would make the mark and the cursor flicker, and the progress line tells the press's progress instead.
|
|
65
100
|
- **Progress line.** While the source has listings queued or in flight, a line floats at the bottom of the tree area, over the rows and clear of the scroll buttons and the scroll bar, without moving the tree (`markdown-explorer-tree-progress`): "Loading 12 folders…", or "Opening all folders (40 opened, 12 loading)…" during a press. After a press stopped at a limit it shows the loading count alone while listings remain and nothing once none does; it never shows the stop sentence, which would cover the last rows until the next press (see the stop notice below).
|
|
@@ -125,9 +160,9 @@ Documents in the multi-panel view sit in `multiView.columns` logical columns (4
|
|
|
125
160
|
A panel that a pick opened or showed is then brought into the stage's view by the least distance, without moving the focus (a pick in the split leaves the focus on the tree row, so the reader keeps picking): in a crowded stage it would otherwise sit below the fold, where the pick changes nothing the reader sees and a second click on the same row closes a panel they never saw.
|
|
126
161
|
A panel is always brought into view whole — its header with the title and buttons, and its body — and kept there, with the focus a restore left in it, while the stage settles around it (its own document arriving, an image loading in a panel above it once the scroll brought that panel near, the restored document's text wrapping again), until the reader's next key, press, wheel or touch anywhere on the page, or until the stage, the panel's scroll area or the page is scrolled to a place these reveals did not leave it at (assistive technology's browse mode,
|
|
127
162
|
the browser's find bar or a script moved it). Meanwhile scroll anchoring is off in the scroll containers around what is kept (`overflow-anchor: none`, restored when the keeping ends): the browser's adjustment holds a node of its own choosing, and it would be such a scroll.
|
|
128
|
-
- **Maximized panels.** A maximized panel covers the stage and the explorer, and everything of the explorer it covers is inert until it is restored: the explorer makes its own side inert — the explorer and its handle (or, in sheet mode, the sheet's bar) — and drag-drop-panels everything else it renders — the other panels, the bar of hidden panels, the drop placeholders and its announcer. Tab and Shift+Tab therefore never land on the explorer's hidden controls, and Enter or Space never acts on one.
|
|
129
|
-
The host's own chrome is not the explorer's to make inert: what the panel covers of it stays focusable, so a host binds
|
|
130
|
-
Escape restores the panel only when nothing else used the key: drag-drop-panels ignores an Escape another handler marked handled (`preventDefault()`), one that belongs to an input method's composition, one
|
|
163
|
+
- **Maximized panels.** A maximized panel covers the stage and the explorer, and everything of the explorer it covers is inert until it is restored: the explorer makes its own side inert — the explorer and its handle (the rail while the reader closed the explorer, or, in sheet mode, the sheet's bar) — and drag-drop-panels everything else it renders — the other panels, the bar of hidden panels, the drop placeholders and its announcer. Tab and Shift+Tab therefore never land on the explorer's hidden controls, and Enter or Space never acts on one.
|
|
164
|
+
The host's own chrome is not the explorer's to make inert: what the panel covers of it stays focusable, so a host binds the explorer's maximize insets to keep its chrome uncovered — `--aqmx-maximize-top`, `-right`, `-bottom` and `-left` (0px by default), which the stage hands to drag-drop-panels' `--aqdd-maximize-*` and which the tree view's maximized document reads too (the demo binds `--aqmx-maximize-top` to its header) — or makes it inert while the maximized panel's frame, or the tree view's maximized document column, carries `data-aqmx-maximized="true"` (see the README's "Load the styles").
|
|
165
|
+
Escape restores the panel only when nothing else used the key: drag-drop-panels ignores an Escape another handler marked handled (`preventDefault()`), one that belongs to an input method's composition, and one the browser turns into a close request for a layer above the page (a modal dialog, a non-modal dialog whose `closedby` takes close requests, or a popover it closes on Escape); one pressed inside a document's block restores the panel.
|
|
131
166
|
Every Escape the explorer handles is marked so — closing the sheet or the tree settings menu (it also stops there, so the explorer's outer handlers never see it) — and so is every Escape the document viewer handles: in a maximized panel, the first Escape in the viewer's open table of contents, style or alignment menu closes the menu, returns the focus to its button and keeps the panel maximized, and the next Escape restores the panel.
|
|
132
167
|
This holds in framework mode as well, where React's root listener sits on the document itself: the mark, not the propagation, is what the page's later listeners read, so a host's own Escape listener on the document honours it by checking `defaultPrevented`.
|
|
133
168
|
- **Panel limit.** A pick beyond `multiView.maxPanels` opens nothing; the announcer says `panelLimit` once and a visible notice appears for three seconds where the reader made the pick.
|
|
@@ -181,6 +216,8 @@ Documents in the multi-panel view sit in `multiView.columns` logical columns (4
|
|
|
181
216
|
A block `@aiquants/markdown` shows full screen — a ```spreadsheets table, a Mermaid diagram or a storage SVG image alone in a paragraph, each from the full-screen toggle that ends its toolbar — becomes a modal dialog over the page, named for full screen (see [Localization](localization.md)), which no pane or panel clips, and carries `data-aqmd-fullscreen` while it is.
|
|
182
217
|
Everything inside it is then the block's: a double-click there neither opens the editor nor maximizes the panel behind it, the editing surface leaves its keys alone (see **Editing a Markdown document** below), and Escape leaves full screen without restoring a maximized panel.
|
|
183
218
|
Where the toolbar covers the inline extent of the document's content — in the tree view and a maximized panel at every width, where the content spans the pane, and in the single view unless its `width` or `maxWidth` leaves room beside the content — the viewer reserves the depth it covers as the top padding and the `scroll-padding-block-start` of its scroll container and publishes it as `--aqmd-toolbar-block-overlap` on `[data-aqmd-scroll-container]`: the first line and every fragment's element start below the buttons. Where the toolbar covers none of the content the band is `0px`.
|
|
219
|
+
Until the viewer has measured its toolbar — in the server's render and until hydration — a viewer that is its region's first child (the progress line that may come before it lies outside the flow) opts in to the viewer's own reservation, `--aqmd-toolbar-reserve-before-measure: 1` on the viewer's frame: wherever the content spans the column (`[data-aqmd-toolbar-over-content]`)
|
|
220
|
+
the band is then the toolbar's inset plus its block size rounded up to a whole px, the depth the measure finds, so the first line does not move when the toolbar is measured. A viewer under a file header (a text file's), whose toolbar lies over the header, and a viewer given a `width` or `maxWidth` reserve nothing before the measure.
|
|
184
221
|
An open, unpinned menu of the toolbar (the table of contents, the style or the alignment menu) closes on Escape while the focus is inside it and returns the focus to its button; the viewer marks that keydown handled (`preventDefault()`). In a panel every part of the document (failure callout, image, media) takes its content height, and an embedded PDF is 1 : √2.
|
|
185
222
|
- A file header (the toolbar of an image, a medium, a text or a table file: its name, the zoom controls or Copy the text, Open in a new tab — for a text and a table file, the whole file as UTF-8 plain text, which a browser shows instead of downloading — and Download) wraps its controls onto more lines instead of letting any of them run out of the pane or the panel at a narrow width or a large text size; the name takes what the controls leave on the first line and is cut with an ellipsis.
|
|
186
223
|
- An image opens fitted to the pane (Fit pressed). Zoom in and Zoom out step through the levels 1/φ², 1/φ, 1, φ and φ² (≈ 38.2 %, 61.8 %, 100 %, 161.8 % and 261.8 %) of a base size — the image's natural size, or for an image without one the fitted size described below — and the level shown is a percentage of that base; from the fitted size they go to the nearest level above or below it.
|
|
@@ -202,7 +239,8 @@ Documents in the multi-panel view sit in `multiView.columns` logical columns (4
|
|
|
202
239
|
A raster image, a media, text or file document, a workbook (a spreadsheet document whose `format` is `workbook`: its bytes are no text) and a failure show no toggle, and neither does a document still loading, which gets it once it is there.
|
|
203
240
|
A table file's source is its CSV or TSV as written, read by the same rule as its table (a byte order mark's encoding, UTF-8 or the configured legacy encoding).
|
|
204
241
|
Pressing it shows the document as written instead of rendered, in place and without moving the focus from the toggle: the pane reads the document's file through the data route's `text` operation (only once the toggle is pressed) and shows the text the way it shows a text file — the file header with Copy the text, Open (the whole file as plain text in a new tab) and Download, the note `textTruncated` when the server cut the file at its `textMaxBytes`, and the text, which wraps and is never interpreted.
|
|
205
|
-
Copy the text (an icon button, `copyText`) puts the text on the clipboard exactly as read, line endings included, and is offered only for a text read whole, so a cut file is never copied in part (Download fetches it whole). The outcome is announced (`copiedText`, or `copyTextFailed` when the browser has no asynchronous clipboard — an insecure origin
|
|
242
|
+
Copy the text (an icon button, `copyText`) puts the text on the clipboard exactly as read, line endings included, and is offered only for a text read whole, so a cut file is never copied in part (Download fetches it whole). The outcome is announced (`copiedText`, or `copyTextFailed` when the browser has no asynchronous clipboard — an insecure origin —, refuses the write or has a clipboard that throws; the refused and the thrown write are also logged to the console) and shown for 2 seconds by the button's icon and tooltip, while its accessible name
|
|
243
|
+
stays the same; a second press counts the 2 seconds again, and only the latest press decides the outcome, so a late answer to an earlier press shows and announces nothing. The same button heads every text file.
|
|
206
244
|
Until the first answer the region shows a skeleton (`markupLoading` for screen readers); a failure before any text shows the failure callout, with Try again for a `failed` read, and is announced once (`documentFailed`), like a document's; a retry that succeeds moves a focus the swap dropped into the text and, in a page view, announces the document (`documentShown`), as the pane does for a document that replaces a failure.
|
|
207
245
|
Every new answer for the document — Refresh document, Refresh tree, a background revalidation — reads the text again, the previous text staying on screen meanwhile and the region busy (its progress line and `aria-busy`); a reading again that fails keeps the text: Refresh document reports it in the bar (see Document refresh), and a background answer's reading that fails says nothing, as a background failure under a loaded document does. The next press shows the document rendered again (an SVG image as the image).
|
|
208
246
|
The choice is part of the URL (`markup`, see the [URL contract](url-contract.md#shape)), written by replacing the entry: a reload, a shared link and Back and Forward show the document the same way, and the switches between the tree and multi views carry it for the document they open. It belongs to that document only: another document opens rendered, and the document still shown while the next one loads keeps the way it showed. The region tells which way a Markdown document, an SVG image or a table file shows with `data-aqmx-document-view` (`rendered` / `markup`).
|
|
@@ -264,7 +302,8 @@ A dialog's margin box's left is clamp((l′ + r′) / 2 − w / 2, 0, W − w),
|
|
|
264
302
|
|
|
265
303
|
## Switching views
|
|
266
304
|
|
|
267
|
-
The tree and multi-panel views are separate parts of the page, so the control a reader uses to switch between them leaves with the old view. Switching with the explorer's own controls keeps the keyboard focus in the explorer instead of dropping it to the page:
|
|
305
|
+
The tree and multi-panel views are separate parts of the page, so the control a reader uses to switch between them leaves with the old view. Switching with the explorer's own controls keeps the keyboard focus in the explorer instead of dropping it to the page:
|
|
306
|
+
the header's link to the other view hands the focus to the new view's link (the same place in the same header), or — below the sheet threshold, where that link sits in the new view's closed sheet — to the sheet's toggle, or — when the reader closed the new view's explorer, which leaves it no link — to the rail's toggle; the selection tray's Open in panels hands it to the first panel it opened.
|
|
268
307
|
The hand-over happens once the new view has rendered, also while its code is still loading. Whether the reader was still on the control is decided after the switch removed it, so the hand-over works whether or not the browser fires `focusout` when it removes the focused element (Chromium does). Focus that was anywhere else, that the reader let go of before the switch, or that the reader moved meanwhile stays where it is.
|
|
269
308
|
|
|
270
309
|
## Busy and unavailable controls
|
|
@@ -277,7 +316,7 @@ It has the server reload the source's tree and shows the tree the server answers
|
|
|
277
316
|
A reload that fails keeps the tree on screen and shows an alert first in the explorer's body (`treeRefreshFailed` with the failure's title, `data-testid="markdown-explorer-refresh-failure"`), until the next refresh starts and only while the pane shows that source. Switching to another source after a refresh fetches that source's tree again in the background (it may share the storage that changed).
|
|
278
317
|
|
|
279
318
|
**Document refresh.** Every view reads one shown document alone again past the host's caches with Refresh document, apart from Refresh tree (which also lists every expanded folder again).
|
|
280
|
-
The tree and single views show it in a thin bar above the document region, at the bar's inline end, as a labelled button (`refreshDocumentLabel`, «Refresh document» / 「文書を更新」, which is also its accessible name; its tooltip is `refreshDocument`), and the tree view's empty state, which has no document, has no bar.
|
|
319
|
+
The tree and single views show it in a thin bar above the document region, at the bar's inline end, as a labelled button (`refreshDocumentLabel`, «Refresh document» / 「文書を更新」, which is also its accessible name; its tooltip is `refreshDocument`), and the tree view's empty state, which has no document, has no bar. In the tree view the bar ends with Maximize (see [The maximized document](#the-maximized-document)) and, below the sheet threshold, is the sheet's bar too (see [The sheet on narrow frames](#the-sheet-on-narrow-frames)).
|
|
281
320
|
A multi-view panel shows it icon-only in a bar pinned to the top of the panel's scroll area (see [The multi-panel stage](#the-multi-panel-stage)), named after the panel's document (`refreshDocumentNamed`, «Refresh a.md» / 「a.md を更新」, its accessible name and its tooltip). The document stays on screen while it reloads.
|
|
282
321
|
A loaded document is replaced in place only when it changed, keeping its scroller and the reader's offset (see [The document region](#the-document-region)); a shown failure, a document the page loader gave up on and one not cached yet are fetched in the foreground. Each press is announced once.
|
|
283
322
|
A document whose content reads a part of it itself — a table file's table, a document shown as written — is reloaded with that part: the control stays busy until the part is read from the new answer, and the outcome is reported only then.
|
|
@@ -294,7 +333,7 @@ Folders whose loads fail within the same animation frame — Expand all or a res
|
|
|
294
333
|
|
|
295
334
|
## Announcements
|
|
296
335
|
|
|
297
|
-
The explorer's own messages — failed folder loads, the start and end of an Expand all press, tree setting changes, the document shown, a document that failed, panel actions other than moves and the panel limit — go through one announcer per reader, which speaks them through a live region (`role="status"`, polite and atomic).
|
|
336
|
+
The explorer's own messages — failed folder loads, the start and end of an Expand all press, tree setting changes, the document shown, a document that failed, the tree view's document maximized or restored, panel actions other than moves and the panel limit — go through one announcer per reader, which speaks them through a live region (`role="status"`, polite and atomic).
|
|
298
337
|
Every message posted before the next animation frame is spoken: the region takes them together in that frame as one text — two or more joined as separate sentences (`announcementSequence`) — so neither of two failures, nor a failure and the document shown in the same frame, is dropped.
|
|
299
338
|
They are spoken in the order posted, except that the items posted through the same list label within a frame (the folders whose children failed, `foldersLoadFailedNamed`) merge into one sentence in the place of the first item, ahead of any message posted between them: folder a failing, then the document shown, then folder b failing in one frame is spoken "a and b could not be loaded. Showing x.md." The region is emptied when the first message of a frame is posted, so the same text posted again is spoken again, and a later frame replaces the text.
|
|
300
339
|
|
|
@@ -319,7 +358,7 @@ A held key repeats its keydown, and the browser turns every repeated Enter into
|
|
|
319
358
|
The guard covers the controls the explorer renders — the selection tray's remove buttons (each removal focuses the next one), Clear the selection and Open in panels; the header's link to the other view (the new view's link receives the focus), Reload, Expand all and Collapse all, and the tree settings button and its rows (opening the menu focuses its first row, and a row would cycle its value); a folder's Try again;
|
|
320
359
|
the sheet's toggle and close button (each focuses the other); an image's Fit, and a file's Open in a new tab and Download; a notice's action link; and a failure's Reload the page and Try again —
|
|
321
360
|
and the controls other packages render inside it, some of which ignore repeats on their own as well: the tree's rows (`@aiquants/directory-tree`), so holding Enter never flips a folder or a gathered document back and forth, and a press that hands the focus to a row (removing the last gathered document, clearing the selection, or a folder's Try again) does not go on to press that row; a panel header's buttons (`@aiquants/drag-drop-panels`: the moves, the drag-mode toggle, Hide, Maximize or Restore, and Close), whose Alt + Shift + arrow shortcuts also move a panel once per held chord;
|
|
322
|
-
the document viewer's toolbar and its popups (`@aiquants/markdown`: the table of contents, the display
|
|
361
|
+
the document viewer's toolbar and its popups (`@aiquants/markdown`: the table of contents, the display popover and the alignment menu, and their pin buttons); and the controls inside a document (links, `<details>` summaries, a diagram's buttons).
|
|
323
362
|
Because the repeated keydowns stop at the explorer's root, keydown listeners the host attaches outside the explorer for the bubbling phase (on `document`, for example) do not receive them either; the host's chrome from `renderFrame` is outside the root and keeps the browser's own handling.
|
|
324
363
|
A control inside the explorer opts in to the key repeat with `data-aqmx-key-repeat="allow"` on itself or on an element around it: a press of Enter that began on the control then keeps activating it once per repeat, as long as the focus stays on it.
|
|
325
364
|
The opt-in follows where the press began, not where its repeats land: a press that began on another control and handed the focus to an opted-in one — following a document link to an image, or a failure's Try again that comes back as an image, both of which focus the image's Zoom out — does not run on into it, and neither does a press that began outside the explorer. Releasing Enter, or moving the focus off the control, ends the press's claim; the next press starts afresh.
|
|
@@ -329,16 +368,26 @@ Space needs no such rule on buttons, which act when the key is released, and a t
|
|
|
329
368
|
## Rhythm
|
|
330
369
|
|
|
331
370
|
- Spacing is the Fibonacci scale 1, 2, 3, 5, 8, 13, 21, 34, 55 px, written in rem (`--aqmx-space-1` to `--aqmx-space-9`), so it scales with the reader's font size.
|
|
332
|
-
- Header rows, icon buttons, menu items, tree rows and the retry button of a folder that failed to load are one control high: 44 px (2.75rem, `--aqmx-control`) under every pointer, the WCAG 2.2 enhanced target size, and icon buttons, labelled buttons and the
|
|
371
|
+
- Header rows, icon buttons, menu items, tree rows and the retry button of a folder that failed to load are one control high: 44 px (2.75rem, `--aqmx-control`) under every pointer, the WCAG 2.2 enhanced target size, and icon buttons, labelled buttons, the sheet's toggle and close button, the rail's toggle and the explorer's close button are at least as wide (the retry button narrows to its icon, 24 px, only in a row without room for its label).
|
|
333
372
|
The tree measures `--aqmx-control` at run time, so its rows follow the root font size and a host's token override. The resize handles are 24 px bands under a fine pointer and 44 px under a coarse one (see [The split](#the-split) and [The editor's split](#the-editors-split)).
|
|
334
373
|
- The tree's virtual scrolling renders 13 rows beyond each edge and reports scrolling at most every 13 ms. Its 8 px scroll bar does not grow under a coarse pointer (the wheel, touch drag and the tree's arrow keys scroll the same list), and its arrow buttons are not Tab stops. The arrow keys, Home and End keep the focused row wholly visible: when the focus moves onto a row outside the tree's window, the tree scrolls by exactly the distance needed.
|
|
335
374
|
- Every scroller the reader browses scrolls natively, with an 8 px pointer scroll bar beside it in place of the native vertical scrollbar: the document of the tree and single views (`@aiquants/markdown`'s `renderScrollBar`), an image's canvas, a medium's and a file view's stage and a failure view there (`@aiquants/markdown`'s `HostedScrollArea`), each multi-view panel's scroll area (drag-drop-panels' `renderPanelScrollArea`) and the multi view's stage (`renderStageScrollBar`).
|
|
375
|
+
The explorer gives every content scroller's bar its slot's width from the first paint (`--aqmx-scroll-bar-slot-size`), since the bars' module loads after the page, so the text never narrows when a bar appears.
|
|
336
376
|
Every bar but the stage's carries the same tap-scroll circle as the tree's bar; every bar shows only while its content overflows, is hidden from assistive technology and has no Tab stops, so the keyboard, the wheel and touch scroll the scroller itself; a zoomed image keeps its native horizontal scrollbar.
|
|
337
|
-
The tables' grids draw their circle in the same look and
|
|
377
|
+
The tables' grids draw their circle in the same look, speeds and size (the look loads on first use, as the bars' module does): a table file's preview and a document's table one control wide, the document's table only where its options say `tapscroll=1`. Inside a multi-view panel the document and the image, media, file and failure views grow to their content and have no bar of their own: the panel's area scrolls.
|
|
338
378
|
The circle is one control wide (44 px) and sits 49 px before its bar, centred in a 54 px gutter (the circle and 5 px on each side) that every document scroller with a circle keeps at its inline end, outside its own padding: the document's scroll container (`@aiquants/markdown`'s `scrollBarGutter`), the image, media, file and failure views, and each multi-view panel's area.
|
|
339
379
|
No content (a diagram's or a table's toolbar, a code block's copy button, a focused link) lies under the circle at any scroll position; only an image zoomed wider than its canvas passes beneath it while it pans sideways. The wheel and touch scroll over the gutter as over the rest of the document.
|
|
340
380
|
The gutter is kept while the content fits as well, as the native scrollbar's room is, so the text never re-wraps when the bar appears. The tree's rows reach under the tree's circle: a gutter there would take 54 px from a pane as narrow as 13rem.
|
|
341
381
|
The stage's bar sits in 8 px the stage adds to the inline end of its padding, and has no circle: 49 px before that bar a circle would cover the right-most panel's own bar and circle, and a gutter that holds it (54 px more of the stage's padding) would cost the stage a column at a 1920 px or a 1440 px window. Menus and popovers, the scrollers nested in a document and embedded frames (a PDF's included) keep their native scrollbars and have no circle.
|
|
382
|
+
- Under a coarse pointer (a touch screen, `(pointer: coarse)`) a narrow screen gives its whole width to the content: every content scroller's bar lies over the scroller's inline end instead of beside it (its slot takes no width: `--aqmx-scroll-bar-slot-size` is `0px` there), and the scrollers keep no gutter for the circle.
|
|
383
|
+
Such a bar takes no presses — a finger scrolls the scroller itself, and a press at the edge reaches the content under the bar — and every bar, the tree's, the stage's and the tables' grids' (a document's tables and a table file's grid) included, leaves out its thumb drag and its track click and draws no arrows, its track running the bar's whole length: an 8 px bar (a table's 12 px) is no
|
|
384
|
+
target for a finger, and a finger that drags a table near its edge would meet an arrow or the track by mistake. The other bars take no presses either, so a finger's pan that starts on a bar's strip scrolls what the bar scrolls: a press on the stage's strip reaches the stage beneath, and one on the tree's strip or on a table's vertical bar reaches the box of the tree's or
|
|
385
|
+
the table's rows' scroll pane, which takes it as a press on its rows (`@aiquants/virtualscroll`), so the pan scrolls the tree or the table's rows and leaves the document where it is. A table's horizontal bar lies below its rows, outside their pane: a pan that starts on its strip goes to the browser, which scrolls the document up or down and has nothing to move sideways.
|
|
386
|
+
So does a pan that starts on a table's header or footer rows, which lie outside the rows' pane too. A horizontal pan over the rows moves the columns even when every row fits the box: the rows' pane then leaves vertical pans to the document (`touch-action: pan-y`) and takes only the horizontal ones.
|
|
387
|
+
The circles, the one part of a bar that takes presses, show only while the reader scrolls: a circle appears when the scroll position changes within 2 s of the reader's own input (a press, a finger, a wheel turn or a key), stays while the scroll goes on (a flick's momentum included) and hides 2 s after the last change, taking no presses while hidden. The watch hears those inputs anywhere in the page and does not ask what they start, so a scroll the page makes on its own (to a fragment, to a restored reading position, scroll anchoring) shows a circle
|
|
388
|
+
only when such an input came within 2 s before it, as a click on a link to a fragment does.
|
|
389
|
+
The tree's bar keeps its place beside the rows, with its Top and Bottom buttons, and its circle follows the same rule; the tables' grids show their circles by it as well. The stylesheet follows `(pointer: coarse)` itself, so the bars and the scrollers' padding take their places from the first paint.
|
|
390
|
+
The server cannot know the pointer and draws the tree's bar for a fine one, with its arrows and an always-shown circle; under a coarse pointer the stylesheet keeps a tree bar that has arrows hidden, in its place, until hydration draws it without them, so no arrow or circle appears and vanishes. The other bars draw only in the browser, with the reader's pointer from the start.
|
|
342
391
|
- The explorer's header wraps rather than cutting a control off: the source switch keeps at least 9rem and the icon buttons wrap below it, so every control stays reachable at the minimum width and at large font sizes.
|
|
343
392
|
A labelled button that is wider on its own than its line — Refresh tree in the header, Refresh document in its bar — shrinks, down to one control wide, and ends its label with an ellipsis (its icon stays whole), so it never pushes the explorer pane or the bar sideways; the cut is visual only, and the button's accessible name stays its whole label. The tree settings menu opens below the header.
|
|
344
393
|
- Durations are 89, 144, 233 and 377 ms (`--aqmx-duration-1` to `--aqmx-duration-4`); with `prefers-reduced-motion: reduce` every explorer duration is 0, the resize handles' (the explorer's and the editor's) included. The drag-and-drop panels follow the setting as well: `@aiquants/drag-drop-panels` leaves out its own transitions and its reorder animation.
|
|
@@ -350,11 +399,12 @@ Space needs no such rule on buttons, which act when the key is released, and a t
|
|
|
350
399
|
## Colour
|
|
351
400
|
|
|
352
401
|
Text colours reach WCAG 2.2's enhanced 7:1 against every surface and tint they are drawn on, in both colour schemes (the editor's syntax colours over its current line and its conflict tints included); a unit test reads the shipped tokens and checks every pair. The scheme follows the `theme` prop (`data-aqmx-theme` on the root), not the operating system, so a host with its own theme switch stays in control.
|
|
353
|
-
The root declares the scheme as its `color-scheme` (`light` or `dark`), so what colours itself by the scheme inside the explorer follows `theme` too, whatever the page declares: the colours `@aiquants/directory-tree`
|
|
402
|
+
The root declares the scheme as its `color-scheme` (`light` or `dark`), so what colours itself by the scheme inside the explorer follows `theme` too, whatever the page declares: the colours `@aiquants/directory-tree` and `@aiquants/virtualscroll` paint from their `light-dark()` palettes (the tree's type icons, and the bars of the tree, the document and the tables), and the browser's own form controls and scrollbars.
|
|
354
403
|
|
|
355
404
|
Tree rows take their text and background colours from the tokens: rest rows `--aqmx-text` on the surface; hovered and selected rows `--aqmx-text` on `--aqmx-tree-row-tint` (a selected row also has a 2 px bar in its text colour); the shown document and documents open as panels `--aqmx-accent` on `--aqmx-tree-row-accent-tint`.
|
|
356
405
|
The two row tints are opaque: with the tree lines on, `@aiquants/directory-tree` draws the connector lines and the expand glyphs on a canvas above the rows, so no row state covers them, and a hovered folder keeps its glyph.
|
|
357
406
|
Every text and focus-ring pair is checked against `--aqmx-surface`, the opaque surface the explorer pane paints under the tree in the split and in the sheet alike, and against each tint. Lines and glyphs use `--aqmx-tree-line`, which reaches 3:1 against every row state in both schemes (the glyph shows whether a folder is expanded).
|
|
407
|
+
The tree's type icons, which `@aiquants/directory-tree` paints from its palette (every pair of its `FILE_ICON_PAIRS`, and `icon` and `iconSelected` of its `MARK_PAIRS`), reach 3:1 against `--aqmx-surface` and each tint in both schemes; a unit test reads the pairs from directory-tree's exports and checks each one.
|
|
358
408
|
The tree draws them in the colour the browser resolves for the token on a hidden probe, never in the token's text, because a canvas resolves a system colour once and keeps it. The colour is read at run time and again when `theme` changes, when forced colors turn on or off and when the preferred colour scheme changes (which is how the browser reports a switch between a light and a dark forced palette), so a host's override recolours them; without the stylesheet no lines are drawn.
|
|
359
409
|
With the tree lines turned off (a tree setting), the tree draws each expand glyph in its row instead, in `--aqmx-tree-line` as well: the explorer passes the token as the glyph's own colour (`@aiquants/directory-tree`'s `expandIconStyle`), so it follows `theme` and a host's override of the token, not the tree's own palette.
|
|
360
410
|
|
|
@@ -7,25 +7,36 @@ This page is part of the host-facing contract of `@aiquants/markdown-explorer`;
|
|
|
7
7
|
- `locale` is the UI language, `"en"` (the default) or `"ja"` — never a BCP 47 region tag. `"ja-JP"`, `"EN"` and any other value throw a `RangeError` on the first render, so a mistyped locale is found in development instead of silently showing English.
|
|
8
8
|
- The catalogs are `MARKDOWN_EXPLORER_LABEL_CATALOGS.en` and `MARKDOWN_EXPLORER_LABEL_CATALOGS.ja`, frozen objects with the same keys; `MARKDOWN_EXPLORER_LABEL_KEYS` lists the keys in declaration order.
|
|
9
9
|
- The explorer passes its document-viewer strings to `@aiquants/markdown`, which names every control and status text of the viewer with them, so the viewer follows the same language:
|
|
10
|
-
its status texts (`viewerLoading`, `viewerErrorPrefix`, `viewerErrorTitle`, `viewerMissingImage`, and `viewerBlockFailed`, the notice in place of a block that cannot render), its toolbar's buttons (`viewerSelectAlign`, `viewerSelectStyle`, `viewerOpenToc`), the alignment
|
|
10
|
+
its status texts (`viewerLoading`, `viewerErrorPrefix`, `viewerErrorTitle`, `viewerMissingImage`, and `viewerBlockFailed`, the notice in place of a block that cannot render), its toolbar's buttons (`viewerSelectAlign`, `viewerSelectStyle`, `viewerOpenToc`), the alignment menu (`viewerAlignTitle`, `viewerAlignLeft`, `viewerAlignCenter`, `viewerAlignRight`, `viewerPinAlign`, `viewerUnpinAlign`),
|
|
11
|
+
the display popover (`viewerStyleTitle`, `viewerPinStyle`, `viewerUnpinStyle`, with `viewerStyleSectionTitle` heading its style section; the width and colour sections' `viewerMeasureTitle`, `viewerMeasureFill`, `viewerMeasureReading`, `viewerColorsTitle`, `viewerColorsDefault`, `viewerColorsSepia`, `viewerColorsDarkLowGlare` and `viewerColorsHighContrast` are passed too, though the explorer shows only the style section), the table of contents (`viewerTocTitle`, which also names its navigation, `viewerPinToc`, `viewerUnpinToc`)
|
|
11
12
|
and every Mermaid diagram's controls (`viewerMermaidInteractionMode` for the mouse-interaction menu and its button, `viewerMermaidModeNone`, `viewerMermaidModeZoom`, `viewerMermaidModePan`, `viewerMermaidModePanShift`, `viewerMermaidModeBoth`, `viewerMermaidModeBothShift` for its modes, `viewerMermaidInteractionModeTouch` for the same menu and button under a coarse pointer, `viewerMermaidModeNoneTouch`, `viewerMermaidModeZoomTouch`, `viewerMermaidModePanTouch`, `viewerMermaidModeBothTouch` for its touch items, `viewerMermaidZoomIn`, `viewerMermaidZoomOut`, `viewerMermaidResetView`,
|
|
12
|
-
`viewerMermaidPanUp`, `viewerMermaidPanDown`, `viewerMermaidPanLeft`, `viewerMermaidPanRight` for the buttons that move the view while the drawing overflows its frame, `viewerMermaidRetry`, `
|
|
13
|
+
`viewerMermaidPanUp`, `viewerMermaidPanDown`, `viewerMermaidPanLeft`, `viewerMermaidPanRight` for the buttons that move the view while the drawing overflows its frame, `viewerMermaidRetry`, `viewerMermaidLoading` while the diagram is drawn, `viewerMermaidInitializationFailed`, `viewerMermaidRenderFailed` and `viewerMermaidEmptyDrawing` for the reasons it could not be drawn (after `viewerErrorPrefix`, which the diagram shares with the viewer),
|
|
14
|
+
`viewerMermaidDiagram`, the name of the diagram's focusable frame, `viewerMermaidFullscreen`, `viewerMermaidExitFullscreen` and `viewerMermaidFullscreenDialog` for the full-screen toggle, the same toggle while the diagram is shown full screen, and the full-screen dialog's name,
|
|
15
|
+
`viewerMermaidSource` for the toggle that shows the diagram's source in place of the drawing, `viewerMermaidSourceRegion` naming the region that holds the source (after the drawing's title when it has one), `viewerMermaidCopySource`, `viewerMermaidCopiedSource` and `viewerMermaidCopySourceFailed` for that region's Copy button and its outcomes,
|
|
16
|
+
and the names of the diagram types, which the drawing carries as its role description in place of the type code Mermaid writes: `viewerMermaidTypeFlowchart` for a `flowchart`, `viewerMermaidTypeSequence` for a `sequence` and a `viewerMermaidType…` key for each of the 31 types the viewer names),
|
|
13
17
|
the toolbar of a storage SVG image that stands alone in a paragraph (`viewerSvgImageToolbar` naming the toolbar, `viewerSvgImageSource` its Source toggle, `viewerSvgImageSourceRegion` the shown SVG, `viewerSvgImageLoading`, `viewerSvgImageFailed` and `viewerSvgImageRetry` while it is read, `viewerSvgImageTruncated` under a file cut at `textMaxBytes`, `viewerSvgImageCopy`, `viewerSvgImageCopied` and `viewerSvgImageCopyFailed` for its Copy button and its outcomes while the source shows, and `viewerSvgImageCopyImage`,
|
|
14
|
-
`viewerSvgImageCopiedImage` and `viewerSvgImageCopyImageFailed` for its Copy button and its outcomes while the image shows, and `viewerSvgImageFullscreen`, `viewerSvgImageExitFullscreen` and `viewerSvgImageFullscreenDialog` for its full-screen toggle, the same toggle while the image is shown full screen, and the full-screen dialog's name)
|
|
18
|
+
`viewerSvgImageCopiedImage` and `viewerSvgImageCopyImageFailed` for its Copy button and its outcomes while the image shows, and `viewerSvgImageFullscreen`, `viewerSvgImageExitFullscreen` and `viewerSvgImageFullscreenDialog` for its full-screen toggle, the same toggle while the image is shown full screen, and the full-screen dialog's name),
|
|
19
|
+
the copy buttons of the code blocks (`viewerCodeBlockCopy` naming the button, `viewerCodeBlockCopied` and `viewerCodeBlockCopyFailed` announcing its outcomes) and of the display formulas (`viewerDisplayMathCopy`, `viewerDisplayMathCopied` and `viewerDisplayMathCopyFailed`)
|
|
15
20
|
and the titles of embedded frames (`viewerEmbeddedVideo` and `viewerEmbeddedPost` after a provider's name, as in "YouTube: embedded video", and `viewerEmbeddedFrame` before the host of an iframe written in a document without a title).
|
|
16
|
-
|
|
21
|
+
The explorer names the UI language as the viewer's `labelsLang`, so every element that bears one of these labels carries it as its `lang`, inside a document too: the content of a Markdown or text document carries the document's language (its `lang`), and a control the viewer draws there keeps the UI language.
|
|
22
|
+
So does an inert link's reason (its `title`), while the link's own text keeps the document's language.
|
|
17
23
|
- Every ```spreadsheets table's labels are `@aiquants/markdown`'s own, derived rather than copied: each label of its table block (`SPREADSHEET_BLOCK_LABEL_CATALOGS` of `@aiquants/markdown/code-blocks`, see its README) is a key prefixed with `viewerSpreadsheet` (`zoomIn` → `viewerSpreadsheetZoomIn`, `cellAnnouncement` → `viewerSpreadsheetCellAnnouncement`), its built-in text is the block's catalog of the UI language, and its placeholders are the block's (`SPREADSHEET_BLOCK_LABEL_PLACEHOLDERS`).
|
|
18
24
|
The explorer passes the viewer only the table labels a host replaced, so every other one keeps the block's text marked with the block's language, and the grid takes `locale` as its own locale, which picks the language of its own catalog, its data-validation messages and its scroll bar.
|
|
19
|
-
A label added to the block becomes a key of the explorer with it. Where the viewer's own built-in label is in a catalog's language, the catalog repeats it word for word (the English catalog the viewer's English labels, such as `Display
|
|
25
|
+
A label added to the block becomes a key of the explorer with it. Where the viewer's own built-in label is in a catalog's language, the catalog repeats it word for word (the English catalog the viewer's English labels, such as `Display` and `Zoom In`; the Japanese catalog its Japanese ones, such as `目次を開く`), writing a full-width form in half-width (`拡大縮小+移動 (左ドラッグ)` for the viewer's `拡大縮小+移動 (左ドラッグ)`).
|
|
20
26
|
- The explorer passes `treeEntryKindDirectory` and `treeEntryKindFile` (the kind words in the rows' accessible names) and `treeScrollUp`, `treeScrollDown`, `treeScrollToTop` and `treeScrollToBottom` (the tree's scroll bar) to `@aiquants/directory-tree`.
|
|
21
27
|
- The explorer passes every string the multi view's drag-and-drop layout shows to `@aiquants/drag-drop-panels`: the panel headers' buttons (`panelMoreActions` for the overflow button, `panelMove`, `panelSwitchToCustomDrag`, `panelSwitchToNormalDrag`, `panelHide`, `panelMaximize`, `panelRestore`, `panelClose`), the items of their move menus (`panelMovePreviousColumn`, `panelMoveNextColumn`, `panelMoveUp`, `panelMoveDown`; the items of the overflow menu keep the names of the moves and the buttons they stand for) and the custom drag mode's badge (`panelCustomDragBadge`),
|
|
22
28
|
the move announcements (`panelMoved`, `panelMoveUnavailable`), a touch or pen drag's lift and cancel announcements (`panelDragStarted`, `panelDragCancelled`), the bar of hidden panels (`hiddenPanelsTitle`)
|
|
23
29
|
, a hidden panel's stand-in while a panel is dragged (`hiddenPanelBadge`, `hiddenPanelNotice`), the drop placeholders (`panelDropHere`), an empty column's text (`multiColumnEmpty`) and the name of each column's region (`multiColumnRegion`).
|
|
24
30
|
The stage never lets the reader resize its columns, so the layout renders no column resize handle and the catalog has no key for that handle's name. A label the layout receives carries no `lang` of its own, so it is read in the page's language, like the explorer's other strings.
|
|
31
|
+
- The explorer passes the texts of the placeholder `@aiquants/resize-panels` draws over a split whose panels cannot fit it to both of its splits (the tree view's explorer and document, and the editor and the preview, side by side or one above the other):
|
|
32
|
+
`panelGroupMinimumExceededSummary` and `panelGroupMinimumExceededDetail` when the panels' minimum sizes add up to more than the split's length, `panelGroupMaximumInsufficientSummary` and `panelGroupMaximumInsufficientDetail` when their maximum sizes add up to less.
|
|
33
|
+
It always passes all four, so the package's rule that a reason's summary and detail come as a pair holds whichever of them a host replaces. The English catalog repeats the package's built-in texts word for word, and a label the split receives carries no `lang` of its own, so it is read in the page's language, like the layout's.
|
|
25
34
|
- `treeRegion` names the tree itself, apart from `explorerRegion`, which names the explorer's landmark (and the sheet on narrow frames).
|
|
26
35
|
- `refreshTreeLabel` is the visible text of the explorer's Refresh tree button and `refreshDocumentLabel` that of the page views' (tree and single) Refresh document button, each also its button's accessible name; `refreshTree` and `refreshDocument` are their tooltips.
|
|
27
36
|
A multi-view panel's Refresh document is icon-only, and `refreshDocumentNamed(name)` (the panel title) is its accessible name and its tooltip. A successful reload is announced with `treeRefreshed` or `documentRefreshed(name)` — a document's once the part its content reads itself (a table file's table, a document shown as written) is read again too. A failed one is shown with `treeRefreshFailed(reason)` (an alert in the explorer)
|
|
28
37
|
or `documentRefreshFailed(reason)` (the bar's notice, which the announcer also speaks, for a failure of the document's answer or of that part's reading), where `reason` is the failure's title (the matching `failure…Title` label).
|
|
38
|
+
- The notices above a document are `documentChangedElsewhere(name)`, the shown document changed outside the explorer (under `hostChangePolicy` `"notify"`, or when the reading again under `"reload"` failed), `mediaLoadFailed(name)` for a medium that could not be loaded and `mediaUnplayable(name)` for one that cannot be played, or, for two or more, `mediaLoadFailedCount(count)` and `mediaUnplayableCount(count)`;
|
|
39
|
+
`name` is the document's name or the medium's file name. The changed notice and the notice of media that could not be loaded have a Reload button, `reload`, which reads the document or the media again. A document read again under `"reload"` is announced with `documentReloadedAfterChange(name)`.
|
|
29
40
|
- `showMarkupLabel` is the visible text of the page views' Source toggle beside Refresh document (shown for a Markdown document, an SVG image and a CSV or TSV table file), also its accessible name, and `showMarkup` its tooltip (`showSvgMarkup` for an SVG image, `showSpreadsheetMarkup(format)` with `CSV` or `TSV` for a table file); a multi-view panel's toggle is icon-only, and `showMarkupNamed(name)` (the panel title) is its accessible name and its tooltip.
|
|
30
41
|
The toggle's pressed state, not its name, tells whether the source shows. `markupLoading` is the screen-reader text while the source loads; a source that cannot be read is announced with `documentFailed(name, title)`, like a document, and a source that replaces that failure on a retry with `documentShown(name)` in a page view; a reading again that fails keeps the source, and a refresh reports it with `documentRefreshFailed(reason)` in the bar; a cut source shows `textTruncated`, like a cut text file.
|
|
31
42
|
- A table file's view names its table after the file and its full-screen table with `spreadsheetFullscreen(name)`; its other table labels are the ```spreadsheets table's (below), a host's replacements included.
|
|
@@ -35,7 +46,10 @@ This page is part of the host-facing contract of `@aiquants/markdown-explorer`;
|
|
|
35
46
|
- A workbook's view names a sheet's table after the file and the sheet with `spreadsheetSheetName(name, sheet)` (its full-screen table with `spreadsheetFullscreen` of that name) and its tabs with `spreadsheetSheets(name)`, each tab named by its sheet as the workbook writes it.
|
|
36
47
|
`spreadsheetSheetLoading` is the screen-reader text while a sheet is read for the first time; a sheet without data shows `spreadsheetSheetEmpty`. Its notes are `spreadsheetUnshownSheets(count)` (sheets left out: hidden, or without a table), `spreadsheetUnlistedSheets(count)` (the number of sheets listed, when the workbook has more than the reader lists) and `spreadsheetWorkbookFirstSheet` (the first sheet's text shown instead of the workbook);
|
|
37
48
|
in place of the tabs or a sheet's table, `spreadsheetWorkbookEncrypted` (a password-protected workbook), `spreadsheetNotWorkbook` (bytes that are no workbook the explorer reads, a legacy `.xls` included) or `spreadsheetWorkbookTooLarge` (past `spreadsheets.maxWorkbookBytes` or the reader's limit for one part).
|
|
38
|
-
- `copyText` is the accessible name and tooltip of the icon-only Copy the text button in the header of a text read whole (a text file, or a Markdown document shown as written). A copy is announced with `copiedText`, or with `copyTextFailed` when the browser has no asynchronous clipboard
|
|
49
|
+
- `copyText` is the accessible name and tooltip of the icon-only Copy the text button in the header of a text read whole (a text file, or a Markdown document shown as written). A copy is announced with `copiedText`, or with `copyTextFailed` when the browser has no asynchronous clipboard, refuses the write or has a clipboard that throws; for 2 seconds the outcome's label is also the button's tooltip, while its name stays `copyText`.
|
|
50
|
+
- An `unauthorized` failure asks the reader to reload the page (`failureUnauthorizedBody` with the `reloadPage` button) unless the host passes `onSessionEnded`; then `accountState` picks its body and its button: `failureUnauthorizedSignInBody` and `signInAgain` while the account is `"signed-in"` (the default; its session ended), `failureUnauthorizedSignedOutBody` and `signIn` while it is `"signed-out"`.
|
|
51
|
+
Neither button names a service, so a host that signs in to a named one says so through `labels`.
|
|
52
|
+
- Under `confirmUnversionedSaves`, a save that would write a change to a source that keeps no previous versions asks first: `unversionedSaveTitle`, `unversionedSaveBody` (the previous content cannot be restored), `unversionedSaveConfirm`, which saves, and `unsavedStay`, which goes back to editing.
|
|
39
53
|
- `switchToTree` and `switchToMulti` name their destination with the README's view names ("Open in the tree view" / "ツリービューで開く", "Open in the multi-panel view" / "マルチビューで開く"); no label names the single view, which no control inside the explorer opens.
|
|
40
54
|
|
|
41
55
|
## Overrides
|
|
@@ -56,11 +70,14 @@ const HANDBOOK_LABELS = {
|
|
|
56
70
|
`expandAllDone(opened, failed, complete)` (the end of a press that no limit stopped; `complete` is whether every folder is open at the end, false when the reader closed one during the press, so the sentence then claims nothing about the rest; nothing opened, nothing failed and complete means every folder was already open), `expandAllFolderLimit(opened, limit, expandAll)` (a press stopped at `expandAll.maxFolders`;
|
|
57
71
|
`expandAll` is the Expand all button's own label, so a host that renames the button keeps the invitation to press it again consistent), `expandAllDepthLimit(opened, depth)` (a press that left folders deeper than `expandAll.maxDepth` closed), `loopFolderName(name)` (the name of a loop row, a folder met again among its own ancestors), `documentFailed(name, title)` (a document that could not be shown:
|
|
58
72
|
the path's last segment and the failure's title — the text of the matching `failure…Title` label, not the reason's code), `imageZoomLevel(percent)`, `treeRefreshFailed(reason)`, `documentRefreshed(name)`, `documentRefreshFailed(reason)`, `refreshDocumentNamed(name)` (a multi-view panel's icon-only Refresh document: its accessible name and tooltip, `name` being the panel title),
|
|
59
|
-
`showMarkupNamed(name)` (a multi-view panel's icon-only Source toggle: its accessible name and tooltip, `name` being the panel title), `panelLimit(max)`, `panelOpened(name)`, `panelClosed(name)`, `panelAlreadyOpen(name)`, `panelHidden(name)`, `panelShown(name)`, `panelMaximized(name)`, `panelRestored(name)
|
|
60
|
-
|
|
73
|
+
`showMarkupNamed(name)` (a multi-view panel's icon-only Source toggle: its accessible name and tooltip, `name` being the panel title), `documentMaximized(name)` and `documentRestored(name)` (the tree view's document maximized and restored, `name` being the last segment of the shown document's path, or of the folder's whose README shows), `panelLimit(max)`, `panelOpened(name)`, `panelClosed(name)`, `panelAlreadyOpen(name)`, `panelHidden(name)`, `panelShown(name)`, `panelMaximized(name)`, `panelRestored(name)`,
|
|
74
|
+
`documentChangedElsewhere(name)` and `documentReloadedAfterChange(name)` (a shown document that changed outside the explorer), `mediaLoadFailed(name)`, `mediaLoadFailedCount(count)`, `mediaUnplayable(name)` and `mediaUnplayableCount(count)` (the media notices: one medium by its file name, two or more by their count) — so each language can place the value where its grammar needs it.
|
|
75
|
+
- The labels another package fills itself are templates instead, strings whose `{name}` placeholders mark where each value goes. Those of `@aiquants/drag-drop-panels` are `panelMoved` (`{title}` the panel's name, `{column}` its visible column, `{position}` its place among that column's shown panels), `panelMoveUnavailable` (`{title}`, and `{move}` the name of the move, one of the `panelMove…` labels), `panelDragStarted` and `panelDragCancelled` (`{title}`) and `multiColumnRegion` (`{column}`); columns and positions count from 1.
|
|
76
|
+
Those of `@aiquants/resize-panels` are `panelGroupMinimumExceededDetail` (`{required}` the panels' minimum sizes' total, rounded up, and `{available}` the split's length, rounded down) and `panelGroupMaximumInsufficientDetail` (`{total}` their maximum sizes' total, rounded down, and `{needed}` the split's length, rounded up), all in CSS pixels.
|
|
61
77
|
So are the table labels `@aiquants/markdown` fills, with the block's placeholders (`viewerSpreadsheetSize` with `{rows}` and `{cols}`, `viewerSpreadsheetCellAnnouncement` with `{cell}` and `{value}`, and so on; `SPREADSHEET_BLOCK_LABEL_PLACEHOLDERS` lists them), and `viewerSvgImageSourceRegion` and `viewerSvgImageFullscreenDialog`, whose `{name}` is the SVG image's name (its alternative text, else its file name).
|
|
62
|
-
`MARKDOWN_EXPLORER_LABEL_TEMPLATES` lists each template's placeholders,
|
|
63
|
-
- `labels` must be a plain object. An unknown key throws a `RangeError` that lists the valid keys, a value of the wrong type (a string where a function is expected, or the reverse) throws a `TypeError`, and a blank string throws a `RangeError`, because a blank name is neither shown nor announced.
|
|
78
|
+
`MARKDOWN_EXPLORER_LABEL_TEMPLATES` lists each template's placeholders, which are the only braces a template holds; braces in every other label are literal text.
|
|
79
|
+
- `labels` must be a plain object. An unknown key throws a `RangeError` that lists the valid keys, a value of the wrong type (a string where a function is expected, or the reverse) throws a `TypeError`, and a blank string throws a `RangeError`, because a blank name is neither shown nor announced.
|
|
80
|
+
A template that uses a placeholder its key does not offer (`{name}` for `{title}`, say) or holds a brace outside a placeholder (an unclosed `{title`, say) throws a `RangeError` naming the placeholders it accepts, because a placeholder that is never filled would be read out as it is. A key set to `undefined` keeps the catalog's string.
|
|
64
81
|
- The overrides are compared by value, key by key: writing `labels={{ … }}` inline does not re-render the explorer on every render of the host, but a function created inline is a new value each time — hoist it, or memoize the object.
|
|
65
82
|
|
|
66
83
|
## Formatting
|
|
@@ -69,6 +86,7 @@ Counts and percentages are formatted by the label functions themselves, so a hos
|
|
|
69
86
|
The sort order's menu row cycles through "Source order", "Name A→Z", "Name Z→A", "Modified old→new" and "Modified new→old" in English and 「取得順」「名前の昇順」「名前の降順」「更新日時の昇順 (古い順)」「更新日時の降順 (新しい順)」 in Japanese (`sortNative`, `sortAscending`, `sortDescending`, `sortOldest`, `sortNewest`). The Modified orders compare the entries' `modifiedAt`, put the entries whose time the source does not know last in both directions, and break equal or unknown times by name, A to Z.
|
|
70
87
|
Folders keep their place among the files unless the folder placement puts them first or last; its menu row reads "Folders: Mixed / First / Last" in English and 「フォルダーの位置: 混ぜる / 先に / 後に」 in Japanese (`settingFolderPlacement`, `folderPlacementMixed`, `folderPlacementFirst`, `folderPlacementLast`).
|
|
71
88
|
A folder's READMEs keep their place in the sort unless the README placement puts them before or after the other files; its menu row reads "README: Mixed / First / Last" in English and 「README の位置: 混ぜる / 先に / 後に」 in Japanese (`settingReadmePlacement`, `readmePlacementMixed`, `readmePlacementFirst`, `readmePlacementLast`). A folder of the tree view without a README says so with `folderReadmeMissing(name)` ("guide has no README." / 「guide には README がありません。」), `name` being the folder's last path segment. The reveal's switch is `settingRevealDocument` ("Reveal the open document", 「開いた文書をツリーで表示」).
|
|
89
|
+
The switch right after it, which ties the tree view's READMEs to its folders' opening and closing, is `settingShowFolderReadme` ("Show folder READMEs", 「フォルダーの README を表示」).
|
|
72
90
|
|
|
73
91
|
## Strings outside the catalog
|
|
74
92
|
|