@heymantle/litho 0.0.14 → 0.0.16

package/dist/esm/components/ResourceList.js

@@ -2,19 +2,22 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { tv } from "tailwind-variants";
 import Spinner from "./Spinner.js";
 import Stack from "./Stack.js";
-var styles = tv({
-    base: "Litho-ResourceList flex flex-col min-w-72",
-    variants: {
-        divider: {
-            true: "divide-y divide-edge-default",
-            false: ""
-        }
-    }
-});
 /**
- * ResourceList component displays a list of items with loading and empty states.
+ * @component ResourceList
+ *
+ * @description A structured list component for displaying collections of similar resources with optional selection, bulk actions, and pagination.
+ *
+ * @usage
+ * - DO: Display collections of similar resources with selection and bulk actions.
+ * - DON'T: Use for simple text lists (use List).
+ *
+ * @accessibility
+ * - Supports keyboard selection; ensure each item has a descriptive label for screen readers.
+ *
+ * @alternative
+ * - If you need a data table with sorting and columns, use `Table`.
+ * - If you need a simple list, use `List`.
  *
- * @component
  * @param {Object} props - The component props.
  * @param {Array} [props.items=[]] - List of items to display.
  * @param {boolean} [props.loading=false] - Whether the list is in a loading state.
@@ -26,7 +29,16 @@ var styles = tv({
  * @param {boolean} [props.divider=true] - Whether to show dividers between items.
  * @param {"none"|"small"|"large"} [props.gap="none"] - Gap size between items.
  * @returns {JSX.Element} The rendered component.
- */ function ResourceList() {
+ */ var styles = tv({
+    base: "Litho-ResourceList flex flex-col min-w-72",
+    variants: {
+        divider: {
+            true: "divide-y divide-edge-default",
+            false: ""
+        }
+    }
+});
+function ResourceList() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var _props_items = props.items, items = _props_items === void 0 ? [] : _props_items, _props_loading = props.loading, loading = _props_loading === void 0 ? false : _props_loading, _props_emptyState = props.emptyState, emptyState = _props_emptyState === void 0 ? "No results found." : _props_emptyState, renderItem = props.renderItem, _props_resourceName = props.resourceName, resourceName = _props_resourceName === void 0 ? {
         singular: "item",
@@ -65,9 +77,11 @@ var itemStyles = tv({
     }
 });
 /**
- * Item component represents a single item in the ResourceList.
+ * @component ResourceList.Item
+ *
+ * @usage
+ * - DO: Use as direct children of ResourceList for each resource entry.
  *
- * @component
  * @param {Object} props - The component props.
  * @param {string} [props.id] - The ID of the item.
  * @param {string} [props.accessibilityLabel] - Accessibility label for the item.

package/dist/esm/components/Select.js

@@ -53,7 +53,43 @@ import Label from "./Label.js";
 import Link from "./Link.js";
 import Text from "./Text.js";
 import { CaretDownMinor, CircleAlertMajor, MagicMajor } from "@shopify/polaris-icons";
-var styles = tv({
+/**
+ * @component Select
+ *
+ * @description A dropdown select input that renders native HTML select with label, help text, and error state support.
+ *
+ * @usage
+ * - DO: Use for choosing one option from a predefined list.
+ * - DON'T: Use when the list is very long or needs filtering (use Autocomplete).
+ *
+ * @accessibility
+ * - Renders a native `<select>` element with full keyboard and screen reader support. Always provide a `label`.
+ *
+ * @alternative
+ * - If you need searchable/filterable selection, use `Autocomplete`. If you need multi-select, use `ChoiceList`.
+ *
+ * @param {Object} props - The properties for the Select component.
+ * @param {Array} props.options - Array of option objects for the select dropdown. Options can include groups.
+ * @param {string} [props.label] - Label for the select input.
+ * @param {Object} [props.labelAction] - An action object for the label. Includes `onAction` and `content`.
+ * @param {boolean} [props.labelHidden] - Whether to hide the label visually.
+ * @param {boolean} [props.labelInline] - Whether to display the label inline with the select.
+ * @param {boolean} [props.disabled=false] - Whether the select is disabled.
+ * @param {string} [props.helpText] - Optional help text displayed below the select.
+ * @param {string} [props.placeholder] - Placeholder text for the select input.
+ * @param {string} props.id - The ID for the select input.
+ * @param {string} props.name - The name for the select input.
+ * @param {string} props.value - The selected value.
+ * @param {React.ReactNode|import("./Tooltip").TooltipContentObject} props.tooltip - Tooltip content for the select.
+ * @param {string|boolean} [props.error] - Error message or flag indicating the select has an error.
+ * @param {function} props.onChange - Callback for when the selected value changes.
+ * @param {function} props.onFocus - Callback for when the select gains focus.
+ * @param {function} props.onBlur - Callback for when the select loses focus.
+ * @param {boolean} [props.requiredIndicator] - Whether to show a required indicator next to the label.
+ * @param {string} [props.className] - Additional CSS classes to apply to the select container.
+ * @param {string} [props.contentClassName] - Additional CSS classes to apply to the select content area.
+ * @returns {JSX.Element} The rendered Select component.
+ */ var styles = tv({
     base: "Litho-Select relative border border-form-border rounded-md",
     variants: {
         disabled: {
@@ -101,31 +137,7 @@ var styles = tv({
 var contentStyles = tv({
     base: "Litho-Select__Content min-h-7.5 pl-3 pr-2 flex items-center justify-between gap-2"
 });
-/**
- * @function Select
- * @description A dropdown component that allows users to select an option from a list.
- * @param {Object} props - The properties for the Select component.
- * @param {Array} props.options - Array of option objects for the select dropdown. Options can include groups.
- * @param {string} [props.label] - Label for the select input.
- * @param {Object} [props.labelAction] - An action object for the label. Includes `onAction` and `content`.
- * @param {boolean} [props.labelHidden] - Whether to hide the label visually.
- * @param {boolean} [props.labelInline] - Whether to display the label inline with the select.
- * @param {boolean} [props.disabled=false] - Whether the select is disabled.
- * @param {string} [props.helpText] - Optional help text displayed below the select.
- * @param {string} [props.placeholder] - Placeholder text for the select input.
- * @param {string} props.id - The ID for the select input.
- * @param {string} props.name - The name for the select input.
- * @param {string} props.value - The selected value.
- * @param {React.ReactNode|import("./Tooltip").TooltipContentObject} props.tooltip - Tooltip content for the select.
- * @param {string|boolean} [props.error] - Error message or flag indicating the select has an error.
- * @param {function} props.onChange - Callback for when the selected value changes.
- * @param {function} props.onFocus - Callback for when the select gains focus.
- * @param {function} props.onBlur - Callback for when the select loses focus.
- * @param {boolean} [props.requiredIndicator] - Whether to show a required indicator next to the label.
- * @param {string} [props.className] - Additional CSS classes to apply to the select container.
- * @param {string} [props.contentClassName] - Additional CSS classes to apply to the select content area.
- * @returns {JSX.Element} The rendered Select component.
- */ function Select() {
+function Select() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var options = props.options, label = props.label, tooltip = props.tooltip, labelAction = props.labelAction, labelHidden = props.labelHidden, labelInline = props.labelInline, _props_disabled = props.disabled, disabled = _props_disabled === void 0 ? false : _props_disabled, helpText = props.helpText, placeholder = props.placeholder, id = props.id, name = props.name, value = props.value, error = props.error, onChange = props.onChange, onFocus = props.onFocus, onBlur = props.onBlur, requiredIndicator = props.requiredIndicator, className = props.className, contentClassName = props.contentClassName;
     var _useState = _sliced_to_array(useState(false), 2), focused = _useState[0], setFocused = _useState[1];

package/dist/esm/components/SkeletonText.js

@@ -1,7 +1,38 @@
+"use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { tv } from "tailwind-variants";
 import { useMemo } from "react";
-var styles = tv({
+/**
+ * @component SkeletonText
+ *
+ * @description A placeholder component that renders animated skeleton lines to represent loading text content.
+ *
+ * @usage
+ * - DO: Use as a content placeholder while text data is loading, matching the expected layout with `lines` and `type`.
+ * - DON'T: Use for non-text placeholders like images or charts; build custom skeleton layouts for those.
+ *
+ * @accessibility
+ * - Skeleton content is decorative; ensure the parent loading region has `aria-busy="true"`.
+ * - Do not use skeleton text as a replacement for meaningful content once data is available.
+ *
+ * @alternative
+ * - If you need a spinning indicator rather than a content placeholder, use `Spinner` instead.
+ * - If you need a page-level loading bar, use `Loading` instead.
+ *
+ * @param {Object} props - The component properties.
+ * @param {number} [props.lines=3] - The number of lines to render. Defaults to 3 for body text.
+ * @param {"body"|"heading"} [props.type="body"] - The type of skeleton text
+ * @param {"xs"|"sm"|"md"|"lg"|"xl"} [props.size="md"] - The size of the skeleton text
+ * @param {number} [props.width] - The width of the skeleton text lines. If not provided, random widths are generated.
+ * @param {boolean} [props.fullWidth=false] - Whether the skeleton text lines should be full width.
+ * @param {"start"|"center"|"end"} [props.align="start"] - The alignment of the skeleton text lines.
+ * @param {string} [props.className] - Additional class names to apply to the root element.
+ *
+ * @returns {JSX.Element} A JSX element rendering a skeleton placeholder text block.
+ *
+ * @example
+ * <SkeletonText lines={5} type="heading" size="lg" width={80} className="custom-class" />
+ */ var styles = tv({
     base: "Litho-SkeletonText flex flex-col",
     variants: {
         gap: {
@@ -61,23 +92,7 @@ var lineStyles = tv({
         }
     ]
 });
-/**
- * SkeletonText component for displaying placeholder text content.
- * 
- * @param {Object} props - The component properties.
- * @param {number} [props.lines=3] - The number of lines to render. Defaults to 3 for body text.
- * @param {"body"|"heading"} [props.type="body"] - The type of skeleton text
- * @param {"xs"|"sm"|"md"|"lg"|"xl"} [props.size="md"] - The size of the skeleton text
- * @param {number} [props.width] - The width of the skeleton text lines. If not provided, random widths are generated.
- * @param {boolean} [props.fullWidth=false] - Whether the skeleton text lines should be full width.
- * @param {"start"|"center"|"end"} [props.align="start"] - The alignment of the skeleton text lines.
- * @param {string} [props.className] - Additional class names to apply to the root element.
- * 
- * @returns {JSX.Element} A JSX element rendering a skeleton placeholder text block.
- * 
- * @example
- * <SkeletonText lines={5} type="heading" size="lg" width={80} className="custom-class" />
- */ function SkeletonText() {
+function SkeletonText() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var tmp = props.lines, _lines = tmp === void 0 ? 3 : tmp, _props_type = props.type, type = _props_type === void 0 ? "body" : _props_type, _props_size = props.size, size = _props_size === void 0 ? "md" : _props_size, _width = props.width, _props_fullWidth = props.fullWidth, fullWidth = _props_fullWidth === void 0 ? false : _props_fullWidth, className = props.className, _props_gap = props.gap, gap = _props_gap === void 0 ? "medium" : _props_gap, _props_align = props.align, align = _props_align === void 0 ? "start" : _props_align;
     var lines = type === "heading" ? 1 : _lines;

package/dist/esm/components/Spinner.js

@@ -1,6 +1,28 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { tv } from "tailwind-variants";
-var styles = tv({
+/**
+ * @component Spinner
+ *
+ * @description An animated loading indicator for inline use within buttons, cards, or sections during asynchronous operations.
+ *
+ * @usage
+ * - DO: Use inline within buttons, cards, or sections to indicate localized loading.
+ * - DON'T: Use as a full-page loading indicator; use `Loading` for page-level progress bars.
+ *
+ * @accessibility
+ * - Renders with `role="status"` and an `aria-label`; always provide a descriptive `accessibilityLabel`.
+ * - Avoid relying on the animation alone; the `role="status"` ensures screen readers announce loading state.
+ *
+ * @alternative
+ * - If you need a page-level progress bar, use `Loading` instead.
+ * - If you need placeholder content while data loads, use `SkeletonText` instead.
+ *
+ * @param {Object} props - The props object.
+ * @param {('small'|'large')} [props.size='large'] - The size of the spinner, either "small" or "large".
+ * @param {('default'|'subdued')} [props.color='default'] - The color variant of the spinner.
+ * @param {string} [props.accessibilityLabel='Loading...'] - The accessible label for screen readers, describing the spinner's purpose.
+ * @returns {JSX.Element} The rendered Spinner component.
+ */ var styles = tv({
     base: "Litho-Spinner",
     variants: {
         size: {
@@ -19,17 +41,7 @@ var svgStyles = tv({
         }
     }
 });
-/**
- * Spinner Component
- *
- * This component renders a loading spinner with customizable size, color, and accessibility label.
- *
- * @param {Object} props - The props object.
- * @param {('small'|'large')} [props.size='large'] - The size of the spinner, either "small" or "large".
- * @param {('default'|'subdued')} [props.color='default'] - The color variant of the spinner.
- * @param {string} [props.accessibilityLabel='Loading...'] - The accessible label for screen readers, describing the spinner's purpose.
- * @returns {JSX.Element} The rendered Spinner component.
- */ function Spinner() {
+function Spinner() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var _props_size = props.size, size = _props_size === void 0 ? "large" : _props_size, _props_color = props.color, color = _props_color === void 0 ? "default" : _props_color, _props_accessibilityLabel = props.accessibilityLabel, accessibilityLabel = _props_accessibilityLabel === void 0 ? "Loading..." : _props_accessibilityLabel;
     var classes = styles({

package/dist/esm/components/Stack.js

@@ -1,4 +1,3 @@
-"use client";
 function _define_property(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
@@ -80,7 +79,62 @@ function _object_without_properties_loose(source, excluded) {
 }
 import { jsx as _jsx } from "react/jsx-runtime";
 import { tv } from "tailwind-variants";
-var styles = tv({
+/**
+ * @component Stack
+ *
+ * @description A flex layout component that arranges children in a row or column with configurable gap, alignment, and wrapping.
+ *
+ * @usage
+ * - DO: Arrange child elements with consistent spacing using the `gap` prop.
+ * - DON'T: Use for grid-based layouts (use `Grid` instead).
+ *
+ * @accessibility
+ * - Stack is a layout utility; ensure child content maintains logical reading order.
+ *
+ * @alternative
+ * - If you need explicit horizontal layout, use `Stack` with `horizontal` prop.
+ * - If you need responsive layout that switches from vertical to horizontal at a breakpoint, use `Stack` with `horizontal="md"` (or `"sm"`, `"lg"`, etc.).
+ * - If you need 2D grid layout, use `Grid`.
+ *
+ * @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 {boolean|'xs'|'sm'|'md'|'lg'|'xl'} [props.horizontal=false] - Direction control. When `true`, always horizontal (flex-row). When a breakpoint string is passed (e.g. `"md"`), the stack is vertical below that breakpoint and horizontal at/above it. Defaults to `false` (vertical).
+ * @param {('none'|'xs'|'sm'|'md'|'lg'|'0'|'px'|'0.5'|'1'|'1.5'|'2'|'3'|'4'|'5'|'6'|'8'|'10')} [props.gap='md'] - Spacing between children. Semantic options: 'none' (0), 'xs' (1), 'sm' (2), 'md' (4), 'lg' (8). Numeric options: '0', 'px', '0.5', '1', '2', '3', '4', '5', '6', '8', '10'. Defaults to 'md'.
+ * @param {string} [props.id] - Optional ID for the component.
+ * @param {string} [props.className] - Additional custom class names to apply to the component.
+ * @param {('start'|'center'|'end'|'stretch'|'baseline')} [props.align='stretch'] - Cross-axis alignment (maps to CSS `align-items`). Controls vertical alignment for horizontal stacks and horizontal alignment for vertical stacks.
+ * @param {boolean} [props.wrap=false] - Whether children should wrap to the next line if necessary. Defaults to false.
+ * @param {('start'|'center'|'end'|'between'|'evenly'|'around')} [props.justify='start'] - Main axis justification. Controls horizontal justification for horizontal stacks and vertical justification for vertical stacks.
+ * @param {boolean} [props.fill=false] - When true and horizontal is active, direct children fill equal space (flex: 1 1 0%). Set to false to let children size naturally. Defaults to false.
+ * @param {('1'|'2'|'3'|'4'|'5'|'6'|null)} [props.flex=null] - Flex grow value. Sets `flex-1` through `flex-6` on the stack. Defaults to null (no flex).
+ * @param {boolean} [props.fullWidth=false] - When true, applies width: 100% (w-full). Defaults to false.
+ * @param {Object} [restProps] - Additional props passed to the root element.
+ *
+ * @returns {JSX.Element} The rendered Stack component.
+ *
+ * @example
+ * // Vertical stack (default)
+ * <Stack gap="sm" align="center">
+ *   <div>Item 1</div>
+ *   <div>Item 2</div>
+ * </Stack>
+ *
+ * @example
+ * // Horizontal stack
+ * <Stack horizontal>
+ *   <div>Item 1</div>
+ *   <div>Item 2</div>
+ * </Stack>
+ *
+ * @example
+ * // Responsive: vertical on mobile, horizontal at md breakpoint
+ * <Stack horizontal="md">
+ *   <div>Column 1</div>
+ *   <div>Column 2</div>
+ *   <div>Column 3</div>
+ * </Stack>
+ */ var styles = tv({
     base: "Litho-Stack flex",
     variants: {
         direction: {
@@ -99,6 +153,7 @@ var styles = tv({
             "px": "gap-px",
             "0.5": "gap-0.5",
             "1": "gap-1",
+            "1.5": "gap-1.5",
             "2": "gap-2",
             "3": "gap-3",
             "4": "gap-4",
@@ -107,75 +162,66 @@ var styles = tv({
             "8": "gap-8",
             "10": "gap-10"
         },
-        align: {
-            start: "justify-start",
-            center: "justify-center",
-            end: "justify-end",
-            "space-between": "justify-between",
-            "space-evenly": "justify-evenly",
-            "space-around": "justify-around",
-            spaceBetween: "justify-between"
+        flex: {
+            "1": "flex-1",
+            "2": "flex-2",
+            "3": "flex-3",
+            "4": "flex-4",
+            "5": "flex-5",
+            "6": "flex-6"
         },
-        blockAlign: {
+        align: {
             start: "items-start",
             center: "items-center",
             end: "items-end",
-            stretch: "items-stretch"
+            stretch: "items-stretch",
+            baseline: "items-baseline"
         },
-        inlineAlign: {
-            start: "items-start",
-            center: "items-center",
-            end: "items-end",
-            stretch: "items-stretch"
+        justify: {
+            start: "justify-start",
+            center: "justify-center",
+            end: "justify-end",
+            between: "justify-between",
+            evenly: "justify-evenly",
+            stretch: "justify-stretch",
+            around: "justify-around"
         },
         wrap: {
             true: "flex-wrap",
             false: "flex-nowrap"
+        },
+        fullWidth: {
+            true: "w-full",
+            false: ""
         }
     },
     defaultVariants: {
         direction: "vertical",
         gap: "md",
-        align: "start"
+        align: "stretch",
+        justify: "start",
+        fullWidth: false
     }
 });
-/**
- * Stack Component
- *
- * A flexible stack component for creating vertical or horizontal layouts with customizable spacing and alignment.
- * By default, creates a vertical stack with medium gap spacing.
- *
- * @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 {boolean} [props.horizontal=false] - If true, renders a horizontal stack (flex-row). Defaults to vertical (flex-col).
- * @param {('none'|'xs'|'sm'|'md'|'lg'|'0'|'px'|'0.5'|'1'|'2'|'3'|'4'|'5'|'6'|'8'|'10')} [props.gap='md'] - Spacing between children. Semantic options: 'none' (0), 'xs' (1), 'sm' (2), 'md' (4), 'lg' (8). Numeric options: '0', 'px', '0.5', '1', '2', '3', '4', '5', '6', '8', '10'. Defaults to 'md'.
- * @param {string} [props.id] - Optional ID for the component.
- * @param {string} [props.className] - Additional custom class names to apply to the component.
- * @param {('start'|'center'|'end'|'space-between'|'space-evenly'|'space-around'|'spaceBetween')} [props.align='start'] - Main axis alignment. Controls horizontal alignment for horizontal stacks and vertical alignment for vertical stacks.
- * @param {('start'|'center'|'end'|'stretch')} [props.blockAlign] - Cross-axis alignment for horizontal stacks (vertical alignment). Only applicable when horizontal=true.
- * @param {('start'|'center'|'end'|'stretch')} [props.inlineAlign] - Cross-axis alignment for vertical stacks (horizontal alignment). Only applicable when horizontal=false.
- * @param {boolean} [props.wrap=false] - Whether children should wrap to the next line if necessary. Defaults to false.
- * @param {Object} [restProps] - Additional props passed to the root element.
- *
- * @returns {JSX.Element} The rendered Stack component.
- *
- * @example
- * // Vertical stack (default)
- * <Stack gap="sm" inlineAlign="center">
- *   <div>Item 1</div>
- *   <div>Item 2</div>
- * </Stack>
- *
- * @example
- * // Horizontal stack
- * <Stack horizontal gap="md" blockAlign="center" wrap={true}>
- *   <div>Item 1</div>
- *   <div>Item 2</div>
- * </Stack>
- */ function Stack() {
+// Static maps for Tailwind JIT scanability — do not construct dynamically
+var responsiveDirectionClasses = {
+    xs: "flex-col xs:flex-row",
+    sm: "flex-col sm:flex-row",
+    md: "flex-col md:flex-row",
+    lg: "flex-col lg:flex-row",
+    xl: "flex-col xl:flex-row"
+};
+var fillModifierClasses = {
+    true: "Litho-Stack--fill",
+    xs: "Litho-Stack--fill-xs",
+    sm: "Litho-Stack--fill-sm",
+    md: "Litho-Stack--fill-md",
+    lg: "Litho-Stack--fill-lg",
+    xl: "Litho-Stack--fill-xl"
+};
+function Stack() {
     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, _props_horizontal = props.horizontal, horizontal = _props_horizontal === void 0 ? false : _props_horizontal, _props_gap = props.gap, gap = _props_gap === void 0 ? "md" : _props_gap, id = props.id, className = props.className, align = props.align, blockAlign = props.blockAlign, inlineAlign = props.inlineAlign, _props_wrap = props.wrap, wrap = _props_wrap === void 0 ? false : _props_wrap, restProps = _object_without_properties(props, [
+    var _props_as = props.as, as = _props_as === void 0 ? "div" : _props_as, children = props.children, _props_horizontal = props.horizontal, horizontal = _props_horizontal === void 0 ? false : _props_horizontal, _props_gap = props.gap, gap = _props_gap === void 0 ? "md" : _props_gap, id = props.id, className = props.className, align = props.align, justify = props.justify, _props_wrap = props.wrap, wrap = _props_wrap === void 0 ? false : _props_wrap, _props_flex = props.flex, flex = _props_flex === void 0 ? null : _props_flex, _props_fill = props.fill, fill = _props_fill === void 0 ? false : _props_fill, _props_fullWidth = props.fullWidth, fullWidth = _props_fullWidth === void 0 ? false : _props_fullWidth, restProps = _object_without_properties(props, [
         "as",
         "children",
         "horizontal",
@@ -183,29 +229,43 @@ var styles = tv({
         "id",
         "className",
         "align",
-        "blockAlign",
-        "inlineAlign",
-        "wrap"
+        "justify",
+        "wrap",
+        "flex",
+        "fill",
+        "fullWidth"
     ]);
-    var direction = horizontal ? "horizontal" : "vertical";
-    // For horizontal stacks, use blockAlign for cross-axis
-    // For vertical stacks, use inlineAlign for cross-axis
-    var crossAxisAlign = horizontal ? blockAlign : inlineAlign;
-    var classes = styles(_object_spread_props(_object_spread({
+    var isResponsive = typeof horizontal === "string";
+    var isHorizontal = horizontal === true;
+    var effectivelyHorizontal = isHorizontal || isResponsive;
+    // For boolean horizontal, use tv direction variant
+    // For responsive, tv gets "vertical" (flex-col) and responsive classes override at breakpoint
+    var direction = isHorizontal ? "horizontal" : "vertical";
+    // Horizontal stacks default to center (items-center), vertical to stretch (items-stretch)
+    var effectiveAlign = align !== undefined ? align : effectivelyHorizontal ? "center" : "stretch";
+    var classes = styles({
         direction: direction,
         gap: gap,
-        align: align
-    }, horizontal && blockAlign ? {
-        blockAlign: blockAlign
-    } : {}, !horizontal && inlineAlign ? {
-        inlineAlign: inlineAlign
-    } : {}), {
-        wrap: wrap
-    }));
+        align: effectiveAlign,
+        justify: justify,
+        wrap: wrap,
+        flex: flex,
+        fullWidth: fullWidth
+    });
+    // Responsive direction classes (e.g. "flex-col md:flex-row")
+    var responsiveClasses = isResponsive ? responsiveDirectionClasses[horizontal] : "";
+    // Fill modifier class for CSS child targeting
+    var fillClass = fill && effectivelyHorizontal ? fillModifierClasses[horizontal] || fillModifierClasses["true"] : "";
     var Element = as;
+    var allClasses = [
+        classes,
+        responsiveClasses,
+        fillClass,
+        className
+    ].filter(Boolean).join(" ");
     return /*#__PURE__*/ _jsx(Element, _object_spread_props(_object_spread({
         id: id,
-        className: "".concat(classes).concat(className ? " ".concat(className) : "")
+        className: allClasses
     }, restProps), {
         children: children
     }));

package/dist/esm/components/TabNavigation.js

@@ -53,7 +53,33 @@ import Button from "./Button.js";
 import Text from "./Text.js";
 import Spinner from "./Spinner.js";
 import Tooltip from "./Tooltip.js";
-var AVG_CHAR_WIDTH = 5.5;
+/**
+ * @component TabNavigation
+ *
+ * @description A URL-based tab navigation component that renders tabs as links, supporting closeable tabs and route-driven active states.
+ *
+ * @usage
+ * - DO: Use for navigation tabs that change the URL/route.
+ * - DON'T: Use for in-page content switching without URL changes (use Tabs).
+ *
+ * @accessibility
+ * - Renders as navigation links; ensure each tab link has descriptive text.
+ *
+ * @alternative
+ * - If you need in-page content tabs without URL routing, use `Tabs`. If you need a sidebar nav, use `Navigation`.
+ *
+ * @param {Object} props - Component properties.
+ * @param {Array<Object>} [props.tabs=[]] - Array of tab objects to display.
+ * @param {string} props.tabs[].id - Unique identifier for the tab.
+ * @param {string} props.tabs[].title - Display title for the tab.
+ * @param {boolean} [props.tabs[].loading] - Whether the tab is in a loading state.
+ * @param {Object} [props.tabs[].readStatus] - Read status indicator for the tab.
+ * @param {string} [props.activeTabId] - The ID of the currently active tab.
+ * @param {Function} [props.onTabClick] - Callback fired when a tab is clicked, receives the tab ID.
+ * @param {Function} [props.onTabClose] - Callback fired when a tab's close button is clicked, receives the tab ID.
+ * @param {string} [props.className=""] - Additional CSS class names for the container.
+ * @returns {JSX.Element} The rendered TabNavigation component.
+ */ var AVG_CHAR_WIDTH = 5.5;
 var tabStyles = tv({
     base: "relative group cursor-pointer rounded-t-sm items-center px-2 pt-2 gap-0.5 overflow-hidden min-w-[60px] max-w-[160px] pointer-coarse:pb-1 pointer-coarse:pt-3 transition-colors",
     variants: {