@k8slens/lds 0.57.0 → 0.58.0

package/README.md

@@ -1,51 +1,56 @@
-# Lens Design System – Core React Component Library
+# @k8slens/lds
 
-## Documentation
-Browse the documentation at [lens-design-system.k8slens.dev](https://lens-design-system.k8slens.dev/?path=/docs/core).
+Core React component library for the Lens Design System.
+
+## Installation
 
-## What is included?
+```bash
+npm install @k8slens/lds @k8slens/lds-tokens
+```
 
-### ES Modules
-- `./lib/es/index.js` - Main ES module
-- `./lib/es/index.electron.js` - Main ES module for Electron
-- `./lib/es/ComponentName/ComponentName.js` - Individual ES modules
+## Setup
 
-### CommonJS modules
-- `./lib/cjs/index.js` - Main CommonJS module
-- `./lib/cjs/ComponentName/ComponentName.js` - Individual CommonJS modules
+Import required styles in your app entry point:
 
-### AMD package
-- `./lib/web/[version-number]/index.css` - Static CSS for web
-- `./lib/web/[version-number]/index.js` - AMD package for RequireJS. Requires external `react` import.
+```tsx
+// Fonts (required)
+import "@k8slens/lds-tokens/lib/electron/font-face.css";
 
-## Usage with React apps
-- run `npm i -s @k8slens/lds @k8slens/lds-tokens`
-- import `@k8slens/lds-tokens/lib/web/font-imports.css` in your React app to include fonts
-- import `@k8slens/lds/index.css` in your React app to include general styles
-- import `@k8slens/lds/typography.css` in your React app (after index.css) to include base typographic styles
-- Use in a component:
+// Tokens (required)
+import "@k8slens/lds-tokens/lib/web/tokens.core.css";
+import "@k8slens/lds-tokens/lib/web/tokens.dark.css"; // or tokens.light.css
 
-```js
-import { Button } from "@k8slens/lds";
+// Component styles (required)
+import "@k8slens/lds/lib/es/index.css";
 
-export const Component = () => (
-  <Button label="My Button" />
-);
+// Optional: Base typography styles
+import "@k8slens/lds/lib/es/typography.css";
 ```
 
-## Usage with Electron React apps
-- run `npm i -s @k8slens/lds @k8slens/lds-tokens`
-- import `@k8slens/lds-tokens/lib/electron/fonts.css` in your React Electron app to include fonts
-- import `@k8slens/lds/index.css` in your React Electron app to include general styles
-- Use in a component:
+## Usage
 
-```js
-import { Button } from "@k8slens/lds";
+```tsx
+import { Button, Input, Modal, Select } from "@k8slens/lds";
 
-export const Component = () => (
-  <Button label="My Button" />
-);
+export const MyComponent = () => <Button label="Click me" type="primary" />;
 ```
 
-## Usage on web
-TBD
+## Documentation
+
+Browse components and examples at [lens-design-system.k8slens.dev](https://lens-design-system.k8slens.dev/?path=/docs/core).
+
+## AI Assistance
+
+This package includes an `llms.txt` file with API documentation optimized for LLMs. Add to your project's AI configuration (e.g., `AGENTS.md` or `CLAUDE.md`):
+
+```markdown
+Read node_modules/@k8slens/lds/llms.txt for component API reference.
+Read node_modules/@k8slens/lds-tokens/llms.txt for design tokens reference.
+
+Always use LDS components and tokens instead of custom implementations:
+
+- Use Button, Input, Modal, Select etc. from @k8slens/lds
+- Use CSS variables from @k8slens/lds-tokens for colors, spacing, radius
+- Never hardcode values that exist as tokens
+- Search llms.txt files before creating custom components or styles.
+```

package/lib/cjs/Avatar/Avatar.d.ts

@@ -19,7 +19,12 @@ export interface AvatarProps extends Pick<HTMLAttributes<HTMLDivElement>, "aria-
     size?: "sm" | "md" | "xl";
 }
 /**
- * Avatar component to display user's profile picture or initials.
- * If no image is provided, initials will be displayed with a random background color.
+ * Displays user's profile picture or initials with random background color.
+ *
+ * Usage: `import { Avatar } from "@k8slens/lds"`
+ *
+ * ```tsx
+ * <Avatar name="John Doe" image="avatar.jpg" />
+ * ```
  */
 export default function Avatar({ name, className, image: AvatarImage, size, ...props }: AvatarProps): React.JSX.Element;

package/lib/cjs/Badge/Badge.d.ts

@@ -14,4 +14,13 @@ export interface BadgeProps extends Pick<HTMLAttributes<HTMLSpanElement>, "id" |
      */
     size?: "sm" | "md" | "lg";
 }
