lisn.js/dist/esm/actions/action.js

Simply handle user gestures and actions. Includes widgets.

/**
 * ## Specification for the HTML API for actions
 *
 * When using the HTML API, actions are always used with triggers. Please see
 * {@link Triggers | the documentation on triggers} for the required syntax.
 *
 * @module Actions
 */

import * as MH from "../globals/minification-helpers.js";
import { splitOn } from "../utils/text.js";
import { fetchWidgetConfig } from "../widgets/widget.js";

/**
 * @interface
 */

/**
 * Registers the given action so that it can be parsed by
 * {@link Triggers.registerTrigger}.
 *
 * **IMPORTANT:** If an action by that name is already registered, the current
 * call does nothing, even if the remaining arguments differ.
 *
 * @param name      The name of the action. Should be in kebab-case.
 * @param newAction Called for every action specification for a trigger
 *                  parsed by {@link Triggers.registerTrigger}
 */
export const registerAction = (name, newAction, configValidator) => {
  if (registeredActions.has(name)) {
    return;
  }
  const newActionFromSpec = async (element, argsAndOptions) => {
    const thisConfigValidator = MH.isFunction(configValidator) ? await configValidator(element) : configValidator;
    const args = [];

    // In general, if an action accepts a boolean *option* (not argument), it
    // may not be followed by a =value. So we pass the full string to the
    // fetchWidgetConfig which will parse such boolean options if they are
    // defined in the config validator.
    const config = thisConfigValidator ? await fetchWidgetConfig(argsAndOptions, thisConfigValidator, ARG_SEP_CHAR) : undefined;
    for (const entry of splitOn(argsAndOptions, ARG_SEP_CHAR, true)) {
      if (entry) {
        if (!MH.includes(entry, "=") && !(config && entry in config)) {
          args.push(entry);
        }
      }
    }
    return newAction(element, args, config);
  };
  registeredActions.set(name, newActionFromSpec);
};

/**
 * Returns an {@link Action} registered under the given name and instantiated
 * with the given element and arguments and options parsed from the given string.
 *
 * @throws {@link Errors.LisnUsageError | LisnUsageError}
 *                If the given spec is not valid.
 */
export const fetchAction = async (element, name, argsAndOptions) => {
  const newActionFromSpec = registeredActions.get(name);
  if (!newActionFromSpec) {
    throw MH.usageError(`Unknown action '${name}'`);
  }
  return await newActionFromSpec(element, argsAndOptions !== null && argsAndOptions !== void 0 ? argsAndOptions : "");
};

// --------------------

const ARG_SEP_CHAR = ",";
const registeredActions = MH.newMap();
//# sourceMappingURL=action.js.map