tintora 0.27.0 → 1.0.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 +151 -59
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,36 +1,42 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
<h1 align="center">
|
|
2
|
+
<picture>
|
|
3
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg" />
|
|
4
|
+
<img src="docs/assets/logo-light.svg" alt="Tintora" height="72" />
|
|
5
|
+
</picture>
|
|
6
|
+
</h1>
|
|
7
|
+
|
|
8
|
+
<p align="center">
|
|
9
|
+
A lightweight React component library with a glassy, dark-first style.<br />
|
|
10
|
+
Small API surface, accessible by default, TypeScript included.
|
|
11
|
+
</p>
|
|
12
|
+
|
|
13
|
+
<p align="center">
|
|
14
|
+
<a href="https://www.npmjs.com/package/tintora"><img alt="npm version" src="https://img.shields.io/npm/v/tintora?color=c94e0c&labelColor=2a2726" /></a>
|
|
15
|
+
<a href="https://github.com/felipevlourenco/tintora/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/felipevlourenco/tintora/ci.yml?branch=main&label=CI&labelColor=2a2726" /></a>
|
|
16
|
+
<a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/npm/l/tintora?color=c94e0c&labelColor=2a2726" /></a>
|
|
17
|
+
<a href="https://felipevlourenco.github.io/tintora/"><img alt="Storybook" src="https://img.shields.io/badge/Storybook-live-c94e0c?labelColor=2a2726" /></a>
|
|
18
|
+
</p>
|
|
4
19
|
|
|
5
20
|
**[Live Storybook →](https://felipevlourenco.github.io/tintora/)**
|
|
6
21
|
|
|
7
22
|
## Features
|
|
8
23
|
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
24
|
+
- **25+ components**: buttons, form controls, feedback and overlays.
|
|
25
|
+
- **Accessible by default**: real roles and labels, keyboard support, focus handling, reduced motion respected, covered by axe checks in the tests.
|
|
26
|
+
- **Dark and light themes** from one set of design tokens, following the OS or forced with an attribute.
|
|
27
|
+
- **TypeScript-first**: every component exports its props type.
|
|
28
|
+
- **Native platform features** where they exist: `<dialog>` for modals and drawers, the top layer for popovers, CSS for animation.
|
|
29
|
+
- **Self-contained styles**: the ESM build imports its own CSS.
|
|
14
30
|
|
|
15
31
|
## Installation
|
|
16
32
|
|
|
17
|
-
Using pnpm:
|
|
18
|
-
|
|
19
33
|
```bash
|
|
20
34
|
pnpm add tintora
|
|
35
|
+
# or: npm install tintora
|
|
36
|
+
# or: yarn add tintora
|
|
21
37
|
```
|
|
22
38
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
```bash
|
|
26
|
-
npm install tintora
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
Using yarn:
|
|
30
|
-
|
|
31
|
-
```bash
|
|
32
|
-
yarn add tintora
|
|
33
|
-
```
|
|
39
|
+
Requires React 18 or newer.
|
|
34
40
|
|
|
35
41
|
## Usage
|
|
36
42
|
|
|
@@ -39,7 +45,9 @@ import { Button } from 'tintora';
|
|
|
39
45
|
|
|
40
46
|
export function Example() {
|
|
41
47
|
return (
|
|
42
|
-
<Button onClick={() => alert('Hello from Tintora!')}>
|
|
48
|
+
<Button variant="primary" onClick={() => alert('Hello from Tintora!')}>
|
|
49
|
+
Click me
|
|
50
|
+
</Button>
|
|
43
51
|
);
|
|
44
52
|
}
|
|
45
53
|
```
|
|
@@ -50,64 +58,148 @@ The ESM build imports its own stylesheet, so a bundler with CSS support (Vite, N
|
|
|
50
58
|
import 'tintora/style.css';
|
|
51
59
|
```
|
|
52
60
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
### Button
|
|
61
|
+
### Theming
|
|
56
62
|
|
|
57
|
-
|
|
63
|
+
Tintora is dark by default and follows the OS preference. Force a theme with `data-theme` on `<html>` or on any wrapper:
|
|
58
64
|
|
|
59
|
-
```
|
|
60
|
-
<
|
|
61
|
-
Submit
|
|
62
|
-
</Button>
|
|
65
|
+
```html
|
|
66
|
+
<html data-theme="light"></html>
|
|
63
67
|
```
|
|
64
68
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
Install dependencies:
|
|
69
|
+
Colours, radii, type and shadows are CSS custom properties prefixed `--tintora-`, so you can override them in your own CSS.
|
|
68
70
|
|
|
69
|
-
|
|
70
|
-
pnpm install
|
|
71
|
-
```
|
|
71
|
+
### Controlled overlays
|
|
72
72
|
|
|
73
|
-
|
|
73
|
+
Modal, Drawer, BottomSheet and Popover are controlled: your state owns `open`.
|
|
74
74
|
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
|
|
75
|
+
```tsx
|
|
76
|
+
import { useState } from 'react';
|
|
77
|
+
import { Button, Modal } from 'tintora';
|
|
78
78
|
|
|
79
|
-
|
|
79
|
+
export function DeleteWorkout() {
|
|
80
|
+
const [open, setOpen] = useState(false);
|
|
80
81
|
|
|
81
|
-
|
|
82
|
-
|
|
82
|
+
return (
|
|
83
|
+
<>
|
|
84
|
+
<Button variant="secondary" onClick={() => setOpen(true)}>
|
|
85
|
+
Delete
|
|
86
|
+
</Button>
|
|
87
|
+
<Modal
|
|
88
|
+
open={open}
|
|
89
|
+
onClose={() => setOpen(false)}
|
|
90
|
+
title="Delete this workout?"
|
|
91
|
+
description="This cannot be undone."
|
|
92
|
+
actions={
|
|
93
|
+
<>
|
|
94
|
+
<Button variant="ghost" onClick={() => setOpen(false)}>
|
|
95
|
+
Cancel
|
|
96
|
+
</Button>
|
|
97
|
+
<Button variant="primary">Delete</Button>
|
|
98
|
+
</>
|
|
99
|
+
}
|
|
100
|
+
/>
|
|
101
|
+
</>
|
|
102
|
+
);
|
|
103
|
+
}
|
|
83
104
|
```
|
|
84
105
|
|
|
85
|
-
|
|
106
|
+
## Components
|
|
107
|
+
|
|
108
|
+
Every component has a story with all its variants in the [Storybook](https://felipevlourenco.github.io/tintora/).
|
|
109
|
+
|
|
110
|
+
### Actions
|
|
111
|
+
|
|
112
|
+
| Component | What it is |
|
|
113
|
+
| ------------ | ------------------------------------------------------------------------------ |
|
|
114
|
+
| `Button` | `primary`, `secondary`, `outline` and `ghost`, with icons and a loading state. |
|
|
115
|
+
| `IconButton` | A round, field or nav button with an icon and a required `aria-label`. |
|
|
116
|
+
| `Chip` | A pill button, or a toggle when `selected` is set. |
|
|
117
|
+
| `Toggle` | A two-option segmented control (`ToggleItem`), such as light and dark. |
|
|
118
|
+
| `Tabs` | A tab list (`Tab`), as a segmented pill or an underline. Arrow-key navigation. |
|
|
119
|
+
|
|
120
|
+
### Forms
|
|
121
|
+
|
|
122
|
+
| Component | What it is |
|
|
123
|
+
| ------------- | -------------------------------------------------------------------- |
|
|
124
|
+
| `TextField` | A labelled input with hint and error messages. |
|
|
125
|
+
| `SearchInput` | A search field with a search icon and a required `aria-label`. |
|
|
126
|
+
| `Select` | A select with a listbox popup that can submit with a form. |
|
|
127
|
+
| `Switch` | An on/off switch. |
|
|
128
|
+
| `Checkbox` | A checkbox with an indeterminate state. |
|
|
129
|
+
| `Radio` | A radio, grouped with `RadioGroup`. |
|
|
130
|
+
| `SettingsRow` | A row for one setting: title, description and a control on the side. |
|
|
131
|
+
|
|
132
|
+
### Display
|
|
133
|
+
|
|
134
|
+
| Component | What it is |
|
|
135
|
+
| --------- | ------------------------------------------------------------------------ |
|
|
136
|
+
| `Avatar` | An image with an initials fallback. |
|
|
137
|
+
| `Card` | A surface or list-row card, and a selectable variant (`SelectableCard`). |
|
|
138
|
+
| `Tag` | A small label in `neutral`, `success`, `accent` or `card`. |
|
|
139
|
+
| `Dot` | An unread, read or section-tick marker. |
|
|
140
|
+
|
|
141
|
+
### Feedback
|
|
142
|
+
|
|
143
|
+
| Component | What it is |
|
|
144
|
+
| ------------- | --------------------------------------------------------------------- |
|
|
145
|
+
| `Alert` | An inline status message, or a full-width announcement bar. |
|
|
146
|
+
| `Toast` | A short-lived message with an action, a timer bar and pause on hover. |
|
|
147
|
+
| `ProgressBar` | Determinate or indeterminate progress. |
|
|
148
|
+
| `Spinner` | A loading indicator in three sizes. |
|
|
149
|
+
| `Skeleton` | A shimmering placeholder. |
|
|
150
|
+
|
|
151
|
+
### Overlays
|
|
152
|
+
|
|
153
|
+
| Component | What it is |
|
|
154
|
+
| ------------- | -------------------------------------------------------------------------------- |
|
|
155
|
+
| `Tooltip` | A hint on hover and focus, with an optional title and keyboard shortcut. |
|
|
156
|
+
| `Popover` | A small floating panel anchored to a trigger. Flips at the viewport edge. |
|
|
157
|
+
| `Modal` | A dialog on native `<dialog>`: focus trap, Esc, scrim click, scroll lock. |
|
|
158
|
+
| `Drawer` | A panel that slides in from any edge. A scrim click or Esc closes it. |
|
|
159
|
+
| `BottomSheet` | A `Drawer` from the bottom with a grabber, a title and `BottomSheetOption` rows. |
|
|
86
160
|
|
|
87
|
-
|
|
88
|
-
pnpm typecheck
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
Run linting:
|
|
161
|
+
## Development
|
|
92
162
|
|
|
93
163
|
```bash
|
|
94
|
-
pnpm
|
|
164
|
+
pnpm install # dependencies
|
|
165
|
+
pnpm storybook # Storybook on http://localhost:6006
|
|
166
|
+
pnpm test # unit tests (Vitest, Testing Library, axe)
|
|
167
|
+
pnpm lint # ESLint and token check
|
|
168
|
+
pnpm typecheck # TypeScript
|
|
169
|
+
pnpm build # library build in dist/
|
|
95
170
|
```
|
|
96
171
|
|
|
97
|
-
|
|
172
|
+
### Project structure
|
|
98
173
|
|
|
99
174
|
```text
|
|
100
175
|
src/
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
176
|
+
<Component>/
|
|
177
|
+
<Component>.tsx the component
|
|
178
|
+
<Component>.css its styles
|
|
179
|
+
<Component>.stories.tsx Storybook stories
|
|
180
|
+
<Component>.test.tsx tests
|
|
181
|
+
hooks/ shared hooks (outside press, escape key, ...)
|
|
182
|
+
utils/ shared helpers
|
|
183
|
+
tokens.css design tokens, dark and light
|
|
184
|
+
index.ts public exports
|
|
185
|
+
docs/ Storybook documentation pages and assets
|
|
105
186
|
```
|
|
106
187
|
|
|
107
|
-
|
|
188
|
+
### Contributing
|
|
189
|
+
|
|
190
|
+
Commits follow [Conventional Commits](https://www.conventionalcommits.org/), checked by a hook. `main` is protected, so work on a branch and open a pull request.
|
|
108
191
|
|
|
109
|
-
|
|
192
|
+
## Releases
|
|
110
193
|
|
|
111
|
-
|
|
194
|
+
Versions are published automatically on every merge to `main` with [semantic-release](https://semantic-release.gitbook.io/), from the commit messages:
|
|
195
|
+
|
|
196
|
+
| Commit | Release |
|
|
197
|
+
| --------------------------------------- | ------- |
|
|
198
|
+
| `fix:`, `perf:`, `refactor:`, `revert:` | patch |
|
|
199
|
+
| `feat:` | minor |
|
|
200
|
+
| `BREAKING CHANGE:` footer, or `feat!:` | major |
|
|
201
|
+
| `docs:`, `chore:`, `style:`, `test:` | none |
|
|
202
|
+
|
|
203
|
+
## License
|
|
112
204
|
|
|
113
|
-
|
|
205
|
+
[MIT](LICENSE)
|