@adrienlcp/react-aria
What every react-aria app of mine repeats: a className merge that follows the render state, a Sass focus ring on data-focus-visible, and a popover that turns into a sheet rising from the bottom of a narrow screen, pulled down by its grabber or from anywhere on its content, and closed by the back gesture
Works with
- React Aria
- React
- TypeScript
- Sassoptional peer
Install
pnpm add @adrienlcp/react-ariaExports
Grouped by the section of the documentation that explains them. A row leads to its section.
Merging a className1 export
A focus ring: focus7 exports
$ring-widthConfigure once, in the app's own_focus.sass:@forward '@adrienlcp/react-aria/focus' with ($ring-color: var(--focus)).@adrienlcp/Sassreact-aria/ focus $ring-color@adrienlcp/Sassreact-aria/ focus $ring-offset@adrienlcp/Sassreact-aria/ focus ringreact-aria stampsdata-focus-visibleon keyboard focus only, and on the element it styles: a control built over a hidden input rings through it alone.@adrienlcp/Sassreact-aria/ focus ring-insetThe ring drawn inside the box, for an element a clipping ancestor would cut.@adrienlcp/Sassreact-aria/ focus ring-withinThe ring drawn on a box while the field inside it has focus — aSearchField'sGrouparound its input and its clear button.@adrienlcp/Sassreact-aria/ focus ring-focusablesThe ring every element that takes focus draws by default, at zero specificity so a component's own ring wins.@adrienlcp/Sassreact-aria/ focus
A popover that becomes a sheet: PopoverSheet3 exports
PopoverSheetWhat a trigger opens, in the place of aPopoverinside aDialogTrigger: a popover beside the trigger on a screen that answerswideQuery, a sheet rising from the bottom edge below it, where a box hung from a corner is out of a thumb's reach.@adrienlcp/Componentreact-aria ScrollbarGutterReleaseLets a modal's scrim reach the screen's edge on a page that reserves its scrollbar's room.@adrienlcp/Componentreact-aria SheetGrabberThe strip across the top of a sheet that a pointer pulls it down by, and what lets a touch pull it from anywhere on its content: downward, from content scrolled to its top, never from a field or a slider.@adrienlcp/Componentreact-aria
The sheet's styles: sheet14 exports
$z-indexConfigure once, in the app's own_sheet.sass:@forward '@adrienlcp/react-aria/sheet' with ($z-index: 3).@adrienlcp/Sassreact-aria/ sheet $scrim@adrienlcp/Sassreact-aria/ sheet $enter@adrienlcp/Sassreact-aria/ sheet $exit@adrienlcp/Sassreact-aria/ sheet $easing@adrienlcp/Sassreact-aria/ sheet $exit-easingThe leave's own curve, never the enter's reversed: an ease-out played backwards holds the sheet still before it drops.@adrienlcp/Sassreact-aria/ sheet $top-gapThe strip of screen the tallest sheet leaves above it, for a press that closes it.@adrienlcp/Sassreact-aria/ sheet $grabber-color@adrienlcp/Sassreact-aria/ sheet $grabber-radius@adrienlcp/Sassreact-aria/ sheet overlayThe scrim a sheet rises over, holding it to the bottom edge.@adrienlcp/Sassreact-aria/ sheet surfaceThe sheet itself: the screen's width, following the thumb on its grabber and settling back from where a short pull let go.@adrienlcp/Sassreact-aria/ sheet grabberThe strip a thumb pulls the sheet down by, at the top of the sheet above its scrolling content.@adrienlcp/Sassreact-aria/ sheet keyframesThe rise ends where the thumb left the sheet, and the fall starts there, so a sheet pulled down leaves from where it was let go.@adrienlcp/Sassreact-aria/ sheet stylesThe rulesPopoverSheetandSheetGrabberneed, included once in the app's components layer.@adrienlcp/Sassreact-aria/ sheet
Documentation
The README and the documents beside it, as written in the repository.
OverviewREADME.md
What every app of mine built on
react-aria-components repeats,
kept in one version across them. Depends on @adrienlcp/react and @adrienlcp/browser; React 19 and
react-aria-components are peers, and Sass an optional one, for the focus
and sheet modules.
pnpm add @adrienlcp/react-ariaMerging a classNameREADME.md
import { composeClassName } from '@adrienlcp/react-aria'
import { Button as AriaButton, type ButtonProps } from 'react-aria-components'
export const Button = ({ className, isWide, ...props }: ButtonProps & { isWide?: boolean }) => (
<AriaButton {...props} className={composeClassName(className, 'button', isWide && 'wide')} />
)react-aria lets className be a function of the component's render state, so
the merge is a function too, built on react-aria's own composeRenderProps: it
puts the component's own class names first, resolves the caller's against the
render state, and drops the falsy ones. It fits a react-aria component, never a
plain DOM element: there, classNames from @adrienlcp/react joins the same
class names into a string, and is what this merge runs once the state is known.
The custom properties react-aria sets: REACT_ARIA_TOKENSREADME.md
react-aria-components writes a few custom properties on the elements it
renders — --trigger-width on a popover, --disclosure-panel-height,
--tab-panel-width, --tree-item-level, --visual-viewport-height — which a
stylesheet reads but never declares. findTokenFailures from
@adrienlcp/styles/audit takes them as provided:
import { REACT_ARIA_TOKENS } from '@adrienlcp/react-aria'
import { findTokenFailures } from '@adrienlcp/styles/audit'
expect(findTokenFailures(SOURCES, { provided: REACT_ARIA_TOKENS })).toEqual([])A test reads react-aria's build and fails when a release adds or drops one.
A focus ring: focusREADME.md
ring and ring-inset draw the outline on [data-focus-visible], which
react-aria stamps on keyboard focus only, and on :focus-visible, for a native
element. A control built over a hidden input — a switch, a checkbox — only
rings through the attribute, since the focused element is the invisible input.
@use '@adrienlcp/react-aria/focus'
.button
@include focus.ring
&[data-hovered]:not([data-disabled])
background: var(--hover)ring-inset draws inside the box, for an element a clipping ancestor would
cut. Both take $on, a selector that draws the ring on a descendant of the
focused element — focus.ring('.track') for a Switch, whose root takes the
focus. ring-within rings a box while a field inside it has focus: a
SearchField's Group around its input and its clear button. ring and
ring-within take $offset for one ring closer than the configured one.
ring-focusables, included once at the root of the base layer, rings every
element that takes focus at zero specificity — never *, since a Group or a
Select root stamps data-focus-visible while the control inside holds the
focus, and would ring beside it. It skips the input VisuallyHidden clips
under a Switch, a Checkbox or a Radio: the visible control rings
through $on. Configure the ring once, in the app's own _focus.sass, and have
components @use that file:
@forward '@adrienlcp/react-aria/focus' with ($ring-color: var(--focus), $ring-offset: 3px, $ring-width: 3px)$ring-width (2px), $ring-color (currentColor) and $ring-offset
(3px) are the defaults. There is no hover mixin: react-aria's
[data-hovered] already ignores the hover a touch screen emulates after a tap,
so a hover style is a plain &[data-hovered] rule.
Resolved through the sass export condition, which Vite reads; with the Sass
CLI, use pkg:@adrienlcp/react-aria/focus and --pkg-importer=node.
A popover that becomes a sheet: PopoverSheetREADME.md
import { PopoverSheet } from '@adrienlcp/react-aria'
import { Button, Dialog, DialogTrigger } from 'react-aria-components'
const WIDE_SCREEN_QUERY = '(width >= 56.25rem)'
export const Menu = () => (
<DialogTrigger>
<Button aria-label='Menu'>…</Button>
<PopoverSheet className='menu' placement='bottom end' wideQuery={WIDE_SCREEN_QUERY}>
<Dialog aria-label='Menu'>…</Dialog>
</PopoverSheet>
</DialogTrigger>
)PopoverSheet takes the place of a Popover inside a DialogTrigger. On a
screen that answers wideQuery — the app's own breakpoint, in rem like its
stylesheets' — it is a popover beside the trigger, taking placement and
maxHeight. Below it, it is a sheet rising from the bottom edge over a scrim,
where a box hung from a corner is out of a thumb's reach: a press on the scrim
or Escape puts it away, and so does a pull past a quarter of its height or a
flick — on the SheetGrabber across its top, or a touch anywhere on its
content, as a native sheet allows. A shorter pull settles back. A touch pulls
only downward and only from content scrolled to its top: one going up or
sideways, starting on scrolled content, a field, a slider or anything whose
touch-action refuses a downward pan is left to the browser, and the press
under the thumb is cancelled once the sheet moves, so a pull that starts on a
button never presses it. The Dialog inside is the caller's, the same on both
faces.
On both faces, the system's back gesture closes it rather than leaving the
page, where the browser has a CloseWatcher (Chromium, whose Android back
gesture it answers); elsewhere the back gesture is the page's, as before. The
watcher lives as long as the overlay, so the next back gesture is the page's
again once it is put away.
The scrim reaches the screen's edge on a page that reserves its scrollbar's
room with scrollbar-gutter: stable: a fixed element never paints over that
gutter, so while the sheet is up the gutter becomes padding on the root, and
the page keeps its width.
The sheet is a plain Modal with its own rise in CSS rather than react-aria's
Sheet: that one enters through the browser's smooth scroll, whose length no
stylesheet sets, and at over half a second it reads as lag after the press.
The popover carries sheet-popover and the sheet sheet, inside a
sheet-overlay, each beside the className given. Before the first render on
a client the sheet is the face drawn: the media query is false on the server
and through hydration (useMediaQuery from @adrienlcp/browser/react).
SheetGrabber is exported for a sheet of the app's own — a modal that becomes
a centred card on a wide screen, say. It must be a direct child of the sheet: it
moves its parent through --sheet-drag-offset, which the sheet's rise ends
on, so a sheet let go leaves from where it was dropped, and it is what lets a
touch on the content pull the sheet too. It calls onDismiss
and leaves the closing to the caller: state.close from a Modal's render
props. Such a modal renders ScrollbarGutterRelease beside its content too,
for its scrim to cover the reserved gutter as the sheet's does:
<Modal className='sheet-modal'>
{({ state }) => (
<>
<ScrollbarGutterRelease />
<SheetGrabber onDismiss={state.close} />
<Dialog>{children}</Dialog>
</>
)}
</Modal>The sheet's styles: sheetREADME.md
The structure ships as Sass; the look — the sheet's ground, its radius, shadow
and padding, the popover's whole surface — stays the app's, on the
className it passes. Include the rules once, in the components layer:
@use '@adrienlcp/react-aria/sheet'
@layer components
@include sheet.styles
.menu
background: var(--ground)
border-start-end-radius: var(--radius-sheet)
border-start-start-radius: var(--radius-sheet)styles writes .sheet-overlay, .sheet and .sheet-grabber and the
sheet-rise, sheet-fall, sheet-scrim and sheet-scrim-out keyframes. The mixins under them — overlay,
surface, grabber and keyframes — style a sheet of the app's own under
its own class names. The overlay is held to the visual viewport react-aria
measures, so a field focused inside the sheet lifts it above the software
keyboard. The sheet never scrolls itself: its content below the grabber
does, so the scrollbar stays clear of the sheet's rounded corners.
Each default reads the token an app built on @adrienlcp/styles declares,
with a fallback where there is none: $scrim (--scrim), $enter and
$exit (--transition-base, --transition-fast), $easing
(--ease-out), $exit-easing, the leave's own curve, never the enter's
reversed (cubic-bezier(0.3, 0.1, 1, 1), moving from the first frame), $top-gap, the strip the tallest sheet leaves above it
(--space-2xl), $grabber-color (--rule-strong) and $grabber-radius
(--radius-full). $z-index is 10. Configure them once, in the app's own
_sheet.sass, and @use that file:
@forward '@adrienlcp/react-aria/sheet' with ($z-index: 3, $grabber-radius: var(--radius-control))Resolved through the sass export condition, like focus.