npm package: @heymantle/litho
Description: Litho is a library of components for building Mantle extensions
Latest version: 0.0.16

# Litho

A modern React component library for building Mantle extensions and web applications. Litho provides a comprehensive set of accessible, themeable, and composable UI components, designed for rapid development and seamless integration with Tailwind CSS and Shopify Polaris icons.

## Installation

```sh
npm install @heymantle/litho
```

> **Note:** `tailwindcss`, `react`, and `react-dom` (v18+) are required as peer dependencies.

## Usage

1. **Import the CSS** (required for correct styling):

```css
// index.css paths here may differ depending on your project structure
@source "./node_modules/@heymantle/litho";
@import "./node_modules/@heymantle/litho/index.css";
```

2. **Wrap your app with `AppProvider`** (required for `Frame` and/or `Form` usage):

```jsx
import { AppProvider, Page, Button } from "litho";

function App() {
  return (
    <AppProvider darkModeAvailable darkModeStorageKey="my-app-dark-mode">
      <Page title="Welcome to Litho">
        <Button primary onClick={() => alert("Hello!")}>
          Click me
        </Button>
      </Page>
    </AppProvider>
  );
}
```

3. **Use any component**:

```jsx
import { Banner, Card, ResourceList } from 'litho';

<Banner status="success" title="Success!">
  Your operation was successful.
</Banner>

<Card>
  <ResourceList
    items={[{ id: 1, name: 'Item 1' }]}
    renderItem={item => <div key={item.id}>{item.name}</div>}
  />
</Card>
```

## Components

Litho exports a wide range of components, including:

- **Layout:** `Page`, `Frame`, `Layout`, `Card`, `Grid`, `Stack`
- **Forms:** `TextField`, `Select`, `Checkbox`, `RadioButton`, `RangeSlider`, `ChoiceList`, `DatePicker`, `ColorField`
- **Navigation:** `Navigation`, `Tabs`, `Pagination`, `TopBar`, `Pane`
- **Feedback:** `Banner`, `Tip`, `InlineError`, `EmptyState`, `Loading`, `SkeletonText`, `FooterHelp`
- **Actions:** `Button`, `ButtonGroup`, `ActionList`, `Popover`, `Modal`, `ContextualSaveBar`
- **Data Display:** `Table`, `ResourceList`, `List`, `Badge`, `Tag`, `Thumbnail`, `Image`, `Tooltip`
- **Utilities:** `useIndexResourceState`, `useTableScrollState`, and more

See the [source code](./components/) for full API documentation and JSDoc usage examples for each component.

## Theming & Customization

- Litho is designed to work with Tailwind CSS. You can customize themes and extend styles using your Tailwind config.

```css
// index.css paths here may differ depending on your project structure
@source "./node_modules/@heymantle/litho";
@import "./node_modules/@heymantle/litho/index.css";
```

## Peer Dependencies

- `react` >= 18
- `react-dom` >= 18
- `tailwindcss` >= 4

## AI Assistant Integration

Litho includes comprehensive guides for AI coding assistants (Claude, ChatGPT, Cursor, Copilot, etc.) to help generate accurate, consistent UI code:

- **`AI_COMPONENTS_GUIDE.md`** - Complete component API reference
- **`AI_PATTERNS_GUIDE.md`** - Ready-to-use UI patterns and examples
- **`AI_INTEGRATION_GUIDE.md`** - Guidelines for AI code generation
- **`COMPONENT_QUICK_REFERENCE.md`** - Fast component lookup
- **`AI_USAGE_IN_PROJECTS.md`** - How to use these guides in your projects

### Using in Your Projects

After installing Litho, the guides are available in `node_modules/@heymantle/litho/`. Reference them in your AI prompts:

```
@node_modules/@heymantle/litho/AI_PATTERNS_GUIDE.md

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