update(scss): add initial helpers/mixins/etc.

packages/scss/README.md

@@ -1,6 +1,17 @@
 # @ooee/scss
 SCSS assets for building CSS stylesheets.
 
+## Installation
 ```
 npm install @ooee/scss
 ```
+
+## Consumption
+
+```scss
+// PRODUCTION
+@use '@ooee/scss';
+
+// DEVELOPMENT
+@use '@ooee/scss/dev';
+```

packages/scss/__overrides.scss

@@ -0,0 +1 @@
+// Try to keep this file empty of any styles!

packages/scss/_config.scss

@@ -0,0 +1,6 @@
+// Module Usage:
+//
+// @use '@ooee/scss/config' with ($env: DEV);
+// @use '@ooee/scss';
+
+$env: PROD !default;

packages/scss/components/index.scss

@@ -0,0 +1,2 @@
+/// TBD...
+//@use 'compnent-name';

packages/scss/core/_theme.scss

@@ -0,0 +1 @@
+// TBD...

packages/scss/core/_typography.scss

@@ -0,0 +1 @@
+// TBD...

packages/scss/core/index.scss

@@ -0,0 +1,2 @@
+@use 'theme';
+@use 'typography';

packages/scss/dev.scss

@@ -0,0 +1,2 @@
+@use 'config' with ($env: DEV);
+@use 'index';

packages/scss/helpers/_visually-hidden.scss

@@ -0,0 +1,5 @@
+@use '../utils/a11y' as A11y
+
+.ui--visuallyHidden {
+  @include A11y.visuallyHidden;
+}

packages/scss/helpers/index.scss

@@ -0,0 +1 @@
+@use 'visually-hidden';

packages/scss/index.scss

@@ -0,0 +1,6 @@
+@use 'resets';
+@use 'core';
+@use 'components';
+@use 'helpers';
+@use '_overrides'; // KEEP LAST!
+

packages/scss/resets/_box-sizing.scss

@@ -0,0 +1,13 @@
+// -----------------------------------------------------------------------------
+// BOX-SIZING RESET
+// -----------------------------------------------------------------------------
+// See https://css-tricks.com/inheriting-box-sizing-probably-slightly-better-best-practice/
+html {
+  box-sizing: border-box;
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: inherit;
+}

packages/scss/resets/_document.scss

@@ -0,0 +1,5 @@
+html,
+body {
+  padding: 0;
+  margin: 0;
+}

packages/scss/resets/_inert.scss

@@ -0,0 +1,15 @@
+@use '../utils/user-select' as UserSelect;
+
+// https://github.com/WICG/inert/commit/be4b4a4f4a4c8e37e775c64b9db22b78ccf9d96a
+// https://github.com/WICG/inert/blob/master/src/inert.js#L703
+// https://github.com/WICG/inert/commit/be4b4a4f4a4c8e37e775c64b9db22b78ccf9d96a#diff-04c6e90faac2675aa89e2176d2eec7d8R85
+
+[inert] {
+  cursor: default;
+  pointer-events: none;
+}
+
+[inert],
+[inert] * {
+  @include UserSelect.set(none);
+}

packages/scss/resets/index.scss

@@ -0,0 +1,5 @@
+@use 'box-sizing';
+@use 'document';
+
+/// OPTIONAL
+//@use 'inert';

packages/scss/utils/_a11y.scss

@@ -0,0 +1,34 @@
+// @use '@ooee/scss/utils/a11y';
+// .foo {
+//   @include a11y.visuallyHidden;
+// }
+@mixin visuallyHidden {
+  // remove visible styles around element perimeter
+  border: 0 !important;
+  outline: none !important;
+  box-shadow: none !important;
+
+  // shrink as small as possible without removing
+  // content from the a11y tree
+  width: 1px !important;
+  height: 1px !important;
+  clip: rect(1px, 1px, 1px, 1px); /* old & current Browsers */
+  clip-path: inset(50%); /* browsers in the future */
+
+  // Prevent the screen reader to skip spaces between words
+  white-space: nowrap;
+
+  // eliminate any space being taken up by the element
+  margin: -1px !important;
+  overflow: hidden !important;
+  padding: 0 !important;
+
+  // remove element from normal document flow
+  position: absolute !important;
+  z-index: -99999 !important;
+
+  // render fg and bg invisible
+  color: transparent;
+  background-color: transparent;
+  text-shadow: none;
+}

packages/scss/utils/_env.scss

@@ -0,0 +1,21 @@
+@use "../config";
+
+// Only generate content if in DEV mode
+//
+// @use "@ooee/scss/utils/env";
+// @include env.DEV { ... }
+@mixin DEV {
+  @if config.$env == DEV {
+    @content;
+  }
+}
+
+// Only generate content if in PROD mode.
+//
+// @use "@ooee/scss/utils/env";
+// @include env.PROD { ... }
+@mixin PROD {
+  @if config.$env == PROD {
+    @content;
+  }
+}

packages/scss/utils/_layout.scss