+/**
+ * A small status indicator dot. Use `type` prop for semantic colors.
+ *
+ * Usage: `import { Badge } from "@k8slens/lds"`
+ *
+ * ```tsx
+ * <Badge type="success" title="Active" />
+ * ```
+ */
 export default function Badge({ className, type, size, title, ...props }: BadgeProps): React.JSX.Element;

package/lib/cjs/Checkbox/Checkbox.d.ts

@@ -4,4 +4,13 @@ export interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputE
     onChange(value: boolean, evt: React.ChangeEvent<HTMLInputElement>): void;
     disabled?: boolean;
 }
+/**
+ * A styled checkbox input with checkmark icon.
+ *
+ * Usage: `import { Checkbox } from "@k8slens/lds"`
+ *
+ * ```tsx
+ * <Checkbox value={checked} onChange={setChecked} />
+ * ```
+ */
 export default function Checkbox({ disabled, value, onChange, className, ...inputProps }: CheckboxProps): React.JSX.Element;

package/lib/cjs/ConfirmDialog/ConfirmDialog.d.ts

@@ -13,7 +13,19 @@ export declare type ConfirmDialogProps = {
     handleCancel: () => void;
 };
 /**
- * ConfirmDialog is a modal dialog that asks the user to confirm an action.
+ * A modal dialog that asks the user to confirm an action. Use with `useConfirmDialog` hook.
+ *
+ * Usage: `import { useConfirmDialog } from "@k8slens/lds"`
+ *
+ * ```tsx
+ * const { ConfirmDialog, confirm } = useConfirmDialog();
+ * return (
+ *   <>
+ *     <Button onClick={() => confirm("Delete?", "This cannot be undone.")} />
+ *     {ConfirmDialog}
+ *   </>
+ * );
+ * ```
  */
 declare const ConfirmDialog: ({ title, message, confirmText, cancelLabel, confirmButtonProps, cancelButtonProps, handleClose, handleConfirm, handleCancel, }: ConfirmDialogProps) => React.JSX.Element;
 declare type ConfirmDialogConfig = Omit<ConfirmDialogProps, "title" | "message" | "handleClose" | "handleConfirm" | "handleCancel">;

package/lib/cjs/LinkButton/LinkButton.d.ts

@@ -14,6 +14,15 @@ export interface LinkButtonProps extends Omit<AnchorHTMLAttributes<HTMLAnchorEle
      */
     onClick?: AnchorHTMLAttributes<HTMLAnchorElement>["onClick"];
 }
+/**
+ * A text link with arrow icon for navigation actions.
+ *
+ * Usage: `import { LinkButton } from "@k8slens/lds"`
+ *
+ * ```tsx
+ * <LinkButton label="Learn more" href="/docs" />
+ * ```
+ */
 declare const LinkButton: React.ForwardRefExoticComponent<LinkButtonProps & {
     children?: React.ReactNode;
 } & React.RefAttributes<HTMLAnchorElement>>;

package/lib/cjs/Lozenge/Lozenge.d.ts

@@ -15,5 +15,14 @@ export interface LozengeProps extends Omit<HTMLAttributes<HTMLSpanElement>, "typ
      */
     size?: "sm" | "md" | "lg";
 }
+/**
+ * A pill-shaped label for status or category display.
+ *
+ * Usage: `import { Lozenge } from "@k8slens/lds"`
+ *
+ * ```tsx
+ * <Lozenge type="success">Active</Lozenge>
+ * ```
+ */
 declare const Lozenge: React.ForwardRefExoticComponent<LozengeProps & React.RefAttributes<HTMLSpanElement>>;
 export default Lozenge;

