@jant/core 0.6.15 → 0.7.0

package/src/client/audio-waveform.ts

@@ -0,0 +1,49 @@
+/**
+ * Client-side Audio Waveform Extraction
+ *
+ * Decodes an audio file with the Web Audio API and samples the peaks the
+ * player draws. Image dimensions and blurhash come from `ImageProcessor`;
+ * video dimensions, poster, and blurhash come from `VideoProcessor`.
+ */
+
+/**
+ * Extract waveform peak amplitudes from an audio file.
+ * Decodes via Web Audio API and returns a JSON string of ~100 normalized peak values (0–1).
+ *
+ * @param file - Audio file to extract peaks from
+ * @returns JSON string of peak values, e.g. "[0.2,0.8,0.5,...]"
+ */
+export async function extractAudioWaveform(file: File): Promise<string> {
+  const buffer = await file.arrayBuffer();
+  const audioCtx = new AudioContext();
+
+  try {
+    const decoded = await audioCtx.decodeAudioData(buffer);
+    const raw = decoded.getChannelData(0);
+    const count = 100;
+    const step = Math.max(1, Math.floor(raw.length / count));
+    const peaks: number[] = new Array(count);
+
+    for (let i = 0; i < count; i++) {
+      let max = 0;
+      const start = i * step;
+      const end = Math.min(start + step, raw.length);
+      for (let j = start; j < end; j++) {
+        const v = Math.abs(raw[j]);
+        if (v > max) max = v;
+      }
+      peaks[i] = max;
+    }
+
+    let maxPeak = 0;
+    for (const p of peaks) if (p > maxPeak) maxPeak = p;
+    if (maxPeak > 0) {
+      for (let i = 0; i < count; i++)
+        peaks[i] = Math.round((peaks[i] / maxPeak) * 100) / 100;
+    }
+
+    return JSON.stringify(peaks);
+  } finally {
+    await audioCtx.close();
+  }
+}

package/src/client/collection-dialog-host.ts

@@ -0,0 +1,72 @@
+/**
+ * Collection dialog host.
+ *
+ * One dialog element for the whole page, mounted lazily and reused. Four
+ * places open it — the collections page toolbar, a directory row's menu, a
+ * collection page's own menu, and the navigation manager — and they all go
+ * through {@link openCollectionDialog}, because creating and editing are one
+ * surface.
+ */
+
+import "./components/jant-collection-dialog.js";
+import type { JantCollectionDialog } from "./components/jant-collection-dialog.js";
+import type {
+  CollectionDialogLabels,
+  CollectionDialogResult,
+} from "./components/collection-dialog-types.js";
+
+const LABELS_ATTRIBUTE = "data-collection-dialog-labels";
+
+let labels: CollectionDialogLabels | null = null;
+let element: JantCollectionDialog | null = null;
+
+/**
+ * The dialog's strings, rendered into the page by whichever surface can open
+ * it. Read once and cached: they are the same on every surface of a page.
+ */
+function readLabels(): CollectionDialogLabels | null {
+  if (labels) return labels;
+  const holder = document.querySelector<HTMLElement>(`[${LABELS_ATTRIBUTE}]`);
+  const raw = holder?.getAttribute(LABELS_ATTRIBUTE);
+  if (!raw) return null;
+  try {
+    labels = JSON.parse(raw) as CollectionDialogLabels;
+    return labels;
+  } catch {
+    return null;
+  }
+}
+
+function ensureElement(
+  dialogLabels: CollectionDialogLabels,
+): JantCollectionDialog {
+  if (element?.isConnected) {
+    element.labels = dialogLabels;
+    return element;
+  }
+  element = document.createElement(
+    "jant-collection-dialog",
+  ) as JantCollectionDialog;
+  element.labels = dialogLabels;
+  document.body.appendChild(element);
+  return element;
+}
+
+/**
+ * Open the collection dialog.
+ *
+ * @param options.collectionId - Edit this one; omit to create a new one
+ * @returns What happened, and the collection when one was saved
+ * @example
+ * const { changed } = await openCollectionDialog({ collectionId: "col_…" });
+ */
+export async function openCollectionDialog(
+  options: {
+    collectionId?: string;
+  } = {},
+): Promise<CollectionDialogResult> {
+  const dialogLabels = readLabels();
+  if (!dialogLabels) return { changed: false };
+
+  return ensureElement(dialogLabels).open(options);
+}

