https://github.com/eccenca/ecc-gui-elements
Collection of low-level GUI elements like Buttons, Icons or Alerts.
https://github.com/eccenca/ecc-gui-elements
Last synced: 4 months ago
JSON representation
Collection of low-level GUI elements like Buttons, Icons or Alerts.
- Host: GitHub
- URL: https://github.com/eccenca/ecc-gui-elements
- Owner: eccenca
- Created: 2018-01-24T12:06:56.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2022-12-10T16:55:58.000Z (over 2 years ago)
- Last Synced: 2025-01-22T07:20:21.576Z (6 months ago)
- Language: JavaScript
- Size: 8.2 MB
- Stars: 2
- Watchers: 13
- Forks: 0
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Low-Level GUI Components (@eccenca/gui-elements)
Collection of shared GUI elements and hocs.
## Mixins
- `ScrollingHOC`: It provides methods to scroll mounted React components into the viewport.
### ScrollingHOC
The scrolling mixin provides methods to scroll a mounted React element or component into the visible viewport of a scrollable area:
* `scrollIntoView()`: use this method within a component to scroll it into the visible viewport
* `ScrollingMixin.scrollElementIntoView(ReactOrDomElement)`: use this method from outside an element to scroll it into the visible viewport
```js
import { ScrollingHOC } from '@eccenca/gui-elements';
const Widget = React.createClass({
componentDidMount() {
const options = {
animationTime: 500, // (optional) integer, time in milliseconds
topOffset: 0, // (optional) integer, pixels to offset top alignment
callbackFinished: function(result) {}, // (optional) function, result parameter is currently 'cancelled' or 'completed',
scrollX: true // (optional) boolean, whether overflowX should be checked to decide whether an element is scrollable,
scrollY: true // (optional) boolean, whether overflowY should be checked to decide whether an element is scrollable,
}
this.scrollIntoView(
options // optional
);
},
// ...
});
export default ScrollingHOC(Widget)
```
It is important that the component height can be calculated correctly, `scrollIntoView()` should be used after all contents are loaded.
Use another method from the mixin to scroll other elements into the viewport.
It's important to use references to active DOM elements or mounted React components, e.g. by using the React ref pattern.
```js
// use it from outside of the component that needs to be scrolled into the visible viewport
import {Card, Button, ScrollingHOC} from '@eccenca/gui-elements';
const Widget = React.createClass({
handleScroll() {
const options = {
// animationTime: 500, // (optional) integer, time in milliseconds
// topOffset: 0, // (optional) integer, pixels to offset top alignment
// callbackFinished: function(result) {}, // (optional) function, result parameter is currently 'cancelled' or 'completed'
}
this.props.scrollElementIntoView(
this.myCard,
options, // optional parameter
);
},
// ...
render() {
return
this.myCard = card}>
Scroll card into viewport
},
});
```
## Core styles
Style core for all projects.
Includes libraries from:
- [Material Lite One](https://github.com/eccenca/material-lite-one)
- [Material Design icons](http://google.github.io/material-design-icons)
- [Roboto Font](https://github.com/FontFaceKit/roboto)
### Include full SCSS into application
Add this into your main scss.
```scss
@import '~@eccenca/gui-elements/src/main';
```
### Use configuration in SCSS
You can import the global default configuration by using it from `@eccenca/gui-elements`:
```scss
@import '~@eccenca/gui-elements/src/configuration.default';
```
#### Justify default configuration
Base configuration can be defined by only 7 variables, they need to be set before importing `~@eccenca/gui-elements/src/configuration.default`.
- Colors:
- `$ecc-color-primary`:
- `$ecc-color-primary-contrast`:
- `$ecc-color-accent`:
- `$ecc-color-accent-contrast`:
- Sizes:
- `$ecc-size-typo-base`:
- `$ecc-size-typo-base-lineheight`:
- `$ecc-size-type-levelratio`:
If necessary you can pre-define all SCSS variables with your own values, please have a look into `src/onfiguration.default` and `src/configuration.mdl` in `@eccenca/gui-elements` for a full list, otherwise they are set by default to base colors (e.g. for alerts) or calculated based on the mentioned variables above.
### Include ready to use CSS
- Copy `/dist` folder and use `style-core.css`
## Helpers
Include helper function in your Sass files:
```scss
@import "~@eccenca/gui-elements/src/scss/helpers";
```
Helper automatically included if the default configuration is loaded.
- `to_color()`: function to transform string into color value type
### to_color($color_value)
Returns correct Sass color value, even if `$color_value` parameter is a string value.
Examples:
```
to_color("#fff") => white
to_color("rgb(255, 255, 255)") => white
to_color("255, 255, 255") => white
```
Parameters:
* `$color_value` (Sass::Script::Value::String) or (Sass::Script::Value::Color)
Returns:
* (Sass::Script::Value::Color)
## GUI elements
- `Alert`: A message box which is optionally dismissable, includes `Error`, `Info`, `Success` and `Warning`.
- `AutoCompleteBox`: A auto-completion box (wrapper around `SelectBox`) which renders label, value and an optional description.
- `BaseDialog`: A custom message box with optional Buttons
- `Button`: A simple Button which also may contain icons
- `BreadcrumbList`: A simple element to create breadcrumb navigation
- `Card`: An application card section including title, menu, content section and button row
- `Content`: container for all page content elements beside header, drawer and footer
- `Checkbox`: A checkbox with optional description
- `Chip`: A chip element for visualized status
- `ConfirmationDialog`: A message box with Buttons for confirmation and cancellation
- `ContextMenu`: A context menu with menu items
- `DateField`: A date field input with calendar picker
- `DateTimeField`: A date and time field input with calendar picker
- `FloatingActionList`: provides FAB functionality for one and more actions, mainly for usage within cards
- `Icon`: Icons with optional tooltips. Uses [mdl icons](https://design.google.com/icons/) which can be used with their ligature names.
- `Layout`: container of the MDL application
- `NotAvailable`: very simple element to use as "not available" placeholder information
- `Nothing`: Literally Nothing
- `Pagination`: A page control element
- `Progressbar`: Progressbar which may be placed globally or locally in a component
- `RadioGroup` and `Radio`: A radio button with optional label and grouping
- `SelectBox`: A selection box for choosing predefined values
- `Spinner`: Progressbar which may be placed globally or locally in a component
- `Switch`: A simple binary switch (a nicer checkbox)
- `Table`: A simple table which can be enriched with react elements as content.
- `Tabs`: A tabs container which manages tabbing behaviour
- `TextField`: A text field with floating label. Wrapper around [React-MDL Textfield]()
- `Version`: A normalised string output of product version
Usage is as simple as importing and rendering the components.
### Alert (Error, Info, Success and Warning)
```js
import { Alert, Error, Info, Success, Warning } from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
onDismiss(){ },
render() {
return (
This is a
untyped message.
info
success
warning
error with tooltip
)
},
// ....
});
```
### AutoCompleteBox
The AutoCompleteBox wraps `SelectBox`, it takes the same properties. The key differences are:
- rendering of multi-line options with label, value and description.
- If value and label are the same, only one is rendered
- descriptions are optional
- the options have to be an array of objects
- it is always searchable, while a SelectBox can be de-activated
```js
import { AutoCompleteBox } from '@eccenca/gui-elements';
const Page = React.createClass({
getInitialState(){
return {
value: null,
};
},
selectBoxOnChange(value){
this.setState({
value
});
},
// template rendering
render() {
return (
console.log(value)} // pass user input directly to parrent
showLabel={true} // define if label in options should be shown (default: true)
showValue={true} // define if value in options should be shown (default: true)
showDescription={true} // define if description in options should be shown (default: true)
/>
)
},
});
```
### Button
Read the [GUI spec about button usage](https://confluence.brox.de/display/ECCGMBH/GUI+Specifications#GUISpecifications-Buttons).
```js
import {Button, AffirmativeButton, DismissiveButton, DisruptiveButton} from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
Simple flat button
// according MDL-API, @see https://getmdl.io/components/index.html#buttons-section
A Button
// Icon button and Floating action button (FAB)
// use button elements to specify meaning of triggered action
// you can combine it with button properties like raised, iconName and ripple
Affirmative action
Dismissive action
)
},
// ....
});
```
Some special class names provide extra functionality:
* `mdl-button--clearance`: add it to buttons that clear input fields or whole input blocks, works with all button types.
#### ProgressButton
There is a special version of the Button element that can be used to visualize a running process. `` elements are shown as raised disabled buttons but this behaviour can be overwritten.
```js
import {ProgressButton} from '@eccenca/gui-elements';
import rxmq from 'ecc-messagebus';
// channel event which updates progressTopic
rxmq.channel('yourchannel').subject('progressNumber').onNext({
progress: 30, // integer, progress in percentage
lastUpdate: 'August 31st 2017, 9:48:24 am.', // string which should be a date, require tooltip to be set
});
const Page = React.createClass({
// template rendering
render() {
return (
Working!
)
},
// ....
});
```
You can use `progress` and `progressTopic` options directly on ``, `` and `` elements.
### Breadcrumb
The are two simple React elements to create breadcrumb navigation.
```js
import {
BreadcrumbList,
BreadcrumbItem,
} from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
Button
Link
Span
)
},
// ....
});
```
### Card
```js
import {
Card,
CardTitle,
CardMenu,
CardContent,
CardActions
} from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
Card title
Menu item 1
Menu item 2
)
},
// ....
});
```
### Content
```js
import {Content} from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
Your content is here.
)
},
// ....
});
```
### FloatingActionList
The `` element provides functionality for a quick adaption of the floating action button (FAB) pattern from Material Design.
It can be configured with a single action handler or a list of them. Then it opens a list of provided actions when activated, with a single action it will trigger the configured event handler immediately.
The position of the FAB is always the right bottom corner within the card but there is an `fixed` option to made it always visible in case the card is not fully shown in the viewport.
When there is already a fixed `` element in use put the `` in it to use it fixed.
```js
import {
Card,
CardTitle,
CardContent,
CardActions,
FloatingActionList
} from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
Card title
Card title
)
},
// ....
});
```
### Icon
```js
import {Icon} from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
)
},
// ....
});
```
### Checkbox and Switch
```js
import { Checkbox, Switch} from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
This is checked by default
Disabled Checkbox with label
Checkbox 3 Text
)
},
// ....
});
```
### Chip and ChipVisual
`` and `` are a wrapper around react-mdl's `` and ``.
`` is essentially the same as in react-mdl, but does not allow of `onClose`.
`` supports images, icons and text labels.
```js
import { ChipVisual, Chip } from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
plain chip
Chip with URI
console.log('#1 chip clicked')} // click handler, default: false
>
clickable with image visual
console.log('#2 chip clicked')}
>
clickable with text visual
plain chip with icon
)
},
// ....
});
```
### RadioGroup and Radio
```js
import { Radio, RadioGroup} from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
Radio 2 Text
Radio 3 Text
Line 2
)
},
// ....
});
```
### ConfirmationDialog
```js
import { Button, ConfirmationDialog } from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
Cancel}
confirmButton={Yes}
>
Dialog Content
)
},
// ....
});
```
### BaseDialog
```js
import { Button, BaseDialog } from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
Cancel,
Yes,
More
]}
>
Dialog Content
)
},
// ....
});
```
### ContextMenu
```js
import { ContextMenu, MenuItem } from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
First Item
Second Item
Menu Item 3
Another Menu Item
Alright
)
},
// ....
});
```
### DateField
```js
import { DateField } from '@eccenca/gui-elements';
const Page = React.createClass({
// value is the date shown to the user
// rawValue is the ISO 8601 representation if value is valid
// isValid indicates if given value matches the defined representation
onChange({value, rawValue, isValid, name}) {
this.setState({
[name]: value,
})
},
// template rendering
render() {
return (
)
},
// ....
});
```
### DateTimeField
```js
import { DateTimeField } from '@eccenca/gui-elements';
const Page = React.createClass({
// value is the date shown to the user
// rawValue is the ISO 8601 representation if value is valid
// isValid indicates if given value matches the defined representation
onChange({value, rawValue, isValid, name}) {
this.setState({
[name]: value,
})
},
// template rendering
render() {
return (
)
},
// ....
});
```
### Layout
```js
import { Layout } from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
...
)
},
// ....
});
```
### NotAvailable
Use that element as very simple "not available" placeholder information, e.g. in empty table cells or statistic overviews.
It currently only supports short label strings and long descriptions used as tooltip addition.
```js
import { NotAvailable } from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
)
},
// ....
});
```
### Nothing
```js
import { Nothing } from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
)
},
// ....
});
```
### Pagination
```js
import { Pagination } from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
)
},
// ....
});
```
### Progressbar
```js
import { Progressbar } from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
)
},
// ....
});
```
### Spinner
The Spinner is global by default.
```js
import { Spinner } from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
)
},
// ....
});
```
### SelectBox
The SelectBox wraps [react-select](https://github.com/JedWatson/react-select) to use mixed content of strings and numbers as well as the default object type.
Please refer to all available properties in the linked documentation.
The SelectBox behaves like a [controlled input](https://facebook.github.io/react/docs/forms.html#controlled-components)
```js
import { SelectBox } from '@eccenca/gui-elements';
const Page = React.createClass({
getInitialState(){
return {
value: 8,
};
},
selectBoxOnChange(value){
this.setState({
value
});
},
// template rendering
render() {
return (
('New stuff: ' + newLabel)} // change default "Create option 'newLabel'" to "New stuff: 'newLabel'"
multi={true} // allow multi selection
clearable={false} // hide 'remove all selected values' button
searchable={true} // whether to behave like a type-ahead or not
/>
)
},
});
```
Note:
- if objects are used in multi selectable options you can add {"clearableValue": false} to it to hide delete button for this specifc object
- if "creatable" is set new values will be applied on Enter, Tab and Comma (",")
- ``placeholder`` label is used within MDL floating label layout
### Table
Provides a simple table which can be enriched with react elements as content.
```js
import {Table} from '@eccenca/gui-elements';
class Page extends React.Component {
// ....
// template rendering
render() {
return (
)
},
// ....
};
```
#### Properties
- **children** (node) -
- **className** (string) - string (optional): additional CSS class name
- **fullWidth** (bool, default: false) - use full width even for smaller tables
- **multiline** (bool, default: false) - allow linebreaks and multilined content in table cells
### Table body
Provides table body element that can be enriched by sub elements.
```js
import {TableBody} from '@eccenca/gui-elements';
class Page extends React.Component {
// ....
// template rendering
render() {
return (
)
},
// ....
};
```
#### Properties
- **children** (node) -
- **className** (string) - string (optional): additional CSS class name
- **multiline** (bool, default: false) - allow linebreaks and multilined content in table cells
### Table cell
Provides table cell element that can be enriched by sub elements.
```js
import {TableCell} from '@eccenca/gui-elements';
class Page extends React.Component {
// ...
// template rendering
// use it inside the correct Table elements
render() {
return (
)
},
// ...
};
```
#### Properties
- **children** (node) -
- **className** (string, default: '') - optional CSS class
- **isHead** (bool, default: false) - table cell is head for column or row
- **likeHead** (bool, default: false) - table cell looks like header cell
- **multiline** (bool, default: false) - allow linebreaks and multilined content in table cells
### Table head
Provides table head element that can be enriched sub elements.
```js
import {TableHead} from '@eccenca/gui-elements';
class Page extends React.Component {
// ....
// template rendering
render() {
return (
)
},
// ....
};
```
#### Properties
- **children** (node) -
- **className** (string) - string (optional): additional CSS class name
- **multiline** (bool, default: false) - allow linebreaks and multilined content in table cells
### Table row
Provides table row element that can be enriched by sub elements.
```js
import {TableRow} from '@eccenca/gui-elements';
class Page extends React.Component {
// ...
// template rendering
// use it inside the correct Table elements
render() {
return (
)
},
// ...
};
```
#### Properties
- **children** (node) -
- **className** (string, default: '') - optional CSS class
- **multiline** (bool, default: false) - allow linebreaks and multilined content in table cells
### Tabs
```js
import { Tabs } from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
)
},
// ....
});
```
### TextField
```js
import { TextField } from '@eccenca/gui-elements';
const Page = React.createClass({
// event is the original react onChange event
// value is event.target.value (a shortcut for convienience)
onChange({value, event, value}) {
this.setState({
[name]: value,
})
},
// template rendering
render() {
return (
)
},
// ....
});
```
### Tooltip
You need to add wrapper to some elements, e.g. icons or checkboxes, to prevent unexepected behaviour. Use `` for inline elements and `` for block elments. If you have `tooltip` options, e.g. on icons, then use that parameter instead of the `` element.
```js
import {Tooltip} from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
I have a tooltip.
)
},
// ....
});
```
### Version
```js
import { Version } from '@eccenca/gui-elements';
const Page = React.createClass({
// template rendering
render() {
return (
)
},
// ....
});
```