[EUI+] Reorganize+improve markdown, tables, and data grid docs

packages/eui-docgen/src/filter_prop.ts

@@ -35,13 +35,16 @@ const allowedParents = [
   'RefAttributes',
 ];
 
+// components/types that should allow all props, even from external modules
+const allowedComponents = ['EuiDataGridVirtualizationOptions'];
+
 /**
  * Filter props to remove props from node modules while keeping those whitelisted
  */
 export const filterProp = (
   prop: PropItem,
   component: any,
-  componentExtends: string[]
+  componentExtends: Record<string, string[]>
 ) => {
   if (allowedProps.includes(prop.name)) {
     return true;
@@ -79,18 +82,24 @@ export const filterProp = (
   }
 
   if (prop.parent) {
-    //Check if props are extended from other node module
+    // Check if props are extended from other node module
     if (allowedParents.includes(prop.parent.name)) return true;
-    if (!componentExtends.includes(prop.parent.name)) {
-      componentExtends.push(prop.parent.name);
+
+    if (!componentExtends[component.name]) {
+      componentExtends[component.name] = [];
     }
+    if (!componentExtends[component.name].includes(prop.parent.name)) {
+      componentExtends[component.name].push(prop.parent.name);
+    }
+
     if (allowedProps.includes(prop.name)) {
       return true;
     }
 
+    if (allowedComponents.includes(component.name)) return true;
     if (prop.parent.fileName.includes('@elastic/charts')) return true;
     return !prop.parent.fileName.includes('node_modules');
   }
 
   return true;
-}
+};

packages/eui-docgen/src/main.ts

@@ -36,7 +36,7 @@ const main = async () => {
   for (const file of files) {
     const fileRelativePath = path.relative(euiSrcPath, file);
 
-    const componentExtends: Array<string> = [];
+    const componentExtends: Record<string, string[]> = {};
     const parser = docgen.withCustomConfig(path.join(euiPackagePath, 'tsconfig.json'), {
       propFilter: (prop, component) => filterProp(prop, component, componentExtends),
       shouldExtractLiteralValuesFromEnum: true,
@@ -51,7 +51,7 @@ const main = async () => {
       const processedComponent = processComponent({
         componentDoc: parsedComponent,
         filePath: fileRelativePath,
-        componentExtends: componentExtends,
+        componentExtends: componentExtends[parsedComponent.displayName] || [],
       });
 
       if (!processedComponent) {

packages/eui/scripts/compile-eui.js

@@ -14,6 +14,7 @@ const IGNORE_TESTS = [
   '**/*.spec.tsx',
   '**/*.stories.ts',
   '**/*.stories.tsx',
+  '**/*.docgen.tsx',
   '**/**.stories.utils.ts',
   '**/**.stories.utils.tsx',
   '**/*.mdx',

packages/eui/scripts/dtsgenerator.js

@@ -39,6 +39,7 @@ const generator = dtsGenerator({
     '**/__mocks__/*',
     'src/test/**/*', // Separate d.ts files are generated for test utils
     'src-docs/**/*', // Don't include src-docs
+    '**/*.docgen.tsx', // Don't include "components" generated just for react-docgen
     '**/*.mdx', // Don't include storybook mdx files
   ],
   resolveModuleId(params) {

packages/eui/src-docs/src/views/datagrid/schema_columns/column_dragging.js

@@ -1,8 +1,7 @@
 import React, { useState, useCallback } from 'react';
+import { EuiDataGrid, EuiAvatar } from '@elastic/eui';
 import { faker } from '@faker-js/faker';
 
-import { EuiDataGrid, EuiAvatar } from '../../../../../src/components';
-
 const columns = [
   {
     id: 'avatar',
@@ -69,11 +68,12 @@ export default () => {
 
   return (
     <EuiDataGrid
-      aria-label="DataGrid demonstrating column sizing constraints"
+      aria-label="DataGrid demonstrating draggable column headers"
       columns={columns}
       columnVisibility={{
         visibleColumns: visibleColumns,
         setVisibleColumns: setVisibleColumns,
+        canDragAndDropColumns: true,
       }}
       rowCount={data.length}
       renderCellValue={({ rowIndex, columnId }) => data[rowIndex][columnId]}

packages/eui/src/components/datagrid/controls/data_grid_toolbar.stories.tsx

@@ -22,15 +22,15 @@ import type {
   EuiDataGridToolBarVisibilityOptions,
   EuiDataGridToolBarAdditionalControlsOptions,
 } from '../data_grid_types';
+import { ToolbarStorybookComponent } from '../data_grid_types.docgen';
 import {
-  EuiDataGridToolbarPropsComponent,
   StatefulDataGrid,
   defaultStorybookArgs,
 } from '../data_grid.stories.utils';
 
 const meta: Meta = {
   title: 'Tabular Content/EuiDataGrid/toolbarVisibility (prop)',
-  component: EuiDataGridToolbarPropsComponent,
+  component: ToolbarStorybookComponent,
 };
 
 export default meta;

packages/eui/src/components/datagrid/data_grid.stories.utils.tsx

@@ -8,12 +8,7 @@
 
 /* eslint-disable storybook/default-exports, storybook/prefer-pascal-case */
 
-import React, {
-  useCallback,
-  useEffect,
-  useState,
-  FunctionComponent,
-} from 'react';
+import React, { useCallback, useEffect, useState } from 'react';
 import { css } from '@emotion/react';
 import { faker } from '@faker-js/faker';
 
@@ -29,10 +24,6 @@ import type {
   EuiDataGridColumnCellActionProps,
   EuiDataGridColumnSortingConfig,
   EuiDataGridProps,
-  EuiDataGridStyle,
-  EuiDataGridRowHeightsOptions,
-  EuiDataGridToolBarVisibilityOptions,
-  EuiDataGridToolBarAdditionalControlsOptions,
 } from './data_grid_types';
 import { EuiDataGrid } from './data_grid';
 
@@ -405,25 +396,3 @@ export const StatefulDataGrid = (props: EuiDataGridProps) => {
     />
   );
 };
-
-/*
- * Components that exist purely for allowing Storybook to parse certain nested
- * interfaces/types into specific example control tables.
- *
- * For whatever reason, they needs to be in a separate file for Storybook's
- * react-typescript-docgen to parse the jsdoc comments into the controls table
- */
-
-export const EuiDataGridToolbarPropsComponent: FunctionComponent<
-  EuiDataGridProps & // We really just want toolbarVisibility and renderCustomToolbar from here, but typescript-docgen is unhappy if we Pick<>
-    EuiDataGridToolBarVisibilityOptions &
-    EuiDataGridToolBarAdditionalControlsOptions
-> = () => <></>;
-
-export const EuiDataGridStylePropsComponent: FunctionComponent<
-  EuiDataGridStyle
-> = () => <></>;
-
-export const EuiDataGridRowHeightsPropsComponent: FunctionComponent<
-  EuiDataGridRowHeightsOptions
-> = () => <></>;

packages/eui/src/components/datagrid/data_grid_row_heights.stories.tsx

@@ -13,13 +13,13 @@ import { enableFunctionToggleControls } from '../../../.storybook/utils';
 import {
   StatefulDataGrid,
   defaultStorybookArgs,
-  EuiDataGridRowHeightsPropsComponent,
 } from './data_grid.stories.utils';
+import { EuiDataGridRowHeightsOptions as Component } from './data_grid_types.docgen';
 import type { EuiDataGridRowHeightsOptions } from './data_grid_types';
 
 const meta: Meta<EuiDataGridRowHeightsOptions> = {
   title: 'Tabular Content/EuiDataGrid/rowHeightsOptions (prop)',
-  component: EuiDataGridRowHeightsPropsComponent,
+  component: Component,
   parameters: {
     codeSnippet: {
       snippet: `<EuiDataGrid rowHeightOptions={{{STORY_ARGS}}} />`,

packages/eui/src/components/datagrid/data_grid_styles.stories.tsx

@@ -14,13 +14,13 @@ import { enableFunctionToggleControls } from '../../../.storybook/utils';
 import {
   StatefulDataGrid,
   defaultStorybookArgs,
-  EuiDataGridStylePropsComponent,
 } from './data_grid.stories.utils';
+import { EuiDataGridStyle as Component } from './data_grid_types.docgen';
 import type { EuiDataGridStyle } from './data_grid_types';
 
 const meta: Meta = {
   title: 'Tabular Content/EuiDataGrid/gridStyle (prop)',
-  component: EuiDataGridStylePropsComponent,
+  component: Component,
 };
 
 export default meta;

packages/eui/src/components/datagrid/data_grid_types.docgen.tsx

@@ -0,0 +1,122 @@
+/*
+ * 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 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 or the Server
+ * Side Public License, v 1.
+ */
+
+import React, { FunctionComponent } from 'react';
+import * as DataGridTypes from './data_grid_types';
+import { EuiDataGridToolbarControlProps } from './controls/data_grid_toolbar_control';
+
+// This file only exists for react-typescript-docgen (used by both EUI+ and Storybook),
+// which has difficulty extracting typescript definitions that aren't directly props of
+// components. NOTE: This file should *NOT* be exported publicly.
+// @see packages/eui-docgen
+
+export const EuiDataGridColumnVisibility: FunctionComponent<
+  DataGridTypes.EuiDataGridColumnVisibility
+> = () => <></>;
+
+export const EuiDataGridPaginationProps: FunctionComponent<
+  DataGridTypes.EuiDataGridPaginationProps
+> = () => <></>;
+
+export const EuiDataGridSorting: FunctionComponent<
+  DataGridTypes.EuiDataGridSorting
+> = () => <></>;
+
+export const EuiDataGridColumn: FunctionComponent<
+  DataGridTypes.EuiDataGridColumn
+> = () => <></>;
+
+export const EuiDataGridColumnActions: FunctionComponent<
+  DataGridTypes.EuiDataGridColumnActions
+> = () => <></>;
+
+export const EuiDataGridColumnCellActionProps: FunctionComponent<
+  DataGridTypes.EuiDataGridColumnCellActionProps
+> = () => <></>;
+
+export const EuiDataGridControlColumn: FunctionComponent<
+  DataGridTypes.EuiDataGridControlColumn
+> = () => <></>;
+
+export const EuiDataGridSchemaDetector: FunctionComponent<
+  DataGridTypes.EuiDataGridSchemaDetector
+> = () => <></>;
+
+export const EuiDataGridCellValueElementProps: FunctionComponent<
+  DataGridTypes.EuiDataGridCellValueElementProps
+> = () => <></>;
+
+export const EuiDataGridCellPopoverElementProps: FunctionComponent<
+  DataGridTypes.EuiDataGridCellPopoverElementProps
+> = () => <></>;
+
+export const EuiDataGridToolBarVisibilityOptions: FunctionComponent<
+  DataGridTypes.EuiDataGridToolBarVisibilityOptions
+> = () => <></>;
+
+export const EuiDataGridToolBarAdditionalControlsOptions: FunctionComponent<
+  DataGridTypes.EuiDataGridToolBarAdditionalControlsOptions
+> = () => <></>;
+
+export const EuiDataGridToolBarAdditionalControlsLeftOptions: FunctionComponent<
+  DataGridTypes.EuiDataGridToolBarAdditionalControlsLeftOptions
+> = () => <></>;
+
+export const EuiDataGridCustomToolbarProps: FunctionComponent<
+  DataGridTypes.EuiDataGridCustomToolbarProps
+> = () => <></>;
+
+export const EuiDataGridToolbarControl: FunctionComponent<
+  EuiDataGridToolbarControlProps
+> = () => <></>;
+
+export const EuiDataGridToolBarVisibilityColumnSelectorOptions: FunctionComponent<
+  DataGridTypes.EuiDataGridToolBarVisibilityColumnSelectorOptions
+> = () => <></>;
+
+export const EuiDataGridToolBarVisibilityDisplaySelectorOptions: FunctionComponent<
+  DataGridTypes.EuiDataGridToolBarVisibilityDisplaySelectorOptions
+> = () => <></>;
+
+export const EuiDataGridDisplaySelectorCustomRenderProps: FunctionComponent<
+  DataGridTypes.EuiDataGridDisplaySelectorCustomRenderProps
+> = () => <></>;
+
+export const ToolbarStorybookComponent: FunctionComponent<
+  DataGridTypes.EuiDataGridProps & // We really just want toolbarVisibility and renderCustomToolbar from here, but typescript-docgen is unhappy if we Pick<>
+    DataGridTypes.EuiDataGridToolBarVisibilityOptions &
+    DataGridTypes.EuiDataGridToolBarAdditionalControlsOptions
+> = () => <></>;
+
+export const EuiDataGridStyle: FunctionComponent<
+  DataGridTypes.EuiDataGridStyle
+> = () => <></>;
+
+export const EuiDataGridRowHeightsOptions: FunctionComponent<
+  DataGridTypes.EuiDataGridRowHeightsOptions
+> = () => <></>;
+
+export const EuiDataGridHeightWidthProps: FunctionComponent<
+  Pick<DataGridTypes.EuiDataGridProps, 'height' | 'width'>
+> = () => <></>;
+
+export const EuiDataGridVirtualizationOptions: FunctionComponent<
+  DataGridTypes.EuiDataGridProps['virtualizationOptions']
+> = () => <></>;
+
+export const EuiDataGridRefProps: FunctionComponent<
+  DataGridTypes.EuiDataGridRefProps
+> = () => <></>;
+
+export const EuiDataGridInMemory: FunctionComponent<
+  DataGridTypes.EuiDataGridInMemory
+> = () => <></>;
+
+export const EuiDataGridCustomBodyProps: FunctionComponent<
+  DataGridTypes.EuiDataGridCustomBodyProps
+> = () => <></>;

packages/eui/src/components/datagrid/data_grid_types.ts

@@ -366,23 +366,21 @@ export type CommonGridProps = CommonProps &
     /**
      * Allows customizing the underlying [react-window grid](https://react-window.vercel.app/#/api/VariableSizeGrid) props.
      */
-    virtualizationOptions?: Partial<
-      Omit<
-        VariableSizeGridProps,
-        | 'children'
-        | 'itemData'
-        | 'height'
-        | 'width'
-        | 'rowCount'
-        | 'rowHeight'
-        | 'columnCount'
-        | 'columnWidth'
-        | 'ref'
-        | 'innerRef'
-        | 'outerRef'
-        | 'innerElementType'
-        | 'useIsScrolling'
-      >
+    virtualizationOptions?: Pick<
+      VariableSizeGridProps,
+      | 'className'
+      | 'style'
+      | 'direction'
+      | 'estimatedRowHeight'
+      | 'estimatedColumnWidth'
+      | 'overscanRowCount'
+      | 'overscanColumnCount'
+      | 'initialScrollTop'
+      | 'initialScrollLeft'
+      | 'onScroll'
+      | 'onItemsRendered'
+      | 'itemKey'
+      | 'outerElementType'
     >;
     /**
      * A #EuiDataGridRowHeightsOptions object that provides row heights options.
@@ -944,12 +942,16 @@ export interface EuiDataGridToolBarVisibilityDisplaySelectorOptions {
   customRender?: EuiDataGridDisplaySelectorCustomRender;
 }
 
-export type EuiDataGridDisplaySelectorCustomRender = (args: {
+export type EuiDataGridDisplaySelectorCustomRenderProps = {
   densityControl: ReactNode;
   rowHeightControl: ReactNode;
   additionalDisplaySettings: ReactNode;
   resetButton: ReactNode;
-}) => ReactNode;
+};
+
+export type EuiDataGridDisplaySelectorCustomRender = (
+  args: EuiDataGridDisplaySelectorCustomRenderProps
+) => ReactNode;
 
 export interface EuiDataGridToolBarVisibilityOptions {
   /**

packages/website/docs/components/editors_and_syntax/markdown/_category_.yml

@@ -0,0 +1,2 @@
+label: Markdown
+collapsed: true