diff --git a/.changeset/dom-node-properties.md b/.changeset/dom-node-properties.md new file mode 100644 index 0000000..27775ee --- /dev/null +++ b/.changeset/dom-node-properties.md @@ -0,0 +1,5 @@ +--- +'@clack/ui': minor +--- + +Add Node nextSibling and previousSibling properties that reflect the current tree after insertion, reordering, removal, and reparenting. diff --git a/packages/ui/src/dom.ts b/packages/ui/src/dom.ts index 3930318..8a5bfd4 100644 --- a/packages/ui/src/dom.ts +++ b/packages/ui/src/dom.ts @@ -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; } diff --git a/packages/ui/test/README.md b/packages/ui/test/README.md index c21c2fd..2e0750d 100644 --- a/packages/ui/test/README.md +++ b/packages/ui/test/README.md @@ -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. diff --git a/packages/ui/test/dom.test.ts b/packages/ui/test/dom.test.ts new file mode 100644 index 0000000..7cddf6a --- /dev/null +++ b/packages/ui/test/dom.test.ts @@ -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(); + }); +});