@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/components/action-menu/ActionMenu.tsx

@@ -0,0 +1,282 @@
+import { Ellipsis } from 'lucide-react'
+import {
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type MouseEvent as ReactMouseEvent,
+  type PointerEvent as ReactPointerEvent,
+  type ReactNode,
+} from 'react'
+import {
+  Header,
+  Keyboard,
+  Menu,
+  MenuItem,
+  MenuSection,
+  MenuTrigger,
+  Popover,
+  Separator,
+  Text,
+  type Key,
+} from 'react-aria-components'
+import { cx } from '../../internal/cx'
+import { useMessages } from '../../internal/provider'
+import type { IconComponent } from '../../internal/types'
+import { Button } from '../button/Button'
+
+export interface ActionMenuItem {
+  type?: 'item'
+  id: string
+  label: string
+  icon?: IconComponent
+  tone?: 'default' | 'danger'
+  disabled?: boolean
+  shortcut?: string
+  /** Makes the item a link (navigates through the router adapter). */
+  href?: string
+}
+export interface ActionMenuSeparator {
+  type: 'separator'
+  id?: string
+}
+export interface ActionMenuSection {
+  type: 'section'
+  id: string
+  title: string
+  items: ActionMenuItem[]
+}
+export type ActionMenuEntry = ActionMenuItem | ActionMenuSeparator | ActionMenuSection
+
+export interface ActionMenuPosition {
+  x: number
+  y: number
+}
+
+export interface ActionMenuProps {
+  items: ActionMenuEntry[]
+  onAction: (id: string) => void
+  /** Accessible name of the menu. */
+  label: string
+  /** `trigger`: opens from a button; `context`: opens at a pointer position over `trigger`. */
+  mode?: 'trigger' | 'context'
+  /** Trigger mode: the button. Context mode: the target that receives the context request. */
+  trigger?: ReactNode
+  /** Context mode: viewport point (controlled). */
+  position?: ActionMenuPosition
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+  className?: string
+}
+
+const GUTTER = 8
+const LONG_PRESS_MS = 500
+
+function collectDisabled(items: ActionMenuEntry[]): string[] {
+  const out: string[] = []
+  for (const e of items) {
+    if (e.type === 'section') out.push(...collectDisabled(e.items))
+    else if (e.type !== 'separator' && e.disabled) out.push(e.id)
+  }
+  return out
+}
+
+function renderItem(item: ActionMenuItem) {
+  const Icon = item.icon
+  return (
+    <MenuItem
+      key={item.id}
+      id={item.id}
+      textValue={item.label}
+      href={item.href}
+      className="ty-action-menu__item"
+      data-tone={item.tone ?? 'default'}
+    >
+      {Icon ? <Icon className="ty-icon ty-action-menu__icon" aria-hidden="true" focusable="false" /> : null}
+      <Text slot="label" className="ty-action-menu__label">
+        {item.label}
+      </Text>
+      {item.shortcut ? <Keyboard className="ty-action-menu__shortcut">{item.shortcut}</Keyboard> : null}
+    </MenuItem>
+  )
+}
+
+function renderEntries(items: ActionMenuEntry[]) {
+  return items.map((entry, i) => {
+    if (entry.type === 'separator') return <Separator key={entry.id ?? `separator-${i}`} className="ty-action-menu__separator" />
+    if (entry.type === 'section') {
+      return (
+        <MenuSection key={entry.id} id={entry.id} className="ty-action-menu__section">
+          <Header className="ty-action-menu__section-title">{entry.title}</Header>
+          {entry.items.map(renderItem)}
+        </MenuSection>
+      )
+    }
+    return renderItem(entry)
+  })
+}
+
+/** Clamps a point so a box of `width` x `height` stays inside the viewport. */
+export function clampToViewport(point: ActionMenuPosition, width: number, height: number): ActionMenuPosition {
+  const vw = typeof window !== 'undefined' ? window.innerWidth : width
+  const vh = typeof window !== 'undefined' ? window.innerHeight : height
+  return {
+    x: Math.max(GUTTER, Math.min(point.x, vw - width - GUTTER)),
+    y: Math.max(GUTTER, Math.min(point.y, vh - height - GUTTER)),
+  }
+}
+
+/** Commands from a trigger button or at a pointer position (spec: wave-1/action-menu.md). */
+export function ActionMenu(props: ActionMenuProps) {
+  const { items, onAction, label, mode = 'trigger', trigger, className } = props
+  const messages = useMessages()
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(props.defaultOpen ?? false)
+  const isOpen = props.open ?? uncontrolledOpen
+  const setOpen = (next: boolean) => {
+    if (props.open === undefined) setUncontrolledOpen(next)
+    props.onOpenChange?.(next)
+  }
+  const labelId = useId()
+  const disabledKeys = collectDisabled(items)
+  const handleAction = (key: Key) => {
+    if (disabledKeys.includes(String(key))) return
+    onAction(String(key))
+  }
+
+  const menu = (
+    <Menu
+      aria-labelledby={labelId}
+      className="ty-action-menu__menu"
+      disabledKeys={disabledKeys}
+      onAction={handleAction}
+      shouldFocusWrap
+      {...(mode === 'context' ? { autoFocus: 'first' as const, onClose: () => setOpen(false) } : {})}
+    >
+      {renderEntries(items)}
+    </Menu>
+  )
+
+  if (mode === 'trigger') {
+    return (
+      <MenuTrigger isOpen={isOpen} onOpenChange={setOpen}>
+        {trigger ?? <Button iconOnly accessibleLabel={messages.moreActions} leadingIcon={<Ellipsis />} variant="quiet" />}
+        <Popover className={cx('ty-action-menu', className)} placement="bottom end" offset={8}>
+          <span id={labelId} className="ty-visually-hidden">
+            {label}
+          </span>
+          {menu}
+        </Popover>
+      </MenuTrigger>
+    )
+  }
+
+  return (
+    <ContextActionMenu {...props} isOpen={isOpen} setOpen={setOpen} menu={menu} labelId={labelId} className={className}>
+      {trigger}
+    </ContextActionMenu>
+  )
+}
+
+interface ContextInternalProps extends ActionMenuProps {
+  isOpen: boolean
+  setOpen: (open: boolean) => void
+  menu: ReactNode
+  labelId: string
+  children: ReactNode
+}
+
+function ContextActionMenu({ isOpen, setOpen, menu, labelId, label, children, className, position }: ContextInternalProps) {
+  const targetRef = useRef<HTMLSpanElement>(null)
+  const anchorRef = useRef<HTMLSpanElement>(null)
+  const popoverRef = useRef<HTMLDivElement>(null)
+  const originRef = useRef<HTMLElement | null>(null)
+  const longPress = useRef<number | undefined>(undefined)
+  const [point, setPoint] = useState<ActionMenuPosition>(position ?? { x: 0, y: 0 })
+  const [clamped, setClamped] = useState<ActionMenuPosition>(point)
+  const effective = position ?? point
+
+  const openAt = (p: ActionMenuPosition) => {
+    const active = document.activeElement
+    originRef.current = active instanceof HTMLElement && active !== document.body ? active : targetRef.current
+    setPoint(p)
+    setOpen(true)
+  }
+
+  const onContextMenu = (e: ReactMouseEvent) => {
+    e.preventDefault()
+    openAt({ x: e.clientX, y: e.clientY })
+  }
+  const onKeyDown = (e: ReactKeyboardEvent) => {
+    if ((e.shiftKey && e.key === 'F10') || e.key === 'ContextMenu') {
+      e.preventDefault()
+      const el = (e.target as HTMLElement) ?? targetRef.current
+      const rect = el.getBoundingClientRect()
+      openAt({ x: rect.left, y: rect.bottom })
+    }
+  }
+  const onPointerDown = (e: ReactPointerEvent) => {
+    if (e.pointerType !== 'touch') return
+    const { clientX, clientY } = e
+    window.clearTimeout(longPress.current)
+    longPress.current = window.setTimeout(() => openAt({ x: clientX, y: clientY }), LONG_PRESS_MS)
+  }
+  const cancelLongPress = () => window.clearTimeout(longPress.current)
+
+  useLayoutEffect(() => {
+    if (!isOpen) return
+    const el = popoverRef.current
+    const rect = el?.getBoundingClientRect()
+    setClamped(clampToViewport(effective, rect?.width ?? 0, rect?.height ?? 0))
+  }, [isOpen, effective.x, effective.y])
+
+  const handleOpenChange = (next: boolean) => {
+    setOpen(next)
+    if (!next) {
+      const origin = originRef.current
+      requestAnimationFrame(() => {
+        if (origin && (document.activeElement === document.body || document.activeElement === null)) origin.focus()
+      })
+    }
+  }
+
+  return (
+    <>
+      <span
+        ref={targetRef}
+        className="ty-action-menu__target"
+        onContextMenu={onContextMenu}
+        onKeyDown={onKeyDown}
+        onPointerDown={onPointerDown}
+        onPointerUp={cancelLongPress}
+        onPointerCancel={cancelLongPress}
+        onPointerMove={cancelLongPress}
+      >
+        {children}
+      </span>
+      <span
+        ref={anchorRef}
+        aria-hidden="true"
+        className="ty-action-menu__anchor"
+        style={{ position: 'fixed', left: effective.x, top: effective.y, width: 0, height: 0 }}
+      />
+      <Popover
+        ref={popoverRef}
+        triggerRef={anchorRef}
+        isOpen={isOpen}
+        onOpenChange={handleOpenChange}
+        placement="bottom start"
+        offset={0}
+        className={cx('ty-action-menu', className)}
+        data-mode="context"
+        style={{ position: 'fixed', left: clamped.x, top: clamped.y }}
+      >
+        <span id={labelId} className="ty-visually-hidden">
+          {label}
+        </span>
+        {menu}
+      </Popover>
+    </>
+  )
+}

