@adatechnology/conversations-ui 0.6.0 → 0.7.0

package/src/participant/participantScrollbars.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from 'bun:test'
+
+import { PARTICIPANT_CSS, declarationsIn, mediaBody, toRem } from './participantCss.test-helper'
+
+const VERTICAL_AREAS = ['.cv-p-thread__scroll', '.cv-p-inbox', '.cv-p-composer__input']
+const HORIZONTAL_STRIPS = ['.cv-p-filters', '.cv-p-quick']
+const NO_PREFERENCE = '(prefers-reduced-motion: no-preference)'
+const FORCED_COLORS = '(forced-colors: active)'
+const WEBKIT_GUARD = 'not (forced-colors: active)'
+
+function webkitRules(selector: string): Map<string, string> {
+  return declarationsIn(`${selector}::-webkit-scrollbar`, mediaBody(WEBKIT_GUARD))
+}
+
+describe.each(VERTICAL_AREAS)('vertical scroller %s', (selector) => {
+  const declarations = declarationsIn(selector)
+
+  it('has a thin themed scrollbar from the tokens', () => {
+    expect(declarations.get('scrollbar-width')).toBe('thin')
+    expect(declarations.get('scrollbar-color')).toBe('var(--cv-p-i-scrollbar-thumb) transparent')
+  })
+
+  it('does not chain the scroll to the page', () => {
+    expect(declarations.get('overscroll-behavior-y')).toBe('contain')
+  })
+
+  it('has a 6px track-less webkit scrollbar with a rounded thumb and no arrows', () => {
+    expect(webkitRules(selector).get('width')).toBe('6px')
+    expect(webkitRules(selector).get('height')).toBe('6px')
+    const track = declarationsIn(`${selector}::-webkit-scrollbar-track`, mediaBody(WEBKIT_GUARD))
+    expect(track.get('background')).toBe('transparent')
+    const thumb = declarationsIn(`${selector}::-webkit-scrollbar-thumb`, mediaBody(WEBKIT_GUARD))
+    expect(thumb.get('background-color')).toBe('var(--cv-p-i-scrollbar-thumb)')
+    expect(thumb.get('border-radius')).toBe('var(--cv-p-i-radius)')
+    const buttons = declarationsIn(`${selector}::-webkit-scrollbar-button`, mediaBody(WEBKIT_GUARD))
+    expect(buttons.get('display')).toBe('none')
+  })
+
+  it('highlights the thumb with the accent on hover and drag', () => {
+    const hover = declarationsIn(`${selector}::-webkit-scrollbar-thumb:hover`, mediaBody(WEBKIT_GUARD))
+    const active = declarationsIn(`${selector}::-webkit-scrollbar-thumb:active`, mediaBody(WEBKIT_GUARD))
+    expect(hover.get('background-color')).toBe('var(--cv-p-i-scrollbar-thumb-hover)')
+    expect(active.get('background-color')).toBe('var(--cv-p-i-scrollbar-thumb-hover)')
+  })
+
+  it('goes back to the system scrollbar under forced colors', () => {
+    const forced = declarationsIn(selector, mediaBody(FORCED_COLORS))
+    expect(forced.get('scrollbar-color')).toBe('auto')
+    expect(forced.get('scrollbar-width')).toBe('auto')
+  })
+})
+
+describe('scrollbar tokens', () => {
+  const root = declarationsIn('.cv-p')
+
+  it('derive from the existing tokens and are overridable', () => {
+    expect(root.get('--cv-p-i-scrollbar-thumb')).toBe('var(--cv-p-scrollbar-thumb, var(--cv-p-i-border))')
+    expect(root.get('--cv-p-i-scrollbar-thumb-hover')).toBe('var(--cv-p-scrollbar-thumb-hover, var(--cv-p-i-accent))')
+  })
+})
+
+describe('thread scrollbar does not move the bubbles', () => {
+  it('reserves no gutter', () => {
+    expect(declarationsIn('.cv-p-thread__scroll').get('scrollbar-gutter')).toBeUndefined()
+    expect(declarationsIn('.cv-p-inbox').get('scrollbar-gutter')).toBeUndefined()
+  })
+})
+
+describe.each(HORIZONTAL_STRIPS)('horizontal strip %s', (selector) => {
+  const declarations = declarationsIn(selector)
+
+  it('hides the scrollbar everywhere', () => {
+    expect(declarations.get('scrollbar-width')).toBe('none')
+    expect(declarationsIn(`${selector}::-webkit-scrollbar`).get('display')).toBe('none')
+  })
+
+  it('fades both edges to hint that it scrolls', () => {
+    const mask = declarations.get('mask-image') ?? ''
+    expect(mask).toContain('linear-gradient(to right')
+    expect(mask).toContain('transparent')
+    expect(declarations.get('-webkit-mask-image')).toBe(mask)
+  })
+
+  it('snaps with proximity and does not chain sideways', () => {
+    expect(declarations.get('scroll-snap-type')).toBe('x proximity')
+    expect(declarations.get('overscroll-behavior-x')).toBe('contain')
+    expect(declarations.get('-webkit-overflow-scrolling')).toBe('touch')
+  })
+
+  it('keeps the first chip clear of the fade', () => {
+    expect(declarations.get('scroll-padding-inline')).toBe('var(--cv-p-i-fade)')
+    expect(declarations.get('padding-inline')).toBe('var(--cv-p-i-fade)')
+    expect(toRem(declarationsIn(selector).get('--cv-p-i-fade'))).toBeGreaterThanOrEqual(0.75)
+    expect(declarationsIn(`${selector} > .cv-p-chip`).get('scroll-snap-align')).toBe('start')
+  })
+
+  it('drops the mask under forced colors', () => {
+    const forced = declarationsIn(selector, mediaBody(FORCED_COLORS))
+    expect(forced.get('mask-image')).toBe('none')
+    expect(forced.get('-webkit-mask-image')).toBe('none')
+  })
+})
+
+describe('smooth scrolling', () => {
+  const SMOOTH_AREAS = ['.cv-p-inbox', '.cv-p-filters', '.cv-p-quick']
+
+  it.each(SMOOTH_AREAS)('%s is smooth only when motion is welcome', (selector) => {
+    expect(declarationsIn(selector, mediaBody(NO_PREFERENCE)).get('scroll-behavior')).toBe('smooth')
+    expect(declarationsIn(selector).get('scroll-behavior')).toBeUndefined()
+  })
+
+  it('never makes the thread scroller smooth: its programmatic positioning must stay instant', () => {
+    expect(declarationsIn('.cv-p-thread__scroll').get('scroll-behavior')).toBeUndefined()
+    expect(declarationsIn('.cv-p-thread__scroll', mediaBody(NO_PREFERENCE)).get('scroll-behavior')).toBeUndefined()
+  })
+
+  it('has no scroll-behavior outside the no-preference block', () => {
+    const outside = PARTICIPANT_CSS.replace(mediaBody(NO_PREFERENCE) ?? '', '')
+    expect(outside).not.toMatch(/(?<!over)scroll-behavior/)
+  })
+})
+
+describe('scroll-to-latest button styles', () => {
+  const button = declarationsIn('.cv-p-thread__latest-button')
+
+  it('is a 44px touch target', () => {
+    expect(button.get('width')).toBe('var(--cv-p-i-touch)')
+    expect(button.get('height')).toBe('var(--cv-p-i-touch)')
+    expect(toRem(declarationsIn('.cv-p').get('--cv-p-i-touch'))).toBeGreaterThanOrEqual(2.75)
+  })
+
+  it('floats without taking room in the scroller', () => {
+    const anchor = declarationsIn('.cv-p-thread__latest')
+    expect(anchor.get('position')).toBe('sticky')
+    expect(anchor.get('bottom')).toBe('0')
+    expect(anchor.get('height')).toBe('0')
+    expect(button.get('position')).toBe('absolute')
+  })
+
+  it('animates its entrance only when motion is welcome', () => {
+    expect(declarationsIn('.cv-p-thread__latest-button', mediaBody(NO_PREFERENCE)).get('animation')).toContain(
+      'cv-p-latest-in',
+    )
+    expect(button.get('animation')).toBeUndefined()
+  })
+
+  it('outlines the badge under forced colors', () => {
+    expect(declarationsIn('.cv-p-thread__latest-badge', mediaBody(FORCED_COLORS)).get('border')).toContain('ButtonText')
+  })
+})
+
+describe('no leftovers', () => {
+  it('uses no Tailwind and no host vocabulary in the new rules', () => {
+    expect(PARTICIPANT_CSS).not.toMatch(/@apply|@tailwind/)
+  })
+})

