---
name: dom-utilities-assistant
description: Specialized assistant for implementing robust DOM manipulation patterns using the bespoke DOM utility library for type-safe element queries.
title: dom-utilities-assistant
canonical_url: https://skilld.dev/gh/corey-alix/dwp-hours/dom-utilities-assistant
last_updated: 2026-10-07T01:30:59.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install corey-alix/dwp-hours/dom-utilities-assistant`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/dom-utilities-assistant`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/corey-alix/dwp-hours/dom-utilities-assistant) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/dom-utilities-assistant`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/dom-utilities-assistant --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/dom-utilities-assistant --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# DOM Utilities Assistant

## Description

Specialized assistant for implementing robust DOM manipulation patterns in the DWP Hours Tracker frontend. Provides guidance on using the bespoke DOM utility library (`client/components/test-utils.ts`) for type-safe element queries, consistent error handling, and enhanced debugging capabilities.

## DOM Utilities System

The DWP Hours Tracker uses a lightweight bespoke DOM utility library to facilitate robust DOM manipulation with enhanced error logging and debugging capabilities. Direct use of native DOM APIs like `document.getElementById()`, `document.querySelector()`, etc. is discouraged in favor of utility functions.

### Core Principles

- **Type-Safe Queries**: Use TypeScript generics for compile-time type checking
- **Automatic Error Logging**: Descriptive errors when elements are not found
- **Consistent Error Handling**: Standardized error patterns across the application
- **Debug-Friendly Output**: Enhanced console logging for development
- **Reliable Interactions**: Ensures DOM operations are predictable and testable

### Key Utility Functions

#### Element Queries

- **`querySingle<T>(selector: string): T`** - Finds a single element by selector, throws descriptive error if not found
- **`queryMultiple<T>(selector: string): T[]`** - Finds multiple elements by selector, throws error if none found
- **`getElementById<T>(id: string): T`** - Finds element by ID with error logging

#### Event Management

- **`addEventListener(element, event, handler, options?)`** - Safely adds event listeners with error handling

#### Element Creation

- **`createElement<T>(tagName, attributes?)`** - Creates elements with optional attributes

## Usage Patterns

### ❌ Avoid Direct DOM APIs

```typescript
const button = document.getElementById("my-button") as HTMLButtonElement;
if (!button) {
  console.error("Button not found");
  throw new Error("Button not found");
}
button.addEventListener("click", handler);
```

### ✅ Use DOM Utilities

```typescript
import { getElementById, addEventListener } from "./components/test-utils.js";
const button = getElementById<HTMLButtonElement>("my-button");
addEventListener(button, "click", handler);
```

## Trigger

Activate this skill when users ask about:

- DOM element queries and manipulation
- Type-safe element access patterns
- Event listener management
- Element creation utilities
- DOM error handling and debugging
- Web component DOM interactions
- Shadow DOM element queries

## Response Pattern

When activated, follow this structured approach:

1. **Identify DOM Operation**: Determine if query involves element access, event handling, or creation
2. **Reference Utility Functions**: Show appropriate functions from `test-utils.ts`
3. **Provide Type-Safe Examples**: Demonstrate TypeScript generic usage
4. **Address Error Scenarios**: Explain error handling and debugging benefits
5. **Ensure Shadow DOM Compatibility**: Consider web component encapsulation needs

## Examples

- "How do I safely query DOM elements?"
- "What's the best way to add event listeners?"
- "How do I handle missing elements gracefully?"
- "How do I create elements with proper typing?"
- "How do I query elements within web components?"

## Additional Context

This skill integrates with the web components architecture and ensures all DOM interactions follow the project's patterns for reliability and testability. The utilities are located in `client/components/test-utils.ts` and should be imported for all DOM operations.
