Sass Mixins

The state that a switch layout keeps track of is a string. All possible switch states must be specified at compile time in order to build the css.

@use 'pkg:@strawburster/switch' as *;

.auth {
    @include switch(auth, 'login', 'register', 'reset-password');
}

In this example, the name of the switch is auth and the state can be either login, register, or reset-password.

It's important that the switch mixin is wrapped in a css selector, like above, because it makes use of the parent selector &.

The sass mixin must work in tandem with the React hook useSwitch. That means it must have the same name and possible states.

import React from 'react';
import useSwitch from '@strawburster/switch';

export defaultFunction Auth() {
  const [authSwitch, setAuth] = useSwitch(
    { name: 'auth' },
    'login',
    'register',
    'reset-password',
  );
}

The useSwitch hook returns a switch and a function to set its current state. The switch object should be spread over the top-level element in the switch layout.

<div {...authSwitch} id="auth"></div>

The function returned by useSwitch can be used to change the state of the switch layout in an onclick handler:

<button onClick={setAuth('reset-password')}>Reset Password</button>

The function accepts a new state string and returns a function which changes the state to the new state. If using typescript, the function will only accept valid states specified with useSwitch.

Both the switch object and state-changing function can be renamed to any valid javascript identifier.

The main use case for a switch layout is hiding and showing elements based on the current state. Without custom styling in the switch mixin, the default behavior is to add the display: none; pointer-events: none; properties to elements when they don't match the current state.

Setting up the template for elements to match the current state can be done in four ways: direct, exclusion, partial, and partial exclusion. The template uses the attribute data-[name] where [name] is the name of the switch layout. So for the above example, with a name of order, the mixin will look for data-order attributes in the template in order to check whether to display or hide each element.

Although the default behavior is to add the display: none; pointer-events: none; properties to any element who's template does not match the current state, that can be overriden in order to provide transitions or animations when the state changes. This can be done by passing in styles to the switch mixin:

.demo {
  [data-demo] {
    transition: opacity 1s;
  }

  @include switch(demo, 'state-a', 'state-b') {
    /**
     * These styles are applied when the current state *does not*
     * match an element's data-demo attribute.
     **/
    opacity: 0;
  }
}

In this example, an opacity transition is applied to all elements which have a data-demo attribute and, when an element's data-demo attribute does not match the current state, it will have an opacity of 0.

You can also specify animations to use by specifying a 'default' animation for all elements, then specifying a 'hiding' animation with the switch mixin.

.demo {
  [data-demo] {
    animation: _fade-in 1s;
  }

  @include switch(demo, 'state-a', 'state-b') {
    animation: _fade-out 1s forwards;
  }
}

@keyframes _fade-in {
  from {
    opacity: 0;
  }
  to {
    opacity: 1;
  }
}

@keyframes _fade-out {
  to {
    opacity: 0;
  }
}

As opposed to the switch layout, the router can specify possible states for both the JS api and the sass mixin simoultaneously. It does this using a JSON object or a serializable JS object.

The router object has three properties: baseUrl, fallback, and pages.

{
  "baseUrl": "/my-site",
  "fallback": "/404",
  "pages": [
    "/",
    "/page-1",
    "/page-2"
  ]
}

The baseUrl can tell the javascript api how to change the url bar when the route changes. If the site is hosted at domain.com/my-site, the /my-site should be used as the baseUrl. This defaults to / if ommitted.

A fallback page can be specified which tells the router to display a certain page if the one requested does not exist. This page may or may not exist in the pages array.

pages is a list of either strings or Page objects. Usually, you'll want to specify at least a home page /. Page objects have a path property and either a redirectTo or children property.

"pages": [
  "/",
  {
    path: "/page-1",
    children: {
      "/child-page-1",
      "/child-page-2"
    }
  },
  {
    path: "/page-2",
    redirectTo: "/page-1/child-page-2"
  }
]

This object must be imported into sass and passed as an argument to the router mixin. One way to do that is with webpack and @strawburster/sass-json-loader (which I wrote) which uses json2scss-map (which was written by AS Devs) to automatically recognize .json and .js imports within sass files:

// webpack.config.js

module.exports = {
  ...
  module: {
    rules: [
      {
        test: /\.s?[ac]ss$/i,
        use: [
          'style-loader',
          'css-loader',
          'sass-loader',
          '@strawburster/sass-json-laoder',
        ],
      },
    ],
  },
};

Now, @use 'router.json' will use the json2scss-map package to create a sass map variable named $router.

@use 'pkg:@strawburster/router' as *;
@use 'router.json';

.router {
  @include router($router);
}

The sass mixin takes a router config object and, by default, applies display: none; pointer-events: none; to elements in the template which do not match the current route.

If not using webpack, the router can be specified as a sass map so long as it matches with the object used in the javascript api.

import React from 'react';
import useRouter from '@strawburster/router';
import routerConfig from './router.json';

export default function App() {
  const [router, goto, currentRoute] = useRouter(routerConfig);
  return (
    <div className="router" {...router}></div>
  )
}

The useRouter react hook takes a router object and returns a router, a route-changing function, and the current route as a string.

The router object should be spread over the top-level element in the router in order to give css access to the current route stored in javascript, like above. The same top-level element should be selectable in the sass, so I will add a className attribute as well.

The route-changing function returned by useRouter can be used to change the current route in an onclick handler:

<button onClick={goto('/new-page')}>Go to new page</button>

All items returned by the useRouter hook can renamed to any valid javascript identifier.

The template syntax for elements closely resembles the syntax for the switch layout. Each element can be hidden or shown using the absolute, exclusionary, relative, relative exclusionary, partial, partial exclusionary, partial relative, or partial relative exclusionary syntax.

The default behavior is to add the styles display: none; pointer-events: none; to elements who's data-route attribute does not match the current route. That can be overridden in order to provide route transitions by passing styles to the router mixin:

.router {
  [data-route] {
    /**
     * These styles are applied all the time regardless of the
     * current route.
     **/
    transition: width 1s;
    overflow: hidden;
    white-space: nowrap;
    width: 50px;
  }

  @include router($router) {
    /**
     * These styles are applied when the current route *DOES NOT*
     * match the data-route attribute.
     **/
    width: 0;
  }
}

In this example, a width transition is applied to all elements which have a data-route attribute, and, when an element's data-route attribute does not match the current route, it will have a width of 0.

You can also specify animations to use by specifying a 'default' animation for all data-route elements, then specifying a 'hiding' animation within the router minix.

.router {
  [data-route] {
    animation: _expand 1s;
    overflow: hidden;
    white-space: nowrap;
  }

  @include router($router) {
    animation: _shrink 1s forwards;
  }
}

@keyframes _expand {
  from {
    width: 0;
  }
  to {
    width: 50px;
  }
}

@keyframes _shrink {
  to {
    width: 0;
  }
}