@cupra/ui-react 2.0.0-canary.6 → 2.0.0-canary.7

package/README.md

@@ -1,10 +1,14 @@
 # UI React (React Components)
 
 ## Overview
+
 React components and wrappers built on top of the DS-UI Web Components, providing a seamless and idiomatic developer experience for React.  
 This package exposes React-friendly APIs (props, JSX, typed events) while preserving the DS-UI theming, styling, and asset resolution model.
 
+---
+
 ## Audience
+
 Use `@cupra/ui-react` if your application is built with **React** and you want:
 
 - First-class React ergonomics with DS-UI components
@@ -14,6 +18,8 @@ Use `@cupra/ui-react` if your application is built with **React** and you want:
 
 If you need a **framework-agnostic** solution, consider `@cupra/ui-kit` (Web Components).
 
+---
+
 ## Requirements & Compatibility
 
 This library currently provides **official support for React 18**.
@@ -22,11 +28,13 @@ This library currently provides **official support for React 18**.
 
 Projects using other React versions may still install and use the library, but behaviour is not guaranteed until official support is released.
 
-### TypeScript and module resolution
+---
+
+## TypeScript and module resolution
 
 This library is **bundler-first**.
 
-#### Subpath imports (recommended)
+### Subpath imports (recommended)
 
 Importing components via subpaths (for example `@cupra/ui-react/Accordion`) requires
 TypeScript to use **bundler-based module resolution**:
@@ -34,7 +42,7 @@ TypeScript to use **bundler-based module resolution**:
 - **TypeScript ≥ 5**
 - `"moduleResolution": "bundler"`
 
-This matches how modern bundlers resolve modules and enables the best DX,
+This matches how modern bundlers resolve modules and enables the best developer experience,
 including proper tree-shaking and code-splitting.
 
 Minimal required `tsconfig.json` setting:
@@ -47,64 +55,89 @@ Minimal required `tsconfig.json` setting:
     }
 ```
 
+Other compiler options (`target`, `module`, `lib`, etc.) are project-specific and can be configured as needed.
+
 ---
 
-#### Root imports (compatibility mode)
+### Root imports (compatibility mode)
 
-If your project cannot use `moduleResolution: "bundler"`, you can still consume
-the library using **root imports**:
+If your project cannot use `moduleResolution: "bundler"`, you can still consume the library using **root imports**:
 
 ```
     import { Accordion, IconButton } from "@cupra/ui-react";
 ```
 
-This mode works with legacy or constrained TypeScript setups, but has the
-following trade-offs:
+This mode works with legacy or constrained TypeScript setups, but has the following trade-offs:
 
 - Subpath imports are not available
 - Reduced tree-shaking and chunking opportunities
 - All components are imported from the package entry point
 
-Root imports are supported as a fallback, but **subpath imports are recommended
-whenever possible**.
+Root imports are supported as a fallback, but **subpath imports are recommended whenever possible**.
 
 ---
 
-#### Notes
+### Notes
 
 - Subpath imports are intentionally designed for bundler-based environments.
 - The library does not attempt to enforce Node-style module resolution.
 - No additional runtime configuration is required when using a modern bundler.
-## Installation
 
-### Install the package
-- npm: `npm install @cupra/ui-react`
-- pnpm: `pnpm add @cupra/ui-react`
-- yarn: `yarn add @cupra/ui-react`
+---
+
+## Getting started
+
+### Installation
+
+`@cupra/ui-react` is a React wrapper around the Web Components provided by
+`@cupra/ui-kit`.
 
-### Registry configuration (only if needed)
+For this reason, **both packages must be installed** in your project.
 
-**.npmrc**
+Using npm:
 
-```ini
-@cupra:registry=https://registry.npmjs.org
+```
+    npm install @cupra/ui-react @cupra/ui-kit
+```
+
+Using pnpm:
+
+```
+    pnpm add @cupra/ui-react @cupra/ui-kit
 ```
 
-**.yarnrc.yml**
+Using yarn:
 
