@zerotal/admin 1.0.0

package/src/actions/ImportRecordsJob.ts

@@ -0,0 +1,108 @@
+/**
+ * The queued half of {@link importAction}.
+ *
+ * A synchronous import holds a WebSocket round-trip open, so a large file looks
+ * like a hang and times out half-written. Handing the work to a queue turns that
+ * into a job the worker chews through while the user gets on with their day.
+ *
+ * This module imports `@zerotal/queue` lazily and only when an app actually
+ * queues an import, so the dependency stays optional for everyone else.
+ *
+ * The worker needs to be able to reconstruct the job from its payload, which
+ * means registering the class where the worker can see it:
+ *
+ *   import { JobRegistry } from "@zerotal/queue";
+ *   import { ImportRecordsJob } from "@zerotal/admin";
+ *
+ *   JobRegistry.register(ImportRecordsJob);
+ *
+ * A job carries the panel id and resource slug rather than the resource itself,
+ * because a class cannot be serialised into a queue — the worker looks it up in
+ * the same registry the panel built at boot.
+ */
+import { Panel } from "../Panel.ts";
+import { importCsv } from "./transfer.ts";
+import type { ImportResult } from "./transfer.ts";
+import { frameworkLog } from "@zerotal/core/logger";
+
+/** What the job needs to do its work, once it is pulled off the queue. */
+export interface ImportRecordsPayload {
+  panelId: string;
+  slug: string;
+  csv: string;
+  mapping?: Record<number, string> | undefined;
+}
+
+/**
+ * A queued CSV import.
+ *
+ * Deliberately shaped like a `@zerotal/queue` `Job` — `handle()` plus
+ * `payload()` — without extending it, so `@zerotal/admin` needs no dependency
+ * on the queue package. Registering it works the same either way.
+ */
+export class ImportRecordsJob {
+  readonly queue = "default";
+  readonly maxAttempts = 1; // A half-applied retry would double-import rows.
+
+  constructor(private readonly _payload: ImportRecordsPayload) {}
+
+  payload(): Record<string, unknown> {
+    return { ...this._payload };
+  }
+
+  get className(): string {
+    return "ImportRecordsJob";
+  }
+
+  async handle(): Promise<void> {
+    const result = await runQueuedImport(this._payload);
+    const log = frameworkLog("admin");
+    if (result.failures.length > 0) {
+      log.warn(`Import finished with ${result.failures.length} skipped row(s)`, {
+        slug: this._payload.slug,
+        created: result.created,
+        failures: result.failures.slice(0, 10),
+      });
+    } else {
+      log.info(`Imported ${result.created} record(s)`, { slug: this._payload.slug });
+    }
+  }
+}
+
+/**
+ * Run an import described by a payload. Exported so an app can drive it from its
+ * own job class without adopting {@link ImportRecordsJob}.
+ */
+export async function runQueuedImport(payload: ImportRecordsPayload): Promise<ImportResult> {
+  const panel = Panel.get(payload.panelId) ?? Panel.default();
+  const resource = panel.find(payload.slug);
+  if (!resource) {
+    return {
+      created: 0,
+      failures: [`No resource "${payload.slug}" on panel "${payload.panelId}".`],
+    };
+  }
+  // The row cap is a guard against holding a request open; a worker has no such
+  // constraint, so a queued import is allowed the whole file.
+  return importCsv(resource, payload.csv, payload.mapping, { limit: Number.POSITIVE_INFINITY });
+}
+
+/**
+ * Push an import onto the queue, returning false when no queue is available so
+ * the caller can fall back to importing inline.
+ */
+export async function dispatchImport(payload: ImportRecordsPayload): Promise<boolean> {
+  try {
+    // Resolved by name so `@zerotal/queue` stays a genuinely optional peer —
+    // a static import would make every admin install depend on it.
+    const mod = (await import(/* @vite-ignore */ "@zerotal/queue" as string)) as {
+      Bus?: { dispatch?: (job: unknown) => Promise<unknown> };
+    };
+    if (typeof mod.Bus?.dispatch !== "function") return false;
+    await mod.Bus.dispatch(new ImportRecordsJob(payload));
+    return true;
+  } catch {
+    // No queue package, or no driver configured — the caller imports inline.
+    return false;
+  }
+}

