@pnx-mixtape/mxds 0.0.30 → 0.1.0-rc.0

package/src/Utility/Elements/cookie-compliance.ts

@@ -7,17 +7,20 @@
  */
 
 import Cookies from "js-cookie"
+import validators from "./validators"
 
 export default class CookieCompliance {
   banner: HTMLElement
   acceptBtn: HTMLButtonElement
   moreBtn: HTMLButtonElement
   rejectBtn: HTMLButtonElement
+  controller: AbortController
   bots: RegExp
   cookieName: string
   waitRemove: number
   trackingCookiesNames: string[]
   hostname: string | undefined
+  timeout?: ReturnType<typeof setTimeout>
   defaultCookieSettings:
     | {
         path: string
@@ -31,12 +34,15 @@ export default class CookieCompliance {
     this.acceptBtn = el.querySelector("[data-cookie-accept]")
     this.moreBtn = el.querySelector("[data-cookie-more]")
     this.rejectBtn = el.querySelector("[data-cookie-reject]")
+    this.controller = new AbortController()
     this.bots = /bot|crawler|spider|crawling/i
     this.cookieName = "has-cookie-consent"
+
+    // Validate waitRemove is a valid non-negative integer (0 or greater)
+    const waitRemoveValue = this.banner.dataset.waitRemove
     this.waitRemove =
-      this.banner.dataset.waitRemove === undefined
-        ? 0
-        : parseInt(this.banner.dataset.waitRemove, 10)
+      waitRemoveValue && validators.integer(waitRemoveValue, 0) ? parseInt(waitRemoveValue, 10) : 0
+
     this.trackingCookiesNames = [
       "__utma",
       "__utmb",
@@ -86,16 +92,21 @@ export default class CookieCompliance {
   }
 
   showBanner = (): void => {
+    const { signal }: AbortController = this.controller
+
     this.banner.removeAttribute("inert")
     if (this.moreBtn) {
-      this.moreBtn.addEventListener("click", this.deleteCookie)
+      this.moreBtn.addEventListener("click", () => this.deleteCookie(), { signal })
     }
     if (this.acceptBtn) {
-      this.acceptBtn.addEventListener("click", this.accept)
+      this.acceptBtn.addEventListener("click", this.accept, { signal })
     }
     if (this.rejectBtn) {
-      this.rejectBtn.addEventListener("click", this.reject)
+      this.rejectBtn.addEventListener("click", this.reject, { signal })
     }
+
+    // Store reference for cleanup
+    window.CookieCompliance = this
   }
 
   reject = (): void => {
@@ -103,7 +114,7 @@ export default class CookieCompliance {
     this.setCookie("false")
 
     // Delete existing tracking cookies
-    this.trackingCookiesNames.map(this.deleteCookie)
+    this.trackingCookiesNames.forEach(name => this.deleteCookie(name))
   }
 
   accept = (): void => {
@@ -111,8 +122,8 @@ export default class CookieCompliance {
     this.setCookie("true")
   }
 
-  hasConsent = (): boolean => {
-    const consent: "true" | "false" = Cookies.get(this.cookieName)
+  hasConsent = (): boolean | null => {
+    const consent = Cookies.get(this.cookieName)
     if (consent === "true") {
       return true
     }
@@ -131,31 +142,58 @@ export default class CookieCompliance {
     })
   }
 
-  deleteCookie = (): void => {
-    Cookies.remove(this.cookieName, this.defaultCookieSettings)
-    Cookies.remove(this.cookieName, {
+  deleteCookie = (name: string = this.cookieName): void => {
+    Cookies.remove(name, this.defaultCookieSettings)
+    Cookies.remove(name, {
       domain: `.${this.hostname}`,
       ...this.defaultCookieSettings,
     })
   }
 
   removeBanner = (wait: number): void => {
-    setTimeout(() => {
+    this.timeout = setTimeout(() => {
       if (this.banner && this.banner.parentNode) {
-        if (this.moreBtn) {
-          this.moreBtn.removeEventListener("click", this.deleteCookie)
-        }
-        if (this.acceptBtn) {
-          this.acceptBtn.removeEventListener("click", this.accept)
-        }
-        if (this.rejectBtn) {
-          this.rejectBtn.removeEventListener("click", this.reject)
-        }
         this.banner.parentNode.removeChild(this.banner)
+
+        // Clean up after banner is removed
+        this.destroy()
       }
     }, wait)
   }
 
+  /**
+   * Clean up event listeners and pending timeouts.
+   * This is called automatically when the banner is removed.
+   *
+   * Manually call this method when:
+   * - Navigating away in a SPA (Single Page Application)
+   * - Cleaning up in tests
+   * - Reinitializing the component
+   *
+   * @example
+   * // In SPA cleanup
+   * window.CookieCompliance?.destroy()
+   *
+   * // Before unmounting in React
+   * useEffect(() => {
+   *   return () => window.CookieCompliance?.destroy()
+   * }, [])
+   */
+  destroy(): void {
+    // Clear pending timeout
+    clearTimeout(this.timeout)
+
+    // Abort controller removes all event listeners automatically
+    this.controller.abort()
+
+    // Prepare for potential reinitialization by creating a new controller
+    this.controller = new AbortController()
+    // Remove global reference
+    if (window.CookieCompliance === this) {
+      window.CookieCompliance = undefined
+    }
+  }
+
   static create({ context = null } = {}): void {
     const [el] = window.once("cookie-compliance", "#cookie-compliance", context || document)
     if (el) {

package/src/Utility/Elements/disclosure-widget.ts

@@ -107,14 +107,22 @@ export default class DisclosureWidget {
       case "ArrowDown":
       case "Enter":
         if (!isOpen) this.handleToggle()
-        if (shouldPreventDefault) event.preventDefault()
+        if (shouldPreventDefault) {
+          event.preventDefault()
+          // Stop other document-level key handlers (e.g. roving link focus)
+          // from also reacting to a key this widget has already handled.
+          event.stopPropagation()
+        }
         break
 
       // Up/Esc should close it.
       case "ArrowUp":
       case "Escape":
         if (isOpen) this.handleToggle()
-        if (shouldPreventDefault) event.preventDefault()
+        if (shouldPreventDefault) {
+          event.preventDefault()
+          event.stopPropagation()
+        }
         break
 
       default:

package/src/Utility/Elements/io-loader.ts

@@ -5,6 +5,7 @@
 export default class IntersectionLoader {
   el: HTMLElement
   callback: () => any
+  controller: AbortController
   observer: IntersectionObserver
   fallbackBtn?: HTMLButtonElement
   errorMsg?: HTMLElement
@@ -14,6 +15,7 @@ export default class IntersectionLoader {
     this.callback = callback
     this.fallbackBtn = this.el.querySelector("[data-load-fallback]")
     this.errorMsg = this.el.querySelector("[data-load-error]")
+    this.controller = new AbortController()
   }
 
   init = (): void => {
@@ -23,7 +25,8 @@ export default class IntersectionLoader {
       })
     })
     this.observer.observe(this.el)
-    this.fallbackBtn?.addEventListener("click", this.handleClick)
+    const { signal }: AbortController = this.controller
+    this.fallbackBtn?.addEventListener("click", this.handleClick, { signal })
   }
 
   load = async (): Promise<void> => {
@@ -31,8 +34,14 @@ export default class IntersectionLoader {
       await this.callback()
     } catch (error) {
       this.handleError(error)
+    } finally {
+      this.destroy()
     }
-    this.observer.unobserve(this.el)
+  }
+
+  destroy = (): void => {
+    this.observer.disconnect()
+    this.controller.abort()
   }
 
   handleClick = (): void => {
@@ -40,7 +49,7 @@ export default class IntersectionLoader {
   }
 
   handleError = (error): void => {
-    console.error(error) // eslint-disable-line no-console
+    if (process.env.NODE_ENV !== "production") console.error(error) // eslint-disable-line no-console
     this.errorMsg?.removeAttribute("hidden")
   }
 

package/src/Utility/Elements/validators.ts

@@ -0,0 +1,201 @@
+/**
+ * Lightweight validation utilities for common input validation needs.
+ * Provides type-safe validators without external dependencies.
+ */
+const validators = {
+  /**
+   * Validates a URL string and optionally checks protocol.
+   * @param value - URL string to validate
+   * @param allowedProtocols - Array of allowed protocols (default: ['http:', 'https:'])
+   * @returns true if valid URL with allowed protocol
+   * @example
+   * validators.url('https://example.com') // true
+   * validators.url('javascript:alert(1)') // false
+   * validators.url('ftp://example.com', ['ftp:', 'ftps:']) // true
+   */
+  url: (value: string, allowedProtocols: string[] = ["http:", "https:"]): boolean => {
+    try {
+      const url = new URL(value)
+      return allowedProtocols.includes(url.protocol)
+    } catch {
+      return false
+    }
+  },
+
+  /**
+   * Validates an email address format.
+   * Uses a simple regex pattern for basic validation.
+   * @param value - Email string to validate
+   * @returns true if valid email format
+   * @example
+   * validators.email('user@example.com') // true
+   * validators.email('invalid-email') // false
+   */
+  email: (value: string): boolean => {
+    if (typeof value !== "string") return false
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
+  },
+
+  /**
+   * Validates a number with optional min/max bounds.
+   * @param value - Value to validate as number
+   * @param min - Optional minimum value (inclusive)
+   * @param max - Optional maximum value (inclusive)
+   * @returns true if valid number within bounds
+   * @example
+   * validators.number(5, 1, 10) // true
+   * validators.number(15, 1, 10) // false
+   * validators.number('5', 1, 10) // true (converts string)
+   */
+  number: (value: any, min?: number, max?: number): boolean => {
+    const num = Number(value)
+    if (isNaN(num)) return false
+    if (min !== undefined && num < min) return false
+    if (max !== undefined && num > max) return false
+    return true
+  },
+
+  /**
+   * Validates an integer with optional min/max bounds.
+   * @param value - Value to validate as integer
+   * @param min - Optional minimum value (inclusive)
+   * @param max - Optional maximum value (inclusive)
+   * @returns true if valid integer within bounds
+   * @example
+   * validators.integer(5, 1, 10) // true
+   * validators.integer(5.5, 1, 10) // false
+   */
+  integer: (value: any, min?: number, max?: number): boolean => {
+    const num = Number(value)
+    if (isNaN(num) || !Number.isInteger(num)) return false
+    if (min !== undefined && num < min) return false
+    if (max !== undefined && num > max) return false
+    return true
+  },
+
+  /**
+   * Validates a string with optional length constraints.
+   * @param value - Value to validate as string
+   * @param minLength - Optional minimum length
+   * @param maxLength - Optional maximum length
+   * @returns true if valid string within length bounds
+   * @example
+   * validators.string('hello', 1, 10) // true
+   * validators.string('', 1, 10) // false
+   */
+  string: (value: any, minLength?: number, maxLength?: number): boolean => {
+    if (typeof value !== "string") return false
+    if (minLength !== undefined && value.length < minLength) return false
+    if (maxLength !== undefined && value.length > maxLength) return false
+    return true
+  },
+
+  /**
+   * Validates a string is not empty (after trimming).
+   * @param value - String to validate
+   * @returns true if string has content after trimming
+   * @example
+   * validators.notEmpty('hello') // true
+   * validators.notEmpty('   ') // false
+   */
+  notEmpty: (value: string): boolean => {
+    return typeof value === "string" && value.trim().length > 0
+  },
+
+  /**
+   * Validates a value matches a regex pattern.
+   * @param value - String to validate
+   * @param pattern - Regex pattern to match
+   * @returns true if value matches pattern
+   * @example
+   * validators.pattern('abc123', /^[a-z0-9]+$/) // true
+   * validators.pattern('ABC', /^[a-z]+$/) // false
+   */
+  pattern: (value: string, pattern: RegExp): boolean => {
+    if (typeof value !== "string") return false
+    // Reset lastIndex to prevent stateful behavior with global/sticky flags
+    pattern.lastIndex = 0
+    return pattern.test(value)
+  },
+
+  /**
+   * Validates a value is one of the allowed values.
+   * @param value - Value to check
+   * @param allowedValues - Array of allowed values
+   * @returns true if value is in allowed list
+   * @example
+   * validators.oneOf('red', ['red', 'green', 'blue']) // true
+   * validators.oneOf('yellow', ['red', 'green', 'blue']) // false
+   */
+  oneOf: <T>(value: T, allowedValues: T[]): boolean => {
+    return allowedValues.includes(value)
+  },
+
+  /**
+   * Validates an array with optional length constraints.
+   * @param value - Value to validate as array
+   * @param minLength - Optional minimum array length
+   * @param maxLength - Optional maximum array length
+   * @returns true if valid array within length bounds
+   * @example
+   * validators.array([1, 2, 3], 1, 5) // true
+   * validators.array([], 1, 5) // false
+   */
+  array: (value: any, minLength?: number, maxLength?: number): boolean => {
+    if (!Array.isArray(value)) return false
+    if (minLength !== undefined && value.length < minLength) return false
+    if (maxLength !== undefined && value.length > maxLength) return false
+    return true
+  },
+
+  /**
+   * Validates a value is a valid JSON string.
+   * @param value - String to validate as JSON
+   * @returns true if valid JSON string
+   * @example
+   * validators.json('{"key": "value"}') // true
+   * validators.json('invalid{json') // false
+   */
+  json: (value: string): boolean => {
+    if (typeof value !== "string") return false
+    try {
+      JSON.parse(value)
+      return true
+    } catch {
+      return false
+    }
+  },
+
+  /**
+   * Validates a date string or Date object.
+   * @param value - Date string or Date object to validate
+   * @param minDate - Optional minimum date
+   * @param maxDate - Optional maximum date
+   * @returns true if valid date within bounds
+   * @example
+   * validators.date('2024-01-01') // true
+   * validators.date('invalid-date') // false
+   */
+  date: (value: string | Date, minDate?: Date, maxDate?: Date): boolean => {
+    const date = value instanceof Date ? value : new Date(value)
+    if (isNaN(date.getTime())) return false
+    if (minDate && date < minDate) return false
+    if (maxDate && date > maxDate) return false
+    return true
+  },
+
+  /**
+   * Validates a hex color code.
+   * @param value - Color string to validate
+   * @returns true if valid hex color (3 or 6 digits)
+   * @example
+   * validators.hexColor('#fff') // true
+   * validators.hexColor('#ffffff') // true
+   * validators.hexColor('fff') // false
+   */
+  hexColor: (value: string): boolean => {
+    return typeof value === "string" && /^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/.test(value)
+  },
+}
+
+export default validators

package/src/Utility/Hooks/useLocalStorage.ts

@@ -19,6 +19,10 @@ const removeLocalStorageItem = (key: string): void => {
   window.dispatchEvent(new StorageEvent("storage", { key, newValue: null }))
 }
 
+const getServerSnapshot = (): never => {
+  throw Error("useLocalStorage is a client-only hook")
+}
+
 const useLocalStorage = ({ key, initialValue }: LocalStorageProps): [string, SetStateCallback] => {
   const subscribe = useCallback((callback: LocalStorageCallback) => {
     window.addEventListener("storage", callback)
@@ -27,10 +31,6 @@ const useLocalStorage = ({ key, initialValue }: LocalStorageProps): [string, Set
 
   const getSnapshot = () => window.localStorage.getItem(key)
 
-  const getServerSnapshot = () => {
-    throw Error("useLocalStorage is a client-only hook")
-  }
-
   const store: string = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
 
   const setState = useCallback(
@@ -45,7 +45,7 @@ const useLocalStorage = ({ key, initialValue }: LocalStorageProps): [string, Set
         }
       } catch (e) {
         // eslint-disable-next-line no-console
-        console.warn(e)
+        if (process.env.NODE_ENV !== "production") console.warn(e)
       }
     },
     [key, store],
@@ -57,7 +57,17 @@ const useLocalStorage = ({ key, initialValue }: LocalStorageProps): [string, Set
     }
   }, [key, initialValue])
 
-  const value: string = store ? (JSON.parse(store) as string) : initialValue
+  const value: string = store
+    ? (() => {
+        try {
+          // Parse JSON once - no need for separate validation
+          return JSON.parse(store) as string
+        } catch {
+          return initialValue
+        }
+      })()
+    : initialValue
+
   return [value, setState]
 }
 

package/src/Utility/Hooks/useMediaQuery.ts

@@ -2,6 +2,10 @@ import { useCallback, useSyncExternalStore } from "react"
 
 type MediaQueryCallBack = (this: MediaQueryList, ev: MediaQueryListEvent) => void
 
+const getServerSnapshot = (): never => {
+  throw Error("useMediaQuery is a client-only hook")
+}
+
 const useMediaQuery = (query: string): boolean => {
   const subscribe = useCallback(
     (callback: MediaQueryCallBack) => {
@@ -17,10 +21,6 @@ const useMediaQuery = (query: string): boolean => {
 
   const getSnapshot = () => window.matchMedia(query).matches
 
-  const getServerSnapshot = () => {
-    throw Error("useMediaQuery is a client-only hook")
-  }
-
   return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
 }
 

package/src/Utility/README.md

@@ -1,15 +1,44 @@
 # Utilities
 
-Common code, used by other components, and utility classes.
+Common code used by components, plus utility CSS classes and a print stylesheet.
 
 ### How to use
 
 **CSS**
 
-`@import '@pnx-mixtape/mxds/src/Utility/utilities.css';`
+```css
+@import "@pnx-mixtape/mxds/src/Utility/utilities.css";
+```
+
+**Print Stylesheet**
+
+This file includes styles that optimize the layout for printing, such as hiding non-essential elements, vertically
+stacking all content and adjusting typography and spacing.
+
+```css
+@import "@pnx-mixtape/mxds/src/Utility/print.css";
+
+/* Add your print-specific styles here */
+```
+
+The print stylesheet is designed to be loaded separately with the `media="print"` attribute to avoid unnecessary bloat
+that can delaying render of the screen styles.
+
+```html
+<link rel="stylesheet" media="print" href="path/to/print.css" />
+```
 
 **JS**
 
-`import { loadOnReady, etc } from '@pnx-mixtape/mxds';`
+```typescript
+import {
+  loadOnReady,
+  validators,
+  createElement,
+  makeAnchor,
+  DisclosureWidget,
+  Keyboard,
+} from "@pnx-mixtape/mxds"
+```
 
-** @todo write documentation for each of them **
+See [API Documentation](../../docs/API.md) for full reference.

package/src/Utility/_mixins.css

@@ -0,0 +1,19 @@
+@define-mixin sr-only {
+  clip-path: inset(50%);
+  inline-size: 1px;
+  block-size: 1px;
+  margin: -1px;
+  overflow: hidden;
+  position: absolute;
+  white-space: nowrap;
+}
+
+@define-mixin sr-undo {
+  clip-path: none;
+  position: revert !important;
+  margin: revert;
+  block-size: revert;
+  inline-size: revert;
+  overflow: revert;
+  white-space: revert;
+}

package/src/Utility/global.d.ts

@@ -17,4 +17,14 @@ declare global {
   }
 }
 
+import type { HTMLAttributes } from "react"
+
+declare module "react/jsx-runtime" {
+  namespace JSX {
+    interface IntrinsicElements {
+      selectedcontent: HTMLAttributes<HTMLElement>
+    }
+  }
+}
+
 export {}