@lilydesignsystem/react-headless 0.5.1 → 0.6.1

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.
Files changed (7) hide show
  1. package/CHANGELOG.md +16 -2
  2. package/LICENSE.md +8 -8
  3. package/README.md +1197 -0
  4. package/dist/index.d.ts +560 -35
  5. package/dist/index.js +4173 -2145
  6. package/index.md +73 -37
  7. package/package.json +6 -5
package/index.md CHANGED
@@ -1,15 +1,15 @@
1
1
  # Lily Design System™ - React Headless
2
2
 
3
- A comprehensive headless React component library with 490 accessible, unstyled components for building design systems. Every component follows WCAG 2.2 AAA guidelines with full ARIA support, keyboard navigation, and internationalization readiness.
3
+ A comprehensive headless React component library with 583 accessible, unstyled components for building design systems. Every component follows WCAG 2.2 AAA guidelines with full ARIA support, keyboard navigation, and internationalization readiness.
4
4
 
5
5
  **Headless** means zero CSS, zero styles, zero opinions about appearance. You provide all styling. Components provide structure, semantics, accessibility, and behavior.
6
6
 
7
7
  ## Features
8
8
 
9
- - 490 headless React components
9
+ - 583 headless React components
10
10
  - TypeScript with full type definitions
11
11
  - WCAG 2.2 AAA accessibility compliance
12
- - Full keyboard navigation support
12
+ - Native keyboard operation from semantic elements; custom key handling (arrows, Home/End, Escape, type-ahead) in about 35 components, listed in each component's `AGENTS.md`
13
13
  - ARIA attributes and roles
14
14
  - Internationalization-ready (no hardcoded strings)
15
15
  - Zero dependencies beyond React
