components/row-list/row-list.react.tsx

Functions

Imports

It imports components/row-list/row-list.ts. Imported by components/attention-list/attention-list.react.tsx.

Source

1import { useEffect, useId, useRef, type ReactNode } from "react";
2import { attachRowList } from "./row-list.ts";
3
4export interface RowListProps {
5  // The list's name: the heading id that names it (preferred), or a label.
6  labelledBy?: string;
7  label?: string;
8  // The page's main list: j and k work on it even before focus is inside it. One per page.
9  primary?: boolean;
10  // shadcn's ItemGroup gap: separate the rows (use with variant "outline" or "muted" on the rows).
11  gap?: "sm" | "xs" | "default";
12  children: ReactNode;
13}
14
15export function RowList({ labelledBy, label, primary = false, gap, children }: RowListProps) {
16  const ref = useRef<HTMLUListElement>(null);
17  useEffect(() => (ref.current ? attachRowList(ref.current) : undefined), []);
18  return (
19    // role="list" keeps list semantics in Safari, which drops them from a list-style: none list.
20    <ul ref={ref} className="cap-rows" data-cap="row-list" role="list" aria-labelledby={labelledBy} aria-label={labelledBy ? undefined : label} data-cap-primary={primary ? "" : undefined} data-gap={gap === undefined ? undefined : gap === "default" ? "" : gap}>
21      {children}
22    </ul>
23  );
24}
25
26export interface RowLinkProps {
27  href: string;
28  "aria-describedby"?: string;
29  children: ReactNode;
30}
31
32export interface RowProps {
33  title: ReactNode;
34  // The row opens its detail by following href (a link), or by calling onOpen (a button)
35  // when the detail opens in place, such as a side panel.
36  href?: string;
37  onOpen?: () => void;
38  // A status (.cap-status: glyph, word and colour), shown first.
39  status?: ReactNode;
40  detail?: ReactNode;
41  // The time or other trailing fact, usually a .cap-time.
42  meta?: ReactNode;
43  // Real buttons, raised above the stretched link.
44  actions?: ReactNode;
45  tone?: "crit";
46  // shadcn's Item variants and sizes: "outline" draws the row's edge, "muted" tints it.
47  variant?: "outline" | "muted";
48  size?: "sm" | "xs";
49  // shadcn's ItemMedia, shown in the first column instead of a status: an icon or a picture.
50  media?: ReactNode;
51  mediaVariant?: "icon" | "image";
52  // A row that opens in place (a group of like rows): its button reports aria-expanded and
53  // names what it controls, and a chevron after the time turns when it is open.
54  expanded?: boolean;
55  controls?: string;
56  // A class a composing component adds to the row (the attention list's cap-attention-child).
57  className?: string;
58  // A router's link component; a plain <a> by default.
59  renderLink?: (props: RowLinkProps) => ReactNode;
60}
61
62const plainLink = ({ children, ...props }: RowLinkProps) => <a {...props}>{children}</a>;
63
64export function Row({ title, href, onOpen, status, detail, meta, actions, tone, variant, size, media, mediaVariant, expanded, controls, className, renderLink = plainLink }: RowProps) {
65  const id = useId();
66  // The link's name is the title; the status and the detail are its description, so a
67  // screen reader moving by link still hears "Critical" and why.
68  const described = [status != null ? `${id}-status` : "", detail != null ? `${id}-detail` : ""].filter(Boolean).join(" ") || undefined;
69  return (
70    <li className={className ? `cap-row ${className}` : "cap-row"} data-tone={tone} data-variant={variant} data-size={size}>
71      {media != null && (
72        <span className="cap-row-media" data-variant={mediaVariant}>
73          {media}
74        </span>
75      )}
76      {status != null && (
77        <span className="cap-row-status" id={`${id}-status`}>
78          {status}
79        </span>
80      )}
81      <div className="cap-row-title">
82        {href != null ? (
83          renderLink({ href, "aria-describedby": described, children: title })
84        ) : (
85          <button type="button" aria-describedby={described} aria-expanded={expanded} aria-controls={expanded === undefined ? undefined : controls} onClick={onOpen}>
86            {title}
87          </button>
88        )}
89      </div>
90      {detail != null && (
91        <p className="cap-row-detail" id={`${id}-detail`}>
92          {detail}
93        </p>
94      )}
95      {(meta != null || expanded !== undefined) && (
96        <span className="cap-row-meta">
97          {meta}
98          {expanded !== undefined ? <span className="cap-row-chevron" aria-hidden="true" /> : null}
99        </span>
100      )}
101      {actions != null && <div className="cap-row-actions">{actions}</div>}
102    </li>
103  );
104}