@pushengineering/umg-web-components 2.0.0 → 2.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushengineering/umg-web-components",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "type": "module",
   "module": "dist/packages/web-components/components/index.js",
   "files": [
@@ -33,6 +33,7 @@
     "./media": "./dist/packages/web-components/components/media/media.js",
     "./media-text": "./dist/packages/web-components/components/media-text/media-text.js",
     "./menu": "./dist/packages/web-components/components/menu/menu.js",
+    "./menu-bar": "./dist/packages/web-components/components/menu-bar/menu-bar.js",
     "./modal": "./dist/packages/web-components/components/overlay/overlay.js",
     "./number-field": "./dist/packages/web-components/components/number-field/number-field.js",
     "./overlay": "./dist/packages/web-components/components/page/page.js",
@@ -59,7 +60,6 @@
     "gr": "rollup -c"
   },
   "dependencies": {
-    "@umg-components/design-tokens": "workspace:^",
     "lit": "^2.7.2"
   },
   "devDependencies": {

package/readme.md

@@ -9,18 +9,7 @@
   - [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.
 
@@ -90,177 +79,3 @@ With Storybook, you can easily navigate and explore our components:
 - 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.
-