tessl/npm-ephox--sugar

A comprehensive DOM manipulation library providing type-safe, functional utilities for elements, events, properties, and selections.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Specialized HTML Elements

Name: tessl/npm-ephox--sugar
Author: tessl

Utilities for working with specific HTML elements like select, option, and form controls. Provides type-safe accessors and specialized operations for complex HTML elements.

Capabilities

Option Element Utilities

Specialized utilities for working with HTML option elements in select lists.

/**
 * Get value attribute from option element
 * @param element - Option element to read from
 * @returns Value attribute content
 */
function getValue(element: SugarElement<HTMLOptionElement>): string;

/**
 * Set value attribute on option element
 * @param element - Option element to modify
 * @param value - Value to set
 */
function setValue(element: SugarElement<HTMLOptionElement>, value: string): void;

/**
 * Get text content from option element
 * @param element - Option element to read from
 * @returns Displayed text content
 */
function getText(element: SugarElement<HTMLOptionElement>): string;

/**
 * Set text content of option element
 * @param element - Option element to modify
 * @param text - Text content to set
 */
function setText(element: SugarElement<HTMLOptionElement>, text: string): void;

/**
 * Check if option element is selected
 * @param element - Option element to check
 * @returns True if option is currently selected
 */
function isSelected(element: SugarElement<HTMLOptionElement>): boolean;

/**
 * Set selected state of option element
 * @param element - Option element to modify
 * @param state - Whether option should be selected
 */
function setSelected(element: SugarElement<HTMLOptionElement>, state: boolean): void;

/**
 * Check if option element is disabled
 * @param element - Option element to check
 * @returns True if option is disabled
 */
function isDisabled(element: SugarElement<HTMLOptionElement>): boolean;

/**
 * Set disabled state of option element
 * @param element - Option element to modify
 * @param state - Whether option should be disabled
 */
function setDisabled(element: SugarElement<HTMLOptionElement>, state: boolean): void;

Usage Examples:

import { OptionTag, SugarElement } from "@ephox/sugar";

// Create option element
const option = SugarElement.fromTag('option');

// Set option properties
OptionTag.setValue(option, 'user-123');
OptionTag.setText(option, 'John Doe');

// Read option properties
const value = OptionTag.getValue(option);    // 'user-123'
const text = OptionTag.getText(option);      // 'John Doe'

// Manage selection state
OptionTag.setSelected(option, true);
const isSelected = OptionTag.isSelected(option); // true

// Handle disabled state
OptionTag.setDisabled(option, false);
const isEnabled = !OptionTag.isDisabled(option); // true

Select Element Utilities

Comprehensive utilities for working with HTML select elements and their options.

/**
 * Get currently selected value from select element
 * @param element - Select element to read from
 * @returns Value of selected option, or empty string if none
 */
function getValue(element: SugarElement<HTMLSelectElement>): string;

/**
 * Set selected value in select element
 * @param element - Select element to modify
 * @param value - Value to select (matches option value attribute)
 */
function setValue(element: SugarElement<HTMLSelectElement>, value: string): void;

/**
 * Get text of currently selected option
 * @param element - Select element to read from
 * @returns Text content of selected option
 */
function getSelectedText(element: SugarElement<HTMLSelectElement>): string;

/**
 * Get index of currently selected option
 * @param element - Select element to read from
 * @returns Zero-based index of selected option, -1 if none
 */
function getSelectedIndex(element: SugarElement<HTMLSelectElement>): number;

/**
 * Set selected option by index
 * @param element - Select element to modify
 * @param index - Zero-based index of option to select
 */
function setSelectedIndex(element: SugarElement<HTMLSelectElement>, index: number): void;

/**
 * Get all option elements from select
 * @param element - Select element to read from
 * @returns Array of all option elements
 */
function getOptions(element: SugarElement<HTMLSelectElement>): SugarElement<HTMLOptionElement>[];

/**
 * Get currently selected option element
 * @param element - Select element to read from
 * @returns Selected option element if one exists
 */
function getSelected(element: SugarElement<HTMLSelectElement>): Optional<SugarElement<HTMLOptionElement>>;

/**
 * Add option element to select
 * @param element - Select element to modify
 * @param option - Option element to add
 */
function add(element: SugarElement<HTMLSelectElement>, option: SugarElement<HTMLOptionElement>): void;

/**
 * Remove option from select by value
 * @param element - Select element to modify
 * @param value - Value of option to remove
 */
function removeByValue(element: SugarElement<HTMLSelectElement>, value: string): void;

