@happyvertical/smrt-content 0.43.3 → 0.43.4

package/dist/svelte/components/ContentList.svelte

@@ -1,11 +1,37 @@
 <script lang="ts">
+import { DataTable, type DataTableColumn } from '@happyvertical/smrt-ui/data';
 import { ConfirmDialog } from '@happyvertical/smrt-ui/feedback';
-import { Input, Select } from '@happyvertical/smrt-ui/forms';
+import { Checkbox, Input, Select } from '@happyvertical/smrt-ui/forms';
 import { useI18n } from '@happyvertical/smrt-ui/i18n';
-import { Button } from '@happyvertical/smrt-ui/ui';
+import { Button, Pagination } from '@happyvertical/smrt-ui/ui';
 import type { Snippet } from 'svelte';
 import { untrack } from 'svelte';
 import type { ContentData } from '../../mock-smrt-client.js';
+import {
+  applyContentListFilter,
+  buildContentListColumns,
+  buildContentListSurfaceDescriptor,
+  CONTENT_LIST_ACTIONS_COLUMN_ID,
+  CONTENT_LIST_ROW_KEY,
+  CONTENT_LIST_SELECTION_COLUMN_ID,
+  CONTENT_LIST_STATUS_FILTER_ID,
+  CONTENT_LIST_TYPE_FILTER_ID,
+  type ContentListDataSurface,
+  type ContentListRow,
+  type ContentListViewMode,
+  contentListRowActions,
+  contentStateVariant,
+  contentStatusVariant,
+  createContentListController,
+  isContentListFilterExactly,
+  normalizeContentType,
+  paginateContentListRows,
+  readContentListFilter,
+  resolveContentHref,
+  selectableContentListRowIds,
+  selectContentListRows,
+  toContentListRows,
+} from '../content-list-controller.js';
 import { M } from '../i18n.contribution.js';
 import ImageThumbnail from './ImageThumbnail.svelte';
 
