@puredesktop/puredesktop-ui-bridge 1.0.0-beta.1

package/src/components/accessibility/AccessibilityReviewDialog.tsx

@@ -0,0 +1,350 @@
+import { useEffect, useMemo, useState } from 'react'
+import { styled } from 'styled-components'
+import { Button } from '../common/buttons/Button.js'
+import { CleanButton } from '../common/buttons/CleanButton.js'
+import { InlineBanner } from '../common/feedback/InlineBanner.js'
+import { TextAreaField } from '../common/inputs/TextAreaField.js'
+import { Modal } from '../common/overlays/Modal.js'
+import { Text } from '../common/typography/Text.js'
+import {
+  annotateAccessibilityIssue,
+  applyAccessibilityIssueDraft,
+  applyAccessibilityIssueFix,
+  auditHtmlAccessibility,
+  getAccessibilityIssueDraft,
+  type AccessibilityIssue,
+  type AccessibilityIssueDraft,
+  type AccessibilityIssueSeverity,
+} from './accessibilityReview.js'
+
+export interface AccessibilityReviewDialogProps {
+  open: boolean
+  html: string
+  title?: string
+  onClose: () => void
+  onChange: (html: string) => void
+  onSelectIssue?: (issue: AccessibilityIssue) => void
+}
+
+const severityLabel: Record<AccessibilityIssueSeverity, string> = {
+  error: 'Needs attention',
+  warning: 'Check',
+  notice: 'Note',
+}
+
+const StyledIntro = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding-bottom: var(--platform-spacing-sm);
+  border-bottom: 1px solid var(--platform-colors-border);
+`
+
+const StyledSummary = styled.div`
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  color: var(--platform-colors-text-secondary);
+  font-size: var(--platform-typography-font-size-sm);
+`
+
+const StyledQueue = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: var(--platform-spacing-sm);
+  min-height: 0;
+  overflow: auto;
+  padding-top: var(--platform-spacing-sm);
+`
+
+const StyledIssue = styled.article`
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  gap: var(--platform-spacing-md);
+  padding: var(--platform-spacing-sm) 0;
+  border-bottom: 1px solid rgb(from var(--platform-colors-border) r g b / 0.7);
+
+  &:last-child {
+    border-bottom: 0;
+  }
+`
+
+const StyledIssueMain = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  min-width: 0;
+`
+
+const StyledIssueSelect = styled(CleanButton)`
+  display: flex;
+  width: 100%;
+  flex-direction: column;
+  align-items: stretch;
+  gap: 4px;
+  padding: 0;
+  color: inherit;
+  text-align: left;
+
+  &:hover {
+    background: rgb(from var(--platform-colors-surface-hover) r g b / 0.55);
+  }
+`
+
+const StyledIssueMeta = styled.div`
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  color: var(--platform-colors-text-secondary);
+  font-size: var(--platform-typography-font-size-xs);
+`
+
+const StyledIssueActions = styled.div`
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+`
+
+const StyledDraft = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  margin-top: var(--platform-spacing-xs);
+  padding: var(--platform-spacing-sm);
+  border-left: 2px solid var(--platform-colors-border-strong);
+  background: rgb(from var(--platform-colors-surface-subtle) r g b / 0.6);
+`
+
+const StyledDraftActions = styled.div`
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+`
+
+const StyledBody = styled.div`
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  max-height: min(560px, calc(100dvh - 180px));
+`
+
+function countBySeverity(
+  issues: AccessibilityIssue[],
+  severity: AccessibilityIssueSeverity,
+): number {
+  return issues.filter(issue => issue.severity === severity).length
+}
+
+function IssueRow({
+  issue,
+  draft,
+  onApply,
+  onApplyDraft,
+  onAnnotate,
+  onDismiss,
+  onSelect,
+}: {
+  issue: AccessibilityIssue
+  draft: AccessibilityIssueDraft | null
+  onApply: (issue: AccessibilityIssue) => void
+  onApplyDraft: (issue: AccessibilityIssue, value: string) => void
+  onAnnotate: (issue: AccessibilityIssue) => void
+  onDismiss: (issue: AccessibilityIssue) => void
+  onSelect?: (issue: AccessibilityIssue) => void
+}): React.ReactElement {
+  const [editingDraft, setEditingDraft] = useState(false)
+  const [draftValue, setDraftValue] = useState(draft?.value ?? '')
+
+  useEffect(() => {
+    setEditingDraft(false)
+    setDraftValue(draft?.value ?? '')
+  }, [draft?.value, issue.id])
+
+  return (
+    <StyledIssue>
+      <StyledIssueMain>
+        <StyledIssueSelect
+          type="button"
+          aria-label={`Show ${issue.title}`}
+          onClick={() => onSelect?.(issue)}
+        >
+          <Text as="h3" size="base" weight="medium">
+            {issue.title}
+          </Text>
+          <Text as="p" size="sm" tone="secondary">
+            {issue.detail}
+          </Text>
+          <StyledIssueMeta>
+            <span>{severityLabel[issue.severity]}</span>
+            <span>{issue.category}</span>
+            <span>{issue.targetLabel}</span>
+            <span>
+              {issue.standard} {issue.wcag.join(', ')}
+            </span>
+          </StyledIssueMeta>
+        </StyledIssueSelect>
+        {editingDraft && draft ? (
+          <StyledDraft
+            onClick={event => event.stopPropagation()}
+            onKeyDown={event => event.stopPropagation()}
+          >
+            <Text as="p" size="sm" tone="secondary">
+              {draft.label}. {draft.description}
+            </Text>
+            <TextAreaField
+              value={draftValue}
+              rows={3}
+              aria-label={draft.label}
+              onChange={event => setDraftValue(event.target.value)}
+            />
+            <StyledDraftActions>
+              <Button
+                type="button"
+                variant="text"
+                size="sm"
+                onClick={() => setEditingDraft(false)}
+              >
+                Cancel
+              </Button>
+              <Button
+                type="button"
+                variant="primary"
+                size="sm"
+                onClick={() => onApplyDraft(issue, draftValue)}
+              >
+                {draft.applyLabel}
+              </Button>
+            </StyledDraftActions>
+          </StyledDraft>
+        ) : null}
+      </StyledIssueMain>
+      <StyledIssueActions>
+        {draft ? (
+          <Button
+            type="button"
+            variant="text"
+            size="sm"
+            onClick={event => {
+              event.stopPropagation()
+              setEditingDraft(true)
+            }}
+          >
+            Draft fix
+          </Button>
+        ) : null}
+        {issue.fix ? (
+          <Button
+            type="button"
+            variant="text"
+            size="sm"
+            onClick={event => {
+              event.stopPropagation()
+              onApply(issue)
+            }}
+          >
+            Apply fix
+          </Button>
+        ) : null}
+        <Button
+          type="button"
+          variant="text"
+          size="sm"
+          onClick={event => {
+            event.stopPropagation()
+            onAnnotate(issue)
+          }}
+        >
+          Annotate
+        </Button>
+        <Button
+          type="button"
+          variant="text"
+          size="sm"
+          onClick={event => {
+            event.stopPropagation()
+            onDismiss(issue)
+          }}
+        >
+          Ignore
+        </Button>
+      </StyledIssueActions>
+    </StyledIssue>
+  )
+}
+
+export function AccessibilityReviewDialog({
+  open,
+  html,
+  title = 'Accessibility review',
+  onClose,
+  onChange,
+  onSelectIssue,
+}: AccessibilityReviewDialogProps): React.ReactElement | null {
+  const [dismissed, setDismissed] = useState<Set<string>>(() => new Set())
+  const issues = useMemo(() => auditHtmlAccessibility(html), [html])
+  const visibleIssues = useMemo(
+    () => issues.filter(issue => !dismissed.has(issue.id)),
+    [dismissed, issues],
+  )
+
+  useEffect(() => {
+    setDismissed(new Set())
+  }, [html])
+
+  const applyAndDismiss = (issue: AccessibilityIssue, nextHtml: string): void => {
+    onChange(nextHtml)
+    setDismissed(current => new Set(current).add(issue.id))
+  }
+
+  return (
+    <Modal open={open} onClose={onClose} title={title} size="lg" chrome>
+      <StyledBody>
+        <StyledIntro>
+          <Text as="p" size="sm" tone="secondary">
+            First-pass chapter checks for structure, images, captions, tables,
+            links, and media. This finds review work; it does not certify the
+            chapter.
+          </Text>
+          <StyledSummary aria-live="polite">
+            <span>{issues.length} findings</span>
+            <span>{countBySeverity(issues, 'error')} need attention</span>
+            <span>{countBySeverity(issues, 'warning')} checks</span>
+          </StyledSummary>
+        </StyledIntro>
+        {issues.length === 0 ? (
+          <InlineBanner>
+            No chapter-level accessibility findings in this pass.
+          </InlineBanner>
+        ) : visibleIssues.length === 0 ? (
+          <InlineBanner>All findings in this queue are handled or ignored.</InlineBanner>
+        ) : (
+          <StyledQueue>
+            {visibleIssues.map(issue => (
+              <IssueRow
+                key={issue.id}
+                issue={issue}
+                draft={getAccessibilityIssueDraft(html, issue)}
+                onApply={item =>
+                  applyAndDismiss(item, applyAccessibilityIssueFix(html, item))
+                }
+                onApplyDraft={(item, value) =>
+                  applyAndDismiss(
+                    item,
+                    applyAccessibilityIssueDraft(html, item, value),
+                  )
+                }
+                onAnnotate={item =>
+                  applyAndDismiss(item, annotateAccessibilityIssue(html, item))
+                }
+                onDismiss={item =>
+                  setDismissed(current => new Set(current).add(item.id))
+                }
+                onSelect={onSelectIssue}
+              />
+            ))}
+          </StyledQueue>
+        )}
+      </StyledBody>
+    </Modal>
+  )
+}

