@zerotal/admin 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -4,10 +4,44 @@ All notable changes to this package are documented here. The format is
 based on [Keep a Changelog](https://keepachangelog.com/); this package
 follows the Zerotal monorepo's unified versioning.
 
-**Maturity: `experimental`**
+**Maturity: `stable`**
 
 ## [Unreleased]
 
+## [1.5.0] — 2026-08-15
+
+### Changed
+
+- **The public surface is now an explicit decision rather than whatever happened to be
+  exported.** 36 exports are marked `@internal` and leave the compatibility promise:
+  layout plumbing (`applyLayout`, `reconcile`, `moveKey`), schema normalisation
+  (`toFormLayout`, `toFormSections`, `flattenFields`, `flattenActions`), rule-tree
+  internals (`parseRuleTree`, `describeRuleTree`, `ruleTreeIsEmpty`), predicates
+  (`isImage`, `isUpload`, `isFormSection`), and the session/storage keys and defaults
+  (`IMPERSONATOR_KEY`, `THEME_STORAGE_KEY`, `VIEW_PARAMS`, `DEFAULT_ADMIN_CONFIG`, …).
+
+  None of these were ever meant to be API; they were exported because something else
+  needed them. Deciding that **now** matters, because after `stable` narrowing the
+  surface is itself a breaking change. The promise drops from 182 callables to 146.
+
+- **Every remaining export is documented.** The reference gained sections for
+  configuration and middleware, the row and bulk actions the guide had not reached
+  (`restoreAction`, `forceDeleteAction`, `bulkEditAction`, `bulkRestoreAction`,
+  `bulkForceDeleteAction`, `textFilter`), impersonation, the media helpers behind
+  `mediaPicker`, import/export, history and permissions — each with its real signature
+  read off the API surface rather than paraphrased. Coverage of the promised surface
+  went from 58% to 100%.
+
+- **Maturity is now `stable`** — the public API follows SemVer strictly for the rest of
+  the 1.x line. Every gate is closed: `@zerotal/flow` and `@zerotal/flow-ui` are stable
+  underneath it, the internal/public boundary is explicit, and the documented surface is
+  complete. The guard and ability middleware — the panel's security boundary — were
+  already covered by tests, alongside 222 tests overall.
+
+  This remains the largest surface in the monorepo at 146 callables, which is exactly
+  why the `@internal` triage came first: freezing a smaller, deliberate surface is a
+  promise worth making, where freezing everything that happened to be exported is not.
+
 ## [1.0.3] — 2026-08-07
 
 ### Changed

package/README.md

@@ -12,7 +12,9 @@ The default UI ships with **light + dark mode out of the box**. Styling currentl
 loads Tailwind via the Play CDN (configured in `theme.ts`); swapping to a real
 Tailwind build later only touches that one file.
 
-> **Status:** experimental. You get navigation, list pages (search / sort /
+> **Status:** stable — the public API follows SemVer strictly for the rest of the 1.x
+> line. Anything importable without an `@internal` marker is covered, and the surface is
+> snapshotted in `api-surface.md`, which CI diffs on every change. You get navigation, list pages (search / sort /
 > paginate), a read-only **View** page (infolists), reactive **Create / Edit**
 > forms with validation, a **Delete** row action, and a configurable auth
 > **guard**. The previous config-driven admin has been retired; it remains

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@zerotal/admin",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "license": "MIT",
-  "maturity": "experimental",
+  "maturity": "stable",
   "private": false,
   "type": "module",
   "main": "./src/index.ts",
@@ -31,16 +31,16 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/cache": "1.4.0",
-    "@zerotal/core": "1.4.0",
-    "@zerotal/flow": "1.4.0",
-    "@zerotal/flow-ui": "1.4.0",
-    "@zerotal/validator": "1.4.0"
+    "@zerotal/cache": "1.5.0",
+    "@zerotal/core": "1.5.0",
+    "@zerotal/flow": "1.5.0",
+    "@zerotal/flow-ui": "1.5.0",
+    "@zerotal/validator": "1.5.0"
   },
   "devDependencies": {
-    "@zerotal/orm": "1.4.0",
-    "@zerotal/auth": "1.4.0",
-    "@zerotal/queue": "1.4.0"
+    "@zerotal/orm": "1.5.0",
+    "@zerotal/auth": "1.5.0",
+    "@zerotal/queue": "1.5.0"
   },
   "peerDependencies": {
     "@zerotal/orm": "^1.0.0",

package/src/Panel.ts

@@ -47,7 +47,10 @@ import type {
 export { PanelInstance } from "./PanelInstance.ts";
 export type { ResourceClass, NavItem, NavGroup, PanelPage } from "./PanelInstance.ts";
 
-/** The id given to the panel every application starts with. */
+/** The id given to the panel every application starts with.
+ *
+ * @internal
+ */
 export const DEFAULT_PANEL_ID = "admin";
 
 export class Panel {

package/src/actions/Action.ts

@@ -366,7 +366,10 @@ export function actionGroup(actions: Action[]): ActionGroup {
 /** Either a single action or a group of them — what a resource may return. */
 export type ActionItem = Action | ActionGroup;
 
-/** Flatten groups so callers that need plain actions (dispatch, lookup) get them. */
+/** Flatten groups so callers that need plain actions (dispatch, lookup) get them.
+ *
+ * @internal
+ */
 export function flattenActions(items: ActionItem[]): Action[] {
   return items.flatMap((item) => (item instanceof ActionGroup ? item._actions : [item]));
 }

package/src/actions/csv.ts

@@ -45,7 +45,7 @@ export function toCsv(rows: Record<string, unknown>[], columns: Column[]): strin
  * 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
+  const source = text.replace(/^\uFEFF/, ""); // strip a spreadsheet's byte-order mark
   if (source.trim() === "") return [];
 
   const rows: string[][] = [];
@@ -102,6 +102,8 @@ export function parseCsv(text: string): string[][] {
  * 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.
+ *
+ * @internal
  */
 export function guessColumnMapping(
   headers: string[],

package/src/actions/transfer.ts

@@ -29,6 +29,8 @@ import { DEFAULT_PANEL_ID } from "../Panel.ts";
  * 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.
+ *
+ * @internal
  */
 export const IMPORT_ROW_LIMIT = 2000;
 
@@ -202,7 +204,10 @@ export async function importCsv(
   return result;
 }
 
-/** Field key a mapping select writes to, for CSV column `index`. */
+/** Field key a mapping select writes to, for CSV column `index`.
+ *
+ * @internal
+ */
 export const MAPPING_FIELD_PREFIX = "map_";
 
 /**

package/src/config.ts

@@ -99,6 +99,12 @@ export interface AdminConfigShape {
   plugins?: Record<string, boolean>;
 }
 
+/**
+ * The raw defaults `AdminConfig()` merges onto. Apps configure the panel through
+ * that factory rather than reaching for this object.
+ *
+ * @internal
+ */
 export const DEFAULT_ADMIN_CONFIG: AdminConfigShape = {
   path: "/admin",
   brand: "Zerotal",

package/src/dashboardLayout.ts

@@ -39,7 +39,10 @@ export interface DashboardLayoutStore {
   save(layout: DashboardLayout): Promise<void> | void;
 }
 
-/** An empty layout — the state before anyone has arranged anything. */
+/** An empty layout — the state before anyone has arranged anything.
+ *
+ * @internal
+ */
 export const EMPTY_LAYOUT: DashboardLayout = { order: [], hidden: [] };
 
 /**
@@ -49,6 +52,8 @@ export const EMPTY_LAYOUT: DashboardLayout = { order: [], hidden: [] };
  * only says how to arrange them. So a widget added since the layout was saved
  * still appears (at the end, where it is noticeable rather than lost), and a
  * widget since removed does not resurrect because a stale key mentions it.
+ *
+ * @internal
  */
 export function applyLayout<T>(
   widgets: T[],
@@ -75,7 +80,10 @@ export function applyLayout<T>(
   };
 }
 
-/** Move one key up or down, returning the new order. */
+/** Move one key up or down, returning the new order.
+ *
+ * @internal
+ */
 export function moveKey(order: string[], key: string, direction: -1 | 1): string[] {
   const from = order.indexOf(key);
   if (from === -1) return order;
@@ -92,6 +100,8 @@ export function moveKey(order: string[], key: string, direction: -1 | 1): string
  *
  * A layout saved when there were three widgets cannot reorder a fourth, so the
  * order is reconciled against the current keys before anything is moved.
+ *
+ * @internal
  */
 export function reconcile(layout: DashboardLayout | null, keys: string[]): DashboardLayout {
   const known = new Set(keys);

package/src/form/ResourceForm.ts

@@ -18,6 +18,7 @@ import { type FormComponent, flattenFields } from "./Section.ts";
 
 export type ResourceFormClass = new () => Form & Record<string, unknown>;
 
+/** @internal */
 export function makeResourceForm(
   schema: FormComponent[],
   mode: FieldMode,

package/src/form/Section.ts

@@ -271,11 +271,15 @@ export function formSection(heading?: string): FormSection {
   return new FormSection(heading);
 }
 
+/** @internal */
 export function isFormSection(c: FormComponent): c is FormSection {
   return c instanceof FormSection;
 }
 
-/** Collect every field across sections, tab groups, + loose fields, in order. */
+/** Collect every field across sections, tab groups, + loose fields, in order.
+ *
+ * @internal
+ */
 export function flattenFields(components: FormComponent[]): Field[] {
   const out: Field[] = [];
   for (const c of components) {
@@ -295,7 +299,10 @@ export function flattenFields(components: FormComponent[]): Field[] {
   return out;
 }
 
-/** Normalize components into sections, wrapping loose fields in a default section. */
+/** Normalize components into sections, wrapping loose fields in a default section.
+ *
+ * @internal
+ */
 export function toFormSections(components: FormComponent[]): FormSection[] {
   const sections: FormSection[] = [];
   let loose: Field[] = [];
@@ -326,7 +333,10 @@ export type FormBlock =
   | { kind: "callout"; callout: Callout }
   | { kind: "prime"; prime: Prime };
 
-/** Normalize the schema into ordered layout blocks (loose fields → a section). */
+/** Normalize the schema into ordered layout blocks (loose fields → a section).
+ *
+ * @internal
+ */
 export function toFormLayout(components: FormComponent[]): FormBlock[] {
   const blocks: FormBlock[] = [];
   let loose: Field[] = [];

package/src/history.ts

@@ -136,7 +136,10 @@ function diff(
   return changes;
 }
 
-/** The values that would put a record back to how it was before an entry. */
+/** The values that would put a record back to how it was before an entry.
+ *
+ * @internal
+ */
 export function revertPayload(entry: HistoryEntry): Record<string, unknown> {
   const payload: Record<string, unknown> = {};
   for (const change of entry.changes) payload[change.field] = change.from;

package/src/impersonation.ts

@@ -19,7 +19,10 @@
  */
 import { frameworkLog } from "@zerotal/core/logger";
 
-/** Session key holding the original user's id while impersonating. */
+/** Session key holding the original user's id while impersonating.
+ *
+ * @internal
+ */
 export const IMPERSONATOR_KEY = "admin.impersonator";
 
 /** The session surface this needs — kept structural so `@zerotal/session` stays optional. */

package/src/media.ts

@@ -64,6 +64,7 @@ export interface MediaProvider {
 /** Image types the picker shows a thumbnail for rather than an icon. */
 const IMAGE_TYPES = /^image\/(png|jpe?g|gif|webp|avif|svg\+xml)$/i;
 
+/** @internal */
 export function isImage(item: MediaItem): boolean {
   return IMAGE_TYPES.test(item.mime);
 }
@@ -203,7 +204,10 @@ export interface UploadedFileLike {
   store(directory: string, disk?: string, filename?: string): Promise<string>;
 }
 
-/** Whether a bound value is an upload rather than an already-stored path. */
+/** Whether a bound value is an upload rather than an already-stored path.
+ *
+ * @internal
+ */
 export function isUpload(value: unknown): value is UploadedFileLike {
   return (
     value != null &&

package/src/pages/RecordViewPage.tsx

@@ -82,6 +82,19 @@ const COLS_CLASS = [
 ];
 const SPAN_CLASS = ["", "", "sm:col-span-2", "sm:col-span-3", "sm:col-span-4"];
 
+/**
+ * The pivot object a BelongsToMany relation method returns when called without
+ * eager-loading. Reached by name off a model instance, so the methods are
+ * optional: the page checks each one before calling it, and a relation that is
+ * not many-to-many has none of them.
+ */
+interface PivotProxy {
+  attach?: (id: unknown) => unknown;
+  detach?: (id: unknown) => unknown;
+  get?: () => unknown;
+  all?: () => unknown;
+}
+
 export class RecordViewPage extends Component {
   static layout = AdminLayout;
   /** Set by each generated subclass. */
@@ -459,9 +472,7 @@ export class RecordViewPage extends Component {
   @expose attachDraft: Record<string, string> = {};
 
   /** Resolve a parent model *instance* and its relation object by method name. */
-  private async _relation(
-    relationName: string,
-  ): Promise<{ attach?: Function; detach?: Function; get?: Function; all?: Function } | null> {
+  private async _relation(relationName: string): Promise<PivotProxy | null> {
     const model = this._resource.model as unknown as {
       find?: (id: unknown) => Promise<Record<string, unknown> | null>;
     };
@@ -469,12 +480,7 @@ export class RecordViewPage extends Component {
     const parent = (await model.find(this.recordId)) as Record<string, unknown> | null;
     const fn = parent && (parent as Record<string, unknown>)[relationName];
     if (typeof fn !== "function") return null;
-    return (fn as () => unknown).call(parent) as {
-      attach?: Function;
-      detach?: Function;
-      get?: Function;
-      all?: Function;
-    };
+    return (fn as () => unknown).call(parent) as PivotProxy;
   }
 
   /** Load the rows currently attached through a BelongsToMany relation. */

package/src/pages/ResourceListPage.tsx

@@ -22,7 +22,6 @@ import type { ResourceClass } from "../Panel.ts";
 import { Panel } from "../Panel.ts";
 import type { PanelInstance } from "../PanelInstance.ts";
 import type { Column, BadgeTone } from "../table/Column.ts";
-import type { Group } from "../table/Group.ts";
 import type { Filter, QueryRule } from "../table/Filter.ts";
 import {
   parseRuleTree,
@@ -1824,7 +1823,6 @@ export class ResourceListPage extends Component {
 
   override async render(): Promise<HtmlNode> {
     const R = this._resource;
-    const base = this._panel.base();
     const currentPage = Math.max(1, parseInt(this.page, 10) || 1);
 
     // Resolve the active tab (defaults to the first) and its query scope.

package/src/renderHooks.ts

@@ -68,6 +68,8 @@ export type RenderHook = (context: RenderHookContext) => HtmlNode | string | nul
  *
  * A hook is decoration: it must not be able to take down the page it decorates,
  * so a throwing hook is logged and skipped rather than propagated.
+ *
+ * @internal
  */
 export function resolveRenderHooks(
   hooks: RenderHook[],

package/src/roles.ts

@@ -151,7 +151,10 @@ export function panelPermissions(panel: PanelInstance): Permission[] {
   return out;
 }
 
-/** Group a flat permission list for rendering, preserving order. */
+/** Group a flat permission list for rendering, preserving order.
+ *
+ * @internal
+ */
 export function groupPermissions(
   permissions: Permission[],
 ): { group: string; items: Permission[] }[] {

package/src/savedViews.ts

@@ -48,6 +48,8 @@ export interface SavedViewProvider {
  * Deliberately explicit rather than "everything in the URL": a saved view should
  * restore how the list was *shaped*, not which page of it happened to be open,
  * so `page` is excluded and a restored view always starts at the top.
+ *
+ * @internal
  */
 export const VIEW_PARAMS = [
   "search",
@@ -62,7 +64,10 @@ export const VIEW_PARAMS = [
   "group",
 ] as const;
 
-/** Reduce a full query string to just the parts a view restores. */
+/** Reduce a full query string to just the parts a view restores.
+ *
+ * @internal
+ */
 export function viewQuery(params: URLSearchParams | string): string {
   const source = typeof params === "string" ? new URLSearchParams(params) : params;
   const out = new URLSearchParams();
@@ -73,7 +78,10 @@ export function viewQuery(params: URLSearchParams | string): string {
   return out.toString();
 }
 
-/** Whether a view matches the list's current state — used to mark the active one. */
+/** Whether a view matches the list's current state — used to mark the active one.
+ *
+ * @internal
+ */
 export function viewIsActive(view: SavedView, current: URLSearchParams | string): boolean {
   return viewQuery(view.query) === viewQuery(current);
 }

package/src/table/Filter.ts

@@ -22,7 +22,10 @@ export type QueryRule =
   | { type: "rule"; constraint: string; operator: string; value?: string }
   | { type: "group"; operator: Conjunction; rules: QueryRule[] };
 
-/** Parse the JSON a query-builder filter stores in the URL. Invalid input filters nothing. */
+/** Parse the JSON a query-builder filter stores in the URL. Invalid input filters nothing.
+ *
+ * @internal
+ */
 export function parseRuleTree(value: string): QueryRule | null {
   if (!value) return null;
   try {
@@ -48,6 +51,8 @@ function isRule(node: unknown): node is QueryRule {
  * "Advanced filter: 3 rules" tells someone their list is narrowed and by roughly
  * how much; the builder itself shows the detail. One rule gets named outright,
  * since that is the common case and the label fits.
+ *
+ * @internal
  */
 export function describeRuleTree(
   node: QueryRule | null,
@@ -73,7 +78,10 @@ export function describeRuleTree(
   return `${rules.length} rules`;
 }
 
-/** Does this tree actually constrain anything? An empty group is a no-op. */
+/** Does this tree actually constrain anything? An empty group is a no-op.
+ *
+ * @internal
+ */
 export function ruleTreeIsEmpty(node: QueryRule | null): boolean {
   if (!node) return true;
   if (node.type === "rule") return false;

package/src/theme.ts

@@ -20,7 +20,10 @@ import {
   THEME_TOGGLE_SCRIPT as FLOW_THEME_TOGGLE_SCRIPT,
 } from "@zerotal/flow-ui";
 
-/** localStorage key the toggle and the no-flash script share. */
+/** localStorage key the toggle and the no-flash script share.
+ *
+ * @internal
+ */
 export const THEME_STORAGE_KEY = FLOW_THEME_STORAGE_KEY;
 
 /** Client helpers (theme toggle + copy-to-clipboard), eval-free. */

package/src/widgets/Widget.ts

@@ -226,6 +226,8 @@ export type DashboardWidget = StatsWidget | ChartWidget | TableWidget;
 /**
  * The shortest poll interval among these widgets, or `undefined` when none
  * polls. The dashboard polls as one unit, so the keenest widget sets the pace.
+ *
+ * @internal
  */
 export function widgetPollInterval(widgets: DashboardWidget[]): string | undefined {
   const intervals = widgets.map((w) => w._poll).filter((i): i is string => Boolean(i));