[Content List] Column sizing & full-width page layout (elastic#267373)

Co-authored-by: Ryan Keairns <contactryank@gmail.com>

Author: clintandrewhall

src/platform/packages/shared/content-management/content_list/kbn-content-list-docs/src/dashboard_listing.stories.tsx

@@ -124,10 +124,10 @@ const OriginalStory = () => {
             </Filters>
           </ContentListToolbar>
           <ContentListTable title="Dashboards">
-            <Column.Name showDescription showTags showStarred width="56%" />
-            <Column.CreatedBy width="180px" />
-            <Column.UpdatedAt width="160px" />
-            <Column.Actions width="96px">
+            <Column.Name showDescription showTags showStarred />
+            <Column.CreatedBy />
+            <Column.UpdatedAt />
+            <Column.Actions>
               <Action.Edit />
               <Action.Delete />
             </Column.Actions>
@@ -187,10 +187,10 @@ const ProposalStory = () => {
               </Filters>
             </ContentListToolbar>
             <ContentListTable title="Dashboards">
-              <Column.Name showDescription showTags showStarred width="56%" />
-              <Column.CreatedBy width="180px" />
-              <Column.UpdatedAt width="160px" />
-              <Column.Actions width="128px">
+              <Column.Name showDescription showTags showStarred />
+              <Column.CreatedBy />
+              <Column.UpdatedAt />
+              <Column.Actions>
                 <Action.Inspect />
                 <Action.Edit />
                 <Action.Delete />

src/platform/packages/shared/content-management/content_list/kbn-content-list-docs/src/files_management.stories.tsx

@@ -165,7 +165,7 @@ const OriginalStory = () => {
                 return formatBytes(size !== undefined && Number.isFinite(size) ? size : undefined);
               }}
             />
-            <Column.Actions width="96px">
+            <Column.Actions>
               <Action.Delete />
             </Column.Actions>
           </ContentListTable>
@@ -212,7 +212,7 @@ const ProposalStory = () => {
               </Filters>
             </ContentListToolbar>
             <ContentListTable title="Files">
-              <Column.Name showDescription width="44%" />
+              <Column.Name showDescription />
               <Column
                 id="fileKind"
                 name="Type"
@@ -236,8 +236,8 @@ const ProposalStory = () => {
                   );
                 }}
               />
-              <Column.UpdatedAt width="160px" />
-              <Column.Actions width="128px">
+              <Column.UpdatedAt />
+              <Column.Actions>
                 <Action.Inspect />
                 <Action.Delete />
               </Column.Actions>

src/platform/packages/shared/content-management/content_list/kbn-content-list-docs/src/maps.stories.tsx

@@ -115,9 +115,9 @@ const OriginalStory = () => {
               </Filters>
             </ContentListToolbar>
             <ContentListTable title="Maps">
-              <Column.Name showDescription showTags width="72%" />
-              <Column.UpdatedAt width="160px" />
-              <Column.Actions width="96px">
+              <Column.Name showDescription showTags />
+              <Column.UpdatedAt />
+              <Column.Actions>
                 <Action.Delete />
               </Column.Actions>
             </ContentListTable>
@@ -168,10 +168,10 @@ const ProposalStory = () => {
               </Filters>
             </ContentListToolbar>
             <ContentListTable title="Maps">
-              <Column.Name showDescription showTags width="56%" />
-              <Column.CreatedBy width="180px" />
-              <Column.UpdatedAt width="160px" />
-              <Column.Actions width="128px">
+              <Column.Name showDescription showTags />
+              <Column.CreatedBy />
+              <Column.UpdatedAt />
+              <Column.Actions>
                 <Action.Inspect />
                 <Action.Delete />
               </Column.Actions>

src/platform/packages/shared/content-management/content_list/kbn-content-list-docs/src/playground/instructions.md

@@ -35,6 +35,8 @@ Use the **component palette** below the tree to add columns, actions, or filters
 | `Column (Type)` | Custom column rendering `item.type` as a badge — demonstrates the base `Column` API. |
 | `Column.Actions` | Row-level action buttons (edit, delete, custom). |
 
+> **Tip:** Each preset (`Column.Name`, `Column.UpdatedAt`, `Column.CreatedBy`, `Column.Starred`, `Column.Actions`) ships with sensible default `width` / `minWidth` / `maxWidth`, so the `width` input in the builder is an **override** — leave it blank to use the default. See the package README's _Defaults_ section for the full table.
+
 ## Available actions
 
 Actions are children of `Column.Actions`:

src/platform/packages/shared/content-management/content_list/kbn-content-list-docs/src/playground/playground_state.ts

@@ -92,6 +92,18 @@ export interface PropDefinition {
   defaultValue: unknown;
 }
 
+/**
+ * Each preset (`Column.Name`, `Column.UpdatedAt`, `Column.CreatedBy`,
+ * `Column.Starred`, `Column.Actions`) ships with a baked-in default `width`
+ * (and matching `minWidth` / `maxWidth`) — see the package README's
+ * "Defaults" section for the full table. The `width` input on every column
+ * below is therefore an **override**: leave it blank (`defaultValue: ''`)
+ * to use the preset default, or supply a CSS length (e.g. `'14em'`,
+ * `'200px'`) to override it. The reducer's `UPDATE_COLUMN_PROPS` case
+ * propagates the override into the rendered preset attributes; an empty
+ * string is filtered out before reaching the preset, so the default still
+ * fires.
+ */
 export const COLUMN_DEFINITIONS: ColumnDefinition[] = [
   {
     type: 'name',
@@ -102,7 +114,7 @@ export const COLUMN_DEFINITIONS: ColumnDefinition[] = [
       { name: 'showDescription', label: 'showDescription', type: 'boolean', defaultValue: true },
       { name: 'showTags', label: 'showTags', type: 'boolean', defaultValue: false },
       { name: 'showStarred', label: 'showStarred', type: 'boolean', defaultValue: false },
-      { name: 'width', label: 'width', type: 'string', defaultValue: '' },
+      { name: 'width', label: 'width (override)', type: 'string', defaultValue: '' },
       { name: 'columnTitle', label: 'columnTitle', type: 'string', defaultValue: '' },
     ],
   },
@@ -112,7 +124,7 @@ export const COLUMN_DEFINITIONS: ColumnDefinition[] = [
     allowMultiple: false,
     defaultProps: {},
     configurableProps: [
-      { name: 'width', label: 'width', type: 'string', defaultValue: '' },
+      { name: 'width', label: 'width (override)', type: 'string', defaultValue: '' },
       { name: 'columnTitle', label: 'columnTitle', type: 'string', defaultValue: '' },
     ],
   },
@@ -122,6 +134,7 @@ export const COLUMN_DEFINITIONS: ColumnDefinition[] = [
     allowMultiple: false,
     defaultProps: {},
     configurableProps: [
+      // Generic `<Column>` has no preset default; this is a required width.
       { name: 'width', label: 'width', type: 'string', defaultValue: '' },
       { name: 'columnTitle', label: 'columnTitle', type: 'string', defaultValue: '' },
     ],
@@ -131,15 +144,17 @@ export const COLUMN_DEFINITIONS: ColumnDefinition[] = [
     label: 'Column.Starred',
     allowMultiple: false,
     defaultProps: {},
-    configurableProps: [{ name: 'width', label: 'width', type: 'string', defaultValue: '' }],
+    configurableProps: [
+      { name: 'width', label: 'width (override)', type: 'string', defaultValue: '' },
+    ],
   },
   {
     type: 'createdBy',
     label: 'Column.CreatedBy',
     allowMultiple: false,
     defaultProps: {},
     configurableProps: [
-      { name: 'width', label: 'width', type: 'string', defaultValue: '' },
+      { name: 'width', label: 'width (override)', type: 'string', defaultValue: '' },
       { name: 'columnTitle', label: 'columnTitle', type: 'string', defaultValue: '' },
     ],
   },
@@ -149,7 +164,7 @@ export const COLUMN_DEFINITIONS: ColumnDefinition[] = [
     allowMultiple: false,
     defaultProps: {},
     configurableProps: [
-      { name: 'width', label: 'width', type: 'string', defaultValue: '' },
+      { name: 'width', label: 'width (override)', type: 'string', defaultValue: '' },
       { name: 'columnTitle', label: 'columnTitle', type: 'string', defaultValue: '' },
     ],
   },

src/platform/packages/shared/content-management/content_list/kbn-content-list-page/src/kibana_content_list_page.test.tsx

@@ -10,8 +10,27 @@
 import React from 'react';
 import { render, screen } from '@testing-library/react';
 import { EuiButton } from '@elastic/eui';
+import { KibanaPageTemplate } from '@kbn/shared-ux-page-kibana-template';
 import { KibanaContentListPage } from './kibana_content_list_page';
 
+jest.mock('@kbn/shared-ux-page-kibana-template', () => {
+  const actual = jest.requireActual('@kbn/shared-ux-page-kibana-template');
+  // Wrap the real `KibanaPageTemplate` in a jest.fn so callers can assert
+  // forwarded props (`restrictWidth`, etc.) without losing the real
+  // sub-component slots (`Header`, `Section`).
+  const KibanaPageTemplateMock = jest.fn(actual.KibanaPageTemplate);
+  // Preserve the compound API EUI exposes via `Object.assign` in the
+  // upstream module.
+  Object.assign(KibanaPageTemplateMock, actual.KibanaPageTemplate);
+  return { ...actual, KibanaPageTemplate: KibanaPageTemplateMock };
+});
+
+const KibanaPageTemplateMock = KibanaPageTemplate as unknown as jest.Mock;
+
+beforeEach(() => {
+  KibanaPageTemplateMock.mockClear();
+});
+
 describe('KibanaContentListPage', () => {
   it('renders children verbatim inside the page template', () => {
     render(
@@ -34,6 +53,34 @@ describe('KibanaContentListPage', () => {
     expect(screen.getByTestId('maps-page')).toBeInTheDocument();
   });
 
+  describe('restrictWidth', () => {
+    it('defaults to `false` so listing pages run full-width', () => {
+      render(
+        <KibanaContentListPage>
+          <div />
+        </KibanaContentListPage>
+      );
+
+      expect(KibanaPageTemplateMock).toHaveBeenCalledWith(
+        expect.objectContaining({ restrictWidth: false }),
+        expect.anything()
+      );
+    });
+
+    it('forwards an explicit `restrictWidth` to `KibanaPageTemplate`', () => {
+      render(
+        <KibanaContentListPage restrictWidth={1024}>
+          <div />
+        </KibanaContentListPage>
+      );
+
+      expect(KibanaPageTemplateMock).toHaveBeenCalledWith(
+        expect.objectContaining({ restrictWidth: 1024 }),
+        expect.anything()
+      );
+    });
+  });
+
   describe('KibanaContentListPage.Header', () => {
     it('renders title, description, and actions', () => {
       render(

src/platform/packages/shared/content-management/content_list/kbn-content-list-page/src/kibana_content_list_page.tsx

@@ -158,13 +158,28 @@ export interface KibanaContentListPageProps {
    * context value, so `Header` and `Section` are always synchronized.
    */
   headingId?: string;
+  /**
+   * Forwarded to {@link KibanaPageTemplate}'s `restrictWidth` prop.
+   *
+   * Defaults to `false` so listing pages run full-width — the
+   * `ContentListTable` column presets each have their own `maxWidth` cap, so
+   * trailing whitespace lives inside the table rather than as a centred
+   * page-section gutter. This intentionally overrides EUI's `true` default
+   * (which resolves to a 1200px page cap and would prevent column
+   * `maxWidth` defaults from engaging on wide viewports).
+   *
+   * Pass `true` for the EUI default (1200px), or a specific number/string
+   * to centre the page chrome at a custom width.
+   */
+  restrictWidth?: boolean | number | string;
   /** Override the root `data-test-subj`. */
   'data-test-subj'?: string;
 }
 
 const KibanaContentListPageRoot = ({
   children,
   headingId: headingIdProp,
+  restrictWidth = false,
   'data-test-subj': dataTestSubj = DEFAULT_DATA_TEST_SUBJ,
 }: KibanaContentListPageProps) => {
   // Generate a unique id per instance so two `KibanaContentListPage` trees
@@ -179,7 +194,7 @@ const KibanaContentListPageRoot = ({
 
   return (
     <KibanaContentListPageContext.Provider value={contextValue}>
-      <KibanaPageTemplate panelled data-test-subj={dataTestSubj}>
+      <KibanaPageTemplate panelled restrictWidth={restrictWidth} data-test-subj={dataTestSubj}>
         {children}
       </KibanaPageTemplate>
     </KibanaContentListPageContext.Provider>
@@ -196,6 +211,12 @@ const KibanaContentListPageRoot = ({
  * - {@link KibanaContentListPage.Header} — page title, description, and actions.
  * - {@link KibanaContentListPage.Section} — a labelled `KibanaPageTemplate.Section`.
  *
+ * The page renders full-width by default (`restrictWidth={false}`). The
+ * `ContentListTable` column presets each have their own `maxWidth` cap, so
+ * trailing whitespace lives inside the table rather than as a centred
+ * page-section gutter. Pass `restrictWidth={true}` (or a specific
+ * number/string) to opt back into a centred page chrome.
+ *
  * @example
  * ```tsx
  * <KibanaContentListPage>
@@ -209,6 +230,14 @@ const KibanaContentListPageRoot = ({
  *   </KibanaContentListPage.Section>
  * </KibanaContentListPage>
  * ```
+ *
+ * @example Restrict the page width (legacy 1200px chrome)
+ * ```tsx
+ * <KibanaContentListPage restrictWidth>
+ *   <KibanaContentListPage.Header title="Maps" />
+ *   <KibanaContentListPage.Section>{...}</KibanaContentListPage.Section>
+ * </KibanaContentListPage>
+ * ```
  */
 export const KibanaContentListPage = Object.assign(KibanaContentListPageRoot, {
   Header: KibanaContentListPageHeader,

src/platform/packages/shared/content-management/content_list/kbn-content-list-table/README.md

@@ -21,7 +21,8 @@ Use the `Column` compound component to declare columns as children. Order in JSX
 const { Column } = ContentListTable;
 
 <ContentListTable title="Dashboards">
-  <Column.Name width="32em" minWidth="24em" maxWidth="64em" truncateText={false} />
+  <Column.Name />
+  <Column.UpdatedAt />
   <Column
     id="status"
     name="Status"
@@ -50,3 +51,42 @@ Column sizing props (`width`, `minWidth`, `maxWidth`, `truncateText`) map to `Eu
 
 Custom columns use the `Column` component with `id`, `name`, and `render` props.
 
+### Defaults
+
+Each preset bakes in `width` / `minWidth` / `maxWidth` defaults so listings look consistent out of the box. The defaults follow a shared three-layer contract:
+
+- **`width`** — preferred English baseline. Drives the look users see most of the time. Every preset ships with one so each column has a deterministic preferred footprint.
+- **`minWidth`** — the floor. For text-bearing presets this defaults to the CSS keyword `'max-content'`, which lets the header expand to fit a translated label (e.g. de "Letzte Aktualisierung") without truncation. `min-width` wins over `max-width` per the CSS spec, so the floor never fights the cap. `Column.Name` instead pins a fixed `'18em'` floor because user-supplied titles can be arbitrarily long.
+- **`maxWidth`** — the cap. Always pinned to the same value as `width`. The cap is advisory on its own (browsers ignore `max-width` on table cells per the [CSS Tables spec](https://drafts.csswg.org/css-tables/#computing-the-table-width)), but the matching `width` does the actual locking — together they keep the column at its preferred footprint regardless of available slack.
+
+| Preset | `width` | `minWidth` | `maxWidth` | Notes |
+|---|---|---|---|---|
+| `Column.Name` | `64em` | `18em` | `64em` | `64em` (~896px) is a comfortable reading-line ceiling. The browser shrinks Name from `width` toward `minWidth` first when the viewport gets too narrow to fit every column at its preferred width. |
+| `Column.UpdatedAt` | `9.5em` | `'max-content'` | `9.5em` | Locked at `9.5em` in English. Long-text locales expand the column via the `'max-content'` floor. |
+| `Column.CreatedBy` | `88px` | `'max-content'` | `88px` | Header (~75px) plus breathing room for the centred 24px avatar. |
+| `Column.Starred` | `40px` | `40px` | `40px` | Pure icon column — header is a 16px `EuiIcon`. No locale exposure, so no `'max-content'` floor. |
+| `Column.Actions` | _(auto from action count)_ | `'max-content'` | _(equal to derived width)_ | Width still computed by the `36N + 12` formula. `'max-content'` floor lets translated headers expand the column when wider than the icon row. |
+
+#### Trailing whitespace on wide pages
+
+`ContentListTable` renders a CSS `::after` pseudo-cell on every `<tr>` (`tr::after { display: table-cell; content: ''; }`). The browser treats it as an anonymous, unsized table cell for layout purposes, so on a wide page it becomes the only column without an explicit `width` and absorbs all the leftover horizontal space. Populated columns sit left-aligned at their preferred widths and the trailing whitespace lives _after_ the last populated column, all the way to the right edge of the table.
+
+On viewports too narrow to fit all preferred widths the pseudo-cell collapses (no slack to absorb) and the browser shrinks the populated columns proportionally; `Column.Name` shrinks first because it has the most range between its `width` and `minWidth`. No consumer action needed for either case.
+
+There is no DOM, accessibility, or clipboard impact: the rendered table has exactly the columns you declared, screen readers read the correct column count, and copying rows into a spreadsheet doesn't add a trailing tab. See `cssTrailingSpacer` in `content_list_table.tsx` for the rationale and the alternatives that were considered.
+
+#### Wide-viewport `Column.Name` upgrade
+
+On viewports ≥ `2560px` (common 4K external displays), `ContentListTable` widens `Column.Name` from `64em` to `90em` via a media-query CSS override (`cssWideViewportNameWidth` in `content_list_table.tsx`). The trailing pseudo-cell still absorbs whatever horizontal slack remains, so populated sibling columns (`UpdatedAt`, `CreatedBy`, `Actions`, etc.) stay at their preferred footprints; only the Name column / spacer ratio shifts. Because EUI applies `width` / `max-width` as inline styles, the rule uses `!important` and so applies regardless of consumer-supplied `width` overrides — the wide-viewport bump is a cross-cutting layout decision rather than a per-instance default.
+
+#### Overriding defaults
+
+There are two ways to opt out of a baked-in default:
+
+- **Replace** with another value: `<Column.UpdatedAt width="14em" />` swaps the `9.5em` default for `14em`. Useful when you want a different size, not "no constraint".
+- **Clear** with explicit `undefined`: `<Column.Name width={undefined} maxWidth={undefined} />` skips the default entirely — no `width` or `max-width` style is emitted, and the column becomes the slack absorber on wide viewports (taking the slack that would otherwise land in the trailing pseudo-cell). Distinct from omitting the prop, which falls back to the documented default.
+
+A consumer-supplied `width` also re-anchors the `maxWidth` default — so `<Column.UpdatedAt width="14em" />` produces `width: 14em; max-width: 14em;` (the column stays locked at the new preferred footprint).
+
+Use `KibanaContentListPage` for the page chrome — it disables EUI's 1200px `restrictWidth` cap by default so the table actually runs to the full page width and the trailing pseudo-cell has slack to absorb. Pass `restrictWidth={true}` (or a specific value) to opt back in.
+

src/platform/packages/shared/content-management/content_list/kbn-content-list-table/src/breakpoints.ts

@@ -0,0 +1,28 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+/**
+ * Layout constants shared by the table shell and individual column cells.
+ *
+ * Lives in its own module so column-level files can read it without
+ * importing `content_list_table.tsx`, which itself imports `./column`
+ * (a cycle that breaks Jest's module loader and produces
+ * `Cannot read properties of undefined (reading 'NameColumn')`).
+ */
+
+/**
+ * Viewport width (px) at which `Column.Name` is allowed to grow past its
+ * default `64em` cap. `2560px` matches a common 4K external display width
+ * — at that size the default footprint leaves enough trailing whitespace
+ * that giving some of it back to the title column is a clear win.
+ *
+ * Not tied to a named EUI breakpoint because EUI tops out at `xl` (~1200px),
+ * so the value would have to be a hard-coded magic number either way.
+ */
+export const WIDE_VIEWPORT_NAME_BREAKPOINT_PX = 2560;