@adea-ai/ui 0.78.2 → 0.79.0

package/dist/lint/index.d.ts

@@ -28,6 +28,7 @@ declare const plugin: {
     rules: {
         'no-raw-interactive-elements': RuleModule;
         'no-primitive-library-imports': RuleModule;
+        'no-interactive-wrappers': RuleModule;
     };
 };
 export default plugin;

package/dist/lint/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lint/index.ts"],"names":[],"mappings":"AAmBA,KAAK,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAA;AAa/E,KAAK,UAAU,GAAG;IAChB,IAAI,EAAE;QACJ,IAAI,EAAE,SAAS,CAAA;QACf,IAAI,EAAE;YAAE,WAAW,EAAE,MAAM,CAAA;SAAE,CAAA;QAC7B,MAAM,EAAE,IAAI,EAAE,CAAA;QACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KACjC,CAAA;IACD,MAAM,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAC,CAAA;CACtE,CAAA;AAED,UAAU,WAAW;IACnB,OAAO,CAAC,EAAE,OAAO,EAAE,CAAA;IACnB,MAAM,EAAE,CAAC,UAAU,EAAE;QACnB,IAAI,EAAE,OAAO,CAAA;QACb,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;KAC5B,KAAK,IAAI,CAAA;CACX;AAwHD,QAAA,MAAM,MAAM;;;;;;;;CAMX,CAAA;AAED,eAAe,MAAM,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lint/index.ts"],"names":[],"mappings":"AAmBA,KAAK,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAA;AAa/E,KAAK,UAAU,GAAG;IAChB,IAAI,EAAE;QACJ,IAAI,EAAE,SAAS,CAAA;QACf,IAAI,EAAE;YAAE,WAAW,EAAE,MAAM,CAAA;SAAE,CAAA;QAC7B,MAAM,EAAE,IAAI,EAAE,CAAA;QACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KACjC,CAAA;IACD,MAAM,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAC,CAAA;CACtE,CAAA;AAED,UAAU,WAAW;IACnB,OAAO,CAAC,EAAE,OAAO,EAAE,CAAA;IACnB,MAAM,EAAE,CAAC,UAAU,EAAE;QACnB,IAAI,EAAE,OAAO,CAAA;QACb,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;KAC5B,KAAK,IAAI,CAAA;CACX;AA2QD,QAAA,MAAM,MAAM;;;;;;;;;CAOX,CAAA;AAED,eAAe,MAAM,CAAA"}

package/dist/lint.js

@@ -75,6 +75,87 @@ var DEFAULT_PRIMITIVE_PACKAGES = Object.freeze([
 	"radix-ui",
 	"@base-ui-components"
 ]);
+/**
+* The interactive ARIA roles an application can dress a generic element in, and
+* the primitive that owns each role. `link` is deliberately absent: an `<a>` is
+* natively interactive and Button itself supports `as="a"` for the link-styled
+* case.
+*/
+var ROLE_PRIMITIVES = Object.freeze({
+	button: {
+		primitive: "Button",
+		path: "@adea-ai/ui/components/ui/button"
+	},
+	checkbox: {
+		primitive: "Checkbox",
+		path: "@adea-ai/ui/components/ui/checkbox"
+	},
+	radio: {
+		primitive: "RadioGroup",
+		path: "@adea-ai/ui/components/ui/radio-group"
+	},
+	switch: {
+		primitive: "Switch",
+		path: "@adea-ai/ui/components/ui/switch"
+	},
+	tab: {
+		primitive: "Tabs",
+		path: "@adea-ai/ui/components/ui/tabs"
+	},
+	option: {
+		primitive: "Select",
+		path: "@adea-ai/ui/components/ui/select"
+	},
+	menuitem: {
+		primitive: "DropdownMenu",
+		path: "@adea-ai/ui/components/ui/dropdown-menu"
+	},
+	textbox: {
+		primitive: "Input",
+		path: "@adea-ai/ui/components/ui/input"
+	}
+});
+/**
+* The elements whose only job is layout or text. A click handler or a tabindex on
+* one of these is a control being hand-built out of a non-control.
+*/
+var GENERIC_ELEMENTS = /* @__PURE__ */ new Set([
+	"div",
+	"span",
+	"li",
+	"ul",
+	"ol",
+	"td",
+	"th",
+	"p",
+	"h1",
+	"h2",
+	"h3",
+	"h4",
+	"h5",
+	"h6",
+	"section",
+	"article",
+	"aside",
+	"header",
+	"footer",
+	"nav",
+	"main",
+	"img",
+	"svg"
+]);
+var CLICK_HANDLERS = /* @__PURE__ */ new Set(["onClick", "onDoubleClick"]);
+/** Reads a static `role` value; a dynamic role is undecidable statically, so it is left to review. */
+var roleOf = (node) => {
+	for (const attribute of node.attributes ?? []) {
+		if (attribute.type !== "JSXAttribute" || attribute.name?.name !== "role") continue;
+		if (attribute.value?.type === "Literal" && typeof attribute.value.value === "string") return attribute.value.value;
+		return null;
+	}
+	return null;
+};
+/** Whether the element carries the attribute, by name. */
+var has = (node, name) => (node.attributes ?? []).some((attribute) => attribute.type === "JSXAttribute" && attribute.name?.name === name);
 var plugin = {
 	meta: { name: "adea" },
 	rules: {
@@ -121,6 +202,75 @@ var plugin = {
 					}
 				};
 			}
