@hkdigital/lib-core 0.3.14 → 0.4.3

package/dist/network/loaders/image/ImageScene.svelte.js

@@ -2,8 +2,9 @@
 
 import * as expect from '../../../util/expect/index.js';
 
+import { LoadingStateMachine } from '../../../state/classes.js';
+
 import {
-  LoadingStateMachine,
   STATE_INITIAL,
   STATE_LOADING,
   STATE_UNLOADING,
@@ -12,7 +13,7 @@ import {
   STATE_ERROR,
   LOAD,
   LOADED
-} from '../../../classes/svelte/loading-state-machine/index.js';
+} from '../../../state/classes/loading-state-machine/constants.js';
 
 import ImageLoader from './ImageLoader.svelte.js';
 
@@ -148,7 +149,7 @@ export default class ImageScene {
    *
    * @param {object} _
    * @param {string} _.label
-   * @param {import('../typedef.js').ImageSource} _.imageSource
+   * @param {import('../../../config/typedef.js').ImageSource} _.imageSource
    */
   defineImage({ label, imageSource }) {
     expect.notEmptyString(label);
@@ -188,7 +189,7 @@ export default class ImageScene {
    *
    * @returns {ImageSceneSource}
    */
-  #getImageSource(label) {
+  #getImageSceneSource(label) {
     for (const source of this.#imageSources) {
       if (label === source.label) {
         return source;
@@ -213,7 +214,7 @@ export default class ImageScene {
    * @returns {ImageLoader}
    */
   getImageLoader(label) {
-    const source = this.#getImageSource(label);
+    const source = this.#getImageSceneSource(label);
 
     return source.imageLoader;
   }
@@ -226,9 +227,9 @@ export default class ImageScene {
    * @returns {ImageMeta}
    */
   getImageMeta(label) {
-    const source = this.#getImageSource(label);
+    const source = this.#getImageSceneSource(label);
 
-    return source.imageMeta;
+    return source.imageLoader.imageMeta;
   }
 
   /**
@@ -241,7 +242,7 @@ export default class ImageScene {
    * @returns {string}
    */
   getObjectURL(label) {
-    const source = this.#getImageSource(label);
+    const source = this.#getImageSceneSource(label);
 
     return source.imageLoader.getObjectURL();
   }

package/dist/network/loaders/image/ImageVariantsLoader.svelte.d.ts

@@ -1,9 +1,9 @@
-/** @typedef {import('../typedef.js').ImageMeta} ImageMeta */
+/** @typedef {import('../../../config/typedef.js').ImageMeta} ImageMeta */
 export default class ImageVariantsLoader {
     /**
-     * @param {ImageMeta[]} imagesMeta
+     * @param {ImageMeta[]} imageSource
      */
-    constructor(imagesMeta: ImageMeta[], { devicePixelRatio }?: {
+    constructor(imageSource: ImageMeta[], { devicePixelRatio }?: {
         devicePixelRatio?: number;
     });
     /**
@@ -20,7 +20,7 @@ export default class ImageVariantsLoader {
         fit?: "cover" | "contain" | "fill";
     }): void;
     get loaded(): boolean;
-    get variant(): import("../typedef.js").ImageMeta;
+    get variant(): import("../../../config/typedef.js").ImageMeta;
     /**
      * Get object URL that can be used as src parameter of an HTML image
      *
@@ -40,4 +40,4 @@ export default class ImageVariantsLoader {
     getOptimalImageMeta(containerWidth: number): ImageMeta | null;
     #private;
 }
-export type ImageMeta = import("../typedef.js").ImageMeta;
+export type ImageMeta = import("../../../config/typedef.js").ImageMeta;

package/dist/network/loaders/image/ImageVariantsLoader.svelte.js

@@ -2,14 +2,14 @@ import { calculateEffectiveWidth } from './utils/index.js';
 
 import ImageLoader from './ImageLoader.svelte.js';
 
-/** @typedef {import('../typedef.js').ImageMeta} ImageMeta */
+/** @typedef {import('../../../config/typedef.js').ImageMeta} ImageMeta */
 
 export default class ImageVariantsLoader {
   /** @type {number} */
   #devicePixelRatio;
 
   /** @type {ImageMeta[]} */
-  #imagesMeta;
+  #imageSource;
 
   /** @type {ImageMeta|null} */
   #imageVariant = $state(null);
@@ -28,12 +28,13 @@ export default class ImageVariantsLoader {
   #loaded = $derived.by(() => this.#progress?.loaded || false);
 
   /**
-   * @param {ImageMeta[]} imagesMeta
+   * @param {ImageMeta[]} imageSource
    */
-  constructor(imagesMeta, { devicePixelRatio = 1 } = {}) {
+  constructor(imageSource, { devicePixelRatio = 1 } = {}) {
     this.#devicePixelRatio = devicePixelRatio ?? 1;
-    this.#imagesMeta = [...imagesMeta].sort((a, b) => a.width - b.width);
-    // console.debug("imagesMeta",imagesMeta);
+    // Keep images in large-to-small order (as provided)
+    this.#imageSource = [...imageSource];
+    // console.debug("imageSource",imageSource);
   }
 
   /**
@@ -45,7 +46,7 @@ export default class ImageVariantsLoader {
    * @param {'cover'|'contain'|'fill'} [params.fit='contain'] Fit mode
    */
   updateOptimalImageMeta({ containerWidth, containerHeight, fit = 'contain' }) {
-    const baseImage = this.#imagesMeta[0];
+    const baseImage = this.#imageSource[0];
     const imageAspectRatio = baseImage.width / baseImage.height;
 
     const effectiveWidth = calculateEffectiveWidth({
@@ -71,7 +72,7 @@ export default class ImageVariantsLoader {
         this.#imageLoader.unload();
       }
 
-      this.#imageLoader = new ImageLoader(newVariant);
+      this.#imageLoader = new ImageLoader([newVariant]);
 
 
       this.#imageLoader.load();
@@ -136,15 +137,15 @@ export default class ImageVariantsLoader {
     // Calculate the required width (container * DPR)
     const requiredWidth = containerWidth * this.#devicePixelRatio;
 
-    const imagesMeta = this.#imagesMeta;
+    const imagesMeta = this.#imageSource;
 
-    // Find the smallest image that's larger than our required width
-
-    const optimal = imagesMeta.find(
+    // Array is large-to-small, so find the last (smallest) image that's still >= required width
+    // This gives us the smallest image that's larger than our required width
+    const optimal = imagesMeta.findLast(
       (current) => current.width >= requiredWidth
     );
 
     // Fall back to the largest image if nothing is big enough
-    return optimal || imagesMeta[imagesMeta.length - 1];
+    return optimal || imagesMeta[0];
   }
 } // end class

package/dist/network/loaders/image/utils/index.d.ts

@@ -4,9 +4,9 @@
  * of sorted responsive image formats, so it should be the
  * largest image.
  *
- * @param {import('../../typedef.js').ImageSource} imageSource
+ * @param {import('../../../../config/typedef.js').ImageSource} imageSource
  */
-export function toSingleImageMeta(imageSource: import("../../typedef.js").ImageSource): import("../../typedef.js").ImageMeta;
+export function toSingleImageMeta(imageSource: import("../../../../config/typedef.js").ImageSource): import("../../../../config/typedef.js").ImageMeta;
 /**
  * Calculate effective width based on container dimensions and fit mode
  *

package/dist/network/loaders/image/utils/index.js

@@ -1,26 +1,23 @@
+import { expect } from '../../../../util/index.js';
+
 /**
  * Returns the unchanged image meta object or the last item of
  * an array of ImageMeta objects. This is assumed to be a list
  * of sorted responsive image formats, so it should be the
  * largest image.
  *
- * @param {import('../../typedef.js').ImageSource} imageSource
+ * @param {import('../../../../config/typedef.js').ImageSource} imageSource
  */
 export function toSingleImageMeta(imageSource) {
-  if (Array.isArray(imageSource)) {
-    if (!imageSource.length) {
-      throw new Error('List of ImageMeta objects is empty');
-    }
-    imageSource = imageSource[imageSource.length - 1];
-  }
+  expect.array(imageSource);
+
+  const imageMeta = imageSource[0];
 
-  if (typeof imageSource === 'object') {
-    return imageSource;
-  } else if (!imageSource) {
-    throw new Error('Missing [imageSource]');
+  if (typeof imageMeta !== 'object') {
+    throw new Error('Invalid value for parameter [imageSource]');
   }
 
-  throw new Error('Invalid value for parameter [imageSource]');
+  return imageMeta;
 }
 
 /**

package/dist/network/loaders/typedef.d.ts

@@ -1,12 +1,3 @@
 declare const _default: {};
 export default _default;
-export type ImageMeta = {
-    src: string;
-    width: number;
-    height: number;
-};
-/**
- * Single ImageMeta object or array of ImageMeta objects
- */
-export type ImageSource = ImageMeta | ImageMeta[];
 export type ObjectPosition = "center" | "top" | "bottom" | "left" | "right" | "left top" | "left center" | "left bottom" | "center top" | "center center" | "center bottom" | "right top" | "right center" | "right bottom" | string;

package/dist/network/loaders/typedef.js

@@ -1,15 +1,3 @@
-/**
- * @typedef {object} ImageMeta
- * @property {string} src
- * @property {number} width
- * @property {number} height
- */
-
-/**
- * @typedef {ImageMeta | ImageMeta[]} ImageSource
- * Single ImageMeta object or array of ImageMeta objects
- */
-
 /**
  * @typedef {"center" | "top" | "bottom" | "left" | "right" |
  *          "left top" | "left center" | "left bottom" |

package/dist/network/states/NetworkLoader.svelte.d.ts

@@ -88,4 +88,4 @@ export default class NetworkLoader {
     getObjectURL(): string;
     #private;
 }
-import { LoadingStateMachine } from '../../classes/svelte/loading-state-machine/index.js';
+import { LoadingStateMachine } from '../../state/classes.js';

package/dist/network/states/NetworkLoader.svelte.js

@@ -1,7 +1,8 @@
 import { CONTENT_TYPE } from '../../constants/http/index.js';
 
+import { LoadingStateMachine } from '../../state/classes.js';
+
 import {
-  LoadingStateMachine,
   STATE_INITIAL,
   STATE_LOADING,
   STATE_UNLOADING,
@@ -13,7 +14,7 @@ import {
   LOADED,
   UNLOAD,
   INITIAL
-} from '../../classes/svelte/loading-state-machine/index.js';
+} from '../../state/classes/loading-state-machine/constants.js';
 
 import * as expect from '../../util/expect/index.js';
 

package/dist/services/index.d.ts

@@ -2,5 +2,3 @@ export { default as ServiceBase } from "./service-base/ServiceBase.js";
 export { default as ServiceManager } from "./service-manager/ServiceManager.js";
 export * from "./service-base/constants.js";
 export * from "./service-manager/constants.js";
-export * from "./service-base/typedef.js";
-export * from "./service-manager/typedef.js";

package/dist/services/index.js

@@ -3,6 +3,3 @@ export { default as ServiceManager } from './service-manager/ServiceManager.js';
 
 export * from './service-base/constants.js';
 export * from './service-manager/constants.js';
-
-export * from './service-base/typedef.js';
-export * from './service-manager/typedef.js';

package/dist/services/service-base/ServiceBase.d.ts

@@ -157,5 +157,5 @@ export type HealthStatus = import("./typedef.js").HealthStatus;
 export type StateChangeEvent = import("./typedef.js").StateChangeEvent;
 export type HealthChangeEvent = import("./typedef.js").HealthChangeEvent;
 export type ServiceErrorEvent = import("./typedef.js").ServiceErrorEvent;
-import { EventEmitter } from '../../classes/event-emitter';
-import { Logger } from '../../logging/internal/logger';
+import { EventEmitter } from '../../generic/events.js';
+import { Logger } from '../../logging/index.js';

package/dist/services/service-base/ServiceBase.js

@@ -50,8 +50,9 @@
  * }
  */
 
-import { EventEmitter } from '../../classes/event-emitter';
-import { Logger, INFO } from '../../logging/internal/logger';
+import { EventEmitter } from '../../generic/events.js';
+import { Logger, INFO } from '../../logging/index.js';
+import { DetailedError } from '../../generic/errors.js';
 
 import {
   CREATED,
@@ -117,9 +118,11 @@ export class ServiceBase extends EventEmitter {
    * @returns {Promise<boolean>} True if initialization succeeded
    */
   async initialize(config = {}) {
-    if (this.state !== CREATED &&
-        this.state !== STOPPED &&
-        this.state !== DESTROYED) {
+    if (
+      this.state !== CREATED &&
+      this.state !== STOPPED &&
+      this.state !== DESTROYED
+    ) {
       this.logger.warn(`Cannot initialize from state: ${this.state}`);
       return false;
     }
@@ -443,18 +446,19 @@ export class ServiceBase extends EventEmitter {
    * @param {Error} error - Error that occurred
    */
   _setError(operation, error) {
-    this.error = error;
+    const detailedError = new DetailedError(`${operation} failed`, {
+      cause: error
+    });
+
+    this.error = detailedError;
     this._setState(ERROR_STATE);
     this._setHealthy(false);
 
-    this.logger.error(`${operation} failed`, {
-      error: error.message,
-      stack: error.stack
-    });
+    this.logger.error(detailedError);
 
     this.emit('error', {
       operation,
-      error
+      error: detailedError
     });
   }
 }

package/dist/services/service-base/typedef.d.ts

@@ -55,38 +55,9 @@ export type HealthStatus = {
 };
 /**
  * Base class interface that services must implement
+ * Allows additional custom properties and methods via Record<string, any>
  */
-export type ServiceInstance = {
-    /**
-     * - Service name
-     */
-    name: string;
-    /**
-     * - Current state
-     */
-    state: string;
-    /**
-     * - Health status
-     */
-    healthy: boolean;
-    /**
-     * - Last error
-     */
-    error: Error | null;
-    /**
-     * - Service logger
-     */
-    logger: import("../../logging/internal/logger").Logger;
-    initialize: (config?: any) => Promise<boolean>;
-    start: () => Promise<boolean>;
-    stop: (options?: StopOptions) => Promise<boolean>;
-    recover: () => Promise<boolean>;
-    destroy: () => Promise<boolean>;
-    getHealth: () => Promise<HealthStatus>;
-    setLogLevel: (level: string) => boolean;
-    on: (event: string, handler: Function) => Function;
-    emit: (event: string, data: any) => boolean;
-};
+export type ServiceInstance = any & Record<string, any>;
 export type StateChangeEvent = {
     /**
      * - Service name (added by ServiceManager)

package/dist/services/service-base/typedef.js

@@ -53,13 +53,14 @@
 
 /**
  * Base class interface that services must implement
+ * Allows additional custom properties and methods via Record<string, any>
  *
- * @typedef {Object} ServiceInstance
+ * @typedef {Object & Record<string, any>} ServiceInstance
  * @property {string} name - Service name
  * @property {string} state - Current state
  * @property {boolean} healthy - Health status
  * @property {Error|null} error - Last error
- * @property {import('../../logging/internal/logger').Logger} logger - Service logger
+ * @property {import('../../logging/index.js').Logger} logger - Service logger
  * @property {(config?: *) => Promise<boolean>} initialize
  * @property {() => Promise<boolean>} start
  * @property {(options?: StopOptions) => Promise<boolean>} stop

package/dist/services/service-manager/ServiceManager.d.ts

@@ -40,10 +40,10 @@ export class ServiceManager extends EventEmitter {
      *
      * @param {string} name - Service name
      *
-     * @returns {import('./typedef.js').ServiceInstance|null}
+     * @returns {import('../service-base/typedef.js').ServiceInstance|null}
      *   Service instance or null if not found
      */
-    get(name: string): import("./typedef.js").ServiceInstance | null;
+    get(name: string): import("../service-base/typedef.js").ServiceInstance | null;
     /**
      * Initialize a service
      *
@@ -141,5 +141,5 @@ export type ServiceManagerConfig = import("./typedef.js").ServiceManagerConfig;
 export type ServiceEntry = import("./typedef.js").ServiceEntry;
 export type HealthCheckResult = import("./typedef.js").HealthCheckResult;
 export type StopOptions = import("../service-base/typedef.js").StopOptions;
-import { EventEmitter } from '../../classes/event-emitter';
+import { EventEmitter } from '../../generic/events.js';
 import { Logger } from '../../logging/index.js';

package/dist/services/service-manager/ServiceManager.js

@@ -63,7 +63,7 @@
  * });
  */
 
-import { EventEmitter } from '../../classes/event-emitter';
+import { EventEmitter } from '../../generic/events.js';
 import { Logger, DEBUG, INFO, WARN } from '../../logging/index.js';
 
 import {
@@ -160,7 +160,7 @@ export class ServiceManager extends EventEmitter {
    *
    * @param {string} name - Service name
    *
-   * @returns {import('./typedef.js').ServiceInstance|null}
+   * @returns {import('../service-base/typedef.js').ServiceInstance|null}
    *   Service instance or null if not found
    */
   get(name) {

package/dist/services/service-manager/typedef.d.ts

@@ -63,12 +63,12 @@ export type LogConfig = {
  * Result of health check for all services
  */
 export type HealthCheckResult = {
-    [x: string]: HealthStatus;
+    [x: string]: import("../service-base/typedef.js").HealthStatus;
 };
 /**
  * Service class constructor type
  */
-export type ServiceConstructor = new (name: string, options?: ServiceOptions) => ServiceInstance;
+export type ServiceConstructor = new (name: string, options?: import("../service-base/typedef.js").ServiceOptions) => import("../service-base/typedef.js").ServiceInstance;
 /**
  * Internal service registry entry
  */
@@ -80,7 +80,7 @@ export type ServiceEntry = {
     /**
      * - Service instance (lazy-created)
      */
-    instance: ServiceInstance | null;
+    instance: import("../service-base/typedef.js").ServiceInstance | null;
     /**
      * - Service configuration
      */

package/dist/services/service-manager/typedef.js

@@ -61,13 +61,13 @@
 
 /**
  * Result of health check for all services
- * @typedef {Object<string, HealthStatus>} HealthCheckResult
+ * @typedef {Object<string, import('../service-base/typedef.js').HealthStatus>} HealthCheckResult
  */
 
 /**
  * Service class constructor type
  *
- * @typedef {new (name: string, options?: ServiceOptions) => ServiceInstance} ServiceConstructor
+ * @typedef {new (name: string, options?: import('../service-base/typedef.js').ServiceOptions) => import('../service-base/typedef.js').ServiceInstance} ServiceConstructor
  */
 
 // ============================================================================
@@ -79,7 +79,7 @@
  *
  * @typedef {Object} ServiceEntry
  * @property {ServiceConstructor} ServiceClass - Service class constructor
- * @property {ServiceInstance|null} instance - Service instance (lazy-created)
+ * @property {import('../service-base/typedef.js').ServiceInstance|null} instance - Service instance (lazy-created)
  * @property {*} config - Service configuration
  * @property {string[]} dependencies - Service dependencies
  * @property {Set<string>} dependents - Services that depend on this one

package/dist/services/typedef.d.ts

@@ -0,0 +1,2 @@
+export * from "./service-base/typedef.js";
+export * from "./service-manager/typedef.js";

package/dist/services/typedef.js

@@ -0,0 +1,2 @@
+export * from './service-base/typedef.js';
+export * from './service-manager/typedef.js';

package/dist/{classes/svelte → state/classes}/loading-state-machine/LoadingStateMachine.svelte.d.ts

@@ -9,4 +9,4 @@ export default class LoadingStateMachine extends FiniteStateMachine {
     get error(): Error;
     #private;
 }
-import { FiniteStateMachine } from '../finite-state-machine/index.js';
+import FiniteStateMachine from '../finite-state-machine/FiniteStateMachine.svelte.js';

package/dist/{classes/svelte → state/classes}/loading-state-machine/LoadingStateMachine.svelte.js

@@ -1,6 +1,6 @@
 //import { FiniteStateMachine } from 'runed';
 
-import { FiniteStateMachine } from '../finite-state-machine/index.js';
+import FiniteStateMachine from '../finite-state-machine/FiniteStateMachine.svelte.js';
 
 import {
   // > States

package/dist/state/classes/subscribers-count/index.d.ts

@@ -0,0 +1 @@
+export { default as SubScribersCount } from "./SubscribersCount.js";

package/dist/state/classes/subscribers-count/index.js

@@ -0,0 +1 @@
+export { default as SubScribersCount } from './SubscribersCount.js';

package/dist/state/classes.d.ts

@@ -0,0 +1,3 @@
+export { default as FiniteStateMachine } from "./classes/finite-state-machine/FiniteStateMachine.svelte.js";
+export { default as LoadingStateMachine } from "./classes/loading-state-machine/LoadingStateMachine.svelte.js";
+export { default as SubscribersCount } from "./classes/subscribers-count/SubscribersCount.js";

package/dist/state/classes.js

@@ -0,0 +1,3 @@
+export { default as FiniteStateMachine } from './classes/finite-state-machine/FiniteStateMachine.svelte.js';
+export { default as LoadingStateMachine } from './classes/loading-state-machine/LoadingStateMachine.svelte.js';
+export { default as SubscribersCount } from './classes/subscribers-count/SubscribersCount.js';

package/dist/{util/svelte/state-context/index.d.ts → state/context/state-context.d.ts}

@@ -14,5 +14,5 @@
  *   getState
  * ]}
  */
-export function defineStateContext<T>(State: new () => T): [(contextKey?: import("../../../typedef").ContextKey) => T, (contextKey?: import("../../../typedef").ContextKey) => T, (contextKey?: import("../../../typedef").ContextKey) => T];
+export function defineStateContext<T>(State: new () => T): [(contextKey?: import("./typedef").ContextKey) => T, (contextKey?: import("./typedef").ContextKey) => T, (contextKey?: import("./typedef").ContextKey) => T];
 export const DEFAULT_CONTEXT_KEY: "default";

package/dist/{util/svelte/state-context/index.js → state/context/state-context.js}

@@ -30,7 +30,7 @@ export function defineStateContext(State) {
   /**
    * Internal function to get the supplied key or the shared key
    *
-   * @param {import('../../../typedef').ContextKey} [contextKey]
+   * @param {import('./typedef').ContextKey} [contextKey]
    *
    * @returns {Symbol} key
    */
@@ -55,7 +55,7 @@ export function defineStateContext(State) {
   /**
    * Create component state
    *
-   * @param {import('../../../typedef').ContextKey} [contextKey]
+   * @param {import('./typedef').ContextKey} [contextKey]
    *
    * @returns {T} state
    */
@@ -80,7 +80,7 @@ export function defineStateContext(State) {
   /**
    * Get component state or create a new state if it does not yet exist
    *
-   * @param {import('../../../typedef').ContextKey} [contextKey]
+   * @param {import('./typedef').ContextKey} [contextKey]
    *
    * @returns {T} state
    */
@@ -99,7 +99,7 @@ export function defineStateContext(State) {
    *
    * @throws Will throw an error if the state-context does not exist
    *
-   * @param {import('../../../typedef').ContextKey} [contextKey]
+   * @param {import('./typedef').ContextKey} [contextKey]
    *
    * @returns {T} state
    */

package/dist/state/context.d.ts

@@ -0,0 +1 @@
+export { defineStateContext, DEFAULT_CONTEXT_KEY } from "./context/state-context.js";

package/dist/state/context.js

@@ -0,0 +1 @@
+export { defineStateContext, DEFAULT_CONTEXT_KEY } from './context/state-context.js';

package/dist/state/stores.d.ts

@@ -0,0 +1 @@
+export * as theme from "./stores/theme.js";

package/dist/state/stores.js

@@ -0,0 +1 @@
+export * as theme from './stores/theme.js';

package/dist/ui/README.md

@@ -0,0 +1,49 @@
+# UI Library Organization
+
+## Primitives vs Components
+
+### **Primitives** (`$lib/ui/primitives/`)
+Basic building blocks that are:
+- Single-purpose
+- Stateless or minimal state
+- Used as building blocks for more complex components
+- Simple, focused functionality
+
+**Examples:**
+- **buttons/** - Basic interactive elements
+- **icons/** - Simple icon wrappers  
+- **inputs/** - Form controls
+- **area/** - Basic layout containers (HkArea, HkGridArea)
+- **panels/** - Simple panel wrapper
+
+### **Components** (`$lib/ui/components/`)
+Compound or complex components that are:
+- Feature-complete solutions
+- Often stateful with complex behavior
+- Solve specific use cases
+- Combine multiple primitives or have complex internal logic
+
+**Examples:**
+- **presenter/** - Complex slideshow with state management
+- **image-box/** - Feature-rich image display
+- **game-box/** - Specialized game container
+- **hk-app-layout/** - Complex app layout with state
+- **compare-left-right/** - Specialized comparison view
+- **virtual-viewport/** - Complex viewport management
+- **button-group/** - Compound button collection
+- **drag-drop/** - Complex system with multiple interdependent parts
+- **tab-bar/** - Complex component with state management
+- **grid-layers/** - Complex layout system with utilities
+- **rows/** - Layout components that combine multiple elements
+
+## Usage
+
+```javascript
+// Import primitives for building blocks
+import { Button, TextInput, HkIcon } from '$lib/ui/primitives.js';
+
+// Import components for complete solutions
+import { Presenter, ImageBox, HkAppLayout } from '$lib/ui/components.js';
+```
+
+The distinction helps library users understand the intended use and complexity of each component.