@heymantle/litho 0.0.14 → 0.0.16

package/dist/cjs/components/AnnouncementBar.js

@@ -12,12 +12,90 @@ var _jsxruntime = require("react/jsx-runtime");
 var _tailwindvariants = require("tailwind-variants");
 var _Text = /*#__PURE__*/ _interop_require_default(require("./Text"));
 var _Icon = /*#__PURE__*/ _interop_require_default(require("./Icon"));
+var _polarisicons = require("@shopify/polaris-icons");
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
 function _interop_require_default(obj) {
     return obj && obj.__esModule ? obj : {
         default: obj
     };
 }
-var styles = (0, _tailwindvariants.tv)({
+function _object_spread(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property(target, key, source[key]);
+        });
+    }
+    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;
+}
+/**
+ * @component AnnouncementBar
+ *
+ * @description A full-width banner displayed at the top of the application for global announcements and promotions.
+ *
+ * @usage
+ * - DO: Display global announcements, promotions, or system-wide messages.
+ * - DON'T: Use for page-specific messages (use Banner).
+ *
+ * @accessibility
+ * - Ensure the announcement text is descriptive; provide a dismiss action for user control.
+ *
+ * @alternative
+ * - If you need page-specific messaging, use `Banner`.
+ * - If you need a contextual hint, use `Tip`.
+ *
+ * @param {Object} props - Component properties.
+ * @param {Function} [props.onClick] - Click handler function.
+ * @param {string} props.content - Text content to be displayed.
+ * @param {string} [props.icon] - Icon source name.
+ * @param {"bounce"} [props.animateIcon] - Animation type for the icon.
+ * @param {boolean} [props.fixed] - Whether to fix the announcement bar to the top of the page.
+ * @param {Function} [props.onDismiss] - Callback to dismiss the announcement bar. Renders a close button when provided.
+ *
+ * @returns {JSX.Element} AnnouncementBar component.
+ */ var styles = (0, _tailwindvariants.tv)({
     base: "Litho-AnnouncementBar text-center p-2 min-h-10 flex items-center justify-center bg-brand",
     variants: {
         fixed: {
@@ -37,28 +115,27 @@ var iconContainerStyles = (0, _tailwindvariants.tv)({
         }
     }
 });
-/**
- * AnnouncementBar Component
- *
- * @param {Object} props - Component properties.
- * @param {Function} [props.onClick] - Click handler function.
- * @param {string} props.content - Text content to be displayed.
- * @param {string} [props.icon] - Icon source name.
- * @param {"bounce"} [props.animateIcon] - Animation type for the icon.
- * @param {boolean} [props.fixed] - Whether to fix the announcement bar to the top of the page.
- *
- * @returns {JSX.Element} AnnouncementBar component.
- */ function AnnouncementBar() {
+function AnnouncementBar() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
-    var onClick = props.onClick, content = props.content, icon = props.icon, animateIcon = props.animateIcon, _props_fixed = props.fixed, fixed = _props_fixed === void 0 ? false : _props_fixed;
-    return /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
+    var onClick = props.onClick, content = props.content, icon = props.icon, animateIcon = props.animateIcon, _props_fixed = props.fixed, fixed = _props_fixed === void 0 ? false : _props_fixed, onDismiss = props.onDismiss;
+    return /*#__PURE__*/ (0, _jsxruntime.jsx)("div", _object_spread_props(_object_spread({
         className: styles({
             fixed: fixed,
             interactive: !!onClick
         }),
-        onClick: onClick,
+        onClick: onClick
+    }, onClick ? {
+        role: "button",
+        tabIndex: 0,
+        onKeyDown: function(e) {
+            if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                onClick(e);
+            }
+        }
+    } : {}), {
         children: /*#__PURE__*/ (0, _jsxruntime.jsxs)("div", {
-            className: "flex items-center justify-center gap-4",
+            className: "flex items-center justify-center gap-4 w-full relative",
             children: [
                 /*#__PURE__*/ (0, _jsxruntime.jsx)(_Text.default, {
                     fontWeight: "medium",
@@ -72,9 +149,29 @@ var iconContainerStyles = (0, _tailwindvariants.tv)({
                     children: /*#__PURE__*/ (0, _jsxruntime.jsx)(_Icon.default, {
                         source: icon
                     })
+                }),
+                onDismiss && /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
+                    className: "absolute right-0 p-1 cursor-pointer rounded-md hover:bg-brand-low",
+                    onClick: function(e) {
+                        e.stopPropagation();
+                        onDismiss();
+                    },
+                    role: "button",
+                    tabIndex: 0,
+                    "aria-label": "Dismiss announcement",
+                    onKeyDown: function(e) {
+                        if (e.key === "Enter" || e.key === " ") {
+                            e.preventDefault();
+                            e.stopPropagation();
+                            onDismiss();
+                        }
+                    },
+                    children: /*#__PURE__*/ (0, _jsxruntime.jsx)(_Icon.default, {
+                        source: _polarisicons.CancelSmallMinor
+                    })
                 })
             ]
         })
-    });
+    }));
 }
 var _default = AnnouncementBar;

