@zerotal/admin 1.8.1 → 1.9.0

package/CHANGELOG.md

@@ -8,6 +8,28 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.9.0] — 2026-08-29
+
+### Documented
+
+- **Every promised export is documented.** The `docs-coverage` gate reads `maturity: stable` as a
+  promise about a package's exports, and measures how much of that promise is written down. It
+  was 798 gaps across the suite; it is now zero. This package's share is covered on its own
+  pages — types named, options shapes described, and the decisions behind them recorded where
+  somebody looking for them will find them.
+
+### Changed
+
+- **INTERNAL: the panel's own page machinery is marked `@internal`.** The `make*Page` factories,
+  the page classes they produce (`ResourceListPage`, `RecordViewPage`, `ResourceFormPage`,
+  `RolesPage`, `MediaPage`, `NotificationsPage`, `ConsolePage`, …), the action and widget
+  renderers, and `AdminPanelHost`.
+
+  **Nothing is removed and nothing breaks** — they are still exported and still work. An app
+  declares a `Resource` and the panel builds these pages from it; none of them has a caller
+  outside `@zerotal/admin` or a line in the guide, because writing one was never the way to use
+  this package.
+
 ## [1.6.0] — 2026-08-15
 
 ### Fixed

package/api-surface.md

@@ -1114,12 +1114,6 @@ interface ActionContext = {
   slug: string
 }
 
