@tenphi/eslint-plugin-tasty 1.17.1 → 1.19.0

package/docs/rules/no-nested-state-map.md

@@ -0,0 +1,33 @@
+# tasty/no-nested-state-map
+
+Reports a state map inside another state map.
+
+**Presets:** error in recommended and strict. **Fix:** none.
+
+## Why
+
+A state map's keys are states and its values are style values. Tasty does not read a map as a value, so the nested map renders nothing. Combine the states in one key instead.
+
+## Examples
+
+```js
+// ❌ Nested state maps are not allowed. Use combined state keys instead.
+fill: {
+  '': '#white',
+  hovered: {
+    '': '#blue',
+    pressed: '#red',
+  },
+}
+
+// ✅ Combined states
+fill: {
+  '': '#white',
+  hovered: '#blue',
+  'hovered & pressed': '#red',
+}
+```
+
+## Options
+
+None.

package/docs/rules/no-own-at-root.md

@@ -0,0 +1,57 @@
+# tasty/no-own-at-root
+
+Reports `@own(...)` in a state key of the root styles, where it is redundant.
+
+**Presets:** warning in recommended and strict. **Fix:** autofix.
+
+## Why
+
+`@own(...)` says "this state belongs to the sub-element itself, not to the root". At the root, the element is the root, so `@own(:hover)` means the same as `:hover`. Writing it there suggests a difference that does not exist.
+
+## Examples
+
+```js
+// ❌ @own() is redundant outside sub-element styles.
+tasty({
+  styles: {
+    fill: { '': '#white', '@own(:hover)': '#blue' },
+  },
+});
+
+// ✅ After the autofix
+tasty({
+  styles: {
+    fill: { '': '#white', ':hover': '#blue' },
+  },
+});
+
+// ✅ In a sub-element, @own() is the sub-element's own state
+tasty({
+  styles: {
+    Icon: {
+      fill: { '': '#white', '@own(:hover)': '#blue' },
+    },
+  },
+});
+```
+
+## Autofix
+
+The fix unwraps every `@own(...)` term of the key and keeps a term with operators inside grouped:
+
+| Before | After |
+| --- | --- |
+| `'@parent(:hover) & !@own(:hover)'` | `'@parent(:hover) & !:hover'` |
+| `'@own(pin=start \| pin=end)'` | `'pin=start \| pin=end'` |
+| `'@own(hovered \| focused) & active'` | `'(hovered \| focused) & active'` |
+
+A key with a comma inside `@own(...)` is reported without a fix.
+
+## Not reported
+
+- Sub-element styles, at any depth.
+- Shared style objects, such as a `const CELL_STYLES: Styles = { … }` that may be spread into a sub-element, where `@own(...)` matters.
+
+## Options
+
+None.

package/docs/rules/no-protected-restyle.md

