@lvl99dotcom/edaha.md 0.1.0 → 0.2.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 (61) hide show
  1. package/LICENSE +183 -183
  2. package/README.md +7 -252
  3. package/dist/cli/index.d.ts +36 -6
  4. package/dist/cli/index.js +48 -9
  5. package/dist/embeds/blocks/index.d.ts +59 -0
  6. package/dist/embeds/blocks/index.js +103 -0
  7. package/dist/embeds/index.d.ts +122 -19
  8. package/dist/embeds/index.js +381 -41
  9. package/dist/embeds/types/index.d.ts +111 -8
  10. package/dist/generator/article/index.d.ts +52 -12
  11. package/dist/generator/article/index.js +94 -26
  12. package/dist/generator/build/index.d.ts +55 -23
  13. package/dist/generator/build/index.js +151 -81
  14. package/dist/generator/config/index.d.ts +45 -8
  15. package/dist/generator/config/index.js +152 -30
  16. package/dist/generator/configFile/index.d.ts +58 -0
  17. package/dist/generator/configFile/index.js +122 -0
  18. package/dist/generator/fields/index.d.ts +93 -0
  19. package/dist/generator/fields/index.js +186 -0
  20. package/dist/generator/format/index.d.ts +40 -0
  21. package/dist/generator/format/index.js +75 -0
  22. package/dist/generator/lists/index.d.ts +3 -3
  23. package/dist/generator/lists/index.js +9 -8
  24. package/dist/generator/markdown/index.d.ts +8 -3
  25. package/dist/generator/markdown/index.js +11 -4
  26. package/dist/generator/metadata/index.d.ts +150 -0
  27. package/dist/generator/metadata/index.js +361 -0
  28. package/dist/generator/metadataGroups/index.d.ts +45 -0
  29. package/dist/generator/metadataGroups/index.js +169 -0
  30. package/dist/generator/templates/index.d.ts +35 -3
  31. package/dist/generator/templates/index.js +72 -6
  32. package/dist/generator/types/index.d.ts +43 -18
  33. package/dist/generator/urls/index.d.ts +18 -8
  34. package/dist/generator/urls/index.js +22 -12
  35. package/dist/index.d.ts +5 -7
  36. package/dist/index.js +6 -7
  37. package/package.json +18 -47
  38. package/theme/static/{site.css → base.css} +132 -24
  39. package/theme/templates/article/list.njk +6 -6
  40. package/theme/templates/article/single.njk +13 -7
  41. package/theme/templates/layouts/html.njk +54 -32
  42. package/theme/templates/layouts/rssfeed.njk +7 -7
  43. package/theme/templates/page/home.njk +2 -7
  44. package/theme/templates/page/single.njk +2 -2
  45. package/dist/client/assets/index-BbKEbPS8.css +0 -1
  46. package/dist/client/assets/index-DtG7vi1d.js +0 -559
  47. package/dist/client/index.html +0 -13
  48. package/dist/editor/index.d.ts +0 -62
  49. package/dist/editor/index.js +0 -102
  50. package/dist/embeds/bandcamp/index.d.ts +0 -9
  51. package/dist/embeds/bandcamp/index.js +0 -28
  52. package/dist/embeds/youtube/index.d.ts +0 -17
  53. package/dist/embeds/youtube/index.js +0 -48
  54. package/dist/server/app/index.d.ts +0 -39
  55. package/dist/server/app/index.js +0 -138
  56. package/dist/server/convert/index.d.ts +0 -25
  57. package/dist/server/convert/index.js +0 -125
  58. package/dist/server/store/index.d.ts +0 -148
  59. package/dist/server/store/index.js +0 -411
  60. package/dist/server/types/index.d.ts +0 -76
  61. package/dist/server/types/index.js +0 -1
