@hkdigital/lib-core 0.3.1

package/dist/util/design-system/components/states.js

@@ -0,0 +1,22 @@
+/**
+ * Generates state classes from an object of state variables
+ *
+ * @param {Object.<string, boolean>} stateObject
+ *   Object with state names as keys and boolean values
+ *
+ * @returns {string} Space-separated string of state classes
+ *
+ * @example
+ * // Returns "state-selected state-error"
+ * toStateClasses({ selected: true, loading: false, error: true });
+ */
+export function toStateClasses(stateObject) {
+  if (!stateObject || typeof stateObject !== 'object') {
+    return '';
+  }
+
+  return Object.entries(stateObject)
+    .filter((entry) => entry[1] === true)
+    .map(([state]) => `state-${state}`)
+    .join(' ');
+}

package/dist/util/design-system/css/clamp.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Extract clamp parameters from a CSS variable
+ *
+ * @param {string} varName - CSS variable name without '--'
+ * @returns {Object} Object with min and max values
+ * @throws {Error} If the CSS variable doesn't exist or doesn't contain a valid clamp function
+ */
+export function getClampParams(varName: string): any;
+/**
+ * CSS clamp function implementation
+ *
+ * @param {number} min - Minimum value
+ * @param {number} value - Value to clamp
+ * @param {number} max - Maximum value
+ * @returns {number} Clamped value
+ */
+export function clamp(min: number, value: number, max: number): number;

package/dist/util/design-system/css/clamp.js

@@ -0,0 +1,66 @@
+import { getRootCssVar } from '../../css/index.js';
+
+/**
+ * Cache to that ensures we parse CSS clamp parameters only once
+ * @type {Object.<string, {min: number, max: number}>}
+ */
+let clampParamCache = {};
+
+/**
+ * Extract clamp parameters from a CSS variable
+ *
+ * @param {string} varName - CSS variable name without '--'
+ * @returns {Object} Object with min and max values
+ * @throws {Error} If the CSS variable doesn't exist or doesn't contain a valid clamp function
+ */
+export function getClampParams(varName) {
+  // Check cache first
+  if (clampParamCache[varName]) {
+    return clampParamCache[varName];
+  }
+
+  // Get the CSS variable value using the existing utility
+  const declaration = getRootCssVar(varName);
+
+  if (declaration === null) {
+    throw new Error(`CSS variable --${varName} not found`);
+  }
+
+  // Parse clamp() function values
+  const clampMatch =
+    typeof declaration === 'string'
+      ? declaration.match(
+          /clamp\s*\(\s*([\d.]+)\s*,\s*[^,]+\s*,\s*([\d.]+)\s*\)/
+        )
+      : null;
+
+  if (!clampMatch || clampMatch.length < 3) {
+    // console.log(declaration);
+    throw new Error(
+      `CSS variable --${varName} does not contain a valid clamp function`
+    );
+  }
+
+  const min = parseFloat(clampMatch[1]);
+  const max = parseFloat(clampMatch[2]);
+
+  if (isNaN(min) || isNaN(max)) {
+    throw new Error(`Invalid min/max values in CSS variable --${varName}`);
+  }
+
+  // Cache the result
+  clampParamCache[varName] = { min, max };
+  return { min, max };
+}
+
+/**
+ * CSS clamp function implementation
+ *
+ * @param {number} min - Minimum value
+ * @param {number} value - Value to clamp
+ * @param {number} max - Maximum value
+ * @returns {number} Clamped value
+ */
+export function clamp(min, value, max) {
+  return Math.max(min, Math.min(value, max));
+}

