@bquery/bquery 1.4.0 → 1.5.0

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

@@ -1,18 +1,39 @@
-/**
- * Platform module providing unified endpoints for web platform APIs.
- * Offers consistent, promise-based interfaces with predictable errors.
- *
- * @module bquery/platform
- */
-
-export { buckets } from './buckets';
-export type { Bucket } from './buckets';
-
-export { cache } from './cache';
-export type { CacheHandle } from './cache';
-
-export { notifications } from './notifications';
-export type { NotificationOptions } from './notifications';
-
-export { storage } from './storage';
-export type { IndexedDBOptions, StorageAdapter } from './storage';
+/**
+ * Platform module providing unified endpoints for web platform APIs.
+ * Offers consistent, promise-based interfaces with predictable errors.
+ *
+ * @module bquery/platform
+ */
+
+export { buckets } from './buckets';
+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';

package/src/platform/meta.ts

@@ -0,0 +1,168 @@
+/**
+ * Document title and meta helpers.
+ *
+ * @module bquery/platform
+ */
+
+import { getBqueryConfig } from './config';
+
+/** Meta tag definition. */
+export interface PageMetaTag {
+  /** Standard meta name attribute. */
+  name?: string;
+  /** Open Graph / custom property attribute. */
+  property?: string;
+  /** http-equiv attribute. */
+  httpEquiv?: string;
+  /** Meta tag content. */
+  content: string;
+}
+
+/** Link tag definition. */
+export interface PageLinkTag {
+  /** Link relation. */
+  rel: string;
+  /** Link URL. */
+  href: string;
+  /** Optional type attribute. */
+  type?: string;
+  /** Optional media query. */
+  media?: string;
+  /** Optional crossOrigin attribute. */
+  crossOrigin?: 'anonymous' | 'use-credentials';
+}
+
+/** Page metadata definition. */
+export interface PageMetaDefinition {
+  /** Document title. */
+  title?: string;
+  /** Convenience shortcut for the description meta tag. */
+  description?: string;
+  /** Additional meta tags. */
+  meta?: PageMetaTag[];
+  /** Additional link tags. */
+  link?: PageLinkTag[];
+  /** Attributes applied to the html element. */
+  htmlAttributes?: Record<string, string>;
+  /** Attributes applied to the body element. */
+  bodyAttributes?: Record<string, string>;
+}
+
+/** Cleanup function returned by definePageMeta(). */
+export type PageMetaCleanup = () => void;
+
+const setAttributes = (target: HTMLElement, attributes: Record<string, string>): (() => void) => {
+  const previousValues = new Map<string, string | null>();
+
+  for (const [name, value] of Object.entries(attributes)) {
+    previousValues.set(name, target.getAttribute(name));
+    target.setAttribute(name, value);
+  }
+
+  return () => {
+    for (const [name, value] of previousValues.entries()) {
+      if (value == null) {
+        target.removeAttribute(name);
+      } else {
+        target.setAttribute(name, value);
+      }
+    }
+  };
+};
+
+const createElement = <T extends 'meta' | 'link'>(
+  tagName: T,
+  attributes: Record<string, string | undefined>
+): HTMLElementTagNameMap[T] => {
+  const element = document.createElement(tagName);
+  element.setAttribute('data-bquery-page-meta', 'true');
+
+  for (const [name, value] of Object.entries(attributes)) {
+    if (value !== undefined) {
+      element.setAttribute(name, value);
+    }
+  }
+
+  return element;
+};
+
+/**
+ * Apply document metadata for the current page.
+ *
+ * @param definition - Title, meta tags, link tags, and document attributes
+ * @returns Cleanup function that restores the previous document state
+ *
+ * @example
+ * ```ts
+ * const cleanup = definePageMeta({
+ *   title: 'Dashboard',
+ *   description: 'Overview of your account',
+ * });
+ * ```
+ */
+export const definePageMeta = (definition: PageMetaDefinition): PageMetaCleanup => {
+  if (typeof document === 'undefined') {
+    return () => {};
+  }
+
+  const config = getBqueryConfig().pageMeta;
+  const title = definition.title
+    ? config?.titleTemplate
+      ? config.titleTemplate(definition.title)
+      : definition.title
+    : undefined;
+
+  const inserted: HTMLElement[] = [];
+  const restoreFns: Array<() => void> = [];
+  const previousTitle = document.title;
+
+  if (title !== undefined) {
+    document.title = title;
+  }
+
+  const metaEntries = [...(definition.meta ?? [])];
+  if (definition.description) {
+    metaEntries.unshift({ name: 'description', content: definition.description });
+  }
+
+  for (const entry of metaEntries) {
+    const meta = createElement('meta', {
+      name: entry.name,
+      property: entry.property,
+      'http-equiv': entry.httpEquiv,
+      content: entry.content,
+    });
+    document.head.appendChild(meta);
+    inserted.push(meta);
+  }
+
+  for (const entry of definition.link ?? []) {
+    const link = createElement('link', {
+      rel: entry.rel,
+      href: entry.href,
+      type: entry.type,
+      media: entry.media,
+      crossorigin: entry.crossOrigin,
+    });
+    document.head.appendChild(link);
+    inserted.push(link);
+  }
+
+  if (definition.htmlAttributes) {
+    restoreFns.push(setAttributes(document.documentElement, definition.htmlAttributes));
+  }
+
+  if (definition.bodyAttributes && document.body) {
+    restoreFns.push(setAttributes(document.body, definition.bodyAttributes));
+  }
+
+  return () => {
+    document.title = previousTitle;
+    for (const restore of restoreFns.reverse()) {
+      restore();
+    }
+    for (const element of inserted) {
+      element.remove();
+    }
+  };
+};