@atlaskit/dynamic-table 14.5.5 → 14.7.0

package/dist/types/types.d.ts

@@ -46,7 +46,7 @@ export interface StatelessProps extends WithAnalyticsEventsProps {
     /**
      * Rows to be placed in the table.
      * Each row contains cells which should map to the ones defined in the head.
-  
+     *
      * Ensure each cell has a unique `key` per column - this is used for both Reacts reconcilation of lists and column sorting.
      */
     rows?: Array<RowType>;
@@ -90,7 +90,7 @@ export interface StatelessProps extends WithAnalyticsEventsProps {
      */
     onPageRowsUpdate?: (pageRows: Array<RowType>) => void;
     /**
-     * Page the table should show.
+     * Page the table should show. Set by default to 1, so never undefined.
      */
     page?: number;
     /**
@@ -129,18 +129,19 @@ export interface StatelessProps extends WithAnalyticsEventsProps {
      */
     highlightedRowIndex?: number | number[];
     /**
-      A `testId` prop is provided for specified elements,
-      which is a unique string that appears as a data attribute
-      `data-testid` in the rendered code, serving as a hook for automated tests.
-  
-      The value of `testId` is used to prefix `testId` props in given elements.
-      + `${testId}--table` - Table.
-      + `${testId}--head` - Table header.
-      + `${testId}--head--{content of the cell}` - Table header cell can be identified by their content.
-      + `${testId}--row--{index - content of the first cell}` - Table row.
-      + `${testId}--body` - Table body.
-      + `${testId}--body--{content of the cell}` - Table body cell can be identified by their content.
-      + `${testId}--loadingSpinner` - The spinner overlaid when loading.
+     *  A `testId` prop is provided for specified elements,
+     *  which is a unique string that appears as a data attribute
+     *  `data-testid` in the rendered code, serving as a hook for automated tests.
+     *
+     *  The value of `testId` is used to prefix `testId` props in given elements.
+     *  - `{testId}--table` - Table.
+     *  - `{testId}--head` - Table header.
+     *  - `{testId}--head--{content of the cell}` - Table header cell can be identified by their content.
+     *  - `{testId}--row--{index - content of the first cell}` - Table row.
+     *  - `{testId}--body` - Table body.
+     *  - `{testId}--body--{content of the cell}` - Table body cell can be identified by their content.
+     *  - `{testId}--loadingSpinner` - The spinner overlaid when loading.
+     * - `{testId}--pagination` - The table pagination.
      */
     testId?: string;
     /**
@@ -164,7 +165,6 @@ export interface StatefulProps extends WithAnalyticsEventsProps {
      * Rows to be placed in the table.
      * Each row contains cells which should map to the ones defined in the head.
      * Rows accept standard HTML <tr> props in addition to those listed below.
-  
      * Ensure each cell has a unique `key` per column - this is used for both React's reconciliation of lists and column sorting.
      */
     rows?: Array<RowType>;
@@ -186,7 +186,7 @@ export interface StatefulProps extends WithAnalyticsEventsProps {
      */
     isFixedSize?: boolean;
     /**
-     * Controls how many rows should be diplayed per page.
+     * Controls how many rows should be displayed per page. If set, also turns on pagination, if there is more than one page to show.
      */
     rowsPerPage?: number;
     /**
@@ -260,18 +260,18 @@ export interface StatefulProps extends WithAnalyticsEventsProps {
      */
     highlightedRowIndex?: number | number[];
     /**
-      A `testId` prop is provided for specified elements,
-      which is a unique string that appears as a data attribute
-      `data-testid` in the rendered code, serving as a hook for automated tests.
-  
-      The value of `testId` is used to prefix `testId` props in given elements.
-      + `${testId}--table` - Table.
-      + `${testId}--head` - Table header.
-      + `${testId}--head--{content of the cell}` - Table header cell can be identified by their content.
-      + `${testId}--row--{index - content of the first cell}` - Table row.
-      + `${testId}--body` - Table body.
-      + `${testId}--body--{content of the cell}` - Table body cell can be identified by their content.
-      + `${testId}--loadingSpinner` - The spinner overlaid when loading.
+     * A `testId` prop is provided for specified elements,
+     * which is a unique string that appears as a data attribute
+     * `data-testid` in the rendered code, serving as a hook for automated tests.
+     * The value of `testId` is used to prefix `testId` props in given elements.
+     *  - `{testId}--table` - Table.
+     *  - `{testId}--head` - Table header.
+     *  - `{testId}--head--{content of the cell}` - Table header cell can be identified by their content.
+     *  - `{testId}--row--{index - content of the first cell}` - Table row.
+     *  - `{testId}--body` - Table body.
+     *  - `{testId}--body--{content of the cell}` - Table body cell can be identified by their content.
+     *  - `{testId}--loadingSpinner` - The spinner overlaid when loading.
+     *  - `{testId}--pagination` - The table pagination.
      */
     testId?: string;
     /**
@@ -313,11 +313,17 @@ export declare type SortOrderType = 'ASC' | 'DESC';
 export declare type SpinnerSizeType = SizeType;
 export declare type LoadingSpinnerSizeType = 'small' | 'large';
 export interface HeadCellType extends RowCellType {
-    /** Whether the column the cell sits above is sortable. */
+    /**
+     * Whether the column the cell sits above is sortable.
+     */
     isSortable?: boolean;
-    /** The pixel width of the cell. */
+    /**
+     * The width of the cell as a percentage.
+     */
     width?: number;
-    /** Whether the text in the cell will truncate or not if constrained. */
+    /**
+     * Whether the text in the cell will truncate or not if constrained.
+     */
     shouldTruncate?: boolean;
 }
 export interface RankEndLocation {

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@atlaskit/dynamic-table",
-  "version": "14.5.5",
+  "version": "14.7.0",
   "description": "A dynamic table displays rows of data with built-in pagination, sorting, and re-ordering functionality.",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
   "homepage": "https://atlassian.design/components/dynamic-table/",
-  "repository": "https://bitbucket.org/atlassian/atlassian-frontend",
+  "repository": "https://bitbucket.org/atlassian/atlassian-frontend-mirror",
   "author": "Atlassian Pty Ltd",
   "license": "Apache-2.0",
   "main": "dist/cjs/index.js",
@@ -14,17 +14,19 @@
   "module:es2019": "dist/es2019/index.js",
   "types": "dist/types/index.d.ts",
   "sideEffects": false,
-  "atlaskit:src": "src/index.ts",
+  "atlaskit:src": "src/index.tsx",
   "atlassian": {
     "team": "Design System Team",
     "deprecatedAutoEntryPoints": true,
     "releaseModel": "scheduled",
     "website": {
-      "name": "Dynamic table"
+      "name": "Dynamic table",
+      "category": "Components"
     }
   },
   "dependencies": {
     "@atlaskit/analytics-next": "^8.0.0",
+    "@atlaskit/ds-lib": "^2.1.0",
     "@atlaskit/pagination": "^14.0.0",
     "@atlaskit/spinner": "^15.0.0",
     "@atlaskit/theme": "^12.1.0",
@@ -38,10 +40,10 @@
     "react-dom": "^16.8.0"
   },
   "devDependencies": {
-    "@atlaskit/avatar": "^20.5.0",
+    "@atlaskit/avatar": "^21.0.0",
     "@atlaskit/button": "^16.3.0",
     "@atlaskit/docs": "*",
-    "@atlaskit/dropdown-menu": "^11.1.0",
+    "@atlaskit/dropdown-menu": "^11.3.0",
     "@atlaskit/ssr": "*",
     "@atlaskit/toggle": "^12.4.0",
     "@atlaskit/visual-regression": "*",
@@ -60,6 +62,8 @@
       "import-structure": "atlassian-conventions"
     },
     "@repo/internal": {
+      "dom-events": "use-bind-event-listener",
+      "design-system": "v1",
       "theming": "tokens",
       "deprecation": "no-deprecated-imports",
       "styling": [

package/report.api.md

@@ -0,0 +1,508 @@
+## API Report File for "@atlaskit/dynamic-table"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+````ts
+import { default as React_2 } from 'react';
+import { Ref } from 'react';
+import { UIAnalyticsEvent } from '@atlaskit/analytics-next';
+import { WithAnalyticsEventsProps } from '@atlaskit/analytics-next';
+import { WithContextProps } from '@atlaskit/analytics-next';
+
+/**
+ * __Dynamic Table__
+ *
+ * A table displays rows of data with built-in pagination, sorting, and re-ordering functionality.
+ *
+ * - [Examples](https://atlaskit.atlassian.com/packages/design-system/dynamic-table)
+ * - [Code](https://bitbucket.org/atlassian/atlassian-frontend/packages/design-system/dynamic-table)
+ *
+ * @example
+ * ```jsx
+ * import DynamicTable from '@atlaskit/dynamic-table';
+ *
+ * export default function TableUncontrolled() {
+ *  return (
+ *   <DynamicTable
+ *    head={head}
+ *    rows={rows}
+ *    rowsPerPage={10}
+ *    defaultPage={1}
+ *    loadingSpinnerSize="large"
+ *    isLoading={false}
+ *   />
+ *  );
+ * }
+ * ```
+ */
+declare class DynamicTable extends React_2.Component<StatefulProps, State> {
+  static defaultProps: {
+    defaultPage: number;
+    isLoading: boolean;
+    isFixedSize: boolean;
+    isRankable: boolean;
+    onSetPage: () => void;
+    onSort: () => void;
+    rowsPerPage: number;
+  };
+  state: {
+    page: number | undefined;
+    sortKey: string | undefined;
+    sortOrder: SortOrderType | undefined;
+    rows: RowType[] | undefined;
+  };
+  UNSAFE_componentWillReceiveProps(newProps: StatefulProps): void;
+  onSetPage: (
+    page: number,
+    analyticsEvent?: UIAnalyticsEvent | undefined,
+  ) => void;
+  onSort: (
+    { key, item, sortOrder }: any,
+    analyticsEvent?: UIAnalyticsEvent | undefined,
+  ) => void;
+  onRankEndIfExists: (params: RankEnd) => void;
+  onRankEnd: (params: RankEnd) => void;
+  render(): JSX.Element;
+}
+export default DynamicTable;
+
+export declare const DynamicTableStateless: React_2.ForwardRefExoticComponent<
+  Pick<
+    Pick<
+      Omit<StatelessProps, keyof WithAnalyticsEventsProps>,
+      | 'caption'
+      | 'head'
+      | 'label'
+      | 'rows'
+      | 'sortKey'
+      | 'sortOrder'
+      | 'onPageRowsUpdate'
+      | 'testId'
+      | 'highlightedRowIndex'
+      | 'emptyView'
+      | 'loadingSpinnerSize'
+      | 'totalRows'
+    > &
+      Partial<
+        Pick<
+          Omit<StatelessProps, keyof WithAnalyticsEventsProps>,
+          | 'isFixedSize'
+          | 'page'
+          | 'rowsPerPage'
+          | 'isLoading'
+          | 'isRankingDisabled'
+          | 'onRankStart'
+          | 'onRankEnd'
+          | 'onSort'
+          | 'isRankable'
+          | 'onSetPage'
+          | 'paginationi18n'
+        >
+      > &
+      Partial<
+        Pick<
+          {
+            isLoading: boolean;
+            isFixedSize: boolean;
+            rowsPerPage: number;
+            onSetPage: () => void;
+            onSort: () => void;
+            page: number;
+            isRankable: boolean;
+            isRankingDisabled: boolean;
+            onRankStart: () => void;
+            onRankEnd: () => void;
+            paginationi18n: {
+              prev: string;
+              next: string;
+              label: string;
+            };
+          },
+          never
+        >
+      > &
+      React_2.RefAttributes<any> &
+      WithContextProps,
+    | 'caption'
+    | 'head'
+    | 'label'
+    | 'key'
+    | 'isFixedSize'
+    | 'rows'
+    | 'page'
+    | 'rowsPerPage'
+    | 'sortKey'
+    | 'sortOrder'
+    | 'onPageRowsUpdate'
+    | 'testId'
+    | 'highlightedRowIndex'
+    | 'isLoading'
+    | 'isRankingDisabled'
+    | 'onRankStart'
+    | 'onRankEnd'
+    | 'onSort'
+    | 'isRankable'
+    | 'emptyView'
+    | 'loadingSpinnerSize'
+    | 'totalRows'
+    | 'onSetPage'
+    | 'paginationi18n'
+    | 'analyticsContext'
+  > &
+    React_2.RefAttributes<any>
+>;
+
+declare interface HeadCellType extends RowCellType {
+  /** Whether the column the cell sits above is sortable. */
+  isSortable?: boolean;
+  /** The pixel width of the cell. */
+  width?: number;
+  /** Whether the text in the cell will truncate or not if constrained. */
+  shouldTruncate?: boolean;
+}
+
+declare interface HeadType {
+  cells: Array<HeadCellType>;
+}
+
+declare interface I18nShape {
+  /**
+   * Accessible label applied to the previous page button in the pagination component.
+   */
+  prev: string;
+  /**
+   * Accessible label applied to the next page button in the pagination component.
+   */
+  next: string;
+  /**
+   * Accessible label applied to the current page button in the pagination component.
+   */
+  label: string;
+}
+
+declare type LoadingSpinnerSizeType = 'small' | 'large';
+
+declare interface RankEnd {
+  sourceIndex: number;
+  sourceKey: string;
+  destination?: RankEndLocation;
+}
+
+declare interface RankEndLocation {
+  index: number;
+  afterKey?: string;
+  beforeKey?: string;
+}
+
+declare interface RankStart {
+  index: number;
+  key: string;
+}
+
+declare interface RowCellType {
+  /**
+   * Key to resolve sorting this cell in its column.
+   */
+  key?: string | number;
+  /**
+   * The number of columns a cell should span. Defaults to 1, and maxes out at the total column width of the table.
+   */
+  colSpan?: number;
+  /**
+   * The content of the cell.
+   */
+  content?: React_2.ReactNode | string;
+  /**
+   * Hook for automated testing.
+   */
+  testId?: string;
+}
+
+declare interface RowType extends React_2.ComponentPropsWithoutRef<'tr'> {
+  cells: Array<RowCellType>;
+  key?: string;
+  /**
+   * A mouse handler to support interaction of a row.
+   */
+  onClick?: React_2.MouseEventHandler;
+  /**
+   * A key event handler to support interaction of a row.
+   */
+  onKeyPress?: React_2.KeyboardEventHandler;
+  /**
+   * Highlights the row. Should be used to draw attention to a row; not to indicate selection.
+   */
+  isHighlighted?: boolean;
+  /**
+   * Hook for automated testing.
+   */
+  testId?: string;
+  ref?: Ref<HTMLTableRowElement>;
+}
+
+/**
+ * Enum style type to determine whether sort results are ascending or descending.
+ */
+declare type SortOrderType = 'ASC' | 'DESC';
+
+declare interface State {
+  page?: number;
+  sortKey?: string;
+  sortOrder?: SortOrderType;
+  rows?: RowType[];
+}
+
+declare interface StatefulProps extends WithAnalyticsEventsProps {
+  /**
+   * Caption for the table styled as a heading.
+   */
+  caption?: React_2.ReactNode;
+  /**
+   * Cells to be placed in the head of the table.
+   * Each element in the head creates a new column.
+   */
+  head?: HeadType;
+  /**
+     * Rows to be placed in the table.
+     * Each row contains cells which should map to the ones defined in the head.
+     * Rows accept standard HTML <tr> props in addition to those listed below.
+
+     * Ensure each cell has a unique `key` per column - this is used for both React's reconciliation of lists and column sorting.
+     */
+  rows?: Array<RowType>;
+  /**
+   * Shown when the table has no content.
+   */
+  emptyView?: React_2.ReactElement<any>;
+  /**
+   * Configuration of the loading spinner shown when `isLoading` is true.
+   * Defaults to `"large"` when a page has more than two rows, else `"small"`.
+   */
+  loadingSpinnerSize?: LoadingSpinnerSizeType;
+  /**
+   * Displays a loading spinner overlaid on top of the current page.
+   */
+  isLoading?: boolean;
+  /**
+   * Displays columns as their initial width regardless of the content that loads in.
+   */
+  isFixedSize?: boolean;
+  /**
+   * Controls how many rows should be diplayed per page.
+   */
+  rowsPerPage?: number;
+  /**
+   * Callback fired when the table page has changed,
+   * useful when wanting to control dynamic table.
+   */
+  onSetPage?: (page: number, UIAnalyticsEvent?: UIAnalyticsEvent) => void;
+  /**
+   * Callback fired when a column heading has been sorted,
+   * useful when wanting to control dynamic table.
+   */
+  onSort?: (data: any, UIAnalyticsEvent?: UIAnalyticsEvent) => void;
+  /**
+   * Callback fired when the rows displayed on a page have changed.
+   */
+  onPageRowsUpdate?: (pageRows: Array<RowType>) => void;
+  /**
+   * Page the table should show.
+   * Useful when wanting to control dynamic table.
+   */
+  page?: number;
+  /**
+   * Default page dynamic table should show when initially rendering.
+   */
+  defaultPage?: number;
+  /**
+   * Column key that the rows should be sorted by.
+   * Corresponds to the `key`'s defined in the `head` prop.
+   * Useful when wanting to control dynamic table.
+   */
+  sortKey?: string;
+  /**
+   * Default column sort key that the rows should be sorted by.
+   * Corresponds to the `key`'s defined in the `head` prop.
+   */
+  defaultSortKey?: string;
+  /**
+   * Column sort order.
+   * Useful when wanting to control dynamic table.
+   */
+  sortOrder?: SortOrderType;
+  /**
+   * Default column sort order used when initially rendering.
+   * Defaults to `"ASC"`.
+   */
+  defaultSortOrder?: SortOrderType;
+  /**
+   * Enables drag & drop sorting of table rows.
+   */
+  isRankable?: boolean;
+  /**
+   * Disables being able to drop rows on the table.
+   * Drag will still function.
+   */
+  isRankingDisabled?: boolean;
+  /**
+   * Callback fired when a drag of a row has started.
+   */
+  onRankStart?: (rankStart: RankStart) => void;
+  /**
+   * Callback fired when a drop of a row has completed.
+   */
+  onRankEnd?: (rankEnd: RankEnd) => void;
+  /**
+   * Labels for the previous and next buttons used in pagination.
+   * Defaults to `"previous"` and `"next"`.
+   */
+  paginationi18n?: I18nShape;
+  /**
+   * Will highlight a row(s) of the table.
+   */
+  highlightedRowIndex?: number | number[];
+  /**
+     A `testId` prop is provided for specified elements,
+     which is a unique string that appears as a data attribute
+     `data-testid` in the rendered code, serving as a hook for automated tests.
+
+     The value of `testId` is used to prefix `testId` props in given elements.
+     - `{testId}--table` - Table.
+     - `{testId}--head` - Table header.
+     - `{testId}--head--{content of the cell}` - Table header cell can be identified by their content.
+     - `{testId}--row--{index - content of the first cell}` - Table row.
+     - `{testId}--body` - Table body.
+     - `{testId}--body--{content of the cell}` - Table body cell can be identified by their content.
+     - `{testId}--loadingSpinner` - The spinner overlaid when loading.
+     - `{testId}--pagination` - The table pagination.
+     */
+  testId?: string;
+  /**
+   * Used to provide a better description of the table for users with assistive technologies.
+   * Rather than a screen reader speaking "Entering table", passing in an label
+   * allows a custom message like "Entering Sample Numerical Data table".
+   */
+  label?: string;
+}
+
+declare interface StatelessProps extends WithAnalyticsEventsProps {
+  /**
+   * Caption for the table styled as a heading.
+   */
+  caption?: React_2.ReactNode;
+  /**
+   * Cells to be placed in the head of the table.
+   * Each element in the head creates a new column.
+   */
+  head?: HeadType;
+  /**
+     * Rows to be placed in the table.
+     * Each row contains cells which should map to the ones defined in the head.
+
+     * Ensure each cell has a unique `key` per column - this is used for both Reacts reconcilation of lists and column sorting.
+     */
+  rows?: Array<RowType>;
+  /**
+   * Shown when the table has no content.
+   */
+  emptyView?: React_2.ReactElement<any>;
+  /**
+   * Configuration of the loading spinner shown when `isLoading` is true.
+   * Defaults to `"large"` when a page has more than two rows, else `"small"`.
+   */
+  loadingSpinnerSize?: LoadingSpinnerSizeType;
+  /**
+   * Displays a loading spinner overlaid on top of the current page.
+   */
+  isLoading?: boolean;
+  /**
+   * Displays columns as their initial width regardless of the content that loads in.
+   */
+  isFixedSize?: boolean;
+  /**
+   * Controls how many rows should be displayed per page.
+   */
+  rowsPerPage?: number;
+  /**
+   * Total number of rows, in case of paginated data.
+   */
+  totalRows?: number;
+  /**
+   * Callback fired when the table page has changed,
+   * useful when wanting to control the pagination of the table.
+   */
+  onSetPage?: (page: number, UIAnalyticsEvent?: UIAnalyticsEvent) => void;
+  /**
+   * Callback fired when a column heading has been sorted,
+   * useful when wanting to control the sort order of the table.
+   */
+  onSort?: (data: any, UIAnalyticsEvent?: UIAnalyticsEvent) => void;
+  /**
+   * Callback fired when the rows displayed on a page have changed.
+   */
+  onPageRowsUpdate?: (pageRows: Array<RowType>) => void;
+  /**
+   * Page the table should show.
+   */
+  page?: number;
+  /**
+   * Column key that the rows should be sorted by.
+   * Corresponds to the `key`'s defined in the `head` prop.
+   */
+  sortKey?: string;
+  /**
+   * Column sort order.
+   */
+  sortOrder?: SortOrderType;
+  /**
+   * Enables drag & drop sorting of table rows.
+   */
+  isRankable?: boolean;
+  /**
+   * Disables being able to drop rows on the table.
+   * Drag will still function.
+   */
+  isRankingDisabled?: boolean;
+  /**
+   * Callback fired when a drag of a row has started.
+   */
+  onRankStart?: (rankStart: RankStart) => void;
+  /**
+   * Callback fired when a drop of a row has completed.
+   */
+  onRankEnd?: (rankEnd: RankEnd, uiAnalyticsEvent?: UIAnalyticsEvent) => void;
+  /**
+   * Labels for the pagination wrapper, previous and next buttons used in pagination.
+   * Defaults to `"pagination"`, `"previous"` and `"next"`.
+   */
+  paginationi18n?: I18nShape;
+  /**
+   * Will highlight a row(s) of the table. Should be used to draw attention to a row; not to indicate selection.
+   */
+  highlightedRowIndex?: number | number[];
+  /**
+     A `testId` prop is provided for specified elements,
+     which is a unique string that appears as a data attribute
+     `data-testid` in the rendered code, serving as a hook for automated tests.
+
+     The value of `testId` is used to prefix `testId` props in given elements.
+     - `{testId}--table` - Table.
+     - `{testId}--head` - Table header.
+     - `{testId}--head--{content of the cell}` - Table header cell can be identified by their content.
+     - `{testId}--row--{index - content of the first cell}` - Table row.
+     - `{testId}--body` - Table body.
+     - `{testId}--body--{content of the cell}` - Table body cell can be identified by their content.
+     - `{testId}--loadingSpinner` - The spinner overlaid when loading.
+     - `{testId}--pagination` - The table pagination.
+     */
+  testId?: string;
+  /**
+   * Used to provide a better description of the table for users with assistive technologies.
+   * Rather than a screen reader speaking "Entering table", passing in an label
+   * allows a custom message like "Entering Sample Numerical Data table".
+   */
+  label?: string;
+}
+
+export {};
+````