package/lib/cjs/Notification/Notification.d.ts

@@ -19,5 +19,14 @@ export interface NotificationProps {
     onClose?(): void;
     className?: string;
 }
+/**
+ * Alert banner for user feedback. Set `type` to control behavior: `flash` auto-dismisses, `closable` shows close button.
+ *
+ * Usage: `import { Notification } from "@k8slens/lds"`
+ *
+ * ```tsx
+ * <Notification level="success" message="Saved successfully" />
+ * ```
+ */
 declare const Notification: React.FC<NotificationProps>;
 export default Notification;

package/lib/cjs/NumberBadge/NumberBadge.d.ts

@@ -31,5 +31,14 @@ interface Props extends BaseNumberBadgeProps {
     role: Exclude<AriaRole, "status">;
 }
 export declare type NumberBadgeProps = StatusNumberBadgeProps | Props;
+/**
+ * A numeric badge that formats large numbers (1500 → "1.5k"). Returns null if value is 0 unless `showZero` is set.
+ *
+ * Usage: `import { NumberBadge } from "@k8slens/lds"`
+ *
+ * ```tsx
+ * <NumberBadge value={42} title="Items" />
+ * ```
+ */
 export default function NumberBadge({ className, value, showZero, displayPlusSign, title, ...props }: NumberBadgeProps): React.JSX.Element | null;
 export {};

package/lib/cjs/ProfileBlock/ProfileBlock.d.ts

@@ -12,5 +12,14 @@ export declare type ProfileBlockProps = HTMLProps<HTMLDivElement> & {
     formatTitle?: (item: Item) => string | ReactElement;
     formatSubtitle?: (item: Item) => string | ReactElement;
 };
+/**
+ * Displays user info with avatar, title, and subtitle. Supports loading state.
+ *
+ * Usage: `import { ProfileBlock } from "@k8slens/lds"`
+ *
+ * ```tsx
+ * <ProfileBlock item={{ title: "@user", subtitle: "Name", avatarTitle: "Name" }} />
+ * ```
+ */
 declare const ProfileBlock: ({ className, loading, item, formatTitle, formatSubtitle, ...props }: ProfileBlockProps) => React.JSX.Element;
 export default ProfileBlock;

package/lib/cjs/ProgressBar/ProgressBar.d.ts

@@ -5,4 +5,13 @@ export interface ProgressBarProps extends React.ProgressHTMLAttributes<HTMLProgr
     type?: "default" | "ok" | "caution" | "danger";
     title?: string;
 }
+/**
+ * A progress bar with semantic color types. Value can be 0-1 or use custom `max`.
+ *
+ * Usage: `import { ProgressBar } from "@k8slens/lds"`
+ *
+ * ```tsx
+ * <ProgressBar value={0.75} type="ok" />
+ * ```
+ */
 export default function ProgressBar({ value, type, max, title, className, ...props }: ProgressBarProps): React.JSX.Element;

package/lib/cjs/Switch/Switch.d.ts

@@ -3,4 +3,13 @@ import React from "react";
 export interface SwitchProps extends Omit<HTMLProps<HTMLInputElement>, "onChange"> {
     onChange?: (checked: boolean, event: ChangeEvent<HTMLInputElement>) => void;
 }
+/**
+ * A toggle switch input with label support.
+ *
+ * Usage: `import { Switch } from "@k8slens/lds"`
+ *
+ * ```tsx
+ * <Switch checked={enabled} onChange={setEnabled}>Enable feature</Switch>
+ * ```
+ */
 export declare function Switch({ className, children, disabled, onChange, ...props }: SwitchProps): React.JSX.Element;

package/lib/cjs/Table/Table.d.ts