package/dist/util/design-system/css/root-design-vars.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Generates a complete HTML style tag with CSS custom properties for
+ * the design system based on provided configuration.
+ *
+ * @param {Object} design - Design dimensions configuration
+ * @param {number} design.width - The design width in pixels
+ * @param {number} design.height - The design height in pixels
+ * @param {Object} clamping - Scaling configuration parameters
+ * @param {Object} clamping.ui - UI clamping configuration
+ * @param {number} clamping.ui.min - Minimum UI scaling factor
+ * @param {number} clamping.ui.max - Maximum UI scaling factor
+ * @param {Object} clamping.textBase - Base text scaling configuration
+ * @param {number} clamping.textBase.min - Minimum base text scaling
+ * @param {number} clamping.textBase.max - Maximum base text scaling
+ * @param {Object} clamping.textHeading - Heading text clamping configuration
+ * @param {number} clamping.textHeading.min - Minimum heading text scaling
+ * @param {number} clamping.textHeading.max - Maximum heading text scaling
+ * @param {Object} clamping.textUi - UI text clamping configuration
+ * @param {number} clamping.textUi.min - Minimum UI text scaling
+ * @param {number} clamping.textUi.max - Maximum UI text scaling
+ *
+ * @returns {string} Complete HTML style tag with design system CSS variables
+ *
+ * @example
+ * // +layout.svelte
+ * <script>
+ * import { DESIGN, CLAMPING } from '../../../tailwind/extend/clamping/config.js';
+ *
+ * import { rootDesignVarsHTML } from '../index.js';
+ * </script>
+ *
+ * <svelte:head>
+ * {@html rootDesignVarsHTML(DESIGN, CLAMPING)}
+ * </svelte:head>
+ *
+ * // Generates style tag for use in svelte:head
+ * // <style>:root { --design-width: 1920; ... }</style>
+ */
+export function rootDesignVarsHTML(design: {
+    width: number;
+    height: number;
+}, clamping: {
+    ui: {
+        min: number;
+        max: number;
+    };
+    textBase: {
+        min: number;
+        max: number;
+    };
+    textHeading: {
+        min: number;
+        max: number;
+    };
+    textUi: {
+        min: number;
+        max: number;
+    };
+}): string;
+/**
+ * Get design width from CSS variables
+ *
+ * @returns {number} Design width
+ */
+export function getRootCssDesignWidth(): number;
+/**
+ * Get design height from CSS variables
+ *
+ * @returns {number} Design height
+ */
+export function getRootCssDesignHeight(): number;
+/**
+ * Retrieves all current scaling factors from CSS variables
+ *
+ * @returns {Object} An object containing all scaling factors
+ */
+export function getAllRootScalingVars(): any;

package/dist/util/design-system/css/root-design-vars.js

