@hkdigital/lib-core 0.3.15 → 0.4.4

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
 
@@ -131,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

@@ -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]
     }
   })
 );

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

@@ -18,10 +18,18 @@ 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 Tailwind's default theme using the design system tokens
     extend: themeExtensions
   },
   plugins: [
+    // Generate custom utility classes like 'type-heading-h2'
     customUtilitiesPlugin
   ]
 };
@@ -40,6 +48,70 @@ export default {
 {@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
@@ -160,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:

package/dist/design/generators/index.js

@@ -83,10 +83,45 @@ export function generateTailwindThemeExtensions({
 
     outlineOffset: {
       ...generateWidthStyles(STROKE_WIDTH_SIZES, '')
+    },
+
+    colors: {
+      ...generateColorStyles()
+    },
+
+    borderColor: {
+      ...generateColorStyles()
     }
   };
 }
 
+/**
+ * Generates color styles using CSS variables
+ * Creates color classes for the design system theme
+ * @returns {Object} Color styles in Tailwind format
+ */
+function generateColorStyles() {
+  const shades = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
+  const colorNames = ['primary', 'secondary', 'tertiary', 'surface', 'success', 'warning', 'error'];
+  const colors = {};
+
+  // Generate main color variations
+  for (const colorName of colorNames) {
+    colors[colorName] = {};
+    for (const shade of shades) {
+      colors[colorName][shade] = `rgb(var(--color-${colorName}-${shade}) / <alpha-value>)`;
+    }
+    
+    // Add contrast colors
+    for (const shade of shades) {
+      colors[`${colorName}-contrast`] = colors[`${colorName}-contrast`] || {};
+      colors[`${colorName}-contrast`][shade] = `rgb(var(--color-${colorName}-contrast-${shade}) / <alpha-value>)`;
+    }
+  }
+
+  return colors;
+}
+
 /**
  * Generates text-based spacing units with with different scaling
  * units (ut, bt, ht)

package/dist/design/themes/hkdev/components/buttons/button-text.css

@@ -2,14 +2,31 @@
 /* Type-based styling for text buttons */
 [data-component='button'][data-type='text'] {
   /* Typography settings */
-  @apply font-ui text-ui-md;
+  @apply type-ui-md-dark;
   @apply uppercase;
   @apply whitespace-nowrap;
 
   /* Size settings */
 
+  &[data-size='sm'] {
+    @apply rounded-sm;
+    @apply type-ui-sm-dark;
+    @apply py-2ut px-8ut;
+    min-width: var(--btn-min-width);
+    min-height: var(--btn-min-height);
+  }
+
   &[data-size='md'] {
     @apply rounded-sm;
+    @apply type-ui-md-dark;
+    @apply py-4ut px-8ut;
+    min-width: var(--btn-min-width);
+    min-height: var(--btn-min-height);
+  }
+
+  &[data-size='lg'] {
+    @apply rounded-sm;
+    @apply type-ui-lg-dark;
     @apply py-8ut px-16ut;
     min-width: var(--btn-min-width);
     min-height: var(--btn-min-height);
@@ -17,10 +34,12 @@
 
   /* Role-specific text adjustments */
   &[data-role='primary'] {
+    color: var(--btn-primary-text);
     @apply font-extrabold;
   }
 
   &[data-role='secondary'] {
+    color: var(--btn-secondary-text);
     @apply font-bold;
   }
 }

package/dist/design/themes/hkdev/theme-ext.js

@@ -1,4 +1,4 @@
-import { theme as themeStore } from '../../../stores/index.js';
+import { theme as themeStore } from '../../../state/stores.js';
 
 /**
  * Set meta them color for the current theme

package/dist/{classes/data → generic/data/classes}/IterableTree.js

@@ -1,8 +1,8 @@
 /* ------------------------------------------------------------------ Imports */
 
-import * as expect from '../../util/expect/index.js';
+import * as expect from '../../../util/expect/index.js';
 
-import { PATH_SEPARATOR } from '../../util/object/index.js';
+import { PATH_SEPARATOR } from '../../../util/object/index.js';
 
 /* ------------------------------------------------------------------ Typedef */
 

package/dist/{classes/data → generic/data/classes}/Selector.js

@@ -28,7 +28,7 @@
 
 /* ------------------------------------------------------------------ Imports */
 
-import * as expect from '../../util/expect/index.js';
+import * as expect from '../../../util/expect/index.js';
 
 /* ------------------------------------------------------------------- Export */
 

package/dist/generic/data/classes/typedef.d.ts

@@ -0,0 +1,24 @@
+declare const _default: {};
+export default _default;
+export type IterableTreeOptions = {
+    /**
+     * - Whether to walk into array elements
+     */
+    walkArrays?: boolean;
+    /**
+     * - Whether to ignore empty object leaves
+     */
+    ignoreEmptyObjectLeaves?: boolean;
+    /**
+     * - Whether to expand path keys
+     */
+    expandPathKeys?: boolean;
+    /**
+     * - Whether to output intermediate nodes
+     */
+    outputIntermediateNodes?: boolean;
+    /**
+     * - Whether to use depth-first traversal
+     */
+    depthFirst?: boolean;
+};

package/dist/generic/data/classes/typedef.js

@@ -0,0 +1,14 @@
+/**
+ * Generic data class type definitions
+ */
+
+/**
+ * @typedef {object} IterableTreeOptions
+ * @property {boolean} [walkArrays=false] - Whether to walk into array elements
+ * @property {boolean} [ignoreEmptyObjectLeaves=false] - Whether to ignore empty object leaves
+ * @property {boolean} [expandPathKeys=false] - Whether to expand path keys
+ * @property {boolean} [outputIntermediateNodes=false] - Whether to output intermediate nodes
+ * @property {boolean} [depthFirst=true] - Whether to use depth-first traversal
+ */
+
+export default {};

package/dist/generic/data.d.ts

@@ -0,0 +1,2 @@
+export { default as Selector } from "./data/classes/Selector.js";
+export { default as IterableTree } from "./data/classes/IterableTree.js";

package/dist/generic/data.js

@@ -0,0 +1,2 @@
+export { default as Selector } from './data/classes/Selector.js';
+export { default as IterableTree } from './data/classes/IterableTree.js';

package/dist/generic/errors.d.ts

@@ -0,0 +1,2 @@
+export * from "./errors/generic.js";
+export * from "./errors/promise.js";

package/dist/generic/errors.js

@@ -0,0 +1,2 @@
+export * from './errors/generic.js';
+export * from './errors/promise.js';

package/dist/generic/events.d.ts

@@ -0,0 +1 @@
+export { default as EventEmitter } from "./events/classes/EventEmitter.js";

package/dist/generic/events.js

@@ -0,0 +1 @@
+export { default as EventEmitter } from './events/classes/EventEmitter.js';

package/dist/{classes/promise → generic/promises/classes}/HkPromise.d.ts

@@ -2,12 +2,16 @@
  * HkPromise extends the default javascript Promise class
  * - Exposes methods to interact with the state of the
  *   promise, such as 'resolve' and 'reject'
+ *
+ * @template T
+ * @extends {Promise<T>}
+ * @implements {PromiseLike<T>}
  */
-export default class HkPromise extends Promise<any> {
+export default class HkPromise<T> extends Promise<T> implements PromiseLike<T> {
     /**
-     * @param {(resolveFn?:function, rejectFn?:function)=>void} [initFn]
+     * @param {(resolveFn?: (value: T | PromiseLike<T>) => void, rejectFn?: (reason?: any) => void) => void} [initFn]
      */
-    constructor(initFn?: (resolveFn?: Function, rejectFn?: Function) => void);
+    constructor(initFn?: (resolveFn?: (value: T | PromiseLike<T>) => void, rejectFn?: (reason?: any) => void) => void);
     /**
      * Get value of property [resolved]
      *
@@ -108,15 +112,21 @@ export default class HkPromise extends Promise<any> {
     /**
      * Register a callback that is called when the promise resolves
      *
-     * @param {...any} args - Callback functions and options
+     * @template TResult1
+     * @template TResult2
+     * @param {((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null} [onfulfilled]
+     * @param {((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null} [onrejected]
+     * @returns {Promise<TResult1 | TResult2>}
      */
-    then(...args: any[]): Promise<any>;
+    then<TResult1, TResult2>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): Promise<TResult1 | TResult2>;
     /**
      * Register a callback that is called when the promise rejects, is
      * cancelled or times out
      *
-     * @param {...any} args - Callback functions and options
+     * @template TResult
+     * @param {((reason: any) => TResult | PromiseLike<TResult>) | undefined | null} [onrejected]
+     * @returns {Promise<T | TResult>}
      */
-    catch(...args: any[]): Promise<any>;
+    catch<TResult>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null): Promise<T | TResult>;
     #private;
 }

package/dist/{classes/promise → generic/promises/classes}/HkPromise.js

@@ -34,11 +34,11 @@
 
 /* ------------------------------------------------------------------ Imports */
 
-import * as expect from '../../util/expect/index.js';
+import * as expect from '../../../util/expect/index.js';
 
-import { noop } from '../../util/function/index.js';
+import { noop } from '../../../util/function/index.js';
 
-import { PromiseError } from '../../errors/promise.js';
+import { PromiseError } from '../../errors.js';
 
 /* ---------------------------------------------------------------- Internals */
 
@@ -48,6 +48,10 @@ import { PromiseError } from '../../errors/promise.js';
  * HkPromise extends the default javascript Promise class
  * - Exposes methods to interact with the state of the
  *   promise, such as 'resolve' and 'reject'
+ * 
+ * @template T
+ * @extends {Promise<T>}
+ * @implements {PromiseLike<T>}
  */
 export default class HkPromise extends Promise {
 	// Private fields using modern JavaScript syntax
@@ -62,7 +66,7 @@ export default class HkPromise extends Promise {
 	#hasThen = false;
 
 	/**
-	 * @param {(resolveFn?:function, rejectFn?:function)=>void} [initFn]
+	 * @param {(resolveFn?: (value: T | PromiseLike<T>) => void, rejectFn?: (reason?: any) => void) => void} [initFn]
 	 */
 	constructor(initFn) {
 		let _resolveFn;
@@ -364,21 +368,27 @@ export default class HkPromise extends Promise {
 	/**
 	 * Register a callback that is called when the promise resolves
 	 *
-	 * @param {...any} args - Callback functions and options
+	 * @template TResult1
+	 * @template TResult2
+	 * @param {((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null} [onfulfilled]
+	 * @param {((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null} [onrejected]
+	 * @returns {Promise<TResult1 | TResult2>}
 	 */
-	then(...args) {
+	then(onfulfilled, onrejected) {
 		this.#hasThen = true;
 
-		return super.then(...args);
+		return super.then(onfulfilled, onrejected);
 	}
 
 	/**
 	 * Register a callback that is called when the promise rejects, is
 	 * cancelled or times out
 	 *
-	 * @param {...any} args - Callback functions and options
+	 * @template TResult
+	 * @param {((reason: any) => TResult | PromiseLike<TResult>) | undefined | null} [onrejected]
+	 * @returns {Promise<T | TResult>}
 	 */
-	catch(...args) {
-		return super.catch(...args);
+	catch(onrejected) {
+		return super.catch(onrejected);
 	}
 } // end class

package/dist/generic/promises.d.ts

@@ -0,0 +1 @@
+export { default as HkPromise } from "./promises/classes/HkPromise.js";

package/dist/generic/promises.js

@@ -0,0 +1 @@
+export { default as HkPromise } from './promises/classes/HkPromise.js';

package/dist/{classes/streams → generic/streaming/classes}/ServerEventsStore.d.ts

@@ -18,4 +18,4 @@ export default class ServerEventsStore {
     subscribe(fn: import("svelte/store").Subscriber<object | null>): () => void;
     #private;
 }
-import SubscribersCount from '../stores/SubscribersCount.js';
+import { SubscribersCount } from '../../../state/classes.js';

package/dist/{classes/streams → generic/streaming/classes}/ServerEventsStore.js

@@ -2,9 +2,9 @@ import { writable } from 'svelte/store';
 
 // eslint-disable-next-line no-unused-vars
 import * as v from 'valibot';
-import { AbsOrRelUrl } from '../../valibot/index.js';
+import { AbsOrRelUrl } from '../../../valibot/index.js';
 
-import SubscribersCount from '../stores/SubscribersCount.js';
+import { SubscribersCount } from '../../../state/classes.js';
 
 // > Class
 

package/dist/generic/streaming.d.ts

@@ -0,0 +1,3 @@
+export { default as LogTransformStream } from "./streaming/classes/LogTransformStream.js";
+export { default as ServerEventsStore } from "./streaming/classes/ServerEventsStore.js";
+export { default as TimeStampSource } from "./streaming/classes/TimeStampSource.js";

package/dist/generic/streaming.js

@@ -0,0 +1,3 @@
+export { default as LogTransformStream } from './streaming/classes/LogTransformStream.js';
+export { default as ServerEventsStore } from './streaming/classes/ServerEventsStore.js';
+export { default as TimeStampSource } from './streaming/classes/TimeStampSource.js';

package/dist/generic/typedef.d.ts

@@ -0,0 +1 @@
+export * from "./data/typedef.js";

package/dist/generic/typedef.js

@@ -0,0 +1 @@
+export * from './data/typedef.js';