package/src/components/activity-feed/ActivityFeed.css

@@ -0,0 +1,91 @@
+/* ActivityFeed (spec: wave-4/activity-feed.md; design direction §2.2, §2.11, §3.5). */
+@layer tympan.components {
+  .ty-activity {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ty-space-3);
+  }
+  .ty-activity__list {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  .ty-activity__entry {
+    display: grid;
+    grid-template-columns: 12rem minmax(0, 1fr);
+    align-items: baseline;
+    gap: var(--ty-space-2) var(--ty-space-4);
+    padding-block: var(--ty-space-3);
+    border-block-end: 1px solid var(--ty-line);
+  }
+  .ty-activity__body {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: baseline;
+    justify-content: space-between;
+    gap: var(--ty-space-1) var(--ty-space-4);
+    min-inline-size: 0;
+  }
+  .ty-activity__text {
+    margin: 0;
+    color: var(--ty-ink-2);
+    font-size: var(--ty-font-size-body);
+    line-height: var(--ty-font-line-height-body);
+  }
+  .ty-activity__meta {
+    display: inline-flex;
+    flex-wrap: wrap;
+    gap: 0 var(--ty-space-3);
+    margin: 0;
+    color: var(--ty-ink-3);
+    font-family: var(--ty-font-mono);
+    font-size: var(--ty-font-size-meta);
+    line-height: var(--ty-font-line-height-meta);
+  }
+  .ty-activity__code {
+    font: inherit;
+  }
+  .ty-activity__empty {
+    margin: 0;
+    color: var(--ty-ink-3);
+  }
+  .ty-activity__more {
+    position: relative;
+    align-self: flex-end;
+    color: var(--ty-accent);
+    font-size: var(--ty-font-size-label);
+    font-weight: var(--ty-font-weight-semibold);
+    text-decoration: none;
+    outline: none;
+  }
+  .ty-activity__more::after {
+    content: '';
+    position: absolute;
+    inset: 50% auto auto 50%;
+    inline-size: max(100%, var(--ty-control-target));
+    block-size: var(--ty-control-target);
+    translate: -50% -50%;
+  }
+  .ty-activity__more[data-hovered] {
+    text-decoration: underline;
+  }
+  .ty-activity__more[data-focus-visible] {
+    border-radius: 4px;
+    outline: var(--ty-focus-width) solid var(--ty-focus-ring);
+    outline-offset: 2px;
+  }
+
+  @media (max-width: 639.98px) {
+    .ty-activity__entry {
+      grid-template-columns: minmax(0, 1fr);
+    }
+    .ty-activity__body {
+      flex-direction: column;
+    }
+  }
+  @media (forced-colors: active) {
+    .ty-activity__entry {
+      border-color: CanvasText;
+    }
+  }
+}

