@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/components/wheel-picker/WheelPicker.tsx

@@ -0,0 +1,228 @@
+import { useCallback, useEffect, useMemo, useRef, useState, type CSSProperties, type KeyboardEvent } from 'react'
+import { ListBox, ListBoxItem, type Key } from 'react-aria-components'
+import { cx } from '../../internal/cx'
+import { requestHaptic } from '../../internal/haptics'
+import { prefersReducedMotion } from '../../internal/media'
+
+export type WheelOption = string | { value: string; label: string }
+
+export interface WheelPickerProps {
+  options: WheelOption[]
+  value: string
+  onChange: (value: string) => void
+  label: string
+  /** Odd number of rows visible at once. */
+  visibleRows?: number
+  disabled?: boolean
+  className?: string
+  /** Relative width inside a WheelPickerGroup. */
+  share?: number
+  /** Shows the label as a caption above the wheel. */
+  showLabel?: boolean
+}
+
+interface Row {
+  id: string
+  text: string
+}
+
+const toRows = (options: WheelOption[]): Row[] => options.map((o) => (typeof o === 'string' ? { id: o, text: o } : { id: o.value, text: o.label }))
+const SETTLE_MS = 120
+const DEFAULT_ROW = 44
+
+/** Pointer-drag scrolling for mouse and pen; touch scrolls natively. */
+function useDragScroll(list: React.RefObject<HTMLElement | null>) {
+  const moved = useRef(false)
+  useEffect(() => {
+    const el = list.current
+    if (!el) return
+    let start: { y: number; top: number } | null = null
+    const down = (e: PointerEvent) => {
+      if (e.pointerType === 'touch') return
+      start = { y: e.clientY, top: el.scrollTop }
+      moved.current = false
+    }
+    const move = (e: PointerEvent) => {
+      if (!start) return
+      const dy = e.clientY - start.y
+      if (Math.abs(dy) > 4) moved.current = true
+      if (moved.current) el.scrollTop = start.top - dy
+    }
+    const up = () => {
+      start = null
+    }
+    el.addEventListener('pointerdown', down)
+    window.addEventListener('pointermove', move)
+    window.addEventListener('pointerup', up)
+    return () => {
+      el.removeEventListener('pointerdown', down)
+      window.removeEventListener('pointermove', move)
+      window.removeEventListener('pointerup', up)
+    }
+  }, [list])
+  /** True once, right after a drag ended (the following tap is ignored). */
+  return () => {
+    const was = moved.current
+    moved.current = false
+    return was
+  }
+}
+
+/**
+ * One wheel: a listbox whose selected option sits in the centre band
+ * (spec: wave-2/wheel-picker.md).
+ */
+export function WheelPicker(props: WheelPickerProps) {
+  const rows = useMemo(() => toRows(props.options), [props.options])
+  const visible = Math.max(3, (props.visibleRows ?? 5) | 1)
+  const listRef = useRef<HTMLDivElement>(null)
+  const index = rows.findIndex((r) => r.id === props.value)
+  const [centre, setCentre] = useState(Math.max(0, index))
+  const programmatic = useRef(false)
+  const settleTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+  const endedDrag = useDragScroll(listRef)
+  const { onChange } = props
+
+  const rowHeight = () => {
+    const item = listRef.current?.querySelector<HTMLElement>('[role="option"]')
+    return item?.offsetHeight || DEFAULT_ROW
+  }
+
+  // Bring the value's row to the band whenever the value changes. React Aria
+  // commits the option rows in a later pass than the ListBox itself (on
+  // React 18 in particular), so on mount the list can still be empty here and
+  // a scroll would be clamped to 0. Wait until the target row exists; the
+  // first placement jumps, later moves animate.
+  const placed = useRef(false)
+  useEffect(() => {
+    const el = listRef.current
+    const target = Math.max(0, index)
+    setCentre(target)
+    if (!el) return
+    const place = () => {
+      const first = !placed.current
+      placed.current = true
+      programmatic.current = true
+      const top = target * rowHeight()
+      const behavior: ScrollBehavior = first || prefersReducedMotion() ? 'instant' : 'smooth'
+      if (typeof el.scrollTo === 'function') el.scrollTo({ top, behavior })
+      else el.scrollTop = top
+      clearTimeout(settleTimer.current)
+      settleTimer.current = setTimeout(() => {
+        programmatic.current = false
+      }, 400)
+    }
+    const ready = () => el.querySelectorAll('[role="option"]').length > target
+    if (ready() || typeof MutationObserver === 'undefined') {
+      place()
+      return
+    }
+    const observer = new MutationObserver(() => {
+      if (!ready()) return
+      observer.disconnect()
+      place()
+    })
+    observer.observe(el, { childList: true, subtree: true })
+    return () => observer.disconnect()
+  }, [index])
+
+  // User scrolling: tick on every row that crosses the band, report on settle.
+  const onScroll = useCallback(() => {
+    const el = listRef.current
+    if (!el) return
+    const at = Math.min(rows.length - 1, Math.max(0, Math.round(el.scrollTop / rowHeight())))
+    setCentre((prev) => {
+      if (prev !== at && !programmatic.current) requestHaptic('light')
+      return at
+    })
+    if (programmatic.current) return
+    clearTimeout(settleTimer.current)
+    settleTimer.current = setTimeout(() => {
+      const row = rows[at]
+      if (row && row.id !== props.value) {
+        requestHaptic('light')
+        onChange(row.id)
+      }
+    }, SETTLE_MS)
+  }, [rows, props.value, onChange])
+
+  useEffect(() => {
+    const el = listRef.current
+    el?.addEventListener('scroll', onScroll, { passive: true })
+    return () => el?.removeEventListener('scroll', onScroll)
+  }, [onScroll])
+  useEffect(() => () => clearTimeout(settleTimer.current), [])
+
+  const choose = (keys: 'all' | Set<Key>) => {
+    if (keys === 'all' || endedDrag()) return
+    const [key] = [...keys]
+    if (key != null && String(key) !== props.value) onChange(String(key))
+  }
+
+  // PageUp/PageDown move by the number of visible rows.
+  const pageKeys = (e: KeyboardEvent<HTMLDivElement>) => {
+    if (e.key !== 'PageUp' && e.key !== 'PageDown') return
+    e.preventDefault()
+    e.stopPropagation()
+    const from = Math.max(0, index)
+    const to = Math.min(rows.length - 1, Math.max(0, from + (e.key === 'PageUp' ? -visible : visible)))
+    const row = rows[to]
+    if (row && row.id !== props.value) onChange(row.id)
+    requestAnimationFrame(() => listRef.current?.querySelector<HTMLElement>(`[data-key="${CSS.escape(String(row?.id ?? ''))}"]`)?.focus())
+  }
+
+  const style = { '--ty-wheel-rows': visible, '--ty-wheel-share': props.share ?? 1 } as CSSProperties
+  return (
+    <div className={cx('ty-wheel', props.className)} style={style} data-disabled={props.disabled || undefined} onKeyDownCapture={pageKeys}>
+      {props.showLabel ? (
+        <span className="ty-wheel__caption" aria-hidden="true">
+          {props.label}
+        </span>
+      ) : null}
+      <div className="ty-wheel__viewport">
+        <span className="ty-wheel__band" aria-hidden="true" />
+        <ListBox
+          ref={listRef}
+          aria-label={props.label}
+          className="ty-wheel__list"
+          items={rows}
+          selectionMode="single"
+          selectionBehavior="replace"
+          disallowEmptySelection
+          shouldFocusWrap={false}
+          selectedKeys={index >= 0 ? [props.value] : []}
+          onSelectionChange={choose}
+          disabledKeys={props.disabled ? rows.map((r) => r.id) : undefined}
+        >
+          {(row) => (
+            <ListBoxItem id={row.id} textValue={row.text} className="ty-wheel__row" data-distance={Math.min(3, Math.abs(rows.indexOf(row) - centre))}>
+              {row.text}
+            </ListBoxItem>
+          )}
+        </ListBox>
+      </div>
+    </div>
+  )
+}
+
+export type WheelColumn = Omit<WheelPickerProps, 'visibleRows' | 'disabled' | 'className' | 'showLabel'>
+
+export interface WheelPickerGroupProps {
+  columns: WheelColumn[]
+  /** Name of the whole group. */
+  label: string
+  visibleRows?: number
+  disabled?: boolean
+  className?: string
+}
+
+/** Several wheels side by side for compound values (day, month, year). */
+export function WheelPickerGroup({ columns, label, visibleRows, disabled, className }: WheelPickerGroupProps) {
+  return (
+    <div role="group" aria-label={label} className={cx('ty-wheel-group', className)}>
+      {columns.map((column) => (
+        <WheelPicker key={column.label} {...column} visibleRows={visibleRows} disabled={disabled} showLabel />
+      ))}
+    </div>
+  )
+}

