@hkdigital/lib-core 0.3.14 → 0.3.15

package/README.md

@@ -88,10 +88,19 @@ For detailed configuration options, see the [config documentation](./src/lib/con
 
 ### Import JS, Svelte files and Typedefs
 
-Most subfolders have an index.js that export all functionality and typedefs.
+Main folders in lib have an index.js, but may also have a more specific export file e.g. http.js or cache.js (@see $lib/network).
 
-```svelte
-import { CHAR } from '@hkdigital/lib-core/constants/regexp/index.js';
+Main folders (should) have a typedef.js that can be used in JSdoc comments.
+
+```js
+// Import Latin char constant for use in regular expressions
+import { LCHAR } from '@hkdigital/lib-core/constants/regexp/index.js';
+```
+
+```js
+/**
+ * @param {import('@hkdigital/lib-core/network/typedef.js').JsonGetOptions} JsonGetOptions
+ */
 ```
 
 ### Import CSS

package/dist/config/README.md

@@ -12,7 +12,7 @@ The `vite.js` provides generators for common Vite setups used across HKdigital p
 // vite.config.js
 import { defineConfig } from 'vitest/config';
 import { sveltekit } from '@sveltejs/kit/vite';
-import { generateViteConfig } from '@hkdigital/lib-sveltekit/config/vite.js';
+import { generateViteConfig } from '@hkdigital/lib-core/config/vite.js';
 
 export default defineConfig(
   await generateViteConfig({
@@ -106,7 +106,7 @@ pnpm add -D vite-imagetools
 For TypeScript and JavaScript projects using VS Code or other TypeScript-aware editors, add to your `app.d.ts`:
 
 ```typescript
-import '@hkdigital/lib-sveltekit/config/imagetools.d.ts';
+import '@hkdigital/lib-core/config/imagetools.d.ts';
 ```
 
 **Why this is needed:**
@@ -157,7 +157,7 @@ import { resolve } from 'path';
 import {
   generateDefaultDirectives,
   generateResponseConfigs
-} from '@hkdigital/lib-sveltekit/config/imagetools-config.js';
+} from '@hkdigital/lib-core/config/imagetools-config.js';
 
 const packageJson = JSON.parse(
   readFileSync(resolve('./package.json'), 'utf-8')
@@ -189,7 +189,7 @@ export default defineConfig({
 // vite.config.js
 import { defineConfig } from 'vitest/config';
 import { sveltekit } from '@sveltejs/kit/vite';
-import { generateViteConfig } from '@hkdigital/lib-sveltekit/config/vite.js';
+import { generateViteConfig } from '@hkdigital/lib-core/config/vite.js';
 
 export default defineConfig(
   await generateViteConfig()

package/dist/design/README.md

@@ -9,19 +9,17 @@ A comprehensive, responsive design system built for SvelteKit applications. This
 ```javascript
 // tailwind.config.js
 import { 
-  spacing, 
-  fontSize, 
-  borderRadius, 
+  generateTailwindThemeExtensions,
+  designTokens,
   customUtilitiesPlugin 
 } from '@hkdigital/lib-core/design/index.js';
 
+const themeExtensions = generateTailwindThemeExtensions(designTokens);
+
+/** @type {import('tailwindcss').Config} \*/
 export default {
   theme: {
-    extend: {
-      spacing,
-      fontSize,
-      borderRadius
-    }
+    extend: themeExtensions
   },
   plugins: [
     customUtilitiesPlugin
@@ -29,14 +27,14 @@ export default {
 };
 ```
 
-```svelte
+```html
 <!-- +layout.svelte -->
 <script>
-  import { DESIGN, CLAMPING, rootDesignVarsHTML } from '@hkdigital/lib-core/design';
+  import { designTokens, designTokensToRootCssVars } from '@hkdigital/lib-core/design/index.js';
 </script>
 
 <svelte:head>
-  {@html rootDesignVarsHTML(DESIGN, CLAMPING)}
+  {@html designTokensToRootCssVars(designTokens)}
 </svelte:head>
 
 {@render children()}
@@ -185,7 +183,7 @@ import {
   getRootCssDesignWidth,
   getRootCssDesignHeight,
   getAllRootScalingVars
-} from '@hkdigital/lib-core/design';
+} from '@hkdigital/lib-core/design/index.js';
 
 // Get current design dimensions
 const designWidth = getRootCssDesignWidth();   // 1024
@@ -199,7 +197,7 @@ const scales = getAllRootScalingVars();
 ### Clamp Utilities
 
 ```javascript
-import { clamp, getClampParams } from '@hkdigital/lib-core/design';
+import { clamp, getClampParams } from '@hkdigital/lib-core/design/index.js';
 
 // Mathematical clamp function
 const value = clamp(0.5, 0.3, 2.0); // Returns 0.5 (clamped between 0.5 and 2.0)
@@ -212,7 +210,7 @@ const params = getClampParams('scale-ui');
 ### Component State Classes
 
 ```javascript
-import { toStateClasses } from '@hkdigital/lib-core/design';
+import { toStateClasses } from '@hkdigital/lib-core/design/index.js';
 
 // Generate state classes from object
 const classes = toStateClasses({
@@ -236,10 +234,10 @@ const classes = toStateClasses({
 #### Viewport-Based Scaling
 
 ```javascript
-import { enableScalingUI } from '@hkdigital/lib-core/design';
+import { enableScalingUI, designTokens } from '@hkdigital/lib-core/design/index.js';
 
 // Enable automatic viewport scaling
-const cleanup = enableScalingUI(DESIGN, CLAMPING);
+const cleanup = enableScalingUI(designTokens.DESIGN, designTokens.CLAMPING);
 
 // Call cleanup when component is destroyed
 onDestroy(cleanup);
@@ -248,23 +246,23 @@ onDestroy(cleanup);
 #### Container-Based Scaling
 
 ```javascript
-import { enableContainerScaling } from '@hkdigital/lib-core/design';
+import { enableContainerScaling, designTokens } from '@hkdigital/lib-core/design/index.js';
 
 let containerElement;
 
 // Enable scaling for specific container
 const cleanup = enableContainerScaling({
   container: containerElement,
-  design: DESIGN,
-  clamping: CLAMPING,
+  design: designTokens.DESIGN,
+  clamping: designTokens.CLAMPING,
   useResizeObserver: true
 });
 
 // Optional custom dimension getter
 const cleanupCustom = enableContainerScaling({
   container: containerElement,
-  design: DESIGN,
-  clamping: CLAMPING,
+  design: designTokens.DESIGN,
+  clamping: designTokens.CLAMPING,
   getDimensions: () => ({ width: 800, height: 600 })
 });
 ```
@@ -273,7 +271,7 @@ const cleanupCustom = enableContainerScaling({
 <!-- Svelte component example -->
 <script>
   import { onMount, onDestroy } from 'svelte';
-  import { enableContainerScaling, DESIGN, CLAMPING } from '@hkdigital/lib-core/design';
+  import { enableContainerScaling, designTokens } from '@hkdigital/lib-core/design/index.js';
   
   let containerElement;
   let cleanup;
@@ -281,8 +279,8 @@ const cleanupCustom = enableContainerScaling({
   onMount(() => {
     cleanup = enableContainerScaling({
       container: containerElement,
-      design: DESIGN,
-      clamping: CLAMPING
+      design: designTokens.DESIGN,
+      clamping: designTokens.CLAMPING
     });
   });
   
@@ -302,59 +300,107 @@ const cleanupCustom = enableContainerScaling({
 ### Custom Design Configuration
 
 ```javascript
-// your-project/src/lib/design/design-config.js
-import { 
-  generateTextBasedSpacing,
-  generateTextStyles 
-} from '@hkdigital/lib-core/design';
-
-// Custom design dimensions
-export const CUSTOM_DESIGN = {
-  width: 1440,
-  height: 900
-};
+// your-project/src/lib/design/design-tokens.js
+export const designTokens = {
+  DESIGN: {
+    width: 1440,
+    height: 900
+  },
+
+  CLAMPING: {
+    ui: { min: 0.4, max: 1.8 },
+    textBase: { min: 0.8, max: 1.4 },
+    textHeading: { min: 0.8, max: 2.0 },
+    textUi: { min: 0.6, max: 1.2 }
+  },
+
+  TEXT_POINT_SIZES: [4, 8, 12, 16, 20, 24, 32],
+  VIEWPORT_POINT_SIZES: [10, 20, 30, 40, 50, 100, 200],
+
+  TEXT_BASE_SIZES: {
+    sm: { size: 12, lineHeight: 1.4 },
+    md: { size: 16, lineHeight: 1.4 },
+    lg: { size: 20, lineHeight: 1.4 }
+  },
 
-// Custom text sizes
-export const CUSTOM_TEXT_SIZES = {
-  sm: { size: 12, lineHeight: 1.4 },
-  md: { size: 16, lineHeight: 1.4 },
-  lg: { size: 20, lineHeight: 1.4 }
+  TEXT_HEADING_SIZES: {
+    h1: { size: 36, lineHeight: 1.2 },
+    h2: { size: 30, lineHeight: 1.2 },
+    h3: { size: 26, lineHeight: 1.2 }
+  },
+
+  TEXT_UI_SIZES: {
+    sm: { size: 12, lineHeight: 1.2 },
+    md: { size: 14, lineHeight: 1.2 },
+    lg: { size: 16, lineHeight: 1.2 }
+  },
+
+  RADIUS_SIZES: {
+    none: '0px',
+    sm: { size: 8 },
+    md: { size: 16 },
+    lg: { size: 24 },
+    full: '9999px'
+  },
+
+  BORDER_WIDTH_SIZES: {
+    thin: { size: 1 },
+    normal: { size: 2 },
+    thick: { size: 3 }
+  },
+
+  STROKE_WIDTH_SIZES: {
+    thin: { size: 1 },
+    normal: { size: 2 },
+    thick: { size: 3 }
+  }
 };
 
-// Generate custom extensions
-export const customSpacing = generateTextBasedSpacing([8, 12, 16, 24, 32]);
-export const customFontSize = generateTextStyles(CUSTOM_TEXT_SIZES, 'base');
+// your-project/tailwind.config.js
+import { generateTailwindThemeExtensions, customUtilitiesPlugin } from '@hkdigital/lib-core/design/index.js';
+import { designTokens } from './src/lib/design/design-tokens.js';
+
+const themeExtensions = generateTailwindThemeExtensions(designTokens);
+
+export default {
+  theme: {
+    extend: themeExtensions
+  },
+  plugins: [customUtilitiesPlugin]
+};
 ```
 
 ### Available Generator Functions
 
+Individual generator functions are available for advanced customization:
+
 ```javascript
 import {
-  generateTextBasedSpacing,      // ut/bt/ht spacing units
-  generateViewportBasedSpacing,  // up/wp/hp spacing units
-  generateTextStyles,            // Complete typography styles
-  generateBorderRadiusStyles,    // Border radius with scaling
-  generateWidthStyles            // Border/stroke width with scaling
-} from '@hkdigital/lib-core/design';
+  generateTailwindThemeExtensions, // Complete theme extension generator
+  generateTextBasedSpacing,        // ut/bt/ht spacing units
+  generateViewportBasedSpacing,    // up/wp/hp spacing units
+  generateTextStyles,              // Complete typography styles
+  generateBorderRadiusStyles,      // Border radius with scaling
+  generateWidthStyles              // Border/stroke width with scaling
+} from '@hkdigital/lib-core/design/index.js';
+
+// Example: Generate only spacing for a custom configuration
+const customSpacing = generateTextBasedSpacing([4, 8, 12, 16, 24]);
 ```
 
-### Configuration Objects
+### Default Design Tokens
 
-All configuration objects are exported for customization:
+The default design tokens are available for reference or as a starting point:
 
 ```javascript
-import {
-  DESIGN,                 // { width: 1024, height: 768 }
-  CLAMPING,              // Min/max scale bounds
-  TEXT_POINT_SIZES,      // [1, 2, 4, 6, 8, 10, ...]
-  VIEWPORT_POINT_SIZES,  // [1, 2, 4, 5, 6, 10, ...]
-  TEXT_BASE_SIZES,       // { sm: {...}, md: {...}, lg: {...} }
-  TEXT_HEADING_SIZES,    // { h1: {...}, h2: {...}, ... }
-  TEXT_UI_SIZES,         // { sm: {...}, md: {...}, lg: {...} }
-  RADIUS_SIZES,          // Border radius configurations
-  BORDER_WIDTH_SIZES,    // Border width configurations
-  STROKE_WIDTH_SIZES     // Stroke width configurations
-} from '@hkdigital/lib-core/design';
+import { designTokens } from '@hkdigital/lib-core/design/index.js';
+
+console.log(designTokens.DESIGN);                // { width: 1024, height: 768 }
+console.log(designTokens.CLAMPING);              // Min/max scale bounds
+console.log(designTokens.TEXT_POINT_SIZES);      // [1, 2, 4, 6, 8, 10, ...]
+console.log(designTokens.VIEWPORT_POINT_SIZES);  // [1, 2, 4, 5, 6, 10, ...]
+console.log(designTokens.TEXT_BASE_SIZES);       // { sm: {...}, md: {...}, lg: {...} }
+// ... and all other token configurations
 ```
 
 ## Best practices
@@ -393,11 +439,35 @@ If migrating from the old structure:
 
 ```javascript
 // OLD
-import { DESIGN } from '$lib/design/design-config.js';
-import { customUtilitiesPlugin } from '$lib/design/skeleton.js';
+import {
+  spacing,
+  fontSize,
+  borderRadius,
+  customUtilitiesPlugin
+} from '@hkdigital/lib-core/design/index.js';
+
+export default {
+  theme: {
+    extend: { spacing, fontSize, borderRadius }
+  },
+  plugins: [customUtilitiesPlugin]
+};
 
 // NEW
-import { DESIGN, customUtilitiesPlugin } from '@hkdigital/lib-core/design';
+import {
+  generateTailwindThemeExtensions,
+  designTokens,
+  customUtilitiesPlugin
+} from '@hkdigital/lib-core/design/index.js';
+
+const themeExtensions = generateTailwindThemeExtensions(designTokens);
+
+export default {
+  theme: {
+    extend: themeExtensions
+  },
+  plugins: [customUtilitiesPlugin]
+};
 ```
 
 ---

package/dist/design/config/{design-config.d.ts → design-tokens.d.ts}

@@ -1,8 +1,20 @@
-export namespace DESIGN {
+export namespace designTokens {
+    export { DESIGN };
+    export { CLAMPING };
+    export { TEXT_POINT_SIZES };
+    export { VIEWPORT_POINT_SIZES };
+    export { TEXT_BASE_SIZES };
+    export { TEXT_HEADING_SIZES };
+    export { TEXT_UI_SIZES };
+    export { RADIUS_SIZES };
+    export { BORDER_WIDTH_SIZES };
+    export { STROKE_WIDTH_SIZES };
+}
+declare namespace DESIGN {
     let width: number;
     let height: number;
 }
-export namespace CLAMPING {
+declare namespace CLAMPING {
     namespace ui {
         let min: number;
         let max: number;
@@ -26,9 +38,9 @@ export namespace CLAMPING {
         export { max_3 as max };
     }
 }
-export const TEXT_POINT_SIZES: number[];
-export const VIEWPORT_POINT_SIZES: number[];
-export namespace TEXT_BASE_SIZES {
+declare const TEXT_POINT_SIZES: number[];
+declare const VIEWPORT_POINT_SIZES: number[];
+declare namespace TEXT_BASE_SIZES {
     namespace sm {
         let size: number;
         let lineHeight: number;
@@ -46,7 +58,7 @@ export namespace TEXT_BASE_SIZES {
         export { lineHeight_2 as lineHeight };
     }
 }
-export namespace TEXT_HEADING_SIZES {
+declare namespace TEXT_HEADING_SIZES {
     namespace h1 {
         let size_3: number;
         export { size_3 as size };
@@ -78,7 +90,7 @@ export namespace TEXT_HEADING_SIZES {
         export { lineHeight_7 as lineHeight };
     }
 }
-export namespace TEXT_UI_SIZES {
+declare namespace TEXT_UI_SIZES {
     export namespace sm_1 {
         let size_8: number;
         export { size_8 as size };
@@ -101,7 +113,7 @@ export namespace TEXT_UI_SIZES {
     }
     export { lg_1 as lg };
 }
-export namespace RADIUS_SIZES {
+declare namespace RADIUS_SIZES {
     export let none: string;
     export namespace xs {
         let size_11: number;
@@ -124,7 +136,7 @@ export namespace RADIUS_SIZES {
     export { lg_2 as lg };
     export let full: string;
 }
-export namespace BORDER_WIDTH_SIZES {
+declare namespace BORDER_WIDTH_SIZES {
     namespace thin {
         let size_15: number;
         export { size_15 as size };
@@ -138,7 +150,7 @@ export namespace BORDER_WIDTH_SIZES {
         export { size_17 as size };
     }
 }
-export namespace STROKE_WIDTH_SIZES {
+declare namespace STROKE_WIDTH_SIZES {
     export namespace thin_1 {
         let size_18: number;
         export { size_18 as size };
@@ -155,3 +167,4 @@ export namespace STROKE_WIDTH_SIZES {
     }
     export { thick_1 as thick };
 }
+export {};

package/dist/design/config/design-tokens.js

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview HKdigital Design Tokens
+ * 
+ * Default design system tokens for the HKdigital design system.
+ * These tokens define all the design values used to generate Tailwind theme extensions.
+ * 
+ * Users can create their own design-tokens.js file with custom values
+ * and pass it to generateTailwindThemeExtensions().
+ */
+
+/* == Design dimensions == */
+
+const DESIGN = {
+  width: 1024,
+  height: 768
+};
+
+/* == Scaling-clamping behaviour == */
+
+const CLAMPING = {
+  ui: { min: 0.3, max: 2 },
+  textBase: { min: 0.75, max: 1.5 },
+  textHeading: { min: 0.75, max: 2.25 },
+  textUi: { min: 0.5, max: 1.25 }
+};
+
+/* == Text == */
+
+const TEXT_POINT_SIZES = [
+  1, 2, 4, 6, 8, 10, 11, 12, 16, 20, 24, 28, 32, 36, 50
+];
+
+const VIEWPORT_POINT_SIZES = [
+  1, 2, 4, 5, 6, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 120, 140, 160, 180,
+  200
+];
+
+const TEXT_BASE_SIZES = {
+  sm: { size: 14, lineHeight: 1.25 },
+  md: { size: 16, lineHeight: 1.25 },
+  lg: { size: 18, lineHeight: 1.25 }
+};
+
+const TEXT_HEADING_SIZES = {
+  h1: { size: 32, lineHeight: 1.25 },
+  h2: { size: 28, lineHeight: 1.25 },
+  h3: { size: 24, lineHeight: 1.25 },
+  h4: { size: 20, lineHeight: 1.25 },
+  h5: { size: 16, lineHeight: 1.25 }
+};
+
+const TEXT_UI_SIZES = {
+  sm: { size: 14, lineHeight: 1 },
+  md: { size: 16, lineHeight: 1 },
+  lg: { size: 18, lineHeight: 1 }
+};
+
+/* == Border radius == */
+
+const RADIUS_SIZES = {
+  none: '0px',
+  xs: { size: 5 },
+  sm: { size: 10 },
+  md: { size: 25 },
+  lg: { size: 35 },
+  full: '9999px'
+};
+
+/* == Border width == */
+
+const BORDER_WIDTH_SIZES = {
+  thin: { size: 1 },
+  normal: { size: 2 },
+  thick: { size: 4 }
+};
+
+/* == Stroke width == */
+
+const STROKE_WIDTH_SIZES = {
+  thin: { size: 1 },
+  normal: { size: 2 },
+  thick: { size: 4 }
+};
+
+/**
+ * Complete design tokens configuration
+ * 
+ * @example Usage with generateTailwindThemeExtensions
+ * ```javascript
+ * import { generateTailwindThemeExtensions } from '@hkdigital/lib-core/design/index.js';
+ * import { designTokens } from '@hkdigital/lib-core/design/config/design-tokens.js';
+ * 
+ * const themeExtensions = generateTailwindThemeExtensions(designTokens);
+ * ```
+ */
+export const designTokens = {
+  DESIGN,
+  CLAMPING,
+  TEXT_POINT_SIZES,
+  VIEWPORT_POINT_SIZES,
+  TEXT_BASE_SIZES,
+  TEXT_HEADING_SIZES,
+  TEXT_UI_SIZES,
+  RADIUS_SIZES,
+  BORDER_WIDTH_SIZES,
+  STROKE_WIDTH_SIZES
+};

package/dist/design/generators/index.d.ts

@@ -1,3 +1,54 @@
+/**
+ * Generate complete Tailwind CSS theme extensions from design configuration
+ *
+ * Takes design configuration objects and generates complete Tailwind theme extensions.
+ * Users can define their own design-config.js with custom values and pass them here.
+ *
+ * @param {Object} designConfig - Design configuration object
+ * @param {Object} designConfig.TEXT_POINT_SIZES - Array of text point sizes for spacing
+ * @param {Object} designConfig.VIEWPORT_POINT_SIZES - Array of viewport point sizes
+ * @param {Object} designConfig.TEXT_BASE_SIZES - Base text size configurations
+ * @param {Object} designConfig.TEXT_HEADING_SIZES - Heading text size configurations
+ * @param {Object} designConfig.TEXT_UI_SIZES - UI text size configurations
+ * @param {Object} designConfig.RADIUS_SIZES - Border radius configurations
+ * @param {Object} designConfig.BORDER_WIDTH_SIZES - Border width configurations
+ * @param {Object} designConfig.STROKE_WIDTH_SIZES - Stroke width configurations
+ *
+ * @returns {Object} Complete Tailwind theme extension object
+ *
+ * @example Basic usage
+ * ```javascript
+ * // your-project/src/lib/design/design-config.js
+ * export const DESIGN = { width: 1440, height: 900 };
+ * export const TEXT_BASE_SIZES = {
+ *   sm: { size: 12, lineHeight: 1.3 },
+ *   md: { size: 16, lineHeight: 1.4 }
+ * };
+ * // ... other exports
+ *
+ * // your-project/tailwind.config.js
+ * import { generateTailwindThemeExtensions } from '@hkdigital/lib-core/design/index.js';
+ * import { customUtilitiesPlugin } from '@hkdigital/lib-core/design/index.js';
+ * import * as designConfig from './src/lib/design/design-config.js';
+ *
+ * export default {
+ *   theme: {
+ *     extend: generateTailwindThemeExtensions(designConfig)
+ *   },
+ *   plugins: [customUtilitiesPlugin]
+ * };
+ * ```
+ */
+export function generateTailwindThemeExtensions({ TEXT_POINT_SIZES, VIEWPORT_POINT_SIZES, TEXT_BASE_SIZES, TEXT_HEADING_SIZES, TEXT_UI_SIZES, RADIUS_SIZES, BORDER_WIDTH_SIZES, STROKE_WIDTH_SIZES }: {
+    TEXT_POINT_SIZES: any;
+    VIEWPORT_POINT_SIZES: any;
+    TEXT_BASE_SIZES: any;
+    TEXT_HEADING_SIZES: any;
+    TEXT_UI_SIZES: any;
+    RADIUS_SIZES: any;
+    BORDER_WIDTH_SIZES: any;
+    STROKE_WIDTH_SIZES: any;
+}): any;
 /**
  * Generates text-based spacing units with with different scaling
  * units (ut, bt, ht)