@heymantle/litho 0.0.14 → 0.0.16

package/dist/cjs/components/Pane.js

@@ -125,7 +125,35 @@ function _unsupported_iterable_to_array(o, minLen) {
     if (n === "Map" || n === "Set") return Array.from(n);
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
 }
-// Reference counter for pane open state (shared across all Pane components)
+/**
+ * @component Pane
+ *
+ * @description A slide-in side panel overlay for displaying supplementary content, detail views, or multi-tab workflows alongside the main page.
+ *
+ * @usage
+ * - DO: Use for secondary content panels that slide in from the side without blocking the main page.
+ * - DON'T: Use for focused tasks requiring full attention (use Modal).
+ *
+ * @accessibility
+ * - Manages focus within the pane when open; supports keyboard dismissal via Escape key. Ensure title provides context.
+ *
+ * @alternative
+ * - If you need a blocking dialog, use `Modal`. If you need inline expandable content, use `Collapsible`.
+ *
+ * @param {Object} props - Component properties.
+ * @param {boolean} props.open - Whether the pane is open.
+ * @param {Function} [props.onClose] - Callback fired when the pane is closed.
+ * @param {Function} [props.onOpen] - Callback fired when the pane should be opened (for auto-open functionality).
+ * @param {React.ReactNode} props.children - Content to render inside the pane.
+ * @param {Object} [props.tabStorage] - Shared tab storage object for managing pane tabs.
+ * @param {Function} [props.onTabRemove] - Callback when a tab is removed, receives (tabId, tab).
+ * @param {Object} [props.onExpandRef] - Ref to expose the expand function to the parent.
+ * @param {string} [props.tabId] - Optional tab ID; if provided, will reuse an existing tab with this ID.
+ * @param {string} [props.tabTitle] - Tab title to display.
+ * @param {string} [props.tabKey] - Optional stable key for tab deduplication.
+ * @param {string} [props.orgId] - Optional organization ID to scope the pane state.
+ * @returns {JSX.Element|null} The rendered Pane component, or null if not open.
+ */ // Reference counter for pane open state (shared across all Pane components)
 var paneOpenCount = 0;
 var MIN_PANE_WIDTH = 360;
 var MAX_PANE_WIDTH = 800;
@@ -727,7 +755,21 @@ function Pane() {
         })
     });
 }
-function Header() {
+/**
+ * @component Pane.Header
+ *
+ * @usage
+ * - DO: Provide title and close action for the pane.
+ *
+ * @param {Object} props - Component properties.
+ * @param {string|React.ReactNode} [props.title] - Title text or custom element for the header.
+ * @param {string|React.ReactNode} [props.subtitle] - Subtitle text or custom element.
+ * @param {Array<Object>} [props.actions=[]] - Array of action button configurations.
+ * @param {boolean} [props.bottomBorder=true] - Whether to show a bottom border.
+ * @param {React.ReactNode} [props.subHeader] - Additional content rendered below the header row.
+ * @param {Object} [props.backAction] - Back navigation action with onAction callback and accessibilityLabel.
+ * @returns {JSX.Element} The rendered Pane.Header component.
+ */ function Header() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var title = props.title, subtitle = props.subtitle, _props_actions = props.actions, actions = _props_actions === void 0 ? [] : _props_actions, _props_bottomBorder = props.bottomBorder, bottomBorder = _props_bottomBorder === void 0 ? true : _props_bottomBorder, subHeader = props.subHeader, tmp = props.backAction, _backAction = tmp === void 0 ? null : tmp;
     var _useState = _sliced_to_array((0, _react.useState)(null), 2), showActionsPopover = _useState[0], setShowActionsPopover = _useState[1];
@@ -819,7 +861,18 @@ function Header() {
     });
 }
 Pane.Header = Header;
-function Content() {
+/**
+ * @component Pane.Content
+ *
+ * @usage
+ * - DO: Wrap scrollable content within the pane.
+ *
+ * @param {Object} props - Component properties.
+ * @param {React.ReactNode} props.children - Content to render inside the pane body.
+ * @param {boolean} [props.padded=true] - Whether to apply padding to the content area.
+ * @param {string} [props.className] - Additional CSS class names.
+ * @returns {JSX.Element} The rendered Pane.Content component.
+ */ function Content() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var children = props.children, _props_padded = props.padded, padded = _props_padded === void 0 ? true : _props_padded, className = props.className;
     return /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
@@ -828,7 +881,17 @@ function Content() {
     });
 }
 Pane.Content = Content;
