@miadi/episode-ui 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The shapes these components take in.
+ *
+ * They are re-declared structurally rather than imported from
+ * `@miadi/episode-vessel` at runtime: a browser bundle must not pull `node:fs`
+ * in, and a host that reaches a vessel over HTTP receives JSON, not the
+ * package's classes. The vessel package is a type-only dependency here, and the
+ * two definitions are kept honest by `test/contract.test.mjs`.
+ */
+export type FileKind = "text" | "document" | "media";
+export interface EpisodeFileView {
+    relativePath: string;
+    name: string;
+    kind: FileKind;
+    size: number;
+    modifiedAt: string;
+    previewable: boolean;
+    editable: boolean;
+    guidance: boolean;
+}
+export interface FileRevisionView {
+    sha256: string;
+    modifiedAt: string;
+    bytes: number;
+}
+export interface EpisodeTextView {
+    content: string;
+    contentType: string;
+    size: number;
+    revision: FileRevisionView;
+}
+export interface EpisodeCapabilitiesView {
+    browse: boolean;
+    read: boolean;
+    edit: boolean;
+    upload: boolean;
+    attachCapture: boolean;
+    writeCeremonyNote: boolean;
+    attachToCeremony: boolean;
+}
+export interface CeremonyAttachmentView {
+    relativePath: string;
+    attachedBy: string;
+    attachedAt: string;
+    note?: string;
+}
+export interface EpisodeShelfEntry {
+    episodePath: string;
+    number: number;
+    numberLabel: string;
+    title: string;
+    date: string;
+    goal?: string;
+    status?: string;
+    /** True when the medicine wheel also holds this episode. */
+    registered?: boolean;
+}
+/** Colours and fonts the host already has. Every component takes the same set. */
+export interface EpisodeUITheme {
+    background: string;
+    card: string;
+    text: string;
+    textDim: string;
+    muted: string;
+    accent: string;
+    border: string;
+    success: string;
+    warning: string;
+    mono: string;
+}
+export declare const DEFAULT_THEME: EpisodeUITheme;
+export declare function themeVars(theme: EpisodeUITheme): Record<string, string>;
+export declare function formatBytes(bytes: number): string;
+export declare function iconFor(file: {
+    name: string;
+    kind: FileKind;
+}): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,CAAA;AAEpD,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,QAAQ,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,OAAO,CAAA;IACpB,QAAQ,EAAE,OAAO,CAAA;IACjB,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,gBAAgB,CAAA;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,OAAO,CAAA;IACf,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,OAAO,CAAA;IACb,MAAM,EAAE,OAAO,CAAA;IACf,aAAa,EAAE,OAAO,CAAA;IACtB,iBAAiB,EAAE,OAAO,CAAA;IAC1B,gBAAgB,EAAE,OAAO,CAAA;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,4DAA4D;IAC5D,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;CACb;AAED,eAAO,MAAM,aAAa,EAAE,cAW3B,CAAA;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAavE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKjD;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,MAAM,CAUtE"}

package/dist/types.js

