Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/dom-node-properties.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@clack/ui': minor
---

Add Node nextSibling and previousSibling properties that reflect the current tree after insertion, reordering, removal, and reparenting.
16 changes: 16 additions & 0 deletions packages/ui/src/dom.ts
Original file line number Diff line number Diff line change
Expand Up @@ -185,6 +185,22 @@ export abstract class Node extends EventTarget {
return this.#childNodes[this.childNodes.length - 1] ?? null;
}

get previousSibling(): Node | null {
if (!this.#parentNode) {
return null;
}
const siblings = this.#parentNode.#childNodes;
return siblings[siblings.indexOf(this) - 1] ?? null;
}

get nextSibling(): Node | null {
if (!this.#parentNode) {
return null;
}
const siblings = this.#parentNode.#childNodes;
return siblings[siblings.indexOf(this) + 1] ?? null;
}

get nodeValue(): string | null {
return null;
}
Expand Down
2 changes: 2 additions & 0 deletions packages/ui/test/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ Rendering, scheduling, notifications, and lifecycle behavior belong in the UI te

[`dom.compatibility.test.ts`](../src/dom.compatibility.test.ts) registers the shared compatibility suite with Vitest. Its synchronous factory creates a fresh instance of the real [`Document`](../src/dom.ts) for each case, with a no-op render notification callback. This fixture owns no external resources, so it needs no disposal callback.

[`dom.test.ts`](dom.test.ts) explicitly holds local DOM coverage missing from the enabled WPT cases. This is usually because getting the WPT test prequisites set up is too onerous a task. For example, testing node properties like nextSibling and previousSibling require things like `document.implementation.createDocumentType()`

[`wpt.config.ts`](wpt.config.ts) supplies the implementation's `globals` and selects the upstream files and cases enforced by this integration. Add new global bindings there. Omitting `config` runs all adapted cases; `exclude` removes matches and explicit `include` rules take precedence. Source keys support `*` and `**`; values are `true` for a whole source or arrays of exact case names and regular expressions. Unmatched rules are configuration errors. No other test groups must be enabled to run a case.

The configuration explicitly excludes unsupported directories. Add includes or narrow exclusions as cases pass. Selecting a source runs all of our adapted cases from that file; it does not imply complete coverage of the upstream file or interface.
Expand Down
115 changes: 115 additions & 0 deletions packages/ui/test/dom.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
/**
* Local DOM coverage not provided by our enabled WPT cases.
* These are independent tests, not adaptations of upstream WPT tests.
* Sibling traversal lives here while Node-properties.html requires unsupported
* HTML/XML document fixtures. Prefer WPT coverage when its dependencies are met.
*/
import { describe, expect, it } from 'vitest';
import { Document } from '../src/dom.ts';

describe('Node sibling properties outside WPT coverage', () => {
it.each(['createElement', 'createTextNode', 'createComment'] as const)(
'%s has no siblings when detached or an only child',
(create) => {
const document = new Document(() => {});
const parent = document.documentElement;
const node = document[create]('document');

expect(node.previousSibling).toBeNull();
expect(node.nextSibling).toBeNull();

parent.appendChild(node);
expect(node.previousSibling).toBeNull();
expect(node.nextSibling).toBeNull();

parent.removeChild(node);
expect(node.previousSibling).toBeNull();
expect(node.nextSibling).toBeNull();
},
);

it('traverses immediate siblings including text and comments', () => {
const document = new Document(() => {});
const parent = document.documentElement;
const first = parent.appendChild(document.createElement('document'));
const text = parent.appendChild(document.createTextNode('text'));
const comment = parent.appendChild(document.createComment('comment'));
const last = parent.appendChild(document.createElement('document'));
const nested = first.appendChild(document.createTextNode('nested'));

expect(first.previousSibling).toBeNull();
expect(first.nextSibling).toBe(text);
expect(text.previousSibling).toBe(first);
expect(text.nextSibling).toBe(comment);
expect(comment.previousSibling).toBe(text);
expect(comment.nextSibling).toBe(last);
expect(last.previousSibling).toBe(comment);
expect(last.nextSibling).toBeNull();
expect(nested.previousSibling).toBeNull();
expect(nested.nextSibling).toBeNull();
});

it('updates both directions when existing children are reordered', () => {
const document = new Document(() => {});
const parent = document.documentElement;
const first = parent.appendChild(document.createElement('document'));
const middle = parent.appendChild(document.createTextNode('middle'));
const last = parent.appendChild(document.createComment('last'));

parent.insertBefore(last, middle);
expect(first.previousSibling).toBeNull();
expect(first.nextSibling).toBe(last);
expect(last.previousSibling).toBe(first);
expect(last.nextSibling).toBe(middle);
expect(middle.previousSibling).toBe(last);
expect(middle.nextSibling).toBeNull();

parent.appendChild(first);
expect(last.previousSibling).toBeNull();
expect(last.nextSibling).toBe(middle);
expect(middle.previousSibling).toBe(last);
expect(middle.nextSibling).toBe(first);
expect(first.previousSibling).toBe(middle);
expect(first.nextSibling).toBeNull();
});

it('updates both trees when a child is moved to a different parent', () => {
const document = new Document(() => {});
const source = document.createElement('document');
const destination = document.createElement('document');
const first = source.appendChild(document.createTextNode('first'));
const moved = source.appendChild(document.createElement('document'));
const last = source.appendChild(document.createComment('last'));
const anchor = destination.appendChild(document.createTextNode('anchor'));

destination.insertBefore(moved, anchor);
expect(first.previousSibling).toBeNull();
expect(first.nextSibling).toBe(last);
expect(last.previousSibling).toBe(first);
expect(last.nextSibling).toBeNull();
expect(moved.previousSibling).toBeNull();
expect(moved.nextSibling).toBe(anchor);
expect(anchor.previousSibling).toBe(moved);
expect(anchor.nextSibling).toBeNull();
});

it('closes the sibling gap on removal and clears detached relationships', () => {
const document = new Document(() => {});
const parent = document.documentElement;
const first = parent.appendChild(document.createTextNode('first'));
const middle = parent.appendChild(document.createComment('middle'));
const last = parent.appendChild(document.createElement('document'));

parent.removeChild(middle);
expect(first.nextSibling).toBe(last);
expect(last.previousSibling).toBe(first);
expect(middle.previousSibling).toBeNull();
expect(middle.nextSibling).toBeNull();

parent.removeChild(first);
expect(first.previousSibling).toBeNull();
expect(first.nextSibling).toBeNull();
expect(last.previousSibling).toBeNull();
expect(last.nextSibling).toBeNull();
});
});
Loading