@hkdigital/lib-core 0.3.14 → 0.4.3

package/README.md

@@ -3,7 +3,7 @@
 Core library that we use to power up our SvelteKit projects
 
 This is a library for [SvelteKit](https://svelte.dev/) projects.
-It contains common code and components that we use to create our projects.
+It contains common code, base components and documentation that help you with setting up a new project.
 
 ## Using the library
 
@@ -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
@@ -122,18 +131,18 @@ export default {
 To build your library:
 
 ```bash
-npm run package
+pnpm run package
 ```
 
-## Building the showcase app
+## Running the showcase app
 
-To create a production version of your showcase app:
+To use the showcase app that illustrates the code in this lib
 
 ```bash
-npm run build
+pnpm run dev
 ```
 
-You can preview the production build with `npm run preview`.
+You can preview the production build with `pnpm run preview`.
 
 > To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
 

package/dist/auth/errors.d.ts

@@ -0,0 +1 @@
+export * from "./errors/jwt.js";

package/dist/auth/errors.js

@@ -0,0 +1 @@
+export * from './errors/jwt.js';

package/dist/{states → browser/navigation}/navigation.svelte.js

@@ -1,6 +1,6 @@
 import { onMount } from 'svelte';
 
-import { lazySingleton } from '../util/singleton/index.js';
+import { lazySingleton } from '../../util/singleton/index.js';
 
 import { beforeNavigate, onNavigate, afterNavigate } from '$app/navigation';
 

package/dist/browser/navigation.d.ts

@@ -0,0 +1 @@
+export { nav } from "./navigation/navigation.svelte.js";

package/dist/browser/navigation.js

@@ -0,0 +1 @@
+export { nav } from './navigation/navigation.svelte.js';

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({
@@ -50,7 +50,7 @@ export default defineConfig(
       'import.meta.env.VITE_API_URL': JSON.stringify('https://api.example.com')
     },
     imagetoolsOptions: {
-      widths: [640, 1024, 1536, 1920]
+      widths: [1920, 1536, 1024, 640]
     }
   })
 );
@@ -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/config/generators/imagetools.d.ts

@@ -4,6 +4,7 @@
  *
  * @param {object} [options]
  * @param {number[]} [options.widths=DEFAULT_WIDTHS]
+ * @param {number[]} [options.thumbnailWidth=DEFAULT_THUMBNAIL_WIDTH]
  *
  * @returns {(
  *   entries: [string, string[]][]
@@ -11,6 +12,7 @@
  */
 export function generateResponseConfigs(options?: {
     widths?: number[];
+    thumbnailWidth?: number[];
 }): (entries: [string, string[]][]) => (Record<string, string | string[]>[]);
 /**
  * Configures and returns a function that can be used as

package/dist/config/generators/imagetools.js

@@ -1,9 +1,12 @@
-const DEFAULT_WIDTHS = [640, 1024, 1536, 1920];
+const DEFAULT_WIDTHS = [1920, 1536, 1024, 640];
+
+const DEFAULT_THUMBNAIL_WIDTH = 150;
 
 const DEFAULT_PRESETS = {
 	default: {
 		format: 'avif',
-		quality: '90'
+		quality: '90',
+		as: 'metadata'
 	},
 	render: {
 		format: 'jpg',
@@ -44,6 +47,7 @@ const DEFAULT_PRESETS = {
  *
  * @param {object} [options]
  * @param {number[]} [options.widths=DEFAULT_WIDTHS]
+ * @param {number[]} [options.thumbnailWidth=DEFAULT_THUMBNAIL_WIDTH]
  *
  * @returns {(
  *   entries: [string, string[]][]
@@ -70,21 +74,30 @@ export function generateResponseConfigs(options) {
 
 		// @ts-ignore
 		const responsiveConfig = entries.find(([key]) => key === 'responsive');
+		// console.log('responsiveConfig found:', !!responsiveConfig);
 
-		if (!responsiveConfig) {
-			// Directive 'responsive' was not set => return original config
+		const widths = options?.widths ?? DEFAULT_WIDTHS;
 
-			return [configPairs];
+		// Always include the main image(s) and a thumbnail version
+		const thumbnailConfig = {
+			...configPairs,
+			w: String(options?.thumbnailWidth ?? DEFAULT_THUMBNAIL_WIDTH)
+		};
 
-			// Alternative: by returning undefined, the default resolveConfig is used
-			// return undefined;
+		if (!responsiveConfig) {
+			// Directive 'responsive' was not set => return original + thumbnail
+			const originalConfig = configPairs; // No 'w' means original dimensions
+			// console.log('Returning original + thumbnail configs:', [originalConfig, thumbnailConfig]);
+			return [originalConfig, thumbnailConfig];
 		}
 
-		const widths = options?.widths ?? DEFAULT_WIDTHS;
-
-		return widths.map((w) => {
+		// Directive 'responsive' was set => return responsive widths + thumbnail
+		const responsiveConfigs = widths.map((w) => {
 			return { ...configPairs, w: String(w) };
 		});
+		const result = [...responsiveConfigs, thumbnailConfig];
+		// console.log('Returning responsive + thumbnail configs:', result);
+		return result;
 	};
 }
 

package/dist/config/generators/vite.js

@@ -83,7 +83,7 @@ export async function generateViteConfig(options = {}) {
         new Date().toISOString()
       ),
       ...customDefines
-    }
+    },
   };
 
   if (enableVitest) {

package/dist/config/imagetools.d.ts

@@ -1,13 +1,13 @@
-type ImageMeta = import('../network/typedef.js').ImageMeta;
-type ImageSource = import('../network/typedef.js').ImageSource;
+type ImageMeta = import('./typedef.js').ImageMeta;
+type ImageSource = import('./typedef.js').ImageSource;
 
 declare module '*?responsive' {
-  const out: ImageMeta[];
+  const out: ImageSource;
   export default out;
 }
 
 declare module '*&responsive' {
-  const out: ImageMeta[];
+  const out: ImageSource;
   export default out;
 }
 
@@ -57,7 +57,7 @@ declare module '*?preset=savedata' {
 }
 
 declare module '*&preset=savedata' {
-  const out: IImageSource;
+  const out: ImageSource;
   export default out;
 }
 

package/dist/config/typedef.d.ts

@@ -0,0 +1,11 @@
+declare const _default: {};
+export default _default;
+export type ImageMeta = {
+    src: string;
+    width: number;
+    height: number;
+};
+/**
+ * Array of ImageMeta objects (always array format)
+ */
+export type ImageSource = ImageMeta[];

package/dist/config/typedef.js

@@ -0,0 +1,17 @@
+/**
+ * Configuration type definitions for imagetools and build-time image processing
+ */
+
+/**
+ * @typedef {object} ImageMeta
+ * @property {string} src
+ * @property {number} width
+ * @property {number} height
+ */
+
+/**
+ * @typedef {ImageMeta[]} ImageSource
+ * Array of ImageMeta objects (always array format)
+ */
+
+export default {};

package/dist/design/README.md

@@ -9,39 +9,109 @@ 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 {
+  // Include @hkdigital libraries in content so Tailwind processes
+  // their design system classes and components for proper styling
+  content: [
+    './node_modules/@hkdigital/**/*.{html,js,svelte}',
+    './src/**/*.{html,js,svelte}'
+  ],
   theme: {
-    extend: {
-      spacing,
-      fontSize,
-      borderRadius
-    }
+    // Extend Tailwind's default theme using the design system tokens
+    extend: themeExtensions
   },
   plugins: [
+    // Generate custom utility classes like 'type-heading-h2'
     customUtilitiesPlugin
   ]
 };
 ```
 
-```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()}
 ```
 
+## Using Design System Classes in External CSS
+
+When using design system utilities like `p-16up`, `bg-surface-300`, or `border-primary-500` in external CSS files (loaded via `<style src="./style.css"></style>`), you **must** include the `@reference` directive at the top of your CSS file.
+
+**SVELTE preprocess**
+You need svelte preprocess to process external CSS files in your svelte files!
+
+```html
+<div data-page>
+  <p>Hello there!</p>
+</div>
+
+<style src="./style.css"></style>
+```
+
+### ✅ Correct Usage
+
+```css
+/* style.css */
+@reference '../../app.css';
+
+[data-page] {
+  & .my-component {
+    @apply p-16up bg-surface-300 border border-primary-500;
+  }
+}
+```
+
+### ❌ Common Mistake
+
+```css
+/* style.css - MISSING @reference directive */
+[data-page] {
+  & .my-component {
+    @apply p-16up bg-surface-300; /* ERROR: Cannot apply unknown utility class */
+  }
+}
+```
+
+### Path Resolution
+
+The `@reference` path must be relative to your CSS file's location:
+
+E.g. `/src/routes/examples/style.css` → `@reference '../../app.css'`
+
+```svelte
+<style>
+  [data-page] {
+    & .my-component {
+      @apply p-16up bg-surface-300 border border-primary-500;
+    }
+  }
+</style>
+```
+
+### Troubleshooting
+
+If you see errors like:
+- `Cannot apply unknown utility class 'p-16up'`
+- `Cannot apply unknown utility class 'bg-surface-300'`
+- `Are you using CSS modules or similar and missing @reference?`
+
+**Solution**: Add `@reference` directive with the correct relative path to your `app.css` file.
+
 ## Core Concepts
 
 ### Responsive Scaling System
@@ -162,6 +232,9 @@ Available for all text point sizes: `1ut/bt/ht`, `2ut/bt/ht`, `4ut/bt/ht`, `6ut/
 
 **Auto Contrast**: Each color includes automatic contrast colors for accessibility. Use `text-{color}-contrast-{shade}` for optimal readability.
 
+**Skeleton**
+This library is based on both Tailwind and Skeleton. See [Skeleton Design Colors](https://www.skeleton.dev/docs/design/colors).
+
 ## Component Styling
 
 Components use `data-` attributes with CSS custom properties:
@@ -185,7 +258,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 +272,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 +285,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 +309,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 +321,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 +346,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 +354,8 @@ const cleanupCustom = enableContainerScaling({
   onMount(() => {
     cleanup = enableContainerScaling({
       container: containerElement,
-      design: DESIGN,
-      clamping: CLAMPING
+      design: designTokens.DESIGN,
+      clamping: designTokens.CLAMPING
     });
   });
   
@@ -302,59 +375,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 }
+  },
 
-// 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_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 }
+  },
+
+  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 +514,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]
+};
 ```
 
 ---