@aiquants/markdown-explorer 0.34.0 → 0.36.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 +608 -0
- package/README.md +121 -41
- package/dist/EditSurface-B70iRFkG.cjs +6 -0
- package/dist/EditSurface-BCFJRyIM.js +990 -0
- package/dist/ExplorerSplit-BNrHrIus.cjs +2 -0
- package/dist/ExplorerSplit-Bgccz2nm.js +1589 -0
- package/dist/MultiLayout-Bo9LAXiY.cjs +1 -0
- package/dist/{MultiLayout-kcZyVnvK.js → MultiLayout-Dy5TIC2t.js} +249 -248
- package/dist/{NativeScrollBar-pUbA4Zq3.cjs → NativeScrollBar-Bj-LKej0.cjs} +1 -1
- package/dist/{NativeScrollBar-UNed10Na.js → NativeScrollBar-DpZMYhmf.js} +2 -2
- package/dist/TreeLayout-DsSKW_Qj.js +103 -0
- package/dist/TreeLayout-T8sc_wg7.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 +13 -0
- package/dist/core/config.d.ts +13 -0
- package/dist/core/contracts.d.cts +31 -4
- package/dist/core/contracts.d.ts +31 -4
- package/dist/core/dataRoute.d.cts +5 -1
- package/dist/core/dataRoute.d.ts +5 -1
- package/dist/core/documentId.d.cts +6 -0
- package/dist/core/documentId.d.ts +6 -0
- package/dist/core/draftAnswer.d.cts +23 -0
- package/dist/core/draftAnswer.d.ts +23 -0
- package/dist/core/labels.d.cts +78 -0
- package/dist/core/labels.d.ts +78 -0
- package/dist/core/location.d.cts +22 -2
- package/dist/core/location.d.ts +22 -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 +3 -1
- package/dist/core/viewSettings.d.ts +3 -1
- package/dist/describeValue-CLlVRO8d.js +17 -0
- package/dist/describeValue-Ccvhbt36.cjs +1 -0
- package/dist/explorerCore-B3RGmMG6.js +1083 -0
- package/dist/explorerCore-CUkyKtm8.cjs +1 -0
- package/dist/index-D0l_BJqb.js +5980 -0
- package/dist/index-lpL7GltU.cjs +18 -0
- package/dist/index.cjs +1 -1
- package/dist/index.d.cts +8 -4
- package/dist/index.d.ts +8 -4
- package/dist/index.js +53 -43
- 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-Dh6K-y7w.js +761 -0
- package/dist/location-DrOP6t1F.cjs +1 -0
- package/dist/lru-DC8GBmkX.js +39 -0
- package/dist/lru-SGmUyBQU.cjs +1 -0
- package/dist/{merge-C1MWvhCS.js → merge-BwcqBd4c.js} +1 -1
- package/dist/{merge-BziXxZkE.cjs → merge-Dckw7r9T.cjs} +1 -1
- package/dist/nestingGuardWorker.js +5511 -0
- package/dist/ownUrls-BTPGNhBt.cjs +1 -0
- package/dist/ownUrls-DD0cSCsF.js +409 -0
- package/dist/sanitizeJob-BYqzjFJC.js +21 -0
- package/dist/sanitizeJob-CudE1RUP.cjs +1 -0
- package/dist/sanitizePolicy-C-ehd0J_.cjs +2 -0
- package/dist/sanitizePolicy-DAPnUUVm.js +139 -0
- package/dist/sanitizeWorker.cjs +1 -1
- package/dist/sanitizeWorker.js +134 -139
- package/dist/sanitizerService-B8v4ap9t.js +240 -0
- package/dist/sanitizerService-DomN7lwC.cjs +1 -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/errors.d.cts +1 -1
- package/dist/server/errors.d.ts +1 -1
- 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 +55 -5
- package/dist/server/ports.d.ts +55 -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-DigcJCsu.cjs → tapScrollCircle-DyLInGck.cjs} +1 -1
- package/dist/{tapScrollCircle-D_BpaLwY.js → tapScrollCircle-smKLgRa2.js} +1 -1
- package/dist/testing.cjs +1 -0
- package/dist/testing.d.cts +11 -0
- package/dist/testing.d.ts +11 -0
- package/dist/testing.js +82 -0
- package/dist/useSplitPersistence-BUa_KMsV.cjs +1 -0
- package/dist/useSplitPersistence-pnb21dsr.js +44 -0
- package/docs/behavior/dom-hooks.md +5 -1
- package/docs/behavior/hosting.md +123 -0
- package/docs/behavior/layout.md +5 -3
- package/docs/behavior/localization.md +25 -8
- package/docs/behavior/security.md +55 -15
- package/docs/behavior/url-contract.md +30 -3
- package/package.json +48 -10
- package/dist/EditSurface-CF82jZQg.cjs +0 -6
- package/dist/EditSurface-CqHk2R3k.js +0 -982
- package/dist/ExplorerSplit-D325YGEf.cjs +0 -1
- package/dist/ExplorerSplit-DGH9bckm.js +0 -1500
- package/dist/MultiLayout-CzR7yJ0m.cjs +0 -1
- package/dist/TreeLayout-BnIU87HX.js +0 -96
- package/dist/TreeLayout-DtvIpuOe.cjs +0 -1
- package/dist/dataRoute-D6KiSHIc.js +0 -298
- package/dist/dataRoute-DwYtgyt6.cjs +0 -1
- package/dist/index-BDCbvHDs.cjs +0 -15
- package/dist/index-DR31S_-4.js +0 -5012
- package/dist/location-C44b9H1S.js +0 -676
- package/dist/location-hGLhCCg4.cjs +0 -1
- package/dist/sanitizePolicy-CwvyPpp5.js +0 -98
- package/dist/sanitizePolicy-T5T-3vV5.cjs +0 -1
- package/dist/storage-DM0EvkVf.cjs +0 -1
- package/dist/useSplitPersistence-DCeYbJMx.js +0 -38
- package/dist/useSplitPersistence-QGcvyMAa.cjs +0 -1
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
export type DenyVector = {
|
|
2
|
+
readonly pattern: string;
|
|
3
|
+
readonly path: string;
|
|
4
|
+
readonly expect: boolean;
|
|
5
|
+
};
|
|
6
|
+
export type DocumentIdVector = {
|
|
7
|
+
readonly written: string;
|
|
8
|
+
readonly canonical: string | null;
|
|
9
|
+
};
|
|
10
|
+
export declare const denyVectors: () => readonly DenyVector[];
|
|
11
|
+
export declare const documentIdVectors: () => readonly DocumentIdVector[];
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
export type DenyVector = {
|
|
2
|
+
readonly pattern: string;
|
|
3
|
+
readonly path: string;
|
|
4
|
+
readonly expect: boolean;
|
|
5
|
+
};
|
|
6
|
+
export type DocumentIdVector = {
|
|
7
|
+
readonly written: string;
|
|
8
|
+
readonly canonical: string | null;
|
|
9
|
+
};
|
|
10
|
+
export declare const denyVectors: () => readonly DenyVector[];
|
|
11
|
+
export declare const documentIdVectors: () => readonly DocumentIdVector[];
|
package/dist/testing.js
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
const a = /* @__PURE__ */ JSON.parse('[{"pattern":".env*","path":".env","expect":true},{"pattern":".env*","path":"apps/web/.env.production","expect":true},{"pattern":".env*","path":".envrc","expect":true},{"pattern":".env*","path":".env~","expect":true},{"pattern":".env*","path":".env-old","expect":true},{"pattern":".env*","path":".env_backup","expect":true},{"pattern":".env*","path":"docs/environment.md","expect":false},{"pattern":".env*","path":"docs/prod.env","expect":false},{"pattern":"*.env","path":"prod.env","expect":true},{"pattern":"*.env","path":"config/staging.env","expect":true},{"pattern":"*.env","path":"prod.env.bak","expect":false},{"pattern":"*.env","path":"environment.md","expect":false},{"pattern":"*.env.*","path":"prod.env.bak","expect":true},{"pattern":"*.env.*","path":"config/deploy.env.production","expect":true},{"pattern":"*.env.*","path":"prod.env","expect":false},{"pattern":"*.env.*","path":"prod.environment.md","expect":false},{"pattern":"*.env~*","path":"prod.env~","expect":true},{"pattern":"*.env~*","path":"config/prod.env~1","expect":true},{"pattern":"*.env~*","path":"prod.env","expect":false},{"pattern":"*.env-*","path":"prod.env-old","expect":true},{"pattern":"*.env-*","path":"config/app.env-2026","expect":true},{"pattern":"*.env-*","path":"my-env-file.md","expect":false},{"pattern":"*.env_*","path":"prod.env_backup","expect":true},{"pattern":"*.env_*","path":"config/app.env_local","expect":true},{"pattern":"*.env_*","path":"my_env_file.md","expect":false},{"pattern":"*.env#*","path":"#prod.env#","expect":true},{"pattern":"*.env#*","path":"config/prod.env#1","expect":true},{"pattern":"*.env#*","path":"prod.env","expect":false},{"pattern":".git","path":".git/config","expect":true},{"pattern":".git","path":"sub/.git/HEAD","expect":true},{"pattern":".git","path":".github/workflows/ci.yml","expect":false},{"pattern":".git","path":".gitignore","expect":false},{"pattern":".git-credentials","path":".git-credentials","expect":true},{"pattern":".git-credentials","path":"home/.git-credentials","expect":true},{"pattern":".git-credentials","path":"git-credentials","expect":false},{"pattern":".svn","path":".svn/entries","expect":true},{"pattern":".svn","path":"svn/entries","expect":false},{"pattern":".hg","path":".hg/hgrc","expect":true},{"pattern":".hg","path":".hgignore","expect":false},{"pattern":"node_modules","path":"node_modules/pkg/index.js","expect":true},{"pattern":"node_modules","path":"packages/a/node_modules/b/README.md","expect":true},{"pattern":"node_modules","path":"docs/node_modules_guide.md","expect":false},{"pattern":"secrets","path":"secrets/api.md","expect":true},{"pattern":"secrets","path":"config/secrets/prod.json","expect":true},{"pattern":"secrets","path":"docs/secrets-overview.md","expect":false},{"pattern":".secrets","path":".secrets/key","expect":true},{"pattern":".secrets","path":"app/.secrets","expect":true},{"pattern":".secrets","path":".secrets.md","expect":false},{"pattern":"secrets.json","path":"secrets.json","expect":true},{"pattern":"secrets.json","path":"config/secrets.json","expect":true},{"pattern":"secrets.json","path":"my-secrets.json","expect":false},{"pattern":"secrets.yml","path":"config/secrets.yml","expect":true},{"pattern":"secrets.yml","path":"secrets.yaml","expect":false},{"pattern":"secrets.yaml","path":"config/secrets.yaml","expect":true},{"pattern":"secrets.yaml","path":"secrets.yml","expect":false},{"pattern":"secrets.toml","path":"config/secrets.toml","expect":true},{"pattern":"secrets.toml","path":"secrets.toml.example","expect":false},{"pattern":"secrets.ini","path":"config/secrets.ini","expect":true},{"pattern":"secrets.ini","path":"app.ini","expect":false},{"pattern":"secrets.txt","path":"notes/secrets.txt","expect":true},{"pattern":"secrets.txt","path":"secrets.txt.bak","expect":false},{"pattern":".ssh","path":".ssh/id_rsa","expect":true},{"pattern":".ssh","path":"home/user/.ssh/config","expect":true},{"pattern":".ssh","path":".ssh_config","expect":false},{"pattern":".aws","path":".aws/credentials","expect":true},{"pattern":".aws","path":"home/user/.aws/config","expect":true},{"pattern":".aws","path":".aws-sam/build.toml","expect":false},{"pattern":".gnupg","path":".gnupg/secring.gpg","expect":true},{"pattern":".gnupg","path":".gnupg2/pubring.kbx","expect":false},{"pattern":".docker","path":".docker/config.json","expect":true},{"pattern":".docker","path":"docker/Dockerfile","expect":false},{"pattern":".kube","path":".kube/config","expect":true},{"pattern":".kube","path":"kube/deployment.yaml","expect":false},{"pattern":".terraform","path":".terraform/terraform.tfstate","expect":true},{"pattern":".terraform","path":"terraform/main.tf","expect":false},{"pattern":".npmrc","path":".npmrc","expect":true},{"pattern":".npmrc","path":"packages/web/.npmrc","expect":true},{"pattern":".npmrc","path":"npmrc","expect":false},{"pattern":".yarnrc","path":".yarnrc","expect":true},{"pattern":".yarnrc","path":".yarnrc.yml","expect":false},{"pattern":".yarnrc.yml","path":".yarnrc.yml","expect":true},{"pattern":".yarnrc.yml","path":".yarnrc","expect":false},{"pattern":".netrc","path":".netrc","expect":true},{"pattern":".netrc","path":"_netrc","expect":false},{"pattern":"_netrc","path":"_netrc","expect":true},{"pattern":"_netrc","path":".netrc","expect":false},{"pattern":".pypirc","path":"home/.pypirc","expect":true},{"pattern":".pypirc","path":"pypirc","expect":false},{"pattern":".pgpass","path":"home/.pgpass","expect":true},{"pattern":".pgpass","path":"pgpass.conf","expect":false},{"pattern":".my.cnf","path":"home/.my.cnf","expect":true},{"pattern":".my.cnf","path":"my.cnf","expect":false},{"pattern":".htpasswd","path":"etc/nginx/.htpasswd","expect":true},{"pattern":".htpasswd","path":"htpasswd","expect":false},{"pattern":".vault-token","path":"home/.vault-token","expect":true},{"pattern":".vault-token","path":"vault-token","expect":false},{"pattern":"id_rsa*","path":"id_rsa","expect":true},{"pattern":"id_rsa*","path":"keys/id_rsa.pub","expect":true},{"pattern":"id_rsa*","path":"my_id_rsa","expect":false},{"pattern":"id_dsa*","path":"legacy/id_dsa","expect":true},{"pattern":"id_dsa*","path":"my_id_dsa","expect":false},{"pattern":"id_ecdsa*","path":"keys/id_ecdsa-cert.pub","expect":true},{"pattern":"id_ecdsa*","path":"my_id_ecdsa","expect":false},{"pattern":"id_ed25519*","path":"keys/id_ed25519.pub","expect":true},{"pattern":"id_ed25519*","path":"my_id_ed25519","expect":false},{"pattern":"*.pem","path":"tls/fullchain.pem","expect":true},{"pattern":"*.pem","path":"tls/fullchain.pem.bak","expect":false},{"pattern":"*.key","path":"certs/server.key","expect":true},{"pattern":"*.key","path":"certs/server.key.pub","expect":false},{"pattern":"*.p8","path":"apple/AuthKey_123.p8","expect":true},{"pattern":"*.p8","path":"apple/AuthKey_123.p8.txt","expect":false},{"pattern":"*.p12","path":"certs/client.p12","expect":true},{"pattern":"*.p12","path":"certs/client.p12.enc","expect":false},{"pattern":"*.pfx","path":"win/signing.pfx","expect":true},{"pattern":"*.pfx","path":"win/signing.pfx.bak","expect":false},{"pattern":"*.ppk","path":"putty/server.ppk","expect":true},{"pattern":"*.ppk","path":"putty/server.ppk.old","expect":false},{"pattern":"*.jks","path":"java/keystore.jks","expect":true},{"pattern":"*.jks","path":"java/keystore.jks.bak","expect":false},{"pattern":"*.keystore","path":"android/release.keystore","expect":true},{"pattern":"*.keystore","path":"android/keystore.properties","expect":false},{"pattern":"*.kdbx","path":"vault/passwords.kdbx","expect":true},{"pattern":"*.kdbx","path":"vault/passwords.kdbx.html","expect":false},{"pattern":"*credentials*.json","path":"gcp/client_credentials_prod.json","expect":true},{"pattern":"*credentials*.json","path":"credentials.json","expect":true},{"pattern":"*credentials*.json","path":"gcp/credentials.yaml","expect":false},{"pattern":"service-account*.json","path":"gcp/service-account-prod.json","expect":true},{"pattern":"service-account*.json","path":"gcp/my-service-account.json","expect":false},{"pattern":"*.tfstate","path":"infra/terraform.tfstate","expect":true},{"pattern":"*.tfstate","path":"infra/terraform.tfstate.backup","expect":false},{"pattern":"*.tfstate.*","path":"infra/terraform.tfstate.backup","expect":true},{"pattern":"*.tfstate.*","path":"infra/terraform.tfstate","expect":false},{"pattern":"*.tfvars","path":"infra/prod.tfvars","expect":true},{"pattern":"*.tfvars","path":"infra/prod.tfvars.json","expect":false},{"pattern":"*.tfvars.json","path":"infra/prod.tfvars.json","expect":true},{"pattern":"*.tfvars.json","path":"infra/prod.tfvars","expect":false},{"pattern":".*_history","path":"home/.bash_history","expect":true},{"pattern":".*_history","path":"home/.zsh_history","expect":true},{"pattern":".*_history","path":"home/bash_history","expect":false},{"pattern":"fish_history","path":"local/share/fish/fish_history","expect":true},{"pattern":"fish_history","path":"docs/fish_history.md","expect":false},{"pattern":".env*","path":".ENV","expect":true},{"pattern":".env*","path":"docs/.Env.Local","expect":true},{"pattern":"*.pem","path":"TLS/Server.PEM","expect":true},{"pattern":"id_ed25519*","path":"keys/ID_ED25519.PUB","expect":true},{"pattern":".AWS","path":"docs/.aws/credentials","expect":true},{"pattern":"*.KEY","path":"certs/tls.key","expect":true},{"pattern":"secrets","path":"docs/ſecrets/note.md","expect":true},{"pattern":".ssh","path":".ſsh/config","expect":true},{"pattern":"id_rsa*","path":"keys/ıd_rsa","expect":true},{"pattern":".env*","path":"docs/.env","expect":true},{"pattern":".ssh","path":".ssh/config","expect":true},{"pattern":"*.key","path":"tls/server.Key","expect":true},{"pattern":".ENV*","path":"apps/.env.local","expect":true},{"pattern":".env*","path":"docs\.env","expect":true},{"pattern":".env*","path":"docs/.env","expect":true},{"pattern":".env*","path":"%2eenv","expect":true},{"pattern":".env*","path":"%2E%45%4E%56","expect":true},{"pattern":".ssh","path":"docs/%2essh/config","expect":true},{"pattern":".env*","path":"%252eenv","expect":true},{"pattern":".aws","path":"docs/%252Eaws/credentials","expect":true},{"pattern":"*.pem","path":"certs/root%252Epem","expect":true},{"pattern":".env*","path":"%25252eenv","expect":true},{"pattern":".gnupg","path":"home/%25252Egnupg/key","expect":true},{"pattern":"id_rsa*","path":"keys/%252569d_rsa","expect":true},{"pattern":".env*","path":"docs%2f.env","expect":true},{"pattern":".ssh","path":"docs%252f.ssh%252fconfig","expect":true},{"pattern":".aws","path":"docs%25255c.aws%25255ccredentials","expect":true},{"pattern":".env*","path":"docs/%EF%BC%8Eenv","expect":true},{"pattern":".env*","path":"docs/%25EF%25BC%258Eenv","expect":true},{"pattern":".env*","path":".env.%ZZlocal","expect":true},{"pattern":".env*","path":"%2eenv.%ZZ","expect":true},{"pattern":".env*","path":"%2eenv.trail%","expect":true},{"pattern":".env*","path":"%2eenv.short%2","expect":true},{"pattern":"secrets","path":"secrets%2F%ZZ","expect":true},{"pattern":".env*","path":"%FF/.env","expect":true},{"pattern":".env*","path":"%ZZenv","expect":false},{"pattern":".env*","path":"%2Genv","expect":false},{"pattern":"*credentials*.json","path":"my-credentials\\\\backup.json","expect":true},{"pattern":"*credentials*.json","path":"my-credentials%5Cbackup.json","expect":true},{"pattern":".env*","path":"apps\\\\backend\\\\.env","expect":true},{"pattern":".ssh","path":"C:\\\\Users\\\\example\\\\.ssh\\\\id","expect":true},{"pattern":"*.key","path":"certs\\\\prod/tls.key","expect":true},{"pattern":".env*","path":"///docs///.env///","expect":true},{"pattern":".env*","path":"\\\\\\\\\\\\docs\\\\\\\\\\\\.env\\\\\\\\","expect":true},{"pattern":".env*","path":"","expect":false},{"pattern":".env*","path":"/","expect":false},{"pattern":".env*","path":"\\\\","expect":false},{"pattern":".env.?","path":".env.?","expect":true},{"pattern":".env.?","path":".env.a","expect":false},{"pattern":"file+[1](test)$^|{2}.txt","path":"dir/file+[1](test)$^|{2}.txt","expect":true},{"pattern":"file+[1](test)$^|{2}.txt","path":"dir/file+1(test)$^|{2}.txt","expect":false},{"pattern":"a|b.md","path":"docs/a|b.md","expect":true},{"pattern":"a|b.md","path":"docs/a.md","expect":false},{"pattern":"foo+bar.md","path":"docs/foo+bar.md","expect":true},{"pattern":"foo+bar.md","path":"docs/fooooobar.md","expect":false},{"pattern":"unrelated","path":"docs/safe-%252561-name/readme.md","expect":false},{"pattern":".env","path":"%2525252Eenv","expect":true},{"pattern":".env*","path":"%2525252Eenv","expect":true},{"pattern":".aws","path":"docs/%2525252Eaws/credentials","expect":true},{"pattern":"unrelated","path":"%2525252Eenv","expect":true},{"pattern":"unrelated","path":"docs/%2525252Eaws/credentials","expect":true},{"pattern":"unrelated","path":"docs/safe-%25252561-name/readme.md","expect":true},{"pattern":".env*","path":"%252525252Eenv","expect":true},{"pattern":"unrelated","path":"a/b/%2525252F/c.md","expect":true},{"pattern":"unrelated","path":"a/b/%2525255C..%2525255C/c.md","expect":true},{"pattern":"unrelated","path":"docs/%2525252Eenv%ZZ","expect":true}]'), r = [
|
|
2
|
+
{
|
|
3
|
+
written: "7K3M9QX2AB4W",
|
|
4
|
+
canonical: "7K3M9QX2AB4W"
|
|
5
|
+
},
|
|
6
|
+
{
|
|
7
|
+
written: "1A0B1C0D1E0J",
|
|
8
|
+
canonical: "1A0B1C0D1E0J"
|
|
9
|
+
},
|
|
10
|
+
{
|
|
11
|
+
written: "000000000000",
|
|
12
|
+
canonical: "000000000000"
|
|
13
|
+
},
|
|
14
|
+
{
|
|
15
|
+
written: "0000000000ZZ",
|
|
16
|
+
canonical: "0000000000ZZ"
|
|
17
|
+
},
|
|
18
|
+
{
|
|
19
|
+
written: "7K3M-9QX2-AB4W",
|
|
20
|
+
canonical: "7K3M9QX2AB4W"
|
|
21
|
+
},
|
|
22
|
+
{
|
|
23
|
+
written: "7k3m-9qx2-ab4w",
|
|
24
|
+
canonical: "7K3M9QX2AB4W"
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
written: "-7K3M--9QX2-AB4W-",
|
|
28
|
+
canonical: "7K3M9QX2AB4W"
|
|
29
|
+
},
|
|
30
|
+
{
|
|
31
|
+
written: "lAoB-iCoD-lEoj",
|
|
32
|
+
canonical: "1A0B1C0D1E0J"
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
written: "7K3M9RX2AB4W",
|
|
36
|
+
canonical: null
|
|
37
|
+
},
|
|
38
|
+
{
|
|
39
|
+
written: "7KM39QX2AB4W",
|
|
40
|
+
canonical: null
|
|
41
|
+
},
|
|
42
|
+
{
|
|
43
|
+
written: "ZZZZZZZZZZZ$",
|
|
44
|
+
canonical: null
|
|
45
|
+
},
|
|
46
|
+
{
|
|
47
|
+
written: "00000000014U",
|
|
48
|
+
canonical: null
|
|
49
|
+
},
|
|
50
|
+
{
|
|
51
|
+
written: "7K3M9QX2AB4",
|
|
52
|
+
canonical: null
|
|
53
|
+
},
|
|
54
|
+
{
|
|
55
|
+
written: "7K3M9QX2AB4WX",
|
|
56
|
+
canonical: null
|
|
57
|
+
},
|
|
58
|
+
{
|
|
59
|
+
written: "",
|
|
60
|
+
canonical: null
|
|
61
|
+
},
|
|
62
|
+
{
|
|
63
|
+
written: "----",
|
|
64
|
+
canonical: null
|
|
65
|
+
},
|
|
66
|
+
{
|
|
67
|
+
written: "7K3M 9QX2 AB4W",
|
|
68
|
+
canonical: null
|
|
69
|
+
},
|
|
70
|
+
{
|
|
71
|
+
written: "7K3M9QX2AB4W",
|
|
72
|
+
canonical: null
|
|
73
|
+
},
|
|
74
|
+
{
|
|
75
|
+
written: "ıA0B1C0D1E0J",
|
|
76
|
+
canonical: null
|
|
77
|
+
}
|
|
78
|
+
], n = Object.freeze(a.map(({ pattern: e, path: t, expect: p }) => Object.freeze({ pattern: e, path: t, expect: p }))), c = Object.freeze(r.map(({ written: e, canonical: t }) => Object.freeze({ written: e, canonical: t }))), s = () => n, h = () => c;
|
|
79
|
+
export {
|
|
80
|
+
s as denyVectors,
|
|
81
|
+
h as documentIdVectors
|
|
82
|
+
};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"use strict";const e=require("react"),m=require("./location-DrOP6t1F.cjs"),f=u=>({minimumExceededSummary:u.panelGroupMinimumExceededSummary,minimumExceededDetail:u.panelGroupMinimumExceededDetail,maximumInsufficientSummary:u.panelGroupMaximumInsufficientSummary,maximumInsufficientDetail:u.panelGroupMaximumInsufficientDetail}),d=u=>{const a=e.useRef(u);e.useLayoutEffect(()=>{a.current=u},[u]);const c=e.useRef(null),r=e.useRef(null),n=e.useRef(!1),t=e.useCallback(()=>{r.current!==null&&clearTimeout(r.current),r.current=setTimeout(()=>{r.current=null,c.current!==null&&a.current(c.current)},m.SPLIT_PERSIST_DELAY_MS)},[]);e.useEffect(()=>()=>{r.current!==null&&clearTimeout(r.current)},[]);const s=e.useCallback((i,o)=>{c.current=i,o.source==="keyboard"?t():o.source==="pointer"&&(n.current=!0)},[t]),l=e.useCallback(i=>{if(i){n.current=!1;return}n.current&&(n.current=!1,t())},[t]);return e.useMemo(()=>({layoutChanged:s,draggingChanged:l}),[s,l])};exports.toPanelGroupLabels=f;exports.useSplitPersistence=d;
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import { useRef as t, useLayoutEffect as f, useCallback as m, useEffect as d, useMemo as p } from "react";
|
|
2
|
+
import { S } from "./location-Dh6K-y7w.js";
|
|
3
|
+
const E = (e) => ({
|
|
4
|
+
minimumExceededSummary: e.panelGroupMinimumExceededSummary,
|
|
5
|
+
minimumExceededDetail: e.panelGroupMinimumExceededDetail,
|
|
6
|
+
maximumInsufficientSummary: e.panelGroupMaximumInsufficientSummary,
|
|
7
|
+
maximumInsufficientDetail: e.panelGroupMaximumInsufficientDetail
|
|
8
|
+
}), M = (e) => {
|
|
9
|
+
const o = t(e);
|
|
10
|
+
f(() => {
|
|
11
|
+
o.current = e;
|
|
12
|
+
}, [e]);
|
|
13
|
+
const i = t(null), u = t(null), r = t(!1), n = m(() => {
|
|
14
|
+
u.current !== null && clearTimeout(u.current), u.current = setTimeout(() => {
|
|
15
|
+
u.current = null, i.current !== null && o.current(i.current);
|
|
16
|
+
}, S);
|
|
17
|
+
}, []);
|
|
18
|
+
d(
|
|
19
|
+
() => () => {
|
|
20
|
+
u.current !== null && clearTimeout(u.current);
|
|
21
|
+
},
|
|
22
|
+
[]
|
|
23
|
+
);
|
|
24
|
+
const a = m(
|
|
25
|
+
(c, s) => {
|
|
26
|
+
i.current = c, s.source === "keyboard" ? n() : s.source === "pointer" && (r.current = !0);
|
|
27
|
+
},
|
|
28
|
+
[n]
|
|
29
|
+
), l = m(
|
|
30
|
+
(c) => {
|
|
31
|
+
if (c) {
|
|
32
|
+
r.current = !1;
|
|
33
|
+
return;
|
|
34
|
+
}
|
|
35
|
+
r.current && (r.current = !1, n());
|
|
36
|
+
},
|
|
37
|
+
[n]
|
|
38
|
+
);
|
|
39
|
+
return p(() => ({ layoutChanged: a, draggingChanged: l }), [a, l]);
|
|
40
|
+
};
|
|
41
|
+
export {
|
|
42
|
+
E as t,
|
|
43
|
+
M as u
|
|
44
|
+
};
|
|
@@ -37,6 +37,7 @@ Tests and host styling may rely on the `data-testid` values and `data-aqmx-*` at
|
|
|
37
37
|
| `data-testid="markdown-explorer-unsaved-guard"` / `-cancel` / `-confirm` | The confirmation before a navigation drops unsaved drafts (a modal `dialog`, one per explorer) | As above; `-confirm` drops those drafts and goes on |
|
|
38
38
|
| `data-testid="markdown-explorer-history"` | The revisions dialog (a modal `dialog`, named `historyTitle`) | Holds `-history-loading`, `-history-failure` or `-history-empty`, else `-history-list` of `-history-entry` buttons (`aria-pressed` for the one shown), the picked revision's text `-history-text` (focusable, so the keyboard scrolls it) or `-history-revision-failure`, and `-history-close` and `-history-restore` (`aria-disabled` until a revision's text is shown) |
|
|
39
39
|
| `data-testid="markdown-explorer-document-refresh"` | The Refresh document button, in the bar | Reads that document alone again past the host's caches. The page views name it by its visible label (`refreshDocumentLabel`; tooltip `refreshDocument`); a panel's is icon-only, with `aria-label` and `title` set to `refreshDocumentNamed` (the panel title). Carries `aria-busy="true"` and `data-aqmx-busy="true"` while it runs, and `aria-disabled="true"` then and while the document loads (never `disabled`) |
|
|
40
|
+
| `data-testid="markdown-explorer-document-permalink"` | The Copy permalink button, in the bar after Refresh document | Drawn with `documentIds` in the configuration while the document is not edited, from the server's render on (see [URL contract](url-contract.md#document-ids)); `aria-disabled="true"` while the document loads or failed, when it ignores presses. The page views name it by its visible label (`copyPermalinkLabel`; tooltip `copyPermalink`); a panel's is icon-only, with `aria-label` and `title` set to `copyPermalinkNamed`. Carries `data-aqmx-copy-outcome`: `idle`, then `copied` or `failed` for 2 seconds after a press, while its `title` says what happened (its name never changes; the announcer speaks the outcome). |
|
|
40
41
|
| `data-testid="markdown-explorer-document-maximize"` | The Maximize button that ends the tree view's document bar | Icon-only, with `aria-label` and `title` naming what a press does (`documentMaximize`, or `documentRestore` while the document is maximized) and no `aria-pressed`; the same element in every state. Absent in the single view and in a multi-view panel |
|
|
41
42
|
| `data-aqmx-maximized` | The tree view's document column (the bar and the document region, `data-aqmx-content-pane`) | `true` while the column covers the page — the document is maximized and has something to show, or its folder's README is being looked for — else `false` (a multi-view panel's frame carries the same attribute, see [Multi-panel view](#multi-panel-view)) |
|
|
42
43
|
| `data-testid="markdown-explorer-document-refresh-failure"` | Notice of a document refresh that failed, inside the bar below its button row | No live role (the announcer speaks the same text); carries `data-aqmx-failure` (the reason). The failure is the document's answer, or the reading of the part the document's content reads itself (a table file's table, a document shown as written) when that content showed a copy of it, which stays. Shown while the copy of the document it kept stays on screen: a newer answer that replaces or confirms that copy, a move to another document (it does not come back on return), a switch between the document rendered and as written and that control's next refresh take it down. It is the one notice of a failed refresh: no notice inside the document repeats it |
|
|
@@ -81,9 +82,12 @@ The tree's stand-in Tab stop, present while the tab-stop row is outside the tree
|
|
|
81
82
|
| `data-testid="markdown-explorer-document-empty"` | No document selected | |
|
|
82
83
|
| `data-testid="markdown-explorer-folder-empty"` | The tree view's folder without a README | The region carries `data-aqmx-document-kind="empty"`; a page view announces the text (`folderReadmeMissing`) once for each folder shown |
|
|
83
84
|
| `data-testid="markdown-explorer-folder-failure"` | Failure to list the tree view's folder, or to load the tree it lies in | Carries `data-aqmx-failure` (the reason; `not-found` for no such folder); its callout has no role: the announcer speaks the failure (`documentFailed`, with the folder's name), once for each failed attempt. A `failed` listing offers Try again (`retry`) |
|
|
84
|
-
| `data-testid="markdown-explorer-document-skeleton"` | Placeholder while a pane has no document to show yet (its first document, one the server gave up on,
|
|
85
|
+
| `data-testid="markdown-explorer-document-skeleton"` | Placeholder while a pane has no document to show yet (its first document, one the server gave up on, the README of the tree view's folder while it is looked for, or the document of an ID URL while its ID is resolved) | The region carries `aria-busy="true"` |
|
|
85
86
|
| `data-testid="markdown-explorer-document-progress"` | Progress bar while the next document (or a fresh copy of a failed one) loads over the one still shown | The region carries `aria-busy="true"` meanwhile, also during router navigations |
|
|
86
87
|
| `data-testid="markdown-explorer-document-failure"` | Document failure | Carries `data-aqmx-failure` (the reason); its callout has no role in every view (tree, single and multi-view panels): the announcer speaks the failure (`documentFailed`), once for each failed attempt |
|
|
88
|
+
| `data-testid="markdown-explorer-document-id-failure"` | Failure to open the document of an ID URL, in the document's place | Carries `data-aqmx-failure` (the reason); its callout has no role: the announcer speaks the failure. Holds Try again only for `failed`, which resolves the ID again (see [URL contract](url-contract.md#document-ids)). |
|
|
89
|
+
| `data-testid="markdown-explorer-document-notices"` | The notices above a document region | `role="status"` (polite, not atomic), in the page whenever the pane shows a document and empty while there is nothing to tell, so each notice is spoken as it appears; in this order: the document changed elsewhere, media that could not be loaded, media that cannot be played |
|
|
90
|
+
| `data-testid="markdown-explorer-document-notice"` | One notice above the document | Carries `data-aqmx-notice` (`changed` under the host change policy `"notify"`, `media-load` or `media-unplayable`) and `data-aqmx-tone` (`info` for `changed`, `warning` for the media); `changed` and `media-load` hold a Reload button (`reload`), and a media notice names the one medium it tells of or counts two or more |
|
|
87
91
|
| `data-testid="markdown-explorer-text-truncated"` | Notice under a cut text preview, or a cut source of a Markdown document shown as written | |
|
|
88
92
|
| `data-testid="markdown-explorer-markup-skeleton"` | Placeholder while the source of a Markdown document shown as written loads (until its first answer) | Hidden from assistive technology; the region holds the screen-reader text `markupLoading` beside it |
|
|
89
93
|
| `data-testid="markdown-explorer-markup-failure"` | Failure to read the source of a document shown as written before any source was read | Carries `data-aqmx-failure` (the reason); its callout has no role: the pane's announcer speaks the failure (`documentFailed`), once for each answer. A `failed` read offers Try again (`retry`); when the retry succeeds the focus moves into the source and a page view announces the document (`documentShown`) |
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Hosting
|
|
2
|
+
|
|
3
|
+
This page is part of the host-facing contract of `@aiquants/markdown-explorer`; its summary is in the [README](../../README.md#installation).
|
|
4
|
+
|
|
5
|
+
The explorer's server half runs on Node behind `@aiquants/markdown-explorer/server`, or inside the page itself — a desktop webview, or a page that answers from what it bundles — on the browser runtime of `@aiquants/markdown-explorer/server/browser`. Both complete the same core, `createExplorerServer` of `@aiquants/markdown-explorer/server/core`, so the explorer answers alike on either.
|
|
6
|
+
|
|
7
|
+
## Entries
|
|
8
|
+
|
|
9
|
+
| Entry | What it holds | What it never loads |
|
|
10
|
+
| --- | --- | --- |
|
|
11
|
+
| `@aiquants/markdown-explorer` | The browser half: `<MarkdownExplorer>` with the handle its `ref` receives and what a host exchanges with it, the shared configuration, the URL contract, the label catalogs, the contract of a browser draft converter with its helpers (`draftAnswerOf`, `draftConversionOf`), the rule of a document's language (`isExplorerDocumentLang`) and the deny rules. | A Node built-in, the server half or `@aiquants/markdown/server`. What a single-view page loads up front also leaves out the tree, split, virtual-scroll and drag-and-drop packages and the editor, which load when a view or an edit needs them. |
|
|
12
|
+
| `@aiquants/markdown-explorer/server` | The Node entry: `createMarkdownExplorer` (the core on Node's runtime, with its sanitizer's worker threads), `createFileSystemSource`, `anonymousAccess`, the ports and the rules a host's adapters share with the explorer. | React or the browser half; of `@aiquants/markdown`, only its React-free entries. |
|
|
13
|
+
| `@aiquants/markdown-explorer/server/core` | The core every runtime completes: `createExplorerServer(config, platform)`, `createInProcessDataFetch`, the ports and the types they show, `ExplorerError`, `ASSET_CONTENT_SECURITY_POLICIES` and the shared rules (the deny rules, the document path rule, the source id rule, the rule of a document's language (`isExplorerDocumentLang`), `EXPLORER_MAX_HEADINGS` and the rule by which a file's bytes read as text). | A Node built-in, `@aiquants/markdown/server`, `undici`, `jsdom`, React or the client's components. |
|
|
14
|
+
| `@aiquants/markdown-explorer/server/browser` | The browser runtime: `createBrowserExplorerPlatform`. | The same as `./server/core`. It starts the nesting-guard worker from a URL and does not import it. |
|
|
15
|
+
| `@aiquants/markdown-explorer/server/browser/nesting-guard-worker` | The nesting guard's module Web Worker, one self-contained ES module. | Anything but the guard and `parse5`: no DOM and no sanitize policy. |
|
|
16
|
+
| `@aiquants/markdown-explorer/storage` | `clearExplorerStorage`. | Any package: no React and no `@aiquants/*`, so a layout that runs on every page can import it. |
|
|
17
|
+
| `@aiquants/markdown-explorer/testing` | `denyVectors()`: the answers the deny rules owe (one segment pattern, a path and whether the rules made of that pattern alone deny the path), for a host's tests and for another implementation of the rules. | Anything else. No other entry carries the table. |
|
|
18
|
+
| `@aiquants/markdown-explorer/styles/markdown-explorer.css` | The stylesheet ([Load the styles](../../README.md#5-load-the-styles)). | — |
|
|
19
|
+
|
|
20
|
+
## Running the server half in the page
|
|
21
|
+
|
|
22
|
+
1. **The core's configuration.** `createExplorerServer(config, platform)` takes the configuration of `createMarkdownExplorer` without its `scopeSecret` (a runtime that keeps a secret holds it itself), and two settings the Node entry fixes:
|
|
23
|
+
- `readSettings(request)` reads the display settings a request carries, as the serialized value (`undefined` when it carries none), for every page request; a malformed value reads as no settings, never as an error. `<MarkdownExplorer persistSettings>` stores the settings where it will find them. The Node entry reads and writes the configuration's `settingsCookie`.
|
|
24
|
+
- `assetMaxRangeBytes` is the most bytes one ranged answer of the `asset` operation carries (a positive safe integer): a satisfiable single range longer than that is shortened from its start and answered 206 with its own `Content-Range`, while a request without `Range`, or whose `If-Range` does not match, is answered whole. `null` answers every range as asked, as the Node entry does.
|
|
25
|
+
- Its `sanitizer` takes the limits every runtime takes; the browser runtime's are [below](#the-browser-runtimes-sanitizer).
|
|
26
|
+
2. **The browser runtime.** `createBrowserExplorerPlatform({ principalKey, scope, window, nestingGuardWorkerUrl, pageFetch })` checks its options when it is created (a `TypeError` names the first one that is wrong):
|
|
27
|
+
- `principalKey` is the one principal key the page serves, a non-empty string. It must be the key the core's `principalKey` answers: a request that names another key is a `TypeError`. `anonymousAccess` is the Node entry's; a page writes its own `authenticate`.
|
|
28
|
+
- `scope` is that principal's scope, 22 base64url characters (for example 16 random bytes your page keeps), which every data response carries and the browser's stores compare to tell readers apart.
|
|
29
|
+
- `window` is the window whose DOM sanitizes; it must be a secure context, since the runtime measures the HTML with its `crypto.subtle`.
|
|
30
|
+
- `nestingGuardWorkerUrl` is the URL of `@aiquants/markdown-explorer/server/browser/nesting-guard-worker` as your bundler emits it; with Vite, its `?url` import resolved against the page (`new URL(url, window.location.href)`).
|
|
31
|
+
- `pageFetch` is the link cards' network port (`PageFetchPort` of `@aiquants/markdown/link-cards`, `{ open, classify }`), or `null` with link cards off; a configuration with link cards on over a runtime without the port throws when the core asks for the card handler.
|
|
32
|
+
3. **The page's fetch.** `createInProcessDataFetch(server, { dataPath, pageAddress })`, given the configuration's `dataPath` and the page's own URL (`window.location.href`), answers a request to `<dataPath>/<operation>` with no network, through the core's `dataLoader` (GET and HEAD) or `dataAction` (any other method), and refuses any other URL with a `TypeError`.
|
|
33
|
+
A HEAD answer keeps its status and headers but not its body, and an aborted request rejects with its reason at once, as `fetch` does. It compares a request's scheme and host with the page's rather than origins, so it also answers on a scheme whose origin is `"null"` (such as `wails://`).
|
|
34
|
+
Pass it as `<MarkdownExplorer fetch>`. The page's router has no `basename`: the data URLs are the configuration's own.
|
|
35
|
+
4. **The route.** The page route has no server loader and no data route. Its `clientLoader` returns the core's `loader`, also during hydration, with a `HydrateFallback` meanwhile, and `shouldRevalidateExplorer` decides when it runs again:
|
|
36
|
+
|
|
37
|
+
```ts
|
|
38
|
+
// explorer-host.client.ts: a module only the browser loads
|
|
39
|
+
import { createBrowserExplorerPlatform } from "@aiquants/markdown-explorer/server/browser"
|
|
40
|
+
import nestingGuardWorkerUrl from "@aiquants/markdown-explorer/server/browser/nesting-guard-worker?url"
|
|
41
|
+
import { createExplorerServer, createInProcessDataFetch } from "@aiquants/markdown-explorer/server/core"
|
|
42
|
+
import { explorerConfig } from "./explorer.config"
|
|
43
|
+
import { assetOf, documentOf, sources } from "./explorer.sources"
|
|
44
|
+
import { keptScope, keptSettings, READER, READER_KEY } from "./explorer.reader"
|
|
45
|
+
|
|
46
|
+
export const explorer = createExplorerServer(
|
|
47
|
+
{
|
|
48
|
+
config: explorerConfig,
|
|
49
|
+
authenticate: async () => ({ status: "signed-in", principal: READER }),
|
|
50
|
+
principalKey: () => READER_KEY,
|
|
51
|
+
sources,
|
|
52
|
+
document: documentOf,
|
|
53
|
+
asset: assetOf,
|
|
54
|
+
signedOutPage: (_request, headers) => new Response(null, { status: 401, headers }),
|
|
55
|
+
readSettings: keptSettings,
|
|
56
|
+
assetMaxRangeBytes: null,
|
|
57
|
+
},
|
|
58
|
+
createBrowserExplorerPlatform({
|
|
59
|
+
principalKey: READER_KEY,
|
|
60
|
+
scope: keptScope(),
|
|
61
|
+
window,
|
|
62
|
+
nestingGuardWorkerUrl: new URL(nestingGuardWorkerUrl, window.location.href),
|
|
63
|
+
pageFetch: null,
|
|
64
|
+
}),
|
|
65
|
+
)
|
|
66
|
+
|
|
67
|
+
export const explorerFetch = createInProcessDataFetch(explorer, { dataPath: explorerConfig.dataPath, pageAddress: window.location.href })
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
```tsx
|
|
71
|
+
// routes/docs.tsx: registered at basePath and basePath/*, like the page route of the quick start
|
|
72
|
+
import { MarkdownExplorer, shouldRevalidateExplorer } from "@aiquants/markdown-explorer"
|
|
73
|
+
import type { ExplorerPageLoaderResult } from "@aiquants/markdown-explorer/server/core"
|
|
74
|
+
import { useLoaderData } from "react-router"
|
|
75
|
+
import { explorer, explorerFetch } from "../explorer-host.client"
|
|
76
|
+
import { explorerConfig } from "../explorer.config"
|
|
77
|
+
import { persistSettings } from "../explorer.reader"
|
|
78
|
+
import type { Route } from "./+types/docs"
|
|
79
|
+
|
|
80
|
+
export const clientLoader = (args: Route.ClientLoaderArgs): Promise<ExplorerPageLoaderResult> => explorer.loader(args)
|
|
81
|
+
clientLoader.hydrate = true as const
|
|
82
|
+
export const shouldRevalidate = shouldRevalidateExplorer
|
|
83
|
+
export const HydrateFallback = () => <p role="status">Loading…</p>
|
|
84
|
+
|
|
85
|
+
export default function Docs() {
|
|
86
|
+
const data = useLoaderData<typeof clientLoader>()
|
|
87
|
+
return <MarkdownExplorer data={data} config={explorerConfig} storageNamespace="docs" fetch={explorerFetch} persistSettings={persistSettings} />
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### What a page host must know
|
|
92
|
+
|
|
93
|
+
- **Images and media load from their URLs.** The browser reads a document's images and media from their asset URLs (`{dataPath}/asset?path=…`, or `mediaDataPath` for videos, audio and PDF documents), never through the explorer's `fetch`, so the in-process fetch never sees those requests. Serve that path over the page's own scheme (a desktop shell's scheme handler, for example, [streaming the files itself](#streaming-files-yourself)), or give the page content without images and media.
|
|
94
|
+
- **Keep your storage keys outside the explorer's namespace.** The explorer keeps its keys under `<storageNamespace>:` (the reader's scope at `<storageNamespace>:scope`) and erases every key of its namespace when the page names another reader, so a key of yours inside it would collide or be erased.
|
|
95
|
+
- **One principal per page.** The core's `principalKey` and the runtime's `principalKey` name the same reader, and the runtime's `scope` stays the same for that reader across page loads; a new scope makes the explorer erase what it kept for the previous reader.
|
|
96
|
+
- **The tree opens the open document's folders only through `ancestors`.** Under the reader's "Reveal the open document" setting (off by default, [Revealing the open document](../../README.md#revealing-the-open-document)), the tree opens the folders down to the open document only when its source answers `ancestors` (the folders from the source's top down to the document's parent, `[]` at the top level, `null` for a path it does not hold); without it, the setting opens no folder.
|
|
97
|
+
- **The browser runtime follows the server's rules.** Every rule of [Security](security.md) holds in the page too: the document admission, the deny rules, the sanitizer's allow-list and limits, the failures a host's adapters throw.
|
|
98
|
+
|
|
99
|
+
## The browser runtime's sanitizer
|
|
100
|
+
|
|
101
|
+
The browser runtime sanitizes with the same rules and limits as the Node entry, over the page's window ([Security](security.md#html) gives the details):
|
|
102
|
+
|
|
103
|
+
- the nesting guard (the same parser and the same depth, node, comment and attribute budgets) runs in the module Web Worker started from `nestingGuardWorkerUrl`, so its cost never blocks the page, and HTML it stops never reaches the DOM; DOMPurify then sanitizes on the page's main thread, one document at a time, after yielding the main thread once;
|
|
104
|
+
- `sanitizer.workers` and `sanitizer.workerHeapMb` are Node's and refused (a `TypeError` when the explorer is created);
|
|
105
|
+
- the node budget is the one of Node's default worker heap (81,920 nodes with the default 4 MiB of HTML), so `sanitizer.maxHtmlBytes` may be at most 14,155,776, the most that leaves the budget 4,096 nodes (a `RangeError` above it);
|
|
106
|
+
- the admission defaults are those of one worker: `jobsPerScope` defaults to `multiView.maxPanels` + 4 (16 with the default 12 panels) and `maxQueuedJobs` to four times `jobsPerScope`, and neither may be set below `multiView.maxPanels`;
|
|
107
|
+
- the per-document deadline spans the guard and DOMPurify: a document that misses it is `too-large`.
|
|
108
|
+
|
|
109
|
+
## The app's own URLs: `appOrigins` and `mediaDataPath`
|
|
110
|
+
|
|
111
|
+
Two options of the shared configuration (`defineExplorerConfig`) tell the sanitizer which absolute URLs are the app's own, which then stay only under the paths their use allows ([Security](security.md#html)):
|
|
112
|
+
|
|
113
|
+
- `appOrigins` lists the origins the app's own pages are served from, written as the browser writes them (`scheme://host[:port]`, without a default port, a path, a query or a fragment), such as `http://wails.localhost` or `wails://localhost`. A document's absolute URL of one of them is treated like a path-absolute one. None by default, so only relative and path-absolute URLs are the app's.
|
|
114
|
+
- `mediaDataPath` is an absolute `http:` or `https:` URL, of an origin and a mount path, on which the asset URLs of videos, audio and PDF documents are built instead of the data route, such as a separate media server's data route (`http://127.0.0.1:<port>/m/<secret>/_data`); a document's `video`, `audio` and `source` may then use it too. None by default: every asset is on the data route.
|
|
115
|
+
|
|
116
|
+
## Streaming files yourself
|
|
117
|
+
|
|
118
|
+
A host that delivers a file's bytes itself — a desktop shell's scheme handler, for example — instead of through the `asset` port's `open` gives each file a `bridge` and asks the core for a plan of each data request:
|
|
119
|
+
|
|
120
|
+
- `ExplorerAssetFile.bridge` is `{ uri, storageVersion, readFailure }`: the storage URI, the storage's own version a read must still find (`null` when the storage keeps none, such as a Google-native Drive file, which is then read without a precondition and without a declared length), and the host's classification of a failed read (the mapping `open` applies, so a failure answers the status a failed `open` would). A host that serves through `open` alone gives none; any other value, `null` included, is a malformed answer. It never reaches the browser.
|
|
121
|
+
- `planData(args)` (of the core and of `createMarkdownExplorer` alike, with the data route's loader arguments) answers a GET of the `asset` operation that the explorer answers with bytes (200 or 206) as a `file` the host streams.
|
|
122
|
+
The plan holds its `status`, every response header (type, length, range, validators, delivery, cache, authentication), the `bridge` (`uri` and `storageVersion`), the `range` to read (`null` for the whole file), the `length` to send (`null` when unknown, then without `Content-Length`), and `fail(error)`, the response to send instead when the bytes cannot be read before the first byte.
|
|
123
|
+
Every other request (HEAD, 304, 416, an empty file, a redirect, a failure, any other operation) is a `response`, exactly as `dataLoader` answers it. A file without a `bridge` cannot be planned and is answered `failed`, and a table preview's workbook (`as=workbook`) is refused as `invalid`.
|
package/docs/behavior/layout.md
CHANGED
|
@@ -7,7 +7,8 @@ This page is part of the host-facing contract of `@aiquants/markdown-explorer`;
|
|
|
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
|
|
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.
|
|
11
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.
|
|
12
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.
|
|
13
14
|
|
|
@@ -357,7 +358,7 @@ A held key repeats its keydown, and the browser turns every repeated Enter into
|
|
|
357
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;
|
|
358
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 —
|
|
359
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;
|
|
360
|
-
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).
|
|
361
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.
|
|
362
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.
|
|
363
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.
|
|
@@ -373,7 +374,7 @@ Space needs no such rule on buttons, which act when the key is released, and a t
|
|
|
373
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`).
|
|
374
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.
|
|
375
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.
|
|
376
|
-
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.
|
|
377
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.
|
|
378
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.
|
|
379
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.
|
|
@@ -403,6 +404,7 @@ The root declares the scheme as its `color-scheme` (`light` or `dark`), so what
|
|
|
403
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`.
|
|
404
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.
|
|
405
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.
|
|
406
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.
|
|
407
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.
|
|
408
410
|
|
|
@@ -7,26 +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
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),
|
|
15
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`)
|
|
16
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).
|
|
17
|
-
|
|
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.
|
|
18
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`).
|
|
19
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.
|
|
20
|
-
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 `拡大縮小+移動 (左ドラッグ)`).
|
|
21
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`.
|
|
22
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`),
|
|
23
28
|
the move announcements (`panelMoved`, `panelMoveUnavailable`), a touch or pen drag's lift and cancel announcements (`panelDragStarted`, `panelDragCancelled`), the bar of hidden panels (`hiddenPanelsTitle`)
|
|
24
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`).
|
|
25
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.
|
|
26
34
|
- `treeRegion` names the tree itself, apart from `explorerRegion`, which names the explorer's landmark (and the sheet on narrow frames).
|
|
27
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.
|
|
28
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)
|
|
29
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)`.
|
|
30
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.
|
|
31
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.
|
|
32
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.
|
|
@@ -37,6 +47,9 @@ This page is part of the host-facing contract of `@aiquants/markdown-explorer`;
|
|
|
37
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);
|
|
38
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).
|
|
39
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.
|
|
40
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.
|
|
41
54
|
|
|
42
55
|
## Overrides
|
|
@@ -57,11 +70,14 @@ const HANDBOOK_LABELS = {
|
|
|
57
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`;
|
|
58
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:
|
|
59
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),
|
|
60
|
-
`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)
|
|
61
|
-
|
|
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.
|
|
62
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).
|
|
63
|
-
`MARKDOWN_EXPLORER_LABEL_TEMPLATES` lists each template's placeholders,
|
|
64
|
-
- `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.
|
|
65
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.
|
|
66
82
|
|
|
67
83
|
## Formatting
|
|
@@ -70,6 +86,7 @@ Counts and percentages are formatted by the label functions themselves, so a hos
|
|
|
70
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.
|
|
71
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`).
|
|
72
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 を表示」).
|
|
73
90
|
|
|
74
91
|
## Strings outside the catalog
|
|
75
92
|
|