Module

Select

Package
purescript-halogen-select
Repository
citizennet/purescript-halogen-select

This module exposes a component that can be used to build accessible selection user interfaces. You are responsible for providing all rendering, with the help of the Select.Utils.Setters module, but this component provides the relevant behaviors for dropdowns, autocompletes, typeaheads, keyboard-navigable calendars, and other selection UIs.

#Component Source

type Component o item eff m = Component HTML (Query o item eff) (Input o item eff) (Message o item) m

A useful shorthand for the Halogen component type

#ComponentHTML Source

type ComponentHTML o item eff = ComponentHTML (Query o item eff)

A useful shorthand for the Halogen component HTML type

#ComponentDSL Source

type ComponentDSL o item eff m = ComponentDSL (StateStore o item eff) (Query o item eff) (Message o item) m

A useful shorthand for the Halogen component DSL type

#StateStore Source

type StateStore o item eff = Store (State item eff) (ComponentHTML o item eff)

The component's state type, wrapped in Store. The state and result of the render function are stored so that extract from Control.Comonad can be used to pull out the render function.

#Effects Source

type Effects eff = (avar :: AVAR, dom :: DOM | eff)

The effects necessary for this component to run. Your component will need to also support these effects.

#QueryF Source

data QueryF o item eff a

These queries ensure the component behaves as expected so long as you use the helper functions from Select.Setters.Utils to attach them to the right elements.

  • o: The query type of the component that will mount this component in a child slot. This allows you to embed your own queries into the Select component.
  • item: Your custom item type. It can be a simple type like String, or something complex like CalendarItem StartDate EndDate (Maybe Disabled).
  • eff: The component's effects.

See the below functions for documentation for the individual constructors. The README details how to use them in Halogen code, since the patterns are a little different.

Constructors

#Query Source

type Query o item eff = Free (QueryF o item eff)

#always Source

always :: forall b a. a -> b -> Maybe a

Trigger the relevant action with the event each time it occurs

#search Source

search :: forall eff item o. String -> Query o item eff Unit

Perform a new search with the included string.

#highlight Source

highlight :: forall eff item o. Target -> Query o item eff Unit

Change the highlighted index to the next item, previous item, or a specific index.

#select Source

select :: forall eff item o. Int -> Query o item eff Unit

Triggers the "Selected" message for the item at the specified index.

#captureRef Source

captureRef :: forall eff item o. Event -> Query o item eff Unit

From an event, captures a reference to the element that triggered the event. Used to manage focus / blur for elements without requiring a particular identifier.

#triggerFocus Source

triggerFocus :: forall eff item o. Query o item eff Unit

Trigger the DOM focus event for the element we have a reference to.

#triggerBlur Source

triggerBlur :: forall eff item o. Query o item eff Unit

Trigger the DOM blur event for the element we have a reference to

#key Source

key :: forall eff item o. KeyboardEvent -> Query o item eff Unit

Register a key event. TextInput-driven components use these only for navigation, whereas Toggle-driven components also use the key stream for highlighting.

#preventClick Source

preventClick :: forall eff item o. MouseEvent -> Query o item eff Unit

A helper query to prevent click events from bubbling up.

#setVisibility Source

setVisibility :: forall eff item o. Visibility -> Query o item eff Unit

Set the container visibility (On or Off)

#getVisibility Source

getVisibility :: forall eff item o. Query o item eff Visibility

Get the container visibility (On or Off). Most useful when sequenced with other actions.

#toggleVisibility Source

toggleVisibility :: forall eff item o. Query o item eff Unit

Toggles the container visibility.

#replaceItems Source

replaceItems :: forall eff item o. Array item -> Query o item eff Unit

Replaces all items in state with the new array of items.

#raise Source

raise :: forall eff item o. o Unit -> Query o item eff Unit

A helper query that the component that mounts Select can use to embed its own queries. Triggers an Emit message containing the query when triggered. This can be used to easily extend Select with more behaviors.

#receive Source

receive :: forall eff item o. Input o item eff -> Query o item eff Unit

Sets the component with new input.

#Target Source

data Target

Represents a way to navigate on Highlight events: to the previous item, next item, or the item at a particular index.

Constructors

Instances

#Visibility Source

data Visibility

Represents whether the component should display the item container. You should use this in your render function to control visibility:

render state = if state.visibility == On then renderAll else renderInputOnly

This is a Boolean Algebra, where On corresponds to true, and Off to false, as one might expect. Thus, not will invert visibility.

Constructors

Instances

#InputType Source

data InputType

Text-driven inputs will operate like a normal search-driven selection component. Toggle-driven inputs will capture key streams and debounce in reverse (only notify about searches when time has expired).

Constructors

#State Source

type State item eff = { debounceTime :: Milliseconds, debouncer :: Maybe (Debouncer eff), highlightedIndex :: Maybe Int, inputElement :: Maybe HTMLElement, inputType :: InputType, items :: Array item, lastIndex :: Int, search :: String, visibility :: Visibility }

The component's state, once unpacked from Store.

  • inputType: Controls whether the component is input-driven or toggle-driven
  • search: The text the user has typed into the text input, or stream of keys they have typed on the toggle.
  • debounceTime: How long, in milliseconds, before events should occur based on user searches.
  • debouncer: A representation of a running timer that, when it expires, will trigger debounced events.
  • inputElement: A reference to the toggle or input element.
  • items: An array of user-provided items.
  • visibility: Whether the array of items should be considered visible or not. Useful for rendering.
  • highlightedIndex: What item in the array of items should be considered highlighted. Useful for rendering.
  • lastIndex: The length of the array of items.

#Debouncer Source

type Debouncer eff = { fiber :: Fiber eff Unit, var :: AVar Unit }

Represents a running computation that, when it completes, will trigger debounced effects.

#Input Source

type Input o item eff = { debounceTime :: Maybe Milliseconds, initialSearch :: Maybe String, inputType :: InputType, items :: Array item, render :: State item eff -> ComponentHTML o item eff }

The component's input type, which includes the component's render function. This render function can also be used to share data with the parent component, as every time the parent re-renders, the render function will refresh in Select.

#Message Source

data Message o item

The parent is only notified for a few important events, but Emit makes it possible to raise arbitrary queries on events.

  • Searched: A new text search has been performed. Contains the text.
  • Selected: An item has been selected. Contains the item.
  • VisibilityChanged: The visibility has changed. Contains the new visibility.
  • Emit: An embedded query has been triggered and can now be evaluated. Contains the query.

Constructors

#component Source

component :: forall m eff item o. MonadAff (Effects eff) m => Component o item (Effects eff) m
Modules
Select
Select.Internal.State
Select.Utils.Setters