@proteos/ui 0.61.0 → 0.76.0

package/src/components/button/button.tsx

@@ -1,3 +1,4 @@
+import { Loader2 } from 'lucide-react'
 import { Button as AriaButton, type ButtonProps as AriaButtonProps } from 'react-aria-components'
 import { tv, type VariantProps } from 'tailwind-variants'
 
@@ -23,6 +24,11 @@ import { cn } from '../../lib/cn'
    and `disabled:` stay on the native pseudo-classes because the RAC root IS
    the focusable <button>. Hover is always a colour step on the surface ramp,
    never opacity; press is translateY(1px) plus one more ramp step.
+
+   `isPending` (React Aria's: presses are ignored, the button stays
+   focusable and announces itself busy) shows a spinner before the label —
+   in place of the icon on the icon sizes — so a save that takes a moment
+   reads as working, not as a dead button.
    ========================================================================= */
 
 // Ink fill with the indigo-tinted hover. Kept verbatim from the old primary.
@@ -124,16 +130,40 @@ export const buttonStyles = tv({
 export type ButtonVariants = VariantProps<typeof buttonStyles>
 export type ButtonProps = AriaButtonProps & ButtonVariants
 
-export function Button({ variant, size, shape, className, ...props }: ButtonProps) {
+const isIconSize = (size: ButtonVariants['size']) =>
+  size === 'icon-sm' || size === 'icon-md' || size === 'icon-lg'
+
+export function Button({ variant, size, shape, className, children, ...props }: ButtonProps) {
   return (
     <AriaButton
       {...props}
       className={(renderProps) =>
         cn(
           buttonStyles({ variant, size, shape }),
+          renderProps.isPending && 'cursor-progress',
           typeof className === 'function' ? className(renderProps) : className,
         )
       }
-    />
+    >
+      {(renderProps) => {
+        const content = typeof children === 'function' ? children(renderProps) : children
+        if (!renderProps.isPending) return content
+        const spinner = (
+          <Loader2
+            className="shrink-0 animate-spin motion-reduce:animate-none"
+            aria-hidden
+            data-slot="pending-spinner"
+          />
+        )
+        return isIconSize(size) ? (
+          spinner
+        ) : (
+          <>
+            {spinner}
+            {content}
+          </>
+        )
+      }}
+    </AriaButton>
   )
 }

package/src/components/conversation-brief-card/conversation-brief-preview.tsx

@@ -1,5 +1,5 @@
 import type { Contact, ConversationBrief } from '@proteos/sdk'
-import { Pencil, Phone } from 'lucide-react'
+import { Pencil, Phone, X } from 'lucide-react'
 import { type ReactNode, useEffect, useMemo, useRef, useState } from 'react'
 import { Button as AriaButton } from 'react-aria-components'
 
@@ -58,6 +58,16 @@ export interface ConversationBriefPreviewProps {
   onEdit?: () => void
   /** Replaces the guidance box wholesale — the host's editing surface. */
   editor?: ReactNode
+  /** A right-hand column next to the dial rows (the records the call
+   *  relates to). Owns its own scrolling. Absent ⇒ single column. */
+  aside?: ReactNode
+  /** Hides the people · channel · status line under the subject — for a
+   *  host whose surrounding chrome already says all of that (the call
+   *  window, where the dial row names the person). */
+  isMetaHidden?: boolean
+  /** Hides the subject line too — for a host whose window title IS the
+   *  subject (the call window). Implies `isMetaHidden`. */
+  isSubjectHidden?: boolean
 }
 
 export function ConversationBriefPreview({
@@ -75,8 +85,15 @@ export function ConversationBriefPreview({
   renderContent,
   onEdit,
   editor,
+  aside,
+  isMetaHidden = false,
+  isSubjectHidden = false,
 }: ConversationBriefPreviewProps) {
   const [pickedContactId, setPickedContactId] = useState('')
+  // The dial row rests as "Calling <value>"; a pencil (only when
+  // there is a choice — several people or several numbers) swaps it for
+  // the selects, which fold back once picked. Mirrors the caller-id row.
+  const [isPickingTarget, setIsPickingTarget] = useState(false)
   const contact = contacts.find((entry) => entry.id === pickedContactId) ?? contacts[0] ?? null
   const numbers = useMemo(() => contactPhoneNumbers(contact), [contact])
   const [pickedNumber, setPickedNumber] = useState('')
@@ -97,31 +114,38 @@ export function ConversationBriefPreview({
 
   return (
     <div className={cn('flex flex-col gap-3', className)}>
-      <div className="min-w-0">
-        <p className="truncate text-[14px] font-semibold text-ink">
-          {brief.subject || names || 'Prepared conversation'}
-        </p>
-        <p className="font-mono text-[10.5px] text-ink-4">
-          {[
-            brief.subject ? names : '',
-            brief.channel ? `Channel ${brief.channel}` : 'Any channel',
-            brief.type_key ? `Type ${brief.type_key}` : '',
-            brief.status === 'prepared'
-              ? 'Prepared'
-              : brief.status === 'used'
-                ? 'Call held'
-                : 'Discarded',
-          ]
-            .filter(Boolean)
-            .join(' · ')}
-        </p>
-      </div>
+      {isSubjectHidden ? null : (
+        <div className="min-w-0">
+          <p className="truncate text-[14px] font-semibold text-ink">
+            {brief.subject || names || 'Prepared conversation'}
+          </p>
+          {isMetaHidden ? null : (
+            <p className="font-mono text-[10.5px] text-ink-4">
+              {[
+                brief.subject ? names : '',
+                brief.channel ? `Channel ${brief.channel}` : 'Any channel',
+                brief.type_key ? `Type ${brief.type_key}` : '',
+                brief.status === 'prepared'
+                  ? 'Prepared'
+                  : brief.status === 'used'
+                    ? 'Call held'
+                    : 'Discarded',
+              ]
+                .filter(Boolean)
+                .join(' · ')}
+            </p>
+          )}
+        </div>
+      )}
       {editor ?? (
-        <div className="group/brief-content relative">
+        // A flex column of its own so a host that gives the box `flex-1`
+        // (the call window) gets a scrolling box that fills the remaining
+        // height; in an unconstrained host (a modal) it just wraps.
+        <div className="group/brief-content relative flex min-h-0 flex-1 flex-col">
           <div
             className={cn(
               'rounded-md border border-rule-2 bg-surface-2/60 px-3 py-2.5',
-              'text-[13px] leading-relaxed text-ink-2 overflow-y-auto [scrollbar-width:thin]',
+              'min-h-0 text-[13px] leading-relaxed text-ink-2 overflow-y-auto [scrollbar-width:thin]',
               renderContent ? null : 'whitespace-pre-wrap',
               contentClassName,
             )}
@@ -147,31 +171,136 @@ export function ConversationBriefPreview({
       )}
       {onCall ? (
         <div className="flex flex-col gap-2 border-t border-rule-2 pt-3">
-          {contacts.length > 1 ? (
-            <Select
-              aria-label="Who to call"
-              selectedKey={contact?.id ?? ''}
-              onSelectionChange={(key) => {
-                setPickedContactId(String(key))
-                setPickedNumber('')
-              }}
-              options={contacts.map((entry) => ({ id: entry.id, label: entry.name || entry.id }))}
-            />
-          ) : null}
-          {numbers.length > 1 ? (
-            <Select
-              aria-label="Number to call"
-              selectedKey={phoneNumber}
-              onSelectionChange={(key) => setPickedNumber(String(key))}
-              options={numbers.map((number) => ({ id: number, label: number }))}
-            />
-          ) : (
-            <p className="font-mono text-[12px] text-ink-3">
-              {phoneNumber ||
-                (contact ? 'This contact has no phone number on file.' : 'No contact to call.')}
-            </p>
-          )}
-          {controls}
+          <div
+            className={cn(
+              'grid gap-3',
+              aside ? 'grid-cols-[minmax(0,1fr)_minmax(0,1fr)]' : 'grid-cols-1',
+            )}
+          >
+            <div className="flex min-w-0 flex-col gap-2">
+              {isPickingTarget && (contacts.length > 1 || numbers.length > 1) ? (
+                <div className="flex min-w-0 flex-col gap-1">
+                  <p className="font-mono text-[10px] uppercase tracking-[0.08em] text-ink-4">
+                    Calling
+                  </p>
+                  <div className="flex min-w-0 items-start gap-1.5">
+                    <div className="flex min-w-0 flex-1 flex-col gap-1.5">
+                      {contacts.length > 1 ? (
+                        <Select
+                          aria-label="Who to call"
+                          size="sm"
+                          autoFocus
+                          selectedKey={contact?.id ?? ''}
+                          onSelectionChange={(key) => {
+                            setPickedContactId(String(key))
+                            setPickedNumber('')
+                            // Fold once the pick is complete: the chosen person has
+                            // at most one number, so there is nothing left to choose.
+                            const picked = contacts.find((entry) => entry.id === String(key))
+                            if (contactPhoneNumbers(picked).length <= 1) setIsPickingTarget(false)
+                          }}
+                          options={contacts.map((entry) => ({
+                            id: entry.id,
+                            label: entry.name || entry.id,
+                          }))}
+                        />
+                      ) : null}
+                      {numbers.length > 1 ? (
+                        <Select
+                          aria-label="Number to dial"
+                          size="sm"
+                          {...(contacts.length > 1 ? {} : { autoFocus: true })}
+                          selectedKey={phoneNumber}
+                          onSelectionChange={(key) => {
+                            if (key !== null) setPickedNumber(String(key))
+                            setIsPickingTarget(false)
+                          }}
+                          options={numbers.map((number) => ({ id: number, label: number }))}
+                        />
+                      ) : null}
+                    </div>
+                    <Button
+                      variant="ghost"
+                      size="icon-sm"
+                      aria-label="Keep the current number"
+                      onPress={() => setIsPickingTarget(false)}
+                    >
+                      <X aria-hidden />
+                    </Button>
+                  </div>
+                </div>
+              ) : (
+                <div className="group/dial flex min-w-0 flex-col gap-1">
+                  <p className="font-mono text-[10px] uppercase tracking-[0.08em] text-ink-4">
+                    Calling
+                  </p>
+                  <div className="flex min-h-9 min-w-0 items-center gap-2">
+                    {(() => {
+                      const hasChoice = contacts.length > 1 || numbers.length > 1
+                      const valueText = phoneNumber
+                        ? contacts.length > 1
+                          ? `${contact?.name || contact?.id} · ${phoneNumber}`
+                          : phoneNumber
+                        : contact
+                          ? `${contacts.length > 1 ? `${contact.name || contact.id} · ` : ''}no phone number on file`
+                          : 'No contact to call.'
+                      const valueClassName = cn(
+                        'min-w-0 truncate text-[12px] tabular-nums',
+                        phoneNumber ? 'text-ink-2' : 'text-warning',
+                      )
+                      // Same weight as a related-record row: a small muted
+                      // glyph in front, 12px text, mid-row.
+                      const icon = (
+                        <Phone
+                          className={cn(
+                            'size-3 shrink-0',
+                            phoneNumber ? 'text-ink-4' : 'text-warning',
+                          )}
+                          aria-hidden
+                        />
+                      )
+                      // With something to choose, the value itself opens the pick
+                      // (the pencil is the hint, not the only handle).
+                      return hasChoice ? (
+                        <AriaButton
+                          className={cn(
+                            'flex min-w-0 cursor-pointer items-center gap-2 rounded-sm text-left outline-none',
+                            'hover:text-ink focus-visible:shadow-[var(--shadow-focus)]',
+                          )}
+                          onPress={() => setIsPickingTarget(true)}
+                        >
+                          {icon}
+                          <span className={valueClassName} title={phoneNumber}>
+                            {valueText}
+                          </span>
+                        </AriaButton>
+                      ) : (
+                        <>
+                          {icon}
+                          <span className={valueClassName} title={phoneNumber}>
+                            {valueText}
+                          </span>
+                        </>
+                      )
+                    })()}
+                    {contacts.length > 1 || numbers.length > 1 ? (
+                      <Button
+                        variant="ghost"
+                        size="icon-sm"
+                        aria-label="Change the number to dial"
+                        className="opacity-0 transition-opacity group-hover/dial:opacity-100 focus-visible:opacity-100"
+                        onPress={() => setIsPickingTarget(true)}
+                      >
+                        <Pencil aria-hidden />
+                      </Button>
+                    ) : null}
+                  </div>
+                </div>
+              )}
+              {controls}
+            </div>
+            {aside ? <div className="min-h-0 min-w-0">{aside}</div> : null}
+          </div>
           {callDisabledReason ? (
             <p className="text-[12px] text-warning">{callDisabledReason}</p>
           ) : null}

package/src/components/conversation-brief-card/conversation-brief-review.test.tsx

@@ -172,9 +172,66 @@ describe('ConversationBriefPreview', () => {
         onCall={onCall}
       />,
     )
+    // Rests as a labelled row naming the first person + number; the pencil
+    // reveals the who-to-call select.
+    expect(screen.getByText('Calling')).toBeInTheDocument()
+    expect(screen.getByText('Alice Example · +4930123456')).toBeInTheDocument()
+    await userEvent.click(screen.getByRole('button', { name: 'Change the number to dial' }))
     expect(screen.getByRole('button', { name: /Who to call/ })).toBeInTheDocument()
+    await userEvent.click(screen.getByRole('button', { name: /Who to call/ }))
+    await userEvent.click(screen.getByRole('option', { name: /Tom Example/ }))
+    expect(screen.getByText('Tom Example · +4915500000')).toBeInTheDocument()
     await userEvent.click(screen.getByRole('button', { name: 'Call' }))
-    expect(onCall).toHaveBeenCalledWith(expect.objectContaining({ id: 'contact-1' }), '+4930123456')
+    expect(onCall).toHaveBeenCalledWith(expect.objectContaining({ id: 'contact-2' }), '+4915500000')
+  })
+
+  it('shows a single number without a pencil and hides the meta line on request', () => {
+    render(
+      <ConversationBriefPreview
+        brief={brief()}
+        contacts={[
+          contact({
+            addresses: [{ id: 'a2', kind: 'phone', value: '+4930123456' }],
+          } as Partial<Contact>),
+        ]}
+        onCall={vi.fn()}
+        isMetaHidden
+      />,
+    )
+    expect(screen.getByText('+4930123456')).toBeInTheDocument()
+    expect(
+      screen.queryByRole('button', { name: 'Change the number to dial' }),
+    ).not.toBeInTheDocument()
+    expect(screen.queryByText(/Channel phone/)).not.toBeInTheDocument()
+  })
+
+  it('lets a contact with several numbers pick which one to dial', async () => {
+    const onSelectionChange = vi.fn()
+    render(
+      <ConversationBriefPreview
+        brief={brief()}
+        contacts={[contact()]}
+        onCall={vi.fn()}
+        isCallButtonHidden
+        onSelectionChange={onSelectionChange}
+      />,
+    )
+    // First number auto-selected; the pencil reveals the number select, the
+    // label stays, and the x folds it back without a change.
+    expect(screen.getByText('+4930123456')).toBeInTheDocument()
+    await userEvent.click(screen.getByRole('button', { name: 'Change the number to dial' }))
+    expect(screen.getByText('Calling')).toBeInTheDocument()
+    await userEvent.click(screen.getByRole('button', { name: 'Keep the current number' }))
+    expect(screen.getByText('+4930123456')).toBeInTheDocument()
+    expect(screen.queryByRole('button', { name: /Number to dial/ })).not.toBeInTheDocument()
+    await userEvent.click(screen.getByRole('button', { name: 'Change the number to dial' }))
+    await userEvent.click(screen.getByRole('button', { name: /Number to dial/ }))
+    await userEvent.click(screen.getByRole('option', { name: '+4917612345' }))
+    expect(screen.getByText('+4917612345')).toBeInTheDocument()
+    expect(onSelectionChange).toHaveBeenLastCalledWith(
+      expect.objectContaining({ id: 'contact-1' }),
+      '+4917612345',
+    )
   })
 
   it('can hide its Call button and report the target to the host', () => {

package/src/components/data-table/data-table.test.tsx

@@ -172,3 +172,68 @@ describe('DataTable grouping', () => {
     expect(screen.queryByText('crm')).toBeNull()
   })
 })
+
+/* `placeholderData: keepPreviousData` keeps the previous rows on screen while
+   a changed filter / sort loads: no skeleton, the body just dims. */
+describe('DataTable placeholder rows', () => {
+  it('keeps the rows and dims the body while the query shows placeholder data', () => {
+    render(
+      <DataTable<Row>
+        query={{ ...query(ROWS), isPlaceholderData: true }}
+        columns={columns}
+        ariaLabel="Records"
+      />,
+    )
+
+    expect(screen.getByText('Alpha')).toBeInTheDocument()
+    expect(screen.queryByRole('status')).toBeNull()
+    expect(screen.getByText('Alpha').closest('[aria-busy]')).toHaveAttribute('aria-busy', 'true')
+  })
+
+  it('renders the body at full opacity once the rows are its own', () => {
+    render(<DataTable<Row> query={query(ROWS)} columns={columns} ariaLabel="Records" />)
+
+    expect(screen.getByText('Alpha').closest('[aria-busy]')).toBeNull()
+  })
+})
+
+/* A host router restores the scroller's position on back navigation before
+   the table's effects run — the sort-change reset must not undo it on mount. */
+describe('DataTable scroll restoration', () => {
+  it('stamps the restoration id on the scroll container', () => {
+    const { container } = render(
+      <DataTable<Row>
+        query={query(ROWS)}
+        columns={columns}
+        ariaLabel="Records"
+        scrollRestorationId="list:customers"
+      />,
+    )
+    expect(container.querySelector('[data-scroll-restoration-id="list:customers"]')).not.toBeNull()
+  })
+
+  it('keeps the restored position on mount and resets it when the sort changes', () => {
+    const scrollTo = vi.fn()
+    const original = HTMLElement.prototype.scrollTo
+    HTMLElement.prototype.scrollTo = scrollTo
+    try {
+      const sorting = [{ id: 'name', desc: false }]
+      const { rerender } = render(
+        <DataTable<Row> query={query(ROWS)} columns={columns} ariaLabel="Records" sorting={sorting} />,
+      )
+      expect(scrollTo).not.toHaveBeenCalled()
+
+      rerender(
+        <DataTable<Row>
+          query={query(ROWS)}
+          columns={columns}
+          ariaLabel="Records"
+          sorting={[{ id: 'name', desc: true }]}
+        />,
+      )
+      expect(scrollTo).toHaveBeenCalledWith({ top: 0 })
+    } finally {
+      HTMLElement.prototype.scrollTo = original
+    }
+  })
+})

package/src/components/data-table/data-table.tsx

@@ -59,6 +59,10 @@ type InfinitePage<TRow> = { data: TRow[]; meta?: { items_total?: number } }
 export type InfiniteQueryLike<TRow> = {
   data?: { pages: InfinitePage<TRow>[] } | undefined
   isLoading: boolean
+  /** The rows on screen belong to the PREVIOUS query (a filter or sort just
+   *  changed and the new rows are still loading — `placeholderData:
+   *  keepPreviousData`). The body dims until the fresh rows land. */
+  isPlaceholderData?: boolean
   isFetchingNextPage: boolean
   hasNextPage: boolean | undefined
   error: Error | null
@@ -73,6 +77,18 @@ export type DataTableProps<TRow> = {
   onSortingChange?: OnChangeFn<SortingState>
   rowHeight?: number
   overscan?: number
+  /**
+   * Stable id stamped on the scroll container as `data-scroll-restoration-id`,
+   * so a router that restores element scroll on back/forward finds this table
+   * by id instead of by its (fragile) DOM path.
+   */
+  scrollRestorationId?: string
+  /**
+   * Scroll offset the table first renders at — a restored position from the
+   * host's router. The virtualizer starts its window there, so the rows at
+   * that offset paint on the first frame instead of a blank band.
+   */
+  initialScrollOffset?: number
   /**
    * Called when a row is clicked. Provides both the original data row and
    * the underlying event so consumers can inspect modifier keys.
@@ -200,6 +216,8 @@ export function DataTable<TRow>({
   onSortingChange,
   rowHeight = DEFAULT_ROW_HEIGHT,
   overscan = 8,
+  scrollRestorationId,
+  initialScrollOffset,
   onRowClick,
   zebra = true,
   emptyState,
@@ -380,10 +398,14 @@ export function DataTable<TRow>({
   }, [tableRows, groupBy])
 
   // Reset scroll to top when sorting changes — without this, the user is
-  // staring at a different slice of a freshly-sorted dataset.
+  // staring at a different slice of a freshly-sorted dataset. Only on a
+  // CHANGE: on mount this would wipe the position the host just restored
+  // (the router restores in the layout phase, before this effect runs).
   const scrollerRef = useRef<HTMLDivElement | null>(null)
-  // biome-ignore lint/correctness/useExhaustiveDependencies: intentional — scroll resets on sort change only
+  const mountedSorting = useRef(sorting)
   useEffect(() => {
+    if (sorting === mountedSorting.current) return
+    mountedSorting.current = sorting
     scrollerRef.current?.scrollTo({ top: 0 })
   }, [sorting])
 
@@ -407,6 +429,7 @@ export function DataTable<TRow>({
     estimateSize: (index) => (listItems[index]?.kind === 'group' ? headingHeight : rowHeight),
     overscan,
     scrollMargin: listOffset,
+    ...(initialScrollOffset !== undefined ? { initialOffset: initialScrollOffset } : {}),
   })
 
   const sentinelRef = useInfiniteScrollSentinel<HTMLDivElement>({
@@ -487,6 +510,9 @@ export function DataTable<TRow>({
           top, and any `sticky left-0` gutter column freezes to the left. */}
       <TableScroller
         ref={scrollerRef}
+        {...(scrollRestorationId !== undefined
+          ? { 'data-scroll-restoration-id': scrollRestorationId }
+          : {})}
         // Scroll padding keeps a row scrolled (or focused) into view clear of
         // the sticky header and, when present, the sticky trailing row —
         // otherwise a freshly added last row lands underneath the strip.
@@ -572,6 +598,11 @@ export function DataTable<TRow>({
                 <div
                   ref={listRef}
                   role="presentation"
+                  aria-busy={query.isPlaceholderData ? true : undefined}
+                  className={cn(
+                    'transition-opacity duration-150 motion-reduce:transition-none',
+                    query.isPlaceholderData && 'opacity-50',
+                  )}
                   style={{ height: totalSize, position: 'relative', width: '100%' }}
                 >
                   {virtualItems.map((vRow) => {

package/src/components/glow-frame/glow-frame.stories.tsx

@@ -0,0 +1,65 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useState } from 'react'
+
+import { Button } from '../button'
+import { TextShimmer } from '../text-shimmer'
+import { GlowFrame, type GlowFrameStatus } from './glow-frame'
+
+const meta: Meta<typeof GlowFrame> = {
+  title: 'Components/GlowFrame',
+  component: GlowFrame,
+  tags: ['autodocs'],
+  argTypes: {
+    status: { control: 'inline-radio', options: ['idle', 'working', 'ready'] },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof GlowFrame>
+
+const BOX = 'rounded-md border border-rule bg-surface p-4 text-[13px] text-ink-2'
+
+export const Playground: Story = {
+  args: { status: 'working', className: 'w-[360px] rounded-md' },
+  render: (args) => (
+    <GlowFrame {...args}>
+      <div className={BOX}>Three fields will change on this deal.</div>
+    </GlowFrame>
+  ),
+}
+
+/** The full sequence: beams while the model works, a flash when the output
+ *  lands. */
+export const Sequence: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => {
+    const [status, setStatus] = useState<GlowFrameStatus>('idle')
+    const run = () => {
+      setStatus('working')
+      window.setTimeout(() => setStatus('ready'), 3000)
+    }
+    return (
+      <div className="flex w-[360px] flex-col gap-4">
+        <GlowFrame status={status} className="rounded-md">
+          <div className={BOX}>
+            {status === 'working' ? (
+              <TextShimmer>Preparing the changes…</TextShimmer>
+            ) : status === 'ready' ? (
+              'Stage → Negotiation, amount → €42,000, close date → 30 Nov.'
+            ) : (
+              'Press run.'
+            )}
+          </div>
+        </GlowFrame>
+        <div className="flex gap-2">
+          <Button size="sm" onPress={run} isDisabled={status === 'working'}>
+            Run
+          </Button>
+          <Button size="sm" variant="ghost" onPress={() => setStatus('idle')}>
+            Reset
+          </Button>
+        </div>
+      </div>
+    )
+  },
+}