Paste

Design System

Disclosure Primitive

An unstyled and accessible basis upon which to build a disclosure.

Status
beta
Version
0.1.1
Sources
Install
yarn add @twilio-paste/disclosure-primitive — or — yarn add @twilio-paste/core

Guidelines#

About the Disclosure Primitive#

The Disclosure primitive is an unstyled, functional version of a Disclosure. It can be used to build a component following the WAI-ARIA Disclosure pattern. Our Disclosure component is built on top of this primitive.

These unstyled primitives are to be used when the styled Disclosure provided by Paste doesn’t meet the requirements needed to solve a unique customer problem. At that point, you are welcome to fallback to this functional primitive to roll your own styled disclosure while still providing a functional and accessible experience to your customers.

This primitive should be used to compose all custom Disclosures to ensure accessibility and upgrade paths.

Warning

We strongly suggest that all components built on top of this primitive get reviewed by the Design Systems team and goes through the UX Review process to ensure an excellent experience for our customers.

Usage Guide#

This package is a wrapper around Reakit's Disclosure. If you’re wondering why we wrapped that package into our own, we reasoned that it would be best for our consumers’ developer experience. For example:

  • We can control which APIs we expose and how to expose them. For example, in this package we rename and export only some of the source package's exports.
  • If we want to migrate the underlying nuts and bolts in the future, Twilio products that depend on this primitive would need to replace all occurrences of import … from ‘@reach/dialog’ to import … from ‘@some-new/package’. By wrapping it in @twilio-paste/disclosure-primitive, this refactor can be avoided. The only change would be a version bump in the package.json file.
  • We can more strictly enforce semver and backwards compatibility than some of our dependencies.
  • We can control when to provide an update and which versions we whitelist, to help reduce potential bugs our consumers may face.

Installation#

This package is available individually or as part of @twilio-paste/core.

yarn add @twilio-paste/disclosure-primitive - or - yarn add @twilio-paste/core

Examples#

Basic Example#

Content

Conditional Rendering Example#

You shouldn't conditionally render the DisclosurePrimitiveContent component as this will make some Reakit features not work. Instead, you can use render props and conditionally render the underneath element:

Multiple Components#

Each DisclosurePrimitiveContent component should have its own useDisclosureState. This is also true for derivative modules like Dialog, Popover, Menu, Tooltip etc.

If you want to have only one DisclosurePrimitive element controling multiple DisclosurePrimitiveContent components, you can use render props to apply the same state to different Disclosures that will result in a single element.

API#

Much of the following is copied directly from Reakit's docs. Because we may update at a different cadence, we're duplicating the docs here to prevent information fragmentation.

useDisclosurePrimitiveState Props#

All the regular HTML attributes (role, aria-*, type, and so on) including the following custom props:

PropTypeDefault
baseId?string
visible?bool
animated?number or boolean
baseId prop

ID that will serve as a base for all the items IDs.

visible prop

Whether it's visible or not.

animated prop

If true, animating will be set to true when visible is updated. It'll wait for stopAnimation to be called or a CSS transition ends. If animated is set to a number, stopAnimation will be called only after the same number of milliseconds have passed.

DisclosurePrimitive Props#

All the regular HTML attributes (role, aria-*, type, and so on) including the following custom props:

PropTypeDefault
disabled?boolean
focusable?boolean
disabled prop

Same as the HTML attribute.

focusable prop

When an element is disabled, it may still be focusable. It works similarly to readOnly on form elements. In this case, only aria-disabled will be set.

State props

These props are returned by the state hook. You can spread them into this component (...state) or pass them separately. You can also provide these props from your own state logic.

PropTypeDefault
visibleboolean
baseIdboolean
toggle() => void
baseId prop

ID that will serve as a base for all the items IDs.

visible prop

Whether it's visible or not.

toggle prop

Toggles the visible state

DisclosurePrimitiveContent Props#

State props

These props are returned by the state hook. You can spread them into this component (...state) or pass them separately. You can also provide these props from your own state logic.

PropTypeDefault
visibleboolean
baseIdboolean
animatednumber or boolean
animatingboolean
stopAnimation() => void
baseId prop

ID that will serve as a base for all the items IDs.

visible prop

Whether it's visible or not.

animated prop

If true, animating will be set to true when visible is updated. It'll wait for stopAnimation to be called or a CSS transition ends. If animated is set to a number, stopAnimation will be called only after the same number of milliseconds have passed.

animating prop

Whether it's animating or not.

stopAnimation prop

Stops animation. It's called automatically if there's a CSS transition.

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

0.1.1 (2020-05-20)

Note: Version bump only for package @twilio-paste/disclosure-primitive

0.1.0 (2020-05-20)

Features#

  • add disclosure primitive package (250ce2e)

Support

If you need support, please open a new issue in our GitHub repository. Please try to provide as much detail as possible in your issue.

Contributing

The Paste design system is open source and contributions are welcome. Check out the project on GitHub to learn more about contributing.

Copyright © 2020 Twilio, Inc.