package/src/components/accessibility/accessibilityReview.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest'
+import {
+  annotateAccessibilityIssue,
+  applyAccessibilityIssueDraft,
+  applyAccessibilityIssueFix,
+  auditHtmlAccessibility,
+  getAccessibilityIssueDraft,
+} from './accessibilityReview.js'
+
+describe('auditHtmlAccessibility', () => {
+  it('finds chapter-level image, table, heading, link, and media issues', () => {
+    const issues = auditHtmlAccessibility(`
+      <h2>Methods</h2>
+      <h4>Skipped heading</h4>
+      <figure><img src="chart.png"></figure>
+      <table><tr><td>Name</td><td>Value</td></tr></table>
+      <p><a href="/x">click here</a></p>
+      <video src="demo.mp4"></video>
+    `)
+
+    expect(issues.map(issue => issue.ruleId)).toEqual(
+      expect.arrayContaining([
+        'heading-level-jump',
+        'image-missing-alt',
+        'figure-missing-caption',
+        'table-missing-caption',
+        'table-no-headers',
+        'link-ambiguous-label',
+        'media-missing-captions',
+      ]),
+    )
+  })
+})
+
+describe('applyAccessibilityIssueFix', () => {
+  it('applies safe table fixes', () => {
+    const html = '<table><tr><td>Name</td><td>Value</td></tr></table>'
+    const issue = auditHtmlAccessibility(html).find(
+      finding => finding.ruleId === 'table-no-headers',
+    )
+    expect(issue).toBeTruthy()
+
+    const fixed = applyAccessibilityIssueFix(html, issue!)
+    expect(fixed).toContain('<th scope="col">Name</th>')
+    expect(fixed).toContain('<th scope="col">Value</th>')
+  })
+
+  it('can annotate a finding with shared comment markup', () => {
+    const html = '<p><a href="/x">click here</a></p>'
+    const issue = auditHtmlAccessibility(html)[0]
+    const annotated = annotateAccessibilityIssue(html, issue)
+
+    expect(annotated).toContain('comment-mark')
+    expect(annotated).toContain('data-comment-type="agent-review"')
+    expect(annotated).toContain(issue.title)
+  })
+})
+
+describe('accessibility draft fixes', () => {
+  it('drafts image alt text from nearby figure captions', () => {
+    const html = '<figure><img src="chart.png"><figcaption>Revenue by quarter</figcaption></figure>'
+    const issue = auditHtmlAccessibility(html).find(
+      finding => finding.ruleId === 'image-missing-alt',
+    )
+    expect(issue).toBeTruthy()
+
+    const draft = getAccessibilityIssueDraft(html, issue!)
+    expect(draft?.value).toBe('Revenue by quarter')
+
+    const fixed = applyAccessibilityIssueDraft(html, issue!, 'Quarterly revenue trend')
+    expect(fixed).toContain('alt="Quarterly revenue trend"')
+  })
+
+  it('drafts table captions from header-like first rows', () => {
+    const html = '<table><tr><td>Name</td><td>Value</td></tr><tr><td>A</td><td>2</td></tr></table>'
+    const issue = auditHtmlAccessibility(html).find(
+      finding => finding.ruleId === 'table-missing-caption',
+    )
+    expect(issue).toBeTruthy()
+
+    const draft = getAccessibilityIssueDraft(html, issue!)
+    expect(draft?.value).toBe('Table of Name, Value')
+
+    const fixed = applyAccessibilityIssueDraft(html, issue!, 'Sample values')
+    expect(fixed).toContain('<caption>Sample values</caption>')
+  })
+
+  it('drafts clearer link labels from the destination', () => {
+    const html = '<p><a href="https://example.com/research-notes">click here</a></p>'
+    const issue = auditHtmlAccessibility(html).find(
+      finding => finding.ruleId === 'link-ambiguous-label',
+    )
+    expect(issue).toBeTruthy()
+
+    const draft = getAccessibilityIssueDraft(html, issue!)
+    expect(draft?.value).toBe('research notes')
+
+    const fixed = applyAccessibilityIssueDraft(html, issue!, 'research notes')
+    expect(fixed).toContain('>research notes</a>')
+  })
+})