Merge pull request #5 from MatteuSan/dev/v1

1.0.0

.github/workflows/sentro.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [ 16.x, 18.x ]
+        node-version: [ 20.x, 21.x ]
     steps:
       - uses: actions/checkout@v3
       - name: Use NodeJS version ${{ matrix.node-version }}

README.md

@@ -1,29 +1,20 @@
 # Sentro
-![lang](https://img.shields.io/badge/lang-SCSS-%23c69)
-[![version_badge](https://img.shields.io/npm/v/@matteusan/sentro)](https://www.npmjs.com/package/@matteusan/sentro)
-![license_badge](https://img.shields.io/npm/l/@matteusan/sentro)
-![stars](https://img.shields.io/github/stars/MatteuSan/sentro?style=social)
-
 A low-level SCSS library for building and managing token-driven design systems.
 
 ## Installation
 ```sh
 # NPM
 npm install @matteusan/sentro --save
-
-# Yarn
-yarn add @matteusan/sentro --save
 ```
 
 ## Documentation
 - The documentation for this project is located [here](https://docs.matteusan.me/docs/sentro).
 
 ## Showcase
 #### SCSS Input
-- Tokenize your UI while creating an intuitive theming API for your design system.
 ```scss
-@use 'path/to/@matteusan/sentro' with (
-  $prefix: 'sdb',
+@use '@matteusan/sentro' with (
+  $prefix: 'sdc',
   $context: 'theme'
 );
 
@@ -56,8 +47,8 @@ yarn add @matteusan/sentro --save
   border-radius: sentro.key-create('button-radius', sentro.token-get('radius-small'));
 }
 ```
+
 #### CSS Output
-- Voila!
 ```css
 :root {
   --sdb-theme-primary: #122c53;

docs/api/breakpoints.md

@@ -0,0 +1,126 @@
+---
+title: Breakpoint Module API
+slug: /api/breakpoints
+---
+
+# Breakpoint API
+
+## `breakpoint-config()` mixin
+
+Adds breakpoints to the design system.
+
+There are two parameters to this mixin. The first one is to insert a pre-made breakpoint map. It could be from the design
+team, or from the project's UX lead. Then the second one is for adding your own breakpoints.
+
+Both parameters can be used simultaneously, or if you don't want that you can always use one or the other.
+
+### Syntax
+
+```scss
+/// @param {map} $token-map
+/// @param {args} $breakpoints...
+breakpoint-config($map: (), $breakpoints...) {}
+```
+
+### Usage
+
+```scss
+@use 'node_modules/@matteusan/sentro' with ($prefix: 'sdc', $context: 'theme');
+
+:root {
+  @include sentro.token-config(
+    $small: 320px,
+    $medium: 677px,
+    $large: 890px,
+    $xlarge: 1077px
+  );
+}
+
+...
+```
+
+## `breakpoint-check()` function
+
+Checks if a breakpoint is a valid breakpoint or not. Must be used within a valid SCSS conditional statement.
+
+**NOTE: It does not throw and error when the value is asserted as false, you need to make the error yourself.**
+
+### Syntax
+
+```scss
+/// @param {*} query
+breakpoint-check($query) {}
+```
+
+### Usage
+
+```scss
+@use 'node_modules/@matteusan/sentro' with ($prefix: 'sdc', $context: 'theme');
+
+@function tell-me-if-its-a-breakpoint($breakpoint) {
+  @if sentro.breakpoint-check($breakpoint) {
+    @return 'IT IS A BREAKPOINT!';
+  } @else {
+    @return 'Oh, that\'s disappointing...';
+  }
+}
+
+...
+```
+
+## `breakpoint-create()` mixin
+
+Creates a breakpoint. Must be used within a valid CSS selector.
+
+### Syntax
+
+```scss
+/// @param {string} $key
+/// @param {*} $value
+breakpoint-create($key, $value) {}
+```
+
+### Usage
+
+```scss
+@use 'node_modules/@matteusan/sentro' with ($prefix: 'sdc', $context: 'theme');
+
+dialog {
+  // CSS Styles
+
+  @include sentro.breakpoint-create('medium') {
+    // CSS Styles
+  }
+}
+
+...
+```
+
+## `breakpoint-get()` function
+
+Queries and retrieves a breakpoint. Must be used as a property value, css-function value, or key-fallback value.
+
+Allows you to query your own breakpoint and pass it off inside a property to be used.
+
+### Syntax
+
+```scss
+/// @param {string} $key
+token-get($key) {}
+```
+
+### Usage
+
+```scss
+@use 'node_modules/@matteusan/sentro' with ($prefix: 'sdc', $context: 'theme');
+
+dialog {
+  // CSS Styles
+
+  @media (min-width: sentro.breakpoint-get('medium')) {
+    // CSS Styles
+  }
+}
+
+...
+```

docs/api/keys.md

@@ -0,0 +1,132 @@
+---
+title: Keys Module API
+slug: /api/keys
+---
+
+# Keys API
+
+## `key-bind()` mixin
+
+Binds a new value to an existing key. Must be used within a valid CSS selector.
+
+### Syntax
+
+```scss
+/// @param {string} $key
+/// @param {*} $value
+key-bind($key, $value) {}
+```
+
+### Usage
+
+```scss
+@use 'node_modules/@matteusan/sentro' with ($prefix: 'sdc', $context: 'theme');
+
+.sdc-card {
+  @include sentro.key-bind('card-bg', sentro.token-switch('surface-light'));
+}
+
+...
+```
+
+## `key-create()` function
+
+Creates a key with a fallback value for a CSS property. Must be used as a property value, css-function value, or
+key-fallback value.
+
+### Syntax
+
+```scss
+/// @param {string} $key
+/// @param {*} $value
+key-create($key, $value) {}
+```
+
+### Usage
+
+```scss
+@use 'node_modules/@matteusan/sentro' with ($prefix: 'sdc', $context: 'theme');
+
+.sdc-card {
+  background: sentro.key-create('card-bg', sentro.token-switch('surface-light'));
+}
+
+...
+```
+
+## `key-check()` function
+
+Checks if a token is a valid key or not. Must be used within a valid SCSS conditional statement.
+
+**NOTE: It does not throw and error when the value is asserted as false, you need to make the error yourself.**
+
+### Syntax
+
+```scss
+/// @param {*} $query
+key-check($query) {}
+```
+
+### Usage
+
+```scss
+@use 'node_modules/@matteusan/sentro' with ($prefix: 'sdc', $context: 'theme');
+
+@function tell-me-if-its-a-key($key) {
+  @if sentro.key-check($key) {
+    @return 'IT IS A KEY!';
+  } @else {
+    @return 'Oh, that\'s disappointing...';
+  }
+}
+
+...
+```
+
+## `key-get()` function
+
+Queries and retrieves a key in its CSS custom property form. Must be used as a property value, css-function value, or
+key-fallback value.
+
+### Syntax
+
+```scss
+/// @param {string} $key
+key-get($key) {}
+```
+
+### Usage
+
+```scss
+@use 'node_modules/@matteusan/sentro' with ($prefix: 'sdc', $context: 'theme');
+
+.sdc-card {
+  background: sentro.key-get('card-bg');
+}
+
+...
+```
+
+## `key-get-raw()` function
+
+Queries and retrieves a key in its raw value form. Must be used as a property value, css-function value, or key-fallback
+value.
+
+### Syntax
+
+```scss
+/// @param {string} $key
+key-get-raw($key) {}
+```
+
+### Usage
+
+```scss
+@use 'node_modules/@matteusan/sentro' with ($prefix: 'sdc', $context: 'theme');
+
+.sdc-card {
+  background: sentro.key-get-raw('card-bg');
+}
+
+...
+```