uncial-cms 5.1.0 → 5.3.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 (86) hide show
  1. package/README.md +216 -23
  2. package/dist/astro/EditorSurface.svelte +6 -2
  3. package/dist/astro/EditorSurface.svelte.d.ts +3 -1
  4. package/dist/astro/index.d.ts +2 -1
  5. package/dist/astro/index.js +7 -2
  6. package/dist/content-sources.d.ts +10 -0
  7. package/dist/content-sources.js +25 -1
  8. package/dist/dashboard/ConfirmDialog.svelte +76 -0
  9. package/dist/dashboard/ConfirmDialog.svelte.d.ts +10 -0
  10. package/dist/dashboard/Dashboard.svelte +650 -0
  11. package/dist/dashboard/Dashboard.svelte.d.ts +4 -0
  12. package/dist/dashboard/FallbackEditor.svelte +42 -0
  13. package/dist/dashboard/FallbackEditor.svelte.d.ts +14 -0
  14. package/dist/dashboard/GlobalForm.svelte +405 -0
  15. package/dist/dashboard/GlobalForm.svelte.d.ts +17 -0
  16. package/dist/dashboard/GlobalsList.svelte +62 -0
  17. package/dist/dashboard/GlobalsList.svelte.d.ts +7 -0
  18. package/dist/dashboard/MediaSection.svelte +221 -0
  19. package/dist/dashboard/MediaSection.svelte.d.ts +16 -0
  20. package/dist/dashboard/PagesSection.svelte +477 -0
  21. package/dist/dashboard/PagesSection.svelte.d.ts +23 -0
  22. package/dist/dashboard/element.d.ts +41 -0
  23. package/dist/dashboard/element.js +113 -0
  24. package/dist/dashboard/pages-list.d.ts +18 -0
  25. package/dist/dashboard/pages-list.js +29 -0
  26. package/dist/dashboard/routes.d.ts +25 -0
  27. package/dist/dashboard/routes.js +81 -0
  28. package/dist/dashboard/types.d.ts +34 -0
  29. package/dist/dashboard/types.js +1 -0
  30. package/dist/define-site.d.ts +15 -6
  31. package/dist/define-site.js +12 -9
  32. package/dist/editor-controller.d.ts +1 -0
  33. package/dist/editor-controller.js +1 -0
  34. package/dist/editor-session.d.ts +5 -0
  35. package/dist/editor-session.js +1 -1
  36. package/dist/errors.d.ts +13 -0
  37. package/dist/errors.js +14 -0
  38. package/dist/github/broker.d.ts +26 -0
  39. package/dist/github/broker.js +196 -0
  40. package/dist/github/index.d.ts +1 -0
  41. package/dist/github/index.js +1 -0
  42. package/dist/globals.d.ts +12 -0
  43. package/dist/globals.js +29 -0
  44. package/dist/image-source.d.ts +0 -10
  45. package/dist/image-source.js +15 -44
  46. package/dist/index-actions.d.ts +29 -2
  47. package/dist/index-actions.js +36 -4
  48. package/dist/index-page.d.ts +2 -0
  49. package/dist/index-page.js +6 -256
  50. package/dist/index.d.ts +6 -3
  51. package/dist/index.js +4 -3
  52. package/dist/local/vite.d.ts +8 -2
  53. package/dist/local/vite.js +32 -15
  54. package/dist/media-source.d.ts +45 -0
  55. package/dist/media-source.js +113 -0
  56. package/dist/mount.d.ts +3 -0
  57. package/dist/mount.js +3 -0
  58. package/dist/nav/index.d.ts +39 -0
  59. package/dist/nav/index.js +52 -0
  60. package/dist/served-url.d.ts +6 -4
  61. package/dist/served-url.js +18 -7
  62. package/dist/server/handlers.d.ts +1 -1
  63. package/dist/server/handlers.js +32 -5
  64. package/dist/server/index.d.ts +2 -1
  65. package/dist/server/index.js +2 -1
  66. package/dist/server/media.d.ts +1 -10
  67. package/dist/server/media.js +7 -11
  68. package/dist/server/postgres-store.d.ts +5 -0
  69. package/dist/server/postgres-store.js +50 -5
  70. package/dist/server-forge/adapter.d.ts +1 -0
  71. package/dist/server-forge/adapter.js +7 -4
  72. package/dist/server-forge/protocol.d.ts +3 -1
  73. package/dist/server-forge/protocol.js +2 -1
  74. package/dist/svelte/EditorPage.svelte +5 -1
  75. package/dist/svelte/EditorPage.svelte.d.ts +3 -1
  76. package/dist/svelte/MediaLibrary.svelte +109 -53
  77. package/dist/svelte/MediaLibrary.svelte.d.ts +10 -2
  78. package/dist/svelte/index.d.ts +1 -4
  79. package/dist/svelte/index.js +1 -4
  80. package/dist/sveltekit/index.d.ts +11 -1
  81. package/dist/sveltekit/index.js +23 -9
  82. package/dist/types.d.ts +2 -0
  83. package/dist/upload-context.d.ts +1 -0
  84. package/dist/upload-context.js +3 -0
  85. package/dist/vite/index.js +18 -4
  86. package/package.json +16 -3