@@ -53,7 +53,10 @@ function App() {
53
53
  />
54
54
  <Button onClick={() => alert(`Hello, ${name}!`)}>Greet</Button>
55
55
  {name && (
56
- <Alert type="success" heading="Greeting">
56
+ <Alert
57
+ type="success"
58
+ heading="Greeting"
59
+ >
57
60
  Welcome, {name}!
58
61
  </Alert>
59
62
  )}
@@ -110,9 +113,9 @@ Component names follow a suffix-based pattern that indicates the root HTML eleme
110
113
  | TableHead | `<thead>` | `DataTableHead` |
111
114
  | TableBody | `<tbody>` | `DataTableBody` |
112
115
  | TableFoot | `<tfoot>` | `DataTableFoot` |
113
- | TableTD | `<th>` | `DataTableTD` |
116
+ | TableTD | `<th>` | `DataTableTD` |
114
117
  | TableRow | `<tr>` | `DataTableRow` |
115
- | TableTD | `<td>` | `DataTableTD` |
118
+ | TableTD | `<td>` | `DataTableTD` |
116
119
  | Div | `<div>` | `PinInputDiv`, `PasswordInputOrTextInputDiv` |
117
120
  | Meter | `<meter>` | `Meter` |
118
121
  | Progress | `<progress>` | `Progress` |
@@ -205,7 +208,7 @@ Every component's root element includes a semantic CSS class matching its kebab-
205
208
  | TagInput | Input for adding and removing tags |
206
209
  | TelInput | Telephone number input |
207
210
  | TextInput | Single-line text input |
208
- | TextAreaInput | Multi-line text area |
211
+ | TextAreaInput | Multi-line text area |
209
212
  | ThemeSelect | Visual theme picker |
210
213
  | ThemeSelect | Theme select dropdown |
211
214
  | ThemeSelectOption | One option in theme select |
@@ -225,24 +228,24 @@ Every component's root element includes a semantic CSS class matching its kebab-
225
228
  | Badge | Small label for counts/statuses |
226
229
  | CalendarTable | Calendar grid for dates |
227
230
  | CalendarTableHead/Body/Foot | Calendar table sections |
228
- | CalendarTableTD/Row/Data | Calendar table cells |
231
+ | CalendarTableTD/Row/Data | Calendar table cells |
229
232
  | Card | Grouped content container |
230
233
  | DataTable | Sortable data table grid |
231
234
  | DataTableHead/Body/Foot | Data table sections |
232
- | DataTableTD/Row/Data | Data table cells |
235
+ | DataTableTD/Row/Data | Data table cells |
233
236
  | GanttTable | Gantt chart schedule table |
234
237
  | GanttTableHead/Body/Foot | Gantt table sections |
235
- | GanttTableTH/Row/Data | Gantt table cells |
238
+ | GanttTableTH/Row/Data | Gantt table cells |
236
239
  | KanbanTable | Kanban board table |
237
240
  | KanbanTableHead/Body/Foot | Kanban table sections |
238
- | KanbanTableTD/Row/Data | Kanban table cells |
241
+ | KanbanTableTD/Row/Data | Kanban table cells |
239
242
  | Table | Table with rows and columns |
240
243
  | TableHead | Table thead |
241
244
  | TableBody | Table tbody |
242
245
  | TableFoot | Table tfoot |
243
- | TableTD | Table column |
246
+ | TableTD | Table column |
244
247
  | TableRow | Table row |
245
- | TableTD | Table data cell |
248
+ | TableTD | Table data cell |
246
249
  | Caption | Table/figure caption |
247
250
  | SuperBanner | High-priority state banner for entire app |
248
251
  | SummaryList | Key-value summary pairs |
@@ -268,7 +271,7 @@ Every component's root element includes a semantic CSS class matching its kebab-
268
271
  | Meter | Scalar value gauge |
269
272
  | MockupBrowser | Box area that looks like a web browser |
270
273
  | MockupLaptop | Box area that looks like a laptop computer |
271
- | MockupPhonePortrait | Box area that looks like a mobile phone |
274
+ | MockupPhonePortrait | Box area that looks like a mobile phone |
272
275
  | MockupTabletLandscape | Box area that looks like a tablet in landscape mode |
273
276
  | MockupTabletPortrait | Box area that looks like a tablet in portrait mode |
274
277
  | MockupShell | Box area that looks like a terminal shell |
@@ -343,7 +346,7 @@ Every component's root element includes a semantic CSS class matching its kebab-
343
346
  | Image | Accessible image element |
344
347
  | InsetText | Indented distinguishing text |
345
348
  | Kbd | Keyboard shortcuts and key combinations display |
346
- | QrCodeImage | QR code generator |
349
+ | QrCodeImage | QR code generator |
347
350
  | Skeleton | Loading placeholder animation |
348
351
  | Sparkline | Inline data trend chart |
349
352
  | Notification | Event notification message |
@@ -448,13 +451,13 @@ See the `examples/` directory for comprehensive standalone examples:
448
451
 
449
452
  | Example | Components Used |
450
453
  | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
451
- | [ContactForm](examples/ContactForm.tsx) | Form, Field, TextInput, EmailInput, TextAreaInput, Select, Option, Button, ErrorSummary |
454
+ | [ContactForm](examples/ContactForm.tsx) | Form, Field, TextInput, EmailInput, TextAreaInput, Select, Option, Button, ErrorSummary |
452
455
  | [SettingsPage](examples/SettingsPage.tsx) | SwitchButton, RadioGroup, RadioInput, Select, Separator, Fieldset, Button, Banner |
453
456
  | [Dashboard](examples/Dashboard.tsx) | Card, Progress, ProgressCircle, Badge, Banner, DataTable, DataTableHead/Body/Row/Data |
454
457
  | [PageLayout](examples/PageLayout.tsx) | SkipLink, Header, Footer, NavigationMenu, BreadcrumbNav/List/ListItem, Sidebar |
455
458
  | [TabbedInterface](examples/TabbedInterface.tsx) | TabBar, TabBarButton, AccordionNav/List/ListItem, Badge |
456
459
  | [DialogFlow](examples/DialogFlow.tsx) | Dialog, AlertDialog, Drawer, Button, Popover, Tooltip |
457
- | [RatingAndFeedback](examples/RatingAndFeedback.tsx) | FiveStarRatingPicker/View, FiveFaceRatingPicker, NetPromoterScorePicker, TextAreaInput, Alert |
460
+ | [RatingAndFeedback](examples/RatingAndFeedback.tsx) | FiveStarRatingPicker/View, FiveFaceRatingPicker, NetPromoterScorePicker, TextAreaInput, Alert |
458
461
  | [FileUploadForm](examples/FileUploadForm.tsx) | FileUpload, Progress, Button, Alert, Badge, Form, Field |
459
462
  | [TaskManagement](examples/TaskManagement.tsx) | TaskList, TaskListItem, TextInput, CheckboxInput, Button, Badge, Progress |
460
463
  | [NavigationAndMenus](examples/NavigationAndMenus.tsx) | NavigationMenu, MenuBar, MenuBarButton, ToolBar, ToolBarButton, HamburgerMenu, DropdownMenu, Separator |
@@ -503,11 +506,27 @@ function ContactForm() {
503
506
  </ul>
504
507
  </ErrorSummary>
505
508
  )}
