Saltcat UI Components

Avant-garde UI component library inspired by Ansel Adams and Leonardo Da Vinci, integrating Saltcat design systems.

Overview

This is the base component library. Individual themes are now packaged separately in the theme-packages/ directory. Each theme uses the metacompiler to generate theme-specific components with customized HTML/CSS/Svelte.

Project Structure

saltcat-ui-components/
├── src/
│   └── base/              # Base components (foundation)
├── theme-packages/        # Separate npm packages for each theme
│   ├── saltcat-theme-leonardo/
│   ├── saltcat-theme-ansel-adams/
│   ├── saltcat-theme-albrecht-durer/
│   ├── saltcat-theme-avant-garde/
│   └── saltcat-theme-custom-example/
├── simple-demo/           # Simple Vite-based demo with HMR
├── metacompile.js         # Metacompiler for theme generation
└── package.json

Installation

Quick Start

Recommended: Install via npm:

# Install the base component library
npm install saltcat-ui-components

# Install Svelte 5 (peer dependency)
npm install svelte@^5.0.0

Verify installation:

npm list saltcat-ui-components

Installing a Theme

npm install @saltcat/theme-leonardo
# or
npm install @saltcat/theme-ansel-adams
# or
npm install @saltcat/theme-albrecht-durer
# or
npm install @saltcat/theme-avant-garde

Alternative Installation Methods

yarn add saltcat-ui-components svelte@^5.0.0

pnpm add saltcat-ui-components svelte@^5.0.0

# Clone the repository
git clone https://github.com/durableprogramming/saltcat-ui-components.git
cd saltcat-ui-components

# Install dependencies
npm install

# Build the library
npm run build

Usage

Basic Setup

<script>
  import { ThemeProvider, Button, Card } from 'saltcat-ui-components';
  import { leonardoTheme } from '@saltcat/theme-leonardo';
</script>

<ThemeProvider theme={leonardoTheme}>
  <Card>
    <Button variant="primary">Hello World</Button>
  </Card>
</ThemeProvider>

Development

Running the Demo

The project now has a simplified demo that supports hot module reload:

# Install demo dependencies (first time only)
npm run demo:install

# Start the dev server with HMR
npm run dev

This starts a simple Vite server at http://localhost:3000 with full HMR support.

Building

# Build base components
npm run build

# Build all theme packages
npm run themes:build

# Build a specific theme
cd theme-packages/saltcat-theme-leonardo
./build.sh

Testing

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

Theme Packages

Each theme is now a separate npm package that:

1. Contains theme-specific overrides and customizations
2. Uses the metacompiler to generate final components
3. Can be published and installed independently
4. Exports theme configuration and components

Available Themes

• @saltcat/theme-leonardo - Renaissance elegance meets photographic mastery
• @saltcat/theme-ansel-adams - Photographic mastery and zone system precision
• @saltcat/theme-albrecht-durer - Northern Renaissance precision and detail
• @saltcat/theme-avant-garde - Bold, experimental, and progressive design
• @saltcat/theme-custom-example - Template for creating custom themes

Components

Core Components

• ThemeProvider: Provides theme context and CSS variables.
• ErrorBoundary: Catches and handles React errors gracefully.

Form Components

• Button: Customizable button with variants and sizes.
• Input: Styled input field.
• Textarea: Multi-line text input.
• Select: Dropdown selection component.
• Checkbox: Boolean input with custom styling.
• Radio: Radio button input.

Layout Components

• Card: Container component with shadow and border.
• Modal: Overlay dialog with accessibility features.
• Tabs: Tabbed interface for organizing content.
• Accordion: Collapsible content sections.

Interactive Components

• Tooltip: Contextual help text on hover/focus.

Troubleshooting

Common Issues

Module not found errors

• Ensure you've installed the peer dependency: npm install svelte@^5.0.0
• Clear node_modules and reinstall: rm -rf node_modules package-lock.json && npm install

Type errors

• Make sure TypeScript is configured to resolve node modules
• Check that "moduleResolution": "node" is set in your tsconfig.json

Build errors

• Verify Node.js version: node --version (requires >=14.0.0)
• Run npm run clean && npm run build to rebuild from scratch

Getting Help

• Issues: Report bugs at https://github.com/durableprogramming/saltcat-ui-components/issues
• Discussions: Ask questions in GitHub Discussions
• Email: Contact [email protected] for enterprise support

Updating

Keep the library up to date:

# Using npm
npm update saltcat-ui-components

# Using yarn
yarn upgrade saltcat-ui-components

# Using pnpm
pnpm update saltcat-ui-components

Integration

This library integrates with:

• saltcat-color-tokens: For dynamic color generation.
• saltcat-design-system: For design tokens.
• saltcat-easing: For smooth animations (future use).

Publishing

For Maintainers Only

To publish a new version:

# Update version in package.json
npm version patch  # or minor, or major

# This will automatically run prepublishOnly (clean, build, test)
npm publish

# Push tags
git push --tags