@bquery/bquery 1.5.0 → 1.7.0

package/src/forms/validators.ts

@@ -0,0 +1,265 @@
+/**
+ * Built-in validation functions for form fields.
+ *
+ * Each factory returns a {@link SyncValidator} that can be passed
+ * to a field's `validators` array in {@link FormConfig}.
+ *
+ * @module bquery/forms
+ */
+
+import type { AsyncValidator, SyncValidator } from './types';
+
+/**
+ * Requires a non-empty value.
+ *
+ * Fails for `undefined`, `null`, empty strings (after trim), and empty arrays.
+ *
+ * @param message - Custom error message (default: `'This field is required'`)
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { required } from '@bquery/bquery/forms';
+ * const validate = required('Name is required');
+ * validate('');    // 'Name is required'
+ * validate('Ada'); // true
+ * ```
+ */
+export const required = (message = 'This field is required'): SyncValidator => {
+  return (value: unknown) => {
+    if (value == null) return message;
+    if (typeof value === 'string' && value.trim() === '') return message;
+    if (Array.isArray(value) && value.length === 0) return message;
+    return true;
+  };
+};
+
+/**
+ * Requires a string to have at least `len` characters.
+ *
+ * Non-string values are coerced via `String()` before checking length.
+ *
+ * @param len - Minimum length
+ * @param message - Custom error message
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { minLength } from '@bquery/bquery/forms';
+ * const validate = minLength(3);
+ * validate('ab');  // 'Must be at least 3 characters'
+ * validate('abc'); // true
+ * ```
+ */
+export const minLength = (len: number, message?: string): SyncValidator<unknown> => {
+  const msg = message ?? `Must be at least ${len} characters`;
+  return (value: unknown) => {
+    const str = typeof value === 'string' ? value : String(value ?? '');
+    return str.length >= len ? true : msg;
+  };
+};
+
+/**
+ * Requires a string to have at most `len` characters.
+ *
+ * Non-string values are coerced via `String()` before checking length.
+ *
+ * @param len - Maximum length
+ * @param message - Custom error message
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { maxLength } from '@bquery/bquery/forms';
+ * const validate = maxLength(10);
+ * validate('hello world!!'); // 'Must be at most 10 characters'
+ * validate('hello');         // true
+ * ```
+ */
+export const maxLength = (len: number, message?: string): SyncValidator<unknown> => {
+  const msg = message ?? `Must be at most ${len} characters`;
+  return (value: unknown) => {
+    const str = typeof value === 'string' ? value : String(value ?? '');
+    return str.length <= len ? true : msg;
+  };
+};
+
+/**
+ * Requires a string to match a regular expression pattern.
+ *
+ * Non-string values are coerced via `String()` before testing.
+ *
+ * @param regex - Pattern to test against
+ * @param message - Custom error message (default: `'Invalid format'`)
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { pattern } from '@bquery/bquery/forms';
+ * const validate = pattern(/^\d+$/, 'Numbers only');
+ * validate('abc'); // 'Numbers only'
+ * validate('123'); // true
+ * ```
+ */
+export const pattern = (regex: RegExp, message = 'Invalid format'): SyncValidator<unknown> => {
+  const safeRegex =
+    regex.global || regex.sticky
+      ? new RegExp(regex.source, regex.flags.replace(/[gy]/g, ''))
+      : regex;
+
+  return (value: unknown) => {
+    const str = typeof value === 'string' ? value : String(value ?? '');
+    safeRegex.lastIndex = 0;
+    return safeRegex.test(str) ? true : message;
+  };
+};
+
+/**
+ * RFC 5322–simplified email validation.
+ *
+ * @param message - Custom error message (default: `'Invalid email address'`)
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { email } from '@bquery/bquery/forms';
+ * const validate = email();
+ * validate('nope');          // 'Invalid email address'
+ * validate('ada@lovelace'); // 'Invalid email address'
+ * validate('ada@love.co');  // true
+ * ```
+ */
+export const email = (message = 'Invalid email address'): SyncValidator<unknown> => {
+  // Intentionally simple — covers the vast majority of valid addresses
+  // without re-implementing the full RFC 5322 grammar.
+  const re = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return (value: unknown) => {
+    const str = typeof value === 'string' ? value : String(value ?? '');
+    if (str === '') return true; // empty is handled by `required`
+    return re.test(str) ? true : message;
+  };
+};
+
+/**
+ * Requires a string to be a valid URL.
+ *
+ * Uses the native `URL` constructor for validation.
+ *
+ * @param message - Custom error message (default: `'Invalid URL'`)
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { url } from '@bquery/bquery/forms';
+ * const validate = url();
+ * validate('not-a-url');                // 'Invalid URL'
+ * validate('https://example.com');      // true
+ * ```
+ */
+export const url = (message = 'Invalid URL'): SyncValidator<unknown> => {
+  return (value: unknown) => {
+    const str = typeof value === 'string' ? value : String(value ?? '');
+    if (str === '') return true; // empty is handled by `required`
+    try {
+      new URL(str);
+      return true;
+    } catch {
+      return message;
+    }
+  };
+};
+
+/**
+ * Requires a numeric value to be at least `limit`.
+ *
+ * @param limit - Minimum allowed value (inclusive)
+ * @param message - Custom error message
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { min } from '@bquery/bquery/forms';
+ * const validate = min(1, 'Must be positive');
+ * validate(0); // 'Must be positive'
+ * validate(1); // true
+ * ```
+ */
+export const min = (limit: number, message?: string): SyncValidator<unknown> => {
+  const msg = message ?? `Must be at least ${limit}`;
+  return (value: unknown) => {
+    if (value == null) return true;
+    if (typeof value === 'string' && value.trim() === '') return true;
+    const num = typeof value === 'number' ? value : Number(value);
+    return num >= limit ? true : msg;
+  };
+};
+
+/**
+ * Requires a numeric value to be at most `limit`.
+ *
+ * @param limit - Maximum allowed value (inclusive)
+ * @param message - Custom error message
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { max } from '@bquery/bquery/forms';
+ * const validate = max(100, 'Too high');
+ * validate(101); // 'Too high'
+ * validate(100); // true
+ * ```
+ */
+export const max = (limit: number, message?: string): SyncValidator<unknown> => {
+  const msg = message ?? `Must be at most ${limit}`;
+  return (value: unknown) => {
+    if (value == null) return true;
+    if (typeof value === 'string' && value.trim() === '') return true;
+    const num = typeof value === 'number' ? value : Number(value);
+    return num <= limit ? true : msg;
+  };
+};
+
+/**
+ * Creates a custom synchronous validator from any predicate function.
+ *
+ * @param fn - Predicate that returns `true` when the value is valid
+ * @param message - Error message when the predicate returns `false`
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { custom } from '@bquery/bquery/forms';
+ * const isEven = custom((v: number) => v % 2 === 0, 'Must be even');
+ * isEven(3); // 'Must be even'
+ * isEven(4); // true
+ * ```
+ */
+export const custom = <T = unknown>(
+  fn: (value: T) => boolean,
+  message: string
+): SyncValidator<T> => {
+  return (value: T) => (fn(value) ? true : message);
+};
+
+/**
+ * Creates a custom asynchronous validator.
+ *
+ * @param fn - Async predicate that resolves to `true` when valid
+ * @param message - Error message when the predicate resolves to `false`
+ * @returns An async validator function
+ *
+ * @example
+ * ```ts
+ * import { customAsync } from '@bquery/bquery/forms';
+ * const isUnique = customAsync(
+ *   async (name: string) => !(await checkExists(name)),
+ *   'Already taken',
+ * );
+ * ```
+ */
+export const customAsync = <T = unknown>(
+  fn: (value: T) => Promise<boolean>,
+  message: string
+): AsyncValidator<T> => {
+  return async (value: T) => ((await fn(value)) ? true : message);
+};

