@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 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
- # Temporary Holding Version
1
+ # @oprt/tailwind
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.