@bquery/bquery 1.2.0 → 1.3.0

package/src/core/utils/string.ts

@@ -0,0 +1,112 @@
+/**
+ * String-focused utility helpers.
+ *
+ * @module bquery/core/utils/string
+ */
+
+/**
+ * Capitalizes the first letter of a string.
+ *
+ * @param str - The string to capitalize
+ * @returns The capitalized string
+ *
+ * @example
+ * ```ts
+ * capitalize('hello'); // 'Hello'
+ * ```
+ */
+export function capitalize(str: string): string {
+  if (!str) return str;
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Converts a string to kebab-case.
+ *
+ * @param str - The string to convert
+ * @returns The kebab-cased string
+ *
+ * @example
+ * ```ts
+ * toKebabCase('myVariableName'); // 'my-variable-name'
+ * ```
+ */
+export function toKebabCase(str: string): string {
+  return str
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase();
+}
+
+/**
+ * Converts a string to camelCase.
+ *
+ * @param str - The string to convert
+ * @returns The camelCased string
+ *
+ * @example
+ * ```ts
+ * toCamelCase('my-variable-name'); // 'myVariableName'
+ * ```
+ */
+export function toCamelCase(str: string): string {
+  return str
+    .replace(/[-_\s]+(.)?/g, (_, char) => (char ? char.toUpperCase() : ''))
+    .replace(/^[A-Z]/, (char) => char.toLowerCase());
+}
+
+/**
+ * Truncates a string to a maximum length.
+ *
+ * @param str - The string to truncate
+ * @param maxLength - The maximum length
+ * @param suffix - The suffix to append when truncating (default: '…')
+ * @returns The truncated string
+ *
+ * @example
+ * ```ts
+ * truncate('Hello world', 8); // 'Hello w…'
+ * ```
+ */
+export function truncate(str: string, maxLength: number, suffix = '…'): string {
+  if (maxLength <= 0) return '';
+  if (str.length <= maxLength) return str;
+  const sliceLength = Math.max(0, maxLength - suffix.length);
+  return `${str.slice(0, sliceLength)}${suffix}`;
+}
+
+/**
+ * Converts a string to a URL-friendly slug.
+ *
+ * @param str - The string to slugify
+ * @returns The slugified string
+ *
+ * @example
+ * ```ts
+ * slugify('Hello, World!'); // 'hello-world'
+ * ```
+ */
+export function slugify(str: string): string {
+  return str
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^\w\s-]/g, '')
+    .trim()
+    .replace(/[\s_-]+/g, '-')
+    .toLowerCase();
+}
+
+/**
+ * Escapes a string for safe usage inside a RegExp.
+ *
+ * @param str - The string to escape
+ * @returns The escaped string
+ *
+ * @example
+ * ```ts
+ * escapeRegExp('[a-z]+'); // '\\[a-z\\]+'
+ * ```
+ */
+export function escapeRegExp(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/core/utils/type-guards.ts

@@ -0,0 +1,112 @@
+/**
+ * Type guard helpers.
+ *
+ * @module bquery/core/utils/type-guards
+ */
+
+/**
+ * Checks if a value is a DOM Element.
+ *
+ * @param value - The value to check
+ * @returns True if the value is an Element
+ */
+export function isElement(value: unknown): value is Element {
+  return typeof Element !== 'undefined' && value instanceof Element;
+}
+
+/**
+ * Checks if a value is a BQueryCollection-like object.
+ *
+ * @param value - The value to check
+ * @returns True if the value has an elements array property
+ */
+export function isCollection(value: unknown): value is { elements: Element[] } {
+  return Boolean(value && typeof value === 'object' && 'elements' in (value as object));
+}
+
+/**
+ * Checks if a value is a function.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a function
+ */
+export function isFunction(value: unknown): value is (...args: unknown[]) => unknown {
+  return typeof value === 'function';
+}
+
+/**
+ * Checks if a value is a string.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a string
+ */
+export function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+
+/**
+ * Checks if a value is a number (excluding NaN).
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid number
+ */
+export function isNumber(value: unknown): value is number {
+  return typeof value === 'number' && !Number.isNaN(value);
+}
+
+/**
+ * Checks if a value is a boolean.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a boolean
+ */
+export function isBoolean(value: unknown): value is boolean {
+  return typeof value === 'boolean';
+}
+
+/**
+ * Checks if a value is an array.
+ *
+ * @template T - The type of array elements
+ * @param value - The value to check
+ * @returns True if the value is an array
+ */
+export function isArray<T = unknown>(value: unknown): value is T[] {
+  return Array.isArray(value);
+}
+
+/**
+ * Checks if a value is a Date instance.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a Date
+ */
+export function isDate(value: unknown): value is Date {
+  return value instanceof Date;
+}
+
+/**
+ * Checks if a value is a Promise-like object.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a Promise-like object
+ */
+export function isPromise<T = unknown>(value: unknown): value is Promise<T> {
+  return Boolean(
+    value &&
+    (value instanceof Promise ||
+      (typeof value === 'object' &&
+        'then' in (value as object) &&
+        typeof (value as { then?: unknown }).then === 'function'))
+  );
+}
+
+/**
+ * Checks if a value is a non-null object.
+ *
+ * @param value - The value to check
+ * @returns True if the value is an object
+ */
+export function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}

