@jxsuite/studio 6.1.1 → 8.0.0

package/src/content/file-record-ids.ts

@@ -0,0 +1,80 @@
+/**
+ * The ids of a file-backed collection's records, as the content loader gives them.
+ *
+ * A collection whose `source` names one file (`./content/projects.csv`) has one entry per record,
+ * and the build names each one: a CSV row by the collection's `idField`, else its `id`, `sku`,
+ * `slug` or `Slug` cell, else its row number from 0 (`coerceCSVRows` in `@jxsuite/parser`); an
+ * object of a JSON array by its `id`, else `<file stem>-<n>` (`loadJSONEntries`). The Site panel
+ * counts these and a reference picker offers them, so both must agree with the build.
+ *
+ * A leaf over the file's text: `grid/sources/content-source.ts` reads the file and hands it here.
+ * `content/file-records.ts` names the same records for the Content home, but it reaches the entry
+ * summaries, which reach the content source, so this module imports only the CSV codec.
+ *
+ * @docs studio/projects/browse
+ */
+
+import { isNonNullObject, isNumber, isString } from "@jxsuite/schema/guards";
+import { parseCsv } from "../grid/csv-codec";
+import type { JsonValue } from "@jxsuite/schema/types";
+
+/**
+ * The ids the CSV loader gives each data row; blank rows are skipped, as the Content home skips
+ * them.
+ */
+function csvIds(text: string, idField: string | undefined): string[] {
+  const { headers, rows } = parseCsv(text);
+  const candidates = [idField, "id", "sku", "slug", "Slug"].flatMap((name) => {
+    const at = name === undefined ? -1 : headers.indexOf(name);
+    return at === -1 ? [] : [at];
+  });
+  return rows
+    .filter((row) => row.some((cell) => cell.trim() !== ""))
+    .map((row, index) => {
+      const at = candidates.find((candidate) => (row[candidate] ?? "") !== "");
+      return at === undefined ? String(index) : row[at]!;
+    });
+}
+
+/**
+ * The ids the JSON loader gives: each object of an array, `<stem>-<n>` where it names none; a file
+ * that is ONE object (`docs/nav.json`) is one entry, its own `id` else the file's stem
+ * (`loadJSONEntries`). `[]` for text that is not JSON.
+ */
+function jsonIds(text: string, stem: string): string[] {
+  let parsed: JsonValue;
+  try {
+    // SAFETY: JSON.parse only ever yields JSON values; its `any` return type says nothing more.
+    parsed = JSON.parse(text) as JsonValue;
+  } catch {
+    return [];
+  }
+  const idOf = (item: JsonValue, fallback: string): string => {
+    const id = isNonNullObject(item) && !Array.isArray(item) ? item.id : undefined;
+    return isString(id) || isNumber(id) ? String(id) : fallback;
+  };
+  if (!Array.isArray(parsed)) {
+    return [idOf(parsed, stem)];
+  }
+  return parsed.map((item, index) => idOf(item, `${stem}-${index}`));
+}
+
+/**
+ * The record ids a collection file holds.
+ *
+ * @param path The file's project-relative path; its extension says how to read it.
+ * @param text The file's text.
+ * @param idField The collection's declared `idField`, if any.
+ * @returns The ids in file order, or `[]` for a file kind that holds no records Studio reads.
+ */
+export function fileRecordIds(path: string, text: string, idField?: string): string[] {
+  const lower = path.toLowerCase();
+  if (lower.endsWith(".csv")) {
+    return csvIds(text, idField);
+  }
+  if (lower.endsWith(".json")) {
+    const stem = (path.split("/").pop() ?? path).replace(/\.json$/i, "");
+    return jsonIds(text, stem);
+  }
+  return [];
+}

package/src/content/file-records.ts

