Skip to content
Tier

Panel section

Pro

Lets something elsewhere on the page reveal a row in the panel: put it round both, usually round AppLayout, so a chat card in the main column and the panel's sections share it. usePanelReveal() gives the function.

Revealing a row opens its section, scrolls the row into view and marks it for about 1.2 seconds, and says politely, once, which row and section it is ("Discovery questions, in Documents"). Focus stays where the person is. A row that isn't in the panel yet (one the app is adding as it reveals it, or one in a panel that is closed) is revealed when it appears, if it appears within 5 seconds; after that, or once another row is revealed, the request is dropped, so a row that appears later (when the person opens the panel themselves) isn't revealed out of the blue. onReveal is called each time, so the app can open its panel with it. Each row listens for its own id only, so a reveal draws again just that row.

Markdown

Preview

Loading the preview

Install

With the Candor CLI

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/panel-section

Brings in: bidi, collapsible, heading-level, heading-scope, link, locale, motion, tokens, use-announcer, utils · npm: lucide-react@^1.67.0

Usage

TSX · The example above
"use client"

import * as React from "react"
import { CircleAlert, FileText, MessagesSquare, PanelRight, Settings } from "lucide-react"
import { AppLayout } from "@/components/candor/app-layout"
import { AppSidebar } from "@/components/candor/app-sidebar"
import { PanelGroup, PanelItem, PanelRevealProvider, PanelSection, PanelSections, usePanelReveal } from "@/components/candor/panel-section"

type Doc = { id: string; title: string; meta?: string | undefined; isNew?: boolean | undefined; notYet?: string | undefined }

const answered: Doc[] = [
  { id: "goals", title: "Goals and scope", meta: "12 answers" },
  { id: "people", title: "Who uses it", meta: "8 answers" },
]

// The panel's sections in AppLayout's `panel`, and a card in the main column that files a document into one. The
// provider goes round both, so the card can reveal the row.
export default function Example() {
  const [panelOpen, setPanelOpen] = React.useState(true)
  const [shown, setShown] = React.useState("goals")
  const [docs, setDocs] = React.useState<Doc[]>([{ id: "risks", title: "Risks", notYet: "After the first round" }])
  return (
    <PanelRevealProvider onReveal={() => setPanelOpen(true)}>
      <div className="h-[460px] overflow-hidden rounded-lg border">
        <AppLayout
          // Sized for this preview box; in a full-screen app the defaults suit. defaultWidth is the frame's width until
          // it is measured, so the panel draws beside the page from the first render.
          defaultWidth={720}
          sidebarAt={560}
          panelAt={640}
          minPanel={240}
          defaultPanel={280}
          maxPanel={360}
          sidebar={
            <AppSidebar
              brand={<span className="px-1 text-sm font-semibold">Keel</span>}
              nav={[
                { id: "chat", label: "Chat", Icon: MessagesSquare },
                { id: "settings", label: "Settings", Icon: Settings },
              ]}
              activeId="chat"
              onNavigate={() => {}}
              user={{ name: "Sam", email: "sam@acme.example" }}
            />
          }
          panel={
            <div className="h-full overflow-y-auto">
              <PanelSections>
                <PanelSection Icon={FileText} title="Documents" summary={`${docs.length + answered.length} · ${answered.length} answered`} onOpenWide={() => {}}>
                  <PanelGroup label="Answered">
                    {answered.map((d) => (
                      <PanelItem key={d.id} id={d.id} title={d.title} meta={d.meta} selected={shown === d.id} onSelect={() => setShown(d.id)} onPreview={() => {}} />
                    ))}
                  </PanelGroup>
                  <PanelGroup label="In progress">
                    {docs.map((d) => (
                      <PanelItem key={d.id} id={d.id} title={d.title} meta={d.meta} isNew={d.isNew} notYet={d.notYet} selected={shown === d.id} onSelect={() => setShown(d.id)} />
                    ))}
                  </PanelGroup>
                </PanelSection>
                {/* Pinned: drawn first, although it is passed second. */}
                <PanelSection Icon={CircleAlert} title="Needs you" summary="1 waiting" pinned>
                  <PanelItem id="approve-scope" title="Approve the scope" isNew onSelect={() => setShown("approve-scope")} selected={shown === "approve-scope"} />
                </PanelSection>
              </PanelSections>
            </div>
          }
          panelOpen={panelOpen}
          onPanelOpenChange={setPanelOpen}
          panelLabel="Project"
        >
          <header className="flex h-11 shrink-0 items-center gap-2 border-b px-4">
            <h2 className="min-w-0 flex-1 truncate text-sm font-semibold">Chat</h2>
            <button
              type="button"
              aria-label="Project panel"
              aria-pressed={panelOpen}
              onClick={() => setPanelOpen((o) => !o)}
              className="flex size-8 items-center justify-center rounded-md text-muted-foreground hover:bg-accent hover:text-foreground"
            >
              <PanelRight className="size-4" />
            </button>
          </header>
          <div className="flex-1 overflow-y-auto p-4">
            <FiledCard
              onFile={() =>
                setDocs((list) => (list.some((d) => d.id === "decisions") ? list : [...list, { id: "decisions", title: "Decisions so far", meta: "3 entries", isNew: true }]))
              }
            />
          </div>
        </AppLayout>
      </div>
    </PanelRevealProvider>
  )
}

