Mapas anidados en SISASS

Tipo: Artículo

Versión: 2.x.x

SISASS utiliza mapas anidados para agrupar una configuración especializada y entregarla al mixin que conoce ese contrato. Así, una API puede delegar opciones de posición o de fondo sin repetir todas sus claves en el nivel exterior.

El anidamiento no es obligatorio para todos los mixins que reciben un map. Este patrón también se denomina map anidado. El artículo explica cómo reconocerlo; las páginas de referencia de cada API siguen siendo la fuente de verdad para sus claves, alias y valores predeterminados.

Mapas planos y mapas anidados

Un mapa plano contiene claves cuyos valores son datos finales para la API que lo recibe. En este ejemplo, width y display pertenecen al mismo nivel: 

$flat_map: (
    width: 140px,
    display: block
);

Un mapa anidado contiene al menos una clave cuyo valor es otro mapa. Aquí, el primer position es la clave contenedora que reconoce replace-base; el segundo position y z pertenecen al mapa interior procesado con la sintaxis del mixin position. 

$nested_map: (
    width: 140px,
    position: (
        position: relative,
        z: 2
    )
);

Claves contenedoras y rutas documentales

Una clave contenedora tiene un contrato propio. Puede aceptar únicamente un mapa, ser opcional o usar un valor como false para desactivar un bloque. Sus claves interiores siguen el contrato de la API delegada y no se pueden trasladar automáticamente al mapa exterior.

La documentación usa puntos para representar la jerarquía. Por ejemplo, position.z significa «clave z dentro del mapa position». Es una ruta documental: no es la clave literal "position.z" ni una sintaxis de acceso válida de Sass.

Ruta documental Significado
position.z Clave z dentro del mapa position.
base.position Clave position dentro del mapa base.
base.position.z Clave z dentro de position, que a su vez está dentro de base.

Una clave con el mismo nombre en niveles distintos no representa necesariamente el mismo dato. Por ejemplo, un z exterior no forma parte del contrato de replace-base; debe escribirse como position.z dentro del mapa de posición.

Valores predeterminados, centinelas y alias

Un valor predeterminado se usa cuando una clave no está presente. Un centinela comunica un comportamiento especial: en replace-base, position: false desactiva todo el bloque de posición, mientras que position.z: false evita generar z-index sin desactivar las demás propiedades de posición. Un valor explícito sustituye el valor que la API habría utilizado por defecto.

normalize-svg parte de position: relative y position.z: 2. Si se proporciona solo una clave en su mapa de posición, el wrapper conserva los demás valores interiores definidos por su integración con replace-base.

Los alias pertenecen al nivel donde se definen. En el siguiente mapa, p, t y l son alias interiores de position; escribirlos en el nivel exterior no produce la misma configuración. Consulta la página de referencia de cada mixin para conocer la precedencia exacta entre una clave principal y sus alias. 

position: (
    p: absolute,
    t: 0,
    l: 0
)

Fusión y reemplazo de mapas

map.merge realiza una fusión superficial. Cuando dos mapas contienen la misma clave contenedora, el segundo valor reemplaza el mapa interior completo; no se fusionan automáticamente sus claves internas. 

@use "sass:map";

$defaults: (
    position: (
        position: relative,
        z: 2
    )
);

$custom: (
    position: (
        top: 10px
    )
);

$result: map.merge($defaults, $custom);

En $result, el mapa position de $custom reemplaza al de $defaults. Por ello, no conserva automáticamente position: relative ni z: 2. Una API puede implementar una fusión específica para preservar valores interiores, como hace normalize-svg, pero SISASS no promete una fusión profunda general.

Mixins y funciones que utilizan mapas anidados

El inventario siguiente incluye únicamente APIs públicas que aceptan un mapa como valor de una de sus claves. Excluye mapas planos y estructuras creadas solo dentro de una implementación.

Tipo API pública Clave anidada API o comportamiento interior Ruta fuente
Mixin replace-base position | p Reutiliza la sintaxis map de position. src/_base.scss
Mixin normalize-svg position | p Configura la posición de replace-base y conserva z: 2 como valor predeterminado. src/_base.scss
Mixin icon-svg position Reutiliza las opciones admitidas por position. src/_base.scss
Mixin icon-svg background Agrupa repeat, position, color y size para construir el fondo. src/_base.scss
Mixin icon-svg-mask position | p Reutiliza la sintaxis map de position; también admite un valor escalar o false. src/_base.scss
Mixin img-replace base Entrega la configuración a replace-base y puede contener otro nivel como base.position. src/_base.scss

img-remplace es un alias de compatibilidad de img-replace, no una API anidada independiente. Actualmente, SISASS no expone funciones públicas cuya configuración requiera mapas anidados. Funciones como bp, pb y mapv reciben o procesan mapas planos.

Ejemplos del proyecto

replace-base y position.z

position es la clave contenedora y z pertenece a su mapa interior. Un z: 2 situado junto a position sería ignorado porque no forma parte del nivel exterior de replace-base. 

.correct {
    @include replace-base((
        position: (
            position: relative,
            z: 2
        )
    ));
}

.incorrect {
    @include replace-base((
        position: (
            position: relative
        ),
        z: 2
    ));
}
/* Fragmento relevante del CSS generado */
.correct {
    position: relative;
    top: 0px;
    left: 0px;
    z-index: 2;
}

.incorrect {
    position: relative;
    top: 0px;
    left: 0px;
}

normalize-svg y sus valores interiores

El wrapper fusiona esta personalización con su configuración interior y conserva position: relative y z-index: 2. 

.icon {
    @include normalize-svg((
        position: (
            top: 4px
        )
    ));
}
/* Fragmento relevante del CSS generado */
.icon {
    position: relative;
    top: 4px;
    z-index: 2;
}

img-replace con dos niveles

base.position identifica el mapa de posición dentro de base, y base.position.z identifica su clave z. 

.logo {
    @include img-replace((
        image: "../img/logo.svg",
        base: (
            position: (
                position: relative,
                z: 3
            )
        )
    ));
}
/* Fragmento relevante del CSS generado */
.logo {
    background-image: url("../img/logo.svg");
    background-repeat: no-repeat;
    background-position: center;
    background-color: transparent;
    background-size: cover;
    position: relative;
    top: 0px;
    left: 0px;
    z-index: 3;
}

icon-svg con mapas hermanos

position y background son mapas hermanos. La ruta position.position configura la propiedad CSS de posicionamiento, mientras background.position configura la posición del fondo, aunque ambas claves interiores se llamen position. 

&::before {
    @include icon-svg((
        svg: "arrow",
        position: (
            p: absolute,
            t: 0,
            l: 0
        ),
        background: (
            repeat: no-repeat,
            position: center,
            size: contain
        )
    ));
}
/* Fragmento relevante del CSS generado */
.arrow::before {
    position: absolute;
    top: 0px;
    left: 0px;
    z-index: 1;
    width: auto;
    height: auto;
    background-image: url("../../img/svg/arrow.svg");
    background-repeat: no-repeat;
    background-position: center;
    background-color: transparent;
    background-size: contain;
}

Recomendaciones y errores frecuentes