@zzzzbov/stacking-context

    0.0.0-alpha.0 • Public • Published

    Stacking Context Sass Module

    The Stacking Context module manages z-indexes across a website or webapp so that the stacking order is unambiguous and easy to understand at a glance.

    Most apps don't need z-index values greater than 10, so if your app has values like 999 or 10000, then this module can probably help.

    Table of Contents

    API

    Mixin stacking-context($indexes...)

    A mixin to create a new stacking context. When used without parameters the mixin is equivalent to isolation: isolate.

    Parameter $indexes

    A list of indexes to assign to $stacking-contexts. The key will be the current selector (&). selector.parse can be used to recreate the key if necessary.

    Function z($index, $context, $direction)

    Meta Details
    returns number or null

    A function to look up the numeric value from the named $index in the specified $context.

    Parameter $index

    Meta Details
    type any map key

    The named index to look up in the specified stacking context.

    Parameter $context

    Meta Details
    default default
    type any map key or list

    The key of the stacking context to use from the module's configured $stacking-contexts, or a list to use as the stacking context.

    Parameter $direction

    Meta Details
    default $direction from the module configuration.
    type ascending or descending

    The direction items are stacked in the specified stacking context.

    See $direction in module configuration for details.

    Module Configuration

    The Stacking Context module exposes the following variables for configuration.

    $direction

    Meta Details
    default ascending
    type ascending or descending

    The default direction items are stacked in the module.

    When ascending is specified, items earlier in the list will be covered by items later in the list. I.E. for (a, b, c): a is covered by b which is covered by c.

    When descending is specified, items earlier in the list will cover items later in the list. I.E. for (a, b, c): a covers b which covers c.

    $stacking-contexts

    Meta Details
    default empty map
    type map with keys of any type and values of lists

    The default stacking contexts to use globally. Any keys may be used. default is used as the default $context in the z function.

    Examples

    Example 1: Using the default stacking context globally

    @use 'path/to/stacking-context' as sc with (
      // Stacking contexts can be globally configured for the module
      $stacking-contexts: (
        default: (
          nav,
          header,
          modal
        )
      )
    );
    
    nav {
      // The default stacking context is used if no value for `$context` is specified
      z-index: sc.z(nav); // 1
    }
    header {
      // By default items farther down the list have a higher z-index
      z-index: sc.z(header); // 2
    }
    .modal {
      z-index: sc.z(modal); // 3
    }

    Example 2: Using a non-default stacking context globally

    @use 'path/to/stacking-context' as sc with (
      $stacking-contexts: (
        default: (
          nav,
          header,
          modal,
        ),
        modal: (
          body,
          footer,
          header,
        )
      )
    );
    
    header {
      // reads the `header` index from the `default` context
      z-index: sc.z(header); // 2
    }
    
    .modal {
      // @include stacking-context is the same as `isolation: isolate` when no
      // parameters are provided.
      isolation: isolate;
      // reads the `modal` index from the `default` context
      z-index: sc.z(modal); // 3
    
      &__header {
        // reads the `header` index from the `modal` context
        z-index: sc.z(header, modal); // 3
      }
      &__body {
        z-index: sc.z(body, modal); // 1
      }
      &__footer {
        z-index: sc.z(footer, modal); // 2
      }
    }

    Example 3: Using a specific stacking context list

    @use 'path/to/stacking-context' as sc;
    
    $indexes: (popup, menu, modal);
    
    .popup {
      z-index: sc.z(popup, $indexes); // 1
    }
    .menu {
      z-index: sc.z(menu, $indexes); // 2
    }
    .modal {
      z-index: sc.z(modal, $indexes); // 3
    }

    Example 4: Updating the default $direction

    @use 'path/to/stacking-context' as sc with (
      $direction: descending,
      $stacking-contexts: (
        default: (
          modal,
          header,
          nav
        )
      )
    );
    
    nav {
      // when `$direction: descending` is specified, items at the top of the list
      // stack on top of items at the bottom of the list
      z-index: sc.z(nav); // 1
    }
    header {
      z-index: sc.z(header); // 2
    }
    .modal {
      z-index: sc.z(modal); // 3
    }

    Example 5: Using a non-default $direction

    @use 'path/to/stacking-context' as sc with (
      $stacking-contexts: (
        default: (
          modal,
          header,
          nav
        )
      )
    );
    
    nav {
      z-index: z(nav, $direction: descending); // 1
    }
    
    header {
      z-index: z(header, $direction: descending); // 2;
    }
    
    .modal {
      z-index: z(modal, $direction: descending); // 3;
    }

    Example 6: Using the stacking-context mixin to create scoped stacking contexts

    @use 'path/to/stacking-context' as sc;
    
    .button-group {
      // keep track of the current selector context
      $ctx: &;
      @include sc.stacking-context(default, focused); // isolation: isolate;
      --border: 0.25em;
      border: var(--border) solid transparent;
      display: inline-flex;
      flex-direction: row;
    
      button {
        appearance: none;
        background-color: transparent;
        border: var(--border) solid #888;
        margin: calc(var(--border) * -1);
        padding: 0.25em 0.5em;
        // use the parent selector context to look up the default z-index
        z-index: sc.z(default, $ctx); // 1
    
        &:not(:first-child) {
          margin-left: 0;
        }
    
        &:hover,
        &:focus {
          background-color: rgba(0, 0, 0, 0.2);
          border-color: #000;
          outline: 1px solid transparent;
          // use the parent selector context to look up the focused z-index
          // this allows the current button to show on top of its neighbors in
          // the button group
          z-index: sc.z(focused, $ctx); // 2
        }
      }
    }

    Example 7: Using selector.parse to access another stacking context created by the stacking-context mixin

    @use 'path/to/stacking-context' as sc;
    @use 'sass:selector';
    
    .modal {
      @include sc.stacking-context(body, footer, header); // isolation: isolate;
    }
    .modal-header {
      z-index: sc.z(header, selector.parse(".modal")); // 3
    }
    .modal-body {
      z-index: sc.z(body, selector.parse(".modal")); // 1
    }
    .modal-footer {
      z-index: sc.z(footer, selector.parse(".modal")); // 2
    }

    Install

    npm i @zzzzbov/stacking-context

    DownloadsWeekly Downloads

    2

    Version

    0.0.0-alpha.0

    License

    MIT

    Unpacked Size

    12.1 kB

    Total Files

    6

    Last publish

    Collaborators

    • zzzzbov