;
+ /**
+ * Creates a new perspective manager
+ * @param config - Configuration for visual effects
+ */
constructor(config: PerspectiveConfig = {}) {
this.config = {
depthStep: config.depthStep ?? 100,
@@ -90,8 +122,10 @@ export class PerspectiveManager {
}
/**
- * Toggle between front (0) and back (1) positions.
- * Smooth spring animation handles the transition.
+ * Toggle between front and back positions
+ *
+ * Uses spring animation for smooth transition. Toggles based on
+ * current state - if spring < 0.5 goes to 1, otherwise goes to 0.
*/
toggle = () => {
const target = this.spring.current < 0.5 ? 1 : 0;
@@ -99,31 +133,40 @@ export class PerspectiveManager {
};
/**
- * Force to back position
+ * Force to back position (blurred, scaled down)
*/
setBack = () => {
this.spring.target = 1;
};
/**
- * Force to front position
+ * Force to front position (fully visible, interactive)
*/
setFront = () => {
this.spring.target = 0;
};
/**
- * Get configuration for style computation
- * @internal
+ * Get current configuration
+ * @internal Used by components to compute styles
*/
getConfig = () => this.config;
}
/**
- * Factory function to create a PerspectiveManager instance.
+ * Factory function to create a perspective manager
*
- * @param config - Configuration options
+ * @param config - Configuration options for visual effects
* @returns Configured PerspectiveManager instance
+ *
+ * @example
+ * ```ts
+ * const perspective = createPerspectiveManager({
+ * scaleStep: 0.6,
+ * blurStep: 8,
+ * layoutMode: 'split'
+ * });
+ * ```
*/
export function createPerspectiveManager(config: PerspectiveConfig = {}) {
return new PerspectiveManager(config);
diff --git a/src/shared/lib/helpers/createResponsiveManager/createResponsiveManager.svelte.ts b/src/shared/lib/helpers/createResponsiveManager/createResponsiveManager.svelte.ts
index 6556732..413b848 100644
--- a/src/shared/lib/helpers/createResponsiveManager/createResponsiveManager.svelte.ts
+++ b/src/shared/lib/helpers/createResponsiveManager/createResponsiveManager.svelte.ts
@@ -1,66 +1,96 @@
-// $shared/lib/createResponsiveManager.svelte.ts
+/**
+ * Responsive breakpoint tracking using Svelte 5 runes
+ *
+ * Provides reactive viewport dimensions and breakpoint detection that
+ * automatically updates on window resize. Includes touch device detection
+ * and orientation tracking.
+ *
+ * Default breakpoints match Tailwind CSS:
+ * - xs: < 640px (mobile)
+ * - sm: 640px (mobile)
+ * - md: 768px (tablet portrait)
+ * - lg: 1024px (tablet)
+ * - xl: 1280px (desktop)
+ * - 2xl: 1536px (desktop large)
+ *
+ * @example
+ * ```svelte
+ *
+ *
+ * {#if responsiveManager.isMobile}
+ *
+ * {:else}
+ *
+ * {/if}
+ *
+ * Viewport: {responsiveManager.width}x{responsiveManager.height}
+ * Breakpoint: {responsiveManager.currentBreakpoint}
+ * ```
+ */
/**
- * Breakpoint definitions following common device sizes
- * Customize these values to match your design system
+ * Breakpoint definitions for responsive design
+ *
+ * Values represent the minimum width (in pixels) for each breakpoint.
+ * Customize to match your design system's breakpoints.
*/
export interface Breakpoints {
- /** Mobile devices (portrait phones) */
+ /** Mobile devices - default 640px */
mobile: number;
- /** Tablet portrait */
+ /** Tablet portrait - default 768px */
tabletPortrait: number;
- /** Tablet landscape */
+ /** Tablet landscape - default 1024px */
tablet: number;
- /** Desktop */
+ /** Desktop - default 1280px */
desktop: number;
- /** Large desktop */
+ /** Large desktop - default 1536px */
desktopLarge: number;
}
/**
- * Default breakpoints (matches common Tailwind-like breakpoints)
+ * Default breakpoint values (Tailwind CSS compatible)
*/
const DEFAULT_BREAKPOINTS: Breakpoints = {
- mobile: 640, // sm
- tabletPortrait: 768, // md
- tablet: 1024, // lg
- desktop: 1280, // xl
- desktopLarge: 1536, // 2xl
+ mobile: 640,
+ tabletPortrait: 768,
+ tablet: 1024,
+ desktop: 1280,
+ desktopLarge: 1536,
};
/**
- * Orientation type
+ * Device orientation type
*/
export type Orientation = 'portrait' | 'landscape';
/**
- * Creates a reactive responsive manager that tracks viewport size and breakpoints.
+ * Creates a responsive manager for tracking viewport state
*
- * Provides reactive getters for:
- * - Current breakpoint detection (isMobile, isTablet, etc.)
- * - Viewport dimensions (width, height)
- * - Device orientation (portrait/landscape)
- * - Custom breakpoint matching
+ * Tracks viewport dimensions, calculates breakpoint states, and detects
+ * device capabilities (touch, orientation). Uses ResizeObserver for
+ * accurate tracking and falls back to window resize events.
*
* @param customBreakpoints - Optional custom breakpoint values
* @returns Responsive manager instance with reactive properties
*
* @example
- * ```svelte
- *
+ * ```ts
+ * // Use defaults
+ * const responsive = createResponsiveManager();
*
- * {#if responsive.isMobile}
- *
- * {:else if responsive.isTablet}
- *
- * {:else}
- *
- * {/if}
+ * // Custom breakpoints
+ * const custom = createResponsiveManager({
+ * mobile: 480,
+ * desktop: 1024
+ * });
*
- * Width: {responsive.width}px
- * Orientation: {responsive.orientation}
+ * // In component
+ * $: isMobile = responsive.isMobile;
+ * $: cols = responsive.isDesktop ? 3 : 1;
* ```
*/
export function createResponsiveManager(customBreakpoints?: Partial) {
@@ -69,7 +99,7 @@ export function createResponsiveManager(customBreakpoints?: Partial
...customBreakpoints,
};
- // Reactive state
+ // Reactive viewport dimensions
let width = $state(typeof window !== 'undefined' ? window.innerWidth : 0);
let height = $state(typeof window !== 'undefined' ? window.innerHeight : 0);
@@ -90,12 +120,12 @@ export function createResponsiveManager(customBreakpoints?: Partial
const isMobileOrTablet = $derived(width < breakpoints.desktop);
const isTabletOrDesktop = $derived(width >= breakpoints.tabletPortrait);
- // Orientation
+ // Orientation detection
const orientation = $derived(height > width ? 'portrait' : 'landscape');
const isPortrait = $derived(orientation === 'portrait');
const isLandscape = $derived(orientation === 'landscape');
- // Touch device detection (best effort)
+ // Touch device detection (best effort heuristic)
const isTouchDevice = $derived(
typeof window !== 'undefined'
&& ('ontouchstart' in window || navigator.maxTouchPoints > 0),
@@ -103,7 +133,11 @@ export function createResponsiveManager(customBreakpoints?: Partial
/**
* Initialize responsive tracking
- * Call this in an $effect or component mount
+ *
+ * Sets up ResizeObserver on document.documentElement and falls back
+ * to window resize event listener. Returns cleanup function.
+ *
+ * @returns Cleanup function to remove listeners
*/
function init() {
if (typeof window === 'undefined') return;
@@ -130,9 +164,17 @@ export function createResponsiveManager(customBreakpoints?: Partial
}
/**
- * Check if current width matches a custom breakpoint
+ * Check if current viewport matches a custom breakpoint range
+ *
* @param min - Minimum width (inclusive)
- * @param max - Maximum width (exclusive)
+ * @param max - Optional maximum width (exclusive)
+ * @returns true if viewport width matches the range
+ *
+ * @example
+ * ```ts
+ * responsive.matches(768, 1024); // true for tablet only
+ * responsive.matches(1280); // true for desktop and larger
+ * ```
*/
function matches(min: number, max?: number): boolean {
if (max !== undefined) {
@@ -142,7 +184,7 @@ export function createResponsiveManager(customBreakpoints?: Partial
}
/**
- * Get the current breakpoint name
+ * Current breakpoint name based on viewport width
*/
const currentBreakpoint = $derived(
(() => {
@@ -158,16 +200,17 @@ export function createResponsiveManager(customBreakpoints?: Partial
case isDesktopLarge:
return 'desktopLarge';
default:
- return 'xs'; // Fallback for very small screens
+ return 'xs';
}
})(),
);
return {
- // Dimensions
+ /** Viewport width in pixels */
get width() {
return width;
},
+ /** Viewport height in pixels */
get height() {
return height;
},
@@ -227,6 +270,12 @@ export function createResponsiveManager(customBreakpoints?: Partial
};
}
+/**
+ * Singleton responsive manager instance
+ *
+ * Auto-initializes on the client side. Use this throughout the app
+ * rather than creating multiple instances.
+ */
export const responsiveManager = createResponsiveManager();
if (typeof window !== 'undefined') {
diff --git a/src/shared/lib/helpers/createResponsiveManager/createResponsiveManager.test.ts b/src/shared/lib/helpers/createResponsiveManager/createResponsiveManager.test.ts
new file mode 100644
index 0000000..c964914
--- /dev/null
+++ b/src/shared/lib/helpers/createResponsiveManager/createResponsiveManager.test.ts
@@ -0,0 +1,107 @@
+/**
+ * Tests for createResponsiveManager
+ */
+
+import {
+ describe,
+ expect,
+ it,
+} from 'vitest';
+import { createResponsiveManager } from './createResponsiveManager.svelte';
+
+describe('createResponsiveManager', () => {
+ describe('initialization', () => {
+ it('should create with default breakpoints', () => {
+ const manager = createResponsiveManager();
+
+ expect(manager.breakpoints).toEqual({
+ mobile: 640,
+ tabletPortrait: 768,
+ tablet: 1024,
+ desktop: 1280,
+ desktopLarge: 1536,
+ });
+ });
+
+ it('should merge custom breakpoints with defaults', () => {
+ const manager = createResponsiveManager({ mobile: 480, desktop: 1200 });
+
+ expect(manager.breakpoints.mobile).toBe(480);
+ expect(manager.breakpoints.desktop).toBe(1200);
+ expect(manager.breakpoints.tablet).toBe(1024); // default preserved
+ });
+
+ it('should have initial width and height from window', () => {
+ const manager = createResponsiveManager();
+
+ // In test environment, window dimensions come from jsdom/mocks
+ expect(typeof manager.width).toBe('number');
+ expect(typeof manager.height).toBe('number');
+ });
+ });
+
+ describe('matches', () => {
+ it('should return true when width is above min', () => {
+ const manager = createResponsiveManager();
+
+ // width is 0 in node env (no window), so matches(0) should be true
+ expect(manager.matches(0)).toBe(true);
+ });
+
+ it('should return false when width is below min', () => {
+ const manager = createResponsiveManager();
+
+ // width is 0, so matches(100) should be false
+ expect(manager.matches(100)).toBe(false);
+ });
+
+ it('should handle range with max', () => {
+ const manager = createResponsiveManager();
+
+ // width is 0, so matches(0, 100) should be true (0 >= 0 && 0 < 100)
+ expect(manager.matches(0, 100)).toBe(true);
+ // matches(1, 100) should be false (0 >= 1 is false)
+ expect(manager.matches(1, 100)).toBe(false);
+ });
+ });
+
+ describe('breakpoint states at width 0', () => {
+ it('should report isMobile when width is 0', () => {
+ const manager = createResponsiveManager();
+
+ expect(manager.isMobile).toBe(true);
+ expect(manager.isTabletPortrait).toBe(false);
+ expect(manager.isTablet).toBe(false);
+ expect(manager.isDesktop).toBe(false);
+ expect(manager.isDesktopLarge).toBe(false);
+ });
+
+ it('should report correct convenience groupings', () => {
+ const manager = createResponsiveManager();
+
+ expect(manager.isMobileOrTablet).toBe(true);
+ expect(manager.isTabletOrDesktop).toBe(false);
+ });
+ });
+
+ describe('orientation', () => {
+ it('should detect portrait when height > width', () => {
+ // Default: width=0, height=0 => not portrait (0 > 0 is false)
+ const manager = createResponsiveManager();
+
+ expect(manager.orientation).toBe('landscape');
+ expect(manager.isLandscape).toBe(true);
+ expect(manager.isPortrait).toBe(false);
+ });
+ });
+
+ describe('init', () => {
+ it('should return undefined in non-browser environment', () => {
+ const manager = createResponsiveManager();
+ const cleanup = manager.init();
+
+ // In node test env, window is undefined so init returns early
+ expect(cleanup).toBeUndefined();
+ });
+ });
+});
diff --git a/src/shared/lib/helpers/createTypographyControl/createTypographyControl.svelte.ts b/src/shared/lib/helpers/createTypographyControl/createTypographyControl.svelte.ts
index 7b1a390..10df8a7 100644
--- a/src/shared/lib/helpers/createTypographyControl/createTypographyControl.svelte.ts
+++ b/src/shared/lib/helpers/createTypographyControl/createTypographyControl.svelte.ts
@@ -1,46 +1,98 @@
+/**
+ * Numeric control with bounded values and step precision
+ *
+ * Creates a reactive control for numeric values that enforces min/max bounds
+ * and rounds to a specific step increment. Commonly used for typography controls
+ * like font size, line height, and letter spacing.
+ *
+ * @example
+ * ```ts
+ * const fontSize = createTypographyControl({
+ * value: 16,
+ * min: 12,
+ * max: 72,
+ * step: 1
+ * });
+ *
+ * // Access current value
+ * fontSize.value; // 16
+ * fontSize.isAtMin; // false
+ *
+ * // Modify value (automatically clamped and rounded)
+ * fontSize.increase();
+ * fontSize.value = 100; // Will be clamped to max (72)
+ * ```
+ */
+
import {
clampNumber,
roundToStepPrecision,
} from '$shared/lib/utils';
+/**
+ * Core numeric control configuration
+ * Defines the bounds and stepping behavior for a control
+ */
export interface ControlDataModel {
- /**
- * Control value
- */
+ /** Current numeric value */
value: number;
- /**
- * Minimal possible value
- */
+ /** Minimum allowed value (inclusive) */
min: number;
- /**
- * Maximal possible value
- */
+ /** Maximum allowed value (inclusive) */
max: number;
- /**
- * Step size for increase/decrease
- */
+ /** Step size for increment/decrement operations */
step: number;
}
+/**
+ * Full control model including accessibility labels
+ *
+ * @template T - Type for the control identifier
+ */
export interface ControlModel extends ControlDataModel {
- /**
- * Control identifier
- */
+ /** Unique identifier for the control */
id: T;
- /**
- * Area label for increase button
- */
+ /** ARIA label for the increase button */
increaseLabel?: string;
- /**
- * Area label for decrease button
- */
+ /** ARIA label for the decrease button */
decreaseLabel?: string;
- /**
- * Control area label
- */
+ /** ARIA label for the control area */
controlLabel?: string;
}
+/**
+ * Creates a reactive numeric control with bounds and stepping
+ *
+ * The control automatically:
+ * - Clamps values to the min/max range
+ * - Rounds values to the step precision
+ * - Tracks whether at min/max bounds
+ *
+ * @param initialState - Initial value, bounds, and step configuration
+ * @returns Typography control instance with reactive state and methods
+ *
+ * @example
+ * ```ts
+ * // Font size control: 12-72px in 1px increments
+ * const fontSize = createTypographyControl({
+ * value: 16,
+ * min: 12,
+ * max: 72,
+ * step: 1
+ * });
+ *
+ * // Line height control: 1.0-2.0 in 0.1 increments
+ * const lineHeight = createTypographyControl({
+ * value: 1.5,
+ * min: 1.0,
+ * max: 2.0,
+ * step: 0.1
+ * });
+ *
+ * // Direct assignment (auto-clamped)
+ * fontSize.value = 100; // Becomes 72 (max)
+ * ```
+ */
export function createTypographyControl(
initialState: T,
) {
@@ -49,12 +101,17 @@ export function createTypographyControl(
let min = $state(initialState.min);
let step = $state(initialState.step);
+ // Derived state for boundary detection
const { isAtMax, isAtMin } = $derived({
isAtMax: value >= max,
isAtMin: value <= min,
});
return {
+ /**
+ * Current control value (getter/setter)
+ * Setting automatically clamps to bounds and rounds to step precision
+ */
get value() {
return value;
},
@@ -64,27 +121,45 @@ export function createTypographyControl(
value = rounded;
}
},
+
+ /** Maximum allowed value */
get max() {
return max;
},
+
+ /** Minimum allowed value */
get min() {
return min;
},
+
+ /** Step increment size */
get step() {
return step;
},
+
+ /** Whether the value is at or exceeds the maximum */
get isAtMax() {
return isAtMax;
},
+
+ /** Whether the value is at or below the minimum */
get isAtMin() {
return isAtMin;
},
+
+ /**
+ * Increase value by one step (clamped to max)
+ */
increase() {
value = roundToStepPrecision(
clampNumber(value + step, min, max),
step,
);
},
+
+ /**
+ * Decrease value by one step (clamped to min)
+ */
decrease() {
value = roundToStepPrecision(
clampNumber(value - step, min, max),
@@ -94,4 +169,7 @@ export function createTypographyControl(
};
}
+/**
+ * Type representing a typography control instance
+ */
export type TypographyControl = ReturnType;
diff --git a/src/shared/lib/helpers/createVirtualizer/createVirtualizer.svelte.ts b/src/shared/lib/helpers/createVirtualizer/createVirtualizer.svelte.ts
index 9b8ea6a..7f5c5fa 100644
--- a/src/shared/lib/helpers/createVirtualizer/createVirtualizer.svelte.ts
+++ b/src/shared/lib/helpers/createVirtualizer/createVirtualizer.svelte.ts
@@ -291,7 +291,7 @@ export function createVirtualizer(
},
};
} else {
- containerHeight = node.offsetHeight;
+ containerHeight = node.clientHeight;
const handleScroll = () => {
scrollOffset = node.scrollTop;
diff --git a/src/shared/lib/helpers/createVirtualizer/createVirtualizer.test.ts b/src/shared/lib/helpers/createVirtualizer/createVirtualizer.test.ts
index c2fdaa5..d78b551 100644
--- a/src/shared/lib/helpers/createVirtualizer/createVirtualizer.test.ts
+++ b/src/shared/lib/helpers/createVirtualizer/createVirtualizer.test.ts
@@ -56,6 +56,11 @@ function createMockContainer(height = 500, scrollTop = 0): any {
configurable: true,
writable: true,
});
+ Object.defineProperty(container, 'clientHeight', {
+ value: height,
+ configurable: true,
+ writable: true,
+ });
Object.defineProperty(container, 'scrollTop', {
value: scrollTop,
writable: true,
diff --git a/src/shared/lib/helpers/index.ts b/src/shared/lib/helpers/index.ts
index d37eb5b..fc63b39 100644
--- a/src/shared/lib/helpers/index.ts
+++ b/src/shared/lib/helpers/index.ts
@@ -1,3 +1,27 @@
+/**
+ * Reactive helper factories using Svelte 5 runes
+ *
+ * Provides composable state management patterns for common UI needs:
+ * - Filter management with multi-selection
+ * - Typography controls with bounds and stepping
+ * - Virtual scrolling for large lists
+ * - Debounced state for search inputs
+ * - Entity stores with O(1) lookups
+ * - Character-by-character font comparison
+ * - Persistent localStorage-backed state
+ * - Responsive breakpoint tracking
+ * - 3D perspective animations
+ *
+ * @example
+ * ```ts
+ * import { createFilter, createVirtualizer, createTypographyControl } from '$shared/lib/helpers';
+ *
+ * const filter = createFilter({ properties: [...] });
+ * const virtualizer = createVirtualizer(() => ({ count: 1000, estimateSize: () => 50 }));
+ * const control = createTypographyControl({ value: 16, min: 12, max: 72, step: 1 });
+ * ```
+ */
+
export {
createFilter,
type Filter,