package/src/full.ts

@@ -1,150 +1,187 @@
-/**
- * bQuery.js — Full Bundle
- *
- * This is the complete bundle containing all modules for CDN usage.
- * Use this when you want all features without tree-shaking concerns.
- *
- * @module bquery/full
- *
- * @example CDN Usage (ES Modules)
- * ```html
- * <script type="module">
- *   import { $, signal, component } from 'https://unpkg.com/bquery@1/dist/full.es.mjs';
- *
- *   const count = signal(0);
- *   $('#counter').text(count.value);
- * </script>
- * ```
- *
- * @example CDN Usage (UMD/Global)
- * ```html
- * <script src="https://unpkg.com/bquery@1/dist/full.umd.js"></script>
- * <script>
- *   const { $, signal } = bQuery;
- *   const count = signal(0);
- * </script>
- * ```
- *
- * @example CDN Usage (IIFE)
- * ```html
- * <script src="https://unpkg.com/bquery@1/dist/full.iife.js"></script>
- * <script>
- *   // bQuery is available as a global variable
- *   const { $, $$ } = bQuery;
- * </script>
- * ```
- */
-
-// ============================================================================
-// Core Module: Selectors, DOM operations, events, utilities
-// ============================================================================
-export { $, $$, BQueryCollection, BQueryElement, utils } from './core/index';
-
-// ============================================================================
-// Reactive Module: Signals, computed values, effects, batching
-// ============================================================================
-export {
-  Computed,
-  Signal,
-  batch,
-  computed,
-  effect,
-  isComputed,
-  isSignal,
-  persistedSignal,
-  readonly,
-  signal,
-  untrack,
-  watch,
-} from './reactive/index';
-export type { CleanupFn, Observer, ReadonlySignal } from './reactive/index';
-
-// ============================================================================
-// Component Module: Web Components helper with Shadow DOM
-// ============================================================================
-export { component, html, safeHtml } from './component/index';
-export type { ComponentDefinition, PropDefinition } from './component/index';
-
-// ============================================================================
-// Motion Module: View transitions, FLIP animations, springs
-// ============================================================================
-export { capturePosition, flip, flipList, spring, springPresets, transition } from './motion/index';
-export type {
-  ElementBounds,
-  FlipOptions,
-  Spring,
-  SpringConfig,
-  TransitionOptions,
-} from './motion/index';
-
-// ============================================================================
-// Security Module: Sanitization, CSP compatibility, Trusted Types
-// ============================================================================
-export {
-  createTrustedHtml,
-  escapeHtml,
-  generateNonce,
-  getTrustedTypesPolicy,
-  hasCSPDirective,
-  isTrustedTypesSupported,
-  sanitize,
-  sanitizeHtml,
-  stripTags,
-} from './security/index';
-export type { SanitizeOptions } from './security/index';
-
-// ============================================================================
-// Platform Module: Storage, buckets, notifications, cache
-// ============================================================================
-export { buckets, cache, notifications, storage } from './platform/index';
-export type {
-  Bucket,
-  CacheHandle,
-  IndexedDBOptions,
-  NotificationOptions,
-  StorageAdapter,
-} from './platform/index';
-
-// ============================================================================
-// Router Module: SPA routing, navigation guards, lazy loading
-// ============================================================================
-export {
-  back,
-  createRouter,
-  currentRoute,
-  forward,
-  interceptLinks,
-  isActive,
-  isActiveSignal,
-  link,
-  navigate,
-  resolve,
-} from './router/index';
-export type {
-  NavigationGuard,
-  Route,
-  RouteDefinition,
-  Router,
-  RouterOptions,
-} from './router/index';
-
-// ============================================================================
-// Store Module: Signal-based state management
-// ============================================================================
-export {
-  createPersistedStore,
-  createStore,
-  destroyStore,
-  getStore,
-  listStores,
-  mapActions,
-  mapState,
-  registerPlugin,
-} from './store/index';
-export type { StateFactory, Store, StoreDefinition, StorePlugin } from './store/index';
-
-// ============================================================================
-// View Module: Declarative DOM bindings without compiler
-// ============================================================================
-export { createTemplate, mount } from './view/index';
-export type { BindingContext, MountOptions, View } from './view/index';
+/**
+ * bQuery.js — Full Bundle
+ *
+ * This is the complete bundle containing all modules for CDN usage.
+ * Use this when you want all features without tree-shaking concerns.
+ *
+ * @module bquery/full
+ *
+ * @example CDN Usage (ES Modules)
+ * ```html
+ * <script type="module">
+ *   import { $, signal, component } from 'https://unpkg.com/bquery@1/dist/full.es.mjs';
+ *
+ *   const count = signal(0);
+ *   $('#counter').text(count.value);
+ * </script>
+ * ```
+ *
+ * @example CDN Usage (UMD/Global)
+ * ```html
+ * <script src="https://unpkg.com/bquery@1/dist/full.umd.js"></script>
+ * <script>
+ *   const { $, signal } = bQuery;
+ *   const count = signal(0);
+ * </script>
+ * ```
+ *
+ * @example CDN Usage (IIFE)
+ * ```html
+ * <script src="https://unpkg.com/bquery@1/dist/full.iife.js"></script>
+ * <script>
+ *   // bQuery is available as a global variable
+ *   const { $, $$ } = bQuery;
+ * </script>
+ * ```
+ */
+
+// ============================================================================
+// Core Module: Selectors, DOM operations, events, utilities
+// ============================================================================
+export { $, $$, BQueryCollection, BQueryElement, utils } from './core/index';
+
+// ============================================================================
+// Reactive Module: Signals, computed values, effects, batching
+// ============================================================================
+export {
+  Computed,
+  Signal,
+  batch,
+  computed,
+  effect,
+  isComputed,
+  isSignal,
+  persistedSignal,
+  readonly,
+  signal,
+  untrack,
+  watch,
+} from './reactive/index';
+export type { CleanupFn, Observer, ReadonlySignal } from './reactive/index';
+
+// ============================================================================
+// Component Module: Web Components helper with Shadow DOM
+// ============================================================================
+export { component, html, safeHtml } from './component/index';
+export type { ComponentDefinition, PropDefinition } from './component/index';
+
+// ============================================================================
+// Motion Module: View transitions, FLIP animations, springs
+// ============================================================================
+export {
+  animate,
+  capturePosition,
+  easeInCubic,
+  easeInOutCubic,
+  easeInOutQuad,
+  easeInQuad,
+  easeOutBack,
+  easeOutCubic,
+  easeOutExpo,
+  easeOutQuad,
+  easingPresets,
+  flip,
+  flipElements,
+  flipList,
+  keyframePresets,
+  linear,
+  prefersReducedMotion,
+  scrollAnimate,
+  sequence,
+  spring,
+  springPresets,
+  stagger,
+  timeline,
+  transition,
+} from './motion/index';
+export type {
+  AnimateOptions,
+  EasingFunction,
+  ElementBounds,
+  FlipGroupOptions,
+  FlipOptions,
+  ScrollAnimateCleanup,
+  ScrollAnimateOptions,
+  SequenceOptions,
+  SequenceStep,
+  Spring,
+  SpringConfig,
+  StaggerFunction,
+  StaggerOptions,
+  TimelineConfig,
+  TimelineControls,
+  TimelineStep,
+  TransitionOptions,
+} from './motion/index';
+
+// ============================================================================
+// Security Module: Sanitization, CSP compatibility, Trusted Types
+// ============================================================================
+export {
+  createTrustedHtml,
+  escapeHtml,
+  generateNonce,
+  getTrustedTypesPolicy,
+  hasCSPDirective,
+  isTrustedTypesSupported,
+  sanitize,
+  sanitizeHtml,
+  stripTags,
+} from './security/index';
+export type { SanitizeOptions } from './security/index';
+
+// ============================================================================
+// Platform Module: Storage, buckets, notifications, cache
+// ============================================================================
+export { buckets, cache, notifications, storage } from './platform/index';
+export type {
+  Bucket,
+  CacheHandle,
+  IndexedDBOptions,
+  NotificationOptions,
+  StorageAdapter,
+} from './platform/index';
+
+// ============================================================================
+// Router Module: SPA routing, navigation guards, lazy loading
+// ============================================================================
+export {
+  back,
+  createRouter,
+  currentRoute,
+  forward,
+  interceptLinks,
+  isActive,
+  isActiveSignal,
+  link,
+  navigate,
+  resolve,
+} from './router/index';
+export type {
+  NavigationGuard,
+  Route,
+  RouteDefinition,
+  Router,
+  RouterOptions,
+} from './router/index';
+
+// ============================================================================
+// Store Module: Signal-based state management
+// ============================================================================
+export {
+  createPersistedStore,
+  createStore,
+  destroyStore,
+  getStore,
+  listStores,
+  mapActions,
+  mapState,
+  registerPlugin,
+} from './store/index';
+export type { StateFactory, Store, StoreDefinition, StorePlugin } from './store/index';
+
+// ============================================================================
+// View Module: Declarative DOM bindings without compiler
+// ============================================================================
+export { createTemplate, mount } from './view/index';
+export type { BindingContext, MountOptions, View } from './view/index';

