From 5ef89da20c9624c2fa0be2a75cd889ca3a48b690 Mon Sep 17 00:00:00 2001 From: Adam Kudrna Date: Thu, 2 Nov 2023 17:24:14 +0100 Subject: [PATCH] Docs(web-react): Extend `Header` README to be as detailed as in the Twig implementation --- .../web-react/src/components/Header/README.md | 751 +++++++++++------- 1 file changed, 442 insertions(+), 309 deletions(-) diff --git a/packages/web-react/src/components/Header/README.md b/packages/web-react/src/components/Header/README.md index 857a403bac..c89537e8af 100644 --- a/packages/web-react/src/components/Header/README.md +++ b/packages/web-react/src/components/Header/README.md @@ -4,398 +4,531 @@ The Header is a highly variable and customizable component. It comes in several design variants and provides a handful of building blocks you can use to achieve your specific design goals. -The Header and HeaderDialog are a composition of several subcomponents: +The Header is a composition of several subcomponents: -```jsx -
- - - - - - - - - - - - - -``` +- [Header](#minimal-header) + - [HeaderMobileActions](#mobile-only-actions) + - [HeaderDesktopActions](#desktop-only-actions) + - [HeaderNav](#navigation) + - [HeaderNavItem](#navigation) + - [HeaderLink](#navigation) +- [HeaderDialog](#header-dialog) + - [HeaderDialogCloseButton](#close-button) + - [HeaderDialogActions](#primary-and-secondary-actions) + - [HeaderDialogNav](#navigation-1) + - [HeaderDialogNavItem](#navigation-1) + - [HeaderDialogLink](#navigation-1) + - [HeaderDialogText](#navigation-1) + +## Accessibility Guidelines -## Minimal inverted Header +👉 The animation effect of this component is dependent on the +`prefers-reduced-motion` media query. + +🌍 Although we don't need it yet, this component experimentally supports RTL +languages (because just a single line had to be added to make it all work 🎉). + +## Minimal Header + +Without any modifier, Header is ready to contain necessary blocks in a classic +left-to-right layout (in LTR documents). Please note it is fully transparent +unless you specify a color variant. ```jsx -
- - Company +
+ + Spirit
``` -## Header Actions +## Color Variants -```jsx -const [isOpen, setOpen] = useState(false); +Currently, Header comes in two color variants: **transparent** (for dark +backgrounds) and **inverted** (for light backgrounds). Use the `color` property +to apply the desired background color to Header. -const handleOpen = () => setOpen(true); -const handleClose = () => setOpen(false); - -// Header +```jsx
- - Company + + Spirit - - - - - Current menu link - - - Menu link - - … - - - - - - … -
-// HeaderDialog - - - - - - Current menu link - - - Menu link - - … - - - - - - … - - ``` -## Header Actions and Header Dialog - -```jsx -const [isMenuOpen, setMenuOpen] = useState(false); -const [isUserMenuOpen, setUserMenuOpen] = useState(false); +## Simple Header -const handleMenuOpen = () => setMenuOpen(true); -const handleMenuClose = () => setMenuOpen(false); -const handleUserMenuOpen = () => setUserMenuOpen(true); -const handleUserMenuClose = () => setUserMenuOpen(false); +The `isSimple` modifier makes the header bar slightly shorter and aligns its +content to the center. Use this design variant when all you need on the page is +just branding. -// Header -
- - - - - - - - Current menu link - - - Menu link - - … - - - - - - - Marian - - - - +```jsx +
+ + Spirit +
-// HeaderDialog #1 - - - - - - Current menu link - - - Menu link - - … - - - - - - Marian - - - Dashboard - - - Profile - - … - - Sign out - - - - -// HeaderDialog #2 - - - - - - Dashboard - - - Profile - - … - - Sign out - - - - ``` -## Header +## API -### API +| Name | Type | Default | Required | Description | +| ------------------ | ----------------------------- | ------------- | -------- | ----------------------------------- | +| `children` | `ReactNode` | — | ✕ | Children node | +| `color` | [`transparent` \| `inverted`] | `transparent` | ✕ | Color variant | +| `isSimple` | `bool` | `false` | ✕ | Shorter, centered version of Header | +| `UNSAFE_className` | `string` | — | ✕ | Custom class name | +| `UNSAFE_style` | `CSSProperties` | — | ✕ | Custom style | -| Name | Type | Default | Required | Description | -| ------------------ | ----------------------------- | ------- | -------- | -------------------------- | -| `children` | `ReactNode` | — | ✕ | Children node | -| `color` | [`inverted` \| `transparent`] | — | ✕ | Header background color | -| `isSimple` | `bool` | — | ✕ | If header should be simple | -| `UNSAFE_className` | `string` | — | ✕ | Header custom class name | -| `UNSAFE_style` | `CSSProperties` | — | ✕ | Header custom style | +The component implements the [`HTMLElement`][mdn-api-html-element] interface. -The rest of the properties are based on the type of `HTMLElement`. [Docs][HTMLElementDocs] +## Supported Content -## HeaderButton +To create a responsive header with top-level navigation, there are the following +building blocks to use: -### API +1. Inside Header: + 1. mobile-only actions, including toggle button by default, + 2. desktop-only actions with primary and secondary action slots. +2. Inside Header Dialog: + 1. primary actions slot (all breakpoints), + 2. secondary actions slot (all breakpoints). -| Name | Type | Default | Required | Description | -| ------------------ | --------------- | ------- | -------- | ------------------------------ | -| `children` | `ReactNode` | — | ✕ | Children node | -| `UNSAFE_className` | `string` | — | ✕ | HeaderButton custom class name | -| `UNSAFE_style` | `CSSProperties` | — | ✕ | HeaderButton custom style | +## Header -The rest of the properties are based on the type of `