@@ -0,0 +1,125 @@
+/**
+ * The entries of a file-backed collection: the records of the one file its `source` names.
+ *
+ * A collection whose `source` is a file (`content.pricing.source: "./content/pricing/prices.csv"`)
+ * has one entry per record, exactly as the parser's loader reads it: a CSV row under the header, or
+ * an object of a JSON array. The Content workspace lists those records, so a fifteen-row price list
+ * reads "Pricing 15" with a row per record rather than "Pricing 1" and the file's name
+ * (`specs/studio.md` §22.5). The records are written in the file's own grid, which opening any of
+ * them opens.
+ *
+ * Pure over the file's text: the scan (`browse/library-source.ts`) reads the file and hands it
+ * here.
+ *
+ * @docs studio/projects/browse
+ */
+
+import { isNonNullObject } from "@jxsuite/schema/guards";
+import { parseCsv } from "../grid/csv-codec";
+import { fieldText, titleFieldOf } from "./entry-summaries";
+import type { ContentTypeSchema, JsonValue } from "@jxsuite/schema/types";
+
+/** One record of a file-backed collection. */
+export interface FileRecord {
+  /** Its position among the file's records, from 0. */
+  index: number;
+  /**
+   * Its position among the file's data rows, from 0, blank rows counted: the row its file's grid
+   * shows it in, which a blank row above it makes differ from {@link index}.
+   */
+  row: number;
+  /** What it is called: its title field, else its first text, else its row number. */
+  title: string;
+  /** Every field it holds, as list text, keyed by field name. */
+  fields: Readonly<Record<string, string>>;
+}
+
+/** The title of one record, as the Content home names it. */
+function recordTitle(
+  schema: ContentTypeSchema | null | undefined,
+  fields: Readonly<Record<string, string>>,
+  index: number,
+  fallback: string,
+): string {
+  const field = titleFieldOf(schema, fields);
+  const named = field === null ? "" : (fields[field] ?? "");
+  const first = Object.values(fields).find((value) => value.trim() !== "");
+  return (named || first || fallback || `Row ${index + 1}`).trim();
+}
+
+/** One record's fields, and the data row it was read from. */
+interface RecordFields {
+  fields: Record<string, string>;
+  row: number;
+  /** The file is this one record, so it is called what the file is called when it says nothing. */
+  single?: boolean;
+}
+
+/** The records of a CSV text: one per data row under the header, blank rows skipped. */
+function csvFields(text: string): RecordFields[] {
+  const { headers, rows } = parseCsv(text);
+  return rows.flatMap((cells, row) =>
+    cells.some((cell) => cell.trim() !== "")
+      ? [{ fields: Object.fromEntries(headers.map((header, i) => [header, cells[i] ?? ""])), row }]
+      : [],
+  );
+}
+
+/**
+ * The records of a JSON text: one per object of an array, or ONE for a file that is a single object
+ * (`docs/nav.json`), which the loader reads as one entry named by the file. Null for text that is
+ * not JSON, which is then listed as the file it is.
+ */
+function jsonFields(text: string): RecordFields[] | null {
+  let parsed: JsonValue;
+  try {
+    // SAFETY: JSON.parse only ever yields JSON values; its `any` return type says nothing more.
+    parsed = JSON.parse(text) as JsonValue;
+  } catch {
+    return null;
+  }
+  const fieldsOf = (item: JsonValue): Record<string, string> =>
+    isNonNullObject(item) && !Array.isArray(item)
+      ? Object.fromEntries(Object.entries(item).map(([key, value]) => [key, fieldText(value)]))
+      : {};
+  if (!Array.isArray(parsed)) {
+    return [{ fields: fieldsOf(parsed), row: 0, single: true }];
+  }
+  return parsed.map((item, row) => ({ fields: fieldsOf(item), row }));
+}
+
+/**
+ * The records a collection file holds, or null when its kind is not one the Content workspace reads
+ * records from (it is then listed as the file it is).
+ *
+ * @param path The file's project-relative path; its extension says how to read it.
+ * @param text The file's text.
+ * @param schema The collection's schema, which names the title field.
+ */
+export function fileRecords(
+  path: string,
+  text: string,
+  schema?: ContentTypeSchema | null,
+): FileRecord[] | null {
+  const lower = path.toLowerCase();
+  const rows = lower.endsWith(".csv")
+    ? csvFields(text)
+    : lower.endsWith(".json")
+      ? jsonFields(text)
+      : null;
+  if (rows === null) {
+    return null;
+  }
+  const stem = (path.split("/").pop() ?? path).replace(/\.[^.]+$/, "");
+  return rows.map(({ fields, row, single }, index) => ({
+    fields,
+    index,
+    row,
+    title: recordTitle(schema, fields, index, single ? stem : ""),
+  }));
+}
+
+/** The key a record's row is listed under: its file and its place in it, `prices.csv#3`. */
+export function recordKey(path: string, index: number): string {
+  return `${path}#${index + 1}`;
+}

package/src/content/page-summaries.ts

