@appius-fr/apx 2.6.2 → 2.7.1

package/modules/toast/README.md

@@ -1,153 +1,186 @@
-# APX Toast
-
-A tiny, framework‑agnostic toast library for APX. Minimal CSS, ESM‑first, no globals. DOM is only touched when you actually show a toast (SSR‑safe to import).
-
-## Install / Import
-
-Just import `APX` — the toast CSS is automatically loaded by `modules/toast/toast.mjs`.
-
-```html
-<script type="module">
-  import APX from './APX.mjs';
-  // CSS is auto‑imported; no <link> tag required.
-  // ...
-  APX.toast.success('Ready!');
- </script>
-```
-
-## Quick start
-
-```js
-// Default manager (lazy)
-APX.toast.success('Saved!');
-APX.toast.warning('Heads up', { durationMs: 4000 });
-APX.toast.danger('Something failed', { durationMs: 0 }); // sticky
-
-// Custom toast
-const ref = APX.toast.show({ message: 'Processing…', type: 'info', durationMs: 0 });
-// Callable shorthand for show:
-APX.toast({ message: 'Hello', type: 'success' });
-ref.update({ message: 'Done', type: 'success', durationMs: 1800 });
-ref.whenClosed().then(() => console.log('closed'));
-
-// Configure defaults at runtime
-APX.toast.configure({ position: 'top-right', maxToasts: 4, dedupe: true });
-```
-
-### Named managers (profiles)
-
-```js
-// Register a named manager
-APX.toast.create('admin', { position: 'bottom-left', ariaLive: 'polite' });
-
-// Use it later
-APX.toast.use('admin').info('Admin ready');
-APX.toast.use('admin').closeAll();
-```
-
-## API overview
-
-- Top‑level (default manager):
-  - `APX.toast.show(opts)`
-  - `APX.toast.info|success|warning|danger(message, opts?)`
-  - `APX.toast.configure(config)`
-  - `APX.toast.closeAll(reason?)`
-  - `APX.toast.create(name, config)` → registers named manager
-  - `APX.toast.use(name)` → returns named manager
-
-- Named manager instance (same surface):
-  - `.show(opts)`, `.info|success|warning|danger(message, opts?)`
-  - `.configure(config)`, `.closeAll(reason?)`
-
-## Options and types
-
-```js
-// ToastConfig (global/manager defaults)
-{
-  position: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left', // default 'bottom-right'
-  maxToasts: number,                // default 5
-  defaultDurationMs: number,       // default 5000
-  zIndex: number,                   // default 11000
-  ariaLive: 'polite'|'assertive'|'off', // default 'polite'
-  gap: number,                      // default 8
-  dedupe: boolean,                 // default false
-  containerClass: string,           // extra class on container
-  offset: number,                  // px offset from screen edges
-  progress: false | true | { enable, position?, pauseButton? }  // default false; pauseButton default false (v2.6.1)
-}
-
-// ToastOptions (per toast)
-{
-  message: string | Node,
-  type: 'info'|'success'|'warning'|'danger', // default 'info'
-  durationMs: number,               // default from config; 0 = sticky
-  dismissible: boolean,             // default true
-  id: string,                       // stable id for dedupe updates
-  className: string,                // extra classes on the toast element
-  progress: true | { enable: boolean, position?: 'top'|'bottom', pauseButton?: boolean },  // v2.6.1; pauseButton default false
-  onClick: (ref, ev) => void,
-  onClose: (ref, reason) => void    // reason: 'timeout'|'close'|'api'|'overflow'
-}
-```
-
-## Theming (minimal CSS)
-
-Override CSS variables to theme without touching markup:
-
-```css
-:root {
-  --apx-toast-gap: 10px;
-  --apx-toast-min-width: 280px;
-  --apx-toast-radius: 8px;
-  --apx-toast-success-bg: #16a34a;
-  --apx-toast-success-fg: #fff;
-}
-```
-
-Class structure (BEM‑like):
-- Container: `APX-toast-container APX-toast-container--{corner}`
-- Toast: `APX-toast APX-toast--{type}`
-- Children: `APX-toast__content`, optional `APX-toast__close`
-- Progress (v2.6.1): `APX-toast__progress`, `APX-toast__progress-track`, `APX-toast__progress-bar`, optional `APX-toast__progress-pause`
-- Animations: `APX-toast--enter/--enter-active`, `APX-toast--exit/--exit-active`
-
-## Progress bar (v2.6.1)
-
-Optional visual countdown for toasts with a duration. Bar shows time remaining (100% → 0%); sync with timer and hover pause.
-
-```js
-// Bar on top (default), no pause button by default
-APX.toast.show({ message: 'Saving…', type: 'info', progress: true });
-
-// Bar with pause/resume button
-APX.toast.show({ message: 'Pausable', type: 'info', progress: { enable: true, position: 'top', pauseButton: true } });
-
-// Bar at bottom
-APX.toast.show({ message: 'Done', type: 'success', progress: { enable: true, position: 'bottom' } });
-
-// Default progress for all toasts from a manager
-APX.toast.configure({ progress: true });
-```
-
-- `progress: true` → bar at top, no pause button.
-- `progress: { enable, position: 'top'|'bottom', pauseButton?: boolean }` — `pauseButton` defaults to `false`; set `pauseButton: true` to show the round pause/resume button on the toast corner.
-- No bar if `durationMs === 0` (sticky). Extra spacing is applied when the button is present so stacked toasts do not overlap.
-
-## Behavior
-
-- Lazy container creation (first `show`).
-- `maxToasts` enforced; oldest removed with reason `'overflow'`.
-- Hover pauses timer; resumes on mouse leave (unless user clicked pause).
-- `durationMs = 0` makes the toast sticky (no progress bar).
-- If `dedupe: true` and `id` matches an open toast, it updates instead of creating a new one.
-- With `progress`, a bar and optional pause/resume button show; button toggles pause (same as hover).
-
-## Accessibility & SSR
-
-- Container uses `aria-live` (configurable).
-- Each toast has `role="status"`.
-- ESM only; no DOM access at import time. Safe to import in SSR; DOM is touched only when showing toasts in the browser.
-
-## License
-
-Copyright Appius.
+# APX Toast
+
+A tiny, framework‑agnostic toast library for APX. Minimal CSS, ESM‑first, no globals. DOM is only touched when you actually show a toast (SSR‑safe to import).
+
+## Install / Import
+
+Just import `APX` — the toast CSS is automatically loaded by `modules/toast/toast.mjs`.
+
+```html
+<script type="module">
+  import APX from './APX.mjs';
+  // CSS is auto‑imported; no <link> tag required.
+  // ...
+  APX.toast.success('Ready!');
+ </script>
+```
+
+## Quick start
+
+```js
+// Default manager (lazy)
+APX.toast.success('Saved!');
+APX.toast.warning('Heads up', { durationMs: 4000 });
+APX.toast.danger('Something failed', { durationMs: 0 }); // sticky
+
+// Custom toast
+const ref = APX.toast.show({ message: 'Processing…', type: 'info', durationMs: 0 });
+// Callable shorthand for show:
+APX.toast({ message: 'Hello', type: 'success' });
+ref.update({ message: 'Done', type: 'success', durationMs: 1800 });
+ref.whenClosed().then(() => console.log('closed'));
+
+// Configure defaults at runtime
+APX.toast.configure({ position: 'top-right', maxToasts: 4, dedupe: true });
+```
+
+### Named managers (profiles)
+
+```js
+// Register a named manager
+APX.toast.create('admin', { position: 'bottom-left', ariaLive: 'polite' });
+
+// Use it later
+APX.toast.use('admin').info('Admin ready');
+APX.toast.use('admin').closeAll();
+```
+
+## API overview
+
+- Top‑level (default manager):
+  - `APX.toast(opts)` — callable shorthand for `show(opts)`
+  - `APX.toast.show(opts)`
+  - `APX.toast.info|success|warning|danger(message, opts?)`
+  - `APX.toast.configure(config)`
+  - `APX.toast.closeAll(reason?)` — `reason`: `'api'` | `'overflow'`
+  - `APX.toast.getOpenToasts()` — returns `ToastRef[]`
+  - `APX.toast.create(name, config)` — register named manager; or `create(config)` to get a new manager without registering
+  - `APX.toast.use(name)` — returns named manager or `null`
+
+- Named manager instance (same surface):
+  - `.show(opts)`, `.info|success|warning|danger(message, opts?)`
+  - `.configure(config)`, `.closeAll(reason?)`, `.getOpenToasts()`
+
+- **ToastRef** (returned by `show` / helpers):
+  - `ref.id`, `ref.el` (HTMLElement)
+  - `ref.close(reason?)` — `reason`: `'api'` | `'close'`
+  - `ref.update(partial)` — merge options (message, type, durationMs, progress, className, etc.)
+  - `ref.whenClosed()` — `Promise<void>` when toast is removed
+  - `ref.on('close'|'click', handler)` — returns unsubscribe function
+  - `ref.off('close'|'click', handler)`
+
+## Options and types
+
+```js
+// ToastConfig (global/manager defaults)
+{
+  position: Position,               // default 'bottom-right' (string or object, see Position below)
+  flow: 'up'|'down'|'auto',         // stacking direction; 'auto' from position (default 'auto')
+  maxToasts: number,                // default 5
+  defaultDurationMs: number,        // default 5000
+  zIndex: number,                  // default 11000
+  ariaLive: 'polite'|'assertive'|'off', // default 'polite'
+  gap: number,                      // default 8
+  dedupe: boolean,                  // default false
+  containerClass: string,           // extra class on container
+  offset: number,                  // px offset from screen edges (string positions only)
+  id: string,                      // default id for toasts when not provided per-call
+  progress: false | true | { enable, position?, pauseButton? }  // default false; pauseButton default false
+}
+
+// Position — string or object
+// String: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
+// Object:
+//   - type 'sticky': fixed viewport, use x / y (e.g. '10px', '-20px' = from right/bottom)
+//   - type 'relative': relative to element; x, y offset; requires element
+//   - type 'anchored': outside element; placement 'top'|'right'|'bottom'|'left' (or 'above'|'below'|'before'|'after'); gap; requires element
+//   - useNativeCSS: true — for relative/anchored, render container inside the element with CSS (no fixed overlay)
+
+// ToastOptions (per toast)
+{
+  message: string | Node,
+  type: 'info'|'success'|'warning'|'danger', // default 'info'
+  durationMs: number,               // default from config; 0 = sticky
+  dismissible: boolean,             // default true
+  id: string,                       // stable id for dedupe updates
+  className: string,                // extra classes on the toast element
+  position: Position,               // override container position for this toast
+  flow: 'up'|'down'|'auto',        // override stacking direction for this toast
+  progress: true | { enable: boolean, position?: 'top'|'bottom', pauseButton?: boolean },  // pauseButton default false
+  onClick: (ref, ev) => void,
+  onClose: (ref, reason) => void    // reason: 'timeout'|'close'|'api'|'overflow'
+}
+```
+
+## Position (advanced)
+
+Besides the four corners (`'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'`), position can be an object:
+
+- **sticky** (or omit type and set `x`/`y`): fixed in viewport. Use `x`, `y` as CSS values; prefix with `-` for right/bottom (e.g. `y: '-20px'`).
+- **relative**: fixed overlay positioned relative to an element. Requires `element` (HTMLElement); `x`, `y` are offsets (px/em). Container follows scroll/resize.
+- **anchored**: container placed outside the element. Requires `element` and `placement` (`'top'|'right'|'bottom'|'left'` or synonyms `'above'|'below'|'before'|'after'`). Optional `gap` (e.g. `'1em'`).
+- **useNativeCSS**: when `true` with relative/anchored, the toast container is rendered inside the target element with `position: absolute` (no fixed overlay). The target gets `position: relative` while toasts exist.
+
+`flow` (`'up'|'down'|'auto'`) controls stacking: `'auto'` is derived from position (e.g. top → up, bottom → down).
+
+## Theming (minimal CSS)
+
+Override CSS variables to theme without touching markup:
+
+```css
+:root {
+  --apx-toast-gap: 10px;
+  --apx-toast-min-width: 280px;
+  --apx-toast-radius: 8px;
+  --apx-toast-success-bg: #16a34a;
+  --apx-toast-success-fg: #fff;
+}
+```
+
+Class structure (BEM‑like):
+- Container: `APX-toast-container APX-toast-container--{corner}`
+- Toast: `APX-toast APX-toast--{type}`
+- Children: `APX-toast__content`, optional `APX-toast__close`
+- Progress (v2.6.1): `APX-toast__progress`, `APX-toast__progress-track`, `APX-toast__progress-bar`, optional `APX-toast__progress-pause`
+- Animations: `APX-toast--enter/--enter-active`, `APX-toast--exit/--exit-active`
+
+## Progress bar (v2.6.1)
+
+Optional visual countdown for toasts with a duration. Bar shows time remaining (100% → 0%); sync with timer and hover pause.
+
+```js
+// Bar on top (default), no pause button by default
+APX.toast.show({ message: 'Saving…', type: 'info', progress: true });
+
+// Bar with pause/resume button
+APX.toast.show({ message: 'Pausable', type: 'info', progress: { enable: true, position: 'top', pauseButton: true } });
+
+// Bar at bottom
+APX.toast.show({ message: 'Done', type: 'success', progress: { enable: true, position: 'bottom' } });
+
+// Default progress for all toasts from a manager
+APX.toast.configure({ progress: true });
+```
+
+- `progress: true` → bar at top, no pause button.
+- `progress: { enable, position: 'top'|'bottom', pauseButton?: boolean }` — `pauseButton` defaults to `false`; set `pauseButton: true` to show the round pause/resume button on the toast corner.
+- No bar if `durationMs === 0` (sticky). Extra spacing is applied when the button is present so stacked toasts do not overlap.
+
+## Behavior
+
+- Lazy container creation (first `show`).
+- `maxToasts` enforced; oldest removed with reason `'overflow'`.
+- Hover pauses timer; resumes on mouse leave (unless user clicked pause).
+- `durationMs = 0` makes the toast sticky (no progress bar).
+- If `dedupe: true` and `id` matches an open toast, it updates instead of creating a new one.
+- With `progress`, a bar and optional pause/resume button show; button toggles pause (same as hover).
+
+## Accessibility & SSR
+
+- Container uses `aria-live` (configurable).
+- Each toast has `role="status"`.
+- ESM only; no DOM access at import time. Safe to import in SSR; DOM is touched only when showing toasts in the browser.
+
+## License
+
+Copyright Appius.

