@medicine-wheel/episode-ui 0.0.0-stage → 0.26.0

package/README.md

@@ -1,3 +1,216 @@
-# Temporary Holding Version
+# @medicine-wheel/episode-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Browse, read and edit the files of a Miadi episode in the browser.
+
+In the Miadi stack, an episode is the folder a piece of work is filed under, and this package
+is how a person opens one: browse its files, read one, preview its markdown, edit it in
+CodeMirror, go full screen with only Save and Back, and survive a conflict without losing the
+draft. It also has React components for a ceremony's working notes, its attachments, and the
+episode shelf. It is the browser half of `@medicine-wheel/episode-vessel`, which holds the rules for
+the folder on the server side.
+
+## Where it lives
+
+Up to 0.6.0 (jgwill/Miadi e4e1b141) this package was `@miadi/episode-ui`, published from jgwill/Miadi. It moved to
+jgwill/medicine-wheel in 0.25.0 so that dependencies run one way: the medicine-wheel suite is
+the foundation, and Miadi consumes it. From 0.7.0, `@miadi/episode-ui` re-exports this package with the
+same entry points, so code that imports it keeps working. Ref jgwill/medicine-wheel#166.
+
+```bash
+npm i @medicine-wheel/episode-ui
+```
+
+## One files workspace, two kinds of host
+
+`mountEpisodeFiles` is framework-free, so a plain page and a React app mount the
+same implementation.
+
+React:
+
+```jsx
+import { EpisodeFiles, httpEpisodeFiles } from "@medicine-wheel/episode-ui"
+import "@medicine-wheel/episode-ui/styles.css"
+
+const service = httpEpisodeFiles({ fileUrl: (file) => `/api/files/${file.relativePath}` })
+<EpisodeFiles files={files} capabilities={capabilities} service={service} />
+```
+
+A page with no bundler: serve `dist/browser/episode-files.js`
+(CodeMirror, marked and DOMPurify inlined) and `src/episode-ui.css`.
+
+```html
+<div id="files"></div>
+<script type="module">
+  import { mountEpisodeFiles, httpEpisodeFiles } from "/vendor/episode-ui/episode-files.js"
+  mountEpisodeFiles(document.getElementById("files"), {
+    files,
+    service: httpEpisodeFiles({
+      fileUrl: (file) => `/api/episode-file?file=${encodeURIComponent(file.relativePath)}`,
+      mediaUrl: (file) => `/api/episode-media?file=${encodeURIComponent(file.relativePath)}`,
+    }),
+  })
+</script>
+```
+
+## What it does
+
+- A filterable file tree: the folders the paths name, every one open, so a file's
+  folder is plain to see. Guidance files are dimmed and media and documents marked.
+- Markdown opens in a sanitised preview (`marked` + DOMPurify); `Source` shows CodeMirror.
+- CodeMirror 6 with markdown, JSON and YAML colouring, undo, search (Ctrl/Cmd-F),
+  line wrapping, and Ctrl/Cmd-S to save.
+- `⛶` opens the viewer full screen with only the file name, its state, Save and `×`.
+  Esc returns.
+- Audio and video play inline; images show inline; documents are a download.
+- A markdown preview shows the episode's own images: `![](images/still.png)` is
+  resolved from the file's folder and shown from the host's `mediaUrl`.
+- **Add images** (button, or drop files on the workspace) appears when the
+  capabilities include `upload` and the service has `upload` (`httpEpisodeFiles`
+  has it only when the host passes `uploadUrl`). Each image is sent
+  to `images/<name>`, the name reduced to safe characters and suffixed `-2`, `-3`
+  when taken; the new files are listed at once, `onFilesAdded` tells the host, and
+  the last one opens.
+- An open image shows the record beside it: caption, role and, at the bottom, the
+  credit (`service.readRecord`). A role holding `edit` gets **Describe** (role,
+  caption, alt text, origin, tool, made by, chosen by; `service.saveRecord` over
+  the revision read) and **Use as cover** (`service.setCover`). `httpEpisodeFiles`
+  offers them when the host passes `recordUrl` and `coverUrl`.
+- Leaving a file or the page with unsaved changes asks first.
+
+## The folders
+
+The vessel lists files, each with its path, and no folders. The workspace builds
+the folders from the paths and draws them as a tree:
+
+- Every folder is open to begin with. A folder closes and opens from its row, and
+  **Collapse all** / **Expand all** does every folder at once. Only a closed folder
+  is remembered, so a folder that arrives later opens.
+- A row says the file's name; its whole path is the row's tooltip, and
+  `data-path` carries it for a host or a test.
+- At each level a `README.md` comes first, then the folders by name, then the
+  files in the vessel's order (text, documents, guidance, images, media). Names
+  compare numerically: `chapter-2` comes before `chapter-10`.
+- A folder shows how many files are beneath it, at any depth.
+- Typing in the filter shows each match in its folders, every one open whatever was
+  closed before; clearing it brings back the folders as the reader left them.
+- A file opened from a link or an address opens the folders it sits in.
+- A list with no folder in it looks as it always did.
+
+`listing="flat"` keeps the old list of whole paths, for a host that wants it.
+
+The grouping is also exported, framework-free, for a host that draws its own:
+`buildFileTree(files)` returns the root folder (`children`, each a `file` or a
+`folder` with its `path` and `fileCount`), `ancestorFolders(path)` names the
+folders above a file and `folderPaths(tree)` every folder in the tree.
+
+## The open file as an address
+
+The workspace holds no URL, so a host that wants the open file in its address
+passes `open` and listens to `onSelectionChange`:
+
+```jsx
+<EpisodeFiles
+  files={files}
+  service={service}
+  open={{ path: "notes.md", mode: "source" }}   // from the address; null closes
+  onSelectionChange={(selection, { push }) => {
+    // selection: { path, mode? } or null. mode is "preview" | "source" for a text file.
+    // push is true when a person opened another file, or kept a draft instead of
+    // following the address: add a history entry. Otherwise replace the current one.
+  }}
+/>
+```
+
+- A requested path waits for `files` to arrive and for the right to read, then
+  opens and scrolls the viewer into view. `open={{ path, reveal: false }}` opens
+  it without scrolling, for a room that opens on its script by default and should
+  not carry a phone past its header. A file a person clicks still scrolls into
+  view on a narrow screen.
+- `open` is acted on only when its value changes, so re-rendering with the same
+  one does nothing, and a click the address has not caught up with is kept.
+- A path the episode does not hold, or a file too large to open, says so. A
+  mode that does not fit the file is corrected, and the corrected selection is
+  reported back.
+- An unsaved draft is never dropped by an address change: the person is asked.
+  A refusal reports the file still shown with `push`, so the entry Back or
+  Forward moved to is kept rather than overwritten.
+- A relative link in a markdown preview is read from that file's folder. A plain
+  click on a link to another file of the episode opens it here in preview, with
+  `push`. Pass `fileHref={(selection) => url}` and those links also carry the
+  file's address, so a new tab or a copied link lands on the same file. A link
+  that leaves the episode (a scheme, a root path, a climb above the root) is
+  left as written. `episodeLinkTarget(fromPath, href)` is the same resolution.
+
+The address rule is also exported on its own: `selectionFromSearch(search)`
+reads `?file=&mode=`, `addressWithSelection(href, selection)` writes it into an
+address and keeps every other parameter, and `writeSelectionToAddress(selection,
+{ push })` writes it into the browser's history. In React, one hook does all of it:
+
+```jsx
+const address = useEpisodeFilesAddress()            // or { search: useSearchParams().toString() } in Next.js
+<EpisodeFiles {...address} files={files} service={service} />
+```
+
+## The room's masthead, lineage and source issues
+
+`EpisodeMasthead`, `LineageList` and `SourceIssueList` draw the top of an
+episode room. They hold no state and fetch nothing, so a server page renders them
+and passes a link callback:
+
+```jsx
+<EpisodeMasthead numberLabel="551" title={summary.title} goal={summary.goal}
+  date={summary.date} status={summary.status} type={summary.type}
+  direction={{ label: "West", oj: "Epangishmok", glyph: "🌊", color: "#5b78b4" }}
+  coverUrl={coverUrl} theme={CHRONICLE_THEME} />
+<LineageList edges={await readEpisodeLineage(root, episode)} href={(folder) => `/episodes/${folder}`} />
+<SourceIssueList issues={summary.references.map((ref) => ({ ref, url: issueUrl(ref) }))} />
+```
+
+An edge whose number two folders claim lists both, each linked.
+
+## The chronicle theme
+
+`@medicine-wheel/episode-ui/chronicle-theme` is the Chronicle's dark surface as data:
+`CHRONICLE_PALETTE`, `CHRONICLE_THEME` (an `EpisodeUITheme`, which
+`@miadi/attention-ui`'s panel also takes), `DIRECTIONS` (the four directions with
+their names, colours and glyphs), `FONT_SANS` and `FONT_MONO`. Every text colour
+of `CHRONICLE_THEME` reads at 4.5:1 or better on its background and its card.
+
+## One file, no folder
+
+A host that opens a single file it names itself, such as Miadi's `/e` editor, passes
+that file in `files` and in `open` with `layout: "single"`: the list, filter and
+count are hidden and the viewer takes the width. `outsideFileHref(path)` gives a
+link in the preview to a file the workspace does not hold an address of its own;
+without it, such a link says the file is not here.
+
+## The conflict path
+
+A save carries the revision the file was read at. When someone else wrote in
+between, the host answers 409 with `currentRevision`: the draft stays in the
+editor, the message says what is on disk now, and Reload is a choice the person
+makes. **A save is never retried automatically.**
+
+## The contract
+
+No component holds a URL or a token, knows a chronicle root, or decides what a
+person is allowed to do. The host passes a `service`; `httpEpisodeFiles` is the
+one module that fetches, and only from URLs the host gives it. The host resolves
+capabilities (`@medicine-wheel/episode-vessel/permissions`) and stays the authority; a
+capability here decides only what is offered. A test holds this contract.
+
+| export | what it is for |
+|---|---|
+| `mountEpisodeFiles(el, options)` | the files workspace; returns `{ update, destroy }` |
+| `EpisodeFiles` | the same, as a React component |
+| `httpEpisodeFiles({ fileUrl, mediaUrl?, headers?, uploadUrl?, recordUrl?, coverUrl? })` | the service for a host that answers GET/PUT JSON; with `uploadUrl` it POSTs a new image's bytes, with `recordUrl` it reads and writes an image's record, with `coverUrl` it names the cover |
+| `imageUploadPath(name, type, taken)` | the `images/` path a chosen image is added at |
+| `CeremonyNoteEditor` | a ceremony's working notes (React) |
+| `CeremonyAttachments` | what a circle was held about (React) |
+| `EpisodeShelfFilter` | find an episode by number, title or slug (React) |
+
+## Styling
+
+One stylesheet of plain class names over CSS custom properties, set from an
+`EpisodeUITheme`. Touch targets are 44px because the first surface this runs on
+is a phone.

