@natachah/vanilla-frontend 0.4.0 → 1.0.0

package/docs/javascript/tree.md

@@ -0,0 +1,220 @@
+<script setup>
+import ComponentPreview from '../vuejs/ComponentPreview.vue'
+</script>
+
+# Tree <Badge type="warning" text="JS" />
+
+```js
+import Tree from "@natachah/vanilla-frontend/js/_tree"
+```
+
+::: warning
+The `role=tree` and `role=treeGrid` are not accessible !
+:::
+
+## Syntax
+
+The tree component make you able to make a tree view by adding the `role="tree"` attribute on a `<ul>` or `<ol>` tag.
+
+The `<li>` must have a `role="treeitem"`, and if nested the `aria-expanded` and `aria-owns` attributes.
+
+<ComponentPreview height="200px">
+<ul class="demo-tree">
+    <li>1: Lorem, ipsum</li>
+    <li>
+        <button role="link" aria-controls="treelist" aria-expanded="false">
+            1: Inventore, perspiciatis (Open)
+        </button>
+        <ul id="treelist" tabindex="0" hidden>
+            <li>2: Lorem</li>
+            <li>
+                <button role="link" aria-controls="subtreelist" aria-expanded="false">
+                    2: Adipisci (Open)
+                </button>
+                <ul id="subtreelist" tabindex="0" hidden>
+                    <li>3: Lorem</li>
+                    <li>3: Adipisci</li>
+                    <li>3: Facilis</li>
+                </ul>
+            </li>
+            <li>1: Facilis</li>
+        </ul>
+    </li>
+    <li>1: Dolor, quis</li>
+</ul>
+</ComponentPreview>
+
+::: code-group
+
+```html
+<ul class="demo-tree">
+    <li>1: Lorem, ipsum</li>
+    <li>
+        <button role="link" aria-controls="treelist" aria-expanded="false">
+            1: Inventore, perspiciatis (Open)
+        </button>
+        <ul id="treelist" tabindex="0" hidden>
+            <li>2: Lorem</li>
+            <li>
+                <button role="link" aria-controls="subtreelist" aria-expanded="false">
+                    2: Adipisci (Open)
+                </button>
+                <ul id="subtreelist" tabindex="0" hidden>
+                    <li>3: Lorem</li>
+                    <li>3: Adipisci</li>
+                    <li>3: Facilis</li>
+                </ul>
+            </li>
+            <li>1: Facilis</li>
+        </ul>
+    </li>
+    <li>1: Dolor, quis</li>
+</ul>
+```
+
+```js
+import Tree from "@natachah/vanilla-frontend/js/_tree"
+const trees = document.querySelectorAll('.demo-tree')
+if (trees) trees.forEach(tree => new Tree(tree))
+```
+
+:::
+
+::: warning 
+Into a `<li>` you must add a `<button>` to toggle the children, otherwise it will toggle if you click on any child.
+:::
+
+## Options
+
+### Table
+
+This can also be implemented on a `<table>` but it required the `role="treegrid"` attribute.
+
+<ComponentPreview height="200px">
+<table id="treeGrid" class="demo-tree" role="treegrid">
+    <tbody>
+        <tr aria-level="1">
+            <td>1: Lorem, ipsum</td>
+        </tr>
+        <tr aria-level="1" aria-expanded="false" aria-controls="row1 row2 row3">
+            <td>1: Cum, dolorum (open me)</td>
+        </tr>
+        <tr id="row1" aria-level="2" tabindex="0" hidden>
+            <td>2: Lorem</td>
+        </tr>
+        <tr id="row2" aria-level="2" aria-expanded="false" aria-controls="row2-1 row2-2" hidden>
+            <td>2: Quo (open me)</td>
+        </tr>
+        <tr id="row2-1" aria-level="3" tabindex="0" hidden>
+            <td>2.1: Quo</td>
+        </tr>
+        <tr id="row2-2" aria-level="3" hidden>
+            <td>2.2: Quo</td>
+        </tr>
+        <tr id="row3" aria-level="2" hidden>
+            <td>2: Odio</td>
+        </tr>
+        <tr aria-level="1">
+            <td>1: Perspiciatis, tenetur</td>
+        </tr>
+    </tbody>
+</table>
+</ComponentPreview>
+
+```html
+<table id="treeGrid" class="demo-tree" role="treegrid">
+    <tbody>
+        <tr aria-level="1">
+            <td>1: Lorem, ipsum</td>
+        </tr>
+        <tr aria-level="1" aria-expanded="false" aria-controls="row1 row2 row3">
+            <td>1: Cum, dolorum (open me)</td>
+        </tr>
+        <tr id="row1" aria-level="2" tabindex="0" hidden>
+            <td>2: Lorem</td>
+        </tr>
+        <tr id="row2" aria-level="2" aria-expanded="false" aria-controls="row2-1 row2-2" hidden>
+            <td>2: Quo (open me)</td>
+        </tr>
+        <tr id="row2-1" aria-level="3" tabindex="0" hidden>
+            <td>2.1: Quo</td>
+        </tr>
+        <tr id="row2-2" aria-level="3" hidden>
+            <td>2.2: Quo</td>
+        </tr>
+        <tr id="row3" aria-level="2" hidden>
+            <td>2: Odio</td>
+        </tr>
+        <tr aria-level="1">
+            <td>1: Perspiciatis, tenetur</td>
+        </tr>
+    </tbody>
+</table>
+```
+
+### Handles
+
+You can decide which part of the item toggle the open/close method with the `data-handle="tree"` attribute
+
+<ComponentPreview height="200px">
+<table class="demo-tree">
+    <tbody>
+        <tr aria-level="1" aria-expanded="false" aria-controls="rowExpandable">
+            <td>
+                <span data-handle="tree">
+                    (open me)
+                </span>
+            </td>
+            <td>1: Cum, dolorum</td>
+        </tr>
+        <tr id="rowExpandable" aria-level="2" tabindex="0" hidden>
+            <td></td>
+            <td>1.1: Lorem</td>
+        </tr>
+    </tbody>
+</table>
+</ComponentPreview>
+
+
+```html
+<table class="demo-tree">
+    <tbody>
+        <tr aria-level="1" aria-expanded="false" aria-controls="rowExpandable">
+            <td>
+                <span data-handle="tree">
+                    (open me)
+                </span>
+            </td>
+            <td>1: Cum, dolorum</td>
+        </tr>
+        <tr id="rowExpandable" aria-level="2" tabindex="0" hidden>
+            <td></td>
+            <td>1.1: Lorem</td>
+        </tr>
+    </tbody>
+</table>
+```
+
+If there is an `<svg>` as handle, the default style will provide an animation.
+
+
+## Javascript
+
+| Method | Description |
+| --- | --- |
+| resetEvents() | This method will reset the items and events |
+
+### Events
+
+| Event name | Description | Value |
+|---|---|---|
+| tree:changed | This event is fired when an item is toggled | isOpen as a boolean |
+
+```js
+const myTree = document.getElementById('myTree')
+
+myTree.addEventListener('tree:changed', (e) => {
+    const isOpen = e.detail.isOpen
+    ...
+})
+```