package/src/full.ts

@@ -39,6 +39,7 @@
 // Core Module: Selectors, DOM operations, events, utilities
 // ============================================================================
 export { $, $$, BQueryCollection, BQueryElement, utils } from './core/index';
+export type { BQueryUtils } from './core/index';
 
 // ============================================================================
 // Reactive Module: Signals, computed values, effects, batching
@@ -77,12 +78,28 @@ export type {
 // ============================================================================
 // Component Module: Web Components helper with Shadow DOM
 // ============================================================================
-export { component, html, registerDefaultComponents, safeHtml } from './component/index';
+export {
+  bool,
+  component,
+  defineComponent,
+  html,
+  registerDefaultComponents,
+  safeHtml,
+  useComputed,
+  useEffect,
+  useSignal,
+} from './component/index';
 export type {
+  AttributeChange,
   ComponentDefinition,
+  ComponentRenderContext,
+  ComponentStateKey,
+  ComponentSignalLike,
+  ComponentSignals,
   DefaultComponentLibraryOptions,
   PropDefinition,
   RegisteredDefaultComponents,
+  ShadowMode,
 } from './component/index';
 
 // ============================================================================
@@ -105,14 +122,18 @@ export {
   flipList,
   keyframePresets,
   linear,
+  morphElement,
+  parallax,
   prefersReducedMotion,
   scrollAnimate,
   sequence,
+  setReducedMotion,
   spring,
   springPresets,
   stagger,
   timeline,
   transition,
+  typewriter,
 } from './motion/index';
 export type {
   AnimateOptions,
@@ -120,6 +141,9 @@ export type {
   ElementBounds,
   FlipGroupOptions,
   FlipOptions,
+  MorphOptions,
+  ParallaxCleanup,
+  ParallaxOptions,
   ScrollAnimateCleanup,
   ScrollAnimateOptions,
   SequenceOptions,
@@ -132,6 +156,8 @@ export type {
   TimelineControls,
   TimelineStep,
   TransitionOptions,
+  TypewriterControls,
+  TypewriterOptions,
 } from './motion/index';
 
 // ============================================================================
@@ -147,8 +173,9 @@ export {
   sanitize,
   sanitizeHtml,
   stripTags,
+  trusted,
 } from './security/index';
-export type { SanitizeOptions } from './security/index';
+export type { SanitizedHtml, SanitizeOptions, TrustedHtml } from './security/index';
 
 // ============================================================================
 // Platform Module: Storage, buckets, notifications, cache
@@ -183,6 +210,7 @@ export type {
 // ============================================================================
 export {
   back,
+  BqLinkElement,
   createRouter,
   currentRoute,
   forward,
@@ -191,7 +219,9 @@ export {
   isActiveSignal,
   link,
   navigate,
+  registerBqLink,
   resolve,
+  useRoute,
 } from './router/index';
 export type {
   NavigationGuard,
@@ -199,6 +229,7 @@ export type {
   RouteDefinition,
   Router,
   RouterOptions,
+  UseRouteReturn,
 } from './router/index';
 
 // ============================================================================
@@ -214,10 +245,236 @@ export {
   mapState,
   registerPlugin,
 } from './store/index';
-export type { StateFactory, Store, StoreDefinition, StorePlugin } from './store/index';
+export type {
+  ActionContext,
+  OnActionCallback,
+  PersistedStoreOptions,
+  StateFactory,
+  StorageBackend,
+  Store,
+  StoreDefinition,
+  StorePlugin,
+  StoreSerializer,
+} from './store/index';
 
 // ============================================================================
 // View Module: Declarative DOM bindings without compiler
 // ============================================================================
 export { createTemplate, mount } from './view/index';
 export type { BindingContext, MountOptions, View } from './view/index';
+
+// ============================================================================
+// Forms Module: Reactive form handling and validation
+// ============================================================================
+export {
+  createForm,
+  custom,
+  customAsync,
+  email,
+  max,
+  maxLength,
+  min,
+  minLength,
+  pattern,
+  required,
+  url,
+} from './forms/index';
+export type {
+  AsyncValidator,
+  CrossFieldValidator,
+  FieldConfig,
+  Form,
+  FormConfig,
+  FormErrors,
+  FormField,
+  FormFields,
+  SubmitHandler,
+  SyncValidator,
+  ValidationResult,
+  Validator,
+} from './forms/index';
+
+// ============================================================================
+// i18n Module: Internationalization, translations, formatting
+// ============================================================================
+export { createI18n, formatDate, formatNumber } from './i18n/index';
+export type {
+  DateFormatOptions,
+  I18nConfig,
+  I18nInstance,
+  LocaleLoader,
+  LocaleMessages,
+  Messages,
+  NumberFormatOptions,
+  TranslateParams,
+} from './i18n/index';
+
+// ============================================================================
+// a11y Module: Accessibility utilities
+// ============================================================================
+// Note: prefersReducedMotion is not re-exported here to avoid naming conflict
+// with the motion module's prefersReducedMotion(). Use @bquery/bquery/a11y for
+// the reactive signal version.
+export {
+  announceToScreenReader,
+  auditA11y,
+  clearAnnouncements,
+  getFocusableElements,
+  prefersColorScheme,
+  prefersContrast,
+  releaseFocus,
+  rovingTabIndex,
+  skipLink,
+  trapFocus,
+} from './a11y/index';
+export type {
+  AnnouncePriority,
+  AuditFinding,
+  AuditResult,
+  AuditSeverity,
+  ColorScheme,
+  ContrastPreference,
+  FocusTrapHandle,
+  RovingTabIndexHandle,
+  RovingTabIndexOptions,
+  SkipLinkHandle,
+  SkipLinkOptions,
+  TrapFocusOptions,
+} from './a11y/index';
+
+// ============================================================================
+// DnD Module: Drag-and-drop, drop zones, sortable lists
+// ============================================================================
+export { draggable } from './dnd/index';
+export { droppable } from './dnd/index';
+export { sortable } from './dnd/index';
+export type {
+  BoundsRect,
+  DragAxis,
+  DragBounds,
+  DragEventData,
+  DragPosition,
+  DraggableHandle,
+  DraggableOptions,
+  DropEventData,
+  DroppableHandle,
+  DroppableOptions,
+  SortEventData,
+  SortableHandle,
+  SortableOptions,
+} from './dnd/index';
+
+// ============================================================================
+// Media Module: Reactive browser and device API signals
+// ============================================================================
+export { mediaQuery } from './media/index';
+export { breakpoints } from './media/index';
+export { useViewport } from './media/index';
+export { useNetworkStatus } from './media/index';
+export { useBattery } from './media/index';
+export { useGeolocation } from './media/index';
+export { useDeviceMotion, useDeviceOrientation } from './media/index';
+export { clipboard } from './media/index';
+export type {
+  BatteryState,
+  BreakpointMap,
+  ClipboardAPI,
+  DeviceMotionState,
+  DeviceOrientationState,
+  GeolocationOptions,
+  GeolocationState,
+  NetworkState,
+  ViewportState,
+} from './media/index';
+
+// ---------------------------------------------------------------------------
+// Plugin module
+// ---------------------------------------------------------------------------
+export {
+  use,
+  isInstalled,
+  getInstalledPlugins,
+  getCustomDirective,
+  getCustomDirectives,
+  resetPlugins,
+} from './plugin/index';
+export type {
+  BQueryPlugin,
+  CustomDirective,
+  CustomDirectiveHandler,
+  PluginInstallContext,
+} from './plugin/index';
+
+// ---------------------------------------------------------------------------
+// DevTools module
+// ---------------------------------------------------------------------------
+export {
+  enableDevtools,
+  isDevtoolsEnabled,
+  trackSignal,
+  untrackSignal,
+  generateSignalLabel,
+  inspectSignals,
+  inspectStores,
+  inspectComponents,
+  recordEvent,
+  getTimeline,
+  clearTimeline,
+  getDevtoolsState,
+  logSignals,
+  logStores,
+  logComponents,
+  logTimeline,
+} from './devtools/index';
+export type {
+  ComponentSnapshot,
+  DevtoolsOptions,
+  DevtoolsState,
+  SignalSnapshot,
+  StoreSnapshot,
+  TimelineEntry,
+  TimelineEventType,
+} from './devtools/index';
+
+// ---------------------------------------------------------------------------
+// Testing module
+// ---------------------------------------------------------------------------
+export {
+  renderComponent,
+  flushEffects,
+  mockSignal,
+  mockRouter,
+  fireEvent,
+  waitFor,
+} from './testing/index';
+export type {
+  FireEventOptions,
+  MockRouter,
+  MockRouterOptions,
+  MockSignal,
+  RenderComponentOptions,
+  RenderResult,
+  TestRoute,
+  WaitForOptions,
+} from './testing/index';
+
+// ---------------------------------------------------------------------------
+// SSR module
+// ---------------------------------------------------------------------------
+export {
+  renderToString,
+  hydrateMount,
+  serializeStoreState,
+  deserializeStoreState,
+  hydrateStore,
+  hydrateStores,
+} from './ssr/index';
+export type {
+  DeserializedStoreState,
+  HydrateMountOptions,
+  HydrationOptions,
+  RenderOptions,
+  SSRResult,
+  SerializeOptions,
+  SerializeResult,
+} from './ssr/index';

package/src/i18n/formatting.ts

@@ -0,0 +1,67 @@
+/**
+ * Number and date formatting helpers using Intl APIs.
+ * @module bquery/i18n
+ */
+
+import type { DateFormatOptions, NumberFormatOptions } from './types';
+
+/**
+ * Formats a number using the Intl.NumberFormat API.
+ *
+ * @param value - The number to format
+ * @param locale - The locale code (e.g. 'en-US', 'de-DE')
+ * @param options - Intl.NumberFormat options
+ * @returns The formatted number string
+ *
+ * @example
+ * ```ts
+ * formatNumber(1234.56, 'en-US'); // '1,234.56'
+ * formatNumber(1234.56, 'de-DE'); // '1.234,56'
+ * formatNumber(0.42, 'en-US', { style: 'percent' }); // '42%'
+ * formatNumber(9.99, 'en-US', { style: 'currency', currency: 'USD' }); // '$9.99'
+ * ```
+ */
+export const formatNumber = (
+  value: number,
+  locale: string,
+  options?: NumberFormatOptions
+): string => {
+  const { locale: _ignored, ...intlOptions } = options ?? {};
+  try {
+    return new Intl.NumberFormat(locale, intlOptions).format(value);
+  } catch {
+    // Fall back to basic toString on Intl errors
+    return String(value);
+  }
+};
+
+/**
+ * Formats a date using the Intl.DateTimeFormat API.
+ *
+ * @param value - The date to format (Date object or timestamp)
+ * @param locale - The locale code
+ * @param options - Intl.DateTimeFormat options
+ * @returns The formatted date string
+ *
+ * @example
+ * ```ts
+ * const date = new Date('2026-03-26');
+ * formatDate(date, 'en-US'); // '3/26/2026'
+ * formatDate(date, 'de-DE'); // '26.3.2026'
+ * formatDate(date, 'en-US', { dateStyle: 'long' }); // 'March 26, 2026'
+ * ```
+ */
+export const formatDate = (
+  value: Date | number,
+  locale: string,
+  options?: DateFormatOptions
+): string => {
+  const { locale: _ignored, ...intlOptions } = options ?? {};
+  const date = typeof value === 'number' ? new Date(value) : value;
+  try {
+    return new Intl.DateTimeFormat(locale, intlOptions).format(date);
+  } catch {
+    // Fall back to toLocaleString on Intl errors
+    return date.toLocaleString();
+  }
+};