# Nano AI Proactive Hero Component Documentation

**Last Updated:** 2026-02-04  
**Component:** `v2/components/nano-ai/proactive-hero-component.php`  
**CSS:** `v2/css/nano-proactive-hero.css`  
**Data:** `docs/data/nano-proactive-scenarios.json`  
**Status:** Pixel-perfect implementation matching Figma designs exactly

## Overview

The Nano AI Proactive Hero Component is an interactive, animated component that showcases Nano's proactive AI suggestions through cycling "Nano Action" cards. The component displays different use cases (shift management, cost control, fairness alerts) with smooth transitions and auto-cycling functionality.

## Component Architecture

### File Structure

```
v2/components/nano-ai/
├── proactive-hero-component.php    # Main component
├── nano-icons.php                  # SVG icon functions
└── chat-hero-component.php.backup  # Backup of old component

v2/css/
└── nano-proactive-hero.css         # Component styles

docs/data/
└── nano-proactive-scenarios.json   # Scenario data
```

### Component Hierarchy

```
nano-proactive-hero (Alpine.js container)
└── nano-chat-window
    ├── nano-chat-header
    │   ├── nano-chat-header-left (chevron + title)
    │   └── nano-chat-header-right (window controls)
    ├── nano-chat-content
    │   └── nano-action-card-container
    │       └── nano-action-card
    │           ├── nano-action-header
    │           ├── nano-action-visual (shift-cards | percentage-cards | grid | chart)
    │           ├── nano-action-content
    │           └── nano-action-footer
    └── nano-chat-input-area
        ├── nano-chat-input-container
        └── nano-quick-actions
```

## Alpine.js Component API

### Component Name

`nanoProactiveHero()`

### State Properties

| Property               | Type         | Description                                       |
| ---------------------- | ------------ | ------------------------------------------------- |
| `scenarios`            | Array        | Array of scenario objects loaded from JSON        |
| `currentScenarioIndex` | Number       | Index of currently displayed scenario (0-based)   |
| `isAnimating`          | Boolean      | Whether transition animation is in progress       |
| `isPaused`             | Boolean      | Whether auto-cycle is paused (on hover)           |
| `cycleInterval`        | Number\|null | Timeout ID for auto-cycle interval                |
| `animationDuration`    | Number       | Duration of fade transitions in ms (default: 500) |

### Computed Properties

| Property          | Type         | Description                                                                |
| ----------------- | ------------ | -------------------------------------------------------------------------- |
| `currentScenario` | Object\|null | Currently displayed scenario object (computed from `currentScenarioIndex`) |

### Methods

#### `init()`

Initializes the component:

- Loads scenarios from JSON if not already loaded from PHP
- Sets initial scenario
- Starts auto-cycle after 1 second delay

#### `loadScenarios()`

Attempts to load scenarios from `/docs/data/nano-proactive-scenarios.json` via fetch API. Falls back silently if fetch fails (scenarios already loaded from PHP).

#### `nextScenario()`

Advances to the next scenario in the cycle:

- Sets `isAnimating` flag
- Increments `currentScenarioIndex` (wraps to 0 at end)
- Resets `isAnimating` after animation duration

#### `previousScenario()`

Goes back to the previous scenario:

- Sets `isAnimating` flag
- Decrements `currentScenarioIndex` (wraps to last at start)
- Resets `isAnimating` after animation duration

#### `startAutoCycle()`

Starts automatic cycling through scenarios:

- Uses `setTimeout` (not `setInterval`) for dynamic duration per scenario
- Respects `isPaused` and `isAnimating` flags
- Uses `getCurrentDisplayDuration()` for timing

#### `stopAutoCycle()`

Stops the auto-cycle:

- Clears the timeout
- Sets `cycleInterval` to null

#### `pauseCycle()`

Pauses auto-cycle (called on mouseenter):

- Sets `isPaused` to true

#### `resumeCycle()`

Resumes auto-cycle (called on mouseleave):

- Sets `isPaused` to false

#### `getCurrentDisplayDuration()`

Returns display duration for current scenario:

