components/bulk-bar/bulk-bar.react.tsx

Functions

Imports

It imports components/bulk-bar/bulk-bar.ts, components/status/status.react.tsx. Imported by components/content/content.react.tsx.

Source

1import { useEffect, useId, useState, type ReactNode } from "react";
2import { Glyph } from "../status/status.react.tsx";
3import { countText, fillCount, orderOutcomes, outcomeSummary, performBulk, type BulkItem, type BulkOutcome } from "./bulk-bar.ts";
4
5export type { BulkOutcome };
6
7export interface BulkBarAction {
8  id: string;
9  label: ReactNode;
10  // A one-way action previews every item in the confirm dialog before it runs.
11  destructive?: boolean;
12  // Templates with {n} and {s}: "Bin {n} item{s}?", "This cannot be undone.", "Bin {n} item{s}".
13  confirmTitle?: string;
14  confirmLead?: string;
15  confirmAction?: string;
16  // What the message region says afterwards, and after Undo.
17  said?: string;
18  undone?: string;
19  // Form mode (the bar has `form`): the action is a submit button of that form, named `intent`
20  // with the action's id as the value. `run` is not used, the server answers.
21  submit?: boolean;
22  run?: (items: readonly BulkItem[]) => void | Promise<void>;
23  // Reverses a reversible action: the region offers Undo.
24  undo?: (items: readonly BulkItem[]) => void | Promise<void>;
25  disabled?: boolean;
26}
27
28export interface BulkBarProps {
29  // The selection. The bar is `hidden` (still rendered) while it is empty.
30  items: readonly BulkItem[];
31  actions: readonly BulkBarAction[];
32  // Called after an action ran and by Clear selection: the app empties its selection.
33  onClear: () => void;
34  // "Select all 24 in view": shown while fewer than `total` are selected.
35  total?: number;
36  onSelectAll?: () => void;
37  // Quiet text after the count, such as the size: "2.4 MB".
38  detail?: ReactNode;
39  position?: "bottom" | "top";
40  // Where focus goes when the bar goes away.
41  returnTo?: HTMLElement | null;
42  // Extra controls before the actions (a tag field).
43  children?: ReactNode;
44  label?: string;
45  // Form mode: the id of the form the selection belongs to (the checkboxes sit in it or name it
46  // with their own `form`). Actions with `submit` post it. The bar is in the delivered page
47  // without script and hides itself only after the page has loaded and nothing is ticked.
48  form?: string;
49  // Form mode: the count's words before script runs, when nothing can be counted ("Tick the
50  // drafts to act on").
51  prompt?: string;
52  // The outcome of the action just run, one per item, refusals first. While there are any the
53  // bar stays in view with nothing selected, so they can be read; a server renders them after a
54  // form post, with no script.
55  outcomes?: readonly BulkOutcome[];
56  // Dismiss results: the app empties `outcomes`. Shown only once the page has loaded.
57  onDismissOutcomes?: () => void;
58}
59
60export function BulkBar({ items, actions, onClear, total, onSelectAll, detail, position = "bottom", returnTo, children, label = "Bulk actions", form, prompt, outcomes = [], onDismissOutcomes }: BulkBarProps) {
61  const [mounted, setMounted] = useState(false);
62  const resultsId = `${useId().replace(/[^a-zA-Z0-9]/g, "")}-results`;
63  const showing = outcomes.length > 0;
64  useEffect(() => setMounted(true), []);
65  const n = items.length;
66  // A status region that is shown and filled in one step is often missed: the count is written
67  // a frame after the bar appears.
68  const [shown, setShown] = useState(n);
69  useEffect(() => {
70    if (n === 0) {
71      setShown(0);
72      return;
73    }
74    if (shown > 0) {
75      setShown(n);
76      return;
77    }
78    const f = requestAnimationFrame(() => setShown(n));
79    return () => cancelAnimationFrame(f);
80  }, [n, shown]);
81
82  const run = async (a: BulkBarAction) => {
83    const ok = await performBulk({
84      action: typeof a.label === "string" ? a.label : a.id,
85      items,
86      run: a.run ?? (() => undefined),
87      undo: a.undo,
88      destructive: a.destructive,
89      confirmTitle: a.confirmTitle,
90      confirmLead: a.confirmLead,
91      confirmAction: a.confirmAction,
92      said: a.said,
93      undone: a.undone,
94      returnTo,
95    });
96    if (ok) onClear();
97  };
98
99  return (
100    <div className="cap-bulk" data-cap="bulk-bar" role="region" aria-label={label} data-position={position === "top" ? "top" : undefined} hidden={(form ? mounted && n === 0 : n === 0) && !showing} onKeyDown={(e) => {
101        if (e.key === "Escape" && !e.defaultPrevented && n > 0) {
102          e.preventDefault();
103          onClear();
104        }
105      }}>
106      <p className="cap-bulk-count" role="status">
107        {shown > 0 ? countText(shown) : !mounted && form && prompt ? prompt : showing && mounted ? "Nothing selected" : ""}
108        {shown > 0 && detail ? (
109          <>
110            {" "}
111            <span className="cap-bulk-detail">{detail}</span>
112          </>
113        ) : null}
114      </p>
115      {onSelectAll && total != null && n < total ? (
116        <button type="button" className="cap-btn" data-variant="quiet" data-cap-part="select-all" onClick={onSelectAll}>
117          {fillCount("Select all {n} in view", total)}
118        </button>
119      ) : null}
120      <div className="cap-bulk-actions">
121        {children}
122        {actions.map((a) => a.submit ? (
123          <button key={a.id} type="submit" form={form} name="intent" value={a.id} className="cap-btn" data-variant={a.destructive ? "danger" : undefined} aria-disabled={a.disabled || undefined}>
124            {a.label}
125          </button>
126        ) : (
127          <button key={a.id} type="button" className="cap-btn" data-variant={a.destructive ? "danger" : undefined} data-cap-bulk-action={a.id} aria-disabled={a.disabled || undefined} onClick={() => (a.disabled ? undefined : void run(a))}>
128            {a.label}
129          </button>
130        ))}
131      </div>
132      <button type="button" className="cap-btn cap-bulk-clear" data-variant="quiet" onClick={onClear}>
133        Clear selection
134      </button>
135      {showing ? (
136        <div className="cap-bulk-results" data-cap-part="results" role="group" aria-labelledby={resultsId}>
137          <p className="cap-bulk-results-summary" id={resultsId}>
138            {outcomeSummary(outcomes)}
139          </p>
140          <ul className="cap-bulk-results-list">
141            {orderOutcomes(outcomes).map((o) => (
142              <li key={o.id} data-ok={String(o.ok)}>
143                <span className="cap-status" data-tone={o.ok ? "ok" : "crit"}>
144                  <Glyph name={o.ok ? "ok" : "crit"} />
145                  {o.ok ? "Done" : "Not done"}
146                </span>{" "}
147                <span className="cap-bulk-result-label">{o.label}</span>
148                {o.message ? (
149                  <>
150                    {" "}
151                    <span className="cap-bulk-result-message">{o.message}</span>
152                  </>
153                ) : null}
154                {o.usedBy?.length ? (
155                  <ul className="cap-bulk-result-uses">
156                    {o.usedBy.map((u) => (
157                      <li key={u}>{u}</li>
158                    ))}
159                  </ul>
160                ) : null}
161              </li>
162            ))}
163          </ul>
164          {onDismissOutcomes ? (
165            <button type="button" className="cap-btn" data-variant="quiet" data-size="sm" data-cap-part="dismiss-results" hidden={!mounted} onClick={onDismissOutcomes}>
166              Dismiss results
167            </button>
168          ) : null}
169        </div>
170      ) : null}
171    </div>
172  );
173}