@digicreon/mucss 1.0.0

package/documentation/mu.card.md

@@ -0,0 +1,135 @@
+# µCard
+
+**µCard** provides colored card variants for the `<article>` element, part of the [µCSS](.) framework. It extends PicoCSS's default card styling with 8 color accents, automatic header/footer shading, and a left border indicator.
+
+---
+
+## Usage
+
+Cards use the standard HTML `<article>` element. Add a color class to apply a colored variant with a left border accent and tinted background.
+
+```html
+<article class="card-primary">
+	<header>Card title</header>
+	Card body content.
+	<footer>Card footer</footer>
+</article>
+```
+
+A card can contain any combination of `<header>`, body content, and `<footer>`. All three sections are optional.
+
+### Body only
+
+```html
+<article class="card-info">
+	<p>A simple card with content only, no header or footer.</p>
+</article>
+```
+
+### Default card (no color)
+
+Without a color class, `<article>` renders with the standard PicoCSS card styling:
+
+```html
+<article>
+	<header>Standard card</header>
+	This card uses the default styling without any color class.
+	<footer>Footer</footer>
+</article>
+```
+
+---
+
+## Color variants
+
+8 color classes are available, matching the µCSS color roles:
+
+| Class             | Color role | Left border          | Background                 |
+|-------------------|------------|----------------------|----------------------------|
+| `.card-primary`   | Primary    | `--pico-primary`     | `--pico-primary-background`   |
+| `.card-secondary` | Secondary  | `--pico-secondary`   | `--pico-secondary-background` |
+| `.card-tertiary`  | Tertiary   | `--pico-tertiary`    | `--pico-tertiary-background`  |
+| `.card-contrast`  | Contrast   | `--pico-contrast`    | `--pico-contrast-background`  |
+| `.card-success`   | Success    | `--pico-success`     | `--pico-success-background`   |
+| `.card-info`      | Info       | `--pico-info`        | `--pico-info-background`      |
+| `.card-warning`   | Warning    | `--pico-warning`     | `--pico-warning-background`   |
+| `.card-error`     | Error      | `--pico-error`       | `--pico-error-background`     |
+
+### All 8 variants example
+
+```html
+<div class="row">
+	<div class="col-12 col-md-6">
+		<article class="card-primary">
+			<header>Primary</header>
+			Card body with primary accent.
+			<footer>Card footer</footer>
+		</article>
+	</div>
+	<div class="col-12 col-md-6">
+		<article class="card-secondary">
+			<header>Secondary</header>
+			Card body with secondary accent.
+			<footer>Card footer</footer>
+		</article>
+	</div>
+	<div class="col-12 col-md-6">
+		<article class="card-success">
+			<header>Success</header>
+			Card body with success accent.
+			<footer>Card footer</footer>
+		</article>
+	</div>
+	<div class="col-12 col-md-6">
+		<article class="card-error">
+			<header>Error</header>
+			Card body with error accent.
+			<footer>Card footer</footer>
+		</article>
+	</div>
+</div>
+```
+
+---
+
+## Visual structure
+
+Colored cards (`article[class*="card-"]`) apply the following styles:
+
+- **Left border**: 4px solid in the card's color role.
+- **Background**: the card's light background tint.
+- **Header/footer background**: a `color-mix()` blend of 12% card color into the card background, creating a subtle shading difference.
+- **Header border-bottom / footer border-top**: `color-mix()` blend of 20% card color, providing a gentle separator.
+
+---
+
+## PicoCSS override
+
+µCard includes one global fix:
+
+```css
+article > *:last-child:not(header):not(footer) {
+	margin-bottom: 0;
+}
+```
+
+This removes the bottom margin on the last content element inside a card (e.g., a `<p>` tag), preventing unwanted spacing before the card's bottom edge or footer. This is necessary because PicoCSS applies default margins to `<p>` elements.
+
+---
+
+## CSS classes reference
+
+| Class             | Description                                      |
+|-------------------|--------------------------------------------------|
+| `.card-primary`   | Primary color variant                            |
+| `.card-secondary` | Secondary color variant                          |
+| `.card-tertiary`  | Tertiary color variant                           |
+| `.card-contrast`  | Contrast color variant                           |
+| `.card-success`   | Success color variant                            |
+| `.card-info`      | Info color variant                               |
+| `.card-warning`   | Warning color variant                            |
+| `.card-error`     | Error color variant                              |
+
+---
+
+→ [Voir l'exemple](../examples/card.html)

package/documentation/mu.checkbox-radio.md

@@ -0,0 +1,121 @@
+# µCheckbox & Radio
+
+**µCheckbox & Radio** describes the native checkbox and radio button styling provided by [µCSS](.) via PicoCSS. These are standard HTML form controls (`<input type="checkbox">` and `<input type="radio">`) that PicoCSS styles automatically without any additional classes.
+
+---
+
+## Checkboxes
+
+### Basic usage
+
+Wrap each `<input type="checkbox">` inside a `<label>` for proper styling and accessibility. Use a `<fieldset>` with `<legend>` to group related checkboxes.
+
+```html
+<fieldset>
+    <legend>Select your interests</legend>
+    <label><input type="checkbox" checked> Design</label>
+    <label><input type="checkbox"> Development</label>
+    <label><input type="checkbox"> Marketing</label>
+    <label><input type="checkbox" disabled> Disabled option</label>
+</fieldset>
+```
+
+### Indeterminate state
+
+The indeterminate state is set via JavaScript and represents a "partially checked" visual state.
+
+```html
+<label>
+    <input type="checkbox" id="indeterminate-check"> Indeterminate state
+</label>
+<script>document.getElementById('indeterminate-check').indeterminate = true;</script>
+```
+
+### Checkbox validation
+
+Use `aria-invalid` to visually indicate valid or invalid checkboxes.
+
+```html
+<label><input type="checkbox" aria-invalid="false" checked> Valid checkbox</label>
+<label><input type="checkbox" aria-invalid="true"> Invalid checkbox</label>
+```
+
+---
+
+## Radio buttons
+
+### Basic usage
+
+Radio buttons use `<input type="radio">` with a shared `name` attribute to form a mutually exclusive group. Wrap them in a `<fieldset>` with `<legend>`.
+
+```html
+<fieldset>
+    <legend>Choose a plan</legend>
+    <label><input type="radio" name="plan" checked> Free</label>
+    <label><input type="radio" name="plan"> Pro</label>
+    <label><input type="radio" name="plan"> Enterprise</label>
+    <label><input type="radio" name="plan" disabled> Deprecated plan</label>
+</fieldset>
+```
+
+### Radio validation
+
+Use `aria-invalid` on individual radio inputs to indicate validation state.
+
+```html
+<fieldset>
+    <legend>Select a valid option</legend>
+    <label><input type="radio" name="valid-radio" aria-invalid="false" checked> Valid choice</label>
+    <label><input type="radio" name="invalid-radio" aria-invalid="true"> Invalid choice</label>
+</fieldset>
+```
+
+---
+
+## In a form
+
+Checkboxes and radio buttons can be combined inside a card (`<article>`) for structured forms.
+
+```html
+<article>
+    <header>Registration</header>
+    <fieldset>
+        <legend>Account type</legend>
+        <label><input type="radio" name="type" checked> Personal</label>
+        <label><input type="radio" name="type"> Business</label>
+    </fieldset>
+    <fieldset>
+        <legend>Agreements</legend>
+        <label><input type="checkbox" required> I accept the terms and conditions</label>
+        <label><input type="checkbox"> Subscribe to newsletter</label>
+    </fieldset>
+</article>
+```
+
+---
+
+## States reference
+
+| Attribute          | Effect                                           |
+|--------------------|--------------------------------------------------|
+| `checked`          | Sets the default checked state                   |
+| `disabled`         | Prevents interaction, muted visual style         |
+| `required`         | Marks the field as mandatory for form submission |
+| `aria-invalid="false"` | Green/success visual indicator              |
+| `aria-invalid="true"`  | Red/error visual indicator                  |
+| `indeterminate` (JS) | Partially checked visual state (checkbox only) |
+
+---
+
+## Accessibility
+
+- Always wrap inputs in a `<label>` to associate the label text with the control.
+- Use `<fieldset>` and `<legend>` to group related checkboxes or radio buttons. Screen readers announce the group label when entering the fieldset.
+- Radio buttons sharing the same `name` attribute are announced as a group by screen readers.
+- The `disabled` attribute natively prevents focus and interaction and is communicated to assistive technologies.
+- Use `aria-invalid` to communicate validation state to screen readers.
+- The `required` attribute is announced by screen readers and triggers native browser validation.
+
+---
+
+→ [Voir l'exemple](../examples/checkbox-radio.html)

package/documentation/mu.dropdown.md

@@ -0,0 +1,183 @@
+# µDropdown
+
+**µDropdown** fournit des menus deroulants CSS purs via l'element `<details class="dropdown">`, styles par [PicoCSS](https://picocss.com) au sein du framework [µCSS](.). Aucun JavaScript n'est necessaire : l'ouverture et la fermeture sont gerees nativement par le navigateur.
+
+---
+
+## Utilisation de base
+
+Un dropdown est construit avec `<details class="dropdown">`. Le `<summary>` sert de declencheur et la liste `<ul>` contient les options.
+
+```html
+<details class="dropdown">
+    <summary>Select an option</summary>
+    <ul>
+        <li><a href="#">Option 1</a></li>
+        <li><a href="#">Option 2</a></li>
+        <li><a href="#">Option 3</a></li>
+    </ul>
+</details>
+```
+
+---
+
+## Style bouton
+
+Ajoutez `role="button"` sur le `<summary>` pour lui donner l'apparence d'un bouton.
+
+```html
+<details class="dropdown">
+    <summary role="button">Actions</summary>
+    <ul>
+        <li><a href="#">Edit</a></li>
+        <li><a href="#">Duplicate</a></li>
+        <li><a href="#">Archive</a></li>
+        <li><a href="#">Delete</a></li>
+    </ul>
+</details>
+```
+
+---
+
+## Variantes natives PicoCSS
+
+PicoCSS fournit des variantes de style via des classes sur le `<summary role="button">` :
+
+| Classe | Apparence |
+|--------|-----------|
+| *(aucune)* | Primary (defaut) |
+| `.secondary` | Secondary |
+| `.contrast` | Contrast |
+| `.outline` | Outline |
+
+```html
+<details class="dropdown">
+    <summary role="button">Primary</summary>
+    <ul>
+        <li><a href="#">Item A</a></li>
+        <li><a href="#">Item B</a></li>
+    </ul>
+</details>
+
+<details class="dropdown">
+    <summary role="button" class="secondary">Secondary</summary>
+    <ul>
+        <li><a href="#">Item A</a></li>
+        <li><a href="#">Item B</a></li>
+    </ul>
+</details>
+
+<details class="dropdown">
+    <summary role="button" class="contrast">Contrast</summary>
+    <ul>
+        <li><a href="#">Item A</a></li>
+        <li><a href="#">Item B</a></li>
+    </ul>
+</details>
+
+<details class="dropdown">
+    <summary role="button" class="outline">Outline</summary>
+    <ul>
+        <li><a href="#">Item A</a></li>
+        <li><a href="#">Item B</a></li>
+    </ul>
+</details>
+```
+
+---
+
+## Variantes de couleur µCSS
+
+µCSS etend les dropdowns avec les classes `.btn-*` sur le `<summary>` pour les 8 roles de couleur :
+
+| Classe | Couleur |
+|--------|---------|
+| `.btn-primary` | Primary |
+| `.btn-secondary` | Secondary |
+| `.btn-tertiary` | Tertiary |
+| `.btn-contrast` | Contrast |
+| `.btn-success` | Success |
+| `.btn-info` | Info |
+| `.btn-warning` | Warning |
+| `.btn-error` | Error |
+
+```html
+<details class="dropdown">
+    <summary role="button" class="btn-primary">Primary</summary>
+    <ul>
+        <li><a href="#">Item A</a></li>
+        <li><a href="#">Item B</a></li>
+    </ul>
+</details>
+
+<details class="dropdown">
+    <summary role="button" class="btn-success">Success</summary>
+    <ul>
+        <li><a href="#">Item A</a></li>
+        <li><a href="#">Item B</a></li>
+    </ul>
+</details>
+
+<details class="dropdown">
+    <summary role="button" class="btn-error">Error</summary>
+    <ul>
+        <li><a href="#">Item A</a></li>
+        <li><a href="#">Item B</a></li>
+    </ul>
+</details>
+```
+
+---
+
+## Remplacement de select
+
+Un dropdown peut servir d'alternative stylee a un `<select>` natif en le placant dans un `<label>`.
+
+```html
+<label>Choose a fruit
+    <details class="dropdown">
+        <summary>Pick one...</summary>
+        <ul>
+            <li><a href="#">Apple</a></li>
+            <li><a href="#">Banana</a></li>
+            <li><a href="#">Cherry</a></li>
+            <li><a href="#">Mango</a></li>
+            <li><a href="#">Orange</a></li>
+        </ul>
+    </details>
+</label>
+```
+
+**Note :** contrairement a un `<select>` natif, la valeur selectionnee n'est pas geree automatiquement. Un minimum de JavaScript applicatif est necessaire pour mettre a jour le texte du `<summary>` apres selection.
+
+---
+
+## Structure
+
+```
+<details class="dropdown">
+    <summary [role="button"] [class="btn-*"]>Trigger text</summary>
+    <ul>
+        <li><a href="#">Menu item</a></li>
+        ...
+    </ul>
+</details>
+```
+
+| Element | Role |
+|---------|------|
+| `<details class="dropdown">` | Conteneur du dropdown |
+| `<summary>` | Declencheur (texte ou bouton) |
+| `<summary role="button">` | Declencheur avec apparence bouton |
+| `<ul>` | Liste des options |
+| `<li><a>` | Element de menu cliquable |
+
+---
+
+## Accessibilite
+
+- Le composant repose sur l'element natif `<details>`/`<summary>`, accessible par defaut au clavier (ouverture via `Enter` ou `Space`).
+- L'attribut `role="button"` sur `<summary>` informe les technologies d'assistance que l'element agit comme un bouton.
+- Le menu se ferme automatiquement lorsque l'utilisateur clique en dehors (comportement natif de `<details>`).
+
+→ [Voir l'exemple](../examples/dropdown.html)

package/documentation/mu.forms-advanced.md

@@ -0,0 +1,164 @@
+# µForms (advanced)
+
+**µForms (advanced)** describes the specialized native input types styled by [µCSS](.) via PicoCSS. These include color pickers, date/time inputs, file uploads, search fields, and other input types, all styled automatically without additional classes.
+
+---
+
+## Color picker
+
+The `<input type="color">` renders a native color picker widget.
+
+```html
+<label>Pick a color
+    <input type="color" value="#0172ad">
+</label>
+```
+
+---
+
+## Date & time inputs
+
+PicoCSS styles all native date and time input types consistently.
+
+```html
+<label>Date
+    <input type="date">
+</label>
+<label>Time
+    <input type="time">
+</label>
+<label>Date and time
+    <input type="datetime-local">
+</label>
+<label>Month
+    <input type="month">
+</label>
+<label>Week
+    <input type="week">
+</label>
+```
+
+| Input type         | Description                          |
+|--------------------|--------------------------------------|
+| `date`             | Date picker (year-month-day)         |
+| `time`             | Time picker (hours-minutes)          |
+| `datetime-local`   | Combined date and time picker        |
+| `month`            | Month and year picker                |
+| `week`             | Week and year picker                 |
+
+---
+
+## File upload
+
+The `<input type="file">` renders a styled file selection button. Add `multiple` to allow selecting more than one file.
+
+```html
+<label>Choose a file
+    <input type="file">
+</label>
+<label>Multiple files
+    <input type="file" multiple>
+</label>
+```
+
+---
+
+## Search
+
+The `<input type="search">` renders a text field with a search-specific style (including a clear button in some browsers).
+
+```html
+<label>Search
+    <input type="search" placeholder="Search...">
+</label>
+```
+
+### Search with group
+
+Wrap a search input and button inside a `<div role="search">` for a grouped search bar layout.
+
+```html
+<div role="search">
+    <input type="search" placeholder="Search...">
+    <button>Go</button>
+</div>
+```
+
+---
+
+## Other input types
+
+PicoCSS styles several additional input types natively.
+
+```html
+<label>Number
+    <input type="number" value="42" min="0" max="100">
+</label>
+<label>URL
+    <input type="url" placeholder="https://example.com">
+</label>
+<label>Telephone
+    <input type="tel" placeholder="+1 (555) 123-4567">
+</label>
+<label>Password
+    <input type="password" value="secret123">
+</label>
+```
+
+---
+
+## Disabled & readonly
+
+Use `disabled` to prevent all interaction, or `readonly` to allow selection and copying but prevent editing.
+
+```html
+<label>Disabled input
+    <input type="text" value="Cannot edit" disabled>
+</label>
+<label>Readonly input
+    <input type="text" value="Read only" readonly>
+</label>
+```
+
+| Attribute   | User can select text | User can edit | Submitted with form |
+|-------------|---------------------|---------------|---------------------|
+| `disabled`  | No                  | No            | No                  |
+| `readonly`  | Yes                 | No            | Yes                 |
+
+---
+
+## Validation states & helper text
+
+Use `aria-invalid` to indicate validation state visually. Add a `<small>` element after the input inside the `<label>` for helper or error messages.
+
+```html
+<label>Email
+    <input type="email" placeholder="user@example.com" aria-invalid="true">
+    <small>Please enter a valid email address.</small>
+</label>
+<label>Username
+    <input type="text" value="johndoe" aria-invalid="false">
+    <small>Username is available.</small>
+</label>
+```
+
+| `aria-invalid` value | Visual feedback                          |
+|----------------------|------------------------------------------|
+| `"true"`             | Red/error border and helper text color   |
+| `"false"`            | Green/success border and helper text color |
+
+---
+
+## Accessibility
+
+- Always wrap inputs in a `<label>` to provide an accessible name.
+- Use `aria-invalid` to communicate validation state to screen readers.
+- The `<small>` helper text following an input is visually associated; for explicit screen reader association, use `aria-describedby`.
+- `disabled` and `readonly` states are natively communicated to assistive technologies.
+- The `role="search"` landmark on the search group container helps screen readers identify the search region.
+- File inputs announce the selected file name(s) to screen readers.
+- Date and time pickers use native browser widgets that provide built-in keyboard and screen reader support.
+
+---
+
+→ [Voir l'exemple](../examples/forms-advanced.html)