@umbraco-ui/uui 1.17.0 → 2.0.0-alpha.1

package/README.md

@@ -1,57 +1,114 @@
-# uui
+![UI Library](docs/images/UI.png)
 
-[![npm](https://img.shields.io/npm/v/@umbraco-ui/uui?logoColor=%231B264F)](https://www.npmjs.com/package/@umbraco-ui/uui)
+# [Umbraco UI Library](https://uui.umbraco.com/)
 
-The full Umbraco UI Library. The package includes and registers all UUI Web Components.
+[![Build](https://github.com/umbraco/Umbraco.UI/actions/workflows/tests.yml/badge.svg)](https://github.com/umbraco/Umbraco.UI/actions/workflows/tests.yml) [![Storybook build](https://github.com/umbraco/Umbraco.UI/actions/workflows/azure-static-web-apps-delightful-beach-055ecb503.yml/badge.svg)](https://github.com/umbraco/Umbraco.UI/actions/workflows/azure-static-web-apps-delightful-beach-055ecb503.yml) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=umbraco_Umbraco.UI&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=umbraco_Umbraco.UI) [![npm](https://img.shields.io/npm/v/@umbraco-ui/uui?logoColor=%231B264F)](https://www.npmjs.com/package/@umbraco-ui/uui) [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
 
-## Installation
+A collection of 80+ web components for building [Umbraco CMS](https://umbraco.com/) interfaces. Built with [Lit](https://lit.dev/) and TypeScript. Browse them in the [Storybook](https://uui.umbraco.com/).
 
-### ES imports
+## Installation
 
-```zsh
-npm i @umbraco-ui/uui
+```sh
+npm install @umbraco-ui/uui
 ```
 
-Import the registration of all `uui` web components via:
+**Requirements:** Node >= 24.13, npm >= 11. Runtime dependency: [Lit](https://lit.dev/) ^3.0.0.
+
+## Quick start
+
+Import only the components you need — your bundler will tree-shake the rest:
+
+```js
+import '@umbraco-ui/uui/components/button/button.js';
+import '@umbraco-ui/uui/components/input/input.js';
+```
 
-```javascript
-import '@umbraco-ui/uui';
+```html
+<uui-button look="primary" label="Save"></uui-button>
+<uui-input label="Name"></uui-input>
 ```
 
-### CDN
+Or register everything at once with `import '@umbraco-ui/uui';`.
 
-The component is available via CDN. This means it can be added to your application without the need of any bundler configuration. Here is how to use it with jsDelivr.
+Include a theme for CSS custom properties and typography:
 
 ```html
-<!-- Latest Version -->
-<script src="https://cdn.jsdelivr.net/npm/@umbraco-ui/uui@latest/dist/uui.min.js"></script>
-
-<!-- Specific version -->
-<script src="https://cdn.jsdelivr.net/npm/@umbraco-ui/uui@X.X.X/dist/uui.min.js"></script>
-```
-
-### Included components
-
-| Component                                                                                                  | Status                                                                                     |
-| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| [`<uui-avatar-group>`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-avatar-group)           | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-avatar-group?logoColor=%231B264F)      |
-| [`<uui-avatar>`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-avatar)                       | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-avatar?logoColor=%231B264F)            |
-| [`<uui-badge>`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-badge)                         | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-badge?logoColor=%231B264F)             |
-| [`uui-base`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-base)                             | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-base?logoColor=%231B264F)              |
-| [`<uui-box>`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-box)                             | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-box?logoColor=%231B264F)               |
-| [`<uui-breadcrumbs>`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-breadcrumbs)             | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-breadcrumbs?logoColor=%231B264F)       |
-| [`<uui-button>`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-button)                       | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-button?logoColor=%231B264F)            |
-| [`<uui-button-group>`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-button-group)           | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-button-group?logoColor=%231B264F)      |
-| [`<uui-checkbox>`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-checkbox)                   | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-checkbox?logoColor=%231B264F)          |
-| [`<uui-input>`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-input)                         | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-input?logoColor=%231B264F)             |
-| [`<uui-keyboard-shortcut>`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-keyboard-shortcut) | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-keyboard-shortcut?logoColor=%231B264F) |
-| [`<uui-loader>`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-loader)                       | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-loader?logoColor=%231B264F)            |
-| [`<uui-loader-bar>`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-loader-bar)               | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-loader-bar?logoColor=%231B264F)        |
-| [`<uui-loader-circle>`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-loader-circle)         | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-loader-circle?logoColor=%231B264F)     |
-| [`<uui-radio>`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-radio)                         | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-radio?logoColor=%231B264F)             |
-| [`<uui-slider>`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-slider)                       | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-slider?logoColor=%231B264F)            |
-| [`<uui-table>`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-table)                         | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-table?logoColor=%231B264F)             |
-| [`<uui-tabs>`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-tabs)                           | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-tabs?logoColor=%231B264F)              |
-| [`<uui-tag>`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-tag)                             | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-tag?logoColor=%231B264F)               |
-| [`<uui-toggle>`](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui-toggle)                       | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui-toggle?logoColor=%231B264F)            |
-| [`uui` bundle package](https://github.com/umbraco/Umbraco.UI/tree/dev/packages/uui)                        | ![npm](https://img.shields.io/npm/v/@umbraco-ui/uui?logoColor=%231B264F)                   |
+<link
+  rel="stylesheet"
+  href="node_modules/@umbraco-ui/uui/dist/themes/light.css" />
+```
+
+Apply the `uui-font` and `uui-text` classes to the element that should carry UUI typography (typically `<body>`):
+
+```html
+<body class="uui-font uui-text">
+  ...
+</body>
+```
+
+No bundler? Use UUI directly in the browser via [import maps](docs/USAGE-WITHOUT-BUNDLER.md).
+
+## Components
+
+80+ components across 13 categories: Buttons, Inputs, Color, Cards, Refs, Feedback, Layout, Forms, Navigation, Icons, Files, Symbols, and Data.
+
+Each component has its own README in [`src/components/{name}/`](src/components/).
+
+- [Browse in Storybook](https://uui.umbraco.com/)
+- [Full component list](docs/COMPONENTS.md)
+
+## Documentation
+
+See [docs/](docs/) for the full documentation index.
+
+## Development
+
+### Setup
+
+Requires Node.js >= 24.13 (see `.nvmrc`) and npm >= 11.
+
+```sh
+git clone https://github.com/umbraco/Umbraco.UI.git
+cd Umbraco.UI
+npm install
+```
+
+### Key commands
+
+| Command                            | Description                                        |
+| ---------------------------------- | -------------------------------------------------- |
+| `npm run storybook`                | Start Storybook dev server on port 6006            |
+| `npm run build`                    | Build the library (Vite + TypeScript declarations) |
+| `npm run test`                     | Run all tests with coverage                        |
+| `npm run test:coverage-for button` | Run tests for a single component                   |
+| `npm run lint`                     | Lint with ESLint                                   |
+| `npm run format`                   | Auto-fix lint and formatting                       |
+
+See [docs/SCRIPTS.md](docs/SCRIPTS.md) for the full list.
+
+### Project structure
+
+```
+src/
+├── internal/     # Mixins, events, types, registration
+├── styles/       # CSS custom properties and text styles
+├── themes/       # Light and dark theme CSS
+├── components/   # 80+ component directories
+└── index.ts      # Barrel — re-exports everything
+```
+
+### Branching model
+
+- **`main`** — development branch, PR target ([storybook](https://delightful-beach-055ecb503-main.westeurope.azurestaticapps.net/))
+- **`production`** — published release, serves Storybook at [uui.umbraco.com](https://uui.umbraco.com)
+- **`release/*`** — intermediary releases (RCs)
+
+## Contributing
+
+Pull requests and stars are always welcome. Read the [contributing guide](docs/CONTRIBUTING.md) to get started.
+
+Report bugs and feature requests in the [issue tracker](https://github.com/umbraco/Umbraco.UI/issues).
+
+## License
+
+[MIT](LICENSE.md)