Repository navigation
Description
What is being proposed?
A new component, ContextPanel, that sits next to the main workspace as a secondary bar. What the user picks in the panel decides what the workspace shows.
This issue covers the panel and its first option, cards: a card list with metadata, viewing, selecting, and optional search and filters. A later folding tree option would reuse the panel and is not part of this issue.
Why is this needed?
Some screens show many items of the same kind (plots, datasets, scans, runs). The user needs to see what exists, narrow it down, and choose which to look at. Nothing in sci-react-ui fits:
SidebarNav: items go to different content, not more of the same.SubNav(New component: SubNav (Sidebar expansion) #262): items are still links to other content, with no cards, metadata, selection or filters.DataCard: shows one item, with no list, selection, search or filters.
xrpddatavis built a variation (a Facets row of dropdowns, a card list, a sort menu, a counts header). Other Diamond apps with a list beside a viewer need the same.
What will change?
Adds one component. Nothing existing changes.
Panel
- Header with title
- Optional slots:
controls(above the list) andfooter(below it). Both stay fixed outside the scroll area.controlsholds search, filters, sort and toggles.footerholds a status bar, bulk actions or pagination. - Optional selection bar (
selectAll) above the cards, with a select-all checkbox. - Scrolling content area.
- Collapses on narrow screens.
- Search and filters are the app's own inputs, placed in
controls. The app filters and passes in the matching items.
Cards
Only the title is required.
- Title, subtitle (identifier line, e.g. "276815 · 15:55"), thumbnail.
- Status: one chip (label, intent, optional icon). There is no status component yet, so this is a chip.
- Metadata: short facts on one line ("707 eV · C+ · 12 K"). Lowest-priority items drop from the end. A label gives the tooltip and accessible name.
- Tags, with "+N" overflow.
- Linked: connected records (raw data, a reconstruction). Each can open something and show a state. A running or failed one is never dropped.
- Footer: start and end (e.g. owner, duration).
- Actions: overflow menu.
- Checkbox.
Clicking and selecting. A card can be clicked to show it, and ticked to select it. The interaction prop chooses how it works:
view: click a card to show it in the workspace. One card at a time. No checkboxes.view-and-select: click a card to show it. Tick its checkbox to select it for actions (compare, delete, export). The two are separate: clicking a card does not change the ticks, and ticking a card does not change what is shown.select: clicking the card and ticking the checkbox do the same thing. Many cards can be selected, and the app decides what to do with them, for example show them all. Checkboxes are optional here.
interaction |
Click a card | Tick a checkbox | App passes |
|---|---|---|---|
view |
Shows it | No checkboxes | shownIds |
view-and-select |
Shows it | Selects it | shownIds, selectedIds |
select |
Selects it | Selects it (same) | selectedIds |
Keys work in every mode. Shift+click picks a range. Cmd/Ctrl+click adds or removes one card.
Select all. selectAll adds a bar above the cards with a checkbox labelled "Select all" and the number selected. It needs checkboxes. The checkbox is unchecked, checked, or indeterminate (some selected). It acts on the items currently listed. Selected items hidden by a filter stay selected. The bar is hidden when there are no items.
Control: The app owns the shown ids, selected ids, search and filter values. The panel reports changes. The app only passes the ids its interaction uses.
Placement: Beside the workspace, not inside SidebarNav. The app composes them. A Workspace wrapper can follow if the pattern repeats.
Left out for now: tree option, grouping and nested cards, sorting, a ready-made search and filter bar, progress on running cards, renderCard.
Interface changes
type StatusIntent = "default" | "info" | "success" | "warning" | "danger";
type StatusChip = {
label: string;
intent?: StatusIntent;
icon?: ReactNode; // colour is never the only cue
};
type Interaction = "view" | "view-and-select" | "select";
type CardItem = {
id: string;
title: string;
subtitle?: ReactNode;
thumbnail?: ReactNode;
status?: StatusChip;
metadata?: {
key: string;
value: ReactNode;
label?: string; // tooltip and accessible name
priority?: number; // lower is kept longer
}[];
tags?: string[];
linked?: {
key: string;
label: string;
state?: StatusChip;
href?: string;
onClick?: () => void;
}[];
footer?: { start?: ReactNode; end?: ReactNode };
actions?: { key: string; label: string; onClick: () => void }[];
};<ContextPanel
title="Scans"
variant="cards"
items={visibleItems} // already filtered by the app
totalCount={items.length}
density="comfortable" // or "compact"
interaction="view-and-select" // "view" | "view-and-select" | "select"
shownIds={shown} // view, view-and-select
onShownChange={setShown}
selectedIds={selected} // view-and-select, select
onSelectedChange={setSelected}
checkboxes // select only (default on). Always on in view-and-select, never in view.
selectAll // optional bar with a select-all checkbox
controls={<><SearchField /><FilterRow /></>}
footer={<StatusBar />}
loading={false}
emptyMessage="No scans yet"
noResultsMessage="No scans match"
noResultsAction={<Button onClick={clearFilters}>Clear filters</Button>}
/>variant decides which props apply. A later variant="tree" would take tree nodes instead of items.
Accessibility
- Labelled landmark. The list is a real list.
- In
viewandview-and-select, a card is a toggle button witharia-pressedfor the shown state. The shown state has a non-colour cue and a text alternative. - Each checkbox is labelled with its card title.
- In
select, when checkboxes are on, the checkbox is the keyboard control. Clicking the card is a mouse shortcut for it. Without checkboxes, the card is a toggle button witharia-pressed. - The select-all checkbox is labelled "Select all" and exposes the indeterminate state.
- Links, the menu and checkboxes inside a card do not also show or select it.
- The status chip is always text. Linked items and actions have accessible names.
- Truncated text is available on focus as well as hover.
- Count and selection changes are announced politely. A running state is announced on finish or failure, not on every update.
- The
controlsslot is the app's own inputs and needs visible labels. - Fully keyboard operable. Space does what a click does, with Shift or Ctrl/Cmd for the modified versions. Arrow keys move focus without changing anything.
Colours and spacing
Tokens only (light and dark). The status chip uses the theme intent roles.
Behaviour and states
| Action | Result |
|---|---|
Click a card (view, view-and-select) |
Shows it and hides the others. In view-and-select, ticked cards stay ticked. |
| Click the only shown card | Stays shown |
Click a card (select) |
Toggles it in the selected set |
| Tick a checkbox | Toggles it in the selected set. In view-and-select, what is shown does not change. |
| Shift+click | Adds the range. On a card in view or view-and-select it adds to what is shown. On a checkbox, or in select, it adds to the selected set. |
| Cmd/Ctrl+click | Adds or removes one card, in the same set as Shift+click |
| Click select all | Selects every listed item. If all are selected, clears them. |
Dragging to select text does not trigger a click.
- Empty:
totalCountis 0. - No results:
totalCount> 0 anditemsis empty. ShowsnoResultsMessageandnoResultsAction. - Loading: skeleton cards.
- Counts: header shows
items.lengthoftotalCount. Per-option filter counts are the app's job. - Overflow: metadata and tags drop from the end by priority.
- Narrow screens: collapses into a drawer, slots included.
Breaking change?
- No
Next steps
A maintainer will review this issue.
If accepted, it will be marked as accepted and a PR may then be opened.
Activity
[-]Change Proposal: ContextPanel, a secondary side panel with a cards option[/-][+]New Component: ContextPanel, a secondary side panel with a cards option[/+]