@tenphi/eslint-plugin-tasty 1.18.0 → 1.19.0

package/docs/rules/no-style-spread.md

@@ -0,0 +1,53 @@
+# tasty/no-style-spread
+
+Reports object and array spreads inside runtime Tasty style objects, and recommends `mergeStyles(...)` when a style object is built from two or more spreads.
+
+**Presets:** warning in recommended and strict. **Fix:** none.
+
+## Why
+
+A spread hides which properties a style object defines and makes overrides hard to review. Object spread is also shallow: spreading `Label: { fill: '#accent' }` over `Label: { padding: '2x', fill: '#surface' }` loses `padding`. `mergeStyles` merges sub-elements and state maps the way Tasty does.
+
+## Examples
+
+```js
+// ❌ Use mergeStyles(...) to compose Tasty style objects.
+const finalStyles: Styles = { ...outerStyles, ...styles };
+
+// ✅ Tasty's merge, in the same override order
+const mergedStyles: Styles = mergeStyles(outerStyles, styles);
+
+// ❌ List Tasty style properties explicitly instead of spreading.
+const Card = tasty({
+  styles: {
+    ...sharedStyles,
+    fill: { '': '#surface', active: '#primary' },
+  },
+});
+```
+
+## What is reported
+
+- **Two or more spreads at the root of a style object** get one `mergeStyles` warning, at the first spread. This includes typed and shared objects such as `const finalStyles: Styles = { ...outerStyles, ...styles }`, call-site styles, variants, JSX and Storybook styles, and configured helpers.
+- **Every other spread** in a runtime style object, including state maps and sub-elements, gets a plain warning.
+
+There is no autofix: `mergeStyles` changes override behavior. A state map without `''` extends the inherited entries, while a map with `''` replaces them.
+
+`tastyStatic()` spreads stay errors under [`tasty/static-no-dynamic-values`](static-no-dynamic-values.md): the extractor rejects them, and a disable comment does not make them valid. To fail CI on warnings that nobody suppressed, run ESLint with `--max-warnings=0`.
+
+## Exceptions
+
+An intentional spread takes a disable comment on its line, with a reason:
+
+```js
+const Card = tasty({
+  styles: {
+    // eslint-disable-next-line tasty/no-style-spread -- generated defaults are shared by all cards
+    ...sharedStyles,
+  },
+});
+```
+
+## Options
+
+None.

package/docs/rules/no-styles-prop.md

@@ -0,0 +1,57 @@
+# tasty/no-styles-prop
+
+Warn about instance `styles` props on recognized Tasty components.
+
+**Presets:** warning in recommended and strict. **Fix:** none.
+
+Choose the replacement according to the override:
+
+- Dynamic values: declare token references and pass `tokens`.
+- State changes: define state maps and pass `mods` or exposed modifier props.
+- Supported customization: use exposed style props or variants.
+- Structural or reusable overrides: create a `tasty(Component, { styles })` wrapper.
+
+```tsx
+import { tasty } from '@tenphi/tasty';
+
+const Box = tasty({ styles: { padding: '1x' } });
+
+// ❌ Prefer a named, reusable extension.
+<Box styles={{ padding: '2x' }} />;
+
+// ✅ Preferred.
+const RoomyBox = tasty(Box, { styles: { padding: '2x' } });
+<RoomyBox />;
+```
+
+Variables, function results, conditional values, TypeScript wrappers, null, and
+visible `styles` keys in inline JSX object spreads are checked too. The rule is
+report-only: choosing a token, state, variant, or wrapper requires the component's
+contract.
+
+An edge case may need an instance style object, for example an adapter that must
+pass through externally supplied overrides. Keep the override and acknowledge
+the exception with an explicit local ignore and a reason:
+
+```tsx
+const adapted = (
+  // eslint-disable-next-line tasty/no-styles-prop -- legacy adapter requires instance overrides
+  <Box styles={adapterOverrides} />
+);
+```
+
+Place the directive immediately before the reported attribute line. It suppresses
+only this rule for that line. The warning message includes this exception path;
+the plugin does not silently exempt edge cases or enforce comment reasons.
+
+Recognition uses local `const` Tasty/configured-options factory results, their
+`const` aliases/sub-elements, and imports from `importSources`. Exports of relative modules (`import { Panel } from './styled'`) count when they
+resolve to one of these, through re-exports too; following them needs the
+`typescript` package. Native elements,
+unrelated components, type-only imports, shadowed bindings, mutable aliases, and
+opaque spread bindings are excluded. Factory definition options (`tasty({ styles })`
+or `tasty(Component, { styles })`) are allowed.
+
+## Options
+
+None.