package/src/components/wizard-page/WizardPage.css

@@ -0,0 +1,114 @@
+/* WizardPage (spec: wave-2/wizard-page.md; design direction §2.1, §2.2, §2.5, §2.7). */
+@layer tympan.components {
+  .ty-wizard-page {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ty-space-6);
+    margin-inline: auto;
+    inline-size: 100%;
+    max-inline-size: var(--ty-layout-reading);
+  }
+  .ty-wizard-page__head {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ty-space-3);
+    padding: var(--ty-space-6);
+    border: 1px solid var(--ty-line);
+    border-radius: var(--ty-radius-sheet);
+    background: var(--ty-surface);
+    box-shadow: var(--ty-shadow-sheet);
+    backdrop-filter: blur(var(--ty-glass-blur-sheet)) saturate(var(--ty-glass-saturate));
+    -webkit-backdrop-filter: blur(var(--ty-glass-blur-sheet)) saturate(var(--ty-glass-saturate));
+  }
+  .ty-wizard-page__top {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--ty-space-3);
+  }
+  .ty-wizard-page__eyebrow {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--ty-space-2);
+    margin: 0;
+    color: var(--ty-ink-3);
+    font-size: var(--ty-font-size-eyebrow);
+    font-weight: var(--ty-font-weight-semibold);
+    line-height: var(--ty-font-line-height-eyebrow);
+    letter-spacing: var(--ty-font-tracking-eyebrow);
+    text-transform: uppercase;
+  }
+  .ty-wizard-page__eyebrow-icon > svg {
+    inline-size: 16px;
+    block-size: 16px;
+  }
+  .ty-wizard-page__title {
+    margin: 0;
+    color: var(--ty-ink);
+    font-family: var(--ty-font-serif);
+    font-size: var(--ty-font-size-h1);
+    font-weight: var(--ty-font-weight-bold);
+    line-height: var(--ty-font-line-height-h1);
+    letter-spacing: var(--ty-font-tracking-h1);
+    outline: none;
+  }
+  .ty-wizard-page__title:focus-visible {
+    outline: var(--ty-focus-width) solid var(--ty-focus-ring);
+    outline-offset: 2px;
+  }
+  .ty-wizard-page__lead {
+    margin: 0;
+    max-inline-size: calc(var(--ty-measure-summary) * 1ch);
+    color: var(--ty-ink-2);
+    font-size: var(--ty-font-size-body-lg);
+    line-height: var(--ty-font-line-height-body-lg);
+  }
+  .ty-wizard-page__body {
+    animation: ty-wizard-cross var(--ty-dur-quick) var(--ty-ease);
+  }
+  @keyframes ty-wizard-cross {
+    from {
+      opacity: 0;
+    }
+  }
+  .ty-wizard-page__nav {
+    display: flex;
+    justify-content: space-between;
+    gap: var(--ty-space-3);
+  }
+  @media (max-width: 767.98px) {
+    .ty-wizard-page__title {
+      font-size: var(--ty-font-size-h1-narrow);
+      line-height: var(--ty-font-line-height-h1-narrow);
+    }
+    .ty-wizard-page__head {
+      padding: var(--ty-space-5);
+    }
+  }
+  /* Under 640: full-width stacked buttons, primary shown first, read last. */
+  @media (max-width: 639.98px) {
+    .ty-wizard-page__nav {
+      flex-direction: column-reverse;
+    }
+    .ty-wizard-page__nav > * {
+      inline-size: 100%;
+    }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .ty-wizard-page__body {
+      animation: none;
+    }
+  }
+  @media (prefers-reduced-transparency: reduce) {
+    .ty-wizard-page__head {
+      background: var(--ty-surface-solid);
+      backdrop-filter: none;
+    }
+  }
+  @media (forced-colors: active) {
+    .ty-wizard-page__head {
+      border: 1px solid CanvasText;
+      backdrop-filter: none;
+    }
+  }
+}