+		},
+		"no-interactive-wrappers": {
+			meta: {
+				type: "problem",
+				docs: { description: "Generic elements dressed as interactive controls — an interactive role, a click handler or a tabindex on a layout element — re-implement a primitive by hand. Compose the real component." },
+				schema: [{
+					type: "object",
+					properties: {
+						allow: {
+							type: "array",
+							items: { type: "string" }
+						},
+						message: { type: "string" }
+					},
+					additionalProperties: false
+				}],
+				messages: {
+					roleWrapper: "A {{element}} with role=\"{{role}}\" hand-builds {{primitive}}: use {{primitive}} from {{path}}. The primitive brings keyboard activation, focus behaviour and ARIA wiring; the wrapper re-implements them badly.",
+					clickWrapper: "A click handler on {{element}} composes {{primitive}} by hand: use {{primitive}} from {{path}}. A div that reacts to clicks is a button that cannot be reached by keyboard.",
+					tabindexWrapper: "A tabindex on {{element}} makes a layout element focusable, which is focus management the primitives already own: compose the real component instead."
+				}
+			},
+			create(context) {
+				const options = context.options?.[0] ?? {};
+				const allowed = new Set(options.allow ?? []);
+				return { JSXOpeningElement(node) {
+					if (node.name?.type !== "JSXIdentifier") return;
+					const element = node.name.name;
+					if (allowed.has(element) || element in ELEMENT_PRIMITIVES) return;
+					const role = roleOf(node);
+					if (role && role in ROLE_PRIMITIVES) {
+						const target = ROLE_PRIMITIVES[role];
+						context.report({
+							node,
+							messageId: "roleWrapper",
+							data: {
+								element,
+								role,
+								primitive: target.primitive,
+								path: target.path
+							},
+							...options.message ? { message: options.message } : {}
+						});
+						return;
+					}
+					if (GENERIC_ELEMENTS.has(element)) {
+						if ([...CLICK_HANDLERS].find((handler) => has(node, handler))) {
+							const target = ROLE_PRIMITIVES.button;
+							context.report({
+								node,
+								messageId: "clickWrapper",
+								data: {
+									element,
+									primitive: target.primitive,
+									path: target.path
+								},
+								...options.message ? { message: options.message } : {}
+							});
+							return;
+						}
+						if (has(node, "tabIndex") || has(node, "tabindex")) context.report({
+							node,
+							messageId: "tabindexWrapper",
+							data: { element },
+							...options.message ? { message: options.message } : {}
+						});
+					}
+				} };
+			}
 		}
 	}
 };

package/dist/lint.js.map