package/src/components/activity-feed/ActivityFeed.test.tsx

@@ -0,0 +1,89 @@
+import { I18nProvider } from 'react-aria-components'
+import { render, screen, within } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { cssOf, mediaBlock } from '../../../test/css'
+import { renderWithProvider } from '../../../test/render'
+import { ThemeScope } from '../../internal/ThemeScope'
+import { ActivityFeed, relativePhrase, type ActivityEntry } from './ActivityFeed'
+
+const now = new Date('2026-09-26T12:00:00Z')
+const entries: ActivityEntry[] = [
+  { id: '1', actor: { kind: 'person', name: 'Marina Duarte' }, text: 'verified the PM2.5 reading of Centro station', at: '2026-09-26T11:55:00Z', meta: 'station-centro-2026' },
+  { id: '2', actor: { kind: 'agent', name: 'limit-counter', agentKey: 'agt_7f' }, text: 'ran the stage count', at: '2026-09-26T09:00:00Z', meta: 'run 2026-09-26' },
+  { id: '3', actor: { kind: 'system', name: 'freeze@2' }, text: 'froze edition 2026-09-20', at: '2026-09-20T03:00:00Z' },
+]
+
+describe('ActivityFeed', () => {
+  it('renders an ordered list in the given order', () => {
+    render(<ActivityFeed entries={entries} label="Recent activity" now={now} locale="en" />)
+    const list = screen.getByRole('list', { name: 'Recent activity' })
+    expect(list.tagName).toBe('OL')
+    const items = within(list).getAllByRole('listitem')
+    expect(items.map((i) => i.querySelector('.ty-activity__text')!.textContent)).toEqual([
+      'verified the PM2.5 reading of Centro station',
+      'ran the stage count',
+      'froze edition 2026-09-20',
+    ])
+  })
+
+  it('shows the word "agent" for an agent', () => {
+    render(<ActivityFeed entries={entries} label="Recent activity" now={now} locale="en" />)
+    expect(within(screen.getAllByRole('listitem')[1]!).getByText('agent')).toBeInTheDocument()
+  })
+
+  it('shows a time element with the ISO date and a relative text', () => {
+    render(<ActivityFeed entries={entries} label="Recent activity" now={now} locale="en" />)
+    const time = screen.getAllByRole('listitem')[0]!.querySelector('time')!
+    expect(time).toHaveAttribute('datetime', '2026-09-26T11:55:00.000Z')
+    expect(time).toHaveTextContent('5 minutes ago')
+    expect(time.getAttribute('title')).toMatch(/2026/)
+  })
+
+  it('puts the actor before the time in DOM order', () => {
+    render(<ActivityFeed entries={entries} label="Recent activity" now={now} locale="en" />)
+    const first = screen.getAllByRole('listitem')[0]!
+    const name = within(first).getByText('Marina Duarte')
+    expect(name.compareDocumentPosition(first.querySelector('time')!) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy()
+  })
+
+  it('picks the unit by magnitude and localises it', () => {
+    expect(relativePhrase(new Date('2026-09-26T09:00:00Z'), now, 'en')).toBe('3 hours ago')
+    expect(relativePhrase(new Date('2026-09-20T12:00:00Z'), now, 'pt-BR')).toBe('há 6 dias')
+  })
+
+  it('shows the empty sentence and wraps meta on phones', () => {
+    render(<ActivityFeed entries={[]} label="Recent activity" />)
+    expect(screen.getByText('No activity yet.')).toBeInTheDocument()
+    expect(mediaBlock(cssOf('components/activity-feed/ActivityFeed.css'), /\(max-width:\s*639\.98px\)/)).toMatch(/flex-direction:\s*column/)
+  })
+
+  it('has no axe violations, light and dark', async () => {
+    const { container } = renderWithProvider(
+      <>
+        {(['light', 'dark'] as const).map((scheme) => (
+          <ThemeScope key={scheme} scheme={scheme}>
+            <ActivityFeed entries={entries} label={`Activity ${scheme}`} now={now} moreHref="/trail" moreLabel="See trail" />
+          </ThemeScope>
+        ))}
+      </>,
+      { navigate: vi.fn() },
+    )
+    await expectNoAxeViolations(container)
+  })
+})
+
+describe('ActivityFeed in right-to-left', () => {
+  it('writes relative time in the locale and passes axe', async () => {
+    const { container } = renderWithProvider(
+      <I18nProvider locale="ar">
+        <div dir="rtl" lang="ar">
+          <ActivityFeed entries={entries} label="النشاط" now={now} />
+        </div>
+      </I18nProvider>,
+      { navigate: vi.fn() },
+    )
+    expect(container.querySelector('time')!.textContent).toMatch(/دقائق|دقيقة/)
+    await expectNoAxeViolations(container)
+  })
+})

package/src/components/activity-feed/ActivityFeed.tsx

@@ -0,0 +1,86 @@
+import type { ReactNode } from 'react'
+import { Link as AriaLink, useLocale } from 'react-aria-components'
+import { cx } from '../../internal/cx'
+import { useMessages } from '../../internal/provider'
+import { ActorChip, type ActorKind } from '../actor-chip/ActorChip'
+
+export interface ActivityEntry {
+  id: string
+  actor: { kind: ActorKind; name: string; agentKey?: string; model?: string }
+  text: ReactNode
+  at: string | Date
+  /** Mono meta (id, rule, hash). */
+  meta?: string
+}
+
+export interface ActivityFeedProps {
+  entries: ActivityEntry[]
+  label: string
+  locale?: string
+  /** Reference time for relative dates (tests, snapshots). */
+  now?: Date
+  moreHref?: string
+  moreLabel?: string
+  className?: string
+}
+
+const STEPS: Array<[Intl.RelativeTimeFormatUnit, number]> = [
+  ['second', 60],
+  ['minute', 60],
+  ['hour', 24],
+  ['day', 7],
+  ['week', 4.35],
+  ['month', 12],
+  ['year', Number.POSITIVE_INFINITY],
+]
+
+/** Relative phrase with the largest unit that keeps the number above one. */
+export function relativePhrase(at: Date, now: Date, locale: string): string {
+  let amount = (at.getTime() - now.getTime()) / 1000
+  for (const [unit, size] of STEPS) {
+    if (Math.abs(amount) < size) return new Intl.RelativeTimeFormat(locale, { numeric: 'auto' }).format(Math.round(amount), unit)
+    amount /= size
+  }
+  return ''
+}
+
+function Stamp({ at, now, locale }: { at: Date; now: Date; locale: string }) {
+  const absolute = new Intl.DateTimeFormat(locale, { dateStyle: 'medium', timeStyle: 'short' }).format(at)
+  return (
+    <time className="ty-activity__time" dateTime={at.toISOString()} title={absolute}>
+      {relativePhrase(at, now, locale)}
+    </time>
+  )
+}
+
+/** Recent acts on the research, actor first (spec: wave-4/activity-feed.md; §2.11). */
+export function ActivityFeed(props: ActivityFeedProps) {
+  const words = useMessages().activityFeed
+  const adapterLocale = useLocale().locale
+  const locale = props.locale ?? adapterLocale
+  const now = props.now ?? new Date()
+  if (!props.entries.length) return <p className={cx('ty-activity__empty', props.className)}>{words.empty}</p>
+  return (
+    <div className={cx('ty-activity', props.className)}>
+      <ol className="ty-activity__list" aria-label={props.label}>
+        {props.entries.map((entry) => (
+          <li key={entry.id} className="ty-activity__entry">
+            <ActorChip compact kind={entry.actor.kind} name={entry.actor.name} agentKey={entry.actor.agentKey} model={entry.actor.model} />
+            <div className="ty-activity__body">
+              <p className="ty-activity__text" dir="auto">{entry.text}</p>
+              <p className="ty-activity__meta">
+                <Stamp at={typeof entry.at === 'string' ? new Date(entry.at) : entry.at} now={now} locale={locale} />
+                {entry.meta ? <code className="ty-activity__code">{entry.meta}</code> : null}
+              </p>
+            </div>
+          </li>
+        ))}
+      </ol>
+      {props.moreHref && props.moreLabel ? (
+        <AriaLink className="ty-activity__more" href={props.moreHref}>
+          {props.moreLabel}
+        </AriaLink>
+      ) : null}
+    </div>
+  )
+}

package/src/components/actor-chip/ActorChip.css

@@ -0,0 +1,93 @@
+/* ActorChip (design direction §2.11: person, agent, system). */
+@layer tympan.components {
+  .ty-actor-chip {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--ty-space-2);
+    min-inline-size: 0;
+    max-inline-size: 100%;
+    color: var(--ty-ink-2);
+    font-family: var(--ty-font-sans);
+    font-size: var(--ty-font-size-body);
+    line-height: var(--ty-font-line-height-body);
+    vertical-align: middle;
+  }
+  .ty-actor-chip[data-compact] {
+    gap: var(--ty-space-1);
+    font-size: var(--ty-font-size-label);
+    line-height: var(--ty-font-line-height-label);
+  }
+
+  .ty-actor-chip__text {
+    display: inline-flex;
+    flex-direction: column;
+    min-inline-size: 0;
+  }
+  .ty-actor-chip__line {
+    display: inline-flex;
+    align-items: baseline;
+    gap: var(--ty-space-1);
+    min-inline-size: 0;
+  }
+
+  .ty-actor-chip__name {
+    overflow: hidden;
+    color: var(--ty-ink);
+    font-weight: var(--ty-font-weight-semibold);
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  /* The kind word ("agent", "system") is always visible text, never colour alone. */
+  .ty-actor-chip__kind {
+    flex: none;
+    color: var(--ty-ink-3);
+    font-size: var(--ty-font-size-meta);
+    line-height: var(--ty-font-line-height-meta);
+  }
+  .ty-actor-chip[data-kind='agent'] .ty-actor-chip__kind {
+    padding-inline: var(--ty-space-1);
+    border: 1px dashed var(--ty-line-strong);
+    border-radius: var(--ty-radius-agent);
+    color: var(--ty-actor-agent);
+  }
+
+  .ty-actor-chip__meta {
+    display: inline-flex;
+    flex-wrap: wrap;
+    gap: 0 var(--ty-space-2);
+    color: var(--ty-ink-3);
+    font-size: var(--ty-font-size-meta);
+    line-height: var(--ty-font-line-height-meta);
+  }
+  .ty-actor-chip__mono {
+    font-family: var(--ty-font-mono);
+    font-size: var(--ty-font-size-meta);
+    line-height: var(--ty-font-line-height-meta);
+  }
+  .ty-actor-chip__rule {
+    color: var(--ty-ink-2);
+  }
+
+  .ty-actor-chip__icon {
+    flex: none;
+    inline-size: 16px;
+    block-size: 16px;
+    color: var(--ty-ink-3);
+  }
+  .ty-actor-chip[data-kind='system'] .ty-actor-chip__icon {
+    color: var(--ty-actor-system);
+  }
+
+  @media (forced-colors: active) {
+    .ty-actor-chip,
+    .ty-actor-chip__name,
+    .ty-actor-chip__kind,
+    .ty-actor-chip__icon {
+      color: CanvasText;
+    }
+    .ty-actor-chip[data-kind='agent'] .ty-actor-chip__kind {
+      border-color: CanvasText;
+    }
+  }
+}