@telefonica/mistica 16.55.0 → 16.56.1-beta.1

package/doc/texts.md

@@ -0,0 +1,42 @@
+# Customizable texts
+
+Some components use some default texts that you can customize using [`theme` prop](./theme-config.md)
+
+You can customize them in your page. For example:
+
+```tsx
+<ThemeContextProvider
+  theme={{
+    skin: getMovistarSkin(),
+    i18n: {locale: 'es-ES', phoneNumberFormattingRegionCode: 'ES'},
+    texts: {
+      formCreditCardExpirationError: 'Fecha incorrecta',
+      // ...
+    },
+  }}
+>
+  <App />
+</ThemeContextProvider>
+```
+
+See the `Dictionary` type to known all the available texts.
+
+If your application supports multi language, you may need to override all the texts and use localized
+translation tokens depending on your user preferred language.
+
+## Using Mística text tokens
+
+You can use Mística tokens in your texts. The translate function `t` will translate the token using the
+configured locale in the `ThemeContextProvider`.
+
+Example:
+
+```tsx
+import {textTokens} from '@telefonica/mistica';
+
+const MyComponent = () => {
+  const {t} = useTheme();
+
+  return <div>{t(textTokens.formCreditCardExpirationError)}</div>;
+};
+```

package/doc/theme-config.md

