@telefonica/mistica 16.55.0 → 16.56.1-beta.1

package/doc/llms.md

@@ -0,0 +1,258 @@
+# @telefonica/mistica
+
+> React components library for Telefonica Design System (Mistica). Provides UI components, layout primitives,
+> form fields, theming, analytics, and more for building web applications following Telefonica's design
+> guidelines.
+
+## Documentation location
+
+This file is the main entry point. All docs live at:
+
+- **Installed package**: `node_modules/@telefonica/mistica/doc/`
+- **GitHub fallback** (use when node_modules is not available):
+  `https://github.com/Telefonica/mistica-web/tree/master/doc`
+
+If you cannot find a documentation file in `node_modules`, fetch the equivalent file from the GitHub
+repository at `https://github.com/Telefonica/mistica-web/blob/master/doc/<filename>`.
+
+## Critical Rules
+
+1. **NEVER hardcode colors.** Always use `skinVars.colors.*` design tokens from `@telefonica/mistica`.
+2. **Try not to use raw `<div>` for layout.** Use Mistica layout components: `Box`, `Stack`, `Inline`,
+   `Align`, `ResponsiveLayout`, `GridLayout`, `Grid`.
+3. **NEVER set font sizes manually.** Use text components: `Text1`-`Text10`, `Title1`-`Title4`.
+4. **NEVER set border radius manually.** Use `skinVars.borderRadii.*` or Mistica components that handle it
+   automatically.
+5. **Always wrap your app** with `<ThemeContextProvider>` and import `@telefonica/mistica/css/mistica.css`.
+6. **Always namespace React hooks**: `React.useState`, `React.useEffect`, `React.useRef`.
+7. **Add `'use client';`** directive to client components when using Next.js app router.
+8. Use `skinVars.rawColors.*` (not `skinVars.colors.*`) when applying alpha with `applyAlpha`.
+
+## Install
+
+```
+yarn add @telefonica/mistica
+```
+
+or
+
+```
+npm install @telefonica/mistica
+```
+
+## Quick Start
+
+```tsx
+'use client';
+
+import '@telefonica/mistica/css/mistica.css';
+import {
+  ThemeContextProvider,
+  getMovistarSkin,
+  ResponsiveLayout,
+  Box,
+  Stack,
+  Title1,
+  Text2,
+  ButtonPrimary,
+} from '@telefonica/mistica';
+
+const misticaTheme = {
+  skin: getMovistarSkin(),
+  i18n: {locale: 'es-ES', phoneNumberFormattingRegionCode: 'ES'},
+};
+
+const App = () => (
+  <ThemeContextProvider theme={misticaTheme}>
+    <ResponsiveLayout>
+      <Box paddingY={24}>
+        <Stack space={16}>
+          <Title1 as="h1">Hello Mistica</Title1>
+          <Text2 regular as="p">
+            Build beautiful UIs with design system components.
+          </Text2>
+          <ButtonPrimary onPress={() => console.log('clicked')}>Get Started</ButtonPrimary>
+        </Stack>
+      </Box>
+    </ResponsiveLayout>
+  </ThemeContextProvider>
+);
+```
+
+## Theme Configuration
+
+The `theme` prop in `ThemeContextProvider` is mandatory. Only `skin` and `i18n` are required:
+
+```ts
+type ThemeConfig = {
+  skin: Skin;
+  colorScheme?: 'light' | 'dark' | 'auto'; // default: 'auto'
+  i18n: {locale: Locale; phoneNumberFormattingRegionCode: RegionCode};
+  platformOverrides?: {platform?: 'ios' | 'android'; insideNovumNativeApp?: boolean; userAgent?: string};
+  texts?: Partial<Dictionary>;
+  analytics?: {
+    logEvent: (event: TrackingEvent) => Promise<void>;
+    eventFormat?: 'universal-analytics' | 'google-analytics-4';
+  };
+  Link?: LinkComponent;
+  useHrefDecorator?: () => (href: string) => string;
+  preventCopyInFormFields?: boolean;
+};
+```
+
+Available skins: `getMovistarSkin()`, `getVivoSkin()`, `getO2Skin()`, `getTelefonicaSkin()`, `getBlauSkin()`,
+`getTuSkin()`, and others via `getSkinByName()`. You can also create a custom skin.
+
+Built-in Link integrations: `Next12`, `Next13`, `Next14`, `ReactRouter5`, `ReactRouter6`.
+
+The `theme` object should be constant (outside the component) or memoized with `React.useMemo`.
+
+### Next.js optimization
+
+```js
+experimental: {
+  optimizePackageImports: ['@telefonica/mistica'];
+}
+```
+
+## Standard Page Layout
+
+```tsx
+<MainNavigationBar sections={[...]} selectedIndex={0} />
+<HeaderLayout header={<Header pretitle="Section" title="Page Title" description="..." />} />
+<ResponsiveLayout>
+  <Box paddingY={24}>
+    <Stack space={32}>
+      {/* Section with 16px element spacing */}
+      <Stack space={16}>
+        <Title1 as="h2">Section</Title1>
+        <Text2 regular as="p">Content</Text2>
+      </Stack>
+      {/* List section */}
+      <Stack space={16}>
+        <Title1 as="h2">List</Title1>
+        <NegativeBox>
+          <RowList>
+            <Row title="Item" onPress={() => {}} />
+          </RowList>
+        </NegativeBox>
+      </Stack>
+    </Stack>
+  </Box>
+</ResponsiveLayout>
+```
+
+Vertical rhythm: containers 24px padding, sections 32px spacing, elements 16px spacing.
+
+## Component Categories
+
+### Core Layout Primitives
+
+`Box`, `Stack`, `Inline`, `Align`, `Grid`/`GridItem`, `NegativeBox`, `Divider`, `HorizontalScroll`, `Boxed`,
+`Overlay`, `StackingGroup`
+
+### Page Layouts
+
+`ResponsiveLayout`, `HeaderLayout`, `GridLayout`, `MainSectionHeaderLayout`, `MasterDetailLayout`,
+`FixedFooterLayout`, `ButtonFixedFooterLayout`, `ButtonLayout`, `DoubleField`
+
+### Buttons
+
+`ButtonPrimary`, `ButtonSecondary`, `ButtonDanger`, `ButtonLink`, `ButtonLinkDanger`, `ButtonGroup`,
+`ButtonLayout`, `IconButton`, `ToggleIconButton`
+
+### Text
+
+`Text1`-`Text10`, `Title1`-`Title4`, `TextLink`
+
+### Cards
+
+`DataCard`, `MediaCard`, `CoverCard`, `NakedCard` (each with size variants: `'default'`, `'snap'`,
+`'display'`)
+
+### Forms
+
+`Form`, `TextField`, `EmailField`, `PhoneNumberField`, `PasswordField`, `Select`, `DateField`, `IntegerField`,
+`DecimalField`, `CreditCardFields`, `IbanField`, `SearchField`, `PinField`, `Switch`, `Checkbox`,
+`RadioGroup`/`RadioButton`, `DoubleField`, `Autocomplete`, `FileUpload`
+
+### Lists
+
+`RowList`/`Row`, `BoxedRowList`/`BoxedRow`, `UnorderedList`, `OrderedList`, `ListItem`
+
+### Navigation
+
+`MainNavigationBar`, `NavigationBar`, `FunnelNavigationBar`, `NavigationBarAction`,
+`NavigationBarActionGroup`, `Tabs`, `NavigationBreadcrumbs`
+
+### Headers
+
+`Header`, `HeaderLayout`, `MainSectionHeader`, `MainSectionHeaderLayout`
+
+### Feedback
+
+`SuccessFeedbackScreen`, `ErrorFeedbackScreen`, `InfoFeedbackScreen`, `Snackbar` (via `useSnackbar`),
+`alert`/`confirm`/`dialog` (via `useDialog`)
+
+### Loading
+
+`SkeletonLine`, `SkeletonText`, `SkeletonCircle`, `SkeletonRow`, `SkeletonRectangle`, `LoadingScreen`,
+`BrandLoadingScreen`, `Spinner`, `LoadingBar`
+
+### Data Display
+
+`Tag`, `Badge`, `Chip`, `Avatar`, `Image`, `Video`, `Table`, `Divider`, `Callout`, `ProgressBar`,
+`ProgressBarStepped`, `Stepper`, `Meter`, `Rating`, `InfoRating`, `Timer`, `TextTimer`,
+`Timeline`/`TimelineItem`, `Counter`
+
+### Containers / Surfaces
+
+`Boxed`, `Carousel`, `CenteredCarousel`, `Slideshow`, `Hero`, `CoverHero`, `EmptyState`, `EmptyStateCard`,
+`Accordion`/`AccordionItem`, `BoxedAccordion`/`BoxedAccordionItem`, `Drawer`, `Tooltip`, `Popover`,
+`Menu`/`MenuItem`/`MenuSection`, `Sheet`/`SheetRoot`/`showSheet`
+
+### Media
+
+`Circle`, `Square`, `StackingGroup`, `Logo`
+
+### Icons
+
+~2000 icons following the pattern `Icon{Name}{Variant}` where Variant is `Regular`, `Filled`, or `Light`. All
+accept `size` and `color` props. Use `color="currentColor"` inside buttons/navigation.
+
+### Hooks
+
+`useTheme`, `useScreenSize`, `useDialog`, `useSnackbar`, `useForm`, `useThemeVariant`, `useIsInViewport`,
+`useElementDimensions`, `useWindowSize`, `useTrackingConfig`, `useCarouselContext`
+
+## Design Tokens
+
+All tokens via `skinVars` from `@telefonica/mistica`:
+
+- **Colors**: `skinVars.colors.*` (286 tokens for backgrounds, text, borders, controls, status, tags)
+- **Raw colors**: `skinVars.rawColors.*` (same tokens as RGB values, for use with `applyAlpha`)
+- **Border radii**: `skinVars.borderRadii.*` (container, button, input, popup, chip, sheet, avatar, tag, etc.)
+- **Text presets**: Handled by text components, not accessed directly
+
+## Docs
+
+- [Components reference](./components.md): full component catalog with props and usage examples
+- [Design tokens](./design-tokens.md): skinVars colors, rawColors, applyAlpha, border radii, text presets,
+  theme variants
+- [Patterns and best practices](./patterns.md): page composition, layout dos/don'ts, color rules, responsive
+  patterns, form patterns, card patterns, list patterns, skeleton loading, funnel flows, routing integration,
+  dark mode
+- [Theme configuration](./theme-config.md): full ThemeConfig reference, Link component setup, custom skins
+- [Layout](./layout.md): Core layout primitives (Box, Stack, Inline, Align, Grid/GridItem, NegativeBox,
+  Divider, HorizontalScroll, Boxed, Overlay, StackingGroup) and page layouts (ResponsiveLayout, HeaderLayout,
+  GridLayout, MasterDetailLayout, FixedFooterLayout, ButtonFixedFooterLayout, ButtonLayout, DoubleField),
+  vertical rhythm
+- [Forms](./forms.md): Form component, all form field types, DoubleField, useForm hook
+- [Analytics](./analytics.md): trackingEvent prop, logEvent setup, default tracking, GA4 support,
+  TrackingConfig
+- [Fonts](./fonts.md): font family setup, system fonts, custom fonts, weight mapping, dynamic font sizes
+- [Texts](./texts.md): customizable text tokens, Dictionary type, translate function
+- [Sheets](./sheet.md): predefined sheets, SheetRoot, showSheet API, native webview integration, custom sheets
+- [Testing](./testing.md): NODE_ENV, unit tests, acceptance tests, isRunningAcceptanceTest
+- [Lottie](./lottie.md): optimizing bundle size with lottie-web light build
+- [Migration guide](./migration-guide.md): cards ecosystem migration (v16), v12 to v13 migration

