# Cards & Configuration

This page documents every frontend resource in the integration, including the shared helper module. Card examples assume a profile sensor such as `sensor.anna`.

## Card Selection Guide

### Good standalone choices
- `custom:menstruation-cycle-card` for daily interaction
- `custom:menstruation-cycle-compact-status` for quick status display
- `custom:menstruation-calendar-card` for month planning
- `custom:menstruation-cycle-history-card-row` for recent trends
- `custom:menstruation-cycle-heatmap-card` for long-term pattern review
- `custom:menstruation-countdown-timer` for product reminders
- `custom:menstruation-product-inventory-card` for shared stock management
- `custom:menstruation-statistics-card` for analytics and hygiene review

### Recommended combinations
- **Daily dashboard:** main card + compact status + countdown timer
- **Planning dashboard:** calendar + history row + main card
- **Analytics dashboard:** heatmap + statistics + history row
- **Household dashboard:** inventory card + countdown timer + statistics card

## Dashboard layout patterns

| Layout | Recommended cards |
| --- | --- |
| Phone | compact status, countdown timer, calendar |
| Tablet | main card, calendar, statistics |
| Desktop | main card, history row, heatmap, statistics, inventory |

## Theme examples

`theme_mode: auto`, `light`, and `dark` are available on the main card.

---

## 1. Main interactive card
<img width="292" height="447" alt="Menstrual Cycle Card" src="https://github.com/user-attachments/assets/c0e1a498-4960-4abb-9e13-45f03a64107d" />

**File:** `menstruation-cycle-card.js`  
**Card type:** `custom:menstruation-cycle-card`

Daily-use card for cycle status, editing, calendar navigation, and profile-specific interaction.

```yaml
type: custom:menstruation-cycle-card
entity: sensor.anna
friendly_name: Anna
title: Cycle of Anna
period_duration_days: learnt
show_editor: true
theme_mode: auto
show_fertile_period: true
show_predicted_cycles: true
num_predicted_cycles: 6
calendar_edit_enabled: true
```

| Option | Purpose |
| --- | --- |
| `entity` or `entry_id` | Target profile |
| `friendly_name` | Display label override |
| `title` | Card title |
| `period_duration_days` | Number `1..14` or `learnt` |
| `show_editor` | Show inline editor controls |
| `theme_mode` | `auto`, `light`, or `dark` |
| `show_fertile_period` | Show fertile markers |
| `show_predicted_cycles` | Show forecast overlays |
| `num_predicted_cycles` | Limit future predictions |
| `calendar_edit_enabled` | Allow calendar-based edits |

**Use cases:** daily input, editing history, primary dashboard card  
**Recommended companions:** compact status, calendar, countdown timer

## 2. Compact status card
<img width="371" height="106" alt="Compact Card" src="https://github.com/user-attachments/assets/33364a90-a5ba-49c1-ad4b-8b97654d7e64" />

**File:** `menstruation-cycle-compact-status-card.js`  
**Card type:** `custom:menstruation-cycle-compact-status`

Minimal phase and day indicator for glanceable status.

```yaml
type: custom:menstruation-cycle-compact-status
entity: sensor.anna
title: Status
show_title: false
```

| Option | Purpose |
| --- | --- |
| `entity` or `entry_id` | Target profile |
| `title` | Optional title |
| `show_title` | Show or hide the label |

**Use cases:** header rows, overview pages, phone dashboards  
**Recommended companions:** main card, countdown timer

## 3. History row card
<img width="1124" height="445" alt="History row card" src="https://github.com/user-attachments/assets/5cba9b65-3a11-44c8-9b10-65c9f1dadd6a" />

**File:** `menstruation-cycle-history-card-row.js`  
**Card type:** `custom:menstruation-cycle-history-card-row`

Timeline-style overview for historical periods, predicted cycles, and special states.

```yaml
type: custom:menstruation-cycle-history-card-row
entity: sensor.anna
title: Cycle History
max_rows: 12
show_fertile_window: true
show_pregnancy_status: true
show_menarche_status: true
show_predicted_cycles: true
num_predicted_cycles: 6
```

| Option | Purpose |
| --- | --- |
| `entity` or `entry_id` | Target profile |
| `title` | Card title |
| `max_rows` | Maximum timeline rows |
| `show_fertile_window` | Show fertile window segments |
| `show_pregnancy_status` | Include pregnancy state hints |
| `show_menarche_status` | Include pre-menarche/menarche states |
| `show_predicted_cycles` | Include forecast rows |
| `num_predicted_cycles` | Limit predicted rows |

**Use cases:** reviewing trends, comparing recent cycles  
**Recommended companions:** calendar, heatmap, statistics

## 4. Heatmap card
<img width="371" height="572" alt="Heatmap Card" src="https://github.com/user-attachments/assets/46e271b1-f560-48e7-b4d8-7c7d2394c670" />

**File:** `menstruation-cycle-heatmap-card.js`  
**Card type:** `custom:menstruation-cycle-heatmap-card`

Long-term heatmap for pattern review across many cycles. Prepared for additional symptom overlays.

```yaml
type: custom:menstruation-cycle-heatmap-card
entity: sensor.anna
title: Cycle Heatmap
max_cycles: 18
period_duration_days: 5
show_fertile_period: true
show_predicted_cycles: true
num_predicted_cycles: 6
cycle_alignment: bottom
symptom_entities:
  - entity: sensor.anna_pms_nausea
    name: Nausea
    icon: mdi:emoticon-sick-outline
```

| Option | Purpose |
| --- | --- |
| `entity` or `entry_id` | Target profile |
| `title` | Card title |
| `max_cycles` | Number of cycles to render |
| `period_duration_days` | Period marker length |
| `show_fertile_period` | Show fertile overlays |
| `show_predicted_cycles` | Show forecasts |
| `num_predicted_cycles` | Limit future cycles |
| `cycle_alignment` | `top` or `bottom` alignment |
| `symptom_entities` | Experimental overlay inputs |

