@motion-proto/live-tokens 0.96.0 → 0.98.2

package/src/editor/ui/a11y/A11yPropertyMark.svelte

@@ -0,0 +1,84 @@
+<script lang="ts">
+  import { a11yPropertyFindings } from '../../core/a11y/a11yReport';
+  import UIInfoPopover from '../UIInfoPopover.svelte';
+  import A11yFindingRow from './A11yFindingRow.svelte';
+  import { accessibilityIssuesLabel, findingRows, reviewLabel } from './a11yView';
+
+  interface Props {
+    variables: string[];
+    /** `gutter` hangs the mark left of its nearest positioned ancestor, in the gap between a row's label and its control. */
+    placement?: 'inline' | 'gutter';
+  }
+
+  let { variables, placement = 'inline' }: Props = $props();
+
+  let findings = $derived([...new Set(variables.flatMap((variable) => $a11yPropertyFindings.get(variable) ?? []))]);
+  let review = $derived(findings.every((finding) => finding.rule === 'a11y-review'));
+  let label = $derived(review ? reviewLabel(findings.length) : accessibilityIssuesLabel(findings.length));
+  let rows = $derived(findingRows([
+    ...findings.filter((finding) => finding.rule !== 'a11y-review'),
+    ...findings.filter((finding) => finding.rule === 'a11y-review'),
+  ]));
+</script>
+
+{#if findings.length > 0}
+  <span class="a11y-property-mark" class:gutter={placement === 'gutter'}>
+    <UIInfoPopover title={label} ariaLabel={label}>
+      {#snippet trigger()}
+        {#if review}
+          <span class="a11y-property-mark-glyph review" aria-hidden="true"></span>
+        {:else}
+          <i class="fa-solid fa-triangle-exclamation a11y-property-mark-glyph" aria-hidden="true"></i>
+        {/if}
+      {/snippet}
+      <ul class="a11y-property-findings">
+        {#each rows as row, i (i)}
+          <A11yFindingRow component={row.finding.component ?? ''} {row} review={row.finding.rule === 'a11y-review'} />
+        {/each}
+      </ul>
+    </UIInfoPopover>
+  </span>
+{/if}
+
+<style>
+  .a11y-property-mark {
+    display: inline-flex;
+    align-items: center;
+    margin-left: var(--ui-space-4);
+    line-height: 1;
+  }
+
+  /* No transform: it would make this span the containing block of the
+     popover, which positions itself against the viewport. */
+  .a11y-property-mark.gutter {
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    right: 100%;
+    margin: 0 var(--ui-space-2) 0 0;
+  }
+
+  .a11y-property-mark-glyph {
+    color: var(--ui-highlight);
+    font-size: var(--ui-font-size-xs);
+  }
+
+  /* The "?" is generated content because the contract harness matches rows by their text. */
+  .a11y-property-mark-glyph.review::after {
+    content: '?';
+    color: var(--ui-text-tertiary);
+    font-size: var(--ui-font-size-sm);
+    font-weight: var(--ui-font-weight-bold);
+  }
+
+  .a11y-property-findings {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  /* The popover spaces its own paragraphs, which would double the row's gaps. */
+  .a11y-property-findings :global(.a11y-issue p) {
+    margin: 0;
+  }
+</style>

package/src/editor/ui/a11y/A11yRailMark.svelte

@@ -0,0 +1,34 @@
+<script lang="ts">
+  interface Props {
+    /** `corner` overlaps the icon of a condensed rail, where the label and its inline mark are hidden. */
+    placement?: 'inline' | 'corner';
+  }
+
+  let { placement = 'inline' }: Props = $props();
+  const label = 'Accessibility issues';
+</script>
+
+{#if placement === 'inline'}
+  <i class="fa-solid fa-triangle-exclamation a11y-rail-mark" role="img" aria-label={label} title={label}></i>
+{:else}
+  <i class="fa-solid fa-triangle-exclamation a11y-rail-mark corner" aria-hidden="true"></i>
+{/if}
+
+<style>
+  .a11y-rail-mark {
+    margin-right: var(--ui-space-6);
+    color: var(--ui-highlight);
+    font-size: var(--ui-font-size-sm);
+  }
+
+  /* Bottom-right of the icon, clear of the unsaved dot at its top-right. */
+  .corner {
+    position: absolute;
+    top: 50%;
+    left: 30px;
+    margin: 0;
+    font-size: var(--ui-font-size-xs);
+    text-shadow: 0 0 2px black;
+    pointer-events: none;
+  }
+</style>

package/src/editor/ui/a11y/AccessibilityTab.svelte

@@ -0,0 +1,334 @@
+<script lang="ts">
+  import { a11yFinishedReport, a11yIssues, a11yReport, startA11yRun } from '../../core/a11y/a11yReport';
+  import { contrastFailures } from '../../core/a11y/contrastFailures';
+  import { allContrastPairs } from '../../core/components/contrastPairRegistry';
+  import { createDomResolver } from '../../core/palettes/resolveColor';
+  import { unsavedEdits } from '../../core/store/unsavedEdits';
+  import { listThemes } from '../../core/themes/themeService';
+  import UIPillButton from '../UIPillButton.svelte';
+  import A11yComponentIssues from './A11yComponentIssues.svelte';
+  import A11yFindingRow from './A11yFindingRow.svelte';
+  import A11yOverview from './A11yOverview.svelte';
+  import {
+    A11Y_REVIEW_SECTION,
+    A11Y_RUN_SECTION,
+    a11ySectionId,
+    codeSpans,
+    componentsWithIssues,
+    formatElapsed,
+    formatRunTime,
+    getA11yViewLink,
+    issuesLabel,
+    openComponentAt,
+    reviewLabel,
+    reviewResults,
+  } from './a11yView';
+
+  const openView = getA11yViewLink();
+
+  let rows = $derived(componentsWithIssues($a11yIssues));
+  let review = $derived(reviewResults($a11yIssues));
+  let reviewTotal = $derived(rows.reduce((sum, row) => sum + row.issues.review.length, 0));
+  let running = $derived($a11yReport?.state === 'running' ? $a11yReport : null);
+  let failed = $derived($a11yReport?.state === 'failed' ? $a11yReport : null);
+  let finished = $derived($a11yFinishedReport);
+  let runProblems = $derived(finished?.findings.filter((f) => f.rule.startsWith('tests-')) ?? []);
+  let notInstalled = $derived(runProblems.some((f) => f.rule === 'tests-not-installed'));
+
+  /** Set by a press while edits were pending; the alert shows only while they still are. */
+  let blockedByEdits = $state(false);
+  let startError: string | null = $state(null);
+  let starting = $state(false);
+
+  let now = $state(Date.now());
+  $effect(() => {
+    if (!running) return;
+    now = Date.now();
+    const timer = setInterval(() => (now = Date.now()), 1000);
+    return () => clearInterval(timer);
+  });
+
+  let themeNames: Record<string, string> = $state({});
+  let themeName = $derived(finished?.theme ? (themeNames[finished.theme] ?? finished.theme) : null);
+  $effect(() => {
+    if (!finished?.theme) return;
+    listThemes()
+      .then((themes) => (themeNames = Object.fromEntries(themes.map((t) => [t.fileName, t.name]))))
+      .catch(() => {});
+  });
+
+  async function runTest() {
+    startError = null;
+    if ($unsavedEdits) {
+      blockedByEdits = true;
+      return;
+    }
+    blockedByEdits = false;
+    starting = true;
+    try {
+      await startA11yRun(contrastFailures(allContrastPairs(), createDomResolver()));
+    } catch (err) {
+      const { code, message } = err as Error & { code?: string };
+      startError = code === 'A11Y_RUN_IN_PROGRESS' ? 'A test is already running.' : message;
+    } finally {
+      starting = false;
+    }
+  }
+</script>
+
+{#snippet message(text: string)}
+  {#each codeSpans(text) as part, i (i)}{#if part.code}<code>{part.text}</code>{:else}{part.text}{/if}{/each}
+{/snippet}
+
+<div class="a11y-tab">
+  <section id={A11Y_RUN_SECTION} class="a11y-run">
+    <header class="a11y-head">
+      <h2 class="a11y-title">Accessibility</h2>
+      <UIPillButton
+        variant="primary"
+        icon="fa-play"
+        disabled={notInstalled || running !== null || starting}
+        onclick={runTest}
+      >Run test</UIPillButton>
+    </header>
+
+    {#if blockedByEdits && $unsavedEdits}
+      <p class="a11y-alert" role="alert">Save the changes you want to have checked.</p>
+    {/if}
+    {#if startError}
+      <p class="a11y-alert" role="alert">{startError}</p>
+    {/if}
+
+    {#if running}
+      <p class="a11y-status" role="status">Test running, {formatElapsed(now - Date.parse(running.startedAt))}</p>
+    {/if}
+    {#if failed}
+      <div class="a11y-failed">
+        <p class="a11y-status">The run of {formatRunTime(failed.startedAt)} failed.</p>
+        <details class="a11y-disclosure">
+          <summary>Error</summary>
+          <pre class="a11y-error">{failed.error}</pre>
+        </details>
+      </div>
+    {/if}
+
+    {#if finished}
+      <p class="a11y-status">
+        Last run {formatRunTime(finished.finishedAt)}{#if themeName}, theme {themeName}{/if}
+      </p>
+      {#if runProblems.length > 0}
+        <ul class="a11y-problems">
+          {#each runProblems as problem, i (i)}
+            <li>{@render message(problem.message)}</li>
+          {/each}
+        </ul>
+        {#if notInstalled}
+          <div class="a11y-recheck">
+            <UIPillButton size="compact" variant="outline" icon="fa-rotate-right" onclick={runTest}>Check again</UIPillButton>
+          </div>
+        {/if}
+      {/if}
+      {#if !notInstalled && rows.length === 0}
+        <p class="a11y-summary">Every component passes the automated checks.</p>
+      {/if}
+    {:else if !running && !failed}
+      <div class="a11y-empty">
+        <p>
+          Run test checks every component in the open theme as saved. It scans each one with axe and Alfa,
+          presses the keys each one answers, and measures the contrast of every color pair.
+        </p>
+        <p>A run takes about three minutes. The report stays here until the next run.</p>
+      </div>
+    {/if}
+  </section>
+
+  {#if rows.length > 0}
+    <A11yOverview {rows} onjump={(component) => openView?.(a11ySectionId(component))} />
+  {/if}
+
+  {#each rows as row (row.component)}
+    <section id={a11ySectionId(row.component)} class="editor-section-card a11y-component">
+      <header class="a11y-component-head">
+        <i class={row.icon} aria-hidden="true"></i>
+        <h3 class="editor-subsection-title">{row.label}</h3>
+        <span class="a11y-count">{issuesLabel(row.count)}</span>
+        <UIPillButton
+          size="compact"
+          variant="outline"
+          icon="fa-arrow-right"
+          title={`Open ${row.label} in the Components view`}
+          onclick={() => openComponentAt(row.component)}
+        >Open component</UIPillButton>
+      </header>
+      <A11yComponentIssues
+        component={row.component}
+        issues={row.issues}
+        onreveal={(variable) => openComponentAt(row.component, variable)}
+        onopen={() => openComponentAt(row.component)}
+      />
+      {#if row.issues.review.length > 0}
+        <button type="button" class="a11y-review-link" onclick={() => openView?.(A11Y_REVIEW_SECTION)}>
+          {reviewLabel(row.issues.review.length)}
+        </button>
+      {/if}
+    </section>
+  {/each}
+
+  {#if review.length > 0}
+    <section id={A11Y_REVIEW_SECTION} class="a11y-review">
+      <details class="a11y-disclosure">
+        <summary>{reviewLabel(reviewTotal)}</summary>
+        <ul class="a11y-review-list">
+          {#each review as { component, label, row }, i (i)}
+            <A11yFindingRow
+              {component}
+              {row}
+              review
+              prefix={label}
+              onreveal={(variable) => openComponentAt(component, variable)}
+              onopen={() => openComponentAt(component)}
+            />
+          {/each}
+        </ul>
+      </details>
+    </section>
+  {/if}
+</div>
+
+<style>
+  .a11y-tab {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ui-space-20);
+    font-size: var(--ui-font-size-md);
+    color: var(--ui-text-secondary);
+  }
+
+  .a11y-run {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ui-space-8);
+  }
+
+  .a11y-head {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--ui-space-12);
+    /* Clears an overlay scrollbar and lines the button up with the cards' own buttons. */
+    padding-right: var(--ui-space-20);
+  }
+
+  .a11y-title {
+    margin: 0;
+    font-size: var(--ui-font-size-2xl);
+    font-weight: var(--ui-font-weight-semibold);
+    color: var(--ui-text-primary);
+  }
+
+  .a11y-alert,
+  .a11y-status,
+  .a11y-summary,
+  .a11y-empty p {
+    margin: 0;
+  }
+
+  .a11y-alert {
+    color: var(--ui-highlight);
+  }
+
+  .a11y-summary {
+    color: var(--ui-text-primary);
+    font-weight: var(--ui-font-weight-semibold);
+  }
+
+  .a11y-empty {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ui-space-8);
+  }
+
+  .a11y-problems {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ui-space-4);
+    margin: 0;
+    padding-left: var(--ui-space-20);
+    color: var(--ui-text-primary);
+  }
+
+  .a11y-recheck {
+    display: flex;
+  }
+
+  .a11y-failed {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ui-space-4);
+  }
+
+  .a11y-disclosure summary {
+    cursor: pointer;
+    color: var(--ui-text-primary);
+  }
+
+  .a11y-error {
+    margin: var(--ui-space-8) 0 0;
+    padding: var(--ui-space-12);
+    overflow-x: auto;
+    background: var(--ui-surface-low);
+    border: 1px solid var(--ui-border-low);
+    border-radius: var(--ui-radius-md);
+    font-family: var(--ui-font-mono);
+    font-size: var(--ui-font-size-xs);
+    white-space: pre-wrap;
+  }
+
+  .a11y-component {
+    gap: var(--ui-space-12);
+  }
+
+  .a11y-component-head {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--ui-space-8) var(--ui-space-12);
+    color: var(--ui-text-primary);
+  }
+
+  .a11y-count {
+    font-size: var(--ui-font-size-sm);
+    color: var(--ui-text-tertiary);
+  }
+
+  .a11y-component-head :global(.ui-pill) {
+    margin-left: auto;
+  }
+
+  .a11y-review-link {
+    align-self: flex-start;
+    padding: 0;
+    background: none;
+    border: none;
+    font-size: var(--ui-font-size-sm);
+    color: var(--ui-text-tertiary);
+    text-decoration: underline;
+    text-underline-offset: 2px;
+    cursor: pointer;
+  }
+
+  .a11y-review-link:hover {
+    color: var(--ui-text-primary);
+  }
+
+  .a11y-review-list {
+    margin: var(--ui-space-8) 0 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .a11y-tab code {
+    font-family: var(--ui-font-mono);
+    font-size: var(--ui-font-size-sm);
+  }
+</style>

package/src/editor/ui/a11y/a11yView.ts

@@ -0,0 +1,218 @@
+import { getContext, setContext } from 'svelte';
+import { writable } from 'svelte/store';
+import { getComponentRegistry, getComponentRegistryEntries } from '../../component-editor/registry';
+import { selectedComponent, setEditorView } from '../../core/store/editorViewStore';
+import type { ComponentA11yIssues } from '../../core/a11y/a11yReport';
+import type { A11yFinding } from '../../core/a11y/a11yReportTypes';
+
+export const A11Y_RUN_SECTION = 'a11y-run';
+export const A11Y_REVIEW_SECTION = 'a11y-review';
+
+export function a11ySectionId(component: string): string {
+  return `a11y-component-${component}`;
+}
+
+const VIEW_LINK = Symbol('a11y-view-link');
+
+/** Set by the editor shell, which hosts the Accessibility view. The standalone component page hosts none. */
+export function setA11yViewLink(open: (sectionId: string) => void): void {
+  setContext(VIEW_LINK, open);
+}
+
+export function getA11yViewLink(): ((sectionId: string) => void) | undefined {
+  return getContext(VIEW_LINK);
+}
+
+export interface A11yRevealTarget {
+  component: string;
+  /** The property row to scroll to. Null scrolls to the component's issues panel. */
+  variable: string | null;
+}
+
+/** One-shot: where the component page scrolls once it opens. The issues panel of that component clears it. */
+export const pendingA11yReveal = writable<A11yRevealTarget | null>(null);
+
+export function openComponentAt(component: string, variable: string | null = null): void {
+  pendingA11yReveal.set({ component, variable });
+  selectedComponent.set(component);
+  setEditorView('components');
+}
+
+export function componentLabel(component: string): string {
+  return getComponentRegistry()[component]?.label ?? component;
+}
+
+/** The success criteria the suite's own checks link to by their Understanding page. */
+const UNDERSTANDING_CRITERIA: Record<string, string> = {
+  'non-text-contrast': '1.4.11',
+  'text-spacing': '1.4.12',
+};
+
+/** Names the kind of page a finding's help URL opens, so the link says where it goes.
+ *  axe and Alfa link to their own rule pages; the suite's own checks link to WCAG and the APG. */
+export function guidanceLabel(url: string): string {
+  const { hostname, pathname } = new URL(url);
+  if (hostname === 'www.w3.org') {
+    const understanding = pathname.match(/\/Understanding\/([a-z-]+)\.html$/);
+    if (understanding) {
+      const criterion = UNDERSTANDING_CRITERIA[understanding[1]];
+      return criterion ? `Success criterion ${criterion}` : 'Success criterion';
+    }
+    if (pathname.includes('/Techniques/')) return 'Technique';
+    if (pathname.includes('/ARIA/apg/')) return 'Pattern';
+  }
+  if (hostname === 'playwright.dev') return 'Reference';
+  return 'Rule';
+}
+
+export interface A11yIssueTotals {
+  property: number;
+  code: number;
+  review: number;
+}
+
+/** A component's findings counted by the fix they need, as the view groups them. */
+export function issueTotals(issues: ComponentA11yIssues): A11yIssueTotals {
+  return {
+    property: issues.contrast.length + issues.property.length,
+    code: issues.code.length,
+    review: issues.review.length,
+  };
+}
+
+export function accessibilityIssuesLabel(count: number): string {
+  return `${count} accessibility ${count === 1 ? 'issue' : 'issues'}`;
+}
+
+export function reviewLabel(count: number): string {
+  return `${count} ${count === 1 ? 'result' : 'results'} to check by eye`;
+}
+
+/** Every finding of the run counts, results to check by eye included (decision 6). */
+export function issueCount(issues: ComponentA11yIssues): number {
+  return issues.contrast.length + issues.property.length + issues.code.length + issues.review.length;
+}
+
+/** One panel row: the findings that share an engine rule, a help text and the properties they trace to. */
+export interface A11yFindingRow {
+  finding: A11yFinding;
+  targets: string[];
+  views: string;
+  variables: string[];
+}
+
+const VIEW_LIMIT = 4;
+const MORE_VIEWS = /^and \d+ more$/;
+
+/** The views of several findings, once each, in the order they first
+ *  appear. A finding lists four views and counts the rest, so the merged list
+ *  cannot count what it drops and says "and more". */
+function mergeViews(views: (string | undefined)[]): string {
+  const named: string[] = [];
+  let hidden = false;
+  for (const view of views) {
+    for (const part of view ? view.split('; ') : []) {
+      if (MORE_VIEWS.test(part)) hidden = true;
+      else if (!named.includes(part)) named.push(part);
+    }
+  }
+  const shown = named.slice(0, VIEW_LIMIT);
+  return hidden || named.length > shown.length ? [...shown, 'and more'].join('; ') : shown.join('; ');
+}
+
+/** Findings that share an engine rule, a help text and their traced properties merge into one row (decision 6). */
+export function findingRows(findings: A11yFinding[]): A11yFindingRow[] {
+  const rows = new Map<string, A11yFinding[]>();
+  for (const finding of findings) {
+    const key = finding.details
+      ? [finding.rule, finding.details.engineRule, finding.details.help, ...(finding.details.variables ?? [])].join('\n')
+      : finding.message;
+    rows.set(key, [...(rows.get(key) ?? []), finding]);
+  }
+  return [...rows.values()].map((group) => ({
+    finding: group[0],
+    targets: [...new Set(group.flatMap((f) => (f.details ? [f.details.target] : [])))],
+    views: group.length === 1 ? (group[0].details?.view ?? '') : mergeViews(group.map((f) => f.details?.view)),
+    variables: group[0].details?.variables ?? [],
+  }));
+}
+
+/** A finding's own words. A keyboard case's engine rule is the case's own name, which the help alone leaves out. */
+export function findingText(finding: A11yFinding): string {
+  if (!finding.details) return finding.message;
+  return finding.rule === 'a11y-keyboard' ? `${finding.details.engineRule}: ${finding.details.help}` : finding.details.help;
+}
+
+export function elementsLabel(count: number): string {
+  return `${count} ${count === 1 ? 'element' : 'elements'}`;
+}
+
+export function issuesLabel(count: number): string {
+  return `${count} ${count === 1 ? 'issue' : 'issues'}`;
+}
+
+export interface A11yComponentRow {
+  component: string;
+  label: string;
+  icon: string;
+  count: number;
+  issues: ComponentA11yIssues;
+}
+
+/** Every registered component with a finding, in the component rail's order. */
+export function componentsWithIssues(all: Record<string, ComponentA11yIssues>): A11yComponentRow[] {
+  return getComponentRegistryEntries().flatMap(({ id, label, icon }) => {
+    const issues = all[id];
+    const count = issues ? issueCount(issues) : 0;
+    return count > 0 ? [{ component: id, label, icon, count, issues }] : [];
+  });
+}
+
+/** Every result to check by eye, merged into rows per component, in the rail's order. */
+export function reviewResults(all: Record<string, ComponentA11yIssues>): { component: string; label: string; row: A11yFindingRow }[] {
+  return getComponentRegistryEntries().flatMap(({ id, label }) =>
+    findingRows(all[id]?.review ?? []).map((row) => ({ component: id, label, row })),
+  );
+}
+
+/** The words of `variable` after the component's prefix that `label` lacks,
+ *  such as "focused" for `--input-focused-border` and "border color". Rows in
+ *  different variants and states share a label, so these words tell them apart. */
+function qualifier(component: string, variable: string, label: string): string {
+  const prefix = `--${component}-`;
+  if (!variable.startsWith(prefix)) return '';
+  const own = new Set(label.split(/[\s-]+/));
+  return variable.slice(prefix.length).split('-').filter((word) => !own.has(word)).join(' ');
+}
+
+/** The label of the property row that sets `variable`, led by its variant and
+ *  state words, with its first letter raised. An intrinsic has no schema row,
+ *  so its key names it. */
+export function propertyLabel(component: string, variable: string): string | null {
+  const entry = getComponentRegistry()[component];
+  const token = entry?.schema.find((t) => t.variable === variable);
+  const label = token
+    ? [qualifier(component, variable, token.label), token.label].filter(Boolean).join(' ')
+    : entry?.intrinsics?.find((spec) => spec.variants.some((v) => spec.variable(v) === variable))?.key.replaceAll('-', ' ');
+  return label ? label.charAt(0).toUpperCase() + label.slice(1) : null;
+}
+
+/** A message split on its backticks, so a command or a variable renders as code. */
+export function codeSpans(message: string): { text: string; code: boolean }[] {
+  return message.split('`').map((text, i) => ({ text, code: i % 2 === 1 })).filter((part) => part.text);
+}
+
+const pad = (n: number) => String(n).padStart(2, '0');
+
+/** "14:02" for a time today, "22 Oct 14:02" for any other day. */
+export function formatRunTime(iso: string, now: Date = new Date()): string {
+  const at = new Date(iso);
+  const clock = `${pad(at.getHours())}:${pad(at.getMinutes())}`;
+  if (at.toDateString() === now.toDateString()) return clock;
+  return `${at.toLocaleDateString(undefined, { day: 'numeric', month: 'short' })} ${clock}`;
+}
+
+export function formatElapsed(ms: number): string {
+  const seconds = Math.max(0, Math.floor(ms / 1000));
+  return `${Math.floor(seconds / 60)}:${pad(seconds % 60)}`;
+}