package/doc/lottie.md

@@ -0,0 +1,17 @@
+# Optimizing bundles size when using Lotties
+
+You may notice that when using `BrandLoadingScreen` component, the `lottie-web` package is imported lazily.
+This package is a dependency of the `lottie-react` library that we use to render Lottie files.
+
+There are several reports mentioning that `lottie-web` is quiet big, so their developers have created a
+"light" version of it, that only supports some of the features
+([Link](https://github.com/airbnb/lottie-web/wiki/Lottie-Light)).
+
+If your use case of `lottie-react` library is not too complex and this light version covers your needs, you
+can patch their library to import the `lottie-web` functionalities from `lottie-web/build/player/lottie_light`
+instead. This will reduce the size of the library considerably.
+
+You can refer to this [example patch](../.yarn/patches/lottie-react-npm-2.4.0-d4d95c55aa.patch) generated by
+using `yarn patch` to understand how to update the `lottie-react` library. There is also
+[a pull request](https://github.com/Gamote/lottie-react/pull/86) in their GitHub repository where you can see
+the required diff in the `lottie-react` source code.

package/doc/migration-guide.md

@@ -0,0 +1,76 @@
+## Migration Guide for the New Cards Ecosystem (Starting from Mistica 16.xx.xx)
+
+The changes introduced in this version are backwards compatible; however, several components and props have
+been deprecated. To ensure your code remains compatible with future major updates, please update your
+implementation to replace the deprecated components and props as outlined below. This will prepare your
+codebase for the eventual removal of these deprecated features.
+
+### Card Components
+
+- The `PosterCard` component has been deprecated. Use `<CoverCard size="default" />`.
+- The `DisplayMediaCard` component has been deprecated. Use `<CoverCard size="display" />`.
+- The `SmallNakedCard` component has been deprecated. Use `<NakedCard size="snap" />`.
+- The `SnapCard` component has been deprecated. Use `<DataCard size="snap" />`.
+- The `DisplayDataCard` component has been deprecated. Use `<DataCard size="display" />`.
+- The `HighlightCard` component has been deprecated. Use `<MediaCard mediaPosition="right" />`.
+
+### Card Props
+
+- The `poster` prop has been deprecated. Use `imageSrc`. The `imageSrc` will be used as the poster when a
+  video is provided.
+- The `media` prop has been deprecated. Use `imageSrc`, `imageSrcSet`, or `videoSrc` and related props like
+  `mediaAspectRatio`.
+- The `extra` prop has been deprecated. Use `slot`.
+- The `actions` prop has been deprecated. Use `topActions`.
+- The `button` prop has been deprecated. Use `buttonPrimary`.
+- The `secondaryButton` prop has been deprecated. Use `buttonSecondary`.
+- The `isInverse` prop has been deprecated. Use `variant`.
+
+### Behavior changes
+
+- A card with onPress and buttons will show the Footer, containing the buttons, even if it was set to `false`
+  via props.
+- Cards now accept 3 kind of buttons: `buttonPrimary`, `buttonSecondary`, and `buttonLink`. You must use at
+  most 2 buttons at the same time.
+- Deprecated cards have a default `slotAlignment` of `bottom`. New cards have a default `slotAlignment` of
+  `content`. If you want to keep the previous behavior, you must set `slotAlignment="bottom"` explicitly.
+
+## Migration Guide from mistica 12.x to mistica 13.x
+
+- First of all, we recommend to run the [`theme-colors-codemod.js`](../codemods/theme-colors-codemod.js). This
+  codemod will replace all the usages of mistica colors from `Theme` (`useTheme`) with the css variables
+  defined in `skinVars.colors`.
+  - If you aren't familiar with codemods, take a look at
+    [jscodeshift doc](https://github.com/facebook/jscodeshift)
+  - To run the codemod execute:
+    ```sh
+    npx jscodeshift -t codemods/theme-colors-codemod.js <path-to-your-code>
+    ```
+- `ThemeConfig.colorScheme` is now `'auto'` by default, this means that mistica will automatically detect the
+  user's preferred color scheme and apply it. If you want to force a color scheme in your app, you can set it
+  to `'light'` or `'dark'` instead.
+- If you were using the `borderLight` and/or `borderDark` colors, you'll need to replace them with `borderLow`
+  and `borderHigh` respectively.
+- If you were applying alpha to mistica colors using some custom function, you'll need to use the new
+  `applyAlpha` function from mistica instead.
+  - Don't use `applyAlpha` with `skinVars.colors`, use it with `skinVars.rawColors` instead.
+- Mistica doesn't ship with builtin jss anymore. If you are using `createUseStyles` in your app, you will need
+  to install `jss` and `react-jss` as dependencies of your app.
+  - Keep in mind that the `jss` that mistica was using in versions 12 and below had some plugins that you may
+    still need in your app if you have decided to keep using `jss`. In that case, take a look at mistica
+    [`jss` setup in v12](https://github.com/Telefonica/mistica-web/blob/v12.13.0/src/jss.tsx#L15-L26) because
+    you may need some similar setup.
+- From version 13, mistica ships with a css file that your app must serve. You can find it in
+  `@telefonica/mistica/css/mistica.css`. The way of serve this css may be different depending on your bundler
+  setup, but the most common way is importing it like this:
+  ```js
+  import '@telefonica/mistica/css/mistica.css';
+  ```
+- If you were using the `extra` prop in `DataCard`, `MediaCard` and/or `SnapCard` components, you may need to
+  adjust some paddings, because previous versions of mistica were adding a top padding of 16px.
+- Some icons changes:
+  - If you were using the `chevron-top-regular` icon, replace the usages with `chevron-up-regular`
+  - If you were using the `play` or `pause` icons, replace them with `play-circle` and `pause-circle`
+    respectively.
+- The `small` prop has been removed from `TextLink`. Wrapping `TextLink` with a `<Text2 regular>` should be
+  equivalent in font size, but with a small variation in line height.