package/modules/tristate/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Tristate Module Changelog
+
+This changelog tracks updates for `modules/tristate` between APX releases.
+
+## TBA (next release)
+
+### Added
+- **Chainable API**: `tristate(options)` now returns an object with `setChildren(childrenApx)`. Use it to link a parent tristate to its child checkboxes.
+- **Parent + sub-checkboxes**: `setChildren(childrenApx)` wires one parent (first in the selection) to all child checkboxes. Parent reflects children (all checked → parent checked, all crossed → parent crossed, all unchecked → parent empty, **mixed → parent shows indeterminate dash**). Clicking the parent applies its new state to all children. Children are initialized as tristates with the same options as the parent.
+- **Automatic indeterminate (dash)**: When `setChildren()` is used, the parent automatically gets the indeterminate (dash) appearance **only when children are mixed**. When all children are unchecked the parent shows an empty frame. Indeterminate is no longer a manual option; it is derived from child states.
+- New `colors` option: an object grouping color targets.
+  - `colors.tick`: checked/crossed symbol color (default: `transparent`).
+  - `colors.checked`: checked state background (default: `#0654ba`).
+  - `colors.crossed`: crossed state background (default: `#f00`).
+  - Flat options `tickColor`, `checkedColor`, `crossedColor` remain supported for backward compatibility; `colors` takes precedence when both are set.
+- CSS class `apx-tristate--mixed`: when the parent has indeterminate-dash and `--mixed`, the dash is shown; when not `--mixed` (e.g. all children unchecked), the parent shows an empty unchecked frame. Used internally by `setChildren()`.
+
+### Changed
+- `size.width` and `size.height` accept numbers (treated as pixels) or strings (used as CSS length, e.g. `'1.25rem'`, `'20px'`). Invalid types throw `TypeError`.
+- Tristate symbols (check and cross) are rendered with `mask-image` and data URIs over themeable backgrounds. Unchecked and indeterminate-dash assets are inlined as data URIs in CSS so the demo works from `file://` without CORS.
+- Unchecked icon uses a rounded inset (`4px`). Indeterminate (dash) uses checked background + tick-colored dash; indeterminate (filled check) uses checked background only with `border-radius: inherit`.
+- **State classes**: Only one of `unchecked` / `checked` / `crossed` is ever set on the tristate DOM (fixes parent with `setChildren` incorrectly showing indeterminate when state was `crossed`). `setDefaultState` and `toggleTriStateCheckboxState` now clear all three before adding the active one.
+- Asset `tristate-indeterminate.svg` renamed to `tristate-indeterminate-dash.svg`.
+
+### Removed
+- **Breaking**: Options `uncheckedAppearance` and `indeterminateDisplay` have been removed. Indeterminate (dash) is no longer configurable manually; it is applied automatically on parents that use `setChildren()` when their children are in a mixed state.
+
+### Docs & Demo
+- Demo `demo/modules/tristate/index.html`: Parameters (size + colors), Live preview, States preview, Interactive cycle, **Parent + sub-checkboxes** real-world section using `APX('#policyParent').tristate(opts).setChildren(APX('#policyEmail, #policySms, #policyPush'))`. Removed manual uncheckedAppearance/indeterminateDisplay controls and the separate “Unchecked appearance” preview section.
+- README: documented `setChildren(childrenApx)`, automatic indeterminate when mixed, and removed `uncheckedAppearance` / `indeterminateDisplay` from the options list.
+
+## 2.6.2 (current)
+
+Baseline for this changelog. Tristate visuals and options prior to the theming improvements above.

