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

    Class GradumSelectWheel<ValueType, SecondaryValueType, EntryType, ViewType, DataType, ModelType, EmitterType>

    GradumSelectWheel

    A swipeable selection wheel. Entries are always position absolute, fanned out by a continuous pixel offset. Dragging moves all entries in real time; releasing snaps to the nearest. The container sizes to the selected entry. Visual state is driven by entryTransitionReifect (CSS transitions) and computeAndApplyStyling (per-entry opacity/scale/transform).

    Type Parameters

    Hierarchy (View Summary)

    Index
    constructor
    _sizeTransitionTimeout select entriesTag values entriesClasses selectedEntriesClasses defaultProperties properties sizePerEntry positionPerEntry totalSize dragLimitOffset openTimeout direction scale generateCustomStyling dragging openTimer opacity onAttach onDetach onAdopt tagName initialized defaultFeedforwardProperties view model emitter data dataId dataIndex dataSize operators handlers interactors tools constrainers unsetDefaultClasses shadowDOM defaultClasses
    entries selectedEntries selectedEntry selectedIndex selectedIndices inputName inputField multiSelection forceSelection enabledEntries enabledValues enabledSecondaryValues selectedValue selectedValues selectedSecondaryValues selectedSecondaryValue stringSelectedValue transitionReifect size entryTransitionReifect transitionDuration customReifect alwaysOpen open isVertical index currentPosition
    beforeResize afterResize initialize computeDragDelta reloadEntrySizes indexToPosition positionToIndex snapToNearest applyTransition applyAllEntryStyles computeAndApplyStyling clearOpenTimer setOpenTimer create customCreate setupChangedCallbacks setupUIElements setupUILayout setupUIListeners connectedCallback disconnectedCallback adoptedCallback destroy feedforward clone

    Protected_sizeTransitionTimeout

    _sizeTransitionTimeout: Timeout

    The pending timer that clears the container's fixed size once the resize animation ends.

    select: GradumSelect<ValueType, SecondaryValueType, EntryType> = ...

    The selection logic backing this element. It owns the entries and their selected state; this element renders them.

    entriesTag:
        | "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 tag used to build entries from plain values.

    values: ValueType[]
    entriesClasses: string | string[]
    selectedEntriesClasses: string | string[]
    defaultProperties: { transitionDuration: number } = ...

    Default properties assigned to a new wheel. Entries animate over 0.3 seconds.

    properties: GradumSelectWheelProperties<
        ValueType,
        SecondaryValueType,
        EntryType,
        ViewType,
        DataType,
        ModelType,
        EmitterType,
    >
    sizePerEntry: number[] = []

    Each entry's measured size along the wheel's axis, indexed by entry position. Refreshed by GradumSelectWheel.reloadEntrySizes.

    positionPerEntry: number[] = []

    Each entry's offset from the start of the wheel, indexed by entry position.

    totalSize: number = 0

    The combined size of every entry along the wheel's axis.

    dragLimitOffset: number = 30

    How far past the first and last entries the wheel can be dragged, in pixels, before it springs back.

    openTimeout: number = 3000

    How long the wheel stays open after the last interaction, in milliseconds, unless GradumSelectWheel.alwaysOpen is set.

    direction: Direction = Direction.horizontal

    The axis the wheel scrolls along.

    scale: Record<Range, number> = ...

    The scale applied to entries at the centre of the wheel and at its edges. Entries in between are scaled proportionally, producing the wheel's depth effect.

    generateCustomStyling: (
        properties: GradumSelectWheelStylingProperties,
    ) => string | PartialRecord<keyof CSSStyleDeclaration, string | number>

    An optional hook replacing the wheel's built-in entry styling. It receives the computed translation, opacity, and scale alongside the default styles, and returns the styles to apply instead.

    dragging: boolean = false

    Whether the wheel is currently being dragged.

    openTimer: Timeout

    The pending timer that will close the wheel once GradumSelectWheel.openTimeout elapses.

    opacity: Record<Range, number>
    onAttach: Delegate<() => void> = ...

    Delegate fired when the element is attached to DOM.

    onDetach: Delegate<() => void> = ...

    Delegate fired when the element is detached from the DOM.

    onAdopt: Delegate<() => void> = ...

    Delegate fired when the element is adopted by a new parent in the DOM.

    tagName: string
    initialized: boolean

    Whether the element was initialized already or not.

    defaultFeedforwardProperties: GradumElementProperties

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

    view: ViewType

    The view (if any) of the element.

    model: ModelType

    The model (if any) of the element.

    emitter: GradumEmitter

    The emitter (if any) of the element.

    data: DataType

    The main data block (if any) attached to the element, taken from its model (if any).

    dataId: string

    The ID of the main data block (if any) of the element, taken from its model (if any).

    dataIndex: number

    The numerical index of the main data block (if any) of the element, taken from its model (if any).

    dataSize: number

    The size (number) of the main data block (if any) of the element, taken from its model (if any).

    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 (if any) attached to the element's MVC structure.

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

    The handlers (if any) 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 (if any) attached to 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 (if any) attached to 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 (if any) attached to the element's MVC structure.

    unsetDefaultClasses: boolean

    Whether to set the default CSS classes defined in the static config on the element or not. Setting it will accordingly add/remove the CSS classes from the element.

    shadowDOM: boolean

    Whether the element renders its children into a shadow root. Assigning true attaches one if the element does not already have it.

    defaultClasses: string | string[]

    The CSS classes applied to every instance of this element class. Assigning a new value swaps the previous classes out for the new ones, unless unsetDefaultClasses is set.

    • get entries(): EntryType[]

      Returns EntryType[]

      The element's entries, in order. Assigning a new list replaces them all.

    • set entries(value: NodeList | HTMLCollection | EntryType[]): void

      Parameters

      Returns void

    selectedEntries: EntryType[]
    selectedEntry: EntryType
    selectedIndex: number
    selectedIndices: number[]
    inputName: string
    inputField: HTMLInputElement
    multiSelection: boolean
    forceSelection: boolean
    enabledEntries: EntryType[]
    enabledValues: ValueType[]
    enabledSecondaryValues: SecondaryValueType[]
    selectedValue: ValueType
    selectedValues: ValueType[]
    selectedSecondaryValues: SecondaryValueType[]
    selectedSecondaryValue: SecondaryValueType
    stringSelectedValue: string
    • get transitionReifect(): Reifect

      Returns Reifect

    • set transitionReifect(value: Reifect<Node> | StatelessReifectProperties): void

      Parameters

      Returns void

    • get size(): Record<Range, number>

      Returns Record<Range, number>

    • set size(value: number | Record<Range, number>): void

      Parameters

      Returns void

      The wheel's extent on either side of its centre, in pixels. Assign a single number to use it symmetrically.

    • get entryTransitionReifect(): Reifect

      Returns Reifect

    • set entryTransitionReifect(
          value: Reifect<Node> | StatelessReifectProperties,
      ): void

      Parameters

      Returns void

      The reifect animating entries as they move through the wheel. Assign reifect properties to build one. It is attached to every existing entry on assignment.

    • set transitionDuration(value: number): void

      Parameters

      • value: number

      Returns void

      Duration of the container size transition in seconds. Kept in sync with switchTransitionReifect — set this to change both at once.

    • get customReifect(): Reifect

      Returns Reifect

    • set customReifect(value: Reifect<Node> | StatelessReifectProperties): void

      Parameters

      Returns void

      An extra reifect applied to entries alongside the built-in transition, for styling beyond position and scale. Assign reifect properties to build one, or null to remove it.

    • set alwaysOpen(value: boolean): void

      Parameters

      • value: boolean

      Returns void

    • set open(value: boolean): void

      Parameters

      • value: boolean

      Returns void

    • get isVertical(): boolean

      Returns boolean

      Whether the wheel scrolls vertically.

    • get index(): number

      Fractional index — integer when snapped, fractional mid-drag.

      Returns number

    • set index(value: number): void

      Parameters

      • value: number

      Returns void

    • get currentPosition(): number

      Returns number

      How far the wheel is scrolled, in pixels from its start. Assigning clamps the value to the draggable range, updates the selected index, and restyles every entry.

    • set currentPosition(value: number): void

      Parameters

      • value: number

      Returns void

    • Parameters

      • selectedEntry: EntryType

        The newly selected entry.

      Returns void

      Called synchronously inside applyTransition, before the rAF that reads the selected entry's new size. Use this to reposition/reflow entries so the size read is correct.

    • Parameters

      • selectedEntry: EntryType

        The entry that is now selected.

      Returns void

      Called after the container size transition completes.

    • Function

      initialize

      Returns void

      Set the wheel up and start tracking its entries, re-measuring them whenever an entry is added or removed.

    • Protected Function

      computeDragDelta

      Parameters

      • delta: Point

        The pointer's movement.

      Returns number

      The distance to scroll, in pixels.

      Convert a drag delta into movement along the wheel's axis, inverted so dragging one way scrolls the entries the other.

    • Protected Function

      reloadEntrySizes

      Returns void

      Re-measure every entry and rebuild the wheel's size and position tables. Call it after the entries change, or after the wheel becomes visible — entries laid out while hidden measure as zero.

    • Protected Function

      indexToPosition

      Parameters

      • index: number

        The entry's index.

      Returns number

      The corresponding scroll position, in pixels.

      Get the scroll position at which the given entry sits at the centre of the wheel.

    • Protected Function

      positionToIndex

      Parameters

      • position: number

        The scroll position, in pixels.

      Returns number

      The fractional entry index.

      Get the entry index a scroll position corresponds to. The result is fractional between entries, which is what drives the wheel's scaling mid-drag.

    • Protected Function

      snapToNearest

      Returns void

      Settle the wheel on the entry nearest its current position and select it. Called when a drag ends.

    • Protected Function

      applyTransition

      Returns void

      Scroll the wheel to the selected entry and size the wheel to match it. Overrides the base selection behaviour, which sizes to the entry element instead.

    • Protected Function

      applyAllEntryStyles

      Returns void

      Restyle every entry for the current scroll position. Styles are applied instantly while dragging, so transforms are not queued behind a frame and left visibly lagging the pointer.

    • Protected Function

      computeAndApplyStyling

      Parameters

      • element: HTMLElement

        The entry to style.

      • translationValue: number

        The entry's offset from the centre, in pixels.

      • Optionalsize: Record<Range, number> = ...

        The wheel's extent, used to scale the falloff.

      • Optionalinstant: boolean = false

        Whether to set the styles directly, skipping the CSS transition.

      Returns void

      Compute an entry's opacity, scale, and transform from how far it sits from the wheel's centre, and apply them. Defers to GradumSelectWheel.generateCustomStyling when one is set.

    • Protected Function

      clearOpenTimer

      Returns void

      Cancel the pending timer that would close the wheel.

    • Protected Function

      setOpenTimer

      Returns void

      Restart the timer that closes the wheel once GradumSelectWheel.openTimeout elapses.

    • Function

      create

      Type Parameters

      Parameters

      • this: This
      • Optionalproperties: This["prototype"]["properties"] & ElementTagDefinition<"div"> & Omit<
            HTMLElementMutableFields<"div">,
            "tag" | "namespace",
        > & {
            id?: string;
            classes?: string | string[];
            style?: string;
            stylesheet?: string;
            shadowDOM?: boolean;
            parent?: Element;
            children?: Element | Element[];
            text?: string;
            listeners?: Record<
                string,
                (e: Event, el: ValidElement<Tag>) => boolean | any,
            >;
            onClick?: (e: Event, el: HTMLDivElement) => any;
            onDrag?: (e: Event, el: HTMLDivElement) => any;
            out?: string | Node;
            [key: string]: any;
        } & MvcProperties<ViewType, ModelType, EmitterType> & {
            data?: DataType;
            initialize?: boolean;
        } & { out?: string
        | Node; [key: string]: any } & {
            unsetDefaultClasses?: boolean;
            shadowDOM?: boolean;
            defaultSelectedClasses?: string | string[];
            defaultClasses?: string | string[];
        }

        Properties to set on the new instance.

      Returns This["prototype"] & GradumElement<ViewType, DataType, ModelType, EmitterType>

      The created instance, typed as the class this was called on.

      Instantiate this class with the given properties. Defaults declared by every class in the inheritance chain are applied first, nearest ancestor last, so a subclass' defaultProperties win over its parent's. The return type follows the class it is called on, and the MVC type parameters are read back off the properties — passing model: MyModel types .model as MyModel without a cast.

      Note: the callee is read through this["prototype"] rather than InstanceType<this>, because the latter instantiates a generic class' parameters with their constraints instead of their defaults, which is what forced casts at call sites.

    • Protected Function

      Parameters

      • properties: object

        Properties to set on the new instance, defaults already merged in.

      Returns object

      The created instance.

      customCreate

      The construction step behind create. Override it to change how instances of a class are built — to route through a factory, or to wrap the instance — while keeping the default-merging that create performs.

    • Protected Function

      setupChangedCallbacks

      Returns void

      Setup method intended to initialize change listeners and callbacks. Called on initialize().

    • Protected Function

      setupUIElements

      Returns void

      Setup method intended to initialize all direct sub-elements attached to this element, and store them in fields. Called on initialize().

    • Protected Function

      setupUILayout

      Returns void

      Setup method to create the layout structure of the element by adding all created sub-elements to this element's child tree. Called on initialize().

    • Protected Function

      setupUIListeners

      Returns void

      Setup method to initialize and define all input/DOM event listeners of the element. Called on initialize().

    • Function

      connectedCallback

      Returns void

      function called when the element is attached to the DOM.

    • Function

      disconnectedCallback

      Returns void

      function called when the element is detached from the DOM.

    • Function

      adoptedCallback

      Returns void

      function called when the element is adopted by a new parent in the DOM.

    • Function

      destroy

      Returns this

      Itself, allowing for method chaining.

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

    • Function

      feedforward

      Parameters

      • Optionalproperties: FeedforwardProperties

        Properties to feed forward. Defaults to defaultFeedforwardProperties.

      Returns this

      Itself, allowing for method chaining.

      Push this element's feedforward properties down to its children, so newly added descendants pick up the same defaults.

    • Function

      clone

      Parameters

      Returns this

      The cloned element.

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

    Settings
    Member Visibility

    On This Page
    Constructors
    Properties
    Accessors
    Methods