@botiverse/raft-ui 0.72.0 → 0.74.0

package/dist/lint/prefer-scroll-area.d.mts

@@ -0,0 +1,75 @@
+//#region src/lint/prefer-scroll-area.d.ts
+/**
+ * raft-ui/prefer-scroll-area: every region that scrolls is a ScrollArea
+ * (scroll-area.md#native-scrolling), so a native overflow that makes an
+ * element scroll is reported where an app writes it.
+ *
+ * Reported:
+ * - a native-scrolling Tailwind class (`overflow`, `overflow-x` or `overflow-y`
+ *   set to auto or scroll, with any variant prefix, `!`, or as an arbitrary
+ *   property) in a string or template literal that is a class: the value of a
+ *   `className`, `class` or `*ClassName` JSX attribute, or an argument of
+ *   `cn`, `clsx`, `cx`, `tv`, `cva`, `twMerge`, `twJoin` or `classNames`,
+ *   through conditionals, `&&`, arrays, objects (keys and values) and `+`;
+ * - an inline `style={{ overflow | overflowX | overflowY: "auto" | "scroll" }}`.
+ *
+ * Allowed with a `raft-ui: native-scroll <reason>` comment, line or block, on
+ * the line above the reported string (or at the end of its line): it covers
+ * the string that starts on that line only, not the rest of the call or the
+ * attribute it is in, so a class added to a multi-line `cn(...)` later is
+ * still reported. For an inline style, the line of its property. A comment
+ * without a reason doesn't count.
+ *
+ * It looks only at literals, with no scope or type information: a class built
+ * in a variable outside these calls isn't seen.
+ */
+export interface Position {
+  line: number;
+  column: number;
+}
+export interface Node {
+  type: string;
+  parent?: Node | null;
+  loc?: {
+    start: Position;
+    end: Position;
+  };
+  range?: [number, number];
+  [key: string]: unknown;
+}
+export interface Comment {
+  type: string;
+  value: string;
+  loc?: {
+    start: Position;
+    end: Position;
+  };
+  range?: [number, number];
+}
+export interface SourceCode {
+  getAllComments(): Comment[];
+  getLocFromIndex(index: number): Position;
+}
+export interface RuleContext {
+  sourceCode?: SourceCode;
+  getSourceCode?: () => SourceCode;
+  report(descriptor: {
+    node: Node;
+    messageId: string;
+  }): void;
+}
+export type RuleVisitor = Record<string, (node: Node) => void>;
+/** An ESLint rule, the format Oxlint's JS plugins take. */
+export interface RuleModule {
+  meta: {
+    type: "problem" | "suggestion" | "layout";
+    docs: {
+      description: string;
+      url: string;
+    };
+    messages: Record<string, string>;
+    schema: readonly unknown[];
+  };
+  create(context: RuleContext): RuleVisitor;
+}
+//#endregion

package/dist/lint/prefer-scroll-area.mjs

