README
@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 focus
ed 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.
(read-only) fastText.paused
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