506
- <Field label="Name" required error={errors.name}>
507
- <TextInput label="Name" value={name} onChange={setName} />
509
+ <Field
510
+ label="Name"
511
+ required
512
+ error={errors.name}
513
+ >
514
+ <TextInput
515
+ label="Name"
516
+ value={name}
517
+ onChange={setName}
518
+ />
508
519
  </Field>
509
- <Field label="Email" required error={errors.email}>
510
- <EmailInput label="Email" value={email} onChange={setEmail} />
520
+ <Field
521
+ label="Email"
522
+ required
523
+ error={errors.email}
524
+ >
525
+ <EmailInput
526
+ label="Email"
527
+ value={email}
528
+ onChange={setEmail}
529
+ />
511
530
  </Field>
512
531
  <Button onClick={handleSubmit}>Submit</Button>
513
532
  </div>
@@ -543,9 +562,7 @@ function TabbedContent() {
543
562
  Details
544
563
  </TabBarButton>
545
564
  </TabBar>
546
- {activeTab === "overview" && (
547
- <div id="overview-panel">Overview content</div>
548
- )}
565
+ {activeTab === "overview" && <div id="overview-panel">Overview content</div>}
549
566
  {activeTab === "details" && <div id="details-panel">Details content</div>}
550
567
  </div>
551
568
  );
