@hyperdivision/ui

UI Components for Heimdall

Structure

The @heimdall/ui exports two primary types of assets:

• elements: functions that return html elements
• components: exported classes that subclass hui.

VHS Tests

Each component and element has a corresponding vhs-tape test associated with it, named as ${name}.vhs.js.

CSS

Additionally, a global CSS file global.css is generated and built during the publish step located in dist/bundle.css and consumed with the style field in package.json.

Elements

button = require('@hyperdivision/ui/elements/button')

Import the button element function.

button(attrs, label)

Returns a styled <button /> element with attrs attributes and a label.

closeButton = require('@hyperdivision/ui/elements/close-button')

Import the button element function.

closeButton(attrs, label)

Returns a styled <button /> element with attrs attributes and a close button icon.

icon = require('@hyperdivision/ui/elements/icon')

Import icon element function. As a side-effect of importing this module, the @hyperdivision/heimdall-icons sprite sheet is inserted into the top of the document.body.

icon(opts)

Returns an <svg/> element for the corresponding opts.name from the @hyperdivision/heimdall-icons sprite sheet.

Opts include:

{
  name, // name of the icon to use.  See https://github.com/hyperdivision/heimdall-icons
  height, // height attribute e.g. '15px'
  width, // height attribute e.g. '15px'
  size, // shortcut for setting height and width in one option
  attrs // any attrs you want added to the SVG element
}

label = require('@hyperdivision/ui/elements/label')

Import a styled input label.

label(attrs, text)

Return a <label/> element with attrs attributes and text is set as element content.

spinner = require('@hyperdivision/ui/elements/spinner')

Import a spinner element.

spinner([attrs])

Return a spinner attribute with attrs attributes applied to the outermost element.

Components

AuthSidebar = require('@hyperdivision/ui/components/auth-sidebar')

Import AuthSidebar component.

sidebar = new AuthSidebar([attrs], [opts])

Create a new AuthSidebar instance with attrs and opts.

opts include:

{
  view // an element to place into the sidebar.
}

sidebar.view

A getter/setter to set the element displayed into the sidebar.

sidebar.wide

A getter/setter to toggle wide-mode on the side bar based on truthy-ness of the value set.

sidebar.background

A getter/setter that sets the sidebar.style.background style attribute.

Input = require('@hyperdivision/ui/components/input')

Import the Input component class. You likely wan't the FormInput component instead which includes additional wrapper functionality.

input = new Input([attrs])

Create a new input component instance with the given attrs. You can pass an onerror function in attrs to receive a callback when validation fails.

input.setValueSync(value)

Set the value of the input element and wait for a raf.

FormInput = require('@hyperdivision/ui/components/form-input')

Import the FormInput component class. The FormInput includes error handling around the Input component and a label.

formInput = new FormInput(attrs, [label])

Create a new FormInput instance with the given attrs which are passed the contained Input component element.

formInput.setValueSync(value)

Set the value of the contained Input element to value.

formInput.setError([errorMsg])

Manually set the error message to errorMsg or clear the current error message when set to null.

formInput.setWarning([warningMsg])

Set a warning message. It is displayed where the error message is displayed when there is no error message. Clearing the error message displays the warning message. Set the warning message to null to clear the warning message.

The message display logic is as follows:

formInput.setAnnotation([el])

Adds a sibling element to the input element. No el removes annotation

error message || warning message || no message

Form = require('@hyperdivision/ui/components/form')

Import the Form component class which can wrap any form elements like FormInput or button elements.

form = new Form(opts, children)

Create a new <form/> element which calls various lifecycle callbacks around the array of children elements.

opts includes:

{
  onsubmit: (formValues) => {}, // submission callback
  onerror: (error) => {} // err callback
}

Pass an array of elements as the children array which will make up the child node list inside the <form/> element.

form.element

Return the form element that the component controls. All children input elements are hoisted accessible from the form element.

