facebook / facebook/astryx

feat(lab): DialogHeroHeader — hero-style Dialog header (port from XDSModalHeroHeader)

Open
#4,182 2 comments 0 reactions 1 assignee Claimed by @cixzhang View on GitHub
component enhancement
Dominant language
TypeScript
Stars
13k
Forks
1.1k
Avg merge
1d 15h
Merged PRs (30d)
690

Description

## Summary

Add a **`DialogHeroHeader`** component — a richer, "hero"-style header for `Dialog`, similar to the internal `XDSModalHeroHeader`. Port the *value and behavior*, not the internal structure or naming (`Modal` → `Dialog` to match Astryx's dialog primitive).

## Why

`Dialog` today has `DialogHeader` — a compact title + subtitle + close-button row built on `LayoutHeader`. `DialogHeroHeader` is the **prominent, high-emphasis** variant: a larger header treatment for dialogs that open onto a featured/marketing/onboarding moment (e.g. a hero image or illustration, larger title, supporting text), where the standard `DialogHeader` is too understated.

This is a **sibling of `DialogHeader`, not a replacement** — consumers choose the compact header or the hero header depending on the dialog's purpose.

## Proposed behavior (confirm against the internal source during the port)

- Composes with `Dialog` the same way `DialogHeader` does (drop into `Layout`'s `header` slot).
- Hero treatment: prominent title, optional supporting text, and a media/visual slot (image, illustration, or icon) — exact anatomy to be derived from `XDSModalHeroHeader`.
- Close-button behavior consistent with `DialogHeader` (`onOpenChange`-driven).
- Extends `BaseProps`, `xstyle`/`className`/`style` escape hatches, `displayName`, `'use client'`.
- Reuse existing primitives — `Heading`, `Text`, `Button`, `Icon`, `LayoutHeader` — not raw HTML. StyleX + semantic tokens only.

## Scope

- Land in **`@astryxdesign/lab`** first (canary-only), following the lab → core graduation path — or as a `Dialog` sub-component if that fits the family better (decide during port).
- Full component surface: implementation, colocated test, `.doc.mjs`, `index.ts` export, Storybook story, showcase block.

## Open questions for the port

- Name: `DialogHeroHeader` vs. a `variant`/`hero` mode on `DialogHeader`. Prefer a distinct component if the anatomy diverges enough; reference the sibling `DialogHeader` API for consistency.
- Which slots does the internal `XDSModalHeroHeader` expose (media, eyebrow, title, description, actions)? Port the ones that carry value; drop internal-only structure.
- Any semantic-name/API differences from the internal version resolve to Astryx conventions.

## Acceptance criteria

- [ ] `DialogHeroHeader` renders a hero-style header that composes with `Dialog` via the `Layout` header slot.
- [ ] Close-button/`onOpenChange` behavior consistent with `DialogHeader`.
- [ ] Composes from existing primitives; StyleX + tokens only; `BaseProps` escape hatches, `displayName`, `'use client'`.
- [ ] Colocated test, `.doc.mjs`, Storybook story, showcase block, export wired.
- [ ] Lands in lab (or as a documented Dialog sub-component); documented as lab/canary if in lab.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.