@@ -0,0 +1,157 @@
+//#region src/lint/prefer-scroll-area.ts
+const NATIVE_SCROLL_CLASS = /(?<![\w-])overflow(?:-[xy])?-(?:auto|scroll)(?![\w-])/;
+const NATIVE_SCROLL_ARBITRARY = /\[overflow(?:-[xy])?:[^\]]*\b(?:auto|scroll)\b[^\]]*\]/;
+const NATIVE_SCROLL_STYLE_KEYS = /* @__PURE__ */ new Set([
+	"overflow",
+	"overflowX",
+	"overflowY"
+]);
+const NATIVE_SCROLL_STYLE_VALUES = /* @__PURE__ */ new Set(["auto", "scroll"]);
+const CLASS_FUNCTIONS = /* @__PURE__ */ new Set([
+	"cn",
+	"clsx",
+	"cx",
+	"tv",
+	"cva",
+	"twMerge",
+	"twJoin",
+	"classNames",
+	"classnames"
+]);
+const CLASS_ATTRIBUTE = /^(?:class|className|\w+ClassName)$/;
+const PASS_THROUGH = /* @__PURE__ */ new Set([
+	"ArrayExpression",
+	"BinaryExpression",
+	"ConditionalExpression",
+	"JSXExpressionContainer",
+	"LogicalExpression",
+	"ObjectExpression",
+	"ParenthesizedExpression",
+	"Property",
+	"SpreadElement",
+	"TemplateLiteral",
+	"TSAsExpression",
+	"TSNonNullExpression",
+	"TSSatisfiesExpression"
+]);
+const ESCAPE = /\braft-ui:\s*native-scroll\s+\S/;
+/** Whether a class string has a native-scrolling class in it. */
+function hasNativeScrollClass(value) {
+	if (!value.includes("overflow")) return false;
+	return NATIVE_SCROLL_CLASS.test(value) || NATIVE_SCROLL_ARBITRARY.test(value);
+}
+function attributeName(node) {
+	const name = node.name;
+	return name?.type === "JSXIdentifier" ? name.name : void 0;
+}
+/** The attribute or call that makes a string a class, or undefined when it isn't one. */
+function classContext(node) {
+	let child = node;
+	let parent = node.parent;
+	while (parent) {
+		if (parent.type === "JSXAttribute") {
+			const name = attributeName(parent);
+			return name !== void 0 && CLASS_ATTRIBUTE.test(name) ? parent : void 0;
+		}
+		if (parent.type === "CallExpression") {
+			const callee = parent.callee;
+			return callee.type === "Identifier" && CLASS_FUNCTIONS.has(callee.name) && parent.arguments.includes(child) ? parent : void 0;
+		}
+		if (!PASS_THROUGH.has(parent.type)) return void 0;
+		child = parent;
+		parent = parent.parent;
+	}
+}
+function stringValue(node) {
+	if (node.type === "Literal" && typeof node.value === "string") return node.value;
+	if (node.type === "TemplateLiteral" && node.expressions.length === 0) {
+		const [quasi] = node.quasis;
+		const value = quasi?.value;
+		return value?.cooked ?? value?.raw;
+	}
+}
+/** The string literals an inline style value can be: `"auto"`, `a ? "auto" : "hidden"`, `a && "auto"`. */
+function styleValueStrings(node, out) {
+	if (node.type === "ConditionalExpression") {
+		styleValueStrings(node.consequent, out);
+		styleValueStrings(node.alternate, out);
+	} else if (node.type === "LogicalExpression") {
+		styleValueStrings(node.left, out);
+		styleValueStrings(node.right, out);
+	} else if (node.type === "TSAsExpression" || node.type === "TSSatisfiesExpression") styleValueStrings(node.expression, out);
+	else if (stringValue(node) !== void 0) out.push(node);
+	return out;
+}
+function propertyKey(property) {
+	const key = property.key;
+	if (property.computed) return stringValue(key);
+	return key.type === "Identifier" ? key.name : stringValue(key);
+}
+const preferScrollArea = {
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Scrolling regions use ScrollArea from @botiverse/raft-ui, not a native overflow.",
+			url: "https://raft-design.botiverse.build/about/use-raft-ui/#lint-rules"
+		},
+		messages: { preferScrollArea: "Scrolling regions use ScrollArea from @botiverse/raft-ui (or PanelScrollViewport inside a Panel). If this one must scroll natively, say why in an `// raft-ui: native-scroll <reason>` comment on the line above. https://raft-design.botiverse.build/components/scroll-area/" },
+		schema: []
+	},
+	create(context) {
+		const sourceCode = context.sourceCode ?? context.getSourceCode?.();
+		let escapeLines;
+		function line(index) {
+			return sourceCode.getLocFromIndex(index).line;
+		}
+		/** The lines an escape comment covers: the one it ends on and the next. */
+		function escaped() {
+			if (escapeLines) return escapeLines;
+			escapeLines = /* @__PURE__ */ new Set();
+			for (const comment of sourceCode?.getAllComments() ?? []) {
+				if (!ESCAPE.test(comment.value)) continue;
+				const end = comment.loc?.end.line ?? line(comment.range[1]);
+				escapeLines.add(end);
+				escapeLines.add(end + 1);
+			}
+			return escapeLines;
+		}
+		function startLine(node) {
+			return node.loc?.start.line ?? line(node.range[0]);
+		}
+		/** Reports `node` unless an escape comment covers the line `anchor` starts on. */
+		function report(node, anchor) {
+			const lines = escaped();
+			if (lines.size > 0 && lines.has(startLine(anchor))) return;
+			context.report({
+				node,
+				messageId: "preferScrollArea"
+			});
+		}
+		function checkClassString(node, value) {
+			if (!hasNativeScrollClass(value)) return;
+			if (classContext(node)) report(node, node);
+		}
+		return {
+			Literal(node) {
+				if (typeof node.value === "string") checkClassString(node, node.value);
+			},
+			TemplateLiteral(node) {
+				checkClassString(node, node.quasis.map((quasi) => quasi.value.raw).join(" "));
+			},
+			JSXAttribute(node) {
+				if (attributeName(node) !== "style") return;
+				const value = node.value;
+				const expression = value?.type === "JSXExpressionContainer" ? value.expression : void 0;
+				if (expression?.type !== "ObjectExpression") return;
+				for (const property of expression.properties) {
+					if (property.type !== "Property") continue;
+					const key = propertyKey(property);
+					if (key === void 0 || !NATIVE_SCROLL_STYLE_KEYS.has(key)) continue;
+					for (const literal of styleValueStrings(property.value, [])) if (NATIVE_SCROLL_STYLE_VALUES.has(stringValue(literal).trim())) report(literal, property);
+				}
+			}
+		};
+	}
+};
+//#endregion
+export { hasNativeScrollClass, preferScrollArea };

