@k8slens/lds 0.57.0 → 0.57.2

package/README.md

@@ -1,51 +1,55 @@
-# 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., `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/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;