@wealth-os/design-system 0.0.0-stage → 0.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/CHANGELOG.md +36 -0
- package/LICENSE +201 -0
- package/README.md +89 -2
- package/dist/button-yvMc7CT-.js +47 -0
- package/dist/charts.d.ts +138 -0
- package/dist/charts.js +712 -0
- package/dist/command-menu.d.ts +3 -0
- package/dist/command-menu.js +53 -0
- package/dist/components/advanced-controls.d.ts +145 -0
- package/dist/components/badge.d.ts +9 -0
- package/dist/components/button-group.d.ts +15 -0
- package/dist/components/button.d.ts +14 -0
- package/dist/components/command-menu.d.ts +42 -0
- package/dist/components/data-display.d.ts +100 -0
- package/dist/components/data-table.d.ts +113 -0
- package/dist/components/date-input.d.ts +36 -0
- package/dist/components/date-range-picker.d.ts +23 -0
- package/dist/components/field.d.ts +18 -0
- package/dist/components/financial.d.ts +83 -0
- package/dist/components/form.d.ts +8 -0
- package/dist/components/icon-button.d.ts +11 -0
- package/dist/components/icons.d.ts +9 -0
- package/dist/components/navigation.d.ts +53 -0
- package/dist/components/notice.d.ts +11 -0
- package/dist/components/number-input.d.ts +44 -0
- package/dist/components/overlays.d.ts +91 -0
- package/dist/components/select-menu.d.ts +27 -0
- package/dist/components/select.d.ts +23 -0
- package/dist/components/status-badge.d.ts +9 -0
- package/dist/components/surface.d.ts +16 -0
- package/dist/components/text-input.d.ts +8 -0
- package/dist/components/textarea.d.ts +7 -0
- package/dist/components/validation-message.d.ts +8 -0
- package/dist/data-display-BA7t1E4G.js +278 -0
- package/dist/data-table.d.ts +2 -0
- package/dist/data-table.js +346 -0
- package/dist/financial.d.ts +1 -0
- package/dist/financial.js +178 -0
- package/dist/form-Csxly6Es.js +74 -0
- package/dist/forms.d.ts +39 -0
- package/dist/forms.js +32 -0
- package/dist/index.d.ts +23 -0
- package/dist/index.js +1411 -0
- package/dist/lib/control-density.d.ts +3 -0
- package/dist/lib/utils.d.ts +3 -0
- package/dist/navigation.d.ts +3 -0
- package/dist/navigation.js +224 -0
- package/dist/notice-jbY9FQu_.js +49 -0
- package/dist/overlays-BleXRtz6.js +219 -0
- package/dist/overlays.d.ts +7 -0
- package/dist/overlays.js +2 -0
- package/dist/reset.css +16 -0
- package/dist/styles.css +3 -0
- package/dist/tokens.css +157 -0
- package/dist/utils-CX-Pz5p6.js +8 -0
- package/docs/accessibility.md +154 -0
- package/docs/charts.md +47 -0
- package/docs/components.md +296 -0
- package/docs/data-table.md +87 -0
- package/docs/layout-composition.md +224 -0
- package/docs/migration.md +91 -0
- package/docs/tokens.md +170 -0
- package/package.json +118 -4
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
# Component catalog
|
|
2
|
+
|
|
3
|
+
Use the documented public entry points: common controls from the package root, optional modules from their public subpaths. Import `@wealth-os/design-system/styles.css` once in the application entry point. Do not import `src/components/*` directly.
|
|
4
|
+
|
|
5
|
+
## Icons
|
|
6
|
+
|
|
7
|
+
`WealthIcon` is the package's small, dependency-free glyph set for foundational controls. It is not a complete product icon library. Consumers may use their existing tree-shaken icon set for product-specific actions and illustrations; icon-only actions must still provide an accessible name through `IconButton` or an equivalent native control.
|
|
8
|
+
|
|
9
|
+
## Button
|
|
10
|
+
|
|
11
|
+
```tsx
|
|
12
|
+
import { Button } from "@wealth-os/design-system";
|
|
13
|
+
|
|
14
|
+
<Button>Save changes</Button>
|
|
15
|
+
<Button variant="secondary">Edit grant</Button>
|
|
16
|
+
<Button variant="ghost" size="sm">View details</Button>
|
|
17
|
+
<Button variant="destructive">Remove draft</Button>
|
|
18
|
+
<Button variant="secondary" asChild><a href="/account">Account</a></Button>
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Variants: `primary` (default), `secondary`, `outline`, `ghost`, `destructive`, `link`. Sizes: `sm`, `md` (default), `lg`, `icon`, `icon-sm`, `icon-lg`. Use `asChild` only to retain the child element's native semantics, such as an anchor for navigation. `outline` adds a transparent bordered action while `secondary` retains the existing white surface. The first landing refresh uses dark navy primary actions, 8px control radii and weight 600. Existing sizes, props and default `type="button"` are unchanged; slice 2 adds an optional density prop without changing omitted-density defaults. Link styling and secondary/outline borders use independent link/control tokens.
|
|
22
|
+
|
|
23
|
+
`IconButton` is the accessible icon-only composition. It requires a `label`, accepts icon content through `icon`, and supports the same action variants. Its icon is hidden from the accessibility tree; the action name comes from `label`.
|
|
24
|
+
|
|
25
|
+
```tsx
|
|
26
|
+
<IconButton label="More grant actions" icon={<MoreHorizontalIcon />} variant="ghost" />
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
`ButtonGroup` groups related actions with `role="group"`. Provide either `aria-label` or `aria-labelledby`. Buttons retain their ordinary tab order; the group does not implement roving focus or selection behavior. Use a radio group, tabs, or a toggle pattern when the controls represent those semantics.
|
|
30
|
+
|
|
31
|
+
```tsx
|
|
32
|
+
<ButtonGroup aria-label="Record actions">
|
|
33
|
+
<Button>Save</Button>
|
|
34
|
+
<Button variant="outline">Save as draft</Button>
|
|
35
|
+
<Button variant="ghost">Cancel</Button>
|
|
36
|
+
</ButtonGroup>
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## TextInput and Textarea
|
|
40
|
+
|
|
41
|
+
Both forward refs and accept their native HTML props. `invalid` sets the visual invalid state; callers own validation and error text. Do not use `type="number"` for financial entry.
|
|
42
|
+
|
|
43
|
+
```tsx
|
|
44
|
+
<TextInput type="email" autoComplete="email" />
|
|
45
|
+
<Textarea rows={4} />
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## NumberInput, MoneyInput, and QuantityInput
|
|
49
|
+
|
|
50
|
+
`NumberInput` is a controlled string field. It never parses into a number or applies financial rules. `inputMode` defaults to `decimal`; `prefix` and `suffix` are visual text only. `format="int"` or `format="money"` groups valid text on blur and calls `onChange` with the formatted string. While editing, typed text is passed through unchanged. `MoneyInput` presets `$`, decimal input, and money grouping; `QuantityInput` presets numeric input and integer grouping. Both retain controlled string values. The component forwards its ref and supports an `inputRef` prop; if both are supplied, both refs receive the input node.
|
|
51
|
+
|
|
52
|
+
```tsx
|
|
53
|
+
<MoneyInput label="Annual salary" value={salary} onChange={setSalary} />
|
|
54
|
+
<QuantityInput label="Shares settling" value={shares} onChange={setShares} />
|
|
55
|
+
<NumberInput label="Rate" value={rate} onChange={setRate} suffix="%" />
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
The wrapper does not validate input, compute amounts, convert currencies, or constrain negative values. `format` uses the browser's `Intl.NumberFormat("en-US")`. Invalid or incomplete strings that cannot be formatted remain unchanged. A valid numeric string with a trailing decimal may normalize when formatting is enabled on blur.
|
|
59
|
+
|
|
60
|
+
## Select and SelectMenu
|
|
61
|
+
|
|
62
|
+
`Select<T>` is the labeled form-field API. `SelectMenu<T>` is the unwrapped select-only combobox for toolbar filters and other controls with their own accessible label. Options have `{ value, label, disabled? }`; `value` is controlled and `onChange` receives the selected string. `compact` uses the 32px toolbar geometry. `SelectMenu` also accepts `className` and `tone` for its host layout/tone contract.
|
|
63
|
+
|
|
64
|
+
The listbox uses a custom popup, including measured upward placement, 36px rows, typeahead, disabled choices, and close-on-outside-pointer. It is deliberately not a searchable entity picker or a native `<select>`. Searchable pickers use the separate combobox API.
|
|
65
|
+
|
|
66
|
+
```tsx
|
|
67
|
+
<Select label="Filing status" value={status} onChange={setStatus} options={filingOptions} />
|
|
68
|
+
<SelectMenu ariaLabel="Filter by status" value={filter} onChange={setFilter} compact options={statusOptions} />
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## DateInput and UsDateInput
|
|
72
|
+
|
|
73
|
+
`DateInput` displays and masks US text (`MM/DD/YYYY`) and emits an ISO `YYYY-MM-DD` string when the typed value is a real date. Incomplete or invalid drafts emit `""` while remaining visible for correction. `min` and `max` constrain calendar choices; typed dates are not rejected by those bounds. `compact` uses the table-row geometry. `longDisplay` shows `Oct 4, 2026` while the field is blurred without changing the ISO value or the text shown on focus.
|
|
74
|
+
|
|
75
|
+
Use `Field` for a basic label/help/error composition or `UsDateInput` for the calculator pattern with an optional confirmation line. Dates are assembled and compared as calendar-day strings; the component does not convert the ISO date to or from a timestamp/timezone.
|
|
76
|
+
|
|
77
|
+
```tsx
|
|
78
|
+
<Field label="Next vest date" help="Use the date on your grant schedule.">
|
|
79
|
+
<DateInput value={vestDate} onChange={setVestDate} min="2026-01-01" />
|
|
80
|
+
</Field>
|
|
81
|
+
<UsDateInput label="Settlement date" value={date} onChange={setDate} confirm="Settles in tax year 2026." />
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
The calendar is a dialog popup with a month grid and keyboard model. It remains in the control's DOM flow rather than using a portal; clipping by an overflow-hidden consumer ancestor is therefore possible and should be considered when composing dense tables.
|
|
85
|
+
|
|
86
|
+
## Field
|
|
87
|
+
|
|
88
|
+
```tsx
|
|
89
|
+
<Field label="Employer" help="The issuer associated with this grant." error={error}>
|
|
90
|
+
<TextInput value={employer} onChange={(event) => setEmployer(event.target.value)} />
|
|
91
|
+
</Field>
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
For a single direct control, `Field` creates a stable React ID and links label, help, and error. An existing child ID is preserved. If `htmlFor` is supplied, it is applied to a child without an ID; if it conflicts with an existing child ID, `Field` throws a descriptive error rather than rendering a broken association. Existing `aria-describedby` references are preserved. For composite/multiple-control fields, label each control explicitly; do not place a wrapper as the direct child and assume nested controls are labeled automatically.
|
|
95
|
+
|
|
96
|
+
`required` adds a visible Required marker and passes the native `required` attribute to a direct control. `optional` adds a visible Optional marker. They cannot be used together. `orientation="horizontal"` places the label beside the field at widths of 640px and above, and stacks it on narrower screens; `vertical` is the unchanged default.
|
|
97
|
+
|
|
98
|
+
`ValidationMessage` provides visible inline validation copy for linking with `aria-describedby`. Its default is passive and does not create a live region. Use `variant="error" | "warning" | "info"` for semantic color roles. A consumer can explicitly pass `role="status"` for a dynamic nonurgent update or `role="alert"` only for an urgent error.
|
|
99
|
+
|
|
100
|
+
```tsx
|
|
101
|
+
<Field label="Employer" required error={error}>
|
|
102
|
+
<TextInput value={employer} onChange={(event) => setEmployer(event.target.value)} />
|
|
103
|
+
</Field>
|
|
104
|
+
<ValidationMessage id="save-error" role="alert">The record could not be saved.</ValidationMessage>
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## Surface and Card
|
|
108
|
+
|
|
109
|
+
`Surface` is a visual container, not a semantic section. Select a semantic HTML element or add `aria-labelledby` at the call site.
|
|
110
|
+
|
|
111
|
+
Variants: `working` (default, landing frame border with existing radius/shadow), `quiet` (same decorative border, no shadow), `raised` (same decorative border with existing elevation). Padding: `none`, `sm`, `md` (default), `lg`.
|
|
112
|
+
|
|
113
|
+
`Card` aliases the working surface and is composable with `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, and `CardFooter`. Domain cards with financial/business meaning remain application-owned. All three variants retain 8px surface radii and existing padding; larger landing frames remain local composition for now. Decorative surface borders must not be reused as input boundaries.
|
|
114
|
+
|
|
115
|
+
## Badge and StatusBadge
|
|
116
|
+
|
|
117
|
+
- `Badge` is for neutral metadata such as “RSU grant” or “Public”. Variants: `default`, `secondary`, `outline`.
|
|
118
|
+
- `StatusBadge` has explicit status values: `neutral`, `confirmed`, `estimated`, `stale`, `warning`, `success`, `error`. Its required children are a non-empty string. Status does not come from color alone.
|
|
119
|
+
|
|
120
|
+
## Notice
|
|
121
|
+
|
|
122
|
+
Variants: `info` (default), `success`, `warning`, `error`. A Notice is passive content by default and does not create a live region. For a dynamically updated, nonurgent message, pass `role="status"`; use `role="alert"` only for an urgent error that needs immediate announcement. Native `role`, `aria-live`, and other ARIA props remain consumer-controlled. Persistent information should remain ordinary content, not an announcement on every render.
|
|
123
|
+
|
|
124
|
+
```tsx
|
|
125
|
+
<Notice variant="warning" title="Reference data may be old">
|
|
126
|
+
Update the price before comparing scenarios.
|
|
127
|
+
</Notice>
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Avoid rendering repeated assertive alerts; reserve `role="alert"` for an error that needs immediate announcement.
|
|
131
|
+
|
|
132
|
+
## Financial presentation
|
|
133
|
+
|
|
134
|
+
Financial display components are isolated at `@wealth-os/design-system/financial`, so applications that do not use them do not load their implementation through the root entry. They format only explicitly supplied values and metadata. They do not parse input strings, calculate totals, convert currencies, infer financial meaning from a sign, or run a scenario. Use `formatted` when the calling application already owns an exact display string.
|
|
135
|
+
|
|
136
|
+
```tsx
|
|
137
|
+
import {
|
|
138
|
+
AllocationBar, AssumptionNotice, CurrencyValue, FinancialMetric,
|
|
139
|
+
PercentageValue, ShareQuantity,
|
|
140
|
+
} from "@wealth-os/design-system/financial";
|
|
141
|
+
|
|
142
|
+
<CurrencyValue value={1250.5} precision="cents" currency="USD" />
|
|
143
|
+
<PercentageValue value={0.1825} mode="rate" maximumFractionDigits={2} />
|
|
144
|
+
<PercentageValue value={2.5} mode="points" maximumFractionDigits={1} />
|
|
145
|
+
<ShareQuantity value={12.5} maximumFractionDigits={1} />
|
|
146
|
+
<FinancialMetric label="Estimated value" value={<CurrencyValue value={1250} />} state="estimated" />
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
`CurrencyValue` defaults to `en-US`, USD, and `precision="auto"`: whole amounts show no decimal places, and non-whole-cent values show cents. Choose `whole` or `cents` to pin precision. `currency` is an ISO currency code; this formats a value and does not convert it. `PercentageValue` in `rate` mode accepts a fraction (`0.125` means 12.5%); `points` accepts percentage points directly and appends “pp”. Precision is configurable. `ShareQuantity` defaults to up to 20 fractional digits so fractional shares are not rounded by default; set `maximumFractionDigits` when the caller has an explicit display precision. It uses singular “share” only when the supplied value is exactly 1. Any formatter displays negative and zero values as supplied. Null, undefined, and non-finite values render an em dash by default; set `unavailableText` or provide `formatted` to customize that display.
|
|
150
|
+
|
|
151
|
+
`FinancialMetric` provides a reusable label/value/detail layout and can display `estimated`, `stale`, `illustrative`, or `unavailable` as a visible text status. Existing `MetricCard` remains the generic summary-card primitive; it covers the proposed financial summary-card candidate without adding a second card API. `EstimateIndicator` can be used when the value and status badge are composed separately.
|
|
152
|
+
|
|
153
|
+
`AllocationBar` takes caller-supplied finite percentages from 0 to 100 that should sum to 100; it throws a `RangeError` for a non-finite or out-of-range segment. It does not sum, recalculate, or normalize the percentages. The bar itself is hidden from assistive technology because the visible legend repeats every label and percentage in text. Colors come from the canonical chart tokens and support up to five distinct token choices.
|
|
154
|
+
|
|
155
|
+
`FinancialDataTable` renders already ordered rows with semantic table markup. It accepts display-ready cells; sorting, raw-value ordering, totals, and calculations stay with the caller. Use the optional `DataTable` when the application needs an interactive table engine.
|
|
156
|
+
|
|
157
|
+
`AssumptionNotice` is a warning/info `Notice` composition. Supply the approved explanatory text at the call site. Status always remains in text; color is supplementary.
|
|
158
|
+
|
|
159
|
+
## Overlays (`@wealth-os/design-system/overlays`)
|
|
160
|
+
|
|
161
|
+
Import the optional overlay family only where needed. Radix owns focus containment, Escape/outside dismissal, collision handling and nested overlay stacking; WealthOS wrappers own canonical tokens, geometry and styles. The subpath does not enter through the core package root.
|
|
162
|
+
|
|
163
|
+
```tsx
|
|
164
|
+
import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter } from "@wealth-os/design-system/overlays";
|
|
165
|
+
|
|
166
|
+
<Dialog>
|
|
167
|
+
<DialogTrigger asChild><Button>Edit reference</Button></DialogTrigger>
|
|
168
|
+
<DialogContent>
|
|
169
|
+
<DialogHeader><DialogTitle>Edit reference</DialogTitle><DialogDescription>Update the display value.</DialogDescription></DialogHeader>
|
|
170
|
+
<DialogFooter><Button>Save</Button></DialogFooter>
|
|
171
|
+
</DialogContent>
|
|
172
|
+
</Dialog>
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
The anatomy is composable and controlled or uncontrolled using Radix `open`, `defaultOpen`, and `onOpenChange`. `DialogContent` adds a portal and overlay; supply a `DialogTitle`, and a description when useful. Escape and outside pointer close by default; prevent outside dismissal only for a documented interaction need.
|
|
176
|
+
|
|
177
|
+
`AlertDialog` provides alert-dialog semantics and Radix's deliberate initial focus and dismissal policy. `ConfirmationDialog` is a reusable confirmation composition (`title`, `description`, `onConfirm`, optional `trigger`, button labels, `destructive`). `Popover` supports `side`, `align`, `sideOffset`, and collision props. `TooltipProvider` wraps tooltip groups; tooltip content is descriptive and noninteractive, and the trigger still needs its own accessible name. `DropdownMenu` exports Radix menu parts, including disabled items and submenus, and supports arrows, Home/End, typeahead, Escape and focus return.
|
|
178
|
+
|
|
179
|
+
`Sheet` uses the Dialog engine and accepts `side="left|right|top|bottom"`; `Drawer` is an alias to that same primitive family, not a second overlay implementation. On mobile the sheet uses dynamic viewport sizing, scrolling and safe-area padding. Base UI Drawer was evaluated but not adopted: the current contract needs modal keyboard/touch navigation, close controls and safe-area sizing, all covered by Radix Dialog, while adding swipe/snap gestures would create an unrequested second overlay behavior engine.
|
|
180
|
+
|
|
181
|
+
`CommandMenu` is separately available from `@wealth-os/design-system/command-menu` so consumers that need only Dialog, Popover or menus do not load the command-search engine. It uses `cmdk` inside the same Radix Dialog engine and accepts controlled `open`, `onOpenChange`, and `CommandMenuItem` children. Editable entity search remains a separate combobox contract.
|
|
182
|
+
|
|
183
|
+
## Navigation (`@wealth-os/design-system/navigation`)
|
|
184
|
+
|
|
185
|
+
`Tabs`, `TabsList`, `TabsTrigger`, and `TabsContent` wrap Radix Tabs. They provide roving focus, arrow keys, Home/End, disabled tabs, and automatic activation by default; set `activationMode="manual"` when panel loading makes automatic activation unsuitable. Tabs switch local panels and do not replace route links.
|
|
186
|
+
|
|
187
|
+
`Breadcrumbs` accepts `{ label, href?, current? }[]`, uses a labeled nav/list and `aria-current="page"`; `maxItems` (default 4) keeps the first and last items visible for long paths. `Pagination` is controlled, one-indexed, clamps displayed page bounds, disables Previous/Next at edges, and announces the current page. Consumers own data loading and page state.
|
|
188
|
+
|
|
189
|
+
`NavigationMenu` exports Radix navigation-menu parts for public multi-level link navigation. `Sidebar`, `SidebarHeader`, `SidebarContent`, `SidebarGroup`, `SidebarGroupLabel`, `SidebarMenu`, `SidebarMenuItem`, and `SidebarMenuButton` are primitives only. Route definitions, persistence, collapse state and the actual AppShell remain application-owned.
|
|
190
|
+
|
|
191
|
+
HoverCard has no validated WealthOS use case; supplementary previews can use Popover. The package does not provide a complete app shell, sidebar provider/persistence, mobile swipe physics, or URL-aware navigation composition. Tables and generic data-display primitives are documented in the [tables and data display guide](data-table.md). The optional Recharts family is documented in the [charts guide](charts.md).
|
|
192
|
+
|
|
193
|
+
## Forms and advanced controls
|
|
194
|
+
|
|
195
|
+
### Searchable selection
|
|
196
|
+
|
|
197
|
+
`Combobox`, `Autocomplete`, and `SearchInput` share one filtered-listbox engine. `Combobox`/`Autocomplete` accept a controlled option value and `ChoiceOption[]`; `SearchInput` accepts a free text string and optional suggestions. Arrow keys move through enabled options, Home/End move to the list edges, Enter selects a suggestion, Escape closes, and Tab leaves normally. `clearable` clears a selected value; `loading` and `emptyMessage` cover asynchronous consumer data. The component does not fetch, rank, or match companies. Use `Select`/`SelectMenu` when the value is chosen from a select-only menu without text search.
|
|
198
|
+
|
|
199
|
+
`MultiSelect` uses the same controlled option model for `string[]`, selected chips, a multiselect listbox, removable chip buttons, Backspace removal, and search filtering. Disabled options cannot be selected. The consumer owns maximum counts, async queries, validation, and persistence.
|
|
200
|
+
|
|
201
|
+
```tsx
|
|
202
|
+
<Combobox label="Company" value={company} onChange={setCompany} options={companies} />
|
|
203
|
+
<MultiSelect label="Grant types" value={types} onChange={setTypes} options={grantTypes} />
|
|
204
|
+
<SearchInput label="Search grants" value={query} onChange={setQuery} onSubmit={runSearch} />
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
### Choice and value controls
|
|
208
|
+
|
|
209
|
+
`Checkbox` is a labeled native checkbox that reports `(checked, event)`. `RadioGroup` uses native radios in a labeled fieldset and reports one string value. `Switch` is a native checkbox with switch semantics. `Slider` wraps a native single-thumb range input and reports a number. These native controls retain browser form behavior, touch operation, and built-in arrow/space interaction. Multi-thumb slider behavior is not part of this API.
|
|
210
|
+
|
|
211
|
+
`Toggle` is a controlled pressed button. `ToggleGroup` and `SegmentedControl` are aliases over one implementation; single selection uses radio semantics with arrow-key roving focus, and `type="multiple"` exposes independently toggleable buttons. Use `RadioGroup` for form choices that need native form serialization, `ToggleGroup` for action-like pressed choices, and Tabs for switching panels.
|
|
212
|
+
|
|
213
|
+
`InputOTP` exposes one accessible numeric text input per digit, supports one-time-code autocomplete and paste distribution, and keeps the complete value as a string. It does not send or verify a code. `FileUpload` keeps native file input access and optional drag-and-drop, validates the configured accept types and per-file size locally, and returns `File[]`. It never uploads or persists files.
|
|
214
|
+
|
|
215
|
+
`Form` is a styled native `<form>` composition and `FormField` aliases the existing `Field`. Form state and domain validation remain consumer-owned. Import `RHFField` from `@wealth-os/design-system/forms` to connect an existing React Hook Form `register` function to the canonical `Field`. For controlled controls using `Controller` or `useController`, `rhfControllerProps(field)` maps the field value and handlers; pass `{ valueProp: "checked" }` for `Checkbox` or `Switch`. These structural adapters have no React Hook Form runtime import, and no Zod resolver or validation schema is bundled.
|
|
216
|
+
|
|
217
|
+
```tsx
|
|
218
|
+
import { RHFField, rhfControllerProps } from "@wealth-os/design-system/forms";
|
|
219
|
+
|
|
220
|
+
<RHFField name="email" register={register} label="Email">
|
|
221
|
+
<TextInput type="email" />
|
|
222
|
+
</RHFField>
|
|
223
|
+
<Checkbox label="I agree" {...rhfControllerProps(agreementField, { valueProp: "checked" })} />
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
### Date ranges
|
|
227
|
+
|
|
228
|
+
`DateRangePicker` accepts and returns `{ start: ISO string, end: ISO string }`, with empty strings for incomplete endpoints. It composes two existing `DateInput` controls, preserving their US typed format, keyboard calendar, min/max constraints, and focus behavior. End-before-start is visibly invalid and `isDateRangeValid` provides a display-only boundary predicate. Consumers decide whether incomplete ranges are allowed and when to block submission.
|
|
229
|
+
|
|
230
|
+
The current calendar grid was retained because it is already the tested WealthOS `DateInput` engine and preserves its input contract. React DayPicker was evaluated as the roadmap's possible range engine, but it is not in the installed dependency set; adding it would create a second calendar implementation before a parity spike. This batch reuses the tested calendar through `DateInput` instead.
|
|
231
|
+
|
|
232
|
+
The batch keeps `NumberInput`, `MoneyInput`, `QuantityInput`, `Select`, `SelectMenu`, `DateInput`, `UsDateInput`, and `Field` APIs intact. The simple controls use native HTML semantics; the package's current Radix foundation continues to own its existing overlay and navigation families. `cmdk` remains isolated to `/command-menu`.
|
|
233
|
+
|
|
234
|
+
## Foundation utilities
|
|
235
|
+
|
|
236
|
+
For measure selection, vertical rhythm, wrapping groups, auto-fit collections, fixed responsive grids, and page recipes, see the [layout composition guide](layout-composition.md).
|
|
237
|
+
|
|
238
|
+
- Typography: `type-display`, `type-display-section`, `type-page-title`, `type-section-title`, `type-subsection`, `type-body`, `type-label`, `type-supporting`, `type-caption`, `type-metadata`, `type-control`, `type-eyebrow`, `type-figure`, and `tabular`.
|
|
239
|
+
- Page measures: `page-container-wide`, `page-container-standard`, `page-container-focused`, `page-container-readable`, and `page-container-shell`.
|
|
240
|
+
- Responsive layout: `layout-stack`, `layout-cluster`, and `layout-auto-grid`. Set `--layout-stack-gap`, `--layout-cluster-gap`, `--layout-grid-gap`, or `--layout-grid-min` on an instance when its spacing needs an explicit adjustment.
|
|
241
|
+
- Focus: `wos-focus-ring` applies the shared visible focus treatment to non-button interactive elements.
|
|
242
|
+
- Motion: transitions use `--motion-duration-fast`, `--motion-duration-standard`, and `--motion-ease-standard`. The package sets durations to zero under `prefers-reduced-motion: reduce`.
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
## Explicit control density (slice 2)
|
|
246
|
+
|
|
247
|
+
```tsx
|
|
248
|
+
import { Button, Field, TextInput, MoneyInput, Select, DateInput, type ControlDensity } from "@wealth-os/design-system";
|
|
249
|
+
const density: ControlDensity = "comfortable";
|
|
250
|
+
<Button density={density}>Save</Button>
|
|
251
|
+
<Field label="Employer"><TextInput density={density} /></Field>
|
|
252
|
+
<MoneyInput density={density} label="Amount" value={amount} onChange={setAmount} />
|
|
253
|
+
<Select density={density} label="Filing status" value={status} onChange={setStatus} options={options} />
|
|
254
|
+
<Field label="Settlement date"><DateInput density={density} value={date} onChange={setDate} /></Field>
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
Use the same explicit density on related supported controls. Compact is 36px/14px; comfortable is 44px/15px. The optional prop is supported by Button, IconButton, TextInput, Textarea, NumberInput, MoneyInput, QuantityInput, Select, SelectMenu, DateInput, UsDateInput and DateRangePicker. Wrappers pass it through to their inputs. It is consumed rather than forwarded as a native `density` attribute.
|
|
258
|
+
|
|
259
|
+
Omission retains all existing sizes. Explicit density overrides legacy Button height/icon size and Select/Date `compact` geometry; existing size-based padding remains. Link Buttons remain auto-height. Caller classes can still override sizing intentionally. Textarea remains multiline (minimum 6rem), with density-specific font/padding rather than a fixed single-line height. Date popup keyboard/grid behavior remains unchanged; only its input and calendar trigger use density. Select popup rows adopt the explicit 36/44px density.
|
|
260
|
+
|
|
261
|
+
No blanket parent density provider is introduced. Other component families retain existing APIs until separately reviewed.
|
|
262
|
+
|
|
263
|
+
## Shared typography roles (slice 2)
|
|
264
|
+
|
|
265
|
+
Use `type-product-page-title` / `type-product-section-title` for application headings (32px, responsive 26px / 22px, weight 500), `type-body` (16px/400), `type-supporting` (14px/400), `type-label` (14px/500) and `type-figure` (28px/500, tabular numerals). Existing `type-page-title` / `type-section-title` remain aliases. CardTitle uses the shared 18px/500 subsection role. FinancialMetric/Stat values consume shared figure styling without changing supplied text or formatting.
|
|
266
|
+
|
|
267
|
+
Marketing uses the opt-in `type-marketing-heading` role (48px/500, 32px on narrow screens). Existing light display roles remain available. Do not apply marketing display/hero dimensions to application headings or ordinary amounts.
|
|
268
|
+
|
|
269
|
+
|
|
270
|
+
## Shared interaction consistency and radius options (slice 3)
|
|
271
|
+
|
|
272
|
+
```tsx
|
|
273
|
+
<Surface radius="lg">16px panel</Surface>
|
|
274
|
+
<Card radius="xl">24px presentation card</Card>
|
|
275
|
+
<Combobox density="comfortable" label="Issuer" value={issuer} onChange={setIssuer} options={issuers} />
|
|
276
|
+
<MultiSelect density="comfortable" label="Grant types" value={types} onChange={setTypes} options={grantTypes} />
|
|
277
|
+
<Checkbox density="comfortable" label="Reviewed" checked={reviewed} onChange={setReviewed} />
|
|
278
|
+
<Toggle density="compact" pressed={comparing} onPressedChange={setComparing}>Compare</Toggle>
|
|
279
|
+
<TabsTrigger density="comfortable" value="summary">Summary</TabsTrigger>
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
Surface and Card share `radius="default" | "lg" | "xl"`; omission stays 8px, new options are 16/24px. The component remains a generic container. No radius prop is added to unrelated families; overlay geometry stays compatible.
|
|
283
|
+
|
|
284
|
+
Additional density support: Combobox and its Autocomplete/SearchInput wrappers, MultiSelect, Checkbox, RadioGroup, Toggle, ToggleGroup/SegmentedControl and TabsTrigger (`TabsTriggerProps` is exported from `/navigation`). All props are optional. MultiSelect and choice/option rows use minimum/growing dimensions; checkbox/radio indicator size and the padded TabsList/group frame do not become fixed 36/44px boxes. Native switches/sliders and OTP/file-upload controls retain their own established sizes.
|
|
285
|
+
|
|
286
|
+
States now consume independent semantic roles: neutral hover, flat selected fill, raised white tab selection, navy solid selection indicator, focus ring, disabled opacity and destructive invalid cue. MultiSelect error/disabled state is visible on its composite boundary. Selected list options keep `aria-selected` and visible selection weight; disabled options stay non-selectable. Menu keyboard highlight gains explicit focus-visible styling; CommandMenu's item styles are scoped to its own wrapper rather than all cmdk instances.
|
|
287
|
+
|
|
288
|
+
Sidebar current items, pagination current page, calendar days, native table checkboxes, progress/timeline indicators and chart legend interaction styling no longer depend on primary-action recoloring. Badge/StatusBadge/Notice were reviewed: neutral metadata stays neutral, while explicit info/estimated/success/warning/error palettes remain as approved. No financial formatting or interaction engine was replaced.
|
|
289
|
+
|
|
290
|
+
|
|
291
|
+
TabsList now wraps within its available width and long trigger labels can wrap. This prevents the 320px example from extending past its content column while preserving logical tab order and the Radix keyboard model. CommandMenu now restores its captured external focus target after close; see the accessibility guide for removed/inert and programmatic-open boundaries.
|
|
292
|
+
|
|
293
|
+
|
|
294
|
+
## Release audit refinements
|
|
295
|
+
|
|
296
|
+
Non-destructive ConfirmationDialog actions use primary action roles (including host primary overrides); destructive confirmation keeps error roles. Main control and select popup radius is 8px. Named `--control-radius-inner: 4px` preserves embedded calendar/clear/chip geometry and gives dense menu rows a consistent inner role. Calendar disabled opacity uses the existing shared disabled-state token. These are visual token refinements; no parsing or calendar keyboard rule changes.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Tables and data display
|
|
2
|
+
|
|
3
|
+
Import `@wealth-os/design-system/styles.css` once. The semantic `Table` family and generic data-display components are included in the root package. `DataTable` is available only from `@wealth-os/design-system/data-table`; this entry imports TanStack Table v9 and its React adapter. It does not fetch data, calculate financial values, or apply domain-specific transformations.
|
|
4
|
+
|
|
5
|
+
## Lightweight semantic tables
|
|
6
|
+
|
|
7
|
+
Use the semantic parts for small, static, or application-managed tables. `Table` accepts native table attributes and `density="compact|comfortable"` (comfortable is the default). The overflow wrapper stays keyboard-scrollable on narrow screens. Name the table with `aria-label` or provide a `TableCaption`.
|
|
8
|
+
|
|
9
|
+
```tsx
|
|
10
|
+
import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell, TableCaption } from "@wealth-os/design-system";
|
|
11
|
+
|
|
12
|
+
<Table aria-label="Records" density="compact">
|
|
13
|
+
<TableCaption>Display-ready record values</TableCaption>
|
|
14
|
+
<TableHeader><TableRow><TableHead>Name</TableHead><TableHead>Value</TableHead></TableRow></TableHeader>
|
|
15
|
+
<TableBody><TableRow><TableCell>Example</TableCell><TableCell className="tabular">$42.80</TableCell></TableRow></TableBody>
|
|
16
|
+
</Table>
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
`TableHead` defaults to `scope="col"`; pass another native scope for row/group headings. Number alignment remains a caller choice (for example `text-right tabular`). The table does not infer financial semantics from a string or color.
|
|
20
|
+
|
|
21
|
+
## Typed advanced table
|
|
22
|
+
|
|
23
|
+
Column definitions use TanStack v9's feature-aware helper. The helper and renderer preserve the consumer's row type, including typed accessor values and cell render props.
|
|
24
|
+
|
|
25
|
+
```tsx
|
|
26
|
+
import { createDataTableColumnHelper, DataTable } from "@wealth-os/design-system/data-table";
|
|
27
|
+
|
|
28
|
+
type RecordRow = { id: string; name: string; displayValue: string };
|
|
29
|
+
const column = createDataTableColumnHelper<RecordRow>();
|
|
30
|
+
const columns = column.columns([
|
|
31
|
+
column.accessor("name", { header: "Name", enableSorting: true, enableColumnFilter: true }),
|
|
32
|
+
column.accessor("displayValue", { header: "Value", meta: { align: "right" } }),
|
|
33
|
+
]);
|
|
34
|
+
|
|
35
|
+
<DataTable
|
|
36
|
+
ariaLabel="Records"
|
|
37
|
+
data={records}
|
|
38
|
+
columns={columns}
|
|
39
|
+
getRowId={(row) => row.id}
|
|
40
|
+
enableSorting
|
|
41
|
+
enableFiltering
|
|
42
|
+
enableGlobalFilter
|
|
43
|
+
enablePagination
|
|
44
|
+
/>
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
DataTable supports client-side sorting, column text filters, global search, pagination, page-scoped row selection, column visibility, pointer and keyboard column resizing, start/end pinning, and expandable rows. Search stays on the left of a compact toolbar; column filters and column visibility open in accessible WealthOS popovers on the right. Active filters are counted and can be cleared together. Each feature can be disabled with its `enable…` prop. Column filters require an accessor column; text contains matching is the default and an explicit `filterFn` overrides it. Sorting can be enabled per column. For expansion, provide `renderSubComponent`; records can also contain nested `subRows`.
|
|
48
|
+
|
|
49
|
+
The `density` prop supports `compact` and `comfortable`. `loading`, `loadingLabel`, `error`, and `emptyState` provide data-state presentation. A supplied `caption` remains a semantic table caption and is displayed compactly above the header. The footer keeps the result count separate from a grouped page-size and pagination control area, which stacks at narrow widths. For an edge-to-edge card composition, pass `className="wos-data-table-card-aligned"` to inset only the toolbar and footer to the canonical page gutter; the table and its scroll area remain full width. `caption`, `ariaLabel`, `toolbar`, `pageSizeOptions`, `renderSubComponent`, `className`, and `getRowId` customize the presentation without replacing its semantics. Stable row IDs are recommended when selection must persist across sorting, filtering, and server pages.
|
|
50
|
+
|
|
51
|
+
## Controlled and uncontrolled state
|
|
52
|
+
|
|
53
|
+
Uncontrolled state starts from `initialState`; the engine manages changes internally. To control a state slice, pass that slice through `state` and pass the matching callback. TanStack callbacks receive either a next value or an updater function and are compatible with React state setters.
|
|
54
|
+
|
|
55
|
+
```tsx
|
|
56
|
+
const [sorting, setSorting] = useState<SortingState>([]);
|
|
57
|
+
<DataTable
|
|
58
|
+
data={records}
|
|
59
|
+
columns={columns}
|
|
60
|
+
state={{ sorting }}
|
|
61
|
+
onSortingChange={setSorting}
|
|
62
|
+
/>
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
State slices are `sorting`, `columnFilters`, `globalFilter`, `pagination`, `rowSelection`, `columnVisibility`, `columnSizing`, `columnPinning`, and `expanded`. `DataTableState` is exported for consumers that keep the combined object. Control only the slices the application needs; provide both a state value and its matching callback.
|
|
66
|
+
|
|
67
|
+
## Server-side data modes
|
|
68
|
+
|
|
69
|
+
The application remains responsible for fetching and transforming data. Set `manualSorting`, `manualFiltering`, and/or `manualPagination` for server-owned operations, control the corresponding state slices, and pass the current page of already-processed data. `pageCount` or `rowCount` can describe the known total for manual pagination. `DataTable` calls no network API and does not infer query parameters or cache keys. For server filtering, expose controls that update the controlled filters/search state and let the application request the next result set.
|
|
70
|
+
|
|
71
|
+
Row selection's header checkbox selects the current page. It does not imply that matching rows on other server pages are selected. The selected row count and state describe the IDs held by TanStack; the application owns bulk actions and cross-page selection policy.
|
|
72
|
+
|
|
73
|
+
## Data-display components
|
|
74
|
+
|
|
75
|
+
- `Avatar` renders a provided image and named fallback; `AvatarGroup` caps visible children and reports the overflow count.
|
|
76
|
+
- `DescriptionList` composes semantic `dl` content, and `KeyValue` provides a `dt`/`dd` pair. `DataList` is a generic semantic list.
|
|
77
|
+
- `EmptyState` is a titled, optional description/action composition. `Skeleton` is hidden from assistive technology; pair it with a named status when loading.
|
|
78
|
+
- `Progress` and `CircularProgress` require `label`, accept a nullable value for indeterminate loading, and expose progressbar values to assistive technology.
|
|
79
|
+
- `Separator`, native-scroll `ScrollArea`, CSS `AspectRatio`, `Stat`, `MetricCard`, and `Timeline` are token-styled presentation primitives.
|
|
80
|
+
|
|
81
|
+
The standard shadcn data-display catalog was reviewed. `Card`/`Surface`, `Badge`, `Notice`, pagination, tabs, breadcrumbs and separators already have canonical WealthOS implementations. `Table`, avatar patterns, descriptions, empty states, skeletons, progress, scroll area, aspect ratio, stats, timelines, and lists fill generic presentation needs in this batch. Chart families remain scheduled for `/charts`; tooltips, hover previews and command controls already belong to their existing overlay/navigation entries. A calendar, financial-value formatting, notification toast, tree view, or domain-specific data grid would duplicate existing behavior or need an application use case and is not introduced here.
|
|
82
|
+
|
|
83
|
+
## Accessibility and responsive behavior
|
|
84
|
+
|
|
85
|
+
Tables render native table elements, a caption or accessible label, scoped column headers, and native buttons/inputs. Sort direction appears in `aria-sort` and the sort action name. Selection uses checkboxes and `aria-selected`; the header checkbox explicitly names current-page selection. Resizable headers can be operated with pointer/touch or focused Arrow Left/Right (16px per key press). Pin and expand actions are named buttons. The component does not implement spreadsheet-style cell navigation; Tab follows the ordinary document order.
|
|
86
|
+
|
|
87
|
+
The table scrolls horizontally when its columns exceed the viewport. Loading uses one polite status region and an error uses an alert. Empty results keep a helpful text state inside the table. Decorative skeletons are hidden from screen readers. Progress values have labels and text alternatives. Shared motion tokens are zeroed for reduced-motion preferences.
|
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
# Layout composition
|
|
2
|
+
|
|
3
|
+
Use this guide to compose WealthOS pages from the existing page measures, layout utilities, Tailwind CSS, and public presentation components. Composition belongs in the page or feature that owns the content. This guide adds no React layout API.
|
|
4
|
+
|
|
5
|
+
The recipes below demonstrate reusable page and section composition patterns with illustrative examples.
|
|
6
|
+
|
|
7
|
+
## Choose the layout tool
|
|
8
|
+
|
|
9
|
+
| Need | Use |
|
|
10
|
+
|---|---|
|
|
11
|
+
| Set the page's readable measure and shared inline gutter | `page-container-*` |
|
|
12
|
+
| Repeat vertical spacing between peer sections | `layout-stack` |
|
|
13
|
+
| Put related controls or actions on one line and let them wrap | `layout-cluster` |
|
|
14
|
+
| Fit equal cards into the available width based on a minimum card width | `layout-auto-grid` |
|
|
15
|
+
| Set unequal columns, fixed semantic rows, or explicit item spans | Native CSS Grid with Tailwind utilities |
|
|
16
|
+
| Align a small set of related inline items without wrapping | Flexbox utilities such as `flex items-center gap-*` |
|
|
17
|
+
|
|
18
|
+
Prefer the simplest composition that expresses the content relationship. Use existing `Surface`, `Card`, `MetricCard`, `FinancialMetric`, and form controls for their established presentation; the parent page decides their order and placement.
|
|
19
|
+
|
|
20
|
+
## Page containers
|
|
21
|
+
|
|
22
|
+
Choose a measure based on the content, not the route name. Each utility centers its content, applies `--page-gutter`, and caps width using the matching `--content-width-*` token.
|
|
23
|
+
|
|
24
|
+
| Utility | Token width | Good fit |
|
|
25
|
+
|---|---:|---|
|
|
26
|
+
| `page-container-wide` | 1152px | Dashboards, broad tables, card collections, and pages with multiple regions |
|
|
27
|
+
| `page-container-standard` | 1024px | Settings, account records, and forms with a moderate number of fields |
|
|
28
|
+
| `page-container-focused` | 512px | Short tasks, authentication, and narrow single-column forms |
|
|
29
|
+
| `page-container-readable` | 672px | Long-form guidance and text-heavy content |
|
|
30
|
+
|
|
31
|
+
`page-container-shell` currently uses the wide measure and gutter for shell-level content. Use the matching `page-container-*` for ordinary page content. These utilities apply inline gutters; do not add another identical page padding without checking the result.
|
|
32
|
+
|
|
33
|
+
```tsx
|
|
34
|
+
import type { CSSProperties } from "react";
|
|
35
|
+
|
|
36
|
+
<main className="page-container-standard py-8">
|
|
37
|
+
<div className="layout-stack" style={{ "--layout-stack-gap": "1.5rem" } as CSSProperties}>
|
|
38
|
+
<header>
|
|
39
|
+
<h1 className="type-page-title">Account details</h1>
|
|
40
|
+
<p className="mt-2 type-supporting text-muted-foreground">Review your saved information.</p>
|
|
41
|
+
</header>
|
|
42
|
+
<AccountDetails />
|
|
43
|
+
</div>
|
|
44
|
+
</main>
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Vertical rhythm
|
|
48
|
+
|
|
49
|
+
Use `layout-stack` for a column of peer items that share a gap. A page-level stack can space sections, while a separate stack inside a card or component controls its local rhythm. Keep these responsibilities separate: large gaps between page sections should not force the same large gaps between a label and its value.
|
|
50
|
+
|
|
51
|
+
The default stack gap is 1rem. For an intentional local exception, set `--layout-stack-gap` on that instance; otherwise use the default spacing or existing Tailwind spacing utilities. Avoid repeated margins on every child when the items are peers.
|
|
52
|
+
|
|
53
|
+
```tsx
|
|
54
|
+
import type { CSSProperties } from "react";
|
|
55
|
+
|
|
56
|
+
<div className="layout-stack" style={{ "--layout-stack-gap": "1.5rem" } as CSSProperties}>
|
|
57
|
+
<PortfolioSummary />
|
|
58
|
+
<UpcomingEvents />
|
|
59
|
+
<HoldingsTable />
|
|
60
|
+
</div>
|
|
61
|
+
|
|
62
|
+
{/* Inside a component, keep its own tighter rhythm. */}
|
|
63
|
+
<Surface className="layout-stack p-5" style={{ "--layout-stack-gap": "0.75rem" } as CSSProperties}>
|
|
64
|
+
<h2 className="type-subsection">Grant details</h2>
|
|
65
|
+
<GrantMetadata />
|
|
66
|
+
</Surface>
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Inline groups
|
|
70
|
+
|
|
71
|
+
Use `layout-cluster` for controls that belong together and may wrap: action groups, filters, badges, and toolbars. It wraps by default, vertically centers items, and uses a 0.5rem gap. Set `--layout-cluster-gap` only when the group needs different spacing. Give a group an accessible name when its controls need shared context.
|
|
72
|
+
|
|
73
|
+
```tsx
|
|
74
|
+
<div className="layout-cluster" aria-label="Portfolio actions">
|
|
75
|
+
<Button>Review grants</Button>
|
|
76
|
+
<Button variant="secondary">Add grant</Button>
|
|
77
|
+
</div>
|
|
78
|
+
|
|
79
|
+
<div className="layout-cluster" aria-label="Grant filters">
|
|
80
|
+
<SelectMenu ariaLabel="Filter by company" value={company} onChange={setCompany} options={companies} />
|
|
81
|
+
<SelectMenu ariaLabel="Filter by grant type" value={type} onChange={setType} options={grantTypes} />
|
|
82
|
+
<Button variant="ghost">Clear filters</Button>
|
|
83
|
+
</div>
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Use the public `ButtonGroup` when controls are a named set of related actions and its documented group semantics fit. A wrapping cluster is a layout behavior; it does not create toolbar keyboard behavior or selection semantics.
|
|
87
|
+
|
|
88
|
+
## Card collections and explicit grids
|
|
89
|
+
|
|
90
|
+
Use `layout-auto-grid` when items are peers, can be equal width, and should fill each row according to a minimum card width. It uses `auto-fit` and `minmax`; set `--layout-grid-min` and `--layout-grid-gap` locally when the content needs different values. The default minimum is 16rem and the default gap is 1rem.
|
|
91
|
+
|
|
92
|
+
```tsx
|
|
93
|
+
import type { CSSProperties } from "react";
|
|
94
|
+
|
|
95
|
+
<div className="layout-auto-grid" style={{ "--layout-grid-min": "15rem", "--layout-grid-gap": "1rem" } as CSSProperties}>
|
|
96
|
+
{events.map((event) => <EventCard key={event.id} event={event} />)}
|
|
97
|
+
</div>
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Use explicit columns when the relationship matters: a 3:2 hero, exactly three summary metrics, a two-column form group, or a full-width item among smaller items. `layout-auto-grid` intentionally does not define fixed columns, unequal widths, or spans.
|
|
101
|
+
|
|
102
|
+
```tsx
|
|
103
|
+
<div className="grid min-w-0 gap-4 xl:grid-cols-[minmax(0,3fr)_minmax(0,2fr)]">
|
|
104
|
+
<section className="min-w-0"><PrimaryMetric /></section>
|
|
105
|
+
<section className="min-w-0"><EquitySummary /></section>
|
|
106
|
+
</div>
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## Dashboard composition
|
|
110
|
+
|
|
111
|
+
Compose a dashboard in semantic reading order: primary summary first, supporting metrics next, then full-width data and detail sections. Use existing metric and chart/data components inside ordinary sections. Let content determine row height. Use `minmax(0, …)` tracks and `min-w-0` on grid items that contain long labels, values, or charts so their intrinsic width does not force page overflow.
|
|
112
|
+
|
|
113
|
+
This example uses the requested wide-screen 3:2 primary split, a three-column secondary row, and full-width sections. `xl` is a starting point for the Lab's 248px sidebar shell, not a universal rule; verify the actual content width in the consuming shell.
|
|
114
|
+
|
|
115
|
+
```tsx
|
|
116
|
+
import type { CSSProperties } from "react";
|
|
117
|
+
|
|
118
|
+
<main className="page-container-wide layout-stack py-8" style={{ "--layout-stack-gap": "1.5rem" } as CSSProperties}>
|
|
119
|
+
<div className="grid min-w-0 gap-4 xl:grid-cols-[minmax(0,3fr)_minmax(0,2fr)]">
|
|
120
|
+
<section aria-labelledby="portfolio-title" className="min-w-0">
|
|
121
|
+
<MetricCard label="Estimated portfolio value" value="$284,650" detail="Illustrative · as of Oct 10" />
|
|
122
|
+
</section>
|
|
123
|
+
<section aria-labelledby="equity-title" className="min-w-0">
|
|
124
|
+
<PortfolioSummary />
|
|
125
|
+
</section>
|
|
126
|
+
</div>
|
|
127
|
+
|
|
128
|
+
<section aria-label="Supporting portfolio metrics" className="grid min-w-0 gap-3 sm:grid-cols-2 xl:grid-cols-3">
|
|
129
|
+
<MetricCard label="Vested shares" value="4,860" detail="Across 3 grants" />
|
|
130
|
+
<MetricCard label="Unvested shares" value="12,420" detail="Next vest Oct 20" />
|
|
131
|
+
<MetricCard label="Needs review" value="2 grants" detail="Confirm dates and counts" />
|
|
132
|
+
</section>
|
|
133
|
+
|
|
134
|
+
<section aria-labelledby="trend-title" className="min-w-0"><PortfolioChart /></section>
|
|
135
|
+
<section aria-labelledby="holdings-title" className="min-w-0"><HoldingsTable /></section>
|
|
136
|
+
</main>
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
The source order is also the narrow-screen order: hero, supporting metrics, chart, and table. The hero and metrics stack below their chosen thresholds. If a three-card row would make cards too narrow in an intermediate shell, keep two columns or stack them until the available width supports three. Do not use CSS `order` to move meaningful information away from its DOM reading order. Tables and charts should own their local overflow or narrow presentation.
|
|
140
|
+
|
|
141
|
+
## Split calculator layouts
|
|
142
|
+
|
|
143
|
+
Use an authored grid for calculator inputs and results because the two regions have different roles and usually different preferred widths. Keep inputs before results in source order, stack them at narrow widths, and choose the desktop threshold from usable content width. Do not add a `SplitLayout` wrapper. Sticky behavior is optional and belongs to the page: use it only if the content height, shell header, scrolling behavior, and keyboard access have been checked together.
|
|
144
|
+
|
|
145
|
+
```tsx
|
|
146
|
+
<div className="grid min-w-0 items-start gap-5 xl:grid-cols-[minmax(0,2fr)_minmax(0,3fr)]">
|
|
147
|
+
<section aria-labelledby="assumptions-title" className="min-w-0">
|
|
148
|
+
<AssumptionsForm />
|
|
149
|
+
</section>
|
|
150
|
+
<section aria-labelledby="results-title" className="min-w-0">
|
|
151
|
+
<ScenarioResults />
|
|
152
|
+
</section>
|
|
153
|
+
</div>
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
If sticky results are useful after review, apply a page-owned class such as `xl:sticky xl:top-20` to the results region and ensure it can scroll when taller than the viewport. Avoid sticky behavior on mobile or when it obscures focused controls.
|
|
157
|
+
|
|
158
|
+
## Forms
|
|
159
|
+
|
|
160
|
+
Use the existing `Field`, `TextInput`, `NumberInput`, `MoneyInput`, `Select`, date, and choice components. A single-column layout is a good default for focused tasks and fields with longer help or validation. Use a two-column grid when adjacent fields are short and related, and allow long fields to span both columns. Collapse to one column before controls become cramped; `sm` is a common starting point, not a mandate.
|
|
161
|
+
|
|
162
|
+
For a focused task, keep fields in one column and let the form's natural width set the measure:
|
|
163
|
+
|
|
164
|
+
```tsx
|
|
165
|
+
<form className="page-container-focused layout-stack py-8">
|
|
166
|
+
<Field label="Email"><TextInput type="email" autoComplete="email" /></Field>
|
|
167
|
+
<Field label="Account name"><TextInput value={name} onChange={setName} /></Field>
|
|
168
|
+
<Button type="submit">Continue</Button>
|
|
169
|
+
</form>
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
For broader records, use a two-column field group that collapses on narrow screens:
|
|
173
|
+
|
|
174
|
+
```tsx
|
|
175
|
+
import type { CSSProperties } from "react";
|
|
176
|
+
|
|
177
|
+
<form className="layout-stack" style={{ "--layout-stack-gap": "1.5rem" } as CSSProperties}>
|
|
178
|
+
<div className="grid min-w-0 gap-x-5 gap-y-4 sm:grid-cols-2">
|
|
179
|
+
<Select label="Company" value={company} onChange={setCompany} options={companies} />
|
|
180
|
+
<Field label="Grant name"><TextInput value={name} onChange={setName} /></Field>
|
|
181
|
+
<MoneyInput label="Strike price" value={strike} onChange={setStrike} />
|
|
182
|
+
<Field label="Grant date"><DateInput value={date} onChange={setDate} ariaLabel="Grant date" /></Field>
|
|
183
|
+
<div className="min-w-0 sm:col-span-2">
|
|
184
|
+
<Field label="Notes"><Textarea value={notes} onChange={(event) => setNotes(event.target.value)} /></Field>
|
|
185
|
+
</div>
|
|
186
|
+
</div>
|
|
187
|
+
<div className="layout-cluster" aria-label="Form actions">
|
|
188
|
+
<Button type="submit">Save grant</Button>
|
|
189
|
+
<Button type="button" variant="secondary">Cancel</Button>
|
|
190
|
+
</div>
|
|
191
|
+
</form>
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
Preserve programmatic labels, help, error associations, and logical DOM order. A visual two-column group does not change which field comes first for keyboard and assistive-technology users.
|
|
195
|
+
|
|
196
|
+
## Responsive thresholds and the application shell
|
|
197
|
+
|
|
198
|
+
Tailwind breakpoints describe viewport width, not the width left for page content. In the Workspace shell, a persistent 248px sidebar appears at `lg` (1024px); page padding and the `page-container` gutter further reduce the usable area. A two-column grid activated at `lg` can therefore become cramped precisely when the sidebar appears.
|
|
199
|
+
|
|
200
|
+
Before enabling a multi-column layout:
|
|
201
|
+
|
|
202
|
+
1. Calculate or inspect the main column width with the real shell/sidebar state and page gutters present.
|
|
203
|
+
2. Check the minimum readable width of every track, including controls, long labels, and chart/table content.
|
|
204
|
+
3. Keep content stacked or use fewer columns until both tracks fit comfortably. `xl` (1280px) is a reasonable initial check for the Lab's full sidebar, not a new global breakpoint or guarantee for every app.
|
|
205
|
+
4. Inspect intermediate widths and the collapsed/drawer shell, not only phone and large desktop widths.
|
|
206
|
+
|
|
207
|
+
Prefer existing `sm` (640px), `md` (768px), `lg` (1024px), and `xl` (1280px) variants. Do not add a global breakpoint to solve one composition. A container query can be appropriate when a reusable component must respond to its own rendered width, but keep that behavior local and use it only when it solves a demonstrated need.
|
|
208
|
+
|
|
209
|
+
## Common mistakes
|
|
210
|
+
|
|
211
|
+
- Using `layout-auto-grid` for a 3:2 hero or a fixed three-item row; use explicit grid tracks for authored relationships.
|
|
212
|
+
- Turning on a desktop grid at `lg` without checking the persistent sidebar and page gutters.
|
|
213
|
+
- Allowing grid children to keep their intrinsic minimum width; use `min-w-0` and `minmax(0, …)` where content can overflow.
|
|
214
|
+
- Applying fixed card heights to align variable content; let rows size naturally and align interiors only when their content contract requires it.
|
|
215
|
+
- Using CSS `order` to rearrange meaningful content; keep DOM order aligned with reading order.
|
|
216
|
+
- Using a cluster as though it provides toolbar keyboard behavior or selection semantics.
|
|
217
|
+
- Nesting page-level spacing rules inside every component, or repeating the same child margins instead of using a stack.
|
|
218
|
+
- Adding a React wrapper for a short native Grid/Flexbox composition. The page owns placement; the Design System owns generic primitives and their presentation.
|
|
219
|
+
|
|
220
|
+
## Related references
|
|
221
|
+
|
|
222
|
+
- [Component catalog](components.md) for public component contracts.
|
|
223
|
+
- [Token reference](tokens.md) for content measures and canonical spacing values.
|
|
224
|
+
- [Accessibility guidance](accessibility.md) for form labeling and semantic composition.
|