Box Tree API Level 1

1. Introduction

The layout stage of CSS is responsible for generating the position and size of a document’s content. During this process, each DOM element produces potentially many boxes, each of which in turn produce potentially many fragments.

This specification describes an API that gives developers access to geometry, text and other information about boxes and fragments.

2. Boxes and Fragments

The [css-display-3] specification describes the relationship between elements, boxes, and fragments.

Elements and pseudo-elements generate zero or more fragments, each of which generates a fragment tree.

Fragments do not in general form a tree that maps cleanly back to the DOM. When an element generates multiple fragment trees, the element that generates a least common ancestor can be arbitrarily far up the DOM tree.

<style>
p::first-line { color: green; }

p::first-letter { color: red; }
</style>
<p>foo <i>bar baz</i></p>

Boxes are not explicitly exposed by this API.

3. API

[Exposed=Window]
interface DeadFragmentInformation {
  readonly attribute Node node;
  readonly attribute double width;
  readonly attribute double height;
  readonly attribute double top;
  readonly attribute double left;
  readonly attribute boolean isOverflowed;
  readonly attribute FrozenArray<DeadFragmentInformation>? children;
  readonly attribute DeadFragmentInformation? nextSibling;
  readonly attribute DeadFragmentInformation? previousSibling;
  readonly attribute DeadFragmentInformation? nextInBox;
  readonly attribute DeadFragmentInformation? previousInBox;
};

enum FragmentFilter {
  "direct-fragments-only",
  "fragment-hierarchy"
};

partial interface Element {
  Promise<DeadFragmentInformation> getFragmentInformation(FragmentFilter filter);
};

partial interface Document {
  void layoutNow();
};