@ahrowe/ui 0.48.0 → 0.50.0

package/docs/ChatMessageList.md

@@ -0,0 +1,113 @@
+# ChatMessageList
+
+**When to use:** The scrolling conversation of a chat: a messenger, a support widget, an AI assistant. It opens at the newest message, follows new ones while the user is at the bottom, and loads older ones at the top without moving the view. Fill it with [ChatMessage](ChatMessage.md)s and put a [ChatComposer](ChatComposer.md) under it. For a long list that is not a conversation, use [VirtualList](VirtualList.md).
+
+**Keywords:** messenger, whatsapp, support chat, chatbot, assistant, LLM, history, thread, stick to bottom, autoscroll, infinite scroll, load older, jump to latest, unread
+
+**Import:** `import { ChatMessageList } from '@ahrowe/ui'`  
+**Types:** `import type { ChatMessageListProps, ChatMessageListHandle, ChatMessageListLabels } from '@ahrowe/ui'`
+
+## A whole chat
+
+```tsx
+import { useRef, useState } from 'react';
+import { Avatar, ChatComposer, ChatMessage, ChatMessageList, ChatMessageStatus, Divider } from '@ahrowe/ui';
+import type { ChatMessageListHandle } from '@ahrowe/ui';
+
+function Chat({ me, initial }: ChatProps) {
+  const [messages, setMessages] = useState<Message[]>(initial);
+  const [hasOlder, setHasOlder] = useState(true);
+  const listRef = useRef<ChatMessageListHandle>(null);
+
+  const loadOlder = async () => {
+    const page = await api.messagesBefore(messages[0].id);
+    setMessages((current) => [...page.messages, ...current]);
+    setHasOlder(page.hasMore);
+  };
+
+  const send = (text: string) => {
+    setMessages((current) => [...current, { id: crypto.randomUUID(), authorId: me.id, text, status: ChatMessageStatus.Sending }]);
+    // Sending from further up the history takes the user down to their message.
+    listRef.current?.scrollToBottom();
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', height: '100dvh' }}>
+      <ChatMessageList ref={listRef} style={{ flex: 1 }} onLoadMore={hasOlder ? loadOlder : undefined}>
+        <Divider text='Today' />
+        {messages.map((message, index) => (
+          <ChatMessage
+            key={message.id}
+            isOwn={message.authorId === me.id}
+            isContinued={messages[index - 1]?.authorId === message.authorId}
+            avatar={message.authorId === me.id ? undefined : <Avatar name={message.authorName} />}
+            author={message.authorId === me.id ? undefined : message.authorName}
+            status={message.status}
+          >
+            {message.text}
+          </ChatMessage>
+        ))}
+      </ChatMessageList>
+      <ChatComposer onSend={send} />
+    </div>
+  );
+}
+```
+
+An AI chat is the same with a `Plain` answer that grows as it streams, and the composer's stop
+button while it does:
+
+```tsx
+<ChatMessageList ref={listRef} style={{ flex: 1 }}>
+  {turns.map((turn) =>
+    turn.role === 'user' ? (
+      <ChatMessage key={turn.id} isOwn>{turn.text}</ChatMessage>
+    ) : (
+      <ChatMessage key={turn.id} styleType={ChatMessageStyleType.Plain} actions={<CopyButton value={turn.text} />}>
+        <Markdown>{turn.text}</Markdown>
+      </ChatMessage>
+    ),
+  )}
+</ChatMessageList>
+<ChatComposer onSend={ask} onStop={isStreaming ? stop : undefined} />
+```
+
+## Scrolling
+
+- **Following.** While the user is within 32px of the bottom, anything that makes the content
+  taller keeps the newest message in view: a new message, an answer streaming in, an image
+  loading, the list getting shorter because the composer grew or a phone keyboard opened.
+- **Reading back.** As soon as the user scrolls up, however little, nothing moves under them: new
+  messages arrive below, and a round button appears in the corner that jumps back down and starts
+  following again. It turns `Primary` once a new message has arrived below. Scrolling back to the
+  bottom by hand does the same.
+- **After sending**, call `scrollToBottom()` on the handle, or a user who sent from further up
+  never sees their own message arrive.
+- **Older messages.** With `onLoadMore`, reaching the top calls it and shows a loader there.
+  Prepend what it loads; the message that was at the top stays exactly where it was, at the very
+  top too, where the browser's own scroll anchoring does nothing and Safari has none at all. It is
+  called again while the loaded page still leaves the top in view. If it rejects, it is called
+  again after three seconds if the top is still in view, or whenever the user next scrolls there.
+  Pass `undefined` once there is nothing older.
+
+**Sizing.** The list scrolls itself and fills the height it is given: `flex: 1` in a column, as
+above, or a `height`. A conversation shorter than the list sits at the bottom, by the composer. To
+start at the top instead, as an AI chat often does: `styles={{ content: { marginTop: 0 } }}`.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Messages, oldest first, and anything between them: a `Divider` with a date, a typing indicator |
+| `onLoadMore` | `() => Promise<void>` | Loads older messages when the top comes into view, see above |
+| `ref` | `Ref<ChatMessageListHandle>` | `scrollToBottom()`: back to the newest message, smoothly unless the user prefers reduced motion, and following again |
+
+**Accessibility:** the scrolling element is a `role="log"`, which screen readers announce
+politely as messages are added, named "Messages" (`labels.messages`). It is a tab stop of its own,
+so the history can be scrolled from the keyboard, and `aria-busy` while older messages load.
+
+**Global defaults:** adopts `ConfigProvider`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `viewport` (the scrolling log) `content` (the column of messages inside it) `scrollButton`
+
+**Labels:** `messages` `scrollToBottom`: the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `ChatMessageListLabels`.

