Document Builder Utility

Build a utility function that creates structured document representations from JSX-like syntax. The function should handle text content, support nested structures, and work with cursor positioning for testing purposes.

Requirements

Your utility should create document structures that:

1. Convert plain text strings into structured text objects
2. Handle multiple adjacent strings appropriately
3. Support nested block structures
4. Work with cursor markers for representing positions within text

Functionality

Core Document Creation

• When given plain strings within a structure, they should be converted to a standardized text format @test
• Multiple adjacent plain strings with the same properties should be combined into a single text node @test
• Nested block structures should maintain proper parent-child relationships @test

Cursor Position Handling

• Cursor markers should be properly positioned within text content @test
• When a cursor appears between strings, the resulting structure should reflect the correct text offset @test

Implementation

@generates

API

/**
 * Creates a structured document from JSX-like syntax.
 *
 * The function should handle automatic text node conversion where:
 * - Plain strings are converted to text objects
 * - Adjacent strings with identical properties are merged
 * - Cursor positions are calculated based on merged text
 *
 * @param {string} tagName - The element type (e.g., 'element', 'text', 'cursor')
 * @param {Object} attributes - Properties to attach to the node
 * @param {...any} children - Child nodes or plain strings
 * @returns {Object} The structured document node
 */
function createDocument(tagName, attributes, ...children) {
  // IMPLEMENTATION HERE
}

module.exports = {
  createDocument
};

Test Cases

The following test cases should pass:

Single String Conversion

// Given a plain string in an element
const result = createDocument('element', {}, 'hello world');

// Should convert to text object
assert.deepEqual(result.children, [{ text: 'hello world' }]);

@test

Adjacent String Merging

// Given multiple adjacent strings
const result = createDocument('element', {}, 'one', ' ', 'two');

// Should merge into single text node
assert.deepEqual(result.children, [{ text: 'one two' }]);

@test

Cursor Position in Merged Text

// Given strings with a cursor marker between them
const result = createDocument(
  'element',
  {},
  'hello',
  createDocument('cursor', {}),
  'world'
);

// Should have merged text with cursor at correct offset
assert.equal(result.children[0].text, 'helloworld');
assert.equal(result.selection.anchor.offset, 5);

@test

Dependencies { .dependencies }

slate-hyperscript { .dependency }

Provides utilities for creating Slate document structures with JSX syntax, including automatic string-to-text conversion and selection handling.