# UI library examples

These task workspaces use real component libraries to exercise geometry, portals,
scrolling, overlays, hit testing, and dynamic layout. The hosted pages run in a
browser; their repository tests run the same workflows in happy-dom with DOM
Layout Shim attached.

## Current compatibility findings

Agreement measures how often the shim matches Chromium across three equally
weighted comparisons: geometry fields within 1 px, visibility state, and the
element receiving a center-point hit test. A checkpoint percentage averages
those three comparisons; overall agreement averages all checkpoints.
Observation coverage is the share of declared elements captured in both
environments. Differences are recorded for inspection and are not failures.

## Material UI

Overall agreement: 87.09%. Coverage: 100%.
Measured with Chromium 151.0.7922.34 at 1280 × 720.

[Full checkpoint results and discrepancies](./examples/material-ui/compatibility-report.json)

The example uses ordinary Material UI components. DOM Layout Shim is attached
only in the happy-dom test environment; no adapter or production application
change is required.

#### 1. Use happy-dom in Vitest

```ts title="vitest.config.ts" source="https://github.com/BenjaBobs/dom-layout-shim/blob/main/examples/material-ui/vitest.config.ts#L2" start="2" lines="2-11"
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    // Give React a DOM-like window that the layout shim can patch.
    environment: 'happy-dom',
    include: ['test/**/*.test.tsx'],
    setupFiles: ['./test/setup.ts'],
  },
});
```

```ts title="test/setup.ts" source="https://github.com/BenjaBobs/dom-layout-shim/blob/main/examples/material-ui/test/setup.ts#L2" start="2" lines="2-31"

import { readFile } from 'node:fs/promises';
import { resolve } from 'node:path';
import {
  attachLayoutEngine,
  createUnsupportedCssReporter,
} from 'dom-layout-shim';

// Tell React that state updates are intentionally coordinated with `act()`.
Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });

// Vitest transforms CSS imports without reliably installing their rules in
// happy-dom, so expose the same authored stylesheet that the browser app loads.
const exampleStyles = await readFile(
  resolve(process.cwd(), 'src/styles.css'),
  'utf8',
);
const style = window.document.createElement('style');
style.textContent = exampleStyles;
window.document.head.append(style);

// Attach once with shared defaults; tests can override only what they exercise.
export const unsupportedCssReporter = createUnsupportedCssReporter();
export const layoutEngine = await attachLayoutEngine({
  window,
  unsupportedCss: {
    default: 'warn',
    onWarning: unsupportedCssReporter.onWarning,
  },
});
```

#### 2. Render React normally

```tsx title="test/task-workspace.test.tsx" source="https://github.com/BenjaBobs/dom-layout-shim/blob/main/examples/material-ui/test/task-workspace.test.tsx#L51" start="51" lines="51-54"
// Mount the real Material UI tree exactly as the consumer test uses it.
document.body.innerHTML = '<div id="app"></div>';
reactRoot = createRoot(requiredElement('#app'));
await act(async () => reactRoot.render(<TaskWorkspace />));
```

#### 3. Click where the element is

```ts title="test/click-where-element-is.ts" source="https://github.com/BenjaBobs/dom-layout-shim/blob/main/examples/material-ui/test/click-where-element-is.ts#L2" start="2" lines="2-22"
export function clickWhereElementIs(element: HTMLElement): void {
  const rect = element.getBoundingClientRect();
  const x = rect.left + rect.width / 2;
  const y = rect.top + rect.height / 2;
  const hitTarget = element.ownerDocument.elementFromPoint(x, y);

  if (!hitTarget || (hitTarget !== element && !element.contains(hitTarget))) {
    throw new Error(
      `Expected ${element.tagName.toLowerCase()} to receive the click at (${x}, ${y})`,
    );
  }

  hitTarget.dispatchEvent(
    new MouseEvent('click', {
      bubbles: true,
      cancelable: true,
      clientX: x,
      clientY: y,
    }),
  );
}
```

The utility measures the element's center, asks the document which element owns
that point, and refuses to click through an overlay. It dispatches the event to
the actual hit target so descendants behave like a coordinate-based browser
click. Call it inside React's `act()` to synchronize resulting state updates.

The example ignores unsupported declarations because Material UI emits many
visual-only rules. Use the default warning policy, or narrow overrides, when
unsupported declarations should remain visible in your own suite.

#### 4. Assert the reachable element

```ts title="test/task-workspace.test.tsx" source="https://github.com/BenjaBobs/dom-layout-shim/blob/main/examples/material-ui/test/task-workspace.test.tsx#L112" start="112" lines="112-123"
const underlyingControl = requiredElement<HTMLElement>(
  '[data-layout-key="underlying-control"]',
);
const rect = underlyingControl.getBoundingClientRect();
// Query the visual center instead of bypassing layout with `.click()`.
const point = {
  x: rect.left + rect.width / 2,
  y: rect.top + rect.height / 2,
};

expect(rect.width).toBeGreaterThan(0);
expect(document.elementFromPoint(point.x, point.y)).toBe(underlyingControl);
```

The same approach works for Material UI portals: open the real menu or dialog,
then query geometry and hit targets through normal DOM APIs.


## Ant Design

