@mp-consulting/homebridge-ui-kit 1.0.1 → 1.1.0

package/README.md

@@ -52,21 +52,23 @@ The plugin's `homebridge-ui/public/index.html` must be a full HTML document. Loa
       } catch(e) {}
     })();
   </script>
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.3/font/bootstrap-icons.min.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" integrity="sha384-QWTKZyjpPEjISv5WaRU9OFeRpok6YctnYmDr5pNlyT2bRjXh0JMhjY6hW+ALEwIH" crossorigin="anonymous">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.3/font/bootstrap-icons.min.css" integrity="sha384-XGjxtQfXaH2tnPFa9x+ruJTuLE3Aa6LhHSWRr1XeTyhezb4abCG4ccI5AkVDxqC+" crossorigin="anonymous">
   <link rel="stylesheet" href="kit.css">
   <link rel="stylesheet" href="styles.css">
 </head>
 <body>
   <!-- your UI here -->
 
-  <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js" integrity="sha384-YvpcrYf0tY3lHB60NNkmXc5s9fDVZLESaAA55NDzOxhy9GkcIdslK1eN7N6jIeHz" crossorigin="anonymous"></script>
   <script src="kit.js"></script>
   <script src="app.js"></script>
 </body>
 </html>
 ```
 
+The `integrity` hashes pin the exact CDN files; update them if you change a version (jsDelivr shows the SRI hash for each file).
+
 The early inline script applies `data-bs-theme="dark"` from the system preference before any CSS loads, preventing a flash of wrong theme. In your app script, also apply the Homebridge user's saved theme setting:
 
 ```js
@@ -90,7 +92,7 @@ homebridge-ui/public/kit.js
 
 ### 5. Update `eslint.config.js`
 
-Add `kit.js` to the ignore list (it is a minified third-party bundle) and expose `MpKit` as a browser global:
+Add `kit.js` to the ignore list (it is a generated, vendored file) and expose `MpKit` as a browser global:
 
 ```js
 export default tseslint.config(
@@ -127,8 +129,18 @@ MpKit.Loading.render('Loading...')
 
 // View switching (.mp-view elements)
 MpKit.View.show('viewId')
+
+// Support footer (only http/https URLs are rendered; icons are inline SVG,
+// so the Bootstrap Icons font is not required)
+MpKit.Footer.render({ github, npm, changelog, target: '.mp-footer' })
+
+// Escape untrusted text before interpolating it into your own HTML
+MpKit.escapeHtml(device.name)
 ```
 
+All text passed to the helpers is HTML-escaped, so it is safe to pass device names or other
+values that came from the network. To include markup, build the element yourself.
+
 ## Dark Mode
 
 Dark mode is handled entirely by Bootstrap's `data-bs-theme="dark"` attribute on `<html>`. Do **not** use `@media (prefers-color-scheme: dark)` blocks, `.dark-mode` CSS classes, or custom CSS variable overrides — Bootstrap handles all of this automatically. Use Bootstrap CSS variables (`var(--bs-body-bg)`, `var(--bs-primary)`, etc.) in your custom CSS instead of hardcoded hex values.
@@ -137,9 +149,14 @@ Dark mode is handled entirely by Bootstrap's `data-bs-theme="dark"` attribute on
 
 ```bash
 npm install
-npm run build   # outputs to dist/
+npm run build        # outputs to dist/ (commit the result)
+npm run build:check  # fails if dist/ is out of date (run in CI)
+npm test
 ```
 
+Use the `--mp-*` tokens for brand colors. For text in the brand color use `--mp-primary-text`,
+which switches to a lighter shade in dark mode so it keeps WCAG AA contrast.
+
 ## License
 
 MIT © MP Consulting

package/dist/kit.css

@@ -1,8 +1,9 @@
-/* @mp-consulting/homebridge-ui-kit v1.0.1 */
+/* @mp-consulting/homebridge-ui-kit v1.1.0 */
 
 /* ── Design tokens ──────────────────────────────────────────────────────────
    CSS custom properties used throughout the design system.
    Override these in your plugin's styles.css to customize per-plugin.
+   Light values live on :root; dark values follow Bootstrap's data-bs-theme.
    ────────────────────────────────────────────────────────────────────────── */
 
 :root {
@@ -10,7 +11,7 @@
   --mp-primary: #4f46e5;
   --mp-primary-rgb: 79, 70, 229;
   --mp-primary-hover: #4338ca;
-  --mp-primary-subtle: rgba(79, 70, 229, 0.12);
+  --mp-primary-text: #4f46e5; /* brand color for text; meets WCAG AA on the body bg */
 
   /* Status */
   --mp-status-online: #10b981;
@@ -19,11 +20,18 @@
   --mp-status-checking: #94a3b8;
 
   /* Surfaces */
-  --mp-surface: rgba(255, 255, 255, 0.03);
-  --mp-border: rgba(255, 255, 255, 0.08);
+  --mp-surface: rgba(0, 0, 0, 0.02);
+  --mp-border: rgba(0, 0, 0, 0.1);
 
   /* Shape */
   --mp-radius: 0.5rem;
+  --mp-shadow-hover: 0 0.5rem 1rem rgba(0, 0, 0, 0.12);
+}
+
+[data-bs-theme="dark"] {
+  --mp-primary-text: #818cf8;
+  --mp-surface: rgba(255, 255, 255, 0.03);
+  --mp-border: rgba(255, 255, 255, 0.08);
   --mp-shadow-hover: 0 0.5rem 1rem rgba(0, 0, 0, 0.3);
 }
 
