@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 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.