package/dist/lint/recommended.json

@@ -0,0 +1,6 @@
+{
+  "jsPlugins": ["@botiverse/raft-ui/lint"],
+  "rules": {
+    "raft-ui/prefer-scroll-area": "error"
+  }
+}

package/dist/lint.d.mts

@@ -0,0 +1,22 @@
+import { RuleContext, RuleModule, RuleVisitor } from "./lint/prefer-scroll-area.mjs";
+//#region src/lint/index.d.ts
+export interface RaftUiLintConfig {
+  name: string;
+  plugins: Record<string, RaftUiLintPlugin>;
+  rules: Record<string, "error" | "warn" | "off">;
+}
+export interface RaftUiLintPlugin {
+  meta: {
+    name: string;
+  };
+  rules: Record<string, RuleModule>;
+  configs: Record<string, RaftUiLintConfig>;
+}
+export declare const rules: Record<string, RuleModule>;
+/** Every rule of the plugin with its severity, as `recommended.json` lists them. */
+export declare const recommendedRules: Record<string, "error">;
+declare const plugin: RaftUiLintPlugin;
+/** ESLint flat config: `export default [raftUi.configs.recommended]`. */
+export declare const recommended: RaftUiLintConfig;
+//#endregion
+export { type RuleContext, type RuleModule, type RuleVisitor, plugin as default };

package/dist/lint.mjs

