sendproof-core 0.1.0.alpha.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/LICENSE +21 -0
- data/README.md +55 -0
- data/lib/sendproof/assets.rb +70 -0
- data/lib/sendproof/attribution.rb +98 -0
- data/lib/sendproof/capture.rb +66 -0
- data/lib/sendproof/clock.rb +54 -0
- data/lib/sendproof/configuration.rb +241 -0
- data/lib/sendproof/data_store.rb +34 -0
- data/lib/sendproof/dynamodb/store.rb +183 -0
- data/lib/sendproof/dynamodb.rb +17 -0
- data/lib/sendproof/elasticsearch/store.rb +24 -0
- data/lib/sendproof/elasticsearch.rb +17 -0
- data/lib/sendproof/firestore/interceptor.rb +38 -0
- data/lib/sendproof/firestore/store.rb +150 -0
- data/lib/sendproof/firestore.rb +99 -0
- data/lib/sendproof/handler.rb +23 -0
- data/lib/sendproof/identity.rb +37 -0
- data/lib/sendproof/limits.rb +113 -0
- data/lib/sendproof/middleware.rb +68 -0
- data/lib/sendproof/mongo/engine.rb +692 -0
- data/lib/sendproof/mongo/guarded.rb +100 -0
- data/lib/sendproof/mongo/plain.rb +45 -0
- data/lib/sendproof/mongo/store.rb +54 -0
- data/lib/sendproof/mongo/subscriber.rb +21 -0
- data/lib/sendproof/mongo.rb +41 -0
- data/lib/sendproof/mongoid/store.rb +58 -0
- data/lib/sendproof/mongoid.rb +65 -0
- data/lib/sendproof/observed_request.rb +108 -0
- data/lib/sendproof/opensearch/store.rb +21 -0
- data/lib/sendproof/opensearch.rb +17 -0
- data/lib/sendproof/operation_matcher.rb +28 -0
- data/lib/sendproof/pool_hooks.rb +80 -0
- data/lib/sendproof/preview_request.rb +44 -0
- data/lib/sendproof/preview_transport.rb +331 -0
- data/lib/sendproof/protocol.rb +81 -0
- data/lib/sendproof/provider.rb +83 -0
- data/lib/sendproof/recorder.rb +298 -0
- data/lib/sendproof/redaction.rb +98 -0
- data/lib/sendproof/redis/commands.rb +76 -0
- data/lib/sendproof/redis/store.rb +205 -0
- data/lib/sendproof/redis.rb +18 -0
- data/lib/sendproof/search/middleware.rb +39 -0
- data/lib/sendproof/search/store.rb +213 -0
- data/lib/sendproof/search.rb +82 -0
- data/lib/sendproof/stores/classify.rb +346 -0
- data/lib/sendproof/stores/guard.rb +127 -0
- data/lib/sendproof/stores/tables.rb +1328 -0
- data/lib/sendproof/stores.rb +12 -0
- data/lib/sendproof/trace_store.rb +110 -0
- data/lib/sendproof/transaction_control.rb +187 -0
- data/lib/sendproof/ui/action-bar.js +91 -0
- data/lib/sendproof/ui/api.js +239 -0
- data/lib/sendproof/ui/app.css +848 -0
- data/lib/sendproof/ui/app.js +742 -0
- data/lib/sendproof/ui/autofill.js +137 -0
- data/lib/sendproof/ui/code-copy.js +71 -0
- data/lib/sendproof/ui/code-picker.js +149 -0
- data/lib/sendproof/ui/commands.js +197 -0
- data/lib/sendproof/ui/components.js +77 -0
- data/lib/sendproof/ui/context-bar.js +82 -0
- data/lib/sendproof/ui/copy.js +92 -0
- data/lib/sendproof/ui/coverage-popover.js +35 -0
- data/lib/sendproof/ui/crumb-fit.js +80 -0
- data/lib/sendproof/ui/deprecation.js +164 -0
- data/lib/sendproof/ui/display-settings.js +175 -0
- data/lib/sendproof/ui/doc-diff.js +209 -0
- data/lib/sendproof/ui/docs-view.js +347 -0
- data/lib/sendproof/ui/favicon.png +0 -0
- data/lib/sendproof/ui/favicon.svg +1 -0
- data/lib/sendproof/ui/field-help.js +52 -0
- data/lib/sendproof/ui/field-modules.js +23 -0
- data/lib/sendproof/ui/fields/controls.js +179 -0
- data/lib/sendproof/ui/fields/dom.js +36 -0
- data/lib/sendproof/ui/fields/infer.js +71 -0
- data/lib/sendproof/ui/fields/lookup-source.js +63 -0
- data/lib/sendproof/ui/fields/lookup.js +285 -0
- data/lib/sendproof/ui/fields/render.js +496 -0
- data/lib/sendproof/ui/fields/select.js +175 -0
- data/lib/sendproof/ui/fields/validate.js +363 -0
- data/lib/sendproof/ui/fields/validation-formats.js +164 -0
- data/lib/sendproof/ui/fields/validation-references.js +68 -0
- data/lib/sendproof/ui/fields/validation-values.js +137 -0
- data/lib/sendproof/ui/generate-menu.js +44 -0
- data/lib/sendproof/ui/generate.js +184 -0
- data/lib/sendproof/ui/header-editor.js +777 -0
- data/lib/sendproof/ui/headers.js +188 -0
- data/lib/sendproof/ui/highlight.js +257 -0
- data/lib/sendproof/ui/history-popover.js +24 -0
- data/lib/sendproof/ui/i18n.js +253 -0
- data/lib/sendproof/ui/icons.js +87 -0
- data/lib/sendproof/ui/index.html +70 -0
- data/lib/sendproof/ui/issues.js +187 -0
- data/lib/sendproof/ui/json-view.js +166 -0
- data/lib/sendproof/ui/lang-icons.js +62 -0
- data/lib/sendproof/ui/layout.js +262 -0
- data/lib/sendproof/ui/listbox.js +334 -0
- data/lib/sendproof/ui/locales/ar-capture.js +366 -0
- data/lib/sendproof/ui/locales/ar-stores.js +116 -0
- data/lib/sendproof/ui/locales/ar.js +561 -0
- data/lib/sendproof/ui/locales/cs-capture.js +442 -0
- data/lib/sendproof/ui/locales/cs-stores.js +116 -0
- data/lib/sendproof/ui/locales/cs.js +689 -0
- data/lib/sendproof/ui/locales/da-capture.js +347 -0
- data/lib/sendproof/ui/locales/da-stores.js +116 -0
- data/lib/sendproof/ui/locales/da.js +522 -0
- data/lib/sendproof/ui/locales/de-capture.js +347 -0
- data/lib/sendproof/ui/locales/de-stores.js +116 -0
- data/lib/sendproof/ui/locales/de.js +519 -0
- data/lib/sendproof/ui/locales/el-capture.js +347 -0
- data/lib/sendproof/ui/locales/el-stores.js +116 -0
- data/lib/sendproof/ui/locales/el.js +520 -0
- data/lib/sendproof/ui/locales/en-capture.js +349 -0
- data/lib/sendproof/ui/locales/en-stores.js +95 -0
- data/lib/sendproof/ui/locales/en.js +522 -0
- data/lib/sendproof/ui/locales/es-capture.js +353 -0
- data/lib/sendproof/ui/locales/es-stores.js +116 -0
- data/lib/sendproof/ui/locales/es.js +525 -0
- data/lib/sendproof/ui/locales/fa-capture.js +348 -0
- data/lib/sendproof/ui/locales/fa-stores.js +116 -0
- data/lib/sendproof/ui/locales/fa.js +521 -0
- data/lib/sendproof/ui/locales/fi-capture.js +347 -0
- data/lib/sendproof/ui/locales/fi-stores.js +116 -0
- data/lib/sendproof/ui/locales/fi.js +523 -0
- data/lib/sendproof/ui/locales/fr-capture.js +353 -0
- data/lib/sendproof/ui/locales/fr-stores.js +116 -0
- data/lib/sendproof/ui/locales/fr.js +525 -0
- data/lib/sendproof/ui/locales/he-capture.js +358 -0
- data/lib/sendproof/ui/locales/he-stores.js +116 -0
- data/lib/sendproof/ui/locales/he.js +529 -0
- data/lib/sendproof/ui/locales/hi-capture.js +348 -0
- data/lib/sendproof/ui/locales/hi-stores.js +116 -0
- data/lib/sendproof/ui/locales/hi.js +523 -0
- data/lib/sendproof/ui/locales/id-capture.js +347 -0
- data/lib/sendproof/ui/locales/id-stores.js +116 -0
- data/lib/sendproof/ui/locales/id.js +521 -0
- data/lib/sendproof/ui/locales/it-capture.js +361 -0
- data/lib/sendproof/ui/locales/it-stores.js +116 -0
- data/lib/sendproof/ui/locales/it.js +523 -0
- data/lib/sendproof/ui/locales/ja-capture.js +346 -0
- data/lib/sendproof/ui/locales/ja-stores.js +116 -0
- data/lib/sendproof/ui/locales/ja.js +521 -0
- data/lib/sendproof/ui/locales/ko-capture.js +346 -0
- data/lib/sendproof/ui/locales/ko-stores.js +116 -0
- data/lib/sendproof/ui/locales/ko.js +522 -0
- data/lib/sendproof/ui/locales/nb-capture.js +349 -0
- data/lib/sendproof/ui/locales/nb-stores.js +116 -0
- data/lib/sendproof/ui/locales/nb.js +521 -0
- data/lib/sendproof/ui/locales/nl-capture.js +355 -0
- data/lib/sendproof/ui/locales/nl-stores.js +116 -0
- data/lib/sendproof/ui/locales/nl.js +520 -0
- data/lib/sendproof/ui/locales/pl-capture.js +432 -0
- data/lib/sendproof/ui/locales/pl-stores.js +116 -0
- data/lib/sendproof/ui/locales/pl.js +528 -0
- data/lib/sendproof/ui/locales/pt-BR-capture.js +350 -0
- data/lib/sendproof/ui/locales/pt-BR-stores.js +116 -0
- data/lib/sendproof/ui/locales/pt-BR.js +523 -0
- data/lib/sendproof/ui/locales/pt-PT-capture.js +350 -0
- data/lib/sendproof/ui/locales/pt-PT-stores.js +116 -0
- data/lib/sendproof/ui/locales/pt-PT.js +523 -0
- data/lib/sendproof/ui/locales/ru-capture.js +437 -0
- data/lib/sendproof/ui/locales/ru-stores.js +116 -0
- data/lib/sendproof/ui/locales/ru.js +624 -0
- data/lib/sendproof/ui/locales/sv-capture.js +349 -0
- data/lib/sendproof/ui/locales/sv-stores.js +116 -0
- data/lib/sendproof/ui/locales/sv.js +518 -0
- data/lib/sendproof/ui/locales/th-capture.js +347 -0
- data/lib/sendproof/ui/locales/th-stores.js +116 -0
- data/lib/sendproof/ui/locales/th.js +521 -0
- data/lib/sendproof/ui/locales/tr-capture.js +348 -0
- data/lib/sendproof/ui/locales/tr-stores.js +116 -0
- data/lib/sendproof/ui/locales/tr.js +521 -0
- data/lib/sendproof/ui/locales/uk-capture.js +442 -0
- data/lib/sendproof/ui/locales/uk-stores.js +116 -0
- data/lib/sendproof/ui/locales/uk.js +630 -0
- data/lib/sendproof/ui/locales/vi-capture.js +346 -0
- data/lib/sendproof/ui/locales/vi-stores.js +116 -0
- data/lib/sendproof/ui/locales/vi.js +523 -0
- data/lib/sendproof/ui/locales/zh-Hans-capture.js +347 -0
- data/lib/sendproof/ui/locales/zh-Hans-stores.js +116 -0
- data/lib/sendproof/ui/locales/zh-Hans.js +523 -0
- data/lib/sendproof/ui/locales/zh-Hant-capture.js +346 -0
- data/lib/sendproof/ui/locales/zh-Hant-stores.js +116 -0
- data/lib/sendproof/ui/locales/zh-Hant.js +522 -0
- data/lib/sendproof/ui/manifest.json +866 -0
- data/lib/sendproof/ui/markdown.js +39 -0
- data/lib/sendproof/ui/model-view.js +182 -0
- data/lib/sendproof/ui/navigation.js +233 -0
- data/lib/sendproof/ui/operation-header.js +76 -0
- data/lib/sendproof/ui/operations.js +7 -0
- data/lib/sendproof/ui/overview-view.js +63 -0
- data/lib/sendproof/ui/personas.js +59 -0
- data/lib/sendproof/ui/popover.js +71 -0
- data/lib/sendproof/ui/preview-false.js +108 -0
- data/lib/sendproof/ui/request-editor.js +496 -0
- data/lib/sendproof/ui/response-metadata.js +354 -0
- data/lib/sendproof/ui/response-viewer.js +618 -0
- data/lib/sendproof/ui/result-blocked.js +155 -0
- data/lib/sendproof/ui/result-capture.js +25 -0
- data/lib/sendproof/ui/result-database.js +185 -0
- data/lib/sendproof/ui/result-effects.js +176 -0
- data/lib/sendproof/ui/result-headers.js +106 -0
- data/lib/sendproof/ui/result-logs.js +408 -0
- data/lib/sendproof/ui/result-states.js +213 -0
- data/lib/sendproof/ui/results.js +371 -0
- data/lib/sendproof/ui/router.js +118 -0
- data/lib/sendproof/ui/schema-model.js +336 -0
- data/lib/sendproof/ui/schema-tree.js +344 -0
- data/lib/sendproof/ui/schema.js +397 -0
- data/lib/sendproof/ui/security.js +31 -0
- data/lib/sendproof/ui/seeded-menu.js +69 -0
- data/lib/sendproof/ui/settings.js +93 -0
- data/lib/sendproof/ui/shortcuts-sheet.js +73 -0
- data/lib/sendproof/ui/shortcuts.js +190 -0
- data/lib/sendproof/ui/sidebar.js +289 -0
- data/lib/sendproof/ui/signin.js +259 -0
- data/lib/sendproof/ui/snippets.js +530 -0
- data/lib/sendproof/ui/store-marks.js +47 -0
- data/lib/sendproof/ui/stores.js +131 -0
- data/lib/sendproof/ui/styles.css +971 -0
- data/lib/sendproof/ui/toggletip.js +53 -0
- data/lib/sendproof/ui/uuid.js +10 -0
- data/lib/sendproof/ui/view.js +122 -0
- data/lib/sendproof/ui/views.css +653 -0
- data/lib/sendproof/version.rb +9 -0
- data/lib/sendproof/workbench.rb +102 -0
- data/lib/sendproof-core.rb +3 -0
- data/lib/sendproof.rb +121 -0
- metadata +292 -0
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
// Nested document diffs for store changes (mock v6-stores.js docCard, screens 113–116 and m26):
|
|
2
|
+
// a MongoDB document, a DynamoDB item or a Redis value as a tree with every object open. Changed
|
|
3
|
+
// leaves are tinted with old → new, added and removed paths are marked, every branch that holds
|
|
4
|
+
// changes says how many, arrays compare by index, Extended JSON reads as typed badges and secret
|
|
5
|
+
// fields as a muted "redacted" pill at any depth. Updates open on Diff with Changes only off; the
|
|
6
|
+
// switch shows Before or After, and each branch folds.
|
|
7
|
+
import { esc, icon } from './components.js';
|
|
8
|
+
import { t } from './i18n.js';
|
|
9
|
+
import { storeKind } from './stores.js';
|
|
10
|
+
|
|
11
|
+
// MongoDB Extended JSON v2 (relaxed and canonical) wrappers shown as a type badge, by key.
|
|
12
|
+
const EXTENDED = {
|
|
13
|
+
$oid: 'ObjectId', $date: 'Date', $numberDecimal: 'Decimal128', $numberLong: 'Int64', $numberInt: 'Int32',
|
|
14
|
+
$numberDouble: 'Double', $binary: 'Binary', $uuid: 'UUID', $timestamp: 'Timestamp', $regularExpression: 'Regex',
|
|
15
|
+
$symbol: 'Symbol', $code: 'Code', $minKey: 'MinKey', $maxKey: 'MaxKey',
|
|
16
|
+
};
|
|
17
|
+
const REDACTED = '[REDACTED]';
|
|
18
|
+
|
|
19
|
+
/** The Extended JSON key of a one-key wrapper such as { "$oid": "…" }, or undefined. */
|
|
20
|
+
export function extendedType(value) {
|
|
21
|
+
if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
|
|
22
|
+
const keys = Object.keys(value);
|
|
23
|
+
return keys.length === 1 && EXTENDED[keys[0]] ? keys[0] : undefined;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
const isBranch = value => !!value && typeof value === 'object' && !extendedType(value);
|
|
27
|
+
const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
|
|
28
|
+
const has = (container, key) => container != null && typeof container === 'object' &&
|
|
29
|
+
(Array.isArray(container) ? key < container.length : Object.hasOwn(container, key));
|
|
30
|
+
|
|
31
|
+
/** One value as it reads in the tree: typed badges, the redacted pill, then JSON literals. */
|
|
32
|
+
export function valueMarkup(value) {
|
|
33
|
+
const ext = extendedType(value);
|
|
34
|
+
if (ext) {
|
|
35
|
+
const inner = value[ext];
|
|
36
|
+
const text = inner && typeof inner === 'object' ? (extendedType(inner) ? inner[extendedType(inner)] : JSON.stringify(inner)) : inner;
|
|
37
|
+
return `<span class="xt"><span class="xt-t">${EXTENDED[ext]}</span><span class="xt-v ltr">${esc(text)}</span></span>`;
|
|
38
|
+
}
|
|
39
|
+
if (value === REDACTED) return `<span class="redacted" title="${esc(t('diff.redactedTip'))}">${icon('lock', true)}${esc(t('diff.redacted'))}</span>`;
|
|
40
|
+
if (value === null) return '<span class="j-null ltr">null</span>';
|
|
41
|
+
if (typeof value === 'string') return `<span class="j-s ltr">"${esc(value)}"</span>`;
|
|
42
|
+
if (typeof value === 'number') return `<span class="j-n ltr">${esc(String(value))}</span>`;
|
|
43
|
+
if (typeof value === 'boolean') return `<span class="j-b ltr">${value}</span>`;
|
|
44
|
+
return `<span class="j-o ltr">${esc(JSON.stringify(value))}</span>`;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Flattens `before` and `after` into tree rows in document order: after's key order, with removed
|
|
49
|
+
* keys where they stood; arrays by index. Each row: { depth, key, index, kind: same|chg|add|del,
|
|
50
|
+
* branch: object|array (branches only), size, inner (changes below a branch), inherit (inside an
|
|
51
|
+
* added or removed branch), before, after, path }.
|
|
52
|
+
*/
|
|
53
|
+
export function diffRows(before, after, depth = 0, out = [], path = '') {
|
|
54
|
+
const keys = [];
|
|
55
|
+
if (Array.isArray(before) || Array.isArray(after)) {
|
|
56
|
+
const length = Math.max(Array.isArray(before) ? before.length : 0, Array.isArray(after) ? after.length : 0);
|
|
57
|
+
for (let index = 0; index < length; index++) keys.push(index);
|
|
58
|
+
} else {
|
|
59
|
+
const kept = Object.keys(after || {});
|
|
60
|
+
keys.push(...kept);
|
|
61
|
+
Object.keys(before || {}).forEach((key, index) => { if (!kept.includes(key)) keys.splice(Math.min(keys.length, index), 0, key); });
|
|
62
|
+
}
|
|
63
|
+
for (const key of keys) {
|
|
64
|
+
const inBefore = has(before, key);
|
|
65
|
+
const inAfter = has(after, key);
|
|
66
|
+
const old = inBefore ? before[key] : undefined;
|
|
67
|
+
const now = inAfter ? after[key] : undefined;
|
|
68
|
+
const kind = !inBefore ? 'add' : !inAfter ? 'del' : same(old, now) ? 'same' : 'chg';
|
|
69
|
+
const rowPath = typeof key === 'number' ? `${path}[${key}]` : path ? `${path}.${key}` : key;
|
|
70
|
+
const shape = kind === 'del' ? old : now;
|
|
71
|
+
const index = typeof key === 'number';
|
|
72
|
+
if (isBranch(shape) && (kind !== 'chg' || isBranch(old))) {
|
|
73
|
+
const row = { depth, key, index, kind: kind === 'chg' ? 'same' : kind, branch: Array.isArray(shape) ? 'array' : 'object', size: Object.keys(shape).length, inner: 0, path: rowPath };
|
|
74
|
+
out.push(row);
|
|
75
|
+
const start = out.length;
|
|
76
|
+
diffRows(kind === 'add' ? undefined : old, kind === 'del' ? undefined : now, depth + 1, out, rowPath);
|
|
77
|
+
const below = out.slice(start);
|
|
78
|
+
if (kind === 'add' || kind === 'del') below.forEach(item => { item.kind = kind; item.inherit = true; });
|
|
79
|
+
row.inner = below.filter(item => !item.inherit && item.kind !== 'same').length;
|
|
80
|
+
} else out.push({ depth, key, index, kind, before: old, after: now, path: rowPath });
|
|
81
|
+
}
|
|
82
|
+
return out;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** Counts for the card: leaves changed, paths added and paths removed (not their contents). */
|
|
86
|
+
export function tally(rows) {
|
|
87
|
+
const top = rows.filter(row => !row.inherit);
|
|
88
|
+
return {
|
|
89
|
+
changed: top.filter(row => row.kind === 'chg').length,
|
|
90
|
+
added: top.filter(row => row.kind === 'add').length,
|
|
91
|
+
removed: top.filter(row => row.kind === 'del').length,
|
|
92
|
+
};
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
const MARKS = { chg: '~', add: '+', del: '−', same: '' };
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* One tree row. `mode` is update (tinted diff), insert or delete (every row marked, nothing
|
|
99
|
+
* tinted: the whole card is one operation) or plain (Before and After).
|
|
100
|
+
*/
|
|
101
|
+
function treeRow(row, mode) {
|
|
102
|
+
const kind = mode === 'insert' ? 'add' : mode === 'delete' ? 'del' : mode === 'plain' ? 'same' : row.kind;
|
|
103
|
+
const tint = mode === 'update' && kind !== 'same' ? ` is-${kind}${row.inherit ? ' is-inherit' : ''}` : kind !== 'same' ? ` is-plain-${kind}` : '';
|
|
104
|
+
const mark = mode === 'update' && row.inherit ? '' : MARKS[kind];
|
|
105
|
+
const key = `<span class="dt-k${row.index ? ' is-idx' : ''} ltr">${esc(row.key)}</span>`;
|
|
106
|
+
let value;
|
|
107
|
+
if (row.branch) {
|
|
108
|
+
const size = t(row.branch === 'array' ? 'diff.items' : 'diff.fields', { n: row.size });
|
|
109
|
+
const inner = mode === 'update' && row.kind === 'same' && row.inner ? `<span class="dt-inner">${esc(t('diff.changes', { n: row.inner }))}</span>` : '';
|
|
110
|
+
value = `<span class="dt-meta"><span class="br" aria-hidden="true">${row.branch === 'array' ? '[' : '{'}</span>${esc(size)}${inner}</span>`;
|
|
111
|
+
} else if (kind === 'chg') {
|
|
112
|
+
value = `<span class="dt-v is-pair"><span class="dt-old">${valueMarkup(row.before)}</span><span class="dt-arrow" aria-hidden="true">→</span><span class="sr-only">${esc(t('db.changedTo'))}</span><span class="dt-new">${valueMarkup(row.after)}</span></span>`;
|
|
113
|
+
} else value = `<span class="dt-v">${valueMarkup(kind === 'del' || (mode === 'plain' && row.after === undefined) ? row.before : row.after)}</span>`;
|
|
114
|
+
const twisty = row.branch
|
|
115
|
+
? `<button type="button" class="dt-tw" data-diff-fold aria-expanded="true" aria-label="${esc(t('diff.fold', { name: String(row.key) }))}">${icon('chevron-down', true)}</button>`
|
|
116
|
+
: '<span class="dt-tw" aria-hidden="true"></span>';
|
|
117
|
+
return `<div class="dt-row${tint}${row.branch ? ' is-branch' : ''}" data-depth="${row.depth}" data-kind="${kind}"${row.branch ? ` data-inner="${row.inner}"` : ''} style="--d:${row.depth}">
|
|
118
|
+
<span class="dt-mk" aria-hidden="true">${mark}</span><span class="dt-in">${twisty}${key}${value}</span></div>`;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/** The tree for one view of a change: diff (update), before or after, or the whole insert/delete. */
|
|
122
|
+
export function treeMarkup(change, view = 'diff') {
|
|
123
|
+
const operation = changeOperation(change);
|
|
124
|
+
if (operation === 'insert') return diffRows(undefined, change.after).map(row => treeRow(row, 'insert')).join('');
|
|
125
|
+
if (operation === 'delete') return diffRows(change.before, undefined).map(row => treeRow(row, 'delete')).join('');
|
|
126
|
+
if (view === 'before') return diffRows(change.before, change.before).map(row => treeRow(row, 'plain')).join('');
|
|
127
|
+
if (view === 'after') return diffRows(change.after, change.after).map(row => treeRow(row, 'plain')).join('');
|
|
128
|
+
return diffRows(change.before, change.after).map(row => treeRow(row, 'update')).join('');
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
const changeOperation = change => String(change.operation || '').toLowerCase();
|
|
132
|
+
|
|
133
|
+
/** The record's key: `_id` for MongoDB, the key attributes for DynamoDB, `key` for Redis. */
|
|
134
|
+
function keyMarkup(key) {
|
|
135
|
+
if (key == null) return '';
|
|
136
|
+
if (typeof key !== 'object' || Array.isArray(key) || extendedType(key)) return `<span class="doc-id">${valueMarkup(key)}</span>`;
|
|
137
|
+
return Object.entries(key).map(([name, value]) => `<span class="doc-id"><span class="k ltr">${esc(name)}</span>${valueMarkup(value)}</span>`).join('');
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
const BADGES = { insert: ['ins', '+ INSERT'], update: ['upd', '~ UPDATE'], delete: ['del', '− DELETE'] };
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* A store change as a card: operation, collection (or table, or key prefix), the "via upsert" or
|
|
144
|
+
* "whole document replaced" qualifier, then the key and the counts, then the tree. `index` ties
|
|
145
|
+
* the card to its change for bindDocDiffs.
|
|
146
|
+
*/
|
|
147
|
+
export function docCard(change, index = 0) {
|
|
148
|
+
const operation = changeOperation(change);
|
|
149
|
+
const [style, label] = BADGES[operation] || ['', operation.toUpperCase()];
|
|
150
|
+
const kind = storeKind(change.store);
|
|
151
|
+
const record = ['document', 'index'].includes(kind) ? 'document' : kind === 'key' ? 'key' : kind === 'sql' ? 'row' : 'item';
|
|
152
|
+
const via = change.via === 'upsert' ? t('diff.viaUpsert') : change.via === 'replace' ? t('diff.viaReplace') : '';
|
|
153
|
+
let summary;
|
|
154
|
+
if (operation === 'update') {
|
|
155
|
+
const counts = tally(diffRows(change.before, change.after));
|
|
156
|
+
summary = [
|
|
157
|
+
counts.changed && `<span class="dc c-upd">${esc(t('diff.changed', { n: counts.changed }))}</span>`,
|
|
158
|
+
counts.added && `<span class="dc c-ins">${esc(t('diff.added', { n: counts.added }))}</span>`,
|
|
159
|
+
counts.removed && `<span class="dc c-del">${esc(t('diff.removed', { n: counts.removed }))}</span>`,
|
|
160
|
+
].filter(Boolean).join('') || `<span class="dc c-same">${esc(t('diff.noChange'))}</span>`;
|
|
161
|
+
} else {
|
|
162
|
+
const fields = Object.keys((operation === 'delete' ? change.before : change.after) || {}).length;
|
|
163
|
+
summary = `<span class="dc c-${style}">${esc(t(`diff.${operation === 'delete' ? 'removedRecord' : 'newRecord'}.${record}`))} · ${esc(t('diff.fields', { n: fields }))}</span>`;
|
|
164
|
+
}
|
|
165
|
+
const views = operation === 'update' ? `<span class="spacer"></span>
|
|
166
|
+
<button type="button" class="btn btn-ghost btn-xs doc-only" data-diff-only aria-pressed="false" title="${esc(t('diff.changesOnly'))}">${icon('filter', true)}<span class="lbl">${esc(t('diff.changesOnly'))}</span></button>
|
|
167
|
+
<div class="segmented sm doc-views" role="group" aria-label="${esc(t('diff.show'))}">${['diff', 'before', 'after'].map(view =>
|
|
168
|
+
`<button type="button" data-diff-view="${view}" aria-pressed="${view === 'diff'}">${esc(t('diff.view.' + view))}</button>`).join('')}</div>` : '';
|
|
169
|
+
return `<article class="doc-card is-${esc(operation)}" data-doc-card="${index}" aria-label="${esc(t('db.cardLabel', { table: change.table, operation }))}">
|
|
170
|
+
<header class="doc-head">${label ? `<span class="op-badge op-${style}">${esc(label)}</span>` : ''}<span class="doc-coll ltr" title="${esc(change.table)}">${esc(change.table)}</span>${via ? `<span class="doc-via">${esc(via)}</span>` : ''}${views}</header>
|
|
171
|
+
<div class="doc-bar">${keyMarkup(change.key)}<span class="doc-sum">${summary}</span></div>
|
|
172
|
+
<div class="dt" data-diff-tree>${treeMarkup(change)}</div>
|
|
173
|
+
</article>`;
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
/** Shows or hides the rows a folded branch or Changes only hides; the two compose. */
|
|
177
|
+
function applyVisibility(card) {
|
|
178
|
+
const only = card.querySelector('[data-diff-only]')?.getAttribute('aria-pressed') === 'true';
|
|
179
|
+
const diff = (card.querySelector('[data-diff-view][aria-pressed="true"]')?.dataset.diffView ?? 'diff') === 'diff';
|
|
180
|
+
let foldedAt = Infinity;
|
|
181
|
+
for (const row of card.querySelectorAll('.dt-row')) {
|
|
182
|
+
const depth = Number(row.dataset.depth);
|
|
183
|
+
if (depth <= foldedAt) foldedAt = Infinity;
|
|
184
|
+
const unchanged = row.dataset.kind === 'same' && (!row.classList.contains('is-branch') || row.dataset.inner === '0');
|
|
185
|
+
row.hidden = depth > foldedAt || (only && diff && unchanged);
|
|
186
|
+
if (!row.hidden && row.querySelector('[data-diff-fold]')?.getAttribute('aria-expanded') === 'false') foldedAt = depth;
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/** Wires each card's view switch, Changes only and branch folding. `changes` are the change records. */
|
|
191
|
+
export function bindDocDiffs(container, changes) {
|
|
192
|
+
container.addEventListener('click', event => {
|
|
193
|
+
const card = event.target.closest('[data-doc-card]');
|
|
194
|
+
if (!card) return;
|
|
195
|
+
const change = changes[Number(card.dataset.docCard)];
|
|
196
|
+
const view = event.target.closest('[data-diff-view]');
|
|
197
|
+
const only = event.target.closest('[data-diff-only]');
|
|
198
|
+
const fold = event.target.closest('[data-diff-fold]');
|
|
199
|
+
if (view && change) {
|
|
200
|
+
card.querySelectorAll('[data-diff-view]').forEach(button => button.setAttribute('aria-pressed', String(button === view)));
|
|
201
|
+
card.querySelector('[data-diff-tree]').innerHTML = treeMarkup(change, view.dataset.diffView);
|
|
202
|
+
const onlyButton = card.querySelector('[data-diff-only]');
|
|
203
|
+
if (onlyButton) onlyButton.disabled = view.dataset.diffView !== 'diff';
|
|
204
|
+
} else if (only) only.setAttribute('aria-pressed', String(only.getAttribute('aria-pressed') !== 'true'));
|
|
205
|
+
else if (fold) fold.setAttribute('aria-expanded', String(fold.getAttribute('aria-expanded') !== 'true'));
|
|
206
|
+
else return;
|
|
207
|
+
applyVisibility(card);
|
|
208
|
+
});
|
|
209
|
+
}
|
|
@@ -0,0 +1,347 @@
|
|
|
1
|
+
// The Docs view of an operation (mocks/docs.js): summary, meta chips, deprecation, markdown
|
|
2
|
+
// description, every parameter, the request body, every documented response and the
|
|
3
|
+
// authentication requirement in the main column; the page outline and code samples in the right
|
|
4
|
+
// column. Try it and Docs fill the same three columns, so D swaps content, never layout.
|
|
5
|
+
import { dereference, encodeRequestBody } from './api.js';
|
|
6
|
+
import { copyButton, esc, icon, method, statusTone, tab } from './components.js';
|
|
7
|
+
import { copyText } from './copy.js';
|
|
8
|
+
import { t, th } from './i18n.js';
|
|
9
|
+
import { inline, linkOperationIds, markdown } from './markdown.js';
|
|
10
|
+
import { deprecationNotice } from './deprecation.js';
|
|
11
|
+
import { contextBar } from './context-bar.js';
|
|
12
|
+
import { bindJsonViews, jsonView } from './json-view.js';
|
|
13
|
+
import { exampleFor, modelExample, refName, resolve, rowSchema, schemaName, propertiesOf } from './schema-model.js';
|
|
14
|
+
import { bindTrees, hasNested, isAllOpen, newTreeState, parameterTree, propertyTree, setAllOpen } from './schema-tree.js';
|
|
15
|
+
import { isPublic, primarySchemes, requiredScopes, scopeText, securityRequirements } from './security.js';
|
|
16
|
+
import { formatRequest, snippetFormats } from './snippets.js';
|
|
17
|
+
import { shortcutAttrs, shortcutHint } from './shortcuts.js';
|
|
18
|
+
import { highlightSnippet } from './highlight.js';
|
|
19
|
+
import { bindCodePicker, codePicker, getCodeFormat, updateCodePicker } from './code-picker.js';
|
|
20
|
+
import { opKey } from './operations.js';
|
|
21
|
+
|
|
22
|
+
/** A soft callout when the operation takes an Idempotency-Key: it's safe to retry with the same key. */
|
|
23
|
+
function idempotencyCallout(op, document) {
|
|
24
|
+
const parameter = op.parameters.map(raw => dereference(raw, document)).find(item => item?.in === 'header' && /^idempotency[-_]?key$/i.test(item.name || ''));
|
|
25
|
+
if (!parameter) return '';
|
|
26
|
+
return `<div class="callout info" role="note">${icon('repeat', true)}<div><strong>${esc(t('docs.idempotency'))}</strong> ${th('docs.idempotencyBody', { header: `<code>${esc(parameter.name)}</code>` })}</div></div>`;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
const firstSentence = text => String(text ?? '').split(/\n\s*\n/)[0].replace(/\s*\n\s*/g, ' ').replace(/[*_`]/g, '').trim().replace(/^(.{0,180}?[.!?])\s.*$/, '$1');
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* What the Docs page remembers about an operation while the session lasts, so coming Back from
|
|
33
|
+
* a model page finds the same responses open and the same rows expanded.
|
|
34
|
+
*/
|
|
35
|
+
export function newDocsState() {
|
|
36
|
+
return { openResponses: null, trees: new Map(), bodyView: 'schema', example: null };
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** A list's state, remembered for the session in `ui` and, for closed child lists, per API in local storage. */
|
|
40
|
+
const treeState = (ui, key, scope) => { if (!ui.trees.has(key)) ui.trees.set(key, newTreeState(scope ? `${scope}|${key}` : undefined)); return ui.trees.get(key); };
|
|
41
|
+
|
|
42
|
+
/** The server base URL shown in the bar: the document's first absolute server, else this origin. */
|
|
43
|
+
export function baseUrl(document) {
|
|
44
|
+
const server = document?.servers?.[0]?.url;
|
|
45
|
+
return /^https?:/.test(server || '') ? server.replace(/\/$/, '') : globalThis.location.origin;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** A request built from the spec's examples, for the samples. Credentials stay placeholders. */
|
|
49
|
+
function sampleRequest(op, document, media, type, samples) {
|
|
50
|
+
const parameters = op.parameters.map(raw => dereference(raw, document)).filter(Boolean);
|
|
51
|
+
const path = op.path.replace(/\{([^}]+)\}/g, (match, name) => {
|
|
52
|
+
const parameter = parameters.find(item => item.in === 'path' && item.name === name);
|
|
53
|
+
const example = parameter?.example ?? exampleFor(parameter?.schema, document);
|
|
54
|
+
return encodeURIComponent(typeof example === 'string' && example !== 'string' ? example : `{${name}}`);
|
|
55
|
+
});
|
|
56
|
+
const url = new URL(path.replace(/^\//, ''), location.origin + new URL('../', globalThis.document.baseURI).pathname);
|
|
57
|
+
for (const parameter of parameters.filter(item => item.in === 'query' && item.required)) url.searchParams.set(parameter.name, String(parameter.example ?? exampleFor(parameter.schema, document)));
|
|
58
|
+
const headers = {};
|
|
59
|
+
for (const parameter of parameters.filter(item => item.in === 'header' && item.required)) headers[parameter.name] = parameter.name.toLowerCase() === 'idempotency-key' ? '$(uuidgen)' : String(parameter.example ?? exampleFor(parameter.schema, document));
|
|
60
|
+
let body = null;
|
|
61
|
+
if (media?.schema) {
|
|
62
|
+
headers['Content-Type'] = type;
|
|
63
|
+
body = encodeRequestBody(documentedExample(media, document, samples), type, headers);
|
|
64
|
+
}
|
|
65
|
+
return { method: op.method, url: url.href, headers, body };
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** The documented example of a media type: its own example, a named one, a real record, else generated. */
|
|
69
|
+
export function documentedExample(media, document, samples = []) {
|
|
70
|
+
if (media.example !== undefined) return media.example;
|
|
71
|
+
const named = Object.values(media.examples || {})[0]?.value;
|
|
72
|
+
if (named !== undefined) return named;
|
|
73
|
+
const name = refName(media.schema);
|
|
74
|
+
return name ? modelExample(name, document, samples).value : exampleFor(media.schema, document);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** Status codes take their class's hue (components.js statusTone). */
|
|
78
|
+
const statusClass = statusTone;
|
|
79
|
+
|
|
80
|
+
/** The deprecation text: an explicit extension, else the description's first paragraph after "Deprecated." */
|
|
81
|
+
function deprecation(operation) {
|
|
82
|
+
const description = String(operation.description || '');
|
|
83
|
+
const lead = /^\s*\**deprecated\.?\**\s*/i.exec(description);
|
|
84
|
+
const rest = lead ? description.slice(lead[0].length) : description;
|
|
85
|
+
const paragraphs = rest.trim().split(/\n\s*\n/).filter(Boolean);
|
|
86
|
+
const explicit = operation['x-deprecation'] || operation['x-deprecated-message'];
|
|
87
|
+
// The notice carries the first paragraph, so the prose below it doesn't repeat it.
|
|
88
|
+
// The notice says "Deprecated" and what to use, so the prose keeps everything after the lead.
|
|
89
|
+
return { notice: explicit || (lead ? paragraphs[0] || '' : ''), prose: lead ? rest.trim() : description };
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
function parameterGroups(op, document) {
|
|
93
|
+
const parameters = op.parameters.map(raw => dereference(raw, document)).filter(parameter => parameter?.name);
|
|
94
|
+
return [['path', 'docs.pathParams'], ['query', 'docs.queryParams'], ['header', 'docs.headers'], ['cookie', 'docs.cookies']]
|
|
95
|
+
.map(([where, key]) => ({ where, key, items: parameters.filter(parameter => parameter.in === where) })).filter(group => group.items.length);
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
function treeHead(raw, document, { id, extra = '' }) {
|
|
99
|
+
const { props, required } = propertiesOf(rowSchema(raw, document), document);
|
|
100
|
+
const count = Object.keys(props).length;
|
|
101
|
+
// Child lists start open, so the head offers Collapse all (syncTreeButtons keeps the label true).
|
|
102
|
+
return `<div class="card-head"><span>${esc(t('docs.props', { n: count }))} · ${esc(t('docs.requiredN', { n: required.size }))}</span><span class="end">${extra}${hasNested(raw, document) ? `<button type="button" class="btn btn-ghost btn-xs" data-tree-all="${esc(id)}">${icon('chevrons-ud', true)}<span>${esc(t('tree.collapseAll'))}</span></button>` : ''}</span></div>`;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
function authentication(op, document, ctx) {
|
|
106
|
+
if (isPublic(op, document)) return `<p class="lede">${esc(t('docs.publicLede'))}</p>`;
|
|
107
|
+
const signedOut = !ctx.state.cap?.identity?.name;
|
|
108
|
+
const canSignIn = (ctx.state.cap?.authProviders || []).length > 0;
|
|
109
|
+
const scheme = primarySchemes(op, document)[0];
|
|
110
|
+
const roles = requiredScopes(op, document);
|
|
111
|
+
const alternatives = securityRequirements(op, document).filter(alternative => alternative.some(item => item.scopes.length)).length || 1;
|
|
112
|
+
return `<div class="req-list">
|
|
113
|
+
<div class="req"><span class="req-ico">${icon('lock', true)}</span><div class="grow"><div class="t">${esc(t('docs.signin'))} <span class="tag tag-mono">${esc(scheme?.name ?? '')}</span>${signedOut ? `<span class="tag tag-accent">${esc(t('docs.youreOut'))}</span>` : ''}</div>
|
|
114
|
+
<div class="s" lang="en">${scheme?.scheme?.description ? inline(String(scheme.scheme.description).replace(/\s*\n\s*/g, ' ')) : esc(t('auth.schemeBody', { name: ctx.state.cap?.apiName || '' }))}</div></div>
|
|
115
|
+
${signedOut && canSignIn ? `<button type="button" class="btn btn-sm btn-primary" data-action="signin">${icon('log-in', true)}${esc(t('shell.signIn'))}</button>` : ''}</div>
|
|
116
|
+
${roles.length ? `<div class="req"><span class="req-ico">${icon('shield', true)}</span><div class="grow"><div class="t">${esc(t('docs.roles'))} ${roles.map(role => `<span class="tag tag-mono">${esc(role)}</span>`).join(' ')}</div><div class="s">${esc(t('docs.rolesBody', { n: roles.length > 1 || alternatives > 1 ? 2 : 1 }))}</div></div></div>` : ''}
|
|
117
|
+
</div>`;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/** The main column: head row, scrolling page and bottom bar. */
|
|
121
|
+
function mainPane(ctx, parts) {
|
|
122
|
+
const { state, ui } = ctx;
|
|
123
|
+
const { op, document, groups, media, type, responses, firstOk } = parts;
|
|
124
|
+
const operation = op.operation;
|
|
125
|
+
const signedOut = !state.cap?.identity?.name;
|
|
126
|
+
const dep = operation.deprecated ? deprecation(operation) : null;
|
|
127
|
+
const description = dep ? dep.prose : operation.description;
|
|
128
|
+
const roles = requiredScopes(op, document);
|
|
129
|
+
const securityTag = isPublic(op, document)
|
|
130
|
+
? `<span class="tag">${icon('globe', true)}${esc(t('op.public'))}</span>`
|
|
131
|
+
: `<span class="tag">${icon(signedOut ? 'lock' : 'shield', true)}${esc(signedOut ? t('docs.needsSignin') : roles.length ? scopeText(op, document) : t('docs.signedInUsers'))}</span>`;
|
|
132
|
+
const bodyName = media?.schema ? schemaName(media.schema, document) : '';
|
|
133
|
+
const openSet = ui.openResponses ??= new Set(firstOk ? [firstOk] : []);
|
|
134
|
+
|
|
135
|
+
const bodyCard = media ? `<h3 id="doc-body">${esc(t('docs.body'))} <span class="faint">· ${esc(type)}${bodyName ? ' ·' : ''}</span> ${bodyName ? `<a class="type-link" href="#model/${encodeURIComponent(bodyName.replace(/\[\]$/, ''))}" data-model="${esc(bodyName.replace(/\[\]$/, ''))}">${esc(bodyName)}</a>` : ''}</h3>
|
|
136
|
+
<div class="card flat" data-body-card>
|
|
137
|
+
${treeHead(media.schema, document, { id: 'body', extra: `<div class="segmented" role="group" aria-label="${esc(t('docs.bodyView'))}"><button type="button" data-body-view="schema" aria-pressed="${ui.bodyView !== 'example'}">${esc(t('docs.schema'))}</button><button type="button" data-body-view="example" aria-pressed="${ui.bodyView === 'example'}">${esc(t('docs.example'))}</button></div>` })}
|
|
138
|
+
<div data-body-content></div>
|
|
139
|
+
</div>` : '';
|
|
140
|
+
|
|
141
|
+
const responseItems = responses.map(([code, response]) => {
|
|
142
|
+
const media2 = Object.values(response.content || {})[0];
|
|
143
|
+
const schema = media2?.schema;
|
|
144
|
+
const open = !!schema && openSet.has(code);
|
|
145
|
+
const name = schema ? schemaName(schema, document) || resolve(schema, document).type : '';
|
|
146
|
+
const id = `doc-response-${code}`;
|
|
147
|
+
const head = `<span class="slot" aria-hidden="true">${schema ? icon(open ? 'chevron-down' : 'chevron-right', true) : ''}</span>
|
|
148
|
+
<span class="code ${statusClass(code)}">${esc(code)}</span><span class="d" lang="en">${esc(firstSentence(response.description || ''))}</span><span class="spacer"></span>
|
|
149
|
+
${schema ? `<span class="type-link">${esc(name)}</span>` : `<span class="faint" style="font-size:var(--fs-sm)">${esc(t('res.noBody'))}</span>`}`;
|
|
150
|
+
return `<div class="resp-item${open ? ' is-open' : ''}">${schema
|
|
151
|
+
? `<button type="button" class="head" aria-expanded="${open}" aria-controls="${id}" data-response-toggle="${esc(code)}">${head}</button>`
|
|
152
|
+
: `<div class="head">${head}</div>`}
|
|
153
|
+
${schema ? `<div class="body" id="${id}" ${open ? '' : 'hidden'}><div class="media"><span>${esc(Object.keys(response.content)[0])}</span><span class="spacer"></span>${hasNested(schema, document) ? `<button type="button" class="btn btn-ghost btn-xs" data-tree-all="r${esc(code)}" data-all="off">${icon('chevrons-ud', true)}<span>${esc(t('tree.expandAll'))}</span></button>` : ''}</div><div data-response-tree="${esc(code)}"></div></div>` : ''}
|
|
154
|
+
</div>`;
|
|
155
|
+
}).join('');
|
|
156
|
+
|
|
157
|
+
return `${contextBar({ kind: 'op', op, view: 'docs' })}
|
|
158
|
+
<div class="pane-scroll" id="doc-main"><div class="doc-inner">
|
|
159
|
+
<h1 id="doc-title" tabindex="-1" lang="en">${esc(op.title)}</h1>
|
|
160
|
+
<div class="doc-meta">${method(op.method)}<code class="ltr">${esc(op.path)}</code>${securityTag}${operation.deprecated ? `<span class="tag tag-warn">${esc(t('side.deprecated'))}</span>` : ''}<span class="tag tag-mono" title="operationId">${esc(opKey(op))}</span></div>
|
|
161
|
+
${dep ? deprecationNotice(op, { ops: state.ops, document, where: 'docs' }) : ''}
|
|
162
|
+
<div class="prose" lang="en">${description?.trim() ? linkOperationIds(markdown(description), state.ops) : dep ? '' : `<p class="faint">${esc(t('docs.noDesc'))}</p>`}</div>
|
|
163
|
+
${idempotencyCallout(op, document)}
|
|
164
|
+
<h2 id="doc-request">${esc(t('docs.request'))}</h2>
|
|
165
|
+
${groups.map(group => `<h3 id="doc-params-${group.where}">${esc(t(group.key))} <span class="faint">· ${group.items.length}</span></h3><div class="card flat" data-params="${group.where}"></div>`).join('')}
|
|
166
|
+
${bodyCard}
|
|
167
|
+
${!groups.length && !media ? `<p class="lede">${esc(t('docs.noInputs'))}</p>` : ''}
|
|
168
|
+
<h2 id="doc-responses">${esc(t('docs.responses'))} <span class="count">${esc(t('docs.documented', { n: responses.length }))}</span></h2>
|
|
169
|
+
<div class="resp-list">${responseItems}</div>
|
|
170
|
+
<h2 id="doc-auth">${esc(t('docs.authentication'))}</h2>
|
|
171
|
+
${authentication(op, document, ctx)}
|
|
172
|
+
</div></div>
|
|
173
|
+
<div class="pane-bar"><span class="bar-text">${icon('info', true)}<span>${esc(t('docs.bar'))}</span></span>
|
|
174
|
+
<button type="button" class="btn btn-primary btn-sm" data-action="docs-try" ${shortcutAttrs('docs')}>${icon('flask', true)}${esc(t('op.tryIt'))}${shortcutHint('docs')}</button></div>`;
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/** The right column: outline, request sample and response examples, then the base URL bar. */
|
|
178
|
+
function asidePane(ctx, parts) {
|
|
179
|
+
const { op, document, groups, media, responses, firstOk, sample } = parts;
|
|
180
|
+
const { samples } = ctx;
|
|
181
|
+
const outline = [['doc-title', t('docs.overview')], ['doc-request', t('docs.request')],
|
|
182
|
+
...groups.map(group => [`doc-params-${group.where}`, t(group.key), true]), ...(media ? [['doc-body', t('docs.body'), true]] : []),
|
|
183
|
+
['doc-responses', t('docs.responses')], ['doc-auth', t('docs.authentication')]];
|
|
184
|
+
const withBody = responses.filter(([, response]) => Object.values(response.content || {})[0]?.schema).slice(0, 4);
|
|
185
|
+
const selected = withBody.some(([code]) => code === firstOk) ? firstOk : withBody[0]?.[0];
|
|
186
|
+
const examples = withBody.map(([code, response]) => {
|
|
187
|
+
const media2 = Object.values(response.content)[0];
|
|
188
|
+
return { code, view: jsonView(documentedExample(media2, document, samples), { label: t('docs.responseExample') }) };
|
|
189
|
+
});
|
|
190
|
+
return `<div class="aside-head">${esc(t('docs.onThisPage'))}</div>
|
|
191
|
+
<div class="pane-scroll" id="aside-scroll"><div class="aside-inner">
|
|
192
|
+
<nav class="outline" aria-label="${esc(t('docs.onThisPage'))}">${outline.map(([id, label, sub], index) => `<a href="#${id}" data-outline="${id}" class="${sub ? 'sub' : ''}"${index === 0 ? ' aria-current="location"' : ''}>${esc(label)}</a>`).join('')}</nav>
|
|
193
|
+
<p class="aside-label">${esc(t('docs.requestSample'))}</p>
|
|
194
|
+
<div class="sample-card card">
|
|
195
|
+
<div class="viewer-bar">${codePicker({ id: 'docs-code-picker' })}<span class="spacer"></span>${copyButton(t('docs.copySample'), { action: 'copy-sample' })}</div>
|
|
196
|
+
<pre class="ltr" data-sample tabindex="0" aria-label="${esc(t('docs.requestSample'))}"></pre>
|
|
197
|
+
</div>
|
|
198
|
+
${examples.length ? `<p class="aside-label">${esc(t('docs.responseExample'))}</p>
|
|
199
|
+
<div class="sample-card card">
|
|
200
|
+
<div class="tabs" role="tablist" aria-label="${esc(t('docs.responseExample'))}">${examples.map(({ code }) => tab(code, { selected: code === selected, id: `doc-example-tab-${code}`, controls: `doc-example-${code}`, data: `data-example="${esc(code)}"`, labelClass: `code-label ${statusClass(code)}` })).join('')}</div>
|
|
201
|
+
${examples.map(({ code, view }) => `<div id="doc-example-${code}" role="tabpanel" aria-labelledby="doc-example-tab-${code}" ${code === selected ? '' : 'hidden'}>${view.html}</div>`).join('')}
|
|
202
|
+
</div>` : ''}
|
|
203
|
+
</div></div>
|
|
204
|
+
<div class="pane-bar"><span class="bar-text">${icon('server', true)}<span>${esc(t('docs.base'))} <code class="ltr">${esc(baseUrl(document))}</code></span></span>${copyButton(t('docs.copyBase'), { action: 'copy-base', size: 'btn-xs' })}</div>`;
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/**
|
|
208
|
+
* Renders the Docs view into the two reading panes.
|
|
209
|
+
* @param {HTMLElement} main the `.doc-pane`
|
|
210
|
+
* @param {HTMLElement} aside the `.aside-pane`
|
|
211
|
+
* @param {{ state: object, ui: object, samples: unknown[] }} ctx `ui` is {@link newDocsState} for this operation
|
|
212
|
+
*/
|
|
213
|
+
export function renderDocs(main, aside, ctx) {
|
|
214
|
+
const { state, ui } = ctx;
|
|
215
|
+
const op = state.op;
|
|
216
|
+
const document = state.doc;
|
|
217
|
+
if (!op) { main.innerHTML = aside.innerHTML = ''; return; }
|
|
218
|
+
const groups = parameterGroups(op, document);
|
|
219
|
+
const body = dereference(op.operation.requestBody, document);
|
|
220
|
+
const type = Object.hasOwn(body?.content || {}, 'application/json') ? 'application/json' : Object.keys(body?.content || {})[0];
|
|
221
|
+
const media = body?.content?.[type];
|
|
222
|
+
const responses = Object.entries(op.operation.responses || {}).map(([code, raw]) => [code, dereference(raw, document) || {}]);
|
|
223
|
+
const hasBody = ([, response]) => !!Object.values(response.content || {})[0]?.schema;
|
|
224
|
+
// The response that matters most opens first: 201 for a create, otherwise the first 2xx.
|
|
225
|
+
const created = op.method === 'POST' ? responses.find(entry => entry[0] === '201' && hasBody(entry)) : undefined;
|
|
226
|
+
const firstOk = (created ?? responses.find(entry => /^2/.test(entry[0]) && hasBody(entry)))?.[0];
|
|
227
|
+
const sample = sampleRequest(op, document, media, type, ctx.samples);
|
|
228
|
+
const parts = { op, document, groups, media, type, responses, firstOk, sample };
|
|
229
|
+
main.innerHTML = mainPane(ctx, parts);
|
|
230
|
+
aside.innerHTML = asidePane(ctx, parts);
|
|
231
|
+
|
|
232
|
+
// Trees render after the markup so each keeps its own open/closed state in `ui`.
|
|
233
|
+
const place = (selector, html) => { const holder = main.querySelector(selector); if (holder) holder.innerHTML = html; };
|
|
234
|
+
const scope = `${state.documentUrl}#docs/${opKey(op)}`;
|
|
235
|
+
for (const group of groups) place(`[data-params="${group.where}"]`, parameterTree(group.items, document, { id: `params-${group.where}`, state: treeState(ui, `params-${group.where}`, scope), label: t(group.key) }));
|
|
236
|
+
const drawBody = () => {
|
|
237
|
+
if (!media) return;
|
|
238
|
+
place('[data-body-content]', ui.bodyView === 'example'
|
|
239
|
+
? jsonView(documentedExample(media, document, ctx.samples), { label: t('docs.example') }).html
|
|
240
|
+
: propertyTree(media.schema, document, { id: 'body', state: treeState(ui, 'body', scope), label: schemaName(media.schema, document) }));
|
|
241
|
+
for (const button of main.querySelectorAll('[data-body-view]')) button.setAttribute('aria-pressed', String(button.dataset.bodyView === ui.bodyView));
|
|
242
|
+
main.querySelector('[data-tree-all="body"]')?.toggleAttribute('hidden', ui.bodyView === 'example');
|
|
243
|
+
bindTrees(main);
|
|
244
|
+
bindJsonViews(main);
|
|
245
|
+
};
|
|
246
|
+
const drawResponse = code => {
|
|
247
|
+
const response = responses.find(([c]) => c === code)?.[1];
|
|
248
|
+
const media2 = Object.values(response?.content || {})[0];
|
|
249
|
+
const holder = main.querySelector(`[data-response-tree="${code}"]`);
|
|
250
|
+
if (holder && media2?.schema && !holder.hasChildNodes()) {
|
|
251
|
+
holder.innerHTML = propertyTree(media2.schema, document, { id: `r${code}`, state: treeState(ui, `r${code}`, scope), label: schemaName(media2.schema, document) });
|
|
252
|
+
bindTrees(main);
|
|
253
|
+
}
|
|
254
|
+
};
|
|
255
|
+
drawBody();
|
|
256
|
+
for (const code of ui.openResponses) drawResponse(code);
|
|
257
|
+
bindTrees(main);
|
|
258
|
+
bindJsonViews(aside);
|
|
259
|
+
syncTreeButtons(main);
|
|
260
|
+
|
|
261
|
+
const pre = aside.querySelector('[data-sample]');
|
|
262
|
+
// The language is the one remembered for Docs and Try it alike (code-picker.js).
|
|
263
|
+
const draw = () => {
|
|
264
|
+
const format = getCodeFormat();
|
|
265
|
+
pre.innerHTML = highlightSnippet(formatRequest(format, sample, []), snippetFormats.find(item => item.id === format)?.lexer);
|
|
266
|
+
pre.dataset.format = format;
|
|
267
|
+
updateCodePicker(aside.querySelector('[data-code-trigger]'), format);
|
|
268
|
+
};
|
|
269
|
+
draw();
|
|
270
|
+
bindCodePicker(aside, { onChange: draw });
|
|
271
|
+
|
|
272
|
+
if (!main.dataset.treeSync) { main.dataset.treeSync = ''; main.addEventListener('tree-change', () => syncTreeButtons(main)); }
|
|
273
|
+
main.onclick = event => {
|
|
274
|
+
const toggle = event.target.closest('[data-response-toggle]');
|
|
275
|
+
if (toggle) {
|
|
276
|
+
const code = toggle.dataset.responseToggle;
|
|
277
|
+
const panel = globalThis.document.getElementById(toggle.getAttribute('aria-controls'));
|
|
278
|
+
const open = panel.hidden;
|
|
279
|
+
panel.hidden = !open;
|
|
280
|
+
if (open) { ui.openResponses.add(code); drawResponse(code); } else ui.openResponses.delete(code);
|
|
281
|
+
toggle.setAttribute('aria-expanded', String(open));
|
|
282
|
+
toggle.closest('.resp-item').classList.toggle('is-open', open);
|
|
283
|
+
toggle.querySelector('use').setAttribute('href', open ? '#i-chevron-down' : '#i-chevron-right');
|
|
284
|
+
syncTreeButtons(main);
|
|
285
|
+
return;
|
|
286
|
+
}
|
|
287
|
+
const view = event.target.closest('[data-body-view]');
|
|
288
|
+
if (view) { ui.bodyView = view.dataset.bodyView; drawBody(); return; }
|
|
289
|
+
const all = event.target.closest('[data-tree-all]');
|
|
290
|
+
if (all) {
|
|
291
|
+
const holder = all.dataset.treeAll === 'body' ? main.querySelector('[data-body-content] .stree') : main.querySelector(`[data-response-tree="${all.dataset.treeAll.slice(1)}"] .stree`);
|
|
292
|
+
if (holder) { setAllOpen(holder, !isAllOpen(holder)); syncTreeButtons(main); }
|
|
293
|
+
}
|
|
294
|
+
};
|
|
295
|
+
aside.onclick = event => {
|
|
296
|
+
const copy = event.target.closest('[data-action="copy-sample"]');
|
|
297
|
+
if (copy) { event.stopPropagation(); copyText(pre.textContent, { button: copy, what: t('copy.what.sample'), select: pre, notice: pre }); return; }
|
|
298
|
+
const base = event.target.closest('[data-action="copy-base"]');
|
|
299
|
+
if (base) { event.stopPropagation(); copyText(baseUrl(document), { button: base, what: t('copy.what.url') }); return; }
|
|
300
|
+
const example = event.target.closest('[data-example]');
|
|
301
|
+
if (example) {
|
|
302
|
+
for (const item of example.parentElement.children) {
|
|
303
|
+
const selected = item === example;
|
|
304
|
+
item.setAttribute('aria-selected', String(selected));
|
|
305
|
+
item.tabIndex = selected ? 0 : -1;
|
|
306
|
+
globalThis.document.getElementById(item.getAttribute('aria-controls')).hidden = !selected;
|
|
307
|
+
}
|
|
308
|
+
return;
|
|
309
|
+
}
|
|
310
|
+
const link = event.target.closest('[data-outline]');
|
|
311
|
+
if (link) {
|
|
312
|
+
event.preventDefault();
|
|
313
|
+
const target = main.querySelector('#' + CSS.escape(link.dataset.outline));
|
|
314
|
+
const scroller = main.querySelector('#doc-main');
|
|
315
|
+
const reduce = matchMedia('(prefers-reduced-motion: reduce)').matches;
|
|
316
|
+
if (target) scroller.scrollTo({ top: link.dataset.outline === 'doc-title' ? 0 : target.offsetTop - scroller.querySelector('.doc-inner').offsetTop - 12, behavior: reduce ? 'auto' : 'smooth' });
|
|
317
|
+
target?.focus?.({ preventScroll: true });
|
|
318
|
+
}
|
|
319
|
+
};
|
|
320
|
+
|
|
321
|
+
// The outline follows the section in view.
|
|
322
|
+
const scroller = main.querySelector('#doc-main');
|
|
323
|
+
const links = [...aside.querySelectorAll('[data-outline]')];
|
|
324
|
+
const follow = () => {
|
|
325
|
+
const top = scroller.getBoundingClientRect().top + 32;
|
|
326
|
+
let current = links[0];
|
|
327
|
+
for (const link of links) {
|
|
328
|
+
const target = main.querySelector('#' + CSS.escape(link.dataset.outline));
|
|
329
|
+
if (target && target.getBoundingClientRect().top <= top) current = link;
|
|
330
|
+
}
|
|
331
|
+
// At the end of the page the last section is current even when it is too short to reach the top.
|
|
332
|
+
if (scroller.scrollTop + scroller.clientHeight >= scroller.scrollHeight - 2 && scroller.scrollTop > 0) current = links.at(-1);
|
|
333
|
+
for (const link of links) link === current ? link.setAttribute('aria-current', 'location') : link.removeAttribute('aria-current');
|
|
334
|
+
};
|
|
335
|
+
scroller.addEventListener('scroll', follow, { passive: true });
|
|
336
|
+
follow();
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
/** Keeps the Expand all / Collapse all buttons' labels in step with their trees. */
|
|
340
|
+
function syncTreeButtons(main) {
|
|
341
|
+
for (const button of main.querySelectorAll('[data-tree-all]')) {
|
|
342
|
+
const holder = button.dataset.treeAll === 'body' ? main.querySelector('[data-body-content] .stree') : main.querySelector(`[data-response-tree="${button.dataset.treeAll.slice(1)}"] .stree`);
|
|
343
|
+
const all = !!holder && isAllOpen(holder);
|
|
344
|
+
button.querySelector('span').textContent = t(all ? 'tree.collapseAll' : 'tree.expandAll');
|
|
345
|
+
}
|
|
346
|
+
}
|
|
347
|
+
|
|
Binary file
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><style>path{fill:#181a20;stroke:#181a20;stroke-width:1;stroke-linejoin:round}.g{opacity:.35}@media (prefers-color-scheme:dark){path{fill:#f7f7f8;stroke:#f7f7f8}.g{opacity:.4}}</style><path class="g" d="M1.5 5 L7.57 8.15 L9.11 12 L7.57 15.85 L1.5 19 L4.3 12 Z"/><path d="M9 5 L22.5 12 L9 19 L11.8 12 Z"/></svg>
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
// The content of a field's "i" toggletip (mock 23): the description from the spec, the type and
|
|
2
|
+
// constraints, an example, and how the value is sent. Spec text keeps lang="en".
|
|
3
|
+
import { esc } from './components.js';
|
|
4
|
+
import { t, th } from './i18n.js';
|
|
5
|
+
import { inline } from './markdown.js';
|
|
6
|
+
import { schemaName } from './schema-model.js';
|
|
7
|
+
import { shortcutHint } from './shortcuts.js';
|
|
8
|
+
|
|
9
|
+
const typeOf = schema => (Array.isArray(schema.type) ? schema.type.find(item => item !== 'null') : schema.type) || (schema.properties ? 'object' : schema.items ? 'array' : 'string');
|
|
10
|
+
|
|
11
|
+
function sentAs(info, schema, example) {
|
|
12
|
+
const parameter = info.parameter;
|
|
13
|
+
const name = info.path.at(-1) ?? parameter?.name;
|
|
14
|
+
if (parameter?.in === 'path') return th('help.sentPath', { name: `<code>{${esc(parameter.name)}}</code>` });
|
|
15
|
+
if (parameter?.in === 'query') return th('help.sentQuery', { example: `<code>?${esc(parameter.name)}=…</code>` });
|
|
16
|
+
const type = typeOf(schema);
|
|
17
|
+
const sample = example !== undefined ? `<code>"${esc(name)}": ${esc(JSON.stringify(example))}</code>` : `<code>"${esc(name)}"</code>`;
|
|
18
|
+
return th('help.sentJson.' + (['number', 'integer', 'boolean', 'array', 'object'].includes(type) ? type : 'string'), { example: sample });
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** HTML for the toggletip of an "i" button rendered by fields/render.js. */
|
|
22
|
+
export function describeField(button, { state, requestMedia }) {
|
|
23
|
+
const info = button.fieldInfo;
|
|
24
|
+
if (!info) return '';
|
|
25
|
+
const schema = info.schema;
|
|
26
|
+
const facts = [];
|
|
27
|
+
const add = (label, value, plain = false) => facts.push(`<dt>${esc(label)}</dt><dd${plain ? ' class="plain"' : ''}>${value}</dd>`);
|
|
28
|
+
add(t('help.type'), esc([typeOf(schema), schema.format].filter(Boolean).join(' · ')));
|
|
29
|
+
if (schema.minimum !== undefined) add(t('help.minimum'), esc(schema.minimum));
|
|
30
|
+
if (schema.exclusiveMinimum !== undefined && typeof schema.exclusiveMinimum === 'number') add(t('help.above'), esc(schema.exclusiveMinimum));
|
|
31
|
+
if (schema.maximum !== undefined && Math.abs(schema.maximum) < 1e15) add(t('help.maximum'), esc(schema.maximum));
|
|
32
|
+
if (schema.minLength !== undefined) add(t('help.minLength'), esc(t('help.chars', { n: schema.minLength })), true);
|
|
33
|
+
if (schema.maxLength !== undefined) add(t('help.maxLength'), esc(t('help.chars', { n: schema.maxLength })), true);
|
|
34
|
+
if (schema.maxItems !== undefined) add(t('help.maxItems'), esc(schema.maxItems));
|
|
35
|
+
if (schema.pattern) add(t('help.pattern'), esc(schema.pattern));
|
|
36
|
+
if (schema.enum) add(t('help.oneOf'), schema.enum.map(value => `<code>${esc(value)}</code>`).join(' '), true);
|
|
37
|
+
if (info.currency) add(t('help.currency'), th('help.currencyFrom', { field: `<code>${esc(info.currency.name)}</code>`, values: (info.currency.values || []).map(esc).join(', ') }), true);
|
|
38
|
+
const example = schema.example ?? (Array.isArray(schema.examples) ? schema.examples[0] : undefined) ?? info.example;
|
|
39
|
+
if (example !== undefined) add(t('help.example'), esc(typeof example === 'string' ? example : JSON.stringify(example)));
|
|
40
|
+
if (schema['x-lookup']?.url) add(t('help.options'), th('help.optionsFrom', { url: `<code>GET ${esc(schema['x-lookup'].url)}</code>` }), true);
|
|
41
|
+
add(t('help.sentAs'), sentAs(info, schema, example ?? schema.enum?.[0]), true);
|
|
42
|
+
const owner = info.parameter ? state.op?.operation.operationId || state.op?.title : schemaName(requestMedia().media?.schema, state.doc);
|
|
43
|
+
const pointer = [owner, ...info.path].filter(item => item !== undefined && item !== '').join('.');
|
|
44
|
+
return `<div class="pop toggletip" role="dialog" aria-label="${esc(t('help.about', { name: info.label }))}">
|
|
45
|
+
<div class="tt-body">
|
|
46
|
+
<h3 lang="en">${esc(info.label)}<span class="tag ${info.required ? 'tag-warn' : ''}">${esc(t(info.required ? 'help.required' : 'help.optional'))}</span></h3>
|
|
47
|
+
${schema.description ? `<p lang="en">${inline(schema.description)}</p>` : `<p>${esc(t('help.noDescription'))}</p>`}
|
|
48
|
+
<dl class="facts">${facts.join('')}</dl>
|
|
49
|
+
</div>
|
|
50
|
+
<div class="tt-foot"><button type="button" class="link" data-action="view-docs">${esc(t('help.openDocs'))}</button>${pointer ? `<span class="ltr faint">${esc(pointer)}</span>` : ''}<span class="spacer"></span>${shortcutHint('escape')}</div>
|
|
51
|
+
</div>`;
|
|
52
|
+
}
|