package/src/client/collection-navigation.ts

@@ -9,16 +9,14 @@ const SITE_HEADER_REQUEST_HEADER = "X-Jant-Site-Header";
 const INCLUDE_SITE_HEADER_RESPONSE = "include";
 
 /**
- * Add a Collection to the end of the primary navigation and refresh the
- * rendered site header when the server returns a fragment.
+ * Create a navigation item and refresh the rendered site header when the
+ * server returns a fragment.
  *
- * @param collectionId - TypeID of the Collection to add
+ * @param body - Request body for `POST /api/nav-items`
  * @returns The created navigation item ID when present
- * @example
- * const navItemId = await addCollectionToNavigation("col_01abc");
  */
-export async function addCollectionToNavigation(
-  collectionId: string,
+async function createNavItem(
+  body: Record<string, unknown>,
 ): Promise<string | undefined> {
   const response = await fetch("/api/nav-items", {
     method: "POST",
@@ -27,18 +25,55 @@ export async function addCollectionToNavigation(
       Accept: "application/json",
       [SITE_HEADER_REQUEST_HEADER]: INCLUDE_SITE_HEADER_RESPONSE,
     },
-    body: JSON.stringify({
-      type: "collection",
-      collectionId,
-      placement: "header",
-    }),
+    body: JSON.stringify(body),
   });
-  const body = await readJsonObject(response);
+  const responseBody = await readJsonObject(response);
 
   if (!response.ok) {
-    throw new Error(getJsonString(body, "error") ?? `HTTP ${response.status}`);
+    throw new Error(
+      getJsonString(responseBody, "error") ?? `HTTP ${response.status}`,
+    );
   }
 
-  applySiteHeaderHtml(getJsonString(body, "headerHtml"));
-  return getJsonString(body, "id");
+  applySiteHeaderHtml(getJsonString(responseBody, "headerHtml"));
+  return getJsonString(responseBody, "id");
+}
+
+/**
+ * Add a Collection to the end of the primary navigation and refresh the
+ * rendered site header when the server returns a fragment.
+ *
+ * @param collectionId - TypeID of the Collection to add
+ * @returns The created navigation item ID when present
+ * @example
+ * const navItemId = await addCollectionToNavigation("col_01abc");
+ */
+export async function addCollectionToNavigation(
+  collectionId: string,
+): Promise<string | undefined> {
+  return createNavItem({
+    type: "collection",
+    collectionId,
+    placement: "header",
+  });
+}
+
+/**
+ * Add a smart collection to the end of the primary navigation. Placement
+ * matches {@link addCollectionToNavigation} — the two kinds are one thing to
+ * the reader, so the same action puts them in the same place.
+ *
+ * @param smartCollectionId - TypeID of the smart collection to add
+ * @returns The created navigation item ID when present
+ * @example
+ * const navItemId = await addSmartCollectionToNavigation("smc_01abc");
+ */
+export async function addSmartCollectionToNavigation(
+  smartCollectionId: string,
+): Promise<string | undefined> {
+  return createNavItem({
+    type: "smart_collection",
+    smartCollectionId,
+    placement: "header",
+  });
 }

package/src/client/collection-page-actions.ts

@@ -1,5 +1,6 @@
 import { getCollectionsDirectoryPath } from "../lib/collection-paths.js";
 import { NAVIGATION_SETTINGS_PATH } from "../lib/settings-paths.js";
+import { openCollectionDialog } from "./collection-dialog-host.js";
 import { addCollectionToNavigation } from "./collection-navigation.js";
 import { showConfirmDialog } from "./confirm.js";
 import { showToast, showToastWithAction } from "./toast.js";
@@ -95,6 +96,27 @@ document
       }
     };
 
