@oprt/tailwind 0.0.0-stage → 0.5.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/LICENSE +21 -0
- package/README.md +185 -2
- package/dist/index.cjs +552 -0
- package/dist/index.d.cts +14 -0
- package/dist/index.d.ts +12 -0
- package/dist/index.js +518 -0
- package/package.json +49 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 OPERATOR contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,186 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @oprt/tailwind
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The OPERATOR plugin for Tailwind CSS 4. It turns the custom properties from
|
|
4
|
+
[`@oprt/tokens`](https://www.npmjs.com/package/@oprt/tokens) into utilities, so a token change reaches every composed
|
|
5
|
+
component. Colors, spacing, control sizes, type, tracking, motion, focus, the container
|
|
6
|
+
variants and the wrap utility are all resolved through `var(--oprt-*)`.
|
|
7
|
+
|
|
8
|
+
It needs Tailwind CSS 4.3.3 or a later 4.x release (`tailwindcss` `>=4.3.3 <5`), the versions it is
|
|
9
|
+
tested with. Tailwind CSS 3 is not supported.
|
|
10
|
+
|
|
11
|
+
## Setup
|
|
12
|
+
|
|
13
|
+
Install both. The plugin emits only `var(--oprt-*)` references, and `@oprt/tokens` is what
|
|
14
|
+
defines them, so without it every OPERATOR declaration is invalid.
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
pnpm add @oprt/tokens
|
|
18
|
+
pnpm add -D @oprt/tailwind tailwindcss@^4.3.3
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
`@oprt/tokens` is not a peer dependency of this package, so your package manager will not
|
|
22
|
+
warn when it is missing or out of step. The `@oprt` packages are released together at one
|
|
23
|
+
version, and a peer range on a sibling would force a major bump of all of them. Keep the two on the
|
|
24
|
+
same release.
|
|
25
|
+
|
|
26
|
+
Add the plugin to the stylesheet where Tailwind is imported, and point Tailwind at the components:
|
|
27
|
+
|
|
28
|
+
```css
|
|
29
|
+
@import "tailwindcss";
|
|
30
|
+
@plugin "@oprt/tailwind";
|
|
31
|
+
/* The components ship as compiled JavaScript, and Tailwind does not look inside node_modules on
|
|
32
|
+
its own. Point it at them (the path is relative to this stylesheet), or they render unstyled. */
|
|
33
|
+
@source "../node_modules/@oprt/react/dist";
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Import the tokens once at the application root, before that stylesheet (`import "@oprt/tokens";`),
|
|
37
|
+
or with a `<link>`. Not with an `@import` in the Tailwind stylesheet: the Tailwind CLI inlines an
|
|
38
|
+
imported file without rewriting its font URLs, so the bundled fonts would not load.
|
|
39
|
+
|
|
40
|
+
A JavaScript config loaded with `@config` works too (`plugins: [operator]`). From CommonJS,
|
|
41
|
+
`require("@oprt/tailwind")` returns the plugin itself, and `.default` remains as an alias.
|
|
42
|
+
|
|
43
|
+
The plugin also sets two defaults that Tailwind 4 dropped and the components rely on: a border
|
|
44
|
+
with no color class of its own takes `--oprt-border`, not the text color, and a button that can be
|
|
45
|
+
pressed shows the pointer cursor.
|
|
46
|
+
|
|
47
|
+
## Utilities
|
|
48
|
+
|
|
49
|
+
Every scale is a theme key, so each works with the Tailwind prefixes that read it. For example, a
|
|
50
|
+
color key works in `bg-`, `text-`, `border-`, `ring-`, `fill-` and `stroke-` classes.
|
|
51
|
+
|
|
52
|
+
### Colors: `bg-oprt-<key>`, `text-oprt-<key>`, `border-oprt-<key>` ...
|
|
53
|
+
|
|
54
|
+
| Role | Keys |
|
|
55
|
+
| -------- | ------------------------------------------------------------------------------------------------------- |
|
|
56
|
+
| Surfaces | `bg`, `surface-1`, `surface-2`, `surface-3`, `surface-4`, `surface-5`, `surface-6` |
|
|
57
|
+
| Borders | `border-subtle`, `border`, `border-strong`, `border-control`, `border-focus` |
|
|
58
|
+
| Text | `text`, `text-dim`, `text-placeholder`, `text-muted` |
|
|
59
|
+
| Accent | `accent`, `accent-light`, `accent-hover`, `accent-active`, `accent-ghost`, `accent-bg`, `accent-border` |
|
|
60
|
+
| Success | `success`, `success-subtle`, `success-strong` |
|
|
61
|
+
| Warning | `warning`, `warning-subtle`, `warning-strong` |
|
|
62
|
+
| Error | `error`, `error-subtle`, `error-strong` |
|
|
63
|
+
| Info | `info`, `info-subtle`, `info-strong` |
|
|
64
|
+
| Series | `cat-1`, `cat-2`, `cat-3`, `cat-4`, `cat-5`, `cat-6`, `cat-7`, `cat-8` |
|
|
65
|
+
| Sequence | `data-seq-1`, `data-seq-2`, `data-seq-3`, `data-seq-4`, `data-seq-5` |
|
|
66
|
+
| Chart | `chart-grid`, `chart-axis`, `chart-threshold` |
|
|
67
|
+
| States | `surface-hover`, `surface-active`, `surface-selected`, `overlay-scrim` |
|
|
68
|
+
|
|
69
|
+
`border-oprt-border` and its siblings draw layout lines: tables, tabs, cards, dividers, panels.
|
|
70
|
+
The boundary of anything you click or type into (text fields, selects, checkboxes, radios,
|
|
71
|
+
toggles, segmented and disabled buttons) is `border-oprt-border-control`, which keeps 3:1 against
|
|
72
|
+
the surface it sits on.
|
|
73
|
+
|
|
74
|
+
Opacity modifiers work (`bg-oprt-bg/80`, `border-oprt-error/40`, `bg-oprt-info/[.35]`). Tailwind
|
|
75
|
+
mixes the token toward transparent with `color-mix()`, so it keeps its hue and only its alpha
|
|
76
|
+
falls. A bare `border` takes `--oprt-border`, not the text color.
|
|
77
|
+
|
|
78
|
+
### Spacing: `p-2u`, `gap-1u`, `-mt-0.5u` ...
|
|
79
|
+
|
|
80
|
+
`1u` is 8px. Keys: `0.5u`, `1u`, `1.5u`, `2u`, `2.5u`, `3u`, `4u`, `5u`, `6u`, `8u`, `12u`, `16u`
|
|
81
|
+
and `40u`. The table-cell insets are `oprt-cell-inline`, `oprt-cell-block` and
|
|
82
|
+
`oprt-cell-block-dense`. There is no `7u`.
|
|
83
|
+
|
|
84
|
+
### Control sizes: `h-`, `w-`, `min-h-`, `min-w-`, `max-h-`, `max-w-` + `oprt-<key>`
|
|
85
|
+
|
|
86
|
+
Keys: `oprt-sm`, `oprt-md` and `oprt-lg` (24, 32 and 40px controls); `oprt-badge-sm` and
|
|
87
|
+
`oprt-badge-md`; `oprt-row` and `oprt-row-dense` (table rows); `oprt-track-sm`, `oprt-track-md`
|
|
88
|
+
and `oprt-track-lg` (slider rails). Use `min-h-oprt-sm` for a target floor on content that may
|
|
89
|
+
grow.
|
|
90
|
+
|
|
91
|
+
### Type: `text-<key>` and `tracking-<key>`
|
|
92
|
+
|
|
93
|
+
| Utility | Keys | Sets |
|
|
94
|
+
| ---------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------- |
|
|
95
|
+
| `text-<key>` | `oprt-xs`, `oprt-sm`, `oprt-base`, `oprt-md`, `oprt-lg`, `oprt-xl`, `oprt-2xl` | Size, line height, tracking and weight of the step |
|
|
96
|
+
| `tracking-<key>` | The same keys, plus `oprt-caps` (11px uppercase controls) and `oprt-caps-lg` (13px) | Letter spacing |
|
|
97
|
+
| `font-<key>` | `sans`, `mono` | `--oprt-font-sans`, `--oprt-font-mono` |
|
|
98
|
+
|
|
99
|
+
`text-oprt-*` never chooses letter case. Add `uppercase` or `normal-case`. The weight comes from
|
|
100
|
+
`--oprt-weight-*`, and `text-oprt-base` is 400: add `font-medium` where an actionable label
|
|
101
|
+
needs 500.
|
|
102
|
+
|
|
103
|
+
### Radius, shadow and wrapping
|
|
104
|
+
|
|
105
|
+
- Every `rounded-*` class, including `rounded-full`, resolves to `0px`.
|
|
106
|
+
- `shadow-oprt-focus` is the 1px focus ring in `--oprt-border-focus`.
|
|
107
|
+
- `oprt-wrap-anywhere` sets `overflow-wrap: anywhere`. Unlike `break-words` it also shrinks
|
|
108
|
+
min-content, so a long ID wraps inside a flex or grid item instead of widening it.
|
|
109
|
+
|
|
110
|
+
### Motion
|
|
111
|
+
|
|
112
|
+
`duration-oprt-instant`, `duration-oprt-fast`, `duration-oprt-normal`, `duration-oprt-slow` and
|
|
113
|
+
`ease-oprt` follow the duration tokens, so they become zero under `prefers-reduced-motion`. The
|
|
114
|
+
component recipes, which also honor `data-oprt-motion="none"`, are `oprt-motion`,
|
|
115
|
+
`oprt-motion-press`, `oprt-motion-track`, `oprt-motion-thumb`, `oprt-motion-check`,
|
|
116
|
+
`oprt-motion-tabs`, `oprt-motion-indicator`, `oprt-motion-panel`, `oprt-motion-chevron`,
|
|
117
|
+
`oprt-motion-popover-chevron`, `oprt-motion-overlay`, `oprt-motion-surface` and
|
|
118
|
+
`oprt-motion-popover`.
|
|
119
|
+
|
|
120
|
+
### The cut
|
|
121
|
+
|
|
122
|
+
`oprt-cut` is the chamfered corner a Button carries. It draws the control's fill and edge in a
|
|
123
|
+
layer behind its content (`::before`), clipped to the cut shape, so the element itself is never
|
|
124
|
+
clipped: its focus ring, hit area and size are those of the plain rectangle.
|
|
125
|
+
|
|
126
|
+
- The component sets what the layer draws: `--oprt-cut-fill` and `--oprt-cut-edge`, per variant
|
|
127
|
+
and state. The element keeps a transparent 1px border.
|
|
128
|
+
- `oprt-cut-sm`, `oprt-cut-md` and `oprt-cut-lg` set the depth: 40% of the matching control height,
|
|
129
|
+
in whole pixels (10, 13 and 16 px).
|
|
130
|
+
- `oprt-cut-standing` cuts the top-right corner at rest. Without it the control is square at rest.
|
|
131
|
+
- On hover, press and keyboard focus both the top-right and the bottom-left corner are cut. An
|
|
132
|
+
unavailable control (`:disabled` or `aria-disabled="true"`) is left alone, and hover counts only
|
|
133
|
+
where a pointer can hover. With `oprt-motion-press` on the same element the cut animates with the
|
|
134
|
+
press.
|
|
135
|
+
- `oprt-cut-hazard` fills the control with red stripes, parallel to the cut, while it is armed
|
|
136
|
+
(hovered, focused from the keyboard, pressed). The stripes are 10% red, so a red label reads on
|
|
137
|
+
them as well as it did on the flat tint they replace.
|
|
138
|
+
- `oprt-cut-none` squares off a control, or every control inside the element that carries it, as
|
|
139
|
+
an attached ButtonGroup does for its segments. It sets `--oprt-cut`, which overrides the depth
|
|
140
|
+
the size would give; another length there gives another depth.
|
|
141
|
+
- In forced colors the layer is not drawn, and the element's own border is the boundary.
|
|
142
|
+
- The cut animates through two registered custom properties and is rounded with `round()`. A
|
|
143
|
+
browser without registered properties shows the same shape without the animation, and one
|
|
144
|
+
without `round()` cuts the plain 40% (9.6 and 12.8 px for the two smaller sizes).
|
|
145
|
+
|
|
146
|
+
`oprt-motion-slide` is a loop, for a pattern that shows work in progress (Progress's unknown
|
|
147
|
+
amount). It moves the element one repeat of its pattern to the right, evenly, and starts again;
|
|
148
|
+
the last frame matches the first, so the movement never jumps. The repeat is `--oprt-slide-distance`,
|
|
149
|
+
by default one repeat of the OPERATOR hatch along a bar (stripes every `--oprt-space-1` at 135
|
|
150
|
+
degrees), and `oprt-motion-slide-[10%]` gives another. The element rests one repeat to the left of
|
|
151
|
+
the area it covers, inside a parent that clips, so the spare repeat hangs off the start and adds
|
|
152
|
+
nothing to scroll. It stays still under `prefers-reduced-motion`, in forced colors and inside
|
|
153
|
+
`data-oprt-motion="none"`, and its keyframes are emitted only where it is used.
|
|
154
|
+
|
|
155
|
+
### Variants
|
|
156
|
+
|
|
157
|
+
| Variant | Applies |
|
|
158
|
+
| ------------------------------------- | ----------------------------------------------------------------------------- |
|
|
159
|
+
| `theme-bone:` | Inside `[data-theme="bone"]` |
|
|
160
|
+
| `@oprt-sm:`, `@oprt-md:`, `@oprt-lg:` | From a container width of 320, 480 and 640px, set by the nearest `@container` |
|
|
161
|
+
|
|
162
|
+
## Container-relative layout
|
|
163
|
+
|
|
164
|
+
A component lays itself out from its own width, not the window's. Mark the box that should be
|
|
165
|
+
measured with `@container`, then style its **descendants** with the `@oprt-*` variants:
|
|
166
|
+
|
|
167
|
+
```tsx
|
|
168
|
+
<div className="@container">
|
|
169
|
+
<div className="flex flex-col gap-2u @oprt-lg:flex-row">...</div>
|
|
170
|
+
</div>
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
- A container query styles descendants only. Put `@oprt-lg:` on the same element as `@container`
|
|
174
|
+
and it queries that element's parent, if any.
|
|
175
|
+
- `@container` sets `container-type: inline-size`, so the box no longer sizes to its content.
|
|
176
|
+
Apply it to a block-level wrapper that has a width of its own, not to a shrink-wrapped item.
|
|
177
|
+
- The variants are emitted narrowest first, so `@oprt-md:` overrides `@oprt-sm:` when both match.
|
|
178
|
+
- `@oprt-lg` (640px of container) is the closest equivalent of Tailwind's viewport `sm:`.
|
|
179
|
+
|
|
180
|
+
## Keeping the plugin and the tokens in step
|
|
181
|
+
|
|
182
|
+
`src/parity.test.ts` ties the type, tracking, color, spacing and duration scales to the token
|
|
183
|
+
CSS, requires every `var(--oprt-*)` the plugin references to be defined, and
|
|
184
|
+
`src/react-usage.test.ts` compiles every OPERATOR class used in `@oprt/react` and requires
|
|
185
|
+
a rule for each. Tailwind drops an unknown utility without a warning, so these are the only
|
|
186
|
+
guard against a dead class.
|