@telefonica/mistica 16.56.0 → 16.57.0-beta.1

package/doc/patterns.md

@@ -0,0 +1,548 @@
+# Patterns and Best Practices
+
+## Critical rules
+
+1. **NEVER hardcode colors.** Always use `skinVars.colors.*` from `@telefonica/mistica`.
+2. **NEVER use raw `<div>` for layout.** Use `Box`, `Stack`, `Inline`, `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 components that handle it (`Boxed`,
+   cards, etc.).
+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`, etc.
+7. **Add `'use client';`** directive to client components when using Next.js app router.
+8. **Set `font-family` and `body` background color.** See [llms.md](./llms.md) rules 9–10 and
+   [fonts.md](./fonts.md) for the per-skin font table, `@font-face` setup, and the `GlobalStyles` pattern.
+
+## Page layout composition
+
+A standard Mistica page follows this structure:
+
+```tsx
+// Navigation
+<MainNavigationBar ... />
+
+// Header section
+<HeaderLayout
+  header={<Header pretitle="Section" title="Page Title" description="Description" />}
+/>
+
+// Content sections
+<ResponsiveLayout>
+  <Box paddingY={24}>
+    <Stack space={32}>
+      {/* Section 1 */}
+      <Stack space={16}>
+        <Title1 as="h2">Section Title</Title1>
+        <Text2 regular as="p">Section description</Text2>
+      </Stack>
+
+      {/* Section 2 - List */}
+      <Stack space={16}>
+        <Title1 as="h2">Another Section</Title1>
+        <NegativeBox>
+          <RowList>
+            <Row title="Item 1" onPress={() => {}} />
+            <Row title="Item 2" onPress={() => {}} />
+          </RowList>
+        </NegativeBox>
+      </Stack>
+    </Stack>
+  </Box>
+</ResponsiveLayout>
+```
+
+### Vertical rhythm
+
+Follow the 24/32/16 rule:
+
+- **Containers**: 24px top and bottom padding (`<Box paddingY={24}>`)
+- **Sections**: 32px space between them (`<Stack space={32}>`)
+- **Elements**: 16px space between them (`<Stack space={16}>`)
+
+## Layout dos and don'ts
+
+### DO: Use layout components
+
+```tsx
+// Vertical spacing
+<Stack space={16}>
+  <Text2 regular>First</Text2>
+  <Text2 regular>Second</Text2>
+</Stack>
+
+// Horizontal spacing
+<Inline space={16}>
+  <ButtonPrimary onPress={() => {}}>Accept</ButtonPrimary>
+  <ButtonSecondary onPress={() => {}}>Cancel</ButtonSecondary>
+</Inline>
+
+// Padding
+<Box padding={16}>
+  <Text2 regular>Padded content</Text2>
+</Box>
+
+// Page container
+<ResponsiveLayout>
+  <Text2 regular>Responsive content</Text2>
+</ResponsiveLayout>
+```
+
+### DON'T: Use divs for spacing/layout
+
+```tsx
+// BAD - raw divs for spacing
+<div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
+  <div style={{padding: 16}}>
+    <span style={{fontSize: 14, color: '#333'}}>Text</span>
+  </div>
+</div>
+
+// GOOD - Mistica components
+<Stack space={16}>
+  <Box padding={16}>
+    <Text2 regular>Text</Text2>
+  </Box>
+</Stack>
+```
+
+## Color dos and don'ts
+
+### DO: Use design tokens
+
+```tsx
+import {skinVars, applyAlpha} from '@telefonica/mistica';
+
+// Direct token usage
+<Text2 regular color={skinVars.colors.textSecondary}>Secondary text</Text2>
+
+// In styles (when absolutely needed)
+<div style={{backgroundColor: skinVars.colors.backgroundContainer}}>...</div>
+
+// Semi-transparent colors
+const overlay = applyAlpha(skinVars.rawColors.backgroundBrand, 0.8);
+```
+
+### DON'T: Hardcode colors
+
+```tsx
+// BAD - hardcoded colors
+<Text2 regular color="#666">Text</Text2>
+<div style={{backgroundColor: '#f5f5f5'}}>...</div>
+<div style={{color: 'rgb(0, 112, 224)'}}>...</div>
+
+// GOOD - design tokens
+<Text2 regular color={skinVars.colors.textSecondary}>Text</Text2>
+<Boxed><Text2 regular>Content in container</Text2></Boxed>
+```
+
+## Responsive patterns
+
+### Conditional rendering by screen size
+
+```tsx
+const {isDesktopOrBigger, isTabletOrSmaller} = useScreenSize();
+
+return (
+  <ResponsiveLayout>
+    <Box paddingY={24}>
+      {isDesktopOrBigger ? (
+        <GridLayout template="6+6" left={<LeftContent />} right={<RightContent />} />
+      ) : (
+        <Stack space={16}>
+          <LeftContent />
+          <RightContent />
+        </Stack>
+      )}
+    </Box>
+  </ResponsiveLayout>
+);
+```
+
+### Grid templates for desktop/mobile
+
+```tsx
+<ResponsiveLayout>
+  <GridLayout template="8+4" left={<MainContent />} right={<Sidebar />} />
+</ResponsiveLayout>
+```
+
+On mobile, GridLayout stacks content vertically automatically.
+
+### Master-detail pattern
+
+```tsx
+const [selectedId, setSelectedId] = React.useState(null);
+
+<MasterDetailLayout
+  isOpen={!!selectedId}
+  master={
+    <RowList>
+      {items.map((item) => (
+        <Row key={item.id} title={item.name} onPress={() => setSelectedId(item.id)} />
+      ))}
+    </RowList>
+  }
+  detail={selectedId ? <DetailView id={selectedId} /> : <Text2 regular>Select an item</Text2>}
+/>;
+```
+
+## Form patterns
+
+### Automatic state management (preferred)
+
+```tsx
+<Form initialValues={{email: '', name: ''}} onSubmit={(formData) => api.submit(formData)}>
+  <Stack space={16}>
+    <TextField name="name" label="Name" />
+    <EmailField name="email" label="Email" />
+    <PhoneNumberField name="phone" label="Phone" optional />
+    <DoubleField>
+      <DateField name="startDate" label="Start date" />
+      <DateField name="endDate" label="End date" />
+    </DoubleField>
+    <Select
+      name="country"
+      label="Country"
+      options={[
+        {value: 'es', text: 'Spain'},
+        {value: 'uk', text: 'United Kingdom'},
+      ]}
+    />
+    <Switch name="newsletter">Receive newsletter</Switch>
+    <ButtonLayout
+      primaryButton={
+        <ButtonPrimary submit loadingText="Sending...">
+          Submit
+        </ButtonPrimary>
+      }
+    />
+  </Stack>
+</Form>
+```
+
+### Form with fixed footer
+
+```tsx
+<ButtonFixedFooterLayout button={<ButtonPrimary submit>Continue</ButtonPrimary>}>
+  <ResponsiveLayout>
+    <Box paddingY={24}>
+      <Form onSubmit={handleSubmit}>
+        <Stack space={16}>
+          <TextField name="name" label="Name" />
+          <EmailField name="email" label="Email" />
+        </Stack>
+      </Form>
+    </Box>
+  </ResponsiveLayout>
+</ButtonFixedFooterLayout>
+```
+
+## Carousel patterns
+
+`Carousel`, `CenteredCarousel`, and `Slideshow` are **horizontal-scroll** components. Use them when content
+needs to be navigated left-to-right (e.g. product cards, promotional banners, image galleries).
+
+### Carousel vs CenteredCarousel vs Slideshow
+
+| Component          | Best for                                           | Visible items               |
+| ------------------ | -------------------------------------------------- | --------------------------- |
+| `Carousel`         | Card collections, product grids                    | Configurable per breakpoint |
+| `CenteredCarousel` | Featured/highlighted items with neighbour peek     | 1 on mobile, 3 on desktop   |
+| `Slideshow`        | Full-width hero banners, autoplay image slideshows | 1 at a time                 |
+
+### Placement rules
+
+- **`Carousel` and `CenteredCarousel`**: place inside `ResponsiveLayout` so they respect the page grid.
+- **`Slideshow`**: place **outside** `ResponsiveLayout` — it bleeds full-width on mobile and tablet
+  automatically.
+
+```tsx
+{
+  /* Carousel inside ResponsiveLayout */
+}
+<ResponsiveLayout>
+  <Box paddingY={24}>
+    <Stack space={16}>
+      <Title2 as="h2">Featured products</Title2>
+      <Carousel
+        itemsPerPage={{mobile: 1, tablet: 2, desktop: 3}}
+        withBullets
+        items={products.map((p, i) => (
+          <DataCard
+            key={i}
+            title={p.name}
+            description={p.description}
+            buttonPrimary={
+              <ButtonPrimary small onPress={() => navigate(p.url)}>
+                View
+              </ButtonPrimary>
+            }
+          />
+        ))}
+      />
+    </Stack>
+  </Box>
+</ResponsiveLayout>;
+
+{
+  /* Slideshow at page level (outside ResponsiveLayout) */
+}
+<Slideshow
+  withBullets
+  autoplay={{time: 5000, loop: true}}
+  items={[
+    <CoverCard key="1" imageSrc="/banner1.jpg" title="Offer 1" />,
+    <CoverCard key="2" imageSrc="/banner2.jpg" title="Offer 2" />,
+  ]}
+/>;
+```
+
+## Card patterns
+
+### Asset pattern for cards and rows
+
+The idiomatic way to create card/row assets is `Circle` + icon:
+
+```tsx
+<Circle backgroundColor={skinVars.colors.brandLow} size={40}>
+  <IconShopRegular color={skinVars.colors.brand} />
+</Circle>
+```
+
+### Card grid
+
+```tsx
+<ResponsiveLayout>
+  <Box paddingY={24}>
+    <Stack space={16}>
+      <Title1 as="h2">Featured</Title1>
+      <Carousel
+        itemsPerPage={{mobile: 1, tablet: 2, desktop: 3}}
+        items={products.map((p) => (
+          <DataCard
+            key={p.id}
+            asset={
+              <Circle backgroundColor={skinVars.colors.brandLow} size={40}>
+                <IconShopRegular color={skinVars.colors.brand} />
+              </Circle>
+            }
+            title={p.name}
+            description={p.description}
+            buttonPrimary={
+              <ButtonPrimary small onPress={() => navigate(p.url)}>
+                View
+              </ButtonPrimary>
+            }
+          />
+        ))}
+      />
+    </Stack>
+  </Box>
+</ResponsiveLayout>
+```
+
+## List patterns
+
+### Unbounded list with NegativeBox
+
+When placing a `RowList` inside a `ResponsiveLayout`, wrap it with `NegativeBox` so hover effects and
+alignment are correct:
+
+```tsx
+<ResponsiveLayout>
+  <Box paddingY={24}>
+    <Stack space={16}>
+      <Title1>Settings</Title1>
+      <NegativeBox>
+        <RowList>
+          <Row
+            asset={
+              <Circle backgroundColor={skinVars.colors.brandLow} size={40}>
+                <IconSettingsRegular color={skinVars.colors.brand} />
+              </Circle>
+            }
+            title="General"
+            description="App settings"
+            onPress={() => {}}
+          />
+          <Row
+            asset={
+              <Circle backgroundColor={skinVars.colors.brandLow} size={40}>
+                <IconBellRegular color={skinVars.colors.brand} />
+              </Circle>
+            }
+            title="Notifications"
+            description="Manage alerts"
+            onPress={() => {}}
+          />
+        </RowList>
+      </NegativeBox>
+    </Stack>
+  </Box>
+</ResponsiveLayout>
+```
+
+### Boxed list (no NegativeBox needed)
+
+```tsx
+<BoxedRowList>
+  <BoxedRow title="Option A" onPress={() => {}} />
+  <BoxedRow title="Option B" onPress={() => {}} />
+</BoxedRowList>
+```
+
+## Variant sections
+
+Use `variant` on `ResponsiveLayout` to create colored sections. Components inside adapt automatically:
+
+```tsx
+{
+  /* Default section */
+}
+<ResponsiveLayout>
+  <Box paddingY={24}>
+    <Text2 regular>Default background</Text2>
+  </Box>
+</ResponsiveLayout>;
+
+{
+  /* Brand section */
+}
+<ResponsiveLayout variant="brand" fullWidth>
+  <ResponsiveLayout>
+    <Box paddingY={24}>
+      <Stack space={16}>
+        <Title1>Brand Section</Title1>
+        <Text2 regular>Colors adapt automatically</Text2>
+        <ButtonPrimary onPress={() => {}}>Action</ButtonPrimary>
+      </Stack>
+    </Box>
+  </ResponsiveLayout>
+</ResponsiveLayout>;
+
+{
+  /* Alternative section */
+}
+<ResponsiveLayout variant="alternative" fullWidth>
+  <ResponsiveLayout>
+    <Box paddingY={24}>
+      <Text2 regular>Alternative background</Text2>
+    </Box>
+  </ResponsiveLayout>
+</ResponsiveLayout>;
+```
+
+## Boxed containers
+
+Use `Boxed` for card-like containers without card semantics:
+
+```tsx
+<Boxed>
+  <Box padding={16}>
+    <Stack space={16}>
+      <Title3>Container Title</Title3>
+      <Text2 regular>Container content</Text2>
+    </Stack>
+  </Box>
+</Boxed>
+```
+
+## Skeleton loading patterns
+
+Replace content with matching skeleton shapes while loading:
+
+```tsx
+const {data, isLoading} = useFetch('/api/data');
+
+if (isLoading) {
+  return (
+    <Stack space={16}>
+      <SkeletonLine width="40%" />
+      <SkeletonText />
+      <Inline space={16}>
+        <SkeletonCircle size={40} />
+        <SkeletonLine width="60%" />
+      </Inline>
+    </Stack>
+  );
+}
+
+return (
+  <Stack space={16}>
+    <Title1>{data.title}</Title1>
+    <Text2 regular>{data.description}</Text2>
+    <Inline space={16}>
+      <Avatar size={40} src={data.avatar} />
+      <Text2 regular>{data.author}</Text2>
+    </Inline>
+  </Stack>
+);
+```
+
+## Funnel / step-by-step flow
+
+```tsx
+<FunnelNavigationBar
+  right={
+    <NavigationBarActionGroup>
+      <NavigationBarAction aria-label="Close" onPress={handleClose}>
+        <IconCloseRegular color="currentColor" />
+      </NavigationBarAction>
+    </NavigationBarActionGroup>
+  }
+/>
+<Stepper currentIndex={currentStep} steps={['Personal', 'Address', 'Payment', 'Confirm']} />
+<ResponsiveLayout>
+  <Box paddingY={24}>
+    {currentStep === 0 && <PersonalInfoForm />}
+    {currentStep === 1 && <AddressForm />}
+    {currentStep === 2 && <PaymentForm />}
+    {currentStep === 3 && <ConfirmationScreen />}
+  </Box>
+</ResponsiveLayout>
+```
+
+## Next.js integration
+
+### Link configuration
+
+```tsx
+import Link from 'next/link';
+
+const theme = {
+  skin: getMovistarNewSkin(),
+  i18n: {locale: 'es-ES', phoneNumberFormattingRegionCode: 'ES'},
+  Link: {type: 'Next14', Component: Link},
+};
+```
+
+### React Router integration
+
+```tsx
+import {Link} from 'react-router-dom';
+
+const theme = {
+  skin: getMovistarNewSkin(),
+  i18n: {locale: 'es-ES', phoneNumberFormattingRegionCode: 'ES'},
+  Link: {type: 'ReactRouter6', Component: Link},
+};
+```
+
+After configuring, use the `to` prop on touchable components for client-side navigation:
+
+```tsx
+<ButtonPrimary to="/dashboard">Go to dashboard</ButtonPrimary>
+<Row title="Profile" to="/profile" />
+<TextLink to="/settings">Settings</TextLink>
+```
+
+## Dark mode
+
+Mistica supports dark mode out of the box via `colorScheme` in theme config:
+
+- `'auto'` (default) -- follows OS/browser preference
+- `'light'` -- force light mode
+- `'dark'` -- force dark mode
+
+All `skinVars.colors.*` tokens automatically resolve to their dark mode values. No additional code is needed.