+    const handleEdit = async () => {
+      closeMenu(false);
+      const { changed, collection } = await openCollectionDialog({
+        collectionId,
+      });
+      if (!changed) return;
+
+      // The address can have moved, and the old one stops resolving the moment
+      // it does — so the page follows it rather than reloading into a 404.
+      // Only the last segment changes: whatever site or language prefix this
+      // reader arrived under is theirs to keep.
+      const nextPath = collection?.slug
+        ? window.location.pathname.replace(/[^/]*$/, collection.slug)
+        : null;
+      if (nextPath && nextPath !== window.location.pathname) {
+        window.location.href = `${nextPath}${window.location.search}`;
+        return;
+      }
+      window.location.reload();
+    };
+
     const handleDelete = async () => {
       closeMenu(false);
 
@@ -197,6 +219,10 @@ document
       if (!actionEl || !root.contains(actionEl)) return;
 
       const action = actionEl.dataset.collectionPageAction;
+      if (action === "edit") {
+        event.preventDefault();
+        void handleEdit();
+      }
       if (action === "delete") {
         event.preventDefault();
         void handleDelete();

package/src/client/components/__tests__/compose-format-convert.test.ts

@@ -55,7 +55,6 @@ describe("convertComposeFormat", () => {
       "quote",
       fields({
         title: "My thoughts",
-        showTitle: true,
         bodyJson: doc(paragraph("body")),
       }),
     );
@@ -216,7 +215,6 @@ describe("convertComposeFormat", () => {
       "link",
       fields({
         title: "Keep me",
-        showTitle: true,
         bodyJson: doc(paragraph("body")),
       }),
     );
@@ -236,7 +234,6 @@ describe("convertComposeFormat", () => {
       }),
     );
     expect(result.title).toBe("Keep me");
-    expect(result.showTitle).toBe(true);
     expect(result.url).toBe("");
     expect(firstBlock(result)).toEqual({
       type: "paragraph",
@@ -317,22 +314,6 @@ describe("convertComposeFormat", () => {
     expect(result.bodyJson).toBeNull();
   });
 
-  it("sets showTitle only for a note that ends up with a title", () => {
-    const toNote = convertComposeFormat(
-      "link",
-      "note",
-      fields({ title: "T", url: "https://example.com" }),
-    );
-    expect(toNote.showTitle).toBe(true);
-
-    const toQuote = convertComposeFormat(
-      "note",
-      "quote",
-      fields({ title: "T" }),
-    );
-    expect(toQuote.showTitle).toBe(false);
-  });
-
   it("treats a non-attribution last line as part of the quote text", () => {
     const result = convertComposeFormat(
       "note",

package/src/client/components/__tests__/jant-collection-dialog.test.ts

@@ -0,0 +1,329 @@
+// @vitest-environment happy-dom
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../../toast.js", () => ({
+  showToast: vi.fn(),
+  showToastWithAction: vi.fn(),
+}));
+
+vi.mock("../../lazy-slugify.js", () => ({
+  slugify: (text: string) =>
+    Promise.resolve(
+      text
+        .toLowerCase()
+        .trim()
+        .replace(/[^\w\s-]/g, "")
+        .replace(/[\s_-]+/g, "-")
+        .replace(/^-+|-+$/g, ""),
+    ),
+  preloadSlug: () => {},
+}));
+
+// happy-dom has no contenteditable, so the description editor is stood in for.
+let editorContent: string | undefined;
+vi.mock("../../tiptap/create-editor.js", () => ({
+  createSettingsEditor: (opts: { element: HTMLElement; content?: string }) => {
+    editorContent = opts.content;
+    opts.element.innerHTML =
+      '<div class="ProseMirror" contenteditable="true"></div>';
+    return {
+      getJSON: () => ({ type: "doc", content: [] }),
+      destroy: () => {},
+    };
+  },
+  jsonToMarkdown: () => "",
+}));
+
+import "../jant-collection-dialog.js";
+import type { JantCollectionDialog } from "../jant-collection-dialog.js";
+import type { CollectionDialogLabels } from "../collection-dialog-types.js";
+
+/**
+ * The dialog is now the only place a collection is written, so what it has to
+ * hold is what the editor page used to: an address derived from the title and
+ * checked against the server, a warning before an existing link moves, and a
+ * save that reports where the collection ended up.
+ */
+
+const labels: CollectionDialogLabels = {
+  createHeading: "New Collection",
+  editHeading: "Edit Collection",
+  title: "Title",
+  titlePlaceholder: "My Collection",
+  link: "Collection link",
+  linkHelp: "This is the last part of the collection link.",
+  editLink: "Edit link",
+  resetLink: "Reset link",
+  linkTaken: "This link is taken. Choose another.",
+  linkInvalid: "Use lowercase letters, numbers, and hyphens only.",
+  linkReserved: "This link is reserved. Choose something else.",
+  linkTooLong: "Keep this link under 200 characters.",
+  linkMovesWarning: "Changing the link breaks the old one immediately.",
+  description: "Description (optional)",
+  descriptionPlaceholder: "What's this collection about?",
+  orderBy: "Order by",
+  sortOptions: {
+    newest: "Newest first",
+    oldest: "Oldest first",
+    rating_desc: "Highest rated",
+  },
+  cancel: "Cancel",
+  save: "Save",
+  saved: "Collection saved.",
+  saveFailed: "Couldn't save. Try again in a moment.",
+  loadFailed: "Could not open this collection. Try again.",
+  titleAndLinkRequired: "A collection needs a title and a link.",
+};
+
+/** Responses the dialog's fetches get, keyed by the path they hit. */
+let responses: Record<string, { ok?: boolean; body: unknown }>;
+let requests: Array<{ url: string; method: string; body: unknown }>;
+
+function mountDialog(): JantCollectionDialog {
+  const element = document.createElement(
+    "jant-collection-dialog",
+  ) as JantCollectionDialog;
+  element.labels = labels;
+  document.body.appendChild(element);
+  return element;
+}
+
+/** Let the debounced address check and the slugify round trip settle. */
+async function settle(element: JantCollectionDialog) {
+  await vi.advanceTimersByTimeAsync(400);
+  await element.updateComplete;
+}
+
+function findButton(
+  element: JantCollectionDialog,
+  text: string,
+): HTMLButtonElement | undefined {
+  return [...element.querySelectorAll("button")].find(
+    (button) => button.textContent?.trim() === text,
+  );
+}
+
+async function typeTitle(element: JantCollectionDialog, value: string) {
+  const input = element.querySelector<HTMLInputElement>("[data-field='title']");
+  if (!input) throw new Error("Expected the title field");
+  input.value = value;
+  input.dispatchEvent(new Event("input", { bubbles: true }));
+  await settle(element);
+}
+
+beforeEach(() => {
+  document.body.innerHTML = "";
+  vi.useFakeTimers();
+  editorContent = undefined;
+
+  responses = {
+    "/api/collections/slug": { body: { slug: "reading", available: true } },
+    "/api/collections": { body: { id: "col_new", slug: "reading" } },
+    "/api/collections/col_books": {
+      body: {
+        id: "col_books",
+        slug: "books",
+        title: "Books",
+        description: "Notes from books",
+        sortOrder: "oldest",
+      },
+    },
+  };
+  requests = [];
+
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string, init?: globalThis.RequestInit) => {
+      const path = url.split("?")[0] ?? url;
+      requests.push({
+        url,
+        method: init?.method ?? "GET",
+        body: init?.body ? JSON.parse(String(init.body)) : undefined,
+      });
+      const response = responses[path] ?? { body: {} };
+      return {
+        ok: response.ok ?? true,
+        status: response.ok === false ? 400 : 200,
+        json: async () => response.body,
+      } as Response;
+    }),
+  );
+
+  // happy-dom's <dialog> has no modal implementation.
+  HTMLDialogElement.prototype.showModal = function showModal() {
+    this.open = true;
+  };
+  HTMLDialogElement.prototype.close = function close() {
+    this.open = false;
+  };
+});
+
+describe("JantCollectionDialog", () => {
+  it("opens on the create heading with nothing filled in", async () => {
+    const element = mountDialog();
+    void element.open({});
+    await settle(element);
+
+    expect(element.textContent).toContain("New Collection");
+    expect(
+      element.querySelector<HTMLInputElement>("[data-field='title']")?.value,
+    ).toBe("");
+    // The link only appears once there is one to show.
+    expect(element.querySelector(".collection-quick-link-box")).toBeNull();
+  });
+
+  it("derives the address from the title and asks whether it is free", async () => {
+    const element = mountDialog();
+    void element.open({});
+    await settle(element);
+    await typeTitle(element, "Reading");
+
+    expect(
+      element.querySelector<HTMLElement>(".collection-quick-link-preview")
+        ?.textContent,
+    ).toContain("/reading");
+    expect(
+      requests.some(
+        (request) =>
+          request.url.includes("/api/collections/slug") &&
+          request.url.includes("slug=reading"),
+      ),
+    ).toBe(true);
+  });
+
+  it("refuses to save onto an address something else already holds", async () => {
+    responses["/api/collections/slug"] = {
+      body: { slug: "reading", available: false },
+    };
+    const element = mountDialog();
+    void element.open({});
+    await settle(element);
+    await typeTitle(element, "Reading");
+
+    expect(element.textContent).toContain(
+      "This link is taken. Choose another.",
+    );
+    expect(findButton(element, "Save")?.disabled).toBe(true);
+  });
+
+  it("loads an existing collection, and warns before its link moves", async () => {
+    const element = mountDialog();
+    void element.open({ collectionId: "col_books" });
+    await settle(element);
+
+    expect(element.textContent).toContain("Edit Collection");
+    expect(
+      element.querySelector<HTMLInputElement>("[data-field='title']")?.value,
+    ).toBe("Books");
+    const sortSelect = element.querySelector(
+      "[data-field='sort']",
+    ) as HTMLSelectElement | null;
+    expect(sortSelect?.value).toBe("oldest");
+    expect(editorContent).toBe("Notes from books");
+    expect(element.textContent).not.toContain(
+      "Changing the link breaks the old one immediately.",
+    );
+
+    findButton(element, "Edit link")?.click();
+    await element.updateComplete;
+    const slugInput = element.querySelector<HTMLInputElement>(
+      "[data-field='slug']",
+    );
+    if (!slugInput) throw new Error("Expected the link field");
+    slugInput.value = "reading";
+    slugInput.dispatchEvent(new Event("input", { bubbles: true }));
+    await settle(element);
+
+    expect(element.textContent).toContain(
+      "Changing the link breaks the old one immediately.",
+    );
+  });
+
+  it("creates a collection and reports where it landed", async () => {
+    const element = mountDialog();
+    const result = element.open({});
+    await settle(element);
+    await typeTitle(element, "Reading");
+
+    findButton(element, "Save")?.click();
+    await settle(element);
+
+    const save = requests.find((request) => request.method === "POST");
+    expect(save?.url).toContain("/api/collections");
+    expect(save?.body).toEqual({
+      slug: "reading",
+      title: "Reading",
+      sortOrder: "newest",
+    });
+    await expect(result).resolves.toEqual({
+      changed: true,
+      collection: { id: "col_new", slug: "reading", title: "Reading" },
+    });
+  });
+
+  it("saves an edit with PUT, and clears a description that was emptied", async () => {
+    responses["/api/collections/col_books"] = {
+      body: {
+        id: "col_books",
+        slug: "books",
+        title: "Books",
+        description: "Notes from books",
+        sortOrder: "newest",
+      },
+    };
+    const element = mountDialog();
+    void element.open({ collectionId: "col_books" });
+    await settle(element);
+
+    findButton(element, "Save")?.click();
+    await settle(element);
+
+    const save = requests.find((request) => request.method === "PUT");
+    expect(save?.url).toContain("/api/collections/col_books");
+    // The stubbed editor round-trips to an empty document, so the edit is
+    // clearing the description — which only an explicit null can do.
+    expect(save?.body).toEqual({
+      slug: "books",
+      title: "Books",
+      sortOrder: "newest",
+      description: null,
+    });
+  });
+
+  it("keeps a failed save open, with the reason the server gave", async () => {
+    responses["/api/collections"] = {
+      ok: false,
+      body: { error: "That link is reserved." },
+    };
+    const element = mountDialog();
+    void element.open({});
+    await settle(element);
+    await typeTitle(element, "Reading");
+
+    findButton(element, "Save")?.click();
+    await settle(element);
+
+    expect(element.textContent).toContain("That link is reserved.");
+    expect(
+      element.querySelector<HTMLDialogElement>(".collection-dialog")?.open,
+    ).toBe(true);
+  });
+
+  it("closes on Escape without saving", async () => {
+    const element = mountDialog();
+    const result = element.open({});
+    await settle(element);
+    await typeTitle(element, "Reading");
+
+    element
+      .querySelector<HTMLInputElement>("[data-field='title']")
+      ?.dispatchEvent(
+        new KeyboardEvent("keydown", { key: "Escape", bubbles: true }),
+      );
+    await element.updateComplete;
+
+    await expect(result).resolves.toEqual({ changed: false });
+    expect(requests.some((request) => request.method === "POST")).toBe(false);
+  });
+});