https://github.com/aegisjsproject/commands
A lightweight command system for handling DOM interactions through `command` events and the `commandfor` attribute.
https://github.com/aegisjsproject/commands
aegisjsproject commands dom invoker invoker-commans
Last synced: 5 months ago
JSON representation
A lightweight command system for handling DOM interactions through `command` events and the `commandfor` attribute.
- Host: GitHub
- URL: https://github.com/aegisjsproject/commands
- Owner: AegisJSProject
- License: mit
- Created: 2025-09-28T16:12:27.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2025-10-09T15:19:00.000Z (8 months ago)
- Last Synced: 2025-10-10T15:35:04.179Z (8 months ago)
- Topics: aegisjsproject, commands, dom, invoker, invoker-commans
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/@aegisjsproject/commands
- Size: 179 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# `@aegisjsproject/commands`
A lightweight command system for handling DOM interactions through `command` events and the `commandfor` attribute.
[](https://github.com/AegisJSProject/commands/actions/workflows/codeql-analysis.yml)
[](https://github.com/AegisJSProject/commands/blob/master/LICENSE)
[](https://github.com/AegisJSProject/commands/commits/master)
[](https://github.com/AegisJSProject/commands/releases)
[](https://github.com/sponsors/shgysk8zer0)
[](https://www.npmjs.com/package/@aegisjsproject/commands)
[](https://www.npmjs.com/package/@aegisjsproject/commands)
[](https://github.com/AegisJSProject)
[](https://twitter.com/shgysk8zer0)
[](https://liberapay.com/shgysk8zer0/donate "Donate using Liberapay")
- - -
- [Code of Conduct](./.github/CODE_OF_CONDUCT.md)
- [Contributing](./.github/CONTRIBUTING.md)
## Core Concept
This library is based on the [Invoker Commands API](https://developer.mozilla.org/en-US/docs/Web/API/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.
```html
Show Modal
Hello, World!
Close
Remove Element
This content will be removed.
```
## 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.
```js
import { observeCommands } from './commands.js';
observeCommands(); // Observes document.body by default
```
### `registerCommand(command, callback)`
Registers custom commands (must be prefixed with `--`).
```js
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.
```js
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.
```js
import { command } from './commands.js';
element.innerHTML = ` alert('clicked'))}>Click me`;
```
### `listenForCommands(target, init?)`
Manually add command listener to specific elements.
```js
import { listenForCommands } from './commands.js';
listenForCommands(myElement, { once: true });
```
## Usage Patterns
### Basic Setup
```js
import { observeCommands } from './commands.js';
observeCommands();
```
### Custom Commands
```js
import { observeCommands, registerCommand } from './commands.js';
registerCommand('--toggle-class', (event) => {
event.target.classList.toggle('active');
});
observeCommands();
```
### Dynamic Command Generation
```js
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 += `Change Color`;
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.