@k8slens/lds 0.58.2 → 0.58.4

package/llms.txt

@@ -11,14 +11,6 @@ npm install @k8slens/lds
 ```
 
 ### Peer Dependencies
-
-The following peer dependencies are required:
-
-```bash
-npm install @headlessui/react @k8slens/lds-icons @popperjs/core clsx initialism randomcolor react react-dom react-popper rooks
-```
-
-Required peer dependencies:
 - `@headlessui/react` ^2.2.0
 - `@k8slens/lds-icons` *
 - `@popperjs/core` ^2.11.6
@@ -40,14 +32,6 @@ import "@k8slens/lds/lib/es/index.css";
 import "@k8slens/lds/lib/es/typography.css";
 ```
 
-## Importing Components
-
-All components are exported from the package root:
-
-```typescript
-import { Button, Input, Modal, Select, Avatar, Badge, ContextMenu, Textarea } from "@k8slens/lds";
-```
-
 ## TypeScript Types
 
 TypeScript definitions are included and exported from `lib/es/index.d.ts`. Component prop types are exported alongside components:
@@ -57,11 +41,6 @@ import { Button, ButtonProps } from "@k8slens/lds";
 import { Select, SelectProps } from "@k8slens/lds";
 ```
 
-## Module Formats
-
-- ES Modules: `lib/es/index.js` (recommended)
-- CommonJS: `lib/cjs/index.js`
-
 ## Components
 
 ### Avatar
@@ -69,61 +48,86 @@ import { Select, SelectProps } from "@k8slens/lds";
 Displays user's profile picture or initials with random background color.
 
 ```tsx
-import { Avatar } from "@k8slens/lds";
-
-<Avatar name="John Doe" image="avatar.jpg" />
+<Avatar name="John Doe" image="avatar.jpg" size="md" />
 ```
 
+**Props:**
+- `name` (required) - Full name of the user. Initials will be generated from this value and shown if no image is provided
+- `image` - URL of the image or an `Icon` component to use as the avatar
+- `size` (default: "md") - "sm", "md", or "xl"
+- `className` - Optional class name to apply to the avatar
+
 ### Badge
 
 A small status indicator dot. Use `type` prop for semantic colors.
 
 ```tsx
-import { Badge } from "@k8slens/lds";
-
 <Badge type="success" title="Active" />
 ```
 
+**Props:**
+- `title` - Accessible title. If not provided, the badge is hidden from screen readers
+- `type` (default: "secondary") - "primary", "secondary", "success", "error", or "warning"
+- `size` (default: "sm") - "sm", "md", or "lg"
+
 ### Button
 
-Accessible button with loading state and icon support.
+Accessible button with icon, loading state, and promise-based loading.
 
 ```tsx
-import { Button } from "@k8slens/lds";
-
-<Button label="Click me" type="primary" onClick={handleClick} />
+<Button label="Save" type="primary" onClick={handleSave} />
 ```
 
+**Props:**
+- `label` (required) - Text label rendered inside the button. Use `ButtonPropsWithLabelNode` when passing a ReactNode (requires explicit `aria-label`)
+- `type` (default: "default") - "default", "primary", "ok", "danger", or "caution"
+- `size` (default: "md") - "xxs", "xs", "sm", or "md"
+- `icon` - Icon component rendered alongside the label
+- `iconPosition` (default: "left") - "left" or "right"
+- `loading` (default: false) - Whether to show the loading activity indicator
+- `loadingStateOnPromise` (default: false) - Show loading indicator until onClick promise resolves
+- `disabled` (default: false) - Whether the button is disabled
+- `discreet` - Whether the button uses the discreet (low-emphasis) style
+- `textTransform` - "uppercase" or "capitalize"
+- `onClick` - Click handler, may return a promise when used with `loadingStateOnPromise`
+- `buttonType` (default: "button") - HTML `type` attribute for the button element
+- `buttonValue` - HTML `value` attribute for the button element
+- `buttonName` - HTML `name` attribute for the button element
+
 ### ButtonBar
 
-Container for button groups with layout control.
+A container for buttons. Set `type` prop to change the layout of the buttons.
 
 ```tsx
