Merge pull request #205 from illright/v3

Version 3

.eslintrc.js

@@ -33,6 +33,7 @@ module.exports = {
       'error',
       { vars: 'all', args: 'none', ignoreRestSiblings: true },
     ],
+    'prefer-arrow-callback': 'off',
     'no-constant-condition': 'off',
     'keyword-spacing': 'error',
     'no-console': ['warn', { allow: ['warn', 'error'] }],

.github/workflows/pr_lint_build.yml

@@ -12,7 +12,9 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: actions/setup-node@v1
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '14'
       - name: Install and Build
         run: |
           yarn install
@@ -33,7 +35,9 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: actions/setup-node@v1
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '14'
       - name: Install and Build
         run: |
           yarn install

.prettierignore

@@ -1,3 +1,4 @@
 node_modules
 __sapper__
 dist
+README.md

.prettierrc.json

@@ -1,6 +1,6 @@
 {
   "singleQuote": true,
   "arrowParens": "avoid",
-  "svelteSortOrder": "scripts-markup-styles",
+  "svelteSortOrder": "options-scripts-markup-styles",
   "svelteBracketNewLine": true
 }

CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/) and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [3.0.0] - 2021-01-10
+
+Not a large release, but still breaking. This will upgrade Attractions to use Sass modules which will allow zero-config installations.
+
+Refer to the [migration guide](./docs/migration-guide) for information on how to upgrade.
+
+### Added
+
+- New Sass variables for the X icon in the search fields and the regular font weight.
+- A slight animation for the checkbox component.
+- Autocompletes can now be disabled like regular text fields.
+
+### Changed
+
+- Sass modules are now used for styling. This is a **breaking** change.
+
 ## [2.3.1] - 2020-12-23
 
 ### Fixed
