Xtreamr-components

examples: https://xtreamr.github.io/xtreamr_components/

Package commands

Start Storybook components guide in local

yarn start

This command first make a build for publish to npm. Then, make a new tag in repo and publish to npm. And also publsih the examples in ghpages.

yarn release
yarn release:minor
yarn release:major 

There are other commands (in order) for make storybook release folder, make a gh pages and make a new tag release

yarn build-storybook
yarn ghpages
yarn release

NPM

https://www.npmjs.com/package/@xtreamr/xtreamr-components

Folder structure

• src
  • index.js (to expose the components library)
  • settings
    • variables.css
    • themes.css
    • …
  • components
    • name
      • name.js
      • name.css
      • name.stories.md
    • …
  • enhancers
    • withVerb.js
  • services
    • Service
      • ServiceActions.js
      • ServiceReducer.js
      • ServiceSelectors.js
      • ServiceService.js
      • ServiceSignals.js
      • index.js (to export the above files)  

How to write components

0. We export all components in src/index to then expose the component for npm

• if a component ins't exported here is not possible to use from '@xtreamr/xtreamr-components' dependency
• Importing components: import { ComponentName, ... } form '@xtreamr/xtreamr-components'

1. Create a folder with the name of the component and into should have

• Component.js
• Component.css
• Component.stories.js

2. At least all components should define this props:

• id (should be placed in the wrapper element and also in all elements with events)
• className (overwrite the default className)
• extraClass (this add a extra class but not delete the default class of the component)

3. Context class

• Context class should be placed in the wrapper element
• Should have the same name of the component but with "-" instead camelcase
• Should have the prefix "xt-"
• xt-[context-class-name]

4. Elements that are into the component

• Should be a class with the same name of the context class + their name
• xt-[context-class-name]-[element-name]
• Same if a element contains elements
• xt-[context-class-name]-[element-name]-[element-name-deep]

5. Modificators or status classes

• No context and no prefix
• In the css file should be ever defined toguether with a context class o element class
• .xt-context-class.positive or xt-context-class-element.hover

6. All css variables are defined into: settings/variables

• We use role name variables https://fixate.it/blog/make-your-css-variable-names-suck-less/
• Into components you can define local variables for overwrite the globals.
• .button { --clrMinButton: var(--clrMin, #fafafb); }

7. Components position rules

• Components never define their position into the dom
• Avoid use of: margin, position, flex...
• Should be flexible for fit into all contexts
• Components define the position and margin of their children elements

Icons

• The icons are autogenerated using the script:
• Use svgo for compress the svg and svgr for make the IconComponent

How to add icons

1. Place into assets/icons the svg file
2. Name svg file: inco[Name].sg
3. Expose the new icons generated on src/index.js

• Use this command for make the magic

yarn icons

• The svg name is use for name the component icon generated
• Icons are generated inton icons/
• Svgr use the file icon.template.js to create the icons

Services

Usually we make services with redux or tokbox. The cicle of redux is ever the same:

• UI event -> dispatch action -> reducer change the state -> render with new state

But, tokbox use signals and our applicatios are listening that signals and in some cases the signals are dispatching actions. Then, exist this alternative flow:

• Signal received -> dispatch action -> reducer change the state -> render with new state

Then we have to kind of event to start the redux flow: ui events or signals.

To know

• Avoid circular dependency between services
• Avoid ciruclar dependency between service and actions. The service can dispatch actions but action can't use the service.
• Domain for actions: DOMAIN/ACTION_NAME
• All API calls should dispatch simple actions: REQUEST action, SUCCESS action and FAIL action describing the request/response flow.

Describe Xtreamr-components here.