@telefonica/mistica 16.56.0 → 16.57.0-beta.1

package/doc/design-tokens.md

@@ -0,0 +1,199 @@
+# Design Tokens
+
+Mistica uses design tokens via CSS custom properties. All tokens are accessed through the `skinVars` object
+exported from `@telefonica/mistica`. Tokens adapt automatically to the active skin and color scheme
+(light/dark mode).
+
+## Critical rules
+
+- **NEVER hardcode colors.** Always use `skinVars.colors.*` for all color values.
+- Use `skinVars.rawColors.*` (not `skinVars.colors.*`) when applying alpha with `applyAlpha`.
+- Use `skinVars.borderRadii.*` for border radius values.
+- Tokens are CSS custom properties at runtime (e.g. `var(--colorBrand)`), so they work in both inline styles
+  and CSS.
+
+## Color tokens
+
+All colors are accessed via `skinVars.colors.*`. Each token resolves to a CSS custom property.
+
+### Semantic colors
+
+| Token                   | Usage                                                    |
+| ----------------------- | -------------------------------------------------------- |
+| `brand`                 | Primary brand color                                      |
+| `brandHigh`             | High-emphasis brand color                                |
+| `inverse`               | Inverse foreground color                                 |
+| `neutralHigh`           | High-emphasis neutral (e.g. primary text on default)     |
+| `neutralMedium`         | Medium-emphasis neutral (e.g. secondary text on default) |
+| `neutralLow`            | Low-emphasis neutral                                     |
+| `neutralLowAlternative` | Alternative low-emphasis neutral                         |
+| `success`               | Success semantic color                                   |
+| `warning`               | Warning semantic color                                   |
+| `error`                 | Error semantic color                                     |
+| `promo`                 | Promotional color                                        |
+| `highlight`             | Highlight color                                          |
+
+### Background colors
+
+| Token                            | Usage                               |
+| -------------------------------- | ----------------------------------- |
+| `background`                     | Default page background             |
+| `backgroundAlternative`          | Alternative section background      |
+| `backgroundBrand`                | Brand-colored background            |
+| `backgroundBrandSecondary`       | Secondary brand background          |
+| `backgroundContainer`            | Container/card background           |
+| `backgroundContainerBrand`       | Container on brand background       |
+| `backgroundContainerAlternative` | Container on alternative background |
+| `backgroundOverlay`              | Modal/sheet overlay                 |
+| `backgroundSkeleton`             | Skeleton loading placeholder        |
+| `appBarBackground`               | App bar background                  |
+| `navigationBarBackground`        | Navigation bar background           |
+
+### Text colors
+
+| Token                  | Usage                                      |
+| ---------------------- | ------------------------------------------ |
+| `textPrimary`          | Primary text on default background         |
+| `textPrimaryInverse`   | Primary text on brand/inverse background   |
+| `textPrimaryBrand`     | Primary text on brand background           |
+| `textPrimaryMedia`     | Primary text on media background           |
+| `textSecondary`        | Secondary text on default background       |
+| `textSecondaryInverse` | Secondary text on brand/inverse background |
+| `textSecondaryBrand`   | Secondary text on brand background         |
+| `textError`            | Error text                                 |
+| `textLink`             | Link text color                            |
+| `textLinkInverse`      | Link text on brand/inverse background      |
+| `textLinkDanger`       | Danger link text color                     |
+
+### Border colors
+
+| Token            | Usage                  |
+| ---------------- | ---------------------- |
+| `borderLow`      | Low-emphasis border    |
+| `border`         | Default border         |
+| `borderHigh`     | High-emphasis border   |
+| `borderSelected` | Selected/active border |
+
+### Status colors (low/high emphasis)
+
+| Low emphasis | High emphasis | Usage          |
+| ------------ | ------------- | -------------- |
+| `successLow` | `successHigh` | Success status |
+| `warningLow` | `warningHigh` | Warning status |
+| `errorLow`   | `errorHigh`   | Error status   |
+| `promoLow`   | `promoHigh`   | Promo status   |
+| `brandLow`   | `brandHigh`   | Brand status   |
+
+### Control colors
+
+| Token              | Usage                                     |
+| ------------------ | ----------------------------------------- |
+| `control`          | Default control (checkbox, radio, switch) |
+| `controlActivated` | Activated control                         |
+| `controlError`     | Error state control                       |
+| `loadingBar`       | Loading bar color                         |
+| `divider`          | Divider line color                        |
+
+### Tag colors
+
+Tags have paired `tagText*` and `tagBackground*` tokens for each type: `Promo`, `Active`, `Inactive`, `Info`,
+`Success`, `Warning`, `Error`. Each also has `Inverse`, `Negative`, and `Brand` variants.
+
+Example: `skinVars.colors.tagTextPromo`, `skinVars.colors.tagBackgroundPromo`.
+
+## Using colors in code
+
+```tsx
+import {skinVars, Text2, Box} from '@telefonica/mistica';
+
+// In inline styles
+<div style={{color: skinVars.colors.textPrimary, backgroundColor: skinVars.colors.backgroundContainer}}>
+  Content
+</div>
+
+// In component color props
+<Text2 regular color={skinVars.colors.textSecondary}>Secondary text</Text2>
+
+// Prefer Mistica components over raw divs:
+<Box padding={16}>
+  <Text2 regular color={skinVars.colors.textSecondary}>Secondary text</Text2>
+</Box>
+```
+
+## Applying alpha to colors
+
+Use `applyAlpha` with `skinVars.rawColors` (not `skinVars.colors`):
+
+```tsx
+import {applyAlpha, skinVars} from '@telefonica/mistica';
+
+// Correct: use rawColors for alpha
+const semiTransparentBrand = applyAlpha(skinVars.rawColors.brand, 0.5);
+
+// Wrong: skinVars.colors contains CSS var() references, not raw RGB values
+// applyAlpha(skinVars.colors.brand, 0.5) // Don't do this
+```
+
+## Border radius tokens
+
+Access via `skinVars.borderRadii.*`:
+
+| Token        | Usage                   |
+| ------------ | ----------------------- |
+| `container`  | Cards, boxed containers |
+| `button`     | Buttons                 |
+| `input`      | Form inputs             |
+| `popup`      | Popups, tooltips        |
+| `checkbox`   | Checkboxes              |
+| `indicator`  | Indicators              |
+| `chip`       | Chips                   |
+| `sheet`      | Bottom sheets           |
+| `bar`        | Progress bars           |
+| `avatar`     | Avatars                 |
+| `mediaSmall` | Small media elements    |
+| `tag`        | Tags                    |
+
+```tsx
+// Use in styles when building custom elements (prefer Mistica components instead)
+<div style={{borderRadius: skinVars.borderRadii.container}}>...</div>
+```
+
+## Text presets
+
+Text sizing is handled by text components (`Text1`-`Text10`, `Title1`-`Title4`). Do not manually set font
+sizes -- use the appropriate text component instead.
+
+| Component        | Weight options                       | Usage                              |
+| ---------------- | ------------------------------------ | ---------------------------------- |
+| `Text1`-`Text4`  | `light`, `regular`, `medium`, `bold` | Body text with configurable weight |
+| `Text5`-`Text10` | Fixed per skin                       | Display/headline text              |
+| `Title1`         | Default weight from skin             | Section title                      |
+| `Title2`         | Default weight from skin             | Subsection title                   |
+| `Title3`         | Default weight from skin             | Card/small title                   |
+| `Title4`         | Default weight from skin             | Smallest title                     |
+
+## ThemeVariant (variant contexts)
+
+Some sections of a page use different color contexts. Use `variant` prop on `ResponsiveLayout` or `Boxed`:
+
+```tsx
+// Brand section (colored background)
+<ResponsiveLayout variant="brand">
+  <Box paddingY={24}>
+    <Text2 regular>Text automatically adapts colors</Text2>
+    <ButtonPrimary onPress={() => {}}>Action</ButtonPrimary>
+  </Box>
+</ResponsiveLayout>
+
+// Alternative section
+<ResponsiveLayout variant="alternative">
+  <Box paddingY={24}>
+    <Text2 regular>Alternative background section</Text2>
+  </Box>
+</ResponsiveLayout>
+```
+
+Available variants: `'default'`, `'brand'`, `'negative'`, `'alternative'`, `'media'`.
+
+Components inside a variant section automatically adapt their colors. You do not need to manually set inverse
+colors.

