@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/components/floating-action-bar/barModel.ts

@@ -0,0 +1,147 @@
+// Pure rules of the action bar (wave-4/floating-action-bar.md): which edge it
+// uses, how many slots fit, which items overflow, how chords are matched and
+// how counts are shown. Kept free of React so every rule is unit-tested.
+
+export type BarEdge = 'bottom' | 'start' | 'end' | 'top'
+export type BarKind = 'destination' | 'contextual'
+
+/** Geometry (px) shared with FloatingActionBar.css. */
+export const BAR_GEOMETRY = {
+  item: 44,
+  gap: 4,
+  padding: 6,
+  margin: 12,
+  separator: 9,
+} as const
+
+/** Items a tab bar shows before its "more" slot. */
+export const TAB_BAR_SLOTS = 5
+
+export interface Placed<T> {
+  item: T
+  kind: BarKind
+}
+
+export interface BarPlan<T> {
+  shown: Placed<T>[]
+  overflow: Placed<T>[]
+}
+
+/** Below 1024 px the bar always sits on the bottom edge. */
+export function effectiveEdge(requested: BarEdge, wide: boolean): BarEdge {
+  return wide ? requested : 'bottom'
+}
+
+export function isHorizontal(edge: BarEdge): boolean {
+  return edge === 'bottom' || edge === 'top'
+}
+
+/** How many item slots fit along `length` px of the edge. */
+export function slotsAlong(length: number): number {
+  const { item, gap, padding, margin, separator } = BAR_GEOMETRY
+  if (!Number.isFinite(length) || length <= 0) return Number.POSITIVE_INFINITY
+  const usable = length - 2 * margin - 2 * padding - separator
+  return Math.max(2, Math.floor((usable + gap) / (item + gap)))
+}
+
+/**
+ * Splits the items into the ones on the bar and the ones in "more". When they
+ * do not fit, one slot goes to "more"; trailing contextual items leave first,
+ * then trailing destinations; an active item never leaves.
+ */
+export function planBar<T extends { active?: boolean }>(destinations: T[], contextual: T[], slots: number): BarPlan<T> {
+  const everything: Placed<T>[] = [
+    ...destinations.map((item) => ({ item, kind: 'destination' as const })),
+    ...contextual.map((item) => ({ item, kind: 'contextual' as const })),
+  ]
+  if (everything.length <= slots) return { shown: everything, overflow: [] }
+  const excess = everything.length - Math.max(1, slots - 1)
+  const leaving = new Set<Placed<T>>()
+  const candidates = [
+    ...everything.filter((p) => p.kind === 'contextual').reverse(),
+    ...everything.filter((p) => p.kind === 'destination').reverse(),
+  ]
+  for (const candidate of candidates) {
+    if (leaving.size >= excess) break
+    if (!candidate.item.active) leaving.add(candidate)
+  }
+  return {
+    shown: everything.filter((p) => !leaving.has(p)),
+    overflow: everything.filter((p) => leaving.has(p)),
+  }
+}
+
+export interface Chord {
+  alt: boolean
+  ctrl: boolean
+  meta: boolean
+  shift: boolean
+  key: string
+}
+
+/** Parses "Alt+Shift+D" (case-insensitive; Mod = Meta on Apple, Ctrl elsewhere is left to the host). */
+export function parseChord(text: string): Chord {
+  const parts = text.split('+').map((p) => p.trim().toLowerCase())
+  const key = parts.pop() ?? ''
+  const has = (name: string) => parts.includes(name)
+  return { alt: has('alt') || has('option'), ctrl: has('ctrl') || has('control'), meta: has('meta') || has('cmd'), shift: has('shift'), key }
+}
+
+interface KeyLike {
+  altKey: boolean
+  ctrlKey: boolean
+  metaKey: boolean
+  shiftKey: boolean
+  key: string
+  code?: string
+}
+
+/** Physical-key aware match: Alt on Apple keyboards changes `key`, so letters and digits also match on `code`. */
+export function chordMatches(event: KeyLike, chord: Chord): boolean {
+  if (event.altKey !== chord.alt || event.ctrlKey !== chord.ctrl || event.metaKey !== chord.meta || event.shiftKey !== chord.shift) return false
+  if (event.key.toLowerCase() === chord.key) return true
+  const code = event.code ?? ''
+  return code === `Key${chord.key.toUpperCase()}` || code === `Digit${chord.key}`
+}
+
+/** `aria-keyshortcuts` form of a chord text ("Alt+Shift+D"). */
+export function ariaShortcut(text: string): string {
+  const c = parseChord(text)
+  return [c.ctrl && 'Control', c.alt && 'Alt', c.meta && 'Meta', c.shift && 'Shift', c.key.length === 1 ? c.key.toUpperCase() : c.key]
+    .filter(Boolean)
+    .join('+')
+}
+
+type Step = 'next' | 'previous' | 'first' | 'last' | 'menu' | null
+
+/** Maps a key to a roving step for the bar's orientation and reading direction. */
+export function stepFor(key: string, edge: BarEdge, rtl: boolean): Step {
+  if (key === 'Home') return 'first'
+  if (key === 'End') return 'last'
+  if (isHorizontal(edge)) {
+    const forward = rtl ? 'ArrowLeft' : 'ArrowRight'
+    const backward = rtl ? 'ArrowRight' : 'ArrowLeft'
+    if (key === forward) return 'next'
+    if (key === backward) return 'previous'
+    return key === 'ArrowDown' ? 'menu' : null
+  }
+  if (key === 'ArrowDown') return 'next'
+  if (key === 'ArrowUp') return 'previous'
+  const opensMenu = (edge === 'start') !== rtl ? 'ArrowRight' : 'ArrowLeft'
+  return key === opensMenu ? 'menu' : null
+}
+
+/** Wrapping index move. */
+export function moveIndex(current: number, count: number, step: Exclude<Step, 'menu' | null>): number {
+  if (count <= 0) return 0
+  switch (step) {
+    case 'first':
+      return 0
+    case 'last':
+      return count - 1
+    case 'next':
+      return (current + 1) % count
+    case 'previous':
+      return (current - 1 + count) % count
+  }
+}