package/src/components/wizard-page/WizardPage.test.tsx

@@ -0,0 +1,117 @@
+import { act, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Sparkles } from 'lucide-react'
+import { describe, expect, it, vi } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { cssOf, mediaBlock } from '../../../test/css'
+import { ThemeScope } from '../../internal/ThemeScope'
+import { WizardPage, type WizardPageProps } from './WizardPage'
+import * as rtlDom from '@testing-library/react'
+import { expectNoAxeViolations as axeRtl } from '../../../test/axe'
+import { renderRtl } from '../../../test/rtl'
+
+const steps = [
+  { id: 'scope', title: 'Scope', description: 'What the project studies.' },
+  { id: 'team', title: 'Team' },
+  { id: 'review', title: 'Review' },
+]
+
+function setup(over: Partial<WizardPageProps> = {}) {
+  const props: WizardPageProps = {
+    title: 'New research project',
+    eyebrow: 'Create',
+    icon: <Sparkles />,
+    steps,
+    currentIndex: 0,
+    onStepChange: vi.fn(),
+    onSubmit: vi.fn(),
+    onCancel: vi.fn(),
+    ...over,
+  }
+  const view = render(<WizardPage {...props} />)
+  return { props, ...view }
+}
+
+describe('WizardPage', () => {
+  it('calls onCancel from previous on the first step', async () => {
+    const { props } = setup()
+    await userEvent.click(screen.getByRole('button', { name: 'Cancel' }))
+    expect(props.onCancel).toHaveBeenCalledTimes(1)
+  })
+
+  it('submits from the last step with the submit label', async () => {
+    const { props } = setup({ currentIndex: 2, submitLabel: 'Create project' })
+    await userEvent.click(screen.getByRole('button', { name: 'Create project' }))
+    expect(props.onSubmit).toHaveBeenCalledTimes(1)
+    await userEvent.click(screen.getByRole('button', { name: 'Previous' }))
+    expect(props.onStepChange).toHaveBeenCalledWith(1)
+  })
+
+  it('disables the primary when it cannot advance', () => {
+    setup({ canAdvance: false })
+    expect(screen.getByRole('button', { name: 'Next' })).toBeDisabled()
+  })
+
+  it('moves focus to the h1 of the new step and updates the document title', () => {
+    const { props, rerender } = setup()
+    expect(screen.getByRole('heading', { level: 1 })).toHaveTextContent('Scope')
+    act(() => rerender(<WizardPage {...props} currentIndex={1} />))
+    const h1 = screen.getByRole('heading', { level: 1 })
+    expect(h1).toHaveTextContent('Team')
+    expect(h1).toHaveFocus()
+    expect(document.title).toContain('Team')
+  })
+
+  it('disables both buttons and announces busy while submitting', () => {
+    setup({ currentIndex: 2, submitting: true })
+    expect(screen.getByRole('button', { name: 'Previous' })).toBeDisabled()
+    const primary = screen.getByRole('button', { name: 'Submitting' })
+    expect(primary).toHaveAttribute('aria-disabled', 'true')
+    expect(primary).toHaveAttribute('aria-busy', 'true')
+    expect(screen.getByRole('status')).toHaveTextContent('Submitting')
+  })
+
+  it('names the close button from the catalogue and stacks buttons on narrow screens', () => {
+    setup()
+    expect(screen.getByRole('button', { name: 'Close' })).toBeInTheDocument()
+    const css = cssOf('components/wizard-page/WizardPage.css')
+    expect(mediaBlock(css, /\(max-width:\s*639\.98px\)/)).toMatch(/column-reverse/)
+    expect(mediaBlock(css, /\(prefers-reduced-motion:\s*reduce\)/)).toMatch(/animation:\s*none/)
+  })
+
+  it('has no axe violations, light and dark', async () => {
+    const { container } = render(
+      <>
+        {(['light', 'dark'] as const).map((scheme) => (
+          <ThemeScope key={scheme} scheme={scheme}>
+            <WizardPage
+              title={`Flow ${scheme}`}
+              eyebrow="Create"
+              icon={<Sparkles />}
+              steps={steps}
+              currentIndex={1}
+              onStepChange={() => {}}
+              onSubmit={() => {}}
+              onCancel={() => {}}
+            >
+              <p>Body</p>
+            </WizardPage>
+          </ThemeScope>
+        ))}
+      </>,
+    )
+    await expectNoAxeViolations(container, ['page-has-heading-one', 'heading-order'])
+  })
+})
+
+describe('WizardPage in right-to-left (ar)', () => {
+  it('renders mirrored where directional and passes axe', async () => {
+    const { container } = renderRtl(
+      <WizardPage title="مشروع جديد" eyebrow="إنشاء" icon={<span />} steps={[{ id: 'a', title: 'النطاق' }, { id: 'b', title: 'الفريق' }]} currentIndex={0} onStepChange={() => {}} onSubmit={() => {}} onCancel={() => {}} submitLabel="إنشاء">
+        <p>نص</p>
+      </WizardPage>,
+    )
+    expect(rtlDom.screen.getByRole('heading', { level: 1 })).toBeInTheDocument()
+    await axeRtl(container)
+  })
+})