package/dist/address.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The open file as the page's address: `?file=<path>&mode=preview|source`.
+ *
+ * A reload, a shared link and Back all land on the same file because the
+ * address carries it. These functions are that rule, with no framework: read a
+ * selection from a query string, and write one into an address. Miadi's room
+ * and eury's room each wrote them by hand; `useEpisodeFilesAddress` is the
+ * React form.
+ */
+import type { EpisodeFileSelection } from "./episode-files.js";
+export declare const FILE_PARAM = "file";
+export declare const MODE_PARAM = "mode";
+/** The selection a query string names (`?file=&mode=`), or null when it names none. A mode it does not know is dropped. */
+export declare function selectionFromSearch(search: string | URLSearchParams): EpisodeFileSelection | null;
+/**
+ * `href` with the selection written into its query, every other parameter and
+ * the fragment kept. `null` removes the file and its mode. The address keeps
+ * its form: absolute stays absolute, `/episodes/551` stays rooted, and
+ * `551?x=1`, `?x=1` or `#top` stay relative to the page.
+ */
+export declare function addressWithSelection(href: string, selection: EpisodeFileSelection | null): string;
+/**
+ * Write the selection into the browser's address: a new history entry when
+ * `push` (a person opened another file), otherwise a replacement. Nothing is
+ * written when the address already says it.
+ */
+export declare function writeSelectionToAddress(selection: EpisodeFileSelection | null, { push }: {
+    push: boolean;
+}): void;
+//# sourceMappingURL=address.d.ts.map