**Use cases:** spotting recurring timing patterns  
**Recommended companions:** history row, statistics

## 5. Calendar card
<img width="374" height="533" alt="Calendar Card" src="https://github.com/user-attachments/assets/24e7e4b9-ea14-4d10-bcc1-1c9735532f40" />

**File:** `menstruation-calendar-card.js`  
**Card type:** `custom:menstruation-calendar-card`

Month view with period, fertile window, ovulation, and cycle-day details.

```yaml
type: custom:menstruation-calendar-card
entity: sensor.anna
title: Cycle Calendar
show_fertile_period: true
show_ovulation_marker: true
show_cycle_day_numbers: false
week_start: monday
show_predicted_cycles: true
num_predicted_cycles: 6
```

| Option | Purpose |
| --- | --- |
| `entity` or `entry_id` | Target profile |
| `title` | Card title |
| `show_fertile_period` | Show fertile range |
| `show_ovulation_marker` | Show ovulation marker |
| `show_cycle_day_numbers` | Display cycle day labels |
| `week_start` | `monday` or `sunday` |
| `show_predicted_cycles` | Show predicted future states |
| `num_predicted_cycles` | Limit forecast count |

**Use cases:** month planning, reviewing dates, shared household visibility  
**Recommended companions:** main card, history row

## 6. Countdown timer card
<img width="292" height="432" alt="Countdown timer card" src="https://github.com/user-attachments/assets/c0829b12-4421-4359-8d7d-aaefbdda7de8" />

**File:** `menstruation-countdown-timer.js`  
**Card type:** `custom:menstruation-countdown-timer`

Product replacement timer with direct `menstruation_cycle.log_product_usage` integration.

```yaml
type: custom:menstruation-countdown-timer
entity: sensor.anna
tampon_duration: 4
pad_duration: 4
cup_duration: 7
underwear_duration: 6
liner_duration: 8
```

| Option | Purpose |
| --- | --- |
| `entity` or `entry_id` | Target profile |
| `tampon_duration` | Hours before reminder |
| `pad_duration` | Hours before reminder |
| `cup_duration` | Hours before reminder |
| `underwear_duration` | Hours before reminder |
| `liner_duration` | Hours before reminder |

**Use cases:** active-period reminders and one-tap logging  
**Recommended companions:** statistics, inventory card

## 7. Product inventory card
<img width="290" height="703" alt="Product inventory card" src="https://github.com/user-attachments/assets/6264911b-dbe5-4d9f-b1f0-f771d07bf7a4" />

**File:** `menstruation-product-inventory-card.js`  
**Card type:** `custom:menstruation-product-inventory-card`

Shared household stock overview with consume, refill, threshold, and shopping-list workflows.

```yaml
type: custom:menstruation-product-inventory-card
inventory_entity: sensor.household_product_stock
title: Household inventory
member: ""
visible_products:
  - tampon
  - pad
  - cup
  - liner
  - underwear
```

| Option | Purpose |
| --- | --- |
| `inventory_entity` | Household inventory sensor |
| `title` | Card title |
| `member` | Filter/member label for manual actions |
| `visible_products` | Which product tiles to show |
| `product_order` | Optional explicit ordering |
| `thresholds` | Optional warning/critical settings |
| `underwear_total_owned` | Total owned pieces |
| `underwear_washing_threshold` | Washing alert threshold |

**Use cases:** shared households, supply planning, shopping reminders  
**Recommended companions:** countdown timer, statistics card

## 8. Statistics card
<img width="294" height="689" alt="Statistics Card" src="https://github.com/user-attachments/assets/3b2b8611-8a19-4be6-8f09-124f4ac0af32" />


**File:** `menstruation-statistics-card.js`  
**Card type:** `custom:menstruation-statistics-card`

Statistics, hygiene usage review, and doctor-report export entry point.

```yaml
type: custom:menstruation-statistics-card
entity: sensor.anna
title: Statistics
```

| Option | Purpose |
| --- | --- |
| `entity` or `entry_id` | Target profile |
| `title` | Card title |

**Use cases:** planning, usage review, report preparation  
**Recommended companions:** heatmap, countdown timer, inventory card

### Product usage data surfaced to cards

When product logging is active, the profile sensor exposes usage-related attributes that several cards reuse:

- `product_usage_today`
- `product_usage_this_cycle`
- `product_usage_stats`
- `product_usage_timeline`

These attributes power the hygiene-focused parts of the statistics and timer workflows.

## 9. Shared icons helper

**File:** `menstruation-icons.js`  
**Card type:** none - shared helper asset

This module provides shared icon assets and helpers used by multiple cards for state, product, and pregnancy icons.

| Item | Purpose |
| --- | --- |
| Shared SVG/icon mapping | Reused across frontend cards |
| Asset base URL handling | Keeps icon loading consistent |
| Product/state icon lookup | Standardizes visuals |

**Use cases:** loaded indirectly by frontend cards  
**Recommended companions:** all card resources

## Example dashboard stack

```yaml
type: vertical-stack
cards:
  - type: custom:menstruation-cycle-card
    entity: sensor.anna
    title: Cycle Overview
    show_editor: true
    show_fertile_period: true
    calendar_edit_enabled: true
  - type: custom:menstruation-countdown-timer
    entity: sensor.anna
    tampon_duration: 4
    pad_duration: 4
    cup_duration: 7
    underwear_duration: 6
    liner_duration: 8
  - type: custom:menstruation-statistics-card
    entity: sensor.anna
    title: Statistics
```