-import { ButtonBar } from "@k8slens/lds";
-
-<ButtonBar type="default">
+<ButtonBar>
   <Button label="Cancel" />
-  <Button label="Submit" type="primary" />
+  <Button label="Save" type="primary" />
 </ButtonBar>
 ```
 
+**Props:**
+- `type` (default: "default") - "default", "centered", "stacked", or "grid"
+- `as` (default: "div") - Element or component to render as the container
+- `gridSize` - Override the grid column count (only used when `type` is "grid")
+
 ### Checkbox
 
 A styled checkbox input with checkmark icon.
 
 ```tsx
-import { Checkbox } from "@k8slens/lds";
-
 <Checkbox value={checked} onChange={setChecked} />
 ```
 
+**Props:**
+- `value` (required) - Whether the checkbox is checked
+- `onChange` (required) - Change handler receiving the new value and the original event
+- `disabled` (default: false) - Whether the checkbox is disabled
+
 ### ContextMenu
 
 A dropdown context menu triggered by an icon button. Uses dot notation API for sub-components. Built with Headless UI v2 Menu for accessibility.
 
 ```tsx
-import { ContextMenu } from "@k8slens/lds";
-
 <ContextMenu>
   <ContextMenu.Item onClick={handleEdit} icon={EditIcon}>Edit</ContextMenu.Item>
   <ContextMenu.Item onClick={handleDelete} disabled>Delete</ContextMenu.Item>
@@ -152,8 +156,6 @@ import { ContextMenu } from "@k8slens/lds";
 A modal dialog that asks the user to confirm an action. Use with `useConfirmDialog` hook.
 
 ```tsx
-import { useConfirmDialog } from "@k8slens/lds";
-
 const { ConfirmDialog, confirm } = useConfirmDialog();
 return (
   <>
@@ -163,159 +165,300 @@ return (
 );
 ```
 
-### Input
+**ConfirmDialog Props (direct usage):**
+- `title` (required) - Title displayed in the confirm dialog header
+- `message` - Optional message body rendered below the title
+- `confirmText` (default: "Ok") - Label for the confirm button
+- `cancelLabel` (default: "Cancel") - Label for the cancel button
+- `confirmButtonProps` - Additional Button props forwarded to the confirm button
+- `cancelButtonProps` - Additional Button props forwarded to the cancel button
+- `handleClose` (required) - Called when the dialog is dismissed
+- `handleConfirm` (required) - Called when the user clicks the confirm button
+- `handleCancel` (required) - Called when the user clicks the cancel button
+
+### DrawerTransition
 
-A text input with optional icon.
+An animated drawer that expands and collapses content with a height transition.
 
 ```tsx
-import { Input } from "@k8slens/lds";
+<DrawerTransition open={isOpen}>
+  <p>Collapsible content here</p>
+</DrawerTransition>
+```
+
+**Props:**
+- `open` (required) - Whether the drawer is open
+- `duration` (default: 250) - Transition duration in milliseconds
+- `afterEnter` - Callback fired after the enter transition completes
+- `afterExit` - Callback fired after the exit transition completes
+- `deps` - Changes in dependencies trigger re-calculation of the drawer dimensions
+- Extends `HTMLAttributes<HTMLDivElement>`
+
+### Input
 
-<Input type="text" placeholder="Enter text..." />
+A simple input component. Set `icon` prop to show an icon on the right side of the input.
+
+```tsx
+<Input placeholder="Enter text" onChange={handleChange} />
 ```
 
+**Props:**
+- `type` - HTML input type (excludes button, checkbox, radio, number)
+- `icon` - Icon component displayed on the right side of the input
+- `wrapperProps` - Props forwarded to the wrapping `div` element
+- Extends standard HTML input attributes
+
 ### LinkButton
 
-A text link with arrow icon for navigation actions.
+A text link with arrow icon for navigation actions. Leave `href` and `onClick` undefined to disable the button.
 
 ```tsx
-import { LinkButton } from "@k8slens/lds";
-
 <LinkButton label="Learn more" href="/docs" />
 ```
 
