@studiometa/eslint-plugin-ui 2.0.0-alpha.1 → 2.0.0-alpha.2
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.
|
|
3
|
+
"version": "2.0.0-alpha.2",
|
|
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
|
+
```
|