@@ -0,0 +1,17 @@
+// @use "@ooee/scss/utils/layout" as Layout;
+// .foo {
+//   @include Layout.stack(8px);
+// }
+@mixin stack($gap: 0) {
+  display: flex;
+  flex-direction: column;
+
+  > * {
+    margin-top: 0;
+    margin-bottom: 0;
+
+    & + * {
+      margin-top: $gap;
+    }
+  }
+}

packages/scss/utils/_placeholder.scss

@@ -0,0 +1,42 @@
+// Mixin for standard `::placeholder` pseudo-element selector
+//    - https://developer.mozilla.org/en-US/docs/Web/CSS/::placeholder#Browser_compatibility
+//    - https://css-tricks.com/snippets/css/style-placeholder-text/
+//
+// Example:
+//   @use '@ooee/scss/utils/placeholder' as Placeholder;
+//   input {
+//     @include Placeholder.apply { ... }
+//   }
+@mixin apply {
+  // Firefox (< 51)
+  &::-moz-placeholder { @content; }
+
+  // Edge
+  &::-ms-input-placeholder { @content; }
+
+  // Chrome (< 57), Opera (< 44), Safari (< 10.1), Edge
+  &::-webkit-input-placeholder { @content; }
+
+  // standards-compliant selector
+  &::placeholder { @content; }
+}
+
+
+// Mixin for standard `:placeholder-shown` pseudo-class
+//    - https://developer.mozilla.org/en-US/docs/Web/CSS/:placeholder-shown#Browser_compatibility
+//
+// Example:
+//   @use "@ooee/scss/utils/placeholder" as Placeholder;
+//   input {
+//     @include Placeholder.applyWhenShown { ... }
+//   }
+@mixin applyWhenShown {
+  // Firefox (< 51) uses non-standard, prefixed selector
+  &:-moz-placeholder { @content; }
+
+  // IE10+ uses non-standard, prefixed selector
+  &:-ms-input-placeholder { @content; }
+
+  // standards-compliant selector
+  &:placeholder-shown { @content; }
+}

packages/scss/utils/_prefers.scss

@@ -0,0 +1,19 @@
+// @use '@ooee/scss/utils/prefers' as Prefers;
+// @include Prefers.reducedMotion {
+//   // apply reduced animations/transitions/motion here...
+// }
+@mixin reducedMotion {
+  @media (prefers-reduced-motion) {
+    @content;
+  }
+}
+
+// @use '@ooee/scss/utils/prefers' as Prefers;
+// @include Prefers.darkMode {
+//   // apply "dark" styles here...
+// }
+@mixin darkMode {
+  @media (prefers-color-scheme: dark) {
+    @content;
+  }
+}

packages/scss/utils/_pseudo.scss

@@ -0,0 +1,76 @@
+@use 'env';
+
+// @use "@ooee/scss/utils/pseudo" as Pseudo;
+// .foo {
+//   @include Pseudo.hover { ... }
+// }
+//                +------------+
+//                | env.$mode  |
+// +--------------+------------+
+// | selector     | DEV | PROD |
+// +--------------+-----+------+
+// | :hover       | X   | X    |
+// +--------------+-----+------+
+// | .mock-hover  | X   |      |
+// +--------------+-----+------+
+@mixin hover {
+  &:hover {
+    @content;
+  }
+
+  @include env.DEV {
+    &.mock-hover {
+      @content;
+    }
+  }
+}
+
+// @use "@ooee/scss/utils/pseudo" as Pseudo;
+// .foo {
+//   @include Pseudo.focus { ... }
+// }
+//                +------------+
+//                | env.$mode  |
+// +--------------+------------+
+// | selector     | DEV | PROD |
+// +--------------+-----+------+
+// | :focus       | X   | X    |
+// +--------------+-----+------+
+// | .mock-focus  | X   |      |
+// +--------------+-----+------+
+@mixin focus {
+  &:focus {
+    @content;
+  }
+
+  @include env.DEV {
+    &.mock-focus {
+      @content;
+    }
+  }
+}
+
+// @use "@ooee/scss/utils/pseudo" as Pseudo;
+// .foo {
+//   @include Pseudo.active { ... }
+// }
+//                +------------+
+//                | env.$mode  |
+// +--------------+------------+
+// | selector     | DEV | PROD |
+// +--------------+-----+------+
+// | :active      | X   | X    |
+// +--------------+-----+------+
+// | .mock-active | X   |      |
+// +--------------+-----+------+
+@mixin active {
+  &:active {
+    @content;
+  }
+
+  @include env.DEV {
+    &.mock-active {
+      @content;
+    }
+  }
+}

packages/scss/utils/_user-select.scss

@@ -0,0 +1,13 @@
+// See https://developer.mozilla.org/en-US/docs/Web/CSS/user-select#Browser_compatibility
+//
+// Example:
+//   @use '@ooee/scss/utils/user-select' as UserSelect;
+//   .foo {
+//     @include UserSelect.set(none);
+//   }
+@mixin set($value) {
+  -webkit-user-select: $value; // Edge, Opera?, Firefox (49-68), Safari
+     -moz-user-select: $value; // Firefox (<49)
+      -ms-user-select: $value; // Edge, IE
+          user-select: $value; // Chromium (54+) and spec-compliant browsers
+}