package/src/components/floating-action-button/FloatingActionButton.css

@@ -0,0 +1,54 @@
+/* FloatingActionButton (spec: wave-2/floating-action-button.md; design direction §2.3, §2.6, §2.7, §2.8). */
+@layer tympan.components {
+  .ty-fab-inline {
+    display: inline-flex;
+  }
+  .ty-fab-dock {
+    --ty-fab-size: 56px;
+    --ty-fab-offset: var(--ty-space-4);
+    position: fixed;
+    z-index: var(--ty-z-sticky);
+    inset-block-end: calc(env(safe-area-inset-bottom, 0px) + var(--ty-fab-offset));
+    animation: ty-fab-in var(--ty-dur-base) var(--ty-ease);
+  }
+  .ty-fab-dock[data-size='large'] {
+    --ty-fab-size: 64px;
+  }
+  .ty-fab-dock[data-placement='end-bottom'] {
+    inset-inline-end: calc(env(safe-area-inset-right, 0px) + var(--ty-fab-offset));
+  }
+  .ty-fab-dock[data-placement='start-bottom'] {
+    inset-inline-start: calc(env(safe-area-inset-left, 0px) + var(--ty-fab-offset));
+  }
+  .ty-fab-dock[data-placement='center-bottom'] {
+    /* physical: centring with a -50% shift is the same in both directions */
+    left: 50%;
+    translate: -50% 0;
+  }
+  .ty-fab-dock .ty-fab {
+    --ty-button-height: var(--ty-fab-size);
+    min-inline-size: var(--ty-fab-size);
+    box-shadow: var(--ty-shadow-floating);
+  }
+  @keyframes ty-fab-in {
+    from {
+      opacity: 0;
+      scale: 0.9;
+    }
+  }
+  /* The page keeps its last row visible above the floating button. */
+  body[data-ty-fab-reserve] {
+    padding-block-end: calc(56px + var(--ty-space-4) * 2 + env(safe-area-inset-bottom, 0px));
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .ty-fab-dock {
+      animation: none;
+    }
+  }
+  @media (forced-colors: active) {
+    .ty-fab-dock .ty-fab {
+      border: 2px solid ButtonText;
+      color: ButtonText;
+    }
+  }
+}