package/docs/rules/no-unknown-state-alias.md

@@ -0,0 +1,45 @@
+# tasty/no-unknown-state-alias
+
+Reports an `@name` state alias that is not in your config, not defined locally and not built in, wherever it appears in a state key.
+
+**Presets:** warning in strict. **Fix:** none.
+
+## Why
+
+Tasty cannot expand an alias it does not know, so the state never applies. A typo such as `@drak` fails silently.
+
+## Examples
+
+```js
+// ❌ Unknown state alias '@drak'. Add it to 'states' in your tasty config, or define it locally as a '@name' key.
+padding: { '': '4x', '@drak': '2x' }
+
+// ❌ The same alias inside a compound key
+padding: { '': '4x', 'hovered & @drak': '2x' }
+
+// ✅ A local alias
+tasty({
+  styles: {
+    '@compact': 'size=small',
+    padding: { '': '4x', '@compact': '2x' },
+  },
+});
+```
+
+## Checks
+
+Compound keys are parsed, so each alias is checked wherever it appears: `'@dark | hovered'`, `'hovered & @dark'`, `'(@dark | hovered)'`, `'@root(@dark)'`.
+
+An alias is known when it is:
+
+- listed in `states` in `tasty.config.*`;
+- a local alias: an `@name: '<state>'` key of the object, or of an enclosing sub-element up to the root. A `mergeStyles(...)` argument stands for the merged object, so aliases from every object argument count, and a `mergeStyles` call used as a sub-element value also sees the styles around it;
+- built in: `@media`, `@root`, `@parent`, `@own`, `@supports`, `@starting`, and the `@(` container query syntax.
+
+Without `states` in the config and no local aliases in view, the rule does nothing.
+
+[`tasty/valid-state-key`](valid-state-key.md), in the recommended preset, reports an unknown alias too when `states` is set.
+
+## Options
+
+None.

package/docs/rules/prefer-auto-calc.md

@@ -0,0 +1,30 @@
+# tasty/prefer-auto-calc
+
+Reports `calc(...)` in a style value. Tasty adds `calc()` to a parenthesized expression by itself.
+
+**Presets:** warning in recommended and strict. **Fix:** autofix.
+
+## Why
+
+In Tasty, a parenthesized expression such as `(100% - 2x)` is auto-calc: Tasty renders it as `calc()`. Writing `calc(...)` yourself is longer and mixes two spellings for one thing.
+
+## Examples
+
+```js
+// ❌ Replace 'calc(100% - 2x)' with Tasty auto-calc '(100% - 2x)'.
+width: 'calc(100% - 2x)'
+
+// ✅ After the autofix
+width: '(100% - 2x)'
+
+// ❌ Also inside a state map
+margin: { '': '0', hovered: 'calc(1x + 2x)' }
+```
+
+## Where it applies
+
+Values in Tasty style objects, and style props of components known to be Tasty components (a local `tasty()` result or a component from your `importSources`). It skips the values of `$name` and `#name` keys, which define tokens.
+
+## Options
+
+None.

package/docs/rules/prefer-custom-property-syntax.md

@@ -0,0 +1,56 @@
+# tasty/prefer-custom-property-syntax
+
+Reports raw CSS where Tasty has a token: `var(--name)`, a `$name-color` reference, `transparent` and `currentColor`.
+
+**Presets:** warning in recommended and strict. **Fix:** autofix.
+
+## Why
+
+Tasty's token syntax is shorter and checked: [`tasty/valid-color-token`](valid-color-token.md) and [`tasty/valid-custom-property`](valid-custom-property.md) catch a misspelled `#name` or `$name`, but not a misspelled `var(--name)`.
+
+## Examples
+
+```js
+// ❌ Use Tasty token syntax '$gap' instead of 'var(--gap)'.
+padding: 'var(--gap)'
+
+// ❌ Use Tasty token syntax '#accent' instead of 'var(--accent-color)'.
+fill: 'var(--accent-color)'
+
+// ❌ Use color token '#text' instead of custom property reference '$text-color'.
+color: '$text-color'
+
+// ❌ Use the '#clear' token instead of the 'transparent' keyword.
+border: '1bw solid transparent'
+
+// ❌ Use the '#current' token instead of the 'currentColor' keyword.
+outline: 'currentColor'
+
+// ✅ After the autofix
+padding: '$gap'
+fill: '#accent'
+color: '#text'
+border: '1bw solid #clear'
+outline: '#current'
+```
+
+## Autofix
+
+| Before | After |
+| --- | --- |
+| `var(--name)` | `$name` |
+| `var(--name-color)` | `#name` |
+| `var(--name, fallback)` | `($name, fallback)` |
+| `$name-color`, `$name-color.5` | `#name`, `#name.5` |
+| `transparent` | `#clear` |
+| `currentColor` | `#current` |
+
+Every fix renders the same CSS. Tasty expands `#name` only in properties that take colors, so the rule stays quiet where a color token would not expand, such as `var(--accent-color)` in `fontSize`.
+
+## Where it applies
+
+Values in Tasty style objects, and style props of components known to be Tasty components. It skips the values of `$name` and `#name` keys, which define tokens.
+
+## Options
+
+None.

