@natachah/vanilla-frontend 0.4.1 → 1.0.0

package/docs/components/button.md

@@ -0,0 +1,254 @@
+<script setup>
+import ComponentPreview from '../vuejs/ComponentPreview.vue'
+</script>
+
+# Button
+
+```scss
+@use '@natachah/vanilla-frontend/scss/components/button'
+```
+
+## Syntax
+
+The button is using the native `<button>` tag, or an `<a>` tag with the attribute `role="button"`.
+
+<ComponentPreview>
+    <button>Button</button>&nbsp;
+    <a href="#" role="button">Link as button</a>
+</ComponentPreview>
+
+::: code-group
+
+```html
+<button>Button</button>
+<a href="#" role="button">Link as button</a>
+```
+
+```css [css properties]
+--button-color
+--button-background
+--button-border-size
+--button-border-style
+--button-border-color
+--button-border-radius
+--button-padding-inline
+--button-padding-block
+--button-transition
+--button-decoration
+```
+
+:::
+
+## States
+
+The button can have multiple states as `:hover`, `:focus`,  `:active` and `:disabled`.
+
+### Hover
+
+The button use a default focus style, but you can customize it with :
+
+```css
+--button-hover-color
+--button-hover-background
+--button-hover-border-color
+```
+
+### Focus
+
+The button use a default focus style, but you can customize it with :
+
+```css
+--button-focus-color
+--button-focus-background
+--button-focus-border-color
+```
+
+You can also customize the outline :
+
+```css
+--button-outline-size
+--button-outline-style
+--button-outline-color
+--button-outline-offset
+```
+
+### Active
+
+Apply the `aria-pressed`, `aria-current`, or `aria-selected` attribute on the `<button>` or `<a>` tag to display the active style.
+
+<ComponentPreview>
+    <button aria-pressed="true">Button pressed</button>&nbsp;
+    <button aria-selected="true">Button selected</button>&nbsp;
+    <a href="#" role="button" aria-current="true">Link as button with current</a>
+</ComponentPreview>
+
+::: code-group
+
+```html
+<button aria-pressed="true">Button pressed</button>
+<button aria-selected="true">Button selected</button>
+<a href="#" role="button" aria-current="true">Link as button with current</a>
+```
+
+```css [css properties]
+--button-active-color
+--button-active-background
+--button-active-border-color
+```
+
+:::
+
+### Disabled
+
+Apply the `disabled` attribute on `<button>` or remove the `href` attribute on `<a>` to display the disabled style.
+
+<ComponentPreview>
+    <button disabled>Button disabled</button>&nbsp;
+    <a role="button" >Link as button disabled</a>
+</ComponentPreview>
+
+::: code-group
+
+```html
+<button disabled>Button disabled</button>
+<a role="button" >Link as button disabled</a>
+```
+
+```css [css property]
+--button-disabled-opacity
+```
+
+:::
+
+## Variants
+
+The button have multiple variations to play with.
+
+### As Link
+
+You can create a button that look as a simple link with the attribute `role="link"`.
+
+<ComponentPreview>
+    <button role="link">As link</button>&nbsp;
+    <button role="link" disabled>As disabled link</button>
+</ComponentPreview>
+
+```html
+<button role="link">As link</button>
+<button role="link" disabled>As disabled link</button>
+```
+
+### Icon
+
+You can add an `<svg>` icon inside the button.
+
+<ComponentPreview>
+<button>
+    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path d="M8 8c.828 0 1.5-.895 1.5-2S8.828 4 8 4s-1.5.895-1.5 2S7.172 8 8 8Z" /><path d="M11.953 8.81c-.195-3.388-.968-5.507-1.777-6.819C9.707 1.233 9.23.751 8.857.454a3.495 3.495 0 0 0-.463-.315A2.19 2.19 0 0 0 8.25.064.546.546 0 0 0 8 0a.549.549 0 0 0-.266.073 2.312 2.312 0 0 0-.142.08 3.67 3.67 0 0 0-.459.33c-.37.308-.844.803-1.31 1.57-.805 1.322-1.577 3.433-1.774 6.756l-1.497 1.826-.004.005A2.5 2.5 0 0 0 2 12.202V15.5a.5.5 0 0 0 .9.3l1.125-1.5c.166-.222.42-.4.752-.57.214-.108.414-.192.625-.281l.198-.084c.7.428 1.55.635 2.4.635.85 0 1.7-.207 2.4-.635.067.03.132.056.196.083.213.09.413.174.627.282.332.17.586.348.752.57l1.125 1.5a.5.5 0 0 0 .9-.3v-3.298a2.5 2.5 0 0 0-.548-1.562l-1.499-1.83ZM12 10.445v.055c0 .866-.284 1.585-.75 2.14.146.064.292.13.425.199.39.197.8.46 1.1.86L13 14v-1.798a1.5 1.5 0 0 0-.327-.935L12 10.445ZM4.75 12.64C4.284 12.085 4 11.366 4 10.5v-.054l-.673.82a1.5 1.5 0 0 0-.327.936V14l.225-.3c.3-.4.71-.664 1.1-.861.133-.068.279-.135.425-.199ZM8.009 1.073c.063.04.14.094.226.163.284.226.683.621 1.09 1.28C10.137 3.836 11 6.237 11 10.5c0 .858-.374 1.48-.943 1.893C9.517 12.786 8.781 13 8 13c-.781 0-1.517-.214-2.057-.607C5.373 11.979 5 11.358 5 10.5c0-4.182.86-6.586 1.677-7.928.409-.67.81-1.082 1.096-1.32.09-.076.17-.135.236-.18Z" /><path d="M9.479 14.361c-.48.093-.98.139-1.479.139-.5 0-.999-.046-1.479-.139L7.6 15.8a.5.5 0 0 0 .8 0l1.079-1.439Z" /></svg>
+    Button
+</button>
+</ComponentPreview>
+
+```html
+<button>
+    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path d="M8 8c.828 0 1.5-.895 1.5-2S8.828 4 8 4s-1.5.895-1.5 2S7.172 8 8 8Z" /><path d="M11.953 8.81c-.195-3.388-.968-5.507-1.777-6.819C9.707 1.233 9.23.751 8.857.454a3.495 3.495 0 0 0-.463-.315A2.19 2.19 0 0 0 8.25.064.546.546 0 0 0 8 0a.549.549 0 0 0-.266.073 2.312 2.312 0 0 0-.142.08 3.67 3.67 0 0 0-.459.33c-.37.308-.844.803-1.31 1.57-.805 1.322-1.577 3.433-1.774 6.756l-1.497 1.826-.004.005A2.5 2.5 0 0 0 2 12.202V15.5a.5.5 0 0 0 .9.3l1.125-1.5c.166-.222.42-.4.752-.57.214-.108.414-.192.625-.281l.198-.084c.7.428 1.55.635 2.4.635.85 0 1.7-.207 2.4-.635.067.03.132.056.196.083.213.09.413.174.627.282.332.17.586.348.752.57l1.125 1.5a.5.5 0 0 0 .9-.3v-3.298a2.5 2.5 0 0 0-.548-1.562l-1.499-1.83ZM12 10.445v.055c0 .866-.284 1.585-.75 2.14.146.064.292.13.425.199.39.197.8.46 1.1.86L13 14v-1.798a1.5 1.5 0 0 0-.327-.935L12 10.445ZM4.75 12.64C4.284 12.085 4 11.366 4 10.5v-.054l-.673.82a1.5 1.5 0 0 0-.327.936V14l.225-.3c.3-.4.71-.664 1.1-.861.133-.068.279-.135.425-.199ZM8.009 1.073c.063.04.14.094.226.163.284.226.683.621 1.09 1.28C10.137 3.836 11 6.237 11 10.5c0 .858-.374 1.48-.943 1.893C9.517 12.786 8.781 13 8 13c-.781 0-1.517-.214-2.057-.607C5.373 11.979 5 11.358 5 10.5c0-4.182.86-6.586 1.677-7.928.409-.67.81-1.082 1.096-1.32.09-.076.17-.135.236-.18Z" /><path d="M9.479 14.361c-.48.093-.98.139-1.479.139-.5 0-.999-.046-1.479-.139L7.6 15.8a.5.5 0 0 0 .8 0l1.079-1.439Z" /></svg>
+    Button
+</button>
+```
+
+### Size
+
+You can adapte the size of the button by changing their `font-size`.
+
+<ComponentPreview>
+<button style="font-size: var(--font-size-small)">Small</button>&nbsp;
+<button>Normal</button>&nbsp;
+<button style="font-size: var(--font-size-large)">Large</button>
+</ComponentPreview>
+
+```html
+<button style="font-size: var(--font-size-small)">Small</button>
+<button>Normal</button>
+<button style="font-size: var(--font-size-large)">Large</button>
+```
+
+### Outline
+
+You can create an outline variation by enable the option and adding the class `.outline`.
+
+<ComponentPreview>
+<button class="outline">Button</button>&nbsp;
+<button class="outline" disabled>Disabled</button>&nbsp;
+<button class="outline" aria-pressed="true">Active</button>
+</ComponentPreview>
+
+::: code-group
+```html
+<button class="outline">Button</button>
+<button class="outline" disabled>Disabled</button>
+<button class="outline" aria-pressed="true">Active</button>
+```
+
+```scss {2}
+@use "@natachah/vanilla-frontend/scss/components/button" with (
+    $outline: true
+);
+```
+:::
+
+### Color
+
+You can create some color variation by including the colors classes name into the import and then by adding the class as `.{COLOR}`.
+
+<ComponentPreview>
+<button class="primary">Primary</button>&nbsp;
+<button class="primary" disabled>Disabled</button>&nbsp;
+<button class="primary" aria-pressed="true">Active</button>&nbsp;
+<button class="primary outline">Primary</button>&nbsp;
+<button class="primary outline" disabled>Disabled</button>&nbsp;
+<button class="primary outline" aria-pressed="true">Active</button>
+</ComponentPreview>
+
+::: code-group
+```html
+<button class="primary">Primary</button>
+<button class="primary" disabled>Disabled</button>
+<button class="primary" aria-pressed="true">Active</button>
+<button class="primary outline">Primary</button>
+<button class="primary outline" disabled>Disabled</button>
+<button class="primary outline" aria-pressed="true">Active</button>
+```
+
+```scss {2}
+@use "@natachah/vanilla-frontend/scss/components/button" with (
+    $colors: ('primary'),
+    $outline: true
+);
+```
+:::
+
+### Group
+
+You can group some buttons by putting them in a `<div>` with the class `.group`.
+
+<ComponentPreview>
+<div class="group">
+    <button class="outline">Button A</button>
+    <button class="outline">Button B</button>
+    <button class="outline">Button C</button>
+</div>
+</ComponentPreview>
+
+::: code-group
+```html
+<div class="group">
+    <button class="outline">Button A</button>
+    <button class="outline">Button B</button>
+    <button class="outline">Button C</button>
+</div>
+```
+
+```scss
+@use '@natachah/vanilla-frontend/scss/components/group';
+```
+:::