/**
 * Remove option from select by index
 * @param element - Select element to modify
 * @param index - Index of option to remove
 */
function removeByIndex(element: SugarElement<HTMLSelectElement>, index: number): void;

/**
 * Clear all options from select
 * @param element - Select element to clear
 */
function clear(element: SugarElement<HTMLSelectElement>): void;

/**
 * Check if select has any options
 * @param element - Select element to check
 * @returns True if select contains options
 */
function hasOptions(element: SugarElement<HTMLSelectElement>): boolean;

/**
 * Get number of options in select
 * @param element - Select element to count
 * @returns Number of option elements
 */
function size(element: SugarElement<HTMLSelectElement>): number;

Usage Examples:

import { SelectTag, OptionTag, SugarElement } from "@ephox/sugar";

// Create select element
const select = SugarElement.fromTag('select');

// Add options
const option1 = SugarElement.fromTag('option');
OptionTag.setValue(option1, 'red');
OptionTag.setText(option1, 'Red');

const option2 = SugarElement.fromTag('option');
OptionTag.setValue(option2, 'blue');
OptionTag.setText(option2, 'Blue');

SelectTag.add(select, option1);
SelectTag.add(select, option2);

// Work with selections
SelectTag.setValue(select, 'blue');
const selectedValue = SelectTag.getValue(select);        // 'blue'
const selectedText = SelectTag.getSelectedText(select);  // 'Blue'
const selectedIndex = SelectTag.getSelectedIndex(select); // 1

// Get options
const allOptions = SelectTag.getOptions(select);
console.log(`Select has ${SelectTag.size(select)} options`);

// Remove options
SelectTag.removeByValue(select, 'red');
SelectTag.clear(select); // Remove all options

Input Element Utilities

Specialized utilities for various HTML input types.

/**
 * Get value from input element
 * @param element - Input element to read from
 * @returns Current input value
 */
function getValue(element: SugarElement<HTMLInputElement>): string;

/**
 * Set value of input element
 * @param element - Input element to modify
 * @param value - Value to set
 */
function setValue(element: SugarElement<HTMLInputElement>, value: string): void;

/**
 * Check if checkbox or radio input is checked
 * @param element - Input element to check
 * @returns True if input is checked
 */
function isChecked(element: SugarElement<HTMLInputElement>): boolean;

/**
 * Set checked state of checkbox or radio input
 * @param element - Input element to modify
 * @param state - Whether input should be checked
 */
function setChecked(element: SugarElement<HTMLInputElement>, state: boolean): void;

/**
 * Get input type attribute
 * @param element - Input element to read from
 * @returns Input type (text, email, password, etc.)
 */
function getType(element: SugarElement<HTMLInputElement>): string;

/**
 * Set input type attribute
 * @param element - Input element to modify
 * @param type - Input type to set
 */
function setType(element: SugarElement<HTMLInputElement>, type: string): void;

/**
 * Check if input is disabled
 * @param element - Input element to check
 * @returns True if input is disabled
 */
function isDisabled(element: SugarElement<HTMLInputElement>): boolean;

/**
 * Set disabled state of input
 * @param element - Input element to modify
 * @param state - Whether input should be disabled
 */
function setDisabled(element: SugarElement<HTMLInputElement>, state: boolean): void;

/**
 * Check if input is readonly
 * @param element - Input element to check
 * @returns True if input is readonly
 */
function isReadonly(element: SugarElement<HTMLInputElement>): boolean;

/**
 * Set readonly state of input
 * @param element - Input element to modify
 * @param state - Whether input should be readonly
 */
function setReadonly(element: SugarElement<HTMLInputElement>, state: boolean): void;

Usage Examples:

import { Value, SugarElement } from "@ephox/sugar";

// Text input
const textInput = SugarElement.fromTag('input');
InputTag.setType(textInput, 'email');
InputTag.setValue(textInput, 'user@example.com');

const email = InputTag.getValue(textInput);
const inputType = InputTag.getType(textInput);

// Checkbox input
const checkbox = SugarElement.fromTag('input');
InputTag.setType(checkbox, 'checkbox');
InputTag.setChecked(checkbox, true);

const isChecked = InputTag.isChecked(checkbox);

// Disabled input
InputTag.setDisabled(textInput, true);
const isDisabled = InputTag.isDisabled(textInput);

// Readonly input
InputTag.setReadonly(textInput, true);
const isReadonly = InputTag.isReadonly(textInput);

Textarea Element Utilities

Utilities for working with textarea elements and their content.

/**
 * Get text content from textarea
 * @param element - Textarea element to read from
 * @returns Current textarea content
 */
