@digicreon/mucss 1.0.0

package/documentation/mu.pagination.md

@@ -0,0 +1,196 @@
+# µPagination
+
+**µPagination** is a flexible page navigation component, part of the [µCSS](.) framework. It supports alignment variants, sizes, responsive behavior, and borderless styling.
+
+---
+
+## Usage
+
+Pagination uses a `<nav>` containing a `<ul>` with the `.pagination` class. Each page is a `<li>` with an `<a>` or `<span>` inside.
+
+```html
+<nav aria-label="Pagination">
+	<ul class="pagination">
+		<li class="pagination-prev"><a href="#">&laquo; Prev</a></li>
+		<li><a href="#">1</a></li>
+		<li class="active"><a href="#" aria-current="page">2</a></li>
+		<li><a href="#">3</a></li>
+		<li><a href="#">4</a></li>
+		<li><a href="#">5</a></li>
+		<li class="pagination-next"><a href="#">Next &raquo;</a></li>
+	</ul>
+</nav>
+```
+
+---
+
+## Item states
+
+### Active page
+
+Add `.active` to the `<li>` to indicate the current page. The active item gets the primary color as background and disables pointer events.
+
+```html
+<li class="active"><a href="#" aria-current="page">2</a></li>
+```
+
+### Disabled
+
+Add `.disabled` to the `<li>` to disable an item (e.g., the "Prev" button on the first page). The item is faded and non-interactive.
+
+```html
+<li class="pagination-prev disabled"><a href="#">&laquo; Prev</a></li>
+```
+
+### Ellipsis
+
+Use `.pagination-ellipsis` with a `<span>` to indicate skipped page numbers:
+
+```html
+<li class="pagination-ellipsis"><span>&hellip;</span></li>
+```
+
+### With ellipsis and disabled
+
+```html
+<nav aria-label="Pagination">
+	<ul class="pagination">
+		<li class="pagination-prev disabled"><a href="#">&laquo; Prev</a></li>
+		<li class="active"><a href="#" aria-current="page">1</a></li>
+		<li><a href="#">2</a></li>
+		<li><a href="#">3</a></li>
+		<li class="pagination-ellipsis"><span>&hellip;</span></li>
+		<li><a href="#">20</a></li>
+		<li class="pagination-next"><a href="#">Next &raquo;</a></li>
+	</ul>
+</nav>
+```
+
+---
+
+## Alignment
+
+By default, pagination is left-aligned. Two modifier classes change the alignment:
+
+| Class                  | Effect                    |
+|------------------------|---------------------------|
+| `.pagination-centered` | `justify-content: center` |
+| `.pagination-end`      | `justify-content: flex-end` |
+
+### Centered
+
+```html
+<nav aria-label="Pagination">
+	<ul class="pagination pagination-centered">
+		<li class="pagination-prev"><a href="#">&laquo;</a></li>
+		<li><a href="#">1</a></li>
+		<li class="active"><a href="#" aria-current="page">2</a></li>
+		<li><a href="#">3</a></li>
+		<li class="pagination-next"><a href="#">&raquo;</a></li>
+	</ul>
+</nav>
+```
+
+### End-aligned
+
+```html
+<nav aria-label="Pagination">
+	<ul class="pagination pagination-end">
+		<li class="pagination-prev"><a href="#">&laquo;</a></li>
+		<li><a href="#">1</a></li>
+		<li class="active"><a href="#" aria-current="page">2</a></li>
+		<li><a href="#">3</a></li>
+		<li class="pagination-next"><a href="#">&raquo;</a></li>
+	</ul>
+</nav>
+```
+
+---
+
+## Sizes
+
+Two size variants adjust the dimensions, padding, and font size of pagination items:
+
+| Class             | Min-width | Height   | Padding              | Font size  |
+|-------------------|-----------|----------|----------------------|------------|
+| `.pagination-sm`  | 1.75rem   | 1.75rem  | `0.15rem 0.45rem`    | `0.75rem`  |
+| *(default)*       | 2.25rem   | 2.25rem  | `0.25rem 0.625rem`   | `0.875rem` |
+| `.pagination-lg`  | 2.75rem   | 2.75rem  | `0.375rem 0.8rem`    | `1rem`     |
+
+```html
+<ul class="pagination pagination-sm">...</ul>
+<ul class="pagination pagination-lg">...</ul>
+```
+
+---
+
+## Borderless
+
+Remove borders from all pagination items:
+
+```html
+<nav aria-label="Pagination">
+	<ul class="pagination pagination-borderless">
+		<li class="pagination-prev"><a href="#">&laquo;</a></li>
+		<li><a href="#">1</a></li>
+		<li class="active"><a href="#" aria-current="page">2</a></li>
+		<li><a href="#">3</a></li>
+		<li><a href="#">4</a></li>
+		<li class="pagination-next"><a href="#">&raquo;</a></li>
+	</ul>
+</nav>
+```
+
+---
+
+## Responsive
+
+Add `.pagination-responsive` to hide page numbers (except the active page and prev/next controls) on screens narrower than 640px:
+
+```html
+<nav aria-label="Pagination">
+	<ul class="pagination pagination-responsive">
+		<li class="pagination-prev"><a href="#">&laquo; Prev</a></li>
+		<li><a href="#">1</a></li>
+		<li><a href="#">2</a></li>
+		<li class="active"><a href="#" aria-current="page">3</a></li>
+		<li><a href="#">4</a></li>
+		<li><a href="#">5</a></li>
+		<li class="pagination-next"><a href="#">Next &raquo;</a></li>
+	</ul>
+</nav>
+```
+
+On mobile (<640px), only `.pagination-prev`, `.pagination-next`, and `.active` items are visible. The pagination stretches full width with `justify-content: space-between`.
+
+---
+
+## CSS classes reference
+
+| Class                  | Applied to | Description                                      |
+|------------------------|------------|--------------------------------------------------|
+| `.pagination`          | `<ul>`     | Base pagination container (flex, list-style none) |
+| `.pagination-prev`     | `<li>`     | Previous page item (bold text)                   |
+| `.pagination-next`     | `<li>`     | Next page item (bold text)                       |
+| `.active`              | `<li>`     | Current page (primary bg, non-interactive)       |
+| `.disabled`            | `<li>`     | Disabled item (faded, non-interactive)           |
+| `.pagination-ellipsis` | `<li>`     | Ellipsis separator (no border)                   |
+| `.pagination-centered` | `<ul>`     | Center-aligned pagination                        |
+| `.pagination-end`      | `<ul>`     | Right-aligned pagination                         |
+| `.pagination-sm`       | `<ul>`     | Small size variant                               |
+| `.pagination-lg`       | `<ul>`     | Large size variant                               |
+| `.pagination-borderless` | `<ul>`   | Remove borders from items                        |
+| `.pagination-responsive` | `<ul>`   | Hide non-essential items on mobile               |
+
+---
+
+## Accessibility
+
+- Wrap pagination in a `<nav>` element with `aria-label="Pagination"`.
+- Add `aria-current="page"` to the active page link.
+- The active page and disabled items have `pointer-events: none` to prevent interaction.
+- Focus-visible outlines (`2px solid`) are applied for keyboard navigation.
+
+---
+
+→ [Voir l'exemple](../examples/pagination.html)

package/documentation/mu.progress.md

@@ -0,0 +1,123 @@
+# µProgress
+
+**µProgress** adds 8 color variants to the native `<progress>` element, part of the [µCSS](.) framework. It uses `accent-color` and vendor-specific pseudo-elements for cross-browser compatibility.
+
+---
+
+## Usage
+
+Apply a color class directly on a `<progress>` element to change the bar color. Without a color class, the default PicoCSS progress styling applies.
+
+```html
+<progress class="progress-primary" value="75" max="100">75%</progress>
+```
+
+The text content inside `<progress>` serves as a fallback for browsers that do not support the element.
+
+---
+
+## Color variants
+
+8 color classes are available, matching the µCSS color roles:
+
+| Class                | Color variable       |
+|----------------------|----------------------|
+| `.progress-primary`  | `--pico-primary`     |
+| `.progress-secondary`| `--pico-secondary`   |
+| `.progress-tertiary` | `--pico-tertiary`    |
+| `.progress-contrast` | `--pico-contrast`    |
+| `.progress-success`  | `--pico-success`     |
+| `.progress-info`     | `--pico-info`        |
+| `.progress-warning`  | `--pico-warning`     |
+| `.progress-error`    | `--pico-error`       |
+
+### All 8 variants
+
+```html
+<label>Primary (75%)
+	<progress class="progress-primary" value="75" max="100">75%</progress>
+</label>
+<label>Secondary (60%)
+	<progress class="progress-secondary" value="60" max="100">60%</progress>
+</label>
+<label>Tertiary (45%)
+	<progress class="progress-tertiary" value="45" max="100">45%</progress>
+</label>
+<label>Contrast (90%)
+	<progress class="progress-contrast" value="90" max="100">90%</progress>
+</label>
+<label>Success (80%)
+	<progress class="progress-success" value="80" max="100">80%</progress>
+</label>
+<label>Info (50%)
+	<progress class="progress-info" value="50" max="100">50%</progress>
+</label>
+<label>Warning (35%)
+	<progress class="progress-warning" value="35" max="100">35%</progress>
+</label>
+<label>Error (20%)
+	<progress class="progress-error" value="20" max="100">20%</progress>
+</label>
+```
+
+---
+
+## Various values
+
+The `value` attribute controls the fill level. Set `max` to define the scale (typically 100).
+
+```html
+<progress class="progress-primary" value="0" max="100">0%</progress>
+<progress class="progress-success" value="25" max="100">25%</progress>
+<progress class="progress-info" value="50" max="100">50%</progress>
+<progress class="progress-primary" value="100" max="100">100%</progress>
+```
+
+---
+
+## Indeterminate
+
+Omit the `value` attribute to create an indeterminate progress bar (animated loading indicator):
+
+```html
+<progress class="progress-primary">Loading...</progress>
+```
+
+---
+
+## Cross-browser implementation
+
+Each color variant sets three properties for full browser support:
+
+| Property                        | Target           |
+|---------------------------------|------------------|
+| `accent-color`                  | Modern browsers  |
+| `::-webkit-progress-value`      | Chrome, Safari   |
+| `::-moz-progress-bar`           | Firefox          |
+
+---
+
+## CSS classes reference
+
+| Class                | Description                          |
+|----------------------|--------------------------------------|
+| `.progress-primary`  | Primary color progress bar           |
+| `.progress-secondary`| Secondary color progress bar         |
+| `.progress-tertiary` | Tertiary color progress bar          |
+| `.progress-contrast` | Contrast color progress bar          |
+| `.progress-success`  | Success (green) progress bar         |
+| `.progress-info`     | Info (blue) progress bar             |
+| `.progress-warning`  | Warning (orange/yellow) progress bar |
+| `.progress-error`    | Error (red) progress bar             |
+
+---
+
+## Accessibility
+
+- The `<progress>` element is natively accessible and announced by screen readers.
+- Include fallback text content inside the element (e.g., `75%`) for older browsers.
+- Wrap progress bars inside `<label>` elements to provide descriptive context.
+
+---
+
+→ [Voir l'exemple](../examples/progress.html)

package/documentation/mu.range.md

@@ -0,0 +1,103 @@
+# µRange
+
+**µRange** describes the native range slider styling provided by [µCSS](.) via PicoCSS. Range sliders use the standard `<input type="range">` element, which PicoCSS styles with a custom track and thumb without any additional classes.
+
+---
+
+## Usage
+
+Wrap an `<input type="range">` inside a `<label>` for proper styling and accessibility. Use `min`, `max`, and `value` attributes to configure the range.
+
+```html
+<label>Volume
+    <input type="range" min="0" max="100" value="50">
+</label>
+```
+
+---
+
+## With live output
+
+Pair the range input with an `<output>` element and a small `oninput` handler to display the current value in real time.
+
+```html
+<label>Brightness: <output id="brightness-val">75</output>%
+    <input type="range" min="0" max="100" value="75"
+           oninput="document.getElementById('brightness-val').textContent = this.value">
+</label>
+```
+
+---
+
+## With steps
+
+Use the `step` attribute to constrain the slider to discrete values.
+
+```html
+<label>Rating (1-5): <output id="rating-val">3</output>
+    <input type="range" min="1" max="5" step="1" value="3"
+           oninput="document.getElementById('rating-val').textContent = this.value">
+</label>
+```
+
+---
+
+## Disabled state
+
+Add the `disabled` attribute to prevent interaction. The slider renders in a muted style.
+
+```html
+<label>Locked value
+    <input type="range" min="0" max="100" value="60" disabled>
+</label>
+```
+
+---
+
+## In a form context
+
+Range sliders work well inside cards (`<article>`) for settings panels.
+
+```html
+<article>
+    <header>Audio settings</header>
+    <label>Master volume: <output id="master-val">80</output>%
+        <input type="range" min="0" max="100" value="80"
+               oninput="document.getElementById('master-val').textContent = this.value">
+    </label>
+    <label>Bass: <output id="bass-val">50</output>%
+        <input type="range" min="0" max="100" value="50"
+               oninput="document.getElementById('bass-val').textContent = this.value">
+    </label>
+    <label>Treble: <output id="treble-val">65</output>%
+        <input type="range" min="0" max="100" value="65"
+               oninput="document.getElementById('treble-val').textContent = this.value">
+    </label>
+</article>
+```
+
+---
+
+## Attributes reference
+
+| Attribute  | Description                                      | Default |
+|------------|--------------------------------------------------|---------|
+| `min`      | Minimum value of the range                       | `0`     |
+| `max`      | Maximum value of the range                       | `100`   |
+| `value`    | Initial value of the slider                      | midpoint|
+| `step`     | Increment between allowed values                 | `1`     |
+| `disabled` | Prevents interaction, muted visual style         | -       |
+
+---
+
+## Accessibility
+
+- Always wrap the range input in a `<label>` to provide an accessible name.
+- The `<output>` element is semantically linked to form controls and can be associated using the `for` attribute for screen readers.
+- Screen readers announce the current value, minimum, and maximum of the range slider.
+- The `disabled` attribute is natively communicated to assistive technologies.
+- Keyboard users can adjust the slider using arrow keys.
+
+---
+
+→ [Voir l'exemple](../examples/range.html)

package/documentation/mu.spinner.md

@@ -0,0 +1,102 @@
+# µSpinner
+
+**µSpinner** is a lightweight CSS loading indicator, part of the [µCSS](.) framework. It provides an animated circular spinner available in 8 color variants and 3 sizes, with no JavaScript required.
+
+---
+
+## Usage
+
+Add the `.spinner` class to an inline element (typically a `<span>`) to create a loading indicator.
+
+```html
+<span class="spinner"></span>
+```
+
+The default spinner uses the primary color and a standard size of 1.5rem.
+
+---
+
+## Color variants
+
+µSpinner supports the 8 standard µCSS color roles. Add a color modifier class alongside `.spinner`:
+
+```html
+<span class="spinner spinner-primary"></span>
+<span class="spinner spinner-secondary"></span>
+<span class="spinner spinner-tertiary"></span>
+<span class="spinner spinner-contrast"></span>
+<span class="spinner spinner-success"></span>
+<span class="spinner spinner-info"></span>
+<span class="spinner spinner-warning"></span>
+<span class="spinner spinner-error"></span>
+```
+
+### Color class reference
+
+| Class               | Color variable          |
+|---------------------|-------------------------|
+| `.spinner-primary`  | `--pico-primary`        |
+| `.spinner-secondary`| `--pico-secondary`      |
+| `.spinner-tertiary` | `--pico-tertiary`       |
+| `.spinner-contrast` | `--pico-contrast`       |
+| `.spinner-success`  | `--pico-success`        |
+| `.spinner-info`     | `--pico-info`           |
+| `.spinner-warning`  | `--pico-warning`        |
+| `.spinner-error`    | `--pico-error`          |
+
+---
+
+## Sizes
+
+Three sizes are available: small, default, and large.
+
+```html
+<!-- Small (1rem) -->
+<span class="spinner spinner-sm spinner-primary"></span>
+
+<!-- Default (1.5rem) -->
+<span class="spinner spinner-primary"></span>
+
+<!-- Large (2.5rem) -->
+<span class="spinner spinner-lg spinner-primary"></span>
+```
+
+### Size class reference
+
+| Class         | Width / Height | Border width |
+|---------------|----------------|--------------|
+| `.spinner-sm` | 1rem           | 0.15em       |
+| *(default)*   | 1.5rem         | 0.2em        |
+| `.spinner-lg` | 2.5rem         | 0.25em       |
+
+---
+
+## In-context usage
+
+A common pattern is placing a small spinner inside a disabled button to indicate a loading state:
+
+```html
+<button class="btn btn-primary" disabled>
+    <span class="spinner spinner-sm"></span>&nbsp; Loading...
+</button>
+```
+
+---
+
+## How it works
+
+The spinner is a bordered `inline-block` element with a colored top border and a transparent-ish track (using `--pico-secondary-background`). It rotates continuously via the `mu-spin` keyframe animation (0.6s linear infinite).
+
+---
+
+## Accessibility
+
+The spinner is purely visual. For screen readers, pair it with appropriate text content (e.g. "Loading...") or use an `aria-label` attribute:
+
+```html
+<span class="spinner spinner-primary" role="status" aria-label="Loading"></span>
+```
+
+---
+
+→ [Voir l'exemple](../examples/spinner.html)

package/documentation/mu.switch.md

@@ -0,0 +1,110 @@
+# µSwitch
+
+**µSwitch** describes the toggle switch controls available natively in [µCSS](.) via PicoCSS. Switches are standard checkboxes enhanced with `role="switch"`, which PicoCSS styles as visual toggle switches without any additional CSS or JavaScript.
+
+---
+
+## Usage
+
+A switch is a standard `<input type="checkbox">` with the `role="switch"` attribute, wrapped in a `<label>`.
+
+```html
+<label>
+    <input type="checkbox" role="switch">
+    Enable notifications
+</label>
+```
+
+---
+
+## Basic switch
+
+Use `checked` to set the initial state.
+
+```html
+<label>
+    <input type="checkbox" role="switch">
+    Enable notifications
+</label>
+<label>
+    <input type="checkbox" role="switch" checked>
+    Dark mode
+</label>
+```
+
+---
+
+## Disabled state
+
+Add the `disabled` attribute to prevent interaction. The switch renders in a muted style.
+
+```html
+<label>
+    <input type="checkbox" role="switch" disabled>
+    Disabled off
+</label>
+<label>
+    <input type="checkbox" role="switch" disabled checked>
+    Disabled on
+</label>
+```
+
+---
+
+## Validation states
+
+Use `aria-invalid` to indicate valid or invalid states visually.
+
+```html
+<label>
+    <input type="checkbox" role="switch" aria-invalid="false" checked>
+    Valid switch
+</label>
+<label>
+    <input type="checkbox" role="switch" aria-invalid="true">
+    Invalid switch
+</label>
+```
+
+| `aria-invalid` value | Visual feedback                |
+|----------------------|--------------------------------|
+| `"false"`            | Green/success indicator        |
+| `"true"`             | Red/error indicator            |
+
+---
+
+## In a form context
+
+Switches work well inside cards (`<article>`) for settings or preference panels.
+
+```html
+<article>
+    <header>Preferences</header>
+    <label>
+        <input type="checkbox" role="switch" checked>
+        Receive email updates
+    </label>
+    <label>
+        <input type="checkbox" role="switch">
+        Make profile public
+    </label>
+    <label>
+        <input type="checkbox" role="switch" checked>
+        Enable two-factor authentication
+    </label>
+</article>
+```
+
+---
+
+## Accessibility
+
+- The `role="switch"` attribute tells screen readers to announce the control as a toggle switch rather than a checkbox.
+- Always wrap the input inside a `<label>` to provide an accessible label.
+- Screen readers will announce the state as "on" or "off" rather than "checked" or "unchecked".
+- Use `aria-invalid` to communicate validation state to assistive technologies.
+- The `disabled` attribute is natively understood by all screen readers.
+
+---
+
+→ [Voir l'exemple](../examples/switch.html)