+```
diff --git a/packages/eslint-plugin-ui/package.json b/packages/eslint-plugin-ui/package.json
new file mode 100644
index 00000000..b89c8f68
--- /dev/null
+++ b/packages/eslint-plugin-ui/package.json
@@ -0,0 +1,42 @@
+{
+ "name": "@studiometa/eslint-plugin-ui",
+ "version": "1.0.0",
+ "description": "ESLint plugin to help developers discover and use @studiometa/ui components",
+ "publishConfig": {
+ "access": "public"
+ },
+ "author": "Studio Meta
(https://www.studiometa.fr)",
+ "license": "MIT",
+ "type": "module",
+ "sideEffects": false,
+ "files": [
+ "dist",
+ "README.md"
+ ],
+ "main": "./dist/index.js",
+ "module": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "import": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "scripts": {
+ "build": "node scripts/build.js",
+ "test": "vitest run",
+ "test:watch": "vitest",
+ "lint:types": "tsgo --build tsconfig.json"
+ },
+ "devDependencies": {
+ "@vitest/coverage-v8": "4.1.2",
+ "esbuild": "0.27.4",
+ "eslint": "9.34.0",
+ "typescript": "6.0.2",
+ "vitest": "4.1.2"
+ },
+ "dependencies": {
+ "@oxlint/plugins": "1.63.0"
+ }
+}
diff --git a/packages/eslint-plugin-ui/scripts/build.js b/packages/eslint-plugin-ui/scripts/build.js
new file mode 100644
index 00000000..1569b155
--- /dev/null
+++ b/packages/eslint-plugin-ui/scripts/build.js
@@ -0,0 +1,28 @@
+import { resolve, dirname } from 'node:path';
+import { execSync } from 'node:child_process';
+import { rmSync } from 'node:fs';
+import esbuild from 'esbuild';
+
+const root = resolve(dirname(new URL(import.meta.url).pathname), '..');
+
+rmSync(resolve(root, 'dist'), { recursive: true, force: true });
+console.log('Building @studiometa/eslint-plugin-ui...');
+
+const { errors, warnings } = await esbuild.build({
+ entryPoints: [resolve(root, 'src/index.ts')],
+ bundle: true,
+ write: true,
+ outdir: resolve(root, 'dist'),
+ target: 'esnext',
+ format: 'esm',
+ sourcemap: true,
+ platform: 'node',
+});
+
+errors.forEach(console.error);
+warnings.forEach(console.warn);
+
+console.log('Emitting types...');
+execSync('tsc --build tsconfig.json', { cwd: root, stdio: 'inherit' });
+
+console.log('Done!');
diff --git a/packages/eslint-plugin-ui/src/index.ts b/packages/eslint-plugin-ui/src/index.ts
new file mode 100644
index 00000000..0750509d
--- /dev/null
+++ b/packages/eslint-plugin-ui/src/index.ts
@@ -0,0 +1,43 @@
+import { eslintCompatPlugin } from '@oxlint/plugins';
+import {
+ preferUiComponent,
+ preferTransition,
+ noManualFetch,
+ preferDataModel,
+ preferAction,
+} from './rules/index.ts';
+
+const PLUGIN_NAME = 'ui';
+
+const rules = {
+ 'prefer-ui-component': preferUiComponent,
+ 'prefer-transition': preferTransition,
+ 'no-manual-fetch': noManualFetch,
+ 'prefer-data-model': preferDataModel,
+ 'prefer-action': preferAction,
+};
+
+const recommendedRules: Record = {
+ [`${PLUGIN_NAME}/prefer-ui-component`]: 'warn',
+ [`${PLUGIN_NAME}/prefer-transition`]: 'warn',
+ [`${PLUGIN_NAME}/no-manual-fetch`]: 'warn',
+ [`${PLUGIN_NAME}/prefer-data-model`]: 'warn',
+ [`${PLUGIN_NAME}/prefer-action`]: 'warn',
+};
+
+const base = eslintCompatPlugin({
+ meta: {
+ name: '@studiometa/eslint-plugin-ui',
+ },
+ rules,
+});
+
+const plugin = Object.assign(base, { configs: {} as Record });
+
+plugin.configs['recommended'] = {
+ plugins: { [PLUGIN_NAME]: plugin },
+ rules: recommendedRules,
+};
+
+export default plugin;
+export { plugin as ui };
diff --git a/packages/eslint-plugin-ui/src/rules/index.ts b/packages/eslint-plugin-ui/src/rules/index.ts
new file mode 100644
index 00000000..f406a35e
--- /dev/null
+++ b/packages/eslint-plugin-ui/src/rules/index.ts
@@ -0,0 +1,5 @@
+export { preferUiComponent } from './prefer-ui-component.ts';
+export { preferTransition } from './prefer-transition.ts';
+export { noManualFetch } from './no-manual-fetch.ts';
+export { preferDataModel } from './prefer-data-model.ts';
+export { preferAction } from './prefer-action.ts';
diff --git a/packages/eslint-plugin-ui/src/rules/no-manual-fetch.test.ts b/packages/eslint-plugin-ui/src/rules/no-manual-fetch.test.ts
new file mode 100644
index 00000000..3bea372d
--- /dev/null
+++ b/packages/eslint-plugin-ui/src/rules/no-manual-fetch.test.ts
@@ -0,0 +1,64 @@
+import { describe, it } from 'vitest';
+import { tester } from '../utils/rule-tester.ts';
+import { noManualFetch } from './no-manual-fetch.ts';
+
+describe('no-manual-fetch', () => {
+ it('passes and fails correctly', () => {
+ tester.run('no-manual-fetch', noManualFetch as any, {
+ valid: [
+ // fetch without DOM write — just data fetching
+ `import { Base } from '@studiometa/js-toolkit';
+ class Foo extends Base {
+ async mounted() {
+ const data = await fetch('/api').then(r => r.json());
+ this.data = data;
+ }
+ }`,
+
+ // Already using Fetch from @studiometa/ui
+ `import { Fetch } from '@studiometa/ui';
+ import { Base } from '@studiometa/js-toolkit';
+ class Foo extends Base {
+ async mounted() {
+ const res = await fetch('/api');
+ this.$el.innerHTML = await res.text();
+ }
+ }`,
+
+ // innerHTML write without fetch — might be something else
+ `import { Base } from '@studiometa/js-toolkit';
+ class Foo extends Base {
+ mounted() { this.$el.innerHTML = 'hello
'; }
+ }`,
+
+ // Outside a Base subclass
+ `async function loadContent(el) {
+ const res = await fetch('/fragment');
+ el.innerHTML = await res.text();
+ }`,
+ ],
+ invalid: [
+ {
+ code: `import { Base } from '@studiometa/js-toolkit';
+class ProductList extends Base {
+ async loadMore() {
+ const res = await fetch('/products?page=2');
+ this.$el.innerHTML = await res.text();
+ }
+}`,
+ errors: [{ messageId: 'preferFetch' }],
+ },
+ {
+ code: `import { Base } from '@studiometa/js-toolkit';
+class Facets extends Base {
+ async update() {
+ const res = await fetch(this.url);
+ this.$refs.container.insertAdjacentHTML('beforeend', await res.text());
+ }
+}`,
+ errors: [{ messageId: 'preferFetch' }],
+ },
+ ],
+ });
+ });
+});
diff --git a/packages/eslint-plugin-ui/src/rules/no-manual-fetch.ts b/packages/eslint-plugin-ui/src/rules/no-manual-fetch.ts
new file mode 100644
index 00000000..4c00cc15
--- /dev/null
+++ b/packages/eslint-plugin-ui/src/rules/no-manual-fetch.ts
@@ -0,0 +1,91 @@
+import {
+ findEnclosingClass,
+ isBaseSubclass,
+ isImportedFromUI,
+ getAncestors,
+ type Node,
+ type RuleContext,
+ createRule,
+} from '../utils/ast.ts';
+
+const DOM_WRITE_METHODS = new Set(['insertAdjacentHTML', 'insertAdjacentElement']);
+
+/**
+ * Detect manual fetch() calls inside Base subclasses that also write to innerHTML
+ * or use insertAdjacentHTML — suggest using the Fetch component from @studiometa/ui.
+ */
+export const noManualFetch = createRule({
+ meta: {
+ type: 'suggestion',
+ docs: {
+ description:
+ 'Prefer the Fetch component from @studiometa/ui over manually fetching and injecting HTML',
+ },
+ messages: {
+ preferFetch:
+ 'Manual fetch() with DOM injection detected. ' +
+ "Consider using the Fetch component from @studiometa/ui instead: import { Fetch } from '@studiometa/ui'.",
+ },
+ },
+ createOnce(context: RuleContext) {
+ const classesWithFetch = new WeakSet();
+ const classesWithDomWrite = new WeakSet();
+ const reported = new WeakSet();
+
+ function getEnclosingBaseClass(node: Node): Node | null {
+ const ancestors = getAncestors(context, node);
+ const cls = findEnclosingClass(ancestors);
+ if (!cls || !isBaseSubclass(cls, context)) return null;
+ if (isImportedFromUI('Fetch', context)) return null;
+ return cls;
+ }
+
+ function maybeReport(cls: Node) {
+ if (reported.has(cls)) return;
+ if (classesWithFetch.has(cls) && classesWithDomWrite.has(cls)) {
+ reported.add(cls);
+ context.report({ node: cls.id ?? cls, messageId: 'preferFetch' });
+ }
+ }
+
+ return {
+ CallExpression(node: Node) {
+ const callee = node.callee;
+
+ // Detect fetch(url)
+ const isFetch =
+ (callee.type === 'Identifier' && callee.name === 'fetch') ||
+ (callee.type === 'MemberExpression' &&
+ callee.property?.name === 'fetch' &&
+ callee.object?.type === 'ThisExpression');
+
+ // Detect el.insertAdjacentHTML / el.insertAdjacentElement
+ const isDomWrite =
+ callee.type === 'MemberExpression' &&
+ DOM_WRITE_METHODS.has(callee.property?.name);
+
+ if (!isFetch && !isDomWrite) return;
+
+ const cls = getEnclosingBaseClass(node);
+ if (!cls) return;
+
+ if (isFetch) classesWithFetch.add(cls);
+ if (isDomWrite) classesWithDomWrite.add(cls);
+
+ maybeReport(cls);
+ },
+
+ AssignmentExpression(node: Node) {
+ const left = node.left;
+ if (left.type !== 'MemberExpression') return;
+ if (left.property?.name !== 'innerHTML') return;
+
+ const cls = getEnclosingBaseClass(node);
+ if (!cls) return;
+
+ classesWithDomWrite.add(cls);
+ maybeReport(cls);
+ },
+ };
+ },
+});
diff --git a/packages/eslint-plugin-ui/src/rules/prefer-action.test.ts b/packages/eslint-plugin-ui/src/rules/prefer-action.test.ts
new file mode 100644
index 00000000..22e54f87
--- /dev/null
+++ b/packages/eslint-plugin-ui/src/rules/prefer-action.test.ts
@@ -0,0 +1,71 @@
+import { describe, it } from 'vitest';
+import { tester } from '../utils/rule-tester.ts';
+import { preferAction } from './prefer-action.ts';
+
+describe('prefer-action', () => {
+ it('passes and fails correctly', () => {
+ tester.run('prefer-action', preferAction as any, {
+ valid: [
+ // Already imports Action
+ `import { Action } from '@studiometa/ui';
+ import { Base } from '@studiometa/js-toolkit';
+ class Toggle extends Base {
+ onClick() { this.$el.classList.toggle('is-active'); }
+ }`,
+
+ // Multiple action methods — more complex than what Action handles
+ `import { Base } from '@studiometa/js-toolkit';
+ class Toggle extends Base {
+ onClick() {}
+ onMouseenter() {}
+ }`,
+
+ // Has additional logic methods
+ `import { Base } from '@studiometa/js-toolkit';
+ class Toggle extends Base {
+ onClick() {}
+ updateState() {}
+ }`,
+
+ // Accesses $children — orchestrates other components
+ `import { Base } from '@studiometa/js-toolkit';
+ class Toggle extends Base {
+ onClick() { this.$children.Panel[0].open(); }
+ }`,
+
+ // Not a Base subclass
+ `class Toggle {
+ onClick() {}
+ }`,
+ ],
+ invalid: [
+ {
+ code: `import { Base } from '@studiometa/js-toolkit';
+class Toggle extends Base {
+ onClick() {
+ this.$el.classList.toggle('is-active');
+ }
+}`,
+ errors: [{ messageId: 'preferAction' }],
+ },
+ {
+ code: `import { Base } from '@studiometa/js-toolkit';
+class HoverEffect extends Base {
+ onMouseenter() {
+ this.$el.classList.add('is-hovered');
+ }
+}`,
+ errors: [{ messageId: 'preferAction' }],
+ },
+ {
+ code: `class SubmitBtn extends Base {
+ onClick() {
+ this.$refs.form.submit();
+ }
+}`,
+ errors: [{ messageId: 'preferAction' }],
+ },
+ ],
+ });
+ });
+});
diff --git a/packages/eslint-plugin-ui/src/rules/prefer-action.ts b/packages/eslint-plugin-ui/src/rules/prefer-action.ts
new file mode 100644
index 00000000..c730babb
--- /dev/null
+++ b/packages/eslint-plugin-ui/src/rules/prefer-action.ts
@@ -0,0 +1,124 @@
+import {
+ isBaseSubclass,
+ getClassMethods,
+ isImportedFromUI,
+ type Node,
+ type RuleContext,
+ createRule,
+} from '../utils/ast.ts';
+
+/**
+ * Simple event handler method names that the Action component already handles.
+ * These are on-handler names on this.$el (root element) — if the class body
+ * contains ONLY these kinds of methods (plus config), it's a good Action candidate.
+ */
+const ACTION_EVENT_METHODS = new Set([
+ 'onClick',
+ 'onMouseenter',
+ 'onMouseleave',
+ 'onMouseover',
+ 'onMouseout',
+ 'onFocus',
+ 'onBlur',
+ 'onKeydown',
+ 'onKeyup',
+ 'onKeypress',
+ 'onPointerenter',
+ 'onPointerleave',
+ 'onPointerdown',
+ 'onPointerup',
+]);
+
+const NON_LOGIC_METHODS = new Set(['mounted', 'destroyed', 'updated']);
+
+/**
+ * Detect Base subclasses whose only logic is a single simple event handler
+ * (onClick, onMouseenter, etc.) — these can be replaced by the Action component.
+ */
+export const preferAction = createRule({
+ meta: {
+ type: 'suggestion',
+ docs: {
+ description:
+ 'Prefer the Action component from @studiometa/ui for simple event-triggered effects',
+ },
+ messages: {
+ preferAction:
+ 'This component only handles "{{method}}" on the root element. ' +
+ 'Consider using the Action component from @studiometa/ui instead, ' +
+ "which declaratively wires events to effects via data attributes: import { Action } from '@studiometa/ui'.",
+ },
+ },
+ createOnce(context: RuleContext) {
+ return {
+ ClassDeclaration(node: Node) {
+ check(node, context);
+ },
+ ClassExpression(node: Node) {
+ check(node, context);
+ },
+ };
+ },
+});
+
+function check(node: Node, context: RuleContext) {
+ if (!isBaseSubclass(node, context)) return;
+ if (isImportedFromUI('Action', context)) return;
+
+ const methods = getClassMethods(node);
+
+ // Find action-handler methods defined in this class
+ const actionMethods: string[] = [];
+ const otherMethods: string[] = [];
+
+ for (const [name] of methods) {
+ if (ACTION_EVENT_METHODS.has(name)) {
+ actionMethods.push(name);
+ } else if (name !== 'config' && !NON_LOGIC_METHODS.has(name)) {
+ otherMethods.push(name);
+ }
+ }
+
+ // Only flag when: exactly one action method, no other logic methods
+ if (actionMethods.length !== 1 || otherMethods.length > 0) return;
+
+ // Check the method body is simple — does not access this.$children or this.$refs
+ // to avoid false positives on components that orchestrate children
+ const method = methods.get(actionMethods[0])!;
+ if (hasComplexBody(method)) return;
+
+ context.report({
+ node: node.id ?? node,
+ messageId: 'preferAction',
+ data: { method: actionMethods[0] },
+ });
+}
+
+function hasComplexBody(methodNode: Node): boolean {
+ let complex = false;
+
+ function walk(n: Node) {
+ if (complex) return;
+ if (!n || typeof n !== 'object') return;
+
+ // Accessing $children or using await suggests complex logic
+ if (
+ n.type === 'MemberExpression' &&
+ n.object?.type === 'ThisExpression' &&
+ (n.property?.name === '$children' || n.property?.name === '$root')
+ ) {
+ complex = true;
+ return;
+ }
+
+ for (const key of Object.keys(n)) {
+ if (key === 'parent') continue;
+ const child = n[key];
+ if (Array.isArray(child)) child.forEach(walk);
+ else if (child && typeof child === 'object' && child.type) walk(child);
+ }
+ }
+
+ walk(methodNode.value ?? methodNode);
+ return complex;
+}
diff --git a/packages/eslint-plugin-ui/src/rules/prefer-data-model.test.ts b/packages/eslint-plugin-ui/src/rules/prefer-data-model.test.ts
new file mode 100644
index 00000000..1d761664
--- /dev/null
+++ b/packages/eslint-plugin-ui/src/rules/prefer-data-model.test.ts
@@ -0,0 +1,57 @@
+import { describe, it } from 'vitest';
+import { tester } from '../utils/rule-tester.ts';
+import { preferDataModel } from './prefer-data-model.ts';
+
+describe('prefer-data-model', () => {
+ it('passes and fails correctly', () => {
+ tester.run('prefer-data-model', preferDataModel as any, {
+ valid: [
+ // Already uses DataModel
+ `import { DataModel } from '@studiometa/ui';
+ import { Base } from '@studiometa/js-toolkit';
+ class Foo extends Base {
+ onInputChange() { this.$refs.output.textContent = this.$refs.input.value; }
+ }`,
+
+ // Input handler but no DOM write on this.$refs
+ `import { Base } from '@studiometa/js-toolkit';
+ class Foo extends Base {
+ onInputChange() { console.log('changed'); }
+ }`,
+
+ // DOM write but no input handler
+ `import { Base } from '@studiometa/js-toolkit';
+ class Foo extends Base {
+ mounted() { this.$refs.label.textContent = 'hello'; }
+ }`,
+
+ // Not a Base subclass
+ `class Foo {
+ onInputChange() { this.$refs.output.textContent = 'x'; }
+ }`,
+ ],
+ invalid: [
+ {
+ code: `import { Base } from '@studiometa/js-toolkit';
+class QuantityInput extends Base {
+ onPlusClick() {}
+ onMinusClick() {}
+ onInputChange() {
+ this.$refs.display.textContent = this.$refs.input.value;
+ }
+}`,
+ errors: [{ messageId: 'preferDataModel' }],
+ },
+ {
+ code: `import { Base } from '@studiometa/js-toolkit';
+class LiveSearch extends Base {
+ onQueryInput() {
+ this.$refs.results.innerHTML = '';
+ }
+}`,
+ errors: [{ messageId: 'preferDataModel' }],
+ },
+ ],
+ });
+ });
+});
diff --git a/packages/eslint-plugin-ui/src/rules/prefer-data-model.ts b/packages/eslint-plugin-ui/src/rules/prefer-data-model.ts
new file mode 100644
index 00000000..908a1668
--- /dev/null
+++ b/packages/eslint-plugin-ui/src/rules/prefer-data-model.ts
@@ -0,0 +1,105 @@
+import {
+ findEnclosingClass,
+ isBaseSubclass,
+ isImportedFromUI,
+ getAncestors,
+ type Node,
+ type RuleContext,
+ createRule,
+} from '../utils/ast.ts';
+
+/**
+ * Detect manual input/change event listeners that update DOM — suggest DataModel/DataEffect.
+ *
+ * Signal: addEventListener('input', ...) or an onInput* method that writes to
+ * textContent / innerHTML / value on another element inside a Base subclass.
+ */
+/** Walk up a member expression chain and check if the root is this.$refs / this.$el / this.$children */
+function isThisComponentAccess(node: Node): boolean {
+ let current = node;
+ while (current?.type === 'MemberExpression') {
+ if (
+ current.object?.type === 'ThisExpression' &&
+ (current.property?.name === '$refs' ||
+ current.property?.name === '$el' ||
+ current.property?.name === '$children')
+ ) {
+ return true;
+ }
+ current = current.object;
+ }
+ return false;
+}
+
+export const preferDataModel = createRule({
+ meta: {
+ type: 'suggestion',
+ docs: {
+ description:
+ 'Prefer DataModel/DataEffect from @studiometa/ui over manually syncing input values to the DOM',
+ },
+ messages: {
+ preferDataModel:
+ 'Manual input→DOM synchronization detected. ' +
+ 'Consider using DataModel and DataEffect from @studiometa/ui for reactive bindings: ' +
+ "import { DataModel, DataEffect } from '@studiometa/ui'.",
+ },
+ },
+ createOnce(context: RuleContext) {
+ const classesWithInputListener = new WeakSet();
+ const classesWithDomWrite = new WeakSet();
+ const reported = new WeakSet();
+
+ function getEnclosingBaseClass(node: Node): Node | null {
+ const ancestors = getAncestors(context, node);
+ const cls = findEnclosingClass(ancestors);
+ if (!cls || !isBaseSubclass(cls, context)) return null;
+ if (isImportedFromUI('DataModel', context) || isImportedFromUI('DataEffect', context))
+ return null;
+ return cls;
+ }
+
+ function maybeReport(cls: Node) {
+ if (reported.has(cls)) return;
+ if (classesWithInputListener.has(cls) && classesWithDomWrite.has(cls)) {
+ reported.add(cls);
+ context.report({ node: cls.id ?? cls, messageId: 'preferDataModel' });
+ }
+ }
+
+ return {
+ // Detect on-handler methods named onInput*, onChange*, onModelInput, etc.
+ MethodDefinition(node: Node) {
+ const name: string = node.key?.name ?? '';
+ if (!/^on.*(Input|Change|Model)/i.test(name)) return;
+
+ const ancestors = getAncestors(context, node);
+ const cls = findEnclosingClass(ancestors);
+ if (!cls || !isBaseSubclass(cls, context)) return;
+ if (isImportedFromUI('DataModel', context)) return;
+
+ classesWithInputListener.add(cls);
+ maybeReport(cls);
+ },
+
+ AssignmentExpression(node: Node) {
+ const left = node.left;
+ if (left.type !== 'MemberExpression') return;
+
+ const prop = left.property?.name;
+ const isDomWrite =
+ prop === 'textContent' || prop === 'innerHTML' || prop === 'value';
+ if (!isDomWrite) return;
+
+ // Must ultimately access this.$refs, this.$el, or this.$children
+ if (!isThisComponentAccess(left.object)) return;
+
+ const cls = getEnclosingBaseClass(node);
+ if (!cls) return;
+
+ classesWithDomWrite.add(cls);
+ maybeReport(cls);
+ },
+ };
+ },
+});
diff --git a/packages/eslint-plugin-ui/src/rules/prefer-transition.test.ts b/packages/eslint-plugin-ui/src/rules/prefer-transition.test.ts
new file mode 100644
index 00000000..c667355f
--- /dev/null
+++ b/packages/eslint-plugin-ui/src/rules/prefer-transition.test.ts
@@ -0,0 +1,54 @@
+import { describe, it } from 'vitest';
+import { tester } from '../utils/rule-tester.ts';
+import { preferTransition } from './prefer-transition.ts';
+
+describe('prefer-transition', () => {
+ it('passes and fails correctly', () => {
+ tester.run('prefer-transition', preferTransition as any, {
+ valid: [
+ // Already extends Transition from @studiometa/ui
+ `import { Transition } from '@studiometa/ui';
+ class Cart extends Transition {
+ open() {}
+ close() {}
+ }`,
+
+ // Has open/close but extends a UI component — fine
+ `import { Modal } from '@studiometa/ui';
+ class Search extends Modal {
+ open() {}
+ close() {}
+ }`,
+
+ // Only one of the two methods
+ `import { Base } from '@studiometa/js-toolkit';
+ class Foo extends Base {
+ open() {}
+ }`,
+
+ // No superclass
+ `class Foo {
+ open() {}
+ close() {}
+ }`,
+ ],
+ invalid: [
+ {
+ code: `import { Base } from '@studiometa/js-toolkit';
+class Cart extends Base {
+ open() { this.$el.classList.add('is-open'); }
+ close() { this.$el.classList.remove('is-open'); }
+}`,
+ errors: [{ messageId: 'preferTransition' }],
+ },
+ {
+ code: `class Drawer extends Base {
+ open() {}
+ close() {}
+}`,
+ errors: [{ messageId: 'preferTransition' }],
+ },
+ ],
+ });
+ });
+});
diff --git a/packages/eslint-plugin-ui/src/rules/prefer-transition.ts b/packages/eslint-plugin-ui/src/rules/prefer-transition.ts
new file mode 100644
index 00000000..b75f3383
--- /dev/null
+++ b/packages/eslint-plugin-ui/src/rules/prefer-transition.ts
@@ -0,0 +1,49 @@
+import {
+ isBaseSubclass,
+ isImportedFromUI,
+ getClassMethods,
+ type Node,
+ type RuleContext,
+ createRule,
+} from '../utils/ast.ts';
+
+/**
+ * Detect classes that extend Base and define both open() and close() methods —
+ * a pattern that duplicates what Transition (or Modal) already provides.
+ */
+export const preferTransition = createRule({
+ meta: {
+ type: 'suggestion',
+ docs: {
+ description:
+ 'Prefer @studiometa/ui Transition over manually implementing open/close logic in a Base subclass',
+ },
+ messages: {
+ preferTransition:
+ 'This class manually implements open() and close() methods. ' +
+ 'Consider extending Transition from @studiometa/ui instead, which handles show/hide with CSS class transitions: ' +
+ "import { Transition } from '@studiometa/ui'.",
+ },
+ },
+ createOnce(context: RuleContext) {
+ return {
+ ClassDeclaration(node: Node) {
+ check(node, context);
+ },
+ ClassExpression(node: Node) {
+ check(node, context);
+ },
+ };
+ },
+});
+
+function check(node: Node, context: RuleContext) {
+ if (!isBaseSubclass(node, context)) return;
+ // Already using a @studiometa/ui component as the base
+ if (isImportedFromUI(node.superClass?.name, context)) return;
+
+ const methods = getClassMethods(node);
+ if (!methods.has('open') || !methods.has('close')) return;
+
+ context.report({ node: node.id ?? node, messageId: 'preferTransition' });
+}
diff --git a/packages/eslint-plugin-ui/src/rules/prefer-ui-component.test.ts b/packages/eslint-plugin-ui/src/rules/prefer-ui-component.test.ts
new file mode 100644
index 00000000..dd6916a7
--- /dev/null
+++ b/packages/eslint-plugin-ui/src/rules/prefer-ui-component.test.ts
@@ -0,0 +1,48 @@
+import { describe, it } from 'vitest';
+import { tester } from '../utils/rule-tester.ts';
+import { preferUiComponent } from './prefer-ui-component.ts';
+
+describe('prefer-ui-component', () => {
+ it('passes and fails correctly', () => {
+ tester.run('prefer-ui-component', preferUiComponent as any, {
+ valid: [
+ // Unknown component name — not in @studiometa/ui
+ `import { Base } from '@studiometa/js-toolkit';
+ class Carousel extends Base {}`,
+
+ // Properly extending from @studiometa/ui
+ `import { Menu as MenuCore } from '@studiometa/ui';
+ class Menu extends MenuCore {}`,
+
+ // Extending a UI component with a different local name
+ `import { Accordion } from '@studiometa/ui';
+ class MyAccordion extends Accordion {}`,
+
+ // No superclass
+ `class Accordion {}`,
+ ],
+ invalid: [
+ {
+ code: `import { Base } from '@studiometa/js-toolkit';
+class Menu extends Base {}`,
+ errors: [{ messageId: 'preferImport' }],
+ },
+ {
+ code: `import { Base } from '@studiometa/js-toolkit';
+class Accordion extends Base {}`,
+ errors: [{ messageId: 'preferImport' }],
+ },
+ {
+ code: `import { Base } from '@studiometa/js-toolkit';
+class Modal extends Base {}`,
+ errors: [{ messageId: 'preferImport' }],
+ },
+ {
+ // Bare Base (no import) also triggers
+ code: `class Sticky extends Base {}`,
+ errors: [{ messageId: 'preferImport' }],
+ },
+ ],
+ });
+ });
+});
diff --git a/packages/eslint-plugin-ui/src/rules/prefer-ui-component.ts b/packages/eslint-plugin-ui/src/rules/prefer-ui-component.ts
new file mode 100644
index 00000000..e5addee9
--- /dev/null
+++ b/packages/eslint-plugin-ui/src/rules/prefer-ui-component.ts
@@ -0,0 +1,43 @@
+import {
+ UI_COMPONENT_NAMES,
+ isBaseSubclass,
+ isImportedFromUI,
+ type Node,
+ type RuleContext,
+ createRule,
+} from '../utils/ast.ts';
+
+export const preferUiComponent = createRule({
+ meta: {
+ type: 'suggestion',
+ docs: {
+ description:
+ 'Prefer importing components from @studiometa/ui over reimplementing them from scratch',
+ },
+ messages: {
+ preferImport:
+ '"{{name}}" is available in @studiometa/ui. ' +
+ 'Extend it instead of reimplementing from Base: import { {{name}} } from \'@studiometa/ui\'.',
+ },
+ },
+ createOnce(context: RuleContext) {
+ return {
+ ClassDeclaration(node: Node) {
+ check(node, context);
+ },
+ ClassExpression(node: Node) {
+ check(node, context);
+ },
+ };
+ },
+});
+
+function check(node: Node, context: RuleContext) {
+ const name: string = node.id?.name ?? '';
+ if (!name || !UI_COMPONENT_NAMES.has(name)) return;
+ if (!isBaseSubclass(node, context)) return;
+ // Already importing it from @studiometa/ui — they're extending it properly
+ if (isImportedFromUI(name, context)) return;
+
+ context.report({ node: node.id ?? node, messageId: 'preferImport', data: { name } });
+}
diff --git a/packages/eslint-plugin-ui/src/utils/ast.ts b/packages/eslint-plugin-ui/src/utils/ast.ts
new file mode 100644
index 00000000..dcf83c1d
--- /dev/null
+++ b/packages/eslint-plugin-ui/src/utils/ast.ts
@@ -0,0 +1,172 @@
+export type Node = Record;
+export type RuleContext = Record;
+
+export type RuleMeta = {
+ type?: 'problem' | 'suggestion' | 'layout';
+ fixable?: 'code' | 'whitespace';
+ hasSuggestions?: boolean;
+ docs?: { description?: string };
+ messages?: Record;
+};
+
+export function createRule unknown>>(rule: {
+ meta?: RuleMeta;
+ createOnce(context: RuleContext): V;
+}): { meta?: RuleMeta; createOnce(context: RuleContext): V } {
+ return rule;
+}
+
+export const UI_PACKAGE = '@studiometa/ui';
+export const TOOLKIT_PACKAGE = '@studiometa/js-toolkit';
+
+/**
+ * All component names exported by @studiometa/ui.
+ * Keep in sync with packages/ui/index.ts exports.
+ */
+export const UI_COMPONENT_NAMES = new Set([
+ 'Accordion',
+ 'AccordionItem',
+ 'Action',
+ 'AnchorNav',
+ 'AnchorNavLink',
+ 'AnchorNavTarget',
+ 'CircularMarquee',
+ 'Cursor',
+ 'DataBind',
+ 'DataComputed',
+ 'DataEffect',
+ 'DataModel',
+ 'Draggable',
+ 'Figure',
+ 'FigureVideo',
+ 'Frame',
+ 'FrameAnchor',
+ 'FrameForm',
+ 'FrameTarget',
+ 'FrameLoader',
+ 'Hoverable',
+ 'LargeText',
+ 'LazyInclude',
+ 'Menu',
+ 'MenuBtn',
+ 'MenuList',
+ 'Modal',
+ 'Panel',
+ 'AbstractPrefetch',
+ 'PrefetchWhenOver',
+ 'PrefetchWhenVisible',
+ 'AbstractScrollAnimation',
+ 'ScrollAnimationTimeline',
+ 'ScrollAnimationTarget',
+ 'ScrollReveal',
+ 'Sentinel',
+ 'Slider',
+ 'SliderItem',
+ 'SliderDrag',
+ 'Sticky',
+ 'Tabs',
+ 'Transition',
+]);
+
+/**
+ * Returns the local name of the superclass for a class declaration/expression.
+ */
+export function getSuperClassName(node: Node): string | null {
+ if (node.type !== 'ClassDeclaration' && node.type !== 'ClassExpression') return null;
+ if (!node.superClass) return null;
+ if (node.superClass.type === 'Identifier') return node.superClass.name;
+ return null;
+}
+
+/**
+ * Returns true when a class extends Base (directly or via a toolkit import).
+ */
+export function isBaseSubclass(node: Node, context: RuleContext): boolean {
+ const superName = getSuperClassName(node);
+ if (!superName) return false;
+ if (superName === 'Base') return true;
+
+ const sourceCode = context.sourceCode ?? context.getSourceCode?.();
+ const ast = sourceCode?.ast;
+ if (!ast) return false;
+
+ for (const n of ast.body) {
+ if (n.type !== 'ImportDeclaration') continue;
+ if (n.source.value !== TOOLKIT_PACKAGE) continue;
+ for (const specifier of n.specifiers) {
+ if (specifier.type === 'ImportSpecifier' && specifier.local.name === superName) return true;
+ }
+ }
+
+ return false;
+}
+
+/**
+ * Returns true when a class extends a component imported from @studiometa/ui.
+ */
+export function isUISubclass(node: Node, context: RuleContext): boolean {
+ const superName = getSuperClassName(node);
+ if (!superName) return false;
+
+ const sourceCode = context.sourceCode ?? context.getSourceCode?.();
+ const ast = sourceCode?.ast;
+ if (!ast) return false;
+
+ for (const n of ast.body) {
+ if (n.type !== 'ImportDeclaration') continue;
+ if (n.source.value !== UI_PACKAGE) continue;
+ for (const specifier of n.specifiers) {
+ if (specifier.type === 'ImportSpecifier' && specifier.local.name === superName) return true;
+ }
+ }
+
+ return false;
+}
+
+/**
+ * Returns true when className is already imported from @studiometa/ui.
+ */
+export function isImportedFromUI(className: string, context: RuleContext): boolean {
+ const sourceCode = context.sourceCode ?? context.getSourceCode?.();
+ const ast = sourceCode?.ast;
+ if (!ast) return false;
+
+ for (const n of ast.body) {
+ if (n.type !== 'ImportDeclaration') continue;
+ if (n.source.value !== UI_PACKAGE) continue;
+ for (const specifier of n.specifiers) {
+ if (specifier.type === 'ImportSpecifier' && specifier.imported?.name === className)
+ return true;
+ }
+ }
+
+ return false;
+}
+
+/**
+ * Walks up ancestor nodes to find the nearest class declaration/expression.
+ */
+export function findEnclosingClass(ancestors: Node[]): Node | null {
+ for (let i = ancestors.length - 1; i >= 0; i--) {
+ const node = ancestors[i];
+ if (node.type === 'ClassDeclaration' || node.type === 'ClassExpression') return node;
+ }
+ return null;
+}
+
+export function getAncestors(context: RuleContext, node: Node): Node[] {
+ return context.getAncestors?.() ?? context.sourceCode?.getAncestors?.(node) ?? [];
+}
+
+/**
+ * Returns all method definitions in a class body by name.
+ */
+export function getClassMethods(classNode: Node): Map {
+ const methods = new Map();
+ for (const member of classNode.body?.body ?? []) {
+ if (member.type === 'MethodDefinition' && member.key?.type === 'Identifier') {
+ methods.set(member.key.name, member);
+ }
+ }
+ return methods;
+}
diff --git a/packages/eslint-plugin-ui/src/utils/rule-tester.ts b/packages/eslint-plugin-ui/src/utils/rule-tester.ts
new file mode 100644
index 00000000..a9f6bf55
--- /dev/null
+++ b/packages/eslint-plugin-ui/src/utils/rule-tester.ts
@@ -0,0 +1,22 @@
+import { RuleTester } from 'eslint';
+import { eslintCompatPlugin } from '@oxlint/plugins';
+
+export { RuleTester };
+
+const _tester = new RuleTester({
+ languageOptions: {
+ ecmaVersion: 'latest',
+ sourceType: 'module',
+ },
+});
+
+export const tester = {
+ run(
+ name: string,
+ rule: Parameters[0]['rules'][string],
+ tests: Parameters['run']>[2],
+ ) {
+ const wrapped = eslintCompatPlugin({ rules: { [name]: rule } });
+ _tester.run(name, wrapped.rules[name] as any, tests);
+ },
+};
diff --git a/packages/eslint-plugin-ui/tsconfig.json b/packages/eslint-plugin-ui/tsconfig.json
new file mode 100644
index 00000000..b99b8425
--- /dev/null
+++ b/packages/eslint-plugin-ui/tsconfig.json
@@ -0,0 +1,13 @@
+{
+ "extends": "../../tsconfig.json",
+ "compilerOptions": {
+ "rootDir": "./src",
+ "outDir": "./dist",
+ "noEmit": false,
+ "emitDeclarationOnly": true,
+ "declaration": true,
+ "allowImportingTsExtensions": true
+ },
+ "include": ["./src/**/*.ts"],
+ "exclude": ["dist", "node_modules", "**/*.test.ts"]
+}
diff --git a/packages/eslint-plugin-ui/vitest.config.ts b/packages/eslint-plugin-ui/vitest.config.ts
new file mode 100644
index 00000000..5c5ff27b
--- /dev/null
+++ b/packages/eslint-plugin-ui/vitest.config.ts
@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+ test: {
+ include: ['src/**/*.test.ts'],
+ coverage: {
+ provider: 'v8',
+ include: ['src/**/*.ts'],
+ exclude: ['src/**/*.test.ts', 'src/utils/rule-tester.ts'],
+ },
+ },
+});
diff --git a/tsconfig.json b/tsconfig.json
index 1d1efc9b..48d83714 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -9,7 +9,7 @@
"noEmit": true,
"noImplicitThis": true,
"esModuleInterop": true,
- "moduleResolution": "node",
+ "moduleResolution": "bundler",
"skipLibCheck": true,
"paths": {
"#private/*": ["./packages/ui/*"],