@@ -0,0 +1,129 @@
+/**
+ * What the Content workspace's Pages list says about each page beyond its file: the template it is
+ * drawn in, the collection a dynamic page expands over, and whether it is marked a draft
+ * (`specs/studio.md` §22.5, the Content-Pages board: Title, URL, Template, Status, Edited).
+ *
+ * The scan behind the Content home knows each page's FILE; its `$layout`, `$paths` and `draft` are
+ * inside it. So this reads each page once, through the same parse the editor uses, and keeps the
+ * answer until a file event drops it ({@link invalidatePageSummaries}, wired beside the
+ * template-page index in `studio.ts`). The read never rejects: a page that cannot be read states
+ * nothing, and is listed by its route alone.
+ *
+ * @docs studio/projects/browse
+ */
+
+import { isNonNullObject } from "@jxsuite/schema/guards";
+import { getPlatform, hasPlatform } from "../platform";
+import { pageFactsOf } from "./collection-pages";
+import { DRAFT_FIELD } from "./draft-state";
+import type { FormatFrontmatter } from "../format/format-host";
+import type { JxMutableNode } from "@jxsuite/schema/types";
+
+/** One page, as the Pages list states it. */
+export interface PageSummary {
+  path: string;
+  /** Its `$layout`: a path, `false` (no layout), or `undefined` (the project's default). */
+  layout: string | false | undefined;
+  /** The collection its `$paths` expands over, or `null` for a page of its own. */
+  contentType: string | null;
+  /** Whether the page carries `draft: true`, the one draft marker a page can have. */
+  draft: boolean;
+}
+
+/** What a page that could not be read states: nothing. */
+function unread(path: string): PageSummary {
+  return { contentType: null, draft: false, layout: undefined, path };
+}
+
+/** The summary a parsed page states. Exported so the rule is assertable without a platform. */
+export function pageSummaryOf(
+  path: string,
+  document: JxMutableNode | null,
+  frontmatter: FormatFrontmatter | null,
+): PageSummary {
+  const { contentType, layout } = pageFactsOf(document, frontmatter);
+  const draft = frontmatter?.[DRAFT_FIELD] === true || document?.[DRAFT_FIELD] === true;
+  return { contentType, draft, layout, path };
+}
+
+/** Read one page. */
+async function readSummary(path: string): Promise<PageSummary> {
+  try {
+    const source = await getPlatform().readFile(path);
+    if (path.endsWith(".json")) {
+      const parsed: unknown = JSON.parse(source);
+      /* SAFETY: a `.json` file under `pages/` is a page document by the project layout; one that is
+         not an object states nothing, which is the branch below. */
+      return isNonNullObject(parsed) && !Array.isArray(parsed)
+        ? pageSummaryOf(path, parsed as JxMutableNode, null)
+        : unread(path);
+    }
+    const { parseSourceForPath } = await import("../files/file-ops");
+    const parsed = await parseSourceForPath(path, source);
+    /* SAFETY: a format class's parser returns its file as a Jx element tree (the format contract);
+       only `$layout`, `$paths` and `draft` are read off it. */
+    return pageSummaryOf(path, parsed.document as JxMutableNode, parsed.frontmatter);
+  } catch {
+    return unread(path);
+  }
+}
+
+// ─── The cache ───────────────────────────────────────────────────────────────
+
+/** At most this many pages are read for one list; the rest are listed by route alone. */
+export const PAGE_READ_LIMIT = 300;
+
+let _cache: { key: string; pages: Map<string, PageSummary> } | null = null;
+let _loading: { key: string; read: Promise<void> } | null = null;
+let _epoch = 0;
+const _listeners = new Set<() => void>();
+
+/**
+ * The pages' summaries as they stand, keyed by path: the map, or `null` while they are being read
+ * (which starts the read; listeners are told when it lands).
+ *
+ * @param paths The page files, in the order the list draws them.
+ */
+export function peekPageSummaries(
+  paths: readonly string[],
+): ReadonlyMap<string, PageSummary> | null {
+  const key = paths.join("\n");
+  if (_cache?.key === key) {
+    return _cache.pages;
+  }
+  if (!hasPlatform()) {
+    return new Map(paths.map((path) => [path, unread(path)]));
+  }
+  if (_loading?.key !== key) {
+    const epoch = _epoch;
+    const read = Promise.all(paths.slice(0, PAGE_READ_LIMIT).map((path) => readSummary(path))).then(
+      (summaries) => {
+        if (epoch !== _epoch || _loading?.read !== read) {
+          return;
+        }
+        _loading = null;
+        _cache = { key, pages: new Map(summaries.map((summary) => [summary.path, summary])) };
+        for (const listener of _listeners) {
+          listener();
+        }
+      },
+    );
+    _loading = { key, read };
+  }
+  return null;
+}
+
+/** Forget every summary. The next list re-reads its pages. */
+export function invalidatePageSummaries(): void {
+  _epoch += 1;
+  _cache = null;
+  _loading = null;
+}
+
+/** Be told when a read lands. Returns the function that stops it. */
+export function onPageSummariesRead(listener: () => void): () => void {
+  _listeners.add(listener);
+  return () => {
+    _listeners.delete(listener);
+  };
+}

