@pushengineering/umg-web-components 2.0.0

package/readme.md

@@ -0,0 +1,266 @@
+# Table of Contents
+
+- [Table of Contents](#table-of-contents)
+- [UMG UX Components Library README](#umg-ux-components-library-readme)
+  - [Learn More about Web Components](#learn-more-about-web-components)
+- [Local Development Environment](#local-development-environment)
+  - [Prerequisites](#prerequisites)
+  - [Installation](#installation)
+  - [Build scripts](#build-scripts)
+- [Lit - Lightning-Fast Components](#lit---lightning-fast-components)
+- [Storybook Integration for Component Previews and Documentation](#storybook-integration-for-component-previews-and-documentation)
+- [Integrating UMG Components into Your Project](#integrating-umg-components-into-your-project)
+  - [Package installation](#package-installation)
+  - [Importing components](#importing-components)
+  - [Theme Styling](#theme-styling)
+    - [Design Tokens](#design-tokens)
+      - [Installing the default theme and system tokens](#installing-the-default-theme-and-system-tokens)
+      - [Types of Design Tokens](#types-of-design-tokens)
+      - [Leveraging Design Tokens](#leveraging-design-tokens)
+    - [More Ways to Customise](#more-ways-to-customise)
+    - [CSS Selector Rules](#css-selector-rules)
+    - [CSS Selectors Cheatsheet](#css-selectors-cheatsheet)
+- [Chromatic notes](#chromatic-notes)
+# UMG UX Components Library README
+Welcome to the UMG UX Components Library! This library provides a collection of UX frontend components designed to be fast, reusable, and highly customisable for any project, without relying on proprietary technologies or frameworks. These components leverage standard Web APIs and are compatible with all modern browsers.
+
+## Learn More about Web Components
+To deepen your understanding of web components, their key concepts, and the specific web APIs we employ, we recommend reading the [MDN guide on Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components).
+
+  
+# Local Development Environment
+
+## Prerequisites
+
+Before you begin, make sure you have the following prerequisites installed on your system:  
+
+Node.js v16.14 or higher. You can download it from [here](https://nodejs.org/en/download)  
+[PNPM](https://pnpm.io/) v8 or higher. Install it via these links: [Mac](https://github.com/nvm-sh/nvm) | [Windows](https://github.com/coreybutler/nvm-windows)
+
+## Installation
+1. Install Node.js globally using one of the following methods:
+- Mac: [NVM](https://github.com/nvm-sh/nvm)
+- Windows: [NVM for Windows](https://github.com/coreybutler/nvm-windows)
+- Direct download: [Node.js](https://nodejs.org/en/download)
+
+2. Install PNPM globally using one of the following methods:
+- Mac: ``brew install pnpm``
+- Windows PowerShell: Run the command ``iwr https://get.pnpm.io/install.ps1 -useb | iex``  
+
+For more details, check the: [PNPM documentation](https://pnpm.io/)
+
+1. Clone the project repository using this command:  
+   ```
+   git clone git@github.com:Push-Entertainment/umg-component-library.git
+   ```
+
+2. Initialise the project by running the following command in your terminal within the project's root directory:  
+   ```
+   pnpm install
+   ```
+
+## Build scripts
+
+We've provided various build scripts to streamline your development process:
+
+- Develop components: `pnpm dev`
+- Develop Storybook: `pnpm dev-storybook`
+- Build components and design tokens: `pnpm build`
+- Build components, design tokens and Storybook static site: `pnpm build-all`
+- Build design tokens: `pnpm build-tokens`
+- Build Storybook static site: `pnpm build-storybook`
+
+# Lit - Lightning-Fast Components
+
+Our library is built using Lit, a framework that simplifies component development without sacrificing performance or relying on non-standard frameworks. Lit builds on web component standards, is lightweight, and reduces boilerplate code. You can find Lit 2's documentation [here](https://lit.dev/docs/).
+
+To save time, minimise errors, and future-proof your code, we've written this library in TypeScript and utilise Lit's decorator methods, which TypeScript transpiles into browser-compatible JavaScript.
+
+# Storybook Integration for Component Previews and Documentation
+
+We've seamlessly integrated Storybook into our component library to provide you with a powerful playground tool with component previews and comprehensive documentation. Storybook serves as a valuable resource for both developers and designers, offering a visual representation of each component's behavior and appearance in different scenarios.
+
+- Exploring Components in Storybook
+With Storybook, you can easily navigate and explore our components:
+
+- Preview Components: View live, interactive previews of each component to understand how they look and behave in various situations.
+
+- Component Variations: Explore different variations and configurations of each component, helping you tailor them to your specific project requirements.
+
+- Interactive Documentation: Access detailed documentation and usage examples for each component, making it easier to implement them effectively in your project.
+
+The Storybook application can be loaded into a browser by running `pnpm dev-storybook` in `node_modules/@pushengineering/umg-components`.
+
+# Integrating UMG Components into Your Project
+## Package installation
+
+To integrate UMG Components into your project, follow these steps:  
+
+1. Ensure you have [Node v16.14^](https://nodejs.org/en/download) installed globally or locally within your project.
+2. In your project's source folder, create a `package.json` file with a minimum configuration like this:
+```
+{
+  "name": "project-name",
+  "target": "web",
+  "type": "module",
+  "sideEffects": false,
+  "dependencies": {
+    "@pushengineering/umg-components": "^1.0.0"
+  },
+}
+```
+3. In the root of your project's source folder, run the following command:  
+   ```
+   npm run install
+   ```
+   If you've previously installed Node packages in your project, skip this step and run:  
+   ```
+   npm install @pushengineering/umg-components --save-dev
+   ```
+
+## Importing components
+Our components are written as ES6 modules for seamless integration into your project without the need for transpilation through tools like Webpack or Babel. You can still use pre-processors like Vite, Webpack, or Roll-up for tree shaking and minification while preserving ES modules.
+
+To initialise a web component and render it in your HTML and the DOM, simply import the component script within your page's entry scripts or as a script tag directly inside your page.
+
+For example, to import the slider web component and its internal component dependencies, add the following to your main script or as a script tag in your page:
+
+```
+import '@pushengineering/umg-web-components/slider'
+```
+Or use a script tag like this:  
+
+```
+<script async type="module" src="path-to-component-modules/slider.js">
+```
+
+If the slider component contains additional web components, such as image banners, you'll also need to import them:  
+
+```
+import '@pushengineering/umg-web-components/banner'
+import '@pushengineering/umg-web-components/image'
+```
+
+If these banner image components require captions with text and buttons, import them as well:  
+
+```
+import '@pushengineering/umg-web-components/button-group'
+import '@pushengineering/umg-web-components/button'
+import '@pushengineering/umg-web-components/text'
+``````
+
+Once imported, you can use these components throughout your page without further imports.  
+
+## Theme Styling
+
+### Design Tokens
+Our UMG UX Components Library is designed on top of a design system that uses custom CSS variables also known as design tokens. These design tokens are mapped to default values assigned to various elements within our components and at the document level. They empower you to customize the theme in a cascading, controlled manner, ensuring consistent design and behavior throughout your application.
+
+#### Installing the default theme and system tokens
+To ensure that unthemed components display as intended, it's crucial to include the default design tokens in your application.  
+
+Follow these steps to integrate the default design tokens into your application:  
+
+1. Navigate to the following directory in your application: `/your-local-source-folder/node_modules/@pushengineering/umg-web-components/packages/web-components/public`.
+2. In your code editor open the `design-tokens.css` file.
+3. Copy the contents of this file.
+4. Paste the copied contents inside a `<style>` tag within the `<head>` section of your application's HTML page. This approach optimises page performance compared to linking to an external stylesheet.
+
+#### Types of Design Tokens
+We've organised our design tokens into two distinct groups, each serving a specific purpose:
+
+1. **Theme Customisation Tokens**  
+The first group of design tokens empowers developers to freely theme the component library without compromising core behavior and design consistency. These tokens cover a wide range of areas, including:
+
+    - Typography
+    - Colour
+    - Shape
+    - Space
+    - And more
+    
+    With these tokens, you have the flexibility to tailor the look and feel of our components to align perfectly with your project's unique visual identity. They allow you to adapt our components to your brand's colour scheme, typography, and spacing guidelines, among other things.
+
+2. **Opinionated Design Tokens**  
+The second group of design tokens consists of opinionated values that solidify our components' expected behavior. These tokens are meticulously crafted to ensure accessibility and deliver an exceptional user experience. They are founded on a series of memorable visual scales governing:
+
+    - Type
+    - Grids
+    - Responsive Sizing and Spacing
+    - Borders
+    - And more
+    
+    These opinionated tokens establish consistency in design and reduce decision-making overhead where it is least useful in terms of customisation. By adhering to these scales, you can rest assured that our components will consistently deliver a cohesive and user-friendly experience across your application.
+
+#### Leveraging Design Tokens
+To make use of these design tokens, simply customise their values to align with your design system's specifications. You can override the default values assigned to the tokens, tailoring them to your project's exact requirements.
+
+By integrating our components with your design tokens, you'll be able to achieve a harmonious blend of visual consistency and user experience excellence in your application, while also benefiting from the flexibility to adapt our components to your unique brand identity.
+
+### More Ways to Customise
+Our component styles are encapsulated within web component shadow DOMs, to prevent external styles from inadvertantly targeting elements and creating unwanted side effects. You can safely use CSS variables or custom properties to style components, but we also provide the CSS `::part` and `::part()` selectors for more targeted styling within shadow DOMs.  
+
+If you need to apply external styles to web component elements when all the above fails to achieve your design needs, consider using [constructed stylesheets](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet/CSSStyleSheet). We've registered a constructed stylesheet named `umgtheme` that's adopted by each web component in the library.
+
+To use this feature, add the following script to your theme template, updating the paths to match your project structure, and ensuring that it runs early in the script loading order:
+
+```
+<script type="module">
+     /* Local path './node_modules/@pushengineering/umg-web-components/lit' */
+    import { css, unsafeCSS } from '../node_modules/lit'
+
+    window.constructibleStyleSheets = {};
+
+    const styleSheetPromise = (cssPath, variableName) => fetch(cssPath)
+        .then(response => response.text())
+        .then(cssRaw => {
+            const cssResult = css`${unsafeCSS(cssRaw)}`;
+            window.constructibleStyleSheets[variableName] = cssResult;
+            return cssResult.styleSheet;
+        }).catch(error => console.error(`😡 [${variableName}]`, error));
+
+    Promise.all([
+        styleSheetPromise(
+          "/global.css", /* path-to-public-stylesheet */
+           "umgtheme", /* Do not edit */
+        )
+    ]).then(styleSheets => {
+        document.adoptedStyleSheets = styleSheets; 
+    }); 
+</script>
+```
+
+### CSS Selector Rules
+
+When styling web components from an external stylesheet, keep these rules in mind:  
+
+- Elements rendered in Light DOM are targetable as usual with standard CSS selectors.
+
+- To target elements within shadow roots or the Shadow DOM, you can pass values via CSS variables registered for elements within the Shadow DOM. Combine standard CSS selectors with the `::part()` CSS pseudo-element selector by referencing the element's part name, e.g., `#section-name::part(button)`.
+
+- To specifically target an element in the shadow root with a part name shared by other elements on the page, you can uniquely reference the element using a unique parent ID or class along with the `::part()` selector, e.g., `#section-name .slide-button::part(button)`.
+
+### CSS Selectors Cheatsheet
+
+|                  **Target**: | doc-root | custom-element | custom-element-root |  shadow-root  |             light-dom            |
+|-----------------------------:|:--------:|:--------------:|:-------------------:|:-------------:|:--------------------------------:|
+|               selector path: |          |                |                     |               |                                  |
+|               stylesheet.css |     ✓    |        ✓       |          ✓          | *::part(foo)  |                 ✓                |
+|                  doc-style > |     ✓    |        ✓       |          ✓          |       x       |                 ✓                |
+| doc-style > custom-element > |          |        ✓       |          ✓          | *::part(foo)  |                 ✓                |
+|             custom-element > |          |      :host     |          ✓          |       ✓       | ::slotted(foo) NOT [root]class > |
+
+
+# Chromatic notes
+
+Please note that Chromatic requires Node.js to be at version 16.19.1 or lower. Versions higher than this may cause issues with the CLI.  
+
+To install Chromatic CLI, run the following command:  
+
+```
+# npm
+npm install --save-dev chromatic
+```
+
+Make sure to set the `CHROMATIC_PROJECT_TOKEN` in your environment to enable the `npm run chromatic` command.  
+You can find your project token in Chromatic under Project → Manage.
+