package/docs/rules/prefer-directional-shorthand.md

@@ -0,0 +1,46 @@
+# tasty/prefer-directional-shorthand
+
+Reports a four-value box, such as `margin: '0 0 1x 0'`, that sets only part of the box. Tasty's directional form, `'1x bottom'`, says the same thing.
+
+**Presets:** warning in recommended and strict. **Fix:** autofix, and an editor suggestion for `border`.
+
+## Why
+
+In a four-value box, the reader has to count positions to see which side is set. The directional form names it.
+
+## Examples
+
+```js
+// ❌ 'margin' value '0 0 1x 0' only sets part of the box. Use '1x bottom' instead.
+margin: '0 0 1x 0'
+
+// ✅ After the autofix
+margin: '1x bottom'
+
+// ❌ 'inset' value 'auto 0 0 0' only sets part of the box. Use '0 bottom dock' instead.
+inset: 'auto 0 0 0'
+
+// ✅ After the autofix
+inset: '0 bottom dock'
+
+// ❌ 'border' value '0 0 1bw 0' does not do what it looks like. Suggestion: '1bw bottom'
+border: '0 0 1bw 0'
+```
+
+## Checks
+
+The rule reads `margin`, `padding`, `inset`, `radius`, `fade` and `border` values with exactly four parts, plain or in a state map. A part is a placeholder when it is `0` (or `auto` for `inset`).
+
+| Four-value box | Directional form |
+| --- | --- |
+| One real value, such as `'0 0 0 2x'` | `'2x left'` |
+| `radius` with one real corner, such as `'0 1r 0 0'` | `'1r top-right'` |
+| `inset` with three equal values and one `auto`, such as `'0 0 0 auto'` | `'0 right dock'` |
+
+The value is always carried into the fix, never replaced by the property default: `margin` defaults to `var(--gap)`, not `1x`, so `'0 0 1x 0'` must not become `'bottom'`.
+
+For `border`, Tasty reads four parts as one border value, so `'0 0 1bw 0'` draws no border at all today. The directional form is what the author meant, but it changes what renders, so it is an editor suggestion, not an autofix.
+
+## Options
+
+None.

package/docs/rules/prefer-element-selector.md

