@cupra/ui-react 2.0.0-canary.264 → 2.0.0-canary.265

package/README.md

@@ -0,0 +1,496 @@
+# UI React (React Components)
+
+## Contents
+
+- [Overview](#overview)
+- [Audience](#audience)
+- [Requirements & Compatibility](#requirements--compatibility)
+- [TypeScript and module resolution](#typescript-and-module-resolution)
+- [Getting started](#getting-started)
+- [Documentation & Live Playground](#documentation--live-playground)
+- [Breaking Changes & Deprecations](#breaking-changes--deprecations)
+- [Versioning and Release Channels](#versioning-and-release-channels)
+- [Recommended usage](#recommended-usage)
+- [Usage](#usage)
+    - [Theme provider props](#theme-provider-props)
+    - [Option A — Manual CSS and font links (recommended for performance)](#option-a--manual-css-and-font-links-recommended-for-performance)
+    - [Option B — Provider loads assets automatically](#option-b--provider-loads-assets-automatically)
+    - [Boolean props](#boolean-props)
+- [Fonts](#fonts)
+- [Icons](#icons)
+- [RTL and internationalization](#rtl-and-internationalization)
+- [License](#license)
+- [Support](#support)
+
+## 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
+- Automatic integration with the underlying Web Components
+- Full theming support with minimal configuration
+- A smooth adoption path inside existing React codebases
+
+If you need a **framework-agnostic** solution, consider `@cupra/ui-kit` (Web Components).
+
+## Requirements & Compatibility
+
+This library provides **official support for React 18 and React 19**.
+
+- **Supported React versions:** `>=18.3.1 <20`
+
+Projects using other React versions may still install and use the library, but behaviour is not guaranteed.
+
+<details>
+<summary>Supported browsers and technical guarantees</summary>
+
+This package wraps `@cupra/ui-kit` Web Components, so the same browser/OS support matrix applies:
+
+| Platform          | Minimum supported version                            |
+| ----------------- | ---------------------------------------------------- |
+| iOS / iPadOS      | 17+                                                  |
+| Android           | 13+                                                  |
+| Chrome (desktop)  | Current stable version − 1                           |
+| Edge (desktop)    | Current stable version − 1                           |
+| Firefox (desktop) | Current stable version − 1                           |
+| Safari (desktop)  | Latest version available on supported macOS releases |
+
+Any browser/OS version representing more than 1% of total website traffic remains supported even
+if it falls below these versions, until its traffic share drops back under that threshold.
+
+The published JavaScript is transpiled to a conservative ES2020 target, but no polyfills are
+shipped for runtime APIs below the versions above, and native support for Custom Elements,
+Shadow DOM and `<slot>` is required.
+
+Full rationale, transpilation details and maintenance guide:
+[BROWSER_SUPPORT.md](../../BROWSER_SUPPORT.md) (repository only — not included in the npm package).
+
+</details>
+
+## TypeScript and module resolution
+
+This library is **bundler-first**.
+
+<details open>
+<summary>Subpath imports (recommended)</summary>
+
+Importing components via subpaths (for example `@cupra/ui-react/Accordion`) requires
+TypeScript to use **bundler-based module resolution**:
+
+- **TypeScript ≥ 5**
+- `"moduleResolution": "bundler"`
+
+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:
+
+```
+    {
+      "compilerOptions": {
+        "moduleResolution": "bundler"
+      }
+    }
+```
+
+Other compiler options (`target`, `module`, `lib`, etc.) are project-specific and can be configured as needed.
+
+</details>
+
+<details>
+<summary>Root imports (compatibility mode)</summary>
+
+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:
+
+- 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**.
+
+</details>
+
+<details>
+<summary>Notes</summary>
+
+- 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.
+
+</details>
+
+## Getting started
+
+### Installation
+
+`@cupra/ui-react` is a React wrapper around the Web Components provided by
+`@cupra/ui-kit`.
+
+For this reason, **both packages must be installed** in your project.
+
+Using npm:
+
+```
+    npm install @cupra/ui-react @cupra/ui-kit
+```
+
+Using pnpm:
+
+```
+    pnpm add @cupra/ui-react @cupra/ui-kit
+```
+
+Using yarn:
+
+```
+    yarn add @cupra/ui-react @cupra/ui-kit
+```
+
+<details>
+<summary>About peer dependencies</summary>
+
+`@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.
+
+</details>
+
+## Documentation & Live 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
+
+## Breaking Changes & Deprecations
+
+Track every breaking change and deprecation, and use the migration helper to safely upgrade between versions:
+
+- Breaking changes (merged + upcoming): [https://seatcode.github.io/ds-ui/](https://seatcode.github.io/ds-ui/)
+- Deprecations (forward-looking advisories): [https://seatcode.github.io/ds-ui/deprecations.html](https://seatcode.github.io/ds-ui/deprecations.html)
+
+## Versioning and Release Channels
+
+This package is distributed through npm using **two release channels**.
+
+<details>
+<summary>Stable releases (latest)</summary>
+
+Production-ready versions:
+
+- Follow Semantic Versioning
+- Include only validated changes
+- Recommended for all production apps
+
+Install:
+
+```
+    npm install @cupra/ui-react
+```
+
+Specific version:
+
+```
+    npm install @cupra/ui-react@0.1.3
+```
+
+</details>
+
+<details>
+<summary>Canary releases (canary)</summary>
+
+Early-access versions published after each merge into `main`.
+
+Use canary releases if you:
+
+- Want to preview upcoming changes
+- Are validating new features
+- Accept small instability or rapid iteration
+
+Latest canary:
+
+```
+    npm install @cupra/ui-react@canary
+```
+
+Specific canary version:
+
+```
+    npm install @cupra/ui-react@0.1.4-canary.2
+```
+
+</details>
+
+## Recommended usage
+
+- **Production:** use **stable versions** (for example `@cupra/ui-react@1.1.3`)
+- **Internal testing / preview:** use **canary** versions
+
+## Usage
+
+When possible, import components via subpaths:
+
+```
+    import { Button } from "@cupra/ui-react/Button";
+```
+
+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`.
+
+### Theme provider props
+
+`ThemeProvider` has one required prop, `theme`, and three optional boolean props that turn off what the
+provider loads on its own. Booleans are `false` unless set, so `skip-fonts` and `skip-fonts={true}` are
+equivalent.
+
+| Prop                 | Type                         | Default         | Description                                                                                                                         |
+| -------------------- | ---------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `theme`              | `'cupra-diagonal' \| 'seat'` | none (required) | Visual theme applied to every descendant component.                                                                                 |
+| `skip-fonts`         | boolean                      | `false`         | Do not add `fonts.css`, the stylesheet that declares the theme's `@font-face` rules, nor the preloads of the critical font weights. |
+| `skip-styles`        | boolean                      | `false`         | Do not add `theme.css`, the stylesheet the `ui-kit` components require.                                                             |
+| `skip-unused-styles` | boolean                      | `false`         | Do not add `unused-styles.css`, the theme's `--ds-` tokens that `ui-kit` doesn't consume internally.                                |
+
+`ThemeProvider` forwards its props directly to the underlying `<ds-theme-provider>` Web Component, so
+prop names match its HTML attributes (kebab-case), not idiomatic React camelCase.
+
+If you set a `skip-*` prop, you must include the corresponding `<link>` tags yourself, as in Option A.
+The provider renders its children once `theme.css` has loaded.
+
+Each theme publishes three stylesheets:
+
+- `theme.css` holds everything the `ui-kit` Web Components actually consume. It is always required.
+- `unused-styles.css` holds the rest of the theme's `--ds-` tokens, which no `ui-kit` component consumes
+  internally. It only matters if your own CSS reads those raw tokens directly, so it can be omitted or
+  deferred otherwise.
+- `fonts.css` holds the theme's `@font-face` rules. See [Fonts](#fonts).
+
+### Option A — Manual CSS and font links (recommended for performance)
+
+By default the provider injects the stylesheets at runtime, after JavaScript runs. Serving them yourself
+from the `<head>` avoids that extra round trip, lets the browser discover them earlier and is better for
+performance. Set the three `skip` props and add the files manually, controlling their priority:
+
+- `theme.css` as a normal, high-priority stylesheet link (always required).
+- `unused-styles.css` with lower priority, for example with `rel="preload"` and `as="style"`, turned into a
+  stylesheet once loaded via `onLoad`, or omitted entirely if you don't read raw tokens. If your own CSS
+  does read raw tokens, load it with the same priority as `theme.css`.
+- `fonts.css` as a stylesheet link, plus a preload for each critical font file.
+
+This is also the setup for server-side rendering, since no JavaScript is needed to load the assets.
+Replace `[theme]` with `cupra-diagonal` or `seat` and `[version]` with the installed package version.
+
+```
+    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 (
+        <>
+          {/* One preload per critical font weight, see Fonts below */}
+          <link rel="preload" as="font" type="font/woff2" href="https://ds-assets.cupra.com/fonts/[theme]/[font-file].woff2" crossOrigin="anonymous" />
+          <link rel="stylesheet" href="https://ds-assets.cupra.com/[version]/styles/[theme]/fonts.css" />
+          <link rel="stylesheet" href="https://ds-assets.cupra.com/[version]/styles/[theme]/theme.css" />
+          {/* Lower priority; only needed if your own CSS reads raw --ds- tokens directly */}
+          <link
+            rel="preload"
+            as="style"
+            href="https://ds-assets.cupra.com/[version]/styles/[theme]/unused-styles.css"
+            onLoad={(e) => { e.currentTarget.rel = "stylesheet"; }}
+          />
+          <ThemeProvider theme="[theme]" skip-fonts skip-styles skip-unused-styles>
+            <Button variant="destructive" icon-name="filters-background">
+              Click me
+            </Button>
+            <Icon icon-name="filters-background" />
+          </ThemeProvider>
+        </>
+      );
+    }
+```
+
+<details>
+<summary>Keeping files in sync and self-hosting</summary>
+
+Keep the three files in sync with the installed package version. To self-host, download the files and
+serve them from your own domain (and the font files they reference):
+
+```bash
+curl -O https://ds-assets.cupra.com/[version]/styles/[theme]/theme.css
+curl -O https://ds-assets.cupra.com/[version]/styles/[theme]/unused-styles.css
+curl -O https://ds-assets.cupra.com/[version]/styles/[theme]/fonts.css
+```
+
+</details>
+
+### Option B — Provider loads assets automatically
+
+```
+    import { ThemeProvider } from "@cupra/ui-react/ThemeProvider";
+    import { Button } from "@cupra/ui-react/Button";
+
+    export function App() {
+      return (
+        <ThemeProvider theme="cupra-diagonal">
+          <Button variant="primary">Button</Button>
+        </ThemeProvider>
+      );
+    }
+```
+
+The provider loads `fonts.css`, `theme.css` and `unused-styles.css` from the CDN for the installed
+`@cupra/ui-kit` version.
+
+### Boolean props
+
+Boolean props of the wrappers are `false` unless set, on React 18 and on React 19. To turn a behavior
+off, use the matching negative prop (`skip-fonts`, `hide-divider`, `hide-close`...) instead of passing
+`false` to a prop that defaults to `true`. If you are upgrading from an earlier version, see the
+`@cupra/ui-react` changelog for the list of renamed props.
+
+## Fonts
+
+Each theme publishes `fonts.css` next to `theme.css`. It only declares the theme's `@font-face` rules
+(woff2, `font-display: fallback`), so the browser downloads just the weights a page renders and only
+swaps the typeface within the first ~3 seconds: later, text doesn't shift. `ThemeProvider` adds it unless
+`skip-fonts` is set; with `skip-fonts`, link it yourself as in Option A. That is also the setup for
+server-side rendering, since no JavaScript is needed to load the fonts.
+
+<details>
+<summary>Preloading the critical font weights</summary>
+
+**Preload the critical weights.** With `fallback` the browser waits about 100 ms for a font, then shows the
+fallback typeface and swaps to the real one if it arrives within ~3 seconds. After that it keeps the
+fallback for that page view and uses the real one on the next, cached, navigation. Unless `skip-fonts` is
+set, `ThemeProvider` preloads the Regular and Medium weights of the theme next to `fonts.css`, while its
+content waits for `theme.css`. With `skip-fonts` or server-side rendering, add the preloads to your
+`<head>` yourself. Adding them there also helps with `ThemeProvider`: the download starts before the
+JavaScript loads, and the provider skips any preload already present. In Next.js, render the `<link>` in
+the root layout; React 19 hoists it to the `<head>`.
+
+```tsx
+<link
+    rel="preload"
+    as="font"
+    type="font/woff2"
+    href="https://ds-assets.cupra.com/fonts/[theme]/[font-file].woff2"
+    crossOrigin="anonymous"
+/>
+```
+
+- Preload only the weights rendered above the fold, usually Regular and Medium. Every preload competes
+  with other critical requests.
+- Keep `crossOrigin`, even on the same origin. Fonts are fetched in CORS mode, and a preload without it
+  is not reused: the font downloads twice.
+- The `href` must match the URL in `fonts.css` exactly.
+
+</details>
+
+<details>
+<summary>Font files per theme</summary>
+
+| Theme            | `font-family`  | Font files (`[font-file]`)                                                                                         |
+| ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `seat`           | `seat`         | `SeatBcn-Book` (350), `SeatBcn-Regular` (400), `SeatBcn-Medium` (500), `SeatBcn-Bold` (700), `SeatBcn-Black` (900) |
+| `cupra-diagonal` | `cupra-screen` | `CupraScreen-Light` (300), `CupraScreen-Book` (350), `CupraScreen-Regular` (400), `CupraScreen-Medium` (500)       |
+
+</details>
+
+## Icons
+
+Icons must always be consumed through the `<Icon>` React component — never by loading SVG files directly from the CDN.
+
+SVG icon files are stored per-theme under the CDN and are optimised to work with the `Icon` component (they rely on CSS custom properties injected by the component to resolve color and size). Loading them directly as `<img>` tags or via `fetch` bypasses this mechanism and will produce unstyled, incorrectly-colored, or incorrectly-sized output.
+
+```tsx
+// Correct: use Icon
+import { Icon } from '@cupra/ui-react/Icon';
+
+<Icon icon-name="arrow-right" />
+
+// Wrong: do not load icon SVGs from the CDN directly
+<img src="https://ds-assets.cupra.com/[version]/assets/icons/[theme]/arrow-right.svg" />
+```
+
+## RTL and internationalization
+
+Set `dir` and `lang` on `<html>`; the components follow them. The `cupra` and `seat-legacy` themes have no RTL support. See the `@cupra/ui-kit` README for the full list of what is automatic and what you configure.
+
+A form with an email field that stays left to right inside an RTL page:
+
+```tsx
+import { SearchInput } from '@cupra/ui-react/SearchInput';
+import { TextInput } from '@cupra/ui-react/TextInput';
+
+export function ContactForm() {
+    return (
+        <form dir="rtl" lang="ar">
+            <TextInput>
+                <input dir="auto" name="name" placeholder="الاسم" />
+            </TextInput>
+
+            <TextInput>
+                <input dir="ltr" type="email" name="email" placeholder="name@example.com" />
+            </TextInput>
+
+            <SearchInput>
+                <input dir="auto" type="text" name="search" placeholder="بحث" />
+            </SearchInput>
+        </form>
+    );
+}
+```
+
+<details>
+<summary>Translating the accessibility texts</summary>
+
+The built-in `aria-label` texts have optional `data-aria-label` props. They are plain strings, so they work in React 18 as they are:
+
+```tsx
+import { Calendar } from '@cupra/ui-react/Calendar';
+
+<Calendar
+    locale="ar"
+    data-aria-label="التقويم"
+    data-aria-label-previous-month="الشهر السابق"
+    data-aria-label-next-month="الشهر التالي"
+/>;
+```
+
+</details>
+
+## License
+
+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.264",
+  "version": "2.0.0-canary.265",
   "description": "React components library",
   "author": "SEAT S.A.",
   "license": "SEAT S.A. Library EULA 1.0",
@@ -50,7 +50,7 @@
     }
   ],
   "peerDependencies": {
-    "@cupra/ui-kit": "2.0.0-canary.248",
+    "@cupra/ui-kit": "2.0.0-canary.249",
     "react": ">= 18.3.1 < 20",
     "react-dom": ">= 18.3.1 < 20",
     "typescript": ">=5.0.0"
@@ -75,7 +75,7 @@
     "storybook": "^10.6.2",
     "typescript": "^5.9.3",
     "vite": "^8.3.3",
-    "@cupra/ui-kit": "2.0.0-canary.248"
+    "@cupra/ui-kit": "2.0.0-canary.249"
   },
   "scripts": {
     "build": "rm -rf dist && pnpm --filter @cupra/ui-kit build:react && tsc --declaration --emitDeclarationOnly && BUILD_FORMAT=esm vite build --emptyOutDir false && BUILD_FORMAT=cjs vite build --emptyOutDir false",