@bquery/bquery 1.5.0 → 1.6.0

package/src/platform/config.ts

@@ -1,163 +1,163 @@
-/**
- * Global bQuery configuration helpers.
- *
- * @module bquery/platform
- */
-
-import { isPlainObject, merge } from '../core/utils/object';
-
-/** Supported response parsing strategies for fetch composables. */
-export type BqueryFetchParseAs = 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData' | 'response';
-
-/** Global fetch defaults used by useFetch(). */
-export interface BqueryFetchConfig {
-  /** Optional base URL prepended to relative request URLs. */
-  baseUrl?: string;
-  /** Default request headers. */
-  headers?: HeadersInit;
-  /** Default response parser. */
-  parseAs?: BqueryFetchParseAs;
-}
-
-/** Global cookie defaults used by useCookie(). */
-export interface BqueryCookieConfig {
-  /** Default cookie path. */
-  path?: string;
-  /** Default SameSite mode. */
-  sameSite?: 'Strict' | 'Lax' | 'None';
-  /** Whether cookies should be marked secure by default. */
-  secure?: boolean;
-}
-
-/** Global announcer defaults used by useAnnouncer(). */
-export interface BqueryAnnouncerConfig {
-  /** Default politeness level. */
-  politeness?: 'polite' | 'assertive';
-  /** Whether announcements should be treated atomically. */
-  atomic?: boolean;
-  /** Delay before writing the message into the live region. */
-  delay?: number;
-  /** Delay after which the live region is cleared automatically. */
-  clearDelay?: number;
-}
-
-/** Global page meta defaults used by definePageMeta(). */
-export interface BqueryPageMetaConfig {
-  /** Optional title template function. */
-  titleTemplate?: (title: string) => string;
-}
-
-/** Global motion defaults used by transition(). */
-export interface BqueryTransitionConfig {
-  /** Skip transitions when reduced motion is preferred. */
-  skipOnReducedMotion?: boolean;
-  /** Classes applied to the root element during transitions. */
-  classes?: string[];
-  /** Transition type identifiers added when supported by the browser. */
-  types?: string[];
-}
-
-/** Global default component library configuration. */
-export interface BqueryComponentLibraryConfig {
-  /** Prefix used by registerDefaultComponents(). */
-  prefix?: string;
-}
-
-/** Complete global bQuery configuration object. */
-export interface BqueryConfig {
-  /** Fetch composable defaults. */
-  fetch?: BqueryFetchConfig;
-  /** Cookie composable defaults. */
-  cookies?: BqueryCookieConfig;
-  /** Announcer composable defaults. */
-  announcer?: BqueryAnnouncerConfig;
-  /** Page metadata defaults. */
-  pageMeta?: BqueryPageMetaConfig;
-  /** View transition defaults. */
-  transitions?: BqueryTransitionConfig;
-  /** Default component library options. */
-  components?: BqueryComponentLibraryConfig;
-}
-
-const defaultConfig: BqueryConfig = {
-  fetch: {
-    headers: {},
-    parseAs: 'json',
-  },
-  cookies: {
-    path: '/',
-    sameSite: 'Lax',
-    secure: false,
-  },
-  announcer: {
-    politeness: 'polite',
-    atomic: true,
-    delay: 16,
-    clearDelay: 1000,
-  },
-  pageMeta: {},
-  transitions: {
-    skipOnReducedMotion: false,
-    classes: [],
-    types: [],
-  },
-  components: {
-    prefix: 'bq',
-  },
-};
-
-const cloneConfigValue = <T>(value: T): T => {
-  if (typeof Headers !== 'undefined' && value instanceof Headers) {
-    return new Headers(value) as T;
-  }
-
-  if (Array.isArray(value)) {
-    return value.map((entry) => cloneConfigValue(entry)) as T;
-  }
-
-  if (isPlainObject(value)) {
-    const result: Record<string, unknown> = {};
-    for (const [key, entry] of Object.entries(value)) {
-      result[key] = cloneConfigValue(entry);
-    }
-    return result as T;
-  }
-
-  return value;
-};
-
-let currentConfig: BqueryConfig = cloneConfigValue(defaultConfig);
-
-/**
- * Define or extend the global bQuery configuration.
- *
- * @param config - Partial configuration values to merge into the current config
- * @returns The resolved configuration after merging
- *
- * @example
- * ```ts
- * defineBqueryConfig({
- *   fetch: { baseUrl: 'https://api.example.com' },
- *   components: { prefix: 'ui' },
- * });
- * ```
- */
-export const defineBqueryConfig = (config: BqueryConfig): BqueryConfig => {
-  currentConfig = cloneConfigValue(
-    merge(
-      defaultConfig as Record<string, unknown>,
-      currentConfig as Record<string, unknown>,
-      config as Record<string, unknown>
-    ) as BqueryConfig
-  );
-  return getBqueryConfig();
-};
-
-/**
- * Get the currently resolved bQuery configuration.
- *
- * @returns A cloned snapshot of the active configuration
- */
-export const getBqueryConfig = (): BqueryConfig => {
-  return cloneConfigValue(currentConfig);
-};
+/**
+ * Global bQuery configuration helpers.
+ *
+ * @module bquery/platform
+ */
+
+import { isPlainObject, merge } from '../core/utils/object';
+
+/** Supported response parsing strategies for fetch composables. */
+export type BqueryFetchParseAs = 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData' | 'response';
+
+/** Global fetch defaults used by useFetch(). */
+export interface BqueryFetchConfig {
+  /** Optional base URL prepended to relative request URLs. */
+  baseUrl?: string;
+  /** Default request headers. */
+  headers?: HeadersInit;
+  /** Default response parser. */
+  parseAs?: BqueryFetchParseAs;
+}
+
+/** Global cookie defaults used by useCookie(). */
+export interface BqueryCookieConfig {
+  /** Default cookie path. */
+  path?: string;
+  /** Default SameSite mode. */
+  sameSite?: 'Strict' | 'Lax' | 'None';
+  /** Whether cookies should be marked secure by default. */
+  secure?: boolean;
+}
+
+/** Global announcer defaults used by useAnnouncer(). */
+export interface BqueryAnnouncerConfig {
+  /** Default politeness level. */
+  politeness?: 'polite' | 'assertive';
+  /** Whether announcements should be treated atomically. */
+  atomic?: boolean;
+  /** Delay before writing the message into the live region. */
+  delay?: number;
+  /** Delay after which the live region is cleared automatically. */
+  clearDelay?: number;
+}
+
+/** Global page meta defaults used by definePageMeta(). */
+export interface BqueryPageMetaConfig {
+  /** Optional title template function. */
+  titleTemplate?: (title: string) => string;
+}
+
+/** Global motion defaults used by transition(). */
+export interface BqueryTransitionConfig {
+  /** Skip transitions when reduced motion is preferred. */
+  skipOnReducedMotion?: boolean;
+  /** Classes applied to the root element during transitions. */
+  classes?: string[];
+  /** Transition type identifiers added when supported by the browser. */
+  types?: string[];
+}
+
+/** Global default component library configuration. */
+export interface BqueryComponentLibraryConfig {
+  /** Prefix used by registerDefaultComponents(). */
+  prefix?: string;
+}
+
+/** Complete global bQuery configuration object. */
+export interface BqueryConfig {
+  /** Fetch composable defaults. */
+  fetch?: BqueryFetchConfig;
+  /** Cookie composable defaults. */
+  cookies?: BqueryCookieConfig;
+  /** Announcer composable defaults. */
+  announcer?: BqueryAnnouncerConfig;
+  /** Page metadata defaults. */
+  pageMeta?: BqueryPageMetaConfig;
+  /** View transition defaults. */
+  transitions?: BqueryTransitionConfig;
+  /** Default component library options. */
+  components?: BqueryComponentLibraryConfig;
+}
+
+const defaultConfig: BqueryConfig = {
+  fetch: {
+    headers: {},
+    parseAs: 'json',
+  },
+  cookies: {
+    path: '/',
+    sameSite: 'Lax',
+    secure: false,
+  },
+  announcer: {
+    politeness: 'polite',
+    atomic: true,
+    delay: 16,
+    clearDelay: 1000,
+  },
+  pageMeta: {},
+  transitions: {
+    skipOnReducedMotion: false,
+    classes: [],
+    types: [],
+  },
+  components: {
+    prefix: 'bq',
+  },
+};
+
+const cloneConfigValue = <T>(value: T): T => {
+  if (typeof Headers !== 'undefined' && value instanceof Headers) {
+    return new Headers(value) as T;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => cloneConfigValue(entry)) as T;
+  }
+
+  if (isPlainObject(value)) {
+    const result: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(value)) {
+      result[key] = cloneConfigValue(entry);
+    }
+    return result as T;
+  }
+
+  return value;
+};
+
+let currentConfig: BqueryConfig = cloneConfigValue(defaultConfig);
+
+/**
+ * Define or extend the global bQuery configuration.
+ *
+ * @param config - Partial configuration values to merge into the current config
+ * @returns The resolved configuration after merging
+ *
+ * @example
+ * ```ts
+ * defineBqueryConfig({
+ *   fetch: { baseUrl: 'https://api.example.com' },
+ *   components: { prefix: 'ui' },
+ * });
+ * ```
+ */
+export const defineBqueryConfig = (config: BqueryConfig): BqueryConfig => {
+  currentConfig = cloneConfigValue(
+    merge(
+      defaultConfig as Record<string, unknown>,
+      currentConfig as Record<string, unknown>,
+      config as Record<string, unknown>
+    ) as BqueryConfig
+  );
+  return getBqueryConfig();
+};
+
+/**
+ * Get the currently resolved bQuery configuration.
+ *
+ * @returns A cloned snapshot of the active configuration
+ */
+export const getBqueryConfig = (): BqueryConfig => {
+  return cloneConfigValue(currentConfig);
+};

