React UI

@mateosuarezdev/react-ui is the shared React UI toolkit used by the template. It provides styled primitives, form integrations, overlays, and small interaction helpers built around the app's semantic CSS tokens.

Exports

Components

• Foundation: Button, Icon, Spinner, Divider, Portal, TopLoadingBar.
• Layout and display: Avatar, AvatarsGroup, ElasticHeader, KeepAlive, LazyImage, List, PageTitle, ShowMoreText, Ups.
• Selection and overlays: Calendar, Dropdown, MultiSelect, PopoverCard, SearchInput, SegmentedControl, Select, SuperModal.
• Forms: Form, Input, TextArea, Checkbox, Switch, Tags, WorkingHours, FilePicker, and Submit, including their form-bound counterparts where exposed.

Form and the form-bound controls work with React Hook Form and Zod. Use the standalone controls when the state does not belong to a form.

Feedback and events

• toast for app notifications.
• events for the corresponding UI event hooks.

Hooks

• Interaction: useClickAway, useKeyListener, useLongPress, useMergedRef, useRipple.
• Environment and layout: useLargeScreen, useNetwork.
• Overlay positioning: usePopover.

Utilities

• cn and design helpers for composing semantic classes.
• Form helpers from utils/forms.
• focusTrap, the package-wide imperative focus manager.
• Overflow helpers from utils/overflow.

Overlay and focus conventions

usePopover owns open state, positioning, and click-away behavior. Focus has two deliberately separate responsibilities:

• Focus containment: temporary modal-like surfaces—such as a DatePicker inside PopoverCard, a dialog, or a drawer—activate the singleton focusTrap for their mounted container. It keeps Tab inside that scope; cleanup restores focus to the prior scope or trigger. The latest active trap owns focus.
• Roving focus: non-modal option collections—such as Dropdown, Select, and eventually calendar days—move focus between their own options for arrow keys and selection. They do not contain focus: Tab closes or leaves the component and browser navigation continues normally.

A contained popover can use both: the trap owns the boundary, while the calendar controls navigate within it.

Styling

The package expects the consuming app to provide its semantic token classes (for example base, brand, contrast, and state colors). Components expose class-name and color props for app-level composition rather than owning a brand theme.