@@ -0,0 +1,63 @@
+/**
+ * The shapes these components take in.
+ *
+ * They are re-declared structurally rather than imported from
+ * `@miadi/episode-vessel` at runtime: a browser bundle must not pull `node:fs`
+ * in, and a host that reaches a vessel over HTTP receives JSON, not the
+ * package's classes. The vessel package is a type-only dependency here, and the
+ * two definitions are kept honest by `test/contract.test.mjs`.
+ */
+export const DEFAULT_THEME = {
+    background: "#0d0f12",
+    card: "#15181d",
+    text: "#e8e6e1",
+    textDim: "#b3afa6",
+    muted: "#7d7a72",
+    accent: "#ffd700",
+    border: "#2a2e35",
+    success: "#5ac37d",
+    warning: "#e0a458",
+    mono: "ui-monospace, SFMono-Regular, Menlo, monospace",
+};
+export function themeVars(theme) {
+    return {
+        "--episode-bg": theme.background,
+        "--episode-card": theme.card,
+        "--episode-text": theme.text,
+        "--episode-text-dim": theme.textDim,
+        "--episode-muted": theme.muted,
+        "--episode-accent": theme.accent,
+        "--episode-border": theme.border,
+        "--episode-success": theme.success,
+        "--episode-warning": theme.warning,
+        "--episode-mono": theme.mono,
+    };
+}
+export function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        return "";
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+export function iconFor(file) {
+    const extension = /\.([^.]+)$/.exec(file.name)?.[1]?.toLowerCase() ?? "";
+    if (["m4a", "mp3", "wav", "opus", "aac", "amr", "ogg"].includes(extension))
+        return "🎙";
+    if (["mp4", "webm", "mov"].includes(extension))
+        return "🎬";
+    if (extension === "mid")
+        return "🎹";
+    if (extension === "md")
+        return "📘";
+    if (["json", "yaml", "yml"].includes(extension))
+        return "🧾";
+    if (["html", "htm"].includes(extension))
+        return "🖼";
+    if (extension === "pdf")
+        return "📕";
+    return "📄";
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuEH,MAAM,CAAC,MAAM,aAAa,GAAmB;IAC3C,UAAU,EAAE,SAAS;IACrB,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,SAAS;IAChB,MAAM,EAAE,SAAS;IACjB,MAAM,EAAE,SAAS;IACjB,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,gDAAgD;CACvD,CAAA;AAED,MAAM,UAAU,SAAS,CAAC,KAAqB;IAC7C,OAAO;QACL,cAAc,EAAE,KAAK,CAAC,UAAU;QAChC,gBAAgB,EAAE,KAAK,CAAC,IAAI;QAC5B,gBAAgB,EAAE,KAAK,CAAC,IAAI;QAC5B,oBAAoB,EAAE,KAAK,CAAC,OAAO;QACnC,iBAAiB,EAAE,KAAK,CAAC,KAAK;QAC9B,kBAAkB,EAAE,KAAK,CAAC,MAAM;QAChC,kBAAkB,EAAE,KAAK,CAAC,MAAM;QAChC,mBAAmB,EAAE,KAAK,CAAC,OAAO;QAClC,mBAAmB,EAAE,KAAK,CAAC,OAAO;QAClC,gBAAgB,EAAE,KAAK,CAAC,IAAI;KAC7B,CAAA;AACH,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,EAAE,CAAA;IACnD,IAAI,KAAK,GAAG,IAAI;QAAE,OAAO,GAAG,KAAK,IAAI,CAAA;IACrC,IAAI,KAAK,GAAG,IAAI,GAAG,IAAI;QAAE,OAAO,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAA;IACjE,OAAO,GAAG,CAAC,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAA;AACnD,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,IAAsC;IAC5D,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAA;IACxE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAA;IACvF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAA;IAC3D,IAAI,SAAS,KAAK,KAAK;QAAE,OAAO,IAAI,CAAA;IACpC,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,IAAI,CAAA;IACnC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAA;IAC5D,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAA;IACpD,IAAI,SAAS,KAAK,KAAK;QAAE,OAAO,IAAI,CAAA;IACpC,OAAO,IAAI,CAAA;AACb,CAAC"}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@miadi/episode-ui",
+  "version": "0.1.0",
+  "description": "Host-driven React components for an episode vessel: browse its files, read one, edit one with a conflict that never loses the draft, keep a ceremony's working notes and name the artefacts a circle was held about. No component fetches, holds a URL or a token, or knows a chronicle root — files, content, capabilities and callbacks come in; intent comes out.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "style": "./src/episode-ui.css",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./styles.css": "./src/episode-ui.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@miadi/episode-vessel": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "react": "^19",
+    "react-dom": "^19",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "miadi",
+    "chronicle",
+    "episode",
+    "vessel",
+    "react",
+    "headless",
+    "file-browser",
+    "ceremony"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jgwill/Miadi.git",
+    "directory": "packages/episode-ui"
+  },
+  "bugs": {
+    "url": "https://github.com/jgwill/Miadi/issues"
+  },
+  "scripts": {
+    "build": "../../node_modules/.bin/tsc -p tsconfig.build.json",
+    "type-check": "../../node_modules/.bin/tsc -p tsconfig.build.json --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs"
+  }
+}

package/src/ceremony.tsx