package/src/platform/cookies.ts

@@ -1,165 +1,165 @@
-/**
- * Reactive cookie helpers.
- *
- * @module bquery/platform
- */
-
-import { effect, signal, type Signal } from '../reactive/signal';
-import { getBqueryConfig } from './config';
-
-/** Options for useCookie(). */
-export interface UseCookieOptions<T> {
-  /** Default value when the cookie is not present. */
-  defaultValue?: T;
-  /** Cookie path. Defaults to the global config or `/`. */
-  path?: string;
-  /** Optional cookie domain. */
-  domain?: string;
-  /** Cookie SameSite attribute. */
-  sameSite?: 'Strict' | 'Lax' | 'None';
-  /** Whether the cookie should be marked secure. */
-  secure?: boolean;
-  /** Cookie expiry date. */
-  expires?: Date;
-  /** Cookie max-age in seconds. */
-  maxAge?: number;
-  /** Automatically persist signal updates back to document.cookie. */
-  watch?: boolean;
-  /** Serialize a value before writing it into the cookie. */
-  serialize?: (value: T) => string;
-  /** Deserialize a cookie string into a typed value. */
-  deserialize?: (value: string) => T;
-}
-
-const readCookie = (name: string): string | null => {
-  if (typeof document === 'undefined') return null;
-
-  const prefix = `${encodeURIComponent(name)}=`;
-  const segments = document.cookie ? document.cookie.split(';') : [];
-
-  for (const segment of segments) {
-    const normalizedSegment = segment.trim();
-    if (normalizedSegment.startsWith(prefix)) {
-      const rawValue = normalizedSegment.slice(prefix.length);
-      try {
-        return decodeURIComponent(rawValue);
-      } catch {
-        return rawValue;
-      }
-    }
-  }
-
-  return null;
-};
-
-const requiresJsonParsing = (value: string): boolean => {
-  const normalized = value.trim();
-  return normalized.startsWith('{') || normalized.startsWith('[') || normalized.startsWith('"');
-};
-
-const removeCookie = (
-  name: string,
-  options: Pick<UseCookieOptions<unknown>, 'path' | 'domain' | 'sameSite' | 'secure'>
-): void => {
-  if (typeof document === 'undefined') return;
-
-  const segments = [`${encodeURIComponent(name)}=`, 'Expires=Thu, 01 Jan 1970 00:00:00 GMT'];
-
-  if (options.path) segments.push(`Path=${options.path}`);
-  if (options.domain) segments.push(`Domain=${options.domain}`);
-  if (options.sameSite) segments.push(`SameSite=${options.sameSite}`);
-  if (options.secure) segments.push('Secure');
-
-  document.cookie = segments.join('; ');
-};
-
-const writeCookie = <T>(name: string, value: T, options: UseCookieOptions<T>): void => {
-  if (typeof document === 'undefined') return;
-
-  const serialized = options.serialize
-    ? options.serialize(value)
-    : typeof value === 'string'
-      ? value
-      : JSON.stringify(value);
-
-  const segments = [`${encodeURIComponent(name)}=${encodeURIComponent(serialized)}`];
-
-  if (options.path) segments.push(`Path=${options.path}`);
-  if (options.domain) segments.push(`Domain=${options.domain}`);
-  if (typeof options.maxAge === 'number') segments.push(`Max-Age=${options.maxAge}`);
-  if (options.expires) segments.push(`Expires=${options.expires.toUTCString()}`);
-  if (options.sameSite) segments.push(`SameSite=${options.sameSite}`);
-  if (options.secure) segments.push('Secure');
-
-  document.cookie = segments.join('; ');
-};
-
-/**
- * Create a reactive cookie signal.
- *
- * @template T - Cookie value type
- * @param name - Cookie name
- * @param options - Read/write configuration for the cookie
- * @returns Reactive signal representing the cookie value
- *
- * @example
- * ```ts
- * const theme = useCookie('theme', { defaultValue: 'light' });
- * theme.value = 'dark';
- * ```
- */
-export const useCookie = <T>(name: string, options: UseCookieOptions<T> = {}): Signal<T | null> => {
-  const cookieConfig = getBqueryConfig().cookies;
-  const resolvedOptions: UseCookieOptions<T> = {
-    path: cookieConfig?.path ?? '/',
-    sameSite: cookieConfig?.sameSite ?? 'Lax',
-    secure: cookieConfig?.secure ?? false,
-    watch: true,
-    ...options,
-  };
-
-  if (resolvedOptions.sameSite === 'None') {
-    resolvedOptions.secure = true;
-  }
-
-  const raw = readCookie(name);
-  let initialValue = (resolvedOptions.defaultValue ?? null) as T | null;
-
-  if (raw !== null) {
-    try {
-      initialValue = resolvedOptions.deserialize
-        ? resolvedOptions.deserialize(raw)
-        : requiresJsonParsing(raw)
-          ? (JSON.parse(raw) as T)
-          : ((raw as T) ?? initialValue);
-    } catch (error) {
-      console.warn(`bQuery: Failed to deserialize cookie "${name}", using raw string value`, error);
-      initialValue = (raw as T) ?? initialValue;
-    }
-  }
-
-  const cookie = signal<T | null>(initialValue);
-
-  if (typeof document === 'undefined' || resolvedOptions.watch === false) {
-    return cookie;
-  }
-
-  let initialized = false;
-  effect(() => {
-    const nextValue = cookie.value;
-
-    if (!initialized) {
-      initialized = true;
-      return;
-    }
-
-    if (nextValue == null) {
-      removeCookie(name, resolvedOptions);
-      return;
-    }
-
-    writeCookie(name, nextValue, resolvedOptions);
-  });
-
-  return cookie;
-};
+/**
+ * Reactive cookie helpers.
+ *
+ * @module bquery/platform
+ */
+
+import { effect, signal, type Signal } from '../reactive/signal';
+import { getBqueryConfig } from './config';
+
+/** Options for useCookie(). */
+export interface UseCookieOptions<T> {
+  /** Default value when the cookie is not present. */
+  defaultValue?: T;
+  /** Cookie path. Defaults to the global config or `/`. */
+  path?: string;
+  /** Optional cookie domain. */
+  domain?: string;
+  /** Cookie SameSite attribute. */
+  sameSite?: 'Strict' | 'Lax' | 'None';
+  /** Whether the cookie should be marked secure. */
+  secure?: boolean;
+  /** Cookie expiry date. */
+  expires?: Date;
+  /** Cookie max-age in seconds. */
+  maxAge?: number;
+  /** Automatically persist signal updates back to document.cookie. */
+  watch?: boolean;
+  /** Serialize a value before writing it into the cookie. */
+  serialize?: (value: T) => string;
+  /** Deserialize a cookie string into a typed value. */
+  deserialize?: (value: string) => T;
+}
+
+const readCookie = (name: string): string | null => {
+  if (typeof document === 'undefined') return null;
+
+  const prefix = `${encodeURIComponent(name)}=`;
+  const segments = document.cookie ? document.cookie.split(';') : [];
+
+  for (const segment of segments) {
+    const normalizedSegment = segment.trim();
+    if (normalizedSegment.startsWith(prefix)) {
+      const rawValue = normalizedSegment.slice(prefix.length);
+      try {
+        return decodeURIComponent(rawValue);
+      } catch {
+        return rawValue;
+      }
+    }
+  }
+
+  return null;
+};
+
+const requiresJsonParsing = (value: string): boolean => {
+  const normalized = value.trim();
+  return normalized.startsWith('{') || normalized.startsWith('[') || normalized.startsWith('"');
+};
+
+const removeCookie = (
+  name: string,
+  options: Pick<UseCookieOptions<unknown>, 'path' | 'domain' | 'sameSite' | 'secure'>
+): void => {
+  if (typeof document === 'undefined') return;
+
+  const segments = [`${encodeURIComponent(name)}=`, 'Expires=Thu, 01 Jan 1970 00:00:00 GMT'];
+
+  if (options.path) segments.push(`Path=${options.path}`);
+  if (options.domain) segments.push(`Domain=${options.domain}`);
+  if (options.sameSite) segments.push(`SameSite=${options.sameSite}`);
+  if (options.secure) segments.push('Secure');
+
+  document.cookie = segments.join('; ');
+};
+
+const writeCookie = <T>(name: string, value: T, options: UseCookieOptions<T>): void => {
+  if (typeof document === 'undefined') return;
+
+  const serialized = options.serialize
+    ? options.serialize(value)
+    : typeof value === 'string'
+      ? value
+      : JSON.stringify(value);
+
+  const segments = [`${encodeURIComponent(name)}=${encodeURIComponent(serialized)}`];
+
+  if (options.path) segments.push(`Path=${options.path}`);
+  if (options.domain) segments.push(`Domain=${options.domain}`);
+  if (typeof options.maxAge === 'number') segments.push(`Max-Age=${options.maxAge}`);
+  if (options.expires) segments.push(`Expires=${options.expires.toUTCString()}`);
+  if (options.sameSite) segments.push(`SameSite=${options.sameSite}`);
+  if (options.secure) segments.push('Secure');
+
+  document.cookie = segments.join('; ');
+};
+
+/**
+ * Create a reactive cookie signal.
+ *
+ * @template T - Cookie value type
+ * @param name - Cookie name
+ * @param options - Read/write configuration for the cookie
+ * @returns Reactive signal representing the cookie value
+ *
+ * @example
+ * ```ts
+ * const theme = useCookie('theme', { defaultValue: 'light' });
+ * theme.value = 'dark';
+ * ```
+ */
+export const useCookie = <T>(name: string, options: UseCookieOptions<T> = {}): Signal<T | null> => {
+  const cookieConfig = getBqueryConfig().cookies;
+  const resolvedOptions: UseCookieOptions<T> = {
+    path: cookieConfig?.path ?? '/',
+    sameSite: cookieConfig?.sameSite ?? 'Lax',
+    secure: cookieConfig?.secure ?? false,
+    watch: true,
+    ...options,
+  };
+
+  if (resolvedOptions.sameSite === 'None') {
+    resolvedOptions.secure = true;
+  }
+
+  const raw = readCookie(name);
+  let initialValue = (resolvedOptions.defaultValue ?? null) as T | null;
+
+  if (raw !== null) {
+    try {
+      initialValue = resolvedOptions.deserialize
+        ? resolvedOptions.deserialize(raw)
+        : requiresJsonParsing(raw)
+          ? (JSON.parse(raw) as T)
+          : ((raw as T) ?? initialValue);
+    } catch (error) {
+      console.warn(`bQuery: Failed to deserialize cookie "${name}", using raw string value`, error);
+      initialValue = (raw as T) ?? initialValue;
+    }
+  }
+
+  const cookie = signal<T | null>(initialValue);
+
+  if (typeof document === 'undefined' || resolvedOptions.watch === false) {
+    return cookie;
+  }
+
+  let initialized = false;
+  effect(() => {
+    const nextValue = cookie.value;
+
+    if (!initialized) {
+      initialized = true;
+      return;
+    }
+
+    if (nextValue == null) {
+      removeCookie(name, resolvedOptions);
+      return;
+    }
+
+    writeCookie(name, nextValue, resolvedOptions);
+  });
+
+  return cookie;
+};