@heymantle/litho 0.0.14 → 0.0.16

package/AI_COMPONENTS_GUIDE.md

@@ -159,7 +159,7 @@ import { ComponentName } from '@heymantle/litho';
   actions={[{ content: 'Edit', onAction: handleEdit }]}
   padded
 >
-  <Stack gap="4">
+  <Stack>
     <Text>Product details go here</Text>
   </Stack>
 </Card>
@@ -214,7 +214,7 @@ import { ComponentName } from '@heymantle/litho';
 
 **Example:**
 ```jsx
-<Grid columns={{ xs: 1, sm: 2, lg: 3 }} gap="4">
+<Grid columns={{ xs: 1, sm: 2, lg: 3 }}>
   <Card>Product 1</Card>
   <Card>Product 2</Card>
   <Card>Product 3</Card>
@@ -225,14 +225,13 @@ import { ComponentName } from '@heymantle/litho';
 
 ### Stack
 
-**Purpose:** Flexible stack component for creating vertical or horizontal layouts with consistent spacing. By default creates a vertical stack.
+**Purpose:** Flexible stack component for creating vertical or horizontal layouts with consistent spacing. By default creates a vertical stack. Supports responsive breakpoints for switching from vertical to horizontal at a given screen width.
 
 **Key Props:**
-- `horizontal` (boolean): If true, creates horizontal layout (flex-row). Defaults to vertical (flex-col)
+- `horizontal` (boolean|'xs'|'sm'|'md'|'lg'|'xl'): Direction control. `true` for always horizontal. A breakpoint string (e.g. `"md"`) makes it vertical below that breakpoint and horizontal at/above it. Defaults to `false` (vertical)
+- `fill` (boolean): When true and horizontal is active, children fill equal space. Defaults to `true`
 - `gap` (string|number): Space between children
-- `align` (string): Main axis alignment ('start', 'center', 'end', 'space-between', 'space-around')
-- `blockAlign` (string): Cross-axis alignment for horizontal stacks (vertical alignment)
-- `inlineAlign` (string): Cross-axis alignment for vertical stacks (horizontal alignment)
+- `align` (string): Main axis alignment ('start', 'center', 'end', 'between', 'around')
 - `wrap` (boolean): Whether children should wrap to the next line
 
 **Common Use Cases:**
@@ -240,14 +239,28 @@ import { ComponentName } from '@heymantle/litho';
 - Form field layouts
 - Content spacing
 - Header actions
+- Responsive column layouts (vertical on mobile, horizontal on desktop)
 
 **Example:**
 ```jsx
-<Stack horizontal gap="4" align="space-between">
+{/* Horizontal with equal-width children (fill is true by default) */}
+<Stack horizontal justify="between">
   <Text variant="headingLg">Title</Text>
   <Button>Action</Button>
 </Stack>
 
+{/* Responsive: vertical on mobile, horizontal columns at md breakpoint */}
+<Stack horizontal="md">
+  <Card title="Plan A" padded>Basic</Card>
+  <Card title="Plan B" padded>Pro</Card>
+</Stack>
+
+{/* Horizontal without fill (children size naturally) */}
+<Stack horizontal>
+  <Button>Cancel</Button>
+  <Button primary>Save</Button>
+</Stack>
+
 <Stack gap="6">
   <TextField label="Name" />
   <TextField label="Email" />
@@ -565,7 +578,7 @@ const handleSave = async () => {
 };
 
 <Form>
-  <Stack gap="4">
+  <Stack>
     <TextField
       label="Name"
       value={formData.name}
