@jxsuite/studio 2.0.0 → 2.1.0

package/src/editor/slash-menu.ts

@@ -174,6 +174,7 @@ function render(showFilter: boolean) {
     html`
       <sp-popover
         open
+        data-jx-region="overlay.menu:slash-menu"
         ${ref((el) => {
           _popoverEl = (el as HTMLElement | undefined) || null;
         })}

package/src/files/elements.ts

@@ -0,0 +1,166 @@
+/**
+ * Elements.ts — what belongs in a document's (or a project's) `$elements`, decided once.
+ *
+ * `$elements` is the list of component modules a document may use. Three surfaces wrote it, each
+ * with its own idea of what "already imported" means, and plan §11.2 names all three: the Packages
+ * panel's cherry-pick checkboxes, its "Add component…" picker, and the automatic push when a
+ * component is dropped on the canvas. "One `enableElement()` / `disableElement()` service behind
+ * all three. Today the same array is written three ways with no shared UI and no shared
+ * validation."
+ *
+ * They really did disagree. The canvas drop matched a local component by `ref.endsWith(basename)`,
+ * so `./components/card.json` counted `./vendor/card.json` as already imported and the drop
+ * silently produced an element the page could not resolve. The picker checked nothing at all and
+ * pushed a duplicate `$ref` every time you chose the same component twice. Only the checkbox knew
+ * that a legacy full-package entry (`@acme/ui`) satisfies a cherry-picked one (`@acme/ui/card`), so
+ * enabling one component through the picker left the package-wide import beside it.
+ *
+ * **Pure functions over the array.** They return the new list rather than writing it, because the
+ * two levels persist differently and genuinely should: a document's `$elements` goes through
+ * `transact` and is undoable, and the project's goes through `updateSiteConfig` and is not. What
+ * they must not differ on is WHICH entries the list should hold.
+ */
+
+import { computeRelativePath } from "./components";
+import type { ComponentEntry } from "./components";
+import type { JxElement } from "@jxsuite/schema/types";
+
+/** One `$elements` entry: an npm specifier, or a `$ref` to a file in this project. */
+export type ElementsEntry = string | JxElement | { $ref: string };
+
+/** The `$ref` of an entry, when it has one. */
+function refOf(entry: ElementsEntry): string | null {
+  return typeof entry === "object" && entry !== null && typeof entry.$ref === "string"
+    ? entry.$ref
+    : null;
+}
+
+/**
+ * The npm specifier a component is imported by — its cherry-picked subpath, or the bare package.
+ *
+ * `null` for a project-local component, which is imported by path instead.
+ */
+export function npmSpecifier(comp: ComponentEntry): string | null {
+  if (comp.source !== "npm" || !comp.package) {
+    return null;
+  }
+  return comp.modulePath ? `${comp.package}/${comp.modulePath}` : comp.package;
+}
+
+/**
+ * The entry that imports `comp` into a document at `fromPath`.
+ *
+ * `null` when the component can be named neither way — an npm entry with no package, or a local one
+ * with no path — which is a registry the caller should not be writing from.
+ */
+export function elementsEntryFor(
+  comp: ComponentEntry,
+  fromPath: string | null,
+): ElementsEntry | null {
+  const specifier = npmSpecifier(comp);
+  if (specifier) {
+    return specifier;
+  }
+  return comp.path ? { $ref: computeRelativePath(fromPath, comp.path) } : null;
+}
+
+/**
+ * Is `comp` already imported by this list?
+ *
+ * ONE rule, and it is the union of what the three call sites each knew separately:
+ *
+ * - An npm component matches its cherry-picked specifier **or** a legacy whole-package entry;
+ * - A local component matches a `$ref` that resolves to the same file, compared on the resolved path
+ *   rather than on its last segment — `endsWith("card.json")` called two different cards the same
+ *   component, and the drop that trusted it produced an unresolvable element.
+ */
+export function hasElement(
+  elements: readonly ElementsEntry[],
+  comp: ComponentEntry,
+  fromPath: string | null,
+): boolean {
+  const specifier = npmSpecifier(comp);
+  if (specifier) {
+    return elements.some(
+      (entry) => typeof entry === "string" && (entry === specifier || entry === comp.package),
+    );
+  }
+  if (!comp.path) {
+    return false;
+  }
+  const wanted = normalizeRef(computeRelativePath(fromPath, comp.path));
+  return elements.some((entry) => {
+    const ref = refOf(entry);
+    return ref !== null && normalizeRef(ref) === wanted;
+  });
+}
+
+/** A `$ref` reduced to a comparable form: `./a/b.json`, `a/b.json` and `././a/b.json` are one file. */
+function normalizeRef(ref: string): string {
+  return ref.replace(/^(?:\.\/)+/, "");
+}
+
+/**
+ * Import `comp`, and return the new list. Idempotent, and it drops what the new entry supersedes.
+ *
+ * Enabling a cherry-picked npm component removes the whole-package entry it replaces — otherwise
+ * the page keeps pulling in every component of that package while the panel shows one ticked.
+ */
+export function enableElement(
+  elements: readonly ElementsEntry[],
+  comp: ComponentEntry,
+  fromPath: string | null,
+): ElementsEntry[] {
+  const entry = elementsEntryFor(comp, fromPath);
+  if (!entry) {
+    return [...elements];
+  }
+  const specifier = npmSpecifier(comp);
+  // The legacy whole-package import goes when a cherry-picked one arrives — but never when the
+  // Component IS the package (`modulePath` absent), where the two are the same entry.
+  const kept =
+    specifier && comp.modulePath ? elements.filter((e) => e !== comp.package) : [...elements];
+  return hasElement(kept, comp, fromPath) ? kept : [...kept, entry];
+}
+
+/** Remove `comp`'s import, and return the new list. Idempotent. */
+export function disableElement(
+  elements: readonly ElementsEntry[],
+  comp: ComponentEntry,
+  fromPath: string | null,
+): ElementsEntry[] {
+  const specifier = npmSpecifier(comp);
+  if (specifier) {
+    // Both spellings: a component ticked off must not stay imported through the package entry.
+    return elements.filter(
+      (entry) => !(typeof entry === "string" && (entry === specifier || entry === comp.package)),
+    );
+  }
+  if (!comp.path) {
+    return [...elements];
+  }
+  const wanted = normalizeRef(computeRelativePath(fromPath, comp.path));
+  return elements.filter((entry) => {
+    const ref = refOf(entry);
+    return ref === null || normalizeRef(ref) !== wanted;
+  });
+}
+
+/** Remove every entry belonging to `pkg` — what uninstalling a package leaves behind. */
+export function removePackageElements(
+  elements: readonly ElementsEntry[],
+  pkg: string,
+): ElementsEntry[] {
+  return elements.filter(
+    (entry) => typeof entry !== "string" || !(entry === pkg || entry.startsWith(`${pkg}/`)),
+  );
+}
+
+/** Remove the entry naming `ref` exactly — the Packages panel's per-row × on a local import. */
+export function removeElementRef(elements: readonly ElementsEntry[], ref: string): ElementsEntry[] {
+  const wanted = normalizeRef(ref);
+  return elements.filter((entry) => {
+    const found = refOf(entry);
+    return found === null || normalizeRef(found) !== wanted;
+  });
+}

package/src/files/file-ops.ts

@@ -1,20 +1,33 @@
 /// <reference lib="dom" />
 /**
- * File Operations — open, save, export documents.
+ * File Operations — open, save, export documents, and confirm the destructive ones.
  *
  * All functions read/write directly from/to `activeTab.value` (the reactive tab). `.json` is the
  * native document format; every other extension dispatches through the project's format registry
  * (parse to open, serialize to save).
+ *
+ * {@link confirmFileDelete} and {@link renamePromptMessage} live here because a delete and a rename
+ * are the same question asked twice — "what does this break?" — and the answer was missing from
+ * both. Every surface that removes or moves a file routes its confirmation through them, so no
+ * caller can ship a destructive dialog that grades only by reversibility again.
+ *
+ * @docs studio/projects/pages-layouts-components
  */
 
+import { html, nothing } from "lit-html";
+import { loadUsages, usageWarning } from "../services/references";
+import { isMediaFile } from "./media-upload";
+import { loadMediaUsages } from "./media-usage";
+import { showConfirmDialog } from "../ui/layers";
 import { locateDocument } from "../services/code-services";
 import { errorMessage } from "@jxsuite/schema/parse";
-import { statusMessage } from "../panels/statusbar";
+import { noteDocumentSaved } from "../panels/statusbar";
+import { notify } from "../services/notify";
 import { validateComponentSlots } from "../services/cem-export";
 import { getPlatform } from "../platform";
 import { getGridController } from "../grid/grid-controller";
 import { activeTab, openTab } from "../workspace/workspace";
-import { collabSave } from "../collab/collab-session";
+import { collabReadOnly, collabSave } from "../collab/collab-session";
 import { flushCanvasEdits } from "../canvas/iframe-host";
 import {
   defaultContentFormat,
@@ -29,6 +42,7 @@ import {
 } from "../format/format-host";
 import type { StudioFormat } from "../format/format-host";
 import type { Tab } from "../tabs/tab.js";
+import { mediaTypeEssence } from "@jxsuite/schema/media-type";
 
 /**
  * Parse a format-class source string into document + frontmatter + mode per the format's
@@ -73,7 +87,9 @@ export async function openFile() {
       ...formats
         .filter((f) => f.capabilities.parse)
         .map((f) => ({
-          accept: { [f.mediaType ?? "text/plain"]: f.extensions },
+          // The essence, not the declared type: a File System Access `accept` key is a bare
+          // MIME type, and `text/markdown; variant=GFM` is not one.
+          accept: { [mediaTypeEssence(f.mediaType) ?? "text/plain"]: f.extensions },
           description: f.name,
         })),
     ];
@@ -102,7 +118,8 @@ export async function openFile() {
       } else {
         throw noFormatError(name);
       }
-      statusMessage(`Opened ${name}`);
+      // Opening a file is stated permanently by the tab strip and the status bar's DOCUMENT
+      // Field; it does not need a message that erases itself.
     };
 
     if ("showOpenFilePicker" in window) {
@@ -128,37 +145,67 @@ export async function openFile() {
       input.click();
     }
   } catch (error) {
+    // A cancelled file picker is not a failure — the user withdrew the request.
     if (!(error instanceof Error && error.name === "AbortError")) {
-      statusMessage(`Error: ${errorMessage(error)}`);
+      notify.error("Could not open the file.", {
+        detail: errorMessage(error),
+        source: "Open File",
+      });
     }
   }
 }
 
 /**
- * Report a slot-validation warning for component documents (root tagName with a hyphen). The save
- * still proceeds — the warning replaces the plain success message.
+ * Record a successful write, and raise the slot-validation warning component documents can carry.
  *
- * @param {Tab} tab
- * @param {string} savedMsg
+ * The success half no longer notifies at ALL. "Saved" is ambient state: the status bar's DOCUMENT
+ * field says "Saved 2m ago" for as long as it is true, which is strictly more information than a
+ * message that said it once and erased itself — and it is the field a reader looks at to ask the
+ * question in the first place.
+ *
+ * The warning half became a PROBLEM. A component whose slots do not line up is a thing to fix, and
+ * it was previously shown for six seconds in the same grey as the word "Saved".
  */
-function savedMessage(tab: Tab, savedMsg: string) {
+function reportSaved(tab: Tab) {
+  noteDocumentSaved(tab.documentPath);
   const doc = tab.doc.document;
   const warning =
     typeof doc.tagName === "string" && doc.tagName.includes("-")
       ? validateComponentSlots(doc)
       : null;
   if (warning) {
-    statusMessage(`${savedMsg} — Warning: ${warning}`, 6000);
-  } else {
-    statusMessage(savedMsg);
+    notify.warn(warning, {
+      key: `slots:${tab.documentPath ?? tab.id}`,
+      ...(tab.documentPath === null ? {} : { path: tab.documentPath }),
+      source: "Components",
+      tier: "problem",
+    });
   }
 }
 
-/** Save the current document back to its source location. */
-export async function saveFile() {
-  const tab = activeTab.value;
+/**
+ * Save a document back to its source location. Defaults to the focused tab.
+ *
+ * Two things here are for the tab strip's Save-on-close, and both are what a caller that must
+ * decide something afterwards needs:
+ *
+ * - `tab` is a PARAMETER. The × on a tab closes that tab, focused or not, and reading
+ *   `activeTab.value` would have saved a different document than the one being closed.
+ * - The return value says whether the work reached disk. Every failure in here is reported to the
+ *   user and swallowed, which is right for ⌘S and useless to a caller that would otherwise close
+ *   the tab on top of the failure.
+ *
+ * **A read-only collaborator has no save target, and that is a refusal rather than a fallback.**
+ * Their edits never reached the Y-doc, so there is nothing for the provider to flush; and the local
+ * file is the ROOM's file, so writing it here would fork the shared document behind the owner's
+ * back. Both "saved" and "written anyway" are wrong answers, so the answer is `false` with the
+ * reason said out loud.
+ *
+ * @returns Whether the document was persisted.
+ */
+export async function saveFile(tab: Tab | null = activeTab.value): Promise<boolean> {
   if (!tab) {
-    return;
+    return false;
   }
   // Text reaches the document on an idle tick, so the words still sitting in the caret's block have
   // To be committed before anything serializes it. This used to be `if (isEditing()) stopEditing()`,
@@ -166,17 +213,40 @@ export async function saveFile() {
   // Realm's copy of that module, where a session never starts. Saving mid-sentence silently wrote
   // The file without the sentence.
   await flushCanvasEdits(tab.id);
+  /* THE REFUSAL COMES FIRST, and it used to come second.
+     `ensureCollab` attaches a session to every tab with a `documentPath` except `project.json` —
+     `.csv` included, and a `.csv` tab is exactly the kind `grid-panel.ts` provisions a controller
+     for. So a read-only collaborator on a co-edited sheet took the grid branch above this line,
+     `grid.save()` wrote the ROOM's file to disk behind the owner's back, and `!tab.doc.dirty`
+     reported it as a save — the precise outcome the paragraph above says this function prevents.
+     A refusal that any earlier branch can step in front of is not a refusal, so nothing may
+     precede it except `flushCanvasEdits`, which commits the caret's block and writes nothing. */
+  if (collabReadOnly(tab)) {
+    notify.warn(
+      `You have read access to this session — changes to ${tab.documentPath ?? "this document"} ` +
+        `stay in your browser and cannot be saved.`,
+      {
+        action: "file.save",
+        key: `save.readOnly:${tab.documentPath ?? tab.id}`,
+        ...(tab.documentPath === null ? {} : { path: tab.documentPath }),
+        source: "Collaboration",
+      },
+    );
+    return false;
+  }
   // Grid tabs batch-save through their controller (per-source commit semantics, not a doc write).
   const grid = getGridController(tab);
   if (grid) {
     await grid.save();
-    return;
+    // A batch commit keeps failed rows dirty and mirrors that onto the tab, so the buffer's own
+    // Verdict is the answer — there is nothing more honest to report here.
+    return !tab.doc.dirty;
   }
   try {
     // A co-edited tab persists through its provider (a direct file write would reset the room).
     if (await collabSave(tab)) {
-      savedMessage(tab, "Synced");
-      return;
+      reportSaved(tab);
+      return true;
     }
     const output = await serializeDocument(tab);
 
@@ -184,8 +254,10 @@ export async function saveFile() {
       const platform = getPlatform();
       await platform.writeFile(tab.documentPath, output);
       tab.doc.dirty = false;
-      savedMessage(tab, "Saved");
-    } else if (tab.fileHandle && "createWritable" in tab.fileHandle) {
+      reportSaved(tab);
+      return true;
+    }
+    if (tab.fileHandle && "createWritable" in tab.fileHandle) {
       const writable =
         await /**
          * @type {{
@@ -198,15 +270,22 @@ export async function saveFile() {
       await writable.write(output);
       await writable.close();
       tab.doc.dirty = false;
-      savedMessage(tab, "Saved");
-    } else {
-      statusMessage("No save target — use Export");
+      reportSaved(tab);
+      return true;
     }
+    notify.warn("This document has no save target — use Export.", { key: "save.noTarget" });
   } catch (error) {
     if (!(error instanceof Error && error.name === "AbortError")) {
-      statusMessage(`Save error: ${errorMessage(error)}`);
+      notify.error(`Could not save ${tab.documentPath ?? tab.id}.`, {
+        action: "file.save",
+        detail: errorMessage(error),
+        key: `save:${tab.documentPath ?? tab.id}`,
+        ...(tab.documentPath === null ? {} : { path: tab.documentPath }),
+        source: "Save",
+      });
     }
   }
+  return false;
 }
 
 /** The output format for a tab: its source format, or the default content format. */
@@ -227,7 +306,9 @@ export async function exportFile() {
     await loadFormats();
     const format = tabFormat(tab);
     const output = await serializeDocument(tab);
-    const mimeType = format ? (format.mediaType ?? "text/plain") : "application/json";
+    const mimeType = format
+      ? (mediaTypeEssence(format.mediaType) ?? "text/plain")
+      : "application/json";
     const ext = format ? format.extensions[0] : ".json";
     const description = format ? format.name : "Jx Component";
     const fallbackName = format ? `content${ext}` : "component.json";
@@ -246,7 +327,8 @@ export async function exportFile() {
       await writable.write(output);
       await writable.close();
       tab.doc.dirty = false;
-      savedMessage(tab, `Exported as ${handle.name}`);
+      reportSaved(tab);
+      notify.success(`Exported as ${handle.name}.`);
     } else {
       // Fallback: download
       const blob = new Blob([output], { type: mimeType });
@@ -257,11 +339,15 @@ export async function exportFile() {
       a.click();
       URL.revokeObjectURL(url);
       tab.doc.dirty = false;
-      savedMessage(tab, "Downloaded");
+      reportSaved(tab);
+      notify.success(`Downloaded ${fallbackName}.`);
     }
   } catch (error) {
     if (!(error instanceof Error && error.name === "AbortError")) {
-      statusMessage(`Export error: ${errorMessage(error)}`);
+      notify.error("Could not export the document.", {
+        detail: errorMessage(error),
+        source: "Export",
+      });
     }
   }
 }
@@ -303,3 +389,64 @@ export async function serializeDocument(tab: Tab): Promise<string> {
   }
   return JSON.stringify(tab.doc.document, null, 2);
 }
+
+// ─── Destructive confirmations ───────────────────────────────────────────────
+
+/**
+ * The reference sentence a destructive dialog carries, or `nothing` when the host cannot count.
+ *
+ * The query is awaited BEFORE the dialog opens rather than rendered into it and filled in later: a
+ * confirm button that becomes truthful two frames after the user has already pressed it is the same
+ * defect as not counting at all.
+ *
+ * **A media file is asked about through the media index, and that is not a refinement.** The
+ * generic sweep compares each authored reference's RESOLVED path to the path it was asked about,
+ * and a media file's authored ref usually resolves somewhere else: `public/hero.jpg` is written
+ * `/hero.jpg` and resolves to `hero.jpg`; an asset inside a collection whose `source` is not
+ * already `content/<type>/` is addressed at its asset mount and resolves under that prefix. Asking
+ * the generic index about the file on disk returns a confident zero for both, which is the one
+ * answer a delete dialog must never invent. `media-usage.ts` asks every authored form and unions
+ * the answers — and reports **unknown** when a lane cannot be counted, rather than totalling the
+ * lanes that could.
+ *
+ * @param path — the file about to be deleted or renamed.
+ * @param verb — which way the references go. A rename repairs them; a delete breaks them.
+ */
+async function usageLine(path: string, verb: "delete" | "rename") {
+  const state = isMediaFile(path) ? await loadMediaUsages(path) : await loadUsages({ path });
+  const sentence = usageWarning(state, verb);
+  return sentence === null ? nothing : html`<p class="dialog-consequence">${sentence}</p>`;
+}
+
+/**
+ * Confirm deleting a file, stating what it breaks and what survives.
+ *
+ * @param file — its display name and project-relative path.
+ * @returns Whether the user confirmed.
+ */
+export async function confirmFileDelete(file: { name: string; path: string }): Promise<boolean> {
+  const consequence = await usageLine(file.path, "delete");
+  // `showDialog`'s generic widens to unknown through the confirm wrapper; the dialog only ever
+  // Resolves true/false, and Boolean() is the narrowing that says so without a cast.
+  return Boolean(
+    await showConfirmDialog(
+      "Delete File",
+      html`<span>Delete <strong>${file.name}</strong>? This cannot be undone.</span>${consequence}`,
+      { confirmLabel: "Delete", destructive: true },
+    ),
+  );
+}
+
+/**
+ * The explanatory copy above a rename field — where the file's references go when it moves.
+ *
+ * A rename is not a delete and must not read like one: the refactor pass rewrites every reference
+ * it finds, so the honest sentence is "N references will be updated automatically", and the count
+ * is there to say how much work is silently being done on the user's behalf.
+ *
+ * @param path — the file about to be renamed.
+ */
+export async function renamePromptMessage(path: string) {
+  const consequence = await usageLine(path, "rename");
+  return consequence === nothing ? undefined : html`${consequence}`;
+}