package/src/participant/participantSubjectIcon.test.tsx

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'bun:test'
+
+import { buildConversation } from './participantFixtures.test-helper'
+import { resolveConversationIcon } from './participantSubjectIcon'
+
+const conversation = buildConversation({ subjectId: '1' })
+const group = { subjectType: 'invoice', label: 'Invoices', icon: <i>group</i> }
+
+describe('resolveConversationIcon', () => {
+  it('prefers the host icon, then the group icon, then nothing', () => {
+    const host = <b>host</b>
+    expect(resolveConversationIcon({ conversation, group, renderSubjectIcon: () => host })).toBe(host)
+    expect(resolveConversationIcon({ conversation, group })).toBe(group.icon)
+    expect(resolveConversationIcon({ conversation, group: { ...group, icon: undefined } })).toBeUndefined()
+    expect(resolveConversationIcon({ conversation, group: undefined })).toBeUndefined()
+  })
+
+  it.each([null, undefined, false, ''])('treats %p from the host as no icon, like the list row', (empty) => {
+    expect(resolveConversationIcon({ conversation, group, renderSubjectIcon: () => empty })).toBe(group.icon)
+  })
+
+  it('hands the conversation to the host renderer', () => {
+    const seen: string[] = []
+    resolveConversationIcon({ conversation, group, renderSubjectIcon: (item) => seen.push(item.subjectId) })
+    expect(seen).toEqual(['1'])
+  })
+})

