@jxsuite/studio 6.1.1 → 8.0.0

package/src/media/media-commands.ts

@@ -0,0 +1,181 @@
+/**
+ * The Media workspace's verbs, as command records (studio.md §22.6, §9.3).
+ *
+ * - `media.browse { filter?, query?, select? }` shows the Media home, set to a filter, a search or
+ *   one file selected. It is what Add new › Media runs after an upload, so the reader lands on what
+ *   arrived, and what a script or the palette runs to ask "what is unused".
+ * - `media.upload` shows the Media home and opens its Upload picker.
+ * - `media.replace { path }` selects a file and opens its Replace picker: the one overwrite.
+ * - `media.delete { path }` deletes a file, through the confirmation that states its usage.
+ *
+ * Every one runs the flow, never a copy of it: the surface's Upload label and Replace input are the
+ * same controls these open (`HTMLInputElement.showPicker()`), and Delete is the detail pane's own.
+ *
+ * DOM-free at import: the flow and the home opener are loaded on the first run, so
+ * `commands/app-commands.ts` can list these records in a bare Bun process.
+ *
+ * @docs studio/projects/media
+ */
+
+import {
+  argsSchema,
+  enumArg,
+  enumProperty,
+  optionalStringArg,
+  stringArg,
+  stringProperty,
+} from "../commands/command-args";
+import { isMediaFile } from "../files/media-upload";
+import { MEDIA_FILTER_KEYS } from "./media-library-model";
+import type { MediaBrowseRequest } from "./media-library";
+import type { CommandArgValues } from "../commands/command-args";
+import type { AnyCommand, CommandRegistry } from "../commands/registry";
+import type * as MediaLibraryModule from "./media-library";
+import type * as WorkspaceHomeModule from "../workspace/workspace-home";
+
+/** The ids, which Add new and the Site panel run. */
+export const MEDIA_BROWSE = "media.browse";
+export const MEDIA_UPLOAD = "media.upload";
+export const MEDIA_REPLACE = "media.replace";
+export const MEDIA_DELETE = "media.delete";
+
+/**
+ * The flow and the home opener, each imported once. One cached promise per module: two dynamic
+ * imports of one module in flight at once is the shape that loses its coverage record.
+ */
+let _library: Promise<typeof MediaLibraryModule> | null = null;
+let _home: Promise<typeof WorkspaceHomeModule> | null = null;
+
+function library(): Promise<typeof MediaLibraryModule> {
+  _library ??= import("./media-library");
+  return _library;
+}
+
+function home(): Promise<typeof WorkspaceHomeModule> {
+  _home ??= import("../workspace/workspace-home");
+  return _home;
+}
+
+/** A path argument that must name a media file. Refused with the sentence a person can act on. */
+function mediaPathArg(commandId: string, args: CommandArgValues, key: string): string {
+  const path = stringArg(commandId, args, key).replace(/^\.\//, "");
+  if (!isMediaFile(path)) {
+    throw new RangeError(
+      `command "${commandId}": "${path}" is not a media file (an image, video, audio, PDF or font).`,
+    );
+  }
+  return path;
+}
+
+/** The `media.browse` arguments as a request, each read with the reader its schema names. */
+function browseRequestOf(args: CommandArgValues): MediaBrowseRequest {
+  const request: MediaBrowseRequest = {};
+  if (args.filter !== undefined) {
+    request.filter = enumArg(MEDIA_BROWSE, args, "filter", MEDIA_FILTER_KEYS);
+  }
+  const query = optionalStringArg(MEDIA_BROWSE, args, "query");
+  if (query !== undefined) {
+    request.query = query;
+  }
+  if (args.select !== undefined) {
+    request.select = mediaPathArg(MEDIA_BROWSE, args, "select");
+  }
+  return request;
+}
+
+/** Open the Media home tab, which enters the Media workspace by being activated (§22.1). */
+async function showHome(): Promise<void> {
+  const { openWorkspaceHome } = await home();
+  openWorkspaceHome("media");
+}
+
+const PATH_DESCRIPTION = "The media file's project path, such as public/media/hero.jpg.";
+
+/** The four records. */
+export function mediaCommands(): AnyCommand[] {
+  const base = {
+    category: "Project",
+    group: "1_media",
+    level: "project",
+    menus: ["palette"],
+    requires: "an open project",
+    when: (ctx) => ctx.project.open,
+  } satisfies Partial<AnyCommand>;
+  return [
+    {
+      ...base,
+      args: argsSchema(
+        {
+          filter: enumProperty(
+            MEDIA_FILTER_KEYS,
+            "Which media to show: all, image, video, audio, document, font, or unused (files no document references).",
+          ),
+          query: stringProperty("Search the media by name or path."),
+          select: stringProperty(`A file to select and describe. ${PATH_DESCRIPTION}`),
+        },
+        [],
+      ),
+      icon: "image",
+      id: MEDIA_BROWSE,
+      run: async (_ctx, args) => {
+        const request = browseRequestOf(args);
+        const flow = await library();
+        flow.applyMediaBrowse(request);
+        await showHome();
+      },
+      title: "Browse Media",
+      undo: "none",
+    },
+    {
+      ...base,
+      icon: "upload-simple",
+      id: MEDIA_UPLOAD,
+      run: async () => {
+        const flow = await library();
+        await showHome();
+        flow.requestMediaUpload();
+      },
+      title: "Upload Media…",
+      undo: "none",
+    },
+    {
+      ...base,
+      args: argsSchema({ path: stringProperty(`The file to replace. ${PATH_DESCRIPTION}`) }, [
+        "path",
+      ]),
+      icon: "arrows-clockwise",
+      id: MEDIA_REPLACE,
+      run: async (_ctx, args) => {
+        const path = mediaPathArg(MEDIA_REPLACE, args, "path");
+        const flow = await library();
+        await showHome();
+        flow.requestMediaReplace(path);
+      },
+      title: "Replace Media File…",
+      undo: "none",
+    },
+    {
+      ...base,
+      args: argsSchema({ path: stringProperty(`The file to delete. ${PATH_DESCRIPTION}`) }, [
+        "path",
+      ]),
+      // A delete is a danger row wherever it is listed, and sorts last (studio-ui-guidelines.md §12.3).
+      destructive: true,
+      group: "9_danger",
+      icon: "trash",
+      id: MEDIA_DELETE,
+      run: async (_ctx, args) => {
+        const path = mediaPathArg(MEDIA_DELETE, args, "path");
+        const flow = await library();
+        await flow.deleteMediaFile(path);
+      },
+      title: "Delete Media File…",
+      undo: "none",
+    },
+  ];
+}
+
+/** Register the Media records. */
+export function registerMediaCommands(registry: CommandRegistry): void {
+  registry.registerAll(mediaCommands());
+}

package/src/media/media-library-model.ts

@@ -0,0 +1,232 @@
+/**
+ * The Media workspace's model: which files a filter keeps, in what order, and where an arrow key
+ * moves the selection.
+ *
+ * Pure over its inputs, so the rules the library is judged by can be tested without a DOM and
+ * without a project: the filter list (studio.md §22.6), what **Unused** may claim, the three sorts,
+ * the search, the counts each filter shows, and the grid's keyboard walk.
+ *
+ * **Unused is the one filter that is not a property of the file.** Kind is read off the name; being
+ * unused is a question about every other document in the project, asked through the usage index one
+ * file at a time (`files/media-usage.ts`). So its answer is `null` until every file's question has
+ * settled, and a file whose question FAILED is never counted as unused: "nobody uses this" and "we
+ * could not find out" are different facts, and a filter that offered the second as the first would
+ * be inviting a delete nobody can stand behind.
+ *
+ * @docs studio/projects/media
+ */
+
+import type { MediaFileKind } from "../files/media-upload";
+
+/** One file as the library lists it. */
+export interface LibraryMediaFile {
+  /** The project-relative path on disk: the file's identity everywhere in the library. */
+  file: string;
+  name: string;
+  kind: MediaFileKind;
+  /** Bytes, from the listing; `null` when the host did not say. */
+  bytes: number | null;
+  /** ISO modified time, from the listing; `null` when the host did not say. */
+  modified: string | null;
+}
+
+/** A filter in the left column. The five kinds, every file, and the one usage question. */
+export type MediaFilterKey = "all" | MediaFileKind | "unused";
+
+/** The filters, in the order the column lists them (studio.md §22.6). */
+export const MEDIA_FILTERS: readonly { key: MediaFilterKey; label: string }[] = [
+  { key: "all", label: "All media" },
+  { key: "image", label: "Images" },
+  { key: "video", label: "Video" },
+  { key: "audio", label: "Audio" },
+  { key: "document", label: "Documents" },
+  { key: "font", label: "Fonts" },
+  { key: "unused", label: "Unused" },
+];
+
+/** The filter keys, for a command's `enum`. */
+export const MEDIA_FILTER_KEYS: readonly MediaFilterKey[] = MEDIA_FILTERS.map((f) => f.key);
+
+/** Whether a value names a filter. A command argument and a stored value are untrusted input. */
+export function isMediaFilterKey(value: unknown): value is MediaFilterKey {
+  return MEDIA_FILTER_KEYS.some((key) => key === value);
+}
+
+/** The heading a filter's grid carries. */
+export function mediaFilterLabel(key: MediaFilterKey): string {
+  return MEDIA_FILTERS.find((f) => f.key === key)?.label ?? "All media";
+}
+
+/** A sort, by the word its menu reads. */
+export type MediaSortKey = "newest" | "name" | "size";
+
+export const MEDIA_SORTS: readonly { key: MediaSortKey; label: string }[] = [
+  { key: "newest", label: "Newest" },
+  { key: "name", label: "Name" },
+  { key: "size", label: "Size" },
+];
+
+export const MEDIA_SORT_KEYS: readonly MediaSortKey[] = MEDIA_SORTS.map((s) => s.key);
+
+/** Whether a value names a sort. */
+export function isMediaSortKey(value: unknown): value is MediaSortKey {
+  return MEDIA_SORT_KEYS.some((key) => key === value);
+}
+
+/** Whether a file passes a filter. `unused` is `null` until the usage sweep has settled. */
+export function passesFilter(
+  file: LibraryMediaFile,
+  filter: MediaFilterKey,
+  unused: ReadonlySet<string> | null,
+): boolean {
+  switch (filter) {
+    case "all": {
+      return true;
+    }
+    case "unused": {
+      return unused !== null && unused.has(file.file);
+    }
+    default: {
+      return file.kind === filter;
+    }
+  }
+}
+
+/**
+ * Whether a file matches a search: its NAME, case-insensitively, as the field's "Search by name…"
+ * says. Not its path: every path starts `public/` or `content/`, so a one-letter search for "b" or
+ * "c" kept the whole library and looked broken.
+ */
+export function matchesQuery(file: LibraryMediaFile, query: string): boolean {
+  const needle = query.trim().toLowerCase();
+  return needle === "" || file.name.toLowerCase().includes(needle);
+}
+
+/**
+ * The files a filter and a search keep, in a sort's order.
+ *
+ * Every sort ends in the path, so two files the sort cannot tell apart (two unmeasured sizes, two
+ * files modified in the same second) keep one order across repaints rather than swapping.
+ */
+export function visibleMedia(
+  files: readonly LibraryMediaFile[],
+  options: {
+    filter: MediaFilterKey;
+    query: string;
+    sort: MediaSortKey;
+    unused: ReadonlySet<string> | null;
+  },
+): LibraryMediaFile[] {
+  const kept = files.filter(
+    (file) =>
+      passesFilter(file, options.filter, options.unused) && matchesQuery(file, options.query),
+  );
+  return kept.toSorted((a, b) => compareBy(options.sort, a, b) || a.file.localeCompare(b.file));
+}
+
+function compareBy(sort: MediaSortKey, a: LibraryMediaFile, b: LibraryMediaFile): number {
+  switch (sort) {
+    case "name": {
+      return a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: "base" });
+    }
+    case "size": {
+      // Largest first, because the question a size sort answers is "what is heavy"; unknown last.
+      return (b.bytes ?? -1) - (a.bytes ?? -1);
+    }
+    default: {
+      // Newest first; a file with no modified time sorts after every file that has one.
+      return (b.modified ?? "").localeCompare(a.modified ?? "");
+    }
+  }
+}
+
+/**
+ * How many files each filter would show, before the search narrows them.
+ *
+ * `unused` is `null` until the sweep has settled, and the column draws no number for it: a count is
+ * a claim, and "0 unused" before anyone has looked would be one nobody can stand behind.
+ */
+export function filterCounts(
+  files: readonly LibraryMediaFile[],
+  unused: ReadonlySet<string> | null,
+): Record<MediaFilterKey, number | null> {
+  const counts: Record<MediaFilterKey, number | null> = {
+    all: files.length,
+    audio: 0,
+    document: 0,
+    font: 0,
+    image: 0,
+    unused: unused === null ? null : files.filter((file) => unused.has(file.file)).length,
+    video: 0,
+  };
+  for (const file of files) {
+    counts[file.kind] = (counts[file.kind] ?? 0) + 1;
+  }
+  return counts;
+}
+
+/** The minimum tile width and the gap the grid is laid out with (`surfaces/media-library.json`). */
+export const TILE_MIN_WIDTH = 132;
+export const TILE_GAP = 12;
+
+/**
+ * How many columns `repeat(auto-fill, minmax(TILE_MIN_WIDTH, 1fr))` makes in a box `width` wide.
+ * The same arithmetic CSS does, so ArrowDown lands on the tile drawn under the current one.
+ */
+export function gridColumns(width: number): number {
+  return Math.max(1, Math.floor((width + TILE_GAP) / (TILE_MIN_WIDTH + TILE_GAP)));
+}
+
+/**
+ * Where a key moves the selection in a grid of `count` tiles laid out `columns` wide, or `null` for
+ * a key the grid does not handle (Tab, a letter), which is then left to the platform.
+ *
+ * The grid pattern of WAI-ARIA's practices: arrows move one cell, Home and End go to the ends of
+ * the row, and Ctrl+Home and Ctrl+End to the ends of the grid. Arrows stop at the edges rather than
+ * wrapping, because a wrap from the last column of one row to the first of the next is a move the
+ * eye does not follow.
+ */
+export function gridStep(
+  index: number,
+  key: string,
+  columns: number,
+  count: number,
+  ctrl = false,
+): number | null {
+  if (count === 0) {
+    return null;
+  }
+  const at = Math.min(Math.max(index, 0), count - 1);
+  const rowStart = at - (at % columns);
+  let next: number;
+  switch (key) {
+    case "ArrowRight": {
+      next = at + 1;
+      break;
+    }
+    case "ArrowLeft": {
+      next = at - 1;
+      break;
+    }
+    case "ArrowDown": {
+      next = at + columns;
+      break;
+    }
+    case "ArrowUp": {
+      next = at - columns;
+      break;
+    }
+    case "Home": {
+      next = ctrl ? 0 : rowStart;
+      break;
+    }
+    case "End": {
+      next = ctrl ? count - 1 : Math.min(rowStart + columns - 1, count - 1);
+      break;
+    }
+    default: {
+      return null;
+    }
+  }
+  return next < 0 || next >= count ? at : next;
+}