package/src/content/record-entry.ts

@@ -0,0 +1,201 @@
+/**
+ * One record of a file-backed collection, edited as an entry: a form over one CSV row.
+ *
+ * A collection whose `source` names one file (`./content/projects.csv`) has one entry per record
+ * (`content/file-records.ts`). The file's own grid edits all of them at once; this is the form-only
+ * entry editor (`content/entry-editor.ts`, `specs/studio.md` §22.5) over ONE of them, so opening a
+ * project from the Content workspace opens that project's fields, typed by the collection's schema,
+ * rather than a table the reader has to find the row in.
+ *
+ * **It is an editor of the file's grid tab, not a second document.** The record's fields are read
+ * from, and written into, the grid controller's edit buffer (`grid/edit-buffer.ts`), the same
+ * buffer the grid's cells write. So ⌘S saves the file through the grid's one commit path (with its
+ * staleness check and its untouched-cell rule), ⌘Z undoes a field edit exactly as it undoes a cell,
+ * the tab's dirty dot is the buffer's, and switching the tab's editor to Grid shows the edit as a
+ * pending cell.
+ *
+ * Which record the form shows is per tab, here, keyed by the tab's id. An opener names the record
+ * by its place among the file's data rows, because that is all a scan knows and the rows may not
+ * have loaded yet; the place resolves to the row's key the moment they have, reactively, so the
+ * form draws the record as soon as it exists. Previous / Next then name rows by key, which a save
+ * that re-reads the file does not move.
+ *
+ * @docs studio/projects/content-types
+ */
+
+import { onScopeDispose, reactive } from "../reactivity";
+import { activateTab, workspace } from "../workspace/workspace";
+import { getGridController } from "../grid/grid-controller";
+import { isBoolean, isNonNullObject, isNumber, isString } from "@jxsuite/schema/guards";
+import { entryDay } from "./entry-summaries";
+import type { GridCellValue } from "../grid/grid-source";
+import type { EntryFields } from "./entry-fields";
+import type { JsonValue } from "../types";
+import type { Tab } from "../tabs/tab";
+
+/** A value that already starts with a calendar day, which a date input reads as it is. */
+const ISO_DAY = /^\d{4}-\d{2}-\d{2}/;
+
+/**
+ * The `canvasMode` the entry form draws under. Defined here, with the record it may be over, and
+ * re-exported by `entry-editor.ts`, which imports this module.
+ */
+export const ENTRY_MODE = "entry";
+
+/** A tab's record: by its row key, or (until the rows load) by its place among the data rows. */
+type ShownRecord = { key: string } | { row: number };
+
+/** Tab id → the record its entry form shows. */
+const shown = reactive(new Map<string, ShownRecord>());
+
+/** The key of the record a tab's entry form shows, or null when it shows none (yet). Tracks. */
+export function recordOf(tab: Tab): string | null {
+  const record = shown.get(tab.id);
+  if (record === undefined) {
+    return null;
+  }
+  if ("key" in record) {
+    return record.key;
+  }
+  return getGridController(tab)?.state.rows[record.row]?.key ?? null;
+}
+
+/** Whether the tab's entry form is over a record of its file, chosen or still loading. Tracks. */
+export function hasRecord(tab: Tab): boolean {
+  return shown.has(tab.id);
+}
+
+/** Show the record keyed `rowKey` in this tab's entry form. */
+export function showRecord(tab: Tab, rowKey: string): void {
+  shown.set(tab.id, { key: rowKey });
+}
+
+/** Forget the tab's record (its tab closed, or the record is gone). */
+export function forgetRecord(tab: Tab): void {
+  shown.delete(tab.id);
+}
+
+/** Whether this tab's entry form is over a record of its grid rather than over its own document. */
+export function isRecordTab(tab: Tab): boolean {
+  return hasRecord(tab) && getGridController(tab) !== null;
+}
+
+/**
+ * The record's fields as the form reads them: every column's current value, pending edits included,
+ * typed as the grid types it (a number column's cell is a number, a list column's a list of
+ * strings). A cell with nothing in it is absent, as an empty frontmatter key would be.
+ */
+export function recordFields(tab: Tab): EntryFields {
+  const controller = getGridController(tab);
+  const rowKey = recordOf(tab);
+  if (!controller || rowKey === null) {
+    return {};
+  }
+  const fields: EntryFields = {};
+  for (const column of controller.state.columns) {
+    const value = controller.buffer.effectiveValue(rowKey, column.field);
+    if (value === null || value === "") {
+      continue;
+    }
+    if (column.kind === "date" && isString(value) && !ISO_DAY.test(value)) {
+      /* A CSV spells a date the way its spreadsheet did (`6/3/2026`), which a date input cannot
+         show. The form is shown the day it means; the cell keeps its spelling until it is edited. */
+      fields[column.field] = entryDay(value) || value;
+      continue;
+    }
+    fields[column.field] = isNonNullObject(value) && !Array.isArray(value) ? value.$ref : value;
+  }
+  return fields;
+}
+
+/** A form value as the cell it is written into. */
+function cellValue(value: JsonValue | undefined): GridCellValue {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => (isString(item) ? item : JSON.stringify(item)));
+  }
+  if (isString(value) || isNumber(value) || isBoolean(value)) {
+    return value;
+  }
+  // A cell holds text: an object a field produced is written as its JSON.
+  return JSON.stringify(value);
+}
+
+/**
+ * Write a form patch into the record's row as one undo step. A field with no column is ignored: the
+ * file has nowhere to keep it, and adding a column is the grid's decision, not a form's.
+ */
+export function commitRecordFields(tab: Tab, patch: Record<string, JsonValue | undefined>): void {
+  const controller = getGridController(tab);
+  const rowKey = recordOf(tab);
+  if (!controller || rowKey === null) {
+    return;
+  }
+  const columns = new Set(controller.state.columns.map((column) => column.field));
+  controller.buffer.group(() => {
+    for (const [field, value] of Object.entries(patch)) {
+      if (columns.has(field)) {
+        controller.buffer.setCell(rowKey, field, cellValue(value));
+      }
+    }
+  });
+}
+
+/** Where the shown record sits among the file's rows, for the form's Previous / Next. */
+export interface RecordPlace {
+  /** Its place among the rows, from 0; -1 when the record is not (or no longer) among them. */
+  index: number;
+  total: number;
+  previous: string | null;
+  next: string | null;
+}
+
+/** The shown record's place among the grid's rows, in file order. Tracks the rows. */
+export function recordPlace(tab: Tab): RecordPlace {
+  const controller = getGridController(tab);
+  const rowKey = recordOf(tab);
+  const rows = controller?.state.rows ?? [];
+  const index = rowKey === null ? -1 : rows.findIndex((row) => row.key === rowKey);
+  return {
+    index,
+    next: index === -1 ? null : (rows[index + 1]?.key ?? null),
+    previous: index <= 0 ? null : (rows[index - 1]?.key ?? null),
+    total: rows.length,
+  };
+}
+
+/**
+ * Open one record of a file-backed collection in its entry form.
+ *
+ * Opens (or reveals) the file's grid tab, names the record at `row` (its place among the file's
+ * data rows, as `content/file-records.ts` numbers it) and puts the tab in the entry editor. The
+ * form draws the record once the grid's rows have loaded ({@link recordOf}).
+ *
+ * @returns The tab, or null when the file could not be opened at all.
+ */
+export async function openRecordEntry(path: string, row: number): Promise<Tab | null> {
+  /* Dynamic for the reason `entry-open.ts` gives: `files/files.ts` reaches the platform, the format
+     registry and the packages layer. */
+  const { openFileInTab } = await import("../files/files");
+  await openFileInTab(path);
+  const tab = workspace.tabs.get(path) ?? null;
+  if (!tab || !getGridController(tab)) {
+    return tab;
+  }
+  if (!shown.has(tab.id)) {
+    // The choice lives as long as the tab: a file reopened later starts on no record.
+    tab.scope.run(() => {
+      onScopeDispose(() => forgetRecord(tab));
+    });
+  }
+  shown.set(tab.id, { row });
+  if (!tab.capabilities.modes.includes(ENTRY_MODE)) {
+    tab.capabilities.modes.unshift(ENTRY_MODE);
+  }
+  tab.session.ui.canvasMode = ENTRY_MODE;
+  tab.session.ui.preview = false;
+  activateTab(tab.id);
+  return tab;
+}