@telefonica/mistica 16.60.0 → 16.62.0-beta.1

package/doc/layout.md

@@ -79,7 +79,8 @@ a horizontal `Stack`, and it covers the most common row-layout use cases you mig
 It supports:
 
 - horizontal distribution via `space={number}` or `space="between" | "around" | "evenly"`
-- vertical alignment of children via `alignItems="flex-start" | "flex-end" | "center" | "stretch" | "baseline"`
+- vertical alignment of children via
+  `alignItems="flex-start" | "flex-end" | "center" | "stretch" | "baseline"`
 - wrapping via `wrap` and row spacing via `verticalSpace`
 
 :information_source: Check `Inline` in
@@ -139,6 +140,24 @@ Distribute items evenly. Items have equal space around them
 
 <img src="./images/layout/inline-evenly.svg" />
 
+### nesting
+
+Nest `Inline` components to compose richer rows. A common pattern groups a leading icon and label on the left
+with a value on the right via `space="between"`:
+
+```tsx
+<Inline space="between" alignItems="center">
+  <Inline space={8} alignItems="center">
+    <IconTruckRegular size={24} color={skinVars.colors.neutralHigh} />
+    <Text2 regular>Envío:</Text2>
+  </Inline>
+  <Text2 regular>Mañana, gratis</Text2>
+</Inline>
+```
+
+The outer `Inline` distributes the two groups to opposite ends; the inner `Inline` keeps the icon tightly
+grouped with its label at a fixed gap.
+
 ## Align
 
 Positions its children within a container using CSS grid alignment. Useful for centering content or placing it

package/doc/llms.md

@@ -15,6 +15,17 @@ This file is the main entry point. All docs live at:
 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>`.
 
+## Source code
+
+Source is available at `node_modules/@telefonica/mistica/src/` (fallback:
+`https://github.com/Telefonica/mistica-web/tree/master/src`). Use `src/index.tsx` to map imports to files.
+
+Read source only when you need to understand internal behavior that docs and types don't cover — for example
+debugging layout/CSS issues (`*.css.ts` files), understanding event handling, or authoring a custom skin (read
+a real skin in `src/skins/` to see canonical token patterns). Normally you shouldn't read source for
+greenfield UI work — the docs already cover that, and reading source tends to pull toward low-level APIs when
+a documented composite component would be simpler.
+
 ## Critical Rules
 
 1. **NEVER hardcode colors in app/component UI code.** Always use `skinVars.colors.*` design tokens from