@@ -956,7 +969,7 @@ const handleSave = async () => {
   onClose={() => setPaneOpen(false)}
   title="Product Details"
 >
-  <Stack gap="4">
+  <Stack>
     {/* Pane content */}
   </Stack>
 </Pane>
@@ -1045,7 +1058,7 @@ const handleSave = async () => {
   items={customers}
   renderItem={(customer) => (
     <ResourceList.Item key={customer.id} id={`customer-${customer.id}`}>
-      <Stack horizontal align="space-between">
+      <Stack horizontal justify="between">
         <Stack gap="1">
           <Text variant="headingSm">{customer.name}</Text>
           <Text variant="bodySm" color="subdued">{customer.email}</Text>
@@ -1266,7 +1279,7 @@ import { EditMinor } from '@shopify/polaris-icons';
 
 **Example:**
 ```jsx
-<Stack gap="4">
+<Stack>
   <Text>Section 1</Text>
   <Divider />
   <Text>Section 2</Text>
@@ -1421,7 +1434,7 @@ const { darkMode, toggleDarkMode } = useDarkMode();
 1. **Always wrap your app with AppProvider** for context access
 2. **Use Page as top-level container** for application pages
 3. **Prefer Layout for complex pages** with multiple sections
-4. **Use VerticalStack/HorizontalStack** for consistent spacing
+4. **Use Stack** for consistent spacing
 5. **Use Card for content grouping** with optional titles
 6. **Provide resourceName** for ResourceList and Table for better accessibility
 7. **Use proper status colors** for badges and banners (success/critical/warning)
@@ -1472,7 +1485,7 @@ const { darkMode, toggleDarkMode } = useDarkMode();
   <Layout>
     <Layout.Section>
       <Card title="Customer Information" padded>
-        <Stack gap="4">
+        <Stack>
           <TextField label="Name" value={name} onChange={setName} />
           <TextField label="Email" value={email} onChange={setEmail} />
         </Stack>
@@ -1496,7 +1509,7 @@ const { darkMode, toggleDarkMode } = useDarkMode();
       description="Basic settings"
     >
       <Card padded>
-        <Stack gap="4">
+        <Stack>
           <TextField label="Store Name" />
           <TextField label="Email" />
         </Stack>

package/AI_INTEGRATION_GUIDE.md

@@ -72,7 +72,7 @@ import Button from '@heymantle/litho/components/Button';
 
 ```jsx
 // ✅ Correct - Use Litho components for layout
-<Stack gap="4">
+<Stack>
   <TextField label="Name" />
   <TextField label="Email" />
 </Stack>
@@ -100,7 +100,7 @@ import Button from '@heymantle/litho/components/Button';
 
 ```jsx
 // ✅ Correct - Use Stack for consistent spacing
-<Stack gap="4">
+<Stack>
   <TextField label="Name" />
   <TextField label="Email" />
   <Button primary>Submit</Button>
@@ -285,7 +285,7 @@ import { TextField as MuiTextField } from '@mui/material';
 </div>
 
 // ✅ CORRECT - Use Stack with horizontal
-<Stack horizontal gap="4">
+<Stack horizontal>
   <Button>Cancel</Button>
   <Button>Save</Button>
 </Stack>

package/AI_PATTERNS_GUIDE.md

@@ -313,8 +313,8 @@ function MultiStepRegistration() {
     switch (currentStep) {
       case 0:
         return (
-          <Stack gap="4">
-            <Grid columns={{ xs: 1, sm: 2 }} gap="4">
+          <Stack>
+            <Grid columns={{ xs: 1, sm: 2 }}>
               <TextField
                 label="First Name"
                 value={formData.firstName}
@@ -347,14 +347,14 @@ function MultiStepRegistration() {
 
       case 1:
         return (
-          <Stack gap="4">
+          <Stack>
             <TextField
               label="Street Address"
               value={formData.address}
               onChange={(value) => updateField('address', value)}
               placeholder="123 Main Street"
             />
-            <Grid columns={{ xs: 1, sm: 3 }} gap="4">
+            <Grid columns={{ xs: 1, sm: 3 }}>
               <TextField
                 label="City"
                 value={formData.city}
@@ -380,7 +380,7 @@ function MultiStepRegistration() {
       case 2:
         return (
           <Stack gap="6">
-            <Stack gap="4">
+            <Stack>
               <Text variant="headingSm">
                 Notification Preferences
               </Text>
@@ -423,7 +423,7 @@ function MultiStepRegistration() {
       {/* Progress Indicator */}
       <Box paddingBlockEnd="8">
         <Stack gap="2">
-          <Stack horizontal align="space-between">
+          <Stack horizontal justify="between">
             {steps.map((step, index) => (
               <Text
                 key={step}
@@ -453,7 +453,7 @@ function MultiStepRegistration() {
         {/* Navigation */}
         <Box paddingBlockStart="8">
           <Box paddingBlockStart="4" className="border-t border-edge-subdued">
-            <Stack horizontal align="space-between">
+            <Stack horizontal justify="between">
               <Button
                 disabled={currentStep === 0}
                 onClick={handlePrevious}
@@ -531,7 +531,7 @@ function ContactForm() {
     <Card title="Contact Us" padded>
       <Form>
         <Stack gap="6">
-          <Stack horizontal gap="4">
+          <Stack horizontal>
             <TextField
               label="Name"
               value={formData.name}
@@ -563,7 +563,7 @@ function ContactForm() {
             placeholder="Select a subject"
           />
 
-          <Stack gap="4">
+          <Stack>
             <Text variant="headingSm">
               Priority
             </Text>
@@ -751,7 +751,7 @@ function OrderList() {
       accessibilityLabel={`View details for order ${order.id}`}
     >
       <Stack gap="2">
-        <Stack horizontal align="space-between" blockAlign="start">
+        <Stack horizontal justify="between" align="start">
           <Stack gap="1">
             <Text variant="headingSm">{order.id}</Text>
             <Text variant="bodySm">{order.customer}</Text>
@@ -764,7 +764,7 @@ function OrderList() {
           </Stack>
         </Stack>
 
-        <Stack horizontal align="space-between" blockAlign="center">
+        <Stack horizontal justify="between" align="center">
           <Text variant="bodySm" color="subdued">
             {order.items} item{order.items !== 1 ? 's' : ''} • {order.date}
           </Text>
@@ -864,7 +864,7 @@ function SettingsPage() {
                 <Checkbox label="Allow search engines to index profile" />
                 <Checkbox label="Show online status" />
               </Stack>
-              <Stack horizontal gap="4">
+              <Stack horizontal>
                 <Button>Change Password</Button>
                 <Button>Setup 2FA</Button>
               </Stack>
@@ -909,7 +909,7 @@ function SettingsPage() {
           description="Irreversible and destructive actions"
         >
           <Card padded>
-            <Stack gap="4">
+            <Stack>
               <Text color="subdued">
                 These actions cannot be undone. Please proceed with caution.
               </Text>
@@ -955,7 +955,7 @@ function ProductManagement() {
           description="Essential details about your product"
         >
           <Card padded>
-            <Stack gap="4">
+            <Stack>
               <TextField label="Product Name" placeholder="Enter product name" />
               <TextField label="SKU" placeholder="Product SKU" />
               <TextField
@@ -973,7 +973,7 @@ function ProductManagement() {
           description="Set pricing and manage stock levels"
         >
           <Card padded>
-            <Grid columns={{ xs: 1, sm: 2, lg: 4 }} gap="4">
+            <Grid columns={{ xs: 1, sm: 2, lg: 4 }}>
               <TextField label="Price" placeholder="$0.00" />
               <TextField label="Compare Price" placeholder="$0.00" />
               <TextField label="Cost per Item" placeholder="$0.00" />
@@ -987,8 +987,8 @@ function ProductManagement() {
           description="Configure shipping options and delivery settings"
         >
           <Card padded>
-            <Stack gap="4">
-              <Grid columns={{ xs: 1, sm: 2, lg: 4 }} gap="4">
+            <Stack>
+              <Grid columns={{ xs: 1, sm: 2, lg: 4 }}>
                 <TextField label="Weight" placeholder="0.0 kg" />
                 <TextField label="Length" placeholder="0.0 cm" />
                 <TextField label="Width" placeholder="0.0 cm" />
@@ -1005,7 +1005,7 @@ function ProductManagement() {
 
         <Layout.Section>
           <Card padded>
-            <Stack horizontal gap="4" align="end">
+            <Stack horizontal align="end">
               <Button>Save as Draft</Button>
               <Button>Preview</Button>
               <Button primary>Publish Product</Button>
@@ -1022,6 +1022,40 @@ function ProductManagement() {
 
 ---
 
+### Responsive Column Layout
+
+**Use Case:** Content that stacks vertically on mobile and displays as equal-width columns on larger screens. Common for pricing cards, feature comparisons, and dashboard panels.
+
+```jsx
+import { Stack, Card, Text } from '@heymantle/litho';
+
+function PricingSection() {
+  return (
+    <Stack horizontal="md">
+      <Card title="Basic" padded>
+        <Text>Essential features for small teams.</Text>
+      </Card>
+      <Card title="Pro" padded>
+        <Text>Advanced features for growing businesses.</Text>
+      </Card>
+      <Card title="Enterprise" padded>
+        <Text>Full-featured solution for large organizations.</Text>
+      </Card>
+    </Stack>
+  );
+}
+```
+
+**Key Points:**
+- `horizontal="md"` makes the stack vertical below 800px and horizontal at/above
+- Children fill equal width by default (`fill={true}`)
+- Use `fill={false}` when children should size naturally (e.g. button groups)
+- Available breakpoints: `"xs"` (320px), `"sm"` (480px), `"md"` (800px), `"lg"` (1038px), `"xl"` (1440px)
+
+**Storybook Reference:** `stories/Stack.stories.js` → ResponsiveFill
+
+---
+
 ## CRUD Operation Patterns
 
 ### List Page with Actions
@@ -1046,14 +1080,14 @@ function ProductsListPage() {
 
   const renderProduct = (product) => (
     <ResourceList.Item key={product.id} id={`product-${product.id}`}>
-      <Stack horizontal align="space-between" blockAlign="center">
+      <Stack horizontal justify="between" align="center">
         <Stack gap="1">
           <Text variant="headingSm">{product.name}</Text>
           <Text variant="bodySm" color="subdued">
             Stock: {product.stock} units
           </Text>
         </Stack>
-        <Stack horizontal gap="4" blockAlign="center">
+        <Stack horizontal align="center">
           <Text variant="headingSm">{product.price}</Text>
           <Badge status={product.status === 'active' ? 'success' : 'critical'}>
             {product.status === 'active' ? 'Active' : 'Out of Stock'}
@@ -1072,7 +1106,7 @@ function ProductsListPage() {
       }}
     >
       <Card padded>
-        <Stack gap="4">
+        <Stack>
           <Filters
             queryValue={searchQuery}
             onQueryChange={setSearchQuery}
@@ -1165,7 +1199,7 @@ function CustomerDetailPage() {
       <Layout>
         <Layout.Section>
           <Card title="Customer Information" padded>
-            <Stack gap="4">
+            <Stack>
               <TextField
                 label="Name"
                 value={customer.name}
@@ -1185,7 +1219,7 @@ function CustomerDetailPage() {
                 onChange={(value) => setCustomer({ ...customer, phone: value })}
                 disabled={!editing}
               />
-              <Stack horizontal gap="2" blockAlign="center">
+              <Stack horizontal gap="2" align="center">
                 <Text variant="bodySm">Status:</Text>
                 <Badge status={customer.status === 'active' ? 'success' : 'warning'}>
                   {customer.status}
@@ -1310,7 +1344,7 @@ function EditProductModal({ open, onClose, product }) {
       ]}
       sectioned
     >
-      <Stack gap="4">
+      <Stack>
         <TextField
           label="Product Name"
           value={formData.name}
@@ -1433,7 +1467,7 @@ function FormWithErrorHandling() {
 
   return (
     <Form>
-      <Stack gap="4">
+      <Stack>
         {generalError && (
           <Banner status="critical" onDismiss={() => setGeneralError('')}>
             {generalError}

package/COMPONENT_QUICK_REFERENCE.md

@@ -26,7 +26,7 @@
 | **Layout.AnnotatedSection** | Section with title/description | `title`, `description` | Settings, forms |
 | **Card** | Content container | `title`, `actions`, `padded`, `sectioned` | Grouping content |
 | **Grid** | Responsive grid | `columns` (object/number), `gap` | Product grids, dashboards |
-| **Stack** | Vertical/horizontal spacing | `gap`, `align`, `horizontal`, `blockAlign`, `inlineAlign` | Form fields, content, button groups, headers |
+| **Stack** | Vertical/horizontal spacing | `gap`, `align`, `horizontal` (bool/breakpoint), `fill`,
 | **Box** | Utility container | `padding`, `background`, `borderRadius` | Spacing, colored sections |
 | **Frame** | App shell with nav | `navigation`, `topBar` | Application wrapper |
 
@@ -192,7 +192,7 @@ const handleSave = async () => {
 };
 
 <Form>
-  <Stack gap="4">
+  <Stack>
     <TextField
       label="Name"
       value={formData.name}
@@ -253,7 +253,7 @@ const handleSave = async () => {
   secondaryActions={[{content: 'Cancel', onAction: close}]}
   sectioned
 >
-  <Stack gap="4">
+  <Stack>
     <TextField label="Name" value={name} onChange={setName} />
   </Stack>
 </Modal>

package/README.md

@@ -107,6 +107,58 @@ Build a customer list page with search and filtering using Litho components.
 
 See **`AI_USAGE_IN_PROJECTS.md`** for detailed instructions on accessing guides and Storybook examples from projects using Litho as a dependency.
 
+## Visual Regression Testing
+
+Litho includes automated visual regression tests using Playwright to catch unintended UI changes.
+
+### Running Tests
+
+```bash
+# Run visual regression tests (uses Docker for CI parity)
+npm run test:visual:docker
+
+# Update baseline screenshots (uses Docker for CI parity)
+npm run test:visual:docker:update
+```
+
+> **Note:** The Docker commands ensure baselines match CI exactly. Native commands (`npm run test:visual`) are also available but may produce different results due to font rendering differences between macOS and Linux.
+
+### When Baselines Need Updating
+
+Update baselines when you've made **intentional** visual changes:
+- Modified component styles or layout
+- Changed default props or variants
+- Updated theme colors or typography
+- Added new visual states to existing components
+
+### Adding New Stories
+
+When you add a new component or story:
+1. The visual tests automatically discover all stories from Storybook
+2. Run `npm run test:visual:update` to generate baseline screenshots for new stories
+3. Commit the new baseline images in `tests/visual/stories.spec.js-snapshots/`
+
+### Skipped Stories
+
+Some stories are skipped because they contain non-deterministic content:
+- **Image stories** - Use random external images from picsum.photos
+- Add problematic stories to `SKIP_STORIES` in `tests/visual/stories.spec.js`
+
+### CI Integration
+
+Visual tests run automatically on PRs to `main`. If tests fail:
+1. Download the `visual-regression-diffs` artifact from the workflow
+2. Review the diff images to determine if changes are intentional
+3. If intentional, use the **Update Visual Baselines** workflow to regenerate baselines
+
+### Generating Baselines from CI
+
+Since macOS and Linux render fonts differently, generate baselines from CI for best results:
+
+1. Go to **Actions** → **Update Visual Baselines** → **Run workflow**
+2. The workflow will create a PR with updated baselines
+3. Review and merge the PR
+
 ## License
 
 MIT

package/dist/cjs/components/ActionList.js

@@ -62,7 +62,36 @@ function _interop_require_wildcard(obj, nodeInterop) {
     }
     return newObj;
 }
-var styles = (0, _tailwindvariants.tv)({
+/**
+ * @component ActionList
+ *
+ * @description A vertical list of actionable items typically displayed inside a Popover for dropdown menus and contextual actions.
+ *
+ * @usage
+ * - DO: Display a list of actions inside a Popover dropdown menu.
+ * - DON'T: Use as a standalone visible list (use List or ResourceList).
+ *
+ * @accessibility
+ * - Renders as a list of buttons; each action item is keyboard navigable.
+ *
+ * @alternative
+ * - If you need a visible list of content, use `List`.
+ * - If you need a selectable list, use `Listbox`.
+ *
+ * @param {Object} props - Component properties.
+ * @param {Array<{title: string, items: Array<ActionListItem>}>} [props.sections] - Sections containing items for the action list.
+ * @param {Array<ActionListItem>} [props.items] - List of items to render in the action list when no sections are provided.
+ * @param {string} [props.iconColor="subdued"] - Default color for icons in the action items.
+ * @param {function} [props.onActionAnyItem] - Callback function invoked whenever any action item is selected.
+ * @param {boolean} [props.fullWidth=false] - Whether to apply full width styling to the action list.
+ * @param {boolean} [props.padded=true] - Whether to apply padding to the action list.
+ * @param {string} [props.className] - Additional CSS classes to apply to the action list.
+ * @example
+ * const items = [{ content: 'Item 1', onAction: () => {} }];
+ * <ActionList items={items} />
+ *
+ * @returns {JSX.Element} The rendered ActionList component.
+ */ var styles = (0, _tailwindvariants.tv)({
     base: "Litho-ActionList",
     variants: {
         fullWidth: {
@@ -120,28 +149,12 @@ var itemStyles = (0, _tailwindvariants.tv)({
  * @property {string} imageUrl - The image to display for the action item.
  * @property {string} url - The URL to navigate to when the action item is selected.
  * @property {SecondaryAction} secondaryAction - The secondary action to display for the action item.
- */ /**
- * ActionList component renders a list of actionable items with optional sections.
- * Supports keyboard navigation and action triggers on item selection.
- *
- * @component
- * @param {Object} props - Component properties.
- * @param {Array<{title: string, items: Array<ActionListItem>}>} [props.sections] - Sections containing items for the action list.
- * @param {Array<ActionListItem>} [props.items] - List of items to render in the action list when no sections are provided.
- * @param {string} [props.iconColor="subdued"] - Default color for icons in the action items.
- * @param {function} [props.onActionAnyItem] - Callback function invoked whenever any action item is selected.
- * @param {boolean} [props.fullWidth=false] - Whether to apply full width styling to the action list.
- * @param {boolean} [props.padded=true] - Whether to apply padding to the action list.
- * @param {string} [props.className] - Additional CSS classes to apply to the action list.
- * @example
- * const items = [{ content: 'Item 1', onAction: () => {} }];
- * <ActionList items={items} />
- *
- * @returns {JSX.Element} The rendered ActionList component.
  */ function ActionList() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var sections = props.sections, _props_padded = props.padded, padded = _props_padded === void 0 ? true : _props_padded, tmp = props.items, initialItems = tmp === void 0 ? [] : tmp, tmp1 = props.iconColor, _iconColor = tmp1 === void 0 ? "subdued" : tmp1, onActionAnyItem = props.onActionAnyItem, className = props.className, _props_fullWidth = props.fullWidth, fullWidth = _props_fullWidth === void 0 ? false : _props_fullWidth;
-    var sectionTitleAsKeys = true;
+    // Always use index-based keys to avoid duplicate key issues when
+    // multiple sections have empty or identical titles
+    var sectionTitleAsKeys = false;
     var items = initialItems || (sections ? sections.flatMap(function(section) {
         return section.items;
     }) : []);
@@ -184,11 +197,6 @@ var itemStyles = (0, _tailwindvariants.tv)({
         padded: padded
     });
     var isSectioned = sections && sections.length > 0;
-    if (isSectioned) {
-        sectionTitleAsKeys = sections.every(function(section) {
-            return Object.prototype.hasOwnProperty.call(section, "title");
-        });
-    }
     var ActionListItem = function(param) {
         var item = param.item, index = param.index;
         var content = item.content, description = item.description, disabled = item.disabled, destructive = item.destructive, icon = item.icon, onAction = item.onAction, prefix = item.prefix, imageUrl = item.imageUrl, url = item.url, secondaryAction = item.secondaryAction;