gradum-kit - v0.1.0
    Preparing search index...

    Class GradumSelector<Type>

    GradumSelector

    Selector class that wraps an object and augments it with useful functions to manipulate it. It also proxies the object, so you can access properties and methods on the underlying object directly through the selector.

    Type Parameters

    • Type extends object = Node

      The type of the object it wraps.

    Hierarchy

    • Node
      • GradumSelector
    Index
    constructor
    constrainersNames activeConstrainers
    element
    defaultFeedforwardProperties
    boundListeners bypassManagerOn
    childHandler childNodesArray childrenArray siblingNodes siblings
    mvc model view emitter data dataId dataIndex dataSize operators handlers interactors tools constrainers
    reifects showTransition isShown
    closestRoot selected defaultSelectedClasses onSelected
    metadata
    addClass removeClass toggleClass hasClass
    makeConstrainer activateConstrainer deactivateConstrainer toggleConstrainer activateOnlyConstrainer activateAllConstrainers deactivateAllConstrainers onConstrainerActivate onConstrainerDeactivate getConstrainerPriority setConstrainerPriority getConstrainerObjectList onConstrainerObjectListChange getConstrainerTriggerList getConstrainerQueue getDefaultConstrainerQueue setDefaultConstrainerQueue getObjectPassesForConstrainer getMaxPassesForConstrainer setMaxPassesForConstrainer getObjectDataForConstrainer setObjectDataForConstrainer addChecker removeChecker clearCheckers checkConstrainer checkConstrainersForEvent addMutator removeMutator clearMutators mutate addSolver removeSolver clearSolvers solveConstrainer solveConstrainersForEvent
    setProperties getFields clone destroy setAttribute removeAttribute blur focus feedforward
    on onTool executeAction hasListener hasToolListener hasListenersByType removeListener removeToolListener removeListenersByType removeAllListeners preventDefault
    bringToFront sendToBack remove addToParent addChild remChild addChildBefore removeChildAt removeAllChildren childAt indexOfChild hasChild findInSubTree findInParents indexInParent closest
    execute apply removeFields getDefaults getIntersection getDifference extract applyDefaults
    setMvc initializeMvc getMvcDifference getOperator addOperator removeOperator getHandler addHandler removeHandler getInteractor addInteractor removeInteractor getTool addTool removeTool getConstrainer addConstrainer removeConstrainer
    show attachReifect detachReifect initializeReifect applyReifect toggleReifect reloadReifects reloadReifectsChainableStyles reifectEnabledState enableReifect
    setStyle appendStyle setStyles
    makeTool isTool getToolNames getToolName onToolActivate onToolDeactivate addToolBehavior hasToolBehavior removeToolBehaviors applyTool clearToolBehaviors embedTool isEmbeddedTool getEmbeddedToolTarget ignoreTool ignoreAllTools isToolIgnored

    • Type Parameters

      • Type extends object = Node

        The type of the object it wraps.

      Returns GradumSelector<Type>

      Create a bare selector. Prefer gradum (or g, gr, $), which caches one selector per target and wires up GradumSelector.element for you. The instance returned is a proxy, so properties not found on the selector fall through to the wrapped object.

    constrainersNames: string[]

    Array of all the constrainers attached to this element.

    activeConstrainers: string[]

    Array of active constrainers on this element.

    element: Type

    The underlying, wrapped object. Every method on the selector reads and writes through it.

    defaultFeedforwardProperties: GradumElementProperties

    The properties passed on to children created through GradumSelector.feedforward, letting a parent seed its descendants with shared defaults.

    boundListeners: ListenerSet

    Readonly set of listeners bound to this node.

    bypassManagerOn: (e: Event) => boolean | GradumEventManagerStateProperties

    If you want the element to bypass the event manager and allow native events to seep through (in case you are preventing default events), you can set this field to a predicate that defines when to bypass the manager according to the passed event.

    childHandler: ChildHandler

    The child handler object associated with the node. It is the node itself (if it is handling its children) or its shadow root (if defined). Set it to change the node where the children are added/ removed/queried from when manipulating the node's children.

    childNodesArray: Node[]

    Static array of all the child nodes of the node.

    childrenArray: Element[]

    Static array of all the child elements of the node.

    siblingNodes: Node[]

    Static array of all the sibling nodes (including the node itself) of the node.

    siblings: Element[]

    Static array of all the sibling elements (including the element itself, if it is one) of the node.

    mvc: MvcProperties

    Every MVC piece bound to the element — its view, model, emitter, and the operator, handler, interactor, tool, and constrainer collections — in one object.

    model: any

    The model of the element's MVC structure.

    view: any

    The view of the element's MVC structure.

    emitter: any

    The emitter of the element's MVC structure.

    data: any

    The main data block attached to the element's model.

    dataId: string

    The ID of the main data block of the element's model.

    dataIndex: number

    The numerical index of the main data block of the element's model.

    dataSize: number

    The size (number) of the main data block of the element's model.

    operators: GradumOperator<
        object,
        GradumView<
            any,
            any,
            GradumEmitter<GradumModel<any, any, any, any, any>, KeyType>,
        >,
        GradumModel<any, any, any, any, any>,
        GradumEmitter<GradumModel<any, any, any, any, any>, KeyType>,
    >[]

    The operators of the element's MVC structure.

    handlers: GradumHandler<GradumModel<any, any, any, any, any>>[]

    The handlers attached to the element's model. Returns an empty array if no model is set.

    interactors: GradumInteractor<
        object,
        GradumView<
            any,
            any,
            GradumEmitter<GradumModel<any, any, any, any, any>, KeyType>,
        >,
        GradumModel<any, any, any, any, any>,
        GradumEmitter<GradumModel<any, any, any, any, any>, KeyType>,
    >[]

    The interactors of the element's MVC structure.

    tools: GradumTool<
        object,
        GradumView<
            any,
            any,
            GradumEmitter<GradumModel<any, any, any, any, any>, KeyType>,
        >,
        GradumModel<any, any, any, any, any>,
        GradumEmitter<GradumModel<any, any, any, any, any>, KeyType>,
    >[]

    The tools of the element's MVC structure.

    constrainers: GradumConstrainer<
        object,
        GradumView<
            any,
            any,
            GradumEmitter<GradumModel<any, any, any, any, any>, KeyType>,
        >,
        GradumModel<any, any, any, any, any>,
        GradumEmitter<GradumModel<any, any, any, any, any>, KeyType>,
    >[]

    The constrainers of the element's MVC structure.

    reifects: Set<StatefulReifect<any, object>>

    Readonly shallow set of the reifects attached to this object.

    showTransition: StatefulReifect<Shown>

    The transition used by the element's show() and isShown methods. Directly modifying its value will modify all elements' default showTransition. Unless this is the desired outcome, set it to a new custom StatefulReifect.

    isShown: boolean

    Boolean indicating whether the element is shown or not, based on its showTransition.

    closestRoot: StylesRoot

    The closest root to the element in the document (the closest ShadowRoot, or the document's head).

    selected: boolean

    Whether the element is selected or not. Setting it on an Element will accordingly toggle on it the "selected" CSS class (or whichever default selected class was set for this element) and update the UI.

    defaultSelectedClasses: string | string[]

    The CSS classes applied when the element is selected. Assigning a new value moves the classes over if the element is currently selected.

    onSelected: Delegate<(value: boolean) => void>

    Delegate fired whenever the element's selected state changes. Receives the new state.

    • get metadata(): GradumModel<object>

      Returns GradumModel<object>

      A key-value store attached to the element, backed by its own GradumModel and created on first read — so it is available whether or not the element has a model of its own. Use it for flags that tools and behaviors read off an element: selectable, dragAndDroppable, and the like. Assigning a plain object replaces the store's contents; assigning a model adopts it.

      Reads participate in effect tracking once a signal exists for the key, so metadata.makeSignal("flag") at setup makes metadata.get("flag") reactive inside an @effect.

    • set metadata(value: object | GradumModel<object, any, any, any, any>): void

      Parameters

      • value: object | GradumModel<object, any, any, any, any>

      Returns void

    • Parameters

      • Optionalclasses: string | string[]

        String of classes separated by spaces, or array of strings.

      Returns this

      Itself, allowing for method chaining.

      Add one or more CSS classes to the element.

    • Parameters

      • Optionalclasses: string | string[]

        String of classes separated by spaces, or array of strings.

      Returns this

      Itself, allowing for method chaining.

      Remove one or more CSS classes from the element.

    • Parameters

      • Optionalclasses: string | string[]

        String of classes separated by spaces, or array of strings.

      • Optionalforce: boolean

        (Optional) Boolean that turns the toggle into a one way-only operation. If set to false, then the class will only be removed, but not added. If set to true, then token will only be added, but not removed.

      Returns this

      Itself, allowing for method chaining.

      Toggle one or more CSS classes in the element.

    • Parameters

      • Optionalclasses: string | string[]

        String of classes separated by spaces, or array of strings.

      Returns boolean

      Whether the element carries every one of the given classes.

      Check if the element's class list contains the provided class(es).

    • Function

      makeConstrainer

      Parameters

      • name: string

        The name of the new constrainer.

      • Optionaloptions: MakeConstrainerOptions

        Options parameter to configure the newly-created constrainer.

      Returns this

      Itself for chaining.

      Creates a new constrainer attached to this element. Useful to maintain certain constraints or ensure some behaviors persist on a list of objects (by attaching solvers to this constrainer).

    • Function

      activateConstrainer

      Parameters

      • ...constrainers: string[]

        The name of the constrainer(s) to activate. Defaults to the first active constrainer.

      Returns this

      Itself for chaining.

      Activate the given constrainer.

    • Function

      deactivateConstrainer

      Parameters

      • ...constrainers: string[]

        The name of the constrainer(s) to deactivate. Defaults to the first active constrainer.

      Returns this

      Itself for chaining.

      Deactivate the given constrainer.

    • Function

      toggleConstrainer

      Parameters

      • Optionalconstrainer: string

        The name of the constrainer to toggle. Defaults to the first active constrainer.

      • Optionalforce: boolean

        If set, the constrainer's active state will be set to this value.

      Returns this

      Itself for chaining.

      Toggle the active state of the given constrainer.

    • Function

      activateOnlyConstrainer

      Parameters

      • constrainer: string

        The constrainer name to activate as the single active constrainer. Defaults to the first active constrainer.

      Returns this

      Itself for chaining.

      Activate the provided constrainer and deactivate all other constrainers attached to this element.

    • Function

      activateAllConstrainers

      Returns this

      Itself for chaining.

      Activate all the constrainers attached to this element.

    • Function

      deactivateAllConstrainers

      Returns this

      Itself for chaining.

      Deactivate all the constrainers attached to this element.

    • Function

      onConstrainerActivate

      Parameters

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns Delegate<() => void>

      The delegate.

      Get the delegate fired when the constrainer of the given name is activated.

    • Function

      onConstrainerDeactivate

      Parameters

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns Delegate<() => void>

      The delegate.

      Get the delegate fired when the constrainer of the given name is deactivated.

    • Function

      getConstrainerPriority

      Parameters

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns number

      The constrainer priority.

      Get the priority of the targeted constrainer. Higher priority constrainers (lower number) should be resolved first.

    • Function

      setConstrainerPriority

      Parameters

      • priority: number

        The priority value to set.

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns this

      Itself for chaining.

      Set the priority of the targeted constrainer. Higher priority constrainers (lower number) should be resolved first.

    • Function

      getConstrainerObjectList

      Parameters

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns GradumNodeList

      The list of objects. To manipulate, check GradumNodeList.

      Retrieve the list of objects that are constrained by the given constrainer.

    • Function

      onConstrainerObjectListChange

      Parameters

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns Delegate<(object: object, status: "added" | "removed") => void>

      The delegate.

      Get the delegate fired whenever an object is added to or removed from the constrainer's object list. Defaults to the children of the element the constrainer is attached to.

    • Function

      getConstrainerTriggerList

      Parameters

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns GradumNodeList

      The list of trigger objects. To manipulate, check GradumNodeList.

      Retrieve the list of objects that trigger the given constrainer to resolve. Interacting with any of these objects would typically lead to the solving of the given constrainer. Defaults to the constrainer's object list.

    • Function

      getConstrainerQueue

      Parameters

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns GradumQueue<object>

      The current constrainer queue.

      Retrieve the current queue to be processed by the constrainer while resolving.

    • Function

      getDefaultConstrainerQueue

      Parameters

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns GradumQueue<object>

      The default constrainer queue.

      Retrieve the default queue template for the constrainer, used when starting a new resolving pass. It defaults to the constrainer's object list.

    • Function

      setDefaultConstrainerQueue

      Parameters

      • queue: GradumQueue<object> | object[]

        The queue (or list to build a queue from).

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns this

      Itself for chaining.

      Define the default queue template for the constrainer, used when starting a new resolving pass.

    • Function

      getObjectPassesForConstrainer

      Parameters

      • object: object

        The object to query.

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns number

      Number of passes already performed on this object.

      Retrieve how many times the given object has been processed for the current resolving session of the constrainer.

    • Function

      getMaxPassesForConstrainer

      Parameters

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns number

      The maximum allowed passes.

      Get the maximum number of passes allowed per object for this constrainer during resolving. This helps prevent infinite cycles in constraint propagation.

    • Function

      setMaxPassesForConstrainer

      Parameters

      • passes: number

        Maximum number of passes.

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns this

      Itself for chaining.

      Set the maximum number of passes allowed per object for this constrainer during resolving. This helps prevent infinite cycles in constraint propagation.

    • Function

      getObjectDataForConstrainer

      Parameters

      • object: object

        The object to query.

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns Record<string, any>

      The stored data object (or an empty object if none).

      Retrieve custom per-object data for this constrainer. It is reset on every new resolving session.

    • Function

      setObjectDataForConstrainer

      Parameters

      • object: object

        The object to update.

      • Optionaldata: Record<string, any>

        The new data object to associate with this object.

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns this

      Itself for chaining.

      Set custom per-object data for this constrainer. It is reset on every new resolving session.

    • Function

      addChecker

      Parameters

      • properties: ConstrainerAddCallbackProperties<ConstrainerChecker>

        Configuration object, including the checker callback to be executed, the name of the checker to access it later, the name of the attached constrainer, and the priority of the checker.

      Returns this

      Itself for chaining.

      Register a checker in the constrainer. Checkers dictate whether the event should continue executing depending on the provided context (event, tool, target, etc.).

    • Function

      removeChecker

      Parameters

      • name: string

        The checker name.

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns this

      Itself for chaining.

      Remove a checker from the given constrainer by its name.

    • Function

      clearCheckers

      Parameters

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns this

      Itself for chaining.

      Remove all checkers attached to the given constrainer.

    • Function

      checkConstrainer

      Parameters

      Returns boolean

      Whether the constrainer passes all checks.

      Evaluate all checkers for the targeted constrainer and return whether the event should proceed or halt.

    • Function

      checkConstrainersForEvent

      Parameters

      Returns boolean

      Whether all the checkers allowed the event to proceed.

      Evaluate checkers for all relevant constrainers for a given event context.

    • Function

      addMutator

      Parameters

      • properties: ConstrainerAddCallbackProperties<ConstrainerMutator<any>>

        Configuration object, including the mutator callback to be executed, the name of the mutator to access it later, the name of the attached constrainer, and the priority of the mutator.

      Returns this

      Itself for chaining.

      Register a mutator in the constrainer. Mutators compute or transform a value based on the context.

    • Function

      removeMutator

      Parameters

      • name: string

        The mutator name.

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns this

      Itself for chaining.

      Remove a mutator from the given constrainer by its name.

    • Function

      clearMutators

      Parameters

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns this

      Itself for chaining.

      Remove all mutators attached to the given constrainer.

    • Function

      mutate

      Type Parameters

      • Type = any

        The type of the value to mutate

      Parameters

      Returns Type

      The mutated result.

      Execute a mutator for the targeted constrainer and return the resulting value.

    • Function

      addSolver

      Parameters

      • properties: ConstrainerAddCallbackProperties<ConstrainerSolver>

        Configuration object, including the solver callback to be executed, the name of the solver to access it later, the name of the attached constrainer, and the priority of the solver.

      Returns this

      Itself for chaining.

      Register a solver in the constrainer. Solvers typically execute after an event is fired to ensure the constrainer's constraints are maintained. They process all objects in the constrainer's queue, one after the other.

    • Function

      removeSolver

      Parameters

      • name: string

        The solver's name.

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns this

      Itself for chaining.

      Remove the given function from the constrainer's list of solvers.

    • Function

      clearSolvers

      Parameters

      • Optionalconstrainer: string

        The name of the targeted constrainer. Defaults to the first active constrainer.

      Returns this

      Itself for chaining.

      Remove all solvers attached to the constrainer.

    • Function

      solveConstrainer

      Parameters

      Returns this

      Itself for chaining.

      Solve the constrainer by executing all of its attached solvers. Each solver will be executed on every object in the constrainer's queue, incrementing its number of passes in the process.

    • Function

      solveConstrainersForEvent

      Parameters

      Returns this

      Itself for chaining.

      Solve all relevant constrainers for a given event context.

    • Function

      setProperties

      Type Parameters

      • Tag extends
            | "symbol"
            | "animate"
            | "animateMotion"
            | "animateTransform"
            | "circle"
            | "clipPath"
            | "defs"
            | "desc"
            | "ellipse"
            | "feBlend"
            | "feColorMatrix"
            | "feComponentTransfer"
            | "feComposite"
            | "feConvolveMatrix"
            | "feDiffuseLighting"
            | "feDisplacementMap"
            | "feDistantLight"
            | "feDropShadow"
            | "feFlood"
            | "feFuncA"
            | "feFuncB"
            | "feFuncG"
            | "feFuncR"
            | "feGaussianBlur"
            | "feImage"
            | "feMerge"
            | "feMergeNode"
            | "feMorphology"
            | "feOffset"
            | "fePointLight"
            | "feSpecularLighting"
            | "feSpotLight"
            | "feTile"
            | "feTurbulence"
            | "filter"
            | "foreignObject"
            | "g"
            | "image"
            | "line"
            | "linearGradient"
            | "marker"
            | "mask"
            | "metadata"
            | "mpath"
            | "path"
            | "pattern"
            | "polygon"
            | "polyline"
            | "radialGradient"
            | "rect"
            | "set"
            | "stop"
            | "svg"
            | "switch"
            | "text"
            | "textPath"
            | "tspan"
            | "use"
            | "view"
            | (keyof HTMLElementTagNameMap)
            | (keyof MathMLElementTagNameMap)
            | (keyof GradumElementTagNameMap)

        The HTML tag of the element (for accurate autocompletion of available properties).

      Parameters

      • properties: GradumProperties<Tag>

        The properties object.

      • OptionalsetOnlyBaseProperties: boolean

        If set to true, will only set the base gradum properties (classes, text, style, id, children, parent, etc.) and ignore all other properties not explicitly defined in GradumProperties.

      Returns this

      Itself, allowing for method chaining.

      Sets the declared properties to the element (if possible).

    • Returns Record<string, any>

      The element's fields, keyed by name.

      Read every own field of the element as a plain object, so it can be diffed or cloned.

    • Parameters

      Returns Type

      The cloned element.

      Create a copy of the element. By default the copy carries the same properties and children, but none of the bound listeners.

    • Returns this

      Itself, allowing for method chaining.

      Destroys the element by removing it from the document and removing all its bound listeners.

    • Parameters

      • name: string

        The name of the attribute.

      • Optionalvalue: string | number | boolean

        The value of the attribute. Can be left blank to represent a true boolean.

      Returns this

      Itself, allowing for method chaining.

      Sets the value of an attribute on the element.

    • Parameters

      • name: string

        The name of the attribute to remove.

      Returns this

      Itself, allowing for method chaining.

      Removes an attribute from the element.

    • Returns this

      Itself, allowing for method chaining.

      Causes the element to lose focus.

    • Returns this

      Itself, allowing for method chaining.

      Sets focus on the element.

    • Function

      on

      Type Parameters

      • Type extends Node

        The type of the element.

      Parameters

      • type: string

        The type of the event.

      • listener: ListenerCallback<Type>

        The function that receives a notification.

      • Optionaloptions: ListenerOptions

        An options object that specifies characteristics about the event listener.

      • Optionalmanager: GradumEventManager

        The associated event manager. Defaults to the first created manager, or a new instantiated one if none already exist.

      Returns this

      Itself, allowing for method chaining.

      Adds an event listener to the element.

    • Function

      onTool

      Type Parameters

      • Type extends Node

        The type of the element.

      Parameters

      • type: string

        The type of the event.

      • toolName: string

        The name of the tool. Set to null or undefined to check for listeners not bound to a tool.

      • listener: ListenerCallback<Type>

        The function that receives a notification.

      • Optionaloptions: ListenerOptions

        An options object that specifies characteristics about the event listener.

      • Optionalmanager: GradumEventManager

        The associated event manager. Defaults to the first created manager, or a new instantiated one if none already exist.

      Returns this

      Itself, allowing for method chaining.

      Adds an event listener to the element.

    • Function

      executeAction

      Parameters

      • type: string

        The type of the event.

      • toolName: string

        The name of the tool. Set to null or undefined to fire listeners not bound to a tool.

      • event: Event

        The event to pass as parameter to the listeners.

      • Optionaloptions: ListenerOptions

        Options object that specifies characteristics about the event listeners to fire.

      • Optionalmanager: GradumEventManager

        The associated event manager. Defaults to the first created manager, or a new instantiated one if none already exist.

      Returns Propagation

      Execute the listeners bound on this element for the given type and toolName. Simulates firing a type event on the element with toolName active.

    • Function

      hasListener

      Parameters

      • type: string

        The type of the event. Set to null or undefined to get all event types.

      • listener: ListenerCallback

        The function that receives a notification.

      • Optionalmanager: GradumEventManager

        The associated event manager. Defaults to the first created manager, or a new instantiated one if none already exist.

      Returns boolean

      Whether the element has the given listener.

      Checks if the given event listener is bound to the element (in its boundListeners list).

    • Function

      hasToolListener

      Parameters

      • type: string

        The type of the event. Set to null or undefined to get all event types.

      • toolName: string

        The name of the tool the listener is attached to. Set to null or undefined to check for listeners not bound to a tool.

      • listener: ListenerCallback

        The function that receives a notification.

      • Optionalmanager: GradumEventManager

        The associated event manager. Defaults to the first created manager, or a new instantiated one if none already exist.

      Returns boolean

      Whether the element has the given listener.

      Checks if the given event listener is bound to the element (in its boundListeners list).

    • Function

      hasListenersByType

      Parameters

      • type: string

        The type of the event. Set to null or undefined to get all event types.

      • OptionaltoolName: string

        The name of the tool to consider (if any). Set to null or undefined to check for listeners not bound to a tool.

      • Optionalmanager: GradumEventManager

        The associated event manager. Defaults to the first created manager, or a new instantiated one if none already exist.

      Returns boolean

      Whether the element has a listener of this type.

      Checks if the element has bound listeners of the given type (in its boundListeners list).

    • Function

      removeListener

      Parameters

      • type: string

        The type of the event.

      • listener: ListenerCallback

        The function that receives a notification.

      • Optionalmanager: GradumEventManager

        The associated event manager. Defaults to the first created manager, or a new instantiated one if none already exist.

      Returns this

      Itself, allowing for method chaining.

      Removes an event listener that is bound to the element (in its boundListeners list).

    • Function

      removeToolListener

      Parameters

      • type: string

        The type of the event.

      • toolName: string

        The name of the tool the listener is attached to. Set to null or undefined to check for listeners not bound to a tool.

      • listener: ListenerCallback

        The function that receives a notification.

      • Optionalmanager: GradumEventManager

        The associated event manager. Defaults to the first created manager, or a new instantiated one if none already exist.

      Returns this

      Itself, allowing for method chaining.

      Removes an event listener that is bound to the element (in its boundListeners list).

    • Function

      removeListenersByType

      Parameters

      • type: string

        The type of the event. Set to null or undefined to consider all types.

      • OptionaltoolName: string

        The name of the tool associated (if any). Set to null or undefined to check for listeners not bound to a tool.

      • Optionalmanager: GradumEventManager

        The associated event manager. Defaults to the first created manager, or a new instantiated one if none already exist.

      Returns this

      Itself, allowing for method chaining.

      Removes all event listeners bound to the element (in its boundListeners list) assigned to the specified type.

    • Function

      removeAllListeners

      Parameters

      • Optionalmanager: GradumEventManager

        The associated event manager. Defaults to the first created manager, or a new instantiated one if none already exist.

      Returns this

      Itself, allowing for method chaining.

      Removes all event listeners bound to the element (in its boundListeners list).

    • Parameters

      Returns this

      Prevent default browser behavior on the provided event types. By default, all basic input events will be processed.

    • Function

      bringToFront

      Returns this

      Itself for chaining.

      Brings the element to the front amongst its siblings in the DOM.

    • Function

      sendToBack

      Returns this

      Itself for chaining.

      Sends the element to the back amongst its siblings in the DOM.

    • Function

      remove

      Returns this

      Itself, allowing for method chaining.

      Removes the node from the document.

    • Function

      addToParent

      Parameters

      • parent: Node

        The parent node to attach the element to.

      • Optionalindex: number

        The position at which to add the element relative to the parent's child list. Leave undefined to add the element at the end.

      • OptionalreferenceList: Node[] | NodeListOf<Node>

        The child list to use as computation reference for index placement. Defaults to the parent's childrenArray.

      Returns this

      Itself, allowing for method chaining.

      Add the element to the given parent node

    • Function

      addChild

      Parameters

      • Optionalchildren: Node | Node[]

        Array of (or single) child nodes.

      • Optionalindex: number

        The position at which to add the child relative to the parent's child list. Leave undefined to add the child at the end.

      • OptionalreferenceList: Node[] | NodeListOf<Node>

        The child list to use as computation reference for index placement. Defaults to the node's childrenArray.

      Returns this

      Itself, allowing for method chaining.

      Add one or more children to the element.

    • Function

      remChild

      Parameters

      • Optionalchildren: Node | Node[]

        Array of (or single) child nodes.

      Returns this

      Itself, allowing for method chaining.

      Remove one or more children from the element.

    • Function

      addChildBefore

      Parameters

      • Optionalchildren: Node | Node[]

        Array of (or single) child nodes to insert before sibling.

      • Optionalsibling: Node

        The sibling node to insert the children before.

      Returns this

      Itself, allowing for method chaining.

      Add one or more children to the element before the provided sibling. If the sibling is not found in the parent's children, the nodes will be added to the end of the parent's child list.

    • Function

      removeChildAt

      Parameters

      • Optionalindex: number

        The index of the child(ren) to remove.

      • Optionalcount: number

        The number of children to remove.

      • OptionalreferenceList: Node[] | NodeListOf<Node>

        The child list to use as computation reference for index placement and count. Defaults to the node's childrenArray.

      Returns this

      Itself, allowing for method chaining.

      Remove one or more child nodes from the element.

    • Function

      removeAllChildren

      Parameters

      • OptionalreferenceList: Node[] | NodeListOf<Node>

        The child list to representing all the nodes to remove. Defaults to the node's childrenArray.

      Returns this

      Itself, allowing for method chaining.

      Remove all children of the node.

    • Function

      childAt

      Parameters

      • Optionalindex: number

        The index of the child to retrieve.

      • OptionalreferenceList: Node[] | NodeListOf<Node>

        The child list to use as computation reference for index placement. Defaults to the node's childrenArray.

      Returns Node

      The child at the given index, or null if the index is invalid.

      Returns the child of the parent node at the given index. Any number inputted (including negatives) will be reduced modulo length of the list size.

    • Function

      indexOfChild

      Parameters

      • Optionalchild: Node

        The child element to find.

      • OptionalreferenceList: Node[] | NodeListOf<Node>

        The child list to use as computation reference for index placement. Defaults to the node's childrenArray.

      Returns number

      The index of the child node in the provided list, or -1 if the child is not found.

      Returns the index of the given child.

    • Function

      hasChild

      Parameters

      • Optionalchildren: Node | Node[]

        Array of (or single) child nodes.

      Returns boolean

      A boolean indicating whether the provided nodes belong to the parent or not.

      Identify whether one or more children belong to this parent node.

    • Function

      findInSubTree

      Parameters

      • Optionalchildren: Node | Node[]

        The child or children to check.

      Returns boolean

      True if the children belong to the node, false otherwise.

      Finds whether one or more children belong to this node.

    • Function

      findInParents

      Parameters

      • Optionalparents: Node | Node[]

        The parent(s) to check.

      Returns boolean

      True if the node is within the given parents, false otherwise.

      Finds whether this node is within the given parent(s).

    • Function

      indexInParent

      Parameters

      • OptionalreferenceList: Node[]

        The siblings list to use as computation reference for index placement. Defaults to the node's siblings.

      Returns number

      True if the children belong to the node, false otherwise.

      Finds whether one or more children belong to this node.

    • Function

      closest

      Type Parameters

      • Tag extends
            | "symbol"
            | "animate"
            | "animateMotion"
            | "animateTransform"
            | "circle"
            | "clipPath"
            | "defs"
            | "desc"
            | "ellipse"
            | "feBlend"
            | "feColorMatrix"
            | "feComponentTransfer"
            | "feComposite"
            | "feConvolveMatrix"
            | "feDiffuseLighting"
            | "feDisplacementMap"
            | "feDistantLight"
            | "feDropShadow"
            | "feFlood"
            | "feFuncA"
            | "feFuncB"
            | "feFuncG"
            | "feFuncR"
            | "feGaussianBlur"
            | "feImage"
            | "feMerge"
            | "feMergeNode"
            | "feMorphology"
            | "feOffset"
            | "fePointLight"
            | "feSpecularLighting"
            | "feSpotLight"
            | "feTile"
            | "feTurbulence"
            | "filter"
            | "foreignObject"
            | "g"
            | "image"
            | "line"
            | "linearGradient"
            | "marker"
            | "mask"
            | "metadata"
            | "mpath"
            | "path"
            | "pattern"
            | "polygon"
            | "polyline"
            | "radialGradient"
            | "rect"
            | "set"
            | "stop"
            | "svg"
            | "switch"
            | "text"
            | "textPath"
            | "tspan"
            | "use"
            | "view"
            | (keyof HTMLElementTagNameMap)
            | (keyof MathMLElementTagNameMap)
            | (keyof GradumElementTagNameMap)

      Parameters

      • type: Tag

        The (valid) tag name.

      Returns ValidElement<Tag>

      The matching ancestor element, or null if no match is found.

      Finds the closest ancestor of the current element (or the current element itself) that matches that is an instance of the element associated with the given tag name.

    • Function

      closest

      Type Parameters

      • Tag extends string

      Parameters

      • type: Tag

        The (valid) CSS selector string.

      Returns Element

      The matching ancestor element, or null if no match is found.

      Finds the closest ancestor of the current element (or the current element itself) that matches the provided CSS selector.

    • Function

      closest

      Type Parameters

      • Type extends Element

        The type of element to find.

      Parameters

      • type: new (...args: any[]) => Type

        The class to match.

      Returns Type

      The matching ancestor element, or null if no match is found.

      Finds the closest ancestor of the current element (or the current element itself) that is an instance of the given class.

    • Parameters

      • callback: (el: this) => void

        The function to execute, with 1 parameter representing the instance itself.

      Returns this

      Itself, allowing for method chaining.

      Execute a callback on the node while still benefiting from chaining.

    • Parameters

      Returns this

      Itself, allowing for method chaining.

      Assign every given property onto the element, overwriting existing values.

    • Parameters

      • keys: (string | keyof Type)[]

        The field names to remove.

      Returns this

      Itself, allowing for method chaining.

      Delete the given fields from the element.

    • Parameters

      • defaults: (string | keyof Type)[]

        The field names to read.

      Returns Partial<Type> & Record<string, any>

      The current value of each requested field.

      Read the element's current values for the given keys, to capture them before overwriting.

    • Parameters

      Returns Partial<Type> & Record<string, any>

      The shared fields. Neither input is modified.

      The fields the element and the given object both have, with the element's values.

    • Parameters

      Returns Partial<Type> & Record<string, any>

      The differing fields. Neither input is modified.

      The fields where the element and the given object disagree, with the element's values.

    • Parameters

      • keys: (string | keyof Type)[]

        The field names to extract.

      Returns Partial<Type> & Record<string, any>

      The requested fields and their values.

      Read the given fields off the element into a plain object, leaving the element unchanged.

    • Function

      applyDefaults

      Parameters

      Returns this

      The same selector instance for chaining.

      Apply default properties to the underlying object, with optional smart merging for array-like keys. By default, merging will happen on all MVC properties that accept arrays (like operators, handlers, tools, etc.) to allow for concatenation of such MVC pieces.

      const properties = {...};
      gradum(properties).applyDefaults({
        tag: "my-el",
        view: MyElementView,
        tools: [selectTool, panTool],
        operators: KeyboardOperator
      });
    • Function

      setMvc

      Parameters

      Returns this

      Itself, allowing for method chaining.

      Configures the MVC structure for the element. Sets the provided MVC pieces (model, view, emitter, operators, handlers, interactors, tools, constrainers) on the element, initializes a default emitter if none is provided, and initializes all MVC pieces unless explicitly disabled.

    • Function

      initializeMvc

      Returns this

      Itself, allowing for method chaining.

      Initializes all MVC pieces attached to the element, in the following order: view, operators, interactors, tools, constrainers, and model. The model is initialized last to allow the view and operators to set up their change callbacks first.

    • Function

      getOperator

      Parameters

      • key: string

        The operator's key.

      Returns GradumOperator

      The operator.

      Retrieves the attached MVC operator with the given key.

    • Function

      addOperator

      Parameters

      Returns this

      Itself, allowing for method chaining.

      Adds the given operator to the element's MVC structure.

    • Function

      removeOperator

      Parameters

      Returns this

      Itself, allowing for method chaining.

      Removes the given operator from the element's MVC structure and unlinks it.

    • Function

      getHandler

      Parameters

      • key: string

        The handler's key.

      Returns GradumHandler

      The handler.

      Retrieves the attached MVC handler with the given key. Returns undefined if no model is set.

    • Function

      addHandler

      Parameters

      Returns this

      Itself, allowing for method chaining.

      Adds the given handler to the element's model. If no model is set, this operation is a no-op.

    • Function

      removeHandler

      Parameters

      Returns this

      Itself, allowing for method chaining.

      Removes the given handler from the element's model and unlinks it. If no model is set, this operation is a no-op.

    • Function

      getInteractor

      Parameters

      • key: string

        The interactor's key.

      Returns GradumInteractor

      The interactor.

      Retrieves the attached MVC interactor with the given key.

    • Function

      addInteractor

      Parameters

      Returns this

      Itself, allowing for method chaining.

      Adds the given interactor to the element's MVC structure.

    • Function

      removeInteractor

      Parameters

      Returns this

      Itself, allowing for method chaining.

      Removes the given interactor from the element's MVC structure and unlinks it.

    • Function

      getTool

      Parameters

      • key: string

        The tool's key.

      Returns GradumTool

      The tool.

      Retrieves the attached MVC tool with the given key.

    • Function

      addTool

      Parameters

      Returns this

      Itself, allowing for method chaining.

      Adds the given tool to the element's MVC structure.

    • Function

      removeTool

      Parameters

      Returns this

      Itself, allowing for method chaining.

      Removes the given tool from the element's MVC structure and unlinks it.

    • Function

      getConstrainer

      Parameters

      • key: string

        The constrainer's key.

      Returns GradumConstrainer

      The constrainer.

      Retrieves the attached MVC constrainer with the given key.

    • Function

      addConstrainer

      Parameters

      Returns this

      Itself, allowing for method chaining.

      Adds the given constrainer to the element's MVC structure.

    • Function

      removeConstrainer

      Parameters

      Returns this

      Itself, allowing for method chaining.

      Removes the given constrainer from the element's MVC structure and unlinks it.

    • Parameters

      • b: boolean

        Whether to show the element.

      • Optionaloptions: ReifectAppliedOptions<Shown>

        Options controlling how the transition is applied.

      Returns this

      Itself, allowing for method chaining.

      Show or hide the element (based on CSS) by transitioning in/out of the element's showTransition.

    • Function

      attachReifect

      Parameters

      Returns this

      Itself, allowing for method chaining.

      Attach one or more reifects to the object.

    • Function

      detachReifect

      Parameters

      Returns this

      Itself, allowing for method chaining.

      Detach one or more reifects from the object.

    • Function

      initializeReifect

      Type Parameters

      • State extends string | number | symbol

        The type of the reifect's states.

      Parameters

      • Optionalreifect: StatefulReifect<State>

        The reifect to initialize.

      • Optionalstate: State

        The state to initialize to (if the reifect is not stateless).

      • Optionaloptions: ReifectAppliedOptions<State>

        Optional overrides for the default values. Set to null to not set anything on the object.

      Returns this

      Itself, allowing for method chaining.

      Initializes the reifect at the given state for the corresponding object.

    • Function

      applyReifect

      Type Parameters

      • State extends string | number | symbol

        The type of the reifect's states.

      Parameters

      • reifect: StatefulReifect<State>

        The reifect to apply.

      • Optionalstate: State

        The state to initialize to (if the reifect is not stateless).

      • Optionaloptions: ReifectAppliedOptions<State>

        Optional overrides for the default values. Set to null to not set anything on the object.

      Returns this

      Itself, allowing for method chaining.

      Applies the reifect at the given state for the corresponding object.

    • Function

      toggleReifect

      Type Parameters

      • State extends string | number | symbol

        The type of the reifect's states.

      Parameters

      Returns this

      Itself, allowing for method chaining.

      Toggles the reifect to the next state for the corresponding object.

    • Function

      reloadReifects

      Returns this

      Itself, allowing for method chaining.

      Reloads all reifects attached to this object. Doesn't recompute values.

    • Function

      reloadReifectsChainableStyles

      Parameters

      • OptionalapplyInstantly: boolean

      Returns this

      Itself, allowing for method chaining.

      Reloads all transitions attached to this object. Doesn't recompute values.

    • Function

      reifectEnabledState

      Parameters

      Returns ReifectEnabledObject

      The enabled state.

      Get the reifect enabled state of this object. If a reifect is provided, the enabled state of the object for this specific reifect will be returned. otherwise, the global state of the object will be returned.

    • Function

      enableReifect

      Parameters

      Returns this

      Itself, allowing for method chaining.

      Set the reifect enabled state of this object. If a reifect is provided, the enabled state of the object for this specific reifect will be updated. otherwise, the global state of the object will be updated

    • Function

      setStyle

      Parameters

      • attribute: keyof CSSStyleDeclaration

        A string representing the style attribute to set.

      • value: string | number

        THe value to append.

      • Optionalinstant: boolean

        If true, will set the fields directly. Otherwise, will set them on next animation frame.

      Returns this

      Itself, allowing for method chaining.

      Set a certain style attribute of the element to the provided value.

    • Function

      appendStyle

      Parameters

      • attribute: keyof CSSStyleDeclaration

        A string representing the style attribute to append to.

      • value: string | number

        The value to append.

      • Optionalseparator: string

        The separator to use between the existing and new values.

      • Optionalinstant: boolean

        If true, will set the fields directly. Otherwise, will set them on next animation frame.

      Returns this

      Itself, allowing for method chaining.

      Append the provided value to a certain style attribute.

    • Function

      setStyles

      Parameters

      • styles: StylesType

        Acceptable styles to set.

      • Optionalinstant: boolean

        If true, will set the fields directly. Otherwise, will set them on next animation frame.

      Returns this

      Itself, allowing for method chaining.

      Parses and applies the given CSS to the element's inline styles.

    • Function

      makeTool

      Parameters

      • toolName: string

        The unique name of the tool to register under the manager. Reusing an existing toolName will make this element another instance of toolName.

      • Optionaloptions: MakeToolOptions

        Tool creation options (custom activation, click mode, key mapping, manager).

      Returns this

      Itself for chaining.

      Turns the element into a tool identified by toolName, optionally wiring activation and key mapping. By default, this function also sets up an event listener on the element to activate the tool on click. This behavior can be overridden via the options parameter.

    • Function

      isTool

      Parameters

      • Optionalmanager: GradumEventManager

        The associated event manager (defaults to GradumEventManager.instance).

      Returns boolean

      True if the element is a tool, false otherwise.

      Whether this element is registered as a tool for the provided manager.

    • Function

      getToolNames

      Parameters

      • Optionalmanager: GradumEventManager

        The associated event manager (defaults to GradumEventManager.instance).

      Returns string[]

      The list of tool names.

      Returns all tool names registered on this element for the provided manager.

    • Function

      getToolName

      Parameters

      • Optionalmanager: GradumEventManager

        The associated event manager (defaults to GradumEventManager.instance).

      Returns string

      The first tool name, if any.

      Returns the first registered tool name on this element for the provided manager.

    • Function

      onToolActivate

      Parameters

      • OptionaltoolName: string

        The name of the tool.

      • Optionalmanager: GradumEventManager

        The associated event manager (defaults to GradumEventManager.instance).

      Returns Delegate<() => void>

      The delegate.

      Retrieve the delegate fired when this tool is activated in the corresponding manager.

    • Function

      onToolDeactivate

      Parameters

      • OptionaltoolName: string

        The name of the tool.

      • Optionalmanager: GradumEventManager

        The associated event manager (defaults to GradumEventManager.instance).

      Returns Delegate<() => void>

      The delegate.

      Retrieve the delegate fired when this tool is deactivated in the corresponding manager.

    • Function

      addToolBehavior

      Parameters

      • type: string

        The type of the event (e.g., "pointerdown", "click", custom gradum event).

      • callback: ToolBehaviorCallback

        The behavior function. Return true to stop propagation.

      • OptionaltoolName: string

        Tool name to bind the behavior to. Defaults to this element's first tool.

      • Optionalmanager: GradumEventManager

        The associated event manager (defaults to GradumEventManager.instance).

      Returns this

      Itself for chaining.

      Adds a behavior callback for a given tool and a given type. This callback will attempt to be executed on the target element when a type event is fired and toolName is active. It is applied to all instances of the tool.

    • Function

      hasToolBehavior

      Parameters

      • type: string

        The type of the event (e.g., "pointerdown", "click", custom gradum event).

      • OptionaltoolName: string

        The tool name to check under. Defaults to this element's first tool.

      • Optionalmanager: GradumEventManager

        The associated event manager (defaults to GradumEventManager.instance).

      Returns boolean

      True if one or more behaviors are registered.

      Checks whether there is at least one tool behavior for the pair "type, toolName."

    • Function

      removeToolBehaviors

      Parameters

      • type: string

        The type of the event (e.g., "pointerdown", "click", custom gradum event).

      • OptionaltoolName: string

        The tool name whose behaviors will be removed. Defaults to this element's first tool.

      • Optionalmanager: GradumEventManager

        The associated event manager (defaults to GradumEventManager.instance).

      Returns this

      Itself for chaining.

      Removes all behaviors for the pair "type, toolName" under the given manager.

    • Function

      applyTool

      Parameters

      • toolName: string

        The name of the tool whose behaviors should run.

      • type: string

        The type of the event (e.g., "pointerdown", "click", custom gradum event).

      • event: Event

        The triggering event instance.

      • Optionalmanager: GradumEventManager

        The associated event manager (defaults to GradumEventManager.instance).

      Returns Propagation

      True if at least one behavior returned true (to stop propagation of the event).

      Executes all behaviors registered for the pair "type, toolName" against this element.

    • Function

      clearToolBehaviors

      Parameters

      • Optionalmanager: GradumEventManager

        The associated event manager (defaults to GradumEventManager.instance).

      Returns this

      Itself for chaining.

      Clears all registered behaviors for the tools attached to this element.

    • Function

      embedTool

      Parameters

      • target: Node

        The node to manipulate when interacting with the tool element itself.

      • Optionalmanager: GradumEventManager

        The associated manager (defaults to GradumEventManager.instance).

      Returns this

      Itself for chaining.

      Embeds this tool into a target node, so all interactions on the tool element apply to the defined target.

    • Function

      isEmbeddedTool

      Parameters

      • Optionalmanager: GradumEventManager

        The associated manager (defaults to GradumEventManager.instance).

      Returns boolean

      True if an embedded target is present.

      Whether this tool is embedded under the provided manager.

    • Function

      getEmbeddedToolTarget

      Parameters

      • Optionalmanager: GradumEventManager

        The associated manager (defaults to GradumEventManager.instance).

      Returns Node

      The embedded tool's target node, if any.

      Returns the target node for this embedded tool under the provided manager.

    • Function

      ignoreTool

      Parameters

      • toolName: string

        The name of the tool to ignore.

      • Optionaltype: string

        The type of the event. If undefined, all event types will be considered.

      • Optionalignore: boolean

        Whether to ignore the tool. Defaults to true.

      • Optionalmanager: GradumEventManager

        The associated manager (defaults to GradumEventManager.instance).

      Returns this

      Itself for chaining.

      Make the current element ignore the provided tool, so interacting with the tool on this element will have no effect and propagate.

    • Function

      ignoreTool

      Parameters

      • Optionalignore: boolean

        Whether to ignore the tools. Defaults to true.

      • Optionalmanager: GradumEventManager

        The associated manager (defaults to GradumEventManager.instance).

      Returns this

      Itself for chaining.

      Make the current element ignore all tools, so interacting with any tool on this element will have no effect and propagate.

    • Function

      isToolIgnored

      Parameters

      • toolName: string

        The name of the tool to check for.

      • Optionaltype: string

        The type of the event. If undefined, all event types will be considered.

      • Optionalmanager: GradumEventManager

        The associated manager (defaults to GradumEventManager.instance).

      Returns boolean

      Whether the tool is ignored for the provided event type.

      Whether the current element is ignoring the provided tool.

    Settings
    Member Visibility

    On This Page
    Constructors - Core
    Properties - Constrainers
    Properties - Core
    Properties - Element
    Properties - Events
    Properties - Hierarchy
    Properties - MVC
    Properties - Reifects
    Properties - Style
    Accessors - MVC
    Methods - Classes
    Methods - Constrainers
    Methods - Element
    Methods - Events
    Methods - Hierarchy
    Methods - Misc
    Methods - MVC
    Methods - Reifects
    Methods - Style
    Methods - Tools