package/docs/components/dialog.md

@@ -0,0 +1,223 @@
+<script setup>
+import ComponentPreview from '../vuejs/ComponentPreview.vue'
+</script>
+
+# Dialog <Badge type="warning" text="JS" />
+
+```scss
+@use '@natachah/vanilla-frontend/scss/components/dialog';
+```
+
+::: tip Difference between modal and non-modal:
+
+The key difference is the level interaction and interaction restriction. A modal will block interaction with the main content, and they have their own context focus (use of a backdrop). But a non-modal don't impose context and restriction. 
+:::
+
+## Syntax
+
+The dialog is using the native `<dialog>` tag.
+
+You can define if the dialog is a modal with the `aria-modal` attribute.
+
+<ComponentPreview height="200px">
+    <button aria-controls="myDialog">Open the dialog</button>
+    <dialog id="myDialog" aria-label="demo">
+  Content of the dialog
+        <button data-dialog-close>Close the dialog</button>
+    </dialog>
+</ComponentPreview>
+
+::: code-group
+
+```html
+<button aria-controls="myDialog">Open the dialog</button>
+<dialog id="myDialog" aria-modal="true" aria-label="demo">
+    Content of the dialog
+    <button data-dialog-close>Close the dialog</button>
+</dialog>
+```
+
+```css [css properties]
+--dialog-color
+--dialog-background
+--dialog-border-size
+--dialog-border-style
+--dialog-border-color
+--dialog-border-radius
+--dialog-padding-inline
+--dialog-padding-block
+--dialog-position
+--dialog-width
+--dialog-height
+--dialog-max-width
+--dialog-max-height
+--dialog-index
+--dialog-backdrop-background
+--dialog-backdrop-filter
+--dialog-open-animation
+--dialog-open-transform
+--dialog-close-animation
+--dialog-close-transform
+--dialog-divider-size
+--dialog-divider-style
+--dialog-divider-color
+```
+
+```js
+import Dialog from "@natachah/vanilla-frontend/js/_dialog"
+const myDialog = document.getElementById('myDialog')
+if (myDialog) new Dialog(myDialog)
+```
+
+:::
+
+To work properly you must have a `<button>` in your page with the attribute `aria-controls="IdOfDialogToOpen"` that will open the dialog.
+
+And inside your `<dialog>` you should have a `<button>` with the attribute `data-dialog-close` to close the dialog.
+
+For accessibility, don't forget to add a `aria-labelledby` into the `<dialog>` to set a title.
+
+## Layout
+
+The dialog can have a `<header>` and/or `<footer>` inside to create a more complexe layout.
+
+<ComponentPreview height="400px">
+<button aria-controls="layoutDialog">Open the dialog</button>
+<dialog id="layoutDialog" aria-labelledby="layoutDialogTitle" aria-modal="true">
+    <header id="layoutDialogTitle">This is a header</header>
+    <div>
+        <p>This is the content</p>
+        <button data-dialog-close>Close</button>
+    </div>
+    <footer>This is a footer</footer>
+</dialog>
+</ComponentPreview>
+
+```html
+<dialog id="layoutDialog" aria-labelledby="layoutDialogTitle" aria-modal="true">
+    <header id="layoutDialogTitle">This is a header</header>
+    <div>
+        <p>This is the content</p>
+        <button data-dialog-close>Close</button>
+    </div>
+    <footer>This is a footer</footer>
+</dialog>
+```
+
+## Form
+
+You can submit a `<form>` inside the `<dialog>`.
+
+<ComponentPreview height="400px">
+<button aria-controls="formDialog">Open the dialog</button>
+<dialog id="formDialog" aria-labelledby="formDialogTitle" aria-modal="true">
+    <h3 id="formDialogTitle">Dialog with form</h3>
+    <form method="POST">
+        <label for="animal">What is your favorite animal</label>
+        <input id="animal" type="text" name="animal" required>
+        <button type="reset" data-dialog-close>Cancel</button>
+        <button type="submit">Default submit</button>
+    </form>
+</dialog>
+</ComponentPreview>
+
+```html
+<dialog id="formDialog" aria-labelledby="formDialogTitle" aria-modal="true">
+    <h3 id="formDialogTitle">Dialog with form</h3>
+    <form method="POST">
+        <label for="animal">What is your favorite animal</label>
+        <input id="animal" type="text" name="animal" required>
+        <button type="reset" data-dialog-close>Cancel</button>
+        <button type="submit">Default submit</button>
+    </form>
+</dialog>
+```
+
+If you want to submit via javascript add the `method="dialog"` attribute on the `<form>` or the `formmethod="dialog"` attribute on the `<button>`.
+
+Then you should use the event `dialog:submited` to catch the values.
+
+<ComponentPreview height="400px">
+<button aria-controls="jsDialog">Open the dialog</button>
+<dialog id="jsDialog" aria-labelledby="jsDialogTitle" aria-modal="true">
+    <h3 id="jsDialogTitle">Dialog with form</h3>
+    <form method="dialog">
+        <label for="animal">What is your favorite animal</label>
+        <input id="animal" type="text" name="animal" required>
+        <button type="reset" data-dialog-close>Cancel</button>
+        <button type="submit">Javascript submit</button>
+    </form>
+</dialog>
+<p>Your favorite animal is: <b id="favorite">--</b></p>
+</ComponentPreview>
+
+::: code-group
+
+```html
+<button aria-controls="jsDialog">Open the dialog</button>
+<dialog id="jsDialog" aria-labelledby="jsDialogTitle" aria-modal="true">
+    <h3 id="jsDialogTitle">Dialog with form</h3>
+    <form method="dialog">
+        <label for="animal">What is your favorite animal</label>
+        <input id="animal" type="text" name="animal" required>
+        <button type="reset" data-dialog-close>Cancel</button>
+        <button type="submit">Javascript submit</button>
+    </form>
+</dialog>
+<p>Your favorite animal is: <span id="favorite">--</span></p>
+```
+
+```js {8-12}
+const demoDialogFormJS = document.getElementById('jsDialog')
+
+if (demoDialogFormJS) {
+
+    // Init the dialog
+    new Dialog(demoDialogFormJS)
+
+    // Check for the dialog:submited event
+    demoDialogFormJS.addEventListener('dialog:submited', (e) => {
+        const value = e.detail.form.querySelector('input').value
+        document.getElementById('favorite').innerText = value
+    })
+
+}
+```
+
+:::
+
+## Javascript
+
+To work properly the dialog required some javascript.
+
+### Methods
+
+| Method | Description |
+| --- | --- |
+| open(e) | This method will open the dialog | 
+| close() | This method will close the dialog | 
+| submit() | This method will submit the dialog | 
+
+### Events
+
+| Event name | Description | Value |
+|---|---|---|
+| dialog:opening | When the method `open()` is called | – |
+| dialog:opened | After the method `open()` is called | –   |
+| dialog:closing | When the method `close()` is called | –   |
+| dialog:closed | After the method `close()` is called | –   |
+| dialog:submiting | When the method `submit()` is called | form as an HTMLElement |
+| dialog:submited | After the method `submit()` is called | form as an HTMLElement |
+
+```js
+// E.G. basic opening
+document.getElementById('myDialogID').addEventListener('dialog:opening', () => {
+    console.log('The dialog is opening')
+})
+
+// E.G. with form value
+document.getElementById('myDialogID').addEventListener('dialog:submited', (e) => {
+    const theHTMLForm = e.detail.form
+    console.log('The dialog is submited')
+})
+```