@@ -0,0 +1,361 @@
1
+ import { Ajv } from "ajv";
2
+ import { fullFormats } from "ajv-formats/dist/formats.js";
3
+ import { checkFieldExtensions, resolveFields } from "../fields/index.js";
4
+ import { isRelativeUrl } from "../format/index.js";
5
+ /** The kinds of field the editor can show for a metadata value (the key under `$edahaField` that configures it) */
6
+ export const FIELD_KINDS = [
7
+ "text",
8
+ "email",
9
+ "url",
10
+ "tel",
11
+ "color",
12
+ "date",
13
+ "time",
14
+ "datetime-local",
15
+ "number",
16
+ "range",
17
+ "textarea",
18
+ "select",
19
+ "checkbox",
20
+ "radio",
21
+ "file",
22
+ ];
23
+ /** The settings every article has, which custom metadata can't use as keys */
24
+ export const CORE_FIELDS = [
25
+ "type",
26
+ "status",
27
+ "date",
28
+ "title",
29
+ "template",
30
+ "author",
31
+ "excerpt",
32
+ "thumbnail",
33
+ "attachments",
34
+ "tags",
35
+ ];
36
+ /** Metadata keys: a letter or underscore, then letters, digits, underscores or hyphens */
37
+ const KEY = /^[A-Za-z_][\w-]*$/;
38
+ /** Check a value is a map (not a list), throwing an Error naming it if not */
39
+ const asMap = (value, what) => {
40
+ if (!value || typeof value !== "object" || Array.isArray(value))
41
+ throw new Error(`${what} must be a map of settings`);
42
+ return value;
43
+ };
44
+ /**
45
+ * The kind of field an `$edahaField` configures.
46
+ *
47
+ * @example
48
+ * fieldKind({ title: "Image", file: { accept: "image/*" } }); // "file"
49
+ */
50
+ export const fieldKind = (field) => FIELD_KINDS.find((kind) => kind in field);
51
+ /**
52
+ * Whether an `$edahaField` names a field kind (maps' and lists' may only set their group and labels).
53
+ *
54
+ * @example
55
+ * hasFieldKind({ group: "files" }); // false
56
+ */
57
+ export const hasFieldKind = (field) => Boolean(field &&
58
+ typeof field === "object" &&
59
+ FIELD_KINDS.some((kind) => kind in field));
60
+ /**
61
+ * A field kind's options, e.g. `{ accept: "image/*" }` for `{ file: { accept: "image/*" } }` (none for `true`).
62
+ */
63
+ export const fieldOptions = (field) => {
64
+ const options = field[fieldKind(field)];
65
+ return options && typeof options === "object"
66
+ ? options
67
+ : {};
68
+ };
69
+ /**
70
+ * Check a schema has editor fields: objects need properties, lists need items (or one field for the whole list), and
71
+ * every value has an `$edahaField` with exactly one field kind. Objects' and lists' own `$edahaField` may set only their
72
+ * group, labels and conditions. Default values and conditions are checked too (see checkFieldExtensions). Throws an Error naming the schema's path.
73
+ *
74
+ * @example
75
+ * checkFieldSchema({ type: "string", $edahaField: { text: true } }, "metadata.subtitle");
76
+ */
77
+ export const checkFieldSchema = (schema, path) => {
78
+ const fields = asMap(schema, `"${path}"`);
79
+ if (fields.$edahaField !== undefined)
80
+ checkFieldExtensions(asMap(fields.$edahaField, `"${path}.$edahaField"`), `"${path}.$edahaField"`);
81
+ if (fields.type === "object") {
82
+ if (Array.isArray(fields.properties))
83
+ throw new Error(`"${path}.properties" must be a map of each property's name to its schema, not a list (remove the "-"s and put each schema under its property's name)`);
84
+ const properties = asMap(fields.properties, `"${path}.properties"`);
85
+ for (const [name, property] of Object.entries(properties))
86
+ checkFieldSchema(property, `${path}.properties.${name}`);
87
+ return;
88
+ }
89
+ // A list is edited item by item, unless one field edits it all (e.g. a select with `multiple`)
90
+ if (fields.type === "array" && !hasFieldKind(fields.$edahaField)) {
91
+ // A list of schemas describes each item in turn; the editor needs one schema for every item
92
+ if (Array.isArray(fields.items))
93
+ throw new Error(`"${path}.items" must be one schema for every item, not a list (remove the "-" before it)`);
94
+ checkFieldSchema(fields.items, `${path}.items`);
95
+ return;
96
+ }
97
+ const field = asMap(fields.$edahaField, `"${path}.$edahaField"`);
98
+ const kinds = FIELD_KINDS.filter((kind) => kind in field);
99
+ if (kinds.length !== 1)
100
+ throw new Error(`"${path}.$edahaField" must have exactly one field kind (${FIELD_KINDS.join(", ")}), not ${kinds.length ? kinds.join(" and ") : "none"}`);
101
+ };
102
+ /**
103
+ * An ajv instance for metadata schemas: every error reported, formats like `uri` and `email` checked, and `$edahaField`
104
+ * allowed beside JSON Schema's own keywords.
105
+ */
106
+ export const createAjv = () => {
107
+ const ajv = new Ajv({ allErrors: true, strict: false, formats: fullFormats });
108
+ ajv.addKeyword({ keyword: "$edahaField", schemaType: "object" });
109
+ return ajv;
110
+ };
111
+ /**
112
+ * Read the config file's `metadata` setting: a map of keys to JSON Schemas with `$edahaField`s. Throws an Error if a
113
+ * key is a core field's name or isn't a usable name, or a schema has no editor fields or can't be compiled.
114
+ *
115
+ * @example
116
+ * parseMetadata({ featured: { type: "string", $edahaField: { file: { accept: "image/*" } } } });
117
+ */
118
+ export const parseMetadata = (value) => {
119
+ if (value === undefined || value === null)
120
+ return {};
121
+ const definitions = asMap(value, '"metadata"');
122
+ const ajv = createAjv();
123
+ for (const [key, schema] of Object.entries(definitions)) {
124
+ if (CORE_FIELDS.includes(key))
125
+ throw new Error(`"metadata.${key}" can't be used: "${key}" is a core setting of every article`);
126
+ if (!KEY.test(key))
127
+ throw new Error(`"metadata.${key}" must start with a letter or "_" and have only letters, digits, "_" and "-"`);
128
+ checkFieldSchema(schema, `metadata.${key}`);
129
+ try {
130
+ ajv.compile(schema);
131
+ }
132
+ catch (error) {
133
+ throw new Error(`"metadata.${key}" isn't a valid JSON Schema: ${error.message}`, { cause: error });
134
+ }
135
+ }
136
+ return definitions;
137
+ };
138
+ /**
139
+ * The custom metadata fields an article type uses: those its `metadata` setting lists, none for `false`, or all when
140
+ * it has none.
141
+ *
142
+ * @example
143
+ * typeMetadataKeys({ featured: {...}, images: {...} }, ["featured"]); // ["featured"]
144
+ */
145
+ export const typeMetadataKeys = (definitions, typeMetadata) => typeMetadata === undefined
146
+ ? Object.keys(definitions)
147
+ : typeMetadata === false
148
+ ? []
149
+ : typeMetadata;
150
+ /** JSON types in plain words, e.g. "a number" */
151
+ const TYPE_NAMES = {
152
+ string: "text",
153
+ number: "a number",
154
+ integer: "a whole number",
155
+ boolean: "yes or no",
156
+ array: "a list",
157
+ object: "a group of settings",
158
+ null: "empty",
159
+ };
160
+ /** Formats in plain words, e.g. "an email address" */
161
+ const FORMAT_NAMES = {
162
+ email: "an email address",
163
+ uri: "a full web address, e.g. https://example.com",
164
+ url: "a full web address, e.g. https://example.com",
165
+ "uri-reference": "a web address or path",
166
+ date: "a date, e.g. 2026-11-19",
167
+ time: "a time, e.g. 14:30:00",
168
+ "date-time": "a date and time, e.g. 2026-11-19T14:30:00Z",
169
+ hostname: "a host name, e.g. example.com",
170
+ ipv4: "an IPv4 address",
171
+ ipv6: "an IPv6 address",
172
+ uuid: "a UUID",
173
+ regex: "a regular expression",
174
+ };
175
+ /** "1 item" or "3 items" */
176
+ const plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
177
+ /** A value in a message: text in quotes, anything else as written */
178
+ const quote = (value) => typeof value === "string" ? `"${value}"` : JSON.stringify(value);
179
+ /**
180
+ * Say what is wrong with a value in plain words, from an ajv error, e.g. "must be at most 10" or "must be an email
181
+ * address". Errors this doesn't know keep ajv's message.
182
+ *
183
+ * @example
184
+ * plainMessage({ keyword: "maximum", params: { limit: 10 }, ... }); // "must be at most 10"
185
+ */
186
+ export const plainMessage = (error) => {
187
+ const params = error.params;
188
+ const limit = params.limit;
189
+ switch (error.keyword) {
190
+ case "type": {
191
+ const types = String(params.type).split(",");
192
+ // Schemas only compile with JSON's own types, which all have names
193
+ return `must be ${types.map((type) => TYPE_NAMES[type]).join(" or ")}`;
194
+ }
195
+ case "minimum":
196
+ return `must be at least ${limit}`;
197
+ case "maximum":
198
+ return `must be at most ${limit}`;
199
+ case "exclusiveMinimum":
200
+ return `must be more than ${limit}`;
201
+ case "exclusiveMaximum":
202
+ return `must be less than ${limit}`;
203
+ case "multipleOf":
204
+ return `must be a multiple of ${params.multipleOf}`;
205
+ case "minLength":
206
+ return limit === 1
207
+ ? "can't be empty"
208
+ : `must be at least ${plural(limit, "character")}`;
209
+ case "maxLength":
210
+ return `must be at most ${plural(limit, "character")}`;
211
+ case "pattern":
212
+ return "isn't in the right form";
213
+ case "format":
214
+ return `must be ${FORMAT_NAMES[params.format] ?? `a valid ${params.format}`}`;
215
+ case "enum":
216
+ return `must be one of ${params.allowedValues.map(quote).join(", ")}`;
217
+ case "const":
218
+ return `must be ${quote(params.allowedValue)}`;
219
+ case "required":
220
+ return "is required";
221
+ case "minItems":
222
+ return `must have at least ${plural(limit, "item")}`;
223
+ case "maxItems":
224
+ return `can have at most ${plural(limit, "item")}`;
225
+ case "uniqueItems":
226
+ return "can't have the same item twice";
227
+ case "additionalProperties":
228
+ return "isn't a known setting";
229
+ default:
230
+ // ajv always describes its errors
231
+ return error.message;
232
+ }
233
+ };
234
+ /**
235
+ * An ajv error as a problem with a value, in plain words (see `plainMessage`). A missing or unknown property is a
236
+ * problem with that property, so its field shows it.
237
+ */
238
+ const problem = (key, error) => {
239
+ const params = error.params;
240
+ const property = (params.missingProperty ?? params.additionalProperty);
241
+ return {
242
+ path: key + error.instancePath + (property ? `/${property}` : ""),
243
+ message: plainMessage(error),
244
+ level: "error",
245
+ };
246
+ };
247
+ /**
248
+ * Validates articles' custom metadata values against their schemas, compiling each schema once.
249
+ *
250
+ * @example
251
+ * const validator = new MetadataValidator(config.metadata);
252
+ * validator.validate("featured", 3); // [{ path: "featured", message: "must be string", level: "error" }]
253
+ */
254
+ export class MetadataValidator {
255
+ ajv = createAjv();
256
+ compiled = new Map();
257
+ /** The custom metadata fields' schemas, by key */
258
+ definitions;
259
+ constructor(definitions) {
260
+ this.definitions = definitions;
261
+ }
262
+ /** The problems with a value of a custom metadata field (none if it's valid) */
263
+ validate(key, value) {
264
+ let validate = this.compiled.get(key);
265
+ if (!validate) {
266
+ validate = this.ajv.compile(this.definitions[key]);
267
+ this.compiled.set(key, validate);
268
+ }
269
+ if (validate(value))
270
+ return [];
271
+ // A value that isn't valid always has errors
272
+ return validate.errors.map((error) => problem(key, error));
273
+ }
274
+ }
275
+ /**
276
+ * Read an article's custom metadata from its settings: fill in default values and leave out hidden fields' values (see
277
+ * resolveFields), validate the values of the fields its type uses, and warn about values of fields its type doesn't use
278
+ * and settings that aren't core or defined.
279
+ *
280
+ * @param typeLabel - the type's plural label, for warnings, e.g. "News"
281
+ *
282
+ * @example
283
+ * articleMetadata({ date, featured: "a.png", oops: 1 }, ["featured"], validator, "News");
284
+ * // { values: { featured: "a.png" }, problems: [{ path: "oops", message: "isn't a known setting", level: "warning" }] }
285
+ */
286
+ export const articleMetadata = (settings, keys, validator, typeLabel) => {
287
+ const given = {};
288
+ /** Settings that aren't used */
289
+ const problems = [];
290
+ for (const [key, value] of Object.entries(settings)) {
291
+ if (CORE_FIELDS.includes(key))
292
+ continue;
293
+ if (keys.includes(key))
294
+ given[key] = value;
295
+ else
296
+ problems.push({
297
+ path: key,
298
+ message: key in validator.definitions
299
+ ? `isn't used by ${typeLabel}`
300
+ : "isn't a known setting",
301
+ level: "warning",
302
+ });
303
+ }
304
+ const schemas = Object.fromEntries(keys.flatMap((key) => {
305
+ const schema = validator.definitions[key];
306
+ return schema ? [[key, schema]] : [];
307
+ }));
308
+ const { values } = resolveFields(schemas, given);
309
+ const errors = Object.entries(values).flatMap(([key, value]) => validator.validate(key, value));
310
+ return { values, problems: [...errors, ...problems] };
311
+ };
312
+ /**
313
+ * Make a value's file fields' relative file names into paths on the website (like `thumbnail`), following its
314
+ * schema's objects and lists.
315
+ *
316
+ * @example
317
+ * resolveFileFields({ $edahaField: { file: true } }, "photo.png", "/news/hello/"); // "/news/hello/photo.png"
318
+ */
319
+ export const resolveFileFields = (schema, value, articleUrl) => {
320
+ if (Array.isArray(value) && schema.items)
321
+ return value.map((item) => resolveFileFields(schema.items, item, articleUrl));
322
+ if (value && typeof value === "object" && schema.properties)
323
+ return Object.fromEntries(Object.entries(value).map(([name, item]) => {
324
+ const property = schema.properties?.[name];
325
+ return [
326
+ name,
327
+ property ? resolveFileFields(property, item, articleUrl) : item,
328
+ ];
329
+ }));
330
+ return typeof value === "string" &&
331
+ schema.$edahaField &&
332
+ "file" in schema.$edahaField &&
333
+ isRelativeUrl(value)
334
+ ? articleUrl + value
335
+ : value;
336
+ };
337
+ /**
338
+ * An article's custom metadata for templates (`article.meta`): its type's valid values, with file fields as paths on
339
+ * the website. Values with errors are left out.
340
+ */
341
+ export const templateMetadata = (metadata, definitions, articleUrl) => {
342
+ const invalid = new Set(metadata.problems
343
+ .filter((problem) => problem.level === "error")
344
+ .map((problem) => problem.path.split("/")[0]));
345
+ return Object.fromEntries(Object.entries(metadata.values)
346
+ .filter(([key]) => !invalid.has(key))
347
+ .map(([key, value]) => [
348
+ key,
349
+ resolveFileFields(definitions[key], value, articleUrl),
350
+ ]));
351
+ };
352
+ /** Check a map key is used only for keys listed, for the type's `metadata` setting */
353
+ export const parseTypeMetadata = (value, what) => {
354
+ if (value === undefined || value === null)
355
+ return undefined;
356
+ if (value === false)
357
+ return false;
358
+ if (!Array.isArray(value) || value.some((key) => typeof key !== "string"))
359
+ throw new Error(`${what} must be a list of metadata keys, or false for none`);
360
+ return value;
361
+ };
@@ -0,0 +1,45 @@
1
+ import type { MetadataDefinitions } from "../metadata/index.ts";
2
+ /** A group of settings in the editor, as the config file's `metadataGroups` defines it */
3
+ export interface MetadataGroupConfig {
4
+ /** The group's heading */
5
+ title: string;
6
+ /** Shown above the group's fields */
7
+ description?: string | undefined;
8
+ /** The group it comes after (by default, groups go at the end) */
9
+ after?: string | undefined;
10
+ /** Whether the group starts open. Default: false */
11
+ openedByDefault: boolean;
12
+ }
13
+ /** A group of settings in the editor: its heading, and its fields' keys in order */
14
+ export interface MetadataGroup {
15
+ key: string;
16
+ title: string;
17
+ description?: string | undefined;
18
+ openedByDefault: boolean;
19
+ /** Its core and custom fields' keys, in order ("uploaded" is the article folder's files) */
20
+ fields: string[];
21
+ }
22
+ /**
23
+ * The editor's own groups, in order, with their core settings. "slug" and "uploaded" (the files in the article's
24
+ * folder) aren't settings, but have their place too. Custom fields without a group go in "custom".
25
+ */
26
+ export declare const BUILT_IN_GROUPS: readonly MetadataGroup[];
27
+ /**
28
+ * Read the config file's `metadataGroups` setting: groups of settings for the editor, by key. Throws an Error if a key
29
+ * is a built-in group's or isn't usable, or a group's settings aren't valid.
30
+ *
31
+ * @example
32
+ * parseMetadataGroups({ seo: { title: "SEO", after: "info", openedByDefault: true } });
33
+ */
34
+ export declare const parseMetadataGroups: (value: unknown) => Record<string, MetadataGroupConfig>;
35
+ /**
36
+ * The editor's groups of settings in order, each with its fields in order: the built-in groups (and the custom groups,
37
+ * placed after the group they name or at the end), with every custom field in its group (after the field it names, or
38
+ * at the group's end). Throws an Error if a field's group doesn't exist, or a field or group names one to follow that
39
+ * isn't there.
40
+ *
41
+ * @example
42
+ * metadataLayout({ hero: { $edahaField: { group: { key: "files", after: "thumbnail" }, file: true } } }, {});
43
+ * // [..., { key: "files", fields: ["thumbnail", "hero", "attachments", "uploaded"], ... }, ...]
44
+ */
45
+ export declare const metadataLayout: (definitions: MetadataDefinitions, groups: Record<string, MetadataGroupConfig>) => MetadataGroup[];
@@ -0,0 +1,169 @@
1
+ /**
2
+ * The editor's own groups, in order, with their core settings. "slug" and "uploaded" (the files in the article's
3
+ * folder) aren't settings, but have their place too. Custom fields without a group go in "custom".
4
+ */
5
+ export const BUILT_IN_GROUPS = [
6
+ {
7
+ key: "info",
8
+ title: "Info",
9
+ openedByDefault: true,
10
+ fields: ["type", "status", "slug", "date", "author"],
11
+ },
12
+ {
13
+ key: "categorise",
14
+ title: "Categorise",
15
+ openedByDefault: false,
16
+ fields: ["tags"],
17
+ },
18
+ {
19
+ key: "customise",
20
+ title: "Customise",
21
+ openedByDefault: true,
22
+ fields: ["excerpt", "template"],
23
+ },
24
+ {
25
+ key: "files",
26
+ title: "Files",
27
+ openedByDefault: true,
28
+ fields: ["thumbnail", "attachments", "uploaded"],
29
+ },
30
+ { key: "custom", title: "Custom", openedByDefault: false, fields: [] },
31
+ ];
32
+ /** The settings a custom group can have */
33
+ const GROUP_KEYS = ["title", "description", "after", "openedByDefault"];
34
+ /** Group keys: a letter, then letters, digits, "_" or "-" */
35
+ const KEY = /^[A-Za-z][\w-]*$/;
36
+ /** Check a value is a map (not a list), throwing an Error naming it if not */
37
+ const asMap = (value, what) => {
38
+ if (!value || typeof value !== "object" || Array.isArray(value))
39
+ throw new Error(`${what} must be a map of settings`);
40
+ return value;
41
+ };
42
+ /** Read an optional text setting, throwing an Error naming it if it isn't text */
43
+ const optionalText = (value, what) => {
44
+ if (value === undefined || value === null)
45
+ return undefined;
46
+ if (typeof value !== "string" || !value.trim())
47
+ throw new Error(`${what} must be non-empty text`);
48
+ return value.trim();
49
+ };
50
+ /**
51
+ * Read the config file's `metadataGroups` setting: groups of settings for the editor, by key. Throws an Error if a key
52
+ * is a built-in group's or isn't usable, or a group's settings aren't valid.
53
+ *
54
+ * @example
55
+ * parseMetadataGroups({ seo: { title: "SEO", after: "info", openedByDefault: true } });
56
+ */
57
+ export const parseMetadataGroups = (value) => {
58
+ if (value === undefined || value === null)
59
+ return {};
60
+ const groups = asMap(value, '"metadataGroups"');
61
+ return Object.fromEntries(Object.entries(groups).map(([key, settings]) => {
62
+ const what = `"metadataGroups.${key}"`;
63
+ if (BUILT_IN_GROUPS.some((group) => group.key === key))
64
+ throw new Error(`${what} can't be used: "${key}" is a built-in group`);
65
+ if (!KEY.test(key))
66
+ throw new Error(`${what} must start with a letter and have only letters, digits, "_" and "-"`);
67
+ const fields = asMap(settings, what);
68
+ const unknown = Object.keys(fields).filter((name) => !GROUP_KEYS.includes(name));
69
+ if (unknown.length)
70
+ throw new Error(`${what} has unknown settings: ${unknown.map((name) => `"${name}"`).join(", ")}`);
71
+ const opened = fields.openedByDefault ?? false;
72
+ if (typeof opened !== "boolean")
73
+ throw new Error(`${what}.openedByDefault must be true or false`);
74
+ return [
75
+ key,
76
+ {
77
+ title: optionalText(fields.title, `${what}.title`) ??
78
+ fail(`${what}.title is required`),
79
+ description: optionalText(fields.description, `${what}.description`),
80
+ after: optionalText(fields.after, `${what}.after`),
81
+ openedByDefault: opened,
82
+ },
83
+ ];
84
+ }));
85
+ };
86
+ /** Throw an Error with a message */
87
+ const fail = (message) => {
88
+ throw new Error(message);
89
+ };
90
+ /**
91
+ * Where a custom field's `$edahaField.group` puts it: a group key, or `{ key, after }`. Fields without one go in
92
+ * "custom". Throws an Error naming the field if it isn't valid.
93
+ */
94
+ const fieldPlace = (name, group) => {
95
+ const what = `"metadata.${name}.$edahaField.group"`;
96
+ if (group === undefined || group === null)
97
+ return { key: "custom" };
98
+ if (typeof group === "string")
99
+ return { key: group };
100
+ const place = asMap(group, what);
101
+ return {
102
+ key: optionalText(place.key, `${what}.key`) ?? fail(`${what}.key is required`),
103
+ after: optionalText(place.after, `${what}.after`),
104
+ };
105
+ };
106
+ /**
107
+ * Put items in order: those without `after` in the order given, then each after the one it names. Throws an Error
108
+ * (from `missing`) for an item whose `after` names nothing in the list.
109
+ */
110
+ const placeAfter = (start, items, missing) => {
111
+ const order = [...start, ...items.filter((i) => !i.after).map((i) => i.name)];
112
+ let waiting = items.filter((i) => i.after);
113
+ // Each pass places the items whose `after` is already placed, until none are left or none can be
114
+ while (waiting.length) {
115
+ const ready = waiting.filter((i) => order.includes(i.after));
116
+ if (!ready.length) {
117
+ const [first] = waiting;
118
+ throw new Error(missing(first.name, first.after));
119
+ }
120
+ for (const { name, after } of ready)
121
+ order.splice(order.indexOf(after) + 1, 0, name);
122
+ waiting = waiting.filter((i) => !ready.includes(i));
123
+ }
124
+ return order;
125
+ };
126
+ /**
127
+ * The editor's groups of settings in order, each with its fields in order: the built-in groups (and the custom groups,
128
+ * placed after the group they name or at the end), with every custom field in its group (after the field it names, or
129
+ * at the group's end). Throws an Error if a field's group doesn't exist, or a field or group names one to follow that
130
+ * isn't there.
131
+ *
132
+ * @example
133
+ * metadataLayout({ hero: { $edahaField: { group: { key: "files", after: "thumbnail" }, file: true } } }, {});
134
+ * // [..., { key: "files", fields: ["thumbnail", "hero", "attachments", "uploaded"], ... }, ...]
135
+ */
136
+ export const metadataLayout = (definitions, groups) => {
137
+ const all = [
138
+ ...BUILT_IN_GROUPS.map((group) => ({
139
+ ...group,
140
+ fields: [...group.fields],
141
+ })),
142
+ ...Object.entries(groups).map(([key, group]) => ({
143
+ key,
144
+ title: group.title,
145
+ description: group.description,
146
+ openedByDefault: group.openedByDefault,
147
+ fields: [],
148
+ })),
149
+ ];
150
+ const byKey = new Map(all.map((group) => [group.key, group]));
151
+ // Each group's custom fields, in the config file's order
152
+ const placed = new Map();
153
+ for (const [name, schema] of Object.entries(definitions)) {
154
+ const place = fieldPlace(name, schema.$edahaField?.group);
155
+ if (!byKey.has(place.key))
156
+ throw new Error(`"metadata.${name}" is in group "${place.key}", which isn't a built-in group or in "metadataGroups"`);
157
+ placed.set(place.key, [
158
+ ...(placed.get(place.key) ?? []),
159
+ { name, after: place.after },
160
+ ]);
161
+ }
162
+ for (const group of all)
163
+ group.fields = placeAfter(group.fields, placed.get(group.key) ?? [], (name, after) => `"metadata.${name}" comes after "${after}", which isn't in group "${group.key}"`);
164
+ const order = placeAfter(BUILT_IN_GROUPS.map((group) => group.key), Object.entries(groups).map(([key, group]) => ({
165
+ name: key,
166
+ after: group.after,
167
+ })), (name, after) => `"metadataGroups.${name}" comes after "${after}", which isn't a group`);
168
+ return order.map((key) => byKey.get(key));
169
+ };
@@ -1,17 +1,49 @@
1
+ import nunjucks from "nunjucks";
1
2
  import type { Logger, TemplateData } from "../types/index.ts";