- Returns `currentScenario.displayDuration` if available
- Defaults to 3200ms if not specified

#### `dismissCard()`

Dismisses current card and shows next:

- Calls `nextScenario()`

#### `refreshScenario()`

Refreshes current scenario:

- Calls `nextScenario()` (in production, could reload data)

#### `provideFeedback()`

Handles feedback action:

- Currently logs to console
- In production, would trigger feedback modal/form

#### `handleCTAAction(action)`

Handles CTA button click:

- Receives action string (e.g., "extend-shift", "accept-suggestion")
- Currently logs to console
- In production, would trigger actual action

## Scenario Data Structure

### JSON Schema

```json
{
  "scenarios": [
    {
      "id": "string",
      "category": "string",
      "categoryLabel": "string",
      "title": "string",
      "description": "string",
      "ctaText": "string",
      "ctaAction": "string",
      "ctaIcon": "string (optional)",
      "visualType": "shift-cards | percentage-cards | grid | chart",
      "visualData": {
        /* type-specific data */
      },
      "shiftCards": [
        /* if visualType is shift-cards */
      ],
      "displayDuration": 3200
    }
  ],
  "metadata": {
    "version": "string",
    "lastUpdated": "YYYY-MM-DD",
    "totalScenarios": 6,
    "categories": ["string"],
    "defaultDisplayDuration": 3200,
    "animationDuration": 500
  }
}
```

### Visual Types

#### 1. Shift Cards (`shift-cards`)

```json
{
  "visualType": "shift-cards",
  "shiftCards": [
    {
      "timeRange": "15:00 - 18:00",
      "countRatio": "1/1",
      "name": "Sarah Klein",
      "duration": "07:30",
      "isActive": true
    }
  ]
}
```

#### 2. Percentage Cards (`percentage-cards`)

```json
{
  "visualType": "percentage-cards",
  "visualData": {
    "currentPercentage": 42,
    "suggestedPercentage": 35,
    "hintText": "4 Stunden ausplanen",
    "currentColor": "#FEE2E2",
    "currentTextColor": "#DC2626",
    "suggestedColor": "#1F2937",
    "suggestedTextColor": "#FFFFFF"
  }
}
```

#### 3. Grid Visualization (`grid`)

```json
{
  "visualType": "grid",
  "visualData": {
    "rows": 3,
    "columns": 4,
    "highlightedCell": {
      "row": 2,
      "column": 3,
      "value": "61€",
      "color": "#1F2937",
      "textColor": "#FFFFFF"
    },
    "defaultCellColor": "#EDEFF3"
  }
}
```

#### 4. Chart Visualization (`chart`)

```json
{
  "visualType": "chart",
  "visualData": {
    "chartType": "bar-line",
    "bars": [
      { "value": 25, "highlighted": false },
      { "value": 38, "highlighted": true, "color": "#FEE2E2" }
    ],
    "lineValues": [24, 27, 31, 34, 38],
    "lineColor": "#4D8EF3",
    "barColor": "#DBEAFE",
    "highlightedBarColor": "#FEE2E2"
  }
}
```

## CSS Classes

### Main Container

- `.nano-proactive-hero` - Main component wrapper

### Chat Window

- `.nano-chat-window` - Chat window container
- `.nano-chat-header` - Header bar
- `.nano-chat-content` - Content area (scrollable)
- `.nano-chat-input-area` - Input area (sticky bottom)

### Nano Action Card

- `.nano-action-card-container` - Card container with transitions
- `.nano-action-card` - Main card element
- `.nano-action-header` - Card header
- `.nano-action-title` - "Nano Action" title
- `.nano-action-close` - Close button
- `.nano-action-visual` - Visual section container
- `.nano-action-content` - Content section (title + description)
- `.nano-action-footer` - Footer with icons and CTA

### Shift Cards