package/docs/components/disclosure.md

@@ -0,0 +1,169 @@
+<script setup>
+import ComponentPreview from '../vuejs/ComponentPreview.vue'
+</script>
+
+# Disclosure
+
+```scss
+@use '@natachah/vanilla-frontend/scss/components/disclosure';
+```
+
+## Syntax
+
+The disclosure is using the native `<details>` and `<summary>` tags.
+
+<ComponentPreview height="200">
+<details>
+<summary>
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M4.646 1.646a.5.5 0 0 1 .708 0l6 6a.5.5 0 0 1 0 .708l-6 6a.5.5 0 0 1-.708-.708L10.293 8 4.646 2.354a.5.5 0 0 1 0-.708z"></path>
+</svg>
+Title
+</summary>
+<div>
+Content
+</div>
+</details>
+</ComponentPreview>
+
+::: code-group
+
+```html
+<details>
+    <summary>
+        <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M4.646 1.646a.5.5 0 0 1 .708 0l6 6a.5.5 0 0 1 0 .708l-6 6a.5.5 0 0 1-.708-.708L10.293 8 4.646 2.354a.5.5 0 0 1 0-.708z"></path></svg>
+        Title
+    </summary>
+    <div>
+        Content
+    </div>
+</details>
+```
+
+```css [css properties]
+--disclosure-color
+--disclosure-background
+--disclosure-border-size
+--disclosure-border-style
+--disclosure-border-color
+--disclosure-border-radius
+--disclosure-padding-inline
+--disclosure-padding-block
+--disclosure-transition
+--disclosure-decoration
+--disclosure-svg-transform
+```
+
+:::
+
+::: tip
+It's recommended to add a `<div>` around the inside content for better design.
+:::
+
+## States
+
+The `<summary>` can have multiple states as `:hover`, `:focus`, and`:active`.
+
+### Hover
+
+The `<summary>` use a default focus style, but you can customize it with :
+
+```css
+--disclosure-hover-color
+--disclosure-hover-background
+--disclosure-hover-border-color
+```
+
+### Focus
+
+The `<summary>` use a default focus style, but you can customize it with :
+
+```css
+--disclosure-focus-color
+--disclosure-focus-background
+--disclosure-focus-border-color
+```
+
+You can also customize the outline :
+
+```css
+--disclosure-outline-size
+--disclosure-outline-style
+--disclosure-outline-color
+--disclosure-outline-offset
+```
+
+### Active
+
+The active state is automatically displayed when the disclosure is `open`.
+
+```css
+--disclosure-active-color
+--disclosure-active-background
+--disclosure-active-border-color
+```
+
+## Variants
+
+The disclosure has a variation to play with.
+
+### Accordion
+
+You can group some disclosures by putting them in a `<div>` with the class `.accordion`.
+
+<ComponentPreview height="250px">
+ <div class="accordion" style="--disclosure-border-color:black">
+    <details>
+        <summary >
+            Disclosure A
+        </summary>
+        <div>
+            AAA
+        </div>
+    </details>
+    <details>
+        <summary>
+            Disclosure B
+        </summary>
+        <div>
+            BBB
+        </div>
+    </details>
+    <details>
+        <summary>
+            Disclosure C
+        </summary>
+        <div>
+            CCC
+        </div>
+    </details>
+</div>
+</ComponentPreview>
+
+```html
+<div class="accordion" style="--disclosure-border-color:black">
+    <details>
+        <summary>
+            Disclosure A
+        </summary>
+        <div>
+            AAA
+        </div>
+    </details>
+    <details>
+        <summary>
+            Disclosure B
+        </summary>
+        <div>
+            BBB
+        </div>
+    </details>
+    <details>
+        <summary>
+            Disclosure C
+        </summary>
+        <div>
+            CCC
+        </div>
+    </details>
+</div>
+```