@studiometa/eslint-plugin-ui 2.0.0-alpha.1 → 2.0.0-alpha.3

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/README.md CHANGED
@@ -13,6 +13,16 @@ ESLint plugin to help developers discover and use components from [@studiometa/u
13
13
  npm install --save-dev @studiometa/eslint-plugin-ui
14
14
  ```
15
15
 
16
+ ## Agent skills
17
+
18
+ The package ships the `studiometa-eslint-plugin-ui` [agent skill](https://agentskills.io). The skill teaches coding agents how to use the package, and it matches the installed version. Link the skills of your dependencies into your project with the [`skills` CLI](https://github.com/vercel-labs/skills):
19
+
20
+ ```bash
21
+ npx skills experimental_sync
22
+ ```
23
+
24
+ The command links each skill from `node_modules` into the agent folders (`.agents/skills/`, `.claude/skills/`…). When you update the package, the linked skill updates too.
25
+
16
26
  ## Configuration
17
27
 
18
28
  ### ESLint
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@studiometa/eslint-plugin-ui",
3
- "version": "2.0.0-alpha.1",
3
+ "version": "2.0.0-alpha.3",
4
4
  "description": "ESLint plugin to help developers discover and use @studiometa/ui components",
5
5
  "publishConfig": {
6
6
  "access": "public"
@@ -16,6 +16,7 @@
16
16
  "sideEffects": false,
17
17
  "files": [
18
18
  "dist",
19
+ "skills",
19
20
  "README.md"
20
21
  ],
21
22
  "main": "./dist/index.js",
@@ -29,7 +30,8 @@
29
30
  }
30
31
  },
31
32
  "scripts": {
32
- "build": "node scripts/build.js",
33
+ "build": "node scripts/build.js && npm run build:skills",
34
+ "build:skills": "node ../../scripts/build-skills.ts",
33
35
  "test": "vitest run",
34
36
  "test:watch": "vitest",
35
37
  "lint:types": "tsgo --build tsconfig.json"
@@ -0,0 +1,49 @@
1
+ ---
2
+ name: studiometa-eslint-plugin-ui
3
+ description: Configure and fix the rules of @studiometa/eslint-plugin-ui, the ESLint and Oxlint plugin that finds custom @studiometa/js-toolkit code that an existing @studiometa/ui component can replace. Use when a project installs @studiometa/eslint-plugin-ui, when a lint report shows a ui/* rule (ui/prefer-ui-component, ui/prefer-transition, ui/no-manual-fetch, ui/prefer-data-model, ui/prefer-action), or when you add the plugin to eslint.config.js or .oxlintrc.json.
4
+ ---
5
+
6
+ # @studiometa/eslint-plugin-ui
7
+
8
+ The plugin warns when a class that extends the js-toolkit `Base` class does again what a `@studiometa/ui` component already does.
9
+
10
+ This skill matches the installed package version. The full rule documentation is in [references/guide/eslint-plugin/index.md](references/guide/eslint-plugin/index.md).
11
+
12
+ ## Configure
13
+
14
+ ESLint v9 flat config:
15
+
16
+ ```js
17
+ import { ui } from '@studiometa/eslint-plugin-ui';
18
+
19
+ export default [ui.configs.recommended];
20
+ ```
21
+
22
+ Oxlint: add the plugin with the name `ui` to get the `ui/` rule prefix:
23
+
24
+ ```json
25
+ {
26
+ "jsPlugins": [{ "name": "ui", "specifier": "@studiometa/eslint-plugin-ui" }],
27
+ "rules": {
28
+ "ui/prefer-ui-component": "warn",
29
+ "ui/prefer-transition": "warn",
30
+ "ui/no-manual-fetch": "warn",
31
+ "ui/prefer-data-model": "warn",
32
+ "ui/prefer-action": "warn"
33
+ }
34
+ }
35
+ ```
36
+
37
+ ## Fix a warning
38
+
39
+ Do not disable a rule to make the warning go away. Replace the custom code with the component that the rule names:
40
+
41
+ | Rule | Replace with |
42
+ | ------------------------ | -------------------------------------------------------------------------- |
43
+ | `ui/prefer-ui-component` | Extend the `@studiometa/ui` component of the same name, not `Base`. |
44
+ | `ui/prefer-transition` | `Transition` (or `withTransition`) for `open()` / `close()` class changes. |
45
+ | `ui/no-manual-fetch` | `Fetch` for `fetch()` followed by `innerHTML` or `insertAdjacentHTML`. |
46
+ | `ui/prefer-data-model` | `DataModel` and `DataEffect` for input values copied to the DOM. |
47
+ | `ui/prefer-action` | `Action` attributes in the HTML for a class with one simple event handler. |
48
+
49
+ Read the component reference before the change. The `studiometa-ui` skill has the API of each component.
@@ -0,0 +1,157 @@
1
+ # ESLint Plugin
2
+
3
+ `@studiometa/eslint-plugin-ui` is an ESLint plugin that helps developers discover and use components from `@studiometa/ui` rather than reimplementing them from scratch.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install --save-dev @studiometa/eslint-plugin-ui
9
+ ```
10
+
11
+ ## Configuration
12
+
13
+ ### ESLint
14
+
15
+ Add the recommended config to your `eslint.config.js` (ESLint v9 flat config):
16
+
17
+ ```js
18
+ import { ui } from '@studiometa/eslint-plugin-ui';
19
+
20
+ export default [ui.configs.recommended];
21
+ ```
22
+
23
+ All rules ship at `warn` severity in the recommended config. To override individual rules:
24
+
25
+ ```js
26
+ import { ui } from '@studiometa/eslint-plugin-ui';
27
+
28
+ export default [
29
+ ui.configs.recommended,
30
+ {
31
+ rules: {
32
+ 'ui/prefer-ui-component': 'error',
33
+ },
34
+ },
35
+ ];
36
+ ```
37
+
38
+ ### Oxlint
39
+
40
+ Add the plugin to your `.oxlintrc.json` using the `"ui"` name to get the `ui/` rule prefix:
41
+
42
+ ```json
43
+ {
44
+ "jsPlugins": [{ "name": "ui", "specifier": "@studiometa/eslint-plugin-ui" }],
45
+ "rules": {
46
+ "ui/prefer-ui-component": "warn",
47
+ "ui/prefer-transition": "warn",
48
+ "ui/no-manual-fetch": "warn",
49
+ "ui/prefer-data-model": "warn",
50
+ "ui/prefer-action": "warn"
51
+ }
52
+ }
53
+ ```
54
+
55
+ ## Rules
56
+
57
+ | Rule | Description | Recommended |
58
+ | ------------------------------------------------ | ---------------------------------------------------------------------------------- | ----------- |
59
+ | [`ui/prefer-ui-component`](#prefer-ui-component) | Warn when a class named after a `@studiometa/ui` component extends `Base` directly | warn |
60
+ | [`ui/prefer-transition`](#prefer-transition) | Warn when a `Base` subclass manually implements `open()` and `close()` | warn |
61
+ | [`ui/no-manual-fetch`](#no-manual-fetch) | Warn when a `Base` subclass combines `fetch()` with DOM injection | warn |
62
+ | [`ui/prefer-data-model`](#prefer-data-model) | Warn when a `Base` subclass manually syncs input values to the DOM | warn |
63
+ | [`ui/prefer-action`](#prefer-action) | Warn when a `Base` subclass only defines a single simple event handler | warn |
64
+
65
+ ### `ui/prefer-ui-component`
66
+
67
+ Detects classes whose name matches a component exported by `@studiometa/ui` (such as `Menu`, `Disclosure`, or `Dialog`) that extend `Base` directly. Suggests importing and extending the existing component instead.
68
+
69
+ ```js
70
+ // ❌ Incorrect
71
+ import { Base } from '@studiometa/js-toolkit';
72
+ class Menu extends Base {}
73
+
74
+ // ✅ Correct
75
+ import { Menu } from '@studiometa/ui';
76
+ class MyMenu extends Menu {}
77
+ ```
78
+
79
+ ### `ui/prefer-transition`
80
+
81
+ Detects `Base` subclasses that manually implement both `open()` and `close()` methods. This pattern is already handled by the [`Transition`](https://ui-v2.studiometa.dev/reference/items/Transition/) component, which manages CSS class transitions declaratively.
82
+
83
+ ```js
84
+ // ❌ Incorrect
85
+ import { Base } from '@studiometa/js-toolkit';
86
+ class Drawer extends Base {
87
+ open() {
88
+ this.$el.classList.add('is-open');
89
+ }
90
+ close() {
91
+ this.$el.classList.remove('is-open');
92
+ }
93
+ }
94
+
95
+ // ✅ Correct
96
+ import { Transition } from '@studiometa/ui';
97
+ class Drawer extends Transition {}
98
+ ```
99
+
100
+ ### `ui/no-manual-fetch`
101
+
102
+ Detects `Base` subclasses that combine a native `fetch()` call with DOM injection via `innerHTML` or `insertAdjacentHTML`. The [`Fetch`](https://ui-v2.studiometa.dev/reference/items/Fetch/) component handles this declaratively.
103
+
104
+ ```js
105
+ // ❌ Incorrect
106
+ import { Base } from '@studiometa/js-toolkit';
107
+ class ProductList extends Base {
108
+ async loadMore() {
109
+ const res = await fetch('/products?page=2');
110
+ this.$el.innerHTML = await res.text();
111
+ }
112
+ }
113
+
114
+ // ✅ Correct
115
+ import { Fetch } from '@studiometa/ui';
116
+ class ProductList extends Fetch {}
117
+ ```
118
+
119
+ ### `ui/prefer-data-model`
120
+
121
+ Detects `Base` subclasses with an `onInput*` or `onChange*` method that writes to `this.$refs.*` DOM properties (`textContent`, `innerHTML`, or `value`). The [`DataModel`](https://ui-v2.studiometa.dev/reference/items/DataModel/) and [`DataEffect`](https://ui-v2.studiometa.dev/reference/items/DataEffect/) components handle reactive bindings declaratively without manual wiring.
122
+
123
+ ```js
124
+ // ❌ Incorrect
125
+ import { Base } from '@studiometa/js-toolkit';
126
+ class LiveSearch extends Base {
127
+ onQueryInput() {
128
+ this.$refs.results.innerHTML = '';
129
+ }
130
+ }
131
+
132
+ // ✅ Correct
133
+ import { DataModel, DataEffect } from '@studiometa/ui';
134
+ ```
135
+
136
+ ### `ui/prefer-action`
137
+
138
+ Detects `Base` subclasses whose only logic is a single simple event handler (`onClick`, `onMouseenter`, `onMouseleave`, etc.) with no other methods. The [`Action`](https://ui-v2.studiometa.dev/reference/items/Action/) component handles this use case declaratively via data attributes, without needing a JavaScript class.
139
+
140
+ ```js
141
+ // ❌ Incorrect
142
+ import { Base } from '@studiometa/js-toolkit';
143
+ class Toggle extends Base {
144
+ onClick() {
145
+ this.$el.classList.toggle('is-active');
146
+ }
147
+ }
148
+ ```
149
+
150
+ ```html
151
+ <!-- ✅ Correct — use the Action component via data attributes -->
152
+ <div
153
+ data-component="Action"
154
+ data-option-on="click"
155
+ data-option-target="#panel"
156
+ data-option-effect="toggle-class:is-active"></div>
157
+ ```