@bquery/bquery 1.4.0 → 1.6.0

package/src/platform/announcer.ts

@@ -0,0 +1,208 @@
+/**
+ * Accessibility live-region announcer helpers.
+ *
+ * @module bquery/platform
+ */
+
+import { effect, signal, type Signal } from '../reactive/signal';
+import { getBqueryConfig } from './config';
+
+/** Options for creating an announcer. */
+export interface UseAnnouncerOptions {
+  /** Live region politeness. */
+  politeness?: 'polite' | 'assertive';
+  /** Whether the live region should be atomic. */
+  atomic?: boolean;
+  /** Delay before applying the message. */
+  delay?: number;
+  /** Delay after which the message is cleared automatically. */
+  clearDelay?: number;
+  /** Optional element id for the live region. */
+  id?: string;
+  /** Optional CSS class name. */
+  className?: string;
+  /** Optional container used to append the live region. */
+  container?: HTMLElement;
+}
+
+/** Runtime options for a single announcement. */
+export interface AnnounceOptions {
+  /** Override politeness for this specific announcement. */
+  politeness?: 'polite' | 'assertive';
+  /** Override the message delay for this specific announcement. */
+  delay?: number;
+  /** Override the auto-clear delay for this specific announcement. */
+  clearDelay?: number;
+}
+
+/** Returned announcer API. */
+export interface AnnouncerHandle {
+  /** The live region element or null outside the DOM. */
+  element: HTMLElement | null;
+  /** Reactive message signal. */
+  message: Signal<string>;
+  /** Announce a message to assistive technologies. */
+  announce: (value: string, options?: AnnounceOptions) => void;
+  /** Clear the current announcement. */
+  clear: () => void;
+  /** Remove the live region if it was created by this announcer. */
+  destroy: () => void;
+}
+
+const visuallyHiddenStyle = [
+  'position:absolute',
+  'width:1px',
+  'height:1px',
+  'padding:0',
+  'margin:-1px',
+  'overflow:hidden',
+  'clip:rect(0, 0, 0, 0)',
+  'white-space:nowrap',
+  'border:0',
+].join(';');
+
+/**
+ * Create or reuse an accessible live region.
+ *
+ * @param options - Live region configuration
+ * @returns An announcer handle with announce(), clear(), and destroy()
+ *
+ * @example
+ * ```ts
+ * const announcer = useAnnouncer();
+ * announcer.announce('Saved successfully');
+ * ```
+ */
+export const useAnnouncer = (options: UseAnnouncerOptions = {}): AnnouncerHandle => {
+  const defaults = getBqueryConfig().announcer;
+  const resolvedOptions: Required<
+    Pick<UseAnnouncerOptions, 'politeness' | 'atomic' | 'delay' | 'clearDelay'>
+  > &
+    UseAnnouncerOptions = {
+    politeness: defaults?.politeness ?? 'polite',
+    atomic: defaults?.atomic ?? true,
+    delay: defaults?.delay ?? 16,
+    clearDelay: defaults?.clearDelay ?? 1000,
+    ...options,
+  };
+
+  const message = signal('');
+
+  if (typeof document === 'undefined') {
+    return {
+      element: null,
+      message,
+      announce(value: string) {
+        message.value = value;
+      },
+      clear() {
+        message.value = '';
+      },
+      destroy() {
+        message.value = '';
+      },
+    };
+  }
+
+  const existing = resolvedOptions.id ? document.getElementById(resolvedOptions.id) : null;
+  const element = (existing ?? document.createElement('div')) as HTMLElement;
+  const created = !existing;
+
+  if (resolvedOptions.id) {
+    element.id = resolvedOptions.id;
+  }
+
+  if (resolvedOptions.className) {
+    element.className = resolvedOptions.className;
+  }
+
+  element.setAttribute('aria-live', resolvedOptions.politeness);
+  element.setAttribute('aria-atomic', String(resolvedOptions.atomic));
+  element.setAttribute('role', resolvedOptions.politeness === 'assertive' ? 'alert' : 'status');
+  element.setAttribute('data-bquery-announcer', 'true');
+  if (!element.getAttribute('style')) {
+    element.setAttribute('style', visuallyHiddenStyle);
+  }
+
+  if (created) {
+    const parent = resolvedOptions.container ?? document.body ?? document.documentElement;
+    if (!parent) {
+      return {
+        element: null,
+        message,
+        announce(value: string) {
+          message.value = value;
+        },
+        clear() {
+          message.value = '';
+        },
+        destroy() {
+          message.value = '';
+        },
+      };
+    }
+    parent.appendChild(element);
+  }
+
+  const disposeMessageEffect = effect(() => {
+    element.textContent = message.value;
+  });
+
+  let messageTimer: ReturnType<typeof setTimeout> | undefined;
+  let clearTimer: ReturnType<typeof setTimeout> | undefined;
+  let destroyed = false;
+
+  const clearTimers = (): void => {
+    if (messageTimer) {
+      clearTimeout(messageTimer);
+      messageTimer = undefined;
+    }
+    if (clearTimer) {
+      clearTimeout(clearTimer);
+      clearTimer = undefined;
+    }
+  };
+
+  const clear = (): void => {
+    if (destroyed) return;
+    clearTimers();
+    message.value = '';
+  };
+
+  const announce = (value: string, announceOptions: AnnounceOptions = {}): void => {
+    if (destroyed) return;
+    const politeness = announceOptions.politeness ?? resolvedOptions.politeness;
+    const delay = announceOptions.delay ?? resolvedOptions.delay;
+    const clearDelay = announceOptions.clearDelay ?? resolvedOptions.clearDelay;
+
+    clearTimers();
+
+    element.setAttribute('aria-live', politeness);
+    element.setAttribute('role', politeness === 'assertive' ? 'alert' : 'status');
+    message.value = '';
+
+    messageTimer = setTimeout(() => {
+      if (destroyed) return;
+      message.value = value;
+      if (clearDelay > 0) {
+        clearTimer = setTimeout(() => {
+          if (destroyed) return;
+          message.value = '';
+        }, clearDelay);
+      }
+    }, delay);
+  };
+
+  const destroy = (): void => {
+    if (destroyed) return;
+    destroyed = true;
+    clearTimers();
+    message.value = '';
+    disposeMessageEffect();
+    if (created) {
+      element.remove();
+    }
+  };
+
+  return { element, message, announce, clear, destroy };
+};