@@ -589,7 +606,11 @@ function ConfirmDelete() {
589
606
  return (
590
607
  <div>
591
608
  <Button onClick={() => setOpen(true)}>Delete Item</Button>
592
- <Dialog open={open} label="Confirm Deletion" onChange={setOpen}>
609
+ <Dialog
610
+ open={open}
611
+ label="Confirm Deletion"
612
+ onChange={setOpen}
613
+ >
593
614
  <p>Are you sure you want to delete this item?</p>
594
615
  <Button onClick={() => setOpen(false)}>Cancel</Button>
595
616
  <Button
@@ -656,7 +677,10 @@ function RatingExample() {
656
677
  value={rating}
657
678
  onChange={setRating}
658
679
  />
659
- <FiveStarRatingView label="Current rating" value={rating} />
680
+ <FiveStarRatingView
681
+ label="Current rating"
682
+ value={rating}
683
+ />
660
684
  </div>
661
685
  );
662
686
  }
@@ -677,15 +701,15 @@ function FAQ() {
677
701
  <AccordionListItem>
678
702
  <h3>What is a headless component?</h3>
679
703
  <p>
680
- A headless component provides behavior, accessibility, and structure
681
- without any visual styling. You supply all CSS.
704
+ A headless component provides behavior, accessibility, and structure without any visual
705
+ styling. You supply all CSS.
682
706
  </p>
683
707
  </AccordionListItem>
684
708
  <AccordionListItem>
685
709
  <h3>Can I use Tailwind CSS?</h3>
686
710
  <p>
687
- Yes. Pass Tailwind classes via the className prop on every
688
- component. Any CSS framework works.
711
+ Yes. Pass Tailwind classes via the className prop on every component. Any CSS framework
712
+ works.
689
713
  </p>
690
714
  </AccordionListItem>
691
715
  <AccordionListItem>
@@ -746,11 +770,17 @@ function EditableProfile() {
746
770
  <h2>Profile</h2>
747
771
  <div>
748
772
  <span>Name: </span>
749
- <Editable label="Edit name" value="Jane Doe" />
773
+ <Editable
774
+ label="Edit name"
775
+ value="Jane Doe"
776
+ />
750
777
  </div>
751
778
  <div>
752
779
  <span>Title: </span>
753
- <Editable label="Edit title" value="Software Engineer" />
780
+ <Editable
781
+ label="Edit title"
782
+ value="Software Engineer"
783
+ />
754
784
  </div>
755
785
  </div>
756
786
  );
@@ -781,7 +811,10 @@ function TermsForm() {
781
811
  checked={newsletter}
782
812
  onChange={setNewsletter}
783
813
  />
784
- <Button type="submit" disabled={!accepted}>
814
+ <Button
815
+ type="submit"
816
+ disabled={!accepted}
817
+ >
785
818
  Sign Up
786
819
  </Button>
787
820
  </form>
@@ -834,7 +867,10 @@ function Dashboard() {
834
867
  Sprint ends in 3 days. {tasksTotal - tasksCompleted} tasks remaining.
835
868
  </Banner>
836
869
  <div>
837
- <ProgressCircle label="Sprint progress" value={percent} />
870
+ <ProgressCircle
871
+ label="Sprint progress"
872
+ value={percent}
873
+ />
838
874
  <Badge type="success">{percent}% complete</Badge>
839
875
  </div>
840
876
  </div>
@@ -1033,7 +1069,7 @@ pnpm install
1033
1069
  ### Testing
1034
1070
 
1035
1071
  ```bash
1036
- # Run all tests (490 files)
1072
+ # Run all tests (583 files)
1037
1073
  pnpm test
1038
1074
 
1039
1075
  # Run tests in watch mode
@@ -1078,7 +1114,7 @@ All components follow WCAG 2.2 AAA guidelines:
1078
1114
 
1079
1115
  - **Semantic HTML**: Proper element usage (`<button>`, `<nav>`, `<dialog>`, etc.)
1080
1116
  - **ARIA attributes**: Roles, labels, states, and properties
1081
- - **Keyboard navigation**: Full keyboard support for all interactive components
1117
+ - **Keyboard**: native elements are keyboard-operable by default; about 35 components add APG key handling (arrows, Home/End, Escape, type-ahead) — see each component's `AGENTS.md`
1082
1118
  - **Screen readers**: Proper announcements via aria-live, role="alert", etc.
1083
1119
  - **Focus management**: Logical focus order and visible focus indicators
1084
1120
  - **Error handling**: Accessible error messages linked via aria-errormessage
@@ -1139,7 +1175,7 @@ No strings are hardcoded in any component. All user-facing text comes through pr
1139
1175
 
1140
1176
  ## Related Projects
1141
1177
 
1142
- - [Lily Design System](https://github.com/LilyDesignSystem/lily) — Parent project
1178
+ - [Lily Design System](https://github.com/LilyDesignSystem/lily-design-system) — Parent project
1143
1179
  - [React Next.js Examples](../lily-design-system-react-next-examples/) — Example app
1144
1180
  - [HTML Headless](../lily-design-system-html-headless/) — Plain HTML equivalent
1145
1181
  - [Svelte Headless](../lily-design-system-svelte-headless/) — Svelte equivalent
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@lilydesignsystem/react-headless",
3
- "version": "0.5.1",
3
+ "version": "0.6.1",
4
4
  "engines": {
5
- "node": "=26"
5
+ "node": ">=26"
6
6
  },
7
7
  "description": "A comprehensive headless React component library with 491 accessible, unstyled components for building design systems. Targets WCAG 2.2 AAA.",
8
8
  "main": "./dist/index.js",
@@ -13,7 +13,8 @@
13
13
  "test:ui": "vitest --ui",
14
14
  "test:watch": "vitest",
15
15
  "storybook": "storybook dev -p 6006",
16
- "build-storybook": "storybook build"
16
+ "build-storybook": "storybook build",
17
+ "check": "tsc --noEmit"
17
18
  },
18
19
  "repository": {
19
20
  "type": "git",
@@ -39,7 +40,7 @@
39
40
  },
40
41
  "homepage": "https://lilydesignsystem.com/",
41
42
  "devDependencies": {
42
- "@storybook/react-vite": "^10.6.2",
43
+ "@storybook/react-vite": "^10.6.5",
43
44
  "@testing-library/react": "^16.3.3",
44
45
  "@testing-library/user-event": "^14.6.8",
45
46
  "@types/react": "^19.3.0",
@@ -49,7 +50,7 @@
49
50
  "jsdom": "^30.1.3",
50
51
  "react": "^19.3.1",
51
52
  "react-dom": "^19.3.1",
52
- "storybook": "^10.6.2",
53
+ "storybook": "^10.6.5",
53
54
  "tsup": "^9.0.0",
54
55
  "typescript": "^5.9.3",
55
56
  "vitest": "^5.0.5"