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

package/src/components/accessibility/accessibilityReview.ts

@@ -0,0 +1,639 @@
+export type AccessibilityIssueSeverity = 'error' | 'warning' | 'notice'
+
+export type AccessibilityIssueCategory =
+  | 'content'
+  | 'headings'
+  | 'images'
+  | 'captions'
+  | 'tables'
+  | 'links'
+  | 'media'
+  | 'structure'
+
+export interface AccessibilityIssueFix {
+  label: string
+  description: string
+  action:
+    | 'set-empty-alt'
+    | 'use-caption-as-alt'
+    | 'add-figure-caption'
+    | 'add-table-caption'
+    | 'promote-first-row-headers'
+    | 'add-video-captions-track'
+    | 'remove-empty-heading'
+}
+
+export interface AccessibilityIssue {
+  id: string
+  ruleId: string
+  category: AccessibilityIssueCategory
+  severity: AccessibilityIssueSeverity
+  title: string
+  detail: string
+  target: string
+  targetLabel: string
+  wcag: string[]
+  standard: string
+  fix?: AccessibilityIssueFix
+}
+
+export interface AccessibilityIssueDraft {
+  label: string
+  description: string
+  value: string
+  applyLabel: string
+}
+
+const ISSUE_AUTHOR = 'Pure accessibility review'
+
+function parseHtml(html: string): Document {
+  return new DOMParser().parseFromString(`<main>${html}</main>`, 'text/html')
+}
+
+function serializeHtml(document: Document): string {
+  return document.body.querySelector('main')?.innerHTML ?? ''
+}
+
+function textOf(element: Element | null | undefined): string {
+  return (element?.textContent ?? '').replace(/\s+/g, ' ').trim()
+}
+
+function elementLabel(element: Element): string {
+  const tag = element.tagName.toLowerCase()
+  if (tag === 'img') {
+    return element.getAttribute('alt')?.trim() || 'image'
+  }
+  if (tag === 'table') {
+    return textOf(element.querySelector('caption')) || 'table'
+  }
+  return textOf(element).slice(0, 80) || tag
+}
+
+function nthOfType(element: Element): number {
+  let index = 1
+  let sibling = element.previousElementSibling
+  while (sibling) {
+    if (sibling.tagName === element.tagName) index += 1
+    sibling = sibling.previousElementSibling
+  }
+  return index
+}
+
+function selectorFor(element: Element): string {
+  const parts: string[] = []
+  let current: Element | null = element
+  while (current && current.tagName.toLowerCase() !== 'main') {
+    const tag = current.tagName.toLowerCase()
+    parts.unshift(`${tag}:nth-of-type(${nthOfType(current)})`)
+    current = current.parentElement
+  }
+  return parts.join(' > ')
+}
+
+function issueId(ruleId: string, target: string): string {
+  return `${ruleId}:${target}`
+}
+
+function pushIssue(
+  issues: AccessibilityIssue[],
+  input: Omit<AccessibilityIssue, 'id' | 'standard'>,
+): void {
+  issues.push({
+    ...input,
+    id: issueId(input.ruleId, input.target),
+    standard: 'WCAG 2.2',
+  })
+}
+
+function closestCaptionText(element: Element): string {
+  const figure = element.closest('figure')
+  return textOf(figure?.querySelector('figcaption'))
+}
+
+function clipDraft(input: string, maxLength = 140): string {
+  const text = input.replace(/\s+/g, ' ').trim()
+  if (text.length <= maxLength) return text
+  return `${text.slice(0, maxLength - 1).trim()}…`
+}
+
+function humanizePathPart(value: string): string {
+  const withoutQuery = value.split(/[?#]/)[0] ?? ''
+  const lastPart = withoutQuery.split('/').filter(Boolean).pop() ?? ''
+  const withoutExtension = lastPart.replace(/\.[a-z0-9]+$/i, '')
+  return withoutExtension
+    .replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+function readableLinkDestination(href: string): string {
+  try {
+    const url = new URL(href, 'https://example.test')
+    const pathLabel = humanizePathPart(url.pathname)
+    if (pathLabel) return clipDraft(pathLabel, 80)
+    return url.hostname.replace(/^www\./, '')
+  } catch {
+    return clipDraft(humanizePathPart(href) || href, 80)
+  }
+}
+
+function nearbySentence(element: Element): string {
+  const candidates = [
+    element.previousElementSibling,
+    element.nextElementSibling,
+    element.parentElement?.previousElementSibling,
+    element.parentElement?.nextElementSibling,
+    element.closest('p'),
+  ]
+  for (const candidate of candidates) {
+    const text = textOf(candidate)
+    if (text) return clipDraft(text)
+  }
+  return ''
+}
+
+function tableCaptionDraft(table: Element): string {
+  const headers = Array.from(table.querySelectorAll('th'))
+    .map(header => textOf(header))
+    .filter(Boolean)
+  if (headers.length > 0) {
+    return clipDraft(`Table of ${headers.slice(0, 4).join(', ')}`)
+  }
+
+  const firstRowCells = Array.from(table.querySelectorAll('tr:first-child > *'))
+    .map(cell => textOf(cell))
+    .filter(Boolean)
+  if (firstRowCells.length > 0) {
+    return clipDraft(`Table of ${firstRowCells.slice(0, 4).join(', ')}`)
+  }
+
+  return nearbySentence(table) || 'Table summary'
+}
+
+function imageAltDraft(image: Element): string {
+  const caption = closestCaptionText(image)
+  if (caption) return clipDraft(caption)
+
+  const src = image.getAttribute('src') ?? ''
+  const sourceLabel = humanizePathPart(src)
+  if (sourceLabel) return clipDraft(sourceLabel, 100)
+
+  return nearbySentence(image) || 'Image description'
+}
+
+function figureCaptionDraft(figure: Element): string {
+  const image = figure.querySelector('img')
+  const alt = image?.getAttribute('alt')?.trim()
+  if (alt) return clipDraft(alt)
+
+  const sourceLabel = image ? humanizePathPart(image.getAttribute('src') ?? '') : ''
+  if (sourceLabel) return clipDraft(sourceLabel, 100)
+
+  return nearbySentence(figure) || 'Figure summary'
+}
+
+function hasAccessibleName(element: Element): boolean {
+  return Boolean(
+    element.getAttribute('aria-label')?.trim() ||
+      element.getAttribute('aria-labelledby')?.trim() ||
+      textOf(element),
+  )
+}
+
+export function auditHtmlAccessibility(html: string): AccessibilityIssue[] {
+  const document = parseHtml(html)
+  const main = document.body.querySelector('main')
+  if (!main) return []
+
+  const issues: AccessibilityIssue[] = []
+
+  const headings = Array.from(
+    main.querySelectorAll('h1,h2,h3,h4,h5,h6'),
+  ) as HTMLElement[]
+  let previousLevel = 0
+  for (const heading of headings) {
+    const target = selectorFor(heading)
+    const level = Number(heading.tagName.slice(1))
+    if (!textOf(heading)) {
+      pushIssue(issues, {
+        ruleId: 'empty-heading',
+        category: 'headings',
+        severity: 'error',
+        title: 'Empty heading',
+        detail:
+          'Headings need visible text so readers and assistive technology can understand the structure.',
+        target,
+        targetLabel: heading.tagName.toLowerCase(),
+        wcag: ['1.3.1 Info and Relationships', '2.4.6 Headings and Labels'],
+        fix: {
+          label: 'Remove heading',
+          description: 'Remove the empty heading element.',
+          action: 'remove-empty-heading',
+        },
+      })
+    }
+    if (previousLevel > 0 && level > previousLevel + 1) {
+      pushIssue(issues, {
+        ruleId: 'heading-level-jump',
+        category: 'headings',
+        severity: 'warning',
+        title: 'Heading level jumps',
+        detail: `This heading moves from h${previousLevel} to h${level}. Check whether the outline skips a section.`,
+        target,
+        targetLabel: textOf(heading) || heading.tagName.toLowerCase(),
+        wcag: ['1.3.1 Info and Relationships', '2.4.6 Headings and Labels'],
+      })
+    }
+    if (textOf(heading)) previousLevel = level
+  }
+
+  for (const image of Array.from(main.querySelectorAll('img'))) {
+    const target = selectorFor(image)
+    const hasAlt = image.hasAttribute('alt')
+    const alt = image.getAttribute('alt')?.trim() ?? ''
+    const caption = closestCaptionText(image)
+    if (!hasAlt) {
+      pushIssue(issues, {
+        ruleId: 'image-missing-alt',
+        category: 'images',
+        severity: 'error',
+        title: 'Image needs alt text or a decorative mark',
+        detail:
+          'Images need an accessible text alternative, unless they are purely decorative.',
+        target,
+        targetLabel: elementLabel(image),
+        wcag: ['1.1.1 Non-text Content'],
+        fix: {
+          label: 'Mark decorative',
+          description:
+            'Set alt="" so assistive technology can ignore the image.',
+          action: 'set-empty-alt',
+        },
+      })
+    } else if (alt && caption && alt.toLowerCase() === caption.toLowerCase()) {
+      pushIssue(issues, {
+        ruleId: 'image-alt-duplicates-caption',
+        category: 'images',
+        severity: 'notice',
+        title: 'Alt text repeats the caption',
+        detail:
+          'If the caption already explains the figure, the alt text may need a shorter functional description.',
+        target,
+        targetLabel: alt,
+        wcag: ['1.1.1 Non-text Content'],
+      })
+    }
+  }
+
+  for (const figure of Array.from(main.querySelectorAll('figure'))) {
+    if (!figure.querySelector('img,svg,canvas,pre[data-type="mermaid"]')) {
+      continue
+    }
+    const target = selectorFor(figure)
+    if (!textOf(figure.querySelector('figcaption'))) {
+      pushIssue(issues, {
+        ruleId: 'figure-missing-caption',
+        category: 'captions',
+        severity: 'warning',
+        title: 'Figure needs a caption',
+        detail:
+          'Figures should have captions when the image contributes to the argument or instructions.',
+        target,
+        targetLabel: elementLabel(figure),
+        wcag: ['1.1.1 Non-text Content', '1.3.1 Info and Relationships'],
+      })
+    }
+  }
+
+  for (const table of Array.from(main.querySelectorAll('table'))) {
+    const target = selectorFor(table)
+    if (!textOf(table.querySelector('caption'))) {
+      pushIssue(issues, {
+        ruleId: 'table-missing-caption',
+        category: 'tables',
+        severity: 'warning',
+        title: 'Table needs a caption',
+        detail:
+          'A caption gives the table a clear accessible name and helps readers understand its purpose.',
+        target,
+        targetLabel: elementLabel(table),
+        wcag: ['1.3.1 Info and Relationships'],
+      })
+    }
+    if (!table.querySelector('th')) {
+      pushIssue(issues, {
+        ruleId: 'table-no-headers',
+        category: 'tables',
+        severity: 'error',
+        title: 'Table has no header cells',
+        detail:
+          'Tables need header cells so row and column relationships are available to assistive technology.',
+        target,
+        targetLabel: elementLabel(table),
+        wcag: ['1.3.1 Info and Relationships'],
+        fix: {
+          label: 'Use first row as headers',
+          description: 'Convert the first row cells to column headers.',
+          action: 'promote-first-row-headers',
+        },
+      })
+    }
+  }
+
+  for (const link of Array.from(main.querySelectorAll('a'))) {
+    const target = selectorFor(link)
+    const label = textOf(link)
+    if (!link.getAttribute('href')?.trim()) {
+      pushIssue(issues, {
+        ruleId: 'link-missing-target',
+        category: 'links',
+        severity: 'error',
+        title: 'Link has no destination',
+        detail: 'Links need a destination or should be plain text.',
+        target,
+        targetLabel: label || 'link',
+        wcag: ['2.4.4 Link Purpose (In Context)'],
+      })
+    }
+    if (!hasAccessibleName(link)) {
+      pushIssue(issues, {
+        ruleId: 'link-empty-label',
+        category: 'links',
+        severity: 'error',
+        title: 'Link has no readable text',
+        detail:
+          'The link needs text or an accessible label that explains where it goes.',
+        target,
+        targetLabel: 'link',
+        wcag: ['2.4.4 Link Purpose (In Context)', '4.1.2 Name, Role, Value'],
+      })
+    } else if (/^(click here|here|read more|more)$/i.test(label)) {
+      pushIssue(issues, {
+        ruleId: 'link-ambiguous-label',
+        category: 'links',
+        severity: 'warning',
+        title: 'Link text is ambiguous',
+        detail:
+          'Link text should make sense out of context, especially in screen reader link lists.',
+        target,
+        targetLabel: label,
+        wcag: ['2.4.4 Link Purpose (In Context)'],
+      })
+    }
+  }
+
+  for (const media of Array.from(main.querySelectorAll('video,audio'))) {
+    const target = selectorFor(media)
+    if (!media.querySelector('track[kind="captions"],track[kind="subtitles"]')) {
+      pushIssue(issues, {
+        ruleId: 'media-missing-captions',
+        category: 'media',
+        severity: 'warning',
+        title: 'Media needs captions or a transcript',
+        detail:
+          'Audio and video should include captions, subtitles, or a nearby transcript.',
+        target,
+        targetLabel: media.tagName.toLowerCase(),
+        wcag: ['1.2.1 Audio-only and Video-only', '1.2.2 Captions'],
+        fix:
+          media.tagName.toLowerCase() === 'video'
+            ? {
+                label: 'Add captions track placeholder',
+                description: 'Insert a captions track placeholder.',
+                action: 'add-video-captions-track',
+              }
+            : undefined,
+      })
+    }
+  }
+
+  for (const iframe of Array.from(main.querySelectorAll('iframe'))) {
+    const target = selectorFor(iframe)
+    if (!iframe.getAttribute('title')?.trim()) {
+      pushIssue(issues, {
+        ruleId: 'frame-missing-title',
+        category: 'structure',
+        severity: 'error',
+        title: 'Embedded frame needs a title',
+        detail:
+          'Frames need titles so assistive technology can identify embedded content.',
+        target,
+        targetLabel: 'iframe',
+        wcag: ['4.1.2 Name, Role, Value'],
+      })
+    }
+  }
+
+  return issues
+}
+
+function findTarget(document: Document, issue: AccessibilityIssue): Element | null {
+  const main = document.body.querySelector('main')
+  return issue.target ? main?.querySelector(issue.target) ?? null : null
+}
+
+export function applyAccessibilityIssueFix(
+  html: string,
+  issue: AccessibilityIssue,
+): string {
+  if (!issue.fix) return html
+  const document = parseHtml(html)
+  const target = findTarget(document, issue)
+  if (!target) return html
+
+  switch (issue.fix.action) {
+    case 'set-empty-alt':
+      if (target instanceof HTMLImageElement) target.alt = ''
+      else target.setAttribute('alt', '')
+      break
+    case 'use-caption-as-alt': {
+      const caption = closestCaptionText(target)
+      if (caption) target.setAttribute('alt', caption)
+      break
+    }
+    case 'add-figure-caption': {
+      if (!target.querySelector('figcaption')) {
+        const caption = document.createElement('figcaption')
+        caption.textContent = 'Describe this figure.'
+        target.append(caption)
+      }
+      break
+    }
+    case 'add-table-caption': {
+      if (!target.querySelector('caption')) {
+        const caption = document.createElement('caption')
+        caption.textContent = 'Describe this table.'
+        target.prepend(caption)
+      }
+      break
+    }
+    case 'promote-first-row-headers': {
+      const firstRow = target.querySelector('tr')
+      if (firstRow) {
+        for (const cell of Array.from(firstRow.children)) {
+          if (cell.tagName.toLowerCase() !== 'td') continue
+          const header = document.createElement('th')
+          header.setAttribute('scope', 'col')
+          header.innerHTML = cell.innerHTML
+          for (const attr of Array.from(cell.attributes)) {
+            if (attr.name !== 'scope') header.setAttribute(attr.name, attr.value)
+          }
+          cell.replaceWith(header)
+        }
+      }
+      break
+    }
+    case 'add-video-captions-track': {
+      const track = document.createElement('track')
+      track.setAttribute('kind', 'captions')
+      track.setAttribute('src', '')
+      track.setAttribute('srclang', 'en')
+      track.setAttribute('label', 'English captions')
+      target.append(track)
+      break
+    }
+    case 'remove-empty-heading':
+      target.remove()
+      break
+  }
+
+  return serializeHtml(document)
+}
+
+export function getAccessibilityIssueDraft(
+  html: string,
+  issue: AccessibilityIssue,
+): AccessibilityIssueDraft | null {
+  const document = parseHtml(html)
+  const target = findTarget(document, issue)
+  if (!target) return null
+
+  switch (issue.ruleId) {
+    case 'image-missing-alt':
+      return {
+        label: 'Alt text',
+        description:
+          'A short description for readers who cannot see the image.',
+        value: imageAltDraft(target),
+        applyLabel: 'Use alt text',
+      }
+    case 'figure-missing-caption':
+      return {
+        label: 'Caption',
+        description: 'A visible caption that explains why this figure is here.',
+        value: figureCaptionDraft(target),
+        applyLabel: 'Add caption',
+      }
+    case 'table-missing-caption':
+      return {
+        label: 'Caption',
+        description: 'A brief table title for readers and assistive technology.',
+        value: tableCaptionDraft(target),
+        applyLabel: 'Add caption',
+      }
+    case 'link-empty-label':
+    case 'link-ambiguous-label': {
+      const href = target.getAttribute('href')?.trim() ?? ''
+      return {
+        label: 'Link text',
+        description: 'Text that still makes sense when read by itself.',
+        value: readableLinkDestination(href) || nearbySentence(target),
+        applyLabel: 'Use link text',
+      }
+    }
+    case 'frame-missing-title': {
+      const src = target.getAttribute('src')?.trim() ?? ''
+      return {
+        label: 'Frame title',
+        description: 'A short name for the embedded content.',
+        value: readableLinkDestination(src) || 'Embedded content',
+        applyLabel: 'Use title',
+      }
+    }
+    default:
+      return null
+  }
+}
+
+export function applyAccessibilityIssueDraft(
+  html: string,
+  issue: AccessibilityIssue,
+  value: string,
+): string {
+  const text = value.replace(/\s+/g, ' ').trim()
+  if (!text) return html
+
+  const document = parseHtml(html)
+  const target = findTarget(document, issue)
+  if (!target) return html
+
+  switch (issue.ruleId) {
+    case 'image-missing-alt':
+      target.setAttribute('alt', text)
+      break
+    case 'figure-missing-caption': {
+      let caption = target.querySelector('figcaption')
+      if (!caption) {
+        caption = document.createElement('figcaption')
+        target.append(caption)
+      }
+      caption.textContent = text
+      break
+    }
+    case 'table-missing-caption': {
+      let caption = target.querySelector('caption')
+      if (!caption) {
+        caption = document.createElement('caption')
+        target.prepend(caption)
+      }
+      caption.textContent = text
+      break
+    }
+    case 'link-empty-label':
+    case 'link-ambiguous-label':
+      target.textContent = text
+      break
+    case 'frame-missing-title':
+      target.setAttribute('title', text)
+      break
+    default:
+      return html
+  }
+
+  return serializeHtml(document)
+}
+
+function createCommentId(): string {
+  if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
+    return `accessibility-${crypto.randomUUID()}`
+  }
+  return `accessibility-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+}
+
+export function annotateAccessibilityIssue(
+  html: string,
+  issue: AccessibilityIssue,
+): string {
+  const document = parseHtml(html)
+  const target = findTarget(document, issue)
+  if (!target) return html
+
+  const classes = new Set(
+    (target.getAttribute('class') ?? '').split(/\s+/).filter(Boolean),
+  )
+  classes.add('comment-mark')
+  classes.add('comment-mark--agent-review')
+  target.setAttribute('class', Array.from(classes).join(' '))
+  target.setAttribute('data-comment-id', createCommentId())
+  target.setAttribute('data-comment-type', 'agent-review')
+  target.setAttribute(
+    'data-comment-text',
+    `${issue.title}: ${issue.detail} (${issue.standard} ${issue.wcag.join(', ')})`,
+  )
+  target.setAttribute('data-comment-author', ISSUE_AUTHOR)
+  target.setAttribute('data-comment-created-at', new Date().toISOString())
+  target.setAttribute('data-comment-replies', '[]')
+  target.setAttribute('title', `${ISSUE_AUTHOR}: ${issue.title}`)
+
+  return serializeHtml(document)
+}

package/src/components/accessibility/index.ts

@@ -0,0 +1,16 @@
+export {
+  AccessibilityReviewDialog,
+  type AccessibilityReviewDialogProps,
+} from './AccessibilityReviewDialog.js'
+export {
+  annotateAccessibilityIssue,
+  applyAccessibilityIssueDraft,
+  applyAccessibilityIssueFix,
+  auditHtmlAccessibility,
+  getAccessibilityIssueDraft,
+  type AccessibilityIssue,
+  type AccessibilityIssueCategory,
+  type AccessibilityIssueDraft,
+  type AccessibilityIssueFix,
+  type AccessibilityIssueSeverity,
+} from './accessibilityReview.js'