@massimo-cassandro/minimo 1.22.1 → 1.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massimo-cassandro/minimo",
-  "version": "1.22.1",
+  "version": "1.23.0",
   "description": "Light css framework & utilities",
   "type": "module",
   "main": "./index.js",

package/src/css/forms/switch.css

@@ -2,17 +2,18 @@
 /* TODO valutare versione con label a sinistra (form-check-reverse) */
 
 /*
-Markup (come bootstrap 5, con l'aggiunta dell'attributo nativo `switch`):
+Markup (same as bootstrap 5, plus the native `switch` attribute):
 
 <div class="form-check form-switch">
   <input class="form-check-input" type="checkbox" role="switch" switch id="my-switch">
-  <label class="form-check-label" for="my-switch">Abilita notifiche</label>
+  <label class="form-label" for="my-switch">Enable notifications</label>
 </div>
 
-L'attributo `switch` (per ora solo WebKit) fa sì che il browser generi un vero
-controllo switch nativo, modellabile con gli pseudo-elementi `::track` e `::thumb`.
-Dove non è supportato (o dove l'attributo è assente) si applica il fallback
-`appearance: none` con la pallina disegnata come background-image.
+The `switch` attribute (WebKit only for now) makes the browser render a real
+native switch control, which can be styled through the `::track` and `::thumb`
+pseudo-elements. Where it is not supported (or where the attribute is missing),
+the `appearance: none` fallback is applied, with the thumb drawn as a
+background-image.
 */
 
 .form-switch {
@@ -34,11 +35,12 @@ Dove non è supportato (o dove l'attributo è assente) si applica il fallback
     appearance: none;
     cursor: pointer;
     background-color: var(--form-switch-background-color);
-    background-image: radial-gradient(
-      circle closest-side,
-      var(--form-switch-cursor-background-color) 98%,
-      transparent
-    );
+    background-image:
+      radial-gradient(
+        circle closest-side,
+        var(--form-switch-cursor-background-color) 98%,
+        transparent
+      );
     background-repeat: no-repeat;
     background-position: var(--form-switch-thumb-inset) center;
     background-size: var(--_switch-thumb-size) var(--_switch-thumb-size);
@@ -63,7 +65,8 @@ Dove non è supportato (o dove l'attributo è assente) si applica il fallback
     }
   }
 
-  .form-check-label {
+  .form-label {
+    padding-inline-start: 0 !important;
     cursor: pointer;
     user-select: none;
   }
@@ -71,7 +74,7 @@ Dove non è supportato (o dove l'attributo è assente) si applica il fallback
   &:has(.form-check-input:disabled) {
     opacity: var(--form-control-disabled-opacity);
 
-    .form-check-input, .form-check-label {
+    .form-check-input, .form-label {
       cursor: not-allowed;
     }
   }

package/src/utilities/dom-builder/dom-builder.js

@@ -18,8 +18,12 @@ import { parseDomString } from './parseDomString.js';
  *   A string or number is set as plain text (`textContent`) unless it contains `<`, in which case it is
  *   treated as markup: sanitized and inserted via the native Sanitizer API (`Element.setHTML`) where
  *   supported, falling back to raw `innerHTML` on browsers without it.
- * @property {boolean} [condition=true] - When false, the element is skipped.
- * @property {(function(HTMLElement): void) | null} [callback] - Callback invoked after the element is created.
+ * @property {string | number} [text] - Literal text node shorthand: inserts a plain `Text` node (never
+ *   parsed as markup) in place of an element, so it can sit as a sibling of tags within `children`/`content`
+ *   arrays. Mutually exclusive with `tag`/`content`/`children`: when set (and `tag` is absent), every other
+ *   property except `condition` and `callback` is ignored.
+ * @property {boolean} [condition=true] - When false, the element (or text node) is skipped.
+ * @property {(function(HTMLElement|Text): void) | null} [callback] - Callback invoked after the element (or text node) is created.
  * @property {Array<DomBuilderItem|string>} [children] - Configuration array for child elements. Accepts strings (shorthand per `parseDomString`) and/or configuration objects.
  */
 
@@ -53,6 +57,18 @@ import { parseDomString } from './parseDomString.js';
  * ]
  * ```
  *
+ * To mix literal text and tags as siblings within the same element (e.g. `Lorem <strong>ipsum</strong> dolor`),
+ * use the `text` shorthand in `children`/`content`, since a plain string item is always parsed as a tag
+ * (see `parseDomString`), never as a text node:
+ *
+ * ```javascript
+ * children: [
+ *   { text: 'Lorem ' },
+ *   { tag: 'strong', content: 'ipsum' },
+ *   { text: ' dolor' }
+ * ]
+ * ```
+ *
  * IDs and classes can be specified either as top-level object keys or inside the `attrs` object.
  * When both are present, top-level properties take precedence.
  *
@@ -74,8 +90,9 @@ import { parseDomString } from './parseDomString.js';
  * - `id` {string | null} - Unique element ID.
  * - `attrs` {[string, *] | [string, *][] | Object<string, *>} - Attributes: a `[name, value]` pair, array of pairs, or `{name: value}` object.
  * - `content` {string | number | Function | Element | DomBuilderItem[] | null} - Element content. A string/number is set as `textContent` unless it contains `<`, in which case it's sanitized and inserted as markup (`Element.setHTML`, falling back to `innerHTML`).
- * - `condition` {boolean} - When false, the element is skipped. Default `true`.
- * - `callback` {(function(HTMLElement): void) | null} - Invoked after the element is created.
+ * - `text` {string | number} - Literal text node shorthand: inserts a plain `Text` node (never parsed as markup) as a sibling of other items, in place of an element. Mutually exclusive with `tag`/`content`/`children`.
+ * - `condition` {boolean} - When false, the element (or text node) is skipped. Default `true`.
+ * - `callback` {(function(HTMLElement|Text): void) | null} - Invoked after the element (or text node) is created.
  * - `children` {Array<DomBuilderItem|string>} - Configuration array for child elements (same format, nested).
  *
  * IDs and classes can be specified either as top-level object keys or inside `attrs`; top-level properties take precedence.
@@ -109,7 +126,7 @@ export function domBuilder(structureArray = [], parent, options = {}) {
   /** @type {HTMLElement | DocumentFragment | null} */
   let target = useFragment ? document.createDocumentFragment() : (parent ?? null);
 
-  /** @type {Map<HTMLElement | DocumentFragment, HTMLElement>} tracks, for `insertMode: 'after'`, the last inserted sibling per parent node */
+  /** @type {Map<HTMLElement | DocumentFragment, Node>} tracks, for `insertMode: 'after'`, the last inserted sibling per parent node */
   const afterAnchors = new Map();
 
   /** @type {HTMLElement | null} */
@@ -135,6 +152,34 @@ export function domBuilder(structureArray = [], parent, options = {}) {
 
       const safeItem = item; // const binding so TypeScript tracks non-null type in nested closures
 
+      // `{ text: '...' }` shorthand: a literal Text node, never parsed as markup, inserted in
+      // place of an element so it can sit as a sibling of tags within `children`/`content` arrays
+      if (safeItem.tag == null && (typeof safeItem.text === 'string' || typeof safeItem.text === 'number')) {
+
+        const textNode = document.createTextNode(String(safeItem.text));
+
+        if (target) {
+          if (options.insertMode === 'before') {
+            const anchor = /** @type {HTMLElement} */ (target);
+            anchor.parentNode?.insertBefore(textNode, anchor);
+
+          } else if (options.insertMode === 'after') {
+            const anchor = afterAnchors.get(/** @type {HTMLElement} */ (target)) ?? /** @type {HTMLElement} */ (target);
+            anchor.parentNode?.insertBefore(textNode, anchor.nextSibling);
+            afterAnchors.set(/** @type {HTMLElement} */ (target), textNode);
+
+          } else {
+            target.appendChild(textNode);
+          }
+        }
+
+        if (safeItem.callback && typeof safeItem.callback === 'function') {
+          safeItem.callback(textNode);
+        }
+
+        return;
+      }
+
       // when tag is an array, create a series of nested elements;
       // the last one receives the remaining object properties
       if (Array.isArray(safeItem.tag)) {

package/src/utilities/dom-builder-helpers/form-tags.js

@@ -132,12 +132,21 @@ export function buildSelect({
 
   id = id || randomId();
 
-  // normalizing option as an array
-  if(options && !Array.isArray(options)) {
-    options = Object.entries(options);
+  // normalizing options as an array of [value, text] pairs
+  /** @type {Array<[string|number, string]>} */
+  let optionsList = [];
 
-  } else if(options && !Array.isArray(options[0])) {
-    options =  options.map(o => Object.values(o));
+  if(options) {
+    if(!Array.isArray(options)) {
+      optionsList = /** @type {Array<[string|number, string]>} */ (Object.entries(options));
+
+    } else if(!Array.isArray(options[0])) {
+      optionsList = /** @type {Array<Record<string, string>>} */ (options)
+        .map(o => /** @type {[string|number, string]} */ (Object.values(o)));
+
+    } else {
+      optionsList = /** @type {Array<[string|number, string]>} */ (options);
+    }
   }
 
 
@@ -157,18 +166,15 @@ export function buildSelect({
         },
         children: [
           ...(addEmptyOption? ['option[value:]'] : []),
-          ...(options
-            ? options.map(([value, text]) => ({
-              tag: 'option',
-              attrs: {
-                value: value,
-                // eslint-disable-next-line eqeqeq
-                selected: value == selectedValue
-              },
-              content: text
-            }))
-            : []
-          )
+          ...optionsList.map(([value, text]) => ({
+            tag: 'option',
+            attrs: {
+              value: value,
+              // eslint-disable-next-line eqeqeq
+              selected: value == selectedValue
+            },
+            content: text
+          }))
         ],
         callback: callback
       }
@@ -186,6 +192,8 @@ export function buildSelect({
  * @param {string | null} args.id - `id` attribute.
  * @param {string | number | null} [args.value=1] - checkbox `value` attribute.
  * @param {boolean} [args.checked=false] - checkbox `checked` attribute.
+ * @param {boolean} [args.switch=false] - When true, the checkbox is rendered as a switch
+ *    (`.form-switch` wrapper, `role="switch"` and the native `switch` attribute).
  * @param {string | null} [args.wrapperClass=null] - optional class to be added to the `.form-group` wrapper (used only when `addFormGroup` is true).
  * @param {boolean} [args.addFormGroup=true] - When true, wraps the checkbox in a `.form-group` element.
  * @param {boolean} [args.condition=true] - When false, the function returns `null` without building anything.
@@ -200,6 +208,7 @@ export function buildCheckbox({
   id = null,
   value = 1,
   checked = false,
+  switch: isSwitch = false,
   wrapperClass = null,
   addFormGroup = true,
   condition = true,
@@ -213,17 +222,24 @@ export function buildCheckbox({
   }
 
   /*
-  <div class="form-group">
+  <div class="form-group"> <- optional
     <div class="form-check">
       <input type="checkbox" id="..." name="..." class="form-check-input" value="1">
       <label for="..." class="form-label">...</label>
     </div>
   </div>
+
+  <div class="form-group"> <- optional
+    <div class="form-check form-switch">
+      <input class="form-check-input" type="checkbox" role="switch" switch id="my-switch">
+      <label class="form-label" for="my-switch">My label</label>
+    </div>
+  </div>
   */
   id = id || randomId();
 
   const tag = {
-    className: classnames('form-check', !addFormGroup && !help && wrapperClass),
+    className: classnames('form-check', isSwitch && 'form-switch', !addFormGroup && !help && wrapperClass),
     children: [
       {
         tag: 'input',
@@ -234,7 +250,9 @@ export function buildCheckbox({
           type: 'checkbox',
           value: value,
           name: name,
-          checked: checked
+          checked: checked,
+          // native switch control (WebKit only for now), with the css fallback elsewhere
+          ...(isSwitch? {role: 'switch', switch: ''} : {})
         },
         callback: callback
       },

package/types/classes.d.ts

@@ -59,7 +59,6 @@ export type MinimoClass =
   | 'font-semibold'
   | 'form-check'
   | 'form-check-input'
-  | 'form-check-label'
   | 'form-check-top-label'
   | 'form-collection'
   | 'form-collection-fset'