# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

### Prerequisites
- Node.js (version specified in `.tool-versions`)
- pnpm (package manager - enforced via `preinstall` script)

### Installation and Setup
```bash
# Clone the repository
git clone https://github.com/heroku/ember-hk-components
cd ember-hk-components

# Install dependencies (must use pnpm)
pnpm install
```

### Development Server
```bash
# Start development server
ember serve
# or
pnpm start

# Visit app at http://localhost:4200
```

### Testing
```bash
# Run all tests
pnpm test              # Runs ember test
ember test             # Direct ember test command
ember test --server    # Run tests in watch mode

# Run compatibility tests across Ember versions
pnpm run test:ember-compatibility
# or
ember try:each
```

### Linting
```bash
# Run all linting
pnpm run lint          # Runs both JS and HBS linting

# Individual linting commands
pnpm run lint:js       # ESLint for JavaScript
pnpm run lint:hbs      # ember-template-lint for Handlebars templates
pnpm run lint:hbs:fix  # Auto-fix template lint issues
```

### Building
```bash
# Build the addon
pnpm run build
# or
ember build
```

### Local Development with Another App
```bash
# In ember-hk-components directory
pnpm link

# In consuming app directory  
pnpm link @heroku/ember-hk-components

# To unlink
pnpm unlink @heroku/ember-hk-components
```

## Architecture Overview

### Project Type
This is an **Ember addon** that provides reusable UI components for Heroku applications. It's built on Ember 3.28 (Octane edition) and assumes usage of the Purple3 CSS framework and Malibu icon system.

### Key Dependencies
- **Purple3 CSS Framework**: Required CSS framework for styling
- **@heroku/ember-malibu-icon**: Icon system integration
- **ember-freestyle**: Component showcase and documentation system
- **ember-changeset**: Form state management
- **ember-power-select**: Advanced select component

### Directory Structure
- `addon/`: Core addon code (components, services, etc.)
- `addon/components/`: Reusable UI components (hk-button, hk-select, etc.)
- `app/`: App-specific re-exports and styles
- `app/styles/ember-hk-components/`: SCSS stylesheets for components
- `tests/dummy/`: Demo application showcasing components
- `tests/`: Test files

### Component Architecture
Components follow Ember Octane patterns with some legacy Classic components still present (migration in progress). Key component families:

- **Form Components**: `hk-input`, `hk-select`, `hk-textarea`, `hk-form-group`
- **UI Components**: `hk-button`, `hk-slide-panel`, `hk-well`
- **Utility Components**: `async-button`, `hk-autofocus-input`, `hk-validation-errors-list`

### CSS Integration
Styles are organized per-component in `app/styles/ember-hk-components/`. Components can be imported individually or all at once:

```scss
// Import all components
@import "ember-hk-components/ember-hk-components";

// Import specific component
@import "ember-hk-components/hk-slide-panel";
```

### Demo Application
The `tests/dummy/` directory contains a demo application using ember-freestyle to showcase all components. This serves as both documentation and development environment.

### Special Features
- **Slide Panel**: Uses a special DOM insertion point (`#hk-slide-panels`) added via addon's `index.js`
- **Accessibility**: Includes ember-a11y-testing for accessibility validation
- **Validation**: Integrated with ember-changeset for form validation patterns

### Legacy Considerations  
The codebase is transitioning from Ember Classic to Octane patterns. ESLint is configured to warn about classic patterns in `app/` and `addon/` directories while maintaining compatibility.