feat(admin): allow trusted plugins to add content list columns

Author: logelog

.changeset/trusted-content-list-columns.md

@@ -0,0 +1,6 @@
+---
+"@emdash-cms/admin": minor
+"emdash": minor
+---
+
+Allow trusted React plugins to add manifest-aware, role-filtered content-list columns without taking ownership of the host table, pagination, or row actions.

docs/src/content/docs/plugins/creating-native-plugins/react-admin.mdx

@@ -5,7 +5,7 @@ description: Ship custom React components for plugin admin pages and dashboard w
 
 import { Aside, Tabs, TabItem } from "@astrojs/starlight/components";
 
-Native plugins can extend the admin panel with custom React pages and dashboard widgets — sandboxed plugins describe their UI as [Block Kit](/plugins/creating-plugins/block-kit/) instead, because shipping plugin JavaScript into the admin would break sandbox isolation.
+Native plugins can extend the admin panel with custom React pages, dashboard widgets, field widgets, and content-list columns — sandboxed plugins describe their UI as [Block Kit](/plugins/creating-plugins/block-kit/) instead, because shipping plugin JavaScript into the admin would break sandbox isolation.
 
 If your plugin only needs a settings form, the auto-generated `admin.settingsSchema` form (see [Your first native plugin](/plugins/creating-native-plugins/your-first-native-plugin/#settings-ui)) covers most cases without writing any React. Reach for custom components when you need richer UI than `settingsSchema` provides.
 
@@ -224,15 +224,53 @@ export function SEOWidget() {
 
 Widgets wrap automatically based on screen width.
 
+## Content-list columns
+
+Trusted React plugins can add read-only columns to active content collection lists. EmDash keeps ownership of the table, pagination, row actions, and loading and empty states; the plugin supplies only the header metadata and cell content.
+
+```typescript title="src/admin.tsx"
+import type {
+	ContentListColumnCellContext,
+	ContentListColumnExtension,
+} from "@emdash-cms/admin";
+
+function ScoreCell({ item }: ContentListColumnCellContext) {
+	const score = item.data.seoScore;
+	return typeof score === "number" ? <span>{score}</span> : <span>—</span>;
+}
+
+export const contentListColumns = [
+	{
+		id: "score",
+		label: "SEO score",
+		collections: ["posts", "pages"],
+		order: 10,
+		align: "end",
+		cell: ScoreCell,
+	},
+] satisfies readonly ContentListColumnExtension[];
+```
+
+Column ids only need to be unique within the plugin. Contributions are ordered by `order`, then plugin id and column id. A plugin can also provide:
+
+- `header`: a custom header component; `label` remains the host-rendered fallback.
+- `collections`: an array or predicate restricting where the column appears.
+- `minRole`: a visibility filter for the admin UI. This is not authorization; plugin API routes must still enforce access.
+
+Disabled or missing plugins are omitted. Invalid definitions, collection predicates that throw, and render failures are isolated so the host content list remains usable. Columns are not shown in Trash.
+
+Content-list columns are display-only. Server-backed sorting and filtering require a separate host data-provider contract; a browser comparator would only sort the currently loaded cursor pages and is therefore not supported by this API.
+
 ## Export structure
 
-The admin entry point exports two objects:
+The admin entry point exports each contribution directly:
 
 ```typescript title="src/admin.tsx"
 import { SettingsPage } from "./components/SettingsPage";
 import { ReportsPage } from "./components/ReportsPage";
 import { StatusWidget } from "./components/StatusWidget";
 import { OverviewWidget } from "./components/OverviewWidget";
+import { ScoreCell } from "./components/ScoreCell";
 
 export const pages = {
 	"/settings": SettingsPage,
@@ -243,10 +281,14 @@ export const widgets = {
 	status: StatusWidget,
 	overview: OverviewWidget,
 };
+
+export const contentListColumns = [
+	{ id: "score", label: "Score", collections: ["posts"], cell: ScoreCell },
+];
 ```
 
 <Aside type="caution">
-	Page paths in `pages` should match the `path` values in `admin.pages`. A trailing slash is treated as equivalent, so `/settings` and `/settings/` resolve to the same page. Opening a plugin at its root resolves to the first registered page. Widget keys must match the `id` values in `admin.widgets`.
+	Page paths in `pages` should match the `path` values in `admin.pages`. A trailing slash is treated as equivalent, so `/settings` and `/settings/` resolve to the same page. Opening a plugin at its root resolves to the first registered page. Widget keys must match the `id` values in `admin.widgets`. Content-list columns are discovered directly from the trusted admin entry point and do not need a separate descriptor entry.
 </Aside>
 
 ## Using admin components
@@ -344,6 +386,7 @@ When a plugin is disabled in the admin:
 
 - Sidebar links are hidden.
 - Dashboard widgets are not rendered.
+- Content-list columns are not rendered.
 - Admin pages return 404.
 - Backend hooks still execute (for data safety).
 

packages/admin/src/components/ContentList.tsx

@@ -27,8 +27,20 @@ import {
 import { Link } from "@tanstack/react-router";
 import * as React from "react";
 
-import type { ContentAuthor, ContentDateField, ContentItem, TrashedContentItem } from "../lib/api";
+import type {
+	AdminManifest,
+	ContentAuthor,
+	ContentDateField,
+	ContentItem,
+	TrashedContentItem,
+} from "../lib/api";
+import {
+	ContentListColumnBoundary,
+	resolveContentListColumns,
+	type ResolvedContentListColumn,
+} from "../lib/content-list-columns.js";
 import { useDebouncedValue } from "../lib/hooks.js";
+import { usePluginAdmins } from "../lib/plugin-context.js";
 import { contentUrl } from "../lib/url.js";
 import { cn } from "../lib/utils";
 import { CaretNext, CaretPrev } from "./ArrowIcons.js";
@@ -140,6 +152,10 @@ export interface ContentListProps {
 	onBulkPublish?: BulkActionHandler;
 	onBulkUnpublish?: BulkActionHandler;
 	onBulkDelete?: BulkActionHandler;
+	/** Current role used only for contributed-column visibility, not authorization. */
+	userRole?: number;
+	/** Manifest state used to omit disabled or stale trusted-plugin contributions. */
+	pluginStates?: AdminManifest["plugins"];
 }
 
 type BulkActionHandler = (ids: string[]) => Promise<string[]>;
@@ -197,8 +213,11 @@ export function ContentList({
 	onBulkPublish,
 	onBulkUnpublish,
 	onBulkDelete,
+	userRole = 0,
+	pluginStates,
 }: ContentListProps) {
 	const { t } = useLingui();
+	const pluginAdmins = usePluginAdmins();
 	const [activeTab, setActiveTab] = React.useState<ViewTab>("all");
 	const [searchQuery, setSearchQuery] = React.useState("");
 	const [page, setPage] = React.useState(0);
@@ -305,6 +324,10 @@ export function ContentList({
 			return next;
 		});
 	const selectedCount = selectedIds.size;
+	const extensionColumns = React.useMemo(
+		() => resolveContentListColumns(pluginAdmins, collection, userRole, pluginStates),
+		[collection, pluginAdmins, pluginStates, userRole],
+	);
 	const [bulkBusy, setBulkBusy] = React.useState(false);
 	const runBulk = (fn?: BulkActionHandler) => {
 		if (!fn || selectedCount === 0 || bulkBusy) return;
@@ -325,7 +348,8 @@ export function ContentList({
 			}
 		})();
 	};
-	const colSpan = (i18n ? 5 : 4) + listColumns.length + (bulkEnabled ? 1 : 0);
+	const colSpan =
+		(i18n ? 5 : 4) + listColumns.length + extensionColumns.length + (bulkEnabled ? 1 : 0);
 
 	return (
 		<div className="space-y-4">
@@ -543,6 +567,14 @@ export function ContentList({
 										onSortChange={onSortChange}
 										label={t`Date`}
 									/>
+									{extensionColumns.map((column) => (
+										<ExtensionColumnHeader
+											key={`${column.pluginId}:${column.extension.id}`}
+											column={column}
+											collection={collection}
+											locale={activeLocale}
+										/>
+									))}
 									<th scope="col" className="px-4 py-3 text-end text-sm font-medium">
 										{t`Actions`}
 									</th>
@@ -598,6 +630,7 @@ export function ContentList({
 											selectable={bulkEnabled}
 											selected={selectedIds.has(item.id)}
 											onToggleSelect={toggleOne}
+											extensionColumns={extensionColumns}
 										/>
 									))
 								)}
@@ -914,6 +947,37 @@ function SortableTh({ field, sort, onSortChange, label }: SortableThProps) {
 	);
 }
 
+interface ExtensionColumnHeaderProps {
+	column: ResolvedContentListColumn;
+	collection: string;
+	locale?: string;
+}
+
+function ExtensionColumnHeader({ column, collection, locale }: ExtensionColumnHeaderProps) {
+	const { pluginId, extension } = column;
+	const Header = extension.header;
+
+	return (
+		<th
+			scope="col"
+			aria-label={extension.label}
+			className={cn(
+				"px-4 py-3 text-sm font-medium",
+				extension.align === "end" ? "text-end" : "text-start",
+			)}
+		>
+			<ContentListColumnBoundary
+				key={`${collection}:${locale ?? ""}:${pluginId}:${extension.id}`}
+				pluginId={pluginId}
+				columnId={extension.id}
+				fallback={extension.label}
+			>
+				{Header ? <Header collection={collection} locale={locale} /> : extension.label}
+			</ContentListColumnBoundary>
+		</th>
+	);
+}
+
 /**
  * Render the row-count line above pagination. The rules are:
  * - A search query always wins — say how many matches there are. In
@@ -967,6 +1031,7 @@ interface ContentListItemProps {
 	selectable?: boolean;
 	selected?: boolean;
 	onToggleSelect?: (id: string) => void;
+	extensionColumns?: ResolvedContentListColumn[];
 }
 
 function ContentListItem({
@@ -980,6 +1045,7 @@ function ContentListItem({
 	selectable,
 	selected,
 	onToggleSelect,
+	extensionColumns,
 }: ContentListItemProps) {
 	const { t } = useLingui();
 	const title = getItemTitle(item);
@@ -1025,6 +1091,26 @@ function ContentListItem({
 			<td data-testid="content-updated" className="px-4 py-3 text-sm text-kumo-subtle">
 				{date.toLocaleDateString()}
 			</td>
+			{extensionColumns?.map(({ pluginId, extension }) => {
+				const Cell = extension.cell;
+				return (
+					<td
+						key={`${pluginId}:${extension.id}`}
+						className={cn(
+							"px-4 py-3 text-sm",
+							extension.align === "end" ? "text-end" : "text-start",
+						)}
+					>
+						<ContentListColumnBoundary
+							key={`${collection}:${item.locale}:${item.id}:${item.updatedAt}:${pluginId}:${extension.id}`}
+							pluginId={pluginId}
+							columnId={extension.id}
+						>
+							<Cell collection={collection} item={item} locale={item.locale} />
+						</ContentListColumnBoundary>
+					</td>
+				);
+			})}
 			<td className="px-4 py-3 text-end">
 				<div className="flex items-center justify-end space-x-1">
 					{item.status === "published" && item.slug && (

packages/admin/src/index.ts

@@ -26,6 +26,12 @@ export {
 	type PluginAdmins,
 } from "./lib/plugin-context";
 
+export type {
+	ContentListColumnHeaderContext,
+	ContentListColumnCellContext,
+	ContentListColumnExtension,
+} from "./lib/content-list-columns";
+
 // Auth provider context (for accessing pluggable auth provider components)
 export {
 	AuthProviderProvider,