@heymantle/litho 0.0.15 → 0.0.16

package/dist/esm/components/Autocomplete.js

@@ -119,42 +119,21 @@ import Spinner from "./Spinner.js";
 import Text from "./Text.js";
 import Icon from "./Icon.js";
 import { SearchMinor } from "@shopify/polaris-icons";
-var styles = tv({
-    base: "Litho-Autocomplete flex flex-col"
-});
-function attachPropToTextField(children, prop) {
-    return React.Children.map(children, function(child) {
-        if (/*#__PURE__*/ isValidElement(child)) {
-            var _child_type, _child_props;
-            if (((_child_type = child.type) === null || _child_type === void 0 ? void 0 : _child_type.displayName) === "Autocomplete.TextField") {
-                return /*#__PURE__*/ cloneElement(child, prop);
-            }
-            if ((_child_props = child.props) === null || _child_props === void 0 ? void 0 : _child_props.children) {
-                return /*#__PURE__*/ cloneElement(child, {
-                    children: attachPropToTextField(child.props.children, prop)
-                });
-            }
-        }
-        return child;
-    });
-}
 /**
- * @typedef {Object} AutocompleteOption
- * @property {string|React.ReactNode} label - The label to display for the option. Can be a string or a React element (e.g., text with a badge).
- * @property {string} value - The value to associate with the option.
- * @property {string} [title] - An optional title to display for the option.
- * @property {boolean} [allowMultiple] - Whether multiple options can be selected.
- * @property {string} [selected] - The value of the option that is currently selected.
- * @property {function} [onSelect] - The function to call when the option is selected.
- * @property {Array<AutocompleteOption>} [options] - An optional array of sub-options to display for the option.
- */ /**
- * @typedef {Object} AutocompleteEmptyState
- * @property {string} content - The content to display in the empty state.
- * @property {React.ReactNode} icon - An optional icon to display in the empty state.
- */ /**
- * Autocomplete component that provides a flexible dropdown menu with search and selection capabilities.
+ * @component Autocomplete
+ *
+ * @description A searchable text input with a dropdown suggestions list for selecting from filtered options.
+ *
+ * @usage
+ * - DO: Use for selecting from a large list with search/filter capability.
+ * - DON'T: Use for short static lists. Instead, use Select (when list is more than 7 items, or dynamic but doesn't need search) or ChoiceList (when list is less than 7 items and static).
+ *
+ * @accessibility
+ * - Implements combobox pattern with `aria-expanded` and `aria-activedescendant`; keyboard navigable.
+ *
+ * @alternative
+ * - If the option list is short and static, use `Select`. If you need a custom dropdown, use `Listbox`.
  *
- * @component
  * @param {Object} props - The props for the Autocomplete component.
  * @param {Array<AutocompleteOption>} props.options - The options to display in the dropdown.
  * @param {Array<string>} props.selected - The currently selected option values.
@@ -184,7 +163,7 @@ function attachPropToTextField(children, prop) {
  * <Autocomplete
  *   options={[
  *     {
- *       label: <Stack horizontal gap="xs" blockAlign="center"><span>Premium</span><Badge>New</Badge></Stack>,
+ *       label: <Stack horizontal gap="xs" align="center"><span>Premium</span><Badge>New</Badge></Stack>,
  *       value: "premium"
  *     }
  *   ]}
@@ -192,7 +171,39 @@ function attachPropToTextField(children, prop) {
  *   onSelect={(selected) => console.log(selected)}
  *   textField={<Autocomplete.TextField placeholder="Search..." />}
  * />
- */ function Autocomplete() {
+ */ var styles = tv({
+    base: "Litho-Autocomplete flex flex-col"
+});
+/**
+ * @typedef {Object} AutocompleteOption
+ * @property {string|React.ReactNode} label - The label to display for the option. Can be a string or a React element (e.g., text with a badge).
+ * @property {string} value - The value to associate with the option.
+ * @property {string} [title] - An optional title to display for the option.
+ * @property {boolean} [allowMultiple] - Whether multiple options can be selected.
+ * @property {string} [selected] - The value of the option that is currently selected.
+ * @property {function} [onSelect] - The function to call when the option is selected.
+ * @property {Array<AutocompleteOption>} [options] - An optional array of sub-options to display for the option.
+ */ /**
+ * @typedef {Object} AutocompleteEmptyState
+ * @property {string} content - The content to display in the empty state.
+ * @property {React.ReactNode} icon - An optional icon to display in the empty state.
+ */ function attachPropToTextField(children, prop) {
+    return React.Children.map(children, function(child) {
+        if (/*#__PURE__*/ isValidElement(child)) {
+            var _child_type, _child_props;
+            if (((_child_type = child.type) === null || _child_type === void 0 ? void 0 : _child_type.displayName) === "Autocomplete.TextField") {
+                return /*#__PURE__*/ cloneElement(child, prop);
+            }
+            if ((_child_props = child.props) === null || _child_props === void 0 ? void 0 : _child_props.children) {
+                return /*#__PURE__*/ cloneElement(child, {
+                    children: attachPropToTextField(child.props.children, prop)
+                });
+            }
+        }
+        return child;
+    });
+}
+function Autocomplete() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var options = props.options, selected = props.selected, _props_preferredPosition = props.preferredPosition, preferredPosition = _props_preferredPosition === void 0 ? "below" : _props_preferredPosition, _props_preferredAlignment = props.preferredAlignment, preferredAlignment = _props_preferredAlignment === void 0 ? "left" : _props_preferredAlignment, allowMultiple = props.allowMultiple, loading = props.loading, emptyState = props.emptyState, onSelect = props.onSelect, textField = props.textField, className = props.className, zIndexOverride = props.zIndexOverride;
     var classes = styles();
@@ -236,6 +247,17 @@ function attachPropToTextField(children, prop) {
                 ]);
                 setShowOptionsPopover && setShowOptionsPopover(false);
             },
