@hkdigital/lib-core 0.3.1

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

@@ -0,0 +1,208 @@
+/**
+ * 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 }) {
+  const fontFamilyUtilities = {
+    '.font-heading': {
+      'font-family': 'var(--heading-font-family)'
+    },
+    '.font-base': {
+      'font-family': 'var(--base-font-family)'
+    },
+    '.font-ui': {
+      'font-family': 'var(--ui-font-family, var(--base-font-family))'
+    }
+  };
+
+  const textColorUtilities = {
+    '.text-base-color': {
+      color: 'var(--base-font-color)'
+    },
+    '.text-base-color-dark': {
+      color: 'var(--base-font-color-dark)'
+    },
+    '.text-heading-color': {
+      color: 'var(--heading-font-color)'
+    },
+    '.text-heading-color-dark': {
+      color: 'var(--heading-font-color-dark)'
+    },
+    '.text-ui-color': {
+      color: 'var(--ui-font-color, var(--base-font-color))'
+    },
+    '.text-ui-color-dark': {
+      color: 'var(--ui-font-color-dark, var(--base-font-color-dark))'
+    }
+  };
+
+  const typographyUtilities = generateTypographyUtilities(theme);
+
+  addUtilities({
+    ...typographyUtilities,
+    ...fontFamilyUtilities,
+    ...textColorUtilities
+  });
+}
+
+/**
+ * Generates typography utility classes based on fontSize entries in the
+ * Tailwind theme
+ *
+ * This function creates typography utility classes for entries in the
+ * theme's fontSize configuration that start with 'heading-', 'base-', or
+ * 'ui-' prefixes. Each class includes font size, line height, font weight,
+ * font family, and color properties.
+ *
+ * @param {Function} theme - Tailwind's theme function to access configuration
+ * @returns {Object} An object containing the generated typography utility classes
+ *
+ * @example
+ * // In your Tailwind plugin:
+ * const typographyUtils = generateTypographyUtilities(theme);
+ * addUtilities(typographyUtils);
+ *
+ * @example
+ * // Example output format:
+ * // {
+ * //   '.type-heading-h1': {
+ * //     fontSize: 'calc(32px * var(--scale-text-heading))',
+ * //     lineHeight: '1.25',
+ * //     fontWeight: '700',
+ * //     fontFamily: 'var(--heading-font-family)',
+ * //     fontStyle: 'var(--heading-font-style)',
+ * //     letterSpacing: 'var(--heading-letter-spacing)',
+ * //     color: 'rgb(var(--heading-font-color))'
+ * //   }
+ * // }
+ */
+function generateTypographyUtilities(theme) {
+  // Get font sizes from theme
+  const fontSizes = theme('fontSize');
+
+  // Create typography utilities
+  const typographyUtilities = {};
+
+  // Process all fontSize entries and create type- classes for them
+  Object.entries(fontSizes).forEach(([key, value]) => {
+    // Skip entries that don't match our prefixes
+    if (
+      !key.startsWith('heading-') &&
+      !key.startsWith('base-') &&
+      !key.startsWith('ui-')
+    ) {
+      return;
+    }
+
+    const [size, options] = Array.isArray(value) ? value : [value, {}];
+
+    // Determine properties based on the prefix
+    let properties = {};
+
+    let propertiesDark;
+
+    if (key.startsWith('heading-')) {
+      properties = {
+        lineHeight: options.lineHeight || 'normal',
+        fontFamily: 'var(--heading-font-family)',
+        fontStyle: 'var(--heading-font-style)',
+        fontWeight: 'var(--heading-font-weight)',
+        letterSpacing: 'var(--heading-letter-spacing)',
+        color: 'var(--heading-font-color)'
+      };
+
+      propertiesDark = {
+        ...properties,
+        color: 'var(--heading-font-color-dark)'
+      };
+    } else if (key.startsWith('base-')) {
+      properties = {
+        lineHeight: options.lineHeight || 'normal',
+        fontFamily: 'var(--base-font-family)',
+        fontWeight: 'var(--base-font-weight)',
+        letterSpacing: 'var(--base-letter-spacing)',
+        color: 'var(--base-font-color)'
+      };
+
+      propertiesDark = {
+        ...properties,
+        color: 'var(--base-font-color-dark)'
+      };
+    } else if (key.startsWith('ui-')) {
+      properties = {
+        lineHeight: options.lineHeight || 'normal',
+        fontFamily: 'var(--ui-font-family, var(--base-font-family))',
+        fontWeight: 'var(--ui-font-weight)',
+        letterSpacing: 'var(--ui-letter-spacing, var(--base-letter-spacing))',
+        color: 'var(--ui-font-color, var(--base-font-color))'
+      };
+
+      propertiesDark = {
+        ...properties,
+        color: 'var(--ui-font-color-dark, var(--base-font-color-dark))'
+      };
+    }
+
+    // Create the utility class using the original key
+    typographyUtilities[`.type-${key}`] = {
+      fontSize: size,
+      ...properties,
+      // Include any other properties defined in the fontSize options
+      ...Object.fromEntries(
+        Object.entries(options).filter(
+          ([k]) => !['lineHeight'].includes(k)
+        )
+      )
+    };
+
+    // Create the utility class using the original key for dark
+    typographyUtilities[`.type-${key}-dark`] = {
+      fontSize: size,
+      ...propertiesDark,
+      // Include any other properties defined in the fontSize options
+      ...Object.fromEntries(
+        Object.entries(options).filter(
+          ([k]) => !['lineHeight'].includes(k)
+        )
+      )
+    };
+  });
+
+  // console.debug(typographyUtilities);
+
+  return typographyUtilities;
+}

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

