@tenphi/eslint-plugin-tasty 1.18.0 → 1.19.0

package/docs/rules/valid-radius-shape.md

@@ -0,0 +1,31 @@
+# tasty/valid-radius-shape
+
+Reports a `radius` shape keyword Tasty does not know, such as `'circle'`.
+
+**Presets:** error in recommended and strict. **Fix:** editor suggestions.
+
+## Why
+
+`radius` takes four shape keywords besides lengths. Any other word renders no radius.
+
+## Examples
+
+```js
+// ✅ Valid
+radius: 'round'
+radius: 'ellipse'
+
+// ❌ Unknown radius shape 'circle'. Valid shapes: round, ellipse, leaf, backleaf.
+radius: 'circle'
+
+// ❌ Unknown radius shape 'roud'. Did you mean 'round'? Suggestion: 'round'
+radius: 'roud'
+```
+
+## Checks
+
+Valid shapes: `round`, `ellipse`, `leaf`, `backleaf`. A word close to one of them gets an editor suggestion to replace it.
+
+## Options
+
+None.

package/docs/rules/valid-recipe.md

@@ -0,0 +1,35 @@
+# tasty/valid-recipe
+
+Reports a recipe name in `recipe` that your config does not list.
+
+**Presets:** error in recommended and strict. **Fix:** none.
+
+## Why
+
+Tasty drops a recipe it does not know, so the styles it should bring never apply.
+
+## Examples
+
+```js
+// ✅ Valid, when tasty.config lists 'card' and 'elevated' in recipes
+recipe: 'card elevated'
+
+// ❌ Unknown recipe 'cards'
+recipe: 'cards'
+```
+
+## Checks
+
+A recipe value is a space-separated list of names. A `/` separates the recipes applied after the component's own styles. `none` means no base recipes.
+
+```text
+recipe: 'card elevated'            → ['card', 'elevated']
+recipe: 'reset input / autofill'   → before: ['reset', 'input'], after: ['autofill']
+recipe: 'none / autofill'          → before: [], after: ['autofill']
+```
+
+Each name must be in `recipes` in `tasty.config.*`. Without `recipes` in the config, the rule does nothing.
+
+## Options
+
+None.

package/docs/rules/valid-state-definition.md

@@ -0,0 +1,46 @@
+# tasty/valid-state-definition
+
+Reports an invalid state alias definition in `configure({ states })`: a key without `@`, or a value that is not a valid state expression.
+
+**Presets:** warning in strict. **Fix:** none.
+
+## Why
+
+Every style that uses an alias gets its definition. A broken definition breaks each of those states at once.
+
+## Examples
+
+```js
+// ✅ Valid
+configure({
+  states: {
+    '@mobile': '@media(w < 768px)',
+    '@dark': '@root(theme=dark)',
+  },
+});
+
+// ❌ Empty @media() query.
+configure({
+  states: {
+    '@mobile': '@media()',
+  },
+});
+
+// ❌ State alias 'mobile' must start with '@'.
+configure({
+  states: {
+    mobile: '@media(w < 768px)',
+  },
+});
+```
+
+## Checks
+
+1. An alias key starts with `@`.
+2. Its value parses as a state expression, with the same parser as [`tasty/valid-state-key`](valid-state-key.md).
+
+The rule reads `configure()` calls imported from Tasty.
+
+## Options
+
+None.

package/docs/rules/valid-state-key.md

