components/admin-shell/admin-shell.react.tsx

Functions

Imports

It imports components/admin-shell/admin-shell.ts, components/admin-shell/apps.tsx, components/shell/shell.react.tsx, components/shell/shell.ts, components/site-header/site-header-parts.react.tsx, components/site-header/site-header.react.tsx, components/theme-switch/theme-switch.ts, components/time/time.react.tsx, components/tooltip/tooltip.ts. Imported by components/admin-shell/examples.tsx, components/site-header/examples.tsx, site/main.tsx.

Source

1import { Fragment, useEffect, useId, useRef, type ComponentPropsWithRef, type ReactNode } from "react";
2import { attach as attachTip, hideTip } from "../tooltip/tooltip.ts";
3import { Time } from "../time/time.react.tsx";
4import { DEFAULT_PREF } from "../shell/shell.ts";
5import { groups, plainLink, useCollapsedPref, type LinkProps } from "../shell/shell.react.tsx";
6import { SheetGroup, SiteHeader, SiteTabs, type HeaderAccount, type HeaderExtra, type HeaderLink, type HeaderLogo, type HeaderSwitcher } from "../site-header/site-header.react.tsx";
7import { countName as headerCountName, TipKeys } from "../site-header/site-header-parts.react.tsx";
8import { applyStoredTheme, THEME_PREF } from "../theme-switch/theme-switch.ts";
9import { badgeText, jumpTarget } from "./admin-shell.ts";
10import { FAMILY_APPS, FIRST_PAGE, FOXHOUND_MARKS, OWNER, type FamilyAppId } from "./apps.tsx";
11
12export type { LinkProps, FamilyAppId, HeaderExtra, HeaderLogo, HeaderSwitcher };
13export { startPageTransition } from "./admin-shell.ts";
14export { FAMILY_APPS, FIRST_PAGE, FOXHOUND_MARKS, OWNER };
15
16// One of the current app's pages. `group` puts consecutive entries under one label.
17export interface AdminEntry {
18  id: string;
19  label: string;
20  href: string;
21  icon?: ReactNode;
22  current?: boolean;
23  // A count beside the entry, and what it counts: "Queue, 2 blocked". Every count is one bubble;
24  // a plain one is neutral, tone "need" is violet (it needs you), crit and warn are status colours.
25  count?: number;
26  countNote?: string;
27  tone?: "need" | "crit" | "warn";
28  group?: string;
29}
30
31// One app in the strip. The family's admin apps come from FAMILY_APPS (apps.tsx); this shape is
32// for a strip outside the family. `logo` is the product's mark (an svg using currentColor takes
33// the tile's colour). `count` is how many things in that app need you; the app you are in never
34// shows one.
35export interface AdminApp {
36  id: string;
37  label: string;
38  href: string;
39  logo?: ReactNode;
40  mono?: string;
41  current?: boolean;
42  count?: number;
43  // What the badge means, for the accessible name: "2 AI drafts waiting". Default "need you".
44  countNote?: string;
45}
46
47export interface AdminAccountLink {
48  label: string;
49  href?: string;
50  onClick?: () => void;
51  // The page you are on (Settings, say).
52  current?: boolean;
53}
54
55// What another app's tile says. One rule for every tile: a badge is always a number, how many
56// things in that app need you (a state with nothing to count, one failing check, is 1). No dots.
57export interface AdminBadge {
58  count?: number;
59  countNote?: string;
60}
61
62// A level of the top bar's trail, before the page itself: "Components" above "Shell".
63export interface AdminCrumb {
64  label: string;
65  href: string;
66}
67
68// The avatar is the owner's (OWNER, "DE") unless a name and initials are given. Its menu, in the
69// header's top right: who you are; this app's rows (`appLinks`); View site and Help; Sign out last.
70export interface AdminAccount {
71  name?: string;
72  initials?: string;
73  // A picture of the person, over the initials (the header's `account.avatar`).
74  avatar?: string;
75  role?: string;
76  email?: string;
77  appLinks?: AdminAccountLink[];
78  // The label over `appLinks`: "This app" by default; a dashboard names the business ("Acme
79  // Supply Co."), so its settings sit under its name.
80  appLabel?: string;
81  onSignOut?: () => void;
82  signOutDisabled?: boolean;
83}
84
85export interface AdminShellProps {
86  // "owner" (your admin): the strip of the family's apps, then a 232px menu. "user" (a customer's
87  // own dashboard): no strip and a 288px menu, so the page starts at the same left edge in both.
88  variant?: "owner" | "user";
89  // The family app this is. The strip lists every family app (FAMILY_APPS) in one order with this
90  // one marked, and the header's logo is its mark and name unless `logo` is given.
91  app?: FamilyAppId;
92  // Other apps' badges, from Capsid's one "what needs the owner" answer. The current app's is
93  // never shown.
94  badges?: Partial<Record<FamilyAppId, AdminBadge>>;
95  // The app's name, for the tab title and the sheet. Default: the family app's. Set it only
96  // outside the family.
97  title?: string;
98  // The strip for a site outside the family. Admin areas pass `app`.
99  apps?: AdminApp[];
100  nav: AdminEntry[];
101  // The page being shown: the tab title "<page> · <app>", and the last step of the trail.
102  page?: string;
103  // The levels above the page. Given, the top bar shows the trail ("Components / Shell"); a
104  // top-level page has none, so the bar never repeats the page's own heading.
105  trail?: AdminCrumb[];
106  // The phone's bottom bar: up to five of this app's top pages, no More. Default: the first five.
107  tabs?: AdminEntry[];
108  navLabel?: string;
109  // The header (components/site-header): the site's logo, its band, a switcher (a dashboard's
110  // business and product), and its extras. Search and Inbox are the header's first two extras;
111  // Help is a row of the account menu.
112  logo?: HeaderLogo;
113  band?: "dark";
114  translucent?: boolean;
115  switchers?: HeaderSwitcher[];
116  extras?: HeaderExtra[];
117  onSearch?: () => void;
118  searchShortcut?: string;
119  inbox?: { count?: number; countNote?: string; href?: string; onOpen?: () => void; shortcut?: string };
120  onHelp?: () => void;
121  // The account menu's View site row.
122  viewSite?: string;
123  account?: AdminAccount;
124  // The page bar: the trail and how fresh the data is on the left; then the page-wide controls
125  // and Refresh (shown when the page can refresh), last. `updated` is the one freshness line every
126  // app shows: "Updated 6 minutes ago", with "· refreshes itself" when `auto`. `status` is anything
127  // else true of the page.
128  updated?: { at: number | Date | string; auto?: boolean };
129  status?: ReactNode;
130  actions?: ReactNode;
131  onRefresh?: () => void;
132  refreshing?: boolean;
133  refreshShortcut?: string;
134  // The theme button's localStorage key ("cap-theme" by default), and the single key the app lets
135  // the header bind to it ("T"); leave it out where the app binds its own.
136  themePrefKey?: string;
137  themeKey?: string;
138  prefKey?: string;
139  // G then 1 to 9 opens the app in that place (the key sequence of GitHub and Linear; Ctrl and a
140  // digit belong to the browser's tabs); on by default. An app that lets single keys be switched off
141  // passes that setting here.
142  jumpKeys?: boolean;
143  // Shown on the collapse control and in its name tip; the app binds the key.
144  collapseKey?: string;
145  renderLink?: (props: LinkProps) => ReactNode;
146  // The main region's own ref and handlers (an app that scrolls to a row, say). Its id, class and
147  // tab stop are the shell's.
148  mainProps?: Omit<ComponentPropsWithRef<"main">, "id" | "className" | "tabIndex" | "children">;
149  collapsed?: boolean;
150  onCollapsedChange?: (collapsed: boolean) => void;
151  // Page transitions (View Transitions API): the content cross-fades between pages while the
152  // header, strip and menu stay put. Off by default; reduced motion and browsers without the API
153  // get no animation. The app wraps its page change in `startPageTransition` (a flushSync inside).
154  transition?: boolean;
155  children: ReactNode;
156}
157
158const Icon = ({ d }: { d: string }) => (
159  <svg className="cap-admin-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false">
160    <path d={d} />
161  </svg>
162);
163// The header's glyphs are the 24-box, 1.6-stroke family the header draws at 18px.
164const HeaderIcon = ({ d }: { d: string }) => (
165  <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">
166    <path d={d} />
167  </svg>
168);
169
170const COLLAPSE_D = "M3 4h18v16H3zM9 4v16M16 10l-2 2 2 2";
171const EXPAND_D = "M3 4h18v16H3zM9 4v16M14 10l2 2-2 2";
172const SEARCH_D = "M11 4a7 7 0 1 0 0 14a7 7 0 1 0 0-14zM21 21l-5-5";
173const INBOX_D = "M3 13h5l1 3h6l1-3h5M5 5h14l2 8v6H3v-6z";
174const REFRESH_D = "M20 12a8 8 0 1 1-2.3-5.6M20 4v4.5h-4.5";
175
176const countName = (label: string, count?: number, note?: string) => (count ? headerCountName(label, count, note) : undefined);
177
178
179// A control's name, shown beside it on hover and keyboard focus: Capsomer's one tooltip (the
180// shared popover's tooltip variant, in the top layer, so it is above every panel, tile and
181// badge). It is a child of its control and attaches to it; keys are key caps ("G", "2").
182// `describe` false leaves the control's description alone, where the tip repeats its name.
183// `offset` clears what sits beside the control: a strip tip starts past the strip's edge (and so
184// past the control's own badge), a menu tip past the menu's.
185function Tip({ text, keys, side = "right", offset = 20, describe = true }: { text: string; keys?: string; side?: "right" | "bottom"; offset?: number; describe?: boolean }) {
186  const tip = useRef<HTMLSpanElement>(null);
187  useEffect(() => {
188    const el = tip.current;
189    const trigger = el?.parentElement;
190    if (!el || !trigger) return;
191    const detach = attachTip(trigger, el);
192    if (!describe) trigger.removeAttribute("aria-describedby");
193    // A control that is used (a click or Enter) has done what its name said: the name goes, so
194    // it does not sit over the panel or page the control opened.
195    const used = () => hideTip(trigger);
196    trigger.addEventListener("click", used);
197    return () => {
198      trigger.removeEventListener("click", used);
199      detach();
200    };
201  }, [describe]);
202  return (
203    <span ref={tip} className="cap-admin-tip cap-popover" data-variant="tooltip" data-side={side} data-offset={offset} popover="manual" role="tooltip" aria-hidden="true">
204      <span className="cap-admin-tip-text">{text}</span>
205      <TipKeys keys={keys} />
206    </span>
207  );
208}
209
210// The strip: the family's apps in their one order, this one marked, others with their badges.
211function stripApps(app: FamilyAppId | undefined, badges: AdminShellProps["badges"], apps: AdminApp[] | undefined): AdminApp[] {
212  if (apps) return apps;
213  return FAMILY_APPS.map((a) => ({ ...badges?.[a.id], id: a.id, label: a.label, href: a.href, logo: a.logo, current: a.id === app }));
214}
215
216const Badge = ({ count }: { count?: number }) =>
217  count ? (
218    <span className="cap-admin-badge" aria-hidden="true">
219      {badgeText(count)}
220    </span>
221  ) : null;
222
223const mark = (a: AdminApp) => a.logo ?? <span aria-hidden="true">{a.mono ?? a.label.slice(0, 1)}</span>;
224
225export function AdminShell(props: AdminShellProps) {
226  const {
227    variant = "owner",
228    app,
229    nav,
230    page,
231    navLabel = "Sections",
232    onSearch,
233    searchShortcut = "Ctrl K",
234    inbox,
235    onHelp,
236    trail,
237    updated,
238    status,
239    actions,
240    onRefresh,
241    refreshing,
242    refreshShortcut,
243    themePrefKey = THEME_PREF,
244    themeKey,
245    prefKey = DEFAULT_PREF,
246    jumpKeys = true,
247    collapseKey = "[",
248    renderLink = plainLink,
249    mainProps,
250    children,
251  } = props;
252  const owner = variant === "owner";
253  const apps = stripApps(app, props.badges, props.apps);
254  const family = FAMILY_APPS.find((a) => a.id === app);
255  const title = props.title ?? family?.label ?? apps.find((a) => a.current)?.label ?? "";
256  const root = useRef<HTMLDivElement>(null);
257  const groupId = useId();
258  const [collapsed, setCollapsed] = useCollapsedPref(prefKey, props.collapsed, props.onCollapsedChange);
259
260  // The tab says the page, then the app: "Queue · Capsid Portal".
261  useEffect(() => {
262    if (title) document.title = page ? `${page} · ${title}` : title;
263  }, [page, title]);
264
265  // The remembered theme, in case the app's head script did not apply it before paint.
266  useEffect(() => void applyStoredTheme(themePrefKey), [themePrefKey]);
267
268  // G then a number jumps between apps (Esc hiding a shown name is the tooltip's own).
269  const appsRef = useRef(apps);
270  appsRef.current = apps;
271  useEffect(() => {
272    if (!owner) return;
273    const armed = { at: 0 };
274    const onKey = (e: KeyboardEvent) => {
275      const to = jumpKeys ? jumpTarget(armed, e, appsRef.current) : null;
276      if (to) {
277        e.preventDefault();
278        location.assign(to);
279      }
280    };
281    document.addEventListener("keydown", onKey);
282    return () => document.removeEventListener("keydown", onKey);
283  }, [jumpKeys, owner]);
284
285  const tabs = (props.tabs ?? nav.slice(0, 5)).slice(0, 5);
286
287  const item = (e: AdminEntry) => (
288    <Fragment key={e.id}>
289      {renderLink({
290        href: e.href,
291        "aria-current": e.current ? "page" : undefined,
292        "aria-label": countName(e.label, e.count, e.countNote),
293        children: (
294          <>
295            {e.icon ?? (
296              <span className="cap-admin-letter" aria-hidden="true">
297                {e.label.slice(0, 1)}
298              </span>
299            )}
300            <span className="cap-admin-label">{e.label}</span>{" "}
301            <span className="cap-admin-count" data-tone={e.tone}>
302              {e.count ? badgeText(e.count) : ""}
303            </span>
304            <Tip text={e.label} offset={12} describe={false} />
305          </>
306        ),
307      })}
308    </Fragment>
309  );
310
311  // The header: the logo (the app's mark and name), the extras (Search, Inbox, then the app's
312  // own), the theme, and the account menu last.
313  const logo: HeaderLogo = props.logo ?? { href: family?.href ?? apps.find((a) => a.current)?.href ?? "/", label: title, mark: family?.logo ?? apps.find((a) => a.current)?.logo };
314  const extras: HeaderExtra[] = [
315    ...(onSearch ? [{ id: "search", label: "Search everything", icon: <HeaderIcon d={SEARCH_D} />, onClick: onSearch, keys: searchShortcut }] : []),
316    ...(inbox ? [{ id: "inbox", label: "Inbox", icon: <HeaderIcon d={INBOX_D} />, href: inbox.href, onClick: inbox.onOpen, count: inbox.count, countNote: inbox.countNote ?? "need you", keys: inbox.shortcut }] : []),
317    ...(props.extras ?? []),
318  ];
319  const accountProps = props.account;
320  const account: HeaderAccount | undefined = accountProps
321    ? {
322        name: accountProps.name ?? OWNER.name,
323        initials: accountProps.initials ?? OWNER.initials,
324        avatar: accountProps.avatar,
325        detail: [accountProps.role, accountProps.email].filter(Boolean).join(" · ") || undefined,
326        groups: [
327          ...(accountProps.appLinks?.length ? [{ label: accountProps.appLabel ?? "This app", links: accountProps.appLinks }] : []),
328          ...(props.viewSite || onHelp ? [{ links: [...(props.viewSite ? [{ label: "View site", href: props.viewSite }] : []), ...(onHelp ? [{ label: "Help and shortcuts", onClick: onHelp }] : [])] }] : []),
329        ],
330        onSignOut: accountProps.onSignOut,
331        signOutDisabled: accountProps.signOutDisabled,
332      }
333    : undefined;
334
335  const toSheet = (e: AdminEntry): HeaderLink => ({ id: e.id, label: e.label, href: e.href, current: e.current, icon: e.icon, count: e.count, countNote: e.countNote });
336
337  return (
338    <div ref={root} className="cap-admin" data-cap="admin-shell" data-variant={variant} data-menu={collapsed ? "collapsed" : undefined} data-transition={props.transition ? "page" : undefined}>
339      <SiteHeader
340        logo={logo}
341        band={props.band}
342        translucent={props.translucent}
343        switchers={props.switchers}
344        extras={extras}
345        themePrefKey={themePrefKey}
346        themeKey={themeKey}
347        account={account}
348        skipTo="#cap-main"
349        renderLink={renderLink}
350        sheetTitle={`${title} menu`}
351        sheetStart={
352          owner
353            ? (close) => (
354                <>
355                  <div className="cap-site-header-sheet-label">Apps</div>
356                  <ul className="cap-site-header-sheet-list">
357                    {apps.map((a) => (
358                      <li key={a.id}>
359                        {renderLink({
360                          href: a.href,
361                          "aria-current": a.current ? "true" : undefined,
362                          "aria-label": a.current ? undefined : countName(a.label, a.count, a.countNote ?? "need you"),
363                          onClick: close,
364                          children: (
365                            <>
366                              <span className="cap-site-header-sheet-icon" aria-hidden="true">
367                                {mark(a)}
368                              </span>
369                              <span className="cap-site-header-sheet-name">{a.label}</span>
370                              {a.current || !a.count ? null : " "}
371                              {a.current || !a.count ? null : (
372                                <span className="cap-site-header-count" aria-hidden="true">
373                                  {badgeText(a.count)}
374                                </span>
375                              )}
376                            </>
377                          ),
378                        })}
379                      </li>
380                    ))}
381                  </ul>
382                </>
383              )
384            : undefined
385        }
386        sheetEnd={(close) => groups(nav).map((g, i) => <SheetGroup key={g.label ?? `g${i}`} label={g.label ?? title} links={g.entries.map(toSheet)} renderLink={renderLink} onClose={close} />)}
387      />
388      {owner ? (
389        <nav className="cap-admin-strip" aria-label="Apps">
390          <ul className="cap-admin-strip-group">
391            {apps.map((a, i) => (
392              <li key={a.id}>
393                {(a.current ? renderLink : plainLink)({
394                  href: a.href,
395                  className: "cap-admin-tile",
396                  "aria-current": a.current ? "true" : undefined,
397                  "aria-label": a.current ? a.label : (countName(a.label, a.count, a.countNote ?? "need you") ?? a.label),
398                  children: (
399                    <>
400                      {mark(a)}
401                      {a.current ? null : <Badge count={a.count} />}
402                      <Tip text={a.label} keys={i < 9 && jumpKeys ? `G ${i + 1}` : undefined} />
403                    </>
404                  ),
405                })}
406              </li>
407            ))}
408          </ul>
409        </nav>
410      ) : null}
411      <nav className="cap-admin-menu" id="cap-admin-menu" aria-label={navLabel}>
412        {/* The collapse control is the menu's first row, in the same place open and collapsed and
413            in both kinds of shell, with its key; collapsed, its words hide and its tip names it. */}
414        <button
415          type="button"
416          className="cap-admin-collapse"
417          data-cap-part="menu-toggle"
418          aria-label={collapsed ? "Expand menu" : "Collapse menu"}
419          aria-expanded={!collapsed}
420          aria-controls="cap-admin-menu"
421          onClick={() => setCollapsed(!collapsed)}
422        >
423          <Icon d={collapsed ? EXPAND_D : COLLAPSE_D} />
424          <span className="cap-admin-label">{collapsed ? "Expand menu" : "Collapse menu"}</span>
425          <span className="cap-keys" aria-hidden="true">
426            <kbd>{collapseKey}</kbd>
427          </span>
428          <Tip text={collapsed ? "Expand menu" : "Collapse menu"} keys={collapseKey} offset={12} describe={false} />
429        </button>
430        {groups(nav).map((g, i) =>
431          g.label ? (
432            <div key={`g${i}`} className="cap-admin-group" role="group" aria-labelledby={`${groupId}-${i}`}>
433              <div className="cap-admin-group-label" id={`${groupId}-${i}`}>
434                {g.label}
435              </div>
436              {g.entries.map(item)}
437            </div>
438          ) : (
439            g.entries.map(item)
440          ),
441        )}
442      </nav>
443      <main {...mainProps} className="cap-admin-main" id="cap-main" tabIndex={-1}>
444        <div className="cap-admin-bar">
445          <div className="cap-admin-bar-text">
446            {trail && trail.length > 0 ? (
447              <nav className="cap-admin-trail" aria-label="Breadcrumb">
448                <ol>
449                  {trail.map((c) => (
450                    <li key={c.href}>{renderLink({ href: c.href, children: c.label })}</li>
451                  ))}
452                  {page ? (
453                    <li>
454                      <span aria-current="page">{page}</span>
455                    </li>
456                  ) : null}
457                </ol>
458              </nav>
459            ) : null}
460            {updated ? (
461              <span className="cap-admin-fresh">
462                Updated <Time at={updated.at} />
463                {updated.auto ? " · refreshes itself" : null}
464              </span>
465            ) : null}
466            {status ? <div className="cap-admin-bar-status">{status}</div> : null}
467          </div>
468          {actions || onRefresh ? (
469            <div className="cap-admin-actions">
470              {actions}
471              {onRefresh && (
472                <button type="button" className="cap-admin-btn" data-cap-part="refresh" aria-label="Refresh" aria-busy={refreshing || undefined} onClick={onRefresh}>
473                  <Icon d={REFRESH_D} />
474                  <Tip text="Refresh" keys={refreshShortcut} side="bottom" offset={6} />
475                </button>
476              )}
477            </div>
478          ) : null}
479        </div>
480        {children}
481      </main>
482      <SiteTabs tabs={tabs.map(toSheet)} label={navLabel} renderLink={renderLink} />
483    </div>
484  );
485}