@openhi/sdk 0.0.0 → 0.1.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/LICENSE +19 -0
- package/README.md +205 -1
- package/astro/OpenhiPreview.astro +59 -0
- package/lib/api-base.d.ts +2 -0
- package/lib/api-base.js +22 -0
- package/lib/astro/index.d.ts +8 -0
- package/lib/astro/index.js +8 -0
- package/lib/astro/loaders.d.ts +131 -0
- package/lib/astro/loaders.js +318 -0
- package/lib/content/asset.d.ts +69 -0
- package/lib/content/asset.js +151 -0
- package/lib/content/blocks/catalogue.d.ts +11 -0
- package/lib/content/blocks/catalogue.js +71 -0
- package/lib/content/blocks/declare.d.ts +143 -0
- package/lib/content/blocks/declare.js +210 -0
- package/lib/content/blocks/index.d.ts +2 -0
- package/lib/content/blocks/index.js +2 -0
- package/lib/content/content-type.d.ts +52 -0
- package/lib/content/content-type.js +97 -0
- package/lib/content/import-plan.d.ts +56 -0
- package/lib/content/import-plan.js +71 -0
- package/lib/content/index.d.ts +14 -0
- package/lib/content/index.js +14 -0
- package/lib/content/page.d.ts +91 -0
- package/lib/content/page.js +222 -0
- package/lib/content/sanitise-html.d.ts +36 -0
- package/lib/content/sanitise-html.js +92 -0
- package/lib/content/section.d.ts +60 -0
- package/lib/content/section.js +59 -0
- package/lib/content/shapes.d.ts +68 -0
- package/lib/content/shapes.js +9 -0
- package/lib/content/theme.d.ts +25 -0
- package/lib/content/theme.js +54 -0
- package/lib/content/types.d.ts +142 -0
- package/lib/content/types.js +121 -0
- package/lib/errors.d.ts +25 -0
- package/lib/errors.js +25 -0
- package/lib/forms/index.d.ts +107 -0
- package/lib/forms/index.js +201 -0
- package/lib/index.d.ts +10 -0
- package/lib/index.js +9 -0
- package/lib/node/bin.d.ts +2 -0
- package/lib/node/bin.js +14 -0
- package/lib/node/cli/api.d.ts +24 -0
- package/lib/node/cli/api.js +62 -0
- package/lib/node/cli/check.d.ts +26 -0
- package/lib/node/cli/check.js +265 -0
- package/lib/node/cli/context.d.ts +37 -0
- package/lib/node/cli/context.js +55 -0
- package/lib/node/cli/env-check.d.ts +4 -0
- package/lib/node/cli/env-check.js +47 -0
- package/lib/node/cli/init.d.ts +2 -0
- package/lib/node/cli/init.js +171 -0
- package/lib/node/cli/load-blocks.d.ts +15 -0
- package/lib/node/cli/load-blocks.js +109 -0
- package/lib/node/cli/local-content.d.ts +47 -0
- package/lib/node/cli/local-content.js +126 -0
- package/lib/node/cli/main.d.ts +3 -0
- package/lib/node/cli/main.js +58 -0
- package/lib/node/cli/optional-tool.d.ts +8 -0
- package/lib/node/cli/optional-tool.js +26 -0
- package/lib/node/cli/pull.d.ts +2 -0
- package/lib/node/cli/pull.js +113 -0
- package/lib/node/cli/push.d.ts +6 -0
- package/lib/node/cli/push.js +227 -0
- package/lib/node/env.d.ts +34 -0
- package/lib/node/env.js +66 -0
- package/lib/node/index.d.ts +9 -0
- package/lib/node/index.js +8 -0
- package/lib/node/media.d.ts +56 -0
- package/lib/node/media.js +176 -0
- package/lib/node/read.d.ts +19 -0
- package/lib/node/read.js +55 -0
- package/lib/paging.d.ts +14 -0
- package/lib/paging.js +41 -0
- package/lib/preview/apply-draft.d.ts +42 -0
- package/lib/preview/apply-draft.js +185 -0
- package/lib/preview/index.d.ts +7 -0
- package/lib/preview/index.js +4 -0
- package/lib/preview/marks.d.ts +25 -0
- package/lib/preview/marks.js +17 -0
- package/lib/preview/runtime.d.ts +17 -0
- package/lib/preview/runtime.js +85 -0
- package/lib/preview/studio-origin.d.ts +3 -0
- package/lib/preview/studio-origin.js +38 -0
- package/lib/transport.d.ts +25 -0
- package/lib/transport.js +58 -0
- package/lib/trim-slashes.d.ts +4 -0
- package/lib/trim-slashes.js +14 -0
- package/package.json +124 -3
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import type { LayoutSection, PageData } from "./shapes.js";
|
|
2
|
+
/**
|
|
3
|
+
* Between a site's content files and OpenHI's `Page` resource.
|
|
4
|
+
*
|
|
5
|
+
* The two are already almost the same thing: `src/content/pages/*.json` are
|
|
6
|
+
* `resourceType: "Page"` documents whose `layout` names a component and
|
|
7
|
+
* carries its data. What OpenHI serves is the same record with the layout
|
|
8
|
+
* expressed as `ContentBlock`, which is the shape Studio edits.
|
|
9
|
+
*
|
|
10
|
+
* So this is a translation, not an import. Nothing about the site's
|
|
11
|
+
* rendering changes: it still switches on a component name and receives
|
|
12
|
+
* the same `data` object it does from git.
|
|
13
|
+
*
|
|
14
|
+
* The rule for `data` is mechanical, which is what keeps it lossless: a key
|
|
15
|
+
* whose name is a `ContentBlock` member (`title`) becomes that member;
|
|
16
|
+
* everything else lives on `instance.property`, under its own name. No
|
|
17
|
+
* per-block table to keep honest, and a block that wants its body text in
|
|
18
|
+
* `ContentBlock.content` only has to call the field `content`.
|
|
19
|
+
*/
|
|
20
|
+
export declare const BLOCK_TYPE_SYSTEM = "https://hl7.openhi.org/fhir/CodeSystem/block-type";
|
|
21
|
+
interface Coding {
|
|
22
|
+
readonly system?: string;
|
|
23
|
+
readonly code?: string;
|
|
24
|
+
}
|
|
25
|
+
/** A link a block carries, as Studio writes it. */
|
|
26
|
+
export interface BlockLink {
|
|
27
|
+
readonly label?: string;
|
|
28
|
+
readonly url: string;
|
|
29
|
+
}
|
|
30
|
+
export interface ContentBlock {
|
|
31
|
+
readonly identifier?: {
|
|
32
|
+
readonly value?: string;
|
|
33
|
+
};
|
|
34
|
+
readonly component: {
|
|
35
|
+
readonly coding?: readonly Coding[];
|
|
36
|
+
};
|
|
37
|
+
readonly title?: string;
|
|
38
|
+
readonly content?: string;
|
|
39
|
+
readonly link?: readonly BlockLink[];
|
|
40
|
+
readonly instance?: {
|
|
41
|
+
readonly key?: string;
|
|
42
|
+
readonly property?: Record<string, unknown>;
|
|
43
|
+
};
|
|
44
|
+
readonly block?: readonly ContentBlock[];
|
|
45
|
+
}
|
|
46
|
+
export interface OpenhiPage {
|
|
47
|
+
readonly resourceType: "Page";
|
|
48
|
+
readonly id?: string;
|
|
49
|
+
readonly url: string;
|
|
50
|
+
readonly title: string;
|
|
51
|
+
readonly status: string;
|
|
52
|
+
readonly description?: string;
|
|
53
|
+
readonly meta?: {
|
|
54
|
+
readonly lastUpdated?: string;
|
|
55
|
+
};
|
|
56
|
+
readonly seo?: Record<string, unknown>;
|
|
57
|
+
readonly block?: readonly ContentBlock[];
|
|
58
|
+
}
|
|
59
|
+
/** The block's code, preferring ours when it carries several codings. */
|
|
60
|
+
export declare function codeOfBlock(block: ContentBlock): string;
|
|
61
|
+
/** One `ContentBlock` as the section a site renders. */
|
|
62
|
+
export declare function sectionFromBlock(block: ContentBlock): LayoutSection;
|
|
63
|
+
/** One section as the `ContentBlock` OpenHI stores. */
|
|
64
|
+
export declare function blockFromSection(section: LayoutSection,
|
|
65
|
+
/** The code system the section's code belongs to. @default the standard catalogue */
|
|
66
|
+
system?: string): ContentBlock;
|
|
67
|
+
/**
|
|
68
|
+
* Flatten a surface's block tree into the section list a site renders.
|
|
69
|
+
*
|
|
70
|
+
* Studio saves a page as one container with the sections inside it, so the
|
|
71
|
+
* top level is usually a single grid. Anything that carries children is
|
|
72
|
+
* descended into; anything that does not is a section.
|
|
73
|
+
*/
|
|
74
|
+
export declare function sectionsFromBlocks(blocks: readonly ContentBlock[] | undefined): LayoutSection[];
|
|
75
|
+
/**
|
|
76
|
+
* An OpenHI `Page` as the site's page data.
|
|
77
|
+
*
|
|
78
|
+
* `status` narrows: OpenHI publishes the FHIR set, and a site only
|
|
79
|
+
* distinguishes what it renders from what it does not. Anything that is not
|
|
80
|
+
* `active` is inactive here, so a draft page in Studio does not appear on
|
|
81
|
+
* the live site by accident.
|
|
82
|
+
*/
|
|
83
|
+
export declare function pageFromResource(resource: OpenhiPage): PageData;
|
|
84
|
+
/** The site's page data as the `Page` OpenHI stores. */
|
|
85
|
+
export declare function resourceFromPage(page: PageData,
|
|
86
|
+
/** The site's declared block codes: a section using one is coded under its system. */
|
|
87
|
+
blocks?: {
|
|
88
|
+
readonly system: string;
|
|
89
|
+
readonly codes: ReadonlySet<string>;
|
|
90
|
+
}): OpenhiPage;
|
|
91
|
+
export {};
|
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
import { trimSlashes } from "../trim-slashes.js";
|
|
2
|
+
/**
|
|
3
|
+
* Between a site's content files and OpenHI's `Page` resource.
|
|
4
|
+
*
|
|
5
|
+
* The two are already almost the same thing: `src/content/pages/*.json` are
|
|
6
|
+
* `resourceType: "Page"` documents whose `layout` names a component and
|
|
7
|
+
* carries its data. What OpenHI serves is the same record with the layout
|
|
8
|
+
* expressed as `ContentBlock`, which is the shape Studio edits.
|
|
9
|
+
*
|
|
10
|
+
* So this is a translation, not an import. Nothing about the site's
|
|
11
|
+
* rendering changes: it still switches on a component name and receives
|
|
12
|
+
* the same `data` object it does from git.
|
|
13
|
+
*
|
|
14
|
+
* The rule for `data` is mechanical, which is what keeps it lossless: a key
|
|
15
|
+
* whose name is a `ContentBlock` member (`title`) becomes that member;
|
|
16
|
+
* everything else lives on `instance.property`, under its own name. No
|
|
17
|
+
* per-block table to keep honest, and a block that wants its body text in
|
|
18
|
+
* `ContentBlock.content` only has to call the field `content`.
|
|
19
|
+
*/
|
|
20
|
+
export const BLOCK_TYPE_SYSTEM = "https://hl7.openhi.org/fhir/CodeSystem/block-type";
|
|
21
|
+
/** Names the editor's grid has taken on `instance.property`. */
|
|
22
|
+
const GEOMETRY = new Set(["col", "row", "w", "h"]);
|
|
23
|
+
/** The block's code, preferring ours when it carries several codings. */
|
|
24
|
+
export function codeOfBlock(block) {
|
|
25
|
+
const coding = block.component.coding ?? [];
|
|
26
|
+
const match = coding.find((entry) => entry.system === BLOCK_TYPE_SYSTEM) ?? coding[0];
|
|
27
|
+
return match?.code ?? "";
|
|
28
|
+
}
|
|
29
|
+
/** One `ContentBlock` as the section a site renders. */
|
|
30
|
+
export function sectionFromBlock(block) {
|
|
31
|
+
const property = block.instance?.property ?? {};
|
|
32
|
+
const data = {};
|
|
33
|
+
const geometry = {};
|
|
34
|
+
for (const [name, value] of Object.entries(property)) {
|
|
35
|
+
// Where a block sits on Studio's canvas is Studio's business, but it is
|
|
36
|
+
// carried beside the data so a push gives it back rather than resetting it.
|
|
37
|
+
if (GEOMETRY.has(name))
|
|
38
|
+
geometry[name] = value;
|
|
39
|
+
else
|
|
40
|
+
data[name] = value;
|
|
41
|
+
}
|
|
42
|
+
if (block.title !== undefined)
|
|
43
|
+
data.title = block.title;
|
|
44
|
+
if (block.content !== undefined)
|
|
45
|
+
data.content = block.content;
|
|
46
|
+
// Studio's Link field. It was dropped here, so a link set on a block in
|
|
47
|
+
// Studio never reached a component that could draw it. Carried as the
|
|
48
|
+
// list it is, under the name `ContentBlock` gives it.
|
|
49
|
+
if (block.link !== undefined && block.link.length > 0)
|
|
50
|
+
data.link = block.link;
|
|
51
|
+
const id = block.identifier?.value ?? "";
|
|
52
|
+
return {
|
|
53
|
+
id,
|
|
54
|
+
identifier: id,
|
|
55
|
+
component: codeOfBlock(block),
|
|
56
|
+
data,
|
|
57
|
+
...(Object.keys(geometry).length > 0 && { geometry }),
|
|
58
|
+
};
|
|
59
|
+
}
|
|
60
|
+
/** One section as the `ContentBlock` OpenHI stores. */
|
|
61
|
+
export function blockFromSection(section,
|
|
62
|
+
/** The code system the section's code belongs to. @default the standard catalogue */
|
|
63
|
+
system = BLOCK_TYPE_SYSTEM) {
|
|
64
|
+
const property = { ...section.geometry };
|
|
65
|
+
let title;
|
|
66
|
+
let content;
|
|
67
|
+
let link;
|
|
68
|
+
for (const [name, value] of Object.entries(section.data)) {
|
|
69
|
+
if (name === "title" && typeof value === "string")
|
|
70
|
+
title = value;
|
|
71
|
+
else if (name === "content" && typeof value === "string")
|
|
72
|
+
content = value;
|
|
73
|
+
else if (name === "link" && linksOf(value) !== undefined)
|
|
74
|
+
link = linksOf(value);
|
|
75
|
+
else
|
|
76
|
+
property[name] = value;
|
|
77
|
+
}
|
|
78
|
+
const id = section.identifier || section.id;
|
|
79
|
+
return {
|
|
80
|
+
identifier: { value: id },
|
|
81
|
+
component: {
|
|
82
|
+
coding: [{ system, code: section.component }],
|
|
83
|
+
},
|
|
84
|
+
...(title !== undefined && { title }),
|
|
85
|
+
...(content !== undefined && { content }),
|
|
86
|
+
...(link !== undefined && { link }),
|
|
87
|
+
instance: {
|
|
88
|
+
key: section.component,
|
|
89
|
+
...(Object.keys(property).length > 0 && { property }),
|
|
90
|
+
},
|
|
91
|
+
};
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* A `link` value as `ContentBlock.link`, when it is one.
|
|
95
|
+
*
|
|
96
|
+
* Anything else under that name stays where it was, on `instance.property`:
|
|
97
|
+
* a section of a site's that happens to call a field `link` and means
|
|
98
|
+
* something else by it should not be rewritten into a shape it is not.
|
|
99
|
+
*/
|
|
100
|
+
function linksOf(value) {
|
|
101
|
+
if (!Array.isArray(value) || value.length === 0)
|
|
102
|
+
return undefined;
|
|
103
|
+
const links = [];
|
|
104
|
+
for (const one of value) {
|
|
105
|
+
if (typeof one !== "object" || one === null)
|
|
106
|
+
return undefined;
|
|
107
|
+
const { url, label } = one;
|
|
108
|
+
if (typeof url !== "string")
|
|
109
|
+
return undefined;
|
|
110
|
+
links.push({ url, ...(typeof label === "string" && { label }) });
|
|
111
|
+
}
|
|
112
|
+
return links;
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* Flatten a surface's block tree into the section list a site renders.
|
|
116
|
+
*
|
|
117
|
+
* Studio saves a page as one container with the sections inside it, so the
|
|
118
|
+
* top level is usually a single grid. Anything that carries children is
|
|
119
|
+
* descended into; anything that does not is a section.
|
|
120
|
+
*/
|
|
121
|
+
export function sectionsFromBlocks(blocks) {
|
|
122
|
+
const sections = [];
|
|
123
|
+
const visit = (nodes) => {
|
|
124
|
+
for (const node of nodes) {
|
|
125
|
+
if (node.block !== undefined && node.block.length > 0)
|
|
126
|
+
visit(node.block);
|
|
127
|
+
else
|
|
128
|
+
sections.push(sectionFromBlock(node));
|
|
129
|
+
}
|
|
130
|
+
};
|
|
131
|
+
visit(blocks ?? []);
|
|
132
|
+
return sections;
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* SEO field names, the site's on the left and `ContentSeo`'s on the right.
|
|
136
|
+
*
|
|
137
|
+
* Anything not named here is carried through under its own name rather than
|
|
138
|
+
* dropped. `ogImage` is a plain URL and `ContentSeo.image` is a reference to
|
|
139
|
+
* a `Media` record, so they are not the same field and pretending otherwise
|
|
140
|
+
* would put a URL where a reference belongs.
|
|
141
|
+
*
|
|
142
|
+
* Enumerating what to keep is how `seo.noindex` went missing the first time
|
|
143
|
+
* this was written. Carrying the remainder makes the mapping lossless by
|
|
144
|
+
* construction instead of by remembering.
|
|
145
|
+
*/
|
|
146
|
+
const SEO_NAMES = [
|
|
147
|
+
["metaTitle", "title"],
|
|
148
|
+
["metaDescription", "description"],
|
|
149
|
+
["ogImageRef", "image"],
|
|
150
|
+
["ogImageAlt", "imageAlt"],
|
|
151
|
+
["noindex", "noIndex"],
|
|
152
|
+
];
|
|
153
|
+
function rename(source, pairs) {
|
|
154
|
+
if (source === undefined)
|
|
155
|
+
return undefined;
|
|
156
|
+
const from = new Map(pairs);
|
|
157
|
+
const out = {};
|
|
158
|
+
for (const [name, value] of Object.entries(source)) {
|
|
159
|
+
if (value === undefined)
|
|
160
|
+
continue;
|
|
161
|
+
out[from.get(name) ?? name] = value;
|
|
162
|
+
}
|
|
163
|
+
return Object.keys(out).length === 0 ? undefined : out;
|
|
164
|
+
}
|
|
165
|
+
const flip = (pairs) => pairs.map(([a, b]) => [b, a]);
|
|
166
|
+
/** `/about` from a permalink, and `about` as the slug beneath it. */
|
|
167
|
+
function slugOf(url) {
|
|
168
|
+
const trimmed = trimSlashes(url);
|
|
169
|
+
return trimmed.length === 0 ? "home" : trimmed;
|
|
170
|
+
}
|
|
171
|
+
/**
|
|
172
|
+
* An OpenHI `Page` as the site's page data.
|
|
173
|
+
*
|
|
174
|
+
* `status` narrows: OpenHI publishes the FHIR set, and a site only
|
|
175
|
+
* distinguishes what it renders from what it does not. Anything that is not
|
|
176
|
+
* `active` is inactive here, so a draft page in Studio does not appear on
|
|
177
|
+
* the live site by accident.
|
|
178
|
+
*/
|
|
179
|
+
export function pageFromResource(resource) {
|
|
180
|
+
const seo = rename(resource.seo, flip(SEO_NAMES));
|
|
181
|
+
return {
|
|
182
|
+
resourceType: "Page",
|
|
183
|
+
id: resource.id ?? slugOf(resource.url),
|
|
184
|
+
status: resource.status === "active" ? "active" : "inactive",
|
|
185
|
+
title: resource.title,
|
|
186
|
+
slug: slugOf(resource.url),
|
|
187
|
+
permalink: resource.url,
|
|
188
|
+
// Derived rather than stored: the field says "is this the front page",
|
|
189
|
+
// which the address already says. Storing it as well would let the two
|
|
190
|
+
// disagree, and a `shell` on a FHIR `Page` would be the site's private
|
|
191
|
+
// field on a shared record. The test pins the invariant so a page that
|
|
192
|
+
// ever needs to break it fails loudly instead of losing the value.
|
|
193
|
+
shell: resource.url === "/" ? "home" : "page",
|
|
194
|
+
...(resource.description !== undefined && { intro: resource.description }),
|
|
195
|
+
...(resource.meta?.lastUpdated !== undefined && {
|
|
196
|
+
meta: { lastUpdated: resource.meta.lastUpdated },
|
|
197
|
+
}),
|
|
198
|
+
...(seo !== undefined && { seo }),
|
|
199
|
+
layout: sectionsFromBlocks(resource.block),
|
|
200
|
+
};
|
|
201
|
+
}
|
|
202
|
+
/** The site's page data as the `Page` OpenHI stores. */
|
|
203
|
+
export function resourceFromPage(page,
|
|
204
|
+
/** The site's declared block codes: a section using one is coded under its system. */
|
|
205
|
+
blocks) {
|
|
206
|
+
const seo = rename(page.seo, SEO_NAMES);
|
|
207
|
+
return {
|
|
208
|
+
resourceType: "Page",
|
|
209
|
+
id: page.id,
|
|
210
|
+
url: page.permalink,
|
|
211
|
+
title: page.title,
|
|
212
|
+
status: page.status === "active" ? "active" : "retired",
|
|
213
|
+
...(page.intro !== undefined && { description: page.intro }),
|
|
214
|
+
...(page.meta?.lastUpdated !== undefined && {
|
|
215
|
+
meta: { lastUpdated: page.meta.lastUpdated },
|
|
216
|
+
}),
|
|
217
|
+
...(seo !== undefined && { seo }),
|
|
218
|
+
block: page.layout.map((section) => blockFromSection(section, blocks?.codes.has(section.component)
|
|
219
|
+
? blocks.system
|
|
220
|
+
: BLOCK_TYPE_SYSTEM)),
|
|
221
|
+
};
|
|
222
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Clean a fragment of author-written HTML before it is rendered.
|
|
3
|
+
*
|
|
4
|
+
* These fields reach the page through `set:html`, which is unescaped by
|
|
5
|
+
* definition — so whatever is in them runs. That was fine while the only
|
|
6
|
+
* way to change them was a commit somebody reviewed. It stopped being
|
|
7
|
+
* fine the moment the content came from the API: anyone who can edit a
|
|
8
|
+
* page in the CMS could otherwise put a script tag in a headline and
|
|
9
|
+
* have it run for every visitor.
|
|
10
|
+
*
|
|
11
|
+
* The allowlist is inline formatting and nothing else. A headline wants
|
|
12
|
+
* emphasis and a line break; it does not want an iframe, a form, an
|
|
13
|
+
* event handler or a style attribute, and a heading that renders a
|
|
14
|
+
* `<script>` is not a formatting choice anybody made on purpose.
|
|
15
|
+
*
|
|
16
|
+
* `class` is allowed because that is how a site's emphasis is styled
|
|
17
|
+
* — `<em class="font-heading italic">` — and a class cannot execute
|
|
18
|
+
* anything. `style` is not: it can load a URL, and
|
|
19
|
+
* the classes cover the cases content actually has.
|
|
20
|
+
*
|
|
21
|
+
* Applied at the point of rendering rather than the point of storage.
|
|
22
|
+
* Storage is not the only way in — the API is — so cleaning on write
|
|
23
|
+
* would protect only the content Studio happens to have touched.
|
|
24
|
+
*/
|
|
25
|
+
export declare function sanitiseHtml(html: string | undefined): string;
|
|
26
|
+
/**
|
|
27
|
+
* Serialise a value for a `<script type="application/ld+json">` block.
|
|
28
|
+
*
|
|
29
|
+
* `JSON.stringify` alone is not enough inside a script element. JSON
|
|
30
|
+
* happily contains `</script>`, and a browser ends the script at the
|
|
31
|
+
* first one it sees in the source — so a string carrying that sequence
|
|
32
|
+
* closes the block early and everything after it is parsed as HTML.
|
|
33
|
+
* Escaping `<` as `\u003c` keeps the JSON identical to a parser and
|
|
34
|
+
* inert to the tokeniser.
|
|
35
|
+
*/
|
|
36
|
+
export declare function jsonLdScript(value: unknown): string;
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
import sanitizeHtml from "sanitize-html";
|
|
2
|
+
/**
|
|
3
|
+
* Clean a fragment of author-written HTML before it is rendered.
|
|
4
|
+
*
|
|
5
|
+
* These fields reach the page through `set:html`, which is unescaped by
|
|
6
|
+
* definition — so whatever is in them runs. That was fine while the only
|
|
7
|
+
* way to change them was a commit somebody reviewed. It stopped being
|
|
8
|
+
* fine the moment the content came from the API: anyone who can edit a
|
|
9
|
+
* page in the CMS could otherwise put a script tag in a headline and
|
|
10
|
+
* have it run for every visitor.
|
|
11
|
+
*
|
|
12
|
+
* The allowlist is inline formatting and nothing else. A headline wants
|
|
13
|
+
* emphasis and a line break; it does not want an iframe, a form, an
|
|
14
|
+
* event handler or a style attribute, and a heading that renders a
|
|
15
|
+
* `<script>` is not a formatting choice anybody made on purpose.
|
|
16
|
+
*
|
|
17
|
+
* `class` is allowed because that is how a site's emphasis is styled
|
|
18
|
+
* — `<em class="font-heading italic">` — and a class cannot execute
|
|
19
|
+
* anything. `style` is not: it can load a URL, and
|
|
20
|
+
* the classes cover the cases content actually has.
|
|
21
|
+
*
|
|
22
|
+
* Applied at the point of rendering rather than the point of storage.
|
|
23
|
+
* Storage is not the only way in — the API is — so cleaning on write
|
|
24
|
+
* would protect only the content Studio happens to have touched.
|
|
25
|
+
*/
|
|
26
|
+
export function sanitiseHtml(html) {
|
|
27
|
+
if (html === undefined || html.length === 0)
|
|
28
|
+
return "";
|
|
29
|
+
return sanitizeHtml(html, {
|
|
30
|
+
allowedTags: [
|
|
31
|
+
"a",
|
|
32
|
+
"abbr",
|
|
33
|
+
"b",
|
|
34
|
+
"br",
|
|
35
|
+
"code",
|
|
36
|
+
"em",
|
|
37
|
+
"i",
|
|
38
|
+
"s",
|
|
39
|
+
"small",
|
|
40
|
+
"span",
|
|
41
|
+
"strong",
|
|
42
|
+
"sub",
|
|
43
|
+
"sup",
|
|
44
|
+
"u",
|
|
45
|
+
// Prose sections are whole documents, not one line.
|
|
46
|
+
"blockquote",
|
|
47
|
+
"h2",
|
|
48
|
+
"h3",
|
|
49
|
+
"h4",
|
|
50
|
+
"hr",
|
|
51
|
+
"li",
|
|
52
|
+
"ol",
|
|
53
|
+
"p",
|
|
54
|
+
"ul",
|
|
55
|
+
],
|
|
56
|
+
allowedAttributes: {
|
|
57
|
+
"*": ["class"],
|
|
58
|
+
a: ["href", "title", "rel", "target"],
|
|
59
|
+
abbr: ["title"],
|
|
60
|
+
},
|
|
61
|
+
// No `data:` and no `javascript:`. A link an author typed is a link
|
|
62
|
+
// to somewhere, not a way to run something.
|
|
63
|
+
allowedSchemes: ["http", "https", "mailto", "tel"],
|
|
64
|
+
allowedSchemesAppliedToAttributes: ["href"],
|
|
65
|
+
// A link that leaves the site should not hand it the opener.
|
|
66
|
+
transformTags: {
|
|
67
|
+
a: (tagName, attribs) => ({
|
|
68
|
+
tagName,
|
|
69
|
+
attribs: {
|
|
70
|
+
...attribs,
|
|
71
|
+
...(attribs.target === "_blank" && {
|
|
72
|
+
rel: "noopener noreferrer",
|
|
73
|
+
}),
|
|
74
|
+
},
|
|
75
|
+
}),
|
|
76
|
+
},
|
|
77
|
+
disallowedTagsMode: "discard",
|
|
78
|
+
});
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Serialise a value for a `<script type="application/ld+json">` block.
|
|
82
|
+
*
|
|
83
|
+
* `JSON.stringify` alone is not enough inside a script element. JSON
|
|
84
|
+
* happily contains `</script>`, and a browser ends the script at the
|
|
85
|
+
* first one it sees in the source — so a string carrying that sequence
|
|
86
|
+
* closes the block early and everything after it is parsed as HTML.
|
|
87
|
+
* Escaping `<` as `\u003c` keeps the JSON identical to a parser and
|
|
88
|
+
* inert to the tokeniser.
|
|
89
|
+
*/
|
|
90
|
+
export function jsonLdScript(value) {
|
|
91
|
+
return JSON.stringify(value).replace(/</g, "\\u003c");
|
|
92
|
+
}
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import { type ContentBlock } from "./page.js";
|
|
2
|
+
import type { SectionData } from "./types.js";
|
|
3
|
+
/**
|
|
4
|
+
* Between a site's `src/content/sections/*.json` and OpenHI's `Section`.
|
|
5
|
+
*
|
|
6
|
+
* Navigation and a footer are sections of a site rather than pages of one,
|
|
7
|
+
* and `Section` is the resource for them — it carries `url`, `name` and a
|
|
8
|
+
* block tree, and belongs to a website. No custom content type is needed
|
|
9
|
+
* and none should be invented: a tenant-defined type is for what the
|
|
10
|
+
* content plane has no resource for.
|
|
11
|
+
*
|
|
12
|
+
* The `data` mapping is the page's, deliberately. One block per section,
|
|
13
|
+
* `instance.key` naming the piece and the rest of `data` on
|
|
14
|
+
* `instance.property`, with `title` and `content` promoted to their own
|
|
15
|
+
* members. It is mechanical, so it round-trips exactly and needs no table
|
|
16
|
+
* of per-section rules to keep honest — the site has to render identically
|
|
17
|
+
* after an import, and a lossy mapping is how that stops being true.
|
|
18
|
+
*
|
|
19
|
+
* A richer mapping is possible later — a navigation is a list of links and
|
|
20
|
+
* `ContentBlock.link` exists — and can happen without the record changing
|
|
21
|
+
* identity, because a `Section` is addressed by `url` either way.
|
|
22
|
+
*/
|
|
23
|
+
export interface OpenhiSection {
|
|
24
|
+
readonly resourceType: "Section";
|
|
25
|
+
readonly id?: string;
|
|
26
|
+
readonly url: string;
|
|
27
|
+
readonly status: string;
|
|
28
|
+
readonly name?: string;
|
|
29
|
+
readonly title?: string;
|
|
30
|
+
readonly meta?: {
|
|
31
|
+
readonly lastUpdated?: string;
|
|
32
|
+
};
|
|
33
|
+
readonly block?: readonly ContentBlock[];
|
|
34
|
+
readonly website?: {
|
|
35
|
+
readonly reference?: string;
|
|
36
|
+
readonly type?: string;
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Where a section lives.
|
|
41
|
+
*
|
|
42
|
+
* `Section.url` is required and is the identity an import matches on, the
|
|
43
|
+
* same way a page is "the one at /about". A section is not served at a path
|
|
44
|
+
* of its own, so it gets a stable internal one rather than a guess at a
|
|
45
|
+
* public address.
|
|
46
|
+
*/
|
|
47
|
+
export declare function sectionUrl(slug: string): string;
|
|
48
|
+
/** One local section file as the `Section` OpenHI stores. */
|
|
49
|
+
export declare function resourceFromSection(section: SectionData): OpenhiSection;
|
|
50
|
+
/**
|
|
51
|
+
* One stored `Section` as the local shape the site renders.
|
|
52
|
+
*
|
|
53
|
+
* `status` narrows the way a page's does, and for the same reason. This
|
|
54
|
+
* asked whether the status was `inactive` and called everything else
|
|
55
|
+
* active — so a `draft` or `retired` Section, which is what Studio
|
|
56
|
+
* writes for unpublished work, arrived on the site looking live. The
|
|
57
|
+
* allowlist is the safe direction: what is not `active` is not
|
|
58
|
+
* published here.
|
|
59
|
+
*/
|
|
60
|
+
export declare function sectionFromResource(resource: OpenhiSection): SectionData;
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import { blockFromSection, sectionFromBlock, } from "./page.js";
|
|
2
|
+
/**
|
|
3
|
+
* Where a section lives.
|
|
4
|
+
*
|
|
5
|
+
* `Section.url` is required and is the identity an import matches on, the
|
|
6
|
+
* same way a page is "the one at /about". A section is not served at a path
|
|
7
|
+
* of its own, so it gets a stable internal one rather than a guess at a
|
|
8
|
+
* public address.
|
|
9
|
+
*/
|
|
10
|
+
export function sectionUrl(slug) {
|
|
11
|
+
return `/sections/${slug}`;
|
|
12
|
+
}
|
|
13
|
+
/** One local section file as the `Section` OpenHI stores. */
|
|
14
|
+
export function resourceFromSection(section) {
|
|
15
|
+
return {
|
|
16
|
+
resourceType: "Section",
|
|
17
|
+
url: sectionUrl(section.slug),
|
|
18
|
+
// As a page does. `inactive` is the site's word for "not published";
|
|
19
|
+
// OpenHI takes the FHIR set, where that is `retired`. Passing the
|
|
20
|
+
// local word through stored a status the API does not define.
|
|
21
|
+
status: section.status === "active" ? "active" : "retired",
|
|
22
|
+
name: section.slug,
|
|
23
|
+
...(section.meta?.lastUpdated !== undefined && {
|
|
24
|
+
meta: { lastUpdated: section.meta.lastUpdated },
|
|
25
|
+
}),
|
|
26
|
+
block: [
|
|
27
|
+
blockFromSection({
|
|
28
|
+
id: section.slug,
|
|
29
|
+
identifier: section.slug,
|
|
30
|
+
component: section.slug,
|
|
31
|
+
data: section.data,
|
|
32
|
+
}),
|
|
33
|
+
],
|
|
34
|
+
};
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* One stored `Section` as the local shape the site renders.
|
|
38
|
+
*
|
|
39
|
+
* `status` narrows the way a page's does, and for the same reason. This
|
|
40
|
+
* asked whether the status was `inactive` and called everything else
|
|
41
|
+
* active — so a `draft` or `retired` Section, which is what Studio
|
|
42
|
+
* writes for unpublished work, arrived on the site looking live. The
|
|
43
|
+
* allowlist is the safe direction: what is not `active` is not
|
|
44
|
+
* published here.
|
|
45
|
+
*/
|
|
46
|
+
export function sectionFromResource(resource) {
|
|
47
|
+
const block = resource.block?.[0];
|
|
48
|
+
const slug = resource.name ?? "";
|
|
49
|
+
return {
|
|
50
|
+
resourceType: "Section",
|
|
51
|
+
id: slug,
|
|
52
|
+
status: resource.status === "active" ? "active" : "inactive",
|
|
53
|
+
slug,
|
|
54
|
+
data: block === undefined ? {} : sectionFromBlock(block).data,
|
|
55
|
+
...(resource.meta?.lastUpdated !== undefined && {
|
|
56
|
+
meta: { lastUpdated: resource.meta.lastUpdated },
|
|
57
|
+
}),
|
|
58
|
+
};
|
|
59
|
+
}
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The record shapes the browser entries read, written out by hand.
|
|
3
|
+
*
|
|
4
|
+
* `types.ts` derives its types from Zod schemas, and a declaration that names
|
|
5
|
+
* one of those would pull Zod's types into `@openhi/sdk/forms` and
|
|
6
|
+
* `@openhi/sdk/preview`. These are the same shapes without the schema library,
|
|
7
|
+
* and `types.ts` fails to compile if the two ever drift apart.
|
|
8
|
+
*/
|
|
9
|
+
/** FHIR-like Reference: points at another resource by type/id. */
|
|
10
|
+
export interface Reference {
|
|
11
|
+
reference: string;
|
|
12
|
+
display?: string | undefined;
|
|
13
|
+
type?: string | undefined;
|
|
14
|
+
}
|
|
15
|
+
/** FHIR-like `Resource.meta` subset used by content envelopes. */
|
|
16
|
+
export interface ResourceMeta {
|
|
17
|
+
versionId?: string | undefined;
|
|
18
|
+
lastUpdated?: string | undefined;
|
|
19
|
+
profile?: string[] | undefined;
|
|
20
|
+
}
|
|
21
|
+
/** What a site distinguishes: rendered or not. */
|
|
22
|
+
export type ResourceStatus = "active" | "inactive";
|
|
23
|
+
/** One block on a page, as the site renders it. */
|
|
24
|
+
export interface LayoutSection {
|
|
25
|
+
id: string;
|
|
26
|
+
identifier: string;
|
|
27
|
+
component: string;
|
|
28
|
+
data: Record<string, unknown>;
|
|
29
|
+
/** Where the block sits on Studio's canvas (`col`, `row`, `w`, `h`). */
|
|
30
|
+
geometry?: Record<string, unknown> | undefined;
|
|
31
|
+
}
|
|
32
|
+
export interface Seo {
|
|
33
|
+
metaTitle: string;
|
|
34
|
+
metaDescription: string;
|
|
35
|
+
ogImage?: string | undefined;
|
|
36
|
+
ogImageRef?: Reference | undefined;
|
|
37
|
+
ogImageAlt?: string | undefined;
|
|
38
|
+
noindex?: boolean | undefined;
|
|
39
|
+
}
|
|
40
|
+
export interface PageData {
|
|
41
|
+
resourceType: "Page";
|
|
42
|
+
id: string;
|
|
43
|
+
meta?: ResourceMeta | undefined;
|
|
44
|
+
status: ResourceStatus;
|
|
45
|
+
title: string;
|
|
46
|
+
intro?: string | undefined;
|
|
47
|
+
slug: string;
|
|
48
|
+
permalink: string;
|
|
49
|
+
shell: "home" | "page";
|
|
50
|
+
cover?: Reference | undefined;
|
|
51
|
+
seo?: Seo | undefined;
|
|
52
|
+
layout: LayoutSection[];
|
|
53
|
+
}
|
|
54
|
+
export interface FormItem {
|
|
55
|
+
linkId: string;
|
|
56
|
+
type: string;
|
|
57
|
+
text?: string;
|
|
58
|
+
required?: boolean;
|
|
59
|
+
repeats?: boolean;
|
|
60
|
+
helpText?: string;
|
|
61
|
+
maxLength?: number;
|
|
62
|
+
answerOption?: Array<{
|
|
63
|
+
value: string;
|
|
64
|
+
label?: string;
|
|
65
|
+
initialSelected?: boolean;
|
|
66
|
+
}>;
|
|
67
|
+
item?: FormItem[];
|
|
68
|
+
}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The record shapes the browser entries read, written out by hand.
|
|
3
|
+
*
|
|
4
|
+
* `types.ts` derives its types from Zod schemas, and a declaration that names
|
|
5
|
+
* one of those would pull Zod's types into `@openhi/sdk/forms` and
|
|
6
|
+
* `@openhi/sdk/preview`. These are the same shapes without the schema library,
|
|
7
|
+
* and `types.ts` fails to compile if the two ever drift apart.
|
|
8
|
+
*/
|
|
9
|
+
export {};
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A Theme as CSS variables, for a site that wants them.
|
|
3
|
+
*
|
|
4
|
+
* A theme holds an open list of tokens: `{ name, type, value, dark? }`.
|
|
5
|
+
* Each becomes `--<name>` on `:root` and, when it has a dark value, on the
|
|
6
|
+
* `.dark` selector (or the one asked for). A site that styles itself some
|
|
7
|
+
* other way never calls this.
|
|
8
|
+
*/
|
|
9
|
+
export interface ThemeToken {
|
|
10
|
+
readonly name: string;
|
|
11
|
+
readonly type?: string;
|
|
12
|
+
readonly value: string;
|
|
13
|
+
readonly dark?: string;
|
|
14
|
+
}
|
|
15
|
+
export interface ThemeLike {
|
|
16
|
+
readonly token?: readonly ThemeToken[];
|
|
17
|
+
}
|
|
18
|
+
export interface ThemeTokensOptions {
|
|
19
|
+
/** Selector the light values go on. @default ":root" */
|
|
20
|
+
readonly light?: string;
|
|
21
|
+
/** Selector the dark values go on. @default ".dark" */
|
|
22
|
+
readonly dark?: string;
|
|
23
|
+
}
|
|
24
|
+
/** The stylesheet text for a theme, or an empty string when it has no usable tokens. */
|
|
25
|
+
export declare function themeTokens(theme: ThemeLike | undefined, options?: ThemeTokensOptions): string;
|