@digicreon/mucss 1.0.0

package/documentation/mu.forms.md

@@ -0,0 +1,147 @@
+# µForms
+
+**µForms** extends PicoCSS form controls with size variants and validation states, part of the [µCSS](.) framework. It applies to `<input>`, `<textarea>`, and `<select>` elements.
+
+---
+
+## Input sizes
+
+Two size modifiers adjust padding and font size. Without a size class, the default PicoCSS styling applies.
+
+```html
+<label>Small input
+	<input type="text" class="input-sm" placeholder="Small input">
+</label>
+<label>Default input
+	<input type="text" placeholder="Default input">
+</label>
+<label>Large input
+	<input type="text" class="input-lg" placeholder="Large input">
+</label>
+```
+
+### Size reference
+
+| Class       | Padding                  | Font size     | Applies to                       |
+|-------------|--------------------------|---------------|----------------------------------|
+| `.input-sm` | `0.375rem 0.625rem`      | `0.8125rem`   | `input`, `textarea`, `select`    |
+| *(default)* | *(PicoCSS default)*      | *(default)*   | `input`, `textarea`, `select`    |
+| `.input-lg` | `0.75rem 1rem`           | `1.125rem`    | `input`, `textarea`, `select`    |
+
+### Textarea sizes
+
+```html
+<label>Small textarea
+	<textarea class="input-sm" placeholder="Small textarea"></textarea>
+</label>
+<label>Large textarea
+	<textarea class="input-lg" placeholder="Large textarea"></textarea>
+</label>
+```
+
+### Select sizes
+
+```html
+<label>Small select
+	<select class="input-sm">
+		<option>Option 1</option>
+		<option>Option 2</option>
+	</select>
+</label>
+<label>Large select
+	<select class="input-lg">
+		<option>Option 1</option>
+		<option>Option 2</option>
+	</select>
+</label>
+```
+
+---
+
+## Validation states
+
+µForms provides two validation classes that set border color and focus ring color. For error states, use the native `aria-invalid="true"` attribute (handled by PicoCSS).
+
+```html
+<label>Success
+	<input type="text" class="input-success" value="Valid value">
+</label>
+<label>Warning
+	<input type="text" class="input-warning" value="Needs attention">
+</label>
+<label>Error (native)
+	<input type="text" aria-invalid="true" value="Invalid value">
+</label>
+```
+
+### Validation reference
+
+| Class / Attribute        | Border color          | Focus ring color          |
+|--------------------------|-----------------------|---------------------------|
+| `.input-success`         | `--pico-success`      | `--pico-success-focus`    |
+| `.input-warning`         | `--pico-warning`      | `--pico-warning-focus`    |
+| `aria-invalid="true"`    | *(PicoCSS built-in)*  | *(PicoCSS built-in)*     |
+
+### Validation on textarea
+
+```html
+<label>Success textarea
+	<textarea class="input-success">This content is valid.</textarea>
+</label>
+<label>Warning textarea
+	<textarea class="input-warning">This content needs review.</textarea>
+</label>
+```
+
+### Validation on select
+
+```html
+<label>Success select
+	<select class="input-success">
+		<option>Valid choice</option>
+	</select>
+</label>
+<label>Warning select
+	<select class="input-warning">
+		<option>Needs review</option>
+	</select>
+</label>
+```
+
+---
+
+## Combining size and validation
+
+Size and validation classes can be used together on the same element:
+
+```html
+<label>Small + success
+	<input type="text" class="input-sm input-success" value="Small valid">
+</label>
+<label>Large + warning
+	<input type="text" class="input-lg input-warning" value="Large needs attention">
+</label>
+```
+
+---
+
+## CSS classes reference
+
+| Class             | Type       | Description                                          |
+|-------------------|------------|------------------------------------------------------|
+| `.input-sm`       | Size       | Smaller padding and font size                        |
+| `.input-lg`       | Size       | Larger padding and font size                         |
+| `.input-success`  | Validation | Green border, green focus ring                       |
+| `.input-warning`  | Validation | Orange/yellow border, orange/yellow focus ring       |
+
+---
+
+## Accessibility
+
+- Use `aria-invalid="true"` for error states (PicoCSS native support).
+- Always wrap form controls inside `<label>` elements for proper association.
+- Validation colors supplement, but do not replace, text-based error messages.
+
+---
+
+→ [Voir l'exemple](../examples/forms.html)

package/documentation/mu.grid.md

@@ -0,0 +1,175 @@
+# µGrid
+
+**µGrid** is a lightweight flexbox-based 12-column responsive grid system, part of the [µCSS](.) framework. It provides a Bootstrap-compatible grid fallback for CSS frameworks that lack a built-in responsive grid (such as PicoCSS).
+
+**Weight:** ~4 KB uncompressed, ~1 KB gzipped.
+
+---
+
+## Breakpoints
+
+µGrid uses a mobile-first approach with 4 breakpoints:
+
+| Name | Prefix | Min-width | Typical use          |
+|------|--------|-----------|----------------------|
+| —    | *(none)* | 0       | Mobile (default)     |
+| sm   | `-sm-` | 640px     | Mobile landscape     |
+| md   | `-md-` | 960px     | Tablet               |
+| lg   | `-lg-` | 1200px    | Desktop              |
+| xl   | `-xl-` | 1400px    | Large desktop        |
+
+All classes without a breakpoint prefix apply to all screen sizes. Prefixed classes apply from the specified breakpoint and up.
+
+---
+
+## Container
+
+Containers center and constrain content horizontally.
+
+```html
+<!-- Fixed-width container (max-width: 1200px) -->
+<div class="container">...</div>
+
+<!-- Full-width container -->
+<div class="container-fluid">...</div>
+```
+
+Both containers have `1rem` horizontal padding.
+
+---
+
+## Row
+
+A `.row` creates a flex container for columns. It uses negative margins to compensate for column gutters.
+
+```html
+<div class="container">
+    <div class="row">
+        <div class="col-6">Half</div>
+        <div class="col-6">Half</div>
+    </div>
+</div>
+```
+
+---
+
+## Columns
+
+Columns are defined using `.col-{n}` and `.col-{bp}-{n}` classes, where `{n}` is a number from 1 to 12.
+
+Each column has a `0.75rem` padding on each side (1.5rem gutter between columns).
+
+### Basic usage
+
+```html
+<div class="row">
+    <div class="col-12">Full width</div>
+</div>
+
+<div class="row">
+    <div class="col-4">One third</div>
+    <div class="col-8">Two thirds</div>
+</div>
+```
+
+### Responsive columns
+
+```html
+<div class="row">
+    <!-- Full width on mobile, half on tablet, one third on desktop -->
+    <div class="col-12 col-md-6 col-lg-4">Content</div>
+    <div class="col-12 col-md-6 col-lg-4">Content</div>
+    <div class="col-12 col-md-12 col-lg-4">Content</div>
+</div>
+```
+
+### Column reference
+
+| Class pattern    | Width      |
+|------------------|------------|
+| `.col-{bp}-1`    | 8.3333%    |
+| `.col-{bp}-2`    | 16.6667%   |
+| `.col-{bp}-3`    | 25%        |
+| `.col-{bp}-4`    | 33.3333%   |
+| `.col-{bp}-5`    | 41.6667%   |
+| `.col-{bp}-6`    | 50%        |
+| `.col-{bp}-7`    | 58.3333%   |
+| `.col-{bp}-8`    | 66.6667%   |
+| `.col-{bp}-9`    | 75%        |
+| `.col-{bp}-10`   | 83.3333%   |
+| `.col-{bp}-11`   | 91.6667%   |
+| `.col-{bp}-12`   | 100%       |
+
+---
+
+## Offsets
+
+Offsets push a column to the right by a given number of columns using `margin-left`.
+
+```html
+<div class="row">
+    <div class="col-6 offset-3">Centered content</div>
+</div>
+```
+
+### Responsive offsets
+
+```html
+<div class="row">
+    <div class="col-12 col-md-8 col-lg-4 offset-md-2 offset-lg-4">Content</div>
+</div>
+```
+
+Use `.offset-{bp}-0` to reset an offset at a given breakpoint.
+
+---
+
+## Ordering
+
+Change the visual order of columns without changing the HTML source order.
+
+```html
+<div class="row">
+    <div class="col-6 order-2">Appears second</div>
+    <div class="col-6 order-1">Appears first</div>
+</div>
+```
+
+### Special values
+
+| Class                  | Effect       |
+|------------------------|--------------|
+| `.order-{bp}-first`    | `order: -1`  |
+| `.order-{bp}-last`     | `order: 13`  |
+| `.order-{bp}-0` to `.order-{bp}-12` | `order: 0` to `order: 12` |
+
+---
+
+## Display / Visibility
+
+| Class             | Effect              |
+|-------------------|---------------------|
+| `.d-{bp}-none`    | `display: none`     |
+| `.d-{bp}-block`   | `display: block`    |
+| `.d-{bp}-flex`    | `display: flex`     |
+
+When showing a `.row` that was previously hidden, use `d-{bp}-flex` instead of `d-{bp}-block` to preserve the flex layout.
+
+```html
+<div class="row d-none d-md-flex">
+    <div class="col-md-6">A</div>
+    <div class="col-md-6">B</div>
+</div>
+```
+
+---
+
+## Bootstrap compatibility
+
+µGrid uses the same class naming conventions as Bootstrap 5. Main differences:
+
+- **4 breakpoints** instead of 5: Bootstrap's `xl` and `xxl` are merged into `xl`.
+- **Breakpoint values differ slightly**: `sm` is 640px (vs 576px), `md` is 960px (vs 768px).
+- **No auto-sizing columns**: `.col` (without a number) is not supported.
+- **No `row-cols-*`**: automatic column count per row is not supported.
+- **No flex alignment utilities**: `justify-content-*`, `align-items-*` are not included.

package/documentation/mu.group.md

@@ -0,0 +1,102 @@
+# µGroup
+
+**µGroup** permet de regrouper visuellement des champs de formulaire et des boutons en une seule ligne, grace a l'attribut `role="group"` style par [PicoCSS](https://picocss.com) au sein du framework [µCSS](.). Les elements groupes partagent des bordures communes et s'alignent horizontalement.
+
+---
+
+## Groupe de boutons
+
+L'attribut `role="group"` sur un conteneur regroupe les boutons en une barre horizontale avec des bordures fusionnees.
+
+```html
+<div role="group">
+    <button>Left</button>
+    <button>Center</button>
+    <button>Right</button>
+</div>
+```
+
+---
+
+## Input + bouton
+
+Combinez un champ de saisie et un bouton dans un meme groupe pour creer un formulaire inline compact.
+
+```html
+<div role="group">
+    <input type="email" placeholder="Enter your email">
+    <button>Subscribe</button>
+</div>
+```
+
+---
+
+## Groupe de recherche
+
+Utilisez `role="search"` pour un groupe semantiquement identifie comme zone de recherche. Le rendu visuel est identique a `role="group"`.
+
+```html
+<div role="search">
+    <input type="search" placeholder="Search...">
+    <button>Search</button>
+</div>
+```
+
+---
+
+## Input + select + bouton
+
+Un groupe peut contenir plus de deux elements, par exemple un `<select>`, un `<input>` et un `<button>`.
+
+```html
+<div role="group">
+    <select>
+        <option>USD</option>
+        <option>EUR</option>
+        <option>GBP</option>
+    </select>
+    <input type="number" placeholder="Amount">
+    <button>Convert</button>
+</div>
+```
+
+---
+
+## Boutons outline
+
+Les boutons `.outline` fonctionnent egalement dans un groupe, offrant un style de barre de selection (toggle bar).
+
+```html
+<div role="group">
+    <button class="outline">Day</button>
+    <button class="outline">Week</button>
+    <button class="outline">Month</button>
+</div>
+```
+
+---
+
+## Resume des roles
+
+| Attribut | Usage |
+|----------|-------|
+| `role="group"` | Groupe generique (boutons, inputs, selects) |
+| `role="search"` | Groupe de recherche (semantique) |
+
+## Elements supportes dans un groupe
+
+| Element | Comportement |
+|---------|-------------|
+| `<button>` | Bouton d'action |
+| `<input>` | Champ de saisie (text, email, search, number, etc.) |
+| `<select>` | Liste de selection |
+
+---
+
+## Accessibilite
+
+- `role="group"` informe les technologies d'assistance que les elements sont lies et forment un ensemble logique.
+- `role="search"` identifie semantiquement la zone comme fonctionnalite de recherche, ce qui aide la navigation au lecteur d'ecran.
+- Les elements du groupe restent accessibles individuellement au clavier (navigation par `Tab`).
+
+→ [Voir l'exemple](../examples/group.html)

package/documentation/mu.loading.md

@@ -0,0 +1,99 @@
+# µLoading
+
+**µLoading** describes the loading indicator states available natively in [µCSS](.) via PicoCSS. Loading states are activated using the standard `aria-busy="true"` attribute on any element, which displays an animated spinner without requiring any additional CSS class or JavaScript library.
+
+---
+
+## Usage
+
+Add `aria-busy="true"` to any HTML element to show a loading spinner. The spinner is rendered via CSS and adapts to the element's context (inline for buttons and paragraphs, block-level for containers).
+
+```html
+<button aria-busy="true">Please wait...</button>
+```
+
+Remove the loading state by setting `aria-busy="false"` or removing the attribute entirely.
+
+---
+
+## Button loading
+
+Apply `aria-busy="true"` on `<button>` elements to show a spinner alongside the button text. This works with all button variants.
+
+```html
+<button aria-busy="true">Please wait...</button>
+<button aria-busy="true" class="secondary">Loading</button>
+<button aria-busy="true" class="contrast">Processing</button>
+```
+
+---
+
+## Standalone spinner
+
+Use an empty `<div>` with `aria-busy="true"` to display a standalone centered spinner. Set a `min-height` so the spinner has space to render.
+
+```html
+<div aria-busy="true" style="min-height: 3rem;"></div>
+```
+
+---
+
+## Loading on a card
+
+Apply `aria-busy="true"` on an `<article>` to indicate the entire card is in a loading state.
+
+```html
+<article aria-busy="true">
+    <p>This card is loading...</p>
+</article>
+```
+
+---
+
+## Loading paragraph
+
+Apply `aria-busy="true"` directly on a `<p>` element to show a spinner inline with text content.
+
+```html
+<p aria-busy="true">Loading content...</p>
+```
+
+---
+
+## Toggle loading dynamically
+
+Use JavaScript to toggle the `aria-busy` attribute on any element to control the loading state at runtime.
+
+```html
+<button onclick="var t = document.getElementById('target'); t.ariaBusy = t.ariaBusy === 'true' ? 'false' : 'true';">
+    Toggle loading state
+</button>
+<article id="target" aria-busy="false">
+    <p>Click the button above to toggle the loading state on this card.</p>
+</article>
+```
+
+---
+
+## Supported elements
+
+| Element       | Behavior                                      |
+|---------------|-----------------------------------------------|
+| `<button>`    | Spinner displayed inline before the text      |
+| `<div>`       | Centered block-level spinner                  |
+| `<article>`   | Spinner overlays the card content             |
+| `<p>`         | Spinner displayed inline with text            |
+
+Any element that accepts `aria-busy` can display the loading indicator.
+
+---
+
+## Accessibility
+
+- `aria-busy="true"` is a standard WAI-ARIA attribute. Screen readers will announce the element as busy/loading.
+- Always provide descriptive text content (e.g., "Please wait...") alongside the spinner for assistive technologies.
+- Set `aria-busy="false"` when loading completes to notify screen readers that content is ready.
+
+---
+
+→ [Voir l'exemple](../examples/loading.html)

package/documentation/mu.modal.md

@@ -0,0 +1,163 @@
+# µModal
+
+**µModal** provides size variants and a close button for native `<dialog>` modals, part of the [µCSS](.) framework. It builds on PicoCSS's dialog styling with small, large, and fullscreen options.
+
+---
+
+## Usage
+
+Modals use the native HTML `<dialog>` element containing an `<article>`. Open with JavaScript's `.showModal()` method and close with `.close()`.
+
+```html
+<dialog id="my-modal">
+	<article>
+		<button class="modal-close" aria-label="Close"
+			onclick="document.getElementById('my-modal').close()">&times;</button>
+		<h3>Modal title</h3>
+		<p>Modal content goes here.</p>
+		<footer>
+			<button class="btn btn-primary"
+				onclick="document.getElementById('my-modal').close()">Close</button>
+		</footer>
+	</article>
+</dialog>
+
+<!-- Trigger button -->
+<button onclick="document.getElementById('my-modal').showModal()">Open modal</button>
+```
+
+---
+
+## Size variants
+
+4 sizes are available. Without a size class, the default PicoCSS dialog width applies.
+
+| Class               | Max-width    | Description                          |
+|---------------------|--------------|--------------------------------------|
+| `.modal-sm`         | 400px        | Confirmations and simple prompts     |
+| *(default)*         | *(PicoCSS)*  | Suitable for most content            |
+| `.modal-lg`         | 900px        | Forms or detailed content            |
+| `.modal-fullscreen` | 100vw        | Full viewport, no border-radius      |
+
+Size classes are applied on the `<dialog>` element, not on the inner `<article>`.
+
+### Small modal
+
+```html
+<dialog id="modal-sm" class="modal-sm">
+	<article>
+		<button class="modal-close" aria-label="Close"
+			onclick="document.getElementById('modal-sm').close()">&times;</button>
+		<h3>Small modal</h3>
+		<p>This is a small modal (max-width: 400px). Ideal for confirmations and simple prompts.</p>
+		<footer>
+			<button class="btn btn-ghost btn-secondary"
+				onclick="document.getElementById('modal-sm').close()">Cancel</button>
+			<button class="btn btn-primary"
+				onclick="document.getElementById('modal-sm').close()">Confirm</button>
+		</footer>
+	</article>
+</dialog>
+```
+
+### Large modal
+
+```html
+<dialog id="modal-lg" class="modal-lg">
+	<article>
+		<button class="modal-close" aria-label="Close"
+			onclick="document.getElementById('modal-lg').close()">&times;</button>
+		<h3>Large modal</h3>
+		<p>This is a large modal (max-width: 900px). Useful for forms or detailed content.</p>
+		<div class="row">
+			<div class="col-6">
+				<label>First name <input type="text" placeholder="First name"></label>
+			</div>
+			<div class="col-6">
+				<label>Last name <input type="text" placeholder="Last name"></label>
+			</div>
+		</div>
+		<label>Email <input type="email" placeholder="Email address"></label>
+		<footer>
+			<button class="btn btn-ghost btn-secondary"
+				onclick="document.getElementById('modal-lg').close()">Cancel</button>
+			<button class="btn btn-success"
+				onclick="document.getElementById('modal-lg').close()">Save</button>
+		</footer>
+	</article>
+</dialog>
+```
+
+### Fullscreen modal
+
+```html
+<dialog id="modal-fullscreen" class="modal-fullscreen">
+	<article>
+		<button class="modal-close" aria-label="Close"
+			onclick="document.getElementById('modal-fullscreen').close()">&times;</button>
+		<h3>Fullscreen modal</h3>
+		<p>This modal covers the entire viewport. Suitable for immersive experiences,
+		image galleries, or complex workflows.</p>
+		<footer>
+			<button class="btn btn-error"
+				onclick="document.getElementById('modal-fullscreen').close()">Close</button>
+		</footer>
+	</article>
+</dialog>
+```
+
+The fullscreen variant sets `width: 100vw`, `min-height: 100vh`, `border-radius: 0`, and `margin: 0` on the inner `<article>`.
+
+---
+
+## Close button
+
+The `.modal-close` class styles a close button positioned absolutely in the top-right corner of the `<article>`.
+
+```html
+<button class="modal-close" aria-label="Close"
+	onclick="document.getElementById('my-modal').close()">&times;</button>
+```
+
+| Property          | Value                           |
+|-------------------|---------------------------------|
+| Position          | Absolute, top-right corner      |
+| Size              | 3rem x 3rem                     |
+| Background        | Transparent                     |
+| Color             | `--pico-secondary`              |
+| Opacity           | 0.6 (1 on hover)               |
+| Focus indicator   | 2px solid outline, 0.25rem radius |
+
+---
+
+## CSS classes reference
+
+| Class               | Applied to   | Description                               |
+|---------------------|--------------|-------------------------------------------|
+| `.modal-sm`         | `<dialog>`   | Small modal (max-width: 400px)            |
+| `.modal-lg`         | `<dialog>`   | Large modal (max-width: 900px)            |
+| `.modal-fullscreen` | `<dialog>`   | Full viewport modal                       |
+| `.modal-close`      | `<button>`   | Positioned close button (top-right)       |
+
+---
+
+## Opening and closing
+
+Modals rely on the native `<dialog>` API. No JavaScript is bundled with µCSS -- behavior is the application's responsibility.
+
+- **Open**: `document.getElementById('modal-id').showModal()`
+- **Close**: `document.getElementById('modal-id').close()`
+- **Backdrop click**: handled natively by `<dialog>` when opened via `.showModal()`
+- **Escape key**: closes the dialog natively
+
+---
+
+## Accessibility
+
+- Always include `aria-label="Close"` on the `.modal-close` button.
+- The `.modal-close` button has a `:focus-visible` outline for keyboard navigation.
+- Use `.showModal()` (not `.show()`) to get the modal backdrop and trap focus inside the dialog.
+
+---
+
+→ [Voir l'exemple](../examples/modal.html)