-function Footer() {
+/**
+ * @component Pane.Footer
+ *
+ * @usage
+ * - DO: Place action buttons at the bottom of the pane.
+ *
+ * @param {Object} props - Component properties.
+ * @param {React.ReactNode} props.children - Content to render inside the footer.
+ * @param {boolean} [props.topBorder=true] - Whether to show a top border.
+ * @returns {JSX.Element} The rendered Pane.Footer component.
+ */ function Footer() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var children = props.children, _props_topBorder = props.topBorder, topBorder = _props_topBorder === void 0 ? true : _props_topBorder;
     var isMobile = (0, _useMobile.useMobile)(MOBILE_BREAKPOINT);

package/dist/cjs/components/Popover.js

@@ -158,24 +158,21 @@ function _unsupported_iterable_to_array(o, minLen) {
     if (n === "Map" || n === "Set") return Array.from(n);
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
 }
-var TOP_SPACING = 4;
-var EDGE_SPACING = 16;
-var styles = (0, _tailwindvariants.tv)({
-    base: "Litho-Popover bg-surface-highest rounded-sm max-h-100 overflow-y-auto overflow-x-hidden shadow-popover dark:shadow-popover-dark outline outline-tint-3 min-w-32  overscroll-contain dark:outline-hidden dark:border-t dark:border-tint-alt-2",
-    variants: {
-        maxWidth: {
-            default: "max-w-80",
-            datePicker: "max-w-75 @sm:max-w-full",
-            none: ""
-        },
-        sectioned: {
-            true: "Litho-Popover--Sectioned p-4",
-            false: ""
-        }
-    }
-});
 /**
- * Popover component for displaying an overlay near an activator.
+ * @component Popover
+ *
+ * @description An anchored floating panel that displays interactive content like menus, forms, or action lists when triggered.
+ *
+ * @usage
+ * - DO: Display interactive content (menus, forms, pickers) anchored to a trigger.
+ * - DON'T: Use for simple text hints (use Tooltip).
+ *
+ * @accessibility
+ * - Manages focus trap and keyboard dismissal (Escape key); ensure the trigger has `aria-expanded` and `aria-haspopup`.
+ *
+ * @alternative
+ * - If you need non-interactive supplementary text, use `Tooltip`.
+ * - If you need a full dialog, use `Modal`.
  *
  * @param {Object} props - The component props.
  * @param {string|React.ComponentType} [props.activatorWrapper="div"] - The wrapper element for the activator.
@@ -189,18 +186,39 @@ var styles = (0, _tailwindvariants.tv)({
  * @param {boolean} [props.sectioned=false] - Whether the popover content is sectioned with padding.
  * @param {string} [props.preferredAlignment="center"] - Preferred alignment for the popover (left, center, right).
  * @param {string} [props.preferredPosition="below"] - Preferred position for the popover (above, below, cover, left, right).
+ * @param {number} [props.horizontalOffset] - Custom horizontal offset in pixels to adjust the popover position.
  * @param {string} [props.className] - Additional class name for the popover.
  * @param {string} [props.containerClassName] - Additional class name for the popover container.
  * @returns {JSX.Element} The rendered popover component.
- */ function Popover() {
+ */ var TOP_SPACING = 4;
+var EDGE_SPACING = 16;
+var styles = (0, _tailwindvariants.tv)({
+    base: "Litho-Popover bg-surface-highest rounded-sm max-h-100 overflow-y-auto overflow-x-hidden shadow-popover dark:shadow-popover-dark outline outline-tint-3 min-w-32  overscroll-contain dark:outline-hidden dark:border-t dark:border-tint-alt-2",
+    variants: {
+        maxWidth: {
+            default: "max-w-80",
+            datePicker: "max-w-75 @sm:max-w-full",
+            none: ""
+        },
+        sectioned: {
+            true: "Litho-Popover--Sectioned p-4",
+            false: ""
+        }
+    }
+});
+function Popover() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
-    var activatorWrapper = props.activatorWrapper, _props_activatorDisplayType = props.activatorDisplayType, activatorDisplayType = _props_activatorDisplayType === void 0 ? "inline-block" : _props_activatorDisplayType, activator = props.activator, children = props.children, onClose = props.onClose, active = props.active, fixed = props.fixed, zIndexOverride = props.zIndexOverride, _props_sectioned = props.sectioned, sectioned = _props_sectioned === void 0 ? false : _props_sectioned, _props_preferredAlignment = props.preferredAlignment, preferredAlignment = _props_preferredAlignment === void 0 ? "center" : _props_preferredAlignment, _props_preferredPosition = props.preferredPosition, preferredPosition = _props_preferredPosition === void 0 ? "below" : _props_preferredPosition, _props_matchActivatorWidth = props.matchActivatorWidth, matchActivatorWidth = _props_matchActivatorWidth === void 0 ? false : _props_matchActivatorWidth, _props_maxWidth = props.maxWidth, maxWidth = _props_maxWidth === void 0 ? "default" : _props_maxWidth, className = props.className, containerClassName = props.containerClassName, _props_closeOnResize = props.closeOnResize, closeOnResize = _props_closeOnResize === void 0 ? true : _props_closeOnResize, _props_debounceResizeObserver = props.debounceResizeObserver, debounceResizeObserver = _props_debounceResizeObserver === void 0 ? false : _props_debounceResizeObserver, _props_usePortal = props.usePortal, usePortal = _props_usePortal === void 0 ? true : _props_usePortal;
+    var activatorWrapper = props.activatorWrapper, _props_activatorDisplayType = props.activatorDisplayType, activatorDisplayType = _props_activatorDisplayType === void 0 ? "inline-block" : _props_activatorDisplayType, activator = props.activator, children = props.children, onClose = props.onClose, activeProp = props.active, fixed = props.fixed, zIndexOverride = props.zIndexOverride, _props_sectioned = props.sectioned, sectioned = _props_sectioned === void 0 ? false : _props_sectioned, _props_preferredAlignment = props.preferredAlignment, preferredAlignment = _props_preferredAlignment === void 0 ? "center" : _props_preferredAlignment, _props_preferredPosition = props.preferredPosition, preferredPosition = _props_preferredPosition === void 0 ? "below" : _props_preferredPosition, _props_horizontalOffset = props.horizontalOffset, horizontalOffset = _props_horizontalOffset === void 0 ? 0 : _props_horizontalOffset, _props_matchActivatorWidth = props.matchActivatorWidth, matchActivatorWidth = _props_matchActivatorWidth === void 0 ? false : _props_matchActivatorWidth, _props_maxWidth = props.maxWidth, maxWidth = _props_maxWidth === void 0 ? "default" : _props_maxWidth, className = props.className, containerClassName = props.containerClassName, _props_closeOnResize = props.closeOnResize, closeOnResize = _props_closeOnResize === void 0 ? true : _props_closeOnResize, _props_debounceResizeObserver = props.debounceResizeObserver, debounceResizeObserver = _props_debounceResizeObserver === void 0 ? false : _props_debounceResizeObserver, _props_usePortal = props.usePortal, usePortal = _props_usePortal === void 0 ? true : _props_usePortal;
     var ActivatorWrapper = activatorWrapper || "div";
     var idValue = (0, _react.useId)();
     var idRef = (0, _react.useRef)(idValue);
     var initialWidthRef = (0, _react.useRef)(null);
     var popoverRef = (0, _react.useRef)(null);
     var activatorRef = (0, _react.useRef)(null);
+    // Check if the activator is inside an inert element (e.g., table cells covered by fixed columns)
+    var isActivatorInert = activatorRef.current ? activatorRef.current.closest('[inert]') !== null : false;
+    // When disabled, prevent popover from opening
+    var active = isActivatorInert ? false : activeProp;
     var _useState = _sliced_to_array((0, _react.useState)(_object_spread({
         visibility: "hidden",
         opacity: 0,
@@ -283,7 +301,7 @@ var styles = (0, _tailwindvariants.tv)({
                     } else if (preferredAlignment === "right") {
                         left = fixed ? activatorRect.right - popoverRect.width : activatorRect.right + window.scrollX - popoverRect.width;
                     } else if (preferredAlignment === "center") {
-                        left = fixed ? activatorRect.left + activatorRect.width / 2 - popoverRect.width / 2 : activatorRect.left + window.scrollX + activatorRect.width / 2 - popoverRect.width / 2;
+                        left = fixed ? activatorRect.left + activatorRect.width / 2 - popoverRect.width / 2 + horizontalOffset : activatorRect.left + window.scrollX + activatorRect.width / 2 - popoverRect.width / 2 + horizontalOffset;
                     }
                 } else if (position === "above") {
                     top = fixed ? activatorRect.top - popoverRect.height - TOP_SPACING : activatorRect.top + window.scrollY - popoverRect.height - TOP_SPACING;
@@ -292,7 +310,7 @@ var styles = (0, _tailwindvariants.tv)({
                     } else if (preferredAlignment === "right") {
                         left = fixed ? activatorRect.right - popoverRect.width : activatorRect.right + window.scrollX - popoverRect.width;
                     } else if (preferredAlignment === "center") {
-                        left = fixed ? activatorRect.left + activatorRect.width / 2 - popoverRect.width / 2 : activatorRect.left + window.scrollX + activatorRect.width / 2 - popoverRect.width / 2;
+                        left = fixed ? activatorRect.left + activatorRect.width / 2 - popoverRect.width / 2 + horizontalOffset : activatorRect.left + window.scrollX + activatorRect.width / 2 - popoverRect.width / 2 + horizontalOffset;
                     }
                 } else if (position === "cover") {
                     top = fixed ? activatorRect.top : activatorRect.top + window.scrollY;
@@ -301,7 +319,7 @@ var styles = (0, _tailwindvariants.tv)({
                     } else if (preferredAlignment === "right") {
                         left = fixed ? activatorRect.right - popoverRect.width : activatorRect.right + window.scrollX - popoverRect.width;
                     } else if (preferredAlignment === "center") {
-                        left = fixed ? activatorRect.left + activatorRect.width / 2 - popoverRect.width / 2 : activatorRect.left + window.scrollX + activatorRect.width / 2 - popoverRect.width / 2;
+                        left = fixed ? activatorRect.left + activatorRect.width / 2 - popoverRect.width / 2 + horizontalOffset : activatorRect.left + window.scrollX + activatorRect.width / 2 - popoverRect.width / 2 + horizontalOffset;
                     }
                 }
                 // Fallback adjustments for vertical positioning (when not in left/right mode)
@@ -314,11 +332,23 @@ var styles = (0, _tailwindvariants.tv)({
                     }
                 }
                 // Fallback adjustments for horizontal positioning
-                if (left + popoverRect.width > windowWidth) {
-                    left = windowWidth - popoverRect.width - EDGE_SPACING;
-                }
-                if (left < 0) {
-                    left = EDGE_SPACING;
+                // Only apply edge constraints if we're not using center alignment with custom offset
+                // This allows center alignment to work even near edges
+                if (preferredAlignment !== "center" || horizontalOffset === 0) {
+                    if (left + popoverRect.width > windowWidth) {
+                        left = windowWidth - popoverRect.width - EDGE_SPACING;
+                    }
+                    if (left < 0) {
+                        left = EDGE_SPACING;
+                    }
+                } else {
+                    // For center alignment with offset, still respect edges but try to maintain centering
+                    if (left + popoverRect.width > windowWidth) {
+                        left = Math.max(EDGE_SPACING, windowWidth - popoverRect.width - EDGE_SPACING);
+                    }
+                    if (left < 0) {
+                        left = EDGE_SPACING;
+                    }
                 }
                 // Fallback adjustments for vertical positioning (when in left/right mode)
                 if (position === "left" || position === "right") {
@@ -448,7 +478,7 @@ var styles = (0, _tailwindvariants.tv)({
                 children: memoizedActivator
             }),
             active && typeof children !== "undefined" && (usePortal ? /*#__PURE__*/ (0, _reactdom.createPortal)(/*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
-                className: "@container",
+                className: "@container/main",
                 children: /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
                     ref: popoverRef,
                     style: popoverStyle,
@@ -456,7 +486,7 @@ var styles = (0, _tailwindvariants.tv)({
                     children: children
                 })
             }), document.body) : /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
-                className: "@container",
+                className: "@container/main",
                 children: /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
                     ref: popoverRef,
                     style: popoverStyle,
@@ -481,7 +511,10 @@ var sectionStyles = (0, _tailwindvariants.tv)({
     }
 });
 /**
- * Section component for use within the Popover.
+ * @component Popover.Section
+ *
+ * @usage
+ * - DO: Use to divide Popover content into logical segments with borders.
  *
  * @param {Object} props - The component props.
  * @param {React.ReactNode} [props.children] - The content of the section.

package/dist/cjs/components/PopoverManager.js

@@ -1,4 +1,17 @@
-"use strict";
+/**
+ * @component PopoverManager
+ *
+ * @description An internal event-based coordination utility that tracks active popovers and emits change events to manage open/close state.
+ *
+ * @usage
+ * - DO: Use to coordinate popover open/close state across multiple Popover instances.
+ * - DON'T: Import directly in most cases; Popover uses it internally.
+ *
+ * @alternative
+ * - If you need to render a popover, use `Popover` directly. PopoverManager is an internal coordination utility.
+ *
+ * @module PopoverManager
+ */ "use strict";
 Object.defineProperty(exports, "__esModule", {
     value: true
 });

package/dist/cjs/components/ProgressBar.js

@@ -10,7 +10,33 @@ Object.defineProperty(exports, "default", {
 });
 var _jsxruntime = require("react/jsx-runtime");
 var _tailwindvariants = require("tailwind-variants");
-var styles = (0, _tailwindvariants.tv)({
+/**
+ * @component ProgressBar
+ *
+ * @description A horizontal bar that visually represents completion progress as a percentage with configurable size and color.
+ *
+ * @usage
+ * - DO: Show completion percentage or progress of a task.
+ * - DON'T: Use for indeterminate loading (use Spinner or Loading).
+ *
+ * @accessibility
+ * - Include an accessible label describing the progress context.
+ * - Consider adding visible percentage text.
+ *
+ * @alternative
+ * - If you need an indeterminate loading indicator, use `Spinner`.
+ * - If you need a status label, use `Badge`.
+ *
+ * @param {Object} props - Properties to configure the progress bar.
+ * @param {number} [props.progress=0] - The progress percentage (0-100).
+ * @param {number} [props.previousProgress] - The previous period's progress percentage (0-100).
+ * @param {boolean} [props.comparisonMode=false] - Whether to show comparison between current and previous period.
+ * @param {("small"|"medium"|"large")} [props.size="medium"] - The size of the progress bar.
+ * @param {("attention"|"highlight"|"success"|"warning"|"critical"|"neutral"|"positive"|"negative")} [props.color="attention"] - The color of the progress indicator.
+ * @param {boolean} [props.animated=true] - Whether the progress bar should animate width changes.
+ *
+ * @returns {JSX.Element} The rendered progress bar component.
+ */ var styles = (0, _tailwindvariants.tv)({
     base: "Litho-ProgressBar relative bg-tint-2 dark:bg-tint-alt-2 rounded-full overflow-hidden min-w-12",
     variants: {
         size: {
@@ -49,20 +75,7 @@ var barStyles = (0, _tailwindvariants.tv)({
         animated: true
     }
 });
-/**
- * A progress bar component with configurable size, color, and animation.
- * Can be used in single or comparison mode to show progress changes.
- *
- * @param {Object} props - Properties to configure the progress bar.
- * @param {number} [props.progress=0] - The progress percentage (0-100).
- * @param {number} [props.previousProgress] - The previous period's progress percentage (0-100).
- * @param {boolean} [props.comparisonMode=false] - Whether to show comparison between current and previous period.
- * @param {("small"|"medium"|"large")} [props.size="medium"] - The size of the progress bar.
- * @param {("attention"|"highlight"|"success"|"warning"|"critical"|"neutral"|"positive"|"negative")} [props.color="attention"] - The color of the progress indicator.
- * @param {boolean} [props.animated=true] - Whether the progress bar should animate width changes.
- *
- * @returns {JSX.Element} The rendered progress bar component.
- */ function ProgressBar() {
+function ProgressBar() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var _props_progress = props.progress, progress = _props_progress === void 0 ? 0 : _props_progress, previousProgress = props.previousProgress, _props_comparisonMode = props.comparisonMode, comparisonMode = _props_comparisonMode === void 0 ? false : _props_comparisonMode, _props_size = props.size, size = _props_size === void 0 ? "medium" : _props_size, _props_color = props.color, color = _props_color === void 0 ? "attention" : _props_color, _props_animated = props.animated, animated = _props_animated === void 0 ? true : _props_animated, className = props.className;
     var classes = styles({

package/dist/cjs/components/RadioButton.js

@@ -17,7 +17,37 @@ function _interop_require_default(obj) {
         default: obj
     };
 }
-var styles = (0, _tailwindvariants.tv)({
+/**
+ * @component RadioButton
+ *
+ * @description A single radio input for selecting one option from a mutually exclusive group.
+ *
+ * @usage
+ * - DO: Use for selecting one option from a mutually exclusive group.
+ * - DON'T: Use for multi-select (use Checkbox).
+ *
+ * @accessibility
+ * - Group radio buttons with a shared `name` prop; ensure each has a descriptive `label`.
+ *
+ * @alternative
+ * - If you need a rich card-style radio, use `RadioButtonCard`. If you need grouped options with a label, use `ChoiceList`.
+ *
+ * @param {Object} props - Props for the RadioButton component.
+ * @param {string} [props.label] - The text label for the radio button.
+ * @param {boolean} [props.labelHidden=false] - If true, hides the label visually but keeps it available for screen readers.
+ * @param {string} [props.id] - The unique identifier for the radio input.
+ * @param {string} [props.name] - The name attribute for the radio input (must be the same for grouped buttons).
+ * @param {string} [props.value] - The value attribute for the radio input.
+ * @param {string} [props.error] - An error message associated with the radio button, if any.
+ * @param {boolean} [props.checked=false] - Indicates whether the radio button is checked.
+ * @param {boolean} [props.disabled=false] - Indicates whether the radio button is disabled.
+ * @param {string} [props.helpText] - Additional descriptive text for the radio button.
+ * @param {function} [props.onChange] - Callback function called when the radio button state changes.
+ * @param {function} [props.onFocus] - Callback function called when the radio button gains focus.
+ * @param {function} [props.onBlur] - Callback function called when the radio button loses focus.
+ *
+ * @returns {JSX.Element} The rendered RadioButton component.
+ */ var styles = (0, _tailwindvariants.tv)({
     base: "Litho-RadioButton group flex gap-2",
     variants: {
         disabled: {
@@ -66,29 +96,7 @@ var radioStyles = (0, _tailwindvariants.tv)({
         }
     ]
 });
-/**
- * RadioButton Component
- * 
- * A custom radio button component with support for labels, help text, and extensive styling using Tailwind Variants (tv).
- * 
- * @component
- * 
- * @param {Object} props - Props for the RadioButton component.
- * @param {string} [props.label] - The text label for the radio button.
- * @param {boolean} [props.labelHidden=false] - If true, hides the label visually but keeps it available for screen readers.
- * @param {string} [props.id] - The unique identifier for the radio input.
- * @param {string} [props.name] - The name attribute for the radio input (must be the same for grouped buttons).
- * @param {string} [props.value] - The value attribute for the radio input.
- * @param {string} [props.error] - An error message associated with the radio button, if any.
- * @param {boolean} [props.checked=false] - Indicates whether the radio button is checked.
- * @param {boolean} [props.disabled=false] - Indicates whether the radio button is disabled.
- * @param {string} [props.helpText] - Additional descriptive text for the radio button.
- * @param {function} [props.onChange] - Callback function called when the radio button state changes.
- * @param {function} [props.onFocus] - Callback function called when the radio button gains focus.
- * @param {function} [props.onBlur] - Callback function called when the radio button loses focus.
- * 
- * @returns {JSX.Element} The rendered RadioButton component.
- */ function RadioButton() {
+function RadioButton() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var label = props.label, tooltip = props.tooltip, labelHidden = props.labelHidden, id = props.id, name = props.name, value = props.value, error = props.error, _props_checked = props.checked, checked = _props_checked === void 0 ? false : _props_checked, _props_disabled = props.disabled, disabled = _props_disabled === void 0 ? false : _props_disabled, helpText = props.helpText, onChange = props.onChange, onFocus = props.onFocus, onBlur = props.onBlur, _props_alignItems = props.alignItems, alignItems = _props_alignItems === void 0 ? "stretch" : _props_alignItems;
     var hasError = !!error;

package/dist/cjs/components/RadioButtonCard.js

@@ -17,8 +17,42 @@ function _interop_require_default(obj) {
         default: obj
     };
 }
-var styles = (0, _tailwindvariants.tv)({
-    base: "Litho-RadioButtonCardContainer border border-transparent rounded-lg p-3 pl-4 flex justify-between gap-2",
+/**
+ * @component RadioButtonCard
+ *
+ * @description A card-styled radio input that displays a title and description within a selectable card container.
+ *
+ * @usage
+ * - DO: Use for visually prominent single-choice selections with descriptive content.
+ * - DON'T: Use for simple inline radio inputs (use RadioButton).
+ *
+ * @accessibility
+ * - The entire card is clickable and keyboard accessible; ensure title clearly describes the option.
+ *
+ * @alternative
+ * - If you need a simple inline radio button, use `RadioButton`. If you need a checkbox-style card, use `CheckboxCard`.
+ *
+ * @param {Object} props - Props for the RadioButtonCard component.
+ * @param {string} [props.label] - The text label for the radio button.
+ * @param {boolean} [props.labelHidden=false] - If true, hides the label visually but keeps it available for screen readers.
+ * @param {string} [props.id] - The unique identifier for the radio input.
+ * @param {string} [props.name] - The name attribute for the radio input (must be the same for grouped buttons).
+ * @param {string} [props.description] - A description of the radio button.
+ * @param {string} [props.value] - The value attribute for the radio input.
+ * @param {string} [props.error] - An error message associated with the radio button, if any.
+ * @param {boolean} [props.checked=false] - Indicates whether the radio button is checked.
+ * @param {boolean} [props.disabled=false] - Indicates whether the radio button is disabled.
+ * @param {string} [props.helpText] - Additional descriptive text for the radio button.
+ * @param {function} [props.onChange] - Callback function called when the radio button state changes.
+ * @param {function} [props.onFocus] - Callback function called when the radio button gains focus.
+ * @param {function} [props.onBlur] - Callback function called when the radio button loses focus.
+ * @param {boolean} [props.hideRadioButton=false] - When true, hides the visual radio button control.
+ * @param {React.ReactNode} [props.icon=null] - Optional icon JSX to display in the card.
+ * @param {boolean} [props.allowDeselect=true] - When true, clicking an already-selected card deselects it by calling onChange with a synthetic event where target.value is null.
+ *
+ * @returns {JSX.Element} The rendered RadioButton component.
+ */ var styles = (0, _tailwindvariants.tv)({
+    base: "Litho-RadioButtonCardContainer border border-transparent rounded-lg p-3 pl-4 flex justify-between gap-2 hover:border-form-border-focus hover:ring hover:ring-form-focus",
     variants: {
         disabled: {
             true: "bg-tint-1",
@@ -33,12 +67,12 @@ var styles = (0, _tailwindvariants.tv)({
         {
             disabled: false,
             checked: true,
-            class: "border-form-border-focus ring-1 ring-inset ring-form-border-focus"
+            class: "border-form-border-focus bg-surface-selected"
         },
         {
             disabled: false,
             checked: false,
-            class: "hover:border-edge-default"
+            class: ""
         }
     ]
 });
@@ -76,32 +110,9 @@ var radioStyles = (0, _tailwindvariants.tv)({
         }
     ]
 });
-/**
- * RadioButton Component
- * 
- * A custom radio button component with support for labels, help text, and extensive styling using Tailwind Variants (tv).
- * 
- * @component
- * 
- * @param {Object} props - Props for the RadioButton component.
- * @param {string} [props.label] - The text label for the radio button.
- * @param {boolean} [props.labelHidden=false] - If true, hides the label visually but keeps it available for screen readers.
- * @param {string} [props.id] - The unique identifier for the radio input.
- * @param {string} [props.name] - The name attribute for the radio input (must be the same for grouped buttons).
- * @param {string} [props.description] - A description of the radio button.
- * @param {string} [props.value] - The value attribute for the radio input.
- * @param {string} [props.error] - An error message associated with the radio button, if any.
- * @param {boolean} [props.checked=false] - Indicates whether the radio button is checked.
- * @param {boolean} [props.disabled=false] - Indicates whether the radio button is disabled.
- * @param {string} [props.helpText] - Additional descriptive text for the radio button.
- * @param {function} [props.onChange] - Callback function called when the radio button state changes.
- * @param {function} [props.onFocus] - Callback function called when the radio button gains focus.
- * @param {function} [props.onBlur] - Callback function called when the radio button loses focus.
- * 
- * @returns {JSX.Element} The rendered RadioButton component.
- */ function RadioButtonCard() {
+function RadioButtonCard() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
-    var label = props.label, tooltip = props.tooltip, labelHidden = props.labelHidden, id = props.id, name = props.name, description = props.description, value = props.value, error = props.error, _props_checked = props.checked, checked = _props_checked === void 0 ? false : _props_checked, _props_disabled = props.disabled, disabled = _props_disabled === void 0 ? false : _props_disabled, helpText = props.helpText, onChange = props.onChange, onFocus = props.onFocus, onBlur = props.onBlur;
+    var label = props.label, tooltip = props.tooltip, labelHidden = props.labelHidden, id = props.id, name = props.name, description = props.description, value = props.value, error = props.error, _props_checked = props.checked, checked = _props_checked === void 0 ? false : _props_checked, _props_disabled = props.disabled, disabled = _props_disabled === void 0 ? false : _props_disabled, helpText = props.helpText, _props_hideRadioButton = props.hideRadioButton, hideRadioButton = _props_hideRadioButton === void 0 ? false : _props_hideRadioButton, _props_icon = props.icon, icon = _props_icon === void 0 ? null : _props_icon, _props_allowDeselect = props.allowDeselect, allowDeselect = _props_allowDeselect === void 0 ? true : _props_allowDeselect, onChange = props.onChange, onFocus = props.onFocus, onBlur = props.onBlur, _props_labelFontWeight = props.labelFontWeight, labelFontWeight = _props_labelFontWeight === void 0 ? "semibold" : _props_labelFontWeight;
     var hasError = !!error;
     var classes = styles({
         checked: checked,
@@ -128,57 +139,71 @@ var radioStyles = (0, _tailwindvariants.tv)({
             onBlur(event);
         }
     };
+    var handleLabelClick = function() {
+        if (allowDeselect && checked && !disabled) {
+            onChange === null || onChange === void 0 ? void 0 : onChange({
+                target: {
+                    value: null
+                }
+            });
+        }
+    };
     return /*#__PURE__*/ (0, _jsxruntime.jsxs)("div", {
         className: "flex flex-col gap-1",
         children: [
             /*#__PURE__*/ (0, _jsxruntime.jsxs)("label", {
                 className: classes,
+                onClick: handleLabelClick,
                 children: [
                     /*#__PURE__*/ (0, _jsxruntime.jsxs)("div", {
-                        className: "flex flex-col gap-1",
+                        className: "flex items-center gap-4",
                         children: [
-                            label && !labelHidden && /*#__PURE__*/ (0, _jsxruntime.jsx)(_Label.default, {
-                                tooltip: tooltip,
-                                disabled: disabled,
-                                fontWeight: "semibold",
-                                as: "p",
-                                children: label
+                            icon && /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
+                                className: "flex-shrink-0",
+                                children: icon
                             }),
-                            description && /*#__PURE__*/ (0, _jsxruntime.jsx)(_Text.default, {
-                                color: disabled ? "disabled" : "subdued",
-                                children: description
+                            /*#__PURE__*/ (0, _jsxruntime.jsxs)("div", {
+                                children: [
+                                    label && !labelHidden && /*#__PURE__*/ (0, _jsxruntime.jsx)(_Label.default, {
+                                        tooltip: tooltip,
+                                        disabled: disabled,
+                                        fontWeight: labelFontWeight,
+                                        as: "p",
+                                        children: label
+                                    }),
+                                    description && /*#__PURE__*/ (0, _jsxruntime.jsx)(_Text.default, {
+                                        color: disabled ? "disabled" : "subdued",
+                                        children: description
+                                    })
+                                ]
                             })
                         ]
                     }),
-                    /*#__PURE__*/ (0, _jsxruntime.jsxs)("div", {
-                        children: [
-                            /*#__PURE__*/ (0, _jsxruntime.jsx)("input", {
-                                type: "radio",
-                                id: id,
-                                name: name,
-                                value: value,
-                                checked: checked,
-                                disabled: disabled,
-                                onChange: handleChange,
-                                onFocus: handleFocus,
-                                onBlur: handleBlur,
-                                className: "sr-only"
-                            }),
-                            /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
-                                className: "Litho-RadioButton__ControlContainer w-5 h-5 flex items-center",
-                                children: /*#__PURE__*/ (0, _jsxruntime.jsxs)("div", {
-                                    className: radioClasses,
-                                    children: [
-                                        checked && !hasError && /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
-                                            className: "rounded-full w-1.5 h-1.5 ".concat(disabled ? "bg-form-input-fg-disabled" : "bg-form-input-fg-light")
-                                        }),
-                                        checked && hasError && /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
-                                            className: "rounded-full w-1.5 h-1.5 ".concat(disabled ? "bg-form-input-fg-disabled" : "bg-form-bg")
-                                        })
-                                    ]
+                    /*#__PURE__*/ (0, _jsxruntime.jsx)("input", {
+                        type: "radio",
+                        id: id,
+                        name: name,
+                        value: value,
+                        checked: checked,
+                        disabled: disabled,
+                        onChange: handleChange,
+                        onFocus: handleFocus,
+                        onBlur: handleBlur,
+                        className: "sr-only"
+                    }),
+                    !hideRadioButton && /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
+                        className: "Litho-RadioButton__ControlContainer w-5 h-5 flex items-center",
+                        children: /*#__PURE__*/ (0, _jsxruntime.jsxs)("div", {
+                            className: radioClasses,
+                            children: [
+                                checked && !hasError && /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
+                                    className: "rounded-full w-1.5 h-1.5 ".concat(disabled ? "bg-form-input-fg-disabled" : "bg-form-input-fg-light")
+                                }),
+                                checked && hasError && /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
+                                    className: "rounded-full w-1.5 h-1.5 ".concat(disabled ? "bg-form-input-fg-disabled" : "bg-form-bg")
                                 })
-                            })
-                        ]
+                            ]
+                        })
                     })
                 ]
             }),