@@ -0,0 +1,124 @@
+# Theme config
+
+The `ThemeContextProvider` component receives a `theme` prop where you can customize some aspects of the lib.
+The `theme` prop must have the following type:
+
+```ts
+type ThemeConfig = {
+  skin: Skin;
+  colorScheme?: ColorScheme;
+  i18n: {
+    locale: Locale;
+    phoneNumberFormattingRegionCode: RegionCode;
+  };
+  platformOverrides?: {
+    platform?: 'ios' | 'android';
+    insideNovumNativeApp?: boolean;
+    userAgent?: string;
+  };
+  texts?: Partial<Dictionary>;
+  analytics?: {
+    logEvent: (event: TrackingEvent) => Promise<void>;
+  };
+  Link?: LinkComponent;
+  useHrefDecorator: () => (href: string) => string;
+  preventCopyInFormFields?: boolean;
+};
+```
+
+Only `skin` and `i18n` are mandatory.
+
+Here is a description of every attribute:
+
+- `skin`: determines the look and feel used by the lib (colors, font weight, etc). You can use
+  `getMovistarSkin`, `getVivoSkin` to use a specific skin or `getSkinByName`. You can also create your own
+  custom skin.
+- `colorScheme`: used to enable/disable the dark mode support. It can be `'light'` (force light mode),
+  `'dark'` (force dark mode), or `'auto'` (uses OS/browser settings, this is the default behavior). We
+  recommend using the default setting (`'auto'`) if you want to support dark mode in your app.
+- `i18n`: we use this to localize some messages or formatting dates phone numbers, etc.
+  - `locale`: a valid locale (language and region codes separated by `'-'`). For example `'es-ES'`.
+  - `phoneNumberFormattingRegionCode`: region code used to format phone numbers (for example in
+    `PhoneNumberField`).
+- `platformOverrides?`:
+  - `platform?`: the lib applies some style differences depending on the current platform.
+    `@telefonica/mistica` will try to automatically detect the platform, but you can manually set this setting
+    to `'ios'` or `'android'`
+  - `insideNovumNativeApp?:` some components have different behavior if the web is running inside a webview in
+    the native Novum App. The lib can autodetect it, but you can force it by setting this to `true`.
+  - `userAgent:` **IMPORTANT** In case you are using SSR, you should set this value with the user-agent header
+    you receive on every request to your server, otherwise the server-side render won't take the user agent
+    into account.
+- `texts?`: some copies you can customize. See [texts doc](./texts.md).
+- `t`: this is the translate funtion. It accepts a token as exported by `textTokens`. See
+  [texts doc](./texts.md).
+- `analytics?`: see [analytics docs](./analytics.md).
+- `Link?`: the `Link` component you want to use by Touchables that use the prop `to`. By default, the lib uses
+  an anchor tag (`<a>`). Use this prop to use the Link component from ReactRouter, Next.js or any other
+  library. Please read the [LinkComponent](#linkcomponent) section for more info.
+- `useHrefDecorator`: it is a React hook that a function that takes a `href` and returns a new `href`. This is
+  useful to automatically add parameters to the `href` being used in Touchable components (for example, to add
+  a `utm_source` parameter to the `href`).
+- `preventCopyInFormFields?`: this is used as the default value for `preventCopy` prop in form fields. `false`
+  by default.
+
+## LinkComponent
+
+You can use a custom component or use a built in one. Mistica has built in support for: `Next12`, `Next13`,
+`Next14`, `ReactRouter5` and `ReactRouter6`.
+
+### Next example
+
+```ts
+import Link from 'next/link';
+
+const theme: ThemeConfig = {
+  ...
+  Link: {type: 'Next14', Component: Link}
+}
+```
+
+### React Router example
+
+```ts
+import {Link} from 'react-router-dom';
+
+const theme: ThemeConfig = {
+  ...
+  Link: {type: 'ReactRouter6', Component: Link}
+}
+```
+
+## Create a custom skin
+
+If your app doesn't follow the branding of mistica builtin skins (Movistar, Vivo, O2, Telefonica, etc.), you
+can still use mistica with your custom skin. Just import the `Skin` type and create a new skin config that
+implements the `Skin` interface (you need to define all the required color constants):
+
+```ts
+import type {Skin} from '@telefonica/mistica';
+
+const skin: Skin = {
+  name: 'your skin name',
+  colors: {
+    // define here the required color constants
+  },
+  darkModeColors: {
+    // optionally define here the color constant overrides for dark mode
+  },
+};
+
+<ThemeContextProvider
+  theme={{
+    skin,
+    i18n: {
+      locale: 'es-ES',
+      phoneNumberFormattingRegionCode: 'ES',
+    },
+  }}
+>
+  <App />
+</ThemeContextProvider>;
+```
+
+You can see an example in the [examples folder](../examples/custom-skin/).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@telefonica/mistica",
-    "version": "16.55.0",
+    "version": "16.56.1-beta.1",
     "license": "MIT",
     "repository": {
         "type": "git",
@@ -13,6 +13,7 @@
         "dist/**",
         "dist-es/**",
         "css/**",
+        "doc/**",
         "community.d.ts",
         "community.js"
     ],
@@ -116,7 +117,7 @@
         "lodash": "^4.17.21",
         "mini-css-extract-plugin": "^1.6.2",
         "node-fetch": "^2.6.7",
-        "playroom": "^1.0.3",
+        "playroom": "^1.2.1",
         "postcss": "^8.4.18",
         "postcss-loader": "^4.2.0",
         "prettier": "^3.3.2",
@@ -198,8 +199,7 @@
         "@types/react-dom": "19.2.3",
         "@testing-library/dom": "^8.19.1",
         "lottie-react@^2.4.0": "patch:lottie-react@npm%3A2.4.0#./.yarn/patches/lottie-react-npm-2.4.0-d4d95c55aa.patch",
-        "playroom@^0.39.0": "patch:playroom@npm%3A0.39.0#./.yarn/patches/playroom-npm-0.39.0-24448abd08.patch",
-        "playroom@^1.0.3": "patch:playroom@npm%3A1.0.3#./.yarn/patches/playroom-npm-1.0.3-d8e0669615.patch"
+        "playroom@^1.2.1": "patch:playroom@npm%3A1.2.1#./.yarn/patches/playroom-npm-1.2.1-6d189aed91.patch"
     },
     "packageManager": "yarn@3.6.1",
     "workspaces": [