@aiquants/markdown-explorer 0.36.0 → 0.37.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +112 -0
- package/README.md +77 -11
- package/dist/{EditSurface-BCFJRyIM.js → EditSurface-BvwgM4lC.js} +250 -245
- package/dist/EditSurface-Ce4bpuvh.cjs +6 -0
- package/dist/ExplorerSplit-DBUFhlo_.cjs +2 -0
- package/dist/ExplorerSplit-DKpqQBsQ.js +1619 -0
- package/dist/{MultiLayout-Bo9LAXiY.cjs → MultiLayout-BfGxy2pf.cjs} +1 -1
- package/dist/{MultiLayout-Dy5TIC2t.js → MultiLayout-CVj5iam0.js} +22 -22
- package/dist/{NativeScrollBar-Bj-LKej0.cjs → NativeScrollBar-BQpaWt45.cjs} +1 -1
- package/dist/{NativeScrollBar-DpZMYhmf.js → NativeScrollBar-BkZPkphH.js} +2 -2
- package/dist/{TreeLayout-DsSKW_Qj.js → TreeLayout-B83wJ2CL.js} +2 -2
- package/dist/{TreeLayout-T8sc_wg7.cjs → TreeLayout-Df4HLMP-.cjs} +1 -1
- package/dist/client/MarkdownExplorer.d.cts +4 -5
- package/dist/client/MarkdownExplorer.d.ts +4 -5
- package/dist/client/hostContract.d.cts +1 -8
- package/dist/client/hostContract.d.ts +1 -8
- package/dist/core/labels.d.cts +0 -9
- package/dist/core/labels.d.ts +0 -9
- package/dist/explorerCore-DivWkFQF.cjs +1 -0
- package/dist/{explorerCore-B3RGmMG6.js → explorerCore-EkU0mwdW.js} +310 -308
- package/dist/index-Bz-n0dl1.cjs +18 -0
- package/dist/{index-D0l_BJqb.js → index-CVnGqEmh.js} +2447 -2430
- package/dist/index.cjs +1 -1
- package/dist/index.d.cts +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +54 -55
- package/dist/{merge-BwcqBd4c.js → merge-BGr72noP.js} +1 -1
- package/dist/{merge-Dckw7r9T.cjs → merge-hFiGx_ND.cjs} +1 -1
- package/dist/server/anonymous.d.cts +2 -2
- package/dist/server/anonymous.d.ts +2 -2
- package/dist/server/ports.d.cts +5 -2
- package/dist/server/ports.d.ts +5 -2
- package/dist/server.cjs +1 -1
- package/dist/server.d.cts +1 -1
- package/dist/server.d.ts +1 -1
- package/dist/server.js +12 -12
- package/dist/serverCore.cjs +1 -1
- package/dist/serverCore.d.cts +1 -1
- package/dist/serverCore.d.ts +1 -1
- package/dist/serverCore.js +1 -1
- package/dist/styles/markdown-explorer.css +1 -1
- package/dist/{tapScrollCircle-smKLgRa2.js → tapScrollCircle-BTCGTQ8T.js} +1 -1
- package/dist/{tapScrollCircle-DyLInGck.cjs → tapScrollCircle-DDwYa54Q.cjs} +1 -1
- package/docs/behavior/dom-hooks.md +8 -1
- package/docs/behavior/hosting.md +1 -1
- package/docs/behavior/localization.md +2 -2
- package/docs/behavior/security.md +2 -2
- package/docs/behavior/url-contract.md +2 -2
- package/package.json +6 -4
- package/dist/EditSurface-B70iRFkG.cjs +0 -6
- package/dist/ExplorerSplit-BNrHrIus.cjs +0 -2
- package/dist/ExplorerSplit-Bgccz2nm.js +0 -1589
- package/dist/explorerCore-CUkyKtm8.cjs +0 -1
- package/dist/index-lpL7GltU.cjs +0 -18
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,117 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## Unreleased
|
|
4
|
+
|
|
5
|
+
### Fixed
|
|
6
|
+
|
|
7
|
+
- **A data request answered 401 no longer reloads the page data (hosts, readers).** The explorer ran the page loader
|
|
8
|
+
again whenever a data request answered 401, so a host whose loader sends a signed-out reader to sign in (as
|
|
9
|
+
`signedOutPage` usually does) moved the reader there on its own, away from what they were doing. Now nothing moves
|
|
10
|
+
and nothing is erased: the place that met the 401 draws the host's presenter's node, whose sign-in action is the
|
|
11
|
+
host's (with auth-core's view, `sign-in-again` for a host that keeps no work, `sign-in-again-in-new-window` for one
|
|
12
|
+
that does), and the reader's work stays. A response carrying another reader's scope still erases what the explorer
|
|
13
|
+
remembers and reloads the page data.
|
|
14
|
+
- **The host's presenter gets one node per access failure (hosts).** A place that met a new access failure while it
|
|
15
|
+
still showed the previous one (the editor's preview answering 401 to two drafts in a row, a table file whose failure
|
|
16
|
+
view read again and failed again) kept the presenter's node of the previous failure and only drew it again, so a
|
|
17
|
+
presenter keeping state for one failure in its node (a notice without a retry that it hides once the reader signed
|
|
18
|
+
in again) carried that state over to the next failure. The node is now keyed by its occurrence, as
|
|
19
|
+
`@aiquants/auth-core`'s `AccessFailurePresenter` asks of a package: it stays mounted while the place shows the same
|
|
20
|
+
failure and is mounted anew for the next one, even one of the same kind at the same place. A node the open sheet
|
|
21
|
+
moves is still mounted again in its new place, with the same occurrence object.
|
|
22
|
+
- **Copy permalink's access failure does not come back after an edit (readers).** The document's bar hid the node of
|
|
23
|
+
Copy permalink's access failure while the document was edited and drew it again, as a new occurrence, once the edit
|
|
24
|
+
ended, so a notice its presenter had hidden after the reader signed in again showed again. The bar now takes the
|
|
25
|
+
failure down when an edit starts, as it does when it moves to another document, and does not show it again; the
|
|
26
|
+
next press shows a fresh outcome.
|
|
27
|
+
|
|
28
|
+
### Tests
|
|
29
|
+
|
|
30
|
+
- `tests/support/accessFailures.tsx`: a presenter stand-in that counts the nodes React mounted
|
|
31
|
+
(`createMountCountingAccessFailure`), drawing the same plain node as the recording one.
|
|
32
|
+
- `tests/components/accessFailure.test.tsx`: the node stays mounted while the same failure is drawn again (a retry
|
|
33
|
+
function that changes included) and is mounted anew for the next failure of the same kind and place (`retry: null`
|
|
34
|
+
included), in place and in the open sheet; a node the sheet moves is mounted again with the same occurrence object;
|
|
35
|
+
the sheet's store keeps every hold as an entry of its own.
|
|
36
|
+
- `tests/components/treeLoading.test.tsx`: a retry of the stopped folders that the presenter calls outside a press, with
|
|
37
|
+
answers that come at once, mounts a new node, with a new occurrence, for the folders that stop again.
|
|
38
|
+
- `tests/components/documentPermalink.test.tsx`: an edit takes Copy permalink's access failure down for good, and a
|
|
39
|
+
failure answered while the document is edited never shows.
|
|
40
|
+
- `tests/components/markdownExplorer.test.tsx`, `tests/unit/stores.test.ts`, `tests/unit/dataClient.test.ts`: a 401
|
|
41
|
+
reports no scope, erases nothing, and neither reloads the page data nor moves the location.
|
|
42
|
+
|
|
43
|
+
## 0.37.0 (2026-11-15) — Access failures: the host's presenter words and draws every 401 and 403, and a forbidden reader gets auth-core's 403
|
|
44
|
+
|
|
45
|
+
### Breaking
|
|
46
|
+
|
|
47
|
+
- **Access failures go to the host's presenter (`accessFailure`, required; hosts, readers).** `<MarkdownExplorer>`
|
|
48
|
+
takes `accessFailure`, an `AccessFailurePresenter<ReactNode>` of `@aiquants/auth-core` (a new peer, `^0.8.0`), and
|
|
49
|
+
words neither `unauthorized` nor `forbidden` itself any more: each place that meets one (a document, the tree and
|
|
50
|
+
its refresh, a folder's children, a document's refresh, its source, the editor's text, a revision, the server's
|
|
51
|
+
preview of a draft, a save, Copy permalink's ID) hands the presenter an occurrence
|
|
52
|
+
`{ kind, place, deniedSentence, retry }` and draws the node it returns inside the place's own hooks. A place hands
|
|
53
|
+
the same frozen occurrence for as long as it shows the same failure; `retry` repeats the place's work once the reader
|
|
54
|
+
is signed in again (`null` for Copy permalink and the preview), and `deniedSentence` is `null` except for the
|
|
55
|
+
`forbidden` answer of an ID URL, which carries `documentIdForbidden`. The explorer's announcer says nothing of an
|
|
56
|
+
access failure, since the presenter's node speaks for itself. Anything but a function throws a `TypeError` at the
|
|
57
|
+
first render. Migration: pass a presenter, for example one that draws auth-core's
|
|
58
|
+
`accessFailureView(occurrence, { keepsWork: true }, resolveAccessFailureLabels(locale))` (the README's quick start
|
|
59
|
+
and [Access failures](README.md#access-failures)).
|
|
60
|
+
- **The props for a session that ended are gone (hosts).** `onReload`, `onSessionEnded` and `accountState` are no longer
|
|
61
|
+
read, and `EXPLORER_ACCOUNT_STATES` and `ExplorerAccountState` are no longer exported. Migration: drop them; signing
|
|
62
|
+
in again is the presenter's action, after which it calls the occurrence's `retry`.
|
|
63
|
+
- **Nine label keys are removed (hosts).** `failureUnauthorizedTitle`, `failureUnauthorizedBody`,
|
|
64
|
+
`failureUnauthorizedSignInBody`, `failureUnauthorizedSignedOutBody`, `failureForbiddenTitle`, `failureForbiddenBody`,
|
|
65
|
+
`reloadPage`, `signInAgain` and `signIn`: the catalogs hold no words for an access failure, and `labels` that names
|
|
66
|
+
one throws, as for any unknown key. Migration: drop them from `labels` and word access failures in the presenter.
|
|
67
|
+
- **`signedOutPage` takes `{ request, url }` (hosts).** Its first argument is the new `ExplorerPageRouteArgs`: the
|
|
68
|
+
request and the URL React Router normalized for the loader (without the single-fetch `.data` suffix and `_routes`),
|
|
69
|
+
so `url.pathname + url.search` is the page to return to after sign-in on a client navigation too, where
|
|
70
|
+
`request.url` names the `.data` request. Migration: `signedOutPage: ({ request, url }, headers) => …`;
|
|
71
|
+
`anonymousAccess` follows.
|
|
72
|
+
- **`forbiddenPage` is removed: a forbidden reader gets auth-core's refusal (hosts).** For a reader `authenticate`
|
|
73
|
+
answers `forbidden` for, the page loader throws `accessFailureResponse("forbidden")` with the authentication's
|
|
74
|
+
headers: a 403 whose body is `{ "accessFailure": "forbidden" }` and whose `Cache-Control` is `no-store` (the
|
|
75
|
+
explorer's own 403 carried `private, no-store`), for the page route's error boundary. The exported `headers` carry
|
|
76
|
+
that `Cache-Control` to the HTML document and the single-fetch data while the page route has its own
|
|
77
|
+
`ErrorBoundary`; the `Content-Type` stays the entry's and React Router's. auth-core throws a `TypeError` when the
|
|
78
|
+
authentication's headers set `Content-Type` or `Cache-Control`. Migration: remove `forbiddenPage`, and draw the
|
|
79
|
+
refusal in the page route's `ErrorBoundary` with the presenter:
|
|
80
|
+
`accessFailureKindOfStatus(error.status)` of an `isRouteErrorResponse` error, as the occurrence
|
|
81
|
+
`{ kind, place: "page", deniedSentence: null, retry: null }`.
|
|
82
|
+
|
|
83
|
+
### Changed
|
|
84
|
+
|
|
85
|
+
- **Every hook that carries `data-aqmx-failure` keeps it for an access failure (hosts).** The element holds the
|
|
86
|
+
presenter's node instead of the explorer's callout: no callout, tone, role or text of the explorer's, whatever it
|
|
87
|
+
holds for the explorer's own reasons (`markdown-explorer-refresh-failure` and `markdown-explorer-tree-failure` are no
|
|
88
|
+
`role="alert"` then). A host's `renderTreeFailure` still replaces what the tree failure holds, and `undefined` keeps
|
|
89
|
+
the presenter's node. `data-aqmx-tone` stays `danger` for `failed` and `warning` for the other reasons of the
|
|
90
|
+
explorer's own.
|
|
91
|
+
- **The ID URL a reader may not open (readers).** Its failure is the presenter's node, with `documentIdForbidden` as the
|
|
92
|
+
sentence of what was denied, instead of a callout whose body that label was.
|
|
93
|
+
- **A save or a Copy permalink press refused by an access failure (readers).** A save leaves the status of the unsaved
|
|
94
|
+
draft (`draftUnsaved`, with `data-aqmx-save="failed"`) and shows the presenter's node below the bar's row
|
|
95
|
+
(`markdown-explorer-save-access-failure`), whose retry saves again without asking `confirmUnversionedSaves` again.
|
|
96
|
+
A permalink press shows its node in the bar (`markdown-explorer-permalink-access-failure`) and is not announced: the
|
|
97
|
+
button stays `idle`, the node shows the latest press's failure only, and it goes at the next press and when the bar
|
|
98
|
+
moves to another document, while the document is edited it is hidden, and it is drawn again (a new occurrence) once
|
|
99
|
+
the editing ends.
|
|
100
|
+
|
|
101
|
+
### Added
|
|
102
|
+
|
|
103
|
+
- **One node for the lazy folders an access failure stops (readers).** The folders whose children meet an access
|
|
104
|
+
failure, one after another, share one node of the presenter above the tree
|
|
105
|
+
(`markdown-explorer-folder-access-failure`, the place `read`), one occurrence while any of them stays stopped, whose
|
|
106
|
+
retry loads them all again; the node goes once none is stopped. The rows keep `data-aqmx-children="failed"` and their
|
|
107
|
+
Try again, the announcer names none of the folders, and the end of an Expand all press counts them among the folders
|
|
108
|
+
that could not be loaded, so the folders one press stops at once share one node that speaks once.
|
|
109
|
+
- **Access failures behind the open sheet move into it (readers).** While the explorer's sheet is open (a native modal
|
|
110
|
+
`dialog` on a frame too narrow for the split, so the content behind it is inert and hidden from assistive
|
|
111
|
+
technology), the content's access failures are drawn at the top of the explorer inside the sheet, in the order they
|
|
112
|
+
came (`markdown-explorer-sheet-access-failures`), and nothing behind it; once the sheet closes each node goes back to
|
|
113
|
+
its place with the same occurrence.
|
|
114
|
+
|
|
3
115
|
## 0.36.0 (2026-11-12) — Document IDs: a permalink that keeps opening its document when the document's path changes
|
|
4
116
|
|
|
5
117
|
### Breaking
|
package/README.md
CHANGED
|
@@ -50,7 +50,7 @@ A single-view (embedding) page never downloads the tree and multi-panel views, w
|
|
|
50
50
|
|
|
51
51
|
- React 19.2.7 or later and React Router 8 in framework mode (route modules with `loader` / `headers`).
|
|
52
52
|
- 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)`.
|
|
53
|
-
- The peer packages, at these versions or later within the caret ranges the package declares: `@aiquants/markdown` ^13.0.0 (document rendering;
|
|
53
|
+
- The peer packages, at these versions or later within the caret ranges the package declares: `@aiquants/auth-core` ^0.8.0 (the access failure contract: the occurrence the host's presenter draws, and the 403 refusal of the page loader, `accessFailureResponse`), `@aiquants/markdown` ^13.0.0 (document rendering;
|
|
54
54
|
the column width and colour pair a reader picks in its display popover (`CONTENT_MEASURES` and `CONTENT_COLORS` of `@aiquants/markdown/viewer-settings`) and the labels of the popover's sections and of a diagram's notices, a document's language for its content (`contentLang`) apart from the UI language of the labels the explorer passes (`labelsLang`), and the size of a document table's tap-scroll circle (`spreadsheetTapScrollCircle`'s `size`);
|
|
55
55
|
the gutter its scroll container keeps beside the explorer's bar for the tap-scroll circle (`scrollBarGutter`, given as a custom property that a media query sets), code blocks whose Copy button sits in a header row above the code, and documents whose front matter does not render; the Source toggle of a storage SVG image that stands alone in a paragraph, read through `imageSource`, and a Copy that copies the image as a PNG image or its source, the source readable in every display style, a notice in place of a block that cannot render and plain text for a fence in a language it does not know;
|
|
56
56
|
the full screen of its tables, Mermaid diagrams and SVG images, which every block marks with the same DOM hook (`data-aqmd-fullscreen`), and `DEFAULT_MARKDOWN_STYLE`, the style a document starts in by default; its components' stylesheet without utilities,
|
|
@@ -75,7 +75,7 @@ A single-view (embedding) page never downloads the tree and multi-panel views, w
|
|
|
75
75
|
## Installation
|
|
76
76
|
|
|
77
77
|
```bash
|
|
78
|
-
pnpm add @aiquants/markdown-explorer @aiquants/markdown @aiquants/directory-tree @aiquants/drag-drop-panels @aiquants/resize-panels @aiquants/virtualscroll
|
|
78
|
+
pnpm add @aiquants/markdown-explorer @aiquants/auth-core @aiquants/markdown @aiquants/directory-tree @aiquants/drag-drop-panels @aiquants/resize-panels @aiquants/virtualscroll
|
|
79
79
|
```
|
|
80
80
|
|
|
81
81
|
The package's entries are `@aiquants/markdown-explorer` (the browser half: `<MarkdownExplorer>`, the shared configuration and links), `@aiquants/markdown-explorer/server` (the server half on Node), `@aiquants/markdown-explorer/storage` (`clearExplorerStorage` only, with no dependencies), `@aiquants/markdown-explorer/testing` (the answers the deny rules owe, for tests) and the stylesheet `@aiquants/markdown-explorer/styles/markdown-explorer.css`.
|
|
@@ -183,8 +183,10 @@ The base route (`docs`) must be registered as well as the splat: a client naviga
|
|
|
183
183
|
|
|
184
184
|
```tsx
|
|
185
185
|
// app/routes/docs.tsx
|
|
186
|
+
import { accessFailureKindOfStatus } from "@aiquants/auth-core"
|
|
186
187
|
import { MarkdownExplorer, shouldRevalidateExplorer } from "@aiquants/markdown-explorer"
|
|
187
188
|
import { isRouteErrorResponse, useLoaderData, useRouteError } from "react-router"
|
|
189
|
+
import { presentAccessFailure } from "../access-failure"
|
|
188
190
|
import { explorerConfig } from "../explorer.config"
|
|
189
191
|
import { explorer } from "../explorer.server"
|
|
190
192
|
|
|
@@ -197,7 +199,7 @@ export default function Docs() {
|
|
|
197
199
|
<div className="docs-page">
|
|
198
200
|
<header>Handbook</header>
|
|
199
201
|
<main className="docs-explorer">
|
|
200
|
-
<MarkdownExplorer data={useLoaderData<typeof loader>()} config={explorerConfig} storageNamespace="docs" lockDocumentScroll />
|
|
202
|
+
<MarkdownExplorer data={useLoaderData<typeof loader>()} config={explorerConfig} storageNamespace="docs" accessFailure={presentAccessFailure} lockDocumentScroll />
|
|
201
203
|
</main>
|
|
202
204
|
</div>
|
|
203
205
|
)
|
|
@@ -205,7 +207,54 @@ export default function Docs() {
|
|
|
205
207
|
|
|
206
208
|
export function ErrorBoundary() {
|
|
207
209
|
const error = useRouteError()
|
|
208
|
-
|
|
210
|
+
const kind = isRouteErrorResponse(error) ? accessFailureKindOfStatus(error.status) : null
|
|
211
|
+
return kind === null ? <p>Something went wrong.</p> : presentAccessFailure({ kind, place: "page", deniedSentence: null, retry: null })
|
|
212
|
+
}
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
```tsx
|
|
216
|
+
// app/access-failure.tsx
|
|
217
|
+
import { type AccessFailureAction, type AccessFailurePresenter, accessFailureView, resolveAccessFailureLabels } from "@aiquants/auth-core"
|
|
218
|
+
import type { ReactNode } from "react"
|
|
219
|
+
|
|
220
|
+
const labels = resolveAccessFailureLabels("en")
|
|
221
|
+
|
|
222
|
+
const follow = (action: AccessFailureAction, retry: (() => void) | null): void => {
|
|
223
|
+
switch (action) {
|
|
224
|
+
case "retry":
|
|
225
|
+
retry?.()
|
|
226
|
+
return
|
|
227
|
+
case "back":
|
|
228
|
+
window.history.back()
|
|
229
|
+
return
|
|
230
|
+
case "top":
|
|
231
|
+
window.location.assign("/")
|
|
232
|
+
return
|
|
233
|
+
case "sign-in":
|
|
234
|
+
case "sign-in-again":
|
|
235
|
+
window.location.assign("/sign-in")
|
|
236
|
+
return
|
|
237
|
+
case "sign-in-again-in-new-window":
|
|
238
|
+
window.open("/sign-in", "_blank", "noopener")
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
// The explorer keeps the reader's unsaved drafts in the page, so it keeps work.
|
|
243
|
+
export const presentAccessFailure: AccessFailurePresenter<ReactNode> = (occurrence) => {
|
|
244
|
+
const view = accessFailureView(occurrence, { keepsWork: true }, labels)
|
|
245
|
+
return (
|
|
246
|
+
<div role={view.politeness}>
|
|
247
|
+
<p>{view.title}</p>
|
|
248
|
+
{view.sentences.map((sentence) => (
|
|
249
|
+
<p key={sentence}>{sentence}</p>
|
|
250
|
+
))}
|
|
251
|
+
{view.actions.map(({ action, label }) => (
|
|
252
|
+
<button key={action} type="button" onClick={() => follow(action, occurrence.retry)}>
|
|
253
|
+
{label}
|
|
254
|
+
</button>
|
|
255
|
+
))}
|
|
256
|
+
</div>
|
|
257
|
+
)
|
|
209
258
|
}
|
|
210
259
|
```
|
|
211
260
|
|
|
@@ -218,7 +267,8 @@ export const action = explorer.dataAction
|
|
|
218
267
|
```
|
|
219
268
|
|
|
220
269
|
- Take the content folder from configuration (an environment variable here), not from `import.meta.url`: after `react-router build` the server module runs from `build/server/index.js`, so a path relative to the module would point into `build/`.
|
|
221
|
-
- The page
|
|
270
|
+
- The explorer words no access failure itself, neither in the page nor around it: it hands each one to the presenter you pass as `accessFailure` (`@aiquants/auth-core`'s `AccessFailurePresenter`, here drawing auth-core's own view of the failure; see [Access failures](#access-failures)), and the page route's error boundary draws the page's own refusal with the same presenter. With `anonymousAccess` nobody is signed out, but a document outside every source still answers `forbidden`.
|
|
271
|
+
- The page route needs its own `ErrorBoundary`: React Router stops carrying `headers` at the boundary that renders an error, so without one the 403 refusal of a reader without access loses its `Cache-Control: no-store`.
|
|
222
272
|
- The data route module must not have a default export; with one it becomes a UI route and the JSON answers are rendered as a page.
|
|
223
273
|
- `shouldRevalidateExplorer` keeps React Router from running the page loader again on a submission, a move to another document, view or source (another path under the splat, another query) and a navigation that drops the hash; the unchanged URL (a `revalidate()` call, a link to the current page) keeps React Router's decision. It is built with `@aiquants/route-revalidation`.
|
|
224
274
|
- The explorer adds no `main` landmark in any view (its own landmarks — the explorer `nav`, the document region, the multi view's columns — sit inside yours), so the page places it in its own `<main>`.
|
|
@@ -357,8 +407,7 @@ In the tree view a folder can be selected as GitHub's file tree does, and the vi
|
|
|
357
407
|
| `sources` | `ExplorerSource<P>[]` | The sources in switcher order (at least one; the first is the default): `id` (lowercase letters, digits and `-`, starting with a letter or digit, unique; the URL's `source` value), `label` (a string, or a function of the principal), `boundary` (where the source's documents may lie, see [Source boundaries](#source-boundaries)), `tree(context)` (lists the source's roots), `children?(context, path, readPath)` for lazy folders (asked only while the tree shows the folder open — the reader opened it, Expand all opened it (a press keeps opening folders as their listings land, within `expandAll`), or a remembered expansion opened it — and only for a path inside the source's boundary; a listing no tree wants any more is aborted through `context.signal`, which the source should honour), `ancestors?(context, path, readPath, options)` (the folders down to a document, for the reader's reveal; see [Revealing the open document](#revealing-the-open-document)), `cacheScope?` (`"principal"`, the default, or `"shared"`). The `context` is described under [Entries and notices](#entries-and-notices). |
|
|
358
408
|
| `document` | `(context, path, readPath) => Promise<ExplorerHostDocument>` | Resolves a document path. Called only for a path inside at least one source's boundary; `readPath` is what the admitting source's `confirm` answered (`path` when that source has no `confirm`), so read `readPath` and show the document as `path`. An image, media, text or file document reports its file's `version`; the explorer writes its URL (see [Documents](#documents)). |
|
|
359
409
|
| `asset` | `(context, path, readPath, options) => Promise<ExplorerAssetFile \| ExplorerAssetRedirect>` | Finds the file behind the data route's `asset` operation (and its `text` operation, which reads a Markdown document's source through it): any regular file the document admission admits, whatever its kind. Called only after the path passed the deny rules and the same union admission as a document, with the same `readPath`; see [Serving files](#serving-files). `options.delivery` says what the explorer delivers of the file (`"file"`, `"text"` or `"workbook"`): with `"file"` it may answer a short-lived URL instead, see [Redirecting to the storage](#redirecting-to-the-storage), and with `"workbook"` a storage that converts the file on read delivers a workbook, see [Serving files](#serving-files). |
|
|
360
|
-
| `signedOutPage` | `(
|
|
361
|
-
| `forbiddenPage?` | `(request, headers) => Response` | The page response for a reader without access (default: a 403 for the route's error boundary). |
|
|
410
|
+
| `signedOutPage` | `(args: ExplorerPageRouteArgs, headers) => Response` | The page response for a signed-out reader, usually a redirect to sign-in. `args` is `{ request, url }`: the request, and `url`, the page's URL normalized by React Router (without the `.data` suffix and the `_routes` parameter of a single-fetch request), the address to return to after signing in. `headers` holds the authentication's headers and `Cache-Control: private, no-store`. Data requests answer 401 instead. |
|
|
362
411
|
| `notices?` | `(context) => Promise<ExplorerNotice[]>` | Callouts above the tree (a missing permission with a link that grants it, for example). |
|
|
363
412
|
| `deny?` | `string[] \| false` | Segment patterns hidden from every listing and refused on every read (default `DEFAULT_DENIED_PATH_SEGMENTS`). |
|
|
364
413
|
| `treeCache?` | `{ ttlMs?, maxEntries?, maxBytes? } \| false` | The server's tree cache, each limit defaulting on its own (5 minutes, 64 entries, 64 MiB of the trees' JSON, counted at two bytes per character). The time to live counts from the moment the tree's walk began, and an expired tree is never answered: a page load or tree request after it waits for one new walk, which every concurrent request shares. Each cached tree is also kept parsed beside its JSON, which `maxBytes` does not count; its share falls as names get longer and is higher for non-ASCII names (measured on trees of 20,000 entries: about 1.0 to 1.9 times the counted bytes for ASCII names of 40 down to 4 characters, 1.4 to 2.2 times for non-ASCII names), and a tree with any non-ASCII name keeps a two-byte JSON as large as its count, so plan for up to about 2.4 times `maxBytes` of memory per process with ASCII names and up to about 3.2 times with short non-ASCII names. `false` turns the cache off. |
|
|
@@ -369,6 +418,8 @@ In the tree view a folder can be selected as GitHub's file tree does, and the vi
|
|
|
369
418
|
| `onTreeRefreshed?` | `(key: string) => void` | Called once per tree refresh, after its reload settled (whatever its result) unless the request went away, with the refreshed tree's cache key (opaque). A multi-process host relays the key to its other processes, which call `forgetTree(key)` (see [Hosting notes](#hosting-notes)). Its return value is ignored, but a promise it returns (an asynchronous relay) is observed, never awaited: a throw, or the rejection of that promise, is logged with the operation `refresh` and does not change the response. |
|
|
370
419
|
| `documentIds?` | `ExplorerDocumentIdPorts<P>` | The registry of document IDs, `{ issue, resolve }` (see [Document IDs](#document-ids)): given exactly when the configuration has `documentIds` (either alone throws a `TypeError`, as does a value that is not an object of the two functions). |
|
|
371
420
|
|
|
421
|
+
A reader `authenticate` answers `forbidden` for is refused by the page loader with `@aiquants/auth-core`'s refusal, `accessFailureResponse("forbidden")` thrown with the authentication's headers: a 403 whose body is `{ "accessFailure": "forbidden" }` and whose `Cache-Control` is auth-core's `no-store`, for the page route's error boundary (React Router reads the body into the error's `data`). Data requests answer 403 instead.
|
|
422
|
+
|
|
372
423
|
It returns `{ loader, headers, dataLoader, dataAction, planData, forgetTree }`. `planData` plans a data request for a host that streams a file's bytes itself (see [Streaming files yourself](docs/behavior/hosting.md#streaming-files-yourself)).
|
|
373
424
|
`forgetTree(key)` drops this process's cached tree for a key another process refreshed and supersedes a load of it that already began (its waiting requests still receive that tree, which is not kept); it starts no load and throws a `TypeError` for a non-string key. Export `headers` from the page route: it carries the loader's `Cache-Control: private, no-store` to both the HTML and the single-fetch responses.
|
|
374
425
|
`dataLoader` and `dataAction` answer a React Router single-fetch request to the data route (`<dataPath>/<operation>.data`) with a `not-found` failure (404) before authenticating or calling a source: React Router would run them for it, read the whole response and keep none of its headers but `Set-Cookie`.
|
|
@@ -800,11 +851,12 @@ Spread it into the configuration when your application has no sign-in: it provid
|
|
|
800
851
|
| `data` | `ExplorerPageData` | `useLoaderData()` of the page route. |
|
|
801
852
|
| `config` | `ExplorerConfig` | The shared configuration. |
|
|
802
853
|
| `storageNamespace` | `string` | Prefix of the browser storage keys (tree settings, expansion state, the multi-view layout, the editor's side-by-side setting and share): 1–64 letters, digits, `.`, `_` or `-`, starting with a letter or digit (anything else throws a `RangeError`). |
|
|
854
|
+
| `accessFailure` | `AccessFailurePresenter<ReactNode>` | Draws the explorer's access failures (`@aiquants/auth-core`): a session that ended (`unauthorized`, the kind `unauthenticated`) and something the reader may not read or write (`forbidden`). The explorer words neither: each place hands the presenter one occurrence and draws the node it returns (see [Access failures](#access-failures)). Anything but a function throws a `TypeError` at the first render. |
|
|
803
855
|
| `locale?` | `"en" \| "ja"` | The UI language (default `"en"`). |
|
|
804
856
|
| `labels?` | `Partial<MarkdownExplorerLabels>` | Per-key overrides; strings that embed a value are functions, except the multi view's templates for `@aiquants/drag-drop-panels` (`MARKDOWN_EXPLORER_LABEL_TEMPLATES`). |
|
|
805
857
|
| `theme?` | `"light" \| "dark"` | The colour scheme (default `"light"`), declared as the root's `color-scheme`, so the colours `@aiquants/directory-tree` paints from its `light-dark()` palette and the browser's own controls and scrollbars inside the explorer follow it, whatever the page declares. |
|
|
806
858
|
| `renderFrame?` | `({ view, children }) => ReactNode` | Wraps each view in your chrome; for example leave the single view without it for embedding. |
|
|
807
|
-
| `renderTreeFailure?` | `(failure) => ReactNode \| undefined` | Renders a tree failure you understand better (by its `code`); `undefined` keeps the explorer's own message. Your node replaces the explorer's callout inside the tree-failure element, which keeps its hooks (`data-testid="markdown-explorer-tree-failure"` and `data-aqmx-failure`); the callout is the failure's only announcement (`role="alert"`), so your node must announce itself (for example with `role="alert"`). |
|
|
859
|
+
| `renderTreeFailure?` | `(failure) => ReactNode \| undefined` | Renders a tree failure you understand better (by its `code`); `undefined` keeps the explorer's own message (for an access failure, the presenter's node). Your node replaces the explorer's callout inside the tree-failure element, which keeps its hooks (`data-testid="markdown-explorer-tree-failure"` and `data-aqmx-failure`); the callout is the failure's only announcement (`role="alert"`), so your node must announce itself (for example with `role="alert"`). |
|
|
808
860
|
| `lockDocumentScroll?` | `boolean` | Stops the page itself from scrolling while the explorer fills the viewport; the explorer must then fit in the viewport (see below). |
|
|
809
861
|
| `onMathDiagnostics?` | `(path, diagnostics: readonly MarkdownMathDiagnostic[]) => void` | Receives the KaTeX diagnostics of a markdown document once it rendered (never during render), with the document's path; the reader's console never sees them. `MarkdownMathDiagnostic` (`{ code, message, formula, displayMode }`) comes from `@aiquants/markdown`. The explorer reaches your function through one stable function, so passing a new function on every render neither parses the document again nor delivers its diagnostics twice; text documents report none. |
|
|
810
862
|
| `onEditGrant?` | `(href: string) => Promise<boolean>` | Lets the reader grant what an edit or a save asked for (`{ kind: "grant", href }`, see [Editing](#editing)): open your root-relative `href` as you see fit (a consent popup, for example) and resolve whether the reader came back from it; the editor then asks again. Without it, the editor links to `href` in a new tab beside Try again. |
|
|
@@ -815,10 +867,7 @@ Spread it into the configuration when your application has no sign-in: it provid
|
|
|
815
867
|
| `hostChangePolicy?` | `"reload" \| "notify"` | What a changed document the reader is not editing does: `"reload"` (default) reads it again and announces it; `"notify"` shows a notice with Reload above it (`data-aqmx-notice="changed"`), which steps aside while the reader edits the document. |
|
|
816
868
|
| `ref?` | `Ref<MarkdownExplorerHandle>` | Receives the explorer's handle (see [The handle](#the-handle)), which always acts on the current reader's explorer. |
|
|
817
869
|
| `guardUnload?` | `boolean` | Whether leaving the page while a draft is unsaved asks through `beforeunload` (default `true`; a host that asks on close itself passes `false`). |
|
|
818
|
-
| `onReload?` | `() => void` | Reloads after a failure the reader asked to retry (default: the page's reload); a host whose state lives outside the page passes its rebuild. The explorer always calls the latest one given. |
|
|
819
|
-
| `onSessionEnded?` | `() => Promise<boolean>` | Restores a session that ended (the `unauthorized` failure) without leaving the page: open your sign-in and resolve `true` once the reader is signed in again, and the failed view tries again; resolve `false` (never reject) when the sign-in fails or is cancelled, and the failure keeps offering it. Calls made while a sign-in is open share its answer. Without it the failure offers the reload. The explorer always calls the latest one given. |
|
|
820
870
|
| `onDraftChange?` | `(change: ExplorerDraftChange) => void` | Receives the unsaved drafts as the explorer writes them (every 144 ms, those changed since the last call, as `kept`) and the paths whose drafts ended (`ended`: saved, discarded, closed, or back to the text they started from), so a host can keep a copy outside the page that `restoreDrafts` takes back (default: none). Its first call holds every draft unsaved by then; the explorer always calls the latest one given. |
|
|
821
|
-
| `accountState?` | `"signed-in" \| "signed-out"` | Whether the reader is signed in to the host's account, which picks the words of an `unauthorized` failure: `"signed-in"` (default) asks to sign in again, `"signed-out"` to sign in. |
|
|
822
871
|
| `confirmUnversionedSaves?` | `boolean` | Asks before every save that would write a change to a source that keeps no previous versions (an `edit` source answered with `history: false`), so every save can be undone or was confirmed (default `false`). |
|
|
823
872
|
| `paletteKey?` | `string` | An opaque name of the palette the host binds the explorer's colour roles to; when it changes, the explorer reads again the colours it paints itself (the tree's connector lines, drawn on a canvas), which `theme` alone cannot tell (default: none). |
|
|
824
873
|
|
|
@@ -942,6 +991,22 @@ export const draftConverter: ExplorerDraftConverter = {
|
|
|
942
991
|
- **The shared halves.** Two functions of the root entry hold what does not depend on the converter you run, so every host makes it one way: `draftConversionOf({ deny, conversion })` makes the converter's options from the deny rules and the conversion limits (`{ maxSourceBytes, maxHtmlBytes, deadlineMs }`) your server converts documents with — `{ timeoutMs, options: { deniedPathSegments, maxHtmlBytes, includeSourceLines: true } }` —,
|
|
943
992
|
and `draftAnswerOf(error)` maps a conversion's failure to the draft answer as your server answers the same conversion: a size limit or the deadline is `too-large`, `invalid_argument` is `invalid`, `internal` is `failed`, and `unavailable` leaves the draft to the server; it rethrows any other error. `@aiquants/markdown`'s browser and service converters throw the same error classes.
|
|
944
993
|
|
|
994
|
+
#### Access failures
|
|
995
|
+
|
|
996
|
+
An `unauthorized` failure (the session ended) and a `forbidden` one (the reader may not read or write it) are not the explorer's to word: each place that meets one hands the host's presenter (`accessFailure`) an occurrence, `{ kind, place, deniedSentence, retry }` (`AccessFailureOccurrence` of `@aiquants/auth-core`), and draws the node the presenter returns inside the place's own hooks. The explorer's announcer says nothing of an access failure, since the presenter's node speaks for itself.
|
|
997
|
+
|
|
998
|
+
- **Kind.** `unauthorized` is the kind `unauthenticated`, `forbidden` the kind `forbidden`. The explorer's own reasons (`not-found`, `not-configured`, `invalid`, `too-large`, `unsupported`, `failed`) keep its own callouts and announcements.
|
|
999
|
+
- **Place.** `read` for what the explorer reads (a document, the tree and its refresh, a folder's children, a document's refresh, its source, the editor's text, a revision, the server's preview of a draft), `write` for what the reader writes (a save, Copy permalink, which issues the document's ID). The page itself is the host's: the page loader's refusal goes to the page route's error boundary.
|
|
1000
|
+
- **Denied sentence.** `null` (the presenter's own sentence), except for the `forbidden` answer of an ID URL, which carries the explorer's `documentIdForbidden`.
|
|
1001
|
+
- **Retry.** Where the place can repeat its work once the reader is signed in again it is the place's latest retry (read again, save again, refresh again, load the stopped folders again); `null` for Copy permalink (the reader presses it again) and for the preview (the next pause renders again).
|
|
1002
|
+
- **One occurrence per failure.** A place hands the same frozen occurrence for as long as it shows the same failure, so a presenter may tell one from the next by identity, and a new one for every new failure; a place drawn again after it was gone hands a new one.
|
|
1003
|
+
- **One node per failure.** As auth-core's `AccessFailurePresenter` asks of a package, the presenter's node is keyed by its occurrence: it stays mounted for as long as the place shows the same failure, and the next failure, even one of the same kind at the same place, mounts a new node. A presenter may therefore keep state for one failure in its node.
|
|
1004
|
+
The folders whose children stop at an access failure, one after another, share one node above the tree, one occurrence while any of them stays stopped (the folders one press of Expand all stops at once share one node that speaks once), whose retry loads them all again; the rows keep their own failure and Try again, and the node goes once no folder is stopped.
|
|
1005
|
+
Copy permalink shows the latest press's failure only and takes it down at the next press, when the bar moves to another document and when an edit of the document starts; it does not come back on return or once the edit ends.
|
|
1006
|
+
- **A session that ended.** A data request answered 401 neither reloads the page data nor navigates: the place that met it draws the presenter's node, whose sign-in action is the host's, and the reader's work (an unsaved draft) stays. Only a response carrying another reader's scope erases what the explorer remembers and reloads the page data (see [Security](docs/behavior/security.md)).
|
|
1007
|
+
- **The sheet.** While the explorer's sheet is open (a native modal `dialog`, on a frame too narrow for the split) everything behind it is inert and hidden from assistive technology, so the content's places hand their occurrences to the sheet, which draws them at the top of the explorer inside it, in the order they came (`data-testid="markdown-explorer-sheet-access-failures"`), and draws nothing behind; once the sheet closes, each node goes back to its place with the same occurrence.
|
|
1008
|
+
A node that moves is mounted again with the same occurrence object, as auth-core's contract asks of a package that moves the node of a failure it still holds, and speaks again there.
|
|
1009
|
+
|
|
945
1010
|
#### The handle
|
|
946
1011
|
|
|
947
1012
|
The handle `ref` receives (`MarkdownExplorerHandle`) lets a host that owns what surrounds the explorer — a desktop shell closing its window, a page routing its announcements — act on the explorer. It always acts on the current reader's explorer.
|
|
@@ -961,6 +1026,7 @@ The handle's methods and the props above check what a host gives: a value of the
|
|
|
961
1026
|
### Localization
|
|
962
1027
|
|
|
963
1028
|
`locale` selects a built-in catalog (`MARKDOWN_EXPLORER_LABEL_CATALOGS.en` / `.ja`); `labels` overrides single keys.
|
|
1029
|
+
The catalogs hold no words for an access failure, which the host's `accessFailure` presenter words in its own (see [Access failures](#access-failures)).
|
|
964
1030
|
The catalogs also name every control of the document viewer (the `viewer…` keys: its toolbar, the table of contents, the style and alignment menus, each Mermaid diagram's controls, full-screen dialog, source view with its copy and type name, a storage SVG image's toolbar, source, copies, notices and full-screen dialog, the notice in place of a block that cannot render, every name, notice and announcement of a ```spreadsheets table, and the titles of embedded frames).
|
|
965
1031
|
A table's labels are `@aiquants/markdown`'s own: each label of its table block under `viewerSpreadsheet…` (`zoomIn` → `viewerSpreadsheetZoomIn`), with the block's catalog of the UI language as the built-in text and its placeholders; only the ones a host replaces reach the viewer, so a table shows its catalog's text marked with its language, and its grid takes `locale` as its own.
|
|
966
1032
|
The multi view's labels name everything its drag-and-drop layout shows (the panel headers' buttons and the custom drag mode's badge, the move announcements and a touch or pen drag's lift and cancel announcements, the bar of hidden panels, the columns' names and the drop placeholders), which therefore follow `locale` too.
|