package/src/index.ts

@@ -1,36 +1,36 @@
-/**
- * bQuery.js — The jQuery for the Modern Web Platform
- *
- * A zero-build, TypeScript-first library that bridges vanilla JavaScript
- * and build-step frameworks with modern features.
- *
- * @module bquery
- * @see https://github.com/bquery/bquery
- */
-
-// Core module: selectors, DOM ops, events, utils
-export * from './core/index';
-
-// Reactive module: signals, computed, effects, binding
-export * from './reactive/index';
-
-// Component module: Web Components helper
-export * from './component/index';
-
-// Motion module: view transitions, FLIP, springs
-export * from './motion/index';
-
-// Security module: sanitizer, CSP, Trusted Types
-export * from './security/index';
-
-// Platform module: storage, buckets, notifications, cache
-export * from './platform/index';
-
-// Router module: SPA routing, navigation guards
-export * from './router/index';
-
-// Store module: state management with signals
-export * from './store/index';
-
-// View module: declarative DOM bindings
-export * from './view/index';
+/**
+ * bQuery.js — The jQuery for the Modern Web Platform
+ *
+ * A zero-build, TypeScript-first library that bridges vanilla JavaScript
+ * and build-step frameworks with modern features.
+ *
+ * @module bquery
+ * @see https://github.com/bquery/bquery
+ */
+
+// Core module: selectors, DOM ops, events, utils
+export * from './core/index';
+
+// Reactive module: signals, computed, effects, binding
+export * from './reactive/index';
+
+// Component module: Web Components helper
+export * from './component/index';
+
+// Motion module: view transitions, FLIP, springs
+export * from './motion/index';
+
+// Security module: sanitizer, CSP, Trusted Types
+export * from './security/index';
+
+// Platform module: storage, buckets, notifications, cache
+export * from './platform/index';
+
+// Router module: SPA routing, navigation guards
+export * from './router/index';
+
+// Store module: state management with signals
+export * from './store/index';
+
+// View module: declarative DOM bindings
+export * from './view/index';