/** Stands in for a chat card: it adds its document to the panel's data and reveals the row. */
function FiledCard({ onFile }: { onFile: () => void }) {
  const reveal = usePanelReveal()
  return (
    <div className="flex max-w-sm flex-col gap-2 rounded-lg border bg-card p-3 text-sm">
      <p className="font-medium">Decisions so far</p>
      <p className="text-muted-foreground">Three decisions from this conversation, kept with the project’s documents.</p>
      <button
        type="button"
        onClick={() => {
          onFile()
          reveal("decisions")
        }}
        className="self-start rounded-md border px-2 py-1 text-xs hover:bg-accent"
      >
        Show in panel
      </button>
    </div>
  )
}

<PanelRevealProvider>

PropTypeDefaultDescription
onReveal((id: string) => void) | undefined—Called with a row's id each time it is revealed, before the row is found: open the app's panel here (`setPanelOpen(true)`) when it can be closed.
childrenReact.ReactNode | undefined—Everything that reveals rows and the panel they are in: usually the whole `AppLayout`.

<PanelSections>

The column of a panel's sections, with pinned ones first. Its own children that are PanelSections with pinned are drawn first, in the order given, then the rest in the order given, so a pinned section stays at the top however the app sorts the others. The order is otherwise the app's: sort the sections before passing them. A section wrapped in another element isn't seen as pinned, so pass PanelSections as direct children (a fragment or an array is fine).

PropTypeDefaultDescription
classNamestring | undefined—Classes for the column, merged with Candor's.
childrenReact.ReactNode | undefined—The `PanelSection`s.

<PanelSection>