@@ -0,0 +1,185 @@
+"use client"
+
+import { useEffect, useState } from "react"
+import type { CSSProperties } from "react"
+import {
+  DEFAULT_THEME,
+  themeVars,
+  type CeremonyAttachmentView,
+  type EpisodeCapabilitiesView,
+  type EpisodeUITheme,
+} from "./types.js"
+
+export interface CeremonyNoteEditorProps {
+  ceremonyId: string
+  /** Where the note lives in the vessel, shown so a person can find it later. */
+  relativePath: string
+  content: string
+  exists: boolean
+  capabilities: EpisodeCapabilitiesView
+  onSave: (content: string) => Promise<{ ok: boolean; message?: string }>
+  label?: string
+  placeholder?: string
+  theme?: EpisodeUITheme
+  className?: string
+  style?: CSSProperties
+}
+
+/**
+ * The working notes of one ceremony, kept in the episode vessel.
+ *
+ * The medicine wheel owns the ceremony record; this is what the circle wrote
+ * down, and it stays in the folder so it travels with the episode and survives
+ * a wheel that is offline. A person without `writeCeremonyNote` reads it.
+ */
+export function CeremonyNoteEditor({
+  ceremonyId,
+  relativePath,
+  content,
+  exists,
+  capabilities,
+  onSave,
+  label = "Working notes",
+  placeholder = "What should remain with this ceremony?",
+  theme = DEFAULT_THEME,
+  className,
+  style,
+}: CeremonyNoteEditorProps) {
+  const [draft, setDraft] = useState(content)
+  const [state, setState] = useState<"idle" | "saving" | "saved" | "error">("idle")
+  const [message, setMessage] = useState("")
+
+  useEffect(() => {
+    setDraft(content)
+    setState("idle")
+  }, [ceremonyId, content])
+
+  const mayWrite = capabilities.writeCeremonyNote
+
+  const save = async () => {
+    setState("saving")
+    try {
+      const outcome = await onSave(draft)
+      setState(outcome.ok ? "saved" : "error")
+      setMessage(outcome.message ?? (outcome.ok ? `Saved to ${relativePath}` : "It could not be saved."))
+    } catch (error) {
+      setState("error")
+      setMessage(error instanceof Error ? error.message : "It could not be saved.")
+    }
+  }
+
+  return (
+    <div
+      className={["ceremony-note-editor", className].filter(Boolean).join(" ")}
+      style={{ ...themeVars(theme), ...style } as CSSProperties}
+    >
+      <div className="ceremony-note-head">
+        <label className="ceremony-note-label" htmlFor={`ceremony-note-${ceremonyId}`}>
+          {label}
+        </label>
+        <span className={`ceremony-note-state is-${exists ? "saved" : "pending"}`} title={relativePath}>
+          {exists ? "notes.md" : "not saved yet"}
+        </span>
+      </div>
+      <textarea
+        id={`ceremony-note-${ceremonyId}`}
+        className="ceremony-note-field"
+        value={draft}
+        maxLength={65536}
+        readOnly={!mayWrite}
+        placeholder={mayWrite ? placeholder : undefined}
+        onChange={(event) => {
+          setDraft(event.target.value)
+          if (state !== "idle") setState("idle")
+        }}
+      />
+      {mayWrite && (
+        <div className="ceremony-note-actions">
+          <button type="button" disabled={state === "saving" || draft === content} onClick={save}>
+            Save notes
+          </button>
+          {message && (
+            <span className={`ceremony-note-message is-${state}`} role="status" aria-live="polite">
+              {message}
+            </span>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}
+
+export interface CeremonyAttachmentsProps {
+  attachments: CeremonyAttachmentView[]
+  capabilities: EpisodeCapabilitiesView
+  onOpen?: (relativePath: string) => void
+  onDetach?: (relativePath: string) => void
+  emptyLabel?: string
+  title?: string
+  theme?: EpisodeUITheme
+  className?: string
+  style?: CSSProperties
+}
+
+/**
+ * What a circle was held about.
+ *
+ * A ceremony with no attachment shows nothing rather than an empty frame — an
+ * absence stated loudly is still noise. When there are attachments, each one
+ * says who put it on the table and when, because that is the part a reader
+ * cannot reconstruct afterwards.
+ */
+export function CeremonyAttachments({
+  attachments,
+  capabilities,
+  onOpen,
+  onDetach,
+  emptyLabel,
+  title = "On the table",
+  theme = DEFAULT_THEME,
+  className,
+  style,
+}: CeremonyAttachmentsProps) {
+  if (attachments.length === 0 && !emptyLabel) return null
+
+  return (
+    <div
+      className={["ceremony-attachments", className].filter(Boolean).join(" ")}
+      style={{ ...themeVars(theme), ...style } as CSSProperties}
+    >
+      <span className="ceremony-attachments-title">{title}</span>
+      {attachments.length === 0 ? (
+        <p className="ceremony-attachments-empty">{emptyLabel}</p>
+      ) : (
+        <ul className="ceremony-attachments-list">
+          {attachments.map((item) => (
+            <li key={item.relativePath} className="ceremony-attachment">
+              <button
+                type="button"
+                className="ceremony-attachment-open"
+                disabled={!capabilities.read || !onOpen}
+                onClick={() => onOpen?.(item.relativePath)}
+              >
+                {item.relativePath}
+              </button>
+              <span className="ceremony-attachment-meta">
+                {item.attachedBy} · {item.attachedAt.slice(0, 16).replace("T", " ")}
+              </span>
+              {item.note && <span className="ceremony-attachment-note">{item.note}</span>}
+              {onDetach && capabilities.attachToCeremony && (
+                <button
+                  type="button"
+                  className="ceremony-attachment-detach"
+                  title="Take this off the table"
+                  onClick={() => onDetach(item.relativePath)}
+                >
+                  remove
+                </button>
+              )}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  )
+}