package/doc/sheet.md

@@ -0,0 +1,122 @@
+# Sheet
+
+Mística provides a sheet component that can be used to display a modal-like content from over the main content
+of the screen.
+
+## Predefined sheets
+
+Some predefined sheets are available: `RadioListSheet`, `ActionsListSheet`, `InfoSheet` and `ActionsSheet`.
+You can see examples in Storybook.
+
+To use them, first you must configure the `SheetRoot` component in your app:
+
+```jsx
+import {SheetRoot} from '@telefonica/mistica';
+
+export const App = () => {
+  return (
+    <SheetRoot>
+      <MyApplication />
+    </SheetRoot>
+  );
+};
+```
+
+Then you can call `showSheet` from anywhere:
+
+```jsx
+import {showSheet} from '@telefonica/mistica';
+
+const MyComponent = () => {
+  return (
+    <ButtonPrimary
+      onPress={() =>
+        showSheet({
+          type: 'RADIO_LIST',
+          props: {
+            title: 'Select an fruit',
+            items: [
+              {id: '1', title: 'Apple'},
+              {id: '2', title: 'Banana'},
+              {id: '3', title: 'Orange'},
+            ],
+          },
+        }).then((result) => {
+          // The promise is resolved when the sheet is closed
+          console.log(result);
+        })
+      }
+    >
+      show sheet
+    </ButtonPrimary>
+  );
+};
+```
+
+### Native implementation
+
+If your app is served inside a webview and uses the `webview-bridge` library, the native implementation of the
+predefined sheets will be used.
+
+```tsx
+import {bottomSheet, isWebViewBridgeAvailable} from '@tef-novum/webview-bridge';
+
+// ...
+
+<SheetRoot nativeImplementation={isWebViewBridgeAvailable() ? bottomSheet : undefined}>
+```
+
+When possible, always use the native implementation, as it provides a better user experience.
+
+## Custom sheets
+
+You can show any content you want inside the sheet by passing it as a child of the component.
+
+```jsx
+import {Sheet} from 'mistica';
+
+const MyComponent = () => {
+  const [showSheet, setShowSheet] = useState(false);
+  return (
+    <>
+      <ButtonPrimary onPress={() => setShowSheet(true)}>show sheet</ButtonPrimary>
+      {showSheet && (
+        <Sheet onClose={() => setShowSheet(false)}>
+          <Placeholder />
+        </Sheet>
+      )}
+    </>
+  );
+};
+```
+
+The sheet will close when the user does the swipe down gesture, when the background overlay is touched, or by
+using the visible dismiss button (close icon) that appears in the top-right corner aligned with the title. The
+`onClose` callback is called when the closing animation finishes, that's the right place to unmount the sheet
+as shown in the example above.
+
+You can also close the sheet programmatically using the render prop:
+
+```jsx
+import {Sheet} from 'mistica';
+
+const MyComponent = () => {
+  const [showSheet, setShowSheet] = useState(false);
+  return (
+    <>
+      <ButtonPrimary onPress={() => setShowSheet(true)}>show sheet</ButtonPrimary>
+      {showSheet && (
+        <Sheet onClose={() => setShowSheet(false)}>
+          {({closeModal, modalTitleId}) => (
+            <>
+              <Title1 id={modalTitleId}>My sheet</Title1>
+              <Placeholder />
+              <ButtonPrimary onPress={closeModal}>Close</ButtonPrimary>
+            </>
+          )}
+        </Sheet>
+      )}
+    </>
+  );
+};
+```