-interface ActionPage = {
-  download?: (filename: string, content: string | Uint8Array, mime?: string) => unknown
-  flash: (message: string, level?: string) => unknown
-  redirect: (url: string) => {    withSuccess(message: string): unknown;}
-}
-
 interface AdminAuthConfig = {
   authMiddleware?: MiddlewareClass[]
   authenticateWhen?: (user: unknown) => boolean | Promise<boolean>
@@ -1170,18 +1164,6 @@ interface AdminNotification = {
   title: string
 }
 
-interface AdminPanelHost = {
-  console: (contribution: ConsoleContribution) => void
-  enabled: (id: string) => boolean
-  navItem: (contribution: NavContribution) => void
-  page: (contribution: PageContribution) => void
-  renderHook: (name: string, hook: (context: RenderHookContext) => HtmlNode | string | null) => void
-  searchProvider: (provider: PanelSearchProvider) => void
-  topbarSlot: (slot: TopbarSlot) => void
-  userMenuItem: (item: UserMenuContribution) => void
-  widget: (contribution: WidgetContribution) => void
-}
-
 interface AdminPlugin = {
   id: string
   install: (panel: AdminPanelHost) => void | Promise<void>
@@ -1492,22 +1474,6 @@ interface PageContribution = {
   title: string
 }
 
-interface PanelPage = {
-  ability: string | undefined
-  cluster?: typeof Cluster | undefined
-  navigationBadge?: (() => Promise<string | number | null> | string | number | null) | undefined
-  navigationBadgeColor?: BadgeTone | undefined
-  navigationGroup: string | undefined
-  navigationIcon: string
-  navigationLabel: string
-  navigationSort: number
-  page: PanelPageClass
-  routeParams: string[]
-  showInNavigation: boolean
-  slug: string
-  title: string
-}
-
 interface PanelSearchProvider = {
   ability: string
   icon?: string
@@ -1527,19 +1493,6 @@ interface PivotColumn = {
   label?: string
 }
 
-interface RecordPage = {
-  lastPage: number
-  page: number
-  perPage: number
-  rows: Record<string, unknown>[]
-  total: number
-}
-
-interface RenderableCell = {
-  badge?: BadgeTone | undefined
-  text: string
-}
-
 interface RenderHookContext = {
   page?: 'list' | 'record' | 'form' | 'dashboard' | undefined
   recordId?: string | undefined
@@ -1663,8 +1616,6 @@ type ActionVisible = (record: AdminRecord | undefined, ctx: ActionContext) => bo
 
 type AdminAuthorizer = (ability: string) => boolean | Promise<boolean>
 
-type AdminPageClass = typeof AdminPage & (new () => AdminPage)
-
 type BadgeTone = 'default' | 'primary' | 'success' | 'muted' | 'destructive'
 
 type CalloutTone = 'default' | 'primary' | 'success' | 'warning' | 'destructive'
@@ -1675,8 +1626,6 @@ type ChartResolver = () => Promise<ChartData> | ChartData
 
 type ChartType = 'line' | 'bar' | 'doughnut' | 'pie'
 
-type ClusterClass = typeof Cluster
-
 type ColumnKind = 'text' | 'toggle' | 'select' | 'input' | 'image' | 'color' | 'icon'
 
 type Conjunction = 'and' | 'or'
@@ -1711,8 +1660,6 @@ type FormComponent = FormSection | FormTabs | Wizard | FormSplit | Callout | Pri
 
 type InfolistComponent = Section | Entry
 
-type PanelPageClass = new () => object
-
 type PrimeKind = 'text' | 'html' | 'image'
 
 type QueryModifier = (query: AdminQuery) => AdminQuery
@@ -1727,8 +1674,6 @@ type RenderHookName = 'body.start' | 'body.end' | 'sidebar.start' | 'sidebar.end
 
 type ResourceClass = typeof Resource
 
-type ResourceFormClass = new () => Form & Record<string, unknown>
-
 type StatsResolver = () => Promise<Stat[]> | Stat[]
 
 type SummaryKind = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'range'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/admin",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -32,16 +32,16 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/cache": "1.8.1",
-    "@zerotal/core": "1.8.1",
-    "@zerotal/flow": "1.8.1",
-    "@zerotal/flow-ui": "1.8.1",
-    "@zerotal/validator": "1.8.1"
+    "@zerotal/cache": "1.9.0",
+    "@zerotal/core": "1.9.0",
+    "@zerotal/flow": "1.9.0",
+    "@zerotal/flow-ui": "1.9.0",
+    "@zerotal/validator": "1.9.0"
   },
   "devDependencies": {
-    "@zerotal/orm": "1.8.1",
-    "@zerotal/auth": "1.8.1",
-    "@zerotal/queue": "1.8.1"
+    "@zerotal/orm": "1.9.0",
+    "@zerotal/auth": "1.9.0",
+    "@zerotal/queue": "1.9.0"
   },
   "peerDependencies": {
     "@zerotal/orm": "^1.0.0",

package/src/Cluster.ts

@@ -46,5 +46,9 @@ export abstract class Cluster {
   }
 }
 
-/** A Cluster subclass (used by its static surface — never instantiated). */
+/**
+ * A Cluster subclass (used by its static surface — never instantiated).
+ *
+ * @internal
+ */
 export type ClusterClass = typeof Cluster;

package/src/PanelInstance.ts

@@ -72,6 +72,8 @@ export interface NavGroup {
  * A registered custom page, normalized from either door — an {@link AdminPage}
  * subclass registered by the app, or a {@link PageContribution} pushed in by a
  * package.
+ *
+ * @internal
  */
 export interface PanelPage {
   slug: string;

package/src/Resource.ts

@@ -114,6 +114,7 @@ export interface EmptyState {
   actions?: ActionItem[];
 }
 
+/** @internal */
 export interface RecordPage {
   rows: Record<string, unknown>[];
   total: number;

package/src/actions/Action.ts

@@ -25,7 +25,11 @@ import { flattenFields } from "../form/index.ts";
 
 export type ActionColor = "default" | "primary" | "success" | "muted" | "destructive";
 
-/** Minimal view of the host page an action handler can drive (flash/redirect). */
+/**
+ * Minimal view of the host page an action handler can drive (flash/redirect).
+ *
+ * @internal
+ */
 export interface ActionPage {
   flash(message: string, level?: string): unknown;
   redirect(url: string): { withSuccess(message: string): unknown };

package/src/actions/render.tsx

@@ -27,7 +27,11 @@ export interface RenderActionOptions {
   args?: unknown[];
 }
 
-/** Render a single action. Link actions become `<a navigate>`, callbacks `<button>`. */
+/**
+ * Render a single action. Link actions become `<a navigate>`, callbacks `<button>`.
+ *
+ * @internal
+ */
 export function renderAction(
   a: Action,
   ctx: ActionContext,
@@ -92,6 +96,8 @@ export function renderAction(
  * 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.
+ *
+ * @internal
  */
 export function renderActionGroup(
   group: ActionGroup,
@@ -128,6 +134,8 @@ export function renderActionGroup(
 /**
  * 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.
+ *
+ * @internal
  */
 export function renderActionMenuItem(
   a: Action,

package/src/auth/AuthLayout.tsx

@@ -7,6 +7,7 @@ import type { HtmlNode } from "@zerotal/flow";
 import { Panel } from "../Panel.ts";
 import { adminHead } from "../theme.ts";
 
+/** @internal */
 export class AuthLayout extends Layout {
   static override get head(): string {
     const cfg = Panel.config();

package/src/form/ResourceForm.ts

@@ -16,6 +16,7 @@ import type { RuleBuilder, FieldRule } from "@zerotal/validator";
 import type { Field, FieldMode } from "./Field.ts";
 import { type FormComponent, flattenFields } from "./Section.ts";
 
+/** @internal */
 export type ResourceFormClass = new () => Form & Record<string, unknown>;
 
 /** @internal */

package/src/pages/AdminPage.ts

@@ -96,5 +96,7 @@ export abstract class AdminPage extends Component {
 /**
  * A concrete {@link AdminPage} subclass — the static metadata above, plus the
  * zero-argument constructor Flow builds the page with.
+ *
+ * @internal
  */
 export type AdminPageClass = typeof AdminPage & (new () => AdminPage);

package/src/pages/ConsolePage.tsx

@@ -36,6 +36,7 @@ const ALIGN: Record<string, string> = {
   end: "text-right tabular-nums",
 };
 
+/** @internal */
 export class ConsolePage extends Component {
   static layout = AdminLayout;
 
@@ -304,6 +305,8 @@ function cell(c: ConsoleColumn, row: ConsoleRow): HtmlNode | string {
  * shared class resolving itself from the route — keeps the console on a static
  * and matches how resource list pages are generated. The explicit name matters:
  * Flow's component registry is keyed by constructor name.
+ *
+ * @internal
  */
 export function makeConsolePage(
   console: ConsoleContribution,

package/src/pages/DashboardPage.tsx

@@ -253,7 +253,11 @@ export class DashboardPage extends Component {
   }
 }
 
-/** The dashboard for one panel, showing only that panel's resources and widgets. */
+/**
+ * The dashboard for one panel, showing only that panel's resources and widgets.
+ *
+ * @internal
+ */
 export function makeDashboardPage(panel: PanelInstance = Panel.default()): typeof DashboardPage {
   const Page = class extends DashboardPage {
     static override panel = panel;

package/src/pages/MediaPage.tsx

@@ -15,6 +15,7 @@ import { deleteMedia, formatSize, isImage, isUpload, mediaUrl, storeMedia } from
 /** How many files the grid shows before the "load more" step. */
 const PAGE_SIZE = 60;
 
+/** @internal */
 export class MediaPage extends Component {
   static layout = AdminLayout;
   /** The panel this page belongs to — set by each generated subclass. */
@@ -338,7 +339,11 @@ export class MediaPage extends Component {
   }
 }
 
-/** Build a MediaPage bound to one panel. */
+/**
+ * Build a MediaPage bound to one panel.
+ *
+ * @internal
+ */
 export function makeMediaPage(panel: PanelInstance = Panel.default()): typeof MediaPage {
   return class BoundMediaPage extends MediaPage {
     static override panel = panel;

package/src/pages/NotificationsPage.tsx

@@ -10,6 +10,7 @@ import { Icon } from "../ui/icons.tsx";
 import { Panel } from "../Panel.ts";
 import type { PanelInstance } from "../PanelInstance.ts";
 
+/** @internal */
 export class NotificationsPage extends Component {
   static layout = AdminLayout;
   /** The panel this page belongs to — set by each generated subclass. */
@@ -142,7 +143,11 @@ export class NotificationsPage extends Component {
   }
 }
 
-/** The notification centre for one panel, reading that panel's provider. */
+/**
+ * The notification centre for one panel, reading that panel's provider.
+ *
+ * @internal
+ */
 export function makeNotificationsPage(
   panel: PanelInstance = Panel.default(),
 ): typeof NotificationsPage {

package/src/pages/RecordViewPage.tsx

@@ -95,6 +95,7 @@ interface PivotProxy {
   all?: () => unknown;
 }
 
+/** @internal */
 export class RecordViewPage extends Component {
   static layout = AdminLayout;
   /** Set by each generated subclass. */
@@ -925,6 +926,8 @@ export class RecordViewPage extends Component {
 /**
  * Build a uniquely-named View page subclass bound to a resource — mirrors
  * {@link makeResourceListPage} so Flow keeps component identity stable.
+ *
+ * @internal
  */
 export function makeRecordViewPage(
   resource: ResourceClass,

package/src/pages/ResourceFormPage.tsx

@@ -63,7 +63,11 @@ const _formRegistry = new Map<string, FormMeta>();
 
 const formKey = (panelId: string, slug: string): string => `${panelId}:${slug}`;
 
-/** Register a resource's form config so the shared page can resolve it. */
+/**
+ * Register a resource's form config so the shared page can resolve it.
+ *
+ * @internal
+ */
 export function registerResourceForm(panelId: string, slug: string, meta: FormMeta): void {
   _formRegistry.set(formKey(panelId, slug), meta);
 }
@@ -72,6 +76,7 @@ const SPAN_CLASS = ["", "", "sm:col-span-2", "sm:col-span-3", "sm:col-span-4"];
 const INPUT_CLASS =
   "mt-1.5 block w-full rounded-lg border border-input bg-background px-3 py-2 text-sm text-foreground shadow-sm outline-none transition placeholder:text-muted-foreground focus:ring-2 focus:ring-ring focus:ring-offset-2 focus:ring-offset-background disabled:cursor-not-allowed disabled:opacity-60";
 
+/** @internal */
 export class ResourceFormPage extends Component {
   @locked slug = "";
   @locked mode: FieldMode = "create";

package/src/pages/ResourceListPage.tsx

@@ -104,6 +104,7 @@ function parseFilters(s: string): Record<string, string> {
   }
 }
 
+/** @internal */
 export class ResourceListPage extends Component {
   static layout = AdminLayout;
   /** Set by each generated subclass. */
@@ -2535,6 +2536,8 @@ export class ResourceListPage extends Component {
 /**
  * Build a uniquely-named List page subclass bound to a resource. The distinct
  * class name keeps Flow's snapshot/component identity stable per resource.
+ *
+ * @internal
  */
 export function makeResourceListPage(
   resource: ResourceClass,

package/src/pages/RolesPage.tsx

@@ -12,6 +12,7 @@ import type { PanelInstance } from "../PanelInstance.ts";
 import type { Permission, Role } from "../roles.ts";
 import { groupPermissions, panelPermissions, roleHas } from "../roles.ts";
 
+/** @internal */
 export class RolesPage extends Component {
   static layout = AdminLayout;
   /** The panel this page belongs to — set by each generated subclass. */
@@ -317,7 +318,11 @@ export class RolesPage extends Component {
   }
 }
 
-/** Build a RolesPage bound to one panel. */
+/**
+ * Build a RolesPage bound to one panel.
+ *
+ * @internal
+ */
 export function makeRolesPage(panel: PanelInstance = Panel.default()): typeof RolesPage {
   return class BoundRolesPage extends RolesPage {
     static override panel = panel;

package/src/pages/SearchPage.tsx

@@ -158,7 +158,11 @@ export class SearchPage extends Component {
   }
 }
 
-/** The search page for one panel, searching only that panel's resources. */
+/**
+ * The search page for one panel, searching only that panel's resources.
+ *
+ * @internal
+ */
 export function makeSearchPage(panel: PanelInstance = Panel.default()): typeof SearchPage {
   const Page = class extends SearchPage {
     static override panel = panel;

package/src/plugin.ts

@@ -40,6 +40,8 @@ import type { RenderHookContext } from "./renderHooks.ts";
  * over without importing anything from `@zerotal/admin`. The panel gives the page
  * its own layout when it mounts the route, so a contributed page renders only its
  * content and inherits the panel's chrome.
+ *
+ * @internal
  */
 export type PanelPageClass = new () => object;
 
@@ -245,6 +247,8 @@ export interface UserMenuContribution {
  * Contributors should declare their own minimal copy of the members they use
  * rather than importing this type, so they depend on the admin package at build
  * time not at all.
+ *
+ * @internal
  */
 export interface AdminPanelHost {
   /**

package/src/table/Column.ts

@@ -37,6 +37,7 @@ export interface SummaryResult {
   text: string;
 }
 
+/** @internal */
 export interface RenderableCell {
   /** Pre-escaped/plain text, or a badge descriptor. */
   text: string;

package/src/ui/AdminLayout.tsx

@@ -15,6 +15,7 @@ import { Icon } from "./icons.tsx";
 import { Command, Toaster, Sidebar } from "@zerotal/flow-ui";
 import type { CommandItem, SidebarItem, SidebarGroup } from "@zerotal/flow-ui";
 
+/** @internal */
 export class AdminLayout extends Layout {
   /**
    * The panel this shell belongs to. The base class serves whichever panel owns
@@ -335,6 +336,8 @@ export class AdminLayout extends Layout {
  * The router keys shell persistence on the layout class name, so each panel needs
  * a class of its own: without that, navigating from one panel to another would
  * swap the content while leaving the previous panel's sidebar in place.
+ *
+ * @internal
  */
 export function makeAdminLayout(panel: PanelInstance): typeof AdminLayout {
   const cached = LAYOUTS.get(panel);

package/src/widgets/render.tsx

@@ -45,6 +45,8 @@ export function chartInitScript(configs: unknown[]): string {
  *
  * Returns `null` when there is nothing to draw, so a caller can drop the whole
  * block rather than leaving an empty gap above its table.
+ *
+ * @internal
  */
 export async function renderWidgets(
   widgets: DashboardWidget[],