package/dist/cjs/components/AnnouncementCard.js

@@ -0,0 +1,269 @@
+"use client";
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "default", {
+    enumerable: true,
+    get: function() {
+        return _default;
+    }
+});
+var _jsxruntime = require("react/jsx-runtime");
+var _tailwindvariants = require("tailwind-variants");
+var _Button = /*#__PURE__*/ _interop_require_default(require("./Button"));
+var _Card = /*#__PURE__*/ _interop_require_default(require("./Card"));
+var _Icon = /*#__PURE__*/ _interop_require_default(require("./Icon"));
+var _Stack = /*#__PURE__*/ _interop_require_default(require("./Stack"));
+var _Text = /*#__PURE__*/ _interop_require_default(require("./Text"));
+var _Tooltip = /*#__PURE__*/ _interop_require_default(require("./Tooltip"));
+var _polarisicons = require("@shopify/polaris-icons");
+function _interop_require_default(obj) {
+    return obj && obj.__esModule ? obj : {
+        default: obj
+    };
+}
+/**
+ * @component AnnouncementCard
+ *
+ * @description A promotional card that displays a title, description, decorative icon, and action buttons. Used for feature announcements, onboarding prompts, and contextual promotions.
+ *
+ * @usage
+ * - DO: Use for feature announcements, onboarding prompts, or promotional content within a page.
+ * - DON'T: Use for alerts or critical messages (use Banner). Don't use for global announcements (use AnnouncementBar).
+ *
+ * @accessibility
+ * - The icon (or image when imageUrl is set) is purely decorative. Title and description convey the full message.
+ * - Action buttons are keyboard accessible via the Litho Button component.
+ * - Dismiss button includes an aria-label for screen readers.
+ *
+ * @alternative
+ * - If you need a contextual alert with status styling, use `Banner`.
+ * - If you need a global top-of-page announcement, use `AnnouncementBar`.
+ * - If you need a subtle inline hint, use `Tip`.
+ *
+ * @param {Object} props - Props for the AnnouncementCard component.
+ * @param {string|React.ReactNode} [props.title=null] - The announcement heading.
+ * @param {string|React.ReactNode} [props.description=null] - Supporting text below the title.
+ * @param {string} [props.imageUrl=null] - Optional image URL. When set, shown in place of the icon with 3/2 aspect ratio. Displayed on md+ screens only.
+ * @param {"0"|"1"|"2"|"3"|"4"} [props.imagePadding="0"] - Padding around the image (maps to p-0, p-1, p-2, p-3, p-4). Only applies when imageUrl is set.
+ * @param {"cover"|"contain"} [props.imageDisplay="cover"] - How the image fits within its container. Only applies when imageUrl is set.
+ * @param {React.ElementType|string} [props.icon=null] - A decorative icon. Pass a Polaris icon (e.g., MagicMajor), a Lucide icon component (e.g., Cable from lucide-react), or a string for dynamic Lucide loading (e.g., "cable"). Icon is automatically colored based on the tint prop. Displayed on md+ screens only. Ignored when imageUrl is set.
+ * @param {"info"|"success"|"critical"|"attention"|"warning"|"insight"|"highlight"|"neutral"|string} [props.tint="info"] - Color tint for the icon and image container background. Pass a named variant or a hex color (e.g. "#f0f0f0").
+ * @param {Object} [props.primaryAction=null] - Primary action button configuration.
+ * @param {string} [props.primaryAction.content] - Button label text.
+ * @param {Function} [props.primaryAction.onAction] - Click handler.
+ * @param {boolean} [props.primaryAction.loading=false] - Loading state.
+ * @param {boolean} [props.primaryAction.disabled=false] - Disabled state.
+ * @param {boolean} [props.primaryAction.destructive=false] - Destructive styling.
+ * @param {React.Component} [props.primaryAction.icon] - Button icon.
+ * @param {string} [props.primaryAction.url] - URL to open on click.
+ * @param {boolean} [props.primaryAction.external=false] - Open URL in new tab.
+ * @param {Object} [props.secondaryAction=null] - Secondary action button configuration (same shape as primaryAction).
+ * @param {Function} [props.onDismiss=null] - Callback when the dismiss button is clicked. When provided, renders a close button.
+ * @param {React.ReactNode|import("./Tooltip").TooltipContentObject} [props.tooltip=null] - Tooltip content for the title. When set, shows an info icon next to the title that displays the tooltip on hover.
+ * @param {string} [props.tooltipPreferredPosition='above'] - Preferred position for the tooltip.
+ * @param {React.ReactNode} [props.children=null] - Optional content rendered below the description. Image and icon are still shown when children are passed.
+ * @returns {React.ReactElement} The rendered AnnouncementCard component.
+ *
+ * @example
+ * import { Cable } from "lucide-react";
+ * import { MagicMajor } from "@shopify/polaris-icons";
+ *
+ * // With a Lucide icon
+ * <AnnouncementCard
+ *   title="Try our new feature"
+ *   description="Get started with the new integration tools."
+ *   icon={Cable}
+ *   tint="highlight"
+ *   primaryAction={{ content: "Learn more", onAction: () => {} }}
+ * />
+ *
+ * // With a Polaris icon
+ * <AnnouncementCard
+ *   title="Try our new feature"
+ *   icon={MagicMajor}
+ *   tint="insight"
+ *   primaryAction={{ content: "Learn more", onAction: () => {} }}
+ * />
+ *
+ * // With a dynamic Lucide string
+ * <AnnouncementCard
+ *   title="Try our new feature"
+ *   icon="cable"
+ *   tint="info"
+ *   primaryAction={{ content: "Learn more", onAction: () => {} }}
+ * />
+ */ var TINT_BG_CLASSES = {
+    info: "bg-info-alt",
+    success: "bg-success-alt",
+    critical: "bg-critical-alt",
+    attention: "bg-attention-alt",
+    warning: "bg-attention-alt",
+    insight: "bg-insight-alt",
+    highlight: "bg-highlight-alt",
+    neutral: "bg-neutral-alt",
+    custom: ""
+};
+var iconContainerStyles = (0, _tailwindvariants.tv)({
+    base: "w-24 h-24 rounded-xl flex items-center justify-center flex-shrink-0",
+    variants: {
+        tint: TINT_BG_CLASSES
+    },
+    defaultVariants: {
+        tint: "info"
+    }
+});
+var imageContainerStyles = (0, _tailwindvariants.tv)({
+    base: "aspect-[3/2] rounded-xl overflow-hidden",
+    variants: {
+        tint: TINT_BG_CLASSES,
+        padding: {
+            "0": "p-0",
+            "1": "p-1",
+            "2": "p-2",
+            "3": "p-3",
+            "4": "p-4"
+        }
+    },
+    defaultVariants: {
+        tint: "info",
+        padding: "0"
+    }
+});
+var IMAGE_DISPLAY_CLASSES = {
+    cover: "object-cover",
+    contain: "object-contain"
+};
+var TINT_ICON_COLORS = {
+    info: "info-alt-icon",
+    success: "success-alt-icon",
+    critical: "critical-alt-icon",
+    attention: "attention-alt-icon",
+    warning: "warning-alt-icon",
+    insight: "insight-alt-icon",
+    highlight: "highlight-alt-icon",
+    neutral: "neutral-alt-icon"
+};
+var renderAction = function(action) {
+    var plain = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : false;
+    if (!action) return null;
+    return /*#__PURE__*/ (0, _jsxruntime.jsx)(_Button.default, {
+        plain: plain,
+        disabled: action.disabled,
+        loading: action.loading,
+        destructive: action.destructive,
+        icon: action.icon,
+        url: action.url,
+        external: action.external,
+        onClick: action.onAction,
+        children: action.content
+    });
+};
+function AnnouncementCard() {
+    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_titleGap = props.titleGap, titleGap = _props_titleGap === void 0 ? "xs" : _props_titleGap, _props_description = props.description, description = _props_description === void 0 ? null : _props_description, _props_imageUrl = props.imageUrl, imageUrl = _props_imageUrl === void 0 ? null : _props_imageUrl, _props_imagePadding = props.imagePadding, imagePadding = _props_imagePadding === void 0 ? "0" : _props_imagePadding, _props_imageDisplay = props.imageDisplay, imageDisplay = _props_imageDisplay === void 0 ? "cover" : _props_imageDisplay, _props_icon = props.icon, icon = _props_icon === void 0 ? null : _props_icon, _props_tint = props.tint, tint = _props_tint === void 0 ? "info" : _props_tint, _props_primaryAction = props.primaryAction, primaryAction = _props_primaryAction === void 0 ? null : _props_primaryAction, _props_secondaryAction = props.secondaryAction, secondaryAction = _props_secondaryAction === void 0 ? null : _props_secondaryAction, _props_onDismiss = props.onDismiss, onDismiss = _props_onDismiss === void 0 ? null : _props_onDismiss, _props_tooltip = props.tooltip, tooltip = _props_tooltip === void 0 ? null : _props_tooltip, _props_tooltipPreferredPosition = props.tooltipPreferredPosition, tooltipPreferredPosition = _props_tooltipPreferredPosition === void 0 ? "above" : _props_tooltipPreferredPosition, _props_children = props.children, children = _props_children === void 0 ? null : _props_children;
+    var hasActions = !!(primaryAction || secondaryAction);
+    var isTintHex = typeof tint === "string" && tint.startsWith("#");
+    var resolvedTint = isTintHex ? "custom" : tint;
+    var tintStyle = isTintHex ? {
+        backgroundColor: tint
+    } : undefined;
+    var _IMAGE_DISPLAY_CLASSES_imageDisplay;
+    return /*#__PURE__*/ (0, _jsxruntime.jsx)(_Card.default, {
+        padded: true,
+        children: /*#__PURE__*/ (0, _jsxruntime.jsxs)("div", {
+            className: "relative group/announcement-card",
+            children: [
+                onDismiss && /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
+                    className: "absolute top-0 right-0 group-hover/announcement-card:block hidden opacity-70 hover:opacity-100",
+                    children: /*#__PURE__*/ (0, _jsxruntime.jsx)(_Button.default, {
+                        plain: true,
+                        icon: _polarisicons.CancelMinor,
+                        onClick: onDismiss,
+                        tooltip: "Dismiss",
+                        "aria-label": "Dismiss",
+                        size: "small"
+                    })
+                }),
+                /*#__PURE__*/ (0, _jsxruntime.jsxs)(_Stack.default, {
+                    horizontal: "md",
+                    justify: "between",
+                    align: "stretch",
+                    gap: "6",
+                    children: [
+                        /*#__PURE__*/ (0, _jsxruntime.jsxs)(_Stack.default, {
+                            justify: "between",
+                            fullWidth: true,
+                            children: [
+                                /*#__PURE__*/ (0, _jsxruntime.jsxs)(_Stack.default, {
+                                    gap: titleGap,
+                                    children: [
+                                        title != null && /*#__PURE__*/ (0, _jsxruntime.jsxs)("div", {
+                                            className: "flex items-center gap-2",
+                                            children: [
+                                                typeof title === "string" ? /*#__PURE__*/ (0, _jsxruntime.jsx)(_Text.default, {
+                                                    variant: "headingMd",
+                                                    fontWeight: "medium",
+                                                    children: title
+                                                }) : title,
+                                                tooltip && /*#__PURE__*/ (0, _jsxruntime.jsx)(_Tooltip.default, {
+                                                    content: tooltip,
+                                                    preferredPosition: tooltipPreferredPosition
+                                                })
+                                            ]
+                                        }),
+                                        description != null && (typeof description === "string" ? /*#__PURE__*/ (0, _jsxruntime.jsx)(_Text.default, {
+                                            color: "subdued",
+                                            children: description
+                                        }) : description),
+                                        children
+                                    ]
+                                }),
+                                hasActions && /*#__PURE__*/ (0, _jsxruntime.jsxs)("div", {
+                                    className: "flex gap-2",
+                                    children: [
+                                        renderAction(primaryAction),
+                                        renderAction(secondaryAction, true)
+                                    ]
+                                })
+                            ]
+                        }),
+                        imageUrl && /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
+                            className: "hidden md:block w-36 flex-shrink-0",
+                            children: /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
+                                className: imageContainerStyles({
+                                    tint: resolvedTint,
+                                    padding: imagePadding
+                                }),
+                                style: tintStyle,
+                                children: /*#__PURE__*/ (0, _jsxruntime.jsx)("img", {
+                                    src: imageUrl,
+                                    alt: "",
+                                    className: "w-full h-full rounded-xl ".concat((_IMAGE_DISPLAY_CLASSES_imageDisplay = IMAGE_DISPLAY_CLASSES[imageDisplay]) !== null && _IMAGE_DISPLAY_CLASSES_imageDisplay !== void 0 ? _IMAGE_DISPLAY_CLASSES_imageDisplay : IMAGE_DISPLAY_CLASSES.cover)
+                                })
+                            })
+                        }),
+                        !imageUrl && icon && /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
+                            className: "hidden md:block",
+                            children: /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
+                                className: iconContainerStyles({
+                                    tint: resolvedTint
+                                }),
+                                style: tintStyle,
+                                children: /*#__PURE__*/ (0, _jsxruntime.jsx)(_Icon.default, {
+                                    source: icon,
+                                    color: TINT_ICON_COLORS[tint] || TINT_ICON_COLORS.info,
+                                    size: 12,
+                                    strokeWidth: 1,
+                                    opacity: 70
+                                })
+                            })
+                        })
+                    ]
+                })
+            ]
+        })
+    });
+}
+var _default = AnnouncementCard;