@@ -0,0 +1,102 @@
+import { getRootCssVar } from '../../css/css-vars.js';
+
+/**
+ * Generates a complete HTML style tag with CSS custom properties for
+ * the design system based on provided configuration.
+ *
+ * @param {Object} design - Design dimensions configuration
+ * @param {number} design.width - The design width in pixels
+ * @param {number} design.height - The design height in pixels
+ * @param {Object} clamping - Scaling configuration parameters
+ * @param {Object} clamping.ui - UI clamping configuration
+ * @param {number} clamping.ui.min - Minimum UI scaling factor
+ * @param {number} clamping.ui.max - Maximum UI scaling factor
+ * @param {Object} clamping.textBase - Base text scaling configuration
+ * @param {number} clamping.textBase.min - Minimum base text scaling
+ * @param {number} clamping.textBase.max - Maximum base text scaling
+ * @param {Object} clamping.textHeading - Heading text clamping configuration
+ * @param {number} clamping.textHeading.min - Minimum heading text scaling
+ * @param {number} clamping.textHeading.max - Maximum heading text scaling
+ * @param {Object} clamping.textUi - UI text clamping configuration
+ * @param {number} clamping.textUi.min - Minimum UI text scaling
+ * @param {number} clamping.textUi.max - Maximum UI text scaling
+ *
+ * @returns {string} Complete HTML style tag with design system CSS variables
+ *
+ * @example
+ * // +layout.svelte
+ * <script>
+ * import { DESIGN, CLAMPING } from '../../../tailwind/extend/clamping/config.js';
+ *
+ * import { rootDesignVarsHTML } from '../index.js';
+ * </script>
+ *
+ * <svelte:head>
+ * {@html rootDesignVarsHTML(DESIGN, CLAMPING)}
+ * </svelte:head>
+ *
+ * // Generates style tag for use in svelte:head
+ * // <style>:root { --design-width: 1920; ... }</style>
+ */
+export function rootDesignVarsHTML(design, clamping) {
+  return `<style>:root {
+      /* Design dimensions */
+      --design-width: ${design.width};
+      --design-height: ${design.height};
+
+      /* Scaling factors */
+      --scale-w: 1;
+      --scale-h: 1;
+
+      /* --scale-viewport: min(var(--scale-w), var(--scale-h)); */
+      --scale-viewport: 1;
+
+      /* Base clamping units */
+      --scale-ui: clamp(${clamping.ui.min}, var(--scale-viewport), ${clamping.ui.max});
+      --scale-text-base: clamp(${clamping.textBase.min}, var(--scale-viewport), ${clamping.textBase.max});
+      --scale-text-heading: clamp(${clamping.textHeading.min}, var(--scale-viewport), ${clamping.textHeading.max});
+      --scale-text-ui: clamp(${clamping.textUi.min}, var(--scale-viewport), ${clamping.textUi.max});
+    }</style>`;
+}
+
+/**
+ * Get design width from CSS variables
+ *
+ * @returns {number} Design width
+ */
+export function getRootCssDesignWidth() {
+  return getRootCssVar('design-width');
+}
+
+/**
+ * Get design height from CSS variables
+ *
+ * @returns {number} Design height
+ */
+export function getRootCssDesignHeight() {
+  return getRootCssVar('design-height');
+}
+
+/**
+ * Retrieves all current scaling factors from CSS variables
+ *
+ * @returns {Object} An object containing all scaling factors
+ */
+export function getAllRootScalingVars() {
+  const styles = getComputedStyle(document.documentElement);
+
+  return {
+    scaleW: parseFloat(styles.getPropertyValue('--scale-w').trim()) || 0,
+    scaleH: parseFloat(styles.getPropertyValue('--scale-h').trim()) || 0,
+    scaleViewport:
+      parseFloat(styles.getPropertyValue('--scale-viewport').trim()) || 0,
+
+    scaleUI: parseFloat(styles.getPropertyValue('--scale-ui').trim()) || 0,
+    scaleTextBase:
+      parseFloat(styles.getPropertyValue('--scale-text-base').trim()) || 0,
+    scaleTextHeading:
+      parseFloat(styles.getPropertyValue('--scale-text-heading').trim()) || 0,
+    scaleTextUI:
+      parseFloat(styles.getPropertyValue('--scale-text-ui').trim()) || 0
+  };
+}

package/dist/util/design-system/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./css/clamp.js";
+export * from "./css/root-design-vars.js";
+export * from "./components/states.js";
+export * from "./layout/scaling.js";
+export * from "./tailwind.js";

package/dist/util/design-system/index.js

@@ -0,0 +1,5 @@
+export * from './css/clamp.js';
+export * from './css/root-design-vars.js';
+export * from './components/states.js';
+export * from './layout/scaling.js';
+export * from './tailwind.js';