package/modules/tristate/README.md

@@ -1,95 +1,158 @@
-# APX Tri-State Checkbox Module
-
-The APX Tri-State Checkbox module provides an augmentation to the `APX` object. This functionality allows you to easily transform standard checkboxes within an `APX` object into tri-state checkboxes.
-
-## Installation
-
-Ensure you have the core `APX` object integrated into your project.
-
-Next, to use this augmentation, make sure you've imported and added the `tristate` module to your project:
-
-```javascript
-import APX from 'path-to-APX';
-// Assuming tristate is part of APX's module structure
-```
-
-Also, link the required CSS:
-
-```html
-<link rel="stylesheet" href="path-to-css/tristate.css">
-```
-
-## Usage
-
-To transform a group of checkboxes into tri-state checkboxes using the `APX` object, first create an `APX` object containing the checkboxes you wish to transform, then simply call the `tristate` method:
-
-```javascript
-const myApxCheckboxes = APX('.my-checkbox-class');
-myApxCheckboxes.tristate();
-```
-
-### Parameters
-
-The `tristate` method accepts an `options` parameter which can have the following properties:
-
-- `size`: An object that defines the `width` and `height` of the tri-state checkbox.
-  - `width`: Width of the checkbox in pixels (e.g., `50` for 50px width).
-  - `height`: Height of the checkbox in pixels.
-  
-- `classes`: A string or an array of strings representing classes to be added to the custom checkbox. The string can contain class names separated by spaces or commas.
-
-- `defaultState`: A string that defines the default state of the tri-state checkbox. Possible values are 'checked', 'unchecked', and 'crossed'.
-
-- `callbacks`: An object that contains callback functions.
-  - `after`: A function that is called after the tri-state checkbox is created.
-  - `change`: A function that is called when the tri-state checkbox state changes.
-
-- `bubbleEvents`: A boolean that determines whether events (`click`, `keyup`, `change`) on the custom checkbox should bubble up to the original checkbox.
-
-Example:
-
-```javascript
-const options = {
-    size: {
-        width: 50,
-        height: 30
-    },
-    classes: 'myClass1 myClass2',
-    defaultState: 'checked',
-    callbacks: {
-        after: function(originalCheckbox, tristateDom, hiddenInput) {
-            console.log("Checkbox created!");
-        },
-        change: function(originalCheckbox, tristateDom, hiddenInput) {
-            console.log("Checkbox state changed!");
-        }
-    },
-    bubbleEvents: true
-};
-
-const myApxCheckboxes = APX('.my-checkbox-class');
-myApxCheckboxes.tristate(options);
-```
-
-## Features
-
-### Tri-State Logic
-
-The checkbox will cycle through three states:
-
-1. Checked (represented by a tick)
-2. Crossed (represented by a cross)
-3. Unchecked (default checkbox state)
-
-### Accessibility
-
-The tri-state checkbox retains the `tabIndex` property of the original checkbox, ensuring the accessibility of the control.
-
-### Event Bubbling
-
-Any `click`, `keyup`, or `change` events attached to the original checkbox will be bubbled up from the custom checkbox if the `bubbleEvents` option is set to true. This ensures that your existing event listeners will still work as expected and that custom callbacks can also be executed.
-
-
-## License
-
+# APX Tri-State Checkbox Module
+
+The APX Tri-State Checkbox module provides an augmentation to the `APX` object. This functionality allows you to easily transform standard checkboxes within an `APX` object into tri-state checkboxes.
+
+### When to use this module
+
+This module is designed for **whitelist/blacklist** and **inheritance-based policy** UIs: permissions, feature flags, or rule matrices where each row can be explicitly allowed, explicitly denied, or left unspecified (inherit/default). Three distinct states avoid forcing a binary choice and keep policy intent clear both in the UI and when submitting to the backend.
+
+## Installation
+
+Ensure you have the core `APX` object integrated into your project.
+
+Next, to use this augmentation, make sure you've imported and added the `tristate` module to your project:
+
+```javascript
+import APX from 'path-to-APX';
+// Assuming tristate is part of APX's module structure
+```
+
+Also, link the required CSS:
+
+```html
+<link rel="stylesheet" href="path-to-css/tristate.css">
+```
+
+## Usage
+
+To transform a group of checkboxes into tri-state checkboxes using the `APX` object, first create an `APX` object containing the checkboxes you wish to transform, then simply call the `tristate` method:
+
+```javascript
+const myApxCheckboxes = APX('.my-checkbox-class');
+myApxCheckboxes.tristate();
+```
+
+**Example: policy row (whitelist/blacklist)** — one checkbox per permission, submitted as allow/deny/inherit:
+
+```html
+<form>
+  <label>Can edit <input type="checkbox" name="perm_edit" class="policy-cb"></label>
+  <label>Can delete <input type="checkbox" name="perm_delete" class="policy-cb"></label>
+</form>
+<script>
+  APX('.policy-cb').tristate({
+    defaultState: 'unchecked',
+    colors: { tick: '#fff' },
+    callbacks: { change: (_, el, hidden) => console.log(hidden.name, hidden.value || 'inherit'); }
+  });
+</script>
+```
+
+### Parameters
+
+The `tristate` method accepts an `options` parameter which can have the following properties:
+
+- `size`: An object that defines the `width` and `height` of the tri-state checkbox.
+  - `width`: Numeric value is treated as pixels (e.g. `50` → `50px`); string values are used as-is (e.g. `'1.25rem'`, `'20px'`).
+  - `height`: Same as `width` (number = px, string = any CSS length).
+  
+- `classes`: A string or an array of strings representing classes to be added to the custom checkbox. The string can contain class names separated by spaces or commas.
+
+- `defaultState`: A string that defines the default state of the tri-state checkbox. Possible values are 'checked', 'unchecked', and 'crossed'.
+
+- `colors`: An object grouping color targets (recommended). Omitted keys keep CSS defaults.
+  - `tick`: CSS color for the check/cross symbol. Default is `transparent`.
+  - `checked`: CSS color for the checked state background. Default is `#0654ba`.
+  - `crossed`: CSS color for the crossed state background. Default is `#f00`.
+  - For backward compatibility, the flat options `tickColor`, `checkedColor`, and `crossedColor` are still supported; they are overridden by `colors` when both are present.
+
+- `callbacks`: An object that contains callback functions.
+  - `after`: A function that is called after the tri-state checkbox is created.
+  - `change`: A function that is called when the tri-state checkbox state changes.
+
+- `bubbleEvents`: A boolean that determines whether events (`click`, `keyup`, `change`) on the custom checkbox should bubble up to the original checkbox.
+
+### Parent + sub-checkboxes: `setChildren(childrenApx)`
+
+`tristate()` returns a chainable object with a `setChildren` method. Use it to link one parent tristate to its child checkboxes. The parent then reflects the children (all checked → parent checked, all crossed → parent crossed, all unchecked → parent empty, **mixed children → parent shows indeterminate dash**). Clicking the parent applies its new state to all children.
+
+The indeterminate (dash) appearance is **automatically** applied to the parent when `setChildren` is used: the dash is shown only when the children are in a mixed state; when all are unchecked the parent shows an empty frame.
+
+```javascript
+APX('#policyParent').tristate({ size: { width: 28, height: 28 }, colors: { tick: '#fff' }, defaultState: 'unchecked' })
+  .setChildren(APX('#policyEmail, #policySms, #policyPush'));
+```
+
+- Only the **first** parent in the APX selection is linked to **all** children in the given APX. For multiple parent/child groups, call `tristate().setChildren()` per parent.
+- Children are initialized as tristates with the same options as the parent (plus internal change callbacks). If they are already tristates, they are just linked.
+
+Example:
+
+```javascript
+const options = {
+    size: {
+        width: 50,
+        height: 30
+    },
+    classes: 'myClass1 myClass2',
+    defaultState: 'checked',
+    callbacks: {
+        after: function(originalCheckbox, tristateDom, hiddenInput) {
+            console.log("Checkbox created!");
+        },
+        change: function(originalCheckbox, tristateDom, hiddenInput) {
+            console.log("Checkbox state changed!");
+        }
+    },
+    colors: {
+        tick: '#ffffff',
+        checked: '#0654ba',
+        crossed: '#ff0000'
+    },
+    bubbleEvents: true
+};
+
+const myApxCheckboxes = APX('.my-checkbox-class');
+myApxCheckboxes.tristate(options);
+```
+
+## Features
+
+### Tri-State Logic
+
+The checkbox will cycle through three states:
+
+1. Checked (represented by a tick)
+2. Crossed (represented by a cross)
+3. Unchecked (default checkbox state)
+
+### Whitelist/Blacklist semantics
+
+For policy UIs, map the three states as follows:
+
+| State     | Visual | Typical meaning        | Backend value (via hidden input) |
+|-----------|--------|-------------------------|----------------------------------|
+| Checked   | Tick   | Allow / whitelist       | `true` (or your chosen value)   |
+| Crossed   | Cross  | Deny / blacklist        | `false` (or your chosen value)  |
+| Unchecked | Empty  | Inherit / default / N/A | Not submitted (no value)        |
+
+This gives you an explicit **deny vs not-set** distinction: users can leave a row unspecified instead of being forced to choose allow or deny.
+
+### Benefits
+
+- **Explicit allow/deny vs inherit** — Unchecked means “no override”; checked and crossed mean explicit policy decisions.
+- **Cleaner inheritance** — Hierarchical rules (e.g. org → team → user) can override only where needed; other levels inherit.
+- **Auditability** — It is clear in the UI and in submitted data whether a rule was explicitly denied or simply not set.
+
+### Accessibility
+
+The tri-state checkbox retains the `tabIndex` property of the original checkbox, ensuring the accessibility of the control.
+
+### Event Bubbling
+
+Any `click`, `keyup`, or `change` events attached to the original checkbox will be bubbled up from the custom checkbox if the `bubbleEvents` option is set to true. This ensures that your existing event listeners will still work as expected and that custom callbacks can also be executed.
+
+
+## License
+
 Copyright Appius SARL

package/modules/tristate/assets/tristate-checked.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
+  <rect width="32" height="32" fill="#0654ba" />
+</svg>