@canonical/maas-react-components 2.0.4 → 2.2.0

package/dist/src/lib/components/GenericTable/GenericTable.d.ts

@@ -1,18 +1,9 @@
 import { DetailedHTMLProps, Dispatch, HTMLAttributes, ReactElement, ReactNode, RefObject, SetStateAction } from 'react';
-import { Column, ColumnDef, ColumnSort, Header, Row, RowSelectionState, SortingState } from '@tanstack/react-table';
-import { PaginationBarProps } from './PaginationBar';
-type SelectionProps<T extends {
-    id: number | string;
-}> = {
-    filterSelectable?: (row: Row<T>) => boolean;
-    disabledSelectionTooltip?: string | ((row: Row<T>) => string);
-    rowSelectionLabelKey?: keyof T;
-    rowSelection?: RowSelectionState;
-    setRowSelection?: Dispatch<SetStateAction<RowSelectionState>>;
-};
-type GenericTableProps<T extends {
-    id: number | string;
-}> = {
+import { Column, ColumnDef, ColumnSort, Header, Row, SortingState } from '@tanstack/react-table';
+import { PaginationBarProps } from './components/PaginationBar';
+import { SelectionProps, GenericTableData } from './types';
+type GenericTableProps<T extends GenericTableData> = {
+    "aria-label"?: string;
     className?: string;
     columns: ColumnDef<T, Partial<T>>[];
     containerRef?: RefObject<HTMLElement | null>;
@@ -22,6 +13,8 @@ type GenericTableProps<T extends {
     getSubRows?: (originalRow: T, index: number) => T[] | undefined;
     groupBy?: string[];
     isLoading: boolean;
+    loadingVariant?: "spinner" | "skeleton";
+    skeletonRowCount?: number;
     noData?: ReactNode;
     pagination?: PaginationBarProps;
     pinGroup?: {
@@ -53,17 +46,15 @@ type GenericTableProps<T extends {
  * @param {(originalRow: T, index: number) => T[] | undefined} [props.getSubRows] - Function that returns the T.prop that contains nested T data
  * @param {string[]} [props.groupBy] - Column IDs to group rows by
  * @param {boolean} props.isLoading - Loading state to display placeholder content
+ * @param {"spinner" | "skeleton"} [props.loadingVariant="spinner"] - Loading display style; "spinner" shows a single spinner row, "skeleton" renders skeletonRowCount pulsing skeleton rows using meta.skeleton per column when defined, falling back to a default Placeholder block
+ * @param {number} [props.skeletonRowCount=10] - Number of skeleton rows to render when loadingVariant="skeleton"
  * @param {ReactNode} [props.noData] - Content to display when no data is available
  * @param {PaginationBarProps} [props.pagination] - Pagination configuration
  * @param {{ value: string; isTop: boolean }[]} [props.pinGroup] - Group pinning configuration
- * @param {ColumnSort[]} [props.sorting] - Initial sort configuration
- * @param {Dispatch<SetStateAction<SortingState>>} [props.setSorting] - Sorting state setter
- * @param {SelectionProps} [props.selection] - Selection configuration
- * @param {((row: Row<T>) => boolean)} [props.selection.filterSelectable] - Function to filter which rows should be selectable
- * @param {string | ((row: Row<T>) => string)} [props.selection.disabledSelectionTooltip] - Tooltip message or constructor on disabled checkboxes
- * @param {RowSelectionState} [props.selection.rowSelection] - Selected rows state
- * @param {keyof T} [props.selection.rowSelectionLabelKey] - Key of T to use as aria-labels for row checkboxes (e.g. "select {keyof T}")
- * @param {Dispatch<SetStateAction<RowSelectionState>>} [props.selection.setRowSelection] - Selection state setter
+ * @param {ColumnSort[]} [props.sorting] - Controlled sort state; changes to this prop are synced into the table after mount
+ * @param {Dispatch<SetStateAction<SortingState>>} [props.setSorting] - Sorting state setter called on user interaction
+ * @param {SelectionProps} [props.selection] - Row selection configuration. See {@link SelectionProps} for all sub-options
+ *   (filterSelectable, disabledSelectionTooltip, rowSelection, rowSelectionLabelKey, setRowSelection).
  * @param {boolean} [props.showChevron=false] - Show group row expansion state chevrons
  * @param {"full-height" | "regular"} [props.variant="full-height"] - Table layout variant
  *
@@ -71,23 +62,23 @@ type GenericTableProps<T extends {
  *
  * @example
  * <GenericTable
+ *   aria-label="Products"
  *   columns={columns}
  *   data={products}
  *   isLoading={isLoading}
- *   canSelect={true}
  *   groupBy={["category"]}
- *   rowSelection={selectedRows}
- *   setRowSelection={setSelectedRows}
+ *   selection={{
+ *     rowSelection: selectedRows,
+ *     setRowSelection: setSelectedRows,
+ *   }}
  *   pagination={{
  *     currentPage: page,
  *     setCurrentPage: setPage,
  *     itemsPerPage: pageSize,
  *     totalItems: totalCount,
- *     handlePageSizeChange: handlePageSizeChange
+ *     handlePageSizeChange: handlePageSizeChange,
  *   }}
  * />
  */
-export declare const GenericTable: <T extends {
-    id: number | string;
-} & Record<string, unknown>>({ className, columns: initialColumns, containerRef, data: initialData, filterCells, filterHeaders, getSubRows, groupBy, isLoading, noData, pagination, pinGroup, sorting, selection, setSorting, showChevron, variant, ...props }: GenericTableProps<T>) => ReactElement;
+export declare const GenericTable: <T extends GenericTableData>({ "aria-label": tableAriaLabel, className, columns: initialColumns, containerRef, data: initialData, filterCells, filterHeaders, getSubRows, groupBy, isLoading, loadingVariant, skeletonRowCount, noData, pagination, pinGroup, sorting: externalSorting, selection, setSorting: setExternalSorting, showChevron, variant, ...divProps }: GenericTableProps<T>) => ReactElement;
 export {};

package/dist/src/lib/components/GenericTable/GenericTable.stories.d.ts

@@ -14,6 +14,8 @@ export default meta;
 type Story = StoryObj<typeof GenericTable<Machine>>;
 export declare const Default: Story;
 export declare const Loading: Story;
+export declare const LoadingDefaultSkeleton: Story;
+export declare const LoadingCustomSkeleton: Story;
 export declare const Empty: Story;
 export declare const Selectable: Story;
 export declare const ConditionallySelectable: Story;

package/dist/src/lib/components/GenericTable/{PaginationBar → components/PaginationBar}/ControlsBar/ControlsBar.d.ts

@@ -1,6 +1,9 @@
 import { PropsWithChildren, ReactElement } from 'react';
+type ControlsBarProps = PropsWithChildren<{
+    "aria-label"?: string;
+}>;
 declare const ControlsBar: {
-    ({ children }: PropsWithChildren<object>): ReactElement;
+    ({ children, "aria-label": ariaLabel, }: ControlsBarProps): ReactElement;
     Left: ({ children }: PropsWithChildren<object>) => import("react/jsx-runtime").JSX.Element;
     Right: ({ children }: PropsWithChildren<object>) => import("react/jsx-runtime").JSX.Element;
 };

package/dist/src/lib/components/GenericTable/hooks/useTableExpansion.d.ts

@@ -0,0 +1,9 @@
+import { ExpandedState, GroupingState } from '@tanstack/react-table';
+import { GenericTableData } from '../types';
+export declare const useTableExpansion: <T extends GenericTableData>({ grouping, initialData, }: {
+    grouping: GroupingState;
+    initialData: T[];
+}) => {
+    expanded: ExpandedState;
+    setExpanded: (updater: ExpandedState | ((prev: ExpandedState) => ExpandedState)) => void;
+};

package/dist/src/lib/components/GenericTable/hooks/useTableGrouping.d.ts

@@ -0,0 +1,11 @@
+import { Dispatch, SetStateAction } from 'react';
+import { GroupingState } from '@tanstack/react-table';
+import { GenericTableData } from '../types';
+export declare const useTableGrouping: <T extends GenericTableData>({ groupBy, initialData, }: {
+    groupBy: string[] | undefined;
+    initialData: T[];
+}) => {
+    grouping: GroupingState;
+    setGrouping: Dispatch<SetStateAction<GroupingState>>;
+    groupedData: T[];
+};

package/dist/src/lib/components/GenericTable/hooks/useTableKeyboardNavigation.d.ts

@@ -0,0 +1,8 @@
+import { RefObject, KeyboardEvent, FocusEvent } from 'react';
+export declare const useTableKeyboardNavigation: ({ isLoading, }: {
+    isLoading: boolean;
+}) => {
+    tableRef: RefObject<HTMLTableElement | null>;
+    handleTableFocus: (e: FocusEvent<HTMLTableElement>) => void;
+    handleTableKeyDown: (e: KeyboardEvent<HTMLTableElement>) => void;
+};

package/dist/src/lib/components/GenericTable/hooks/useTableScrollHeight.d.ts

@@ -0,0 +1,11 @@
+import { RefObject } from 'react';
+export declare const useTableScrollHeight: ({ containerRef, variant, length, isLoading, }: {
+    containerRef?: RefObject<HTMLElement | null>;
+    variant: "full-height" | "regular";
+    length: number;
+    isLoading: boolean;
+}) => {
+    tableBodyRef: RefObject<HTMLTableSectionElement | null>;
+    maxHeight: string;
+    effectiveVariant: "full-height" | "regular";
+};

package/dist/src/lib/components/GenericTable/hooks/useTableSorting.d.ts

@@ -0,0 +1,17 @@
+import { Dispatch, SetStateAction } from 'react';
+import { ColumnSort, GroupingState, SortingState } from '@tanstack/react-table';
+import { GenericTableData } from '../types';
+export declare const useTableSorting: <T extends GenericTableData>({ externalSorting, setExternalSorting, grouping, groupedData, pinGroup, }: {
+    externalSorting: ColumnSort[] | undefined;
+    setExternalSorting: Dispatch<SetStateAction<SortingState>> | undefined;
+    grouping: GroupingState;
+    groupedData: T[];
+    pinGroup: {
+        value: string;
+        isTop: boolean;
+    }[] | undefined;
+}) => {
+    sorting: SortingState;
+    setSorting: (updaterOrValue: SortingState | ((prev: SortingState) => SortingState)) => void;
+    sortedData: T[];
+};

package/dist/src/lib/components/GenericTable/index.d.ts

@@ -1 +1,2 @@
-export * from './GenericTable';
+export { GenericTable } from './GenericTable';
+export type { GenericTableData, SelectionProps } from './types';

package/dist/src/lib/components/GenericTable/types.d.ts

@@ -0,0 +1,27 @@
+import { Dispatch, ReactNode, SetStateAction } from 'react';
+import { Row, RowData, RowSelectionState } from '@tanstack/react-table';
+declare module "@tanstack/react-table" {
+    interface ColumnMeta<TData extends RowData, TValue = unknown> {
+        /** Custom loading skeleton renderer. Overrides the default shimmer for this column. */
+        skeleton?: () => ReactNode;
+        /** Returns an aria-label for a data cell. Use for icon-only, stacked, or badge cells. */
+        cellAriaLabel?: (row: Row<TData>) => string;
+        /** Set true when the header contains an interactive element to skip the sort-button wrapper. */
+        isInteractiveHeader?: boolean;
+        /** aria-label for the <th> — use for non-text headers such as checkboxes. */
+        headerAriaLabel?: string;
+        /** Set true to hide the header cell from assistive technology. */
+        headerAriaHidden?: boolean;
+    }
+}
+/** Base constraint for all GenericTable row data: must have an `id` and be string-indexable. */
+export type GenericTableData = {
+    id: number | string;
+} & Record<string, unknown>;
+export type SelectionProps<T extends GenericTableData> = {
+    filterSelectable?: (row: Row<T>) => boolean;
+    disabledSelectionTooltip?: string | ((row: Row<T>) => string);
+    rowSelectionLabelKey?: keyof T;
+    rowSelection?: RowSelectionState;
+    setRowSelection?: Dispatch<SetStateAction<RowSelectionState>>;
+};

package/dist/src/lib/components/GenericTable/utils/processColumnDefs.d.ts

@@ -0,0 +1,11 @@
+import { ColumnDef } from '@tanstack/react-table';
+import { SelectionProps, GenericTableData } from '../types';
+export declare const processColumnDefs: <T extends GenericTableData>({ canSelect, initialColumns, isLoading, groupBy, getSubRows, selection, showChevron, }: {
+    canSelect: boolean;
+    initialColumns: ColumnDef<T, Partial<T>>[];
+    isLoading: boolean;
+    groupBy: string[] | undefined;
+    getSubRows?: (originalRow: T, index: number) => T[] | undefined;
+    selection?: SelectionProps<T>;
+    showChevron: boolean;
+}) => ColumnDef<T, Partial<T>>[];

package/dist/src/lib/components/GenericTable/utils/renderDataRows.d.ts

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+import { Column, ColumnDef, Row, Table } from '@tanstack/react-table';
+import { SelectionProps, GenericTableData } from '../types';
+export declare const renderDataRows: <T extends GenericTableData>({ table, columns, filterCells, getSubRows, noData, selection, }: {
+    table: Table<T>;
+    columns: ColumnDef<T, Partial<T>>[];
+    filterCells: (row: Row<T>, column: Column<T>) => boolean;
+    getSubRows?: (originalRow: T, index: number) => T[] | undefined;
+    noData: ReactNode;
+    selection?: SelectionProps<T>;
+}) => import("react/jsx-runtime").JSX.Element | import("react/jsx-runtime").JSX.Element[];

package/dist/src/lib/components/GenericTable/utils/renderLoadingRows.d.ts

@@ -0,0 +1,9 @@
+import { ColumnDef, Header, Table } from '@tanstack/react-table';
+import { GenericTableData } from '../types';
+export declare const renderLoadingRows: <T extends GenericTableData>({ table, columns, filterHeaders, loadingVariant, skeletonRowCount, }: {
+    table: Table<T>;
+    columns: ColumnDef<T, Partial<T>>[];
+    filterHeaders: (header: Header<T, unknown>) => boolean;
+    loadingVariant?: "skeleton" | "spinner";
+    skeletonRowCount: number;
+}) => import("react/jsx-runtime").JSX.Element | import("react/jsx-runtime").JSX.Element[];

package/dist/src/lib/components/Pagination/Pagination.d.ts

@@ -1,5 +1,5 @@
-import { ChangeEvent } from 'react';
-export interface PaginationProps extends React.AriaAttributes {
+import { AriaAttributes, ChangeEvent, FC } from 'react';
+export interface PaginationProps extends AriaAttributes {
     className?: string;
     currentPage: number | undefined;
     error?: string;
@@ -10,11 +10,11 @@ export interface PaginationProps extends React.AriaAttributes {
     onPreviousClick: () => void;
     totalPages: number;
 }
-export declare const Pagination: React.FC<PaginationProps>;
+export declare const Pagination: FC<PaginationProps>;
 export interface PaginationContainerProps {
     currentPage: PaginationProps["currentPage"];
     disabled: PaginationProps["disabled"];
     paginate: (page: number) => void;
     totalPages: PaginationProps["totalPages"];
 }
-export declare const PaginationContainer: React.FC<PaginationContainerProps>;
+export declare const PaginationContainer: FC<PaginationContainerProps>;

package/dist/src/lib/elements/Placeholder/Placeholder.d.ts

@@ -1,12 +1,42 @@
-import { ReactNode } from 'react';
-export type PlaceholderProps = {
+import { CSSProperties, HTMLAttributes, ReactElement, ReactNode } from 'react';
+type PlaceholderProps = {
     className?: string;
+    width?: CSSProperties["width"];
+    height?: CSSProperties["height"];
+    /** @deprecated */
     isPending?: boolean;
-} & ({
-    text?: never;
-    children?: ReactNode;
-} | {
+    /** @deprecated */
     text?: string;
-    children?: never;
-});
-export declare const Placeholder: ({ text, children, className, isPending, }: PlaceholderProps) => import("react/jsx-runtime").JSX.Element;
+    /** @deprecated */
+    children?: ReactNode;
+    variant?: "block" | "text";
+} & Omit<HTMLAttributes<HTMLDivElement>, "children">;
+/**
+ * Placeholder - A pulsing skeleton block used to represent loading content
+ *
+ * Renders a rectangular block with a pulse animation that matches the dimensions
+ * of the content it is replacing. Use `width` and `height` to control the size
+ * explicitly, or rely on the default block layout for full-width skeletons.
+ *
+ * @param {Object} props - Component props
+ * @param {string} [props.className] - Additional CSS class names applied to the root element
+ * @param {CSSProperties["width"]} [props.width] - Width of the skeleton block; accepts any valid CSS value (e.g. "200px", "100%", "12rem"). When omitted the block stretches to fill its container
+ * @param {CSSProperties["height"]} [props.height] - Height of the skeleton block; accepts any valid CSS value (e.g. "1rem", "48px", "3em"). When omitted the block collapses unless content or a sizer provides height
+ * @param {"block" | "text"} [props.variant="text"] - Rendering variant. `"block"` renders a standalone skeleton div; `"text"` is the legacy variant that requires `isPending` to be set
+ * @param {HTMLAttributes<HTMLDivElement>} [props.style] - Any HTML div attributes (e.g. `style`, `data-*`, `aria-*`) are forwarded to the root element. `style` is merged with the component's internal width/height styles, with consumer values taking precedence
+ * @param {boolean} [props.isPending] - @deprecated Use conditional rendering at the call-site instead. When `true` the skeleton is shown; when `false` the `children` are rendered. Will be removed in a future major version
+ * @param {string} [props.text] - @deprecated Width is now controlled via the `width` prop. When provided the text is rendered in a visually-hidden sizer span that gives the block its natural content width. Will be removed in a future major version
+ * @param {ReactNode} [props.children] - @deprecated Pass children outside the Placeholder and control visibility at the call-site. Will be removed in a future major version
+ *
+ * @returns {ReactElement} The rendered skeleton block, or the children when `isPending` is `false`
+ *
+ * @example
+ * // Standalone skeleton block
+ * <Placeholder width="200px" height="1rem" />
+ *
+ * @example
+ * // Composed loading state
+ * {isLoading ? <Placeholder width="100%" height="1.5rem" /> : <p>{content}</p>}
+ */
+export declare const Placeholder: ({ className, width, height, isPending, text, children, variant, style, ...divProps }: PlaceholderProps) => ReactElement;
+export {};

package/dist/src/lib/elements/Placeholder/Placeholder.stories.d.ts

@@ -2,5 +2,10 @@ import { Meta, StoryObj } from '@storybook/react';
 import { Placeholder } from './Placeholder';
 declare const meta: Meta<typeof Placeholder>;
 export default meta;
-export declare const TextExample: StoryObj<typeof Placeholder>;
-export declare const ComponentExample: StoryObj<typeof Placeholder>;
+type Story = StoryObj<typeof Placeholder>;
+export declare const TextLine: Story;
+export declare const Paragraph: Story;
+export declare const Block: Story;
+export declare const Complex: Story;
+export declare const LegacyTextProp: Story;
+export declare const LegacyChildrenProp: Story;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@canonical/maas-react-components",
   "description": "React components for use in MAAS UI projects.",
-  "version": "2.0.4",
+  "version": "2.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/canonical/maas-react-components.git"