Gadgets NPM | npm.io

gadgets

Reusable React UI widgets - This is my widget library. There are many like it, but this one is mine...

This library provides widgets and composite controls for building desktop apps using Electron. The widgets are listed below.

Requirements

Electron v4.x+
Node v10.x+
React v16.3+

Usage

The CSS styles must be included within a project using CSS modules or via webpack configuration:

code snippet

const styles = require('gadgets/dist/styles.css');

import {
	Button,
	ButtonToggle
} from 'gadgets';

...

<Button />
<ButtonToggle />

webpack snippet

module.exports = {
	entry: [
		path.resolve(__dirname, 'node_modules', 'gadgets', 'dist', 'styles.css'),
	],
	target: 'node',
	output: {
		path: path.resolve(__dirname, 'dist'),
		filename: 'bundle.js',
		publicPath: "dist/",
		libraryTarget: "commonjs"
	},
    ...

This will give a webpack module an entry point to copy the gadgets CSS file into that build's distribution. Without this the built in styles for each control will be missing.

Note that React is NOT packaged with the app. An app that uses this library must supply the React library. The demo application shows an example of this.

Installation

This module uses yarn to manage dependencies and run scripts for development.

To install as an application dependency:

$ yarn add gadgets

To build the app and run all tests:

$ yarn run all

To build and run the demo application in electron use:

$ yarn run demo

This will check out all dependencies, build the code, test, and then try to run it within electron. This will take some time to complete.

To just attempt to run the application without building use (assuming the app was recently built):

$ yarn start

Development

Building

The build process happens in two steps:

Typescript Compilation (first)
Webpack vial babel-loader (second)

The Typescript build converts all of the .ts and .tsx files into their .js and .jsx counterparts, while also generating typing information (.d.ts). It uses the tsc compiler to generate this code. The second part uses webpack to take these converted files and generate a webpack bundle. During the bundle creation the generated typings are placed into the dist directory with the generated bundle. This process is followed instead of using a webpack loader to handle the typescript compilation (such as ts-loader. The webpack build can't generate typings via the loader and use the copy webpack plugin at the same time. This happens because the copy plugin tries to copy files in parallel while they are being generated. This leads to errors and warnings in the build for missing files that are not yet generated. In the future this may be changed to use a loader and the webpack-shell-plugin instead of the webpack copy plugin, but the current solution didn't require custom code to perform the copy. This two part solution works, but does lead to the following complication.

To change the code while electron is running and use CMD + R to refresh electron (in two terminals):

$ yarn watch:types.    # starts the typescript compiler in terminal 1
$ yarn watch:webpack   # starts the webpack watcher in terminal 2

This starts two separate watchers. It will watch for changes in the typescript files first. When detected the typescript compiler will build from .ts/.tsx to .js/.jsx. The webpack watcher will then see this and rebuild the bundle with the second watcher.

This library was created for use in the Electron UI and has been tested to work with the most recent version of Chromium in Electron. It contains a custom set of React widgets and composite components used to create a desktop application. The build uses Typescript and Wepback to create the package. Once built it contains a distribution bundle (bundle.js) and a CSS file (styles.css) that can be included within another project. The library also makes use of styled components.

Click on the each documented element below to see a picture of the component (where applicable). To see a live demo, build the application (listed above). It will run a demo electron application demonstrating each component. The demo application also contains samples that demonstrate how the components are used.

Debugging

The library use the debug module to print information to log. To see debugging information set the environment variable DEBUG_GADGETS to true. Also, set a string qualifier to the DEBUG environment varaible to turn on messages for a component (this is needed by the debug module). All of the components have their own namespace that follows the convention:

"gadgets.{component}[:{action}]"

Where component is the React name for the component, i.e. Accordion, List, etc... The :action is either empty, :create, or :render. e.g.

"gadgets.Accordion:render"

Will print debugging information when the render() method is called. This includes the props and state at the time the render operation started. Wildcards can also be used:

'gadgets.*:create`

When the constructor is called to create each instance of a component, the create message will displayed in the console. It will contain references to the initial props and state. With the wildcard above this will display the create message for every component as it is created.

Widgets

The module contains the following widgets (click on each header to see attribute/event details for each):

Accordion/AccordionItem

An accordion control contains N number of AccordionItems. These items will display/hide the contents of that item when the header of that item is clicked. The content of an AccordionItem can be any set of HTML tags. The demo application shows a List embedded within the accordion.

Badge

A counter widget that annotates (overlays) another widget.

BaseProps

This module represents the properties that are shared by every class in the project. This includes properties such as color, id, disabled, etc.

Breadcrumbs

A navigation control used to keep track of previous locations visited. The rightmost item is the current location. This provides a "path" back to the start of some navigation.

Break

A wrapper for the <br> tag. This respects the Sizing option for controls so that the height of the break matches the current line height.

Browser

Creates a web browser instance using a webview tag

Button

A typical button control widget. This control only uses an icon and no text to represent the button. The icons are Font Awesome strings. That library is built into this module, so any font available in the current release of that library is available.

ButtonCircle

A circular button control. Works like a typical button... except it's a circle.

ButtonDialog

A button control that when pushed displays a local dialog box. The contents of the control make up the dialog window.

ButtonText

A button control that contains an icon and a text string. The text string can be to the left or right of the icon.

ButtonToggle

A button control that switches between the given icons when clicked. The state of the button is maintained until it is clicked again.

Container

A generic control used to group other controls. It creates a section tag around the given child component.

DataGrid

A component that represents data in a 2D table format like excel. The underlying code is a wrapper around the react-data-grid component.

DateChooser

TODO: create the DateChooser control

DialogBox

A modal, dialog box popup window for yes/no user decisions.

DialogWindow

A modal dialog window.

Dropdown

A dropdown list using the HTML select/option elements.

DynamicList

A specialized List control that can be manipulated by the user. They can add/remove/select items from it.

Editor

A multi-line text editor control. It uses a custom markup module under the Quill editor/api.

Gauge

TODO: create a circular gauge control

Icon

Displays a graphical icon within the current container.

Label

A text label string control that can be edited.

List/ListDivider/ListFooter/ListHeader/ListItem

A container element that holds a list of other elements. The List resolves to a <ul> and the items within it resolve to <li>.

Option

A checkbox/radio button control. This is just a specialized form of ButtonToggle.

OptionGroup

A grouping of Option conmponents.

Pager

A pagination control. This takes an input size I and a page size P and breaks it up into N = I/P entries. The entries are displayed as a list of pages that can be chosen by the user.

Preview

Takes a string of a markup language (asciidoc, markdown, or restructuredtext), converts it to HTML, and presents it in a webview control.

ProgressBar

TODO: create the ProgressBar control

Rating

TODO: create the Rating control

Slider

The Slider control creates a horizontal line overlapped by a chevron that can be moved along this horizontal line.

Switch

A button control that works like a toggle. Pressing the button will turn it on or off. The color of the slider shows the state.

TagList (Tag)

The tag list control is a basic list of strings that act as metadata for another control. They are used to categorize information.

TabContainer (Tab)

A typical tab control container. This manages Tab elements within it.

TextArea

A multiline text editing component. It is a contenteditable div.

TextField (Validator)

The TextField is a wrapper component for the built in <input> tag. This control allows the user to add validation routines to the input control beyond the builtin routines.

TimeChooser

TODO: create TimeChooser control

Title

A reusable title block used to format two items: a title and a widget. The title is generally a text string and the widget can be a text string or another control.

Toast

A popup that contains a message on the top or bottom of that container. The message will disapper after N seconds. Contains an X button to remove sooner. It contains four basic modes: info, warning, error, custom.

Toolbar/Divider

A grouping of buttons and/or controls in a horizontal bar.

Tooltip

A text popup window on a control used to give help or feedback to the user of that control.

Treeview

This component represents data in a hierarchical parent/child view. The underlying code is a wrapper around the react-sortable-tree component written by Chris Fritz.

Triangle

Uses SVG to draw a triangle within the container.

Voting

TODO: Create a Voting control (up/down arrows to affect vote count like Reddit)

Wrapper

Each component uses the Wrapper component to catch potential errors within the control. These are error boundaries that are new to React 16. It also wraps the ThemeProvider used by the styled-components.

Styles

The library contains an external style sheet that must be included. It is located in node_modules/gadgets/dist/styles.css. This library also uses highlight.js. If the Editor control is used, then the highlight CSS files need to be included as well. They are located in node_modules/gadgets/dist/highlights/*.css. These should be copied to the root of the site/app (with something like the Copy Webpack Plugin).