package/src/components/floating-action-button/FloatingActionButton.test.tsx

@@ -0,0 +1,87 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Plus } from 'lucide-react'
+import { describe, expect, it, vi } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { cssOf, mediaBlock } from '../../../test/css'
+import { setViewportWidth } from '../../../test/media'
+import { ThemeScope } from '../../internal/ThemeScope'
+import { FloatingActionButton } from './FloatingActionButton'
+import * as rtlDom from '@testing-library/react'
+import { expectNoAxeViolations as axeRtl } from '../../../test/axe'
+import { renderRtl } from '../../../test/rtl'
+
+describe('FloatingActionButton', () => {
+  it('is inline at 1280 with no floating copy', () => {
+    setViewportWidth(1280)
+    render(<FloatingActionButton label="New session" icon={<Plus />} onPress={() => {}} />)
+    expect(screen.getAllByRole('button', { name: 'New session' })).toHaveLength(1)
+    expect(document.querySelector('.ty-fab-dock')).toBeNull()
+    expect(screen.getByRole('button')).toHaveTextContent('New session')
+  })
+
+  it('floats once at 375, after the content, above the safe area', () => {
+    setViewportWidth(375)
+    render(
+      <main>
+        <FloatingActionButton label="New session" icon={<Plus />} onPress={() => {}} />
+        <p>Last row</p>
+      </main>,
+    )
+    const buttons = screen.getAllByRole('button', { name: 'New session' })
+    expect(buttons).toHaveLength(1)
+    const dock = buttons[0]!.closest('.ty-fab-dock')!
+    expect(dock).not.toBeNull()
+    expect(screen.getByText('Last row').compareDocumentPosition(dock) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy()
+    expect(document.body).toHaveAttribute('data-ty-fab-reserve')
+    expect(cssOf('components/floating-action-button/FloatingActionButton.css')).toMatch(/safe-area-inset-bottom/)
+  })
+
+  it('ignores presses while loading and reports busy', async () => {
+    setViewportWidth(375)
+    const onPress = vi.fn()
+    render(<FloatingActionButton label="New session" icon={<Plus />} onPress={onPress} loading />)
+    const button = screen.getByRole('button', { name: 'New session' })
+    button.focus()
+    await userEvent.keyboard('{Enter}')
+    expect(onPress).not.toHaveBeenCalled()
+    expect(button).toHaveAttribute('aria-busy', 'true')
+  })
+
+  it('announces the label when only the icon is visible', () => {
+    setViewportWidth(375)
+    render(<FloatingActionButton label="Add source" icon={<Plus />} onPress={() => {}} />)
+    expect(screen.getByRole('button', { name: 'Add source' })).toHaveAttribute('data-icon-only')
+  })
+
+  it('does not scale in under reduced motion', () => {
+    const reduced = mediaBlock(cssOf('components/floating-action-button/FloatingActionButton.css'), /\(prefers-reduced-motion:\s*reduce\)/)
+    expect(reduced).toMatch(/\.ty-fab-dock\s*\{[^}]*animation:\s*none/)
+  })
+
+  it('has no axe violations in each state, light and dark', async () => {
+    setViewportWidth(1280)
+    const { container } = render(
+      <>
+        {(['light', 'dark'] as const).map((scheme) => (
+          <ThemeScope key={scheme} scheme={scheme}>
+            <FloatingActionButton label={`New ${scheme}`} icon={<Plus />} onPress={() => {}} />
+            <FloatingActionButton label={`Busy ${scheme}`} icon={<Plus />} onPress={() => {}} loading />
+            <FloatingActionButton label={`Off ${scheme}`} icon={<Plus />} onPress={() => {}} disabled emphasis="secondary" />
+          </ThemeScope>
+        ))}
+      </>,
+    )
+    await expectNoAxeViolations(container)
+    setViewportWidth(375)
+    await expectNoAxeViolations(document.body)
+  })
+})
+
+describe('FloatingActionButton in right-to-left (ar)', () => {
+  it('renders mirrored where directional and passes axe', async () => {
+    const { container } = renderRtl(<FloatingActionButton label="جلسة جديدة" icon={<span />} onPress={() => {}} presentation="inline" />)
+    expect(rtlDom.screen.getByRole('button', { name: 'جلسة جديدة' })).toBeInTheDocument()
+    await axeRtl(container)
+  })
+})

package/src/components/floating-action-button/FloatingActionButton.tsx

@@ -0,0 +1,87 @@
+import { useEffect, type ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+import { cx } from '../../internal/cx'
+import { requestHaptic } from '../../internal/haptics'
+import { breakpoints, useMediaQuery } from '../../internal/media'
+import { Button } from '../button/Button'
+
+export type FabPlacement = 'end-bottom' | 'start-bottom' | 'center-bottom'
+export type FabPresentation = 'responsive' | 'floating' | 'inline'
+
+export interface FloatingActionButtonProps {
+  label: string
+  icon?: ReactNode
+  onPress: () => void
+  placement?: FabPlacement
+  presentation?: FabPresentation
+  /** Shows the label beside the icon while floating. */
+  extended?: boolean
+  size?: 'regular' | 'large'
+  emphasis?: 'primary' | 'secondary'
+  loading?: boolean
+  disabled?: boolean
+  /** Haptic tick on activation where supported. */
+  haptic?: boolean
+  className?: string
+}
+
+/** Page attribute that reserves room under the last row while a button floats. */
+const RESERVE_ATTRIBUTE = 'data-ty-fab-reserve'
+
+function useReserveBottom(active: boolean) {
+  useEffect(() => {
+    if (!active || typeof document === 'undefined') return
+    const body = document.body
+    const depth = Number(body.getAttribute(RESERVE_ATTRIBUTE) ?? '0') + 1
+    body.setAttribute(RESERVE_ATTRIBUTE, String(depth))
+    return () => {
+      const left = Number(body.getAttribute(RESERVE_ATTRIBUTE) ?? '1') - 1
+      if (left > 0) body.setAttribute(RESERVE_ATTRIBUTE, String(left))
+      else body.removeAttribute(RESERVE_ATTRIBUTE)
+    }
+  }, [active])
+}
+
+/**
+ * The screen's main creation action (spec: wave-2/floating-action-button.md).
+ * One element only: inline where it is placed on wide screens; on small
+ * screens the same element moves (portal) to the end of the document so it
+ * follows the main content in reading order and floats above the safe area.
+ */
+export function FloatingActionButton(props: FloatingActionButtonProps) {
+  const wide = useMediaQuery(`(min-width: ${breakpoints.lg}px)`, true)
+  const presentation = props.presentation ?? 'responsive'
+  const floats = presentation === 'floating' || (presentation === 'responsive' && !wide)
+  const showsText = !floats || (props.extended ?? false)
+  useReserveBottom(floats)
+
+  const press = () => {
+    if (props.haptic) requestHaptic('light')
+    props.onPress()
+  }
+
+  const control = (
+    <Button
+      className={cx('ty-fab', props.className)}
+      variant={props.emphasis === 'secondary' ? 'secondary' : 'primary'}
+      size={props.size === 'large' ? 'large' : 'regular'}
+      shape={floats ? (showsText ? 'pill' : 'circle') : 'rounded'}
+      iconOnly={!showsText}
+      accessibleLabel={props.label}
+      leadingIcon={props.icon}
+      busy={props.loading}
+      disabled={props.disabled}
+      onPress={press}
+    >
+      {props.label}
+    </Button>
+  )
+
+  if (!floats) return <span className="ty-fab-inline">{control}</span>
+  const floating = (
+    <div className="ty-fab-dock" data-placement={props.placement ?? 'end-bottom'} data-size={props.size ?? 'regular'}>
+      {control}
+    </div>
+  )
+  return typeof document === 'undefined' ? floating : createPortal(floating, document.body)
+}

package/src/components/form-actions/FormActions.css

@@ -0,0 +1,34 @@
+/* FormActions (spec: wave-2/form-actions.md; design direction §2.1, §2.10). */
+@layer tympan.components {
+  .ty-form-actions {
+    --ty-form-actions-justify: flex-end;
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: var(--ty-form-actions-justify);
+    gap: var(--ty-space-3);
+  }
+  .ty-form-actions[data-align='start'] {
+    --ty-form-actions-justify: flex-start;
+  }
+  .ty-form-actions[data-align='between'] {
+    --ty-form-actions-justify: space-between;
+  }
+
+  /* Phones: full width, primary on top visually; the DOM keeps secondary first. */
+  @media (max-width: 639.98px) {
+    .ty-form-actions {
+      flex-direction: column-reverse;
+      align-items: stretch;
+    }
+    .ty-form-actions > * {
+      inline-size: 100%;
+    }
+  }
+
+  @media (forced-colors: active) {
+    .ty-form-actions__primary {
+      border-width: 3px;
+    }
+  }
+}

package/src/components/form-actions/FormActions.test.tsx

@@ -0,0 +1,96 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { cssOf, mediaBlock } from '../../../test/css'
+import { ThemeScope } from '../../internal/ThemeScope'
+import { FormActions } from './FormActions'
+import * as rtlDom from '@testing-library/react'
+import { expectNoAxeViolations as axeRtl } from '../../../test/axe'
+import { renderRtl } from '../../../test/rtl'
+
+describe('FormActions', () => {
+  it('calls onCancel from the secondary button', async () => {
+    const onCancel = vi.fn()
+    render(<FormActions cancelLabel="Cancel" saveLabel="Save" onCancel={onCancel} onSave={() => {}} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Cancel' }))
+    expect(onCancel).toHaveBeenCalledTimes(1)
+  })
+
+  it('submits the enclosing form when onSave is absent', async () => {
+    const onSubmit = vi.fn((e: React.FormEvent) => e.preventDefault())
+    render(
+      <form onSubmit={onSubmit}>
+        <FormActions cancelLabel="Cancel" saveLabel="Save" onCancel={() => {}} />
+      </form>,
+    )
+    const save = screen.getByRole('button', { name: 'Save' })
+    expect(save).toHaveAttribute('type', 'submit')
+    await userEvent.click(save)
+    expect(onSubmit).toHaveBeenCalledTimes(1)
+  })
+
+  it('disables only the primary with saveDisabled', () => {
+    render(<FormActions cancelLabel="Cancel" saveLabel="Save" onCancel={() => {}} saveDisabled />)
+    expect(screen.getByRole('button', { name: 'Save' })).toBeDisabled()
+    expect(screen.getByRole('button', { name: 'Cancel' })).toBeEnabled()
+  })
+
+  it('disables both and exposes busy while saving', async () => {
+    const onSave = vi.fn()
+    render(<FormActions cancelLabel="Cancel" saveLabel="Save" onCancel={() => {}} onSave={onSave} saving />)
+    const primary = screen.getByRole('button', { name: 'Saving' })
+    expect(primary).toHaveAttribute('aria-busy', 'true')
+    expect(screen.getByRole('button', { name: 'Cancel' })).toBeDisabled()
+    await userEvent.click(primary)
+    expect(onSave).not.toHaveBeenCalled()
+  })
+
+  it('stacks full width below 640 px by layout reversal, keeping DOM order', () => {
+    render(<FormActions cancelLabel="Cancel" saveLabel="Save" onCancel={() => {}} />)
+    const [first, second] = screen.getAllByRole('button')
+    expect(first).toHaveTextContent('Cancel')
+    expect(second).toHaveTextContent('Save')
+    const phone = mediaBlock(cssOf('components/form-actions/FormActions.css'), /\(max-width:\s*639\.98px\)/)
+    expect(phone).toMatch(/flex-direction:\s*column-reverse/)
+    expect(phone).toMatch(/inline-size:\s*100%/)
+  })
+
+  it('uses the danger variant with an icon and word when destructive', () => {
+    render(<FormActions cancelLabel="Keep" saveLabel="Delete edition" onCancel={() => {}} onSave={() => {}} emphasis="destructive" />)
+    const primary = screen.getByRole('button', { name: 'Delete edition' })
+    expect(primary).toHaveAttribute('data-variant', 'danger')
+    expect(primary.querySelector('svg')).not.toBeNull()
+  })
+
+  it('renders free children in a group', () => {
+    render(
+      <FormActions label="Row">
+        <button type="button">One</button>
+      </FormActions>,
+    )
+    expect(screen.getByRole('group', { name: 'Row' })).toContainElement(screen.getByRole('button', { name: 'One' }))
+  })
+
+  it('has no axe violations, light and dark', async () => {
+    const { container } = render(
+      <>
+        {(['light', 'dark'] as const).map((scheme) => (
+          <ThemeScope key={scheme} scheme={scheme}>
+            <FormActions cancelLabel="Cancel" saveLabel="Save" onCancel={() => {}} onSave={() => {}} />
+            <FormActions cancelLabel="Keep" saveLabel="Delete" onCancel={() => {}} onSave={() => {}} emphasis="destructive" saving />
+          </ThemeScope>
+        ))}
+      </>,
+    )
+    await expectNoAxeViolations(container)
+  })
+})
+
+describe('FormActions in right-to-left (ar)', () => {
+  it('renders mirrored where directional and passes axe', async () => {
+    const { container } = renderRtl(<FormActions cancelLabel="إلغاء" saveLabel="حفظ" onCancel={() => {}} onSave={() => {}} />)
+    expect(rtlDom.screen.getByRole('button', { name: 'حفظ' })).toBeInTheDocument()
+    await axeRtl(container)
+  })
+})

package/src/components/form-actions/FormActions.tsx

@@ -0,0 +1,83 @@
+import { TriangleAlert } from 'lucide-react'
+import type { ReactNode } from 'react'
+import { cx } from '../../internal/cx'
+import { useMessages } from '../../internal/provider'
+import { Button } from '../button/Button'
+
+export type FormActionsAlign = 'end' | 'between' | 'start'
+export type FormActionsEmphasis = 'default' | 'destructive'
+
+export interface FormActionsProps {
+  cancelLabel?: string
+  saveLabel?: string
+  onCancel?: () => void
+  /** Without it the primary button submits the enclosing form. */
+  onSave?: () => void
+  saveDisabled?: boolean
+  saving?: boolean
+  emphasis?: FormActionsEmphasis
+  align?: FormActionsAlign
+  /** Optional name of the group. */
+  label?: string
+  /** Free row: replaces the preset buttons. */
+  children?: ReactNode
+  className?: string
+}
+
+interface PresetSlots {
+  secondary: ReactNode
+  primary: ReactNode
+}
+
+function usePresetSlots(p: FormActionsProps): PresetSlots | null {
+  const m = useMessages()
+  if (p.children != null) return null
+  const destructive = p.emphasis === 'destructive'
+  const busy = !!p.saving
+  return {
+    secondary:
+      p.cancelLabel != null ? (
+        <Button variant="secondary" disabled={busy} onPress={() => p.onCancel?.()}>
+          {p.cancelLabel}
+        </Button>
+      ) : null,
+    primary:
+      p.saveLabel != null ? (
+        <Button
+          variant={destructive ? 'danger' : 'primary'}
+          type={p.onSave ? 'button' : 'submit'}
+          disabled={!!p.saveDisabled}
+          busy={busy}
+          busyLabel={m.formActions.saving}
+          leadingIcon={destructive ? <TriangleAlert /> : undefined}
+          onPress={p.onSave ? () => p.onSave?.() : undefined}
+          className="ty-form-actions__primary"
+        >
+          {p.saveLabel}
+        </Button>
+      ) : null,
+  }
+}
+
+/** The closing row of a form or dialog (spec: wave-2/form-actions.md). DOM order: secondary, then primary. */
+export function FormActions(props: FormActionsProps) {
+  const slots = usePresetSlots(props)
+  return (
+    <div
+      role="group"
+      aria-label={props.label}
+      className={cx('ty-form-actions', props.className)}
+      data-align={props.align ?? 'end'}
+      data-emphasis={props.emphasis ?? 'default'}
+    >
+      {slots ? (
+        <>
+          {slots.secondary}
+          {slots.primary}
+        </>
+      ) : (
+        props.children
+      )}
+    </div>
+  )
+}