package/dist/address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../src/address.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAY,MAAM,oBAAoB,CAAA;AAExE,eAAO,MAAM,UAAU,SAAS,CAAA;AAChC,eAAO,MAAM,UAAU,SAAS,CAAA;AAIhC,2HAA2H;AAC3H,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,oBAAoB,GAAG,IAAI,CAMjG;AAKD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,oBAAoB,GAAG,IAAI,GAAG,MAAM,CAWjG;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,oBAAoB,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAOjH"}

package/dist/address.js

@@ -0,0 +1,64 @@
+/**
+ * The open file as the page's address: `?file=<path>&mode=preview|source`.
+ *
+ * A reload, a shared link and Back all land on the same file because the
+ * address carries it. These functions are that rule, with no framework: read a
+ * selection from a query string, and write one into an address. Miadi's room
+ * and eury's room each wrote them by hand; `useEpisodeFilesAddress` is the
+ * React form.
+ */
+export const FILE_PARAM = "file";
+export const MODE_PARAM = "mode";
+const isMode = (value) => value === "preview" || value === "source";
+/** The selection a query string names (`?file=&mode=`), or null when it names none. A mode it does not know is dropped. */
+export function selectionFromSearch(search) {
+    const params = typeof search === "string" ? new URLSearchParams(search) : search;
+    const path = params.get(FILE_PARAM);
+    if (!path)
+        return null;
+    const mode = params.get(MODE_PARAM);
+    return isMode(mode) ? { path, mode } : { path };
+}
+/** A base for reading a relative href: no scheme a browser fetches, and a folder to strip off again. */
+const RELATIVE_BASE = "address:/~/";
+/**
+ * `href` with the selection written into its query, every other parameter and
+ * the fragment kept. `null` removes the file and its mode. The address keeps
+ * its form: absolute stays absolute, `/episodes/551` stays rooted, and
+ * `551?x=1`, `?x=1` or `#top` stay relative to the page.
+ */
+export function addressWithSelection(href, selection) {
+    const absolute = /^[a-z][a-z0-9+.-]*:/i.test(href);
+    const url = new URL(href, RELATIVE_BASE);
+    if (selection)
+        url.searchParams.set(FILE_PARAM, selection.path);
+    else
+        url.searchParams.delete(FILE_PARAM);
+    if (selection?.mode)
+        url.searchParams.set(MODE_PARAM, selection.mode);
+    else
+        url.searchParams.delete(MODE_PARAM);
+    if (absolute)
+        return url.href;
+    const rooted = href.startsWith("/");
+    const path = !rooted && url.pathname.startsWith("/~/") ? url.pathname.slice(3) : url.pathname;
+    return `${path}${url.search}${url.hash}`;
+}
+/**
+ * Write the selection into the browser's address: a new history entry when
+ * `push` (a person opened another file), otherwise a replacement. Nothing is
+ * written when the address already says it.
+ */
+export function writeSelectionToAddress(selection, { push }) {
+    if (typeof window === "undefined")
+        return;
+    const next = addressWithSelection(window.location.href, selection);
+    if (next === window.location.href)
+        return;
+    // `null` state, as Next.js's app router documents for its own pushState sync.
+    if (push)
+        window.history.pushState(null, "", next);
+    else
+        window.history.replaceState(null, "", next);
+}
+//# sourceMappingURL=address.js.map

