@zerotal/admin 1.0.0

package/src/actions/transfer.ts

@@ -0,0 +1,307 @@
+/**
+ * Import and export actions — moving records in and out of the panel as CSV.
+ *
+ *   static headerActions() {
+ *     return [createAction(), exportAction(), importAction()];
+ *   }
+ *
+ *   static bulkActions() {
+ *     return [bulkExportAction(), bulkDeleteAction()];
+ *   }
+ *
+ * An export reflects the list exactly as the user left it: the same search, the
+ * same filters, the same tab, the same sort. That is the whole point — someone
+ * who has narrowed a table to the twelve rows they care about expects twelve
+ * rows in the file, not the entire table.
+ */
+import { Action } from "./Action.ts";
+import type { ActionContext } from "./Action.ts";
+import { toCsv, parseCsv, guessColumnMapping } from "./csv.ts";
+import { toXlsx } from "./xlsx.ts";
+import { flattenFields, fileUpload, select } from "../form/index.ts";
+import type { Column } from "../table/Column.ts";
+import type { ResourceClass } from "../Panel.ts";
+import { DEFAULT_PANEL_ID } from "../Panel.ts";
+
+/**
+ * How many rows one import may create.
+ *
+ * A synchronous import holds a WebSocket round-trip open, so a hundred-thousand
+ * row file would look like a hang and time out half-written. Files beyond this
+ * belong on a queue; the action says so rather than trying and failing.
+ */
+export const IMPORT_ROW_LIMIT = 2000;
+
+/** Columns that may leave the panel, in table order. */
+function exportableColumns(resource: ResourceClass): Column[] {
+  return resource.columns().filter((c) => c._exportable);
+}
+
+/** What an export is written as. */
+export type ExportFormat = "csv" | "xlsx";
+
+const MIME: Record<ExportFormat, string> = {
+  csv: "text/csv",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+};
+
+/** `orders-2026-07-28.csv` — dated, so repeated exports don't overwrite each other. */
+function exportFilename(resource: ResourceClass, format: ExportFormat): string {
+  const date = new Date().toISOString().slice(0, 10);
+  return `${resource.getSlug()}-${date}.${format}`;
+}
+
+function deliver(ctx: ActionContext, rows: Record<string, unknown>[], format: ExportFormat): void {
+  // `download` is present on every panel page; a custom host that lacks it gets
+  // told rather than silently doing nothing.
+  if (typeof ctx.page.download !== "function") {
+    ctx.page.flash("This page cannot deliver downloads.", "warning");
+    return;
+  }
+  const columns = exportableColumns(ctx.resource);
+  const body =
+    format === "xlsx"
+      ? toXlsx(rows, columns, { sheet: ctx.resource.getPluralLabel() })
+      : toCsv(rows, columns);
+  ctx.page.download(exportFilename(ctx.resource, format), body, MIME[format]);
+}
+
+/**
+ * Header action → download every row the current list query returns.
+ *
+ * Reads `ctx.listOptions`, which the list page fills with its live scope, and
+ * asks for all of it rather than the visible page.
+ */
+export function exportAction(format: ExportFormat = "csv"): Action {
+  return new Action(format === "xlsx" ? "export-xlsx" : "export")
+    .label(format === "xlsx" ? "Export to Excel" : "Export")
+    .icon("download")
+    .run(async (ctx) => {
+      const { resource, listOptions } = ctx;
+      const rows = await resource.listAll(listOptions ?? {});
+      if (rows.length === 0) {
+        ctx.page.flash("Nothing to export.", "warning");
+        return;
+      }
+      deliver(ctx, rows, format);
+    })
+    .authorize((_rec, ctx) => ctx.resource.can("viewAny"));
+}
+
+/** Bulk action → download just the selected rows. */
+export function bulkExportAction(format: ExportFormat = "csv"): Action {
+  return new Action(format === "xlsx" ? "bulk-export-xlsx" : "bulk-export")
+    .label(format === "xlsx" ? "Export to Excel" : "Export")
+    .icon("download")
+    .asBulk()
+    .run(async (ctx) => {
+      // Bulk dispatch hands over ids; the rows are loaded here rather than for
+      // every bulk action, most of which never need them.
+      const rows = ctx.records?.length
+        ? (ctx.records as Record<string, unknown>[])
+        : ((await Promise.all((ctx.ids ?? []).map((id) => ctx.resource.find(id)))).filter(
+            Boolean,
+          ) as Record<string, unknown>[]);
+
+      if (rows.length === 0) {
+        ctx.page.flash("Nothing to export.", "warning");
+        return;
+      }
+      deliver(ctx, rows, format);
+    })
+    .authorize((_rec, ctx) => ctx.resource.can("viewAny"));
+}
+
+/** The outcome of an import, as reported back to the user. */
+export interface ImportResult {
+  created: number;
+  /** One message per rejected row, already prefixed with its line number. */
+  failures: string[];
+}
+
+/**
+ * Turn CSV text into records on `resource`.
+ *
+ * Every row is validated through the resource's own form fields, so an import
+ * cannot write anything a human couldn't have typed into the create form. A row
+ * that fails is reported and skipped — one bad line out of five hundred should
+ * not discard the other four hundred and ninety-nine.
+ */
+export async function importCsv(
+  resource: ResourceClass,
+  csv: string,
+  /** Column index → field key. Omit to infer from the header row. */
+  mapping?: Record<number, string>,
+  /** `limit` overrides the row cap — a queued import has no request to hold open. */
+  options: { limit?: number } = {},
+): Promise<ImportResult> {
+  const rows = parseCsv(csv);
+  const result: ImportResult = { created: 0, failures: [] };
+  if (rows.length < 2) {
+    result.failures.push("The file has no data rows.");
+    return result;
+  }
+
+  const fields = flattenFields(resource.form());
+  const resolved =
+    mapping ??
+    guessColumnMapping(
+      rows[0]!,
+      fields.map((f) => ({ key: f._key, label: f.getLabel() })),
+    );
+  if (Object.keys(resolved).length === 0) {
+    result.failures.push("No column in the file matches a field on this resource.");
+    return result;
+  }
+
+  const byKey = new Map(fields.map((f) => [f._key, f]));
+  const dataRows = rows.slice(1);
+  const limit = options.limit ?? IMPORT_ROW_LIMIT;
+  if (dataRows.length > limit) {
+    result.failures.push(
+      `The file has ${dataRows.length} rows; ${limit} is the most one import can take. ` +
+        "Queue the import to lift that.",
+    );
+    return result;
+  }
+
+  for (const [i, row] of dataRows.entries()) {
+    // Line numbers are what the user sees in their spreadsheet: 1 is the header.
+    const line = i + 2;
+    // A row that is entirely blank is trailing whitespace, not a failure.
+    if (row.every((cell) => cell.trim() === "")) continue;
+
+    const data: Record<string, unknown> = {};
+    for (const [index, key] of Object.entries(resolved)) {
+      const cell = row[Number(index)];
+      if (cell === undefined) continue;
+      data[key] = cell;
+    }
+
+    const missing = fields
+      .filter((f) => f._required && !String(data[f._key] ?? "").trim())
+      .map((f) => f.getLabel());
+    if (missing.length > 0) {
+      result.failures.push(`Row ${line}: missing ${missing.join(", ")}.`);
+      continue;
+    }
+
+    try {
+      for (const [key, value] of Object.entries(data)) {
+        const field = byKey.get(key);
+        if (field) data[key] = await field.dehydrate(value);
+      }
+      const record = await resource.create(resource.mutateBeforeSave(data, "create"));
+      await resource.afterSave((record ?? data) as Record<string, unknown>, "create");
+      result.created++;
+    } catch (err) {
+      result.failures.push(`Row ${line}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  return result;
+}
+
+/** Field key a mapping select writes to, for CSV column `index`. */
+export const MAPPING_FIELD_PREFIX = "map_";
+
+/**
+ * Header action → upload a CSV and create a record per row.
+ *
+ * The modal has two steps in one screen: pick a file, and then — once its header
+ * row is readable — one select per column saying which field it feeds. The
+ * selects start on whatever the header names match, so a file the panel exported
+ * needs no adjustment, and a file from somewhere else needs only the columns that
+ * didn't line up.
+ */
+export function importAction(options: { queue?: boolean } = {}): Action {
+  return new Action("import")
+    .label("Import")
+    .icon("upload")
+    .modalHeading("Import records")
+    .modalSubmitLabel("Import")
+    .formUsing((data, resource) => {
+      const file = fileUpload("file")
+        .label("CSV file")
+        .accept(".csv,text/csv")
+        .required()
+        .helperText("The first row must be a header.");
+
+      const csv = String(data["file"] ?? "");
+      if (!csv.trim()) return [file];
+
+      const rows = parseCsv(csv);
+      const headers = rows[0] ?? [];
+      if (headers.length === 0) return [file];
+
+      // Fields the resource can actually accept, plus the option to skip.
+      const target = flattenFields(resource.form());
+      const options: Record<string, string> = { "": "— skip this column —" };
+      for (const f of target) options[f._key] = f.getLabel();
+
+      return [
+        file,
+        ...headers.map((header, i) =>
+          select(`${MAPPING_FIELD_PREFIX}${i}`)
+            .label(header || `Column ${i + 1}`)
+            .options(options)
+            .helperText(`${rows.length - 1} row${rows.length === 2 ? "" : "s"} of data`),
+        ),
+      ];
+    })
+    .authorize((_rec, ctx) => ctx.resource.can("create"))
+    .run(async (ctx) => {
+      const csv = String(ctx.data?.["file"] ?? "");
+      if (!csv.trim()) {
+        ctx.page.flash("Choose a CSV file to import.", "warning");
+        return;
+      }
+
+      // Whatever the mapping selects hold wins; an untouched modal falls back to
+      // inference, which is the same thing the selects were seeded with.
+      const chosen: Record<number, string> = {};
+      for (const [key, value] of Object.entries(ctx.data ?? {})) {
+        if (!key.startsWith(MAPPING_FIELD_PREFIX)) continue;
+        const field = String(value ?? "");
+        if (field) chosen[Number(key.slice(MAPPING_FIELD_PREFIX.length))] = field;
+      }
+      const mapping = Object.keys(chosen).length > 0 ? chosen : undefined;
+
+      // Hand a big file to the queue when the app asked for it. A worker has no
+      // request to hold open, so the row cap doesn't apply there.
+      if (options.queue) {
+        const { dispatchImport } = await import("./ImportRecordsJob.ts");
+        const queued = await dispatchImport({
+          panelId: ctx.panelId ?? DEFAULT_PANEL_ID,
+          slug: ctx.slug,
+          csv,
+          mapping,
+        });
+        if (queued) {
+          ctx.page.flash("Import queued. Rows will appear as the worker gets through them.");
+          return;
+        }
+        // No queue configured — importing inline beats silently doing nothing.
+      }
+
+      const { created, failures } = await importCsv(ctx.resource, csv, mapping);
+
+      if (created === 0) {
+        ctx.page.flash(failures[0] ?? "Nothing was imported.", "warning");
+        return;
+      }
+      const label = created === 1 ? ctx.resource.getLabel() : ctx.resource.getPluralLabel();
+      if (failures.length === 0) {
+        ctx.page.flash(`Imported ${created} ${label.toLowerCase()}.`);
+        return;
+      }
+      // Lead with what worked, then the first few problems — a hundred identical
+      // failures in a flash message helps nobody.
+      const shown = failures.slice(0, 3).join(" ");
+      const rest = failures.length > 3 ? ` (+${failures.length - 3} more)` : "";
+      ctx.page.flash(
+        `Imported ${created} ${label.toLowerCase()}; ${failures.length} skipped. ${shown}${rest}`,
+        "warning",
+      );
+    });
+}

package/src/actions/xlsx.ts

@@ -0,0 +1,304 @@
+/**
+ * A spreadsheet writer, for exports that need to open in Excel as a spreadsheet
+ * rather than as text.
+ *
+ * CSV is the better interchange format and stays the default. This exists for
+ * the case CSV genuinely cannot serve: a recipient who opens the file, sees
+ * `007` turned into `7` and a leading `=` treated as a formula, and reasonably
+ * calls the export broken. Writing real cell types fixes that at the source.
+ *
+ * An `.xlsx` is a ZIP of XML parts, so the whole format is built here from two
+ * small pieces — a ZIP writer and a sheet serialiser — rather than pulling in a
+ * spreadsheet library for what an export button needs. The scope is deliberately
+ * one sheet with a header row and typed cells: no formulas, charts or merges.
+ */
+import type { Column } from "../table/Column.ts";
+
+// ── ZIP ──────────────────────────────────────────────────────────────────────
+
+/** Entries are stored uncompressed — valid ZIP, and an export is written once. */
+const STORED = 0;
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let i = 0; i < 256; i++) {
+    let c = i;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[i] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(bytes: Uint8Array): number {
+  let c = 0xffffffff;
+  for (const byte of bytes) c = CRC_TABLE[(c ^ byte) & 0xff]! ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+interface ZipEntry {
+  name: string;
+  data: Uint8Array;
+}
+
+/**
+ * Pack entries into a ZIP archive.
+ *
+ * Timestamps are fixed rather than taken from the clock, so exporting the same
+ * rows twice produces byte-identical files — which makes the output testable and
+ * keeps a checksum meaningful.
+ */
+function zip(entries: ZipEntry[]): Uint8Array {
+  const chunks: Uint8Array[] = [];
+  const central: Uint8Array[] = [];
+  let offset = 0;
+
+  for (const entry of entries) {
+    const name = new TextEncoder().encode(entry.name);
+    const sum = crc32(entry.data);
+
+    const local = new Uint8Array(30 + name.length);
+    const lv = new DataView(local.buffer);
+    lv.setUint32(0, 0x04034b50, true); // local file header
+    lv.setUint16(4, 20, true); // version needed
+    lv.setUint16(6, 0, true); // flags
+    lv.setUint16(8, STORED, true);
+    lv.setUint16(10, 0, true); // time
+    lv.setUint16(12, 0x0021, true); // date — 1980-01-01, the ZIP epoch
+    lv.setUint32(14, sum, true);
+    lv.setUint32(18, entry.data.length, true);
+    lv.setUint32(22, entry.data.length, true);
+    lv.setUint16(26, name.length, true);
+    lv.setUint16(28, 0, true); // extra field length
+    local.set(name, 30);
+
+    chunks.push(local, entry.data);
+
+    const dir = new Uint8Array(46 + name.length);
+    const dv = new DataView(dir.buffer);
+    dv.setUint32(0, 0x02014b50, true); // central directory header
+    dv.setUint16(4, 20, true); // version made by
+    dv.setUint16(6, 20, true); // version needed
+    dv.setUint16(8, 0, true);
+    dv.setUint16(10, STORED, true);
+    dv.setUint16(12, 0, true);
+    dv.setUint16(14, 0x0021, true);
+    dv.setUint32(16, sum, true);
+    dv.setUint32(20, entry.data.length, true);
+    dv.setUint32(24, entry.data.length, true);
+    dv.setUint16(28, name.length, true);
+    dv.setUint32(42, offset, true); // offset of the local header
+    dir.set(name, 46);
+    central.push(dir);
+
+    offset += local.length + entry.data.length;
+  }
+
+  const centralSize = central.reduce((n, c) => n + c.length, 0);
+  const end = new Uint8Array(22);
+  const ev = new DataView(end.buffer);
+  ev.setUint32(0, 0x06054b50, true); // end of central directory
+  ev.setUint16(8, entries.length, true);
+  ev.setUint16(10, entries.length, true);
+  ev.setUint32(12, centralSize, true);
+  ev.setUint32(16, offset, true);
+
+  const all = [...chunks, ...central, end];
+  const out = new Uint8Array(all.reduce((n, c) => n + c.length, 0));
+  let at = 0;
+  for (const chunk of all) {
+    out.set(chunk, at);
+    at += chunk.length;
+  }
+  return out;
+}
+
+// ── Sheet ────────────────────────────────────────────────────────────────────
+
+const utf8 = (text: string): Uint8Array => new TextEncoder().encode(text);
+
+/**
+ * Whether a character is one XML will not accept.
+ *
+ * Tab, newline and carriage return are legal; the rest of the C0 range is not,
+ * and a single one of them makes the whole file unopenable. Checked by code
+ * point rather than by a regular expression, because a regex literal holding
+ * raw control characters is unreadable and easy to mangle.
+ */
+function isIllegalXmlChar(code: number): boolean {
+  return code < 0x20 && code !== 0x09 && code !== 0x0a && code !== 0x0d;
+}
+
+function escapeXml(text: string): string {
+  let out = "";
+  for (const char of text) {
+    const code = char.codePointAt(0) ?? 0;
+    if (isIllegalXmlChar(code)) continue;
+    out +=
+      char === "&"
+        ? "&amp;"
+        : char === "<"
+          ? "&lt;"
+          : char === ">"
+            ? "&gt;"
+            : char === '"'
+              ? "&quot;"
+              : char;
+  }
+  return out;
+}
+
+/** `0 → A`, `26 → AA`. */
+function columnLetter(index: number): string {
+  let out = "";
+  let n = index;
+  do {
+    out = String.fromCharCode(65 + (n % 26)) + out;
+    n = Math.floor(n / 26) - 1;
+  } while (n >= 0);
+  return out;
+}
+
+/**
+ * Days since 1899-12-30, the epoch spreadsheets count dates from.
+ *
+ * The two-day offset from 1900-01-01 is the usual one: the format deliberately
+ * repeats a bug that treated 1900 as a leap year, and every reader expects it.
+ */
+function excelSerial(date: Date): number {
+  return date.getTime() / 86_400_000 + 25_569;
+}
+
+type CellValue = string | number | boolean | Date | null;
+
+function cellXml(ref: string, value: CellValue): string {
+  if (value == null || value === "") return "";
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? `<c r="${ref}"><v>${value}</v></c>` : "";
+  }
+  if (typeof value === "boolean") return `<c r="${ref}" t="b"><v>${value ? 1 : 0}</v></c>`;
+  if (value instanceof Date) {
+    return `<c r="${ref}" s="2"><v>${excelSerial(value)}</v></c>`;
+  }
+  // Inline rather than via a shared-string table: one pass, no second index to
+  // keep consistent, and the size difference does not matter for an export.
+  return `<c r="${ref}" t="inlineStr"><is><t xml:space="preserve">${escapeXml(value)}</t></is></c>`;
+}
+
+/**
+ * Read a cell's value with its type intact.
+ *
+ * A column's rendered text is the fallback, not the first choice: exporting
+ * "R1,299.00" as a string gives a spreadsheet nothing to sum.
+ */
+function cellValue(column: Column, row: Record<string, unknown>): CellValue {
+  const raw = column.raw(row);
+  if (raw == null) return null;
+  if (typeof raw === "number" || typeof raw === "boolean") return raw;
+  if (typeof raw === "bigint") return Number(raw);
+  if (raw instanceof Date) return raw;
+  if (typeof raw === "string") {
+    // A date column arrives as an ISO string from most drivers; keeping it a
+    // date is what lets the recipient sort and filter by it.
+    if (/^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2})/.test(raw)) {
+      const parsed = new Date(raw);
+      if (!Number.isNaN(parsed.getTime())) return parsed;
+    }
+    return raw;
+  }
+  return column.cell(row).text;
+}
+
+const CONTENT_TYPES = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
+<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+<Default Extension="xml" ContentType="application/xml"/>
+<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>
+<Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>
+<Override PartName="/xl/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"/>
+</Types>`;
+
+const ROOT_RELS = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>
+</Relationships>`;
+
+const WORKBOOK_RELS = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/>
+<Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>
+</Relationships>`;
+
+// Three styles: default, bold (the header row), and a date format.
+const STYLES = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<styleSheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">
+<numFmts count="1"><numFmt numFmtId="164" formatCode="yyyy-mm-dd hh:mm"/></numFmts>
+<fonts count="2"><font><sz val="11"/><name val="Calibri"/></font><font><b/><sz val="11"/><name val="Calibri"/></font></fonts>
+<fills count="2"><fill><patternFill patternType="none"/></fill><fill><patternFill patternType="gray125"/></fill></fills>
+<borders count="1"><border><left/><right/><top/><bottom/><diagonal/></border></borders>
+<cellStyleXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0"/></cellStyleXfs>
+<cellXfs count="3">
+<xf numFmtId="0" fontId="0" fillId="0" borderId="0" xfId="0"/>
+<xf numFmtId="0" fontId="1" fillId="0" borderId="0" xfId="0" applyFont="1"/>
+<xf numFmtId="164" fontId="0" fillId="0" borderId="0" xfId="0" applyNumberFormat="1"/>
+</cellXfs>
+<cellStyles count="1"><cellStyle name="Normal" xfId="0" builtinId="0"/></cellStyles>
+</styleSheet>`;
+
+/** Sheet names may not carry these, and may not exceed 31 characters. */
+function sheetName(name: string): string {
+  const cleaned = name.replace(/[\\/?*[\]:]/g, " ").trim();
+  return escapeXml(cleaned.slice(0, 31) || "Sheet1");
+}
+
+/**
+ * Build an `.xlsx` workbook: one sheet, a bold header row from the column
+ * labels, and one row per record with values typed rather than stringified.
+ *
+ * The header row is frozen and an auto-filter is set over the used range, since
+ * an exported table is nearly always going to be sorted or filtered on arrival.
+ */
+export function toXlsx(
+  rows: Record<string, unknown>[],
+  columns: Column[],
+  options: { sheet?: string } = {},
+): Uint8Array {
+  const header = columns
+    .map((c, i) => {
+      const ref = `${columnLetter(i)}1`;
+      return `<c r="${ref}" t="inlineStr" s="1"><is><t xml:space="preserve">${escapeXml(c.getLabel())}</t></is></c>`;
+    })
+    .join("");
+
+  const body = rows
+    .map((row, r) => {
+      const cells = columns
+        .map((c, i) => cellXml(`${columnLetter(i)}${r + 2}`, cellValue(c, row)))
+        .join("");
+      return `<row r="${r + 2}">${cells}</row>`;
+    })
+    .join("");
+
+  const lastColumn = columnLetter(Math.max(0, columns.length - 1));
+  const lastRow = rows.length + 1;
+  const sheet = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">
+<sheetViews><sheetView workbookViewId="0"><pane ySplit="1" topLeftCell="A2" activePane="bottomLeft" state="frozen"/></sheetView></sheetViews>
+<sheetData><row r="1">${header}</row>${body}</sheetData>
+<autoFilter ref="A1:${lastColumn}${lastRow}"/>
+</worksheet>`;
+
+  const workbook = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
+<sheets><sheet name="${sheetName(options.sheet ?? "Sheet1")}" sheetId="1" r:id="rId1"/></sheets>
+</workbook>`;
+
+  return zip([
+    // `[Content_Types].xml` must come first — readers look for it at the front.
+    { name: "[Content_Types].xml", data: utf8(CONTENT_TYPES) },
+    { name: "_rels/.rels", data: utf8(ROOT_RELS) },
+    { name: "xl/workbook.xml", data: utf8(workbook) },
+    { name: "xl/_rels/workbook.xml.rels", data: utf8(WORKBOOK_RELS) },
+    { name: "xl/styles.xml", data: utf8(STYLES) },
+    { name: "xl/worksheets/sheet1.xml", data: utf8(sheet) },
+  ]);
+}

package/src/auth/AuthLayout.tsx

@@ -0,0 +1,34 @@
+/** @jsxImportSource @zerotal/flow */
+// Minimal centered layout for the guest auth screens (login / forgot / reset).
+// Shares the admin theme head (dark/light + tokens) but not the sidebar shell.
+
+import { Layout } from "@zerotal/flow";
+import type { HtmlNode } from "@zerotal/flow";
+import { Panel } from "../Panel.ts";
+import { adminHead } from "../theme.ts";
+
+export class AuthLayout extends Layout {
+  static override get head(): string {
+    const cfg = Panel.config();
+    return adminHead(cfg.brand ?? "Admin", cfg.theme);
+  }
+
+  render(slot: HtmlNode): HtmlNode {
+    const cfg = Panel.config();
+    return (
+      <div class="flex min-h-screen flex-col items-center justify-center bg-background px-4 py-12 text-foreground">
+        <div class="w-full max-w-sm">
+          <div class="mb-6 flex flex-col items-center gap-2 text-center">
+            <div class="flex h-11 w-11 items-center justify-center rounded-xl bg-primary text-lg font-bold text-primary-foreground shadow-sm">
+              {cfg.brand.slice(0, 1).toUpperCase()}
+            </div>
+            <div class="text-lg font-semibold tracking-tight">{cfg.auth?.heading ?? cfg.brand}</div>
+          </div>
+          <div class="rounded-2xl border border-border bg-card p-6 text-card-foreground shadow-sm sm:p-7">
+            {slot}
+          </div>
+        </div>
+      </div>
+    );
+  }
+}

package/src/auth/index.ts

@@ -0,0 +1,13 @@
+/**
+ * `@zerotal/admin/auth` — the opt-in auth screens. Kept on a separate subpath so
+ * the `@zerotal/auth` dependency these modules pull in stays optional for apps
+ * that don't use the built-in auth pages. Enable them with
+ * `Panel.auth({ enabled: true, ... })`; `AdminProvider` mounts the routes.
+ */
+export { AuthLayout } from "./AuthLayout.tsx";
+export { LoginPage } from "./pages/LoginPage.tsx";
+export { ProfilePage } from "./pages/ProfilePage.tsx";
+export { ForgotPasswordPage } from "./pages/ForgotPasswordPage.tsx";
+export { ResetPasswordPage } from "./pages/ResetPasswordPage.tsx";
+export { VerifyEmailPage } from "./pages/VerifyEmailPage.tsx";
+export { registerAuthRoutes } from "./register.ts";