@@ -0,0 +1,77 @@
+# tasty/prefer-element-selector
+
+Prefer Tasty element names over explicit `data-element` attributes in sub-element
+`$` selectors. The autofix applies when the shorter form preserves the generated selector.
+
+**Presets:** warning in recommended and strict. **Fix:** autofix.
+
+```js
+// ❌ Before
+const Component = tasty({
+  styles: {
+    Search: {
+      $: '[data-element="Primary"] > [data-element="Search"]',
+      display: 'block',
+    },
+  },
+});
+
+// ✅ After autofix
+const Component = tasty({
+  styles: {
+    Search: {
+      $: 'Primary > Search',
+      display: 'block',
+    },
+  },
+});
+```
+
+The rule reports one warning per eligible `$` value and shortens all safe
+attributes in that value. It accepts exact, unnamespaced `data-element` equality
+selectors whose names match `[A-Z][a-zA-Z0-9]*`, including single-quoted,
+double-quoted and unquoted CSS values. Child and sibling combinators, selector
+lists and explicit `&` prefixes are supported.
+
+## Preserving the target
+
+Tasty can append the owning sub-element after a different trailing element name.
+For example, in an `Other` sub-element, the rule fixes:
+
+```js
+Other: {
+  // Before: '[data-element="Primary"] > [data-element="Search"]'
+  $: 'Primary > [data-element="Search"]',
+}
+```
+
+The final attribute remains explicit because `$: 'Primary > Search'` in that
+scope would select `Search`'s `Other` descendants instead of `Search` itself.
+
+Element names also insert a separator. Attributes inside compounds, including
+whitespace that the affix renderer ignores, remain explicit. For example,
+`'[data-element="Primary"][data-element="Search"]'` becomes
+`'Primary[data-element="Search"]'`, preserving the same-element requirement.
+
+## Scope and limits
+
+This rule checks literal sub-element `$` values and templates without
+interpolation. It supports the plugin's existing Tasty style contexts, including
+typed/shared styles, JSX/Storybook styles, nested sub-elements and configured
+`styleFunctions`. TypeScript wrappers and statically computed keys are supported.
+Root `$` values, global selector arguments and unrelated objects are outside its
+scope.
+
+Attributes with CSS comparison flags, namespaces, non-equality operators or
+unsupported names remain explicit. Branches containing pseudo selectors or
+other unsupported syntax are left alone. Selectors containing comments or CSS
+escapes are also left alone. These are conservative rewrite limits, not syntax
+errors. Existing state-selector rules still apply independently.
+
+If the JavaScript source uses escapes (for example, escaped quotes), the warning
+can still appear, but no autofix is offered: source offsets may differ from the
+string's actual value.
+
+## Options
+
+None.

package/docs/rules/prefer-fill-mix.md

@@ -0,0 +1,119 @@
+# tasty/prefer-fill-mix
+
+Replace deprecated two-color fills with compound colors, and catch mix parts
+that are weighted by their opacity.
+
+**Presets:** warning in recommended and strict. **Fix:** autofix and editor suggestions.
+
+Tasty 3.16 layers color tokens with `+`: `'#surface+#dark.04'` paints `#dark` at
+4% over `#surface` as one color,
+`color-mix(in srgb, var(--dark-color) 4%, var(--surface-color))`, in any color
+slot. It replaces both older ways to put two colors in a `fill` (or
+`backgroundColor`):
+
+- `'#surface #dark.04'` paints the second color as a `background-image` layer,
+  which contrast checkers such as axe-core cannot see through. Deprecated in
+  Tasty 3.15.
+- `'#dark 4%, #surface'` mixes the colors as the arguments of `color-mix()`. It
+  is the same color as the compound, but only in `fill`. Deprecated in Tasty
+  3.17.
+
+```js
+// ❌ Before
+const Item = tasty({
+  styles: {
+    fill: {
+      '': '#surface #clear',
+      hovered: '#surface #dark.04',
+      pressed: '#dark 8%, #surface',
+    },
+  },
+});
+
+// ✅ After autofix
+const Item = tasty({
+  styles: {
+    fill: {
+      '': '#surface',
+      hovered: '#surface+#dark.04',
+      pressed: '#surface+#dark.08',
+    },
+  },
+});
+```
+
+The rule's name predates compound colors: it covers every two-color fill.
+
+## Autofixes
+
+| Before | After |
+|--------|-------|
+| `'#base #tok.N'` | `'#base+#tok.N'` |
+| `'#base #clear'`, `'#base #tok.0'` | `'#base'` |
+| `'#tok N%, #base'`, `'#base, #tok N%'` | `'#base+#tok.N'` |
+| `'#tok ($prop * 100%), #base'` | `'#base+#tok.$prop'` |
+| `'#tok 0%, #base'` / `'#tok 100%, #base'` | `'#base'` / `'#tok'` |
+| any other two-color mix | `'color-mix(in srgb, <the same parts>)'` |
+
+`#base` can be faded, or a compound itself: `'#accent 10%, #surface+#dark.04'`
+becomes `'#surface+#dark.04+#accent.1'`. A weight becomes the opacity the way
+Tasty reads it, as a decimal fraction: `4%` is `.04`, `4.5%` is `.045`, `30%` is
+`.3`. A base a compound cannot take, such as `rgb(…)`, is mixed in `color-mix()`
+itself.
+
+Every comma-mix fix is the same color as the mix: a compound compiles to the
+same `color-mix()`. That includes a weight from a custom property, such as
+`'#tok $weight, #base'`, which becomes
+`'color-mix(in srgb, #tok $weight, #base)'`: a compound's `$prop` opacity has to
+hold a number (`.04`), not a percentage (`4%`), so to use one, change what the
+property holds and write `'#base+#tok.$alpha'`. A weighted `#clear` stays a
+`color-mix()` too: a compound leaves a transparent layer out, while the mix lets
+it thin out the other color.
+
+A space-separated fix renders the same color as the layer when the overlay token
+holds an opaque color. Drawing an opaque color at alpha `a` over the base is the
+compound, also when the base is translucent. If `#tok` itself holds a
+translucent color, the compound differs from the layer; give such a token an
+opaque color and put its alpha in the suffix.
+
+## Reported without a fix
+
+When the overlay's alpha is not written on it, the rule cannot tell what the
+layer painted, so it only reports:
+
+- an overlay token with no opacity, such as `'#surface #primary-accent-surface'`.
+  If the token is opaque, it covered the base completely: use it alone. If it
+  holds a translucent color, split it into an opaque color and an opacity:
+  `'#base+#overlay.$overlay-alpha'`.
+- a literal overlay such as `rgb(0 0 0 / .1)`;
+- three or more space-separated colors.
+
+A comma mix of three or more colors is reported too: Tasty mixes only the first
+two.
+
+## Translucent mix parts
+
+When neither part of a comma mix has a percentage, each takes half, so a part
+with an opacity is weighed down twice, by its share of the mix and by its own
+alpha, and the background comes out see-through: `'#dark.04, #surface'` is 52%
+opaque, not `#dark` at 4% over `#surface`. The rule reports it with an editor
+suggestion, `'#surface+#dark.04'` (or the other color alone for `#clear`). It is
+not an autofix, because the rewrite changes what renders. Opposite a part with a
+percentage, a faded part is the base the other is painted over, and the mix is
+exact: `'#dark 4%, #surface.5'` is fixed to `'#surface.5+#dark.04'`.
+
+## Tasty version
+
+The rule does nothing unless the project has `@tenphi/tasty` 3.15.0 or later
+installed: an older Tasty renders only the first color of a two-color fill, so a
+fix would break it.
+
+With Tasty 3.15, which has no compound colors, the rule fixes the
+space-separated form to a comma mix (`'#base #tok.N'` to `'#tok N%, #base'`),
+leaves comma mixes alone, and suggests a weight for a translucent part
+(`'#dark 4%, #surface'`). Once the project is on 3.16, the next run fixes those
+comma mixes to compound colors.
+
+## Options
+
+None.

