content-list-plan.md

Content List Production Plan

Summary

This plan splits the 55,000+ line Content List PR into 18 reviewable PRs organized by feature. Each PR delivers a complete feature across all layers (provider, hooks, components, tests), making reviews focused and incremental.

Approach:

• 12 sequential feature PRs build the Content List architecture incrementally
• 6 migration PRs replace TableListView in existing consumers (Graph, Maps, Files, Event Annotations, Visualizations, Dashboard)
• 4 milestones define when each consumer can be migrated
• Migration PRs can be developed in parallel once their milestone is reached

New packages: @kbn/content-list-provider, @kbn/content-list-provider-client, @kbn/content-list-table, @kbn/content-list-toolbar, @kbn/content-list-mock-data

Notes

• The server provider (@kbn/content-list-provider-server) and /internal/content_management/list endpoint are not included in this plan.
  • They can be added as a parallel PR after PR 3.
• Milestones 2 and 3 can be easily swapped, based on feedback or prioritization.
• Data Streams could be an additional milestone, as a custom consumer, based on where it fits in the Feature Requirements matrix.

---

Table of Contents

1. Feature Requirements
2. Packages Overview
3. PR Sequence
4. Timeline
5. PR and Milestone Details
6. Review Strategy

---

Feature Requirements

Before diving into PRs, here's what each TableListView consumer needs:

Consumer	Core	Tags	Custom Cols	Users	Starred	Editor	Migration
Graph	Yes						MS1
Maps	Yes	Yes					MS2
Files Mgmt	Yes		Yes				MS3
Event Annotations	Yes	Yes	Yes			Yes	MS4.1
Visualizations	Yes	Yes	Yes			Yes	MS4.2
Dashboard	Yes	Yes		Yes	Yes	Yes	MS4.3

Core = Search + Sort + Pagination + UpdatedAt + Actions + Selection (PRs 1-7)

---

Packages Overview

The Content List system is organized into provider packages (state management and data fetching), component packages (UI rendering), and support packages (testing and documentation).

flowchart TB
    subgraph providers [Providers]
        base[kbn-content-list-provider]
        client[kbn-content-list-provider-client]
    end
    
    subgraph components [Components]
        table[kbn-content-list-table]
        toolbar[kbn-content-list-toolbar]
        grid[kbn-content-list-grid]
        footer[kbn-content-list-footer]
    end
    
    subgraph support [Support]
        mock[kbn-content-list-mock-data]
        docs[kbn-content-list-docs]
    end
    
    consumers[Consumers]
    
    base --> client
    base --> table
    base --> toolbar
    base --> grid
    base --> footer
    client --> consumers

Loading

---

PR Sequence

Feature PRs are merged sequentially. Migration PRs can begin in parallel once their milestone is reached.

ID	Type	Description	Est. Files
PR 1	Feature	Provider Foundation	~25
PR 2	Feature	UI Foundation	~25
PR 3	Feature	Pagination	~15
PR 4	Feature	Search	~10
PR 5	Feature	UpdatedAt Column + Sort	~8
PR 6	Feature	Actions Column	~10
PR 7	Feature	Selection	~15
MS1	Milestone	Graph Migration	~5
PR 8	Feature	Tags	~20
MS2	Milestone	Maps Migration	~10
PR 9	Feature	Custom Columns	~15
MS3	Milestone	Files Mgmt Migration	~10
PR 10	Feature	Users + CreatedBy	~20
PR 11	Feature	Starred	~15
PR 12	Feature	Content Editor	~20
MS4.1	Milestone	Event Annotations Migration	~10
MS4.2	Milestone	Visualizations Migration	~15
MS4.3	Milestone	Dashboard Migration	~20

---

Timeline

Visual overview of the PR sequence and migration opportunities.

