@canonical/maas-react-components 2.1.0 → 2.2.0

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

@@ -46,7 +46,7 @@ type GenericTableProps<T extends GenericTableData> = {
  * @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 shimmer rows using meta.skeleton per column when defined, falling back to a default shimmer bar
+ * @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

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.1.0",
+  "version": "2.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/canonical/maas-react-components.git"