package/dist/util/design-system/layout/scaling.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Manages responsive design scaling by calculating and applying scale factors
+ * based on container dimensions and design system requirements.
+ *
+ * @param {Object} options - Configuration options
+ * @param {HTMLElement} options.container - The container element to apply scaling to
+ * @param {Object} options.design - The base design dimensions
+ * @param {number} options.design.width - The reference design width
+ * @param {number} options.design.height - The reference design height
+ * @param {Object} options.clamping - The min/max values for various scale factors
+ * @param {Object} options.clamping.ui - UI element scaling constraints
+ * @param {number} options.clamping.ui.min - Minimum UI scale factor
+ * @param {number} options.clamping.ui.max - Maximum UI scale factor
+ * @param {Object} options.clamping.textBase - Base text scaling constraints
+ * @param {number} options.clamping.textBase.min - Minimum base text scale factor
+ * @param {number} options.clamping.textBase.max - Maximum base text scale factor
+ * @param {Object} options.clamping.textHeading - Heading text scaling constraints
+ * @param {number} options.clamping.textHeading.min - Minimum heading text scale factor
+ * @param {number} options.clamping.textHeading.max - Maximum heading text scale factor
+ * @param {Object} options.clamping.textUi - UI text scaling constraints
+ * @param {number} options.clamping.textUi.min - Minimum UI text scale factor
+ * @param {number} options.clamping.textUi.max - Maximum UI text scale factor
+ * @param {Function} [options.getDimensions] - Optional function to get width and height
+ * @param {boolean} [options.useResizeObserver=true] - Whether to use ResizeObserver
+ *
+ * @returns {()=>void} A cleanup function that removes event listeners and observers
+ */
+export function enableContainerScaling({ container, design, clamping, getDimensions, useResizeObserver }: {
+    container: HTMLElement;
+    design: {
+        width: number;
+        height: number;
+    };
+    clamping: {
+        ui: {
+            min: number;
+            max: number;
+        };
+        textBase: {
+            min: number;
+            max: number;
+        };
+        textHeading: {
+            min: number;
+            max: number;
+        };
+        textUi: {
+            min: number;
+            max: number;
+        };
+    };
+    getDimensions?: Function;
+    useResizeObserver?: boolean;
+}): () => void;
+/**
+ * Manages responsive design scaling by calculating and applying scale factors
+ * based on viewport dimensions and design system requirements.
+ *
+ * @param {Object} design - The base design dimensions
+ * @param {number} design.width - The reference design width
+ * @param {number} design.height - The reference design height
+ * @param {Object} clamping - The min/max values for various scale factors
+ * @param {Object} clamping.ui - UI element scaling constraints
+ * @param {number} clamping.ui.min - Minimum UI scale factor
+ * @param {number} clamping.ui.max - Maximum UI scale factor
+ * @param {Object} clamping.textBase - Base text scaling constraints
+ * @param {number} clamping.textBase.min - Minimum base text scale factor
+ * @param {number} clamping.textBase.max - Maximum base text scale factor
+ * @param {Object} clamping.textHeading - Heading text scaling constraints
+ * @param {number} clamping.textHeading.min - Minimum heading text scale factor
+ * @param {number} clamping.textHeading.max - Maximum heading text scale factor
+ * @param {Object} clamping.textUi - UI text scaling constraints
+ * @param {number} clamping.textUi.min - Minimum UI text scale factor
+ * @param {number} clamping.textUi.max - Maximum UI text scale factor
+ *
+ * @returns {()=>void} A cleanup function that removes the event listener
+ */
+export function enableScalingUI(design: {
+    width: number;
+    height: number;
+}, clamping: {
+    ui: {
+        min: number;
+        max: number;
+    };
+    textBase: {
+        min: number;
+        max: number;
+    };
+    textHeading: {
+        min: number;
+        max: number;
+    };
+    textUi: {
+        min: number;
+        max: number;
+    };
+}): () => void;

package/dist/util/design-system/layout/scaling.js

