Disclosure

Import

import { Disclosure } from '@envsemble/envui';

Usage

A Disclosure is a native <details>: title is its one-line summary, and children the details shown below it while it is open. It keeps its own state, closed unless defaultOpen is set; finding text in a closed panel opens it where the browser supports it.

VisibilityHelp.tsx

import { Disclosure, Text } from '@envsemble/envui';

export default function VisibilityHelp() {
  return (
    <Disclosure title="How visibility works" style={{ inlineSize: 'min(100%, 24rem)' }}>
      <Text>
        Team projects are open to every workspace member. Private projects are visible only to the
        people invited to them.
      </Text>
    </Disclosure>
  );
}

One at a time

Disclosures that share a name open one at a time, where the browser supports it.

<Disclosure name="plan-questions" title="Who can see a shared plan?" defaultOpen>
  <Text>Everyone in the workspace can read it.</Text>
</Disclosure>
<Disclosure name="plan-questions" title="Can I move a plan to another workspace?">
  …
</Disclosure>

Open on an error

open and onOpenChange(open) control it, such as to open it when a field inside has an error. A native onToggle still passes through.

<Disclosure title="Advanced settings" open={advanced} onOpenChange={setAdvanced}>
  <TextField label="Custom domain" error={error} />
</Disclosure>

Composition

Never nest a disclosure in another.

Customize

The summary is env-disclosure > summary, and the details are in env-disclosure-panel.

Accessibility

You provide

A summary that says what the details hold.
open where something inside needs attention.

envUI provides

Native <details> and <summary>: the summary reports whether it is expanded, and a closed panel is hidden.
A focus outline, and a 2.75 rem summary on touch screens.

Props

A summary that shows and hides the details below it, on the native details element.

Prop	Type	Description
`title`required	`ReactNode`	The summary: one line that says what the details hold and opens or closes them.
`children`	`ReactNode`	The details, shown below the summary while the disclosure is open.
`open`	`boolean`	Whether the details show, for a controlled disclosure: update it from onOpenChange. Use defaultOpen instead to leave it to the disclosure.
`defaultOpen`Default `false`	`boolean`	Whether the details show at first, for a disclosure that keeps its own state.
`onOpenChange`	`(open: boolean) => void`	Receives whether the details show, each time the disclosure opens or closes.

Also accepts the native props of <details>, such as ref, className and aria-* attributes.

Part names

Each part's class and state attributes are public and versioned, for an application's CSS to style.

env-disclosure: The disclosure: a summary that shows and hides a panel.
env-disclosure-indicator: The chevron before the summary's words, turned down while open.
env-disclosure-panel: The panel it shows.

Changelog

1.0.0: Disclosure takes open, defaultOpen and onOpenChange(open); a native onToggle still passes through. DisclosureNote is Disclosure, and its content env-disclosure-panel; the page is disclosure.
1.0.0-prerelease.6: The details grow to their height as they open and shrink as they close, fading in and out, as an accordion's panel does, where the browser can size them to their content.

The summary's chevron is the icon set's, env-disclosure-indicator, at the small icon size in the middle of its first line, as a tree's is, rather than a text character, and turns to point down while open; the panel lines up with the summary's words.

The summary lays the shared state layer on hover and press, in a small rounded rectangle a little past its words, and its focus ring takes the same rounded corners rather than square ones.