@@ -0,0 +1,62 @@
+# tasty/valid-state-key
+
+Reports a state key that does not parse, such as `'hovered &'` or `':hovr'`, a misused `_` fallback floor, and an `@alias` your config does not list.
+
+**Presets:** error in recommended and strict. **Fix:** none.
+
+## Why
+
+Tasty skips a state key it cannot parse, so the value under it never applies. Nothing reports it at runtime.
+
+## Examples
+
+```js
+// ✅ Valid
+fill: { '': '#white', hovered: '#gray.05' }
+fill: { '': '#white', ':hover': '#gray.05' }
+fill: { '': '#white', '@mobile': '#gray' }
+
+// ✅ A standalone '_' fallback floor
+inset: { _: 'auto', '@(scroll-state(stuck: top))': '0 auto auto auto' }
+
+// ✅ The '_' floor and the '' default together
+fill: { _: '#white', '': '#gray', hovered: '#blue' }
+
+// ❌ Expected expression after '&' operator.
+fill: { '': '#white', 'hovered &': '#gray' }
+
+// ❌ Unknown pseudo-class ':hovr'.
+fill: { '': '#white', ':hovr': '#gray' }
+
+// ❌ Unknown state alias '@mobil'. Configured aliases: @mobile.
+fill: { '': '#white', '@mobil': '#gray' }
+
+// ❌ The fallback floor "_" cannot be combined with other state logic.
+fill: { '': '#white', '_ & hovered': '#blue' }
+```
+
+## Valid state keys
+
+- `''`: the default, the lowest priority among states.
+- `_`: the fallback floor, standalone only.
+- A modifier: `hovered`, `pressed`, `disabled`.
+- A value modifier: `theme=danger`, `size=large`, `size^=sm`, with `=`, `^=`, `$=` or `*=`.
+- A pseudo-class: any standard CSS pseudo-class, such as `:hover`, `:focus-visible`, `:popover-open`, `:nth-child(2n+1)` or `:dir(rtl)`.
+- A class or an attribute: `.active`, `[aria-expanded="true"]`, `[data-mode]`.
+- Combinations: `hovered & .active`, `!disabled`, `(loading | processing) & !readonly`, with `&`, `|`, `^` and `!`.
+- Advanced states: `@media(...)`, `@root(...)`, `@parent(...)`, `@(...)` container queries, `@own(...)`, `@starting`, `@supports(...)`.
+- Aliases: `@mobile`, `@dark` and others from `states` in `tasty.config.*` or local `@name` keys.
+
+## Checks
+
+1. **Syntax.** Operators, balanced parentheses, known pseudo-classes, and the dimension shorthands (`w`, `h`, `is`, `bs`) inside `@media(...)` and `@(...)`.
+2. **Aliases.** When `states` in `tasty.config.*` lists aliases, every `@name` must be one of them or a local alias. [`tasty/no-unknown-state-alias`](no-unknown-state-alias.md) does the same with more context, in the strict preset.
+3. **Fallback floor.** `_` stands alone. Combined with other state logic (`_ & hovered`, `_ | loading`), Tasty ignores the key.
+
+## The `_` fallback floor
+
+A standalone `_` key is a fallback for the whole map. Its value always applies, and states with higher priority layer over it through the cascade. It covers the case where a negated `@supports(...)` or container-query default would otherwise never apply, which leaves no rule active. `_` can sit next to `''`: one is the always-on floor, the other the negated default.
+
+## Options
+
+None.

package/docs/rules/valid-styles-structure.md

