components/site-header/site-header-parts.react.tsx

Functions

Imports

It imports components/shell/shell.react.tsx, components/site-header/site-header.ts, components/tooltip/tooltip.ts. Imported by components/admin-shell/admin-shell.react.tsx, components/site-header/site-header.react.tsx.

Source

1// The site header's props and the small parts its panels and sheet are built from (site-header.react.tsx).
2
3import { Fragment, type ReactNode, useEffect, useRef } from "react";
4import type { LinkProps } from "../shell/shell.react.tsx";
5import { attach as attachTip, hideTip } from "../tooltip/tooltip.ts";
6import { badgeText, wirePanel } from "./site-header.ts";
7
8// One link in a panel, the sheet or the bottom bar. `count` is a bubble beside it (99+ past 99);
9// `countNote` says what it counts, for its accessible name: "Inbox, 4 need you".
10export interface HeaderLink {
11  id?: string;
12  label: string;
13  href: string;
14  current?: boolean;
15  icon?: ReactNode;
16  count?: number;
17  countNote?: string;
18}
19
20// A group of links under a quiet label, in a panel or the sheet.
21export interface HeaderGroup {
22  label?: string;
23  links: HeaderLink[];
24}
25
26// The site's logo: its mark (an svg at most 24px tall) and its name, which is also the link's name.
27// `wordmark` is what is drawn beside the mark; leave it out to show `label`.
28export interface HeaderLogo {
29  href: string;
30  label: string;
31  mark?: ReactNode;
32  wordmark?: ReactNode;
33}
34
35// A button showing where you are, opening the site's panel: Foxhound's business ("Acme Supply
36// Co.", with `tile` "A" in a square) and its product ("Recovery"). `name` is its accessible name
37// when the label alone does not say what it switches ("Business: Acme Supply Co."). The panel holds
38// `groups`, or the site's own `panel`; the sheet lists `groups` under `sheetLabel`.
39export interface HeaderSwitcher {
40  id: string;
41  label: string;
42  name?: string;
43  tile?: string;
44  mark?: ReactNode;
45  groups: HeaderGroup[];
46  panel?: ReactNode;
47  sheetLabel?: string;
48}
49
50// A section link. With `groups` or a `panel` it is a disclosure button opening a panel; else a
51// link. Its panel's contents and layout are the site's.
52export interface HeaderSection {
53  id: string;
54  label: string;
55  href?: string;
56  current?: boolean;
57  groups?: HeaderGroup[];
58  panel?: ReactNode;
59}
60
61// An extra: up to two icon controls (Search, Inbox, the bell) and one button (Free audit, Join
62// free). `keys` is shown in its tip as key caps ("Ctrl K"). An icon extra stays in the phone's top
63// row; the button moves into the sheet, full width.
64export interface HeaderExtra {
65  id: string;
66  label: string;
67  kind?: "icon" | "button";
68  icon?: ReactNode;
69  href?: string;
70  onClick?: () => void;
71  count?: number;
72  countNote?: string;
73  keys?: string;
74}
75
76export interface HeaderAccountLink {
77  label: string;
78  href?: string;
79  onClick?: () => void;
80  current?: boolean;
81}
82
83// The account menu, the same shape everywhere: who you are; the site's own rows in groups (a
84// business's settings under its name, "Admin" for an admin, "View site" and "Help" in an admin);
85// Sign out last. A site that draws its own panel (Foxing) passes `panel` and the same `groups` for
86// the sheet.
87export interface HeaderAccount {
88  name: string;
89  // Drawn as the avatar when there is no picture, or under one that fails to load.
90  initials: string;
91  // A picture of the person (its address), drawn over the initials in the account button.
92  avatar?: string;
93  detail?: string;
94  groups?: Array<{ label?: string; links: HeaderAccountLink[] }>;
95  onSignOut?: () => void;
96  signOutHref?: string;
97  signOutDisabled?: boolean;
98  panel?: ReactNode;
99}
100
101// A part of the sheet a site gives; as a function it is handed the sheet's close for its links.
102export type SheetPart = ReactNode | ((close: () => void) => ReactNode);
103
104export interface SiteHeaderProps {
105  logo: HeaderLogo;
106  switchers?: HeaderSwitcher[];
107  sections?: HeaderSection[];
108  // Where the section links sit: after the switcher (left), centred in the header (center), or on
109  // the right before the extras, after a thin divider (right).
110  links?: "left" | "center" | "right";
111  extras?: HeaderExtra[];
112  // The theme button; on by default. `themeKey` is the single key the header binds to switch it
113  // ("T"), shown in its tip; leave it out where the site does not bind single keys.
114  theme?: boolean;
115  themePrefKey?: string;
116  themeKey?: string;
117  // Signed in: the avatar menu. Signed out: Sign in holds its place, last.
118  account?: HeaderAccount;
119  signIn?: { href: string; label?: string };
120  // The band: dark in both themes, and translucent over the page.
121  band?: "dark";
122  translucent?: boolean;
123  // Off only for a header drawn inside a frame that scrolls itself (a specimen).
124  sticky?: boolean;
125  // The skip link's target, first in the tab order ("#main").
126  skipTo?: string;
127  // The site's own rows at the top of the phone's sheet (in your admin, the family's apps), and
128  // what follows the switchers and the section links (in your admin and a dashboard, the menu).
129  // A function is given the sheet's close, for its links.
130  sheetStart?: SheetPart;
131  sheetEnd?: SheetPart;
132  // The sheet's heading; default "<name> menu".
133  sheetTitle?: string;
134  renderLink?: (props: LinkProps) => ReactNode;
135}
136
137export const plainLink = ({ children, ...props }: LinkProps) => <a {...props}>{children}</a>;
138
139const svg = (body: ReactNode) => (
140  <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">
141    {body}
142  </svg>
143);
144export const CHEV = (
145  <svg className="cap-site-header-chev" viewBox="0 0 24 24" aria-hidden="true" focusable="false">
146    <path d="m6 9 6 6 6-6" />
147  </svg>
148);
149export const MENU_ICON = svg(<path d="M4 7h16M4 12h16M4 17h16" />);
150export const PERSON_ICON = svg(
151  <>
152    <circle cx="12" cy="8" r="4" />
153    <path d="M4 21c1.5-4 4.5-6 8-6s6.5 2 8 6" />
154  </>,
155);
156
157// "Inbox, 4 need you": a count is in the name, with what it counts. Past 99 the badge reads 99+,
158// so the name starts with what is seen and keeps the real count: "Inbox 99+, 120 need you". The
159// visible label and count must be words of the name in that order (WCAG 2.5.3; axe-core 4.14's
160// label-content-name-mismatch reads aria-hidden text too).
161export const countName = (label: string, count?: number, note?: string): string => (count ? `${label}${count > 99 ? " 99+" : ""}, ${count}${note ? ` ${note}` : ""}` : label);
162
163// A tip's key caps ("G 2"), after its words.
164export function TipKeys({ keys }: { keys?: string }) {
165  return keys ? (
166    <span className="cap-keys">
167      {keys.split(" ").map((k) => (
168        <kbd key={k}>{k}</kbd>
169      ))}
170    </span>
171  ) : null;
172}
173
174// An icon control's name, shown on hover and keyboard focus: Capsomer's one tooltip, a child of
175// its control, below the header's controls. It repeats the control's name, so it adds no
176// description; a press hides it.
177export function HeaderTip({ text, keys }: { text: string; keys?: string }) {
178  const tip = useRef<HTMLSpanElement>(null);
179  useEffect(() => {
180    const el = tip.current;
181    const trigger = el?.parentElement;
182    if (!el || !trigger) return;
183    const detach = attachTip(trigger, el);
184    trigger.removeAttribute("aria-describedby");
185    const used = () => hideTip(trigger);
186    trigger.addEventListener("click", used);
187    return () => {
188      trigger.removeEventListener("click", used);
189      detach();
190    };
191  }, []);
192  return (
193    <span ref={tip} className="cap-site-header-tip cap-popover" data-variant="tooltip" data-side="bottom" data-offset="6" popover="manual" role="tooltip" aria-hidden="true">
194      <span className="cap-site-header-tip-text">{text}</span>
195      <TipKeys keys={keys} />
196    </span>
197  );
198}
199
200// A disclosure button and its panel, wired by the behaviour module (the open state is the
201// platform's popover state, not React's).
202export function Disclosure({ id, className, label, name, current, align, children, button }: { id: string; className: string; label?: string; name?: string; current?: boolean; align?: "end"; children: ReactNode; button: ReactNode }) {
203  const trigger = useRef<HTMLButtonElement>(null);
204  const panel = useRef<HTMLDivElement>(null);
205  useEffect(() => {
206    if (trigger.current && panel.current) return wirePanel(trigger.current, panel.current);
207  }, []);
208  return (
209    <>
210      <button ref={trigger} type="button" className={className} data-cap-part="panel-trigger" data-current={current ? "" : undefined} aria-expanded="false" aria-controls={id} aria-label={name}>
211        {button}
212      </button>
213      <div ref={panel} id={id} className="cap-site-header-panel" popover="manual" data-align={align} role="group" aria-label={label}>
214        {children}
215      </div>
216    </>
217  );
218}
219
220export function GroupList({ groups, renderLink }: { groups: HeaderGroup[]; renderLink: (p: LinkProps) => ReactNode }) {
221  return (
222    <>
223      {groups.map((g, i) => (
224        <Fragment key={g.label ?? i}>
225          {i > 0 && !g.label ? <hr /> : null}
226          {g.label ? <div className="cap-site-header-panel-label">{g.label}</div> : null}
227          <ul className="cap-site-header-panel-list">
228            {g.links.map((l) => (
229              <li key={l.id ?? l.href}>
230                {renderLink({
231                  href: l.href,
232                  "aria-current": l.current ? "page" : undefined,
233                  "aria-label": l.count ? countName(l.label, l.count, l.countNote) : undefined,
234                  children: (
235                    <>
236                      {l.icon ? <span className="cap-site-header-mark" aria-hidden="true">{l.icon}</span> : null}
237                      {l.label}
238                      {l.count ? " " : null}
239                      {l.count ? <span className="cap-site-header-count" aria-hidden="true">{badgeText(l.count)}</span> : null}
240                    </>
241                  ),
242                })}
243              </li>
244            ))}
245          </ul>
246        </Fragment>
247      ))}
248    </>
249  );
250}
251
252function SheetList({ links, renderLink, onClose }: { links: HeaderLink[]; renderLink: (p: LinkProps) => ReactNode; onClose: () => void }) {
253  return (
254    <ul className="cap-site-header-sheet-list">
255      {links.map((l) => (
256        <li key={l.id ?? l.href}>
257          {renderLink({
258            href: l.href,
259            "aria-current": l.current ? "page" : undefined,
260            "aria-label": l.count ? countName(l.label, l.count, l.countNote) : undefined,
261            onClick: onClose,
262            children: (
263              <>
264                <span className="cap-site-header-sheet-icon" aria-hidden="true">
265                  {l.icon}
266                </span>
267                <span className="cap-site-header-sheet-name">{l.label}</span>
268                {l.count ? " " : null}
269                {l.count ? (
270                  <span className="cap-site-header-count" aria-hidden="true">
271                    {badgeText(l.count)}
272                  </span>
273                ) : null}
274              </>
275            ),
276          })}
277        </li>
278      ))}
279    </ul>
280  );
281}
282
283// A labelled group of rows in the sheet, for a site's own rows (your admin's apps, its menu).
284export function SheetGroup({ label, links, renderLink = plainLink, onClose }: { label?: string; links: HeaderLink[]; renderLink?: (p: LinkProps) => ReactNode; onClose: () => void }) {
285  return (
286    <>
287      {label ? <div className="cap-site-header-sheet-label">{label}</div> : null}
288      <SheetList links={links} renderLink={renderLink} onClose={onClose} />
289    </>
290  );
291}
292
293export const part = (p: SheetPart, close: () => void) => (typeof p === "function" ? p(close) : p);