@@ -0,0 +1,228 @@
+import { clamp } from '../css/clamp.js';
+
+/**
+ * Manages responsive design scaling by calculating and applying scale factors
+ * based on container dimensions and design system requirements.
+ *
+ * @param {Object} options - Configuration options
+ * @param {HTMLElement} options.container - The container element to apply scaling to
+ * @param {Object} options.design - The base design dimensions
+ * @param {number} options.design.width - The reference design width
+ * @param {number} options.design.height - The reference design height
+ * @param {Object} options.clamping - The min/max values for various scale factors
+ * @param {Object} options.clamping.ui - UI element scaling constraints
+ * @param {number} options.clamping.ui.min - Minimum UI scale factor
+ * @param {number} options.clamping.ui.max - Maximum UI scale factor
+ * @param {Object} options.clamping.textBase - Base text scaling constraints
+ * @param {number} options.clamping.textBase.min - Minimum base text scale factor
+ * @param {number} options.clamping.textBase.max - Maximum base text scale factor
+ * @param {Object} options.clamping.textHeading - Heading text scaling constraints
+ * @param {number} options.clamping.textHeading.min - Minimum heading text scale factor
+ * @param {number} options.clamping.textHeading.max - Maximum heading text scale factor
+ * @param {Object} options.clamping.textUi - UI text scaling constraints
+ * @param {number} options.clamping.textUi.min - Minimum UI text scale factor
+ * @param {number} options.clamping.textUi.max - Maximum UI text scale factor
+ * @param {Function} [options.getDimensions] - Optional function to get width and height
+ * @param {boolean} [options.useResizeObserver=true] - Whether to use ResizeObserver
+ *
+ * @returns {()=>void} A cleanup function that removes event listeners and observers
+ */
+export function enableContainerScaling({
+  container,
+  design,
+  clamping,
+  getDimensions,
+  useResizeObserver = true
+}) {
+  if (!container) {
+    throw new Error('Container element is required for enableContainerScaling');
+  }
+
+  let resizeObserver;
+
+  /**
+   * Updates CSS scale variables based on container dimensions
+   * and design system constraints
+   */
+  function updateScaleValues() {
+    try {
+      let containerWidth, containerHeight;
+
+      // Use custom dimension getter if provided
+      if (typeof getDimensions === 'function') {
+        const dimensions = getDimensions();
+        containerWidth = dimensions.width;
+        containerHeight = dimensions.height;
+      } else {
+        // Otherwise use container's client dimensions
+        const rect = container.getBoundingClientRect();
+        containerWidth = rect.width;
+        containerHeight = rect.height;
+      }
+
+      // Skip update if dimensions are zero (container not visible)
+      if (containerWidth <= 0 || containerHeight <= 0) {
+        return;
+      }
+
+      // Calculate scale factors based on container size relative to design dimensions
+      const scaleW = containerWidth / design.width;
+      const scaleH = containerHeight / design.height;
+
+      // Use the smaller scale factor to ensure content fits within container
+      const scaleViewport = Math.min(scaleW, scaleH);
+
+      // Apply clamping to different element types
+      const scaleUI = clamp(clamping.ui.min, scaleViewport, clamping.ui.max);
+
+      const scaleTextBase = clamp(
+        clamping.textBase.min,
+        scaleViewport,
+        clamping.textBase.max
+      );
+
+      const scaleTextHeading = clamp(
+        clamping.textHeading.min,
+        scaleViewport,
+        clamping.textHeading.max
+      );
+
+      const scaleTextUi = clamp(
+        clamping.textUi.min,
+        scaleViewport,
+        clamping.textUi.max
+      );
+
+      // Set CSS custom properties on the container
+      container.style.setProperty('--scale-w', String(scaleW));
+      container.style.setProperty('--scale-h', String(scaleH));
+      container.style.setProperty('--scale-viewport', String(scaleViewport));
+      container.style.setProperty('--scale-ui', String(scaleUI));
+      container.style.setProperty('--scale-text-base', String(scaleTextBase));
+      container.style.setProperty(
+        '--scale-text-heading',
+        String(scaleTextHeading)
+      );
+      container.style.setProperty('--scale-text-ui', String(scaleTextUi));
+    } catch (error) {
+      console.error('Error updating container scale values:', error);
+    }
+  }
+
+  // Initialize scales
+  updateScaleValues();
+
+  // Set up ResizeObserver for container resize detection
+  if (useResizeObserver && typeof ResizeObserver !== 'undefined') {
+    resizeObserver = new ResizeObserver(updateScaleValues);
+    resizeObserver.observe(container);
+  } else {
+    // Fallback to window resize event
+    window.addEventListener('resize', updateScaleValues);
+  }
+
+  // Return cleanup function
+  return function cleanup() {
+    if (resizeObserver) {
+      resizeObserver.disconnect();
+    } else {
+      window.removeEventListener('resize', updateScaleValues);
+    }
+  };
+}
+
+/**
+ * Manages responsive design scaling by calculating and applying scale factors
+ * based on viewport dimensions and design system requirements.
+ *
+ * @param {Object} design - The base design dimensions
+ * @param {number} design.width - The reference design width
+ * @param {number} design.height - The reference design height
+ * @param {Object} clamping - The min/max values for various scale factors
+ * @param {Object} clamping.ui - UI element scaling constraints
+ * @param {number} clamping.ui.min - Minimum UI scale factor
+ * @param {number} clamping.ui.max - Maximum UI scale factor
+ * @param {Object} clamping.textBase - Base text scaling constraints
+ * @param {number} clamping.textBase.min - Minimum base text scale factor
+ * @param {number} clamping.textBase.max - Maximum base text scale factor
+ * @param {Object} clamping.textHeading - Heading text scaling constraints
+ * @param {number} clamping.textHeading.min - Minimum heading text scale factor
+ * @param {number} clamping.textHeading.max - Maximum heading text scale factor
+ * @param {Object} clamping.textUi - UI text scaling constraints
+ * @param {number} clamping.textUi.min - Minimum UI text scale factor
+ * @param {number} clamping.textUi.max - Maximum UI text scale factor
+ *
+ * @returns {()=>void} A cleanup function that removes the event listener
+ */
+export function enableScalingUI(design, clamping) {
+  /**
+   * Updates CSS scale variables based on current viewport dimensions
+   * and design system constraints
+   */
+  function updateScaleValues() {
+    try {
+      const vw = window.innerWidth;
+      const vh = window.innerHeight;
+
+      // Calculate scale factors based on viewport size relative to design dimensions
+      const scaleW = vw / design.width;
+      const scaleH = vh / design.height;
+
+      // Use the smaller scale factor to ensure content fits within viewport
+      const scaleViewport = Math.min(scaleW, scaleH);
+
+      // Apply clamping to different element types
+      const scaleUI = clamp(clamping.ui.min, scaleViewport, clamping.ui.max);
+
+      const scaleTextBase = clamp(
+        clamping.textBase.min,
+        scaleViewport,
+        clamping.textBase.max
+      );
+
+      const scaleTextHeading = clamp(
+        clamping.textHeading.min,
+        scaleViewport,
+        clamping.textHeading.max
+      );
+
+      const scaleTextUi = clamp(
+        clamping.textUi.min,
+        scaleViewport,
+        clamping.textUi.max
+      );
+
+      // Set CSS custom properties for use in the design system
+      document.documentElement.style.setProperty('--scale-w', String(scaleW));
+      document.documentElement.style.setProperty('--scale-h', String(scaleH));
+      document.documentElement.style.setProperty(
+        '--scale-viewport',
+        String(scaleViewport)
+      );
+      document.documentElement.style.setProperty('--scale-ui', String(scaleUI));
+      document.documentElement.style.setProperty(
+        '--scale-text-base',
+        String(scaleTextBase)
+      );
+      document.documentElement.style.setProperty(
+        '--scale-text-heading',
+        String(scaleTextHeading)
+      );
+      document.documentElement.style.setProperty(
+        '--scale-text-ui',
+        String(scaleTextUi)
+      );
+    } catch (error) {
+      console.error('Error updating design scale values:', error);
+    }
+  }
+
+  // Initialize scales and attach resize listener
+  updateScaleValues();
+  window.addEventListener('resize', updateScaleValues);
+
+  // Return cleanup function
+  return function cleanup() {
+    window.removeEventListener('resize', updateScaleValues);
+  };
+}