@@ -0,0 +1,48 @@
+# tasty/valid-styles-structure
+
+Reports a styles object with the wrong shape: state keys at the top level, at-rule keys whose value is not the object they need, a `recipe` that is not a string, and the at-rule key spellings of Tasty v2.
+
+**Presets:** error in recommended and strict. **Fix:** autofix (renamed at-rule keys).
+
+## Why
+
+State maps go inside property values. A state key at the top of a styles object, such as `':hover': { fill: '#gray' }`, is read as a property name and renders nothing.
+
+## Examples
+
+```js
+// ❌ State key '' at top level is not valid. State maps belong inside property values.
+tastyStatic({
+  '': { fill: '#white' },
+  _: { fill: '#white' }, // the '_' floor goes inside a property too
+  ':hover': { fill: '#gray' },
+});
+
+// ✅ A state map inside the property
+tastyStatic({
+  fill: {
+    '': '#white',
+    ':hover': '#gray',
+  },
+});
+
+// ❌ '@properties' was renamed to '@property' in Tasty v3. Autofix: '@property'
+tasty({ styles: { '@properties': { angle: { syntax: '<angle>', inherits: false, initialValue: '0deg' } } } });
+```
+
+## Checks
+
+1. Top-level keys are properties, sub-elements or special keys, not state keys.
+2. `@keyframes` is an object of `{ name: { step: styles } }`.
+3. `@property` is an object of `{ name: { syntax, inherits, initialValue } }`.
+4. `@font-face` is an object of `{ familyName: descriptors | descriptors[] }`.
+5. `@counter-style` is an object of `{ name: descriptors }`.
+6. `@function` is an object of `{ '$$name': { args, result } }`.
+7. `recipe` is a string.
+8. The Tasty v2 spellings `@properties`, `@fontFace` and `@counterStyle` are renamed to `@property`, `@font-face` and `@counter-style`. This is the only autofix, so `eslint --fix` does most of a v2 upgrade.
+
+An at-rule value is reported only when it is surely not an object: a literal, a template or an array. A variable such as `'@font-face': fontFaceMap` may hold the object and is left alone.
+
+## Options
+
+None.

package/docs/rules/valid-sub-element.md

@@ -0,0 +1,100 @@
+# tasty/valid-sub-element
+
+Sub-element values must be style objects, or `false` or `null` to disable the
+sub-element. In a later `mergeStyles` layer or a `styles` prop, either one
+removes the sub-element styles below it.
+Their `$` selectors must select inner elements or pseudo-elements, rather than
+reuse the sub-element mechanism to style the component root.
+
+**Presets:** error in recommended and strict. **Fix:** none.
+
+For a nested sub-element, `&` attaches to the containing sub-element's selector
+rather than the component root. A nested `Heading: { $: '&:is(h1)' }` inside
+`Outer` therefore styles `Outer` itself. Put that condition in `Outer`'s property
+state maps using `@own(:is(h1))`, or select a descendant heading instead.
+
+## Reported
+
+```js
+const Heading = tasty({
+  styles: {
+    Level1: { $: '&:is(h1)', preset: 'h1' },
+    Level2: { $: '&:is(h2)', preset: 'h2' },
+  },
+});
+```
+
+`&:is(h1)` attaches directly to the root selector. It selects a root `h1`,
+rather than an element named `Level1`. The same issue applies to root compounds
+such as `&.active` or `&[data-level="1"]`. Each `$` value gets one error, even
+when several branches select the root. A root-targeting branch is also reported
+in a list that contains valid pseudo-element or descendant selectors.
+
+## Style the root with a property state map
+
+If the component itself can be a heading, put the condition in the root's
+property state map. Preset names below assume corresponding configured presets.
+
+```js
+const Heading = tasty({
+  styles: {
+    preset: {
+      '': 'body',
+      ':is(h1)': 'h1',
+      ':is(h2)': 'h2',
+      ':is(h3)': 'h3',
+      ':is(h4)': 'h4',
+      ':is(h5)': 'h5',
+      ':is(h6)': 'h6',
+    },
+  },
+});
+```
+
+Choose the default or fallback preset according to the component's contract.
+
+## Select descendant headings with an affix
+
+If the headings are inside the component, use a descendant selector:
+
+```js
+const Content = tasty({
+  styles: {
+    Level1: { $: 'h1', preset: 'h1' },
+    Level2: { $: 'h2', preset: 'h2' },
+  },
+});
+```
+
+The `h1` affix selects descendant `h1` tags. Omitting `$` selects
+`[data-element="Level1"]` instead. Combinators and `@` placeholders remain
+supported, for example `$: '>h1'` and `$: '>@'`.
+
+Root pseudo-elements remain valid:
+
+```js
+Before: { $: '&::before', content: '""' }
+```
+
+The legacy pseudo-element spellings `:before`, `:after`, `:first-line`, and
+`:first-letter` are also supported. The separate `no-state-in-selector` rule
+may warn about conditions such as `&:hover::before`; those conditions belong
+in property state maps.
+
+## Scope and limits
+
+The selector check applies to literal strings and templates without interpolation
+inside owned sub-elements, including nested sub-elements, typed/shared styles,
+JSX/Storybook styles, and configured style helpers. TypeScript wrappers and
+statically computed sub-element and `$` keys are supported.
+
+Root `$` values, selector arguments to `tastyStatic()` or `useGlobalStyles()`,
+unrelated objects, and dynamic selectors are outside the selector check.
+Malformed selectors that cannot be parsed are left to syntax validation.
+
+There is no autofix or editor suggestion: choosing between a root state map and
+a descendant selector changes which elements receive the styles.
+
+## Options
+
+None.

