dub-step

0.0.7

DubStep ▸
- Static members
- .propTypes
- Instance members
- #Step
- #Next
- #Previous
- #Play
- #Pause
- #StepIndex
StateAndHelpers

DubStep

dub-step 🕺🏽

Primitives for building step based UI widgets controlled by swipe, timers, and/or buttons.

Many existing carousel/swipe solutions in one way or another end up dictating the markup of your UI. They expose many options to allow for extensibility, but this results in a convoluted API that is not flexible. In these cases, your often very specific design must be fit into an existing rigid solution. dub-step simply manages the state needed to power a carousel, slideshow, photo gallery, or even multi-step forms, allowing you to build the UI how you want. It uses the function as child and "prop getter" patterns, which gives you maximum flexibility with a minimal API.

dub-step provides an API for updating the state of an index or "step".

Directly when an "action" like next is called.
Incrementally when the provided Next/Previous components are clicked.
On swipe when a Step component is swiped.
On a timer when the provided Play/Pause components are clicked.

new DubStep(props: any)

Extends Component

Parameters

props (any)

Static Members

▸ propTypes

These props affect how/when the step and associated state is updated.

propTypes

Properties

total (number) : The total number of steps. Defaults to 0 .

defaultStep (number) : The initial step of dub-step. Defaults to 0 .

cycle (boolean) : Whether or not dub-step should cycle. Defaults to false .

stepInterval (number) : The number of steps to interate when navigating. Defaults to 1 .

autoPlay (boolean) : Should dub-step autoPlay? Defaults to false .

duration (number) : How long should each step wait? Defaults to 0 .

vertical (boolean) : Are the steps changing vertically? Defaults to false .

swipe (boolean) : Are the steps swipable? Defaults to false .

draggable (boolean) : Are the steps draggable on desktop? Defaults to false .

pauseOnHover (boolean) : Should dub-step pause on hover? Defaults to false .

touchThreshold (number) : How much it takes to change steps. Defaults to 20 .

swipeIterateOnly (number) : Regardless of swipe direction, the step is iterated. Defaults to false .

animationSpeed (number) : The transition animation speed. Defaults to 0 .

onBeforeChange (function) : Called immediately before the step is changed. Defaults to () => {} .

onChange (function) : Called once the step has changed. Defaults to () => {} .

onAfterChange (function) : Called after the step has changed and after animationSpeed seconds if present. Defaults to () => {} .

onPlay (function) : Called when played. Defaults to () => {} .

onPause (function) : Called when paused. Defaults to () => {} .

onNext (function) : Called when iterating to the next step. Defaults to () => {} .

onPrevious (function) : Called when iterating to the previous step. Defaults to () => {} .

onSwipeStart (function) : Called when swiping/dragging has begun. Defaults to () => {} .

onSwipeMove (function) : Called when a swipe/drag is moved. Warning: This gets called a lot . Defaults to () => {} .

onSwipeEnd (function) : Called when a swipe/drag is cancelled. Defaults to () => {} .

children ((function | array)) : Called with an object containing current state and prop getters.

Instance Members

▸ Step

This component is responsible for tracking touch/drag interactions and sets dub-steps swipe state properties respectively.

Step

Parameters

props (object)

Name	Description
props.component `(ReactElement \| string)` (default `div`)	The element to render

Returns

ReactElement:

Example

// In this example, GlamorousDogeImg is a glamorous.img. The only required prop here is component. The rest gets passed through for glamorous to for styling purposes (Like css transforms).
// NOTE: Glamorous is only used as an example. Any kind of component can be passed to the component prop.
// If no component is passed, a div will be used.
<Step
 component={GlamorousDogeImg}
 swipeLeftDistance={swipeLeftDistance}
 dragging={dragging}
 src={url}
 alt="doge pic"
/>

▸ Next

This component is responsible for incrementing the step by the stepInterval value.

Parameters

props (object)

Name	Description
props.component `(ReactElement \| string)` (default `button`)	The element to render

Returns

ReactElement:

Example

<Next>Next</Next>

▸ Previous

This component is responsible for decrementing the step by the stepInterval value.

Parameters

props (object)

Name	Description
props.component `(ReactElement \| string)` (default `button`)	The element to render

Returns

ReactElement:

Example

<Previous>Previous</Previous>

▸ Play

This component is responsible for starting an internal interval that increments the step by the stepInterval value.