@@ -40,6 +48,8 @@
   --bs-btn-active-bg: var(--mp-primary-hover);
   --bs-btn-active-border-color: var(--mp-primary-hover);
   --bs-btn-focus-shadow-rgb: var(--mp-primary-rgb);
+  --bs-btn-disabled-bg: var(--mp-primary);
+  --bs-btn-disabled-border-color: var(--mp-primary);
 }
 
 /* Primary spinner */
@@ -122,6 +132,11 @@
   box-shadow: var(--mp-shadow-hover) !important;
 }
 
+.mp-device-card:focus-visible {
+  outline: 2px solid var(--mp-primary);
+  outline-offset: 2px;
+}
+
 /* ── Settings surface card ──────────────────────────────── */
 
 .mp-settings-card {
@@ -184,20 +199,20 @@
 .mp-tabs .nav-link {
   color: var(--bs-secondary-color);
   border: none;
+  border-bottom: 2px solid transparent; /* reserve space so the active tab doesn't shift */
   padding: 0.75rem 1.25rem;
   font-weight: 500;
 }
 
 .mp-tabs .nav-link:hover {
   color: var(--bs-body-color);
-  border: none;
+  border-color: transparent;
 }
 
 .mp-tabs .nav-link.active {
-  color: var(--mp-primary);
+  color: var(--mp-primary-text);
   background: transparent;
-  border: none;
-  border-bottom: 2px solid var(--mp-primary);
+  border-bottom-color: var(--mp-primary);
 }
 
 /* ── Metadata label ─────────────────────────────────────── */
@@ -244,10 +259,34 @@
 }
 
 .mp-footer a:hover {
-  color: var(--mp-primary);
+  color: var(--mp-primary-text);
+}
+
+.mp-footer-icon {
+  width: 1em;
+  height: 1em;
+  flex-shrink: 0;
+  fill: currentColor;
 }
 
 .mp-footer-sep {
   color: var(--mp-border);
   user-select: none;
 }
+
+/* ── Reduced motion ─────────────────────────────────────── */
+
+@media (prefers-reduced-motion: reduce) {
+  .mp-status-checking {
+    animation: none;
+  }
+
+  .mp-device-card,
+  .mp-footer a {
+    transition: none;
+  }
+
+  .mp-device-card:hover {
+    transform: none;
+  }
+}

package/dist/kit.js

