Selecto.js Documentation

Selecto emits several events that provide detailed information about the selection process.

Selection Events

Selection events (selectStart, select, selectEnd) provide information about which elements are being manipulated.

• SelectedTargets: The core data for selection changes.
  • beforeSelected: Elements that were selected before the current change.
  • selected: The current list of selected elements.
  • added: Elements newly added to the selection.
  • removed: Elements removed from the selection.
• OnSelectEvent: Extends SelectedTargets with:
  • inputEvent: The original input event.
  • data: Shared data from dragStart through selectEnd.
  • isDragStartEnd: True if the drag ended immediately at the start.
  • isTrusted: Whether the interaction was a user-initiated drag.
• OnSelectEnd: Specific to the end of a selection action, adding:
  • isClick: True if the action was a click.
  • isDouble: True if it was a double click.
  • afterAdded / afterRemoved: Elements after the selection logic has finalized.

Selecto provides several events to manage the selection lifecycle. You can listen to these using the .on() method.

• selectStart: Triggered when the selection (drag) begins.
• select: Triggered in real-time as the selection area changes during a drag.
• selectEnd: Triggered when the selection (drag or click) ends. This event provides detailed information about what was added and removed from the selection.

Example of managing CSS classes based on selection state:

selecto.on("selectStart", e => {
  e.added.forEach(el => {
    el.classList.add("selected");
  });
  e.removed.forEach(el => {
    el.classList.remove("selected");
  });
}).on("selectEnd", e => {
  e.afterAdded.forEach(el => {
    el.classList.add("selected");
  });
  e.afterRemoved.forEach(el => {
    el.classList.remove("selected");
  });
});

import Selecto from "selecto";

const selecto = new Selecto({
  container: document.body,
  selectByClick: true,
  selectFromInside: false,
});

selecto.on("selectStart", e => {
  e.added.forEach(el => {
    el.classList.add("selected");
  });
  e.removed.forEach(el => {
    el.classList.remove("selected");
  });
}).on("selectEnd", e => {
  e.afterAdded.forEach(el => {
    el.classList.add("selected");
  });
  e.afterRemoved.forEach(el => {
    el.classList.remove("selected");
  });
});

Initialize a new Selecto instance by providing a configuration object. You can listen to the select event to handle elements being added to or removed from the current selection.

import Selecto from "selecto";

const selecto = new Selecto({
    // The container to add a selection element
    container: document.body,
    // Selecto's root container (No transformed container. (default: null)
    rootContainer: null,
    // The area to drag selection element (default: container)
    dragContainer: Element,
    // Targets to select. You can register a queryselector or an Element.
    selectableTargets: [".target", document.querySelector(".target2")],
    // Whether to select by click (default: true)
    selectByClick: true,
    // Whether to select from the target inside (default: true)
    selectFromInside: true,
    // After the select, whether to select the next target with the selected target (deselected if the target is selected again).
    continueSelect: false,
    // Determines which key to continue selecting the next target via keydown and keyup.
    toggleContinueSelect: "shift",
    // The container for keydown and keyup events
    keyContainer: window,
    // The rate at which the target overlaps the drag area to be selected. (default: 100)
    hitRate: 100,
});

selecto.on("select", e => {
    e.added.forEach(el => {
        el.classList.add("selected");
    });
    e.removed.forEach(el => {
        el.classList.remove("selected");
    });
});

This configuration file defines how the croffle build tool transforms and bundles Selecto's Storybook stories across different frameworks (React, Vue, Svelte, Angular, Lit). It uses croissant for high-level transformations and waffle for framework-specific bundling logic.

Key transformations include:

• Selecto Component Transformation: Automatically injects the container property into the Selecto options object during the build process.
• Framework-specific adaptations: Handles module prefixing, template attribute renaming (e.g., for Lit), and keydown event handling (e.g., useKeycon) for various environments.
• Prop Injection: Injects preview props into components to facilitate Storybook usage.

const config = [
    {
        targets: "stories/**/+([0-9A-Za-z])-*/React*App.tsx",
        croissant: () => {
            const croissant = new ReactCroissant();
            croissant.addSirup(PreviewPropsSirup);
            // ...
            return croissant;
        },
        waffle: [
            // Framework-specific waffle configurations (Vanilla, Vue, Svelte, Angular, Lit)
        ],
    },
];

module.exports = config;