# Home BD Module Architecture

## Overview
- Module lives in `pages/home-bd/` and powers the Bangladesh home page via shortcodes dropped into Elementor or the block editor.
- Content editors manage all copy, media, toggles, and section ordering from the "Remark Builder > Home (Bangladesh)" options page that this module registers.
- Each shortcode pulls ACF option data, renders a scoped markup fragment, then triggers `remark_load_page_assets('home-bd')` so CSS/JS/animation bundles load once per request.
- Markup sticks to `.remark-home-bd-*` name spacing so page styles and scripts stay isolated from the rest of the theme.

## Directory Layout
- `pages/home-bd/acf.php` - Registers the Home (Bangladesh) builder field group, per-section toggles, and the tabbed admin layout.
- `pages/home-bd/shortcodes.php` - Declares the rendering pipeline for every section shortcode and automatically enqueues the page assets.
- `pages/home-bd/page.css` - Base layout, typography, responsive rules, and component styling for all Home BD sections.
- `pages/home-bd/page.js` - Page-level behaviour (currently spins up the Swiper carousel for the Blogs section).
- `pages/home-bd/page.anim.js` - GSAP/ScrollTrigger timelines for hero reveals, section fades, stat counters, marquee logos, and button flair.
- `pages/home-bd/README.md` - On-boarder for editors/devs working only inside this module.

## ACF Field Structure (`acf.php`)
- Registers the local field group `group_remark_home_bd_builder` against the options page slug `remark-home-bd`.
- Tabs mirror the front-end sections so editors can hop between "Hero", "Brands", "Promo 1", "Promo 2", "Certificates", "CTA Banner", and "Blogs".
- Section toggles use `true_false` fields; shortcodes bail early when a section is disabled to avoid empty wrappers.
- Brand stats repeater captures icon/image, animated number ranges (start/end/step/decimals), suffix text, and supporting copy; animation hooks rely on the numeric metadata.
- Promo 1 + Promo 2 store multi-line titles, subtitles, badge text, media, and CTA data; Promo 1 exposes stroked CTA styling, Promo 2 supports a linked badge pill.
- Certificates repeater collects images only; Blogs section configures CTA label/link, posts-per-page, and optional category filters.
- A final `acf/load_field_group/key=group_remark_home_bd_builder` filter re-injects the Blogs, Certificates, and CTA tabs in a fixed order. This prevents the optional tabs from drifting when ACF reorders fields during sync.

## Rendering & Shortcodes (`shortcodes.php`)
- All shortcodes resolve the options `post_id` via `remark_get_options_post_id('home-bd')`, sanitise values, and return early if the section has no meaningful data.
- **`[remark_home_bd_hero]`** - Builds the hero headline (desktop + mobile variants), badge, subtitle, CTA button, and optional image. Double braces (`{{ }}`) in headings become highlighted spans that the CSS/animations accent.
- **`[remark_home_bd_brands]`** - Outputs hero-style heading, summary, CTA, stat grid, and animated marquee of brand logos. Logos pull from the separate "Brands" options page, so the section stays in sync with the global brand registry.
- **`[remark_home_bd_promo_1]`** - Full-width media block with stacked title lines, description, optional CTA (stroke style), and image. Multi-line titles are split into `<span>` rows for fine-grained styling.
- **`[remark_home_bd_promo_2]`** - Two-column feature with badge (optionally linked), title, subtitle, rich description, and image. Badge text shares the hero gradient treatment for animation parity.
- **`[remark_home_bd_cta_banner]`** - Compact CTA band with editable copy, button, image, and background colour. Background colour defaults to `#00357A` but can be overridden per content entry.
- **`[remark_home_bd_certificates]`** - Renders a responsive image grid so editors can drop accreditation logos. Section quietly skips rendering when disabled or when the repeater is empty.
- **`[remark_home_bd_blogs]`** - Queries recent `post` entries (respecting category filters and `posts_per_page` limits). Includes an optional CTA linking to the long-form archive and loads Swiper's CDN assets to present the posts inside a horizontal carousel.

## Front-End Behaviour
- **CSS (`page.css`)** - Establishes the shared colour variables, hero layout, gradients, stat cards, marquee tracks, promo sections, certificates grid, and blog card styling. Uses responsive clamps to keep typography and spacing fluid across breakpoints.
- **JavaScript (`page.js`)** - Detects Swiper availability and instantiates a free-mode carousel with responsive slide counts (approx 1.2 cards on mobile, 3.5 on desktop). Gracefully no-ops if CDN assets fail to load.
- **Animations (`page.anim.js`)** - Registers GSAP + ScrollTrigger, fades hero subcomponents in sequence, animates section entrances, runs gradient text loops, counts stat numbers using data attributes, creates GSAP-powered marquee loops for brand logos, and wires up magnetic button flair interactions.

## Working Patterns & Extension Tips
- Add fields: extend `acf.php`, then sync the local JSON via ACF PRO so the PHP stays the source of truth.
- New shortcode sections should follow the existing guard pattern (feature flag, data presence checks, `remark_load_page_assets`) to avoid shipping empty markup.
- Keep new markup scoped to `.remark-home-bd-*` prefixes so existing CSS/JS rules do not leak into other templates.
- If a section depends on global data (e.g. brands CPT or options), resolve the related options page once per render and guard against missing rows.
- When integrating third-party scripts, mirror the Blogs section approach: enqueue via CDN inside the shortcode and defensively check for globals before calling constructors in `page.js`.