@@ -0,0 +1,29 @@
+import { preferScrollArea } from "./lint/prefer-scroll-area.mjs";
+//#region src/lint/index.ts
+/**
+* raft-ui's lint plugin: the Raft Design System's rules for the code of an app
+* built on raft-ui, in the ESLint plugin format, which Oxlint loads as a JS
+* plugin (`jsPlugins`). Published as `@botiverse/raft-ui/lint`.
+*
+* Enable every rule at once by extending `recommended.json` from the same
+* package (Oxlint) or adding `configs.recommended` (ESLint flat config), so a
+* rule added in a later release reaches the app with the upgrade. See
+* design/about/use-raft-ui.md#lint-rules.
+*/
+const rules = { "prefer-scroll-area": preferScrollArea };
+/** Every rule of the plugin with its severity, as `recommended.json` lists them. */
+const recommendedRules = { "raft-ui/prefer-scroll-area": "error" };
+const plugin = {
+	meta: { name: "raft-ui" },
+	rules,
+	configs: {}
+};
+/** ESLint flat config: `export default [raftUi.configs.recommended]`. */
+const recommended = {
+	name: "raft-ui/recommended",
+	plugins: { "raft-ui": plugin },
+	rules: recommendedRules
+};
+plugin.configs.recommended = recommended;
+//#endregion
+export { plugin as default, recommended, recommendedRules, rules };

package/dist/styles.css

@@ -893,8 +893,9 @@ textarea:-webkit-autofill:disabled {
   --list-cell: 1;
 }
 
-/* The scrollbar of a scroller that holds list cells (design/patterns/
-   lists.md): an 8px classic scrollbar with a 4px thumb, so a cell's
+/* For a native scroller of list cells that can't be a ScrollArea
+   (design/patterns/lists.md; raft-ui's own list scrollers are ScrollAreas,
+   whose overlay scrollbar takes no room): an 8px classic scrollbar with a 4px thumb, so a cell's
    end inset can come out of the scrollbar's own width and its fill sits 8px
    from both edges of the list. Styling ::-webkit-scrollbar makes Chromium
    draw this classic, always-visible 8px bar even where the platform's own

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/raft-ui",
-  "version": "0.72.0",
+  "version": "0.74.0",
   "description": "React components and CSS foundations for the Raft Design System.",
   "keywords": [
     "agent-skills",
@@ -46,6 +46,11 @@
       "types": "./dist/wip.d.mts",
       "default": "./dist/wip.mjs"
     },
+    "./lint": {
+      "types": "./dist/lint.d.mts",
+      "default": "./dist/lint.mjs"
+    },
+    "./lint/recommended.json": "./dist/lint/recommended.json",
     "./fonts.css": "./dist/fonts.css",
     "./styles.css": "./dist/styles.css",
     "./package.json": "./package.json",

package/skills/raft-ui-guide/SKILL.md

@@ -90,6 +90,7 @@ When reviewing or editing code that uses raft-ui, check:
 - [ ] Menu rows are `…Item` parts, not raw `<button>`s; raw buttons drop out of keyboard navigation
 - [ ] Product state (upload, permissions, read/unread) lives in the app; the component renders parts, not a `state` prop
 - [ ] No shadow written as `shadow-[var(--…)]`: named utility or fully literal
+- [ ] Every region that scrolls is a `ScrollArea` (or `PanelScrollViewport` in a Panel), not `overflow-auto` / `overflow-scroll`; a native scroller kept on purpose has a `// raft-ui: native-scroll <reason>` comment. The `raft-ui/prefer-scroll-area` lint rule checks it: https://raft-design.botiverse.build/about/use-raft-ui.md#lint-rules
 
 ## Stability
 

package/skills/raft-ui-guide/rules/technical-overview.md

@@ -19,6 +19,7 @@ description: "raft-ui's technical foundations, package contents, and integration
 | `@botiverse/raft-ui/foundation.css` | Native CSS theme variables              |
 | `@botiverse/raft-ui/styles.css`     | Tailwind integration                    |
 | `@botiverse/raft-ui/fonts.css`      | Optional web fonts                      |
+| `@botiverse/raft-ui/lint`           | Lint plugin with the DS rules for apps  |
 
 Component declarations live in `dist/index.d.mts` (see [API lookup](./lookup.md)). Version-matched Markdown guides and optional `raft-ui-guide` / `raft-ui-critique` skills ship in `skills/`.