Overall agreement: 91.45%. Coverage: 100%.
Measured with Chromium 151.0.7922.34 at 1280 × 720.

[Full checkpoint results and discrepancies](./examples/ant-design/compatibility-report.json)

The example mounts real Ant Design components and portals. DOM Layout Shim is a
test-only layout engine; the application does not import it or use an Ant-specific
adapter.

#### 1. Configure happy-dom and React tests

```ts title="vitest.config.ts" source="https://github.com/BenjaBobs/dom-layout-shim/blob/main/examples/ant-design/vitest.config.ts#L2" start="2" lines="2-14"
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    // Give React a DOM-like window that the layout shim can patch.
    environment: 'happy-dom',
    include: ['test/**/*.test.tsx'],
    setupFiles: ['./test/setup.ts'],
    // Real Ant Design observer and animation phases can exceed Vitest's 5s
    // default on slower CI runners while still settling normally in auto mode.
    testTimeout: 10_000,
  },
});
```

```ts title="test/setup.ts" source="https://github.com/BenjaBobs/dom-layout-shim/blob/main/examples/ant-design/test/setup.ts#L2" start="2" lines="2-33"

import { readFile } from 'node:fs/promises';
import { resolve } from 'node:path';
import {
  attachLayoutEngine,
  createUnsupportedCssReporter,
} from 'dom-layout-shim';

// Tell React that state updates are intentionally coordinated with `act()`.
Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });

// Vitest transforms CSS imports without adding them to happy-dom, so install the
// example's authored stylesheet before the layout engine reads computed styles.
const exampleStyles = await readFile(
  resolve(process.cwd(), 'src/styles.css'),
  'utf8',
);
const style = window.document.createElement('style');
style.textContent = exampleStyles;
window.document.head.append(style);

// Attach once with shared defaults; tests can override only what they exercise.
export const unsupportedCssReporter = createUnsupportedCssReporter();
export const layoutEngine = await attachLayoutEngine({
  window,
  // Exercise the default automatic observer delivery used by consumers. Parsed
  // stylesheet rules are reused across Ant Design's observer-driven DOM phases.
  unsupportedCss: {
    default: 'warn',
    onWarning: unsupportedCssReporter.onWarning,
  },
});
```

#### 2. Mount the application normally

```tsx title="test/task-workspace.test.tsx" source="https://github.com/BenjaBobs/dom-layout-shim/blob/main/examples/ant-design/test/task-workspace.test.tsx#L13" start="13" lines="13-20"
// Mount the real Ant Design tree, including its normal portal behavior.
document.body.innerHTML = '<main id="app"></main>';
const container = document.querySelector('#app');
if (!container) throw new Error('Missing example application root');
await act(async () => {
  root = mountTaskWorkspace(container);
  await nextAnimationFrame();
});
```

#### 3. Click where the element is

```ts title="test/click-where-element-is.ts" source="https://github.com/BenjaBobs/dom-layout-shim/blob/main/examples/ant-design/test/click-where-element-is.ts#L2" start="2" lines="2-22"
export function clickWhereElementIs(element: HTMLElement): void {
  const rect = element.getBoundingClientRect();
  const x = rect.left + rect.width / 2;
  const y = rect.top + rect.height / 2;
  const hitTarget = element.ownerDocument.elementFromPoint(x, y);

  if (!hitTarget || (hitTarget !== element && !element.contains(hitTarget))) {
    throw new Error(
      `Expected ${element.tagName.toLowerCase()} to receive the click at (${x}, ${y})`,
    );
  }

  hitTarget.dispatchEvent(
    new MouseEvent('click', {
      bubbles: true,
      cancelable: true,
      clientX: x,
      clientY: y,
    }),
  );
}
```

The utility measures the element's center, asks the document which element owns
that point, and refuses to click through an overlay. It dispatches the event to
the actual hit target so descendants behave like a coordinate-based browser
click. Call it inside React's `act()` to synchronize resulting state updates.

The example ignores unsupported declarations because Ant Design emits many
visual-only rules. Use the default warning policy, or narrow overrides, when
unsupported declarations should remain visible in your own suite.

#### 4. Use geometry-aware assertions

Before opening the modal:

```ts title="test/task-workspace.test.tsx" source="https://github.com/BenjaBobs/dom-layout-shim/blob/main/examples/ant-design/test/task-workspace.test.tsx#L47" start="47" lines="47-48"
// This helper clicks the geometry-derived center rather than bypassing layout.
expectReceivesPointer(addTask);
```

After opening the real Ant Design modal:

```ts title="test/task-workspace.test.tsx" source="https://github.com/BenjaBobs/dom-layout-shim/blob/main/examples/ant-design/test/task-workspace.test.tsx#L77" start="77" lines="77-79"
// Ant Design places its full-screen interaction wrapper above the visual mask.
// Verify that this real modal layer wins the same point while the modal is open.
expectBlockedBy(addTask, modalWrap);
```

The helpers derive interaction points from element geometry, so the test checks
whether overlays actually cover or expose a control instead of bypassing layout
with a direct `.click()`.


These summaries are generated by running the same scripted interaction in
Chromium and happy-dom with DOM Layout Shim. Agreement is observational rather
than a pass threshold: expand any checkpoint to inspect its recorded geometry,
visibility, or hit-testing differences.