package/docs/rules/valid-transition.md

@@ -0,0 +1,46 @@
+# tasty/valid-transition
+
+Reports a `transition` name that is neither a Tasty semantic transition nor a CSS property, a camelCase CSS name, and a CSS name that has a semantic equivalent.
+
+**Presets:** warning in recommended and strict. **Fix:** editor suggestions.
+
+## Why
+
+Tasty expands semantic names (`fill`, `theme`, `radius`, …) into the CSS properties they cover. Any other name is lowercased and emitted as is, so a typo or a camelCase name animates nothing.
+
+## Examples
+
+```js
+// ✅ Valid
+transition: 'fill 0.2s'
+transition: 'theme 0.3s ease'
+transition: '$$my-prop 0.2s'
+
+// ❌ Unknown transition name 'colour'
+transition: 'colour 0.2s'
+
+// ❌ 'gridTemplateColumns' compiles to 'gridtemplatecolumns', which is not a CSS property.
+//    Suggestion: 'grid-template-columns'
+transition: 'gridTemplateColumns 0.2s'
+
+// ❌ 'background-color' has a Tasty semantic equivalent. Suggestion: 'fill'
+transition: 'background-color 0.2s'
+```
+
+## Checks
+
+A transition value is a comma-separated list. Each entry is `name [duration] [easing] [delay]`.
+
+1. The name must be a semantic transition, a CSS property, or a `$$name` custom property reference.
+2. A CSS property must be kebab-case. `zIndex` is the exception: it is a semantic name that compiles to `z-index`.
+3. A CSS property with a semantic equivalent (`background-color`, `box-shadow`) gets a suggestion to use the semantic name.
+
+Semantic names: `fade`, `fill`, `color`, `theme`, `border`, `radius`, `shadow`, `outline`, `preset`, `text`, `gap`, `opacity`, `translate`, `rotate`, `scale`, `filter`, `image`, `background`, `width`, `height`, `inset` and `zIndex`.
+
+`flow` is reported although the CSS property dataset lists it: no browser implements it, and Tasty has no `flow` transition.
+
+Durations are checked by [`tasty/no-raw-transition-duration`](no-raw-transition-duration.md).
+
+## Options
+
+None.

package/docs/rules/valid-value.md