2
3
  /** Templates that must exist for the build to run */
3
4
  export declare const REQUIRED_TEMPLATES: string[];
4
5
  /**
5
- * Make root-relative `href` and `src` URLs in HTML absolute, e.g. for RSS feeds read outside the website.
6
+ * Template names starting with this always load from the last template folder (the default theme's), e.g.
7
+ * `{% extends "@theme/article/single.njk" %}` in a site's own `article/single.njk`, to build on the theme's version.
8
+ */
9
+ export declare const THEME_PREFIX = "@theme/";
10
+ /**
11
+ * A Nunjucks loader for template names starting with THEME_PREFIX, from one folder. Other names are left to the next
12
+ * loader.
13
+ *
14
+ * @example
15
+ * themeLoader("/theme/templates").getSource("@theme/article/single.njk"); // the theme's article/single.njk
16
+ */
17
+ export declare const themeLoader: (dir: string) => nunjucks.ILoader;
18
+ /**
19
+ * Make a root-relative URL absolute on the website's domain, e.g. for RSS feeds read outside the website. Template
20
+ * data URLs already start with the website's base URL, so only its origin is added.
21
+ *
22
+ * @example
23
+ * absoluteUrl("/news/", "https://example.com"); // "https://example.com/news/"
24
+ * absoluteUrl("/edaha.md/news/", "https://lvl99.github.io/edaha.md"); // "https://lvl99.github.io/edaha.md/news/"
25
+ */
26
+ export declare const absoluteUrl: (url: string, siteUrl: string) => string;
27
+ /**
28
+ * Make root-relative `href` and `src` URLs in HTML absolute (see absoluteUrl), e.g. for RSS feeds read outside the
29
+ * website.
6
30
  *
7
31
  * @example
8
32
  * absoluteUrls('<a href="/news/">', "https://example.com"); // '<a href="https://example.com/news/">'
9
33
  */
10
34
  export declare const absoluteUrls: (html: string, siteUrl: string) => string;
35
+ /** Template tags that output the page's embed HTML (`TemplateData.embeds`), by where it goes */
36
+ export declare const EMBED_TAGS: {
37
+ readonly embedHead: "head";
38
+ readonly embedFoot: "foot";
39
+ readonly embedRenderHead: "head";
40
+ readonly embedRenderFoot: "foot";
41
+ };
11
42
  /**
12
- * Loads and renders the blog's Nunjucks templates from one or more folders. A file in an earlier folder overrides the
43
+ * Loads and renders the site's Nunjucks templates from one or more folders. A file in an earlier folder overrides the
13
44
  * same file in later ones (e.g. a site's templates over the default theme's). Falls back to the `article` templates
14
- * (with a warning) when an article type has none of its own.
45
+ * (with a warning) when an article type has none of its own. Names starting with THEME_PREFIX (`@theme/`) load from
46
+ * the last folder only.
15
47
  *
16
48
  * @example
17
49
  * const templates = new Templates(["site/templates", join(THEME_DIR, "templates")], console);