@aiquants/markdown-explorer 0.24.0 → 0.25.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 +45 -0
- package/README.md +25 -11
- package/dist/{EditSurface-CcWEczj3.js → EditSurface-Blymamic.js} +3 -3
- package/dist/{EditSurface-CRc4g0Qa.cjs → EditSurface-Co4Rvfa1.cjs} +1 -1
- package/dist/{ExplorerSplit-97SeIAOS.js → ExplorerSplit-BZ0PA3z3.js} +47 -47
- package/dist/{ExplorerSplit-ByxxXlgs.cjs → ExplorerSplit-WApgYMPb.cjs} +1 -1
- package/dist/{MultiLayout-CnbuAlxd.js → MultiLayout-B5-1N3JD.js} +3 -3
- package/dist/{MultiLayout-B_yMVDt_.cjs → MultiLayout-dAW_JCzg.cjs} +1 -1
- package/dist/{NativeScrollBar-BXdaM3EA.js → NativeScrollBar-BraWuZvN.js} +1 -1
- package/dist/{NativeScrollBar-D4a7fBOS.cjs → NativeScrollBar-ThVMbI0Y.cjs} +1 -1
- package/dist/{TreeLayout-C6QDpEBS.cjs → TreeLayout-C60lb9hP.cjs} +1 -1
- package/dist/{TreeLayout-BIQBKAkV.js → TreeLayout-CChoxh9W.js} +3 -3
- package/dist/core/labels.d.cts +3 -0
- package/dist/core/labels.d.ts +3 -0
- package/dist/core/textEncoding.d.cts +1 -0
- package/dist/core/textEncoding.d.ts +1 -0
- package/dist/index-B6FkGD-p.cjs +13 -0
- package/dist/{index-CeZDCyEl.js → index-Bd6hgisa.js} +546 -537
- package/dist/index.cjs +1 -1
- package/dist/index.js +3 -3
- package/dist/location-D3DgoELB.cjs +1 -0
- package/dist/{location-gXXmC7CQ.js → location-DIxIjqs7.js} +147 -140
- package/dist/{merge-DqjUgcV_.js → merge-CgSp-0Dd.js} +1 -1
- package/dist/{merge-QLktbpZY.cjs → merge-DRWmjC24.cjs} +1 -1
- package/dist/server.cjs +1 -1
- package/dist/server.js +785 -725
- package/dist/{useSplitPersistence-Bmpb2prR.cjs → useSplitPersistence-D-T75Hlh.cjs} +1 -1
- package/dist/{useSplitPersistence-BPNjvuJi.js → useSplitPersistence-Df63lnQZ.js} +1 -1
- package/docs/behavior/layout.md +7 -4
- package/docs/behavior/localization.md +6 -3
- package/docs/behavior/security.md +7 -3
- package/docs/behavior/url-contract.md +3 -3
- package/package.json +3 -3
- package/dist/index-BwTVYkTR.cjs +0 -13
- package/dist/location-CasigkBk.cjs +0 -1
|
@@ -1 +1 @@
|
|
|
1
|
-
"use strict";const e=require("react"),d=require("./location-
|
|
1
|
+
"use strict";const e=require("react"),d=require("./location-D3DgoELB.cjs"),f="(pointer: coarse)",E=r=>{const n=window.matchMedia(f);return n.addEventListener("change",r),()=>n.removeEventListener("change",r)},S=()=>window.matchMedia(f).matches,m=()=>!1,C=()=>e.useSyncExternalStore(E,S,m),R=r=>{const n=e.useRef(r);e.useLayoutEffect(()=>{n.current=r},[r]);const c=e.useRef(null),t=e.useRef(null),s=e.useRef(!1),u=e.useCallback(()=>{t.current!==null&&clearTimeout(t.current),t.current=setTimeout(()=>{t.current=null,c.current!==null&&n.current(c.current)},d.SPLIT_PERSIST_DELAY_MS)},[]);e.useEffect(()=>()=>{t.current!==null&&clearTimeout(t.current)},[]);const a=e.useCallback((o,l)=>{c.current=o,l.source==="keyboard"?u():l.source==="pointer"&&(s.current=!0)},[u]),i=e.useCallback(o=>{if(o){s.current=!1;return}s.current&&(s.current=!1,u())},[u]);return e.useMemo(()=>({layoutChanged:a,draggingChanged:i}),[a,i])};exports.useCoarsePointer=C;exports.useSplitPersistence=R;
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { useSyncExternalStore as d, useRef as c, useLayoutEffect as E, useCallback as a, useEffect as S, useMemo as h } from "react";
|
|
2
|
-
import { S as y } from "./location-
|
|
2
|
+
import { S as y } from "./location-DIxIjqs7.js";
|
|
3
3
|
const m = "(pointer: coarse)", C = (e) => {
|
|
4
4
|
const t = window.matchMedia(m);
|
|
5
5
|
return t.addEventListener("change", e), () => t.removeEventListener("change", e);
|
package/docs/behavior/layout.md
CHANGED
|
@@ -197,12 +197,14 @@ Documents in the multi-panel view sit in `multiView.columns` logical columns (4
|
|
|
197
197
|
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`).
|
|
198
198
|
- **Table file.** A spreadsheet document shows its file header and, below it, the file's body: one scroller (the document's, with the pane's pointer scroll bar in a page view) that holds the notes — a workbook's first sheet (`spreadsheetFirstSheetOnly`) and a table that is only part of its file (`spreadsheetTruncated`), which take the same insets as every document notice (13 px above, 21 px at the sides) — and the table.
|
|
199
199
|
The table sits on a stage whose padding continues that rhythm (13 px above, 21 px at the sides and below, `--aqmx-space-6` and `--aqmx-space-7`): in a page pane the stage takes the rest of the body's height and the table block fills it (its `fill` layout:
|
|
200
|
-
the block's toolbar and notice line keep their height and the grid's box takes the rest, scrolling inside), so the body does not scroll around the table, unless the pane is shorter than the file header, the notes, the stage's padding and the table block at its fewest — its toolbar and notice line, whose 44 px controls wrap onto more lines in a narrow pane, and the box's three rows at the grid's zoom, capped at the viewport's height less two 44 px bands —, as at a 400 % zoom, where the body scrolls to the notes and the whole table;
|
|
201
|
-
|
|
200
|
+
the block's toolbar and notice line keep their height and the grid's box takes the rest, scrolling inside), so the body does not scroll around the table, unless the pane is shorter than the file header, the notes, the stage's padding and the table block at its fewest — its toolbar and notice line, whose 44 px controls wrap onto more lines in a narrow pane, and the box's three rows at the grid's zoom, capped at the viewport's height less two 44 px bands —, as at a 400 % zoom, where the body scrolls to the notes and the whole table;
|
|
201
|
+
in a multi-view panel the table takes the height of its rows (its `inline` layout, at most the viewport's), as every child of a panel follows its content, and the panel's area scrolls.
|
|
202
|
+
The table is `@aiquants/markdown`'s table block, read-only, named after the file, in the explorer's colour scheme (`data-theme` on the stage); until the first reading the body shows the skeleton, after which a page view announces the document (`documentShown`); a failure before anything was read shows the failure view with its retry and is announced alone (`documentFailed`; a retry that succeeds moves the focus into the body and a page view announces the document); and bytes that are no table — or a file without data (`spreadsheetEmpty`:
|
|
203
|
+
read whole, its cells, taken whole within the preview's budget, all empty, or none at all) — show a note in place of the table on the file view's sunken stage, 13 px below a note above it, with the download for bytes that are no table (`spreadsheetUnreadableEncoding`, `spreadsheetNotText`, and `spreadsheetLongRow` when no row ends within `spreadsheets.maxBytes`).
|
|
202
204
|
A reading again (a new answer for the document, a retry) keeps what was shown, with the region busy; Refresh document reports a failure of it in the bar, and a background answer's reading that fails says nothing.
|
|
203
205
|
- **Source of an SVG image inside a document.** In a rendered Markdown document — a page view's pane, a panel and the editor's preview alike — every storage SVG image that stands alone in a paragraph (as `@aiquants/markdown`'s viewer picks them: an image the converter wrote with `data-asset-src`, not inside a link or beside text) has a toolbar above it at the row's end (`viewerSvgImageToolbar`) holding Copy (`viewerSvgImageCopy`) and then the Source toggle (`viewerSvgImageSource`, `aria-pressed`), which swaps the image for its SVG as written and back, keeping the focus on the toggle.
|
|
204
206
|
The explorer reads the SVG through the same `text` operation as a document's source, only while the source shows or when Copy is pressed on the image (a read the reader leaves is aborted), so it is refused and admitted exactly as the image itself; the block shows a loading line (`viewerSvgImageLoading`), the text named after the image (`viewerSvgImageSourceRegion`), the note `viewerSvgImageTruncated` under a file cut at `textMaxBytes`,
|
|
205
|
-
and a failure (`viewerSvgImageFailed`) with Try again (`viewerSvgImageRetry`) for a `failed` read. Copy shows while the image shows, where it reads the file and copies
|
|
207
|
+
and a failure (`viewerSvgImageFailed`) with Try again (`viewerSvgImageRetry`) for a `failed` read. Copy shows while the image shows, where it reads the file and copies the image as a PNG that pastes as an image (`viewerSvgImageCopyImage`, its outcome `viewerSvgImageCopiedImage` or `viewerSvgImageCopyImageFailed`), and while the whole file shows, where it copies the SVG as written (`viewerSvgImageCopy`, its outcome `viewerSvgImageCopied` or `viewerSvgImageCopyFailed`); a file cut at `textMaxBytes` is never copied.
|
|
206
208
|
The choice is the block's own and is not part of the URL: a reload or another document shows the image, while a render that keeps the image's paragraph (a revalidation, the preview's next draft) keeps the choice. A double-click inside the shown SVG selects its text: it never opens the editor of a document the reader may edit, as a double-click on the document's words does (see **Editing a Markdown document** below).
|
|
207
209
|
- **Editing a Markdown document.** The editing surface takes the document's place in the region (`data-aqmx-document-view="edit"`). In a page view and in a maximized panel it fills the pane — in a panel the region then fills the scroll area below the pinned bar — and the editor scrolls itself; in a panel that is not maximized it grows with its text and the panel's scroll area scrolls it.
|
|
208
210
|
The bar's view switch shows the editor alone, the editor and the preview side by side, or the preview alone (`data-aqmx-edit-view`). Side by side, offered where the pane fills, they share one grid, each scrolling itself, in two columns or one above the other on a narrow pane, with a handle between them that resizes them (see [The editor's split](#the-editors-split)).
|
|
@@ -262,7 +264,8 @@ A multi-view panel shows it icon-only in a bar pinned to the top of the panel's
|
|
|
262
264
|
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.
|
|
263
265
|
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.
|
|
264
266
|
A document reloaded in the background is announced as reloaded (`documentRefreshed`); one whose outcome the pane shows in place of what it showed — a shown failure, a document the page loader gave up on or one not cached yet, fetched in the foreground, and a part whose content showed its failure view — is the pane's, so in the tree and single views the pane alone announces it — as shown (`documentShown`) or as a failure (`documentFailed`) — and in a panel, whose pane announces no document it shows, the control announces a document as reloaded and leaves a failure to the pane.
|
|
265
|
-
A reload that answers a failure — the document's answer, or the reading of that part while the content showed a copy of it — keeps the document, and the part's copy, and shows a notice inside the bar, below its button row (`documentRefreshFailed` with the failure's title, `data-testid="markdown-explorer-document-refresh-failure"`), the one notice of the failed reload, while the copy it kept stays on screen:
|
|
267
|
+
A reload that answers a failure — the document's answer, or the reading of that part while the content showed a copy of it — keeps the document, and the part's copy, and shows a notice inside the bar, below its button row (`documentRefreshFailed` with the failure's title, `data-testid="markdown-explorer-document-refresh-failure"`), the one notice of the failed reload, while the copy it kept stays on screen:
|
|
268
|
+
a newer answer that replaces or confirms that copy (Refresh tree, the background revalidation of a document opened again more than 55 s after it was fetched, a fetch after the cache dropped it), a move to another document (the notice does not come back on return), a switch between the document rendered and as written (whose content reads the document again) and that control's next refresh each take it down;
|
|
266
269
|
the notice is no live region, and the announcer speaks the same text (see [Announcements](#announcements)). Like Refresh tree, the button is `aria-disabled` and ignores activation while it runs (also `aria-busy`, its icon spinning unless motion is reduced) and while the document loads, and never takes `disabled`.
|
|
267
270
|
Each page view's control and each panel's control keeps its own state: refreshing one panel never makes another panel busy, shows another panel's notice or requests another panel's document. An outcome that arrives after its control moved to another document (a URL change, a link followed inside a panel) or went away (a panel closed or rebuilt) is not reported, and a refresh that a newer request for the same document replaced — Refresh tree reading the shown documents again meanwhile, for example — ends silently while that request updates the document.
|
|
268
271
|
A folder whose children failed to load shows Try again in its row, and the button leaves the row while the children load again: activating it while it holds the focus (Enter, Space or a click) first moves the focus to the folder's row, without scrolling, so the focus stays in the tree whether the retry succeeds or fails again.
|
|
@@ -10,7 +10,8 @@ This page is part of the host-facing contract of `@aiquants/markdown-explorer`;
|
|
|
10
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 and style menus (`viewerAlignTitle`, `viewerAlignLeft`, `viewerAlignCenter`, `viewerAlignRight`, `viewerPinAlign`, `viewerUnpinAlign`, `viewerStyleTitle`, `viewerPinStyle`, `viewerUnpinStyle`), the table of contents (`viewerTocTitle`, which also names its navigation, `viewerPinToc`, `viewerUnpinToc`)
|
|
11
11
|
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
12
|
`viewerMermaidPanUp`, `viewerMermaidPanDown`, `viewerMermaidPanLeft`, `viewerMermaidPanRight` for the buttons that move the view while the drawing overflows its frame, `viewerMermaidRetry`, and `viewerMermaidDiagram`, the name of the diagram's focusable frame),
|
|
13
|
-
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`,
|
|
13
|
+
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)
|
|
14
15
|
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).
|
|
15
16
|
A label the viewer receives carries no `lang` of its own, so it is read in the page's language.
|
|
16
17
|
- 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`).
|
|
@@ -23,12 +24,14 @@ This page is part of the host-facing contract of `@aiquants/markdown-explorer`;
|
|
|
23
24
|
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.
|
|
24
25
|
- `treeRegion` names the tree itself, apart from `explorerRegion`, which names the explorer's landmark (and the sheet on narrow frames).
|
|
25
26
|
- `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.
|
|
26
|
-
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)
|
|
27
|
+
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
|
+
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).
|
|
27
29
|
- `showMarkupLabel` is the visible text of the page views' Source toggle beside Refresh document (shown for a Markdown document, an SVG image and a 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.
|
|
28
30
|
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.
|
|
29
31
|
- 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.
|
|
30
32
|
`spreadsheetLoading` is the screen-reader text until its first reading, after which a page view announces the document with `documentShown(name)`; a reading that fails before anything was read is announced with `documentFailed(name, title)` alone (a table that replaces it on a retry with `documentShown(name)` in a page view), and one that fails again later keeps the table, a refresh reporting it with `documentRefreshFailed(reason)` in the bar;
|
|
31
|
-
its notes are `spreadsheetFirstSheetOnly` (the first sheet of a workbook), `spreadsheetTruncated` (part of the file) and, in place of the table, `spreadsheetEmpty` (a file without data: read whole, its cells, taken whole within the preview's budget, all empty, or none at all), `spreadsheetUnreadableEncoding(encodings)` (bytes in no encoding of the explorer's rule; the encodings tried, one or two, by their written names: the one a byte order mark names, or `UTF-8` and the legacy encoding, such as `Shift_JIS`), `spreadsheetNotText` (text holding NUL)
|
|
33
|
+
its notes are `spreadsheetFirstSheetOnly` (the first sheet of a workbook), `spreadsheetTruncated` (part of the file) and, in place of the table, `spreadsheetEmpty` (a file without data: read whole, its cells, taken whole within the preview's budget, all empty, or none at all), `spreadsheetUnreadableEncoding(encodings)` (bytes in no encoding of the explorer's rule; the encodings tried, one or two, by their written names: the one a byte order mark names, or `UTF-8` and the legacy encoding, such as `Shift_JIS`), `spreadsheetNotText` (text holding NUL)
|
|
34
|
+
or `spreadsheetLongRow` (no row ends within the bytes read, `spreadsheets.maxBytes`: the first row runs past them, or, in a TSV, a quote that opens in it closes nowhere within them).
|
|
32
35
|
- `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 or refuses the write; for 2 seconds the outcome's label is also the button's tooltip, while its name stays `copyText`.
|
|
33
36
|
- `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.
|
|
34
37
|
|
|
@@ -107,16 +107,20 @@ In a tree or children listing, an entry with an empty name, or with a path the b
|
|
|
107
107
|
Once the reload settled and unless the request went away, `onTreeRefreshed` receives the tree's cache key, which a multi-process host relays to its other processes' `forgetTree`; the response does not wait for a promise it returns, and a throw or that promise's rejection is logged (operation `refresh`).
|
|
108
108
|
- A document GET carrying `X-Markdown-Explorer: refresh` marks a request a refresh triggered: the host's `document` (and the admitting source's `confirm`) receive `refresh: true` and skip their caches. Such a request must carry the header's exact value and pass the same cross-origin check as the refresh itself (as a `GET`, a request without Fetch Metadata passes whatever its `Origin`, since another origin's page cannot add the header without a CORS preflight), or it is answered 403 before any host call, so a cross-site page cannot make the host re-parse documents.
|
|
109
109
|
- The `text` operation (`GET {dataPath}/text?path=`) answers JSON like a document request: GET and HEAD only; a missing, repeated or unacceptable `path` is 400; signed out 401 and forbidden 403.
|
|
110
|
-
Everything else is status 200: a text document (`name`, `text`, `truncated`, and the file's asset `url` with its version), or a failure document — `forbidden` for a denied or unadmitted path, `unsupported` for a file whose decoded text holds NUL (U+0000;
|
|
110
|
+
Everything else is status 200: a text document (`name`, `text`, `truncated`, and the file's asset `url` with its version), or a failure document — `forbidden` for a denied or unadmitted path, `unsupported` for a file whose decoded text holds NUL (U+0000;
|
|
111
|
+
the zero bytes of a UTF-16 file with a byte order mark are read as part of its characters, so only a U+0000 of its own is NUL, while a UTF-16 file without the mark is read as UTF-8 and its zero bytes are), the reason of an `ExplorerError` the host's `asset` port throws, and otherwise `failed`, logged with the operation `text` (a stream that ends before the size the port reported included).
|
|
111
112
|
It carries no refresh mark: the host's `asset` port receives `refresh: false`. The file is opened as the asset operation opens it — the first `textMaxBytes` bytes as a range when the port reports a longer size, the whole file otherwise, an empty file never — and the stream is cancelled once enough was read.
|
|
112
113
|
- The `asset` operation answers bytes instead of JSON (its failures stay JSON failures with the statuses above). GET and HEAD only; a request whose own URL path ends in `.data` is 404 before authentication; signed out 401 and forbidden 403 with no redirect; a missing, repeated or unacceptable `path` 400; a denied or unadmitted path 403.
|
|
113
114
|
After admission it answers 304 for a matching `If-None-Match`, 200 for the whole file (without `Accept-Ranges` and `Content-Length` when the host reports no size; empty with `Content-Length: 0` for an empty file), 206 for one satisfiable byte range, and 416 (`Content-Range: bytes */<size>`, `Cache-Control: private, no-store`) for a range starting at or after the end; HEAD carries the GET's status and headers without a body.
|
|
114
|
-
`If-None-Match` matches the ETag (`"<version>"`) as RFC 9110 evaluates it: `*`, or a comma-separated list holding the ETag by the weak comparison, so `W/"<version>"` matches too, while a malformed element matches nothing; an `If-Range` counts only when it is the ETag itself (the strong comparison).
|
|
115
|
+
`If-None-Match` matches the ETag (`"<version>"`; `"<legacy encoding>;<version>"` for the plain-text display, below) as RFC 9110 evaluates it: `*`, or a comma-separated list holding the ETag by the weak comparison, so `W/"<version>"` matches too, while a malformed element matches nothing; an `If-Range` counts only when it is the ETag itself (the strong comparison).
|
|
115
116
|
`If-None-Match` and `Range` are read only after admission, so a path outside every boundary is 403 even with a matching validator.
|
|
116
117
|
Every 200, 206 and 304 carries the declared type as a browser parses it (else `application/octet-stream`), `X-Content-Type-Options: nosniff`, `Content-Disposition` (`inline` or `attachment`, see [What the explorer serves](#what-the-explorer-serves)), `Content-Security-Policy: default-src 'none'; media-src 'self'; style-src 'unsafe-inline'; sandbox` except for PDF, `Cross-Origin-Resource-Policy: same-origin`, `Cache-Control: private, max-age=60, stale-while-revalidate=600, no-transform` and `Vary: Cookie`.
|
|
117
118
|
Inline audio and video get `sandbox allow-same-origin` instead of `sandbox`: the browser's media document of a file opened on its own fetches the file again, and under a plain `sandbox` its opaque origin would send that request cross-site, without the reader's `SameSite` cookie, to be answered 401; without `allow-scripts` no script runs.
|
|
118
119
|
The authentication's headers (a refreshed session cookie) go onto every asset response; the reader's scope header never does.
|
|
119
120
|
A body with a `Content-Length` carries exactly that many bytes: the bytes past it are dropped and the host's stream is cancelled, and a stream that ends short fails the response, so a file that changes while it is served never gets a body that disagrees with its length and ETag.
|
|
121
|
+
The plain-text display (`as=text`) names its `charset` from the file's first 64 KiB by the explorer's one text rule before it answers, holding the host's chunks that carry those bytes until they are sent:
|
|
122
|
+
a whole GET opens the file once and sends them first, and a HEAD or a range reads them on their own (as a range, or the whole file cancelled after them when the host reports no size; a range then opens its own bytes).
|
|
123
|
+
A beginning that ends before the reported size is answered `failed` (logged) before any header is sent. Its ETag is `"<legacy encoding>;<version>"` (the legacy encoding's written name, nothing when none is configured), so a cached copy revalidates into a new `charset` when the configuration changes. The bytes are sent as stored, never converted.
|
|
120
124
|
- Responses never contain tokens, principals, server paths or raw error messages. A failure carries only its reason and an optional host-defined code (`[a-z0-9-]{1,64}`); everything else goes to the server's `logger`. `new ExplorerError` throws a `RangeError` for a malformed code, and a failure document returned with one is logged and sent as `failed`.
|
|
121
125
|
|
|
122
126
|
- The `link-card` operation passes the answers of `@aiquants/markdown`'s link-card handler through unchanged (see [Link cards](#link-cards)): a card is `200` JSON with `Cache-Control: private, max-age=1800`, a link without a card `204 No Content` with `X-Link-Card-Skip`, and the handler's own errors JSON with `no-store`; each carries `nosniff` and never `Set-Cookie`. Only the explorer's own refusals in front of it (`not-found`, 405, a refused authentication) are the explorer's failure JSON above.
|
|
@@ -178,7 +182,7 @@ In a tree or children listing, an entry with an empty name, or with a path the b
|
|
|
178
182
|
## What the explorer serves
|
|
179
183
|
|
|
180
184
|
- Any regular file the document admission admits, whatever its kind: the bytes of image and media documents, the whole file behind a text preview, every `file` document (a file the explorer cannot show) and every image embedded in Markdown.
|
|
181
|
-
- Inline only for raster images, audio, video and PDF; everything else, SVG and an empty or unknown type included, as an attachment — unless the request asks for the plain-text display (`as=text`, the text viewers' Open in a new tab and a table file's preview), which shows any admitted file in place as `text/plain; charset
|
|
185
|
+
- Inline only for raster images, audio, video and PDF; everything else, SVG and an empty or unknown type included, as an attachment — unless the request asks for the plain-text display (`as=text`, the text viewers' Open in a new tab and a table file's preview), which shows any admitted file in place as `text/plain; charset=<encoding>` (the encoding the explorer's one text rule reads the file's first 64 KiB in) whatever its declared type,
|
|
182
186
|
under the same `nosniff` and sandboxing policy, so an HTML or SVG file opened that way shows its source and runs nothing. Both dispositions name the file (`filename*=UTF-8''<name>`, the RFC 8187 encoding of the name with `'`, `(`, `)` and `*` percent-encoded too), so a saved file keeps its name although every asset URL's path ends in `asset`.
|
|
183
187
|
- The type is the one the host declares, parsed as a browser parses it, never guessed from the name; `nosniff` stops the browser from guessing either, and the sandboxing policy keeps an SVG or HTML file opened on its own from running script.
|
|
184
188
|
- For `createFileSystemSource`, files of unknown extensions are downloadable, and so are the whole bytes of every Markdown and text file the source admits: raw Markdown keeps what the rendered view drops (front matter, HTML comments), and a text file is served beyond its preview. Its deny rules — `DEFAULT_DENIED_PATH_SEGMENTS` (environment files, keys and certificates, credential files, Terraform state, shell histories) plus the host's `deny` patterns — are the only filter, so add a pattern for anything else the folder must withhold.
|
|
@@ -103,11 +103,11 @@ The explorer serves every file it shows or offers for download through the `asse
|
|
|
103
103
|
| --- | --- |
|
|
104
104
|
| Path | `<dataPath>/asset`. GET and HEAD only; any other method answers 405 with `Allow: GET, HEAD`. |
|
|
105
105
|
| `path` | Required exactly once: the document path exactly as the explorer shows it (workspace-relative, `gcs://bucket/object`, `gdrive://…`), an acceptable document path; otherwise 400. `filePath` is not a parameter (`?filePath=` alone answers 400). |
|
|
106
|
-
| `v` | Written only on the URL a document carries (image, media, text and file documents), from the version the host reported: a cache-buster the server never reads. The response's ETag
|
|
107
|
-
| `as` | Optional: `text` (exactly once) asks for the file as
|
|
106
|
+
| `v` | Written only on the URL a document carries (image, media, text, spreadsheet and file documents), from the version the host reported: a cache-buster the server never reads. The response's ETag always names the file's current version (`"<version>"`, or `"<legacy encoding>;<version>"` with `as=text`). |
|
|
107
|
+
| `as` | Optional: `text` (exactly once) asks for the file as plain text shown in place (`text/plain; charset=<encoding>`, the encoding the explorer's one text rule reads the file's first 64 KiB in, `inline`), whatever type the host declares; any other value, an empty one or the parameter repeated answers 400 before the port is called. `explorerPlainTextHref(assetHref)` adds it to a text or spreadsheet document's `url` for the viewers' Open in a new tab. |
|
|
108
108
|
| Encoding | `encodeURIComponent` once, decoded once by `URLSearchParams`: exact for `%`, `#`, `?`, `+`, spaces, NFC and NFD names and a trailing `.data`. The request's own path always ends in `asset`, never in `.data`, so no name needs another escape. |
|
|
109
109
|
|
|
110
|
-
Two writers call it: the copy of the host's `document` answer, for the `url` of image, media, text and file documents (with `v`), and the sanitizer, for images marked with `data-asset-src` (without `v`). With `dataPath` `/docs/_data`:
|
|
110
|
+
Two writers call it: the copy of the host's `document` answer, for the `url` of image, media, text, spreadsheet and file documents (with `v`), and the sanitizer, for images marked with `data-asset-src` (without `v`). With `dataPath` `/docs/_data`:
|
|
111
111
|
|
|
112
112
|
- `` in `guide/README.md` → `<img data-asset-src="guide/images/diagram.png" data-asset-exists="true">` from the parser → `src="/docs/_data/asset?path=guide%2Fimages%2Fdiagram.png"` after the sanitizer.
|
|
113
113
|
- An image document opened in the tree view: `url: "/docs/_data/asset?path=guide%2Fimages%2Fdiagram.png&v=<version>"`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@aiquants/markdown-explorer",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.25.0",
|
|
4
4
|
"description": "Markdown document explorer for React Router 8 (framework mode): a source tree with a single-document view and a multi-panel reading view, storage-agnostic server ports, golden-ratio layout and an en / ja UI.",
|
|
5
5
|
"sideEffects": [
|
|
6
6
|
"**/*.css"
|
|
@@ -70,7 +70,7 @@
|
|
|
70
70
|
"peerDependencies": {
|
|
71
71
|
"@aiquants/directory-tree": "^5.0.1",
|
|
72
72
|
"@aiquants/drag-drop-panels": "^0.12.0",
|
|
73
|
-
"@aiquants/markdown": "^11.
|
|
73
|
+
"@aiquants/markdown": "^11.3.0",
|
|
74
74
|
"@aiquants/resize-panels": "^2.2.0",
|
|
75
75
|
"@aiquants/spreadsheet": "^0.16.1",
|
|
76
76
|
"@aiquants/virtualscroll": "^3.22.1",
|
|
@@ -81,7 +81,7 @@
|
|
|
81
81
|
"devDependencies": {
|
|
82
82
|
"@aiquants/directory-tree": "5.0.1",
|
|
83
83
|
"@aiquants/drag-drop-panels": "0.12.0",
|
|
84
|
-
"@aiquants/markdown": "11.
|
|
84
|
+
"@aiquants/markdown": "11.3.0",
|
|
85
85
|
"@aiquants/resize-panels": "2.2.0",
|
|
86
86
|
"@aiquants/spreadsheet": "0.16.1",
|
|
87
87
|
"@aiquants/virtualscroll": "3.22.1",
|