package/doc/fonts.md

@@ -0,0 +1,287 @@
+# Fonts
+
+Mistica does **not** inject a font family automatically. Without explicit setup, browsers fall back to their
+default serif font (Times New Roman on desktop). You must declare `@font-face` rules and set `font-family` on
+`body`.
+
+## Font per skin
+
+Each skin has a designated font family. Use the correct one for the skin your app is using:
+
+| Skin                         | Getter function        | Font family         |
+| ---------------------------- | ---------------------- | ------------------- |
+| `movistar-new` _(preferred)_ | `getMovistarNewSkin()` | `'Movistar Sans'`   |
+| `movistar` _(legacy)_        | `getMovistarSkin()`    | `'On Air'`          |
+| `o2-new` _(preferred)_       | `getO2NewSkin()`       | `'On Air'`          |
+| `o2` _(legacy)_              | `getO2Skin()`          | `'On Air'`          |
+| `vivo-new` _(preferred)_     | `getVivoNewSkin()`     | `'Vivo Type'`       |
+| `vivo` _(legacy)_            | `getVivoSkin()`        | `'Roboto'`          |
+| `telefonica`                 | `getTelefonicaSkin()`  | `'Telefonica Sans'` |
+| `blau`                       | `getBlauSkin()`        | `'Roboto'`          |
+| `tu`                         | `getTuSkin()`          | `'Telefonica Sans'` |
+| `esimflag`                   | `getEsimflagSkin()`    | `'On Air'`          |
+
+## Setting font-family
+
+Set the font from inside a component rendered under `ThemeContextProvider`. This keeps font and background
+color in sync with the active theme, including in dark mode:
+
+```tsx
+import {skinVars} from '@telefonica/mistica';
+
+const GlobalStyles = () => (
+  <style>{`
+    body {
+      font-family: 'Movistar Sans', 'Helvetica', 'Arial', sans-serif;
+      background-color: ${skinVars.colors.background};
+    }
+  `}</style>
+);
+```
+
+Render `<GlobalStyles />` as a direct child of `ThemeContextProvider`, before the rest of the app.
+
+## @font-face setup
+
+Declare the font weights your app needs. Mistica uses **300 (light), 400 (regular), 500 (medium) and 700
+(bold)**. Serve the `.woff2` files from your own static hosting.
+
+### On Air (Movistar, O2, O2 New, Esimflag)
+
+```css
+@font-face {
+  font-family: 'On Air';
+  font-style: normal;
+  font-weight: 300;
+  src: url('/fonts/OnAir-Light.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'On Air';
+  font-style: normal;
+  font-weight: 400;
+  src: url('/fonts/OnAir-Regular.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'On Air';
+  font-style: normal;
+  font-weight: 500;
+  src: url('/fonts/OnAir-Medium.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'On Air';
+  font-style: normal;
+  font-weight: 700;
+  src: url('/fonts/OnAir-Bold.woff2') format('woff2');
+}
+
+body {
+  font-family: 'On Air', 'Helvetica', 'Arial', sans-serif;
+}
+```
+
+### Movistar Sans (Movistar New)
+
+```css
+@font-face {
+  font-family: 'Movistar Sans';
+  font-style: normal;
+  font-weight: 300;
+  src: url('/fonts/MovistarSans-Light.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Movistar Sans';
+  font-style: normal;
+  font-weight: 400;
+  src: url('/fonts/MovistarSans-Regular.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Movistar Sans';
+  font-style: normal;
+  font-weight: 500;
+  src: url('/fonts/MovistarSans-Medium.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Movistar Sans';
+  font-style: normal;
+  font-weight: 700;
+  src: url('/fonts/MovistarSans-Bold.woff2') format('woff2');
+}
+
+body {
+  font-family: 'Movistar Sans', 'Helvetica', 'Arial', sans-serif;
+}
+```
+
+### Vivo Type (Vivo New)
+
+```css
+@font-face {
+  font-family: 'Vivo Type';
+  font-style: normal;
+  font-weight: 300;
+  src: url('/fonts/vivo-type-light.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Vivo Type';
+  font-style: normal;
+  font-weight: 400;
+  src: url('/fonts/vivo-type-regular.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Vivo Type';
+  font-style: normal;
+  font-weight: 500;
+  src: url('/fonts/vivo-type-medium.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Vivo Type';
+  font-style: normal;
+  font-weight: 700;
+  src: url('/fonts/vivo-type-bold.woff2') format('woff2');
+}
+
+body {
+  font-family: 'Vivo Type', 'Helvetica', 'Arial', sans-serif;
+}
+```
+
+### Telefonica Sans (Telefonica, Tu)
+
+```css
+@font-face {
+  font-family: 'Telefonica Sans';
+  font-style: normal;
+  font-weight: 300;
+  src: url('/fonts/Telefonica_Sans_Light.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Telefonica Sans';
+  font-style: normal;
+  font-weight: 400;
+  src: url('/fonts/Telefonica_Sans_Regular.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Telefonica Sans';
+  font-style: normal;
+  font-weight: 500;
+  src: url('/fonts/Telefonica_Sans_Medium.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Telefonica Sans';
+  font-style: normal;
+  font-weight: 700;
+  src: url('/fonts/Telefonica_Sans_Bold.woff2') format('woff2');
+}
+
+body {
+  font-family: 'Telefonica Sans', 'Helvetica', 'Arial', sans-serif;
+}
+```
+
+### Roboto (Vivo, Blau)
+
+Roboto is available via [Google Fonts](https://fonts.google.com/specimen/Roboto) or
+[Bunny Fonts](https://fonts.bunny.net/family/roboto) (GDPR-friendly alternative). The weights needed are 300,
+400, 500, and 700.
+
+Google Fonts import:
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link
+  href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap"
+  rel="stylesheet"
+/>
+```
+
+Or self-hosted `@font-face`:
+
+```css
+@font-face {
+  font-family: 'Roboto';
+  font-style: normal;
+  font-weight: 300;
+  src:
+    local('Roboto Light'),
+    local('Roboto-Light'),
+    url('/fonts/roboto-300.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Roboto';
+  font-style: normal;
+  font-weight: 400;
+  src:
+    local('Roboto'),
+    local('Roboto-Regular'),
+    url('/fonts/roboto-400.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Roboto';
+  font-style: normal;
+  font-weight: 500;
+  src:
+    local('Roboto Medium'),
+    local('Roboto-Medium'),
+    url('/fonts/roboto-500.woff2') format('woff2');
+}
+@font-face {
+  font-family: 'Roboto';
+  font-style: normal;
+  font-weight: 700;
+  src:
+    local('Roboto Bold'),
+    local('Roboto-Bold'),
+    url('/fonts/roboto-700.woff2') format('woff2');
+}
+
+body {
+  font-family: -apple-system, 'Roboto', 'Helvetica', 'Arial', sans-serif;
+}
+```
+
+## Body background color
+
+Always set `body` background from inside a component under `ThemeContextProvider` using the
+`skinVars.colors.background` token. This ensures the background matches the active theme in both light and
+dark mode:
+
+```tsx
+const GlobalStyles = () => <style>{`body { background-color: ${skinVars.colors.background}; }`}</style>;
+```
+
+## Override browser fonts for form elements
+
+Some browsers apply a different `font-family` to form inputs, textareas, and code elements. Override with:
+
+```css
+input,
+textarea,
+pre,
+code {
+  font: inherit;
+}
+```
+
+Or use a CSS reset that handles this, such as
+[modern-normalize](https://github.com/sindresorhus/modern-normalize).
+
+## Dynamic font sizes
+
+To support OS/browser accessibility font size settings, set the base size on `html`:
+
+```css
+html {
+  font-size: 16px; /* or 100% */
+}
+```
+
+To support Dynamic Type on iOS:
+
+```css
+@supports (font: -apple-system-body) {
+  html {
+    font: -apple-system-body !important;
+  }
+}
+```

package/doc/forms.md

@@ -0,0 +1,177 @@
+# Forms
+
+<!-- TOC depthFrom:2 -->
+
+- [Form example](#form-example)
+  - [Important notes](#important-notes)
+- [Form fields](#form-fields)
+  - [CreditCardFields](#creditcardfields)
+  - [CreditCardNumberField](#creditcardnumberfield)
+  - [CreditCardExpirationField](#creditcardexpirationfield)
+  - [CvvField](#cvvfield)
+  - [DateField](#datefield)
+  - [DecimalField](#decimalfield)
+  - [IntegerField](#integerfield)
+  - [PasswordField](#passwordfield)
+  - [EmailField](#emailfield)
+  - [Select](#select)
+  - [PhoneNumberField](#phonenumberfield)
+  - [IbanField](#ibanfield)
+- [DoubleField](#doublefield)
+- [useForm Hook](#useform-hook)
+
+<!-- /TOC -->
+
+You can build complex forms with automatic state handling using the components provided by this library
+
+## Form example
+
+Let's see a quick example to see how it works
+
+```js
+import {Form, TextField, ButtonPrimary} from '@telefonica/mistica';
+
+const validateName = (name) => (/^\w+$/.test(name) ? '' : 'bad username');
+
+const LoginForm = () => {
+  // {user, pass} contains field values for inputs named "user" and "pass"
+  const handleSubmit = ({user, pass}) =>
+    api.login({user, pass}).then(() => {
+      document.location.href = '/home';
+    });
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      <TextField name="user" label="Username" validate={validateName} />
+      <TextField name="pass" label="Password" type="password" />
+      <ButtonPrimary submit>Log in</ButtonPrimary>
+    </Form>
+  );
+};
+```
+
+### Important notes
+
+- Submit button must include the `submit` prop
+- :warning: Submit handler automatically prevents default submit event (calls to `event.preventDefault()`).
+  So, for now, you can't use this component to send a `POST` request to `action` attribute URL.
+- Form fields are required by default. If a required field is empty it will be marked as error on submit or
+  blur. Add the `optional` prop to mark a field as optional.
+- `Form`'s `onSubmit` prop is a `function` that receives an `object` whose keys are the names of the form
+  fields and the values are the values of the form fields. This function must return a promise.
+- When the form is submitting (while the `onSubmit` promise is not resolved or rejected), all fields are
+  automatically disabled and a spinner is shown inside submit button.
+- Form fields accept a `validate` prop that can be used to validate field values before submitting. This
+  validation is executed on blur or submit. Validation function must return a string with the error message or
+  empty string if succeeded.
+- Form optionally accepts an object of `initialValues` e.g. `<Form initialValues={{email: prevEmail}}`
+- You can also use FormField components outside a `<Form>` component but you will lose the magic: automatic
+  form validation, disable fields when sending, show spinner on submit button, etc.
+
+## Form fields
+
+### CreditCardFields
+
+- Use it if you want to request credit card information
+- This component will render 3 fields:
+  - `CreditCardNumberField`
+  - `CreditCardExpirationField`
+  - `CvvField`
+- When used inside a `<Form>` component, these fields have built-in validations:
+  - Simple validation is performed in credit card number
+  - CVV length depends on card type
+  - Expiration date must be a future date
+
+### CreditCardNumberField
+
+- To request a Credit Card number
+- Use `acceptedCards` prop to set accepted cards. By default:
+  - `{americanExpress: true, visa: true, masterCard: true}`
+- An icon will hint the card type based on the card number
+
+### CreditCardExpirationField
+
+- To request a Credit Card expiration date
+- Format as you write (MM/YY)
+
+### CvvField
+
+- To request the Credit Card Verification value
+
+### DateField
+
+- To select dates
+- Uses device/browser native date picker
+
+### DecimalField
+
+- Shows a numeric keypad in mobile devices
+- Values restricted to decimal values
+- Decimal separator characted (comma or dot) depends on context locale
+
+### IntegerField
+
+- Shows a numeric keypad in mobile devices
+- Values restricted to integer values
+
+### PasswordField
+
+- Use this field to request a password
+- Includes an "eye" icon to show/hide password
+- Use the `autoComplete` prop to autocomplete to an existing password (`"current-password"`) or request a new
+  one (`"new-password"`)
+
+### EmailField
+
+- Use this field to request an email address
+- Has built-in email address validation (naive)
+- Uses an email keypad on mobile
+- Autocompletes to current email, to disable, set `autoComplete` to `"off"`
+
+### Select
+
+Use this component to create a `Select`
+
+```js
+const options = [
+  {value: 1, text: 'orange'},
+  {value: 2, text: 'apple'},
+];
+
+//...
+
+<Select options={options} />;
+```
+
+### PhoneNumberField
+
+To enter phone numbers
+
+- Uses Google's `libphonenumber` library to format numbers as you type (uses `locale` from theme context to
+  format numbers accordingly)
+
+### IbanField
+
+To enter bank accounts using the IBAN format
+
+- Formats the IBAN number as you type
+- Validates the number using the checksum
+
+## DoubleField
+
+Use this component to place two fields at the same row
+
+```js
+<DoubleField>
+  <TextField name="foo" label="Foo" />
+  <TextField name="bar" label="Bar" />
+</DoubleField>
+```
+
+## useForm Hook
+
+With `useForm` you can access the form context. See `form-context.tsx`.
+
+This allows you to implement advanced form logic. See form stories for examples.
+
+Please open an issue if your use case is not covered or you need additional examples.

package/doc/images/layout/box.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="152" viewBox="-1 -1 302 152">
+    <rect y="0" width="300" height="150" fill="pink" />
+    <rect y="32" x="16" width="calc(300 - 32)" height="calc(150 - 64)" fill="lightgray" stroke="black" />
+    <text x="130" y="20">32px</text>
+    <text x="0" y="80" >16px</text>
+</svg>

package/doc/images/layout/grid-layout-desktop-5-4.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="243" viewBox="-1 -1 362 242">
+  <rect x="0" y="0" height="240" width="360" fill="pink" stroke="black"/>
+  <rect x="48" y="0" height="240" width="calc(360 - 96)" fill="lightgray" stroke="black"/>
+  <rect x="69.5" y="0" height="60" width="105.5" stroke="black" fill="rgba(255,0,0,0.3)"/>
+  <rect x="205.5" y="0" height="60" width="82" stroke="black" fill="rgba(0,0,255,0.3)"/>
+  <text x="78" y="20">Left</text>
+  <text x="214" y="20">Right</text>
+</svg>

package/doc/images/layout/grid-layout-desktop-6-6.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="243" viewBox="-1 -1 362 242">
+  <rect x="0" y="0" height="240" width="360" fill="pink" stroke="black"/>
+  <rect x="48" y="0" height="240" width="calc(360 - 96)" fill="lightgray" stroke="black"/>
+  <rect x="48" y="0" height="60" width="128" stroke="black" fill="rgba(255,0,0,0.3)"/>
+  <rect x="184" y="0" height="60" width="128" stroke="black" fill="rgba(0,0,255,0.3)"/>
+  <text x="56" y="20">Left</text>
+  <text x="192" y="20">Right</text>
+</svg>