@@ -0,0 +1,111 @@
+import React, { HTMLAttributes, ReactNode, TdHTMLAttributes, ThHTMLAttributes } from "react";
+/** Props for the Table component. */
+export declare type TableProps = HTMLAttributes<HTMLTableElement> & {
+    /**
+     * Whether the table uses responsive layout on mobile viewports.
+     * @default true
+     */
+    responsive?: boolean;
+    /**
+     * Whether the table renders with inner row borders.
+     * @default false
+     */
+    bordered?: boolean;
+};
+/** Props for the TableCaption component. */
+export declare type TableCaptionProps = HTMLAttributes<HTMLTableCaptionElement> & {
+    /**
+     * Controls caption visibility: "visible" renders normally, "sr-only" is screen-reader only, "hidden" hides completely.
+     * @default "sr-only"
+     */
+    visibility?: "visible" | "sr-only" | "hidden";
+};
+export declare const TableCaption: ({ visibility, className, children, ...props }: TableCaptionProps) => React.JSX.Element;
+/** Props for the TableHead component. */
+export declare type TableHeadProps = HTMLAttributes<HTMLTableSectionElement>;
+export declare const TableHead: ({ children, ...props }: TableHeadProps) => React.JSX.Element;
+/** Props for the TableBody component. */
+export declare type TableBodyProps = HTMLAttributes<HTMLTableSectionElement> & {
+    /**
+     * Whether the table body is in a loading state.
+     * @default false
+     */
+    loading?: boolean;
+};
+export declare const TableBody: ({ loading, children, ...props }: TableBodyProps) => React.JSX.Element;
+/** Props for the TableRow component. */
+export declare type TableRowProps = HTMLAttributes<HTMLTableRowElement> & {
+    /**
+     * Whether the row displays an error flash animation.
+     * @default false
+     */
+    error?: boolean;
+};
+export declare const TableRow: ({ error, className, children, ...props }: TableRowProps) => React.JSX.Element;
+/** Props for the TableHeaderCell component. */
+export declare type TableHeaderCellProps = Omit<ThHTMLAttributes<HTMLTableCellElement>, "align"> & {
+    /** Horizontal alignment of header content. */
+    align?: "start" | "center" | "end";
+    /**
+     * Whether the column is sortable.
+     * @default false
+     */
+    sortable?: boolean;
+    /**
+     * Current sort direction, or false if unsorted.
+     * @default false
+     */
+    sorted?: "asc" | "desc" | false;
+};
+export declare const TableHeaderCell: ({ align, sortable, sorted, className, children, ...props }: TableHeaderCellProps) => React.JSX.Element;
+/** Props for the TableCell component. */
+export declare type TableCellProps = Omit<TdHTMLAttributes<HTMLTableCellElement>, "align"> & {
+    /**
+     * Whether this cell is the primary (row header) cell, rendered as `<th scope="row">`.
+     * @default false
+     */
+    primary?: boolean;
+    /** Horizontal alignment of cell content. */
+    align?: "start" | "center" | "end";
+    /** Text color style variant. */
+    textStyle?: "default" | "accent" | "secondary" | "tertiary" | "quarternary";
+    /** Label shown as a responsive header on mobile viewports. */
+    responsiveHeader?: ReactNode;
+};
+export declare const TableCell: ({ primary, align, textStyle, responsiveHeader, className, children, ...props }: TableCellProps) => React.JSX.Element;
+/** Props for the TableStatusRow component. */
+export declare type TableStatusRowProps = HTMLAttributes<HTMLTableRowElement> & {
+    /** Number of columns the status cell should span. */
+    colSpan: number;
+};
+export declare const TableStatusRow: ({ colSpan, children, ...props }: TableStatusRowProps) => React.JSX.Element;
+/**
+ * A composable data table with responsive layout, sorting indicators, and row states.
+ *
+ * Usage: `import Table from "@k8slens/lds/Table"`
+ *
+ * ```tsx
+ * <Table>
+ *   <Table.Head>
+ *     <Table.Row>
+ *       <Table.HeaderCell>Name</Table.HeaderCell>
+ *     </Table.Row>
+ *   </Table.Head>
+ *   <Table.Body>
+ *     <Table.Row>
+ *       <Table.Cell>Value</Table.Cell>
+ *     </Table.Row>
+ *   </Table.Body>
+ * </Table>
+ * ```
+ */
+declare const Table: (({ responsive, bordered, className, children, ...props }: TableProps) => React.JSX.Element) & {
+    Caption: ({ visibility, className, children, ...props }: TableCaptionProps) => React.JSX.Element;
+    Head: ({ children, ...props }: TableHeadProps) => React.JSX.Element;
+    Body: ({ loading, children, ...props }: TableBodyProps) => React.JSX.Element;
+    Row: ({ error, className, children, ...props }: TableRowProps) => React.JSX.Element;
+    HeaderCell: ({ align, sortable, sorted, className, children, ...props }: TableHeaderCellProps) => React.JSX.Element;
+    Cell: ({ primary, align, textStyle, responsiveHeader, className, children, ...props }: TableCellProps) => React.JSX.Element;
+    StatusRow: ({ colSpan, children, ...props }: TableStatusRowProps) => React.JSX.Element;
+};
+export default Table;