package/src/platform/config.ts

@@ -0,0 +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);
+};

package/src/platform/cookies.ts

@@ -0,0 +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;
+};

package/src/platform/index.ts

@@ -11,8 +11,29 @@ export type { Bucket } from './buckets';
 export { cache } from './cache';
 export type { CacheHandle } from './cache';
 
+export { useCookie } from './cookies';
+export type { UseCookieOptions } from './cookies';
+
+export { defineBqueryConfig, getBqueryConfig } from './config';
+export type {
+  BqueryAnnouncerConfig,
+  BqueryComponentLibraryConfig,
+  BqueryConfig,
+  BqueryCookieConfig,
+  BqueryFetchConfig,
+  BqueryFetchParseAs,
+  BqueryPageMetaConfig,
+  BqueryTransitionConfig,
+} from './config';
+
 export { notifications } from './notifications';
 export type { NotificationOptions } from './notifications';
 
+export { useAnnouncer } from './announcer';
+export type { AnnounceOptions, AnnouncerHandle, UseAnnouncerOptions } from './announcer';
+
+export { definePageMeta } from './meta';
+export type { PageLinkTag, PageMetaCleanup, PageMetaDefinition, PageMetaTag } from './meta';
+
 export { storage } from './storage';
 export type { IndexedDBOptions, StorageAdapter } from './storage';