@aegisjsproject/commands

A lightweight command system for handling DOM interactions through command events and the commandfor attribute.

• Code of Conduct
• Contributing

Core Concept

This library is based on the Invoker Commands API. Elements with a commandfor attribute automatically dispatch command events to their target elements when triggered. The library handles these events with built-in commands or custom registered handlers.

<!-- Using Built-In Commands -->
<button commandfor="my-element" command="show-modal">Show Modal</button>
<dialog id="my-element">
  <p>Hello, World!</p>
  <button commandfor="my-element" command="close">Close</button>
</dialog>
<!-- Using Custom Commands -->
<button commandfor="another-el" command="--aegis-command-remove">Remove Element</button>
<div id="another-el">This content will be removed.</div>

Custom, pre-registered Commands

• --aegis-command-hide/--aegis-command-unhide - Controls hidden attribute
• --aegis-command-disable/--aegis-command-enable - Controls disabled attribute
• --aegis-command-remove - Removes element from DOM
• --aegis-command-scroll-into-view - Scrolls element into view (respects prefers-reduced-motion)
• --aegis-command-request-fullscreen/--aegis-command-exit-fullscreen/--aegis-command-toggle-fullscreen - Fullscreen API
• --aegis-command-show-picker - Opens input picker (date, color, etc.)
• --aegis-command-step-up/--aegis-command-step-down - Steps numeric inputs
• --aegis-command-open-details/--aegis-command-close-details/--aegis-command-toggle-details - Controls elements
• --aegis-command-play-media/--aegis-command-pause-media - Media element controls
• --aegis-command-request-picture-in-picture - Picture-in-picture for videos
• --aegis-command-copy-text - Copies element's textContent to clipboard

API

observeCommands(target?)

Sets up automatic command handling. Call once during initialization.

import { observeCommands } from './commands.js';
observeCommands(); // Observes document.body by default

registerCommand(command, callback)

Registers custom commands (must be prefixed with --).

import { registerCommand } from './commands.js';

registerCommand('--my-command', (event) => {
  console.log('Custom command triggered on', event.target);
});

createCommand(callback)

Generates a unique command string and registers the callback.

import { createCommand } from './commands.js';

const cmd = createCommand((event) => {
  event.target.style.color = 'red';
});
// Use `cmd` as the command attribute value

command(callback)

Convenience function that returns a complete attribute string.

import { command } from './commands.js';

element.innerHTML = `<button ${command(e => alert('clicked'))}>Click me</button>`;

listenForCommands(target, init?)

Manually add command listener to specific elements.

import { listenForCommands } from './commands.js';
listenForCommands(myElement, { once: true });

Usage Patterns

Basic Setup

import { observeCommands } from './commands.js';
observeCommands();

Custom Commands

import { observeCommands, registerCommand } from './commands.js';

registerCommand('--toggle-class', (event) => {
  event.target.classList.toggle('active');
});

observeCommands();

Dynamic Command Generation

import { observeCommands, createCommand } from './commands.js';

const toggleColor = createCommand((event) => {
  const colors = ['red', 'blue', 'green'];
  const current = colors.indexOf(event.target.style.color);
  event.target.style.color = colors[(current + 1) % colors.length];
});

document.body.innerHTML += `<button commandfor="target" command="${toggleColor}">Change Color</button>`;
observeCommands();

CommandEvent Properties

Command events extend regular events with:

• source - The element that triggered the command (the button/trigger)
• command - The command string that was executed#

Memory Considerations

[!WARNING] Command listeners are not automatically removed when elements are deleted. If you're frequently adding/removing elements with commandfor attributes in long-running applications, consider using listenForCommands() with { once: true } for one-time interactions, or manually manage listeners for dynamic content.

Security

Command registration closes automatically after initial setup. Call closeCommandRegistration() explicitly if needed for additional security.