package/docs/rules/prefer-hide.md

@@ -0,0 +1,31 @@
+# tasty/prefer-hide
+
+Reports `display: 'none'`. Use `hide: true` instead.
+
+**Presets:** warning in recommended and strict. **Fix:** autofix for a plain value; a value in a state map is reported only.
+
+## Why
+
+Tasty resolves `display` together with `hide`, `textOverflow`, `overflow` and `whiteSpace`, and `hide` has the highest priority. `hide: true` hides the element whatever `display` a state, a recipe or an extension sets. `display: 'none'` is one more `display` value that another one can override.
+
+## Examples
+
+```js
+// ❌ Use 'hide: true' instead of "display: 'none'".
+tasty({ styles: { display: 'none' } });
+
+// ✅ After the autofix
+tasty({ styles: { hide: true } });
+
+// ❌ Reported in a state map, without a fix
+tasty({ styles: { display: { '': 'flex', collapsed: 'none' } } });
+
+// ✅ By hand
+tasty({ styles: { display: 'flex', hide: { '': false, collapsed: true } } });
+```
+
+A `'none'` inside a state map has no autofix, because moving it to `hide` changes the shape of both maps.
+
+## Options
+
+None.

package/docs/rules/prefer-longhand-property.md

@@ -0,0 +1,25 @@
+# tasty/prefer-longhand-property
+
+Reports the `flex` shorthand. Use `flexGrow`, `flexShrink` and `flexBasis` instead.
+
+**Presets:** error in recommended and strict. **Fix:** none.
+
+## Why
+
+`flex` resets the parts you leave out to values that are not their initial ones: `flex: 1` sets `flex-basis` to `0%`, not `auto`. The longhands set only what you write, which also lets a state or an extension change one part without touching the others.
+
+## Examples
+
+```js
+// ❌ 'flex' resets the components you omit to non-initial values. Use flexGrow / flexShrink / flexBasis instead.
+flex: '1'
+
+// ✅ Only what you mean
+flexGrow: 1
+```
+
+There is no autofix: splitting the shorthand needs to know which parts you meant to set.
+
+## Options
+
+None.