Play

Parameters

props (object)

Name	Description
props.component `(ReactElement \| string)` (default `button`)	The element to render

Returns

ReactElement:

Example

// Any dub-step component can be customized by passing a `component` prop.
<Play component={MyCustomPlayButton}>Play</Play>

▸ Pause

This component is responsible for clearing an internal interval that increments the step by the stepInterval value.

Pause

Parameters

props (object)

Name	Description
props.component `(ReactElement \| string)` (default `button`)	The element to render

Returns

ReactElement:

Example

<Pause>Stop</Pause>

▸ StepIndex

This component is responsible for setting the current step of dub-step.

StepIndex

Parameters

props (object)

Name	Description
props.component `(ReactElement \| string)` (default `button`)	The element to render

step (number) The step to which dub-step should change.

Returns

ReactElement:

Example

// Remember, any other prop added gets passed through to the component.
<StepIndex
  step={index}
  onMouseEnter={() => console.log(`About to switch to step ${index}`)}
>
  {stepNumber}
</StepIndex>

StateAndHelpers

The state of dub-step and prop getters/actions for changing the state are exposed as a parameter to the render prop.

The paramters of this function can be split into 4 categories: State, Components, Actions.

State: State properties of dub-step exposed to your render code. Controlled state can be passed as a prop and "controlled" by an outside component/router/store.
Components Components that control the current step. They take a component prop which allows you to control your UI, add internal props, and pass through any additional props you add. Examples include: Step, Next, Previous, Play, Pause. NOTE: Each component has an alternative and respective "prop getter", if that pattern is preferred. These are functions named get*ControlProps. Call/spread these on the element you're rendering for a given purpose. For example: <button {...getNextControlProps(otherProps)}))>Next</button>. It's advisable to pass all your props to that function rather than applying them on the element yourself to avoid your props being overridden (or overriding the props returned).
Actions: Call these to directly change the state of dub-step.

StateAndHelpers

Type: object

Properties

step (number) : state - The current step of dub-step. Controlled.

paused (boolean) : state - Is dub-step paused? Controlled.

animating (boolean) : state - Is the step component transition animating?

swiping (boolean) : state - Has the swipe threshold been reached?

dragging (boolean) : state - Has the step component been initially dragged?

swipeLeftDistance (number) : state - A number representing the distance the step component has been dragged horizontally.

swipeDownDistance (number) : state - A number representing the distance the step component has been dragged vertically.

swiped (boolean) : state - Has the step component been dragged enough to be moved to the next/previous step?

swipeRatio (number) : state - A number between 0 and 1 with nearness to 1 representing closeness to being swiped.

swipeDirectionSign (number) : state - Either 1 or -1. 1 representing right and -1 representing left.

Step (ReactElement) : Component - This component is responsible for tracking touch/drag interactions and sets dub-steps swipe state properties respectively. Alternatively, use getStepProps if you prefer the prop getter patern. Returns the props you should apply to an element you render that is expected to have swipe/drag interactions.

Next (ReactElement) : Component - This component is responsible for incrementing the step by the stepInterval value. Alternatively, use getNextControlProps if you prefer the prop getter pattern. It returns the props you should apply to a next button element you render.

Previous (ReactElement) : Component - This component is responsible for decrementing the step by the stepInterval value. Alternatively, use getPreviousControlProps if you prefer the prop getter patern. It returns the props you should apply to a previous/back button element you render.

Play (ReactElement) : Component - This component is responsible for starting an internal interval that increments the step by the stepInterval value. Alternatively, use getPlayControlProps if you prefer the prop getter patern. It returns the props you should apply to a play button element you render.

Pause (ReactElement) : Component - This component is responsible for clearing an internal interval that increments the step by the stepInterval value. Alternatively, use getPauseControlProps if you prefer the prop getter patern. It returns the props you should apply to a pause button element you render.

StepIndex (ReactElement) : Component - This component is responsible for setting the current step of dub-step. NOTE: It takes a step prop representing the step to which dub-step should change. Alternatively, use getStepControlProps if you prefer the prop getter patern. It returns the props you should apply to an element you render that sets the step of dub-step.

next (function) : Action - Increments the step by the stepInterval.

previous (function) : Action - Decrements the step by the stepInterval.

play (function) : Action - Starts the dub-step incrementor interval.

pause (function) : Action - Pauses dub-step.