package/dist/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../src/address.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAA;AAChC,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAA;AAEhC,MAAM,MAAM,GAAG,CAAC,KAAoB,EAAqB,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,QAAQ,CAAA;AAErG,2HAA2H;AAC3H,MAAM,UAAU,mBAAmB,CAAC,MAAgC;IAClE,MAAM,MAAM,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;IAChF,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAA;IACnC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAA;IACtB,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAA;IACnC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAA;AACjD,CAAC;AAED,wGAAwG;AACxG,MAAM,aAAa,GAAG,aAAa,CAAA;AAEnC;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,SAAsC;IACvF,MAAM,QAAQ,GAAG,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAClD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,aAAa,CAAC,CAAA;IACxC,IAAI,SAAS;QAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,EAAE,SAAS,CAAC,IAAI,CAAC,CAAA;;QAC1D,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;IACxC,IAAI,SAAS,EAAE,IAAI;QAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,EAAE,SAAS,CAAC,IAAI,CAAC,CAAA;;QAChE,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;IACxC,IAAI,QAAQ;QAAE,OAAO,GAAG,CAAC,IAAI,CAAA;IAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAA;IACnC,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAA;IAC7F,OAAO,GAAG,IAAI,GAAG,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,CAAA;AAC1C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,SAAsC,EAAE,EAAE,IAAI,EAAqB;IACzG,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,OAAM;IACzC,MAAM,IAAI,GAAG,oBAAoB,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAA;IAClE,IAAI,IAAI,KAAK,MAAM,CAAC,QAAQ,CAAC,IAAI;QAAE,OAAM;IACzC,8EAA8E;IAC9E,IAAI,IAAI;QAAE,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,CAAA;;QAC7C,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,CAAA;AAClD,CAAC"}