package/docs/prologue/conventions.md

@@ -0,0 +1,92 @@
+# Naming conventions
+
+Because all project should have some little rules...
+
+## Almost classless
+
+The framework try to be classless as much as possible, this are the exeptions:
+
+- .accordion
+- .badge
+- .breadcrumb
+- .card
+- .container
+- .container-full
+- .drawer
+- .drawer-button
+- .dropdown
+- .grid
+- .flex-grid
+- .slider
+- .subgrid
+- .group
+- .list
+
+And for variations:
+
+- .outline
+- .COLORNAME (e.g.: .primary)
+
+::: warning
+For good practice avoid as much it's possible classes !
+:::
+
+## HTML, CSS and SCSS
+
+- The custom properties and variable must be kebab-case
+- Private properties start with an underscore
+- The classes must be kebab-case
+- The IDs must be camelCase
+- Use comment like in [SassDoc](http://sassdoc.com/)
+
+```scss
+:root {
+    --global-property: red;
+}
+
+.my-class {
+    background-color: var(--global-property)
+}
+
+#myId {
+    --_private-property: green;
+    background-color: var(--_private-property);
+}
+
+/// Description of the mixin
+///
+/// @example something(red) // color: red
+/// @link http://sassdoc.com/annotations/
+/// @require {mixin} something
+/// @param {name} $name - The description
+/// @access public
+///
+@mixin something($name){
+    color: $name
+}
+```
+
+::: warning
+Limit the number of **custom properties defined**, using too many of them can impact performance. Avoid unnecessary complexity.
+:::
+
+## Javascript
+
+- The variable and method name must be camelCase
+- Use comment like in [JSDoc](https://jsdoc.app/)
+- Use single quote
+- Avoid semicolon
+
+```js
+/**
+* Explaination of the method
+*
+* @param {number} length - The length of the rectangle
+* @param {number} width - The width of the rectangle
+* @returns {number} - The area of the rectangle
+*/
+function calculate(length, width) {
+    const myVariable = 'nothing'
+    return length * height
+}
+```

package/docs/prologue/release.md

@@ -0,0 +1,44 @@
+# Release note
+
+## Versioning Scheme
+
+The package use a three-part numbering system (e.g., 1.2.3) to track updates. This helps the developers to understand the scope of changes at a glance.
+
+### The "Patch" Release (0.0.X)
+
+The third digit is reserved for small fixes.
+
+- **Purpose:** Bug fixes, security patches, or minor text corrections.
+- **Impact:** These updates do not change how the site functions and are safe to deploy immediately.
+- **Example:** Moving from 1.0.1 to 1.0.2.
+
+### The "Minor" Release (0.X.0)
+
+The second digit represents medium-sized updates.
+
+- **Purpose:** Adding new features or making significant modifications to existing ones.
+- **Impact:** These introduce new functionality but remain backward-compatible (they should not "break" the existing setup !).
+- **Example:** Moving from 1.1.0 to 1.2.0.
+
+### The "Major" Release (X.0.0)
+
+The first digit indicates major structural changes.
+
+- **Purpose:** Complete redesigns, total code refactoring, or breaking changes that alter how the system works fundamentally.
+- **Impact:** These are significant milestones and often require thorough testing before deployment.
+- **Example:** Moving from 1.0.0 to 2.0.0.
+
+## GIT branches
+
+The package supports the current version and one previous version. Here the branches naming convention:
+
+- **main:** Is the latest version DEV branch
+- **production:** Is the latest version PROD branch
+- **support/vx.x.x :** Is the legacy version PROD branches per MAJOR+MINOR release
+- **hotfix/vx.x.x :** Is the legacy version DEV branches for PATCH release only
+
+## Support Policy
+
+The current version of the package is construct with SCSS and vanilla JS !
+
+Make sure you can use some of the new HTML/CSS/JS into the browser !

package/docs/prologue/upgrade.md

@@ -0,0 +1,21 @@
+# Upgrade Guide
+
+## 0.4.0 to 1.0.0
+
+These update includes some changes as:
+
+- [Doc](#doc)
+- [Popover](#popover)
+- [Slider](#slider)
+
+### Doc
+
+The most important change is the Documentation ! Now it is in Vitepress, and you have access to. a Sandbox via `npm run sandbox` to play with the code and test it.
+
+### Popover
+
+There is the new Popover component, and it will replace the current Dropdown. But be carefull because not all browser support it yet :-)
+
+### Slider
+
+The slider has the ability to have a play and a pause button for more accessibility. 

package/docs/{pages/demo/layout.html → public/demo/demo.html}

@@ -5,7 +5,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Documentations: Layout > Demo</title>
-
+    <link rel="stylesheet" href="/bundles/vanilla-frontend.css">
     <style>
         #content {
             --subgrid-gap-block: 1rem;
@@ -34,7 +34,6 @@
 
         @media (min-width: 1440px) {}
     </style>
-
 </head>
 
 <body data-preload>

package/docs/start/customization.md

@@ -0,0 +1,184 @@
+# Customization
+
+The framework make you able to customize almost everything. But keep in mind that most of the work will be to create you own components per website !
+
+## CSS custom properties
+
+There is a bunch of default CSS custom properties, and (almost) each component have their own properties if needed.
+
+### Root
+
+In the `:root` set the default CSS properties that are global to all your website.
+
+You also can split in multiple files, e.g.: `root.scss` and `color.scss`..
+
+You can use the default file `@natachah/vanilla-frontend/scss/themes/_root.scss`, or copy this code in your own file:
+
+```scss
+////
+/// ------------------------------------------------------------------
+/// Root
+/// ------------------------------------------------------------------
+/// Regroup all the default CSS custom properties
+///
+/// @group themes
+/// @author Natacha Herth
+///
+////
+
+:root {
+
+    // Typography
+    --font-size: 16px;
+    --line-height: 1.5;
+    --font-family: Arial;
+    --font-weight: normal;
+    --font-weight-light: 300;
+    --font-weight-medium: 500;
+    --font-weight-bold: 600;
+
+    --font-size-h1: 2.25em; // 36px
+    --font-size-h2: 2.00em; // 32px
+    --font-size-h3: 1.75em; // 28px
+    --font-size-h4: 1.50em; // 24px
+    --font-size-h5: 1.25em; // 20px
+    --font-size-h6: 1.125em; // 18px
+    --font-size-large: 1.25em;
+    --font-size-medium: 1.125em;
+    --font-size-small: .875em;
+
+    --word-spacing: normal;
+    --letter-spacing: normal;
+
+    // Anchor
+    --decoration: none;
+
+    // Layouts
+    --padding-inline: .75em;
+    --padding-block: .5em;
+
+    // Border
+    --border-size: 1px;
+    --border-style: solid;
+    --border-radius: .25rem;
+
+    // Outline (:focus)
+    --outline-size: 3px;
+    --outline-style: solid;
+    --outline-offset: 0;
+    // --outline-color: var(--color-primary);
+
+    // Backdrop
+    --backdrop-color: rgba(0, 0, 0, .5);
+
+    // Hover (color-mix)
+    --hover-color: black;
+    --hover-percent: 5%;
+
+    // Active (color-mix)
+    --active-color: black;
+    --active-percent: 10%;
+
+    // Focus (color-mix)
+    --focus-color: currentColor;
+    --focus-percent: 50%;
+
+    // Disabled
+    --disabled-opacity: 50%;
+
+    // Colors
+    --color-body: white;
+    --color-font: black;
+    --color-primary: #B790E5;
+    --color-error: #DC3030;
+    --color-success: #008A00;
+    --color-warning: #FFA500;
+
+    // Contrasts
+    --color-warning-contrast: black;
+
+    // Form
+    --form-border-color: currentColor;
+    --form-active-background: color-mix(in srgb, var(--form-background, transparent), var(--active-color, currentColor) 40%);
+
+    // Icons
+    --icon-external: url('data: image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" ><path fill-rule="evenodd" d="M8.636 3.5a.5.5 0 0 0-.5-.5H1.5A1.5 1.5 0 0 0 0 4.5v10A1.5 1.5 0 0 0 1.5 16h10a1.5 1.5 0 0 0 1.5-1.5V7.864a.5.5 0 0 0-1 0V14.5a.5.5 0 0 1-.5.5h-10a.5.5 0 0 1-.5-.5v-10a.5.5 0 0 1 .5-.5h6.636a.5.5 0 0 0 .5-.5" /><path fill-rule="evenodd" d="M16 .5a.5.5 0 0 0-.5-.5h-5a.5.5 0 0 0 0 1h3.793L6.146 9.146a.5.5 0 1 0 .708.708L15 1.707V5.5a.5.5 0 0 0 1 0z" /></svg>');
+    --icon-date: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="black" viewBox="0 0 16 16"><path d="M3.5 0a.5.5 0 0 1 .5.5V1h8V.5a.5.5 0 0 1 1 0V1h1a2 2 0 0 1 2 2v11a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2V3a2 2 0 0 1 2-2h1V.5a.5.5 0 0 1 .5-.5zM1 4v10a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1V4H1z"/></svg>');
+    --icon-time: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path d="M8 3.5a.5.5 0 0 0-1 0V9a.5.5 0 0 0 .252.434l3.5 2a.5.5 0 0 0 .496-.868L8 8.71V3.5z"/><path d="M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16zm7-8A7 7 0 1 1 1 8a7 7 0 0 1 14 0z"/></svg>');
+    --icon-file: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path d="M.5 9.9a.5.5 0 0 1 .5.5v2.5a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-2.5a.5.5 0 0 1 1 0v2.5a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2v-2.5a.5.5 0 0 1 .5-.5z"/><path d="M7.646 1.146a.5.5 0 0 1 .708 0l3 3a.5.5 0 0 1-.708.708L8.5 2.707V11.5a.5.5 0 0 1-1 0V2.707L5.354 4.854a.5.5 0 1 1-.708-.708l3-3z"/></svg>');
+    --icon-select: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>');
+    --icon-radio: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="white" viewBox="0 0 16 16"><circle cx="8" cy="8" r="8"/></svg>');
+    --icon-check: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="white" viewBox="0 0 16 16"><path d="M10.97 4.97a.75.75 0 0 1 1.07 1.05l-3.99 4.99a.75.75 0 0 1-1.08.02L4.324 8.384a.75.75 0 1 1 1.06-1.06l2.094 2.093 3.473-4.425a.267.267 0 0 1 .02-.022z"/></svg>');
+    --icon-switch: var(--icon-radio);
+
+    // Layout
+    --layout-width: 1280px;
+    --layout-gap-block: 1rem;
+    --layout-gap-inline: 1rem;
+    --layout-columns: 1;
+
+    @media (min-width: 720px) {
+        --layout-columns: 6;
+        --layout-gap-block: 1rem;
+        --layout-gap-inline: 1rem;
+    }
+
+    @media (min-width: 1024px) {
+        --layout-columns: 12;
+        --layout-gap-block: 2rem;
+        --layout-gap-inline: 2rem;
+    }
+
+    @media (min-width: 1440px) {
+        --layout-columns: 12;
+        --layout-gap-block: 4rem;
+        --layout-gap-inline: 2rem;
+    }
+
+}
+```
+
+### Themes
+
+You can define some CSS properties per theme with the attribute `[data-theme=MYTHEME]`:
+
+```scss
+// This is the light theme (or if there is none)
+html[data-theme=light],
+html:not([data-theme]) {
+    --color-body: white;
+    --color-font: black;
+}
+
+// This is for the dark theme
+html[data-theme=dark] {
+    --color-body: black;
+    --color-font: white;
+}
+
+// This is for the dark theme
+html[data-theme=my-custom-theme] {
+    --color-body: white;
+    --color-font: orange;
+}
+```
+
+::: tip
+In best practive it will be better to have a file per theme.
+:::
+
+### SCSS options
+
+You can set custom settings with `@use "@natachah/vanilla-frontend/scss/components/..." with ( ... );`.
+These custom values will override the default variables.
+
+There is also a `$default-item-properties` to define the default properties to use for items *(see mixins)*
+
+There is 4 components that use this syntax, and that you can pass the `$colors` and if there is the `$outline` style enable:
+
+```scss
+@use "./components/badge" with ($colors: ('primary'), $outline: true);
+@use "./components/button" with ($colors: ('primary'), $outline: true);
+@use "./components/card" with ($colors: ('primary'), $outline: true);
+@use "./components/popover" with ($colors: ('primary'));
+```

package/docs/start/install.md

@@ -0,0 +1,80 @@
+# Installation
+
+## NPM
+
+Install the latest package via NPM
+
+```ssh
+npm i @natachah/vanilla-frontend
+```
+
+## SCSS
+
+You can import the global SCSS file:
+
+```scss
+@use '@natachah/vanilla-frontend/scss/vanilla-frontend.scss';
+```
+
+Or better, include **only the files that you need**, here the template with all files:
+
+```scss
+// Should be overide by your own files
+@use '@natachah/vanilla-frontend/scss/themes/_root';
+
+// If you need to use the mixin
+@use '@natachah/vanilla-frontend/scss/abstracts/_mixins';
+
+// Base files (reset, typography and media)
+@use "@natachah/vanilla-frontend/scss/base";
+
+// Components files (or: @use "@natachah/vanilla-frontend/scss/components";)
+@use '@natachah/vanilla-frontend/scss/components/_badge';
+@use '@natachah/vanilla-frontend/scss/components/_breadcrumb';
+@use '@natachah/vanilla-frontend/scss/components/_button';
+@use '@natachah/vanilla-frontend/scss/components/_card';
+@use '@natachah/vanilla-frontend/scss/components/_dialog';
+@use '@natachah/vanilla-frontend/scss/components/_disclosure';
+@use '@natachah/vanilla-frontend/scss/components/_drawer';
+@use '@natachah/vanilla-frontend/scss/components/_dropdown';
+@use '@natachah/vanilla-frontend/scss/components/_form';
+@use '@natachah/vanilla-frontend/scss/components/_grid';
+@use '@natachah/vanilla-frontend/scss/components/_group';
+@use '@natachah/vanilla-frontend/scss/components/_list';
+@use '@natachah/vanilla-frontend/scss/components/_loading';
+@use '@natachah/vanilla-frontend/scss/components/_progress';
+@use '@natachah/vanilla-frontend/scss/components/_slider';
+@use '@natachah/vanilla-frontend/scss/components/_table';
+```
+
+::: tip
+There is no required files, but it's recommanded to have at least the base/* and the themes/root
+:::
+
+## Javascript
+
+Import the Javascript files that you need, here the template:
+
+```js
+// If you need to create some component, you can use this
+import BaseComponent from "@natachah/vanilla-frontend/js/utilities/_base-component"
+import ErrorMessage from "@natachah/vanilla-frontend/js/utilities/_error"
+import Cookie from "@natachah/vanilla-frontend/js/utilities/_cookie"
+
+// Here the helpers
+import FormHelper from "@natachah/vanilla-frontend/js/utilities/_form-helper"
+
+// Here the components
+import Autofill from "@natachah/vanilla-frontend/js/_autofill"
+import CheckAll from "@natachah/vanilla-frontend/js/_check-all"
+import Comfort from "@natachah/vanilla-frontend/js/_comfort"
+import Consent from "@natachah/vanilla-frontend/js/_consent"
+import Dialog from "@natachah/vanilla-frontend/js/_dialog"
+import Dropdown from "@natachah/vanilla-frontend/js/_dropdown"
+import Drawer from "@natachah/vanilla-frontend/js/_drawer"
+import Scroll from "@natachah/vanilla-frontend/js/_scroll"
+import Slider from "@natachah/vanilla-frontend/js/_slider"
+import Sortable from "@natachah/vanilla-frontend/js/_sortable"
+import Toggle from "@natachah/vanilla-frontend/js/_toggle"
+import Tree from "@natachah/vanilla-frontend/js/_tree"
+```