@heymantle/litho 0.0.14 → 0.0.16

package/dist/esm/components/Listbox.js

@@ -51,7 +51,44 @@ import { MobileAcceptMajor } from "@shopify/polaris-icons";
 import { tv } from "tailwind-variants";
 import Icon from "./Icon.js";
 import { useFrame } from "./Frame.js";
-var styles = tv({
+/**
+ * @component Listbox
+ *
+ * @description A selectable list component that renders options as interactive items with optional icons and descriptions.
+ *
+ * @usage
+ * - DO: Use for custom-styled selection lists with full keyboard navigation.
+ * - DON'T: Use for simple dropdowns (use Select).
+ *
+ * @accessibility
+ * - Implements listbox ARIA pattern with keyboard arrow navigation and selection.
+ *
+ * @alternative
+ * - If you need a native dropdown, use `Select`. If you need a searchable list, use `Autocomplete`.
+ *
+ * @param {Object} props - The properties object.
+ * @param {Array<Object>} props.options - Array of options to render in the listbox.
+ * Each option should be an object with the following properties:
+ *   - `label` {string}: The display label of the option.
+ *   - `value` {string | number}: The unique value of the option.
+ *   - `icon` {React.ComponentType | string} [optional]: Icon source (Polaris, Lucide component, or string) rendered via `<Icon>`. Colors automatically based on selected state.
+ *   - `showIconOnMobile` {boolean} [optional, default: true]: When false, the option icon is hidden on mobile and only shown at md (≥800px) breakpoint.
+ *   - `selected` {boolean}: Whether the option is currently selected.
+ *   - `onAction` {function}: A callback function invoked when the option is clicked or "Enter" is pressed.
+ * @param {boolean} [props.showIcon=false] - Determines whether to display an icon next to selected options.
+ * @param {React.ReactNode} [props.icon=MobileAcceptMajor] - The icon to display for selected options (default is `MobileAcceptMajor`).
+ * @param {boolean} [props.displayHorizontallyOnMobile=false] - Determines whether to display the listbox horizontally on mobile.
+ *
+ * @example
+ * const options = [
+ *   { label: "Option 1", value: "opt1", selected: false, onAction: () => console.log("Option 1 clicked") },
+ *   { label: "Option 2", value: "opt2", selected: true, onAction: () => console.log("Option 2 clicked") },
+ * ];
+ *
+ * <Listbox options={options} showIcon={true} icon={CustomIcon} />
+ *
+ * @returns {JSX.Element} The rendered Listbox component.
+ */ var styles = tv({
     base: "Litho-Listbox__Option rounded-md cursor-pointer min-h-8 py-1 flex items-center justify-between pl-3 focus:outline-hidden active:ring-0",
     variants: {
         showIcon: {
@@ -80,32 +117,7 @@ var containerStyles = tv({
         displayHorizontallyOnMobile: false
     }
 });
-/**
- * A customizable Listbox component for displaying a list of options with selectable states.
- * The component supports keyboard navigation and optional icons for selected items.
- *
- * @component
- * @param {Object} props - The properties object.
- * @param {Array<Object>} props.options - Array of options to render in the listbox.
- * Each option should be an object with the following properties:
- *   - `label` {string}: The display label of the option.
- *   - `value` {string | number}: The unique value of the option.
- *   - `selected` {boolean}: Whether the option is currently selected.
- *   - `onAction` {function}: A callback function invoked when the option is clicked or "Enter" is pressed.
- * @param {boolean} [props.showIcon=false] - Determines whether to display an icon next to selected options.
- * @param {React.ReactNode} [props.icon=MobileAcceptMajor] - The icon to display for selected options (default is `MobileAcceptMajor`).
- * @param {boolean} [props.displayHorizontallyOnMobile=false] - Determines whether to display the listbox horizontally on mobile.
- *
- * @example
- * const options = [
- *   { label: "Option 1", value: "opt1", selected: false, onAction: () => console.log("Option 1 clicked") },
- *   { label: "Option 2", value: "opt2", selected: true, onAction: () => console.log("Option 2 clicked") },
- * ];
- *
- * <Listbox options={options} showIcon={true} icon={CustomIcon} />
- *
- * @returns {JSX.Element} The rendered Listbox component.
- */ function Listbox() {
+function Listbox() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var options = props.options, _props_showIcon = props.showIcon, showIcon = _props_showIcon === void 0 ? false : _props_showIcon, _props_displayHorizontallyOnMobile = props.displayHorizontallyOnMobile, displayHorizontallyOnMobile = _props_displayHorizontallyOnMobile === void 0 ? false : _props_displayHorizontallyOnMobile, _props_icon = props.icon, icon = _props_icon === void 0 ? MobileAcceptMajor : _props_icon;
     var screenSizes = useFrame().screenSizes;
@@ -161,7 +173,7 @@ var containerStyles = tv({
             displayHorizontallyOnMobile: displayHorizontallyOnMobile
         }),
         children: options.map(function(option, index) {
-            var selected = option.selected, label = option.label, value = option.value, onAction = option.onAction;
+            var selected = option.selected, label = option.label, value = option.value, optionIcon = option.icon, _option_showIconOnMobile = option.showIconOnMobile, showIconOnMobile = _option_showIconOnMobile === void 0 ? true : _option_showIconOnMobile, onAction = option.onAction;
             var classes = styles({
                 selected: selected,
                 showIcon: showIcon,
@@ -182,9 +194,19 @@ var containerStyles = tv({
                     return handleKeyDown(e, index);
                 },
                 children: [
-                    /*#__PURE__*/ _jsx("div", {
-                        className: "whitespace-nowrap pointer-events-none w-full",
-                        children: label
+                    /*#__PURE__*/ _jsxs("div", {
+                        className: "flex items-center gap-2 whitespace-nowrap pointer-events-none w-full",
+                        children: [
+                            optionIcon && /*#__PURE__*/ _jsx("span", {
+                                className: showIconOnMobile ? "" : "hidden @md:inline-flex",
+                                children: /*#__PURE__*/ _jsx(Icon, {
+                                    source: optionIcon,
+                                    color: selected ? "active" : "subdued",
+                                    size: "sm"
+                                })
+                            }),
+                            label
+                        ]
                     }),
                     showIcon && /*#__PURE__*/ _jsx("div", {
                         className: "w-5 h-5 pointer-events-none",

package/dist/esm/components/Loading.js

@@ -48,9 +48,21 @@ function _unsupported_iterable_to_array(o, minLen) {
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useState } from "react";
 /**
- * A loading progress bar component that animates over a specified duration.
+ * @component Loading
+ *
+ * @description A page-level progress bar that animates across the top of the viewport during navigation or data fetching.
+ *
+ * @usage
+ * - DO: Use as a page-level loading indicator at the top of the viewport during navigation or data fetching.
+ * - DON'T: Use for inline or localized loading states; use `Spinner` for those cases.
+ *
+ * @accessibility
+ * - The progress bar is purely visual; pair with `aria-busy` on the loading container if screen reader announcements are needed.
+ *
+ * @alternative
+ * - If you need an inline loading indicator, use `Spinner` instead.
+ * - If you need placeholder content while data loads, use `SkeletonText` instead.
  *
- * @component
  * @param {Object} props - The props object.
  * @param {number} [props.maxDuration=10000] - The maximum duration (in milliseconds) for the loading progress bar to reach 100%.
  * @returns {JSX.Element} A fixed progress bar displayed at the top of the page.

package/dist/esm/components/Modal.js

@@ -61,9 +61,69 @@ import Text from "./Text.js";
 import Tooltip from "./Tooltip.js";
 import { useFrame } from "./Frame.js";
 import { useBodyScrollLock } from "../utilities/useBodyScrollLock.js";
-export var ModalContext = /*#__PURE__*/ createContext(false);
+/**
+ * @component Modal
+ *
+ * @description A dialog overlay that focuses the user on a specific task or confirmation, with header, body sections, and footer actions.
+ *
+ * @usage
+ * - DO: Use for focused tasks that require user attention or input, like confirmations or forms.
+ * - DON'T: Use for content that should remain accessible while reading the page (use Pane).
+ *
+ * @accessibility
+ * - Traps focus within the modal when open; supports Escape key dismissal.
+ * - Ensure `title` provides context for screen readers.
+ *
+ * @alternative
+ * - If you need a side panel that doesn't block the page, use `Pane`.
+ * - If you need inline messaging, use `Banner`.
+ *
+ * @param {Object} props - The component props.
+ * @param {React.ReactNode} [props.children] - The content of the modal.
+ * @param {string} [props.title] - The title of the modal.
+ * @param {string} [props.subtitle] - The subtitle of the modal.
+ * @param {boolean} [props.open=false] - Whether the modal is open.
+ * @param {Function} [props.onClose] - Callback function for closing the modal.
+ * @param {boolean} [props.sectioned=false] - Whether the modal content should be sectioned.
+ * @param {Object} [props.primaryAction] - The primary action for the modal.
+ * @param {string} [props.primaryAction.content] - Content of the primary action button.
+ * @param {Function} [props.primaryAction.onAction] - Callback for the primary action.
+ * @param {boolean} [props.primaryAction.loading=false] - Whether the primary action is loading.
+ * @param {boolean} [props.primaryAction.disabled=false] - Whether the primary action is disabled.
+ * @param {boolean} [props.primaryAction.destructive=false] - Whether the primary action is destructive.
+ * @param {Object} [props.secondaryAction] - The secondary action for the modal.
+ * @param {string} [props.secondaryAction.content] - Content of the secondary action button.
+ * @param {Function} [props.secondaryAction.onAction] - Callback for the secondary action.
+ * @param {boolean} [props.secondaryAction.disabled=false] - Whether the secondary action is disabled.
+ * @param {Object[]} [props.secondaryActions=[]] - Additional secondary actions.
+ * @param {Object} [props.destructiveAction] - A destructive action for the modal.
+ * @param {boolean} [props.loading=false] - Whether the modal is in a loading state.
+ * @param {string} [props.size="default"] - The size of the modal (default, large, or full).
+ * @param {React.ReactNode} [props.leftAccessory] - Left accessory content in the footer.
+ * @param {boolean} [props.hideCloseButton=false] - Whether to hide the close button.
+ * @param {Function} [props.backAction] - Callback function for the back button. When provided, displays a back button next to the title.
+ * @param {number} [props.zIndexOverride=1000] - The z-index of the modal.
+ * @param {boolean} [props.autoFocusFirstInput=true] - Whether to focus the first input when the modal opens.
+ * @param {boolean} [props.pinToTop=false] - Whether to pin the modal to the top of the viewport instead of centering it vertically. Useful when modal content changes height dynamically.
+ * @param {string} [props.bodyClassName] - Additional CSS classes to apply to the modal body.
+ * @returns {React.ReactPortal|null} The rendered modal component or null if not open.
+ */ export var ModalContext = /*#__PURE__*/ createContext(false);
 var containerStyles = tv({
-    base: "Litho-ModalContainer fixed inset-0 block flex flex-col justify-end md:justify-center items-center pointer-events-none"
+    base: "Litho-ModalContainer fixed inset-0 block flex flex-col justify-end items-center pointer-events-none",
+    variants: {
+        hidden: {
+            true: "hidden opacity-0 pointer-events-none",
+            false: ""
+        },
+        pinToTop: {
+            true: "md:justify-start md:py-5",
+            false: "md:justify-center"
+        }
+    },
+    defaultVariants: {
+        hidden: false,
+        pinToTop: false
+    }
 });
 var styles = tv({
     base: "Litho-Modal relative bg-surface-highest shadow-modal dark:shadow-modal-dark w-full mx-auto pointer-events-auto flex flex-col overflow-hidden",
@@ -109,40 +169,9 @@ var sectionStyles = tv({
         flush: false
     }
 });
-/**
- * Modal component for displaying a customizable dialog.
- *
- * @param {Object} props - The component props.
- * @param {React.ReactNode} [props.children] - The content of the modal.
- * @param {string} [props.title] - The title of the modal.
- * @param {string} [props.subtitle] - The subtitle of the modal.
- * @param {boolean} [props.open=false] - Whether the modal is open.
- * @param {Function} [props.onClose] - Callback function for closing the modal.
- * @param {boolean} [props.sectioned=false] - Whether the modal content should be sectioned.
- * @param {Object} [props.primaryAction] - The primary action for the modal.
- * @param {string} [props.primaryAction.content] - Content of the primary action button.
- * @param {Function} [props.primaryAction.onAction] - Callback for the primary action.
- * @param {boolean} [props.primaryAction.loading=false] - Whether the primary action is loading.
- * @param {boolean} [props.primaryAction.disabled=false] - Whether the primary action is disabled.
- * @param {boolean} [props.primaryAction.destructive=false] - Whether the primary action is destructive.
- * @param {Object} [props.secondaryAction] - The secondary action for the modal.
- * @param {string} [props.secondaryAction.content] - Content of the secondary action button.
- * @param {Function} [props.secondaryAction.onAction] - Callback for the secondary action.
- * @param {boolean} [props.secondaryAction.disabled=false] - Whether the secondary action is disabled.
- * @param {Object[]} [props.secondaryActions=[]] - Additional secondary actions.
- * @param {Object} [props.destructiveAction] - A destructive action for the modal.
- * @param {boolean} [props.loading=false] - Whether the modal is in a loading state.
- * @param {string} [props.size="default"] - The size of the modal (default, large, or full).
- * @param {React.ReactNode} [props.leftAccessory] - Left accessory content in the footer.
- * @param {boolean} [props.hideCloseButton=false] - Whether to hide the close button.
- * @param {Function} [props.backAction] - Callback function for the back button. When provided, displays a back button next to the title.
- * @param {number} [props.zIndexOverride=1000] - The z-index of the modal.
- * @param {boolean} [props.autoFocusFirstInput=true] - Whether to focus the first input when the modal opens.
- * @param {string} [props.bodyClassName] - Additional CSS classes to apply to the modal body.
- * @returns {React.ReactPortal|null} The rendered modal component or null if not open.
- */ function Modal() {
+function Modal() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
-    var children = props.children, title = props.title, subtitle = props.subtitle, open = props.open, onClose = props.onClose, sectioned = props.sectioned, primaryAction = props.primaryAction, secondaryAction = props.secondaryAction, _props_secondaryActions = props.secondaryActions, secondaryActions = _props_secondaryActions === void 0 ? [] : _props_secondaryActions, destructiveAction = props.destructiveAction, loading = props.loading, _props_size = props.size, size = _props_size === void 0 ? "default" : _props_size, leftAccessory = props.leftAccessory, _props_hideCloseButton = props.hideCloseButton, hideCloseButton = _props_hideCloseButton === void 0 ? false : _props_hideCloseButton, backAction = props.backAction, zIndexOverride = props.zIndexOverride, _props_autoFocusFirstInput = props.autoFocusFirstInput, autoFocusFirstInput = _props_autoFocusFirstInput === void 0 ? true : _props_autoFocusFirstInput, bodyClassName = props.bodyClassName;
+    var children = props.children, title = props.title, subtitle = props.subtitle, open = props.open, _props_hidden = props.hidden, hidden = _props_hidden === void 0 ? false : _props_hidden, onClose = props.onClose, sectioned = props.sectioned, primaryAction = props.primaryAction, secondaryAction = props.secondaryAction, _props_secondaryActions = props.secondaryActions, secondaryActions = _props_secondaryActions === void 0 ? [] : _props_secondaryActions, destructiveAction = props.destructiveAction, loading = props.loading, _props_size = props.size, size = _props_size === void 0 ? "default" : _props_size, leftAccessory = props.leftAccessory, _props_hideCloseButton = props.hideCloseButton, hideCloseButton = _props_hideCloseButton === void 0 ? false : _props_hideCloseButton, backAction = props.backAction, zIndexOverride = props.zIndexOverride, _props_autoFocusFirstInput = props.autoFocusFirstInput, autoFocusFirstInput = _props_autoFocusFirstInput === void 0 ? true : _props_autoFocusFirstInput, _props_pinToTop = props.pinToTop, pinToTop = _props_pinToTop === void 0 ? false : _props_pinToTop, bodyClassName = props.bodyClassName;
     var setModalIsOpen = useFrame().setModalIsOpen;
     var modalContentRef = useRef(null);
     var hasChildren = !!children;
@@ -150,7 +179,10 @@ var sectionStyles = tv({
         sectioned: sectioned,
         size: size
     });
-    var containerClasses = containerStyles();
+    var containerClasses = containerStyles({
+        hidden: hidden,
+        pinToTop: pinToTop
+    });
     var headerClasses = headerStyles({
         hasChildren: hasChildren
     });
@@ -159,7 +191,7 @@ var sectionStyles = tv({
     var _useState = _sliced_to_array(useState(null), 2), container = _useState[0], setContainer = _useState[1];
     useEffect(function() {
         var div = document.createElement("div");
-        div.className = "@container Litho-ModalPortal";
+        div.className = "@container/main Litho-ModalPortal";
         setContainer(div);
         document.body.appendChild(div);
         return function() {
@@ -302,6 +334,7 @@ var sectionStyles = tv({
                                             onClick: primaryAction.onAction,
                                             loading: primaryAction.loading,
                                             disabled: primaryAction.disabled,
+                                            insight: primaryAction.insight,
                                             destructive: primaryAction.destructive,
                                             url: primaryAction.url,
                                             tooltip: primaryAction.tooltip,
@@ -318,6 +351,7 @@ var sectionStyles = tv({
             /*#__PURE__*/ _jsx("div", {
                 className: overlayClasses,
                 onClick: onClose,
+                "aria-hidden": "true",
                 style: zIndexOverride ? {
                     zIndex: zIndexOverride - 1
                 } : {}
@@ -326,19 +360,24 @@ var sectionStyles = tv({
     }), container);
 }
 /**
- * Section component for use within the Modal.
+ * @component Modal.Section
+ *
+ * @usage
+ * - DO: Divide modal content into bordered sections for visual separation.
  *
  * @param {Object} props - The component props.
  * @param {React.ReactNode} [props.children] - The content of the section.
  * @param {boolean} [props.flush=false] - Whether the section should be flush with no padding.
+ * @param {string} [props.className] - Additional CSS classes to apply to the section.
  * @returns {JSX.Element} The rendered section.
  */ function Section() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
-    var children = props.children, flush = props.flush, title = props.title, _props_titleVariant = props.titleVariant, titleVariant = _props_titleVariant === void 0 ? "headingSm" : _props_titleVariant, description = props.description, action = props.action, icon = props.icon, accessory = props.accessory, tooltip = props.tooltip;
+    var children = props.children, flush = props.flush, title = props.title, _props_titleVariant = props.titleVariant, titleVariant = _props_titleVariant === void 0 ? "headingSm" : _props_titleVariant, description = props.description, action = props.action, icon = props.icon, accessory = props.accessory, tooltip = props.tooltip, className = props.className;
     var showHeader = !!(title || action);
     var sectionClasses = sectionStyles({
         flush: flush,
-        showHeader: showHeader
+        showHeader: showHeader,
+        className: className
     });
     return /*#__PURE__*/ _jsxs("div", {
         className: sectionClasses,

package/dist/esm/components/Navigation.js

@@ -26,6 +26,30 @@ function _object_spread(target) {
     }
     return target;
 }
+function ownKeys(object, enumerableOnly) {
+    var keys = Object.keys(object);
+    if (Object.getOwnPropertySymbols) {
+        var symbols = Object.getOwnPropertySymbols(object);
+        if (enumerableOnly) {
+            symbols = symbols.filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(object, sym).enumerable;
+            });
+        }
+        keys.push.apply(keys, symbols);
+    }
+    return keys;
+}
+function _object_spread_props(target, source) {
+    source = source != null ? source : {};
+    if (Object.getOwnPropertyDescriptors) {
+        Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
+    } else {
+        ownKeys(Object(source)).forEach(function(key) {
+            Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
+        });
+    }
+    return target;
+}
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import React from "react";
 import { tv } from "tailwind-variants";
@@ -34,7 +58,34 @@ import Icon from "./Icon.js";
 import Text from "./Text.js";
 import { ChevronLeftMinor, ChevronRightMinor, ExternalMinor } from "@shopify/polaris-icons";
 import { useFrame } from "./Frame.js";
-var styles = tv({
+/**
+ * @component Navigation
+ *
+ * @description A sidebar navigation component that renders a vertical list of links and sections for primary app navigation within a Frame.
+ *
+ * @usage
+ * - DO: Use as the primary navigation sidebar within a Frame layout.
+ * - DON'T: Use for in-page content tabs (use Tabs).
+ *
+ * @accessibility
+ * - Renders as a `<nav>` element; ensure navigation items have descriptive labels.
+ *
+ * @alternative
+ * - If you need in-page tab switching, use `Tabs`. If you need a top bar, use `TopBar`.
+ *
+ * @param {Object} props - Component properties.
+ * @param {Object} [props.breadcrumb] - Breadcrumb navigation item.
+ * @param {string} [props.breadcrumb.content] - Label for the breadcrumb.
+ * @param {Function} [props.breadcrumb.onAction] - Callback for breadcrumb action.
+ * @param {Array<Object>} [props.sections] - Array of navigation sections.
+ * @param {Object} [props.sections[].title] - Section title configuration.
+ * @param {string} [props.sections[].title.label] - Title label.
+ * @param {boolean} [props.sections[].title.selected] - Whether the title is selected.
+ * @param {Function} [props.sections[].title.onAction] - Callback for title action.
+ * @param {Array<Object>} [props.sections[].links] - Array of link configurations for the section.
+ * @param {Array<Object>} [props.footerLinks] - Array of footer link configurations.
+ * @returns {JSX.Element} The rendered Navigation component.
+ */ var styles = tv({
     base: "Litho-Navigation h-full w-full pt-12 @md:pt-0 pr-2.5 pb-3 @md:pb-0 flex flex-col gap-2 justify-between bg-surface-normal"
 });
 var sectionStyles = tv({
@@ -51,24 +102,7 @@ var titleStyles = tv({
         }
     }
 });
-/**
- * Navigation component.
- * A sidebar navigation component for displaying links, sections, and footer links.
- *
- * @component
- * @param {Object} props - Component properties.
- * @param {Object} [props.breadcrumb] - Breadcrumb navigation item.
- * @param {string} [props.breadcrumb.content] - Label for the breadcrumb.
- * @param {Function} [props.breadcrumb.onAction] - Callback for breadcrumb action.
- * @param {Array<Object>} [props.sections] - Array of navigation sections.
- * @param {Object} [props.sections[].title] - Section title configuration.
- * @param {string} [props.sections[].title.label] - Title label.
- * @param {boolean} [props.sections[].title.selected] - Whether the title is selected.
- * @param {Function} [props.sections[].title.onAction] - Callback for title action.
- * @param {Array<Object>} [props.sections[].links] - Array of link configurations for the section.
- * @param {Array<Object>} [props.footerLinks] - Array of footer link configurations.
- * @returns {JSX.Element} The rendered Navigation component.
- */ function Navigation() {
+function Navigation() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var breadcrumb = props.breadcrumb, sections = props.sections, footerLinks = props.footerLinks;
     var setShowMobileNavigation = useFrame().setShowMobileNavigation;
@@ -90,7 +124,7 @@ var titleStyles = tv({
                         })
                     }),
                     sections && sections.map(function(section, index) {
-                        var _section_title, _section_title1;
+                        var _section_title, _section_title1, _section_title2;
                         if (!section.links) return null;
                         var titleClasses = titleStyles({
                             selected: (_section_title = section.title) === null || _section_title === void 0 ? void 0 : _section_title.selected,
@@ -106,17 +140,34 @@ var titleStyles = tv({
                         return /*#__PURE__*/ _jsxs("div", {
                             className: sectionClasses,
                             children: [
-                                section.title && /*#__PURE__*/ _jsx("div", {
+                                section.title && /*#__PURE__*/ _jsxs("div", _object_spread_props(_object_spread({
                                     className: titleClasses,
-                                    onClick: handleTitleClick,
-                                    children: /*#__PURE__*/ _jsx(Text, {
-                                        color: section.title.selected ? "link" : "normal",
-                                        fontWeight: "medium",
-                                        variant: "bodySm",
-                                        truncate: true,
-                                        children: section.title.label
-                                    })
-                                }),
+                                    onClick: handleTitleClick
+                                }, ((_section_title2 = section.title) === null || _section_title2 === void 0 ? void 0 : _section_title2.onAction) ? {
+                                    role: "button",
+                                    tabIndex: 0,
+                                    onKeyDown: function(e) {
+                                        if (e.key === "Enter" || e.key === " ") {
+                                            e.preventDefault();
+                                            handleTitleClick();
+                                        }
+                                    }
+                                } : {}), {
+                                    children: [
+                                        /*#__PURE__*/ _jsx(Text, {
+                                            color: section.title.selected ? "link" : "normal",
+                                            fontWeight: "medium",
+                                            variant: "bodySm",
+                                            truncate: true,
+                                            children: section.title.label
+                                        }),
+                                        section.title.onAction && /*#__PURE__*/ _jsx(Icon, {
+                                            source: ChevronRightMinor,
+                                            color: "subdued",
+                                            className: "opacity-50"
+                                        })
+                                    ]
+                                })),
                                 section.links.map(function(link, index) {
                                     return /*#__PURE__*/ _jsx(Navigation.Link, _object_spread({}, link), "navigation-link-".concat(index));
                                 })
@@ -206,9 +257,19 @@ var linkStyles = tv({
             showDividerAbove && /*#__PURE__*/ _jsx("div", {
                 className: "h-px w-full bg-tint-3 dark:bg-tint-alt-3 my-3"
             }),
-            /*#__PURE__*/ _jsxs("div", {
+            /*#__PURE__*/ _jsxs("div", _object_spread_props(_object_spread({
                 className: linkClasses,
-                onClick: handleClick,
+                onClick: handleClick
+            }, onAction ? {
+                role: "link",
+                tabIndex: 0,
+                onKeyDown: function(e) {
+                    if (e.key === "Enter") {
+                        e.preventDefault();
+                        handleClick();
+                    }
+                }
+            } : {}), {
                 children: [
                     /*#__PURE__*/ _jsxs("div", {
                         className: "flex items-center gap-2 truncate",
@@ -238,7 +299,7 @@ var linkStyles = tv({
                         className: "opacity-50"
                     }) : accessory ? accessory : null
                 ]
-            }),
+            })),
             (expanded || selected || subLinkIsSelected || grandChildLinkIsSelected) && !disclosure && subLinks && /*#__PURE__*/ _jsx("div", {
                 className: "flex flex-col mb-3",
                 children: subLinks.map(function(subLink, index) {
@@ -296,9 +357,19 @@ var subLinkStyles = tv({
             setShowMobileNavigation(false);
         }
     };
-    return /*#__PURE__*/ _jsxs("div", {
+    return /*#__PURE__*/ _jsxs("div", _object_spread_props(_object_spread({
         className: subLinkClasses,
-        onClick: handleClick,
+        onClick: handleClick
+    }, onAction ? {
+        role: "link",
+        tabIndex: 0,
+        onKeyDown: function(e) {
+            if (e.key === "Enter") {
+                e.preventDefault();
+                handleClick();
+            }
+        }
+    } : {}), {
         children: [
             /*#__PURE__*/ _jsxs("div", {
                 className: "flex items-center gap-2",
@@ -321,7 +392,7 @@ var subLinkStyles = tv({
             })),
             accessory
         ]
-    });
+    }));
 }
 Navigation.SubLink = SubLink;
 export default Navigation;

package/dist/esm/components/Page.js

@@ -106,7 +106,46 @@ import Popover from "./Popover.js";
 import ActionList from "./ActionList.js";
 import { ArrowLeftMinor, MobileHorizontalDotsMajor } from "@shopify/polaris-icons";
 import { useFrame } from "./Frame.js";
-var styles = tv({
+/**
+ * @component Page
+ *
+ * @description A top-level page container that renders a title bar with heading, breadcrumbs, actions, and a content area.
+ *
+ * @usage
+ * - DO: Use as the root container for each page view with title and primary/secondary actions.
+ * - DON'T: Nest Page inside another Page.
+ *
+ * @accessibility
+ * - Page title renders as the main heading; ensure it accurately describes the page content.
+ *
+ * @alternative
+ * - If you need a simple container without page-level chrome, use `Card` or `Layout`.
+ *
+ * @param {Object} props - Props for the component.
+ * @param {string|React.ReactNode} props.title - The title of the page. Can be a string or React element.
+ * @param {string|React.ReactNode} props.subtitle - The subtitle of the page. Can be a string or React element.
+ * @param {Object} [props.backAction] - Configuration for the back action button.
+ * @param {Function} [props.backAction.onAction] - Callback when the back action is triggered.
+ * @param {string} [props.backAction.accessibilityLabel] - Accessibility label for the back action button.
+ * @param {boolean} [props.narrowWidth=false] - Whether to use a narrow width layout.
+ * @param {boolean} [props.fullWidth=false] - Whether to use a full-width layout.
+ * @param {boolean} [props.showTitleInTopBar=true] - Whether to show the title in the top bar area.
+ * @param {boolean} [props.wrapInContentContainer=true] - Whether to wrap the content in a container with padding.
+ * @param {Object} [props.primaryAction] - Configuration for the primary action button.
+ * @param {Function} [props.primaryAction.onAction] - Callback when the primary action is triggered.
+ * @param {boolean} [props.primaryAction.loading] - Whether the primary action button is in a loading state.
+ * @param {boolean} [props.primaryAction.disabled] - Whether the primary action button is disabled.
+ * @param {boolean} [props.primaryAction.destructive] - Whether the primary action button is styled as destructive.
+ * @param {string} [props.primaryAction.tooltip] - Tooltip to show when hovering over the primary action button.
+ * @param {React.ReactNode} [props.primaryAction.content="Save"] - Content for the primary action button.
+ * @param {Object[]} [props.secondaryActions=[]] - List of secondary actions.
+ * @param {string} [props.moreActionsLabel="Actions"] - Label for the "More Actions" button in mobile view.
+ * @param {React.ReactNode} [props.titleMetadata] - Metadata displayed alongside the title.
+ * @param {React.ReactNode} [props.children] - Content for the main section of the page.
+ * @param {Object} [props.footerActions] - Configuration for the footer actions.
+ * @param {string} [props.className] - Additional CSS classes for the Page.
+ * @returns {React.ReactElement} Rendered Page component.
+ */ var styles = tv({
     base: "Litho-Page w-full mx-auto",
     variants: {
         narrowWidth: {
@@ -178,36 +217,7 @@ var contentStyles = tv({
         wrapInContentContainer: true
     }
 });
-/**
- * Page component that provides a structured layout with a header, primary and secondary actions, and content.
- *
- * @component
- *
- * @param {Object} props - Props for the component.
- * @param {string|React.ReactNode} props.title - The title of the page. Can be a string or React element.
- * @param {string|React.ReactNode} props.subtitle - The subtitle of the page. Can be a string or React element.
- * @param {Object} [props.backAction] - Configuration for the back action button.
- * @param {Function} [props.backAction.onAction] - Callback when the back action is triggered.
- * @param {string} [props.backAction.accessibilityLabel] - Accessibility label for the back action button.
- * @param {boolean} [props.narrowWidth=false] - Whether to use a narrow width layout.
- * @param {boolean} [props.fullWidth=false] - Whether to use a full-width layout.
- * @param {boolean} [props.showTitleInTopBar=true] - Whether to show the title in the top bar area.
- * @param {boolean} [props.wrapInContentContainer=true] - Whether to wrap the content in a container with padding.
- * @param {Object} [props.primaryAction] - Configuration for the primary action button.
- * @param {Function} [props.primaryAction.onAction] - Callback when the primary action is triggered.
- * @param {boolean} [props.primaryAction.loading] - Whether the primary action button is in a loading state.
- * @param {boolean} [props.primaryAction.disabled] - Whether the primary action button is disabled.
- * @param {boolean} [props.primaryAction.destructive] - Whether the primary action button is styled as destructive.
- * @param {string} [props.primaryAction.tooltip] - Tooltip to show when hovering over the primary action button.
- * @param {React.ReactNode} [props.primaryAction.content="Save"] - Content for the primary action button.
- * @param {Object[]} [props.secondaryActions=[]] - List of secondary actions.
- * @param {string} [props.moreActionsLabel="Actions"] - Label for the "More Actions" button in mobile view.
- * @param {React.ReactNode} [props.titleMetadata] - Metadata displayed alongside the title.
- * @param {React.ReactNode} [props.children] - Content for the main section of the page.
- * @param {Object} [props.footerActions] - Configuration for the footer actions.
- * @param {string} [props.className] - Additional CSS classes for the Page.
- * @returns {React.ReactElement} Rendered Page component.
- */ function Page() {
+function Page() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var title = props.title, subtitle = props.subtitle, _props_showTitleInTopBar = props.showTitleInTopBar, showTitleInTopBar = _props_showTitleInTopBar === void 0 ? true : _props_showTitleInTopBar, tmp = props.backAction, _backAction = tmp === void 0 ? null : tmp, children = props.children, narrowWidth = props.narrowWidth, fullWidth = props.fullWidth, primaryAction = props.primaryAction, _props_secondaryActions = props.secondaryActions, secondaryActions = _props_secondaryActions === void 0 ? [] : _props_secondaryActions, titleMetadata = props.titleMetadata, _props_moreActionsLabel = props.moreActionsLabel, moreActionsLabel = _props_moreActionsLabel === void 0 ? "Actions" : _props_moreActionsLabel, _props_wrapInContentContainer = props.wrapInContentContainer, wrapInContentContainer = _props_wrapInContentContainer === void 0 ? true : _props_wrapInContentContainer, footerActions = props.footerActions, className = props.className;
     var paneIsOpen = useFrame().paneIsOpen;
@@ -368,6 +378,7 @@ var contentStyles = tv({
                                                             disclosure: true,
                                                             insight: action.insight,
                                                             icon: action.icon,
+                                                            pressed: action.pressed,
                                                             onClick: function() {
                                                                 return togglePopover(index);
                                                             },
@@ -384,6 +395,7 @@ var contentStyles = tv({
                                                 return /*#__PURE__*/ _jsx(Button, {
                                                     plain: !action.destructive && !action.insight,
                                                     onClick: action.onAction || action.onClick,
+                                                    pressed: action.pressed,
                                                     disabled: action.disabled,
                                                     icon: action.icon,
                                                     loading: action.loading,
@@ -406,6 +418,7 @@ var contentStyles = tv({
                                     url: primaryAction.url,
                                     loading: primaryAction.loading,
                                     disabled: primaryAction.disabled,
+                                    pressed: primaryAction.pressed,
                                     destructive: primaryAction.destructive,
                                     tooltip: primaryAction.tooltip,
                                     connectedDisclosure: primaryAction.connectedDisclosure,