package/dist/util/design-system/skeleton.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Creates utility classes for UI font styling that work with Skeleton themes
+ *
+ * This plugin adds utility classes for UI typography that reference CSS
+ * variables defined in your Skeleton theme, allowing consistent styling of UI
+ * elements across your application.
+ *
+ * @note Important Configuration Requirements:
+ * 1. Add UI font variables to your theme file:
+ *    - `--ui-font-family`: Font family for UI elements
+ *      (falls back to `--base-font-family`)
+ *    - `--ui-font-color`: Text color for UI elements
+ *      (falls back to `--base-font-color`)
+ *    - `--ui-font-color-dark`: Dark mode text color
+ *      (falls back to `--base-font-color-dark`)
+ *
+ * 2. This plugin generates the following utility classes:
+ *    - `font-ui`: Applies UI font family
+ *    - `text-ui`: Applies UI text color
+ *    - `text-ui-dark`: Applies UI dark mode text color (with .dark selector)
+ *
+ * @example
+ * // tailwind.config.js
+ * import { customUtilitiesPlugin }
+ *   from './src/lib/util/design-system/skeleton.js';
+ *
+ * export default {
+ *   plugins: [
+ *     customUtilitiesPlugin,
+ *     skeleton({
+ *       themes: [defaultThemes.cerberus, customThemes.yourTheme]
+ *     })
+ *   ]
+ * };
+ *
+ * @param {Object} api - Tailwind plugin API
+ * @param {Function} api.addUtilities - Function to add utilities
+ */
+export function customUtilitiesPlugin({ addUtilities, theme }: {
+    addUtilities: Function;
+}): void;