-```yaml
-npmScopes:
-cupra:
-npmRegistryServer: "https://registry.npmjs.org"
 ```
+    yarn add @cupra/ui-react @cupra/ui-kit
+```
+
+---
+
+### About peer dependencies
+
+`@cupra/ui-kit` is declared as a **peer dependency** of `@cupra/ui-react`.
+
+This means:
+
+- `@cupra/ui-react` does not bundle or ship the Web Components itself
+- the consuming project must provide a compatible version of `@cupra/ui-kit`
+- only a single instance of the design system is expected at runtime
+
+Some package managers (such as npm ≥ 7 or pnpm with compatible settings) may install
+peer dependencies automatically. Others (such as Yarn) require installing them explicitly.
+
+If you encounter missing-module or runtime errors after installing `@cupra/ui-react`,
+make sure that `@cupra/ui-kit` is also installed in your project.
 
 ---
 
 ## Documentation & Live Playground
 
-You can explore all `ui-react` Components, their APIs, theming options and live examples in the online documentation and playground:
+You can explore all `ui-react` components, their APIs, theming options and live examples
+in the online documentation and playground:
 
-[https://diagonal.cupra.com/ui-react/index.html](https://diagonal.cupra.com/ui-react/index.html)
+https://diagonal.cupra.com/ui-react/index.html
 
 ---
 
@@ -112,7 +145,8 @@ You can explore all `ui-react` Components, their APIs, theming options and live
 
 This package is distributed through npm using **two release channels**.
 
-### Stable Releases (`latest`)
+### Stable releases (`latest`)
+
 Production-ready versions:
 
 - Follow Semantic Versioning
@@ -121,19 +155,20 @@ Production-ready versions:
 
 Install:
 
-```bash
-npm install @cupra/ui-react
+```
+    npm install @cupra/ui-react
 ```
 
 Specific version:
 
-```bash
-npm install @cupra/ui-react@0.1.3
+```
+    npm install @cupra/ui-react@0.1.3
 ```
 
 ---
 
-### Canary Releases (`canary`)
+### Canary releases (`canary`)
+
 Early-access versions published after each merge into `main`.
 
 Use canary releases if you:
@@ -144,89 +179,99 @@ Use canary releases if you:
 
 Latest canary:
 
-```bash
-npm install @cupra/ui-react@canary
+```
+    npm install @cupra/ui-react@canary
 ```
 
 Specific canary version:
 