@@ -92,7 +108,8 @@ Minor documentation and bug fixes.
 First stable release with proper documentation.
 Previous, undocumented, releases can be found in [the releases section](https://github.com/illright/attractions/releases).
 
-[unreleased]: https://github.com/illright/attractions/compare/v2.3.1...HEAD
+[unreleased]: https://github.com/illright/attractions/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/illright/attractions/releases/tag/v3.0.0
 [2.3.1]: https://github.com/illright/attractions/releases/tag/v2.3.1
 [2.3.0]: https://github.com/illright/attractions/releases/tag/v2.3.0
 [2.2.4]: https://github.com/illright/attractions/releases/tag/v2.2.4

MAINTAINER_GUIDE.md

@@ -0,0 +1,37 @@
+# Maintainer's Guide
+
+Notes to self and quirks of the project's implementation in case all of the current maintainers get hit by the same bus.
+
+## Why we use Sass
+
+- A lot of the colors are computed with Sass color functions, switching to CSS variables would mean a whole lot more variables.
+- Using Sass variables instead of CSS variables gives us more browser compatibility.
+
+## Why we use Sass so strangely
+
+Specifically talking about how most of the components have the following line:
+
+```scss
+@use 'node_modules/attractions/_variables';
+```
+
+That path doesn't exist for us, library developers, but it does exist for the users who installed this library and are now compiling SCSS. This is done to enable zero-config installation for those users who are not interested in changing Sass variables or using them in their own stylesheets.
+
+So how does it work? Glad you asked.  
+Sass has several stages of resolution when it comes to imports:
+
+> 1. Loading a file relative to the file in which the `@use` or `@import` appeared.
+>
+> 2. Each custom importer.
+>
+> 3. Loading a file relative to the current working directory.
+>
+> 4. Each load path in `includePaths`
+>
+> 5. Each load path specified in the `SASS_PATH` environment variable, which should be semicolon-separated on Windows and colon-separated elsewhere.
+
+The trick is to utilize the steps after the second so that the users who want to configure their installation could intercept the resolution chain at step 2.  
+Particularly, this import uses step 3 (reminding you that the current working directory is the one your terminal is at when running the compilation command, which is probably the same one that holds `rollup.config.js`). Thus, if there are no importers, step 1 fails, step 2 fails, and step 3 resolves.  
+We too can intercept the chain at step 2 when building the library, so it's okay that the path doesn't exist – our building code will not fail.
+
+Sass mixins, on the other hand, never need to be overridden, so it's okay to import them with step 1 (`@use '../_mixins';`).

MIGRATION_GUIDE.md

@@ -0,0 +1,57 @@
+# Migration Guide
+
+Here you may find guidance on upgrading Attractions from one major version to another.
+
+## From v2.x to v3.x
+
+The main change in version 3 is the migration to Sass modules.
+
+If you have existing code that used Sass for styling and was using the old `@import` statements, consider using the automatic [Sass Migrator](https://sass-lang.com/documentation/cli/migrator) tool first.
+
+**Heads up**: if your styles used imports that relied on `includePaths`, you can still make Sass Migrator understand them by setting the `SASS_PATH` environment variable to the path that you previously had in your `includePaths` Sass compiler option.
+
+Once your code is ready for Sass modules, replace Node Sass (`node-sass`) with Dart Sass (`sass`).
+
+Update your `rollup.config.js` to use the new Attractions importers:
+
+```js
+import autoPreprocess from 'svelte-preprocess';
+import makeAttractionsImporter from 'attractions/importer.js';
+
+const preprocessChain = [
+  autoPreprocess({
+    scss: {
+      importer: makeAttractionsImporter({
+        // If you previously had a file that was overriding Attractions variables,
+        //   provide the path to it here.
+        // If it was empty, you may delete it, omit this parameter
+        //   and call the function with no arguments.
+        themeFile: './static/css/_attractions-theme.scss',
+      }),
+
+      includePaths: ['./static/css'],
+    },
+  }),
+];
+```
+
+Lastly, if your `_attractions-theme.scss` had any variable overrides, move them to the module configuration.
+
+Before:
+
+```scss
+@import '_attractions-theme.scss';
+$font: 'Open Sans', sans-serif;
+$main: green;
+$my-custom-variable: 1px;
+```
+
+After:
+
+```scss
+@forward "~attractions/_variables" with (
+  $font: ('Open Sans', sans-serif),
+  $main: green;
+);
+$my-custom-variable: 1px;
+```

README.md

@@ -13,28 +13,54 @@ Refer to the main documentation: <https://illright.github.io/attractions>
 
 ## Installation
 
-**Step 1.** Install the library with npm or Yarn:
+**Step 1.** Install the library with your favorite package manager:
 
 ```bash
 npm install --save-dev attractions
 # -- or --
 yarn add -D attractions
+# -- or --
+pnpm add --save-dev attractions
 ```
 
-**Step 2.** Add [`svelte-preprocess`](https://github.com/sveltejs/svelte-preprocess/blob/master/docs/usage.md) to your preprocessor chain for compiling SCSS.
+**Step 2.** Install `svelte-preprocess`, Dart Sass and PostCSS:
+
+```bash
+npm install --save-dev svelte-preprocess sass postcss
+# -- or --
+yarn add --dev svelte-preprocess sass postcss
+# -- or --
+pnpm add --save-dev svelte-preprocess sass postcss
+```
 
-**Step 3.** Create a file named `_attractions-theme.scss` (can be empty) anywhere in the project and add the path to the directory containing file to `includePaths` for SCSS:
+**Step 3.** Add `svelte-preprocess` to your preprocessor chain ([as shown here](https://github.com/sveltejs/svelte-preprocess/blob/main/docs/usage.md)):
 
 ```js
-import autoPreprocess from 'svelte-preprocess';
+// rollup.config.js
+import sveltePreprocess from 'svelte-preprocess';
+
+export default {
+  // ...,
+  plugins: [
+    svelte({
+      preprocess: sveltePreprocess(),
+    }),
+  ],
+};
+```
+
+**Step 4.** Import the desired components as named imports and use wherever you like!
 
-autoPreprocess({
-  scss: {
-    includePaths: ['./path/to/theme'],
-  },
-});
+```svelte
+<script>
+  import { Button } from 'attractions';
+</script>
+
+<Button>click me</Button>
 ```
 
+For more information on how to customize/theme your installation, see [the docs](https://illright.github.io/attractions/docs/theming).
+
 ---
 
 Alternatively, the library can be used from a CDN, such as [unpkg](https://unpkg.com/attractions), and then the components will be registered as custom elements. This is especially useful for quick prototypes that do not need all the features provided.
@@ -52,17 +78,6 @@ Example usage:
 
 For more details, check out [the docs](https://illright.github.io/attractions/docs/custom-elements).
 
-## Theming
-
-You may configure style parameters such as colors, fonts and shadows by overriding respective variables in your `_attractions-theme.scss` file:
-
-```scss
-$main: #b17200;
-$font: 'Noto Sans', sans-serif;
-```
-
-Refer to the documentation for each component for the variables available for overriding.
-
 ## License
 
 This project is [MIT licensed](./LICENSE).

attractions/_appearances.scss

@@ -0,0 +1,55 @@
+@use 'sass:color';
+@use 'node_modules/attractions/_variables' as vars;
+
+@mixin text-field {
+  padding: 0 0.625em 0.0625em;
+  box-sizing: border-box;
+  width: 100%;
+  border: 0 solid vars.$textfield-border; // to disable the global border
+  border-bottom-width: 0.0625em;
+  border-top-left-radius: 0.375em;
+  border-top-right-radius: 0.375em;
+  background-color: vars.$textfield-bg;
+
+  &:hover {
+    background-color: color.scale(vars.$textfield-bg, $lightness: -3%);
+  }
+}
+
+@mixin text-field-focused {
+  background-color: color.scale(vars.$textfield-bg, $lightness: -8%);
+  border-bottom-width: 0.125em;
+  border-color: color.scale(vars.$main, $lightness: 4%);
+  padding-bottom: 0;
+}
+
+@mixin text-field-disabled {
+  background-color: color.scale(vars.$textfield-bg, $lightness: 15%);
+  border-color: color.adjust(vars.$dark, $alpha: -0.7);
+  color: vars.$disabled;
+
+  &:hover {
+    background-color: color.scale(vars.$textfield-bg, $lightness: 15%);
+  }
+}
+
+@mixin text-field-input {
+  outline: none;
+  font-family: vars.$font;
+  font-size: 1rem;
+  font-weight: vars.$thin-font-weight;
+  height: 2.8em;
+}
+
+@mixin button {
+  font-family: vars.$font;
+  font-weight: vars.$bold-font-weight;
+  outline: none;
+  display: flex;
+  align-items: center;
+  cursor: pointer;
+
+  &::-moz-focus-inner {
+    border: 0;
+  }
+}

attractions/_mixins.scss

@@ -1,3 +1,6 @@
+@use 'sass:color';
+@use 'node_modules/attractions/_variables' as vars;
+
 @mixin hide-accessible {
   clip: rect(0, 0, 0, 0);
   width: 1px;
@@ -15,3 +18,29 @@
   overflow: visible;
   position: static;
 }
+
+@mixin show-on-focus {
+  @include hide-accessible;
+
+  &:focus {
+    @include show-accessible;
+  }
+}
+
+@mixin slim-scrollbar {
+  &::-webkit-scrollbar {
+    width: 0.3125em;
+    height: 0.5em;
+    background: none;
+    margin: 1em 0;
+  }
+
+  &::-webkit-scrollbar-thumb {
+    background: vars.$light-contrast;
+    border-radius: 0.3125em;
+
+    &:hover {
+      background: color.scale(vars.$light-contrast, $lightness: -10%);
+    }
+  }
+}