package/src/participant/participantSubjectIcon.ts

@@ -0,0 +1,26 @@
+import type { ReactNode } from 'react'
+
+import type { ParticipantConversationSummary } from '@adatechnology/conversation-contracts'
+
+import type { ParticipantSubjectGroup, ParticipantSubjectIconRenderer } from './participant.types'
+
+export type ResolveConversationIconParams = {
+  readonly conversation: ParticipantConversationSummary
+  readonly group: ParticipantSubjectGroup | undefined
+  readonly renderSubjectIcon?: ParticipantSubjectIconRenderer
+}
+
+export function isDrawable(node: ReactNode): boolean {
+  return node !== null && node !== undefined && node !== false && node !== ''
+}
+
+/** Host icon, then group icon, then nothing; the list row adds its own text fallback, the header draws no tile. */
+export function resolveConversationIcon({
+  conversation,
+  group,
+  renderSubjectIcon,
+}: ResolveConversationIconParams): ReactNode | undefined {
+  const custom = renderSubjectIcon?.(conversation)
+  if (isDrawable(custom)) return custom
+  return isDrawable(group?.icon) ? group?.icon : undefined
+}

package/src/participant/useParticipantCopyFeedback.ts

@@ -0,0 +1,33 @@
+import { useEffect, useReducer } from 'react'
+
+import { useAnnounceCopy } from './ParticipantCopyAnnouncer'
+import { INITIAL_PROTOCOL_COPY_STATE, copyProtocolToClipboard, protocolCopyReducer } from './participantProtocolCopy'
+
+const COPIED_FEEDBACK_MS = 2000
+
+export type CopyFeedback = {
+  readonly isCopied: boolean
+  readonly copy: (value: string, announcement: string) => void
+}
+
+/** Copied state is local to each token; a clipboard failure is silent and shows nothing. */
+export function useParticipantCopyFeedback(): CopyFeedback {
+  const [state, dispatch] = useReducer(protocolCopyReducer, INITIAL_PROTOCOL_COPY_STATE)
+  const announce = useAnnounceCopy()
+  const { isCopied, copyCount } = state
+
+  useEffect(() => {
+    if (!isCopied) return undefined
+    const timer = setTimeout(() => dispatch({ type: 'expired' }), COPIED_FEEDBACK_MS)
+    return () => clearTimeout(timer)
+  }, [isCopied, copyCount])
+
+  async function copyValue(value: string, announcement: string): Promise<void> {
+    const clipboard = typeof navigator === 'undefined' ? undefined : navigator.clipboard
+    if (!(await copyProtocolToClipboard(value, clipboard))) return
+    dispatch({ type: 'copied' })
+    announce(announcement)
+  }
+
+  return { isCopied, copy: (value, announcement) => void copyValue(value, announcement) }
+}

package/src/participant/useParticipantThreadScroll.ts