@@ -0,0 +1,65 @@
+# tasty/valid-value
+
+Parses every string style value and reports what Tasty cannot read: unknown words, modifiers a property does not take, colors where none belong, unbalanced parentheses and `!important`.
+
+**Presets:** error in recommended and strict. **Fix:** none.
+
+## Why
+
+Tasty's runtime parser files every word it does not recognize as a modifier and moves on, so a typo renders as nothing, with no error. This rule uses the plugin's own value parser, which reports every unrecognized token instead.
+
+## Examples
+
+```js
+// ❌ Modifier 'topp' is not valid for 'padding'. Accepted: top, right, bottom, left, longhand.
+padding: '2x topp'
+
+// ❌ Property 'padding' does not accept color tokens, but found '#red'.
+padding: '2x #red'
+
+// ❌ Unbalanced parentheses in value.
+fill: 'rgb(255, 0, 0'
+
+// ❌ 'svgFill' takes a single paint: Tasty keeps one color and drops the rest.
+svgFill: 'none #red'
+
+// ❌ '#purple' is not expanded after url()
+svgFill: 'url(#gradient) #purple'
+
+// ✅ Valid
+fill: '#purple.5'
+padding: '2x top bottom'
+border: '1bw solid #red top'
+border: '1bw Highlight' // CSS named and system colors are colors
+width: 'min 200px'
+display: '-webkit-box' // with -webkit-line-clamp; also -webkit-inline-box
+aspectRatio: '16/10' // <ratio> allows optional whitespace: same as '16 / 10'
+svgFill: 'context-stroke'
+svgFill: 'url(#gradient) currentColor' // a url() fallback is plain CSS
+```
+
+## How it works
+
+1. The value is split into groups (by commas) and parts (by spaced slashes), and each token is classified: color token, custom property, function, number with a unit, keyword, or unknown.
+2. The result is compared with what the property expects:
+   - A property without modifiers (`fill`, `color`, `opacity`, `width`, `height`, …) must have no modifier words.
+   - A property with modifiers (`border`, `padding`, `radius`, …) takes only modifiers from its own set.
+   - A property without colors (`padding`, `margin`, `gap`, `width`, …) must have no color tokens.
+   - `svgFill` is the native SVG `fill`, so it also takes `context-fill` and `context-stroke`. It takes one paint: Tasty keeps one color and drops the rest. A `url()` may have one fallback, but Tasty passes that value through as plain CSS, so a `#name` fallback is reported: it is never expanded.
+
+`recipe` (checked by [`tasty/valid-recipe`](valid-recipe.md)) and the at-rule keys are not parsed.
+
+## Related rules
+
+`valid-value` asks "does it parse?". Other rules check that the names exist in your config:
+
+| Check | Rule |
+| --- | --- |
+| Does this value parse without unknown tokens? | `tasty/valid-value` |
+| Is `#purple` a known color token? | [`tasty/valid-color-token`](valid-color-token.md) |
+| Is `3cols` a known unit? | [`tasty/valid-custom-unit`](valid-custom-unit.md) |
+| Is `$spacign` a known custom property? | [`tasty/valid-custom-property`](valid-custom-property.md) |
+
+## Options
+
+None.

package/harness/dev.harnesspm/hooks.json

@@ -0,0 +1,12 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "id": "check-edit",
+        "matcher": { "claude": "Edit|Write|MultiEdit" },
+        "run": "check-edit",
+        "timeout": 30
+      }
+    ]
+  }
+}

package/harness/dev.harnesspm/rules/usage.md

@@ -0,0 +1,11 @@
+# Linting Tasty styles
+
+## After you change styles
+
+- Lint the changed files and fix every `tasty/*` problem.
+- `tasty-lint:check <files>` runs only the Tasty rules.
+- Each `tasty/<rule>` has a page in the `tasty-lint` docs index.
+
+## Exceptions
+
+- Disable a rule for one line only: `// eslint-disable-next-line tasty/<rule> -- <reason>`.

package/harness/dev.harnesspm/scripts/check-edit.mjs