package/dist/cjs/components/AppProvider.js

@@ -150,7 +150,20 @@ var screenSizes = typeof window !== "undefined" ? {
     "2xl": parseInt(getComputedStyle(document.documentElement).getPropertyValue("--breakpoint-2xl"), 10)
 } : {};
 /**
- * Provider component for managing global application state.
+ * @component AppProvider
+ *
+ * @description The root context provider that initializes dark mode, frame state, and form context for the entire Litho application.
+ *
+ * @usage
+ * - DO: Wrap your entire application to provide dark mode, frame, and form context.
+ * - DON'T: Use multiple AppProviders in the same tree.
+ *
+ * @accessibility
+ * - AppProvider manages the `data-theme` attribute on `<html>` for dark mode; ensures consistent theming for all components.
+ *
+ * @alternative
+ * - If you only need toast notifications, use `ToastProvider` independently.
+ *
  * @param {Object} props
  * @param {React.ReactNode} props.children - The child components.
  * @param {boolean} props.embedded - Whether the app is embedded.
@@ -244,7 +257,7 @@ var screenSizes = typeof window !== "undefined" ? {
                     setDiscardAction: setDiscardAction
                 },
                 children: /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
-                    className: "app-wrapper ".concat(embedded ? "@container" : ""),
+                    className: "app-wrapper ".concat(embedded ? "@container/main" : ""),
                     children: children
                 })
             })

package/dist/cjs/components/Autocomplete.js

@@ -175,42 +175,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 styles = (0, _tailwindvariants.tv)({
-    base: "Litho-Autocomplete flex flex-col"
-});
-function attachPropToTextField(children, prop) {
-    return _react.default.Children.map(children, function(child) {
-        if (/*#__PURE__*/ (0, _react.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__*/ (0, _react.cloneElement)(child, prop);
-            }
-            if ((_child_props = child.props) === null || _child_props === void 0 ? void 0 : _child_props.children) {
-                return /*#__PURE__*/ (0, _react.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.
@@ -240,7 +219,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"
  *     }
  *   ]}
@@ -248,7 +227,39 @@ function attachPropToTextField(children, prop) {
  *   onSelect={(selected) => console.log(selected)}
  *   textField={<Autocomplete.TextField placeholder="Search..." />}
  * />
- */ function Autocomplete() {
+ */ var styles = (0, _tailwindvariants.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.default.Children.map(children, function(child) {
+        if (/*#__PURE__*/ (0, _react.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__*/ (0, _react.cloneElement)(child, prop);
+            }
+            if ((_child_props = child.props) === null || _child_props === void 0 ? void 0 : _child_props.children) {
+                return /*#__PURE__*/ (0, _react.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();
@@ -292,6 +303,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/cjs/components/Badge.js

@@ -10,8 +10,33 @@ Object.defineProperty(exports, "default", {
 });
 var _jsxruntime = require("react/jsx-runtime");
 var _tailwindvariants = require("tailwind-variants");
-var styles = (0, _tailwindvariants.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 = (0, _tailwindvariants.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",
@@ -196,18 +221,7 @@ var progressBadgeStyles = (0, _tailwindvariants.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({