@@ -43,6 +54,11 @@ repository at `https://github.com/Telefonica/mistica-web/blob/master/doc/<filena
     ```tsx
     <style>{`body { background-color: ${skinVars.colors.background}; }`}</style>
     ```
+11. **Re-apply these rules during debugging, reviewing, and fixing — not just while writing new code.**
+    TypeScript errors, visual mismatches, and "I just need this to work" pressure are not exceptions. If you
+    are about to add `style={{...}}` to a `<div>`, a hex literal, a manual `font-size`, a `margin: auto` /
+    `justify-content: center` workaround, or any other escape hatch inside Mistica code, stop and find the
+    primitive first — the rule you need is already above.
 
 ## Install
 
@@ -313,6 +329,7 @@ After reading the minimum set, read any further files that apply to your specifi
 | **Testing (read if you have to implement tests)** | `doc/testing.md`         |
 | **Migrating from older versions**                 | `doc/migration-guide.md` |
 | **Optimizing bundle size with lottie**            | `doc/lottie.md`          |
+| **Implementing a Figma design via Figma MCP**     | `doc/figma-mcp.md`       |
 
 ## Docs reference
 
@@ -336,3 +353,4 @@ After reading the minimum set, read any further files that apply to your specifi
 - [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
+- [Figma MCP](./figma-mcp.md): mandatory translation rules when implementing from Figma MCP output.

package/doc/patterns.md

@@ -2,19 +2,8 @@
 
 ## Critical rules
 
-1. **NEVER hardcode colors in app/component UI code.** Always use `skinVars.colors.*` from
-   `@telefonica/mistica`. For skins and theme-level customization, see [theme-config.md](./theme-config.md).
-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`). If those
-   don't cover your necessities you can set custom sizes with `Text` component.
-4. **NEVER set border radius manually.** Use `skinVars.borderRadii.*` or components that handle it (`Boxed`,
-   cards, etc.). For theme-level visual customization without a dedicated component prop, use a custom skin.
-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.
+See [Critical Rules in `llms.md`](./llms.md#critical-rules) — the single source of truth. These rules apply
+throughout this document.
 
 ## Page layout composition
 
@@ -501,10 +490,10 @@ return (
   <ResponsiveLayout>
     <Stack space={24}>
       <Stepper currentIndex={currentStep} steps={['Personal', 'Address', 'Payment', 'Confirm']} />
-        {currentStep === 0 && <PersonalInfoForm />}
-        {currentStep === 1 && <AddressForm />}
-        {currentStep === 2 && <PaymentForm />}
-        {currentStep === 3 && <ConfirmationScreen />}
+      {currentStep === 0 && <PersonalInfoForm />}
+      {currentStep === 1 && <AddressForm />}
+      {currentStep === 2 && <PaymentForm />}
+      {currentStep === 3 && <ConfirmationScreen />}
     </Stack>
   </ResponsiveLayout>
 </Stack>

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@telefonica/mistica",
-    "version": "16.60.0",
+    "version": "16.62.0-beta.1",
     "license": "MIT",
     "repository": {
         "type": "git",
@@ -14,6 +14,18 @@
         "dist-es/**",
         "css/**",
         "doc/**",
+        "src/**",
+        "!src/generated/**",
+        "!src/**/__tests__/**",
+        "!src/**/__acceptance_tests__/**",
+        "!src/**/__screenshot_tests__/**",
+        "!src/**/__type_tests__/**",
+        "!src/**/__stories__/**",
+        "!src/**/__private_stories__/**",
+        "!src/**/*-test.ts",
+        "!src/**/*-test.tsx",
+        "!src/**/*-story.ts",
+        "!src/**/*-story.tsx",
         "community.d.ts",
         "community.js"
     ],

package/src/accordion.css.ts

@@ -0,0 +1,121 @@
+import {style} from '@vanilla-extract/css';
+import * as mq from './media-queries.css';
+import {vars} from './skins/skin-contract.css';
+import {sprinkles} from './sprinkles.css';
+
+export const itemContent = sprinkles({
+    width: '100%',
+    border: 'none',
+    background: 'transparent',
+    display: 'block',
+    height: '100%',
+    padding: 0,
+});
+
+export const boxed = style({});
+
+const boxedTouchableBorderRadiusStyles = {
+    [`${boxed} &:active`]: {
+        // needed because we can't use overflow: hidden on the boxed container for the focus ring to be visible
+        borderRadius: `calc(${vars.borderRadii.container} - 1px)`,
+    },
+    [`${boxed} &:hover`]: {
+        // needed because we can't use overflow: hidden on the boxed container for the focus ring to be visible
+        borderRadius: `calc(${vars.borderRadii.container} - 1px)`,
+    },
+    [`${boxed} &[aria-expanded="true"]`]: {
+        borderBottomLeftRadius: 0,
+        borderBottomRightRadius: 0,
+    },
+};
+
+export const touchableBackground = style({
+    transition: 'background-color 0.1s ease-in-out',
+    ':active': {
+        background: vars.colors.backgroundContainerPressed,
+    },
+    '@media': {
+        [mq.supportsHover]: {
+            ':hover': {
+                background: vars.colors.backgroundContainerHover,
+            },
+            ':active': {
+                background: vars.colors.backgroundContainerPressed,
+            },
+        },
+        [mq.touchableOnly]: {
+            transition: 'none',
+        },
+    },
+    selectors: boxedTouchableBorderRadiusStyles,
+});
+
+export const touchableBackgroundOverBrand = style({
+    transition: 'background-color 0.1s ease-in-out',
+    ':active': {
+        background: vars.colors.backgroundContainerBrandPressed,
+    },
+    '@media': {
+        [mq.supportsHover]: {
+            ':hover': {
+                background: vars.colors.backgroundContainerBrandHover,
+            },
+            ':active': {
+                background: vars.colors.backgroundContainerBrandPressed,
+            },
+        },
+        [mq.touchableOnly]: {
+            transition: 'none',
+        },
+    },
+    selectors: boxedTouchableBorderRadiusStyles,
+});
+
+export const rightContentContainer = style({
+    height: '100%',
+});
+
+export const chevronContainer = style({
+    height: '100%',
+    display: 'flex',
+    alignItems: 'center',
+});
+
+export const panelContainer = style({
+    display: 'grid',
+});
+
+export const panelTransitionClasses = {
+    enter: style({
+        gridTemplateRows: '0fr',
+    }),
+    enterActive: style({
+        gridTemplateRows: '1fr',
+        transition: 'grid-template-rows 0.4s',
+        '@media': {
+            ['(prefers-reduced-motion)']: {
+                transition: 'none',
+            },
+        },
+    }),
+    exit: style({
+        gridTemplateRows: '1fr',
+    }),
+    exitActive: style({
+        gridTemplateRows: '0fr',
+        transition: 'grid-template-rows 0.4s',
+        '@media': {
+            ['(prefers-reduced-motion)']: {
+                transition: 'none',
+            },
+        },
+    }),
+};
+
+export const panel = style({
+    overflow: 'hidden',
+});
+
+export const accordionItem = sprinkles({
+    width: '100%',
+});

package/src/accordion.tsx

@@ -0,0 +1,366 @@
+'use client';
+import * as React from 'react';
+import {Content as HeaderContent} from './list';
+import IconChevron from './icons/icon-chevron';
+import Box from './box';
+import * as styles from './accordion.css';
+import Stack from './stack';
+import {BaseTouchable} from './touchable';
+import classNames from 'classnames';
+import {vars as skinVars} from './skins/skin-contract.css';
+import {getPrefixedDataAttributes} from './utils/dom';
+import Divider from './divider';
+import {InternalBoxed} from './boxed';
+import {useThemeVariant} from './theme-variant-context';
+import {CSSTransition} from 'react-transition-group';
+import {isRunningAcceptanceTest} from './utils/platform';
+import Inline from './inline';
+
+import type {ExclusifyUnion} from './utils/utility-types';
+import type {DataAttributes, TrackingEvent} from './utils/types';
+import type {TouchableElement} from './touchable';
+
+const ACCORDION_TRANSITION_DURATION_IN_MS = 400;
+
+type AccordionContextType = {
+    index: ReadonlyArray<number>;
+    toggle: (item: number) => void;
+};
+
+const AccordionContext = React.createContext<AccordionContextType>({
+    index: [],
+    toggle: () => {},
+});
+
+const useAccordionContext = (): AccordionContextType => React.useContext(AccordionContext);
+
+interface AccordionItemContentProps {
+    children?: void;
+    title: string;
+    titleAs?: string;
+    subtitle?: string;
+    asset?: React.ReactNode;
+    content: React.ReactNode;
+    dataAttributes?: DataAttributes;
+    trackingEvent?: TrackingEvent | ReadonlyArray<TrackingEvent>;
+    role?: string;
+    detail?: string;
+    right?: React.ReactNode;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+}
+
+const useAccordionState = ({
+    value,
+    defaultValue,
+    onChange,
+    singleOpen,
+}: {
+    value?: number | ReadonlyArray<number>;
+    defaultValue?: number | ReadonlyArray<number>;
+    onChange?: (item: number, value: boolean) => void;
+    singleOpen?: boolean;
+}): [ReadonlyArray<number>, (value: number) => void] => {
+    const isControlledByParent = value !== undefined;
+
+    const getValueAsList = (value?: number | ReadonlyArray<number>) => {
+        return value === undefined ? [] : typeof value === 'number' ? [value] : value;
+    };
+
+    const [index, setIndex] = React.useState<ReadonlyArray<number>>(getValueAsList(defaultValue));
+
+    React.useEffect(() => {
+        if (index.length > 1 && singleOpen) {
+            const newIndex = [...index];
+            newIndex.splice(1);
+            setIndex(newIndex);
+        }
+    }, [singleOpen, index]);
+
+    const updateIndexOnToggle = (item: number, index?: ReadonlyArray<number>) => {
+        if (!index) {
+            return [item];
+        }
+
+        const valueIndex = index.indexOf(item);
+        let newIndex = [...index];
+        if (valueIndex === -1) {
+            if (singleOpen) {
+                newIndex = [item];
+            } else {
+                newIndex.push(item);
+            }
+        } else {
+            newIndex.splice(valueIndex, 1);
+        }
+
+        return newIndex;
+    };
+
+    const toggle = (item: number) => {
+        if (!isControlledByParent) {
+            setIndex(updateIndexOnToggle(item, index));
+        }
+        if (onChange) {
+            const currentItemValue = (isControlledByParent ? getValueAsList(value) : index).includes(item);
+            onChange(item, !currentItemValue);
+        }
+    };
+
+    if (isControlledByParent) {
+        return [getValueAsList(value), toggle];
+    }
+
+    return [index, toggle];
+};
+
+const getAccordionItemIndex = (element: Element | null) => {
+    const accordionAncestor = element?.closest('[data-accordion]');
+    if (!accordionAncestor) return undefined;
+
+    return Array.from(accordionAncestor.querySelectorAll('[data-accordion-item]'))
+        .filter((e) => e.closest('[data-accordion]') === accordionAncestor)
+        .findIndex((e) => e === element);
+};
+
+const getAssetText = (asset: React.ReactNode): string => {
+    if (!React.isValidElement(asset)) return '';
+
+    const props = asset.props as {alt?: unknown; 'aria-label'?: unknown};
+
+    if (typeof props.alt === 'string' && props.alt.trim()) {
+        return props.alt.trim();
+    }
+
+    if (typeof props['aria-label'] === 'string' && props['aria-label'].trim()) {
+        return props['aria-label'].trim();
+    }
+
+    return '';
+};
+
+const AccordionItemContent = React.forwardRef<TouchableElement, AccordionItemContentProps>(
+    (
+        {
+            content,
+            dataAttributes,
+            trackingEvent,
+            right,
+            'aria-label': ariaLabel,
+            'aria-labelledby': ariaLabelledby,
+            ...props
+        },
+        ref
+    ) => {
+        const panelContainerRef = React.useRef<HTMLDivElement | null>(null);
+        const itemRef = React.useRef<HTMLDivElement | null>(null);
+        const {index, toggle} = useAccordionContext();
+        const variant = useThemeVariant();
+        const labelId = React.useId();
+        const panelId = React.useId();
+
+        const assetText = getAssetText(props.asset);
+
+        const computedAriaLabel = ariaLabel ?? [props.title, assetText].filter(Boolean).join(' ');
+
+        const [itemIndex, setItemIndex] = React.useState<number>();
+        const isOpen = itemIndex !== undefined && index?.includes(itemIndex);
+
+        React.useEffect(() => {
+            setItemIndex(getAccordionItemIndex(itemRef.current));
+        }, []);
+
+        const iconColor = {
+            default: isOpen ? skinVars.colors.chevronIndicator : skinVars.colors.chevronIndicator,
+            alternative: isOpen ? skinVars.colors.chevronIndicator : skinVars.colors.chevronIndicator,
+            brand: skinVars.colors.textSecondaryBrand,
+            media: skinVars.colors.textSecondaryBrand,
+            negative: skinVars.colors.textSecondaryNegative,
+        }[variant];
+
+        return (
+            <div ref={itemRef} {...getPrefixedDataAttributes({...dataAttributes, 'accordion-item': true})}>
+                <BaseTouchable
+                    ref={ref}
+                    className={classNames(
+                        styles.itemContent,
+                        variant === 'brand' || variant === 'media' || variant === 'negative'
+                            ? styles.touchableBackgroundOverBrand
+                            : styles.touchableBackground
+                    )}
+                    onPress={() => {
+                        if (itemIndex !== undefined) toggle(itemIndex);
+                    }}
+                    trackingEvent={trackingEvent}
+                    aria-expanded={isOpen}
+                    aria-controls={panelId}
+                    aria-label={computedAriaLabel}
+                    aria-labelledby={ariaLabelledby}
+                >
+                    <Box paddingX={16}>
+                        <HeaderContent
+                            labelId={labelId}
+                            {...props}
+                            right={({centerY}) => (
+                                <Inline
+                                    space={4}
+                                    alignItems={centerY ? 'center' : undefined}
+                                    className={styles.rightContentContainer}
+                                >
+                                    {right}
+                                    <div className={styles.chevronContainer}>
+                                        <IconChevron
+                                            size={20}
+                                            transitionDuration={ACCORDION_TRANSITION_DURATION_IN_MS}
+                                            direction={isOpen ? 'up' : 'down'}
+                                            color={iconColor}
+                                        />
+                                    </div>
+                                </Inline>
+                            )}
+                        />
+                    </Box>
+                </BaseTouchable>
+                <CSSTransition
+                    in={isOpen}
+                    timeout={isRunningAcceptanceTest() ? 0 : ACCORDION_TRANSITION_DURATION_IN_MS}
+                    nodeRef={panelContainerRef}
+                    classNames={styles.panelTransitionClasses}
+                    mountOnEnter
+                    unmountOnExit
+                >
+                    <div className={styles.panelContainer} ref={panelContainerRef}>
+                        <div className={styles.panel} role="region" aria-labelledby={labelId} id={panelId}>
+                            <Box paddingX={16} paddingBottom={16}>
+                                {content}
+                            </Box>
+                        </div>
+                    </div>
+                </CSSTransition>
+            </div>
+        );
+    }
+);
+
+export const AccordionItem = React.forwardRef<TouchableElement, AccordionItemContentProps>(
+    ({dataAttributes, role, ...props}, ref) => (
+        <div role={role} className={styles.accordionItem}>
+            <AccordionItemContent
+                {...props}
+                ref={ref}
+                dataAttributes={{'component-name': 'AccordionItem', ...dataAttributes}}
+            />
+        </div>
+    )
+);
+
+type AccordionBaseProps = {
+    children: React.ReactNode;
+    dataAttributes?: DataAttributes;
+    onChange?: (index: number, value: boolean) => void;
+    role?: string;
+};
+
+type SingleOpenProps = {
+    singleOpen: true;
+    index?: number;
+    defaultIndex?: number;
+};
+
+type MultipleOpenProps = {
+    singleOpen?: false;
+    index?: number | ReadonlyArray<number>;
+    defaultIndex?: number | ReadonlyArray<number>;
+};
+
+type AccordionProps = AccordionBaseProps & ExclusifyUnion<SingleOpenProps | MultipleOpenProps>;
+
+export const Accordion = ({
+    children,
+    dataAttributes,
+    index,
+    defaultIndex,
+    onChange,
+    singleOpen,
+    role,
+}: AccordionProps): JSX.Element => {
+    const [indexList, toggle] = useAccordionState({
+        value: index,
+        defaultValue: defaultIndex,
+        onChange,
+        singleOpen,
+    });
+    const childrenContent = React.Children.toArray(children).filter(Boolean);
+    const lastIndex = childrenContent.length - 1;
+
+    return (
+        <AccordionContext.Provider value={{index: indexList, toggle}}>
+            <div
+                role={role}
+                {...getPrefixedDataAttributes({...dataAttributes, accordion: true}, 'Accordion')}
+            >
+                {childrenContent.map((child, index) => (
+                    <React.Fragment key={index}>
+                        {child}
+                        {index < lastIndex && (
+                            <Box paddingX={16}>
+                                <Divider />
+                            </Box>
+                        )}
+                    </React.Fragment>
+                ))}
+            </div>
+        </AccordionContext.Provider>
+    );
+};
+
+interface BoxedAccordionItemProps extends AccordionItemContentProps {
+    /**
+     * @deprecated Use `variant="brand"` instead.
+     */
+    isInverse?: boolean;
+    variant?: 'default' | 'brand';
+}
+
+export const BoxedAccordionItem = React.forwardRef<HTMLDivElement, BoxedAccordionItemProps>(
+    ({dataAttributes, isInverse, variant, ...props}, ref) => (
+        <InternalBoxed
+            overflow="visible"
+            className={styles.boxed}
+            variant={variant ?? (isInverse ? 'brand' : 'default')}
+            ref={ref}
+            dataAttributes={{'component-name': 'BoxedAccordionItem', ...dataAttributes}}
+        >
+            <AccordionItemContent {...props} />
+        </InternalBoxed>
+    )
+);
+
+export const BoxedAccordion = ({
+    children,
+    dataAttributes,
+    index,
+    defaultIndex,
+    onChange,
+    singleOpen,
+    role,
+}: AccordionProps): JSX.Element => {
+    const [indexList, toggle] = useAccordionState({
+        value: index,
+        defaultValue: defaultIndex,
+        onChange,
+        singleOpen,
+    });
+
+    return (
+        <AccordionContext.Provider value={{index: indexList, toggle}}>
+            <Stack
+                space={16}
+                role={role}
+                dataAttributes={{'component-name': 'BoxedAccordion', accordion: true, ...dataAttributes}}
+            >
+                {children}
+            </Stack>
+        </AccordionContext.Provider>
+    );
+};

package/src/align.css.ts

@@ -0,0 +1,7 @@
+import {style} from '@vanilla-extract/css';
+
+export const container = style({
+    display: 'grid',
+    width: '100%',
+    height: '100%',
+});

package/src/align.tsx

@@ -0,0 +1,32 @@
+import * as React from 'react';
+import {getPrefixedDataAttributes} from './utils/dom';
+import * as styles from './align.css';
+
+import type {DataAttributes} from './utils/types';
+
+type Props = {
+    x?: 'start' | 'center' | 'end';
+    y?: 'start' | 'center' | 'end';
+    width?: number | string;
+    height?: number | string;
+    children?: React.ReactNode;
+    dataAttributes?: DataAttributes;
+};
+
+const Align = ({x = 'start', y = 'start', width, height, children, dataAttributes}: Props): JSX.Element => {
+    return (
+        <div
+            {...getPrefixedDataAttributes(dataAttributes, 'Align')}
+            className={styles.container}
+            style={{
+                placeItems: `${y} ${x}`,
+                ...(width !== undefined ? {width} : {}),
+                ...(height !== undefined ? {height} : {}),
+            }}
+        >
+            {children}
+        </div>
+    );
+};
+
+export default Align;