@heymantle/litho 0.0.14 → 0.0.16

package/dist/esm/components/Frame.js

@@ -56,7 +56,39 @@ import FrameSaveBar from "./FrameSaveBar.js";
 import TopBar from "./TopBar.js";
 import Popover from "./Popover.js";
 import ActionList from "./ActionList.js";
-var frameStyles = tv({
+/**
+ * @component Frame
+ *
+ * @description The root application layout shell that provides navigation sidebar, top bar, mobile nav, and contextual save bar slots.
+ *
+ * @usage
+ * - DO: Use as the root layout wrapper providing navigation sidebar, top bar, and main content area.
+ * - DON'T: Nest Frame inside another Frame.
+ *
+ * @accessibility
+ * - Frame establishes landmark regions (nav, main, header) for screen reader navigation.
+ *
+ * @alternative
+ * - If you need a simple page container without app shell chrome, use `Page` or `Layout`.
+ *
+ * @param {Object} props - Props for the Frame component.
+ * @param {React.ReactNode} props.navigation - Component to render as the navigation menu.
+ * @param {React.ReactNode} props.announcement - Component to render an announcement bar.
+ * @param {Object} props.logo - Logo configuration.
+ * @param {string} props.logo.url - URL for the logo link.
+ * @param {string} props.logo.source - Source for the logo image.
+ * @param {string} props.logo.accessibilityLabel - Accessibility label for the logo image.
+ * @param {number} props.logo.width - Width of the logo image.
+ * @param {boolean} props.showSearchTrigger - Whether to show the search trigger.
+ * @param {React.ReactNode} props.searchModal - Modal to render as the search modal.
+ * @param {function} props.onToggleSearch - Function to toggle the search modal.
+ * @param {boolean} [props.enableSearchShortcut=true] - Whether to register the Cmd+K keyboard shortcut for search.
+ * @param {string} [props.className] - Additional CSS classes for the Frame.
+ * @param {React.ReactNode} props.children - Content to render within the Frame.
+ * @param {boolean} [props.alwaysShowUserMenuInTopBar] - Whether to always show the user menu in the top bar.
+ * @param {React.ReactNode} [props.headerAccessory] - Accessory to render in the header.
+ * @returns {React.ReactElement} The rendered Frame component.
+ */ var frameStyles = tv({
     base: "Litho-Frame bg-surface-normal",
     variants: {
         paneIsOpen: {
@@ -147,26 +179,7 @@ var logoStyles = tv({
         alwaysShowLogo: false
     }
 });
-/**
- * Frame component that provides a layout structure with top bar, navigation, logo, and content.
- * @param {Object} props - Props for the Frame component.
- * @param {React.ReactNode} props.navigation - Component to render as the navigation menu.
- * @param {React.ReactNode} props.announcement - Component to render an announcement bar.
- * @param {Object} props.logo - Logo configuration.
- * @param {string} props.logo.url - URL for the logo link.
- * @param {string} props.logo.source - Source for the logo image.
- * @param {string} props.logo.accessibilityLabel - Accessibility label for the logo image.
- * @param {number} props.logo.width - Width of the logo image.
- * @param {boolean} props.showSearchTrigger - Whether to show the search trigger.
- * @param {React.ReactNode} props.searchModal - Modal to render as the search modal.
- * @param {function} props.onToggleSearch - Function to toggle the search modal.
- * @param {boolean} [props.enableSearchShortcut=true] - Whether to register the Cmd+K keyboard shortcut for search.
- * @param {string} [props.className] - Additional CSS classes for the Frame.
- * @param {React.ReactNode} props.children - Content to render within the Frame.
- * @param {boolean} [props.alwaysShowUserMenuInTopBar] - Whether to always show the user menu in the top bar.
- * @param {React.ReactNode} [props.headerAccessory] - Accessory to render in the header.
- * @returns {React.ReactElement} The rendered Frame component.
- */ var Frame = function(param) {
+var Frame = function(param) {
     var navigation = param.navigation, announcement = param.announcement, logo = param.logo, children = param.children, className = param.className, userMenu = param.userMenu, moreActions = param.moreActions, _param_showSearchTrigger = param.showSearchTrigger, showSearchTrigger = _param_showSearchTrigger === void 0 ? true : _param_showSearchTrigger, _param_alwaysShowUserMenuInTopBar = param.alwaysShowUserMenuInTopBar, alwaysShowUserMenuInTopBar = _param_alwaysShowUserMenuInTopBar === void 0 ? false : _param_alwaysShowUserMenuInTopBar, _param_searchLabel = param.searchLabel, searchLabel = _param_searchLabel === void 0 ? "Search" : _param_searchLabel, _param_searchIcon = param.searchIcon, searchIcon = _param_searchIcon === void 0 ? /*#__PURE__*/ _jsx(Icon, {
         source: SearchMajor,
         color: "subdued"
@@ -200,6 +213,10 @@ var logoStyles = tv({
                 document.documentElement.style.setProperty("--litho-top-bar-height", "56px");
                 document.documentElement.style.setProperty("--litho-table-header-sticky-at", "56px");
             }
+        } else {
+            document.documentElement.style.setProperty("--litho-header-offset", "0px");
+            document.documentElement.style.setProperty("--litho-top-bar-height", "56px");
+            document.documentElement.style.setProperty("--litho-table-header-sticky-at", "56px");
         }
     }, [
         announcement
@@ -237,6 +254,15 @@ var logoStyles = tv({
         onClick: function() {
             return onToggleSearch();
         },
+        role: "button",
+        tabIndex: 0,
+        "aria-label": searchLabel,
+        onKeyDown: function(e) {
+            if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                onToggleSearch();
+            }
+        },
         children: [
             searchIcon,
             /*#__PURE__*/ _jsxs("div", {
@@ -259,7 +285,7 @@ var logoStyles = tv({
             paneIsOpen: paneIsOpen
         }), " ").concat(className),
         children: /*#__PURE__*/ _jsxs("div", {
-            className: embedded ? "" : "@container",
+            className: embedded ? "" : "@container/main",
             children: [
                 !contentIsFullPage && /*#__PURE__*/ _jsx("div", {
                     className: logoStyles({
@@ -370,6 +396,15 @@ var logoStyles = tv({
                             },
                             children: /*#__PURE__*/ _jsx("div", {
                                 className: "fixed cursor-pointer top-2.5 @md:hidden p-2 rounded-full bg-tint-10 hover:bg-tint-12 dark:bg-tint-alt-10 dark:hover:bg-tint-alt-12 left-56.5",
+                                role: "button",
+                                tabIndex: 0,
+                                "aria-label": "Close navigation",
+                                onKeyDown: function(e) {
+                                    if (e.key === "Enter" || e.key === " ") {
+                                        e.preventDefault();
+                                        setShowMobileNavigation(false);
+                                    }
+                                },
                                 children: /*#__PURE__*/ _jsx(Icon, {
                                     source: CancelMajor,
                                     color: "alternate"

package/dist/esm/components/FrameSaveBar.js

@@ -55,7 +55,24 @@ import Icon from "./Icon.js";
 import Tooltip from "./Tooltip.js";
 import { ChevronUpMinor, ChevronDownMinor } from "@shopify/polaris-icons";
 import { useFrame } from "./Frame.js";
-var styles = tv({
+/**
+ * @component FrameSaveBar
+ *
+ * @description A save bar component embedded within the Frame layout that displays save and discard actions for unsaved form changes.
+ *
+ * @usage
+ * - DO: Use within a Frame layout to show a contextual save bar that integrates with the app shell.
+ * - DON'T: Use without a Frame parent.
+ *
+ * @accessibility
+ * - Keyboard accessible save and discard actions; message text describes the unsaved context.
+ *
+ * @alternative
+ * - If you need a standalone save bar outside Frame, use `ContextualSaveBar`.
+ *
+ * @param {Object} props.logo - Logo configuration.
+ * @returns {JSX.Element} The rendered FrameSaveBar component
+ */ var styles = tv({
     base: "Litho-FrameSaveBar fixed top-[var(--litho-header-offset)] right-0 left-0 h-[var(--litho-header-height)] px-4 @md:px-5 flex items-center gap-2 bg-surface-alternate dark:bg-brand transition-opacity transition-transform duration-300 transform",
     variants: {
         visible: {
@@ -94,11 +111,7 @@ var toggleStyles = tv({
         paneIsOpen: false
     }
 });
-/**
- * FrameSaveBar component sisplays a save bar at the top of the screen with contextual save and discard actions.
- * @param {Object} props.logo - Logo configuration.
- * @returns {JSX.Element} The rendered FrameSaveBar component
- */ function FrameSaveBar(param) {
+function FrameSaveBar(param) {
     var logo = param.logo;
     var darkMode = useDarkMode().darkMode;
     var paneIsOpen = useFrame().paneIsOpen;
@@ -145,6 +158,15 @@ var toggleStyles = tv({
                         onClick: function() {
                             return setTucked(false);
                         },
+                        role: "button",
+                        tabIndex: 0,
+                        "aria-label": "Show save bar",
+                        onKeyDown: function(e) {
+                            if (e.key === "Enter" || e.key === " ") {
+                                e.preventDefault();
+                                setTucked(false);
+                            }
+                        },
                         children: /*#__PURE__*/ _jsx(Icon, {
                             source: ChevronDownMinor,
                             color: "FrameSaveBar"
@@ -192,6 +214,15 @@ var toggleStyles = tv({
                                                 onClick: function() {
                                                     return setTucked(true);
                                                 },
+                                                role: "button",
+                                                tabIndex: 0,
+                                                "aria-label": "Hide save bar",
+                                                onKeyDown: function(e) {
+                                                    if (e.key === "Enter" || e.key === " ") {
+                                                        e.preventDefault();
+                                                        setTucked(true);
+                                                    }
+                                                },
                                                 children: /*#__PURE__*/ _jsx(Icon, {
                                                     source: ChevronUpMinor,
                                                     color: "FrameSaveBar"

package/dist/esm/components/Grid.js

@@ -50,7 +50,31 @@ function _unsupported_iterable_to_array(o, minLen) {
 }
 import { jsx as _jsx } from "react/jsx-runtime";
 import { tv } from "tailwind-variants";
-// Map semantic gap values to numeric Tailwind values
+/**
+ * @component Grid
+ *
+ * @description A CSS grid layout component for arranging children in a two-dimensional grid with configurable columns and gap.
+ *
+ * @usage
+ * - DO: Use for two-dimensional layouts with rows and columns.
+ * - DON'T: Use for simple linear stacking (use `Stack` instead).
+ *
+ * @accessibility
+ * - Grid is a layout utility; ensure grid items maintain a logical tab and reading order.
+ *
+ * @alternative
+ * - If you need one-dimensional flex layout, use `Stack` instead.
+ * - If you need a simple two-column layout, use `Layout`.
+ *
+ * @param {object} [props={}] - Props for the Grid component.
+ * @param {React.ReactNode} [props.children] - Content to render inside the Grid.
+ * @param {number|object} [props.columns] - Defines the number of columns in the grid. Can be a single number or an object with breakpoints as keys.
+ * @param {(number|'none'|'xs'|'sm'|'md'|'lg'|object)} [props.gap] - Defines the gap between grid items. Can be a number, semantic value ('none', 'xs', 'sm', 'md', 'lg'), or an object with breakpoints as keys. Semantic values: 'none' (0), 'xs' (1), 'sm' (2), 'md' (4), 'lg' (8).
+ * @param {"stretch"|"start"|"end"|"center"} [props.justify="stretch"] - Horizontal alignment of the grid items.
+ * @param {"stretch"|"start"|"end"|"center"} [props.align="stretch"] - Vertical alignment of the grid items.
+ * @param {string} [props.className] - Additional class names to apply to the grid.
+ * @returns {JSX.Element} A div element representing the grid container.
+ */ // Map semantic gap values to numeric Tailwind values
 var gapMap = {
     none: "0",
     xs: "1",
@@ -79,18 +103,7 @@ var styles = tv({
         align: "stretch"
     }
 });
-/**
- * Tailwind-based Grid component with customizable columns, gaps, alignment, and justification.
- *
- * @param {object} [props={}] - Props for the Grid component.
- * @param {React.ReactNode} [props.children] - Content to render inside the Grid.
- * @param {number|object} [props.columns] - Defines the number of columns in the grid. Can be a single number or an object with breakpoints as keys.
- * @param {(number|'none'|'xs'|'sm'|'md'|'lg'|object)} [props.gap] - Defines the gap between grid items. Can be a number, semantic value ('none', 'xs', 'sm', 'md', 'lg'), or an object with breakpoints as keys. Semantic values: 'none' (0), 'xs' (1), 'sm' (2), 'md' (4), 'lg' (8).
- * @param {"stretch"|"start"|"end"|"center"} [props.justify="stretch"] - Horizontal alignment of the grid items.
- * @param {"stretch"|"start"|"end"|"center"} [props.align="stretch"] - Vertical alignment of the grid items.
- * @param {string} [props.className] - Additional class names to apply to the grid.
- * @returns {JSX.Element} A div element representing the grid container.
- */ function Grid() {
+function Grid() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var children = props.children, columns = props.columns, _props_gap = props.gap, gap = _props_gap === void 0 ? "md" : _props_gap, _props_justify = props.justify, justify = _props_justify === void 0 ? "stretch" : _props_justify, _props_align = props.align, align = _props_align === void 0 ? "stretch" : _props_align, className = props.className;
     var columnClasses;
@@ -128,8 +141,11 @@ var styles = tv({
 }
 ;
 /**
- * Cell component for the Grid, allowing column span customization.
- * 
+ * @component Grid.Cell
+ *
+ * @usage
+ * - DO: Wrap grid children to control column/row span.
+ *
  * @param {object} [props={}] - Props for the Cell component.
  * @param {number|object} [props.columnSpan] - Defines the column span for the cell. Can be a single number or an object with breakpoints as keys.
  * @param {React.ReactNode} [props.children] - Content to render inside the cell.

package/dist/esm/components/HorizontalStack.js

@@ -79,7 +79,43 @@ function _object_without_properties_loose(source, excluded) {
 }
 import { jsx as _jsx } from "react/jsx-runtime";
 import { tv } from "tailwind-variants";
-var styles = tv({
+/**
+ * @component HorizontalStack
+ *
+ * @description A horizontal flex layout component for arranging children in a row with consistent spacing and alignment.
+ *
+ * @deprecated Use `Stack` with `horizontal` boolean prop set to true instead. This component will be removed in a future release.
+ *
+ * @usage
+ * - DO: Arrange elements horizontally with consistent spacing.
+ * - DON'T: Use for vertical stacking (use `VerticalStack` or `Stack` instead).
+ *
+ * @accessibility
+ * - Ensure content order in the DOM matches the visual horizontal order for screen readers.
+ *
+ * @alternative
+ * - If you need vertical stacking, use `VerticalStack`.
+ * - If you need flexible direction, use `Stack`.
+ *
+ * @param {Object} [props={}] - Component props.
+ * @param {string} [props.as='div'] - The HTML element to render. Defaults to `div`.
+ * @param {React.ReactNode} [props.children] - Child elements to render inside the stack.
+ * @param {('none'|'xs'|'sm'|'md'|'lg'|'0'|'px'|'0.5'|'1'|'2'|'3'|'4'|'5'|'6'|'8'|'10')} [props.gap] - Spacing between children. Semantic options: 'none', 'xs' (1), 'sm' (2), 'md' (4), 'lg' (8). Numeric options: '0', 'px', '0.5', '1', '2', '3', '4', '5', '6', '8', '10'.
+ * @param {string} [props.id] - Optional ID for the component.
+ * @param {string} [props.className] - Additional custom class names to apply to the component.
+ * @param {string} [props.align='start'] - Horizontal alignment of children. Options: 'start', 'center', 'end'.
+ * @param {string} [props.blockAlign='start'] - Vertical alignment of children. Options: 'start', 'center', 'end'.
+ * @param {boolean} [props.wrap=true] - Whether children should wrap to the next line if necessary. Defaults to `true`.
+ * @param {Object} [restProps] - Additional props passed to the root element.
+ *
+ * @returns {JSX.Element} The rendered HorizontalStack component.
+ *
+ * @example
+ * <HorizontalStack gap="2" align="center" blockAlign="start">
+ *   <div>Item 1</div>
+ *   <div>Item 2</div>
+ * </HorizontalStack>
+ */ var styles = tv({
     base: "Litho-HorizontalStack flex flex-row",
     variants: {
         gap: {
@@ -125,30 +161,7 @@ var styles = tv({
         blockAlign: "start"
     }
 });
-/**
- * HorizontalStack Component
- *
- * A flexible horizontal stack component with customizable spacing, alignment, and wrapping.
- *
- * @param {Object} [props={}] - Component props.
- * @param {string} [props.as='div'] - The HTML element to render. Defaults to `div`.
- * @param {React.ReactNode} [props.children] - Child elements to render inside the stack.
- * @param {('none'|'xs'|'sm'|'md'|'lg'|'0'|'px'|'0.5'|'1'|'2'|'3'|'4'|'5'|'6'|'8'|'10')} [props.gap] - Spacing between children. Semantic options: 'none', 'xs' (1), 'sm' (2), 'md' (4), 'lg' (8). Numeric options: '0', 'px', '0.5', '1', '2', '3', '4', '5', '6', '8', '10'.
- * @param {string} [props.id] - Optional ID for the component.
- * @param {string} [props.className] - Additional custom class names to apply to the component.
- * @param {string} [props.align='start'] - Horizontal alignment of children. Options: 'start', 'center', 'end'.
- * @param {string} [props.blockAlign='start'] - Vertical alignment of children. Options: 'start', 'center', 'end'.
- * @param {boolean} [props.wrap=true] - Whether children should wrap to the next line if necessary. Defaults to `true`.
- * @param {Object} [restProps] - Additional props passed to the root element.
- *
- * @returns {JSX.Element} The rendered HorizontalStack component.
- *
- * @example
- * <HorizontalStack gap="2" align="center" blockAlign="start" wrap={false}>
- *   <div>Item 1</div>
- *   <div>Item 2</div>
- * </HorizontalStack>
- */ function HorizontalStack() {
+function HorizontalStack() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var _props_as = props.as, as = _props_as === void 0 ? 'div' : _props_as, children = props.children, gap = props.gap, id = props.id, className = props.className, align = props.align, blockAlign = props.blockAlign, _props_wrap = props.wrap, wrap = _props_wrap === void 0 ? true : _props_wrap, restProps = _object_without_properties(props, [
         "as",