@@ -0,0 +1,183 @@
+/**
+ * Generates text-based spacing units with with different scaling
+ * units (ut, bt, ht)
+ *
+ * @param {number[]} values
+ *   Array of pixel values to generate text-based spacing units for
+ *
+ * @returns {{[key: string]: string}}
+ *   Generated text-based spacing units with ut, bt, and ht suffixes
+ *
+ * @throws {Error} If values is not an array or contains non-numeric values
+ *
+ * @example
+ * generateTextBasedSpacing([1, 2, 4, 8])
+ * // Returns:
+ * // {
+ * //   '1ut': 'calc(1px * var(--scale-text-ui))',
+ * //   '2ut': 'calc(2px * var(--scale-text-ui))',
+ * //   '1bt': 'calc(1px * var(--scale-text-base))',
+ * //   '2bt': 'calc(2px * var(--scale-text-base))',
+ * //   '1ht': 'calc(1px * var(--scale-text-heading))',
+ * //   '2ht': 'calc(2px * var(--scale-text-heading))'
+ * // }
+ */
+export function generateTextBasedSpacing(values: number[]): {
+    [key: string]: string;
+};
+/**
+ * Generates viewport-based spacing units with different scaling
+ * units (up, wp, hp)
+ *
+ * @param {number[]} values
+ *   Array of pixel values to generate viewport-based spacing units for
+ *
+ * @returns {Object.<string, string>}
+ *   Generated viewport-based spacing units:
+ *   - up: UI points (clamped scaling)
+ *   - p:  UI points (deprecated, will be removed in future versions)
+ *   - wp: Width points
+ *   - hp: Height points
+ *
+ * @throws {Error} If values is not an array or contains non-numeric values
+ *
+ * @example
+ * generateViewportBasedSpacing([1, 2, 4])
+ * // Returns:
+ * // {
+ * //   '1up': 'calc(1px * var(--scale-ui))',
+ * //   '1p': 'calc(1px * var(--scale-ui))',  // deprecated
+ * //   '1wp': 'calc(1px * var(--scale-w))',
+ * //   '1hp': 'calc(1px * var(--scale-h))'
+ * // }
+ */
+export function generateViewportBasedSpacing(values: number[]): {
+    [x: string]: string;
+};
+/**
+ * @typedef {{
+ *   size?: number,
+ *   lineHeight?: number|string
+ *  }} TextStyleSizes
+ */
+/**
+ * Generates semantic text style definitions for a specific text category
+ * (base, UI, or heading). Each style includes a scaled font size and
+ * line height.
+ *
+ * @param {{[key: string]: TextStyleSizes}} sizes
+ *   Set of text sizes to generate styles for
+ *
+ * @param {'base' | 'ui' | 'heading'} category
+ *   Text category to generate styles for
+ *
+ * @returns {{[key: string]: [string, {lineHeight: number}]}}
+ *   Generated text styles in Tailwind format
+ *
+ * @throws {Error} If a size has an invalid size or lineHeight
+ *
+ * @example
+ * const TEXT_BASE_SIZES = {
+ *   sm: { size: 16, lineHeight: 1.5 },
+ *   md: { size: 20, lineHeight: 1.5 },
+ *   lg: { size: 24, lineHeight: 1.4 }
+ * };
+ *
+ * generateTextStyles(TEXT_BASE_SIZES, 'base');
+ * // Returns:
+ * // {
+ * //   'base-sm':
+ * //     ['calc(16px * var(--scale-text-base))', { lineHeight: 1.5 }],
+ * //   'base-md':
+ * //     ['calc(20px * var(--scale-text-base))', { lineHeight: 1.5 }],
+ * //   'base-lg':
+ * //     ['calc(24px * var(--scale-text-base))', { lineHeight: 1.4 }]
+ * // }
+ */
+export function generateTextStyles(sizes: {
+    [key: string]: TextStyleSizes;
+}, category: "base" | "ui" | "heading"): {
+    [key: string]: [string, {
+        lineHeight: number;
+    }];
+};
+/**
+ * Generates border radius styles with UI scaling
+ *
+ * @param {{[key: string]: string | {size: number}}} sizes
+ *   Set of radius sizes to generate, either as:
+ *   - Object with size property (e.g., { size: 10 })
+ *   - Direct string value (e.g., '0px', '9999px')
+ *
+ * @returns {Object.<string, string>}
+ *   Generated border radius styles in Tailwind format
+ *
+ * @throws {Error} If a value has an invalid type
+ *
+ * @example
+ * const RADIUS_SIZES = {
+ *   none: '0px',
+ *   sm: { size: 10 },
+ *   md: { size: 15 },
+ *   full: '9999px'
+ * };
+ *
+ * generateBorderRadiusStyles(RADIUS_SIZES)
+ * // Returns:
+ * // {
+ * //   'none': '0px',
+ * //   'sm': 'calc(10px * var(--scale-ui))',
+ * //   'md': 'calc(15px * var(--scale-ui))',
+ * //   'full': '9999px'
+ * // }
+ */
+export function generateBorderRadiusStyles(sizes: {
+    [key: string]: string | {
+        size: number;
+    };
+}): {
+    [x: string]: string;
+};
+/**
+ * Generates width styles for various CSS properties with UI scaling and explicit naming
+ *
+ * @param {{[key: string]: {size: number}}} sizes
+ *   Set of width sizes to generate
+ *
+ * @param {string} [prefix='width']
+ *   Prefix to add before each variant name (default: 'width')
+ *
+ * @param {string} scaleVar
+ *   CSS variable to use for scaling (default: '--scale-ui')
+ *
+ * @returns {{[key: string]: string}}
+ *   Generated width styles in Tailwind format
+ *
+ * @throws {Error} If a size has an invalid type
+ *
+ * @example
+ * const WIDTH_SIZES = {
+ *   thin: { size: 1 },
+ *   normal: { size: 2 },
+ *   thick: { size: 4 }
+ * };
+ *
+ * generateWidthStyles(WIDTH_SIZES, 'width')
+ * // Returns:
+ * // {
+ * //   'width-thin': 'calc(1px * var(--scale-ui))',
+ * //   'width-normal': 'calc(2px * var(--scale-ui))',
+ * //   'width-thick': 'calc(4px * var(--scale-ui))'
+ * // }
+ */
+export function generateWidthStyles(sizes: {
+    [key: string]: {
+        size: number;
+    };
+}, prefix?: string, scaleVar?: string): {
+    [key: string]: string;
+};
+export type TextStyleSizes = {
+    size?: number;
+    lineHeight?: number | string;
+};

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