+**Props:**
+- `label` (required) - Text label displayed in the link button
+- `size` (default: "md") - "sm" or "md"
+- `textTransform` - "uppercase" or "capitalize"
+- `href` - Navigation URL. Omit to disable the button
+- `onClick` - Click handler. Omit to disable the button
+
 ### LoadingIndicator
 
-A spinning loading indicator.
+Animated spinner for loading states. Wraps a SpinnerIcon with configurable size.
 
 ```tsx
-import { LoadingIndicator } from "@k8slens/lds";
-
-<LoadingIndicator size="xl" />
+<LoadingIndicator size="md" />
 ```
 
+**Props:**
+- `size` (default: "md") - Icon size, see SVGIcon for available values
+- `className` - Optional class name
+
 ### Lozenge
 
 A pill-shaped label for status or category display.
 
 ```tsx
-import { Lozenge } from "@k8slens/lds";
-
 <Lozenge type="success">Active</Lozenge>
 ```
 
+**Props:**
+- `type` (default: "secondary") - "primary", "secondary", "success", "error", or "warning"
+- `size` (default: "sm") - "sm", "md", or "lg"
+- `textTransform` - "uppercase" or "capitalize"
+
 ### Modal
 
-A responsive modal dialog with header, footer, and content areas.
+Responsive modal dialog extending Panel with header, footer, and size options.
 
 ```tsx
-import { Modal } from "@k8slens/lds";
-
-<Modal isOpen={isOpen} onClose={close} title="Title" footer={<Button label="Close" />}>
-  Content
+<Modal isOpen={open} onClose={close} title="Confirm" size="sm">
+  <p>Are you sure?</p>
 </Modal>
 ```
 
+**Props:**
+- `title` (required) - Title displayed in the modal header
+- `subTitle` - Optional subtitle displayed below the title
+- `isOpen` (required) - Whether the modal is currently open
+- `onClose` (required) - Called when the modal is dismissed (overlay click or escape key)
+- `size` (default: "md") - "sm", "md", "lg", or "xl"
+- `footer` - Content rendered in the modal footer, wrapped by ButtonBar
+- `contentComponent` - Element type or component used as the content wrapper (passed to Panel)
+- `contentProps` - Props forwarded to the content wrapper component
+- `buttonBarProps` (default: {}) - Props forwarded to the footer ButtonBar component
+- `className` (default: "") - Additional class name for the modal Panel
+
 ### Notification
 
-Alert banner for user feedback. `type="flash"` auto-dismisses, `type="closable"` shows close button.
+Alert banner for user feedback. Set `type` to control behavior: `flash` auto-dismisses, `closable` shows close button.
 
 ```tsx
-import { Notification } from "@k8slens/lds";
-
 <Notification level="success" message="Saved successfully" />
 ```
 
+**Props:**
+- `message` (required) - The notification body content (string or ReactNode)
+- `title` - Optional bold heading rendered above the message
+- `type` (default: "default") - "flash", "closable", "inline", or "default"
+- `level` (default: "info") - "info", "success", "error", or "warning"
+- `flashDuration` (default: 5000) - Hide after this many milliseconds if type is "flash"
+- `onClose` - Called after the notification finishes its exit transition
+- `className` - Additional class name for the notification wrapper
+
 ### NumberBadge
 
-A numeric badge that formats large numbers (1500 → "1.5k").
+A numeric badge that formats large numbers (1500 → "1.5k"). Returns null if value is 0 unless `showZero` is set.
 
 ```tsx
-import { NumberBadge } from "@k8slens/lds";
-
 <NumberBadge value={42} title="Items" />
 ```
 
+**Props:**
+- `value` (required) - Numeric value to display
+- `title` - Accessible title. If not provided, the badge is hidden from screen readers
+- `showZero` - Show badge even if value is zero
+- `displayPlusSign` (default: false) - Show a plus sign for positive values
+- `type` - Color type, inherited from Lozenge: "primary", "secondary", "success", "error", or "warning"
+
 ### Panel
 