@@ -1 +1 @@
-{"version":3,"file":"lint.js","names":[],"sources":["../src/lint/index.ts"],"sourcesContent":["/*\n * The design system's own oxlint plugin.\n *\n * The styling rules live in `@shadcn/lint`; what that plugin cannot know is which\n * *elements* the design system owns. This is the other half of the contract, for\n * the applications that consume the library: an interactive element this package\n * provides is not re-implemented at the application layer, and the primitive\n * libraries this package is built from are not imported around it.\n *\n * Loaded as an oxlint jsPlugin:\n *\n *   // .oxlintrc.json\n *   { \"jsPlugins\": [\"@adea-ai/ui/lint\"], \"rules\": { \"adea/no-raw-interactive-elements\": \"error\" } }\n *\n * Rules are errors by intent. A violation means an application composed its own\n * control out of raw markup — unreachable focus behaviour, an absent keyboard\n * story, a second implementation of a decision this package exists to make once.\n */\n\ntype Json = string | number | boolean | null | Json[] | { [key: string]: Json }\n\n/** The raw elements this package replaces, and the primitive that replaces them. */\nconst ELEMENT_PRIMITIVES: Readonly<Record<string, { primitive: string; path: string }>> =\n  Object.freeze({\n    button: { primitive: 'Button', path: '@adea-ai/ui/components/ui/button' },\n    input: { primitive: 'Input', path: '@adea-ai/ui/components/ui/input' },\n    textarea: { primitive: 'Textarea', path: '@adea-ai/ui/components/ui/textarea' },\n    select: { primitive: 'Select', path: '@adea-ai/ui/components/ui/select' },\n    option: { primitive: 'Select', path: '@adea-ai/ui/components/ui/select' },\n    label: { primitive: 'Label', path: '@adea-ai/ui/components/ui/label' },\n  })\n\ntype RuleModule = {\n  meta: {\n    type: 'problem'\n    docs: { description: string }\n    schema: Json[]\n    messages: Record<string, string>\n  }\n  create: (context: LintContext) => Record<string, (node: any) => void>\n}\n\ninterface LintContext {\n  options?: unknown[]\n  report: (descriptor: {\n    node: unknown\n    messageId?: string\n    message?: string\n    data?: Record<string, Json>\n  }) => void\n}\n\ninterface RawElementOptions {\n  /** Element names this rule should not report (rare; prefer fixing the file). */\n  allow?: string[]\n  /** Replaces the default report message. */\n  message?: string\n}\n\nconst noRawInteractiveElements: RuleModule = {\n  meta: {\n    type: 'problem',\n    docs: {\n      description:\n        'Interactive elements this package provides (button, input, textarea, select, option, label) are composed from the package, not written as raw markup.',\n    },\n    schema: [\n      {\n        type: 'object',\n        properties: {\n          allow: { type: 'array', items: { type: 'string' } },\n          message: { type: 'string' },\n        },\n        additionalProperties: false,\n      },\n    ],\n    messages: {\n      rawElement:\n        '{{element}} is provided by the design system: use {{primitive}} from {{path}}. A raw element has no keyboard story, no focus behaviour and no token styling — that is the work the primitive already did.',\n    },\n  },\n  create(context) {\n    const options = (context.options?.[0] ?? {}) as RawElementOptions\n    const allowed = new Set(options.allow ?? [])\n    const emit = (node: unknown, element: string) => {\n      const target = ELEMENT_PRIMITIVES[element]!\n      context.report({\n        node,\n        messageId: 'rawElement',\n        data: { element, primitive: target.primitive, path: target.path },\n        ...(options.message ? { message: options.message } : {}),\n      })\n    }\n    return {\n      JSXOpeningElement(node: any) {\n        if (node.name?.type !== 'JSXIdentifier') return\n        const element = node.name.name\n        if (!(element in ELEMENT_PRIMITIVES) || allowed.has(element)) return\n        emit(node, element)\n      },\n    }\n  },\n}\n\ninterface PrimitiveImportOptions {\n  /** Package prefixes this rule reports. Defaults to the primitive libraries the ui package wraps. */\n  packages?: string[]\n  /** Replaces the default report message. */\n  message?: string\n}\n\nconst DEFAULT_PRIMITIVE_PACKAGES = Object.freeze([\n  '@kobalte/core',\n  '@ark-ui',\n  '@zag-js',\n  '@radix-ui',\n  'radix-ui',\n  '@base-ui-components',\n])\n\nconst noPrimitiveLibraryImports: RuleModule = {\n  meta: {\n    type: 'problem',\n    docs: {\n      description:\n        'The primitive libraries the design system is built on (Kobalte and friends) are its internal affair — compose the exported components instead of importing the primitives.',\n    },\n    schema: [\n      {\n        type: 'object',\n        properties: {\n          packages: { type: 'array', items: { type: 'string' } },\n          message: { type: 'string' },\n        },\n        additionalProperties: false,\n      },\n    ],\n    messages: {\n      primitiveImport:\n        'Import from the design system, not from {{package}}: the primitives it wraps carry the focus, keyboard and ARIA behaviour the components exist to provide.',\n    },\n  },\n  create(context) {\n    const options = (context.options?.[0] ?? {}) as PrimitiveImportOptions\n    const prefixes = options.packages ?? DEFAULT_PRIMITIVE_PACKAGES\n    const offender = (source: unknown): string | null => {\n      const name = String(source ?? '')\n      return prefixes.find((prefix) => name === prefix || name.startsWith(`${prefix}/`)) ?? null\n    }\n    const report = (node: unknown, source: unknown) => {\n      const pkg = offender(source)!\n      context.report({\n        node,\n        messageId: 'primitiveImport',\n        data: { package: pkg },\n        ...(options.message ? { message: options.message } : {}),\n      })\n    }\n    return {\n      ImportDeclaration(node: any) {\n        if (offender(node.source?.value)) report(node, node.source.value)\n      },\n      ImportExpression(node: any) {\n        if (typeof node.source?.value === 'string' && offender(node.source.value))\n          report(node, node.source.value)\n      },\n    }\n  },\n}\n\nconst plugin = {\n  meta: { name: 'adea' },\n  rules: {\n    'no-raw-interactive-elements': noRawInteractiveElements,\n    'no-primitive-library-imports': noPrimitiveLibraryImports,\n  },\n}\n\nexport default plugin\n"],"mappings":";;AAsBA,IAAM,qBACJ,OAAO,OAAO;CACZ,QAAQ;EAAE,WAAW;EAAU,MAAM;CAAmC;CACxE,OAAO;EAAE,WAAW;EAAS,MAAM;CAAkC;CACrE,UAAU;EAAE,WAAW;EAAY,MAAM;CAAqC;CAC9E,QAAQ;EAAE,WAAW;EAAU,MAAM;CAAmC;CACxE,QAAQ;EAAE,WAAW;EAAU,MAAM;CAAmC;CACxE,OAAO;EAAE,WAAW;EAAS,MAAM;CAAkC;AACvE,CAAC;AA6BH,IAAM,2BAAuC;CAC3C,MAAM;EACJ,MAAM;EACN,MAAM,EACJ,aACE,wJACJ;EACA,QAAQ,CACN;GACE,MAAM;GACN,YAAY;IACV,OAAO;KAAE,MAAM;KAAS,OAAO,EAAE,MAAM,SAAS;IAAE;IAClD,SAAS,EAAE,MAAM,SAAS;GAC5B;GACA,sBAAsB;EACxB,CACF;EACA,UAAU,EACR,YACE,4MACJ;CACF;CACA,OAAO,SAAS;EACd,MAAM,UAAW,QAAQ,UAAU,MAAM,CAAC;EAC1C,MAAM,UAAU,IAAI,IAAI,QAAQ,SAAS,CAAC,CAAC;EAC3C,MAAM,QAAQ,MAAe,YAAoB;GAC/C,MAAM,SAAS,mBAAmB;GAClC,QAAQ,OAAO;IACb;IACA,WAAW;IACX,MAAM;KAAE;KAAS,WAAW,OAAO;KAAW,MAAM,OAAO;IAAK;IAChE,GAAI,QAAQ,UAAU,EAAE,SAAS,QAAQ,QAAQ,IAAI,CAAC;GACxD,CAAC;EACH;EACA,OAAO,EACL,kBAAkB,MAAW;GAC3B,IAAI,KAAK,MAAM,SAAS,iBAAiB;GACzC,MAAM,UAAU,KAAK,KAAK;GAC1B,IAAI,EAAE,WAAW,uBAAuB,QAAQ,IAAI,OAAO,GAAG;GAC9D,KAAK,MAAM,OAAO;EACpB,EACF;CACF;AACF;AASA,IAAM,6BAA6B,OAAO,OAAO;CAC/C;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;AAoDD,IAAM,SAAS;CACb,MAAM,EAAE,MAAM,OAAO;CACrB,OAAO;EACL,+BAA+B;EAC/B,gCAAgC;GArDlC,MAAM;IACJ,MAAM;IACN,MAAM,EACJ,aACE,6KACJ;IACA,QAAQ,CACN;KACE,MAAM;KACN,YAAY;MACV,UAAU;OAAE,MAAM;OAAS,OAAO,EAAE,MAAM,SAAS;MAAE;MACrD,SAAS,EAAE,MAAM,SAAS;KAC5B;KACA,sBAAsB;IACxB,CACF;IACA,UAAU,EACR,iBACE,6JACJ;GACF;GACA,OAAO,SAAS;IACd,MAAM,UAAW,QAAQ,UAAU,MAAM,CAAC;IAC1C,MAAM,WAAW,QAAQ,YAAY;IACrC,MAAM,YAAY,WAAmC;KACnD,MAAM,OAAO,OAAO,UAAU,EAAE;KAChC,OAAO,SAAS,MAAM,WAAW,SAAS,UAAU,KAAK,WAAW,GAAG,OAAO,EAAE,CAAC,KAAK;IACxF;IACA,MAAM,UAAU,MAAe,WAAoB;KACjD,MAAM,MAAM,SAAS,MAAM;KAC3B,QAAQ,OAAO;MACb;MACA,WAAW;MACX,MAAM,EAAE,SAAS,IAAI;MACrB,GAAI,QAAQ,UAAU,EAAE,SAAS,QAAQ,QAAQ,IAAI,CAAC;KACxD,CAAC;IACH;IACA,OAAO;KACL,kBAAkB,MAAW;MAC3B,IAAI,SAAS,KAAK,QAAQ,KAAK,GAAG,OAAO,MAAM,KAAK,OAAO,KAAK;KAClE;KACA,iBAAiB,MAAW;MAC1B,IAAI,OAAO,KAAK,QAAQ,UAAU,YAAY,SAAS,KAAK,OAAO,KAAK,GACtE,OAAO,MAAM,KAAK,OAAO,KAAK;KAClC;IACF;GACF;EAOkC;CAClC;AACF"}
+{"version":3,"file":"lint.js","names":[],"sources":["../src/lint/index.ts"],"sourcesContent":["/*\n * The design system's own oxlint plugin.\n *\n * The styling rules live in `@shadcn/lint`; what that plugin cannot know is which\n * *elements* the design system owns. This is the other half of the contract, for\n * the applications that consume the library: an interactive element this package\n * provides is not re-implemented at the application layer, and the primitive\n * libraries this package is built from are not imported around it.\n *\n * Loaded as an oxlint jsPlugin:\n *\n *   // .oxlintrc.json\n *   { \"jsPlugins\": [\"@adea-ai/ui/lint\"], \"rules\": { \"adea/no-raw-interactive-elements\": \"error\" } }\n *\n * Rules are errors by intent. A violation means an application composed its own\n * control out of raw markup — unreachable focus behaviour, an absent keyboard\n * story, a second implementation of a decision this package exists to make once.\n */\n\ntype Json = string | number | boolean | null | Json[] | { [key: string]: Json }\n\n/** The raw elements this package replaces, and the primitive that replaces them. */\nconst ELEMENT_PRIMITIVES: Readonly<Record<string, { primitive: string; path: string }>> =\n  Object.freeze({\n    button: { primitive: 'Button', path: '@adea-ai/ui/components/ui/button' },\n    input: { primitive: 'Input', path: '@adea-ai/ui/components/ui/input' },\n    textarea: { primitive: 'Textarea', path: '@adea-ai/ui/components/ui/textarea' },\n    select: { primitive: 'Select', path: '@adea-ai/ui/components/ui/select' },\n    option: { primitive: 'Select', path: '@adea-ai/ui/components/ui/select' },\n    label: { primitive: 'Label', path: '@adea-ai/ui/components/ui/label' },\n  })\n\ntype RuleModule = {\n  meta: {\n    type: 'problem'\n    docs: { description: string }\n    schema: Json[]\n    messages: Record<string, string>\n  }\n  create: (context: LintContext) => Record<string, (node: any) => void>\n}\n\ninterface LintContext {\n  options?: unknown[]\n  report: (descriptor: {\n    node: unknown\n    messageId?: string\n    message?: string\n    data?: Record<string, Json>\n  }) => void\n}\n\ninterface RawElementOptions {\n  /** Element names this rule should not report (rare; prefer fixing the file). */\n  allow?: string[]\n  /** Replaces the default report message. */\n  message?: string\n}\n\nconst noRawInteractiveElements: RuleModule = {\n  meta: {\n    type: 'problem',\n    docs: {\n      description:\n        'Interactive elements this package provides (button, input, textarea, select, option, label) are composed from the package, not written as raw markup.',\n    },\n    schema: [\n      {\n        type: 'object',\n        properties: {\n          allow: { type: 'array', items: { type: 'string' } },\n          message: { type: 'string' },\n        },\n        additionalProperties: false,\n      },\n    ],\n    messages: {\n      rawElement:\n        '{{element}} is provided by the design system: use {{primitive}} from {{path}}. A raw element has no keyboard story, no focus behaviour and no token styling — that is the work the primitive already did.',\n    },\n  },\n  create(context) {\n    const options = (context.options?.[0] ?? {}) as RawElementOptions\n    const allowed = new Set(options.allow ?? [])\n    const emit = (node: unknown, element: string) => {\n      const target = ELEMENT_PRIMITIVES[element]!\n      context.report({\n        node,\n        messageId: 'rawElement',\n        data: { element, primitive: target.primitive, path: target.path },\n        ...(options.message ? { message: options.message } : {}),\n      })\n    }\n    return {\n      JSXOpeningElement(node: any) {\n        if (node.name?.type !== 'JSXIdentifier') return\n        const element = node.name.name\n        if (!(element in ELEMENT_PRIMITIVES) || allowed.has(element)) return\n        emit(node, element)\n      },\n    }\n  },\n}\n\ninterface PrimitiveImportOptions {\n  /** Package prefixes this rule reports. Defaults to the primitive libraries the ui package wraps. */\n  packages?: string[]\n  /** Replaces the default report message. */\n  message?: string\n}\n\nconst DEFAULT_PRIMITIVE_PACKAGES = Object.freeze([\n  '@kobalte/core',\n  '@ark-ui',\n  '@zag-js',\n  '@radix-ui',\n  'radix-ui',\n  '@base-ui-components',\n])\n\n/**\n * The interactive ARIA roles an application can dress a generic element in, and\n * the primitive that owns each role. `link` is deliberately absent: an `<a>` is\n * natively interactive and Button itself supports `as=\"a\"` for the link-styled\n * case.\n */\nconst ROLE_PRIMITIVES: Readonly<Record<string, { primitive: string; path: string }>> =\n  Object.freeze({\n    button: { primitive: 'Button', path: '@adea-ai/ui/components/ui/button' },\n    checkbox: { primitive: 'Checkbox', path: '@adea-ai/ui/components/ui/checkbox' },\n    radio: { primitive: 'RadioGroup', path: '@adea-ai/ui/components/ui/radio-group' },\n    switch: { primitive: 'Switch', path: '@adea-ai/ui/components/ui/switch' },\n    tab: { primitive: 'Tabs', path: '@adea-ai/ui/components/ui/tabs' },\n    option: { primitive: 'Select', path: '@adea-ai/ui/components/ui/select' },\n    menuitem: { primitive: 'DropdownMenu', path: '@adea-ai/ui/components/ui/dropdown-menu' },\n    textbox: { primitive: 'Input', path: '@adea-ai/ui/components/ui/input' },\n  })\n\n/**\n * The elements whose only job is layout or text. A click handler or a tabindex on\n * one of these is a control being hand-built out of a non-control.\n */\nconst GENERIC_ELEMENTS: ReadonlySet<string> = new Set([\n  'div',\n  'span',\n  'li',\n  'ul',\n  'ol',\n  'td',\n  'th',\n  'p',\n  'h1',\n  'h2',\n  'h3',\n  'h4',\n  'h5',\n  'h6',\n  'section',\n  'article',\n  'aside',\n  'header',\n  'footer',\n  'nav',\n  'main',\n  'img',\n  'svg',\n])\n\nconst CLICK_HANDLERS: ReadonlySet<string> = new Set(['onClick', 'onDoubleClick'])\n\ninterface InteractiveWrapperOptions {\n  /** Element names this rule should not report (rare; prefer fixing the file). */\n  allow?: string[]\n  /** Replaces the default report message. */\n  message?: string\n}\n\n/** Reads a static `role` value; a dynamic role is undecidable statically, so it is left to review. */\nconst roleOf = (node: any): string | null => {\n  for (const attribute of node.attributes ?? []) {\n    if (attribute.type !== 'JSXAttribute' || attribute.name?.name !== 'role') continue\n    if (attribute.value?.type === 'Literal' && typeof attribute.value.value === 'string')\n      return attribute.value.value\n    return null\n  }\n  return null\n}\n\n/** Whether the element carries the attribute, by name. */\nconst has = (node: any, name: string): boolean =>\n  (node.attributes ?? []).some(\n    (attribute: any) => attribute.type === 'JSXAttribute' && attribute.name?.name === name\n  )\n\nconst noInteractiveWrappers: RuleModule = {\n  meta: {\n    type: 'problem',\n    docs: {\n      description:\n        'Generic elements dressed as interactive controls — an interactive role, a click handler or a tabindex on a layout element — re-implement a primitive by hand. Compose the real component.',\n    },\n    schema: [\n      {\n        type: 'object',\n        properties: {\n          allow: { type: 'array', items: { type: 'string' } },\n          message: { type: 'string' },\n        },\n        additionalProperties: false,\n      },\n    ],\n    messages: {\n      roleWrapper:\n        'A {{element}} with role=\"{{role}}\" hand-builds {{primitive}}: use {{primitive}} from {{path}}. The primitive brings keyboard activation, focus behaviour and ARIA wiring; the wrapper re-implements them badly.',\n      clickWrapper:\n        'A click handler on {{element}} composes {{primitive}} by hand: use {{primitive}} from {{path}}. A div that reacts to clicks is a button that cannot be reached by keyboard.',\n      tabindexWrapper:\n        'A tabindex on {{element}} makes a layout element focusable, which is focus management the primitives already own: compose the real component instead.',\n    },\n  },\n  create(context) {\n    const options = (context.options?.[0] ?? {}) as InteractiveWrapperOptions\n    const allowed = new Set(options.allow ?? [])\n    return {\n      JSXOpeningElement(node: any) {\n        if (node.name?.type !== 'JSXIdentifier') return\n        const element = node.name.name\n        if (allowed.has(element) || element in ELEMENT_PRIMITIVES) return\n\n        const role = roleOf(node)\n        if (role && role in ROLE_PRIMITIVES) {\n          const target = ROLE_PRIMITIVES[role]!\n          context.report({\n            node,\n            messageId: 'roleWrapper',\n            data: { element, role, primitive: target.primitive, path: target.path },\n            ...(options.message ? { message: options.message } : {}),\n          })\n          return\n        }\n\n        if (GENERIC_ELEMENTS.has(element)) {\n          const click = [...CLICK_HANDLERS].find((handler) => has(node, handler))\n          if (click) {\n            const target = ROLE_PRIMITIVES.button!\n            context.report({\n              node,\n              messageId: 'clickWrapper',\n              data: { element, primitive: target.primitive, path: target.path },\n              ...(options.message ? { message: options.message } : {}),\n            })\n            return\n          }\n          if (has(node, 'tabIndex') || has(node, 'tabindex')) {\n            context.report({\n              node,\n              messageId: 'tabindexWrapper',\n              data: { element },\n              ...(options.message ? { message: options.message } : {}),\n            })\n          }\n        }\n      },\n    }\n  },\n}\n\nconst noPrimitiveLibraryImports: RuleModule = {\n  meta: {\n    type: 'problem',\n    docs: {\n      description:\n        'The primitive libraries the design system is built on (Kobalte and friends) are its internal affair — compose the exported components instead of importing the primitives.',\n    },\n    schema: [\n      {\n        type: 'object',\n        properties: {\n          packages: { type: 'array', items: { type: 'string' } },\n          message: { type: 'string' },\n        },\n        additionalProperties: false,\n      },\n    ],\n    messages: {\n      primitiveImport:\n        'Import from the design system, not from {{package}}: the primitives it wraps carry the focus, keyboard and ARIA behaviour the components exist to provide.',\n    },\n  },\n  create(context) {\n    const options = (context.options?.[0] ?? {}) as PrimitiveImportOptions\n    const prefixes = options.packages ?? DEFAULT_PRIMITIVE_PACKAGES\n    const offender = (source: unknown): string | null => {\n      const name = String(source ?? '')\n      return prefixes.find((prefix) => name === prefix || name.startsWith(`${prefix}/`)) ?? null\n    }\n    const report = (node: unknown, source: unknown) => {\n      const pkg = offender(source)!\n      context.report({\n        node,\n        messageId: 'primitiveImport',\n        data: { package: pkg },\n        ...(options.message ? { message: options.message } : {}),\n      })\n    }\n    return {\n      ImportDeclaration(node: any) {\n        if (offender(node.source?.value)) report(node, node.source.value)\n      },\n      ImportExpression(node: any) {\n        if (typeof node.source?.value === 'string' && offender(node.source.value))\n          report(node, node.source.value)\n      },\n    }\n  },\n}\n\nconst plugin = {\n  meta: { name: 'adea' },\n  rules: {\n    'no-raw-interactive-elements': noRawInteractiveElements,\n    'no-primitive-library-imports': noPrimitiveLibraryImports,\n    'no-interactive-wrappers': noInteractiveWrappers,\n  },\n}\n\nexport default plugin\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adea-ai/ui",
-  "version": "0.78.2",
+  "version": "0.79.0",
   "description": "The Adea design system: Kobalte-backed Solid components, semantic OKLCH tokens, and the app-shell layout primitives shared by Adea and Cortana.",
   "keywords": [
     "adea",

package/src/lint/index.ts

@@ -118,6 +118,153 @@ const DEFAULT_PRIMITIVE_PACKAGES = Object.freeze([
   '@base-ui-components',
 ])
 
+/**
+ * The interactive ARIA roles an application can dress a generic element in, and
+ * the primitive that owns each role. `link` is deliberately absent: an `<a>` is
+ * natively interactive and Button itself supports `as="a"` for the link-styled
+ * case.
+ */
+const ROLE_PRIMITIVES: Readonly<Record<string, { primitive: string; path: string }>> =
+  Object.freeze({
+    button: { primitive: 'Button', path: '@adea-ai/ui/components/ui/button' },
+    checkbox: { primitive: 'Checkbox', path: '@adea-ai/ui/components/ui/checkbox' },
+    radio: { primitive: 'RadioGroup', path: '@adea-ai/ui/components/ui/radio-group' },
+    switch: { primitive: 'Switch', path: '@adea-ai/ui/components/ui/switch' },
+    tab: { primitive: 'Tabs', path: '@adea-ai/ui/components/ui/tabs' },
+    option: { primitive: 'Select', path: '@adea-ai/ui/components/ui/select' },
+    menuitem: { primitive: 'DropdownMenu', path: '@adea-ai/ui/components/ui/dropdown-menu' },
+    textbox: { primitive: 'Input', path: '@adea-ai/ui/components/ui/input' },
+  })
+
+/**
+ * The elements whose only job is layout or text. A click handler or a tabindex on
+ * one of these is a control being hand-built out of a non-control.
+ */
+const GENERIC_ELEMENTS: ReadonlySet<string> = new Set([
+  'div',
+  'span',
+  'li',
+  'ul',
+  'ol',
+  'td',
+  'th',
+  'p',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'section',
+  'article',
+  'aside',
+  'header',
+  'footer',
+  'nav',
+  'main',
+  'img',
+  'svg',
+])
+
+const CLICK_HANDLERS: ReadonlySet<string> = new Set(['onClick', 'onDoubleClick'])
+
+interface InteractiveWrapperOptions {
+  /** Element names this rule should not report (rare; prefer fixing the file). */
+  allow?: string[]
+  /** Replaces the default report message. */
+  message?: string
+}
+
+/** Reads a static `role` value; a dynamic role is undecidable statically, so it is left to review. */
+const roleOf = (node: any): string | null => {
+  for (const attribute of node.attributes ?? []) {
+    if (attribute.type !== 'JSXAttribute' || attribute.name?.name !== 'role') continue
+    if (attribute.value?.type === 'Literal' && typeof attribute.value.value === 'string')
+      return attribute.value.value
+    return null
+  }
+  return null
+}
+
+/** Whether the element carries the attribute, by name. */
+const has = (node: any, name: string): boolean =>
+  (node.attributes ?? []).some(
+    (attribute: any) => attribute.type === 'JSXAttribute' && attribute.name?.name === name
+  )
+
+const noInteractiveWrappers: RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Generic elements dressed as interactive controls — an interactive role, a click handler or a tabindex on a layout element — re-implement a primitive by hand. Compose the real component.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          allow: { type: 'array', items: { type: 'string' } },
+          message: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      roleWrapper:
+        'A {{element}} with role="{{role}}" hand-builds {{primitive}}: use {{primitive}} from {{path}}. The primitive brings keyboard activation, focus behaviour and ARIA wiring; the wrapper re-implements them badly.',
+      clickWrapper:
+        'A click handler on {{element}} composes {{primitive}} by hand: use {{primitive}} from {{path}}. A div that reacts to clicks is a button that cannot be reached by keyboard.',
+      tabindexWrapper:
+        'A tabindex on {{element}} makes a layout element focusable, which is focus management the primitives already own: compose the real component instead.',
+    },
+  },
+  create(context) {
+    const options = (context.options?.[0] ?? {}) as InteractiveWrapperOptions
+    const allowed = new Set(options.allow ?? [])
+    return {
+      JSXOpeningElement(node: any) {
+        if (node.name?.type !== 'JSXIdentifier') return
+        const element = node.name.name
+        if (allowed.has(element) || element in ELEMENT_PRIMITIVES) return
+
+        const role = roleOf(node)
+        if (role && role in ROLE_PRIMITIVES) {
+          const target = ROLE_PRIMITIVES[role]!
+          context.report({
+            node,
+            messageId: 'roleWrapper',
+            data: { element, role, primitive: target.primitive, path: target.path },
+            ...(options.message ? { message: options.message } : {}),
+          })
+          return
+        }
+
+        if (GENERIC_ELEMENTS.has(element)) {
+          const click = [...CLICK_HANDLERS].find((handler) => has(node, handler))
+          if (click) {
+            const target = ROLE_PRIMITIVES.button!
+            context.report({
+              node,
+              messageId: 'clickWrapper',
+              data: { element, primitive: target.primitive, path: target.path },
+              ...(options.message ? { message: options.message } : {}),
+            })
+            return
+          }
+          if (has(node, 'tabIndex') || has(node, 'tabindex')) {
+            context.report({
+              node,
+              messageId: 'tabindexWrapper',
+              data: { element },
+              ...(options.message ? { message: options.message } : {}),
+            })
+          }
+        }
+      },
+    }
+  },
+}
+
 const noPrimitiveLibraryImports: RuleModule = {
   meta: {
     type: 'problem',
@@ -173,6 +320,7 @@ const plugin = {
   rules: {
     'no-raw-interactive-elements': noRawInteractiveElements,
     'no-primitive-library-imports': noPrimitiveLibraryImports,
+    'no-interactive-wrappers': noInteractiveWrappers,
   },
 }