search

RocketCommunicationsInc / astro-components

Other
24 stars 8 forks source link

readme

NOTE: The Astro Component using Lit Element are in maintenace mode

Please see new improved Stencil based components available at https://github.com/RocketCommunicationsInc/astro/blob/main/packages/web-components/readme.md and have your voice heard before release. The updated components are quite mature and we would encourage new projects to seriously consider using the updated Stencil components moving forward.

Astro Web Component and CSS Library

The Astro Web Component and CSS Library provides a starting point to begin developing Astro-compliant applications.

NOTE: The Astro Component Library is still new and tends to release breaking changes, but follows semver so you can control when you incorporate them. We typically follow a 6 month release schedule which includes two major release per year with breaking changes, and intermediate patch releases with bug fixes.

Download and Install for all Astro Web Components and Styles

The directions below assume basic knowledge of NodeJS. Make sure you have installed both globally before continuing. An example can be seen on the Astro Storybook site

Create a new directory and change directory

mkdir astro
cd astro

Clone this repository

git clone https://github.com/RocketCommunicationsInc/astro-components.git

Install NPM modules for this project

npm i

Run the Storybook Server

npm run storybook

Visit the site locally, the Storybook CLI process will notify you of the correct URL, but you can typically view the site in your browser at http://localhost:9001/

To make use of this repository as a basis for your application you will need to implement your own build system. We recommend Open WC as a starting point.

Download and Install for CSS Library

For projects that won’t use the Web Component Library you only need the contents of the static directory.

Clone this repository

git@github.com:RocketCommunicationsInc/astro-components.git

Copy the contents of the static directory (css, fonts, icons, img, favicon.ico) to your project directory. Create a link to the CSS.

For development

<link rel="stylesheet" href="https://github.com/RocketCommunicationsInc/astro-components/blob/master/css/astro.css" />

For production

<link rel="stylesheet" href="https://github.com/RocketCommunicationsInc/astro-components/blob/master/css/astro.min.css" />

Using NPM

Follow the instructions for downloading and installing the CSS Library

Use npm to install the UI Library Elements required for your project. For example to intall an Astro Button

npm i -D @astrouxds/rux-button

Backwards Compatibility

The Astro Component Library is designed for use on modern browsers that support the W3C Custom Elements Standard. For backwards compatibility with Pre-Chromium Edge and Firefox versions prior to Firefox 63 you will need to use the web components polyfill

Documentation

Component Package (if available as Web Component) Documentation Guidelines
Accordion @astrouxds/rux-accordion Guidelines
Buttons @astrouxds/rux-button Docs Guidelines
Checkbox n/a Guidelines
Clock @astrouxds/rux-clock Docs Guidelines
Dialog Box / Modal @astrouxds/rux-modal Docs Guidelines
Global Status Bar @astrouxds/rux-global-status-bar Docs Guidelines
Icons @astrouxds/rux-icon Docs Guidelines
Input Field n/a Guidelines
Links n/a Guidelines
Log @astrouxds/rux-log Docs Guidelines
Notification Banner @astrouxds/rux-notification Docs Guidelines
Pagination n/a Guidelines
Pop Up Menu @astrouxds/rux-pop-up-menu Docs Guidelines
Progress @astrouxds/rux-progress Docs Guidelines
Push Buttons @astrouxds/rux-push-button Docs Guidelines
Radio Button n/a Guidelines
Search n/a Guidelines
Select Menu n/a Guidelines
Segmented Button @astrouxds/rux-segmented-button Docs Guidelines
Slider @astrouxds/rux-slider Docs Guidelines
Status Symbol @astrouxds/rux-status Docs Guidelines
Table n/a Guidelines
Tabs @astrouxds/rux-tabs Docs Guidelines
Timeline @astrouxds/rux-timeline Guidelines
Toggle @astrouxds/rux-toggle Docs Guidelines
Tree @astrouxds/rux-tree Docs Guidelines

Contributing

Follow the style defined in /.eslintrc, installing such tools as your IDE supports for revealing discrepencies before committing.

Astro Web Components

The folders in /src/components/* contain the Web Components, which are tested using matching Stories in /stories/*. The Story files create instances of the components with various properties exposed via Storybook Knobs. All component variations should be demonstrated using Knobs before publishing or updating to ensure that the properties work as intended. There are heavily commented templates for Stories (/stores/__rux-.stories.template.js) and Components (/src/components/__rux-template/) to enable maintainers to quickly scaffold new Components. These component folders are what are ultimately published on NPM under the AstroUXDS org.

Further information on Contributing to Astro Web Components

Astro CSS

The Astro CSS library is used to style native HTML Elements and to set theme styles that are inherited throughout the application, even when developers do not use the Web Components themselves. The CSS is divided into partials in /src/css/*, which is concatenated into the /static/css/ files using PostCSS when the project builds using Gulp. See /gulpfile.js for more details.

Note: Changes to the Astro CSS should never be made directly to the /static/css/* files, as those are for distribution only.

Be sure to demonstrate any new or changed HTML elements using a Story. The Form Elements story (/stories/rux-form-elements.stories.js) shows how, even without a Web Component to mount, the functionality and variations can be displayed. If both Web Components and native HTML Elements can be used, such as in the case of Buttons (/stories/rux-button.stories.js), be sure to demonstrate both options.