-A container with optional header, footer, and loading state.
+Composable panel with configurable header, content, and footer sections.
 
 ```tsx
-import { Panel } from "@k8slens/lds";
-
 <Panel header={<h2>Title</h2>} loading={isLoading}>Content</Panel>
 ```
 
+**Props:**
+- `header` - Content rendered in the header section
+- `footer` - Content rendered in the footer section
+- `loading` (default: false) - Whether to show a loading indicator overlay
+- `className` - Optional class name applied to header, content, and footer elements
+- `wrapperComponent` (default: Fragment) - Component used to wrap the entire panel
+- `wrapperProps` - Props forwarded to the wrapper component
+- `headerComponent` (default: "header") - Component used for the header section
+- `headerProps` - Props forwarded to the header component
+- `contentComponent` (default: "div") - Component used for the content section
+- `contentProps` - Props forwarded to the content component
+- `footerComponent` (default: "footer") - Component used for the footer section
+- `footerProps` - Props forwarded to the footer component
+
 ### ProfileBlock
 
-Displays user info with avatar, title, and subtitle.
+Displays user info with avatar, title, and subtitle. Supports loading state.
 
 ```tsx
-import { ProfileBlock } from "@k8slens/lds";
-
 <ProfileBlock item={{ title: "@user", subtitle: "Name", avatarTitle: "Name" }} />
 ```
 
+**Props:**
+- `item` (required) - User data to display: `{ title, subtitle, avatarTitle, avatar? }`
+- `loading` (default: false) - Whether to show a loading indicator instead of text content
+- `formatTitle` - Custom formatter for the title text, receives `item` and returns string or ReactElement
+- `formatSubtitle` - Custom formatter for the subtitle text, receives `item` and returns string or ReactElement
+
 ### ProgressBar
 
 A progress bar with semantic color types. Value can be 0-1 or use custom `max`.
 
 ```tsx
-import { ProgressBar } from "@k8slens/lds";
-
 <ProgressBar value={0.75} type="ok" />
 ```
 
+**Props:**
+- `value` (required) - Current progress value
+- `max` (default: 1) - Maximum value for the progress bar
+- `type` (default: "default") - "default", "ok", "caution", or "danger"
+- `title` - Accessible title text. Falls back to percentage display if not provided
+
 ### RadioCard
 
-Styled radio button cards for option selection.
+A card-based radio group for visual option selection. Renders each option as a styled card with a radio indicator.
 
 ```tsx
-import { RadioCard } from "@k8slens/lds";
-
-<RadioCard name="choice" options={options} value={selected} onChange={setSelected} />
+<RadioCard
+  name="plan"
+  options={[{ id: "1", label: "Free" }, { id: "2", label: "Pro" }]}
+  value={selected}
+  onChange={setSelected}
+/>
 ```
 
+**Props:**
+- `name` (required) - Name attribute for the radio group
+- `options` (required) - Array of options to render as radio cards
+- `value` (required) - Currently selected option
+- `onChange` (required) - Change handler receiving the selected option
+- `renderItem` - Function to render the content of each card item (receives option and state)
+- `invalid` (default: false) - Whether the radio group is in an invalid state
+- `disabled` (default: false) - Whether the entire radio group is disabled
+- `id` - HTML `id` attribute for the radio group
+- `aria-label` - Accessible label for the radio group
+- `className` - Optional class name for the radio group container
+- `itemClassName` - Optional class name applied to each radio card item
+
 ### Select
 
-A dropdown select component with single or multiple selection.
+A dropdown select with single and multi-value modes, grouped options, custom renderers, and keyboard navigation.
 
 ```tsx
-import { Select } from "@k8slens/lds";
-
-<Select options={options} value={selected} onChange={setSelected} />
+<Select
+  options={[{ id: "1", label: "Option 1" }]}
+  value={selected}
+  onChange={setSelected}
+/>
 ```
 