flowchart TB
    subgraph foundation [Foundation PRs 1-7]
        pr1[PR1: Provider] --> pr2[PR2: UI]
        pr2 --> pr3[PR3: Pagination]
        pr3 --> pr4[PR4: Search]
        pr4 --> pr5[PR5: UpdatedAt]
        pr5 --> pr6[PR6: Actions]
        pr6 --> pr7[PR7: Selection]
    end
    
    pr7 --> ms1((MS1))
    
    ms1 --> pr8[PR8: Tags]
    pr8 --> ms2((MS2))
    
    ms2 --> pr9[PR9: Custom Cols]
    pr9 --> ms3((MS3))
    
    ms3 --> pr10[PR10: Users]
    pr10 --> pr11[PR11: Starred]
    pr11 --> pr12[PR12: Editor]
    pr12 --> ms4((MS4))
    
    ms1 -.-> graphMig[Graph]
    ms2 -.-> mapsMig[Maps]
    ms3 -.-> filesMig[Files Mgmt]
    ms4 -.-> eventMig[Event Annotations]
    ms4 -.-> visMig[Visualizations]
    ms4 -.-> dashMig[Dashboard]

Loading

Key: Solid lines = sequential dependencies. Dotted lines = parallel migration work.

---

PR and Milestone Details

Detailed scope for each feature PR and migration milestone.

PR 1: Provider Foundation

Goal: Core state management and data fetching infrastructure

Packages to create:

• @kbn/content-list-provider (minimal core)
  • src/context/ - Config and state contexts
  • src/state/ - Reducer and state management
  • src/datasource/ - Data fetching interface
  • src/query/ - React Query integration
  • src/features/sorting/ - Sort feature only
  • src/item/ - Item types and transform
  • src/services/ - Services skeleton (types, context)
• @kbn/content-list-provider-client (skeleton)
  • provider.tsx - Provider component
  • strategy.ts - Client-side adapter (no caching yet)
• @kbn/content-list-mock-data (minimal)
  • Basic mock data for tests

Estimated files: ~25 files

---

PR 2: UI Foundation

Goal: Table, toolbar, and footer components with sorting

Packages to create:

• @kbn/content-list-table (name column only)
  • content_list_table.tsx - Table component
  • columns/column.tsx - Column base
  • columns/name/ - Name column
  • hooks/use_sorting.ts - Table sorting hook
  • empty_state/ - Basic empty states
• @kbn/content-list-toolbar
  • Toolbar container
  • Sort order selector component
• @kbn/content-list-footer (skeleton)
  • Footer container
  • Item count display

Estimated files: ~25 files

---

PR 3: Pagination Feature

Goal: Add pagination controls

Changes:

• @kbn/content-list-provider
  • src/features/pagination/ - Pagination state and hooks
• @kbn/content-list-footer
  • Pagination controls (page size selector, page navigation)
• @kbn/content-list-provider-client
  • Client-side pagination logic

Estimated files: ~15 files

---

PR 4: Search Feature

Goal: Add search capability to the toolbar

Changes:

• @kbn/content-list-provider
  • src/features/search/ - Search state and hooks
• @kbn/content-list-toolbar
  • Search input component added to toolbar

Estimated files: ~10 files

---

PR 5: UpdatedAt Column

Goal: Add timestamp column and "Last updated" sort option

Changes:

• @kbn/content-list-table
  • columns/updated_at/ - UpdatedAt column with relative time formatting
• @kbn/content-list-toolbar
  • Add "Last updated" sort option to sort order selector

Estimated files: ~8 files

---

PR 6: Actions Column

Goal: Add row actions (edit, delete)

Changes:

• @kbn/content-list-table
  • columns/actions/ - Actions column
  • Action.Edit component
  • Action.Delete component with confirmation

Estimated files: ~10 files

---

PR 7: Selection and Bulk Actions

Goal: Add multi-select with bulk delete capability

Changes:

• @kbn/content-list-provider
  • src/features/selection/ - Selection state and hooks
• @kbn/content-list-table
  • hooks/use_selection.ts - Selection integration
  • Checkbox column for rows
• @kbn/content-list-toolbar
  • Selection actions bar (delete selected, count display)

Estimated files: ~15 files

---

MS1: Graph Migration

• x-pack/platform/plugins/private/graph/public/apps/listing_route.tsx
• Simple migration: basic CRUD, custom empty prompt
• Estimated files: ~5 files

---

PR 8: Tags Feature

Goal: Add tags filtering and display

Changes:

• @kbn/content-list-provider
  • src/features/filtering/tags/ - Tags Filtering
  • src/services/tags/ - Tags service adapter
• @kbn/content-list-table
  • columns/name/ - Add showTags prop to Name column