package/src/actions/csv.ts

@@ -0,0 +1,123 @@
+/**
+ * CSV encoding and decoding for the import/export actions.
+ *
+ * Deliberately small and dependency-free, but strict about the two things that
+ * actually bite: quoting on the way out (a comma, quote or newline inside a
+ * value must not shift every later column) and quote handling on the way in.
+ */
+import type { Column } from "../table/Column.ts";
+
+/** Quote a field when it contains anything that would otherwise break the row. */
+function encodeField(value: string): string {
+  if (!/[",\r\n]/.test(value)) return value;
+  return `"${value.replace(/"/g, '""')}"`;
+}
+
+/**
+ * Render a value for a CSV cell.
+ *
+ * Primitives go out as themselves — a date export should be re-importable, not
+ * "3 days ago". Anything structured (a loaded relation, a JSON column) falls
+ * back to the column's display text, which is the only meaningful flat form.
+ */
+function encodeValue(column: Column, row: Record<string, unknown>): string {
+  const raw = column.raw(row);
+  if (raw == null) return "";
+  if (typeof raw === "string") return raw;
+  if (typeof raw === "number" || typeof raw === "boolean" || typeof raw === "bigint") {
+    return String(raw);
+  }
+  if (raw instanceof Date) return raw.toISOString();
+  return column.cell(row).text;
+}
+
+/** Serialise rows to CSV with a header line, one column per exportable column. */
+export function toCsv(rows: Record<string, unknown>[], columns: Column[]): string {
+  const header = columns.map((c) => encodeField(c.getLabel())).join(",");
+  const body = rows.map((row) => columns.map((c) => encodeField(encodeValue(c, row))).join(","));
+  return [header, ...body].join("\r\n");
+}
+
+/**
+ * Parse CSV into rows of raw strings, the first row being the header.
+ *
+ * Handles quoted fields containing commas, escaped quotes (`""`) and embedded
+ * newlines. Returns an empty array for empty input rather than a phantom row.
+ */
+export function parseCsv(text: string): string[][] {
+  const source = text.replace(/^/, ""); // strip a spreadsheet's byte-order mark
+  if (source.trim() === "") return [];
+
+  const rows: string[][] = [];
+  let row: string[] = [];
+  let field = "";
+  let quoted = false;
+
+  for (let i = 0; i < source.length; i++) {
+    const char = source[i]!;
+
+    if (quoted) {
+      if (char !== '"') {
+        field += char;
+        continue;
+      }
+      // A doubled quote is a literal one; a lone quote closes the field.
+      if (source[i + 1] === '"') {
+        field += '"';
+        i++;
+      } else {
+        quoted = false;
+      }
+      continue;
+    }
+
+    if (char === '"' && field === "") {
+      quoted = true;
+    } else if (char === ",") {
+      row.push(field);
+      field = "";
+    } else if (char === "\r") {
+      // Swallow it; the \n that follows ends the row.
+    } else if (char === "\n") {
+      row.push(field);
+      rows.push(row);
+      row = [];
+      field = "";
+    } else {
+      field += char;
+    }
+  }
+
+  // A file not ending in a newline still has one row left in hand.
+  if (field !== "" || row.length > 0) {
+    row.push(field);
+    rows.push(row);
+  }
+  return rows;
+}
+
+/**
+ * Pair a CSV's header cells with resource fields.
+ *
+ * Matching is forgiving about the ways a label and a key differ in practice —
+ * case, spaces, underscores, hyphens — so a file exported from the panel
+ * re-imports without the user mapping a single column by hand.
+ */
+export function guessColumnMapping(
+  headers: string[],
+  candidates: { key: string; label: string }[],
+): Record<number, string> {
+  const normalize = (s: string): string => s.toLowerCase().replace(/[\s_-]+/g, "");
+  const byKey = new Map<string, string>();
+  for (const c of candidates) {
+    byKey.set(normalize(c.key), c.key);
+    byKey.set(normalize(c.label), c.key);
+  }
+
+  const mapping: Record<number, string> = {};
+  headers.forEach((header, i) => {
+    const match = byKey.get(normalize(header));
+    if (match) mapping[i] = match;
+  });
+  return mapping;
+}

package/src/actions/index.ts

@@ -0,0 +1,39 @@
+export {
+  Action,
+  ActionGroup,
+  action,
+  actionGroup,
+  flattenActions,
+  viewAction,
+  editAction,
+  deleteAction,
+  createAction,
+  replicateAction,
+  impersonateAction,
+  bulkEditAction,
+  bulkDeleteAction,
+  restoreAction,
+  forceDeleteAction,
+  bulkRestoreAction,
+  bulkForceDeleteAction,
+} from "./Action.ts";
+export type {
+  ActionColor,
+  ActionContext,
+  ActionHandler,
+  ActionItem,
+  ActionPage,
+  ActionVisible,
+} from "./Action.ts";
+export { renderAction, renderActionGroup, renderActionMenuItem } from "./render.tsx";
+export type { RenderActionOptions } from "./render.tsx";
+export {
+  exportAction,
+  bulkExportAction,
+  importAction,
+  importCsv,
+  IMPORT_ROW_LIMIT,
+  MAPPING_FIELD_PREFIX,
+} from "./transfer.ts";
+export type { ImportResult } from "./transfer.ts";
+export { toCsv, parseCsv, guessColumnMapping } from "./csv.ts";

package/src/actions/render.tsx

@@ -0,0 +1,181 @@
+/** @jsxImportSource @zerotal/flow */
+// Render an Action as a themed link (navigate) or server-action button (with an
+// optional `confirm` dialog). Shared by row actions, header actions, and the
+// bulk toolbar so every action looks and behaves consistently.
+
+import type { HtmlNode } from "@zerotal/flow";
+import { DropdownMenu } from "@zerotal/flow-ui";
+import { Icon } from "../ui/icons.tsx";
+import type { Action, ActionColor, ActionContext, ActionGroup } from "./Action.ts";
+
+const COLOR: Record<ActionColor, string> = {
+  default:
+    "border-input bg-background text-muted-foreground hover:bg-accent hover:text-accent-foreground",
+  primary: "border-transparent bg-primary text-primary-foreground hover:bg-primary/90 shadow-sm",
+  success: "border-input bg-background text-success hover:bg-success/10 hover:border-success/40",
+  muted: "border-input bg-background text-muted-foreground hover:bg-accent",
+  destructive:
+    "border-input bg-background text-muted-foreground hover:border-destructive/40 hover:bg-destructive/10 hover:text-destructive",
+};
+
+export interface RenderActionOptions {
+  /** The page's @expose handler invoked for callback actions. */
+  onRun?: unknown;
+  /** The page's @expose handler invoked for actions with a modal form (opens it). */
+  onForm?: unknown;
+  /** Args serialized into `data-args` for the handler (e.g. [key, id]). */
+  args?: unknown[];
+}
+
+/** Render a single action. Link actions become `<a navigate>`, callbacks `<button>`. */
+export function renderAction(
+  a: Action,
+  ctx: ActionContext,
+  opts: RenderActionOptions = {},
+): HtmlNode | null {
+  if (!a.isVisibleFor(ctx.record, ctx)) return null;
+
+  const colorCls = COLOR[a._color];
+  const cls = a._iconOnly
+    ? `inline-flex h-8 w-8 items-center justify-center rounded-md border transition ${colorCls}`
+    : `inline-flex h-9 items-center gap-1.5 rounded-lg border px-3 text-sm font-medium transition ${colorCls}`;
+
+  const inner = (
+    <>
+      {a._icon ? <Icon name={a._icon} class="h-4 w-4" /> : null}
+      {a._iconOnly ? null : <span>{a.getLabel()}</span>}
+    </>
+  );
+
+  // Modal-form action: open the dialog (no confirm — the modal is the confirm).
+  if (a.hasForm() && opts.onForm) {
+    return (
+      <button
+        type="button"
+        onClick={opts.onForm}
+        data-args={JSON.stringify(opts.args ?? [])}
+        title={a.getLabel()}
+        class={cls}
+      >
+        {inner}
+      </button>
+    );
+  }
+
+  if (a.isLink()) {
+    const href = a.href(ctx) ?? "#";
+    return (
+      <a href={href} navigate title={a.getLabel()} class={cls}>
+        {inner}
+      </a>
+    );
+  }
+
+  // Callback action: server method + optional confirm dialog.
+  return (
+    <button
+      type="button"
+      onClick={opts.onRun}
+      data-args={JSON.stringify(opts.args ?? [])}
+      {...(a._confirm ? { confirm: a._confirm } : {})}
+      title={a.getLabel()}
+      class={cls}
+    >
+      {inner}
+    </button>
+  );
+}
+
+/**
+ * Render a group as one trigger opening a menu of its members.
+ *
+ * Returns `null` when nothing inside is visible, so an empty menu never appears.
+ * `argsFor` builds each member's handler arguments, since those carry the
+ * action's own key.
+ */
+export function renderActionGroup(
+  group: ActionGroup,
+  ctx: ActionContext,
+  opts: RenderActionOptions & { argsFor?: (a: Action) => unknown[] } = {},
+): HtmlNode | null {
+  const members = group.visibleActions(ctx.record, ctx);
+  if (members.length === 0) return null;
+
+  return (
+    <DropdownMenu
+      align="right"
+      trigger={
+        <button
+          type="button"
+          title={group.getLabel()}
+          class="inline-flex h-8 w-8 items-center justify-center rounded-md border border-input bg-background text-muted-foreground transition hover:bg-accent hover:text-accent-foreground"
+        >
+          <Icon name={group._icon} class="h-4 w-4" />
+        </button>
+      }
+    >
+      {members.map((a) => {
+        const args = opts.argsFor ? opts.argsFor(a) : opts.args;
+        return renderActionMenuItem(a, ctx, {
+          ...opts,
+          ...(args === undefined ? {} : { args }),
+        });
+      })}
+    </DropdownMenu>
+  );
+}
+
+/**
+ * Render an action as a full-width dropdown menu row (icon + label). Used by the
+ * row-action overflow menu when a row has more actions than fit inline.
+ */
+export function renderActionMenuItem(
+  a: Action,
+  ctx: ActionContext,
+  opts: RenderActionOptions = {},
+): HtmlNode | null {
+  if (!a.isVisibleFor(ctx.record, ctx)) return null;
+
+  const tone =
+    a._color === "destructive"
+      ? "text-destructive hover:bg-destructive/10"
+      : "hover:bg-accent hover:text-accent-foreground";
+  const cls = `flex w-full cursor-pointer items-center gap-2 rounded-sm px-2 py-1.5 text-left text-sm outline-none transition-colors ${tone}`;
+  const inner = (
+    <>
+      {a._icon ? <Icon name={a._icon} class="h-4 w-4" /> : null}
+      <span>{a.getLabel()}</span>
+    </>
+  );
+
+  if (a.hasForm() && opts.onForm) {
+    return (
+      <button
+        type="button"
+        onClick={opts.onForm}
+        data-args={JSON.stringify(opts.args ?? [])}
+        class={cls}
+      >
+        {inner}
+      </button>
+    );
+  }
+  if (a.isLink()) {
+    return (
+      <a href={a.href(ctx) ?? "#"} navigate class={cls}>
+        {inner}
+      </a>
+    );
+  }
+  return (
+    <button
+      type="button"
+      onClick={opts.onRun}
+      data-args={JSON.stringify(opts.args ?? [])}
+      {...(a._confirm ? { confirm: a._confirm } : {})}
+      class={cls}
+    >
+      {inner}
+    </button>
+  );
+}