@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.
Files changed (90) hide show
  1. package/LICENSE +19 -0
  2. package/README.md +205 -1
  3. package/astro/OpenhiPreview.astro +59 -0
  4. package/lib/api-base.d.ts +2 -0
  5. package/lib/api-base.js +22 -0
  6. package/lib/astro/index.d.ts +8 -0
  7. package/lib/astro/index.js +8 -0
  8. package/lib/astro/loaders.d.ts +131 -0
  9. package/lib/astro/loaders.js +318 -0
  10. package/lib/content/asset.d.ts +69 -0
  11. package/lib/content/asset.js +151 -0
  12. package/lib/content/blocks/catalogue.d.ts +11 -0
  13. package/lib/content/blocks/catalogue.js +71 -0
  14. package/lib/content/blocks/declare.d.ts +143 -0
  15. package/lib/content/blocks/declare.js +210 -0
  16. package/lib/content/blocks/index.d.ts +2 -0
  17. package/lib/content/blocks/index.js +2 -0
  18. package/lib/content/content-type.d.ts +52 -0
  19. package/lib/content/content-type.js +97 -0
  20. package/lib/content/import-plan.d.ts +56 -0
  21. package/lib/content/import-plan.js +71 -0
  22. package/lib/content/index.d.ts +14 -0
  23. package/lib/content/index.js +14 -0
  24. package/lib/content/page.d.ts +91 -0
  25. package/lib/content/page.js +222 -0
  26. package/lib/content/sanitise-html.d.ts +36 -0
  27. package/lib/content/sanitise-html.js +92 -0
  28. package/lib/content/section.d.ts +60 -0
  29. package/lib/content/section.js +59 -0
  30. package/lib/content/shapes.d.ts +68 -0
  31. package/lib/content/shapes.js +9 -0
  32. package/lib/content/theme.d.ts +25 -0
  33. package/lib/content/theme.js +54 -0
  34. package/lib/content/types.d.ts +142 -0
  35. package/lib/content/types.js +121 -0
  36. package/lib/errors.d.ts +25 -0
  37. package/lib/errors.js +25 -0
  38. package/lib/forms/index.d.ts +107 -0
  39. package/lib/forms/index.js +201 -0
  40. package/lib/index.d.ts +10 -0
  41. package/lib/index.js +9 -0
  42. package/lib/node/bin.d.ts +2 -0
  43. package/lib/node/bin.js +14 -0
  44. package/lib/node/cli/api.d.ts +24 -0
  45. package/lib/node/cli/api.js +62 -0
  46. package/lib/node/cli/check.d.ts +26 -0
  47. package/lib/node/cli/check.js +265 -0
  48. package/lib/node/cli/context.d.ts +37 -0
  49. package/lib/node/cli/context.js +55 -0
  50. package/lib/node/cli/env-check.d.ts +4 -0
  51. package/lib/node/cli/env-check.js +47 -0
  52. package/lib/node/cli/init.d.ts +2 -0
  53. package/lib/node/cli/init.js +171 -0
  54. package/lib/node/cli/load-blocks.d.ts +15 -0
  55. package/lib/node/cli/load-blocks.js +109 -0
  56. package/lib/node/cli/local-content.d.ts +47 -0
  57. package/lib/node/cli/local-content.js +126 -0
  58. package/lib/node/cli/main.d.ts +3 -0
  59. package/lib/node/cli/main.js +58 -0
  60. package/lib/node/cli/optional-tool.d.ts +8 -0
  61. package/lib/node/cli/optional-tool.js +26 -0
  62. package/lib/node/cli/pull.d.ts +2 -0
  63. package/lib/node/cli/pull.js +113 -0
  64. package/lib/node/cli/push.d.ts +6 -0
  65. package/lib/node/cli/push.js +227 -0
  66. package/lib/node/env.d.ts +34 -0
  67. package/lib/node/env.js +66 -0
  68. package/lib/node/index.d.ts +9 -0
  69. package/lib/node/index.js +8 -0
  70. package/lib/node/media.d.ts +56 -0
  71. package/lib/node/media.js +176 -0
  72. package/lib/node/read.d.ts +19 -0
  73. package/lib/node/read.js +55 -0
  74. package/lib/paging.d.ts +14 -0
  75. package/lib/paging.js +41 -0
  76. package/lib/preview/apply-draft.d.ts +42 -0
  77. package/lib/preview/apply-draft.js +185 -0
  78. package/lib/preview/index.d.ts +7 -0
  79. package/lib/preview/index.js +4 -0
  80. package/lib/preview/marks.d.ts +25 -0
  81. package/lib/preview/marks.js +17 -0
  82. package/lib/preview/runtime.d.ts +17 -0
  83. package/lib/preview/runtime.js +85 -0
  84. package/lib/preview/studio-origin.d.ts +3 -0
  85. package/lib/preview/studio-origin.js +38 -0
  86. package/lib/transport.d.ts +25 -0
  87. package/lib/transport.js +58 -0
  88. package/lib/trim-slashes.d.ts +4 -0
  89. package/lib/trim-slashes.js +14 -0
  90. 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;