Utility Functions

WakaPAC provides built-in utility functions for data formatting, HTML sanitization, element positioning, and component communication. These are accessible via this within component methods.

Data Formatting

Use formatValue() to safely convert any value to a display string:

<div id="app">
    <button data-pac-bind="click: showValues">Show Values</button>
    <pre>{{output}}</pre>
</div>

<script>
    wakaPAC('#app', {
        output: '',

        showValues() {
            const values = [
                this.formatValue(null),           // ""
                this.formatValue(undefined),      // ""
                this.formatValue([1, 2, 3]),      // "[1,2,3]"
                this.formatValue({name: 'John'})  // JSON formatted
            ];

            this.output = values.join('\n');
        }
    });
</script>

HTML Sanitization

Prevent XSS attacks with escapeHTML() and sanitizeUserInput():

<div id="app">
    <textarea data-pac-bind="value: userInput"></textarea>
    <button data-pac-bind="click: process">Process</button>

    <p>Escaped: {{escaped}}</p>
    <p>Sanitized: {{sanitized}}</p>
</div>

<script>
    wakaPAC('#app', {
        userInput: '<script>alert("XSS")</script><b>Bold</b>',
        escaped: '',
        sanitized: '',

        process() {
            // Escape HTML entities - safe to display
            this.escaped = this.escapeHTML(this.userInput);
            // "&lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;&lt;b&gt;Bold&lt;/b&gt;"

            // Strip all HTML - plain text only
            this.sanitized = this.sanitizeUserInput(this.userInput);
            // "alert(\"XSS\")Bold"
        }
    });
</script>

formatValue() Behavior

Coordinate Extraction (Win32-Style)

WakaPAC provides Win32-style functions for extracting mouse coordinates from lParam in msgProc. These are static functions on wakaPAC. Coordinates extracted from lParam are relative to the container's top-left corner (client-area relative in Win32 terms).

MAKEPOINTS(lParam)

Extracts both X and Y coordinates from a packed lParam value. Returns an object with x and y properties.

msgProc(event) {
    if (event.message === wakaPAC.MSG_MOUSEMOVE) {
        const pos = wakaPAC.MAKEPOINTS(event.lParam);
        console.log(pos.x, pos.y); // Container-relative coordinates
    }
}

LOWORD(lParam)

Extracts the low 16 bits from lParam (X coordinate for mouse events).

const x = wakaPAC.LOWORD(event.lParam);

HIWORD(lParam)

Extracts the high 16 bits from lParam (Y coordinate for mouse events).

const y = wakaPAC.HIWORD(event.lParam);

Coordinate Conversion

Convert between container-relative and viewport-absolute coordinates. These are instance methods called via this within component methods.

containerToViewport(x, y)

Converts container-relative coordinates to viewport-absolute coordinates. Use this when you have coordinates from lParam and need to pass them to hit-testing functions.

msgProc(event) {
    if (event.message === wakaPAC.MSG_MOUSEMOVE) {
        const pos = wakaPAC.MAKEPOINTS(event.lParam);
        const viewport = this.containerToViewport(pos.x, pos.y);

        // Now can use with hit-testing
        const element = wakaPAC.elementFromPoint(viewport.x, viewport.y);
    }
}

• Parameters: x, y - Container-relative coordinates
• Returns: { x, y } - Viewport-absolute coordinates
• Win32 Equivalent: ClientToScreen

viewportToContainer(x, y)

Converts viewport-absolute coordinates to container-relative coordinates. Use this when you have coordinates from event.originalEvent.clientX/clientY and need them in container space.

msgProc(event) {
    const clientX = event.originalEvent.clientX;
    const clientY = event.originalEvent.clientY;
    const containerPos = this.viewportToContainer(clientX, clientY);

    console.log(containerPos.x, containerPos.y); // Same as MAKEPOINTS(lParam)
}

• Parameters: x, y - Viewport-absolute coordinates
• Returns: { x, y } - Container-relative coordinates
• Win32 Equivalent: ScreenToClient

Hit Testing & Element Lookup

WakaPAC provides Win32-style hit-testing functions for determining what lies under a given screen coordinate. These are static functions on wakaPAC, not instance methods — call them as wakaPAC.ptInElement(), not this.ptInElement(). All coordinates are in viewport (client) space, matching what you get from event.originalEvent.clientX/clientY or from converting container-relative coordinates with this.containerToViewport().

ptInElement(x, y, element)

Tests whether a point lies within an element's bounding rectangle. Equivalent to Win32's PtInRect. Returns false if the element is null.

msgProc(event) {
    if (event.message === wakaPAC.MSG_MOUSEMOVE) {
        const pos = wakaPAC.MAKEPOINTS(event.lParam);
        const viewport = this.containerToViewport(pos.x, pos.y);
        const dropZone = document.getElementById('drop-target');

        this.overTarget = wakaPAC.ptInElement(viewport.x, viewport.y, dropZone);
        return false;
    }
}

elementFromPoint(x, y)

Returns the topmost DOM element at the given viewport coordinates. This is a thin wrapper around document.elementFromPoint(), provided so hit-testing code can use a consistent API without mixing wakaPAC and document calls.

const pos = this.containerToViewport(localX, localY);
const element = wakaPAC.elementFromPoint(pos.x, pos.y);

if (element?.classList.contains('droppable')) {
    // Cursor is over a droppable element
}

containerFromPoint(x, y)

Returns the nearest WakaPAC container element at the given viewport coordinates, or null if the point is not over any container. Internally calls elementFromPoint() and then walks up the DOM with closest('[data-pac-id]'). Useful for drag-and-drop between containers or determining which component the cursor is hovering over.

msgProc(event) {
    if (event.message === wakaPAC.MSG_MOUSEMOVE && this._dragging) {
        const pos = wakaPAC.MAKEPOINTS(event.lParam);
        const viewport = this.containerToViewport(pos.x, pos.y);
        const target = wakaPAC.containerFromPoint(viewport.x, viewport.y);

        if (target && target !== this.container) {
            // Cursor is over a different container — show drop indicator
            this.dropTargetId = target.getAttribute('data-pac-id');
        }

        return false;
    }
}

Container Lookup

getContainerByPacId(pacId)

Resolves a WakaPAC container's DOM element by its data-pac-id value. Returns null with a console warning if the container is not found. Use this when you have a pac-id (from this.pacId, containerFromPoint(), or stored state) and need the actual element.

const container = wakaPAC.getContainerByPacId(targetPacId);

if (container) {
    const rect = container.getBoundingClientRect();
    // Position something relative to the target container
}