@@ -0,0 +1,127 @@
+/**
+ * The check-edit hook: after an agent edits a file that imports Tasty, lints
+ * it with the recommended Tasty rules and hands the new problems back.
+ *
+ * Claude Code runs it on PostToolUse for Edit, Write and MultiEdit, with the
+ * event as JSON on stdin. Exit 0 says nothing. Exit 2 puts stderr in front of
+ * the agent. Any other exit shows stderr to the person only, which is how a
+ * broken setup is reported: the agent cannot fix it.
+ */
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import {
+  NO_PARSER,
+  collectProblems,
+  createLinter,
+  formatProblems,
+  importsFrom,
+  isLintable,
+  isTypeScript,
+  loadESLint,
+  loadTypeScriptParser,
+  newProblems,
+  rulePage,
+} from './lint.mjs';
+
+/** More problems than this are summed up, not listed. */
+const LIMIT = 20;
+
+const PACKAGE_ROOT = realpathSync(
+  fileURLToPath(new URL('../../../', import.meta.url)),
+);
+
+function setupError(message) {
+  console.error(`tasty-lint (check-edit hook): ${message}`);
+  process.exit(1);
+}
+
+let event;
+try {
+  event = JSON.parse(readFileSync(0, 'utf8') || '{}');
+} catch {
+  process.exit(0);
+}
+const filePath = event?.tool_input?.file_path;
+if (typeof filePath !== 'string' || !isLintable(filePath)) process.exit(0);
+
+const cwd = typeof event.cwd === 'string' ? event.cwd : process.cwd();
+const projectDir = process.env.HARNESSPM_PROJECT_DIR || cwd;
+const file = resolve(cwd, filePath);
+let text;
+try {
+  text = readFileSync(file, 'utf8');
+} catch {
+  process.exit(0);
+}
+
+const build = (name) => pathToFileURL(join(PACKAGE_ROOT, 'dist', name)).href;
+if (!existsSync(join(PACKAGE_ROOT, 'dist/index.js'))) {
+  setupError(`cannot find the plugin build in ${PACKAGE_ROOT}/dist.`);
+}
+
+// The cheap test first. Only a file without a Tasty import pays for loading
+// the config, to look for the design system modules it lists.
+if (!importsFrom(text)) {
+  const { loadConfig } = await import(build('config.js'));
+  let sources = [];
+  try {
+    sources = loadConfig(file).importSources;
+  } catch {
+    // A broken config is reported when a file that imports Tasty is linted.
+  }
+  if (!importsFrom(text, sources)) process.exit(0);
+}
+
+let problems;
+try {
+  const { default: plugin, recommended } = await import(build('index.js'));
+  const dirs = [dirname(file), projectDir];
+  const ESLint = await loadESLint(dirs, PACKAGE_ROOT);
+  const parser = await loadTypeScriptParser(dirs);
+  if (!parser && isTypeScript(file)) setupError(NO_PARSER);
+  const eslint = createLinter({
+    ESLint,
+    plugin,
+    rules: recommended,
+    parser,
+    cwd: projectDir,
+  });
+  const lint = async (source) =>
+    collectProblems(
+      await eslint.lintText(source, { filePath: file }),
+      projectDir,
+    ).problems;
+
+  problems = await lint(text);
+  // Report only what this edit added, so problems an older line already had
+  // do not come back after every edit of the file.
+  const original = event.tool_response?.originalFile;
+  if (problems.length > 0 && typeof original === 'string' && original) {
+    problems = newProblems(problems, text, await lint(original), original);
+  }
+} catch (error) {
+  setupError(error instanceof Error ? error.message : String(error));
+}
+
+if (problems.length === 0) process.exit(0);
+
+const shown = problems.slice(0, LIMIT);
+const relativeFile = shown[0].file;
+// Paths print relative to the project root: the event's cwd is wherever the
+// agent's shell went last, such as a folder in node_modules.
+const pageOf = (name) =>
+  rulePage(name, { projectDir, packageRoot: PACKAGE_ROOT, cwd: projectDir });
+const out = [
+  `tasty-lint: this edit left ${problems.length} Tasty lint problem${problems.length === 1 ? '' : 's'} in ${relativeFile}. Fix ${problems.length === 1 ? 'it' : 'them'}. For an intentional exception, put \`// eslint-disable-next-line tasty/<rule> -- <reason>\` above the line.`,
+  '',
+  formatProblems(shown, pageOf),
+];
+if (problems.length > LIMIT) {
+  out.push(
+    '',
+    `${problems.length - LIMIT} more: run \`npx harnesspm run tasty-lint:check ${relativeFile}\`.`,
+  );
+}
+console.error(out.join('\n'));
+process.exit(2);