components/shell/shell.react.tsx

Functions

Imports

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

Source

1import { Fragment, useCallback, useEffect, useId, useRef, useState, type ReactNode } from "react";
2import { Dialog, DialogBody, DialogHeader, DialogTitle } from "../dialog/dialog.react.tsx";
3import { DEFAULT_PREF, readPref, writePref } from "./shell.ts";
4
5export interface ShellEntry {
6  id: string;
7  label: string;
8  href: string;
9  icon?: ReactNode;
10  current?: boolean;
11  // A count beside the entry, and what it counts: "Queue, 2 blocked".
12  count?: number;
13  countNote?: string;
14  tone?: "crit" | "warn";
15  // A group label over the entries that share it (Sidebar's group). Consecutive entries with
16  // the same `group` form one group; entries with none sit ungrouped. The label is hidden
17  // when the rail is collapsed.
18  group?: string;
19}
20
21export interface LinkProps {
22  href: string;
23  className?: string;
24  "aria-current"?: "page" | "true";
25  "aria-label"?: string;
26  onClick?: () => void;
27  children: ReactNode;
28}
29
30export interface ShellProps {
31  // The name beside the logo. Leave it null when the logo is the whole brand, and give `brandLabel`.
32  brand: ReactNode;
33  brandHref?: string;
34  // The site's logo (an `<img alt="">` or an `<svg>`), before the name: held to the bar's height, in
35  // proportion, and hidden from a screen reader because the name or `brandLabel` is the link's name.
36  logo?: ReactNode;
37  // The brand link's name when `brand` is empty (the logo alone).
38  brandLabel?: string;
39  nav: ShellEntry[];
40  // At most four: the wrapper adds More as the fifth when `more` is given.
41  tabs?: ShellEntry[];
42  // The views the tab bar has no room for, listed in the More sheet. `current` on one of
43  // them marks the More tab as current. The sheet's count reads "1 paused" (count, then countNote).
44  more?: ShellEntry[];
45  moreLabel?: string;
46  moreIcon?: ReactNode;
47  navLabel?: string;
48  // The top bar, left to right after the brand: a status, then actions. Put the theme
49  // switch, then Settings, then Sign out (where there is one) last in `actions`.
50  status?: ReactNode;
51  actions?: ReactNode;
52  railFoot?: ReactNode;
53  prefKey?: string;
54  // A router's link component; a plain <a> by default.
55  renderLink?: (props: LinkProps) => ReactNode;
56  // Controlled collapse, for an app that binds a key to it.
57  collapsed?: boolean;
58  onCollapsedChange?: (collapsed: boolean) => void;
59  children: ReactNode;
60}
61
62const RailIcon = () => (
63  <svg className="cap-shell-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false">
64    <path fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" d="M2.5 2.5h11v11h-11zM6 2.5v11M10.5 6 8.5 8l2 2" />
65  </svg>
66);
67
68const MoreIcon = () => (
69  <svg className="cap-shell-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false">
70    <circle cx="3" cy="8" r="1.4" fill="currentColor" />
71    <circle cx="8" cy="8" r="1.4" fill="currentColor" />
72    <circle cx="13" cy="8" r="1.4" fill="currentColor" />
73  </svg>
74);
75
76export const plainLink = ({ children, ...props }: LinkProps) => <a {...props}>{children}</a>;
77
78// Consecutive entries with the same `group` are one group.
79export function groups<E extends { group?: string }>(nav: E[]): Array<{ label?: string; entries: E[] }> {
80  const out: Array<{ label?: string; entries: E[] }> = [];
81  for (const e of nav) {
82    const last = out[out.length - 1];
83    if (last && last.label === e.group) last.entries.push(e);
84    else out.push({ label: e.group, entries: [e] });
85  }
86  return out;
87}
88
89// The rail's collapsed state: the prop when the app controls it, else the stored preference.
90export function useCollapsedPref(prefKey: string, controlled: boolean | undefined, onChange: ((next: boolean) => void) | undefined): [boolean, (next: boolean) => void] {
91  const [own, setOwn] = useState(false);
92  useEffect(() => setOwn(readPref(prefKey) === "collapsed"), [prefKey]);
93  const setCollapsed = useCallback(
94    (next: boolean) => {
95      writePref(prefKey, next ? "collapsed" : "expanded");
96      setOwn(next);
97      onChange?.(next);
98    },
99    [prefKey, onChange],
100  );
101  return [controlled ?? own, setCollapsed];
102}
103
104export function Shell(props: ShellProps) {
105  const { brand, brandHref = "./", logo, brandLabel, nav, tabs, more, moreLabel = "More", moreIcon, navLabel = "Sections", status, actions, railFoot, prefKey = DEFAULT_PREF, renderLink = plainLink, children } = props;
106  const moreButton = useRef<HTMLButtonElement>(null);
107  const groupId = useId();
108  const [moreOpen, setMoreOpen] = useState(false);
109  // The shared dialog closes by Esc, Close, the backdrop and Back; a link in the list closes it
110  // too. Focus goes back to More, which a browser that does not focus a pressed button needs.
111  const closeMore = useCallback(() => {
112    setMoreOpen(false);
113    requestAnimationFrame(() => moreButton.current?.focus());
114  }, []);
115  const [collapsed, setCollapsed] = useCollapsedPref(prefKey, props.collapsed, props.onCollapsedChange);
116  // A phone tab bar holds at most five entries (rule 9): with a More sheet, four and More.
117  const phoneTabs = tabs?.slice(0, more ? 4 : 5);
118
119  const entry = (e: ShellEntry, phone: boolean) => {
120    // The visible label and count, then what it counts: "Sites, 2 down or degraded" (WCAG 2.5.3).
121    const named = e.count ? `${e.label}, ${e.count}${e.countNote ? ` ${e.countNote}` : ""}` : undefined;
122    return (
123      <Fragment key={e.id}>
124        {renderLink({
125          href: e.href,
126          "aria-current": e.current ? "page" : undefined,
127          "aria-label": named,
128          children: phone ? (
129            <>
130              {e.icon}
131              {e.label}
132              {e.count ? " " : null}
133              {e.count ? <span className="cap-shell-badge">{e.count}</span> : null}
134            </>
135          ) : (
136            <>
137              {e.icon ?? <span aria-hidden="true" />}
138              <span className="cap-shell-label">{e.label}</span>{" "}
139              <span className="cap-shell-count" data-tone={e.tone}>
140                {e.count ? e.count : ""}
141              </span>
142            </>
143          ),
144        })}
145      </Fragment>
146    );
147  };
148
149  return (
150    <div className="cap-shell" data-cap="shell" data-rail={collapsed ? "collapsed" : undefined}>
151      <a className="cap-shell-skip" href="#cap-main">
152        Skip to content
153      </a>
154      <header className="cap-shell-top">
155        {renderLink({
156          href: brandHref,
157          className: "cap-shell-brand",
158          "aria-label": brandLabel,
159          children: (
160            <>
161              {logo ? (
162                <span className="cap-shell-logo" aria-hidden="true">
163                  {logo}
164                </span>
165              ) : null}
166              {brand}
167            </>
168          ),
169        })}
170        <div className="cap-shell-spacer" />
171        {status}
172        <div className="cap-shell-actions">{actions}</div>
173      </header>
174      <nav className="cap-shell-rail" id="cap-rail" aria-label={navLabel}>
175        {groups(nav).map((g, i) =>
176          g.label ? (
177            <div key={`g${i}`} className="cap-shell-group" role="group" aria-labelledby={`${groupId}-${i}`}>
178              <div className="cap-shell-group-label" id={`${groupId}-${i}`}>
179                {g.label}
180              </div>
181              {g.entries.map((e) => entry(e, false))}
182            </div>
183          ) : (
184            g.entries.map((e) => entry(e, false))
185          ),
186        )}
187        <div className="cap-shell-foot">
188          {railFoot}
189          <button type="button" className="cap-shell-toggle" data-cap-part="rail-toggle" aria-expanded={!collapsed} aria-controls="cap-rail" onClick={() => setCollapsed(!collapsed)}>
190            <RailIcon />
191            <span className="cap-shell-label">{collapsed ? "Expand menu" : "Collapse menu"}</span>
192            <kbd aria-hidden="true">[</kbd>
193          </button>
194        </div>
195      </nav>
196      <main className="cap-shell-main" id="cap-main" tabIndex={-1}>
197        {children}
198      </main>
199      {phoneTabs && phoneTabs.length > 0 && (
200        <nav className="cap-shell-tabs" aria-label={navLabel}>
201          {phoneTabs.map((e) => entry(e, true))}
202          {more && (
203            <button
204              ref={moreButton}
205              type="button"
206              data-cap-part="more"
207              aria-haspopup="dialog"
208              aria-expanded={moreOpen}
209              aria-controls="cap-more"
210              aria-current={more.some((e) => e.current) ? "true" : undefined}
211              onClick={() => setMoreOpen(true)}
212            >
213              {moreIcon ?? <MoreIcon />}
214              {moreLabel}
215            </button>
216          )}
217        </nav>
218      )}
219      {more && (
220        <Dialog open={moreOpen} onOpenChange={(o) => !o && closeMore()} placement="bottom" id="cap-more" className="cap-shell-more" aria-labelledby="cap-more-title">
221          <DialogHeader>
222            <DialogTitle id="cap-more-title">More views</DialogTitle>
223          </DialogHeader>
224          <DialogBody>
225            <nav aria-labelledby="cap-more-title">
226              <ul className="cap-shell-more-list">
227                {more.map((e) => (
228                  <li key={e.id}>
229                    {renderLink({
230                      href: e.href,
231                      "aria-current": e.current ? "page" : undefined,
232                      onClick: closeMore,
233                      children: (
234                        <>
235                          {e.icon}
236                          <span className="cap-shell-more-name">{e.label}</span>
237                          {e.count ? " " : null}
238                          {e.count ? <span className="cap-shell-count">{`${e.count}${e.countNote ? ` ${e.countNote}` : ""}`}</span> : null}
239                        </>
240                      ),
241                    })}
242                  </li>
243                ))}
244              </ul>
245            </nav>
246          </DialogBody>
247        </Dialog>
248      )}
249    </div>
250  );
251}