@@ -2,6 +2,7 @@ import { useEffect, useRef } from 'react'
 
 import { collectServerMessageIds, countNewIncomingMessages } from './participantNewMessages'
 import type { ParticipantTimelineItem } from './participantMessages'
+import { useScrollAwayState } from './useScrollAwayState'
 import { useStickToBottom, type ParticipantThreadScroll } from './useStickToBottom'
 
 export type UseParticipantThreadScrollResult = {
@@ -14,8 +15,15 @@ function keyOf(item: ParticipantTimelineItem | undefined): string | undefined {
   return item.kind === 'server' ? item.message.id : `pending:${item.pending.clientMessageId}`
 }
 
-export function useParticipantThreadScroll(items: readonly ParticipantTimelineItem[]): UseParticipantThreadScrollResult {
-  const { scroll, isNearBottom } = useStickToBottom({ firstKey: keyOf(items[0]), lastKey: keyOf(items[items.length - 1]) })
+export function useParticipantThreadScroll(
+  items: readonly ParticipantTimelineItem[],
+): UseParticipantThreadScrollResult {
+  const { scroll: base, isNearBottom } = useStickToBottom({
+    firstKey: keyOf(items[0]),
+    lastKey: keyOf(items[items.length - 1]),
+  })
+  const { isAwayFromBottom, scrollToLatest } = useScrollAwayState(base.ref, isNearBottom)
+  const scroll = { ...base, isAwayFromBottom, scrollToLatest }
   const seenIds = useRef<ReadonlySet<string>>(new Set())
 
   useEffect(() => {

package/src/participant/useRevealActiveChip.ts

@@ -0,0 +1,20 @@
+import { useEffect, useRef, type RefObject } from 'react'
+
+import { readPrefersReducedMotion, scrollIntoViewOptions } from './participantScrollView'
+
+/** Brings the pressed chip into view when the active one changes; the first render never scrolls. */
+export function useRevealActiveChip(active: string): RefObject<HTMLDivElement | null> {
+  const strip = useRef<HTMLDivElement | null>(null)
+  const previousActive = useRef<string | undefined>(undefined)
+
+  useEffect(() => {
+    const wasActive = previousActive.current
+    previousActive.current = active
+    if (wasActive === undefined || wasActive === active) return
+    strip.current
+      ?.querySelector<HTMLElement>('[aria-pressed="true"]')
+      ?.scrollIntoView(scrollIntoViewOptions(readPrefersReducedMotion()))
+  }, [active])
+
+  return strip
+}

package/src/participant/useScrollAwayState.ts

@@ -0,0 +1,24 @@
+import { useCallback, type RefObject } from 'react'
+
+import { readPrefersReducedMotion, scrollToLatestOptions } from './participantScrollView'
+
+export type UseScrollAwayStateResult = {
+  readonly isAwayFromBottom: boolean
+  readonly scrollToLatest: () => void
+}
+
+/** Away is the negation of the near-the-end state useStickToBottom already tracks with shouldStickToBottom. */
+export function useScrollAwayState(
+  ref: RefObject<HTMLDivElement | null>,
+  isNearBottom: boolean,
+): UseScrollAwayStateResult {
+  const scrollToLatest = useCallback((): void => {
+    const element = ref.current
+    if (!element) return
+    element.scrollTo(
+      scrollToLatestOptions({ scrollHeight: element.scrollHeight, isReducedMotion: readPrefersReducedMotion() }),
+    )
+  }, [ref])
+
+  return { isAwayFromBottom: !isNearBottom, scrollToLatest }
+}

package/src/participant/useStickToBottom.ts

@@ -1,6 +1,11 @@
 import { useCallback, useLayoutEffect, useRef, useState, type RefObject, type UIEvent } from 'react'
 
-import { NEAR_BOTTOM_THRESHOLD_PX, resolveScrollAction, scrollAnchorAfterPrepend, shouldStickToBottom } from './participantScroll'
+import {
+  NEAR_BOTTOM_THRESHOLD_PX,
+  resolveScrollAction,
+  scrollAnchorAfterPrepend,
+  shouldStickToBottom,
+} from './participantScroll'
 
 export type UseStickToBottomParams = {
   readonly firstKey: string | undefined
@@ -10,6 +15,9 @@ export type UseStickToBottomParams = {
 export type ParticipantThreadScroll = {
   readonly ref: RefObject<HTMLDivElement | null>
   readonly onScroll: (event: UIEvent<HTMLDivElement>) => void
+  /** Absent draws no scroll-to-latest button. */
+  readonly isAwayFromBottom?: boolean
+  readonly scrollToLatest?: () => void
 }
 
 export type UseStickToBottomResult = {
@@ -27,7 +35,13 @@ type Snapshot = {
 
 export function useStickToBottom({ firstKey, lastKey }: UseStickToBottomParams): UseStickToBottomResult {
   const ref = useRef<HTMLDivElement | null>(null)
-  const snapshot = useRef<Snapshot>({ hasPositioned: false, firstKey: undefined, lastKey: undefined, scrollTop: 0, scrollHeight: 0 })
+  const snapshot = useRef<Snapshot>({
+    hasPositioned: false,
+    firstKey: undefined,
+    lastKey: undefined,
+    scrollTop: 0,
+    scrollHeight: 0,
+  })
   const [isNearBottom, setIsNearBottom] = useState(true)
   const isNearBottomRef = useRef(true)
 

package/src/participantLayoutShrink.test.ts

@@ -0,0 +1,82 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'bun:test'
+
+import { splitBlocks } from './cssBlocks.test-helper'
+
+const CSS = readFileSync(join(import.meta.dir, 'styles.css'), 'utf8').replace(/\/\*[\s\S]*?\*\//g, '')
+
+const NON_SHRINKING_ITEMS = [
+  '.cv-p-filters',
+  '.cv-p-quick',
+  '.cv-p-search',
+  '.cv-p-composer',
+  '.cv-p-thread__header',
+  '.cv-p-thread__subject-card',
+]
+
+type FlexState = { grow: number; shrink: number }
+
+const FLEX_KEYWORDS: Record<string, FlexState> = {
+  none: { grow: 0, shrink: 0 },
+  auto: { grow: 1, shrink: 1 },
+  initial: { grow: 0, shrink: 1 },
+}
+
+function parseFlexShorthand(value: string): FlexState {
+  const keyword = FLEX_KEYWORDS[value]
+  if (keyword) return { ...keyword }
+  const numbers = value
+    .split(/\s+/)
+    .filter((token) => /^\d*\.?\d+$/.test(token))
+    .map(Number)
+  return { grow: numbers[0] ?? 0, shrink: numbers[1] ?? 1 }
+}
+
+function cleanValue(raw: string): string {
+  return raw
+    .replace(/!important/g, '')
+    .trim()
+    .toLowerCase()
+}
+
+// Only depth-0 style rules count (@media/@supports are conditional); later declarations win.
+function effectiveFlex(selector: string): FlexState | undefined {
+  let state: FlexState | undefined
+  for (const { prelude, body } of splitBlocks(CSS)) {
+    if (body === undefined || prelude.startsWith('@')) continue
+    if (!prelude.split(',').some((entry) => entry.trim() === selector)) continue
+    for (const declaration of body.split(';')) {
+      const separator = declaration.indexOf(':')
+      if (separator === -1) continue
+      const property = declaration.slice(0, separator).trim().toLowerCase()
+      const value = cleanValue(declaration.slice(separator + 1))
+      if (property === 'flex') state = parseFlexShorthand(value)
+      if (property === 'flex-shrink') state = { grow: state?.grow ?? 0, shrink: Number(value) }
+    }
+  }
+  return state
+}
+
+function hasMinHeightZero(selector: string): boolean {
+  return splitBlocks(CSS).some(
+    ({ prelude, body }) =>
+      body !== undefined &&
+      !prelude.startsWith('@') &&
+      prelude.split(',').some((entry) => entry.trim() === selector) &&
+      /min-height:\s*0\b/.test(body),
+  )
+}
+
+describe('participant view flex layout', () => {
+  it.each(NON_SHRINKING_ITEMS)('%s does not shrink inside a flex column', (selector) => {
+    expect(effectiveFlex(selector)?.shrink).toBe(0)
+  })
+
+  it('keeps the thread scroller as the only shrinking, growing region', () => {
+    const scroller = effectiveFlex('.cv-p-thread__scroll')
+    expect(scroller?.grow).toBe(1)
+    expect(scroller?.shrink).toBe(1)
+    expect(hasMinHeightZero('.cv-p-thread__scroll')).toBe(true)
+  })
+})