package/doc/testing.md

@@ -0,0 +1,43 @@
+# Testing notes
+
+## Environment variables
+
+Our code uses the NODE_ENV var to define code blocks that should be executed in specific environments, like
+`'test'` or `'production'`.
+
+For example:
+
+```js
+if (process.env.NODE_ENV !== 'test') {
+  // this will only be executed if not inside a test
+}
+```
+
+Make sure your bundler (webpack, rollup, parcel, etc) makes the correct substitutions and the minifier
+effectively removes unused code.
+
+## Unit tests
+
+Unit tests usually don't require CSS because they test component functionality. Some Mistica components have
+different layouts in mobile and desktop, and there are cases in which we use CSS styles to achieve this
+result. If you are trying to test something that depends on these styles, you can either import `mistica.css`
+classes in the HTML content you render in the test or write acceptance/screenshot tests instead.
+
+## Acceptance tests
+
+To change some behaviors to facilitate acceptance tests (tests that run in a browser), a helper function is
+used.
+
+`isRunningAcceptanceTest` returns true if the user agent includes the `'acceptance-test'` string.
+
+To make this work in your test environment, you should add that string to the browser's user agent. For
+example in `Puppeteer`:
+
+```js
+await page.setUserAgent(`${currentUserAgent} acceptance-test`);
+```
+
+## Questions?
+
+Don't hesistate to ask at
+[Mistica Teams Channel](https://teams.microsoft.com/l/channel/19%3ad2e3607a32ec411b8bf492f43cd0fe0c%40thread.tacv2/General?groupId=e265fe99-929f-45d1-8154-699649674a40&tenantId=9744600e-3e04-492e-baa1-25ec245c6f10)