@cratis/eslint-plugin-components 0.0.0

package/README.md

@@ -0,0 +1,43 @@
+# @cratis/eslint-plugin-components
+
+ESLint rules for projects that consume Cratis Components. Compose these on top of the
+Cratis base config, [`@cratis/eslint-config`](https://www.npmjs.com/package/@cratis/eslint-config).
+
+| Rule | What it does |
+|---|---|
+| `no-root-barrel-import` | Disallows importing from the `@cratis/components` root barrel. Use a subpath export (`@cratis/components/CommandDialog`, `@cratis/components/DataPage`, `@cratis/components/Toolbar`, …) — the root pulls the whole optional-peer-heavy surface and hides intent. |
+| `no-primereact-dialog` | Disallows importing `Dialog` from `primereact/dialog`. Use `CommandDialog` from `@cratis/components/CommandDialog`, or `Dialog` from `@cratis/components/Dialogs` — the wrappers add Arc command binding, overlay/focus fixes, and theming. |
+
+Both cover `import` and re-`export … from` forms.
+
+## Install
+
+```sh
+yarn add -D @cratis/eslint-plugin-components @cratis/eslint-config eslint
+```
+
+## Use
+
+```js
+// eslint.config.mjs
+import cratis from '@cratis/eslint-config';
+import components from '@cratis/eslint-plugin-components';
+
+export default [
+    ...cratis.configs.consumer,
+    ...components.configs.recommended,
+    // …your project rules
+];
+```
+
+### Options
+
+```js
+'@cratis/components/no-root-barrel-import': ['error', {
+    packageName: '@cratis/components',  // barrel to forbid
+    allow: [],                          // exact specifiers to permit
+}],
+'@cratis/components/no-primereact-dialog': ['error', {
+    source: 'primereact/dialog',        // module to forbid
+}],
+```

package/index.js

@@ -0,0 +1,41 @@
+import { createRequire } from 'node:module';
+import { noPrimereactDialog } from './lib/noPrimereactDialog.js';
+import { noRootBarrelImport } from './lib/noRootBarrelImport.js';
+
+const { version } = createRequire(import.meta.url)('./package.json');
+
+// A single flat-config plugin object — meta + rules + self-referencing configs — per the
+// ESLint flat-config plugin convention. The default export IS the plugin, so consumers
+// get `components.meta`, `components.rules`, and `components.configs` directly. Composes
+// on top of @cratis/eslint-config.
+const plugin = {
+    meta: { name: '@cratis/eslint-plugin-components', version },
+    rules: {
+        'no-primereact-dialog': noPrimereactDialog,
+        'no-root-barrel-import': noRootBarrelImport,
+    },
+    configs: {},
+};
+
+// configs reference the plugin itself, so they are assigned after it exists.
+//
+//   import cratis from '@cratis/eslint-config';
+//   import components from '@cratis/eslint-plugin-components';
+//   export default [...cratis.configs.consumer, ...components.configs.recommended];
+Object.assign(plugin.configs, {
+    recommended: [
+        {
+            name: '@cratis/components/recommended',
+            files: ['**/*.ts', '**/*.tsx'],
+            plugins: { '@cratis/components': plugin },
+            rules: {
+                '@cratis/components/no-primereact-dialog': 'error',
+                '@cratis/components/no-root-barrel-import': 'error',
+            },
+        },
+    ],
+});
+
+export default plugin;
+export const { configs, rules, meta } = plugin;
+export { noPrimereactDialog, noRootBarrelImport };

package/lib/noPrimereactDialog.js

@@ -0,0 +1,45 @@
+const DEFAULTS = { source: 'primereact/dialog' };
+
+// Disallow importing PrimeReact's Dialog directly. Cratis Components wraps it with
+// behavior (Arc command binding, overlay/focus fixes, theming) via CommandDialog and the
+// Dialogs surface; reaching past those to `primereact/dialog` bypasses all of it. Covers
+// `import` and re-`export … from` forms.
+export const noPrimereactDialog = {
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Disallow importing Dialog from primereact/dialog; use the Cratis Components dialog wrappers.',
+            recommended: true,
+            url: 'https://github.com/Cratis/Components/blob/main/ESLint/README.md',
+        },
+        schema: [{
+            type: 'object',
+            properties: {
+                source: { type: 'string' },
+            },
+            additionalProperties: false,
+        }],
+        messages: {
+            useWrapper: "Do not import from '{{source}}'. Use CommandDialog from '@cratis/components/CommandDialog', or Dialog from '@cratis/components/Dialogs'.",
+        },
+    },
+    create(context) {
+        const options = { ...DEFAULTS, ...(context.options[0] ?? {}) };
+
+        const check = node => {
+            const source = node.source;
+            if (!source || typeof source.value !== 'string') return;
+            if (source.value === options.source) {
+                context.report({ node: source, messageId: 'useWrapper', data: { source: options.source } });
+            }
+        };
+
+        return {
+            ImportDeclaration: check,
+            ExportNamedDeclaration: check,
+            ExportAllDeclaration: check,
+        };
+    },
+};
+
+export default noPrimereactDialog;

package/lib/noRootBarrelImport.js

@@ -0,0 +1,48 @@
+const DEFAULTS = { packageName: '@cratis/components', allow: [] };
+
+// Disallow importing from the Cratis Components root barrel. The package exposes
+// purpose-built subpath exports (`@cratis/components/CommandDialog`,
+// `@cratis/components/DataPage`, `@cratis/components/Toolbar`, …); importing the root
+// pulls the whole optional-peer-heavy surface and hides intent. Covers `import` and
+// re-`export … from` forms.
+export const noRootBarrelImport = {
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Disallow importing from the @cratis/components root barrel; use a subpath export.',
+            recommended: true,
+            url: 'https://github.com/Cratis/Components/blob/main/ESLint/README.md',
+        },
+        schema: [{
+            type: 'object',
+            properties: {
+                packageName: { type: 'string' },
+                allow: { type: 'array', items: { type: 'string' } },
+            },
+            additionalProperties: false,
+        }],
+        messages: {
+            useSubpath: "Import from a '{{packageName}}' subpath (e.g. '{{packageName}}/CommandDialog'), not the package root barrel.",
+        },
+    },
+    create(context) {
+        const options = { ...DEFAULTS, ...(context.options[0] ?? {}) };
+        const allow = new Set(options.allow);
+
+        const check = node => {
+            const source = node.source;
+            if (!source || typeof source.value !== 'string') return;
+            if (source.value === options.packageName && !allow.has(source.value)) {
+                context.report({ node: source, messageId: 'useSubpath', data: { packageName: options.packageName } });
+            }
+        };
+
+        return {
+            ImportDeclaration: check,
+            ExportNamedDeclaration: check,
+            ExportAllDeclaration: check,
+        };
+    },
+};
+
+export default noRootBarrelImport;

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@cratis/eslint-plugin-components",
+  "version": "0.0.0",
+  "description": "Cratis Components ESLint rules: import from subpaths, not the root barrel, and use the Cratis dialog wrappers instead of primereact/dialog. Compose on top of @cratis/eslint-config.",
+  "author": "Cratis",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Cratis/Components"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "cratis",
+    "components"
+  ],
+  "files": [
+    "index.js",
+    "lib",
+    "README.md"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./index.js"
+  },
+  "scripts": {
+    "test": "yarn g:test",
+    "ci": "yarn g:test"
+  },
+  "peerDependencies": {
+    "eslint": ">=9"
+  }
+}