+**Props:**
+- `options` (required) - List of selectable options or option groups (`Group<T>` for grouped options)
+- `value` (required) - Currently selected value(s)
+- `onChange` (required) - Called when the selected value(s) change
+- `multiple` - Set to `true` for multi selection (changes value type to array)
+- `placeholder` (default: "") - Placeholder text shown when no value is selected
+- `renderContent` - Function to render the content of the select element (receives option, state, placeholder)
+- `loading` (default: false) - Loading state of the select element
+- `openingDirection` (default: "auto") - "above", "below", or "auto"
+- `size` (default: "md") - "md" or "lg"
+- `maxHeight` - Maximum height of the dropdown in pixels
+- `disabled` - Whether the select element is disabled
+- `invalid` - Whether the select element is in an invalid state
+- `id` - HTML `id` for the select button
+- `aria-label` - Accessible label for the select element
+- `name` - HTML `name` attribute passed to the underlying Listbox
+- `title` - Tooltip of the select element
+- `className` - Additional class name for the select wrapper
+- `dropdownClassName` - Class name passed to `<Listbox.Options />`
+- `itemClassName` - Class name passed to `<Listbox.Option />` (can be a function receiving state)
+- `multiOptionClassName` - Additional class name for multi-option pills (multi-select only)
+- `buttonRef` - Ref forwarded to the select button element
+
 ### SideNav
 
-Side navigation container. Use with SideNavGroup and SideNavItem.
+Side navigation container. Use `SideNavGroup` with `SideNavItem` as direct children.
 
 ```tsx
-import { SideNav, SideNavGroup, SideNavItem } from "@k8slens/lds";
-
 <SideNav>
-  <SideNavGroup label="Section">
-    <SideNavItem href="/page1">Page 1</SideNavItem>
+  <SideNavGroup label="Settings">
+    <SideNavItem active>General</SideNavItem>
   </SideNavGroup>
 </SideNav>
 ```
 
+**SideNavGroup Props:**
+- `label` - Group label text (provide either `label` or `aria-label`)
+- `aria-label` - Accessible label when no visible label is needed
+- `component` (default: "nav") - Component to render as the container
+- `componentProps` - Props forwarded to the container component
+- `id` - HTML `id` attribute
+
+**SideNavItem Props:**
+- `component` (default: "a") - Component to render as the item (e.g. `Link` from react-router)
+- `componentProps` - Props forwarded to the item component
+- `active` (default: false) - Whether the item is currently active (sets `aria-current="page"`)
+- `disabled` (default: false) - Whether the item is disabled
+- `type` (default: "default") - "default" or "danger"
+- `externalLink` (default: false) - Renders a visual indication of an external link
+
 ### Switch
 
 A toggle switch input with label support.
 
 ```tsx
-import { Switch } from "@k8slens/lds";
-
 <Switch checked={enabled} onChange={setEnabled}>Enable feature</Switch>
 ```
 
+**Props:**
+- `checked` - Whether the switch is checked
+- `onChange` - Change handler receiving `(checked: boolean, event: ChangeEvent<HTMLInputElement>)`
+- `disabled` - Whether the switch is disabled
+- Extends `HTMLProps<HTMLInputElement>` (minus `onChange`)
+
 ### Textarea
 
 A multi-line text input with optional auto-resize and character counter. Mirrors the Input component API.
 
 ```tsx
-import { Textarea } from "@k8slens/lds";
-
 <Textarea maxLength={500} autoResize placeholder="Write something..." />
 ```
 