- `.nano-shift-cards-carousel` - Horizontal scrollable container
- `.nano-shift-card` - Individual shift card
- `.nano-shift-card-active` - Active state modifier
- `.nano-shift-card-top-bar` - Blue top bar (active cards)
- `.nano-shift-card-content` - Card content wrapper
- `.nano-shift-time` - Time range text
- `.nano-shift-ratio` - Count ratio text
- `.nano-shift-name` - Employee name
- `.nano-shift-duration` - Duration badge

### Visual Components

- `.nano-percentage-cards` - Percentage cards container
- `.nano-percentage-card` - Individual percentage card
- `.nano-percentage-current` - Current state card
- `.nano-percentage-suggested` - Suggested state card
- `.nano-percentage-hint` - Hint text above suggested card
- `.nano-grid-visualization` - Grid container
- `.nano-grid-row` - Grid row
- `.nano-grid-cell` - Grid cell
- `.nano-grid-cell-highlighted` - Highlighted cell modifier
- `.nano-chart-visualization` - Chart container
- `.nano-chart-svg` - SVG chart element

### Content

- `.nano-scenario-title` - Scenario title (bold)
- `.nano-scenario-description` - Scenario description text

### Actions

- `.nano-action-icons` - Icon buttons container
- `.nano-action-icon-btn` - Individual icon button
- `.nano-action-cta` - CTA button
- `.nano-cta-icon` - AI icon in CTA
- `.nano-cta-text` - CTA text
- `.nano-cta-star` - Star icon (optional)

### Input Area

- `.nano-chat-input-container` - Input container
- `.nano-input-icon-btn` - Plus icon button
- `.nano-chat-input` - Input field
- `.nano-input-send-btn` - Send button
- `.nano-quick-actions` - Quick action buttons container
- `.nano-quick-action-btn` - Individual quick action button

## Animation System

### Transition Timing

- **Fade In/Out:** 500ms (`animationDuration`)
- **Display Duration:** 3200-3500ms per scenario (configurable per scenario, optimized for faster cycling)
- **Easing:** `ease-out` for enter, `ease-in` for leave

### Alpine.js Transitions

The component uses Alpine.js `x-transition` directives:

```html
x-transition:enter="transition ease-out duration-500"
x-transition:enter-start="opacity-0 translate-y-4"
x-transition:enter-end="opacity-100 translate-y-0"
x-transition:leave="transition ease-in duration-300"
x-transition:leave-start="opacity-100 translate-y-0"
x-transition:leave-end="opacity-0 translate-y-4"
```

### Auto-Cycle Behavior

1. **Initialization:** Starts after 1 second delay
2. **Timing:** Uses `setTimeout` with dynamic duration per scenario
3. **Pause on Hover:** Auto-cycle pauses when mouse enters component
4. **Resume on Leave:** Auto-cycle resumes when mouse leaves
5. **Animation Lock:** Prevents cycling during transitions (`isAnimating` flag)
6. **Loop:** Wraps to first scenario after last

### Reduced Motion Support

Respects `prefers-reduced-motion` media query:

- Disables transitions
- Disables animations
- Uses instant state changes

## Icon System

Icons are defined in `v2/components/nano-ai/nano-icons.php` as PHP functions:

- `nano_icon_refresh($size, $color)` - Circular refresh arrow
- `nano_icon_feedback($size, $color)` - Speech bubble with star
- `nano_icon_ai($size, $color)` - Stylized AI with sparkle
- `nano_icon_close($size, $color)` - X close icon
- `nano_icon_plus($size, $color)` - Plus icon
- `nano_icon_maximize($size, $color)` - Maximize icon
- `nano_icon_chevron_down($size, $color)` - Chevron down
- `nano_icon_send($size, $color)` - Send/arrow up
- `nano_icon_star($size, $color)` - Star icon

All icons return SVG markup as strings.

## Responsive Design

### Breakpoints

- **Mobile:** `< 640px`

  - Chat window min-height: `550px` (no fixed height, adapts to content)
  - Shift cards: `120px` width
  - Reduced padding: `12px`
  - Stacked quick actions

- **Tablet:** `641px - 1024px`

  - Chat window min-height: `620px` (no fixed height, adapts to content)
  - Shift cards: `130px` width