package/lib/cjs/Table/Table.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("../_virtual/_tslib.js"),a=require("react"),t=require("clsx"),r=require("@k8slens/lds-icons"),l=require("./Table.module.css.js");function n(e){return e&&"object"==typeof e&&"default"in e?e:{default:e}}var s=n(a),i=n(t),d=r.navigation.ArrowUpIcon,o=r.navigation.ArrowDownIcon,c=a.createContext({responsive:!0}),u=function(a){var t=a.visibility,r=void 0===t?"sr-only":t,n=a.className,d=a.children,o=e.__rest(a,["visibility","className","children"]);return s.default.createElement("caption",e.__assign({},o,{className:i.default(l.caption,n,{"lds-only-aria":"sr-only"===r}),hidden:"hidden"===r||void 0}),d)},v=function(a){var t=a.children,r=e.__rest(a,["children"]);return s.default.createElement("thead",e.__assign({},r),t)},f=function(a){var t=a.loading,r=void 0!==t&&t,l=a.children,n=e.__rest(a,["loading","children"]);return s.default.createElement("tbody",e.__assign({},n,{"aria-busy":r||void 0}),l)},m=function(a){var t,r=a.error,n=void 0!==r&&r,d=a.className,o=a.children,c=e.__rest(a,["error","className","children"]);return s.default.createElement("tr",e.__assign({},c,{className:i.default(l.row,d,(t={},t[l.rowError]=n,t))}),o)},_=function(a){var t,r,n,c=a.align,u=a.sortable,v=void 0!==u&&u,f=a.sorted,m=void 0!==f&&f,_=a.className,p=a.children,b=e.__rest(a,["align","sortable","sorted","className","children"]),h="center"===c?l.center:"end"===c?l.end:void 0;return s.default.createElement("th",e.__assign({},b,{scope:null!==(n=b.scope)&&void 0!==n?n:"col","aria-sort":"asc"===m?"ascending":"desc"===m?"descending":void 0,className:i.default(l.tableHeader,_,h,(t={},t[l.sortable]=v,t))}),s.default.createElement("span",null,p,v&&("asc"===m?s.default.createElement(d,{className:l.sortIcon}):s.default.createElement(o,{className:i.default(l.sortIcon,(r={},r[l.inactive]=!m,r))}))))},p={accent:l.textAccent,secondary:l.textSecondary,tertiary:l.textTertiary,quarternary:l.textQuarternary,default:l.textDefault},b=function(t){var r=t.primary,n=void 0!==r&&r,d=t.align,o=t.textStyle,u=t.responsiveHeader,v=t.className,f=t.children,m=e.__rest(t,["primary","align","textStyle","responsiveHeader","className","children"]),_=a.useContext(c).responsive,b=n?"th":"td",h="center"===d?l.center:"end"===d?l.end:void 0,y=o?p[o]:void 0;return s.default.createElement(b,e.__assign({},m,n?{scope:"row"}:{},{className:i.default(l.tableCell,v,h,y)}),_&&null!=u&&s.default.createElement("div",{"aria-hidden":!0,className:l.cellHeader},u),f)},h=function(a){var t=a.colSpan,r=a.children,n=e.__rest(a,["colSpan","children"]);return s.default.createElement("tr",e.__assign({},n),s.default.createElement("td",{colSpan:t},s.default.createElement("div",{className:l.noData},r)))},y=Object.assign((function(a){var t,r=a.responsive,n=void 0===r||r,d=a.bordered,o=void 0!==d&&d,u=a.className,v=a.children,f=e.__rest(a,["responsive","bordered","className","children"]);return s.default.createElement(c.Provider,{value:{responsive:n}},s.default.createElement("table",e.__assign({},f,{className:i.default(l.table,u,(t={},t[l.bordered]=o,t[l.responsive]=n,t))}),v))}),{Caption:u,Head:v,Body:f,Row:m,HeaderCell:_,Cell:b,StatusRow:h});exports.TableBody=f,exports.TableCaption=u,exports.TableCell=b,exports.TableHead=v,exports.TableHeaderCell=_,exports.TableRow=m,exports.TableStatusRow=h,exports.default=y;