ImagePicker = require('@hyperdivision/ui/components/image-picker')

Import the ImagePicker component class.

imagePicker = new ImagePicker(attrs, label)

Create a new ImagePicker instance with attrs and a label. You can add this components element to a Form's children array, and get back a Buffer of the selected image in your form submission object. Includes image resizing capabilities so that images that are passed in are not too large.

imagePicker.element

Return the element controlled by the component instance.

imagePicker.setValue

Set the value of the ImagePicker component instance to a Buffer.

imagePicker.setError

Set the error message of the ImagePicker component.

Image = require('@hyperdivision/ui/components/image')

Import the Image component class which is used for displaying image Buffers at various sizes.

image = new Image(attrs)

Create an Image component instance with the attrs object.

Notable attrs include:

{
  src // a buffer to show as an image
}

image.src

Getter/setter that returns the src Buffer or sets the src buffer and runs .update()

Modal = require('@hyperdivision/ui/components/modal')

Import the Modal component class.

modal = new Modal()

Create a new Modal instance.

modal.show(view)

Show the modal with the view element that you pass in. Disables overflow scroll on the document.body while the modal is open.

modal.hide()

Hide the modal. Re-enables overflow scroll on the document.body while the modal is closed.

StepTracker = require('@hyperdivision/ui/components/step-tracker')

Import the StepTracker component used during the auth flow.

stepTracker = new StepTracker(attrs, opts)

Create a StepTracker instance with the given attrs and various opts.

opts include:

{
  state: [] // a state array
}

The state array can look like:

[
  {
    state: 'complete',
    text: 'Create passphrase'
  },
  {
    state: 'loading',
    text: 'Create profile'
  },
  {
    state: 'focus',
    text: 'Some async step'
  },
  {
    state: 'blur',
    text: 'Connect to network'
  }
]

Each state object has a text property and a state property. The state property can be one of complete, loading, focus, or blur.

stepTracker.state

A setter/getter that lets you update the state array. Use this if you want to set the complete state of the step tracker.

stepTracker.index

A getter setter to get or set the index of the currently focused or loading step.

stepTracker.next()

Jump to the next step in the state array.

stepTracker.prev()

Jump to the previous step in the state array.

stepTracker.setText(text)

Update the text of the currently active step.

stepTracker.loading(bool)

Set the loading state with bool of the current step. Advancing with stepTracker.next() will mark a currently loading step as complete.

PinEntry = require('@hyperdivision/ui/components/pin-entry')

Import the PinEntry component.

pinEntry = new PinEntry(attrs, opts)

Create a new pinEntry component instance.

opts include:

{
  length: 8 // length of pin entry
  onchange: () => {}, // called when the pin forms are filled
  disabled: false, // create a disabled pin-entry
  label: null // optional label element
}

pinEntry.value

A getter / setter to return the value of all pin boxes.

pinEntry.filled

A getter that returns bool depending on if the pin boxes are filled or not.

v1 API

var pretty = new PrettyHex({...attrs}, text)

Nice way to show hex, blobs, base64, keys or other long encoded binary values in constrained text flows.

pretty.element

Read-only reference to a HTMLSpanElement

var img = new Image({src, ...attrs})

Create a new image component. This is different from the <img /> tag since it supports binary encodings of images in addition to normal URLs.

img.element

Read-only reference to a HTMLImageElement

img.src = buffer

img.src = dataUrl

img.src = blob

Update the image displayed. Can be a valid image Buffer, Blob or data URL.

FastText = require('@hyperdivision/ui/components/fast-text')

Import the FastText component class.

fastText = new FastText(attrs, fn)

Create a new FastText instance, rendering fn on each RAF tick.

fastText.paused (read-only)

Boolean indicating whether the component is updating

fastText.pause()

Pause component rendering

fastText.start()

Start component rendering

fastText.toggle()

Toggle component rendering

Install

npm install @hyperdivision/ui

License

ISC