package/src/components/wizard-page/WizardPage.tsx

@@ -0,0 +1,123 @@
+import { X } from 'lucide-react'
+import { useEffect, useRef, type ReactNode } from 'react'
+import { cx } from '../../internal/cx'
+import { useMessages } from '../../internal/provider'
+import { Button } from '../button/Button'
+import { StepList } from '../step-list/StepList'
+
+export interface WizardStep {
+  id: string
+  title: string
+  description?: string
+  icon?: ReactNode
+}
+
+export interface WizardPageProps {
+  /** Flow title; also names the StepList. */
+  title: string
+  subtitle?: string
+  eyebrow: string
+  icon: ReactNode
+  steps: WizardStep[]
+  currentIndex: number
+  onStepChange: (index: number) => void
+  onSubmit: () => void
+  onCancel: () => void
+  canAdvance?: boolean
+  submitting?: boolean
+  submitLabel?: string
+  aside?: ReactNode
+  /** When the step body is a form, the primary submits it (`form` = its id). */
+  form?: string
+  children?: ReactNode
+  className?: string
+}
+
+/** Moves focus to the heading whenever the step index changes after mount. */
+function useAnnounceStep(index: number, heading: React.RefObject<HTMLHeadingElement | null>) {
+  const shown = useRef(index)
+  useEffect(() => {
+    if (shown.current === index) return
+    shown.current = index
+    heading.current?.focus()
+  }, [index, heading])
+}
+
+/** Keeps the document title in step with the flow; restores it on unmount. */
+function useStepDocumentTitle(text: string) {
+  useEffect(() => {
+    if (typeof document === 'undefined') return
+    const before = document.title
+    document.title = text
+    return () => {
+      document.title = before
+    }
+  }, [text])
+}
+
+/** Full-page frame for a multi-step creation flow (spec: wave-2/wizard-page.md). */
+export function WizardPage(props: WizardPageProps) {
+  const copy = useMessages().wizardPage
+  const heading = useRef<HTMLHeadingElement>(null)
+  const last = props.steps.length - 1
+  const at = Math.min(Math.max(0, props.currentIndex), Math.max(0, last))
+  const step = props.steps[at]
+  const busy = props.submitting ?? false
+  const onFinal = at === last
+
+  useAnnounceStep(at, heading)
+  useStepDocumentTitle(step ? copy.documentTitle(step.title, props.title) : props.title)
+
+  const goBack = () => (at === 0 ? props.onCancel() : props.onStepChange(at - 1))
+  const goOn = () => (onFinal ? props.onSubmit() : props.onStepChange(at + 1))
+  const primaryText = onFinal ? (props.submitLabel ?? copy.submit) : copy.next
+
+  return (
+    <div className={cx('ty-wizard-page', props.className)} aria-busy={busy || undefined}>
+      <div className="ty-wizard-page__head">
+        <div className="ty-wizard-page__top">
+          <p className="ty-wizard-page__eyebrow">
+            <span aria-hidden="true" className="ty-wizard-page__eyebrow-icon">
+              {props.icon}
+            </span>
+            {props.eyebrow}
+          </p>
+          <Button variant="quiet" iconOnly shape="circle" accessibleLabel={copy.close} leadingIcon={<X />} onPress={props.onCancel} />
+        </div>
+        <h1 ref={heading} tabIndex={-1} className="ty-wizard-page__title">
+          {step?.title ?? props.title}
+        </h1>
+        {(step?.description ?? props.subtitle) ? <p className="ty-wizard-page__lead">{step?.description ?? props.subtitle}</p> : null}
+        {props.aside ? <div className="ty-wizard-page__aside">{props.aside}</div> : null}
+        <StepList
+          label={props.title}
+          currentIndex={at}
+          steps={props.steps.map((s) => ({ id: s.id, name: s.title, icon: s.icon }))}
+          onStepSelect={busy ? undefined : props.onStepChange}
+        />
+      </div>
+      <div className="ty-wizard-page__body" key={step?.id}>
+        {props.children}
+      </div>
+      <div className="ty-wizard-page__nav" role="group" aria-label={copy.actions}>
+        <Button onPress={goBack} disabled={busy}>
+          {at === 0 ? copy.cancel : copy.previous}
+        </Button>
+        <Button
+          variant="primary"
+          type={props.form ? 'submit' : 'button'}
+          form={props.form}
+          onPress={props.form ? undefined : goOn}
+          disabled={!(props.canAdvance ?? true) && !busy}
+          busy={busy}
+          busyLabel={copy.submitting}
+        >
+          {primaryText}
+        </Button>
+      </div>
+      <span role="status" className="ty-visually-hidden">
+        {busy ? copy.submitting : ''}
+      </span>
+    </div>
+  )
+}