package/docs/ConfigProvider.md

@@ -97,6 +97,7 @@ Each entry is a `Partial<...Props>`, so any of that component's props can be def
 - **Form inputs:** `Input` · `Textarea` · `NumberInput` · `Dropdown` · `InputDropdown` · `Checkbox` · `Switch` · `RadioGroup` · `DatePicker` · `OptionPicker` · `OtpInput`
 - **Display:** `Button` · `CopyButton` · `ActionButtons` · `Badge` · `Chip` · `Card` · `SectionHeader` · `Skeleton` · `Loader` · `LoadingOverlay` · `Accordion` · `Divider` · `Timer` · `WeatherIcon` · `Stepper`
 - **Overlays:** `ConfirmModal` · `Modal` · `CommandPalette` · `Popover`
+- **Chat:** `ChatMessage` · `ChatMessageList` · `ChatComposer`
 - **Editors:** `RoomDrawer`, `RoomViewer`
 - **Scheduling:** `Calendar`, for `labels`, `locale`, `weekStartsOn`, `slotMinutes`, `views`, `hiddenDays`, `scrollToHour`, `workingHours` and `showWeekNumbers` only (see below)
 

package/docs/Hooks.md

@@ -59,6 +59,7 @@ Two rules worth knowing:
 | `target` | `RefObject<HTMLElement \| null>` | window | Scope the shortcuts to one element |
 | `enableInFields` | `boolean` | `false` | Let a combo fire while a text field or `contenteditable` has focus. Only combos the field would otherwise consume are held back: a single character, or an editing key (`arrowup`, `home`, `backspace`, `enter`, `tab`, …). Anything carrying Ctrl, Cmd or Alt fires regardless, and so do `f2`, `escape` and the other keys a field does not use |
 | `preventDefault` | `boolean` | `true` | Call `preventDefault()` on a match, so `mod+s` does not also open the browser's save dialog |
+| `repeat` | `boolean` | `false` | Fire again for each repeat while the combo is held. Off, holding `mod+s` saves once; turn it on for keys that step through something |
 
 Shortcuts keep firing while a `Modal` or `Drawer` is open, which is usually what a command palette
 wants. Pass `enabled` for the ones that should not:
@@ -67,7 +68,14 @@ wants. Pass `enabled` for the ones that should not:
 useHotkeys({ n: createRecord }, { enabled: !isModalOpen });
 ```
 
-A held key repeats, as it does natively. Check `event.repeat` in the handler to ignore repeats.
+A held combo fires once, where the browser's key repeat would save over and over or flicker a
+toggle. The skipped repeats are still `preventDefault()`-ed. Where a repeat is the point, as with
+arrows or zoom, ask for it, in a call of its own if the page also has actions:
+
+```tsx
+useHotkeys({ 'mod+s': save, '?': toggleHelp });
+useHotkeys({ j: selectNext, k: selectPrevious }, { repeat: true });
+```
 
 ### formatHotkey
 
@@ -79,9 +87,10 @@ formatHotkey('mod+shift+k'); // '⇧⌘K' on an Apple platform, 'Ctrl+Shift+K' e
 formatHotkey('f2'); // 'F2'
 ```
 
-This is what `Menu` uses to draw the shortcut on an entry, from the same string `menuHotkeys`
-turns into a binding, see [Menu.md](Menu.md). A combo it cannot parse is handed back unchanged. The platform is read at call
-time, so a server-rendered page renders the non-Apple spelling.
+This is what `Menu`, `CommandPalette` and `Button` use to draw a shortcut, from the same string
+`useHotkeys` binds, see [Menu.md](Menu.md) and [Button.md](Button.md). A combo it cannot parse is
+handed back unchanged. The platform is read at call time, so a server-rendered page renders the
+non-Apple spelling.
 
 ## useMediaQuery
 
@@ -266,3 +275,13 @@ Hooks documented with the thing they belong to:
 - `useComponentDefaults`, `useLabels` — see [ConfigProvider.md](ConfigProvider.md)
 - `useFormValidator` — see [FormValidator.md](FormValidator.md)
 - `useFormValidatorGroup` — see [FormValidatorGroup.md](FormValidatorGroup.md)
