pixelize-design-library 3.2.0 → 3.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -9,6 +9,15 @@ Found a bug or a gap? Report it as a GitHub issue and track it to closure — se
9
9
  [COMPONENT-GOTCHAS.md](COMPONENT-GOTCHAS.md#found-a-gap-or-a-bug-report-it-then-track-it). A fix's
10
10
  line below names its issue number.
11
11
 
12
+ ## [3.3.1] — 2026-11-11
13
+
14
+ ### Docs
15
+
16
+ - **One look in every app.** `DESIGN-GUIDE.md` §5a is a swap table from each browser-native or raw-Chakra
17
+ control (`<select>`, `<input>`, `Badge`, `Tooltip`, `Menu`, `useToast`, `window.confirm`, a bordered `Box`)
18
+ to the library component and the props that look right. New code always passes `Select native={false}`;
19
+ the `native` default is unchanged, so no call site moves.
20
+
12
21
  ## [Unreleased]
13
22
 
14
23
  ### Added
@@ -28,6 +37,13 @@ line below names its issue number.
28
37
  `AssistantStatusBanner` and `AssistantTypingIndicator`. The shared message model (`AssistantMessageModel`,
29
38
  `AssistantPart` and one type per part) and every props, labels and item type are root exports. Demo at
30
39
  `/assistant`, full screen at `/examples/assistant`.
40
+ - **`AssistantThread` `followMode`** (`"bottom"` or `"reply-start"`, default `"bottom"`, which behaves exactly as before). With
41
+ `"reply-start"`, a reply that arrives as a new message with `status: "streaming"` is read from its first line: the thread
42
+ keeps the reply's top 12px below the top edge, so a short reply shows whole at the bottom and a reply taller than the
43
+ viewport stays pinned at its start while it grows. A wheel, touch, pointer press or scroll key in the thread, or Jump to
44
+ latest, hands scrolling back to the person and the usual stick-to-bottom rules apply again. Sending a message and opening
45
+ a saved conversation still land at the bottom. Every message now sits in a `data-message-id` wrapper (the `renderMessage`
46
+ path already had one).
31
47
 
32
48
  ### Fixed
33
49
 
@@ -119,6 +119,11 @@ There is now **one** picker. `Select` does both modes off the `native` prop:
119
119
  fully-React popup — searchable, `isMulti` with chips, grouped options, `isClearable`,
120
120
  `onCreate`, `renderOption`, `onLoadMore`, optional windowing via `virtualizeAfter`.
121
121
 
122
+ **New code passes `native={false}`.** The `true` default only exists so existing call sites don't
123
+ change; a native `<select>` next to themed fields is the "two apps" look DESIGN-GUIDE §5a removes.
124
+ Converting an existing call site changes its DOM (`combobox`/`listbox`, no `<option>`), so update
125
+ its tests in the same diff.
126
+
122
127
  `isMulti` always forces the popup — there is no native multi-select — and dev-warns if you
123
128
  also passed `native`.
124
129
 
@@ -2101,6 +2106,10 @@ While a window is open (not minimized) role queries for background elements need
2101
2106
  (`headingLevel`). A single newline inside a paragraph is a line break.
2102
2107
  - **`AssistantThread` announces a reply only when its `status` leaves `"streaming"`.** A reply that is never marked
2103
2108
  `streaming` first is never announced; one left on `streaming` keeps its caret and hides its action row.
2109
+ - **`AssistantThread followMode="reply-start"` engages only for a reply that arrives as a new message with
2110
+ `status: "streaming"`.** A reply first added as `complete` (no `status` means complete), or an existing message
2111
+ flipped to `streaming`, gets the plain `"bottom"` behaviour. While a long reply streams the view is pinned at its
2112
+ start, so "Jump to latest" shows by design; a wheel, touch, click or scroll key in the thread hands scrolling back.
2104
2113
  - **`AssistantHistoryList` without `now` freezes "now" at mount**, so Today and Yesterday do not roll over at midnight
2105
2114
  until it remounts. Pass `now` when a list can stay open across days. `onDelete` runs only after the confirm dialog;
2106
2115
  a rejected promise keeps the dialog open.
package/DESIGN-GUIDE.md CHANGED
@@ -141,6 +141,38 @@ icon-only button gets an `aria-label` and a `ToolTip`. Inline or panel busy indi
141
141
  input in `FormControl` + `FormLabel`. In a settings row (title + description left, control right)
142
142
  the row title is the label: `<Text as="label" htmlFor={id}>` pointing at the field's `id`.
143
143
 
144
+ ## 5a. One look everywhere — the swap table
145
+
146
+ A screen that mixes library controls with browser or raw-Chakra ones looks like two apps. Every
147
+ row below has one answer; pass exactly these props and nothing that restates a default.
148
+
149
+ | Instead of | Use | Props that look right |
150
+ | --- | --- | --- |
151
+ | `<select>`, `Select` with no `native` | `Select` | `native={false}` — always; the default `native` renders the browser's own list |
152
+ | `<input>`, Chakra `Input` | `TextInput` | `label`, `helperText`, `errorMessage`; default `outline` |
153
+ | `<input type="number">` | `NumberInput` | — |
154
+ | `<input type="date">` / `"time"` | `DatePicker` / `TimePicker` | — |
155
+ | `<textarea>` | `InputTextArea` | `label` |
156
+ | `<input type="checkbox">` | `Checkbox` | — |
157
+ | `<input type="radio">` | `RadioButtonGroup` + `RadioButton`, or `ChoiceCardGroup` for big choices | — |
158
+ | An on/off checkbox or `Switch` | `ToggleSwitch` | in a settings list, inside `SettingRow` |
159
+ | `<button>`, Chakra `Button` | `Button` / `IconButton` | §5 role table; icon-only gets `aria-label` + `ToolTip` |
160
+ | Chakra `Badge`, a coloured `Box` pill | `StatusTag` for a status, `Tag` otherwise | `Tag variant="subtle" size="sm" tone=…` |
161
+ | `title=""`, Chakra `Tooltip` | `ToolTip` (`OverflowToolTip` for truncated text) | — |
162
+ | Chakra `Menu` for row/page actions | `Dropdown` | — |
163
+ | `Thead`/`Tr`/`Td` data lists | `Table` | `TableRoot` only for a tiny static key/value grid; prefer `DescriptionList` |
164
+ | `window.confirm`, a hand-built confirm `Modal` | `AlertDialog` / `ConfirmDialog` | `tone="danger"` for destructive |
165
+ | `alert()`, Chakra `useToast` | `useToaster().showToast` | `status` |
166
+ | Chakra `Spinner`, "Loading…" text | `Skeletons` shaped like the content; `Spinner` inline | — |
167
+ | A `Box` with border + shadow as a card | `Card` | default `elevated`; `variant="outline"` around a table or row list |
168
+ | A hand-built header row | `PageHeader` | one `solid` action |
169
+ | A blank area when there is no data | `EmptyState` / `QueryStateBoundary` | §7 |
170
+ | Tabs built from buttons | `Tabs` (panels) / `SegmentedControl` (a value) | defaults |
171
+
172
+ Layout and type (`Box`, `Flex`, `Stack`, `Grid`, `Text`, `Heading`, `Divider`) are not swaps — import
173
+ them from `pixelize-design-library` (§8). If a row's library component can't do what the screen
174
+ needs, report the gap rather than falling back to the raw one.
175
+
144
176
  ## 6. Page anatomy
145
177
 
146
178
  ```
@@ -292,7 +324,9 @@ hides its primary; when only one section is empty on a populated page, that sect
292
324
  passthrough at all — the owned component is the only one.
293
325
  - Reaching for `SelectV2` (`@deprecated`), `SearchSelect` or `SelectSearch` (not deprecated, but not the
294
326
  preferred picker) in new work.
295
- One picker now: `Select` (`native={false}` for the themed, searchable, multi popup).
327
+ One picker now: `Select`, always with `native={false}` in new work (the themed popup).
328
+ - Any browser-native control (`<select>`, `<input type="date">`, `<textarea>`, `window.confirm`)
329
+ or raw Chakra twin where §5a names a library component.
296
330
  `Dropdown` is the exception — it is an action menu, not a picker, and is not replaced.
297
331
  - A card inside a card; a border on a content `Card` (it is borderless by default), or any resting
298
332
  shadow heavier than `shadows.card`.
package/README.md CHANGED
@@ -75,6 +75,10 @@ function App() {
75
75
  export default App;
76
76
  ```
77
77
 
78
+ Building screens? Use the library component for every control, never the browser's or Chakra's —
79
+ [DESIGN-GUIDE.md §5a](DESIGN-GUIDE.md#5a-one-look-everywhere--the-swap-table) maps each native
80
+ element to its component and props (e.g. `Select` always takes `native={false}`).
81
+
78
82
  ## Theming and filled surfaces
79
83
 
80
84
  Nine brand presets with light/dark palettes. Wrap your app in `PixelizeThemeProvider` and read tokens
@@ -1,3 +1,3 @@
1
1
  import type { AssistantThreadProps } from "./AssistantThreadProps";
2
- declare const _default: import("react").MemoExoticComponent<({ messages, renderMessage, messageProps, emptyState, children, stickThreshold, scrollContainerRef, labels, "data-testid": testId, }: AssistantThreadProps) => import("react/jsx-runtime").JSX.Element>;
2
+ declare const _default: import("react").MemoExoticComponent<({ messages, renderMessage, messageProps, emptyState, children, stickThreshold, followMode, scrollContainerRef, labels, "data-testid": testId, }: AssistantThreadProps) => import("react/jsx-runtime").JSX.Element>;
3
3
  export default _default;
@@ -17,6 +17,7 @@ const VisuallyHidden_1 = __importDefault(require("../../VisuallyHidden/VisuallyH
17
17
  const AssistantMessage_1 = __importDefault(require("../message/AssistantMessage"));
18
18
  const assistantModel_1 = require("../assistantModel");
19
19
  const parseMarkdown_1 = require("../markdown/parseMarkdown");
20
+ const replyStartScroll_1 = require("./replyStartScroll");
20
21
  const DEFAULT_LABELS = {
21
22
  region: "Conversation",
22
23
  jumpToLatest: "Jump to latest",
@@ -24,19 +25,28 @@ const DEFAULT_LABELS = {
24
25
  failed: "The assistant's reply failed",
25
26
  stopped: "Response stopped",
26
27
  };
28
+ const SCROLL_KEYS = new Set(["ArrowUp", "ArrowDown", "PageUp", "PageDown", "Home", "End", " "]);
27
29
  const distanceFromBottom = (el) => el.scrollHeight - el.scrollTop - el.clientHeight;
30
+ const nextAlignedReply = (messages, known, current) => {
31
+ const started = messages.filter((m) => !known.has(m.id) && m.role === "assistant" && m.status === "streaming").pop();
32
+ if (started)
33
+ return started.id;
34
+ return messages.some((m) => m.id === current && m.status === "streaming") ? current : null;
35
+ };
28
36
  /**
29
37
  * Scroll container for a conversation. It follows the newest content while the person is at the bottom,
30
38
  * stops following once they scroll up (showing "Jump to latest"), and re-sticks when they send. A polite
31
39
  * live region announces a reply once it finishes streaming, never token by token.
32
40
  */
33
- const AssistantThread = ({ messages, renderMessage, messageProps, emptyState, children, stickThreshold = 48, scrollContainerRef, labels, "data-testid": testId = "assistant-thread", }) => {
41
+ const AssistantThread = ({ messages, renderMessage, messageProps, emptyState, children, stickThreshold = 48, followMode = "bottom", scrollContainerRef, labels, "data-testid": testId = "assistant-thread", }) => {
34
42
  const { colors } = (0, useCustomTheme_1.useCustomTheme)();
35
43
  const text = { ...DEFAULT_LABELS, ...labels };
36
44
  const reducedMotion = (0, motion_1.usePrefersReducedMotion)();
37
45
  const scrollRef = (0, react_1.useRef)(null);
38
46
  const contentRef = (0, react_1.useRef)(null);
39
47
  const stuck = (0, react_1.useRef)(true);
48
+ const aligned = (0, react_1.useRef)(null);
49
+ const knownIds = (0, react_1.useRef)(new Set());
40
50
  const [showJump, setShowJump] = (0, react_1.useState)(false);
41
51
  const [announcement, setAnnouncement] = (0, react_1.useState)("");
42
52
  const statuses = (0, react_1.useRef)(new Map());
@@ -52,35 +62,63 @@ const AssistantThread = ({ messages, renderMessage, messageProps, emptyState, ch
52
62
  else
53
63
  el.scrollTop = top;
54
64
  }, [reducedMotion]);
55
- const onScroll = () => {
65
+ const syncFollow = (0, react_1.useCallback)(() => {
56
66
  const el = scrollRef.current;
57
67
  if (!el)
58
68
  return;
59
69
  const atBottom = distanceFromBottom(el) <= stickThreshold;
60
70
  stuck.current = atBottom;
61
71
  setShowJump(!atBottom);
62
- };
72
+ }, [stickThreshold]);
73
+ const alignReply = (0, react_1.useCallback)(() => {
74
+ const scroll = scrollRef.current;
75
+ const content = contentRef.current;
76
+ if (!scroll || !content)
77
+ return;
78
+ const reply = Array.from(content.querySelectorAll("[data-message-id]")).find((el) => el.dataset.messageId === aligned.current);
79
+ if (!reply)
80
+ return;
81
+ scroll.scrollTop = (0, replyStartScroll_1.replyStartScrollTop)({
82
+ replyTop: reply.offsetTop - scroll.offsetTop,
83
+ scrollHeight: scroll.scrollHeight,
84
+ clientHeight: scroll.clientHeight,
85
+ });
86
+ // NOTE: a held position fires no scroll event, so refresh stuck and the jump button here.
87
+ syncFollow();
88
+ }, [syncFollow]);
63
89
  // New content: follow it if stuck; a message the person just sent always re-sticks.
64
90
  (0, react_1.useLayoutEffect)(() => {
65
91
  const last = messages[messages.length - 1];
66
- if (last && last.id !== lastId.current && last.role === "user")
92
+ const sent = last && last.id !== lastId.current && last.role === "user";
93
+ if (sent)
67
94
  stuck.current = true;
68
95
  lastId.current = last === null || last === void 0 ? void 0 : last.id;
69
- if (stuck.current) {
96
+ if (followMode === "reply-start") {
97
+ aligned.current = nextAlignedReply(messages, knownIds.current, sent ? null : aligned.current);
98
+ knownIds.current = new Set(messages.map((m) => m.id));
99
+ }
100
+ else {
101
+ aligned.current = null;
102
+ }
103
+ if (aligned.current !== null)
104
+ alignReply();
105
+ else if (stuck.current) {
70
106
  scrollToBottom(false);
71
107
  setShowJump(false);
72
108
  }
73
- }, [messages, scrollToBottom]);
109
+ }, [messages, scrollToBottom, alignReply, followMode]);
74
110
  // Growth that is not a new message (markdown reflow, an image loading, a card expanding).
75
111
  (0, react_1.useEffect)(() => {
76
112
  const el = contentRef.current;
77
113
  if (!el)
78
114
  return undefined;
79
115
  return (0, sharedResizeObserver_1.observeResize)(el, () => {
80
- if (stuck.current)
116
+ if (aligned.current !== null)
117
+ alignReply();
118
+ else if (stuck.current)
81
119
  scrollToBottom(false);
82
120
  });
83
- }, [scrollToBottom]);
121
+ }, [scrollToBottom, alignReply]);
84
122
  (0, react_1.useEffect)(() => {
85
123
  const seen = statuses.current;
86
124
  messages.forEach((message) => {
@@ -100,13 +138,21 @@ const AssistantThread = ({ messages, renderMessage, messageProps, emptyState, ch
100
138
  // Labels are read at announcement time on purpose; only message transitions drive this effect.
101
139
  // eslint-disable-next-line react-hooks/exhaustive-deps
102
140
  }, [messages]);
141
+ const stopAligning = () => {
142
+ aligned.current = null;
143
+ };
144
+ const onKeyDown = (event) => {
145
+ if (SCROLL_KEYS.has(event.key))
146
+ stopAligning();
147
+ };
103
148
  const jump = () => {
149
+ aligned.current = null;
104
150
  stuck.current = true;
105
151
  setShowJump(false);
106
152
  scrollToBottom(true);
107
153
  };
108
- return ((0, jsx_runtime_1.jsxs)(react_2.Box, { position: "relative", flex: "1", minH: 0, h: "100%", "data-testid": testId, children: [(0, jsx_runtime_1.jsx)(react_2.Box, { ref: ref, role: "region", "aria-label": text.region, h: "100%", overflowY: "auto", overscrollBehavior: "contain", sx: (0, scrollbar_1.scrollbarStyles)(colors), onScroll: onScroll, "data-testid": `${testId}-scroll`, children: (0, jsx_runtime_1.jsxs)(react_2.Flex, { ref: contentRef, direction: "column", gap: 5, px: 4, py: 4, minH: "100%", children: [messages.length === 0 && emptyState
154
+ return ((0, jsx_runtime_1.jsxs)(react_2.Box, { position: "relative", flex: "1", minH: 0, h: "100%", "data-testid": testId, children: [(0, jsx_runtime_1.jsx)(react_2.Box, { ref: ref, role: "region", "aria-label": text.region, h: "100%", overflowY: "auto", overscrollBehavior: "contain", sx: (0, scrollbar_1.scrollbarStyles)(colors), onScroll: syncFollow, onWheel: stopAligning, onTouchStart: stopAligning, onPointerDown: stopAligning, onKeyDown: onKeyDown, "data-testid": `${testId}-scroll`, children: (0, jsx_runtime_1.jsxs)(react_2.Flex, { ref: contentRef, direction: "column", gap: 5, px: 4, py: 4, minH: "100%", children: [messages.length === 0 && emptyState
109
155
  ? emptyState
110
- : messages.map((message, index) => renderMessage ? ((0, jsx_runtime_1.jsx)(react_2.Box, { children: renderMessage(message, index) }, message.id)) : ((0, jsx_runtime_1.jsx)(AssistantMessage_1.default, { ...messageProps, message: message }, message.id))), children] }) }), showJump ? ((0, jsx_runtime_1.jsx)(react_2.Box, { position: "absolute", bottom: 3, left: "50%", transform: "translateX(-50%)", boxShadow: "md", borderRadius: "full", bg: colors.surfaceRaised, children: (0, jsx_runtime_1.jsx)(Button_1.default, { size: "xs", variant: "outline", colorScheme: "gray", borderRadius: "full", leftIcon: (0, jsx_runtime_1.jsx)(lucide_react_1.ArrowDown, { size: 14 }), label: text.jumpToLatest, onClick: jump, "data-testid": `${testId}-jump` }) })) : null, (0, jsx_runtime_1.jsx)(VisuallyHidden_1.default, { role: "status", "aria-live": "polite", "aria-atomic": "true", "data-testid": `${testId}-live`, children: announcement })] }));
156
+ : messages.map((message, index) => ((0, jsx_runtime_1.jsx)(react_2.Box, { "data-message-id": message.id, children: renderMessage ? (renderMessage(message, index)) : ((0, jsx_runtime_1.jsx)(AssistantMessage_1.default, { ...messageProps, message: message })) }, message.id))), children] }) }), showJump ? ((0, jsx_runtime_1.jsx)(react_2.Box, { position: "absolute", bottom: 3, left: "50%", transform: "translateX(-50%)", boxShadow: "md", borderRadius: "full", bg: colors.surfaceRaised, children: (0, jsx_runtime_1.jsx)(Button_1.default, { size: "xs", variant: "outline", colorScheme: "gray", borderRadius: "full", leftIcon: (0, jsx_runtime_1.jsx)(lucide_react_1.ArrowDown, { size: 14 }), label: text.jumpToLatest, onClick: jump, "data-testid": `${testId}-jump` }) })) : null, (0, jsx_runtime_1.jsx)(VisuallyHidden_1.default, { role: "status", "aria-live": "polite", "aria-atomic": "true", "data-testid": `${testId}-live`, children: announcement })] }));
111
157
  };
112
158
  exports.default = (0, react_1.memo)(AssistantThread);
@@ -28,6 +28,8 @@ export interface AssistantThreadProps {
28
28
  children?: ReactNode;
29
29
  /** Distance from the bottom, in px, that still counts as "at the bottom". Default 48. */
30
30
  stickThreshold?: number;
31
+ /** "bottom" (default) follows the newest content; "reply-start" keeps a new streaming reply's top in view until the person scrolls. */
32
+ followMode?: "bottom" | "reply-start";
31
33
  /** Ref to the scrolling element. */
32
34
  scrollContainerRef?: Ref<HTMLDivElement>;
33
35
  /** Translated region name, button text and announcements. */
@@ -0,0 +1,8 @@
1
+ export declare const REPLY_START_GAP = 12;
2
+ interface ReplyStartGeometry {
3
+ replyTop: number;
4
+ scrollHeight: number;
5
+ clientHeight: number;
6
+ }
7
+ export declare const replyStartScrollTop: ({ replyTop, scrollHeight, clientHeight }: ReplyStartGeometry) => number;
8
+ export {};
@@ -0,0 +1,6 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.replyStartScrollTop = exports.REPLY_START_GAP = void 0;
4
+ exports.REPLY_START_GAP = 12;
5
+ const replyStartScrollTop = ({ replyTop, scrollHeight, clientHeight }) => Math.max(0, Math.min(scrollHeight - clientHeight, replyTop - exports.REPLY_START_GAP));
6
+ exports.replyStartScrollTop = replyStartScrollTop;
@@ -12,6 +12,7 @@ import VisuallyHidden from "../../VisuallyHidden/VisuallyHidden.js";
12
12
  import AssistantMessage from "../message/AssistantMessage.js";
13
13
  import { messageText, truncate } from "../assistantModel.js";
14
14
  import { markdownToPlainText } from "../markdown/parseMarkdown.js";
15
+ import { replyStartScrollTop } from "./replyStartScroll.js";
15
16
  const DEFAULT_LABELS = {
16
17
  region: "Conversation",
17
18
  jumpToLatest: "Jump to latest",
@@ -19,19 +20,28 @@ const DEFAULT_LABELS = {
19
20
  failed: "The assistant's reply failed",
20
21
  stopped: "Response stopped",
21
22
  };
23
+ const SCROLL_KEYS = new Set(["ArrowUp", "ArrowDown", "PageUp", "PageDown", "Home", "End", " "]);
22
24
  const distanceFromBottom = (el) => el.scrollHeight - el.scrollTop - el.clientHeight;
25
+ const nextAlignedReply = (messages, known, current) => {
26
+ const started = messages.filter((m) => !known.has(m.id) && m.role === "assistant" && m.status === "streaming").pop();
27
+ if (started)
28
+ return started.id;
29
+ return messages.some((m) => m.id === current && m.status === "streaming") ? current : null;
30
+ };
23
31
  /**
24
32
  * Scroll container for a conversation. It follows the newest content while the person is at the bottom,
25
33
  * stops following once they scroll up (showing "Jump to latest"), and re-sticks when they send. A polite
26
34
  * live region announces a reply once it finishes streaming, never token by token.
27
35
  */
28
- const AssistantThread = ({ messages, renderMessage, messageProps, emptyState, children, stickThreshold = 48, scrollContainerRef, labels, "data-testid": testId = "assistant-thread", }) => {
36
+ const AssistantThread = ({ messages, renderMessage, messageProps, emptyState, children, stickThreshold = 48, followMode = "bottom", scrollContainerRef, labels, "data-testid": testId = "assistant-thread", }) => {
29
37
  const { colors } = useCustomTheme();
30
38
  const text = { ...DEFAULT_LABELS, ...labels };
31
39
  const reducedMotion = usePrefersReducedMotion();
32
40
  const scrollRef = useRef(null);
33
41
  const contentRef = useRef(null);
34
42
  const stuck = useRef(true);
43
+ const aligned = useRef(null);
44
+ const knownIds = useRef(new Set());
35
45
  const [showJump, setShowJump] = useState(false);
36
46
  const [announcement, setAnnouncement] = useState("");
37
47
  const statuses = useRef(new Map());
@@ -47,35 +57,63 @@ const AssistantThread = ({ messages, renderMessage, messageProps, emptyState, ch
47
57
  else
48
58
  el.scrollTop = top;
49
59
  }, [reducedMotion]);
50
- const onScroll = () => {
60
+ const syncFollow = useCallback(() => {
51
61
  const el = scrollRef.current;
52
62
  if (!el)
53
63
  return;
54
64
  const atBottom = distanceFromBottom(el) <= stickThreshold;
55
65
  stuck.current = atBottom;
56
66
  setShowJump(!atBottom);
57
- };
67
+ }, [stickThreshold]);
68
+ const alignReply = useCallback(() => {
69
+ const scroll = scrollRef.current;
70
+ const content = contentRef.current;
71
+ if (!scroll || !content)
72
+ return;
73
+ const reply = Array.from(content.querySelectorAll("[data-message-id]")).find((el) => el.dataset.messageId === aligned.current);
74
+ if (!reply)
75
+ return;
76
+ scroll.scrollTop = replyStartScrollTop({
77
+ replyTop: reply.offsetTop - scroll.offsetTop,
78
+ scrollHeight: scroll.scrollHeight,
79
+ clientHeight: scroll.clientHeight,
80
+ });
81
+ // NOTE: a held position fires no scroll event, so refresh stuck and the jump button here.
82
+ syncFollow();
83
+ }, [syncFollow]);
58
84
  // New content: follow it if stuck; a message the person just sent always re-sticks.
59
85
  useLayoutEffect(() => {
60
86
  const last = messages[messages.length - 1];
61
- if (last && last.id !== lastId.current && last.role === "user")
87
+ const sent = last && last.id !== lastId.current && last.role === "user";
88
+ if (sent)
62
89
  stuck.current = true;
63
90
  lastId.current = last === null || last === void 0 ? void 0 : last.id;
64
- if (stuck.current) {
91
+ if (followMode === "reply-start") {
92
+ aligned.current = nextAlignedReply(messages, knownIds.current, sent ? null : aligned.current);
93
+ knownIds.current = new Set(messages.map((m) => m.id));
94
+ }
95
+ else {
96
+ aligned.current = null;
97
+ }
98
+ if (aligned.current !== null)
99
+ alignReply();
100
+ else if (stuck.current) {
65
101
  scrollToBottom(false);
66
102
  setShowJump(false);
67
103
  }
68
- }, [messages, scrollToBottom]);
104
+ }, [messages, scrollToBottom, alignReply, followMode]);
69
105
  // Growth that is not a new message (markdown reflow, an image loading, a card expanding).
70
106
  useEffect(() => {
71
107
  const el = contentRef.current;
72
108
  if (!el)
73
109
  return undefined;
74
110
  return observeResize(el, () => {
75
- if (stuck.current)
111
+ if (aligned.current !== null)
112
+ alignReply();
113
+ else if (stuck.current)
76
114
  scrollToBottom(false);
77
115
  });
78
- }, [scrollToBottom]);
116
+ }, [scrollToBottom, alignReply]);
79
117
  useEffect(() => {
80
118
  const seen = statuses.current;
81
119
  messages.forEach((message) => {
@@ -95,13 +133,21 @@ const AssistantThread = ({ messages, renderMessage, messageProps, emptyState, ch
95
133
  // Labels are read at announcement time on purpose; only message transitions drive this effect.
96
134
  // eslint-disable-next-line react-hooks/exhaustive-deps
97
135
  }, [messages]);
136
+ const stopAligning = () => {
137
+ aligned.current = null;
138
+ };
139
+ const onKeyDown = (event) => {
140
+ if (SCROLL_KEYS.has(event.key))
141
+ stopAligning();
142
+ };
98
143
  const jump = () => {
144
+ aligned.current = null;
99
145
  stuck.current = true;
100
146
  setShowJump(false);
101
147
  scrollToBottom(true);
102
148
  };
103
- return (_jsxs(Box, { position: "relative", flex: "1", minH: 0, h: "100%", "data-testid": testId, children: [_jsx(Box, { ref: ref, role: "region", "aria-label": text.region, h: "100%", overflowY: "auto", overscrollBehavior: "contain", sx: scrollbarStyles(colors), onScroll: onScroll, "data-testid": `${testId}-scroll`, children: _jsxs(Flex, { ref: contentRef, direction: "column", gap: 5, px: 4, py: 4, minH: "100%", children: [messages.length === 0 && emptyState
149
+ return (_jsxs(Box, { position: "relative", flex: "1", minH: 0, h: "100%", "data-testid": testId, children: [_jsx(Box, { ref: ref, role: "region", "aria-label": text.region, h: "100%", overflowY: "auto", overscrollBehavior: "contain", sx: scrollbarStyles(colors), onScroll: syncFollow, onWheel: stopAligning, onTouchStart: stopAligning, onPointerDown: stopAligning, onKeyDown: onKeyDown, "data-testid": `${testId}-scroll`, children: _jsxs(Flex, { ref: contentRef, direction: "column", gap: 5, px: 4, py: 4, minH: "100%", children: [messages.length === 0 && emptyState
104
150
  ? emptyState
105
- : messages.map((message, index) => renderMessage ? (_jsx(Box, { children: renderMessage(message, index) }, message.id)) : (_jsx(AssistantMessage, { ...messageProps, message: message }, message.id))), children] }) }), showJump ? (_jsx(Box, { position: "absolute", bottom: 3, left: "50%", transform: "translateX(-50%)", boxShadow: "md", borderRadius: "full", bg: colors.surfaceRaised, children: _jsx(Button, { size: "xs", variant: "outline", colorScheme: "gray", borderRadius: "full", leftIcon: _jsx(ArrowDown, { size: 14 }), label: text.jumpToLatest, onClick: jump, "data-testid": `${testId}-jump` }) })) : null, _jsx(VisuallyHidden, { role: "status", "aria-live": "polite", "aria-atomic": "true", "data-testid": `${testId}-live`, children: announcement })] }));
151
+ : messages.map((message, index) => (_jsx(Box, { "data-message-id": message.id, children: renderMessage ? (renderMessage(message, index)) : (_jsx(AssistantMessage, { ...messageProps, message: message })) }, message.id))), children] }) }), showJump ? (_jsx(Box, { position: "absolute", bottom: 3, left: "50%", transform: "translateX(-50%)", boxShadow: "md", borderRadius: "full", bg: colors.surfaceRaised, children: _jsx(Button, { size: "xs", variant: "outline", colorScheme: "gray", borderRadius: "full", leftIcon: _jsx(ArrowDown, { size: 14 }), label: text.jumpToLatest, onClick: jump, "data-testid": `${testId}-jump` }) })) : null, _jsx(VisuallyHidden, { role: "status", "aria-live": "polite", "aria-atomic": "true", "data-testid": `${testId}-live`, children: announcement })] }));
106
152
  };
107
153
  export default memo(AssistantThread);
@@ -0,0 +1,2 @@
1
+ export const REPLY_START_GAP = 12;
2
+ export const replyStartScrollTop = ({ replyTop, scrollHeight, clientHeight }) => Math.max(0, Math.min(scrollHeight - clientHeight, replyTop - REPLY_START_GAP));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pixelize-design-library",
3
- "version": "3.2.0",
3
+ "version": "3.3.1",
4
4
  "description": "React component library for Pixelize apps: themeable Chakra-based components, design tokens and light/dark brand theming.",
5
5
  "keywords": [
6
6
  "react",