@@ -0,0 +1,288 @@
+/**
+ * Generates text-based spacing units with with different scaling
+ * units (ut, bt, ht)
+ *
+ * @param {number[]} values
+ *   Array of pixel values to generate text-based spacing units for
+ *
+ * @returns {{[key: string]: string}}
+ *   Generated text-based spacing units with ut, bt, and ht suffixes
+ *
+ * @throws {Error} If values is not an array or contains non-numeric values
+ *
+ * @example
+ * generateTextBasedSpacing([1, 2, 4, 8])
+ * // Returns:
+ * // {
+ * //   '1ut': 'calc(1px * var(--scale-text-ui))',
+ * //   '2ut': 'calc(2px * var(--scale-text-ui))',
+ * //   '1bt': 'calc(1px * var(--scale-text-base))',
+ * //   '2bt': 'calc(2px * var(--scale-text-base))',
+ * //   '1ht': 'calc(1px * var(--scale-text-heading))',
+ * //   '2ht': 'calc(2px * var(--scale-text-heading))'
+ * // }
+ */
+export function generateTextBasedSpacing(values) {
+  if (!Array.isArray(values)) {
+    throw new Error('values must be an array');
+  }
+
+  return values.reduce((units, value) => {
+    if (typeof value !== 'number' || isNaN(value)) {
+      throw new Error(`Invalid spacing value: ${value}. Must be a number.`);
+    }
+
+    // Generate UI text spacing units
+    units[`${value}ut`] = `calc(${value}px * var(--scale-text-ui))`;
+
+    // Generate base text spacing units
+    units[`${value}bt`] = `calc(${value}px * var(--scale-text-base))`;
+
+    // Generate heading text spacing units
+    units[`${value}ht`] = `calc(${value}px * var(--scale-text-heading))`;
+
+    return units;
+  }, {});
+}
+
+/**
+ * Generates viewport-based spacing units with different scaling
+ * units (up, wp, hp)
+ *
+ * @param {number[]} values
+ *   Array of pixel values to generate viewport-based spacing units for
+ *
+ * @returns {Object.<string, string>}
+ *   Generated viewport-based spacing units:
+ *   - up: UI points (clamped scaling)
+ *   - p:  UI points (deprecated, will be removed in future versions)
+ *   - wp: Width points
+ *   - hp: Height points
+ *
+ * @throws {Error} If values is not an array or contains non-numeric values
+ *
+ * @example
+ * generateViewportBasedSpacing([1, 2, 4])
+ * // Returns:
+ * // {
+ * //   '1up': 'calc(1px * var(--scale-ui))',
+ * //   '1p': 'calc(1px * var(--scale-ui))',  // deprecated
+ * //   '1wp': 'calc(1px * var(--scale-w))',
+ * //   '1hp': 'calc(1px * var(--scale-h))'
+ * // }
+ */
+export function generateViewportBasedSpacing(values) {
+  if (!Array.isArray(values)) {
+    throw new Error('values must be an array');
+  }
+
+  return values.reduce((units, value) => {
+    if (typeof value !== 'number' || isNaN(value)) {
+      throw new Error(`Invalid spacing value: ${value}. Must be a number.`);
+    }
+
+    // Width points
+    units[`${value}wp`] = `calc(${value}px * var(--scale-w))`;
+    // Height points
+    units[`${value}hp`] = `calc(${value}px * var(--scale-h))`;
+    // UI points (standard)
+    units[`${value}up`] = `calc(${value}px * var(--scale-ui))`;
+    // UI points (deprecated)
+    units[`${value}p`] = `calc(${value}px * var(--scale-ui))`;
+    return units;
+  }, {});
+}
+
+/**
+ * @typedef {{
+ *   size?: number,
+ *   lineHeight?: number|string
+ *  }} TextStyleSizes
+ */
+
+/**
+ * Generates semantic text style definitions for a specific text category
+ * (base, UI, or heading). Each style includes a scaled font size and
+ * line height.
+ *
+ * @param {{[key: string]: TextStyleSizes}} sizes
+ *   Set of text sizes to generate styles for
+ *
+ * @param {'base' | 'ui' | 'heading'} category
+ *   Text category to generate styles for
+ *
+ * @returns {{[key: string]: [string, {lineHeight: number}]}}
+ *   Generated text styles in Tailwind format
+ *
+ * @throws {Error} If a size has an invalid size or lineHeight
+ *
+ * @example
+ * const TEXT_BASE_SIZES = {
+ *   sm: { size: 16, lineHeight: 1.5 },
+ *   md: { size: 20, lineHeight: 1.5 },
+ *   lg: { size: 24, lineHeight: 1.4 }
+ * };
+ *
+ * generateTextStyles(TEXT_BASE_SIZES, 'base');
+ * // Returns:
+ * // {
+ * //   'base-sm':
+ * //     ['calc(16px * var(--scale-text-base))', { lineHeight: 1.5 }],
+ * //   'base-md':
+ * //     ['calc(20px * var(--scale-text-base))', { lineHeight: 1.5 }],
+ * //   'base-lg':
+ * //     ['calc(24px * var(--scale-text-base))', { lineHeight: 1.4 }]
+ * // }
+ */
+export function generateTextStyles(sizes, category) {
+  if (!sizes || typeof sizes !== 'object') {
+    throw new Error('configs must be an object');
+  }
+
+  if (!['base', 'ui', 'heading'].includes(category)) {
+    throw new Error('category must be one of: base, ui, heading');
+  }
+
+  return Object.entries(sizes).reduce((result, [variant, config]) => {
+    // Validate config
+    if (!config || typeof config !== 'object') {
+      throw new Error(
+        `Invalid size config for "${variant}": must be an object`
+      );
+    }
+
+    if (typeof config.size !== 'number') {
+      throw new Error(
+        `Invalid size for "${category}-${variant}": must be a number`
+      );
+    }
+
+    const extraProps = { ...config };
+    delete extraProps.size;
+
+    result[`${category}-${variant}`] = [
+      `calc(${config.size}px * var(--scale-text-${category}))`,
+      extraProps
+    ];
+
+    return result;
+  }, {});
+}
+
+/**
+ * Generates border radius styles with UI scaling
+ *
+ * @param {{[key: string]: string | {size: number}}} sizes
+ *   Set of radius sizes to generate, either as:
+ *   - Object with size property (e.g., { size: 10 })
+ *   - Direct string value (e.g., '0px', '9999px')
+ *
+ * @returns {Object.<string, string>}
+ *   Generated border radius styles in Tailwind format
+ *
+ * @throws {Error} If a value has an invalid type
+ *
+ * @example
+ * const RADIUS_SIZES = {
+ *   none: '0px',
+ *   sm: { size: 10 },
+ *   md: { size: 15 },
+ *   full: '9999px'
+ * };
+ *
+ * generateBorderRadiusStyles(RADIUS_SIZES)
+ * // Returns:
+ * // {
+ * //   'none': '0px',
+ * //   'sm': 'calc(10px * var(--scale-ui))',
+ * //   'md': 'calc(15px * var(--scale-ui))',
+ * //   'full': '9999px'
+ * // }
+ */
+export function generateBorderRadiusStyles(sizes) {
+  if (!sizes || typeof sizes !== 'object') {
+    throw new Error('sizes must be an object');
+  }
+
+  return Object.entries(sizes).reduce((result, [variant, value]) => {
+    if (typeof value === 'object' && value !== null) {
+      // Handle {size: 10} format
+      if (typeof value.size !== 'number') {
+        throw new Error(
+          `Invalid radius size for "${variant}": size must be a number`
+        );
+      }
+      result[variant] = `calc(${value.size}px * var(--scale-ui))`;
+    } else if (typeof value === 'string') {
+      // Handle direct strings (like '0px' or '9999px')
+      result[variant] = value;
+    } else {
+      throw new Error(
+        `Invalid radius value for "${variant}": ` +
+          `must be an object with size property or a string`
+      );
+    }
+    return result;
+  }, {});
+}
+
+/**
+ * Generates width styles for various CSS properties with UI scaling and explicit naming
+ *
+ * @param {{[key: string]: {size: number}}} sizes
+ *   Set of width sizes to generate
+ *
+ * @param {string} [prefix='width']
+ *   Prefix to add before each variant name (default: 'width')
+ *
+ * @param {string} scaleVar
+ *   CSS variable to use for scaling (default: '--scale-ui')
+ *
+ * @returns {{[key: string]: string}}
+ *   Generated width styles in Tailwind format
+ *
+ * @throws {Error} If a size has an invalid type
+ *
+ * @example
+ * const WIDTH_SIZES = {
+ *   thin: { size: 1 },
+ *   normal: { size: 2 },
+ *   thick: { size: 4 }
+ * };
+ *
+ * generateWidthStyles(WIDTH_SIZES, 'width')
+ * // Returns:
+ * // {
+ * //   'width-thin': 'calc(1px * var(--scale-ui))',
+ * //   'width-normal': 'calc(2px * var(--scale-ui))',
+ * //   'width-thick': 'calc(4px * var(--scale-ui))'
+ * // }
+ */
+export function generateWidthStyles(
+  sizes,
+  prefix = 'width',
+  scaleVar = '--scale-ui'
+) {
+  if (!sizes || typeof sizes !== 'object') {
+    throw new Error('sizes must be an object');
+  }
+
+  return Object.entries(sizes).reduce((result, [variant, value]) => {
+    if (typeof value === 'object' && value !== null) {
+      if (typeof value.size !== 'number') {
+        throw new Error(
+          `Invalid width size for "${variant}": size must be a number`
+        );
+      }
+
+      result[`${prefix}${prefix.length ? '-' : ''}${variant}`] =
+        `calc(${value.size}px * var(${scaleVar}))`;
+    } else {
+      throw new Error(
+        `Invalid width value for "${variant}": ` +
+          `must be an object with size property`
+      );
+    }
+    return result;
+  }, {});
+}

package/dist/util/env/index.d.ts

@@ -0,0 +1 @@
+export const isTestEnv: boolean;

package/dist/util/env/index.js

@@ -0,0 +1,9 @@
+
+export const isTestEnv = (
+  // For Vite environments
+  (typeof import.meta !== 'undefined' && import.meta.env?.MODE === 'test') ||
+  // For Node environments, safely check process
+  (typeof process !== 'undefined' && process?.env?.NODE_ENV === 'test') ||
+  // For Vitest specific check
+  (typeof process !== 'undefined' && process?.env?.VITEST !== undefined)
+);

package/dist/util/exceptions/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Creates a new Error from the error message and throws it with a reference
+ * to the originating Error
+ * - The originating Error is set as `cause` property
+ *
+ * @param {string} message - Additional message to prepend
+ * @param {Error|string} error - Original error
+ * @param {string|Object.<string, any>} details
+ *
+ * @throws {DetailedError}
+ * @returns {never} This function never returns
+ */
+export function rethrow(message: string, error: Error | string, details: string | {
+    [x: string]: any;
+}): never;