function getValue(element: SugarElement<HTMLTextAreaElement>): string;

/**
 * Set text content of textarea
 * @param element - Textarea element to modify
 * @param value - Text content to set
 */
function setValue(element: SugarElement<HTMLTextAreaElement>, value: string): void;

/**
 * Get cursor position in textarea
 * @param element - Textarea element to read from
 * @returns Current cursor position (selection start)
 */
function getCursorPosition(element: SugarElement<HTMLTextAreaElement>): number;

/**
 * Set cursor position in textarea
 * @param element - Textarea element to modify
 * @param position - Character position to set cursor to
 */
function setCursorPosition(element: SugarElement<HTMLTextAreaElement>, position: number): void;

/**
 * Get selected text from textarea
 * @param element - Textarea element to read from
 * @returns Currently selected text
 */
function getSelectedText(element: SugarElement<HTMLTextAreaElement>): string;

/**
 * Replace selected text in textarea
 * @param element - Textarea element to modify
 * @param replacement - Text to replace selection with
 */
function replaceSelectedText(element: SugarElement<HTMLTextAreaElement>, replacement: string): void;

/**
 * Insert text at cursor position
 * @param element - Textarea element to modify
 * @param text - Text to insert
 */
function insertAtCursor(element: SugarElement<HTMLTextAreaElement>, text: string): void;

Button Element Utilities

Utilities for button elements and their states.

/**
 * Get text content from button
 * @param element - Button element to read from
 * @returns Button text content
 */
function getText(element: SugarElement<HTMLButtonElement>): string;

/**
 * Set text content of button
 * @param element - Button element to modify
 * @param text - Text content to set
 */
function setText(element: SugarElement<HTMLButtonElement>, text: string): void;

/**
 * Get button type attribute
 * @param element - Button element to read from
 * @returns Button type (button, submit, reset)
 */
function getType(element: SugarElement<HTMLButtonElement>): string;

/**
 * Set button type attribute
 * @param element - Button element to modify
 * @param type - Button type to set
 */
function setType(element: SugarElement<HTMLButtonElement>, type: 'button' | 'submit' | 'reset'): void;

/**
 * Check if button is disabled
 * @param element - Button element to check
 * @returns True if button is disabled
 */
function isDisabled(element: SugarElement<HTMLButtonElement>): boolean;

/**
 * Set disabled state of button
 * @param element - Button element to modify
 * @param state - Whether button should be disabled
 */
function setDisabled(element: SugarElement<HTMLButtonElement>, state: boolean): void;

Form Element Utilities

Utilities for form elements and form data management.

/**
 * Get form data as key-value pairs
 * @param element - Form element to read from
 * @returns Object containing form field values
 */
function getFormData(element: SugarElement<HTMLFormElement>): Record<string, string>;

/**
 * Set form data from key-value pairs
 * @param element - Form element to modify
 * @param data - Object containing field values to set
 */
function setFormData(element: SugarElement<HTMLFormElement>, data: Record<string, string>): void;

/**
 * Reset form to default values
 * @param element - Form element to reset
 */
function reset(element: SugarElement<HTMLFormElement>): void;

/**
 * Check if form is valid (HTML5 validation)
 * @param element - Form element to validate
 * @returns True if all form fields are valid
 */
function isValid(element: SugarElement<HTMLFormElement>): boolean;

/**
 * Get all form field elements
 * @param element - Form element to read from
 * @returns Array of all input, select, and textarea elements
 */
function getFields(element: SugarElement<HTMLFormElement>): SugarElement<HTMLElement>[];

/**
 * Submit form programmatically
 * @param element - Form element to submit
 */
function submit(element: SugarElement<HTMLFormElement>): void;

Usage Examples:

import { SugarElement } from "@ephox/sugar";

const form = SugarElement.fromTag('form');

// Set form data
FormTag.setFormData(form, {
  username: 'johndoe',
  email: 'john@example.com',
  age: '25'
});

// Get form data
const formData = FormTag.getFormData(form);
console.log('Form data:', formData);

// Validate and submit
if (FormTag.isValid(form)) {
  FormTag.submit(form);
} else {
  console.log('Form validation failed');
}

// Reset form
FormTag.reset(form);

Types

// Form data type for key-value pairs
type FormData = Record<string, string>;

// Button type union for type safety
type ButtonType = 'button' | 'submit' | 'reset';

// Input type union for common input types
type InputType = 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'search' | 
                 'checkbox' | 'radio' | 'file' | 'hidden' | 'submit' | 'reset' | 'button';

Install with Tessl CLI