@@ -0,0 +1,192 @@
+# tasty/no-protected-restyle
+
+Warn when a design system's protected components are restyled rather than
+customized through their props. It does nothing until a `tasty.config.*` lists
+`protectedComponents`.
+
+**Presets:** warning in recommended and strict. **Fix:** none.
+
+A design system built on Tasty exposes `styles` and `*Styles` props on its
+components, but for most of them the look is a contract: a consumer picks a
+`type`, `theme` or `size` rather than restyling a `Button`. This rule lets the
+design system say which components those are, and asks an override to explain
+itself.
+
+## Configuration
+
+The design system ships the list in its own `tasty.config.*`, and consumers
+inherit it through `extends`:
+
+```ts
+// @my-org/ui tasty.config.ts
+import type { TastyValidationConfig } from '@tenphi/eslint-plugin-tasty';
+
+export default {
+  importSources: ['@my-org/ui'],
+  protectedComponents: [
+    {
+      source: '@my-org/ui',
+      exclude: ['Block', 'Flex', 'Grid', 'Space', 'Text', 'Title', '*Icon'],
+      allowedStyleProps: ['position', 'dimension'],
+    },
+  ],
+} satisfies TastyValidationConfig;
+```
+
+```ts
+// the consumer's tasty.config.ts
+export default {
+  extends: '@my-org/ui',
+};
+```
+
+| Key | Meaning |
+| --- | --- |
+| `source` | The package the components are imported from. `*` matches any run of characters. |
+| `include` | Exported names or member paths to protect. Defaults to every export. |
+| `exclude` | Exported names or member paths to leave open, usually layout and typography primitives. `*` matches any run of characters, so `*Icon` covers every icon. |
+| `allowedStyleProps` | Style props that place or size the root and stay allowed. `'position'` and `'dimension'` stand for Tasty's `POSITION_STYLES` (`gridArea`, `margin`, `inset`, `zIndex`, …) and `DIMENSION_STYLES` (`width`, `height`, `flex`, …); anything else is a property name. Defaults to none. |
+
+A component matches the first entry whose `source`, `include` and `exclude` fit
+it, so a second entry for the same source can give a few components their own
+`allowedStyleProps`. Entries from an extended config come first; a config can
+add its own, or set `protectedComponents: false` to drop the inherited ones.
+
+### Sub-components
+
+A sub-component such as `<Button.Primary>` follows the entry of the export it
+hangs off, which suits one that shares its parent's contract. Some are separate
+components attached for convenience, though: `Button.Group` may be a layout
+primitive. A name with a dot in `include` or `exclude` is a member path
+(`'Button.Group'`, `'Menu.*'`), and an entry that names a component's member
+path decides for it before any entry that matches only its export:
+
+```ts
+protectedComponents: [
+  {
+    source: '@my-org/ui',
+    exclude: ['Space', 'ButtonGroup', 'Button.Group'],
+    allowedStyleProps: ['position', 'dimension'],
+  },
+  // `Button.Split` gets its own allowance; `Button` and `Button.Primary` don't.
+  { source: '@my-org/ui', include: ['Button.Split'], allowedStyleProps: ['direction'] },
+],
+```
+
+```tsx
+<Button.Group gap="1x" flow="row" />; // passes: Button.Group is excluded
+<Button.Split direction="column" />; // passes
+<Button gap="1x" />; // reported: Button keeps its contract
+```
+
+The longest named path wins, so `'Button.Group'` also covers
+`<Button.Group.Item>`, and the first entry that names a path decides it:
+excluding the path leaves it open, including it protects it with that entry's
+`allowedStyleProps`. Patterns without a dot, `*` included, only ever match the
+export name.
+
+For `extends: '@my-org/ui'` to find the list, the package has to publish its
+`tasty.config.*` at the package root.
+
+The design system's own source imports its components by relative path, which
+does not match `source`, so the design system itself is not held to the rule.
+
+## Options
+
+```js
+'tasty/no-protected-restyle': ['error', { usages: 'wrappers' }],
+```
+
+| `usages` | Reports |
+| --- | --- |
+| `'all'` (default) | Instance `styles`, `*Styles` and style props, and `tasty()` wrappers |
+| `'wrappers'` | `tasty()` wrappers that restyle a protected component, and wrappers of those wrappers |
+
+A wrapper defines a restyled component once, and every use of it inherits the
+restyle. `'wrappers'` lets a project enforce the rule on those definitions while
+its instance overrides are still being worked through.
+
+## What it reports
+
+On a protected component:
+
+```tsx
+import { tasty } from '@tenphi/tasty';
+import { Button, ComboBox } from '@my-org/ui';
+
+// Instance styles: `styles` and every `*Styles` prop.
+<Button styles={{ fill: '#danger' }} />;
+<ComboBox inputStyles={{ padding: '2x' }} />;
+
+// Appearance style props.
+<Button fill="#danger" radius="round" />;
+
+// Wrappers that restyle it: `styles`, `variants`, or `*Styles` and appearance
+// style props among their default props.
+const DangerButton = tasty(Button, { styles: { fill: '#danger' } });
+
+// Wrappers of wrappers still restyle `Button`.
+const CopyButton = tasty(Button, { type: 'clear' });
+<CopyButton styles={{ fill: '#danger' }} />;
+tasty(CopyButton, { fill: '#danger' });
+```
+
+And not:
+
+```tsx
+// Its own props, tokens and mods.
+<Button type="primary" theme="danger" size="small" tokens={{ $gap: '1x' }} />;
+
+// Allowed style props, and root `styles` whose keys are all allowed.
+<Button width="100%" gridArea="actions" />;
+<Button styles={{ width: '100%', gridArea: 'actions' }} />;
+
+// A wrapper that only sets semantic defaults.
+const CopyButton = tasty(Button, { type: 'clear', size: 'small' });
+```
+
+Root `styles` passes only as an inline object whose every key is an allowed
+style prop. A sub-element key, a spread, or a variable holding the styles is
+reported. `*Styles` props style the component's inner elements, so they are
+always reported.
+
+A style prop is a Tasty style property or an entry in `config.styles`. Plain
+CSS property names are left out, because some of them (`size`, `orientation`)
+are common semantic props. With
+[`typeAwareJSX`](../../README.md#experimental-type-aware-jsx-props) on, a prop
+the component declares with its own type (such as a `position: 'before' |
+'after'` prop) is not a style prop either. Callbacks and JSX values are never
+style values.
+
+## Recognition
+
+A component resolves to the name its source exports it under, so:
+
+- an aliased import (`import { Button as UIButton }`) still counts;
+- a namespace member (`<UI.Button>`) is `Button`;
+- a sub-component (`<Text.Strong>`) follows `Text`, so excluding `Text` leaves
+  `Text.Strong` open too, unless an entry names the member path (see
+  [Sub-components](#sub-components));
+- `const` aliases and `tasty()` wrappers are followed, within the file and
+  across relative imports, along with relative re-exports and `export *` from a
+  protected source. Following relative modules needs the `typescript` package.
+
+Shadowed bindings, `let` aliases, type-only imports and native elements are not
+protected components.
+
+## Intentional overrides
+
+A justified override takes a reasoned disable on its line:
+
+```tsx
+// eslint-disable-next-line tasty/no-protected-restyle -- campaign banner needs the brand fill
+<Button fill="#brand" />;
+```
+
+## Relation to `no-styles-prop`
+
+`tasty/no-styles-prop` reports instance `styles` on every recognized Tasty
+component. Once a design system lists its protected components, this rule
+covers those with a message that names the component. A project that relies on
+it can turn `no-styles-prop` off, so layout primitives keep `styles` as their
+expected API.

package/docs/rules/no-raw-color-values.md

@@ -0,0 +1,49 @@
+# tasty/no-raw-color-values
+
+Reports raw colors in style values: hex colors, color functions such as `rgb()` or `okhsl()`, and named colors such as `red`. Use a color token instead.
+
+**Presets:** warning in recommended and strict. **Fix:** none.
+
+## Why
+
+A design system owns its colors in one place. A raw color skips the palette, so it does not follow themes, dark mode or high contrast, and it drifts from the tokens over time.
+
+## Examples
+
+```js
+// ❌ Use a color token instead of raw hex color '#ff0000'.
+fill: '#ff0000'
+
+// ❌ Use a color token instead of raw rgb() color.
+color: 'rgb(0 0 0)'
+
+// ❌ Use a color token instead of raw named color 'red'.
+border: '1bw solid red'
+
+// ✅ A token
+fill: '#danger'
+
+// ✅ A token definition may hold a raw color
+'#accent': '#ff0000'
+```
+
+## Checks
+
+1. **Hex colors:** `#` followed by 3, 4, 6 or 8 hex digits. A token name made only of those characters (`#add`, `#beef`) reads as a hex color too.
+2. **Color functions:** `rgb()`, `rgba()`, `hsl()`, `hsla()`, `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()`, `okhsl()`, `okhsv()`, `okhst()`, `color()`, `device-cmyk()` and `light-dark()`.
+3. **Named colors** (`red`, `rebeccapurple`, …) in properties that take colors. `transparent` and `currentColor` are left to [`tasty/prefer-custom-property-syntax`](prefer-custom-property-syntax.md), which suggests `#clear` and `#current`.
+
+Not reported: values of `#name` and `$name` keys, which define tokens, values inside `tastyStatic(':root', { … })`, quoted strings and URLs.
+
+## Exceptions
+
+For an intentional one-off color, disable the rule for that line, with a reason:
+
+```js
+// eslint-disable-next-line tasty/no-raw-color-values -- brand color from the partner's guidelines
+fill: '#1db954',
+```
+
+## Options
+
+None.

package/docs/rules/no-raw-motion-duration.md

@@ -0,0 +1,50 @@
+# tasty/no-raw-motion-duration
+
+Reports a hardcoded duration in `animation`, `animationDuration` and `transitionDuration`, such as `'spin 2s linear infinite'`. Use a duration token instead.
+
+**Presets:** none. Turn it on in your config. **Fix:** editor suggestions.
+
+## Why
+
+When a design system keeps its animation timing in tokens, a raw `2s` drifts from it. This rule extends [`tasty/no-raw-transition-duration`](no-raw-transition-duration.md) to the CSS animation and duration properties. It is opt-in because not every design system has motion tokens.
+
+## Examples
+
+```js
+// ❌ animation duration '2s' is hardcoded. Use a duration token.
+animation: 'spin 2s linear infinite'
+
+// ❌ transitionDuration duration '150ms' is hardcoded. Use a duration token.
+transitionDuration: '150ms'
+
+// ✅ A token
+animationDuration: '$fast-duration'
+
+// ✅ A delay: the second time in an animation shorthand
+animation: 'spin $spin-duration linear 2s'
+```
+
+## Checks
+
+- The duration in `animation`, and the values of `animationDuration` and `transitionDuration`, in Tasty style objects and JSX style props.
+- A second time in an animation shorthand is a delay and is left alone.
+- Zero and token-based timing are fine.
+
+The editor suggests each configured duration token whose name fits the property, such as a `$…duration` token. It never suggests removing the duration: unlike Tasty's `transition`, these CSS properties have no Tasty timing to fall back to.
+
+Lengths and other numbers are outside this rule. [`tasty/consistent-token-usage`](consistent-token-usage.md) covers pixel lengths.
+
+## Turning it on
+
+```js
+import tasty from '@tenphi/eslint-plugin-tasty';
+
+export default [
+  tasty.configs.recommended,
+  { rules: { 'tasty/no-raw-motion-duration': 'warn' } },
+];
+```
+
+## Options
+
+None.

package/docs/rules/no-raw-transition-duration.md

@@ -0,0 +1,56 @@
+# tasty/no-raw-transition-duration
+
+Reports a hardcoded duration in a `transition` value, such as `'fill 0.2s'`. Use a duration token, or leave the duration out to get the design system's timing.
+
+**Presets:** warning in recommended and strict. **Fix:** editor suggestions.
+
+## Why
+
+A design system that owns its motion timing owns it in one place. A `0.2s` sprinkled through components drifts the same way a raw hex color does. Without a duration, Tasty uses `var(--<name>-transition, var(--transition))`, so the timing follows the design system.
+
+## Examples
+
+```js
+// ❌ Transition duration '0.2s' is hardcoded. Use a duration token ($transition),
+//    or omit it to inherit $fill-transition (falling back to $transition).
+transition: 'fill 0.2s'
+
+// ❌ Transition duration '(0.2s * 2)' contains a hardcoded time.
+transition: 'fill (0.2s * 2)'
+
+// ✅ A token
+transition: 'fill $transition'
+
+// ✅ No duration: Tasty uses the per-name timing
+transition: 'fill'
+transition: 'fill ease-in'
+
+// ✅ A delay, not a duration
+transition: 'fill ease-in 0.1s'
+
+// ✅ Zero turns the motion off
+transition: 'fill 0s'
+```
+
+## Checks
+
+The rule checks only the **duration**: the second word of each comma group, when it is not an easing. A Tasty transition is `[name] [duration] [easing] [delay]` or `[name] [easing] [delay]`, so a later time is a delay and is left alone. Leaving out a delay means "no delay", a real change, while leaving out a duration falls back to the design system's timing.
+
+Hardcoded means a nonzero CSS time (`0.2s`, `200ms`, `.15s`), or an expression with a raw time and no token, such as `(0.2s * 2)`. Tokens and expressions built on them are fine: `$transition`, `var(--transition)`, `calc(var(--transition) * 2)`.
+
+The rule also checks the `transition` JSX prop of a local `const` component created by an imported `tasty()` call. Other components' props are not assumed to use Tasty's transition syntax.
+
+## Suggestions
+
+For a literal duration, the editor offers:
+
+1. each duration token in the project config: a `tokens` entry named `$transition`, ending in `-transition`, or containing `duration`;
+2. removing the duration, to inherit `var(--<name>-transition, var(--transition))`.
+
+Neither is an autofix: both change what the browser renders. An expression with a raw time gets no suggestion, since replacing or removing it may change what it computes.
+
+`@tenphi/tasty` ships a `tasty.config.ts` that lists `$transition`, and the plugin reads it as the base of the config chain, so there is always at least one token to suggest.
+
+## Options
+
+None.

package/docs/rules/no-runtime-styles-mutation.md

@@ -0,0 +1,58 @@
+# tasty/no-runtime-styles-mutation
+
+Reports style values and keys computed at render time: props, state, hook results, parameters, local bindings, calls, conditionals, computed keys and template interpolation.
+
+**Presets:** warning in recommended and strict. **Fix:** none.
+
+## Why
+
+Tasty generates CSS once per distinct styles object. Values that change on every render generate new CSS each time they change, and they hide what the component can look like. Express dynamic behavior with modifiers (`mods`), tokens (`tokens`) or CSS custom properties, and keep style values static.
+
+## Examples
+
+```js
+// ❌ Prefer a static style value for 'fill'. Use states with mods, tokens, or styleProps.
+function Tab({ isActive }) {
+  return <Box styles={{ fill: isActive ? '#blue' : '#gray' }} />;
+}
+
+// ✅ A state map and a modifier
+const TabBox = tasty({
+  styles: {
+    fill: {
+      '': '#gray',
+      active: '#blue',
+    },
+  },
+});
+
+function Tab({ isActive }) {
+  return <TabBox mods={{ active: isActive }} />;
+}
+```
+
+## What is reported
+
+The rule reports the specific value inside a state map or sub-element.
+
+- A style object that no function encloses is built once, while the module loads, so none of its values is reported, calls and unresolved names included. An instance field does not count as module level: it runs for every instance.
+- Inside a function, values fixed once the module has loaded are allowed, since Tasty generates their CSS once, as for a literal: `undefined`, module-scope `const` bindings, enums and imports (and their members, including computed members with such keys), and templates, operators, conditionals and `mergeStyles(...)` calls built only from those. The same test applies to computed keys.
+- Anything that reaches render-time scope is reported: props, state, hook results, parameters, a local or `let` binding, any other call.
+- A `mergeStyles` object-literal argument is a style object of its own and is checked where it stands.
+- Literal strings, `null`, `false` and `true` are fine.
+
+Style objects are found where they reach Tasty, not only where they are written: an object behind a conditional or logical operator (`mergeStyles(cond ? { … } : null, styles)`), and an object held in a render-scope variable that is read as styles (`const local = { … }` or `styles = { ...styles, … }`, then `styles={local}`, `mergeStyles(styles, local)` or `Icon: local`). A render-scope `const` bound to an object literal is not reported where it is passed on: its values are checked where it is written.
+
+Not covered here:
+
+- Spreads, which [`tasty/no-style-spread`](no-style-spread.md) reports, so each can be disabled on its own.
+- `tastyStatic()`, which [`tasty/static-no-dynamic-values`](static-no-dynamic-values.md) checks.
+- At-rule definition objects (`@keyframes`, `@font-face`, …), which may be shared JavaScript data.
+
+## Exceptions
+
+For JavaScript computation that is really needed, disable the rule for that line, with a reason.
+
+## Options
+
+None.

package/docs/rules/no-state-in-selector.md

@@ -0,0 +1,142 @@
+# tasty/no-state-in-selector
+
+Keep sub-element `$` selectors structural. Express state conditions in property
+state maps so Tasty can resolve their priority and make competing states
+exclusive.
+
+**Presets:** warning in recommended and strict. **Fix:** none.
+
+## Reported
+
+```js
+const Content = tasty({
+  styles: {
+    ResponsiveWidth: {
+      $: 'img:not([width]), :where(picture), video:not([width])',
+      inlineSize: 'max 100%',
+    },
+    Link: {
+      $: 'a:hover',
+      color: '#active',
+    },
+  },
+});
+```
+
+The rule reports one warning per `$` value, pointing out its first condition.
+Attribute selectors (such as `[width]`, `[disabled]`, `[data-active]`, and
+`[aria-expanded="true"]`) and pseudo-classes (including `:hover`, `:not()`,
+`:has()`, and `:last-child`) are conditions. Conditions are also reported inside
+structural grouping functions such as `:is()` and `:where()`.
+
+## Preferred
+
+```js
+const Content = tasty({
+  styles: {
+    Link: {
+      $: 'a',
+      color: {
+        '': '#text',
+        '@own(:hover)': '#active',
+      },
+    },
+    Picture: {
+      $: ':where(picture)',
+      inlineSize: 'max 100%',
+    },
+    Before: {
+      $: '&::before',
+      content: '""',
+    },
+  },
+});
+```
+
+Use `@own(...)` when the state belongs to the selected sub-element, for example
+`@own(![width])`. Ordinary state keys such as `:hover` refer to the root component.
+Conditions on ancestors need the appropriate root/parent state expression.
+When a selector list mixes conditions with unconditional targets, keep their
+different behavior explicit. For example, `picture` in the reported media list
+has no width condition and can own a separate unconditional style definition.
+
+Choose a default or fallback for each property state map deliberately. Removing
+a condition from `$` broadens the selector: every property in that sub-element
+must retain its intended condition, and default values can affect elements that
+previously received no rule. The rule provides no automatic fixes or editor
+suggestions because a safe migration depends on that intent.
+
+## Allowed structural selectors
+
+- Tags, universal selectors, Tasty element names and `@` placeholders.
+- Combinators, classes and IDs that identify the component's anatomy.
+- Exact, non-namespaced `[data-element="Name"]` selectors with a nonempty name.
+- Pseudo-elements, including the legacy spellings `:before`, `:after`,
+  `:first-line`, and `:first-letter`.
+- `:is()` and `:where()` containing only structural selectors.
+
+## Selectors that end in a pseudo-element
+
+When a `$` item ends in a pseudo-element, Tasty treats the pseudo-element as
+the sub-element: `@own(...)` states go after it, and states a pseudo-element
+cannot have (attributes, classes, `:first-child`, `:nth-*()`, `:empty`,
+`:has()`, and modifiers) are dropped with a warning. A condition on the element
+the pseudo-element belongs to must therefore stay in `$`, before the
+pseudo-element, and the rule accepts it:
+
+```js
+const Pagination = tasty({
+  styles: {
+    NextArrow: {
+      $: 'a[rel="next"]::before',
+      content: '"→"',
+    },
+    Marker: {
+      $: 'li:last-child::marker',
+      color: '#text',
+    },
+    Label: {
+      // Not '@::part(label):hover': @own(:hover) is the part's own state.
+      $: '@::part(label)',
+      color: { '': '#text', '@own(:hover)': '#active' },
+    },
+  },
+});
+```
+
+Moving such a condition into `@own(...)` would not work: Tasty ignores it, and
+[`tasty/no-ignored-pseudo-element-state`](no-ignored-pseudo-element-state.md)
+reports it. Pseudo-classes written after the pseudo-element are its own states,
+which `@own(...)` expresses exactly, so they are still reported. Conditions after it
+that `@own(...)` would drop, such as `::part(label):first-child`, are not.
+Conditions inside the pseudo-element, such as `::slotted(img:hover)`, are part
+of what it selects and stay in `$`. A condition in an earlier compound, such as
+`:last-child` in `li:last-child > a::before`, describes an ancestor and is
+still reported.
+
+"Ends in a pseudo-element" means the first `::name` or legacy single-colon
+spelling in the item's last compound. Each item of a selector list is checked
+on its own, so `summary::marker, li:last-child` still reports `:last-child`.
+
+Class and ID names are treated as identities; the rule cannot infer whether a
+particular class name represents application state. Keep such state in maps too.
+
+## Scope and limits
+
+This rule checks literal strings and templates without interpolation in
+sub-element `$` values. It uses the plugin's existing Tasty style detection,
+including `tasty()`, `tastyStatic()`, `useStyles()`, `useGlobalStyles()`, typed/shared
+style objects, JSX/Storybook styles, and configured `styleFunctions` helpers.
+TypeScript wrappers and statically computed `$` keys are supported.
+
+Root selector arguments to `tastyStatic()` and `useGlobalStyles()` are outside
+this rule's scope, as are unrelated JavaScript objects and dynamic selectors.
+Malformed selectors that cannot be parsed are left to syntax validation; this
+rule does not validate CSS syntax. Other rules may flag dynamic style values.
+
+For an intentional exception, disable only this rule on the selector's line and
+explain why its condition must remain part of the structural selection.
+
+## Options
+
+None.