@datatechsolutions/tympan 0.3.0 → 0.4.0

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>
+  )
+}

package/src/elements/action-menu/definition.ts

@@ -0,0 +1,123 @@
+import type { ElementDefinition, ElementNode } from '../definition.ts'
+
+/** A lucide glyph (ISC, THIRD_PARTY_NOTICES): every child carries a class so the element's patch pass can match it. */
+const glyph = (tag: string, attrs: Record<string, string>): ElementNode => ({
+  tag,
+  class: 'ty-action-menu__glyph',
+  attrs: Object.fromEntries(Object.entries(attrs).map(([name, value]) => [name, { value }])),
+})
+
+/** The built-in trigger's ellipsis (lucide strokes), used only in trigger mode when the trigger slot is empty. */
+const ellipsisIcon: ElementNode = {
+  tag: 'svg',
+  class: 'ty-icon',
+  attrs: {
+    viewBox: { value: '0 0 24 24' },
+    fill: { value: 'none' },
+    stroke: { value: 'currentColor' },
+    'stroke-width': { value: '2' },
+    'stroke-linecap': { value: 'round' },
+    'stroke-linejoin': { value: 'round' },
+    'aria-hidden': { value: 'true' },
+    focusable: { value: 'false' },
+  },
+  children: [
+    glyph('circle', { cx: '12', cy: '12', r: '1' }),
+    glyph('circle', { cx: '19', cy: '12', r: '1' }),
+    glyph('circle', { cx: '5', cy: '12', r: '1' }),
+  ],
+}
+
+/**
+ * `<ty-action-menu>`: the ActionMenu's single source (spec: wave-1/action-menu.md).
+ *
+ * The entries are data (`items`, JSON), which the declarative anatomy cannot
+ * express (no dynamic repetition), so — as the skeleton composes its presets
+ * — the element composes the item rows into the anatomy's empty
+ * `.ty-action-menu__menu` on upgrade. Examples therefore stay closed: an open
+ * example would render its rows only after the element runs, and the parity
+ * renderers could not produce them.
+ */
+export const actionMenuDefinition = {
+  tag: 'ty-action-menu',
+  name: 'TyActionMenu',
+  kind: 'enhancing',
+  doc: 'A list of commands opened from a trigger button (mode `trigger`, the APG Menu Button pattern) or at a pointer position over a target (mode `context`: secondary click, Shift+F10, the ContextMenu key, or a long press on touch). Opening moves focus to the first enabled item (ArrowUp from the trigger: the last); ArrowDown/ArrowUp move with wrapping, Home/End jump, typing a character moves to the next enabled item starting with it, Enter/Space activate, Escape closes and returns focus to the origin, Tab and an outside press close. Disabled items are skipped and announced as disabled. In context mode the surface is clamped so it never overflows the viewport. Visibility is controlled: the element asks with `ty-open-change`, the host flips `open`.',
+  props: {
+    open: { type: 'boolean', attribute: 'open', doc: 'Shown (controlled). The anatomy stays mounted but `hidden` while closed, so nothing reaches the accessibility tree.' },
+    mode: { type: 'enum', values: ['trigger', 'context'], default: 'trigger', attribute: 'mode', doc: '`trigger`: opens from the trigger button; `context`: opens at a viewport point over the trigger slot\'s target.' },
+    label: { type: 'string', attribute: 'label', doc: 'Accessible name of the menu (required by the spec).' },
+    triggerLabel: { type: 'string', default: 'More actions', attribute: 'trigger-label', doc: 'Accessible name of the built-in icon-only trigger (the React messages.moreActions default), used in trigger mode when the trigger slot is empty.' },
+    items: { type: 'string', attribute: 'items', doc: 'JSON array of entries in order: an item `{ id, label, icon?, iconPath?, tone?, disabled?, shortcut? }` (`icon` a decorative text glyph; `iconPath` an SVG icon as 24×24 path data rendered in the standard icon frame — when both are present `iconPath` wins, and subpaths separated by " | " become one `<path>` each; `tone` "danger" marks a destructive command, `shortcut` a displayed hint only), `{ "type": "separator" }`, or `{ "type": "section", "id", "title", "items": [...] }`. The element composes the rows on upgrade.' },
+    position: { type: 'string', attribute: 'position', doc: 'Context mode: the viewport point the menu opens at, "x,y" in CSS pixels (controlled); the last context-request point when unset. Clamped so the menu stays inside the viewport.' },
+  },
+  events: [
+    { type: 'ty-action', kind: 'custom', detail: { id: 'string' }, reactProp: 'onAction', doc: 'An item was activated (pointer, Enter or Space); the element then asks to close. A disabled item never fires.' },
+    { type: 'ty-open-change', kind: 'custom', detail: { open: 'boolean' }, reactProp: 'onOpenChange', doc: 'The element asks the host to change visibility — `open: true` on a trigger activation or a context request (secondary click, Shift+F10, the ContextMenu key, a long press), `open: false` on Escape, Tab, an outside press or after an action. Controlled: the element does not toggle itself; the host flips `open`.' },
+  ],
+  slots: {
+    trigger: { doc: 'Trigger mode: the host\'s own toggle — any single focusable element, wired with aria-haspopup="menu" and aria-expanded. Context mode: the target that receives the context request (secondary click, Shift+F10, long press). Empty in trigger mode: the built-in ellipsis button named by `triggerLabel`.' },
+  },
+  anatomy: {
+    tag: 'span',
+    class: 'ty-action-menu__target',
+    attrs: { 'data-mode': { prop: 'mode' } },
+    children: [
+      // The built-in trigger (only in trigger mode, only when the trigger
+      // slot is empty): a quiet, icon-only button with the ellipsis glyph —
+      // exactly the chrome ActionMenu.tsx composes.
+      {
+        tag: 'button',
+        class: 'ty-button ty-action-menu__trigger',
+        when: ['!slot:trigger', 'mode:trigger'],
+        attrs: {
+          type: { value: 'button' },
+          'aria-label': { prop: 'triggerLabel' },
+          'aria-haspopup': { value: 'menu' },
+          'data-variant': { value: 'quiet' },
+          'data-icon-only': { value: '' },
+        },
+        children: [
+          {
+            tag: 'span',
+            class: 'ty-button__icon',
+            attrs: { 'aria-hidden': { value: 'true' } },
+            children: [ellipsisIcon],
+          },
+        ],
+      },
+      { slot: 'trigger', when: ['slot:trigger'] },
+      {
+        tag: 'div',
+        class: 'ty-action-menu',
+        // Always rendered (a framework's closed menu has an anatomy to
+        // find); `hidden` while closed, so nothing reaches the tree.
+        attrs: {
+          hidden: { value: '', when: ['!open'] },
+          'data-mode': { prop: 'mode' },
+        },
+        children: [
+          // Rendered empty: the element composes the item rows from the
+          // `items` JSON on upgrade (the anatomy cannot repeat).
+          {
+            tag: 'div',
+            class: 'ty-action-menu__menu',
+            attrs: {
+              id: { idref: 'menu' },
+              role: { value: 'menu' },
+              'aria-label': { prop: 'label' },
+              'aria-orientation': { value: 'vertical' },
+              tabindex: { value: '-1' },
+            },
+          },
+        ],
+      },
+    ],
+  },
+  examples: [
+    { name: 'closed', props: { label: 'Item actions' }, slots: {} },
+    { name: 'own-trigger', props: { label: 'Run actions' }, slots: { trigger: 'More' } },
+    { name: 'context', props: { mode: 'context', label: 'File actions' }, slots: { trigger: 'report.csv' } },
+    { name: 'translated', props: { label: 'Ações do item', triggerLabel: 'Mais ações' }, slots: {} },
+  ],
+} as const satisfies ElementDefinition