+            role: "option",
+            tabIndex: 0,
+            onKeyDown: function(e) {
+                if (e.key === "Enter" || e.key === " ") {
+                    e.preventDefault();
+                    onSelect([
+                        option.value
+                    ]);
+                    setShowOptionsPopover && setShowOptionsPopover(false);
+                }
+            },
             children: option.label
         });
     };

package/dist/esm/components/Badge.js

@@ -1,7 +1,32 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { tv } from "tailwind-variants";
-var styles = tv({
-    base: "Litho-Badge inline-flex items-center gap-1.5 text-sm rounded-full leading-normal min-h-5.5",
+/**
+ * @component Badge
+ *
+ * @description A small status indicator that displays a short label with a color-coded background to convey state like success, warning, or attention.
+ *
+ * @usage
+ * - DO: Convey status (success, warning, critical) on list items or table rows.
+ * - DON'T: Use for interactive or clickable elements (use Button or Tag).
+ * - DON'T: Overuse. Badges have a lot of visual weight, so use them sparingly. Consider using a Text component if content doesn't need to be prioritized over other content.
+ *
+ * @accessibility
+ * - Badge content is read as inline text; ensure status text is descriptive.
+ * - Do not rely on color alone to convey meaning.
+ *
+ * @alternative
+ * - If you need a removable label, use `Tag`.
+ * - If you need a full-sentence status message, use `Banner`.
+ *
+ * @param {object} props - Component properties.
+ * @param {React.ReactNode} props.children - Content to display within the badge.
+ * @param {"complete" | "incomplete" | "partiallyComplete" | null} [props.progress] - Progress state of the badge.
+ * @param {boolean} [props.capitalize] - Capitalize the first letter of the badge.
+ * @param {"default" | "info" | "success" | "warning" | "critical" | "attention" | "highlight"} [props.status="default"] - Status variant to style the badge.
+ * @param {string} [props.className] - Additional CSS classes to apply to the badge.
+ * @returns {JSX.Element} - Rendered Badge component with optional progress indicator.
+ */ var styles = tv({
+    base: "Litho-Badge inline-flex items-center gap-1.5 text-sm rounded-full leading-normal min-h-5",
     variants: {
         status: {
             info: "bg-info-alt text-info-alt-fg",
@@ -186,18 +211,7 @@ var progressBadgeStyles = tv({
         progress: "null"
     }
 });
-/**
- * A Badge component that renders a small, colored label with a status or progress indicator. The badge can be configured with different statuses, progress states, and sizes.
- *
- * @component
- * @param {object} props - Component properties.
- * @param {React.ReactNode} props.children - Content to display within the badge.
- * @param {"complete" | "incomplete" | "partiallyComplete" | null} [props.progress] - Progress state of the badge.
- * @param {boolean} [props.capitalize] - Capitalize the first letter of the badge.
- * @param {"default" | "info" | "success" | "warning" | "critical" | "attention" | "highlight"} [props.status="default"] - Status variant to style the badge.
- * @param {string} [props.className] - Additional CSS classes to apply to the badge.
- * @returns {JSX.Element} - Rendered Badge component with optional progress indicator.
- */ function Badge() {
+function Badge() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var children = props.children, progress = props.progress, status = props.status, capitalize = props.capitalize, className = props.className;
     var classes = styles({

package/dist/esm/components/Banner.js

@@ -6,7 +6,43 @@ import Text from "./Text.js";
 import Button from "./Button.js";
 import Link from "./Link.js";
 import { CancelMinor, CircleAlertMajor, CircleInformationMajor, MagicMajor, TickMinor } from "@shopify/polaris-icons";
-var styles = tv({
+/**
+ * @component Banner
+ *
+ * @description A contextual message bar that displays informational, success, warning, or critical notices with optional actions and dismiss functionality.
+ *
+ * @usage
+ * - DO: Display important contextual messages at the top of a page or section (info, success, warning, critical).
+ * - DON'T: Use for transient notifications (use ToastNotification).
+ *
+ * @accessibility
+ * - Banner uses `role="status"` or appropriate ARIA role based on status; ensure the message text is descriptive.
+ *
+ * @alternative
+ * - If you need a brief, auto-dismissing notification, use `ToastNotification`.
+ * - If you need a contextual hint, use `Tip`.
+ *
+ * @param {Object} props - The properties for configuring the Banner component.
+ * @param {string} [props.title] - The title text for the banner. If not provided, no title will be displayed.
+ * @param {BannerStatus} [props.status='neutral'] - The status of the banner, which determines its color and icon.
+ * @param {Function} [props.onDismiss] - Callback function to handle the banner's dismiss action.
+ * @param {React.ReactNode} [props.children] - Additional content to display within the banner.
+ * @param {BannerAction} [props.action] - Primary action configuration object
+ * @param {BannerAction} [props.secondaryAction] - Secondary action configuration object
+ * @param {FunctionComponent} [props.icon] - Custom icon to display on the banner. If not provided, a default icon is used based on the status.
+ * @param {boolean} [props.spinner] - Shows a spinner icon instead of a status icon when set to true.
+ *
+ * @returns {JSX.Element} The rendered Banner component.
+ *
+ * @example
+ * <Banner
+ *   title="Warning"
+ *   status="warning"
+ *   onDismiss={() => console.log('Dismissed')}
+ *   action={{ content: "Action", primary: true, onAction: () => console.log('Action clicked') }}
+ *   secondaryAction={{ content: "Learn more", link: true, monochrome: true, url: "https://example.com" }}
+ * />
+ */ var styles = tv({
     base: "Litho-Banner relative rounded-md shadow-card bg-surface-highest outline outline-tint-3"
 });
 var headerStyles = tv({
@@ -97,32 +133,6 @@ var STATUS_STYLES = {
  * @property {boolean} [loading=false] - Whether to show a loading state
  * @property {Function} [onAction] - Click handler for the action
  * @property {string} [url] - URL to navigate to when clicked (opens in new tab)
- */ /**
- * A Banner component that displays a styled banner with customizable title, status, icon, actions, and dismiss functionality.
- * The banner style and content change based on the provided props, allowing for various statuses and themes.
- *
- * @component
- *
- * @param {Object} props - The properties for configuring the Banner component.
- * @param {string} [props.title] - The title text for the banner. If not provided, no title will be displayed.
- * @param {BannerStatus} [props.status='neutral'] - The status of the banner, which determines its color and icon.
- * @param {Function} [props.onDismiss] - Callback function to handle the banner's dismiss action.
- * @param {React.ReactNode} [props.children] - Additional content to display within the banner.
- * @param {BannerAction} [props.action] - Primary action configuration object
- * @param {BannerAction} [props.secondaryAction] - Secondary action configuration object
- * @param {FunctionComponent} [props.icon] - Custom icon to display on the banner. If not provided, a default icon is used based on the status.
- * @param {boolean} [props.spinner] - Shows a spinner icon instead of a status icon when set to true.
- *
- * @returns {JSX.Element} The rendered Banner component.
- *
- * @example
- * <Banner
- *   title="Warning"
- *   status="warning"
- *   onDismiss={() => console.log('Dismissed')}
- *   action={{ content: "Action", primary: true, onAction: () => console.log('Action clicked') }}
- *   secondaryAction={{ content: "Learn more", link: true, monochrome: true, url: "https://example.com" }}
- * />
  */ function Banner() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var _props_title = props.title, title = _props_title === void 0 ? null : _props_title, _props_status = props.status, status = _props_status === void 0 ? "neutral" : _props_status, _props_onDismiss = props.onDismiss, onDismiss = _props_onDismiss === void 0 ? null : _props_onDismiss, _props_children = props.children, children = _props_children === void 0 ? null : _props_children, _props_action = props.action, action = _props_action === void 0 ? null : _props_action, _props_secondaryAction = props.secondaryAction, secondaryAction = _props_secondaryAction === void 0 ? null : _props_secondaryAction, _props_icon = props.icon, icon = _props_icon === void 0 ? null : _props_icon, _props_spinner = props.spinner, spinner = _props_spinner === void 0 ? false : _props_spinner;

package/dist/esm/components/Box.js

@@ -28,7 +28,55 @@ function _object_spread(target) {
 }
 import { jsx as _jsx } from "react/jsx-runtime";
 import { tv } from "tailwind-variants";
-var styles = tv({
+/**
+ * @component Box
+ *
+ * @description A flexible container component with configurable padding, background, border radius, shadow, and overflow properties.
+ *
+ * @usage
+ * - DO: Use as a flexible container for padding, spacing, and background styling.
+ * - DON'T: Use for page-level layout (use `Layout` instead).
+ *
+ * @accessibility
+ * - Box renders a generic div by default; use the `as` prop for semantic HTML elements when appropriate.
+ *
+ * @alternative
+ * - If you need a bordered card, use `Card`.
+ * - If you need flex layout, use `Stack`.
+ *
+ * @param {Object} props - Properties to configure the Box component.
+ * @param {string} [props.as='div'] - The HTML element to render as. Defaults to `div`.
+ * @param {'default' | 'subdued'} [props.background] - Background color variant.
+ * @param {'default' | 'subdued'} [props.borderColor] - Border color variant.
+ * @param {'default' | 'sm' | 'lg' | 'full'} [props.borderRadius] - Border radius variant.
+ * @param {'none' | '0' | '1'} [props.borderBlockStartWidth] - Top border width variant.
+ * @param {'none' | '0' | '1'} [props.borderBlockEndWidth] - Bottom border width variant.
+ * @param {'none' | '0' | '1'} [props.borderInlineStartWidth] - Left border width variant.
+ * @param {'none' | '0' | '1'} [props.borderInlineEndWidth] - Right border width variant.
+ * @param {'none' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10'} [props.padding] - Padding for all sides.
+ * @param {'none' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10'} [props.paddingBlockStart] - Top padding.
+ * @param {'none' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10'} [props.paddingBlockEnd] - Bottom padding.
+ * @param {'none' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10'} [props.paddingInlineStart] - Left padding.
+ * @param {'none' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10'} [props.paddingInlineEnd] - Right padding.
+ * @param {'hidden' | 'scroll'} [props.overflow] - Overflow setting for all sides.
+ * @param {'hidden' | 'scroll'} [props.overflowX] - Overflow setting for x-axis.
+ * @param {'hidden' | 'scroll'} [props.overflowY] - Overflow setting for y-axis.
+ * @param {'relative' | 'absolute' | 'fixed' | 'sticky'} [props.position] - CSS positioning of the box.
+ * @param {React.ReactNode} [props.children] - Child elements to render inside the Box.
+ * @param {string} [props.id] - ID for the Box element.
+ * @param {number | string} [props.height] - CSS height of the Box.
+ * @param {number | string} [props.width] - CSS width of the Box.
+ * @param {number | string} [props.minHeight] - Minimum CSS height.
+ * @param {number | string} [props.maxHeight] - Maximum CSS height.
+ * @param {number | string} [props.minWidth] - Minimum CSS width.
+ * @param {number | string} [props.maxWidth] - Maximum CSS width.
+ * @param {number | string} [props.zIndex] - CSS z-index.
+ * @param {Object} [props.style] - Additional inline styles for the Box.
+ * @param {string} [props.className] - Additional CSS classes to apply to the Box.
+ * @param {Function} [props.onClick] - Click handler for the Box.
+ *
+ * @returns {JSX.Element} A rendered Box component with customized styling.
+*/ var styles = tv({
     base: "Litho-Box",
     variants: {
         background: {
@@ -155,43 +203,7 @@ var styles = tv({
         }
     }
 });
-/**
- * Renders a customizable Box component with various styling options.
- *
- * @component
- * @param {Object} props - Properties to configure the Box component.
- * @param {string} [props.as='div'] - The HTML element to render as. Defaults to `div`.
- * @param {'default' | 'subdued'} [props.background] - Background color variant.
- * @param {'default' | 'subdued'} [props.borderColor] - Border color variant.
- * @param {'default' | 'sm' | 'lg' | 'full'} [props.borderRadius] - Border radius variant.
- * @param {'none' | '0' | '1'} [props.borderBlockStartWidth] - Top border width variant.
- * @param {'none' | '0' | '1'} [props.borderBlockEndWidth] - Bottom border width variant.
- * @param {'none' | '0' | '1'} [props.borderInlineStartWidth] - Left border width variant.
- * @param {'none' | '0' | '1'} [props.borderInlineEndWidth] - Right border width variant.
- * @param {'none' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10'} [props.padding] - Padding for all sides.
- * @param {'none' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10'} [props.paddingBlockStart] - Top padding.
- * @param {'none' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10'} [props.paddingBlockEnd] - Bottom padding.
- * @param {'none' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10'} [props.paddingInlineStart] - Left padding.
- * @param {'none' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10'} [props.paddingInlineEnd] - Right padding.
- * @param {'hidden' | 'scroll'} [props.overflow] - Overflow setting for all sides.
- * @param {'hidden' | 'scroll'} [props.overflowX] - Overflow setting for x-axis.
- * @param {'hidden' | 'scroll'} [props.overflowY] - Overflow setting for y-axis.
- * @param {'relative' | 'absolute' | 'fixed' | 'sticky'} [props.position] - CSS positioning of the box.
- * @param {React.ReactNode} [props.children] - Child elements to render inside the Box.
- * @param {string} [props.id] - ID for the Box element.
- * @param {number | string} [props.height] - CSS height of the Box.
- * @param {number | string} [props.width] - CSS width of the Box.
- * @param {number | string} [props.minHeight] - Minimum CSS height.
- * @param {number | string} [props.maxHeight] - Maximum CSS height.
- * @param {number | string} [props.minWidth] - Minimum CSS width.
- * @param {number | string} [props.maxWidth] - Maximum CSS width.
- * @param {number | string} [props.zIndex] - CSS z-index.
- * @param {Object} [props.style] - Additional inline styles for the Box.
- * @param {string} [props.className] - Additional CSS classes to apply to the Box.
- * @param {Function} [props.onClick] - Click handler for the Box.
- * 
- * @returns {JSX.Element} A rendered Box component with customized styling.
-*/ var Box = function() {
+var Box = function() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var _props_as = props.as, as = _props_as === void 0 ? 'div' : _props_as, background = props.background, borderColor = props.borderColor, borderBlockStartWidth = props.borderBlockStartWidth, borderBlockEndWidth = props.borderBlockEndWidth, borderInlineStartWidth = props.borderInlineStartWidth, borderInlineEndWidth = props.borderInlineEndWidth, borderRadius = props.borderRadius, children = props.children, id = props.id, height = props.height, width = props.width, minHeight = props.minHeight, maxHeight = props.maxHeight, minWidth = props.minWidth, maxWidth = props.maxWidth, overflow = props.overflow, overflowX = props.overflowX, overflowY = props.overflowY, padding = props.padding, paddingBlockStart = props.paddingBlockStart, paddingBlockEnd = props.paddingBlockEnd, paddingInlineStart = props.paddingInlineStart, paddingInlineEnd = props.paddingInlineEnd, position = props.position, zIndex = props.zIndex, onClick = props.onClick, style = props.style, className = props.className;
     var classes = styles({