+
+## Migration from repeating hotkeys
+
+Before 0.49, a held `useHotkeys` combo fired its handler for every repeat the browser sent. It now
+fires once. Nothing fails to compile, so look for shortcuts that are meant to be held:
+
+| Before | After |
+|--------|-------|
+| `useHotkeys({ arrowdown: next })`, relying on the repeat | `useHotkeys({ arrowdown: next }, { repeat: true })` |
+| `if (event.repeat) return;` at the top of a handler | nothing: drop the check |

package/docs/Menu.md

@@ -34,7 +34,7 @@ const items: MenuEntry[] = [
 
 `keywords` are extra search terms for [CommandPalette](CommandPalette.md), which takes the same entries. The menu ignores them.
 
-**Shortcuts are drawn, not bound.** A `shortcut` is a combo in [useHotkeys](Hooks.md) spelling, and the menu writes it on the trailing edge for the platform the reader is on: `mod+s` shows as `⌘S` on an Apple one and `Ctrl+S` everywhere else. So there is one spelling per shortcut and a hand-written `'⌘S'` can no longer be wrong on Windows.
+**Shortcuts are drawn, not bound.** A `shortcut` is a combo in [useHotkeys](Hooks.md) spelling, and the menu writes it on the trailing edge for the platform the reader is on: `mod+s` shows as `⌘S` on an Apple one and `Ctrl+S` everywhere else. So there is one spelling per shortcut and a hand-written `'⌘S'` can no longer be wrong on Windows. Screen readers get it through `aria-keyshortcuts`, not as part of the item's name.
 
 Listening for it is yours, because only your app knows what else is listening: if it already binds `⌘S` and the menu bound it too, both would fire and the action would run twice. `menuHotkeys` turns the same entries into a map for `useHotkeys`, so the one spelling covers the hint and the binding:
 

package/docs/TabHeader.md

@@ -1,18 +1,18 @@
 # TabHeader
 
-**When to use:** A horizontal row of tabs to switch between sibling views or sections — settings panels, dashboards, detail pages. Each tab carries an icon plus an optional title and subtitle.
+**When to use:** A horizontal row of tabs to switch between sibling views or sections — settings panels, dashboards, detail pages. Each tab carries an icon plus an optional title, subtitle and end content such as a badge.
 
-**Keywords:** tabs navigation, tab bar
+**Keywords:** tabs navigation, tab bar, pill, counter
 
 **Import:** `import { TabHeader } from '@ahrowe/ui'`
 
-**Mobile behaviour:** On narrow screens (≤ 640px) only the active tab keeps its title and subtitle; every other tab collapses to just its icon.
+**Mobile behaviour:** On narrow screens (≤ 640px) only the active tab keeps its title and subtitle; every other tab collapses to its icon and `endContent`.
 
 ```tsx
 import { useState } from 'react';
-import { TabHeader } from '@ahrowe/ui';
+import { TabHeader, Badge, ThemeColor } from '@ahrowe/ui';
 import type { TabHeaderTab } from '@ahrowe/ui';
-import { faUser, faBell, faGear } from '@fortawesome/free-solid-svg-icons';
+import { faUser, faBell, faGear, faInbox, faAt } from '@fortawesome/free-solid-svg-icons';
 
 const TABS: TabHeaderTab[] = [
   { id: 'profile', icon: faUser, title: 'Profile', subtitle: 'Your details' },
@@ -32,6 +32,16 @@ function Example() {
   onChange={setTab}
 />
 
+// A count next to the title, still shown when a narrow screen collapses the tab
+<TabHeader
+  tabs={[
+    { id: 'inbox', icon: faInbox, title: 'Inbox', endContent: <Badge count={12} /> },
+    { id: 'mentions', icon: faAt, title: 'Mentions', endContent: <Badge count={3} color={ThemeColor.Error} /> },
+  ]}
+  currentTab={tab}
+  onChange={setTab}
+/>
+
 // Disabled tab — dimmed and not selectable
 <TabHeader
   tabs={[
@@ -57,8 +67,9 @@ function Example() {
 |-------|------|-------------|
 | `id` | `string` | Unique identifier, matched against `currentTab` |
 | `icon` | `IconDefinition \| ReactElement` | FontAwesome icon or any React element (always visible, incl. mobile) |
-| `title` | `string` | Optional title next to the icon |
-| `subtitle` | `string` | Optional subtitle beneath the title |
+| `title` | `ReactNode` | Optional title next to the icon |
+| `subtitle` | `ReactNode` | Optional subtitle beneath the title |
+| `endContent` | `ReactNode` | After the labels. Stays visible when a narrow screen collapses the tab, so keep it small: a `Badge`, a dot |
 | `disabled` | `boolean` | Dim the tab and prevent selection |
 
-**Slots:** `root` `tab` `icon` `labels` `title` `subtitle`
+**Slots:** `root` `tab` `icon` `labels` `title` `subtitle` `endContent`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.48.0",
+  "version": "0.50.0",
   "description": "A React UI component library with theming, CSS Modules, and TypeScript support",
   "keywords": [
     "agent",