@botiverse/raft-ui 0.73.0 → 0.74.0

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+## [0.74.0](https://github.com/botiverse/raft-design/compare/v0.73.0...v0.74.0) (2026-11-08)
+
+### Added
+
+- **Lint rules for apps**: `@botiverse/raft-ui/lint` is a lint plugin with the design system's rules for app code, in the ESLint plugin format, which Oxlint loads as a JS plugin. Its first rule, `raft-ui/prefer-scroll-area`, reports a class or an inline style that makes an element scroll natively (`overflow-auto`, `overflow-scroll` and their `-x-` and `-y-` forms, with any variant) where an app writes it, unless a `// raft-ui: native-scroll <reason>` comment on the line above says which exception it is. The comment covers the string on the next line only, not the rest of a multi-line `cn(...)`, so a class added to the list later is still checked. Turn on every rule at once by extending `./node_modules/@botiverse/raft-ui/dist/lint/recommended.json` from `.oxlintrc.json` (or `configs.recommended` in an ESLint flat config); a rule added later reaches the app with the upgrade. ([#1058](https://github.com/botiverse/raft-design/pull/1058), [#1059](https://github.com/botiverse/raft-design/pull/1059))
+  - Why: the design system's rules should reach the apps, and the agents working in them, with raft-ui itself rather than through each repository's instructions; every region that scrolls is a ScrollArea, and nothing outside raft-ui checked it (Artea, #proj-raft-ui:#209).
+  - Affects: nothing until an app turns the plugin on. Then each native scroller in its code is reported: make it a ScrollArea (or `PanelScrollViewport` in a Panel), or add the comment with its reason.
+  - Docs: https://raft-design.botiverse.build/about/use-raft-ui/#lint-rules
+
+### Changed
+
+- **useScrollAreaContainer gives its container the overflow**: the classes in `containerProps.className` make the element scroll in the `orientation`, as ScrollArea's own container does (vertical: `overflow-y: auto` and `overflow-x: hidden`; horizontal: the other way round; both: `auto`), so the element needs no overflow class of its own and nothing for `raft-ui/prefer-scroll-area` to report. `ComposerInput` and `ActivityInboxViewport` no longer carry `overflow-y-auto`. ([#1059](https://github.com/botiverse/raft-design/pull/1059))
+  - Why: the hook asked the app to add a native overflow class, which the new lint rule reports (Jasper's review of the lint rule).
+  - Affects: apps can drop the overflow class from a `useScrollAreaContainer` element. One they keep still wins (the hook's rule has no specificity), so nothing breaks. A vertical container that had only `overflow-y-auto` now clips sideways (`overflow-x: hidden`) instead of scrolling sideways with no scrollbar; pass `orientation="both"` for content that scrolls both ways.
+  - Docs: https://raft-design.botiverse.build/components/scroll-area/#your-own-container
+
+### Design System
+
+- **A thread's timeline**: conversation.md lists what a thread's timeline shows (the message it started from and every message a person wrote), when it appears, the rail for a mouse, the Timeline entry in the thread's More menu on every device, a half-height sheet on a phone and a popover wider, and how its items are marked. No raft-ui component changed. ([#1057](https://github.com/botiverse/raft-design/pull/1057))
+  - Why: a long thread buries the few messages people wrote under agents' work (Artea, #proj-raft-ui:#206).
+  - Docs: https://raft-design.botiverse.build/patterns/conversation/#a-threads-timeline
+
 ## [0.73.0](https://github.com/botiverse/raft-design/compare/v0.72.0...v0.73.0) (2026-11-08)
 
 ### Changed

package/dist/components/activity-inbox/activity-inbox-shell.recipe.mjs

@@ -9,7 +9,7 @@ const activityInboxShell = tv({ slots: {
 	],
 	frame: ["min-h-0 flex-1"],
 	viewport: [
-		"relative flex min-h-0 flex-1 flex-col gap-0.5 overflow-y-auto *:shrink-0",
+		"relative flex min-h-0 flex-1 flex-col gap-0.5 *:shrink-0",
 		"outline-none focus-visible:shadow-focus",
 		"bg-layer-canvas px-0 pt-2 pb-[calc(8px+env(safe-area-inset-bottom,0px))]"
 	],

package/dist/components/composer/composer.recipe.mjs

@@ -12,7 +12,7 @@ const composer = tv({
 		inputFrame: ["w-full min-w-0", "[--r-scroll-area-resize-grip-size:0px]"],
 		input: [
 			"max-h-32 w-full resize-none bg-transparent outline-none",
-			"field-sizing-content overflow-y-auto",
+			"field-sizing-content",
 			"min-h-6 px-0.5",
 			"font-sans text-body font-normal text-foreground",
 			"placeholder:text-foreground-hint"

package/dist/components/scroll-area/scroll-area.css

@@ -24,8 +24,8 @@
  * `--overflow-{y,x}-{start,end}` (more content past that edge; `x` is
  * inline; these and `--rtl` are set by the script with `classList`, never
  * rendered) and `--textarea`; `__container` (with absolute gutters, the
- * container), `__viewport` (ScrollArea's own `<div>` container: its
- * overflow), `__content`, `__textarea`, `__gutters` (with `--scrolling`,
+ * container), `__viewport` (ScrollArea's own `<div>` container),
+ * `__content`, `__textarea`, `__gutters` (with `--scrolling`,
  * from the first scroll until `hideDelay` after the last, and `--dragging`,
  * both set by the script: on the layer, so toggling them restyles only the
  * gutters, not the content under the root), `__gutter` (`--vertical`,
@@ -216,9 +216,9 @@
   }
 
   /*
-   * The container. Its own overflow, layout and focus are its own (a list,
-   * a textarea); the overlay scrollbars replace its native ones. With sticky
-   * gutters it is the root.
+   * The container. Its layout and focus are its own (a list, a textarea);
+   * its overflow is the orientation's (below), and the overlay scrollbars
+   * replace its native ones. With sticky gutters it is the root.
    */
   .r-scroll-area.r-scroll-area--sticky-gutters,
   .r-scroll-area.r-scroll-area--absolute-gutters > .r-scroll-area__container {
@@ -242,17 +242,34 @@
     position: relative;
   }
 
-  /* ScrollArea's own `<div>` container (always sticky) scrolls in the orientation. */
-  .r-scroll-area.r-scroll-area--sticky-gutters.r-scroll-area__viewport {
+  /*
+   * Every container scrolls in the orientation: ScrollArea's own `<div>` and
+   * a `useScrollAreaContainer` element alike, so a caller never writes the
+   * overflow. With no specificity (`:where`), so a component's own rule for
+   * its scroller (VirtualList's) or an overflow in the caller's `className`
+   * still wins over it.
+   */
+  :where(.r-scroll-area.r-scroll-area--sticky-gutters),
+  :where(.r-scroll-area.r-scroll-area--absolute-gutters > .r-scroll-area__container) {
     overflow: hidden auto;
-    position: relative;
   }
-  .r-scroll-area.r-scroll-area--sticky-gutters.r-scroll-area--horizontal-orientation.r-scroll-area__viewport {
+  :where(.r-scroll-area.r-scroll-area--sticky-gutters.r-scroll-area--horizontal-orientation),
+  :where(
+    .r-scroll-area.r-scroll-area--absolute-gutters.r-scroll-area--horizontal-orientation
+      > .r-scroll-area__container
+  ) {
     overflow: auto hidden;
   }
-  .r-scroll-area.r-scroll-area--sticky-gutters.r-scroll-area--both-orientation.r-scroll-area__viewport {
+  :where(.r-scroll-area.r-scroll-area--sticky-gutters.r-scroll-area--both-orientation),
+  :where(
+    .r-scroll-area.r-scroll-area--absolute-gutters.r-scroll-area--both-orientation
+      > .r-scroll-area__container
+  ) {
     overflow: auto;
   }
+  .r-scroll-area.r-scroll-area--sticky-gutters.r-scroll-area__viewport {
+    position: relative;
+  }
 
   /*
    * A scroll that reaches the end stops there instead of scrolling the page:

package/dist/components/scroll-area/types.d.mts

@@ -116,7 +116,9 @@ export type ScrollAreaContainerProps<E extends HTMLElement = HTMLElement> = {
   ref: RefCallback<E>;
   /**
    * Before your own classes. With sticky gutters the container is the root, so these are the
-   * root's classes and modifiers; with absolute gutters, `r-scroll-area__container`.
+   * root's classes and modifiers; with absolute gutters, `r-scroll-area__container`. They give the
+   * element the orientation's overflow (vertical: `overflow-y: auto`, `overflow-x: hidden`), so
+   * it needs no overflow class of its own; one of yours still wins over it.
    */
   className: string;
   /** With sticky gutters, the root's variables (`railInset`, the timelines); merge your style after it. */

package/dist/components/scroll-area/use-scroll-area-container.d.mts

@@ -6,7 +6,8 @@ import { ScrollAreaContainer, ScrollAreaContainerOptions, ScrollAreaFrameProps }
  * its scroll, and keeps the state; you render the elements.
  *
  * Spread `containerProps` on the element that scrolls (a `<ul>`, a `<textarea>`, VirtualList's
- * scroller through `domRef`), merging your own `className` and `style` with them (pass your own
+ * scroller through `domRef`), merging your own `className` and `style` with them; its classes give
+ * the element the orientation's overflow, so it needs no overflow class (pass your own
  * refs as `containerRef` and `frameRef`: the returned `ref`s already forward to them), and render
  * `<ScrollAreaGutters {...guttersProps} />` where `guttersPosition` says:
  *

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/raft-ui",
-  "version": "0.73.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/`.