-```bash
-npm install @cupra/ui-react@0.1.4-canary.2
+```
+    npm install @cupra/ui-react@0.1.4-canary.2
 ```
 
 ---
 
 ## Recommended usage
 
-- **Production:** use **stable versions (e.g. `@cupra/ui-react@1.1.3`)**
-- **Internal testing / preview:** use **`canary`** (e.g. `@cupra/ui-react@canary` or `@cupra/ui-react@0.1.4-canary.2`)
-
-```bash
-npm install @cupra/ui-react@0.1.4-canary.2
-```
+- **Production:** use **stable versions** (for example `@cupra/ui-react@1.1.3`)
+- **Internal testing / preview:** use **canary** versions
 
 ---
 
 ## Usage
 
-Import components via subpaths. Do not import from the package index:
-- @cupra/ui-react → React wrappers built on top of the Web Components (e.g. `import { Button } from '@cupra/ui-react/Button'`)
+When possible, import components via subpaths:
+
+```
+    import { Button } from "@cupra/ui-react/Button";
+```
 
-If you see TypeScript errors like `TS2307: Cannot find module '@cupra/ui-react/Accordion'`, check your `tsconfig` and apply one of the configurations from the section above. With TS 4.9 + `node`, the library publishes `typesVersions` to resolve subpath typings, but the recommendation is to use `bundler` (TS ≥ 5) or `node16`/`nodenext`.
+If your TypeScript setup does not support bundler-based module resolution, use root imports instead:
+
+```
+    import { Button } from "@cupra/ui-react";
+```
+
+Wrap your React application with `ThemeProvider`.
 
-Wrap your React app with `ThemeProvider`.  
 The provider requires **three props**:
 
-| Prop       | Type    | Required | Description                                   |
-|------------|---------|----------|-----------------------------------------------|
-| `theme`    | string  | Yes      | Visual theme identifier (e.g. cupra-diagonal) |
-| `loadFonts` | boolean | Yes     | Auto-load DS-UI font files                    |
-| `loadStyles` | boolean | Yes    | Auto-load DS-UI CSS                           |
+| Prop        | Type    | Required | Description                                   |
+|-------------|---------|----------|-----------------------------------------------|
+| `theme`     | string  | Yes      | Visual theme identifier (e.g. cupra-diagonal) |
+| `loadFonts` | boolean | Yes      | Auto-load DS-UI font files                    |
+| `loadStyles`| boolean | Yes      | Auto-load DS-UI CSS                           |
 
-If `loadFonts` or `loadStyles` are `false`, you must manually include `<link>` tags in your HTML.
+If `loadFonts` or `loadStyles` are `false`, you must manually include the corresponding `<link>` tags.
 
 ### Option A — Manual CSS and font links
 
-```tsx
-import { ThemeProvider } from '@cupra/ui-react/ThemeProvider';
-import { Button } from '@cupra/ui-react/Button';
-import { Icon } from '@cupra/ui-react/Icon';
+```
+    import { ThemeProvider } from "@cupra/ui-react/ThemeProvider";
+    import { Button } from "@cupra/ui-react/Button";
+    import { Icon } from "@cupra/ui-react/Icon";
 
-export function App() {
-    return (
+    export function App() {
+      return (
         <>
-            <link rel="preload" as="style" href="https://ds-assets.cupra.com/[version]/styles/cupra/theme.css" />
-            <link rel="stylesheet" href="https://ds-assets.cupra.com/[version]/styles/cupra/theme.css" />
-            <ThemeProvider theme="cupra-diagonal" loadFonts={false} loadStyles={false}>
-                <Button variant="destructive" icon-name="filters-background">Click me</Button>
-                <Icon icon-name="filters-background" />
-            </ThemeProvider>
+          <link rel="preload" as="style" href="https://ds-assets.cupra.com/[version]/styles/cupra/theme.css" />
+          <link rel="stylesheet" href="https://ds-assets.cupra.com/[version]/styles/cupra/theme.css" />
+          <ThemeProvider theme="cupra-diagonal" loadFonts={false} loadStyles={false}>
+            <Button variant="destructive" icon-name="filters-background">
+              Click me
+            </Button>
+            <Icon icon-name="filters-background" />
+          </ThemeProvider>
         </>
-    );
-}
+      );
+    }
 ```
 
 ### Option B — Provider loads assets automatically
 
-```tsx
-import { ThemeProvider } from '@cupra/ui-react/ThemeProvider';
-import { Button } from '@cupra/ui-react/Button';
+```
+    import { ThemeProvider } from "@cupra/ui-react/ThemeProvider";
+    import { Button } from "@cupra/ui-react/Button";
 
-export function App() {
-    return (
+    export function App() {
+      return (
         <ThemeProvider theme="cupra-diagonal" loadFonts={true} loadStyles={true}>
-            <Button variant="primary">Button</Button>
+          <Button variant="primary">Button</Button>
         </ThemeProvider>
-    );
-}
+      );
+    }
 ```
 
 ---
 
 ## License
-License: SEAT S.A. Library EULA 1.0  
+
+SEAT S.A. Library EULA 1.0  
 See `LICENSE.md` in this package for the full text.  
 Third-party attributions may appear in `THIRD_PARTY_LICENSES.md`.
 
+---
+
 ## Support
+
 For help and support, contact: **ds.support@seat.es**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cupra/ui-react",
-  "version": "2.0.0-canary.6",
+  "version": "2.0.0-canary.7",
   "description": "React components library",
   "author": "SEAT S.A.",
   "license": "SEAT S.A. Library EULA 1.0",