- **Desktop:** `> 1024px`
  - Chat window min-height: `680px` (no fixed height, adapts to largest content)
  - Component fits largest scenario without scrolling
  - No shrink/expand behavior during animations
  - Shift cards: `150px` width
  - Full padding: `20px`

## Accessibility

### ARIA Labels

- `role="region"` on main container
- `aria-label="Nano AI Proactive Suggestions"` on main container
- `aria-label` on all interactive buttons
- Descriptive labels for actions (e.g., "Aktion ausführen: Schicht verlängern")

### Keyboard Navigation

- **Tab:** Navigate through interactive elements
- **Enter/Space:** Activate buttons
- **Escape:** Close Nano Action card (if implemented)

### Focus States

- `:focus-visible` styles with blue outline (`#4D8EF3`)
- `2px` outline with `2px` offset
- Matches element border radius

### Screen Reader Support

- Semantic HTML structure
- Descriptive text content
- Hidden decorative elements (window controls are `tabindex="-1"`)

## Performance Considerations

### CSS Optimizations

- Uses CSS transforms for animations (not layout properties)
- `will-change` used sparingly
- GPU acceleration via `transform: translateZ(0)` (if needed)

### JavaScript Optimizations

- Scenarios loaded from PHP (no initial fetch delay)
- Fallback fetch only if PHP load fails
- Debounced auto-cycle to prevent rapid switching
- Animation lock prevents concurrent transitions

### Bundle Size

- CSS: `13.8 KB` → `10.1 KB` minified (27.1% reduction)
- Icons: Inline SVG (no external requests)
- No external dependencies beyond Alpine.js

## Usage Example

### Basic Usage

```php
<?php include '../components/nano-ai/proactive-hero-component.php'; ?>
```

### With Custom Scenarios

Modify `docs/data/nano-proactive-scenarios.json` to add/update scenarios. The component automatically loads scenarios from this file.

### Styling Override

Override CSS variables for theme customization:

```css
.nano-proactive-hero {
  --nano-blue: #your-color;
  --nano-button-dark: #your-color;
}
```

## Troubleshooting

### Scenarios Not Loading

1. Check `docs/data/nano-proactive-scenarios.json` exists and is valid JSON
2. Verify file permissions allow read access
3. Check browser console for fetch errors
4. Scenarios should load from PHP on initial render

### Animations Not Working

1. Verify Alpine.js is loaded before component
2. Check `prefers-reduced-motion` is not enabled
3. Verify CSS file is loaded (`nano-proactive-hero.min.css`)
4. Check browser console for JavaScript errors

### Styling Issues

1. Verify CSS file is loaded and minified
2. Check for CSS conflicts with other stylesheets
3. Verify CSS variables are defined
4. Check responsive breakpoints are correct

## Related Documentation

- **[Design Specifications](../design/nano-ai/FIGMA_SPEC.md)** - Complete Figma design specs
- **[Scenario Data](../data/nano-proactive-scenarios.json)** - Scenario JSON structure
- **[Nano AI Page Documentation](nano-ai-documentation.md)** - Overall page documentation
- **[Nano AI Benefits](../product-features/nano-ai-benefits.md)** - Benefits documentation

## Maintenance

### Adding New Scenarios

1. Edit `docs/data/nano-proactive-scenarios.json`
2. Add new scenario object to `scenarios` array
3. Update `metadata.totalScenarios` count
4. Test component displays new scenario correctly

### Modifying Visual Types

1. Update scenario `visualType` and `visualData` in JSON
2. Add corresponding template in `proactive-hero-component.php` if new type
3. Add CSS styles for new visual type in `nano-proactive-hero.css`

### Updating Icons

1. Modify icon functions in `nano-icons.php`
2. Icons are SVG, so update paths/attributes as needed
3. Test icons display correctly at all sizes

## Rollback Procedure

To revert to old component:

1. Restore backup: `cp chat-hero-component.php.backup chat-hero-component.php`
2. Update `product_nano_ai.php` to include old component
3. Remove `nano-proactive-hero.min.css` from head section
4. Test page loads correctly