A section of a side panel (AppLayout's panel): a header with an icon, a title and a one-line summary in the app's words ("46 · 40 answered"), and rows (PanelItem) under group headers (PanelGroup) that fold away. The header is a button inside a heading, with aria-expanded, so Enter or Space opens and closes it. Sections start open unless the app says otherwise; a folded section's rows stay in the page, hidden, so a reveal can find them.

"Open wide" opens the section's whole content somewhere roomier (a page, a document reader): give wideHref for an address, drawn as a link through the app's router, or onOpenWide for anything else.

pinned keeps the section first inside PanelSections and reads "Pinned" after its title. Words and order are the app's: name sections with the app's nouns, and sort them before passing them.

PropTypeDefaultDescription
titlerequiredstring—The section's name, in the app's words.
summarystring | undefined—One line under the title, in the app's words: "46 · 40 answered".
IconReact.ComponentType<{ className?: string | undefined }> | undefined—An icon drawn before the title, hidden from screen readers.
pinnedboolean | undefinedfalseKeeps the section first inside `PanelSections`, and reads "Pinned" after its title. Defaults to false.
openboolean | undefined—Whether the section is open, when the app controls it. A reveal asks to open it through `onOpenChange`.
defaultOpenboolean | undefinedtrueWhether the section starts open, when it keeps its own state. Defaults to true.
onOpenChange((open: boolean) => void) | undefined—Called when the person opens or closes the section, or a reveal opens it.
wideHrefstring | undefined—Where Open wide goes: an address in the app, drawn as a link through the app's router.
onOpenWide(() => void) | undefined—Opens the section wide, when it isn't an address. `wideHref` wins when both are given.
headingLevelHeadingLevel | undefined—The level of the section's heading. One below the nearest `HeadingScope`, else 2, when left out.
classNamestring | undefined—Classes for the section, merged with Candor's.
childrenReact.ReactNode | undefined—The section's rows: `PanelGroup`s and `PanelItem`s.

<PanelGroup>

A header over some of a section's rows ("Answered", "Waiting"), with the rows under it as a named group. Its words are the app's.

PropTypeDefaultDescription
labelrequiredstring—The group's header, in the app's words.
classNamestring | undefined—Classes for the group, merged with Candor's.
childrenReact.ReactNode | undefined—The group's `PanelItem`s.

<PanelItem>

One row in a PanelSection: a title, an optional detail at the end (meta), and what the app says about it.

  • isNew draws a dot and reads "New" after the title. Pass it from data (what arrived since the person last looked, useArrivals), not from when the row first drew.
  • selected marks the row being shown elsewhere (aria-current), drawn with a heavier weight and a fill.
  • notYet is a row that isn't ready: it can't be opened, it says "Not yet" in words (and the app's reason, when given a string), and it is drawn muted.
  • onPreview adds a quick-look button beside the row.

The row opens with href (a link through the app's router) or onSelect. Its id is what usePanelReveal() takes.

PropTypeDefaultDescription
idrequiredstring—The row's id, unique in the panel: what `usePanelReveal()` reveals it by.
titlerequiredstring—The row's name, drawn as text.
metastring | undefined—A short detail drawn at the row's end, in the app's words: "12 answers", "Draft".
IconReact.ComponentType<{ className?: string | undefined }> | undefined—An icon drawn before the title, hidden from screen readers.
isNewboolean | undefinedfalseDraws a dot and reads "New" after the title. From data, not from when the row first drew. Defaults to false.
selectedboolean | undefinedfalseThe row being shown elsewhere now (`aria-current`). Defaults to false.
notYetboolean | string | undefined—The row isn't ready: true says "Not yet"; a string says "Not yet" and the app's reason ("After round 2"). It can't be opened or looked at.
hrefstring | undefined—Where the row goes: an address in the app, drawn as a link through the app's router.
onSelect(() => void) | undefined—Opens the row, when it isn't an address. `href` wins when both are given.
onPreview(() => void) | undefined—Opens a quick look at the row; draws a button beside it.
classNamestring | undefined—Classes for the row, merged with Candor's.

Functions

usePanelReveal()

The function that reveals a row by its id: it opens the row's section, scrolls it into view and marks it briefly. Call it from an event (a chat card that has filed itself, a "Show in panel" button), never while drawing. Outside a PanelRevealProvider it does nothing.

const reveal = usePanelReveal()
<Button onClick={() => reveal("doc-discovery")}>Show in panel</Button>

Strings

The fixed words, in English by default. Change any of them under panelSection in <LocaleProvider strings={{ … }}>; the table is exported as panelSectionStrings.

KeyEnglish
pinnedPinned
openWideOpen wide
openWideLabelOpen wide: {section}
newNew
notYetNot yet
quickLookQuick look at {item}
revealed{item}, in {section}

Motion

MomentFamilyWhat it does
openreveal, sizeThe chevron beside a section's title turns when the person opens the section and turns back when they close it. Under reduced motion it turns at once.
revealattentionA revealed row draws one ring that grows and fades, while a bar at its start edge marks it, for about 1.2 seconds (the moment's duration). Under reduced motion, the calm level or `data-motion="none"` there is no ring: the bar shows, still, for 1.2 seconds.
scrollmoveA revealed row is scrolled into view smoothly. Under reduced motion, the calm level or `data-motion="none"` it jumps there at once.

Set with --cd-motion-panel-section-<moment>-* in your brand file; the families are in the design reference.

Types from other items

The props above take these. Each is defined by another item; import it from the path shown.

HeadingLevel from @/lib/candor/heading-level
A heading's level in the page's outline: `1` is `<h1>`, `6` is `<h6>`. Every Candor item that draws a heading takes its `headingLevel` as this type; the level is where the heading sits in the outline, never how large it looks.
1 | 2 | 3 | 4 | 5 | 6