# HomAroma Admin Section Guide

This guide explains the dynamic page blocks available in the Page Builder and what each block contains.

## Field Shape Legend

- `localized string` = plain text or `{ th, en, ja, zh, vi, ko }`
- `plain string` = one string only
- `optional` = can be omitted

## Available Blocks

### `HERO`

- Purpose: Main hero banner for a page
- Contains:
  - `tagline` localized string
  - `title` localized string
  - `description` localized string
  - `imageUrl` plain string
  - `buttonText` localized string
  - `buttonLink` plain string
- Best for: Landing pages, featured campaigns, page introductions

### `BANNER`

- Purpose: Image banner with optional CTA
- Contains:
  - `imageUrl` plain string
  - `linkUrl` plain string
  - `title` localized string optional
  - `description` localized string optional
  - `buttonText` localized string optional

### `TEXT`

- Purpose: Simple content block
- Contains:
  - `title` localized string optional
  - `content` localized string
  - `textAlign` plain string optional: `left`, `center`, `right`

### `ANNOUNCEMENT_BAR`

- Purpose: Rotating announcement strip
- Contains:
  - `slides` array of localized strings
  - `backgroundColor` plain string optional
  - `textColor` plain string optional
  - `speed` number optional

### `NEWSLETTER`

- Purpose: Newsletter signup panel
- Contains:
  - `title` localized string
  - `description` localized string
  - `buttonText` localized string
  - `placeholderText` plain string optional
  - `showPrivacyCheckbox` boolean
  - `privacyText` plain string optional

### `EDITORIAL_TILE`

- Purpose: Side-by-side editorial story tile
- Contains:
  - `title` localized string
  - `description` localized string
  - `imageUrl` plain string
  - `imagePosition` plain string: `left` or `right`
  - `buttonText` plain string optional
  - `buttonLink` plain string optional
  - `backgroundColor` plain string optional
  - `textColor` plain string optional

### `EDITORIAL_CAROUSEL`

- Purpose: Multi-slide editorial storytelling block
- Contains:
  - `title` localized string
  - `slides` array of:
    - `category` localized string
    - `title` localized string
    - `description` localized string
    - `imageUrl` plain string
    - `buttonText` plain string optional
    - `buttonLink` plain string optional

### `PRODUCTS`

- Purpose: Product list/grid section
- Contains:
  - `title` localized string
  - `subtitle` localized string optional
  - `type` plain string: `featured`, `scent`, or `custom`
  - `scentId` number optional
  - `productIds` number array optional
  - `limit` number optional
  - `layout` plain string optional: `grid` or `carousel`
  - `enableQuickShop` boolean optional

### `CATEGORIES`

- Purpose: Category showcase block
- Contains:
  - `title` localized string
  - `subtitle` localized string optional
  - `categoryIds` number array optional

### `HERO_ARTICLE`

- Purpose: Editorial hero/article header
- Contains:
  - `title` localized string
  - `subtitle` localized string optional
  - `author` localized string optional
  - `category` localized string optional
  - `publishDate` plain string optional
  - `date` plain string optional
  - `imageUrl` plain string
  - `backgroundImageUrl` plain string optional
  - `overlayColor` plain string optional
- Notes:
  - The image is set by entering an image URL in `imageUrl`
  - In the Admin UI, the image picker stores the URL for you

### `RICH_TEXT`

- Purpose: Flexible HTML/text content block
- Contains:
  - `title` localized string optional
  - `content` localized string required
- Notes:
  - HTML is allowed
  - Use language tabs to translate each version

### `SCENT_NOTES_BREAKDOWN`

- Purpose: Fragrance layer breakdown
- Contains:
  - `title` localized string optional
  - `description` localized string optional
  - `topNotes` array of strings or localized string objects
  - `heartNotes` array of strings or localized string objects
  - `middleNotes` array of strings or localized string objects
  - `baseNotes` array of strings or localized string objects
- Notes:
  - `heartNotes` and `middleNotes` are mirrored together by the backend

### `QUOTE_CALLOUT`

- Purpose: Highlighted quote block
- Contains:
  - `quote` localized string required
  - `author` localized string optional
  - `role` localized string optional

### `PRODUCT_CAROUSEL`

- Purpose: Featured product carousel
- Contains:
  - `title` localized string optional
  - `description` localized string optional
  - `collectionId` plain string optional
  - `limit` number optional
  - `showPrice` boolean optional
  - `showAddToCart` boolean optional
  - `products` optional explicit product list
- Notes:
  - If `products` is omitted, the backend can auto-populate products on read-back

### `ACCORDION`

- Purpose: FAQ-style expandable block
- Contains:
  - `title` localized string optional
  - `categories` required array
    - each category has:
      - `name` localized string
      - `icon` plain string optional
      - `questions` required array
        - each question has:
          - `q` localized string
          - `a` localized string

### `CONTACT_INFO`

- Purpose: Contact details block
- Contains:
  - `title` localized string optional
  - `address` localized string required
  - `email` plain string required
  - `line` plain string required
  - `hours` localized string required

### `CONTACT_FORM`

- Purpose: Contact form header block
- Contains:
  - `title` localized string optional
  - `subtitle` localized string optional
- Notes:
  - This block has no extra fields beyond title and subtitle

## Recommended Admin Workflow

1. Create or open a page.
2. Add blocks in the order you want them rendered.
3. Fill localized fields per language.
4. Use the media picker or image URL fields for image-based blocks.
5. Save the block, then verify the rendered page.

## Quick Tips

- Use `HERO_ARTICLE` for editorial-style stories.
- Use `RICH_TEXT` for long-form content.
- Use `SCENT_NOTES_BREAKDOWN` for fragrance layer storytelling.
- Use `PRODUCT_CAROUSEL` when you want featured products without manually listing each one.
- Use `ACCORDION` for FAQ content.
- Use `CONTACT_INFO` and `CONTACT_FORM` together for contact pages.