@@ -1,47 +1,96 @@
-/* @mp-consulting/homebridge-ui-kit v1.0.0
+/* @mp-consulting/homebridge-ui-kit v1.1.0
    Brand design system for Homebridge plugins
    https://github.com/mp-consulting/homebridge-ui-kit */
 
 (function (global) {
   'use strict';
 
+  var ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', '\'': '&#39;' };
+
+  /** Escapes a value for safe use in HTML text and quoted attributes. */
+  function escapeHtml(value) {
+    return String(value == null ? '' : value).replace(/[&<>"']/g, function (c) {
+      return ESCAPES[c];
+    });
+  }
+
+  /** Returns the URL if it uses http(s), otherwise null (blocks javascript:, data:, …). */
+  function safeUrl(url) {
+    if (typeof url !== 'string') { return null; }
+    return /^https?:\/\//i.test(url.trim()) ? url.trim() : null;
+  }
+
+  function badge(badgeClass, dotClass, label) {
+    return '<span class="badge ' + badgeClass + '">'
+      + (dotClass ? '<span class="mp-status ' + dotClass + ' me-1" aria-hidden="true"></span>' : '')
+      + escapeHtml(label) + '</span>';
+  }
+
+  // Icon paths from Bootstrap Icons 1.11.3 (MIT), inlined so the footer
+  // works whether or not the plugin loads the icon font.
+  var FOOTER_LINKS = [
+    {
+      key: 'github',
+      text: 'GitHub',
+      paths: [
+        'M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27s1.36.09 2 .27c1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8',
+      ],
+    },
+    {
+      key: 'npm',
+      text: 'npm',
+      paths: [
+        'M8.186 1.113a.5.5 0 0 0-.372 0L1.846 3.5l2.404.961L10.404 2zm3.564 1.426L5.596 5 8 5.961 14.154 3.5zm3.25 1.7-6.5 2.6v7.922l6.5-2.6V4.24zM7.5 14.762V6.838L1 4.239v7.923zM7.443.184a1.5 1.5 0 0 1 1.114 0l7.129 2.852A.5.5 0 0 1 16 3.5v8.662a1 1 0 0 1-.629.928l-7.185 2.874a.5.5 0 0 1-.372 0L.63 13.09a1 1 0 0 1-.63-.928V3.5a.5.5 0 0 1 .314-.464z',
+      ],
+    },
+    {
+      key: 'changelog',
+      text: 'Changelog',
+      paths: [
+        'M8.515 1.019A7 7 0 0 0 8 1V0a8 8 0 0 1 .589.022zm2.004.45a7 7 0 0 0-.985-.299l.219-.976q.576.129 1.126.342zm1.37.71a7 7 0 0 0-.439-.27l.493-.87a8 8 0 0 1 .979.654l-.615.789a7 7 0 0 0-.418-.302zm1.834 1.79a7 7 0 0 0-.653-.796l.724-.69q.406.429.747.91zm.744 1.352a7 7 0 0 0-.214-.468l.893-.45a8 8 0 0 1 .45 1.088l-.95.313a7 7 0 0 0-.179-.483m.53 2.507a7 7 0 0 0-.1-1.025l.985-.17q.1.58.116 1.17zm-.131 1.538q.05-.254.081-.51l.993.123a8 8 0 0 1-.23 1.155l-.964-.267q.069-.247.12-.501m-.952 2.379q.276-.436.486-.908l.914.405q-.24.54-.555 1.038zm-.964 1.205q.183-.183.35-.378l.758.653a8 8 0 0 1-.401.432z',
+        'M8 1a7 7 0 1 0 4.95 11.95l.707.707A8.001 8.001 0 1 1 8 0z',
+        'M7.5 3a.5.5 0 0 1 .5.5v5.21l3.248 1.856a.5.5 0 0 1-.496.868l-3.5-2A.5.5 0 0 1 7 9V3.5a.5.5 0 0 1 .5-.5',
+      ],
+    },
+  ];
+
+  function icon(paths) {
+    return '<svg class="mp-footer-icon" viewBox="0 0 16 16" aria-hidden="true" focusable="false">'
+      + paths.map(function (d) { return '<path d="' + d + '"/>'; }).join('')
+      + '</svg>';
+  }
+
   var MpKit = {
 
+    escapeHtml: escapeHtml,
+
     /**
      * StatusBadge — returns inline HTML for device status badges.
+     * Labels are HTML-escaped.
      *
      * MpKit.StatusBadge.online()    → green dot + "Online"
      * MpKit.StatusBadge.offline()   → red dot + "Offline"
-     * MpKit.StatusBadge.checking()  → animated dot + "Checking..."
+     * MpKit.StatusBadge.checking()  → animated dot + "Checking…"
      * MpKit.StatusBadge.disabled()  → grey badge + "Disabled"
      */
     StatusBadge: {
       online: function (label) {
-        label = label || 'Online';
-        return '<span class="badge bg-success-subtle text-success">'
-          + '<span class="mp-status mp-status-online me-1"></span>'
-          + label + '</span>';
+        return badge('bg-success-subtle text-success', 'mp-status-online', label || 'Online');
       },
       offline: function (label) {
-        label = label || 'Offline';
-        return '<span class="badge bg-danger-subtle text-danger">'
-          + '<span class="mp-status mp-status-offline me-1"></span>'
-          + label + '</span>';
+        return badge('bg-danger-subtle text-danger', 'mp-status-offline', label || 'Offline');
       },
       checking: function (label) {
-        label = label || 'Checking...';
-        return '<span class="badge bg-secondary-subtle text-secondary">'
-          + '<span class="mp-status mp-status-checking me-1"></span>'
-          + label + '</span>';
+        return badge('bg-secondary-subtle text-secondary', 'mp-status-checking', label || 'Checking…');
       },
       disabled: function (label) {
-        label = label || 'Disabled';
-        return '<span class="badge bg-secondary">' + label + '</span>';
+        return badge('bg-secondary', null, label || 'Disabled');
       },
     },
 
     /**
      * EmptyState — returns HTML for an empty list placeholder.
+     * All options are HTML-escaped.
      *
      * MpKit.EmptyState.render({
      *   iconClass: 'bi bi-lightbulb',
@@ -56,24 +105,25 @@
         var title = opts.title || 'No items';
         var hint = opts.hint || '';
         return '<div class="mp-empty-state">'
-          + '<i class="' + icon + ' mp-empty-state-icon"></i>'
-          + '<p class="mp-empty-state-title">' + title + '</p>'
-          + (hint ? '<p class="mp-empty-state-hint">' + hint + '</p>' : '')
+          + '<i class="' + escapeHtml(icon) + ' mp-empty-state-icon" aria-hidden="true"></i>'
+          + '<p class="mp-empty-state-title">' + escapeHtml(title) + '</p>'
+          + (hint ? '<p class="mp-empty-state-hint">' + escapeHtml(hint) + '</p>' : '')
           + '</div>';
       },
     },
 
     /**
      * Loading — returns HTML for a centred loading spinner with message.
+     * The message is HTML-escaped and announced to screen readers.
      *
      * MpKit.Loading.render('Loading device information...')
      */
     Loading: {
       render: function (message) {
-        message = message || 'Loading...';
-        return '<div class="mp-loading">'
-          + '<div class="spinner-border spinner-border-sm text-secondary" role="status" aria-hidden="true"></div>'
-          + '<span>' + message + '</span>'
+        message = message || 'Loading…';
+        return '<div class="mp-loading" role="status" aria-live="polite">'
+          + '<div class="spinner-border spinner-border-sm text-secondary" aria-hidden="true"></div>'
+          + '<span>' + escapeHtml(message) + '</span>'
           + '</div>';
       },
     },
@@ -87,20 +137,20 @@
     View: {
       show: function (id) {
         document.querySelectorAll('.mp-view').forEach(function (v) {
-          v.classList.remove('active');
+          v.classList.toggle('active', v.id === id);
         });
-        var el = document.getElementById(id);
-        if (el) { el.classList.add('active'); }
       },
     },
 
     /**
      * Footer — renders support links into a .mp-footer element.
+     * Only http(s) URLs are rendered; anything else is skipped.
      *
      * MpKit.Footer.render({
      *   github: 'https://github.com/mp-consulting/homebridge-...',
      *   npm: 'https://www.npmjs.com/package/@mp-consulting/...',
      *   changelog: 'https://github.com/.../blob/main/CHANGELOG.md',
+     *   target: '.mp-footer', // optional selector or element
      * })
      */
     Footer: {
@@ -110,19 +160,13 @@
         var el = typeof target === 'string' ? document.querySelector(target) : target;
         if (!el) { return; }
         var links = [];
-        if (opts.github) {
-          links.push('<a href="' + opts.github + '" target="_blank" rel="noopener">'
-            + '<i class="bi bi-github"></i>GitHub</a>');
-        }
-        if (opts.npm) {
-          links.push('<a href="' + opts.npm + '" target="_blank" rel="noopener">'
-            + '<i class="bi bi-box-seam"></i>npm</a>');
-        }
-        if (opts.changelog) {
-          links.push('<a href="' + opts.changelog + '" target="_blank" rel="noopener">'
-            + '<i class="bi bi-clock-history"></i>Changelog</a>');
-        }
-        el.innerHTML = links.join('<span class="mp-footer-sep">|</span>');
+        FOOTER_LINKS.forEach(function (link) {
+          var url = safeUrl(opts[link.key]);
+          if (!url) { return; }
+          links.push('<a href="' + escapeHtml(url) + '" target="_blank" rel="noopener noreferrer">'
+            + icon(link.paths) + link.text + '</a>');
+        });
+        el.innerHTML = links.join('<span class="mp-footer-sep" aria-hidden="true">|</span>');
       },
     },
 
@@ -130,4 +174,4 @@
 
   global.MpKit = MpKit;
 
-})(window);
+})(typeof window !== 'undefined' ? window : globalThis);

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@mp-consulting/homebridge-ui-kit",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Brand design system for @mp-consulting Homebridge plugins",
+  "keywords": [
+    "homebridge",
+    "homebridge-ui",
+    "bootstrap",
+    "design-system"
+  ],
+  "homepage": "https://github.com/mp-consulting/homebridge-ui-kit#readme",
+  "bugs": {
+    "url": "https://github.com/mp-consulting/homebridge-ui-kit/issues"
+  },
   "author": "MP Consulting",
   "license": "MIT",
   "type": "module",
@@ -12,7 +22,12 @@
   "files": [
     "dist"
   ],
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
-    "build": "node scripts/build.js"
+    "build": "node scripts/build.js",
+    "build:check": "node scripts/build.js --check",
+    "test": "node --test test/*.test.js"
   }
 }