# Page builder: section library

Owner: FRONTEND (builder). For the backend engineer and the owner.

Each section is one definition `resources/blocks/{type}.php` (label, description, icon, group, heading, fields with default values) and one view `resources/views/blocks/{type}.blade.php`. Shared view pieces live in `resources/views/blocks/partials/` (not section types). Styles: `resources/css/blocks.css` (+ `resources/css/blocks/*.css`); behaviour: `resources/js/blocks.js`. Both are pushed by the section views themselves, once per page (`@pushOnce('head', 'builder-blocks-css')`, `@pushOnce('scripts', 'builder-blocks-js')`), so pages without sections do not load them. Preview locally: `/_blocks` (all, default values) or `/_blocks/hero-simple,text,cta`.

Every section works in any order, any number of times on one page, with any optional field empty (a section with nothing to show renders nothing). Text is escaped; only `richtext` (Text section) is printed as stored. Links accept site paths, `https://`, `http://`, `mailto:` and `tel:`; anything else (for example `javascript:`) is dropped. Highlight fields ("part shown in mint") must be part of the title; if the title is rewritten and the highlight no longer appears in it, it is ignored.

Spacing: ordinary sections are separated by one even gap (about 64 to 130 px depending on the screen); scenes (pinned scenes, heroes, big number) bring their own full-screen space. Use "Space and line" for a deliberate pause.