package/README.md CHANGED
@@ -18,8 +18,8 @@ itself. The docs are the live demo.
18
18
  Uncial document). Nested paths map naturally: `/blog/hello/` ↔
19
19
  `content/blog/hello.json`.
20
20
  - Production (non-editor) pages ship **zero** uncial-cms JavaScript. The editing
21
- surface exists only on generated editor variants (`/about/edit/`) and the site
22
- index (`/uncial/`).
21
+ surface exists only on generated editor variants (`/about/edit/`) and the
22
+ Dashboard (`/uncial/`).
23
23
  - **Load:** the runtime fetches the JSON + its blob sha live from the forge
24
24
  (never the baked build output), normalizes it, and mounts `<uncial-editor>`.
25
25
  - **Save:** validate → serialize → commit with the recorded sha (optimistic
@@ -50,10 +50,13 @@ The package also ships a `uncial-cms` command; see
50
50
  (`mountEditorPage`, `mountIndexPage`), `createPage`/`deletePage`/`listPages`,
51
51
  `uploadAsset`/`uploadImageAsset`/`fitImage`/`servedUrl` (see
52
52
  [Media](#media)), `parseDocument`/`serializeDocument`, the session providers
53
- (`popupSessionProvider`, `patSessionProvider`), `MAX_CONTENT_BYTES`,
53
+ (`popupSessionProvider`, `brokerSessionProvider`, `patSessionProvider`),
54
+ `MAX_CONTENT_BYTES`,
54
55
  `ConflictError`, `NotFoundError`, and the shared types (`Site`,
55
56
  `SiteOptions`, `UncialCmsSiteConfig`, `ForgeSession`, `SessionProvider`,
56
57
  `ForgeAdapter`).
58
+ - `uncial-cms/dashboard` — registers `<uncial-dashboard>`, the `/uncial/`
59
+ Dashboard.
57
60
  - `uncial-cms/svelte` — `EditorPage`, the Svelte component that is the
58
61
  recommended door onto an Editor variant in a SvelteKit site.
59
62
  - `uncial-cms/session` — `createEditorSession`: the same editing session
@@ -69,11 +72,14 @@ The package also ships a `uncial-cms` command; see
69
72
  site's editor routes.
70
73
  - `uncial-cms/vite` — `uncialCms(siteOptions)`, the Vite plugins a site
71
74
  installs: the development editing endpoint, and the build's forge literal.
75
+ - `uncial-cms/nav` — `buildNav`, grouped and ordered site navigation from
76
+ Content documents' meta. Pure, so a reader layout can import it. See
77
+ [Navigation](#navigation).
72
78
  - `uncial-cms/paths` — the pure path↔source mapping and the page-path
73
79
  validators, with no `node:` module and no `@sveltejs/kit` in the import
74
80
  graph, so a plain Node script or a browser bundle can import it.
75
81
  - `uncial-cms/github` — the GitHub `ForgeAdapter` (`createGitHubAdapter`) over
76
- the Contents API, plus the two session providers.
82
+ the Contents API, plus the three GitHub session providers.
77
83
  - `uncial-cms/local` — the local filesystem `ForgeAdapter`
78
84
  (`createLocalAdapter`), its unauthenticated `localSessionProvider`, and
79
85
  `createLocalVitePlugin` for the development endpoint.
@@ -126,6 +132,35 @@ Set them to self-host the worker or run your own App.
126
132
  `autosaveMs` applies only when the resolved forge is local — on a forge every
127
133
  keystroke would be a commit — so the same declaration is right in both builds.
128
134
 
135
+ ### Content on another branch
136
+
137
+ `contentDir` and `mediaDir` are forge paths, relative to the root of
138
+ `github.branch`, which need not be the branch the code lives on. Check that
139
+ branch out somewhere the build can read it (a git worktree, say) and name the
140
+ local copies separately:
141
+
142
+ ```ts
143
+ export const siteOptions: SiteOptions = {
144
+ contentDir: 'pages', // on the `content` branch
145
+ mediaDir: 'media', // on the `content` branch
146
+ localContentDir: 'content/pages', // the worktree, from the build's cwd
147
+ localMediaDir: 'content/media',
148
+ mediaUrlPrefix: '/media', // where the site serves mediaDir
149
+ github: { repo: 'owner/name', branch: 'content' }
150
+ };
151
+ ```
152
+
153
+ - **`localMediaDir`** is where `mediaDir` sits on disk. The development endpoint
154
+ writes media there and content to `localContentDir`, each wherever it is.
155
+ Without it, `mediaDir` must sit beside `contentDir` in one checkout.
156
+ - **`mediaUrlPrefix`** is the site-root URL path the site serves `mediaDir`
157
+ under, and what [`servedUrl`](#media) maps uploads to. With it, `mediaDir` no
158
+ longer has to sit under the static dir. Serving the files there is the site's
159
+ job: copy or link `localMediaDir` into the build output, and into the static
160
+ dir in development.
161
+
162
+ Leave both out and `mediaDir` must sit under the static dir, as before.
163
+
129
164
  ## Vite plugins
130
165
 
131
166
  ```ts
@@ -142,13 +177,16 @@ export default defineConfig({
142
177
 
143
178
  `uncialCms` installs two things: the development-only local editing endpoint,
144
179
  rooted at the repository and permitting writes under the content directory and
145
- `mediaDir`; and a `define` of the forge the build targets, which is how a
180
+ `mediaDir` (or at `localContentDir` and `localMediaDir`, when a site declares
181
+ [content on another branch](#content-on-another-branch)); and a `define` of the forge the build targets, which is how a
146
182
  local-only production build drops the editor stack statically rather than merely
147
183
  leaving it unrouted.
148
184
 
149
185
  `createLocalVitePlugin` from `uncial-cms/local` is the same endpoint on its own,
150
186
  for a site that is not using `defineSite`; it takes the repository `root` and the
151
- repo-root-relative `permittedRoots` writes are confined to. It is serve-only and
187
+ repo-root-relative `permittedRoots` writes are confined to. A permitted root
188
+ given as `{ path, local }` is the forge path `path` kept at the FS path `local`
189
+ instead of under `root`. It is serve-only and
152
190
  binds Vite to `127.0.0.1` unless given a `host`. Every path it takes is repo-root-relative,
153
191
  exactly as the GitHub adapter addresses one. The adapter calls it at the fixed,
154
192
  development-only JSON endpoint `/__uncial-cms/local`:
@@ -206,6 +244,10 @@ export const entries = handlers.entries; // derived from the content dir
206
244
  export const load = handlers.load; // { document, meta, path }
207
245
  ```
208
246
 
247
+ `handlers.list()` returns every page as `{ path, sourcePath, document }`, the
248
+ same shape as the Astro helpers' `list()`, for a layout that builds
249
+ [navigation](#navigation) from the pages.
250
+
209
251
  **2. Editor variant** — `src/routes/[...path]/edit/+page.server.ts` bakes the
210
252
  mapping only; the document is always fetched live from the forge, never read
211
253
  out of the build:
@@ -258,15 +300,17 @@ Its props:
258
300
  | `sessionProvider` | `SessionProvider` | Defaults to the provider the resolved forge implies. |
259
301
  | `attributesPanel` | `'docked' \| 'overlay' \| 'off'` | Default `'overlay'`: the panel costs the document no width. |
260
302
  | `presentation` | `'card' \| 'bare'` | Default `'bare'`: no surface of the editor's own. |
303
+ | `attributeInputs` | `AttributeInputs` | Components for host-defined attribute inputs; see [Custom attribute inputs](#custom-attribute-inputs). |
261
304
 
262
305
  Pass `devOnly: true` to `createEditorHandlers` for a **GitHub** site that still
263
306
  wants editing in development only; a local-only site gets that behaviour without
264
307
  saying so. Kit reports a prerenderable route it never crawled, so a build strict
265
308
  about that also names the route in `prerender.handleUnseenRoutes`.
266
309
 
267
- **3. Site index** — `src/routes/uncial/+page.server.ts` + `+page.svelte` (OAuth
268
- landing, create/delete, hash-routed fallback editor). The Index page keeps the
269
- plain-DOM mount:
310
+ **3. Dashboard** — `src/routes/uncial/+page.server.ts` + `+page.svelte`. One
311
+ custom element, `<uncial-dashboard>`, is the whole signed-in area: Pages (list,
312
+ search, create, delete, and the hash-routed Fallback editor), Media, Globals and
313
+ the host's own App sections.
270
314
 
271
315
  ```ts
272
316
  import { createIndexHandlers } from 'uncial-cms/sveltekit';
@@ -281,23 +325,28 @@ export const load = handlers.load;
281
325
  <script lang="ts">
282
326
  import { onMount } from 'svelte';
283
327
  import { base } from '$app/paths';
284
- import { mountIndexPage } from 'uncial-cms';
328
+ import 'uncial-cms/dashboard';
285
329
  import { blocks, schema, site } from '../site.js';
286
330
 
287
- let target: HTMLElement;
288
- onMount(() => {
289
- const handle = mountIndexPage(target, { config: site.config, blocks, schema, basePath: base });
290
- return () => handle.destroy();
291
- });
331
+ let mounted = $state(false);
332
+ onMount(() => (mounted = true));
292
333
  </script>
293
334
 
294
- <div bind:this={target}></div>
335
+ {#if mounted}
336
+ <uncial-dashboard config={site} {blocks} {schema} basePath={base}></uncial-dashboard>
337
+ {/if}
295
338
  ```
296
339
 
297
- When the site is served under a base path (e.g. GitHub Pages project sites at
298
- `/owner/repo/`), pass the framework's base path to `mountIndexPage`
299
- (`basePath`) so live-page links resolve; the default mapping always operates on
300
- **site-relative** paths with the base stripped.
340
+ The element's options are objects and functions, which a prerendered attribute
341
+ cannot carry, so it renders after mount and Svelte sets them as properties.
342
+ `config` takes the whole site object, Globals included. When the site is served
343
+ under a base path (e.g. GitHub Pages project sites at `/owner/repo/`), pass the
344
+ framework's base path as `basePath` so live-page links resolve; the default
345
+ mapping always operates on **site-relative** paths with the base stripped. The
346
+ other options (`editorHref`, `can`, `appSections`, `staticDir`, `theme` and
347
+ more) are in the [Dashboard docs](https://d-flood.github.io/uncial/docs/dashboard/).
348
+ `mountIndexPage` still works, as a deprecated wrapper that renders the Dashboard
349
+ showing only Pages.
301
350
 
302
351
  ### Excluding non-page files, and a schema per path
303
352
 
@@ -318,6 +367,28 @@ const handlers = createContentHandlers({
318
367
  Pass the same resolver to `EditorPage` and to the Content page's renderer, and
319
368
  one page path means one schema everywhere.
320
369
 
370
+ ## Navigation
371
+
372
+ `buildNav` from `uncial-cms/nav` turns the pages' meta into grouped, ordered
373
+ navigation. Each page's `navGroup` names its submenu (blank for top level),
374
+ `navOrder` its position (lowest first, absent last) and `navLabel` its link text
375
+ (falling back to `title`, then the path). A group sits where its first member
376
+ sorts. Declare the fields in the schema's `metaFields`, and pass only the pages
377
+ the nav should show:
378
+
379
+ ```ts
380
+ import { buildNav } from 'uncial-cms/nav';
381
+
382
+ const nav = buildNav(
383
+ handlers.list().filter(({ document }) => document.meta?.navOrder !== undefined),
384
+ {
385
+ base, // prepended to site-root hrefs
386
+ links: [{ href: '/search/', label: 'Search', order: 50 }] // fixed links, placed like pages
387
+ }
388
+ );
389
+ // [{ kind: 'link', href, label } | { kind: 'group', id, label, links: [{ href, label }] }]
390
+ ```
391
+
321
392
  ## Quick start: Astro
322
393
 
323
394
  An Astro site renders content with `@astrojs/svelte` and Uncial's SSR renderer,
@@ -395,6 +466,34 @@ export function getStaticPaths() {
395
466
  a `sessionProvider` and an `imageSource` (see [Media](#media)). Against the GitHub forge it shows a Sign in button first,
396
467
  since a sign-in popup opened outside a click is blocked.
397
468
 
469
+ The Dashboard is one page that renders `<uncial-dashboard>` and sets its
470
+ options from a script, which Astro bundles for that page alone:
471
+
472
+ ```astro
473
+ ---
474
+ // src/pages/uncial.astro
475
+ ---
476
+
477
+ <html lang="en">
478
+ <head><title>Dashboard</title></head>
479
+ <body>
480
+ <uncial-dashboard></uncial-dashboard>
481
+ <script>
482
+ import 'uncial-cms/dashboard';
483
+ import { defineSite } from 'uncial-cms';
484
+ import { blocks, schema } from '../site';
485
+ import { siteOptions } from '../site-options';
486
+
487
+ Object.assign(document.querySelector('uncial-dashboard')!, {
488
+ config: defineSite(siteOptions),
489
+ blocks,
490
+ schema
491
+ });
492
+ </script>
493
+ </body>
494
+ </html>
495
+ ```
496
+
398
497
  Astro bundles a `client:only` island for any page file that renders it, even
399
498
  one whose `getStaticPaths` returns nothing. A site that wants no editor code in
400
499
  its production build at all injects the editor route from an integration only
@@ -511,8 +610,8 @@ Leave `autosaveMs` unset on a forge, where every keystroke would become a commit
511
610
 
512
611
  Authentication is owned entirely by the session provider — the `sessionProvider`
513
612
  option on `EditorPage`, `createEditorSession`, `mountEditorPage` and
514
- `mountIndexPage`. It defaults to the provider the resolved forge implies. Two
515
- ship in the box, plus the unauthenticated `localSessionProvider` the local forge
613
+ `mountIndexPage`, and the Dashboard. It defaults to the provider the resolved
614
+ forge implies. Three ship in the box, plus the unauthenticated `localSessionProvider` the local forge
516
615
  uses:
517
616
 
518
617
  - **`popupSessionProvider` (default under GitHub).** Opens the auth worker in a
@@ -523,6 +622,18 @@ uses:
523
622
  hosted instance exists; self-hosting is first-class). Tokens live in
524
623
  `sessionStorage` per repo; on expiry the popup re-runs, and GitHub skips
525
624
  re-consent so renewal is a flash.
625
+ - **`brokerSessionProvider({ brokerOrigin, clientId, appSlug, basePath? })`.**
626
+ Signs in with your own GitHub App through a code-exchange broker that holds
627
+ its client secret and serves `POST /github/token` and `POST /github/refresh`.
628
+ It opens GitHub's authorize page in a popup with a `state` kept in
629
+ `sessionStorage`; GitHub returns to the Dashboard at `<basePath>/uncial/`,
630
+ which relays the code to the opener, so register that page as the App's
631
+ callback URL. The broker's answer is read for `error` before its status,
632
+ because GitHub refuses with a 200. The user-to-server token it returns is the
633
+ forge's bearer, so GitHub itself decides who may push; `appSlug` names the App
634
+ when it cannot reach the repository. A refresh token, if the App issues one,
635
+ is kept in `localStorage` and renews the session without the popup; the
636
+ Dashboard's Sign out forgets it.
526
637
  - **`patSessionProvider`.** Zero-backend mode: prompts for a fine-grained
527
638
  personal access token (contents read/write on the target repo) and validates
528
639
  it via `GET /user`. The permanent dev / self-service mode — no worker needed.
@@ -536,6 +647,20 @@ uses:
536
647
  <EditorPage {site} {blocks} {schema} {sourcePath} {pagePath} sessionProvider={patSessionProvider} />
537
648
  ```
538
649
 
650
+ A broker-backed site passes the same provider to both doors:
651
+
652
+ ```ts
653
+ import { brokerSessionProvider } from 'uncial-cms';
654
+
655
+ export const sessionProvider = brokerSessionProvider({
656
+ brokerOrigin: 'https://github-broker.example.org',
657
+ clientId: 'Iv23li…',
658
+ appSlug: 'my-site-editor',
659
+ basePath: base
660
+ });
661
+ // <EditorPage {sessionProvider} … /> and <uncial-dashboard {sessionProvider} …>
662
+ ```
663
+
539
664
  ## The `uncial-cms` command
540
665
 
541
666
  The package ships a `bin` with two commands.
@@ -630,6 +755,63 @@ Residual risks accepted for v1 (see the spec's §6.5 for the full treatment):
630
755
  to repos the victim can push to *and* whose allowlist names the attacker
631
756
  origin — i.e. near zero.
632
757
 
758
+ ## Rich text: superscript, subscript and embeds
759
+
760
+ Uncial ships `superscript` and `subscript` marks, off by default. Name them in
761
+ the schema's `allowedMarks` and the editor gains them, with toolbar buttons,
762
+ and the renderer draws them as `<sup>` and `<sub>`:
763
+
764
+ ```ts
765
+ export const schema = createSchema(blocks, {
766
+ allowedMarks: ['bold', 'italic', 'strike', 'code', 'link', 'superscript', 'subscript']
767
+ });
768
+ ```
769
+
770
+ A host that already registers its own `superscript` or `subscript` extension,
771
+ toolbar feature or mark component keeps it.
772
+
773
+ `embedBlock` from `uncial` is an `embed` Block for oEmbed-style URL embeds:
774
+ YouTube and Vimeo URLs render as a player iframe, and any other URL as a link.
775
+ Register it like any Block:
776
+
777
+ ```ts
778
+ import { embedBlock } from 'uncial';
779
+
780
+ export const blocks = createBlockRegistry([embedBlock, …]);
781
+ ```
782
+
783
+ ## Custom attribute inputs
784
+
785
+ A Block attribute or meta field whose `input` names a kind of the host's own
786
+ gets that host's Svelte component as its field in the attributes and metadata
787
+ panels. Map kinds to components with `attributeInputs` on `EditorPage`,
788
+ `EditorSurface`, `mountEditorPage` and `<uncial-dashboard>` (for the Fallback
789
+ editor), or on Uncial's `Editor`:
790
+
791
+ ```ts
792
+ // a Block attribute
793
+ page: { default: { item: '', page: 1 }, input: 'item-page' }
794
+ ```
795
+
796
+ ```svelte
797
+ <!-- ItemPagePicker.svelte -->
798
+ <script lang="ts">
799
+ import type { AttributeInputProps } from 'uncial/core';
800
+
801
+ let { value, update }: AttributeInputProps<{ item: string; page: number }> = $props();
802
+ </script>
803
+
804
+ <button type="button" onclick={() => update({ item: 'abc', page: 3 })}>{value.item || 'Choose'}</button>
805
+ ```
806
+
807
+ ```svelte
808
+ <EditorPage {site} {blocks} {schema} {sourcePath} {pagePath} attributeInputs={{ 'item-page': ItemPagePicker }} />
809
+ ```
810
+
811
+ The component receives `name`, `spec`, the current `value` and `update`, and
812
+ the value it passes to `update` is stored as is, so it must be plain JSON. A
813
+ kind with no component keeps the chooser button and `onChooseAttribute`.
814
+
633
815
  ## Media
634
816
 
635
817
  A Block gets image upload by declaring an attribute with `input: 'image'`:
@@ -641,6 +823,15 @@ media dir for Choose existing. Pass `list` and `thumbnail` to override the
641
823
  listing and tile URLs for a rendition pipeline, or `imageSource` to replace the
642
824
  source outright.
643
825
 
826
+ The picker and `MediaLibrary` from `uncial-cms/svelte` both read media through a
827
+ **Media source**. `mediaSourceFor(config, session, { staticDir })` picks the
828
+ server forge's Media library, or the git forge's `mediaDir` through an editing
829
+ session's adapter and author. A source's `capabilities` say whether it has
830
+ titles and dimensions (`metadata`), `usage`, `delete` and `search`, and
831
+ `<MediaLibrary {source} />` shows only those; a git source keeps no metadata.
832
+ Deleting a server item that Content documents still use rejects with
833
+ `MediaInUseError`. `MediaLibrary`'s `apiBase` prop is deprecated.
834
+
644
835
  Underneath, single-image upload commits an image straight into the repo and
645
836
  answers its served path. It is exposed as pure, adapter-injected functions in
646
837
  the same family as `createPage`/`deletePage`:
@@ -674,7 +865,9 @@ updateAttributes?.({ src: servedUrl(site, result.path, STATIC_DIR) });
674
865
  passes through untouched. `fitImage` is exported for use on its own.
675
866
  - **`servedUrl(site, repoPath, staticDir?)`** maps a committed repo-root path
676
867
  under the static directory to the site-root-relative URL the built site serves
677
- it from. It carries **no base path**: a stored `src` must stay correct at
868
+ it from. A site with a `mediaUrlPrefix` maps a path under `mediaDir` to that
869
+ prefix instead, wherever `mediaDir` lives (see
870
+ [Content on another branch](#content-on-another-branch)). It carries **no base path**: a stored `src` must stay correct at
678
871
  every `paths.base` the same content is built at, so the site prepends its base
679
872
  at render time.
680
873
  - **Content-addressed.** The committed name is a hash of the bytes plus the
@@ -10,7 +10,7 @@
10
10
  */
11
11
  import 'uncial/styles/chrome.css';
12
12
  import { onMount, type ComponentProps } from 'svelte';
13
- import type { BlockRegistry, ContentDocument, ContentSchema } from 'uncial/core';
13
+ import type { AttributeInputs, BlockRegistry, ContentDocument, ContentSchema } from 'uncial/core';
14
14
  import {
15
15
  Editor,
16
16
  type ImageSource,
@@ -49,6 +49,8 @@
49
49
  presentation?: 'card' | 'bare';
50
50
  /** Forwarded to `Editor`; defaults to `cmsImageSource(site.config)`. */
51
51
  imageSource?: ImageSource;
52
+ /** Forwarded to `Editor`: Svelte components for host-defined attribute `input` kinds. */
53
+ attributeInputs?: AttributeInputs;
52
54
  }
53
55
 
54
56
  let {
@@ -63,7 +65,8 @@
63
65
  toolbarExtensions,
64
66
  attributesPanel = 'overlay',
65
67
  presentation = 'bare',
66
- imageSource
68
+ imageSource,
69
+ attributeInputs
67
70
  }: Props = $props();
68
71
 
69
72
  const resolvedSchema = $derived(typeof schema === 'function' ? schema(pagePath) : schema);
@@ -176,6 +179,7 @@
176
179
  {attributesPanel}
177
180
  {presentation}
178
181
  imageSource={resolvedImageSource}
182
+ {attributeInputs}
179
183
  onChange={(next) => controller?.documentChanged(next as ContentDocument)}
180
184
  />
181
185
  {/if}
@@ -9,7 +9,7 @@
9
9
  */
10
10
  import 'uncial/styles/chrome.css';
11
11
  import { type ComponentProps } from 'svelte';
12
- import type { BlockRegistry, ContentSchema } from 'uncial/core';
12
+ import type { AttributeInputs, BlockRegistry, ContentSchema } from 'uncial/core';
13
13
  import { Editor, type ImageSource, type ToolbarFeature, type ToolbarFeatureSelection } from 'uncial/editor';
14
14
  import type { Site } from '../define-site.js';
15
15
  import type { SessionProvider } from '../types.js';
@@ -37,6 +37,8 @@ interface Props {
37
37
  presentation?: 'card' | 'bare';
38
38
  /** Forwarded to `Editor`; defaults to `cmsImageSource(site.config)`. */
39
39
  imageSource?: ImageSource;
40
+ /** Forwarded to `Editor`: Svelte components for host-defined attribute `input` kinds. */
41
+ attributeInputs?: AttributeInputs;
40
42
  }
41
43
  declare const EditorSurface: import("svelte").Component<Props, {}, "">;
42
44
  type EditorSurface = ReturnType<typeof EditorSurface>;
@@ -1,6 +1,8 @@
1
1
  import type { BlockRegistry, ContentDocument, ContentSchema } from 'uncial/core';
2
2
  import type { SiteOptions } from '../define-site.js';
3
3
  export { uncialCms } from './integration.js';
4
+ export { loadGlobal, type GlobalStore } from '../content-sources.js';
5
+ export type { GlobalValue } from '../globals.js';
4
6
  /** A content file as the helpers see it: site-relative path, repo-root-relative source. */
5
7
  export interface ContentEntry {
6
8
  path: string;
@@ -19,7 +21,6 @@ export interface ContentRouteOptions {
19
21
  blocks: BlockRegistry;
20
22
  /** One schema for the whole site, or the schema this page path is written against. */
21
23
  schema: ContentSchema | ((path: string) => ContentSchema);
22
- /** Keep a non-page file — site settings, a manifest — out of the routes. */
23
24
  exclude?: (entry: ContentEntry) => boolean;
24
25
  }
25
26
  /**
@@ -17,11 +17,16 @@ import { readFileSync } from 'node:fs';
17
17
  import { join } from 'node:path';
18
18
  import { normalizeDocument } from 'uncial/core';
19
19
  import { listContentSources } from '../content-sources.js';
20
+ import { isGlobalsPath } from '../globals.js';
20
21
  import { defaultMapPathToSource, defaultMapSourceToPath } from '../paths/index.js';
21
22
  export { uncialCms } from './integration.js';
23
+ export { loadGlobal } from '../content-sources.js';
22
24
  function localContentDir({ siteOptions }) {
23
25
  return siteOptions.localContentDir ?? siteOptions.contentDir;
24
26
  }
27
+ function excluded(opts, entry) {
28
+ return isGlobalsPath(entry.path) || (opts.exclude?.(entry) ?? false);
29
+ }
25
30
  function listEntries(opts) {
26
31
  const { contentDir } = opts.siteOptions;
27
32
  return listContentSources(localContentDir(opts))
@@ -29,7 +34,7 @@ function listEntries(opts) {
29
34
  const source = `${contentDir}/${rel}`;
30
35
  return { path: defaultMapSourceToPath(source, contentDir), source };
31
36
  })
32
- .filter((entry) => !opts.exclude?.(entry));
37
+ .filter((entry) => !excluded(opts, entry));
33
38
  }
34
39
  function readPage(opts, { path, source }) {
35
40
  const rel = source.slice(opts.siteOptions.contentDir.length + 1);
@@ -50,7 +55,7 @@ export function createContentRoutes(opts) {
50
55
  list,
51
56
  load: (path) => {
52
57
  const source = defaultMapPathToSource(path, opts.siteOptions.contentDir);
53
- if (opts.exclude?.({ path, source })) {
58
+ if (excluded(opts, { path, source })) {
54
59
  throw new Error(`Content path "${path}" is excluded from this site's routes.`);
55
60
  }
56
61
  return readPage(opts, { path, source });
@@ -1,2 +1,12 @@
1
+ import type { Site } from './define-site.js';
2
+ import { type GlobalValue } from './globals.js';
1
3
  /** Every `.json` file under the local content dir, content-dir-relative and sorted. */
2
4
  export declare function listContentSources(localContentDir: string, prefix?: string): string[];
5
+ export interface GlobalStore {
6
+ get(path: string): Promise<{
7
+ published: unknown;
8
+ } | null>;
9
+ }
10
+ export declare function loadGlobal<S extends Site, N extends keyof S['globals'] & string>(site: S, name: N, opts?: {
11
+ store?: GlobalStore;
12
+ }): Promise<GlobalValue<S, N>>;
@@ -1,6 +1,8 @@
1
- /** Build-time enumeration of a content directory, shared by the framework route factories. Node only. */
2
1
  import { readdirSync } from 'node:fs';
2
+ import { readFile } from 'node:fs/promises';
3
3
  import { join } from 'node:path';
4
+ import { normalizeDocument } from 'uncial/core';
5
+ import { globalRecordPath, globalSourcePath } from './globals.js';
4
6
  /** Every `.json` file under the local content dir, content-dir-relative and sorted. */
5
7
  export function listContentSources(localContentDir, prefix = '') {
6
8
  const sources = [];
@@ -13,3 +15,25 @@ export function listContentSources(localContentDir, prefix = '') {
13
15
  }
14
16
  return sources.sort();
15
17
  }
18
+ async function readGlobal(site, name, store) {
19
+ if (site.config.forge === 'server') {
20
+ if (!store)
21
+ throw new Error('A server site reads its Globals from its content store: pass { store }.');
22
+ return (await store.get(globalRecordPath(name)))?.published ?? null;
23
+ }
24
+ try {
25
+ return JSON.parse(await readFile(globalSourcePath(site.localContentDir, name), 'utf-8'));
26
+ }
27
+ catch (error) {
28
+ if (error.code === 'ENOENT')
29
+ return null;
30
+ throw error;
31
+ }
32
+ }
33
+ export async function loadGlobal(site, name, opts = {}) {
34
+ const schema = site.globals[name];
35
+ if (!schema)
36
+ throw new Error(`The site declares no Global named "${name}".`);
37
+ const stored = (await readGlobal(site, name, opts.store));
38
+ return (normalizeDocument(stored, [], schema).meta ?? {});
39
+ }
@@ -0,0 +1,76 @@
1
+ <svelte:options css="injected" />
2
+
3
+ <script lang="ts">
4
+ import { onMount, type Snippet } from 'svelte';
5
+
6
+ interface Props {
7
+ title: string;
8
+ confirmLabel: string;
9
+ onclose: (confirmed: boolean) => void;
10
+ children: Snippet;
11
+ }
12
+
13
+ let { title, confirmLabel, onclose, children }: Props = $props();
14
+
15
+ const uid = $props.id();
16
+ let dialog = $state<HTMLDialogElement>();
17
+ let cancel = $state<HTMLButtonElement>();
18
+ // The close event lands a task after Escape, by when the parent may have opened another dialog.
19
+ let mounted = true;
20
+
21
+ onMount(() => {
22
+ dialog?.showModal();
23
+ cancel?.focus();
24
+ return () => (mounted = false);
25
+ });
26
+ </script>
27
+
28
+ <dialog
29
+ bind:this={dialog}
30
+ class="dialog"
31
+ aria-labelledby="{uid}-title"
32
+ aria-describedby="{uid}-body"
33
+ onclose={() => mounted && onclose(dialog?.returnValue === 'confirm')}
34
+ >
35
+ <form method="dialog">
36
+ <h2 id="{uid}-title">{title}</h2>
37
+ <div id="{uid}-body" class="body">{@render children()}</div>
38
+ <div class="actions">
39
+ <button bind:this={cancel} value="cancel" class="btn">Cancel</button>
40
+ <button value="confirm" class="btn btn-danger">{confirmLabel}</button>
41
+ </div>
42
+ </form>
43
+ </dialog>
44
+
45
+ <style>
46
+ .dialog {
47
+ width: min(28rem, calc(100vw - 2rem));
48
+ padding: var(--uncial-space-5);
49
+ border: 1px solid var(--uncial-color-border);
50
+ border-radius: var(--uncial-radius-lg);
51
+ background: var(--uncial-color-surface);
52
+ color: var(--uncial-color-text);
53
+ box-shadow: var(--uncial-shadow-md);
54
+ }
55
+
56
+ .dialog::backdrop {
57
+ background: rgb(0 0 0 / 0.45);
58
+ }
59
+
60
+ h2 {
61
+ margin: 0 0 var(--uncial-space-3);
62
+ font-size: 1.125rem;
63
+ }
64
+
65
+ .body {
66
+ margin: 0 0 var(--uncial-space-5);
67
+ overflow-wrap: anywhere;
68
+ }
69
+
70
+ .actions {
71
+ display: flex;
72
+ flex-wrap: wrap;
73
+ justify-content: flex-end;
74
+ gap: var(--uncial-space-2);
75
+ }
76
+ </style>
@@ -0,0 +1,10 @@
1
+ import { type Snippet } from 'svelte';
2
+ interface Props {
3
+ title: string;
4
+ confirmLabel: string;
5
+ onclose: (confirmed: boolean) => void;
6
+ children: Snippet;
7
+ }
8
+ declare const ConfirmDialog: import("svelte").Component<Props, {}, "">;
9
+ type ConfirmDialog = ReturnType<typeof ConfirmDialog>;
10
+ export default ConfirmDialog;