• @kbn/content-list-toolbar
  • Tags filter popover (include/exclude)
  • Filter pills display

Estimated files: ~20 files

---

MS2: Maps Migration

• x-pack/platform/plugins/shared/maps/public/routes/list_page/maps_list_view.tsx
• Needs: Core + Tags
• Estimated files: ~10 files

---

PR 9: Custom Columns

Goal: Add support for custom columns with custom rendering and sorting options

Changes:

• @kbn/content-list-table
  • Column.Custom component for arbitrary custom columns
  • Custom render function support: (field, record) => ReactNode
  • Custom field path support (e.g., 'attributes.size')
  • Custom width and sortable options
  • customSortingOptions for custom sort labels (e.g., "Type A-Z", "Type Z-A")

API (matching existing TableListView):

// Custom column definition
customTableColumn={{
  field: 'attributes.size',
  name: 'Size',
  sortable: true,
  width: '150px',
  render: (value, record) => numeral(value).format('0[.]0 b'),
}}

// Custom sorting options
customSortingOptions={{
  field: 'typeTitle',
  sortingLabels: [
    { label: 'Type A-Z', direction: 'asc' },
    { label: 'Type Z-A', direction: 'desc' },
  ],
}}

Estimated files: ~15 files

---

MS3: Files Management Migration

• src/platform/plugins/private/files_management/public/app.tsx
• Needs: Core + Custom Columns (file size column)
• Estimated files: ~10 files

---

PR 10: User Profiles and CreatedBy

Goal: Add user profile filtering and CreatedBy column

Changes:

• @kbn/content-list-provider
  • src/features/filtering/user_profile/ - Add user filtering
  • src/services/user_profile/ - User profile service
• @kbn/content-list-table
  • columns/created_by/ - CreatedBy column with avatar
• @kbn/content-list-toolbar
  • Created by filter popover

Estimated files: ~20 files

---

PR 11: Starred/Favorites Feature

Goal: Add favorites support with starred filter

Changes:

• @kbn/content-list-provider
  • src/features/filtering/starred/ - Starred filtering (is:starred)
  • src/services/favorites/ - Favorites service integration
• @kbn/content-list-table
  • columns/name/ - Starred button in Name column
• @kbn/content-list-toolbar
  • Starred filter toggle

Estimated files: ~15 files

---

PR 12: Content Editor Integration

Goal: Add metadata editing flyout

Milestone: After this PR, MS4 enables Event Annotations, Visualizations, and Dashboard migrations

Changes:

• @kbn/content-list-provider
  • src/features/content_editor/ - Content editor config
  • ContentEditorActionProvider component
• @kbn/content-list-table
  • columns/actions/ - View Details action
  • columns/expander/ - Expandable rows

Depends on existing @kbn/content-management-content-editor package.

Estimated files: ~20 files

---

MS4.1: Event Annotations Migration

• src/platform/plugins/private/event_annotation_listing/public/components/table_list.tsx
• Needs: Core + Tags + Custom Columns + Content Editor
• Estimated files: ~10 files

---

MS4.2: Visualizations Migration

• src/platform/plugins/shared/visualizations/public/visualize_app/components/visualize_listing.tsx
• Needs: Core + Tags + Custom Columns + Content Editor + Custom Sorting
• Note: Tabbed interface (TabbedTableListView) may require additional work
• Estimated files: ~15 files

---

MS4.3: Dashboard Migration

• src/platform/plugins/shared/dashboard/public/dashboard_listing/dashboard_content_list.tsx
• Needs: All features (Users, Starred, Content Editor)
• Dashboard-specific: Unsaved changes listing, content insights, access control
• Estimated files: ~20 files

---

Review Strategy

Feature PRs should include:

1. Package code with unit tests
2. Storybook stories for visual components
3. Updated README documentation
4. Jest config and tsconfig updates

Migration PRs should include:

1. Functional tests
2. Side-by-side comparison (if needed during transition)
3. Migration guide updates

@clintandrewhall
I realized the plan is missing recently viewed sorting and url state URL sync for the dashboard feature parity and rollout

Not sure if URL sync is a good built in feature for table, maybe it should just move outside to dashboard level and we can provide some helpers/adapters (like we did with localstorage and page size)