Module

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.Setters module, but this component provides the relevant behaviors for dropdowns, autocompletes, typeaheads, keyboard-navigable calendars, and other selection UIs.

#Component 

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

A useful shorthand for the Halogen component type

#ComponentHTML 

type ComponentHTML o item = ComponentHTML (Query o item)

A useful shorthand for the Halogen component HTML type

#ComponentDSL 

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

A useful shorthand for the Halogen component DSL type

#StateStore 

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

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.

#QueryF 

data QueryF o item 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).

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 

type Query o item = Free (QueryF o item)

#always 

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

Trigger the relevant action with the event each time it occurs

#search 

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

Perform a new search with the included string.

#highlight 

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

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

#select 

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

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

#triggerFocus 

triggerFocus :: forall o item. Query o item Unit

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

#triggerBlur 

triggerBlur :: forall o item. Query o item Unit

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

#key 

key :: forall o item. KeyboardEvent -> Query o item 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 

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

A helper query to prevent click events from bubbling up.

#setVisibility 

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

Set the container visibility (On or Off)

#getVisibility 

getVisibility :: forall o item. Query o item Visibility

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

#toggleVisibility 

toggleVisibility :: forall o item. Query o item Unit

Toggles the container visibility.

#replaceItems 

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

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

#raise 

raise :: forall o item. o Unit -> Query o item 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 

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

Sets the component with new input.

#Target 

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 

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 

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 

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

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 

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

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

#Input 

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

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 

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 

component :: forall o item m. MonadAff m => Component o item m

Modules