Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

chore(core): one owner module turns scroll anchoring off (#10173)

Cindy Zhang6e0b604291ff
diff --git a/.changeset/scroll-anchoring-owner.md b/.changeset/scroll-anchoring-owner.md
new file mode 100644
index 0000000000..80b97487aa
--- /dev/null
+++ b/.changeset/scroll-anchoring-owner.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: one owner module now turns the browser's scroll anchoring off on a container whose position a component owns. `useChatStreamScroll` uses it while it follows the end, with the same behaviour as before, and the undocumented `@astryxdesign/core/internal/scroll-anchoring` entry gives its writer to Lab. Internal entries are outside the public API and its compatibility promise.
+
+@cixzhang
diff --git a/apps/docsite/src/__tests__/theme-showcase/theme-showcase.test.tsx b/apps/docsite/src/__tests__/theme-showcase/theme-showcase.test.tsx
index 15dab93d3f..5e4033b0fc 100644
--- a/apps/docsite/src/__tests__/theme-showcase/theme-showcase.test.tsx
+++ b/apps/docsite/src/__tests__/theme-showcase/theme-showcase.test.tsx
@@ -424,7 +424,7 @@ describe('theme-showcase local interactions', () => {
).toBeInTheDocument();
expect(composer).toHaveTextContent('');
await waitFor(() => expect(viewport.scrollTop).toBe(700));
- expect(viewport).toHaveAttribute('data-astryx-chat-following');
+ expect(viewport).toHaveAttribute('data-astryx-scroll-anchoring', 'off');
const list = viewport.querySelector('.astryx-chat-message-list')!;
expect(resizeCallbacks.has(list)).toBe(true);
Object.defineProperty(viewport, 'scrollHeight', {value: 1200});
@@ -432,7 +432,7 @@ describe('theme-showcase local interactions', () => {
await waitFor(() => expect(viewport.scrollTop).toBe(1000), {timeout: 3000});
viewport.scrollTop = 200;
fireEvent.scroll(viewport);
- expect(viewport).not.toHaveAttribute('data-astryx-chat-following');
+ expect(viewport).not.toHaveAttribute('data-astryx-scroll-anchoring');
Object.defineProperty(viewport, 'scrollHeight', {value: 1500});
resizeCallbacks.get(list)!();
expect(viewport.scrollTop).toBe(200);
diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md
index 50b2dddff7..71826820eb 100644
--- a/docs/architecture/public-component-api.md
+++ b/docs/architecture/public-component-api.md
@@ -267,7 +267,11 @@ guidance owns the process used to propose and test APIs.
where it is written, and it never exports them or sets the attribute. Every
other file in that package spreads those exports and
never writes the attribute or its selector, and no package imports another
- package's owner module through an internal path. StyleX merges styles one
+ package's owner module through an internal path. An owner module whose
+ attribute marks an element its package does not render may write its
+ selector once in an injected rule instead of `stylex.create`; Core may
+ re-export only that module's writer to Lab through an internal entry, and
+ the attribute name and selector stay private to the owner. StyleX merges styles one
whole property at a time, so an owner style carries every condition of each
property it sets, its rest state and pointer states included, and a caller
does not set those properties again on the same element. Outside the owner
diff --git a/docs/specs/components/Chat/ChatLayout.spec.md b/docs/specs/components/Chat/ChatLayout.spec.md
index e5feba3826..2b49e26036 100644
--- a/docs/specs/components/Chat/ChatLayout.spec.md
+++ b/docs/specs/components/Chat/ChatLayout.spec.md
@@ -90,6 +90,10 @@ inline-size`, and the `chat-layout` theming target with its `density` axis.
- Scroll measurement, spring animation, lock behavior, or new-message detection —
owned by `useChatStreamScroll` and `useChatNewMessages`.
+- Turning the browser's scroll anchoring off while following — owned by
+ `useChatStreamScroll`, which writes it only through Core's scroll-anchoring
+ owner module (`privateAttributes/scrollAnchoring.stylex.ts`), the one owner
+ of that rule (`architecture:public-component-api` INV23).
- Message presentation, grouping, or sender semantics — owned by
`component:ChatMessageList` and `component:ChatMessage`.
- Composer behavior, sizing, or status — owned by `component:ChatComposer`.
diff --git a/internal/eslint-plugin-astryx/no-raw-private-attribute.baseline.json b/internal/eslint-plugin-astryx/no-raw-private-attribute.baseline.json
index 673d42376c..9703aa8ef0 100644
--- a/internal/eslint-plugin-astryx/no-raw-private-attribute.baseline.json
+++ b/internal/eslint-plugin-astryx/no-raw-private-attribute.baseline.json
@@ -7,10 +7,6 @@
"packages/core/src/Chat/useChatDictation.ts": [
"data-astryx-dictation-interim"
],
- "packages/core/src/Chat/useChatStreamScroll.ts": [
- "data-astryx-chat-following",
- "data-astryx-chat-following-style"
- ],
"packages/core/src/Chat/useTriggerMenu.tsx": ["data-astryx-trigger-anchor"],
"packages/core/src/CheckboxInput/CheckboxInput.tsx": [
"data-astryx-press",
diff --git a/packages/core/package.json b/packages/core/package.json
index 44f49b17e8..22aba2fd6f 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -863,6 +863,11 @@
"source": "./src/internal/dialog-context.ts",
"types": "./dist/internal/dialog-context.d.ts",
"default": "./dist/internal/dialog-context.js"
+ },
+ "./internal/scroll-anchoring": {
+ "source": "./src/internal/scroll-anchoring.ts",
+ "types": "./dist/internal/scroll-anchoring.d.ts",
+ "default": "./dist/internal/scroll-anchoring.js"
}
},
"files": [
diff --git a/packages/core/src/Chat/__tests__/useChatStreamScroll.a11y.chromium.spec.ts b/packages/core/src/Chat/__tests__/useChatStreamScroll.a11y.chromium.spec.ts
index 7975f1f35c..588eea66f6 100644
--- a/packages/core/src/Chat/__tests__/useChatStreamScroll.a11y.chromium.spec.ts
+++ b/packages/core/src/Chat/__tests__/useChatStreamScroll.a11y.chromium.spec.ts
@@ -87,7 +87,7 @@ async function position(page: Page) {
return viewport(page).evaluate(element => ({
top: element.scrollTop,
gap: element.scrollHeight - element.clientHeight - element.scrollTop,
- following: element.hasAttribute('data-astryx-chat-following'),
+ following: getComputedStyle(element).overflowAnchor === 'none',
dpr: devicePixelRatio,
reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,
}));
diff --git a/packages/core/src/Chat/useChatStreamScroll.test.tsx b/packages/core/src/Chat/useChatStreamScroll.test.tsx
index 76b4442d32..bd550079ab 100644
--- a/packages/core/src/Chat/useChatStreamScroll.test.tsx
+++ b/packages/core/src/Chat/useChatStreamScroll.test.tsx
@@ -297,22 +297,22 @@ describe('useChatStreamScroll — reader intent while content arrives', () => {
// inline style.
const {api, el, unmount} = renderHook();
settleAtBottom(el);
- expect(el.hasAttribute('data-astryx-chat-following')).toBe(true);
+ expect(el.getAttribute('data-astryx-scroll-anchoring')).toBe('off');
const rule = document.head.querySelector(
- '[data-astryx-chat-following-style]',
+ '[data-astryx-scroll-anchoring="rule"]',
);
expect(rule?.textContent).toContain('overflow-anchor:none !important');
expect(el.style.overflowAnchor).toBe('');
scrollUpDuringGrowth(el);
expect(api.current!.isLocked).toBe(false);
- expect(el.hasAttribute('data-astryx-chat-following')).toBe(false);
+ expect(el.hasAttribute('data-astryx-scroll-anchoring')).toBe(false);
act(() => api.current!.scrollToBottom({behavior: 'instant'}));
- expect(el.hasAttribute('data-astryx-chat-following')).toBe(true);
+ expect(el.getAttribute('data-astryx-scroll-anchoring')).toBe('off');
unmount();
- expect(el.hasAttribute('data-astryx-chat-following')).toBe(false);
+ expect(el.hasAttribute('data-astryx-scroll-anchoring')).toBe(false);
});
it("never touches the element's own overflow-anchor, whatever it becomes", () => {
diff --git a/packages/core/src/Chat/useChatStreamScroll.ts b/packages/core/src/Chat/useChatStreamScroll.ts
index 915e5ce8f7..0184f04b8f 100644
--- a/packages/core/src/Chat/useChatStreamScroll.ts
+++ b/packages/core/src/Chat/useChatStreamScroll.ts
@@ -33,6 +33,7 @@
import {useCallback, useEffect, useRef, useState} from 'react';
import {useMediaQuery} from '../hooks/useMediaQuery';
+import {setScrollAnchoringOff} from '../privateAttributes/scrollAnchoring.stylex';
// =============================================================================
// Types
@@ -128,28 +129,6 @@ export interface UseChatStreamScrollReturn {
const SIXTY_FPS_MS = 1000 / 60;
-// While following, the hook owns the container's position, so the browser's
-// scroll anchoring must not move it. The rule rides on an attribute rather
-// than the element's inline style: a consumer's own `overflow-anchor` is never
-// read, written or restored — it simply applies again once the attribute is
-// gone. `!important` so an inline `auto` cannot switch anchoring back on under
-// a following container; an inline `!important` still wins, deliberately.
-const FOLLOWING_ATTR = 'data-astryx-chat-following';
-const FOLLOWING_STYLE_ATTR = 'data-astryx-chat-following-style';
-
-function ensureFollowingStyle(): void {
- if (
- typeof document === 'undefined' ||
- document.head.querySelector(`[${FOLLOWING_STYLE_ATTR}]`)
- ) {
- return;
- }
- const style = document.createElement('style');
- style.setAttribute(FOLLOWING_STYLE_ATTR, '');
- style.textContent = `[${FOLLOWING_ATTR}]{overflow-anchor:none !important}`;
- document.head.appendChild(style);
-}
-
export function useChatStreamScroll({
scrollRef,
enabled = true,
@@ -187,7 +166,10 @@ export function useChatStreamScroll({
(locked: boolean) => {
lockedRef.current = locked;
setIsLocked(locked);
- scrollRef.current?.toggleAttribute(FOLLOWING_ATTR, locked);
+ const el = scrollRef.current;
+ if (el != null) {
+ setScrollAnchoringOff(el, locked);
+ }
},
[scrollRef],
);
@@ -367,8 +349,7 @@ export function useChatStreamScroll({
}
lastScrollTopRef.current = el.scrollTop;
- ensureFollowingStyle();
- el.toggleAttribute(FOLLOWING_ATTR, lockedRef.current);
+ setScrollAnchoringOff(el, lockedRef.current);
const onScroll = () => {
const {scrollTop, scrollHeight, offsetHeight} = el;
@@ -414,7 +395,7 @@ export function useChatStreamScroll({
return () => {
el.removeEventListener('scroll', onScroll);
el.removeEventListener('scrollend', onScrollEnd);
- el.removeAttribute(FOLLOWING_ATTR);
+ setScrollAnchoringOff(el, false);
};
}, [scrollRef, enabled, lockThreshold, buttonThreshold, setLocked]);
diff --git a/packages/core/src/internal/scroll-anchoring.ts b/packages/core/src/internal/scroll-anchoring.ts
new file mode 100644
index 0000000000..af332f9494
--- /dev/null
+++ b/packages/core/src/internal/scroll-anchoring.ts
@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/**
+ * @file scroll-anchoring.ts
+ * @input The scroll-anchoring owner module
+ * @output `@astryxdesign/core/internal/scroll-anchoring`: setScrollAnchoringOff,
+ * re-exported by name for Lab
+ * @position An internal entry reserved for Astryx's own packages. It is
+ * undocumented, outside the public API and its compatibility promise, and
+ * versioned in lockstep with Core. The `@astryx/no-core-internal-import`
+ * lint rule allows it only in Core and Lab. Core components import the
+ * owner module by relative path. Named re-exports only: the writer, never
+ * the attribute's name.
+ *
+ * SYNC: When modified, update scripts/sync-exports.js.
+ */
+export {setScrollAnchoringOff} from '../privateAttributes/scrollAnchoring.stylex';
diff --git a/packages/core/src/privateAttributes/scrollAnchoring.stylex.ts b/packages/core/src/privateAttributes/scrollAnchoring.stylex.ts
new file mode 100644
index 0000000000..ac8fcefe7f
--- /dev/null
+++ b/packages/core/src/privateAttributes/scrollAnchoring.stylex.ts
@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file privateAttributes/scrollAnchoring.stylex.ts
+ * @input A scroll container whose position a component owns
+ * @output setScrollAnchoringOff, which turns the browser's scroll anchoring
+ * off on an element and back on
+ * @position Owner module of the private scroll-anchoring attribute: the only
+ * file that writes its name or its rule. Core's useChatStreamScroll calls
+ * it while it follows the end; Lab reaches the writer through
+ * `@astryxdesign/core/internal/scroll-anchoring`. No public entry exports
+ * it.
+ */
+
+const SCROLL_ANCHORING = 'data-astryx-scroll-anchoring';
+/** On a scroll container: the browser's anchoring is off there. */
+const OFF = 'off';
+/** On the one `<style>` element that holds the rule. */
+const RULE = 'rule';
+
+/**
+ * Add the one rule the attribute switches on, once per document. A rule on
+ * an attribute, not the element's inline style, so the caller's own
+ * `overflow-anchor` is never read, written or restored, and applies again
+ * once the attribute is gone. `!important` so an inline `auto` cannot turn
+ * anchoring back on under a component that positions the content itself.
+ */
+function ensureRule(doc: Document): void {
+ if (doc.head.querySelector(`[${SCROLL_ANCHORING}="${RULE}"]`) != null) {
+ return;
+ }
+ const style = doc.createElement('style');
+ style.setAttribute(SCROLL_ANCHORING, RULE);
+ style.textContent = `[${SCROLL_ANCHORING}="${OFF}"]{overflow-anchor:none !important}`;
+ doc.head.appendChild(style);
+}
+
+/**
+ * Turn the browser's scroll anchoring off on `element` (`on`), or hand it
+ * back (`!on`). A component calls this while it alone moves the container's
+ * position, so native anchoring does not move it a second time.
+ */
+export function setScrollAnchoringOff(element: Element, on: boolean): void {
+ if (on) {
+ ensureRule(element.ownerDocument);
+ element.setAttribute(SCROLL_ANCHORING, OFF);
+ } else {
+ element.removeAttribute(SCROLL_ANCHORING);
+ }
+}
diff --git a/packages/core/src/privateAttributes/scrollAnchoring.test.ts b/packages/core/src/privateAttributes/scrollAnchoring.test.ts
new file mode 100644
index 0000000000..8222069097
--- /dev/null
+++ b/packages/core/src/privateAttributes/scrollAnchoring.test.ts
@@ -0,0 +1,49 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file scrollAnchoring.test.ts
+ * @input Uses vitest and jsdom
+ * @output The scroll-anchoring writer turns anchoring off with one rule per
+ * document and hands it back, never touching the element's inline style
+ * @position Unit tests of privateAttributes/scrollAnchoring.stylex.ts
+ */
+
+import {afterEach, describe, expect, it} from 'vitest';
+import {setScrollAnchoringOff} from './scrollAnchoring.stylex';
+
+afterEach(() => {
+ document.body.replaceChildren();
+});
+
+describe('setScrollAnchoringOff', () => {
+ it("turns anchoring off through an attribute and one rule, and hands the element's own value back", () => {
+ const first = document.createElement('div');
+ const second = document.createElement('div');
+ document.body.append(first, second);
+ first.style.overflowAnchor = 'auto';
+
+ setScrollAnchoringOff(first, true);
+ setScrollAnchoringOff(second, true);
+ expect(first.getAttribute('data-astryx-scroll-anchoring')).toBe('off');
+ const rules = document.head.querySelectorAll(
+ '[data-astryx-scroll-anchoring="rule"]',
+ );
+ expect(rules).toHaveLength(1);
+ expect(rules[0].textContent).toBe(
+ '[data-astryx-scroll-anchoring="off"]{overflow-anchor:none !important}',
+ );
+ expect(first.style.overflowAnchor).toBe('auto');
+
+ setScrollAnchoringOff(first, false);
+ expect(first.hasAttribute('data-astryx-scroll-anchoring')).toBe(false);
+ expect(first.style.overflowAnchor).toBe('auto');
+ expect(second.getAttribute('data-astryx-scroll-anchoring')).toBe('off');
+ });
+
+ it('is re-exported by name from the internal entry', async () => {
+ const entry: Record<string, unknown> =
+ await import('../internal/scroll-anchoring');
+ expect(entry.setScrollAnchoringOff).toBe(setScrollAnchoringOff);
+ expect(Object.keys(entry)).toEqual(['setScrollAnchoringOff']);
+ });
+});
diff --git a/scripts/sync-exports.js b/scripts/sync-exports.js
index 3ae9bd5180..47b97b6742 100644
--- a/scripts/sync-exports.js
+++ b/scripts/sync-exports.js
@@ -244,6 +244,7 @@ const FILE_MODULE_SUBPATH_EXPORTS = [
'internal/spinner-rotor',
'internal/calendar-system',
'internal/dialog-context',
+ 'internal/scroll-anchoring',
];
/**