| Section (type) | Group | What it is for | Fields | Constraints and advice |
|---|---|---|---|---|
| Hero: fly through a word (`hero-word`) | Hero | Opening scene of a product or campaign page: one word of the title is a window onto moving light; scrolling flies through it and lands on a big line with names. Can carry the page's h1. | title before, big word, title after, text, button + link, second button + link, landing line, landing highlight, names (list: name) | Big word: one word, 4 to 10 letters is best (longer words get smaller). Words after: up to about 40 characters. Names: 2 to 6 short names. Use once, at the top. Without a landing line and names, the whole title comes back at the end of the scroll. |
| Hero: simple (`hero-simple`) | Hero | Calm opening for ordinary pages, offers, articles. Can carry the h1. | eyebrow, title, title highlight, introduction, two buttons, picture + alt | Picture optional: a transparent PNG/WebP about 800 px wide floating on a glow; without a picture the title is centred over dimmed light. Title up to about 8 words. |
| Scene: the product rises (`rise`) | Scenes | Pinned scene: title, then a screenshot rises in a device while names light up. Use after a hero. | title, subtitle, screenshot + alt, frame (laptop, monitor, tablet, phone, white frame, none), names (list) | Screenshot: landscape, at least 1600 px wide for laptop or monitor; portrait for phone. Title up to about 8 words. Names 2 to 6. Without a screenshot it is a plain (not pinned) title. |
| Scene: turning screens (`deck`) | Scenes | Pinned scene: screenshots turn like cards while a giant title and text change. 2 to 5 features of one product. | items (list: title, screenshot, alt, text, link label, link) | 2 to 5 items (6 maximum shown). Titles 1 to 4 words; text up to about 250 characters (longer text can run into the bottom of the screen on phones). Landscape screenshots; they are cropped to 640:420 from the top. |
| Big number (`number`) | Scenes | One giant figure that counts up, with caption and sentence. | prefix, number, suffix, caption, sentence, background picture | Number: digits only to count up (1,000 with a comma is shown as typed, without counting). Background: wide, at least 1920 px; it is darkened. |
| Statement (`statement`) | Text and pictures | One big sentence lighting up word by word, optional paragraph and link. Can carry the h1. | eyebrow, statement, highlight, paragraph, link label + link | One sentence, up to about 15 words. |
| Statement with picture (`statement-picture`) | Text and pictures | Statement beside a picture that moves in. Use several in a row, alternating sides. | statement, highlight, paragraph, link label + link, picture + alt, side (right, left), motion (tilts flat, shutter, slides in, rests on a glow), frame (white frame, none) | Picture about 1000 px wide. Screenshots: white frame; transparent illustrations: no frame with "slides in" or "rests on a glow". Very tall pictures are cropped to one screen. |
| Big sliding lines (`lines`) | Text and pictures | Short strengths in very large type, each with a sentence (home "strengths"). | small title, lines (list: small label, line, sentence), link label + link | 2 to 5 lines; each line 1 to 4 words (it is very large type). |
| Text (`text`) | Text and pictures | Comfortable reading text: articles, terms, explanations. Can carry the h1. | title, text (rich text) | Inside the rich text use Heading 2/3 for sub-headings when the section has no title, Heading 3 when it has one. Any length. |
| Picture (`picture`) | Text and pictures | One large picture or screenshot in a frame or device, with caption. | picture + alt, frame (white frame, none, laptop, monitor, tablet, phone), caption | At least 1600 px wide for white frame, laptop or monitor; portrait for phone. Tall pictures are limited to one screen height. |
| Video (`video`) | Text and pictures | Poster with a play button opening the site's video player. | title, text, video (MP4), poster + alt, play button text (screen readers) | Poster landscape about 1600 px wide (cropped to 16:9). Without JavaScript the link opens the MP4. |
| Check list (`checks`) | Text and pictures | Title with short points and check marks, in large type. Can carry the h1. | title, highlight, text, points (list), link label + link | 2 to 10 points, a few words each. |
| Testimonials (`quote`) | Proof and conversion | Quotes one at a time with name, role and photo; dots, previous/next, pause. | title, quotes (list: quote, name, role, photo, photo alt), button texts for screen readers | 1 to 5 quotes (8 maximum shown), up to about 350 characters each. Photo optional (square); without a photo the initials are shown. Quotes change every 7 s only while on screen and not hovered/focused; never with reduced motion. |
| Plans and prices (`plans`) | Proof and conversion | Plan cards with price, features and a button; one highlighted. Can carry the h1. | title, text, label on the highlighted plan, plans (list: name, price, period, features one per line, button label + link, highlighted yes/no) | 1 to 4 plans (4 maximum shown); up to about 10 features each. Buttons carry `data-track="plan_click"`. |
| Questions and answers (`faq`) | Proof and conversion | Questions that open to show the answer (works without JavaScript). Can carry the h1. | title, questions (list: question, answer plain text) | Any number. Answers keep line breaks. |
| Call to action (`cta`) | Proof and conversion | The big close: label, statement, one line, one or two buttons. Can carry the h1. | eyebrow, statement, highlight, text, two buttons | Statement up to about 10 words. |
| Form (`form`) | Proof and conversion | One of the three iDealers forms on the light panel, title and text beside it. Can carry the h1. | which form (request a demo, contact, talk to sales), title, text | No free address on purpose: the form address comes from Settings (forms.*), its height and screen-reader title from the matching page's content, so the Content-Security-Policy keeps working. The phone bar steps aside while the form is on screen. |
| Links with icons (`links`) | Proof and conversion | Centred row of links with small icons (home product row). | title, group name for screen readers, links (list: label, link, icon) | 2 to 8 links; icons square, 80 px or more (optional). |
| Space and line (`divider`) | Layout | Extra breathing space, optional thin line. | extra space (none, medium, large), line (yes, no) | Adds to the normal gap; use sparingly. |

## Notes for the backend engineer

- The views push their own CSS/JS with `@pushOnce` keys `builder-blocks-css` / `builder-blocks-js`. If a layout or page also pushes `resources/css/blocks.css` / `resources/js/blocks.js`, use `@pushOnce` with the same keys (or drop it) to avoid loading them twice. The form section also pushes a preconnect to idealers.app (key `builder-form-preconnect`).
- The registry gives the h1 to the first heading-capable section even when that section's title is empty, so the page then has no h1. Suggest: also require a non-empty title (`title` field) before handing out the h1, or validate in the admin.
- The preview route uses `id = type`, so the same type twice gets the same `$block['id']`; the views add `$block['index']` to every id, so ids stay unique either way.
- Vertical rhythm relies on collapsing margins: render the sections as plain siblings inside `<main>` or a block-level wrapper (not inside a flex or grid container). A flow section that is the first child of `<main>` clears the header by itself.
- Default values are complete, so a freshly added section looks finished. Missing keys in stored data fall back to these defaults (registry behaviour).