@@ -333,9 +476,7 @@ Uses `forwardRef` for direct textarea access.
 A composable data table with responsive layout, sorting indicators, and row states. Uses dot notation API for sub-components.
 
 ```tsx
-import { Table } from "@k8slens/lds";
-
-<Table responsive bordered={false}>
+<Table responsive>
   <Table.Caption visibility="sr-only">User data</Table.Caption>
   <Table.Head>
     <Table.Row>
@@ -343,8 +484,8 @@ import { Table } from "@k8slens/lds";
       <Table.HeaderCell align="end">Count</Table.HeaderCell>
     </Table.Row>
   </Table.Head>
-  <Table.Body loading={false}>
-    <Table.Row error={false}>
+  <Table.Body>
+    <Table.Row>
       <Table.Cell primary responsiveHeader="Name">John</Table.Cell>
       <Table.Cell align="end" textStyle="accent">42</Table.Cell>
     </Table.Row>
@@ -368,8 +509,8 @@ import { Table } from "@k8slens/lds";
 
 **TableHeaderCell Props:**
 - `align` - "start", "center", or "end"
-- `sortable` (default: false) - Indicates column is sortable
-- `sorted` (default: false) - "asc", "desc", or false. When `sortable` is true, a sort direction icon is always visible. The icon appears at reduced opacity when the column is not the active sort column. When actively sorted, the icon shows full opacity with direction (up for asc, down for desc)
+- `sortable` (default: false) - Whether the column is sortable
+- `sorted` (default: false) - "asc", "desc", or false. Current sort direction or false if unsorted
 
 **TableCell Props:**
 - `primary` (default: false) - Renders as `<th scope="row">`
@@ -383,24 +524,43 @@ import { Table } from "@k8slens/lds";
 
 ### Tooltip
 
-Shows contextual information on hover/focus.
+Shows contextual information on hover/focus. Wrap any element to add a tooltip.
 
 ```tsx
-import { Tooltip } from "@k8slens/lds";
-
 <Tooltip text="Helpful info"><span>Hover me</span></Tooltip>
 ```
 
+**Props:**
+- `text` - Content displayed inside the tooltip popup (string or ReactElement)
+- `placement` (default: "auto") - Popper placement of the tooltip popup
+- `wrapper` (default: "span") - "span" or "div" wrapper element type around the children
+- `alwaysVisible` (default: false) - Whether the tooltip is always visible (ignores hover/focus)
+- `mutationsListenerElement` (default: document.body) - Element to listen for DOM mutations on to reposition
+- `popupClassName` - Additional class name for the tooltip popup element
+- `id` - HTML `id` attribute for the wrapper element
+
 ### UserMenu
 
 Displays user info with dropdown menu for account actions. Uses default menu items if `items` prop is not provided.
 
 ```tsx
-import { UserMenu } from "@k8slens/lds";
-
 <UserMenu user={{ name: "John", username: "john" }} onLogoutClick={logout} />
 ```
 
+**Props (default items variant):**
+- `user` (required) - `{ name, username, avatar? }` - User information to display
+- `onLogoutClick` (required) - Callback when the user clicks the Logout button
+- `header` - Optional header content to display in the dropdown
+- `footer` - Optional footer content to display in the dropdown
+- `origin` (default: "https://app.k8slens.dev") - Origin for default menu item hrefs
+- `className` - Optional class name for the trigger button
+- `buttonRef` - Ref forwarded to the trigger button element
+- `loading` (default: false) - Loading state of the User Menu
+
+**Props (custom items variant):**
+- `items` (required) - Array of `MenuItemGroup` for custom menu items
+- `onLogoutClick` - Optional callback mapped to item with key "logout"
+
 ## Theming
 
 Components are styled using CSS modules with CSS custom properties from @k8slens/lds-tokens. Import the tokens CSS to enable theming:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k8slens/lds",
-  "version": "0.58.2",
+  "version": "0.58.4",
   "description": "Lens Design System – Core React Component Library",
   "author": "Mirantis Inc",
   "license": "MIT",
@@ -29,8 +29,8 @@
     "format": "oxlint --fix . && prettier --write ."
   },
   "devDependencies": {
-    "@k8slens/lds-tokens": "^0.59.2",
-    "@storybook/react": "6.5.16",
+    "@k8slens/lds-tokens": "^0.59.4",
+    "@storybook/react": "10.2.15",
     "@testing-library/react": "14.0.0",
     "@types/randomcolor": "0.5.9",
     "@types/rollup-plugin-delete": "1.0.0",
@@ -64,5 +64,5 @@
       "\\.svg": "<rootDir>/../../__mocks__/SVGStub.js"
     }
   },
-  "gitHead": "1f889df45a91e8b67494c6e5e45197639861a84f"
+  "gitHead": "4d79cf509073c250bbc49794d459230e41de28e6"
 }