@nubitio/ui 1.1.2 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +235 -1
- package/dist/index.cjs +1611 -1592
- package/dist/index.d.cts +207 -25
- package/dist/index.d.mts +207 -25
- package/dist/index.mjs +1601 -1594
- package/dist/style.css +853 -593
- package/package.json +4 -1
package/README.md
CHANGED
|
@@ -34,11 +34,162 @@ export function App() {
|
|
|
34
34
|
|
|
35
35
|
## What's inside
|
|
36
36
|
|
|
37
|
+
### Nubit Labs visual foundation
|
|
38
|
+
|
|
39
|
+
`<ThemeProvider visualStyle="nubit">` opts into the Nubit Labs Figma foundation
|
|
40
|
+
(semantic tokens, Lexend, rounded surfaces and normal-density controls). Existing
|
|
41
|
+
applications retain their current appearance unless they opt in. Light/dark
|
|
42
|
+
switching still uses `ThemeProvider`; the preset is included in `style.css` and
|
|
43
|
+
overrides asynchronously loaded theme values. Explicit compact/comfortable
|
|
44
|
+
density tokens and persisted user accent overrides remain supported.
|
|
45
|
+
|
|
46
|
+
Install `@fontsource/lexend` in the consuming app and import its
|
|
47
|
+
`latin-400.css`, `latin-500.css`, `latin-600.css` and `latin-700.css` files once.
|
|
48
|
+
The library does not download fonts at runtime.
|
|
49
|
+
|
|
50
|
+
Figma `--nb-color-*`, `--nb-space-*` and `--nb-radius-*` variables are exposed
|
|
51
|
+
alongside the existing `--surface-*`, `--text-*`, etc. component vocabulary;
|
|
52
|
+
consumers do not need to rewrite existing components. Source design:
|
|
53
|
+
`m124loXKRsHFvZcrYkoTbk`, semantic-token frame `11:341`.
|
|
54
|
+
|
|
37
55
|
- **Primitives** — `Button`, `IconButton`, `Badge`, `Chip`, `Toggle`, `Avatar`, `Skeleton`, `EmptyState`, `StatCard`, `Card`, `CollapsibleSection`
|
|
38
56
|
- **Overlays** — `AppDialog`, `ConfirmDialog`, `Drawer`, `Popover`, `ContextMenu`, `AppDropdown`
|
|
39
|
-
- **Form controls** — `TextField`, `TextAreaField`, `SelectField`, `FormField`, `DatePicker`, `DateRangePicker`
|
|
57
|
+
- **Form controls** — `TextField`, `TextAreaField`, `SelectField`, `FormField`, `DatePicker`, `DateRangePicker`, `TimePicker`
|
|
40
58
|
- **Theming** — `ThemeProvider`, `ThemeSwitcher`, `DensityProvider`, `useAccentColor`, `SettingsPanel`
|
|
41
59
|
- **Layout** — `AppToolbar`
|
|
60
|
+
- **Selection and navigation** — `Checkbox` (native, including mixed state), `RadioGroup` (native radios), `Tabs` (controlled, keyboard navigation)
|
|
61
|
+
- **Loading** — `Spinner`, `Progress` (native determinate or indeterminate progress)
|
|
62
|
+
|
|
63
|
+
### Selection, tabs and loading
|
|
64
|
+
|
|
65
|
+
```tsx
|
|
66
|
+
<Checkbox label="Receive updates" checked={updates} onChange={(event) => setUpdates(event.target.checked)} />
|
|
67
|
+
<RadioGroup label="Channel" name="channel" value={channel} onChange={setChannel}
|
|
68
|
+
options={[{ value: 'email', label: 'Email' }, { value: 'sms', label: 'SMS' }]} />
|
|
69
|
+
<Tabs aria-label="Account sections" value={tab} onChange={setTab} keepMounted
|
|
70
|
+
items={[{ value: 'general', label: 'General', content: <AccountForm /> },
|
|
71
|
+
{ value: 'activity', label: 'Activity', content: <Activity /> }]} />
|
|
72
|
+
<Spinner label="Loading account" />
|
|
73
|
+
<Progress label="Upload" value={40} />
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
`Checkbox` accepts native input props and forwards its input ref. Its `onChange`
|
|
77
|
+
receives the native React change event. Use `indeterminate` for partial selection;
|
|
78
|
+
it does not change the submitted checked value. Supply a label or `aria-label`.
|
|
79
|
+
|
|
80
|
+
`RadioGroup` uses a fieldset and legend, shares a native radio name, and supports
|
|
81
|
+
disabled options and horizontal/vertical layout. Supply `label` or `aria-label`.
|
|
82
|
+
|
|
83
|
+
`Tabs` supports arrow keys, Home/End, disabled tabs and horizontal/vertical
|
|
84
|
+
orientation. The default `activationMode="automatic"` selects on arrow navigation;
|
|
85
|
+
`manual` selects with Enter/Space or click. Set `keepMounted` to preserve inactive
|
|
86
|
+
panel state. Values must be unique and `value` should identify an enabled item.
|
|
87
|
+
|
|
88
|
+
`Spinner` is decorative without a label; labelled spinners expose a status role.
|
|
89
|
+
`Progress` defaults to `max={100}`; omit `value` for indeterminate progress.
|
|
90
|
+
Supply a visible label or `aria-label`. Localize labels in the application.
|
|
91
|
+
All five components are also exported by `@nubitio/react-admin`.
|
|
92
|
+
|
|
93
|
+
### Combobox and tooltip
|
|
94
|
+
|
|
95
|
+
```tsx
|
|
96
|
+
<Combobox label="Country" name="country" value={country} onChange={setCountry}
|
|
97
|
+
options={[{ value: 'pe', label: 'Peru' }, { value: 'cl', label: 'Chile' }]}
|
|
98
|
+
helpText="Type to filter countries" />
|
|
99
|
+
<Tooltip content="Download the report">
|
|
100
|
+
<Button>Export</Button>
|
|
101
|
+
</Tooltip>
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Combobox uses Apache-2.0-licensed React Aria Components; Tooltip uses MIT-licensed
|
|
105
|
+
Base UI. Both provide interaction and positioning, with Nubit CSS tokens for
|
|
106
|
+
presentation. Applications do not need to install these libraries separately. `TooltipProvider` is optional and shares hover delays across
|
|
107
|
+
nearby tooltips. Both libraries are runtime dependencies and stay external in published Nubit
|
|
108
|
+
bundles.
|
|
109
|
+
|
|
110
|
+
`Combobox` is a controlled, single-select control: `value` is an option ID or `null`,
|
|
111
|
+
and `onChange` receives that ID or `null` when cleared. IDs must be unique. The
|
|
112
|
+
input filters the supplied options locally by label; free text is not a selected
|
|
113
|
+
value. It supports disabled options, required/read-only/disabled states, native
|
|
114
|
+
form submission through `name`, and forwards its input ref. Use `label` or
|
|
115
|
+
`aria-label` for its accessible name. `error` and `helpText` are linked to the
|
|
116
|
+
input; errors also set `aria-invalid`. Action and empty-result strings come from
|
|
117
|
+
`UiStringsProvider`, with `openLabel`, `clearLabel` and `emptyMessage` overrides.
|
|
118
|
+
|
|
119
|
+
`MultiSelect` uses the same options and loading API. Its `value`/`onChange` use
|
|
120
|
+
arrays of string IDs, rendered as keyboard-accessible removable chips. Read-only
|
|
121
|
+
and disabled selections cannot be removed. `name` submits one native form entry
|
|
122
|
+
per selected ID (`new FormData(form).getAll(name)`). `selectedLabel` and
|
|
123
|
+
`removeLabel(option)` customize chip accessibility strings.
|
|
124
|
+
|
|
125
|
+
```tsx
|
|
126
|
+
<MultiSelect
|
|
127
|
+
label="Countries"
|
|
128
|
+
name="countries"
|
|
129
|
+
value={countries}
|
|
130
|
+
onChange={setCountries}
|
|
131
|
+
options={countryOptions}
|
|
132
|
+
/>
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### Remote search and pagination
|
|
136
|
+
|
|
137
|
+
Pass a stable `loadOptions` callback to either component. It receives the trimmed
|
|
138
|
+
query and `{ signal, cursor }` and returns `{ options, nextCursor? }`. `cursor` is
|
|
139
|
+
absent for the first page; return `null` or omit `nextCursor` to stop pagination.
|
|
140
|
+
An empty query loads the default first page. Search is debounced (250 ms by
|
|
141
|
+
default), aborts when the query/session changes, and ignores obsolete responses
|
|
142
|
+
even when a loader ignores its signal. Failures are shown with a retry action.
|
|
143
|
+
|
|
144
|
+
```tsx
|
|
145
|
+
const loadPeople: ComboboxLoader = async (query, { signal, cursor }) => {
|
|
146
|
+
const params = new URLSearchParams({ q: query, cursor: String(cursor ?? '') });
|
|
147
|
+
const response = await fetch(`/api/people/options?${params}`, { signal });
|
|
148
|
+
if (!response.ok) throw new Error('Could not load people');
|
|
149
|
+
return response.json(); // { options: [{ value, label }], nextCursor? }
|
|
150
|
+
};
|
|
151
|
+
|
|
152
|
+
<Combobox
|
|
153
|
+
label="Person"
|
|
154
|
+
value={person}
|
|
155
|
+
onChange={setPerson}
|
|
156
|
+
options={selectedPersonOptions}
|
|
157
|
+
loadOptions={loadPeople}
|
|
158
|
+
/>;
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Seed `options` with selected records, including those outside the current page.
|
|
162
|
+
Selected labels are retained across searches; chosen options remain pinned in
|
|
163
|
+
the remote list. Server results are not filtered again on the client. Pages
|
|
164
|
+
are appended and deduplicated by ID; scrolling near the bottom, PageDown or the
|
|
165
|
+
Load more action requests the next page. `minSearchLength` defaults to 0;
|
|
166
|
+
`debounceMs` adjusts the delay. `loadingMessage` and `searchErrorMessage` override
|
|
167
|
+
the localized search statuses.
|
|
168
|
+
|
|
169
|
+
### CRUD relation integration
|
|
170
|
+
|
|
171
|
+
Native CRUD forms use `Combobox` for single `ENTITY` relations and `MultiSelect`
|
|
172
|
+
for `TAGS` and `ENTITY.multiple` relations. No new backend hints are required.
|
|
173
|
+
Existing value/text fields, filters, `byKeyUrl`, prepend records, rich
|
|
174
|
+
`itemFormatter` options and `onSelect` callbacks remain supported. A selection
|
|
175
|
+
missing from the loaded page is resolved through the resource store's `byKey`.
|
|
176
|
+
Numeric IDs (including zero) retain their original types, and Hydra relations
|
|
177
|
+
retain their IRIs when serialized.
|
|
178
|
+
|
|
179
|
+
Relation search uses the existing resource store with 50-row pages and
|
|
180
|
+
`searchEnabled`/`searchExpr`. Grid filters and inline detail cells continue to
|
|
181
|
+
edit a single relation. REST and Hydra stores forward cancellation signals to
|
|
182
|
+
HTTP requests; custom stores receive `ResourceLoadOptions.signal` and can honor
|
|
183
|
+
it as well. Selection labels are pinned in the UI rather than prepended to
|
|
184
|
+
server pages, so selected rows do not distort pagination offsets.
|
|
185
|
+
|
|
186
|
+
`Tooltip` accepts a single native focusable element or a component that forwards
|
|
187
|
+
its DOM ref and injected props; Nubit `Button` and `IconButton` support this.
|
|
188
|
+
It opens on hover or keyboard focus and dismisses on Escape. The popup adds a
|
|
189
|
+
supplementary description while preserving an existing `aria-describedby`.
|
|
190
|
+
Keep trigger labels meaningful and essential instructions visible; tooltips
|
|
191
|
+
are supplementary, non-interactive content and are not a touch-device help flow.
|
|
192
|
+
Use `side`, `delay` and `disabled` to customize behavior.
|
|
42
193
|
|
|
43
194
|
All components ship their styles in `dist/style.css`; import it once at the app root. Static design tokens (typography, spacing, radii) are included in `style.css`.
|
|
44
195
|
|
|
@@ -73,3 +224,86 @@ Partial overrides work too (`strings={{ close: 'Schließen' }}`); missing keys f
|
|
|
73
224
|
## License
|
|
74
225
|
|
|
75
226
|
MIT
|
|
227
|
+
|
|
228
|
+
## Accessible overlays
|
|
229
|
+
|
|
230
|
+
`AppDialog` and `Drawer` share Base UI's modal behavior: focus stays within the
|
|
231
|
+
active modal, background interaction and document scrolling are blocked, and
|
|
232
|
+
closing returns focus to the control that opened it. Drawers now have modal
|
|
233
|
+
semantics, matching their scrim and focus boundary. `keepMounted` preserves form
|
|
234
|
+
state while hiding the closed dialog from keyboard and assistive technology.
|
|
235
|
+
`AppDialog.initialFocus` accepts an element ref; `ConfirmDialog` uses it to focus
|
|
236
|
+
Cancel without stealing the focus-return target.
|
|
237
|
+
|
|
238
|
+
`ContextMenu` delegates arrow navigation, disabled items, typeahead and focus
|
|
239
|
+
return to Base UI Menu. `AppDropdown` delegates selection to Base UI Select;
|
|
240
|
+
its form, toolbar and compact variants and option values remain available.
|
|
241
|
+
`Popover` uses Base UI positioning, dismissal and focus return. Custom menu and
|
|
242
|
+
popover triggers should forward their DOM ref and button props, as Nubit Button
|
|
243
|
+
and IconButton do.
|
|
244
|
+
|
|
245
|
+
`SearchableAppDropdown` is a compatibility adapter around Combobox. Search is
|
|
246
|
+
entered directly in the control. Its `onSearch`, selected option, minimum search
|
|
247
|
+
length, open callback and loading/empty messages remain supported; Combobox
|
|
248
|
+
provides debounce, stale-response protection and retry. Non-searchable mode uses
|
|
249
|
+
AppDropdown. Native CRUD enum fields also use Combobox and preserve the original
|
|
250
|
+
option value types.
|
|
251
|
+
|
|
252
|
+
Nested controls portal within their owning modal, so calendars, combobox lists,
|
|
253
|
+
tooltips, menus, popovers and child modals stay inside its focus boundary. Escape
|
|
254
|
+
closes the active layer first. The showcase's **Nested overlays** example exercises
|
|
255
|
+
this combination, including a drawer and confirmation nested inside a dialog.
|
|
256
|
+
|
|
257
|
+
For a custom portalled control, use `useOverlayContainer()` as the portal target
|
|
258
|
+
and fall back to `document.body` outside a modal. This is also used by native grid
|
|
259
|
+
row menus and mobile filter sheets inside dialog or drawer views. Handle Escape
|
|
260
|
+
on the child panel before it bubbles to the owning dialog.
|
|
261
|
+
|
|
262
|
+
Interaction reference: [Base UI Dialog](https://base-ui.com/react/components/dialog).
|
|
263
|
+
|
|
264
|
+
### Dates, ranges and times
|
|
265
|
+
|
|
266
|
+
```tsx
|
|
267
|
+
<DatePicker id="invoice-date" name="date" ariaLabel="Invoice date"
|
|
268
|
+
value={date} onChange={setDate} locale="es-PE" min="2026-01-01" />
|
|
269
|
+
<DateRangePicker ariaLabel="Reporting period" startValue={start} endValue={end}
|
|
270
|
+
onChange={(start, end) => setPeriod([start, end])} />
|
|
271
|
+
<TimePicker ariaLabel="Appointment time" name="time" value={time}
|
|
272
|
+
onChange={setTime} hourCycle={24} min="08:00" max="18:00" />
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
React Aria manages calendar navigation, range selection, overlay focus and segmented
|
|
276
|
+
hour/minute editing. Date controls preserve native text inputs, IDs, external labels
|
|
277
|
+
and the `DatePicker` input ref used by CRUD. Dates use `YYYY-MM-DD` values without
|
|
278
|
+
conversion to a timezone. Text entry follows `locale`, accepts pasted ISO dates,
|
|
279
|
+
and commits on Enter or blur; invalid or out-of-bounds edits revert to the current
|
|
280
|
+
value. ArrowDown opens the calendar; Escape dismisses it. Month/year selectors
|
|
281
|
+
allow long-distance navigation. Partial ranges remain supported and completed
|
|
282
|
+
ranges are sorted chronologically.
|
|
283
|
+
|
|
284
|
+
`TimePicker` is controlled and emits `HH:mm`, or `HH:mm:ss` with
|
|
285
|
+
`granularity="second"`. It represents a wall-clock time, with no date or timezone.
|
|
286
|
+
Display defaults to the locale's hour cycle; `hourCycle={12 | 24}` overrides it.
|
|
287
|
+
Its ref points to the segmented input group, and `name` submits React Aria's ISO
|
|
288
|
+
time value (`HH:mm:ss`). Use `ariaLabel` to name the control. All three support
|
|
289
|
+
`disabled`, `readOnly`, `required` and `invalid`; `TimePicker` exposes built-in
|
|
290
|
+
min/max validation through `aria-invalid`. Components are exported by both
|
|
291
|
+
`@nubitio/ui` and `@nubitio/react-admin`.
|
|
292
|
+
|
|
293
|
+
Record detail pages can compose existing surfaces with `DetailLayout`:
|
|
294
|
+
|
|
295
|
+
```tsx
|
|
296
|
+
<Page>
|
|
297
|
+
<PageHeader title="Record" metadata={<Badge>Active</Badge>} actions={<Button>Action</Button>} />
|
|
298
|
+
<DetailLayout asideLabel="Related information" aside={<Card variant="panel">...</Card>}>
|
|
299
|
+
<Card variant="panel">
|
|
300
|
+
<Section variant="panel" title="Details">
|
|
301
|
+
...
|
|
302
|
+
</Section>
|
|
303
|
+
</Card>
|
|
304
|
+
</DetailLayout>
|
|
305
|
+
</Page>
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
The main/aside columns stack on narrower screens. The panel Section uses a
|
|
309
|
+
sentence-case title, while its default label variant retains compact headings.
|