@@ -15,12 +41,20 @@ interface Props {
   apiBaseUrl?: string;
   contents: ContentData[];
   type?: string;
-  defaultViewMode?: 'grid' | 'detailed' | 'compact';
+  defaultViewMode?: ContentListViewMode;
   onEdit: (content: ContentData) => void;
   onDelete: (content: ContentData) => void;
   onAdd: () => void;
   controls?: Snippet;
   getViewHref?: (content: ContentData) => string | null;
+  /** Announced uniformly by every presentation; #2455 extends it. */
+  loading?: boolean;
+  /** Load failure announced instead of the list. */
+  error?: string | null;
+  /** Retry affordance rendered with an error. */
+  onRetry?: () => void;
+  /** Opt-in agent addressability. Non-table presentations land with #2456. */
+  dataSurface?: ContentListDataSurface;
 }
 
 let {
@@ -33,154 +67,407 @@ let {
   onAdd,
   controls,
   getViewHref = undefined,
+  loading = false,
+  error = null,
+  onRetry = undefined,
+  dataSurface = undefined,
 }: Props = $props();
 
-let searchTerm = $state('');
-let selectedType = $state('All Types');
-let selectedStatus = $state('All Statuses');
-let viewMode: 'grid' | 'detailed' | 'compact' = $state(
-  untrack(() => defaultViewMode),
+// One controller owns search, filters, sorting, paging, and selection for
+// every presentation. The view mode lives beside it, so switching presentation
+// never touches query or selection state.
+// The seed is intentionally the initial `type`; the effect below keeps the
+// locked filter in sync afterwards.
+const controller = createContentListController({
+  type: untrack(() => type),
+});
+let snapshot = $state(controller.snapshot());
+let viewMode: ContentListViewMode = $state(untrack(() => defaultViewMode));
+let pendingDelete = $state<ContentListRow | null>(null);
+
+$effect(() =>
+  controller.subscribe((transition) => {
+    snapshot = transition.next;
+  }),
+);
+
+const tableState = $derived(snapshot.state);
+
+/** The normalized type the `type` prop locks the list to, if any. */
+const lockedType = $derived(type?.trim() ? normalizeContentType(type) : null);
+
+// A `type` prop locks the type filter, exactly as the legacy select did. The
+// lock is enforced against the live state, not only against the prop, because a
+// data-surface `set-filters` or `reset` command can otherwise replace or clear
+// it. The equality guard keeps the effect from dispatching in a loop.
+$effect(() => {
+  const locked = lockedType;
+  if (locked === null) {
+    // Unlocked: the toolbar select owns the filter. Only reading `type` here
+    // keeps the legacy behaviour of clearing it when the prop is removed.
+    untrack(() =>
+      applyContentListFilter(controller, CONTENT_LIST_TYPE_FILTER_ID, null),
+    );
+    return;
+  }
+  if (
+    isContentListFilterExactly(tableState, CONTENT_LIST_TYPE_FILTER_ID, locked)
+  )
+    return;
+  untrack(() =>
+    applyContentListFilter(controller, CONTENT_LIST_TYPE_FILTER_ID, locked),
+  );
+});
+
+const columnLabels = $derived({
+  type: t(M['content.content_list.column_type']),
+  title: t(M['content.content_list.column_title']),
+  author: t(M['content.content_list.column_author']),
+  status: t(M['content.content_list.column_status']),
+  state: t(M['content.content_list.column_state']),
+  publish: t(M['content.content_list.column_publish']),
+  updated: t(M['content.content_list.column_updated']),
+  site: t(M['content.content_list.column_site']),
+});
+
+const queryColumns = $derived(buildContentListColumns(columnLabels));
+const rows = $derived(toContentListRows(contents));
+const queryRows = $derived(
+  selectContentListRows(rows, tableState, queryColumns),
 );
+const pageRows = $derived(paginateContentListRows(queryRows, tableState));
 
+// The adapter owns filtering, sorting, and paging, so the controller's page has
+// to be clamped against the adapter's result count rather than DataTable's.
 $effect(() => {
-  selectedType = type || 'All Types';
+  const totalRows = queryRows.length;
+  untrack(() => controller.clampPage(totalRows));
 });
 
-function getTextValue(value: unknown): string {
-  return typeof value === 'string' ? value : '';
+// The card presentations have to render their own page controls: DataTable —
+// and with it the page navigation — is only mounted in compact mode, so a page
+// size set from a saved view or a surface command would otherwise strand the
+// operator on page one.
+const totalPages = $derived(
+  tableState.pageSize
+    ? Math.max(1, Math.ceil(queryRows.length / tableState.pageSize))
+    : 1,
+);
+const showPagination = $derived(Boolean(tableState.pageSize) && totalPages > 1);
+/** Rows are already rendered, so a load is a refresh rather than a first fill. */
+const refreshing = $derived(loading && pageRows.length > 0);
+
+const selectedRowKeys = $derived(
+  new Set(tableState.selectedRowIds.map((rowId) => String(rowId))),
+);
+// Only durable rows may be addressed by a selection.
+const identifiedRowKeys = $derived(
+  new Set(selectableContentListRowIds(rows).map((rowId) => String(rowId))),
+);
+const selectablePageRowIds = $derived(selectableContentListRowIds(pageRows));
+const allPageSelected = $derived(
+  selectablePageRowIds.length > 0 &&
+    selectablePageRowIds.every((rowId) => selectedRowKeys.has(String(rowId))),
+);
+const somePageSelected = $derived(
+  !allPageSelected &&
+    selectablePageRowIds.some((rowId) => selectedRowKeys.has(String(rowId))),
+);
+const selectedCount = $derived(tableState.selectedRowIds.length);
+
+// DataTable's own selection column and data-surface commands can both introduce
+// ids for rows that carry no durable identity. Normalizing here covers every
+// path at once; re-dispatching only on a real difference keeps it settling.
+$effect(() => {
+  const selected = tableState.selectedRowIds;
+  const durable = selected.filter((rowId) =>
+    identifiedRowKeys.has(String(rowId)),
+  );
+  if (durable.length === selected.length) return;
+  untrack(() =>
+    controller.dispatch({ type: 'setSelectedRows', rowIds: durable }),
+  );
+});
+
+const selectedType = $derived(
+  readContentListFilter(tableState, CONTENT_LIST_TYPE_FILTER_ID) ?? '',
+);
+const selectedStatus = $derived(
+  readContentListFilter(tableState, CONTENT_LIST_STATUS_FILTER_ID) ?? '',
+);
+
+const surfaceOptions = $derived(
+  dataSurface
+    ? {
+        registry: dataSurface.registry,
+        descriptor:
+          dataSurface.descriptor ??
+          buildContentListSurfaceDescriptor({ columnLabels }),
+      }
+    : undefined,
+);
+
+function isSelected(row: ContentListRow): boolean {
+  return selectedRowKeys.has(String(row.id));
 }
 
-function getDisplayTitle(content: ContentData): string {
-  return getTextValue(content.title) || 'Untitled content';
+function toggleRow(row: ContentListRow) {
+  if (!row.identified) return;
+  controller.dispatch({ type: 'toggleRowSelection', rowId: row.id });
 }
 
-function getDisplayDescription(content: ContentData): string {
-  return getTextValue(content.description);
+function togglePageSelection() {
+  const remaining = tableState.selectedRowIds.filter(
+    (rowId) =>
+      !selectablePageRowIds.some(
+        (pageRowId) => String(pageRowId) === String(rowId),
+      ),
+  );
+  controller.dispatch({
+    type: 'setSelectedRows',
+    rowIds: allPageSelected
+      ? remaining
+      : [...remaining, ...selectablePageRowIds],
+  });
 }
 
-function getDisplayAuthor(content: ContentData): string {
-  return getTextValue(content.author);
+function clearSelection() {
+  controller.dispatch({ type: 'setSelectedRows', rowIds: [] });
 }
 
-function getNormalizedType(value: unknown): string {
-  return getTextValue(value).toLowerCase() || 'content';
+function handlePageChange(page: number) {
+  controller.dispatch({ type: 'setPage', page });
 }
 
-const filteredContents = $derived(
-  contents.filter((content: ContentData) => {
-    const title = getDisplayTitle(content);
-    const description = getDisplayDescription(content);
-    const author = getDisplayAuthor(content);
-
-    const matchesSearch =
-      searchTerm === '' ||
-      title.toLowerCase().includes(searchTerm.toLowerCase()) ||
-      description.toLowerCase().includes(searchTerm.toLowerCase()) ||
-      author.toLowerCase().includes(searchTerm.toLowerCase());
-
-    const isLockedType = !!type;
-    const matchesType = isLockedType
-      ? content.type === type
-      : selectedType === 'All Types' ||
-        (selectedType === 'Articles' && content.type === 'article') ||
-        (selectedType === 'Documents' && content.type === 'document') ||
-        (selectedType === 'Mirrors' && content.type === 'mirror');
-
-    const matchesStatus =
-      selectedStatus === 'All Statuses' ||
-      content.status.toLowerCase() === selectedStatus.toLowerCase();
-
-    return matchesSearch && matchesType && matchesStatus;
-  }),
-);
+function handleSearch(value: string) {
+  controller.dispatch({ type: 'setSearch', search: value });
+}
 
-function getTypeLabel(value: unknown) {
-  switch (getNormalizedType(value)) {
-    case 'article':
-      return 'Article';
-    case 'mirror':
-      return 'Mirror';
-    case 'document':
-      return 'Document';
-    default:
-      return 'Content';
-  }
+function handleFilter(columnId: string, value: string) {
+  applyContentListFilter(controller, columnId, value || null);
 }
 
-function getStatusBadge(value: unknown) {
-  switch (getTextValue(value).toLowerCase()) {
-    case 'published':
-      return 'published';
-    case 'draft':
-      return 'draft';
-    case 'archived':
-      return 'archived';
-    default:
-      return 'unknown';
-  }
+function rowActions(row: ContentListRow) {
+  return contentListRowActions(row, { getViewHref });
 }
 
-function getStateBadge(value: unknown) {
-  switch (getTextValue(value).toLowerCase()) {
-    case 'highlighted':
-      return 'highlighted';
-    case 'active':
-      return 'active';
-    case 'deprecated':
-      return 'deprecated';
-    default:
-      return 'unknown';
-  }
+function viewHref(row: ContentListRow): string | null {
+  return resolveContentHref(row.content, getViewHref);
 }
 
-let pendingDelete = $state<ContentData | null>(null);
+function selectRowLabel(row: ContentListRow): string {
+  return isSelected(row)
+    ? t(M['content.content_list.deselect_row'], { title: row.title })
+    : t(M['content.content_list.select_row'], { title: row.title });
+}
 
-function handleDeleteContent(content: ContentData) {
-  pendingDelete = content;
+function handleDeleteContent(row: ContentListRow) {
+  pendingDelete = row;
 }
 
 function confirmDelete() {
   const target = pendingDelete;
   pendingDelete = null;
   if (target) {
-    onDelete(target);
+    onDelete(target.content);
   }
 }
 
 function cancelDelete() {
   pendingDelete = null;
 }
+
+/**
+ * Compact mode renders the shared columns with content-specific cells.
+ *
+ * Selection is a content-owned column rather than DataTable's built-in one:
+ * DataTable has no per-row selection predicate, so its header select-all would
+ * address the synthetic id of an unidentified row, which the normalization
+ * effect then strips — leaving the header permanently indeterminate. Owning the
+ * column keeps compact select-all identical to the card presentations.
+ */
+const tableColumns: DataTableColumn<ContentListRow>[] = $derived([
+  {
+    id: CONTENT_LIST_SELECTION_COLUMN_ID,
+    label: t(M['content.content_list.select_all']),
+    role: 'action',
+    align: 'center',
+    width: '3rem',
+    sortable: false,
+    searchable: false,
+    filterable: false,
+    header: selectHeader,
+    cell: selectCell,
+  },
+  ...queryColumns.map((column) => {
+    if (column.id === 'type') return { ...column, cell: typeCell };
+    if (column.id === 'title') return { ...column, cell: titleCell };
+    if (column.id === 'status') return { ...column, cell: statusCell };
+    if (column.id === 'state') return { ...column, cell: stateCell };
+    if (column.id === 'publish') return { ...column, cell: publishCell };
+    if (column.id === 'updated') return { ...column, cell: updatedCell };
+    return column;
+  }),
+  {
+    id: CONTENT_LIST_ACTIONS_COLUMN_ID,
+    label: t(M['content.content_list.actions_column']),
+    role: 'action',
+    align: 'right',
+    sortable: false,
+    searchable: false,
+    filterable: false,
+    cell: actionsCell,
+  },
+]);
 </script>
 
+{#snippet tableEmptyState()}
+  <p class="table-empty-state">{t(M['content.content_list.empty'])}</p>
+{/snippet}
+
+{#snippet selectHeader()}
+  <Checkbox
+    checked={allPageSelected}
+    indeterminate={somePageSelected}
+    aria-label={t(M['content.content_list.select_all'])}
+    onchange={togglePageSelection}
+  />
+{/snippet}
+
+{#snippet selectCell({ row }: { row: ContentListRow })}
+  <Checkbox
+    checked={isSelected(row)}
+    disabled={!row.identified}
+    aria-label={selectRowLabel(row)}
+    title={row.identified
+      ? undefined
+      : t(M['content.content_list.row_not_selectable'])}
+    onchange={() => toggleRow(row)}
+  />
+{/snippet}
+
+{#snippet typeCell({ row }: { row: ContentListRow })}
+  <span class={`type-pill type-pill--${row.type}`}>{row.typeLabel}</span>
+{/snippet}
+
+{#snippet titleCell({ row }: { row: ContentListRow })}
+  {#if viewHref(row)}
+    <a class="title-link" href={viewHref(row)}>{row.title}</a>
+  {:else}
+    <strong>{row.title}</strong>
+  {/if}
+{/snippet}
+
+{#snippet statusCell({ row }: { row: ContentListRow })}
+  <span class="badge status-{contentStatusVariant(row.status)}">{row.statusLabel}</span>
+{/snippet}
+
+{#snippet stateCell({ row }: { row: ContentListRow })}
+  <span class="badge state-{contentStateVariant(row.state)}">{row.stateLabel}</span>
+{/snippet}
+
+{#snippet publishCell({ row }: { row: ContentListRow })}
+  {row.publishLabel || '-'}
+{/snippet}
+
+{#snippet updatedCell({ row }: { row: ContentListRow })}
+  {row.updatedLabel || '-'}
+{/snippet}
+
+{#snippet actionsCell({ row }: { row: ContentListRow })}
+  {@const actions = rowActions(row)}
+  <div class="actions-cell">
+    {#if actions.includes('view')}
+      <a
+        class="icon-btn"
+        href={viewHref(row)}
+        title={t(M['content.content_list.view_published_article'])}
+        aria-label={t(M['content.content_list.view_published_article'])}
+      >
+        <span aria-hidden="true">🔎</span>
+      </a>
+    {/if}
+    {#if actions.includes('edit')}
+      <Button
+        variant="ghost"
+        size="sm"
+        class="icon-btn"
+        type="button"
+        onclick={() => onEdit(row.content)}
+        title={t(M['content.content_list.edit'])}
+        aria-label={t(M['content.content_list.edit'])}
+      >
+        <span aria-hidden="true">✏️</span>
+      </Button>
+    {/if}
+    {#if actions.includes('delete')}
+      <Button
+        variant="ghost"
+        size="sm"
+        class="icon-btn delete-icon"
+        type="button"
+        onclick={() => handleDeleteContent(row)}
+        title={t(M['content.content_list.delete'])}
+        aria-label={t(M['content.content_list.delete'])}
+      >
+        <span aria-hidden="true">🗑️</span>
+      </Button>
+    {/if}
+  </div>
+{/snippet}
+
 <div class="content-list-wrapper">
-  
+
   <div class="content-controls">
     <div class="search-filters">
-      <Input type="text" placeholder={t(M['content.content_list.search_placeholder'])} bind:value={searchTerm} />
-
-      {#if !type}
-        <Select bind:value={selectedType}>
-          <option value="All Types">{t(M['content.content_list.all_types'])}</option>
-          <option value="Articles">Articles</option>
-          <option value="Documents">Documents</option>
-          <option value="Mirrors">Mirrors</option>
+      <Input
+        type="text"
+        placeholder={t(M['content.content_list.search_placeholder'])}
+        aria-label={t(M['content.content_list.search_label'])}
+        value={tableState.search}
+        oninput={(event: Event) =>
+          handleSearch((event.currentTarget as HTMLInputElement).value)}
+      />
+
+      {#if !lockedType}
+        <Select
+          aria-label={t(M['content.content_list.filter_type'])}
+          value={selectedType}
+          onchange={(event: Event) =>
+            handleFilter(
+              CONTENT_LIST_TYPE_FILTER_ID,
+              (event.currentTarget as HTMLSelectElement).value,
+            )}
+        >
+          <option value="">{t(M['content.content_list.all_types'])}</option>
+          <option value="article">{t(M['content.content_list.type_articles'])}</option>
+          <option value="document">{t(M['content.content_list.type_documents'])}</option>
+          <option value="mirror">{t(M['content.content_list.type_mirrors'])}</option>
         </Select>
       {/if}
 
-      <Select bind:value={selectedStatus}>
-        <option value="All Statuses">{t(M['content.content_list.all_statuses'])}</option>
-        <option value="Published">Published</option>
-        <option value="Draft">Draft</option>
-        <option value="Archived">Archived</option>
+      <Select
+        aria-label={t(M['content.content_list.filter_status'])}
+        value={selectedStatus}
+        onchange={(event: Event) =>
+          handleFilter(
+            CONTENT_LIST_STATUS_FILTER_ID,
+            (event.currentTarget as HTMLSelectElement).value,
+          )}
+      >
+        <option value="">{t(M['content.content_list.all_statuses'])}</option>
+        <option value="published">{t(M['content.content_list.status_published'])}</option>
+        <option value="draft">{t(M['content.content_list.status_draft'])}</option>
+        <option value="archived">{t(M['content.content_list.status_archived'])}</option>
       </Select>
-      
+
       {#if controls}
         {@render controls()}
       {/if}
     </div>
-    
+
     <div class="actions-group">
-      <div class="view-toggles">
+      <div class="view-toggles" role="group" aria-label={t(M['content.content_list.view_mode'])}>
         <Button
           variant="ghost"
           size="sm"
@@ -191,7 +478,7 @@ function cancelDelete() {
           aria-label={t(M['content.content_list.grid_view'])}
           title={t(M['content.content_list.grid_view'])}
         >
-          <svg viewBox="0 0 24 24" width="18" height="18" stroke="currentColor" stroke-width="2" fill="none">
+          <svg viewBox="0 0 24 24" width="18" height="18" stroke="currentColor" stroke-width="2" fill="none" aria-hidden="true">
             <rect x="3" y="3" width="7" height="7"></rect>
             <rect x="14" y="3" width="7" height="7"></rect>
             <rect x="14" y="14" width="7" height="7"></rect>
@@ -208,7 +495,7 @@ function cancelDelete() {
           aria-label={t(M['content.content_list.detailed_list'])}
           title={t(M['content.content_list.detailed_list'])}
         >
-          <svg viewBox="0 0 24 24" width="18" height="18" stroke="currentColor" stroke-width="2" fill="none">
+          <svg viewBox="0 0 24 24" width="18" height="18" stroke="currentColor" stroke-width="2" fill="none" aria-hidden="true">
             <line x1="8" y1="6" x2="21" y2="6"></line>
             <line x1="8" y1="12" x2="21" y2="12"></line>
             <line x1="8" y1="18" x2="21" y2="18"></line>
@@ -227,7 +514,7 @@ function cancelDelete() {
           aria-label={t(M['content.content_list.compact_list'])}
           title={t(M['content.content_list.compact_list'])}
         >
-          <svg viewBox="0 0 24 24" width="18" height="18" stroke="currentColor" stroke-width="2" fill="none">
+          <svg viewBox="0 0 24 24" width="18" height="18" stroke="currentColor" stroke-width="2" fill="none" aria-hidden="true">
             <line x1="3" y1="6" x2="21" y2="6"></line>
             <line x1="3" y1="12" x2="21" y2="12"></line>
             <line x1="3" y1="18" x2="21" y2="18"></line>
@@ -236,7 +523,7 @@ function cancelDelete() {
       </div>
 
       <Button variant="ghost" class="add-button" type="button" onclick={() => onAdd()}>
-        <svg viewBox="0 0 24 24" width="16" height="16" stroke="currentColor" stroke-width="2" fill="none">
+        <svg viewBox="0 0 24 24" width="16" height="16" stroke="currentColor" stroke-width="2" fill="none" aria-hidden="true">
           <line x1="12" y1="5" x2="12" y2="19"></line>
           <line x1="5" y1="12" x2="19" y2="12"></line>
         </svg>
@@ -245,160 +532,235 @@ function cancelDelete() {
     </div>
   </div>
 
-  {#if filteredContents.length === 0}
-    <div class="empty-state">
-      {t(M['content.content_list.empty'])}
+  {#if error}
+    <div class="state-panel state-panel--error" role="alert">
+      <p class="state-panel__title">{t(M['content.content_list.error_title'])}</p>
+      <p class="state-panel__detail">{error}</p>
+      {#if onRetry}
+        <Button variant="ghost" type="button" class="retry-button" onclick={() => onRetry?.()}>
+          {t(M['content.content_list.retry'])}
+        </Button>
+      {/if}
     </div>
-  {:else if viewMode === 'compact'}
-    <div class="content-table-wrapper">
-      <table class="content-table">
-        <thead>
-          <tr>
-            <th>Type</th>
-            <th>Title</th>
-            <th>Author</th>
-            <th>Status</th>
-            <th>State</th>
-            <th class="actions-col">Actions</th>
-          </tr>
-        </thead>
-        <tbody>
-          {#each filteredContents as content (content.id)}
-            <tr>
-              <td class="type-cell">
-                <span class={`type-pill type-pill--${getNormalizedType(content.type)}`}>
-                  {getTypeLabel(content.type)}
-                </span>
-              </td>
-              <td class="title-cell"><strong>{getDisplayTitle(content)}</strong></td>
-              <td>{getDisplayAuthor(content) || '-'}</td>
-              <td><span class="badge status-{getStatusBadge(content.status)}">{content.status}</span></td>
-              <td><span class="badge state-{getStateBadge(content.state)}">{content.state}</span></td>
-              <td class="actions-cell">
-                {#if getViewHref?.(content)}
-                  <a class="icon-btn" href={getViewHref(content) || '#'} title={t(M['content.content_list.view_published_article'])} aria-label={t(M['content.content_list.view_published_article'])}>🔎</a>
+  {:else}
+    {#if pageRows.length > 0 || selectedCount > 0}
+      <div class="content-selection">
+        {#if viewMode !== 'compact'}
+          <Checkbox
+            checked={allPageSelected}
+            indeterminate={somePageSelected}
+            aria-label={t(M['content.content_list.select_all'])}
+            onchange={togglePageSelection}
+          />
+        {/if}
+        <span class="content-selection__count" aria-live="polite">
+          {t(M['content.content_list.selection_count'], { count: selectedCount })}
+        </span>
+        {#if selectedCount > 0}
+          <Button variant="ghost" size="sm" type="button" class="clear-selection" onclick={clearSelection}>
+            {t(M['content.content_list.clear_selection'])}
+          </Button>
+        {/if}
+      </div>
+    {/if}
+
+    {#if refreshing && viewMode !== 'compact'}
+      <!-- DataTable announces its own refresh; the card views need their own. -->
+      <p class="content-refreshing" role="status" aria-live="polite">
+        {t(M['content.content_list.refreshing'])}
+      </p>
+    {/if}
+
+    {#if viewMode === 'compact'}
+      <!--
+        The compact table stays mounted for empty and loading results: it owns
+        the mounted data surface, so unmounting it on a zero-row query would
+        unregister the surface and leave an agent unable to undo its own search.
+      -->
+      <div class="content-table-wrapper">
+        <DataTable
+          data={pageRows}
+          totalRows={queryRows.length}
+          columns={tableColumns}
+          rowKey={CONTENT_LIST_ROW_KEY}
+          {controller}
+          sortable
+          agentAddressable
+          {loading}
+          caption={t(M['content.content_list.table_caption'])}
+          rowLabel={(row: ContentListRow) => row.title}
+          dataSurface={surfaceOptions}
+          empty={tableEmptyState}
+        />
+      </div>
+    {:else if loading && pageRows.length === 0}
+      <div class="state-panel" role="status">
+        {t(M['content.content_list.loading'])}
+      </div>
+    {:else if pageRows.length === 0}
+      <div class="state-panel empty-state">
+        {t(M['content.content_list.empty'])}
+      </div>
+    {:else if viewMode === 'detailed'}
+      <div class="content-detailed">
+        {#each pageRows as row (row.id)}
+          {@const content = row.content}
+          {@const actions = rowActions(row)}
+          <article class="content-row">
+            <div class="content-row__select">
+              <Checkbox
+                checked={isSelected(row)}
+                disabled={!row.identified}
+                aria-label={selectRowLabel(row)}
+                title={row.identified
+                  ? undefined
+                  : t(M['content.content_list.row_not_selectable'])}
+                onchange={() => toggleRow(row)}
+              />
+            </div>
+
+            <div class="content-row__main">
+              <div class="content-row__eyebrow">
+                <span class={`type-pill type-pill--${row.type}`}>{row.typeLabel}</span>
+                {#if row.author}
+                  <span class="content-row__author">By {row.author}</span>
                 {/if}
-                <Button variant="ghost" size="sm" class="icon-btn" type="button" onclick={() => onEdit(content)} title={t(M['content.content_list.edit'])} aria-label={t(M['content.content_list.edit'])}>✏️</Button>
-                <Button variant="ghost" size="sm" class="icon-btn delete-icon" type="button" onclick={() => handleDeleteContent(content)} title={t(M['content.content_list.delete'])} aria-label={t(M['content.content_list.delete'])}>🗑️</Button>
-              </td>
-            </tr>
-          {/each}
-        </tbody>
-      </table>
-    </div>
-  {:else if viewMode === 'detailed'}
-    <div class="content-detailed">
-      {#each filteredContents as content (content.id)}
-        <article class="content-row">
-          <div class="content-row__main">
-            <div class="content-row__eyebrow">
-              <span class={`type-pill type-pill--${getNormalizedType(content.type)}`}>
-                {getTypeLabel(content.type)}
-              </span>
-              {#if getDisplayAuthor(content)}
-                <span class="content-row__author">By {getDisplayAuthor(content)}</span>
+              </div>
+
+              <h3>{row.title}</h3>
+
+              {#if row.description}
+                <p class="content-row__description">{row.description}</p>
+              {/if}
+
+              {#if content.url || content.fileKey}
+                <div class="content-row__links">
+                  {#if content.url}
+                    <a href={content.url} target="_blank" rel="noreferrer">
+                      {t(M['content.content_list.source_material'])}
+                    </a>
+                  {/if}
+                  {#if content.fileKey}
+                    <span>{content.fileKey}</span>
+                  {/if}
+                </div>
               {/if}
             </div>
 
-            <h3>{getDisplayTitle(content)}</h3>
+            <div class="content-row__meta">
+              <span class="meta-label">{t(M['content.content_list.column_status'])}</span>
+              <span class="badge status-{contentStatusVariant(row.status)}">{row.statusLabel}</span>
+              <span class="meta-label">{t(M['content.content_list.column_state'])}</span>
+              <span class="badge state-{contentStateVariant(row.state)}">{row.stateLabel}</span>
+            </div>
 
-            {#if getDisplayDescription(content)}
-              <p class="content-row__description">{getDisplayDescription(content)}</p>
+            <div class="content-row__actions">
+              {#if actions.includes('view')}
+                <a href={viewHref(row)} class="quiet-action">{t(M['content.content_list.view_article'])}</a>
+              {/if}
+              {#if actions.includes('edit')}
+                <Button variant="ghost" type="button" class="quiet-action" onclick={() => onEdit(content)}>
+                  {t(M['content.content_list.edit'])}
+                </Button>
+              {/if}
+              {#if actions.includes('delete')}
+                <Button
+                  variant="ghost"
+                  type="button"
+                  class="quiet-action quiet-action--danger"
+                  onclick={() => handleDeleteContent(row)}
+                >
+                  {t(M['content.content_list.delete'])}
+                </Button>
+              {/if}
+            </div>
+          </article>
+        {/each}
+      </div>
+    {:else}
+      <div class="content-grid">
+        {#each pageRows as row (row.id)}
+          {@const content = row.content}
+          {@const actions = rowActions(row)}
+          <div class="content-card">
+            {#if content.thumbnailAssetId}
+              <div class="card-thumbnail">
+                <ImageThumbnail
+                  apiBaseUrl={apiBaseUrl}
+                  assetId={content.thumbnailAssetId}
+                />
+              </div>
             {/if}
+            <div class="content-header">
+              <div class="content-header__eyebrow">
+                <Checkbox
+                  checked={isSelected(row)}
+                  disabled={!row.identified}
+                  aria-label={selectRowLabel(row)}
+                  title={row.identified
+                    ? undefined
+                    : t(M['content.content_list.row_not_selectable'])}
+                  onchange={() => toggleRow(row)}
+                />
+                <span class={`type-pill type-pill--${row.type}`}>{row.typeLabel}</span>
+                {#if row.author}
+                  <div class="author">{row.author}</div>
+                {/if}
+              </div>
+              <h3>{row.title}</h3>
+            </div>
 
-            {#if content.url || content.fileKey}
-              <div class="content-row__links">
+            <div class="content-meta">
+              <div>{row.typeLabel}</div>
+              <div class="badges">
+                <span class="badge status-{contentStatusVariant(row.status)}">{row.statusLabel}</span>
+                <span class="badge state-{contentStateVariant(row.state)}">{row.stateLabel}</span>
+              </div>
+            </div>
+
+            <p class="content-description">{row.description}</p>
+
+            <div class="content-footer">
+              <div class="meta-links">
                 {#if content.url}
-                  <a href={content.url} target="_blank" rel="noreferrer">
-                    {t(M['content.content_list.source_material'])}
-                  </a>
+                  <div class="source">Source: <a href={content.url} target="_blank" rel="noreferrer">{content.url}</a></div>
                 {/if}
                 {#if content.fileKey}
-                  <span>{content.fileKey}</span>
+                  <div class="file">File: {content.fileKey}</div>
                 {/if}
               </div>
-            {/if}
-          </div>
-
-          <div class="content-row__meta">
-            <span class="meta-label">Status</span>
-            <span class="badge status-{getStatusBadge(content.status)}">{content.status}</span>
-            <span class="meta-label">State</span>
-            <span class="badge state-{getStateBadge(content.state)}">{content.state}</span>
-          </div>
 
-          <div class="content-row__actions">
-            {#if getViewHref?.(content)}
-              <a href={getViewHref(content) || '#'} class="quiet-action">{t(M['content.content_list.view_article'])}</a>
-            {/if}
-            <Button variant="ghost" type="button" class="quiet-action" onclick={() => onEdit(content)}>{t(M['content.content_list.edit'])}</Button>
-            <Button
-              variant="ghost"
-              type="button"
-              class="quiet-action quiet-action--danger"
-              onclick={() => handleDeleteContent(content)}
-            >
-              {t(M['content.content_list.delete'])}
-            </Button>
-          </div>
-        </article>
-      {/each}
-    </div>
-  {:else}
-    <div class="content-{viewMode}">
-      {#each filteredContents as content (content.id)}
-        <div class="content-card">
-          {#if content.thumbnailAssetId}
-            <div class="card-thumbnail">
-              <ImageThumbnail
-                apiBaseUrl={apiBaseUrl}
-                assetId={content.thumbnailAssetId}
-              />
-            </div>
-          {/if}
-          <div class="content-header">
-            <div class="content-header__eyebrow">
-              <span class={`type-pill type-pill--${getNormalizedType(content.type)}`}>
-                {getTypeLabel(content.type)}
-              </span>
-              {#if getDisplayAuthor(content)}
-                <div class="author">{getDisplayAuthor(content)}</div>
-              {/if}
-            </div>
-            <h3>{getDisplayTitle(content)}</h3>
-          </div>
-          
-          <div class="content-meta">
-            <div>{getTypeLabel(content.type)}</div>
-            <div class="badges">
-              <span class="badge status-{getStatusBadge(content.status)}">{content.status}</span>
-              <span class="badge state-{getStateBadge(content.state)}">{content.state}</span>
-            </div>
-          </div>
-          
-          <p class="content-description">{getDisplayDescription(content)}</p>
-          
-          <div class="content-footer">
-            <div class="meta-links">
-              {#if content.url}
-                <div class="source">Source: <a href={content.url} target="_blank">{content.url}</a></div>
-              {/if}
-              {#if content.fileKey}
-                <div class="file">File: {content.fileKey}</div>
-              {/if}
-            </div>
-            
-            <div class="content-actions">
-              {#if getViewHref?.(content)}
-                <a href={getViewHref(content) || '#'} class="view-btn">{t(M['content.content_list.view_article_button'])}</a>
-              {/if}
-              <Button variant="ghost" type="button" class="content-action-btn" onclick={() => onEdit(content)}>{t(M['content.content_list.edit'])}</Button>
-              <Button variant="ghost" type="button" class="content-action-btn delete-btn" onclick={() => handleDeleteContent(content)}>{t(M['content.content_list.delete'])}</Button>
+              <div class="content-actions">
+                {#if actions.includes('view')}
+                  <a href={viewHref(row)} class="view-btn">{t(M['content.content_list.view_article_button'])}</a>
+                {/if}
+                {#if actions.includes('edit')}
+                  <Button variant="ghost" type="button" class="content-action-btn" onclick={() => onEdit(content)}>
+                    {t(M['content.content_list.edit'])}
+                  </Button>
+                {/if}
+                {#if actions.includes('delete')}
+                  <Button variant="ghost" type="button" class="content-action-btn delete-btn" onclick={() => handleDeleteContent(row)}>
+                    {t(M['content.content_list.delete'])}
+                  </Button>
+                {/if}
+              </div>
             </div>
           </div>
-        </div>
-      {/each}
-    </div>
+        {/each}
+      </div>
+    {/if}
+
+    {#if showPagination && viewMode !== 'compact'}
+      <div class="content-pagination">
+        <Pagination
+          currentPage={tableState.page}
+          {totalPages}
+          onPageChange={handlePageChange}
+          aria-label={t(M['content.content_list.pagination'])}
+        />
+      </div>
+    {/if}
   {/if}
 
 </div>
@@ -407,7 +769,7 @@ function cancelDelete() {
   open={pendingDelete !== null}
   title={t(M['content.content_list.delete_confirm_title'])}
   message={t(M['content.content_list.delete_confirm_message'], {
-    title: pendingDelete ? getDisplayTitle(pendingDelete) : '',
+    title: pendingDelete ? pendingDelete.title : '',
   })}
   confirmLabel={t(M['content.content_list.delete'])}
   cancelLabel={t(M['content.content_list.cancel'])}
@@ -516,6 +878,20 @@ function cancelDelete() {
     box-shadow: 0 4px 6px -1px color-mix(in srgb, var(--smrt-color-primary) 50%, transparent);
   }
 
+  /* Selection summary shared by every presentation. */
+  .content-selection {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    padding: 0.35rem 0.1rem 0.75rem;
+    color: var(--smrt-color-on-surface-variant);
+    font-size: var(--smrt-typography-body-medium-size, 0.875rem);
+  }
+
+  .content-selection :global(input[type='checkbox']) {
+    cursor: pointer;
+  }
+
   .content-header__eyebrow,
   .content-row__eyebrow {
     display: flex;
@@ -658,7 +1034,7 @@ function cancelDelete() {
     color: var(--smrt-color-primary);
     text-decoration: none;
   }
-  
+
   .source a:hover {
     text-decoration: underline;
   }
@@ -723,13 +1099,17 @@ function cancelDelete() {
 
   .content-row {
     display: grid;
-    grid-template-columns: minmax(0, 1.8fr) auto auto;
+    grid-template-columns: auto minmax(0, 1.8fr) auto auto;
     gap: 1.25rem;
     align-items: start;
     padding: 1.1rem 0;
     border-bottom: 1px solid var(--smrt-color-outline-variant);
   }
 
+  .content-row__select {
+    padding-top: 0.25rem;
+  }
+
   .content-row h3 {
     margin: 0;
     font-size: var(--smrt-typography-title-medium-size, 1.1rem);
@@ -816,53 +1196,39 @@ function cancelDelete() {
     box-shadow: var(--smrt-elevation-1, 0 1px 3px rgba(0,0,0,0.05));
   }
 
-  .content-table {
-    width: 100%;
-    border-collapse: collapse;
-    text-align: left;
-  }
-
-  .content-table th {
-    background: var(--smrt-color-surface-container-low);
-    padding: 1rem;
-    font-size: var(--smrt-typography-title-small-size, 0.875rem);
-    font-weight: var(--smrt-typography-weight-semibold, 600);
+  .content-refreshing {
+    margin: 0 0 0.75rem;
     color: var(--smrt-color-on-surface-variant);
-    border-bottom: 1px solid var(--smrt-color-outline-variant);
-  }
-
-  .content-table td {
-    padding: 1rem;
-    border-bottom: 1px solid var(--smrt-color-outline-variant);
-    color: var(--smrt-color-on-surface);
     font-size: var(--smrt-typography-body-medium-size, 0.875rem);
-    vertical-align: middle;
   }
 
-  .content-table tr:last-child td {
-    border-bottom: none;
-  }
-
-  .content-table tr:hover {
-    background: var(--smrt-color-surface-container-low);
+  .content-pagination {
+    display: flex;
+    justify-content: center;
+    margin-top: 1.25rem;
   }
 
-  .type-cell {
-    white-space: nowrap;
+  .table-empty-state {
+    margin: 0;
+    padding: 1.5rem 0;
+    text-align: center;
+    color: var(--smrt-color-on-surface-variant);
   }
 
-  .title-cell strong {
-    color: var(--smrt-color-on-surface);
+  .title-link {
+    color: var(--smrt-color-primary);
     font-weight: var(--smrt-typography-weight-semibold, 600);
+    text-decoration: none;
   }
 
-  .actions-col {
-    width: 100px;
-    text-align: right;
+  .title-link:hover {
+    text-decoration: underline;
   }
 
   .actions-cell {
-    text-align: right;
+    display: flex;
+    justify-content: flex-end;
+    gap: 0.15rem;
     white-space: nowrap;
   }
 
@@ -875,6 +1241,7 @@ function cancelDelete() {
     border-radius: 0.25rem;
     transition: background 0.2s;
     opacity: 0.7;
+    text-decoration: none;
   }
 
   .actions-cell :global(.icon-btn:hover) {
@@ -886,7 +1253,8 @@ function cancelDelete() {
     background: var(--smrt-color-error-container);
   }
 
-  .empty-state {
+  /* Shared empty, loading, and error presentation. */
+  .state-panel {
     background: var(--smrt-color-surface);
     padding: 4rem;
     text-align: center;
@@ -896,13 +1264,33 @@ function cancelDelete() {
     font-size: var(--smrt-typography-body-large-size, 1.1rem);
   }
 
-  .source, .file {
+  .state-panel--error {
+    border-style: solid;
+    border-color: var(--smrt-color-error);
+    color: var(--smrt-color-on-surface);
+  }
+
+  .state-panel__title {
+    margin: 0 0 0.5rem;
+    font-weight: var(--smrt-typography-weight-semibold, 600);
+  }
+
+  .state-panel__detail {
+    margin: 0 0 1rem;
     color: var(--smrt-color-on-surface-variant);
+    font-size: var(--smrt-typography-body-medium-size, 0.875rem);
+  }
+
+  .state-panel :global(.retry-button) {
+    border: 1px solid var(--smrt-color-outline);
+    border-radius: 0.5rem;
+    padding: 0.5rem 1rem;
+    cursor: pointer;
   }
 
   @media (max-width: 960px) {
     .content-row {
-      grid-template-columns: minmax(0, 1fr);
+      grid-template-columns: auto minmax(0, 1fr);
       gap: 0.9rem;
     }