package/lib/cjs/Table/Table.module.css.js

@@ -0,0 +1 @@
+"use strict";module.exports={table:"lds-table",row:"lds-table--row",bordered:"lds-table--bordered",tableHeader:"lds-table--table-header",sortable:"lds-table--sortable",sortIcon:"lds-table--sort-icon",inactive:"lds-table--inactive",center:"lds-table--center",end:"lds-table--end",tableCell:"lds-table--table-cell",textAccent:"lds-table--text-accent",textSecondary:"lds-table--text-secondary",textTertiary:"lds-table--text-tertiary",textQuarternary:"lds-table--text-quarternary",textDefault:"lds-table--text-default",cellHeader:"lds-table--cell-header",noData:"lds-table--no-data",caption:"lds-table--caption",responsive:"lds-table--responsive",rowError:"lds-table--row-error",flashError:"lds-table--flash-error"};

package/lib/cjs/Tooltip/Tooltip.d.ts

@@ -23,4 +23,13 @@ export interface SpanTooltipProps extends Omit<HTMLAttributes<HTMLSpanElement>,
 export interface DivTooltipProps extends Omit<HTMLAttributes<HTMLDivElement>, "onFocus" | "onBlur" | "onMouseEnter" | "onMouseLeave" | "onMouseMove" | "aria-describedby">, TooltipProps {
     wrapper: "div";
 }
+/**
+ * Shows contextual information on hover/focus. Wrap any element to add a tooltip.
+ *
+ * Usage: `import { Tooltip } from "@k8slens/lds"`
+ *
+ * ```tsx
+ * <Tooltip text="Helpful info"><span>Hover me</span></Tooltip>
+ * ```
+ */
 export default function Tooltip({ id, wrapper: Wrapper, mutationsListenerElement: initialMutationsListenerElement, popupClassName, placement, alwaysVisible, text, children, ...props }: SpanTooltipProps | DivTooltipProps): React.JSX.Element;

package/lib/cjs/UserMenu/UserMenu.d.ts

@@ -50,6 +50,12 @@ export interface CustomUserMenuProps extends BaseUserMenuProps {
 }
 export declare type UserMenuProps = DefaultUserMenuProps | CustomUserMenuProps;
 /**
- * UserMenu is a component that displays a user's information and a dropdown menu of links.
+ * Displays user info with dropdown menu for account actions. Uses default menu items if `items` prop is not provided.
+ *
+ * Usage: `import { UserMenu } from "@k8slens/lds"`
+ *
+ * ```tsx
+ * <UserMenu user={{ name: "John", username: "john" }} onLogoutClick={logout} />
+ * ```
  */
 export default function UserMenu({ user, header, footer, origin, className, onLogoutClick, loading, ...props }: UserMenuProps): React.JSX.Element;

package/lib/cjs/components.d.ts

@@ -24,3 +24,4 @@ export { default as Tooltip } from "./Tooltip/Tooltip";
 export { default as UserMenu } from "./UserMenu/UserMenu";
 export { DefaultHeader as UserMenuDefaultHeader } from "./UserMenu/DefaultHeader";
 export { Switch } from "./Switch/Switch";
+export { default as Table } from "./Table/Table";