bitwrench 2.0.23 → 2.0.25

package/src/bitwrench.d.ts

@@ -0,0 +1,659 @@
+// bitwrench TypeScript type definitions
+// https://github.com/deftio/bitwrench
+
+// ---------------------------------------------------------------------------
+// TACO format types
+// ---------------------------------------------------------------------------
+
+/** Raw HTML marker returned by bw.raw() */
+export interface BwRaw {
+  __bw_raw: true;
+  v: string;
+}
+
+/** TACO content: text, nested TACO, array of mixed, raw HTML, or null */
+export type TacoContent =
+  | string
+  | number
+  | Taco
+  | TacoContent[]
+  | BwRaw
+  | null
+  | undefined;
+
+/** TACO attributes object */
+export interface TacoAttributes {
+  id?: string;
+  class?: string | string[];
+  style?: string | Record<string, string | number>;
+  disabled?: boolean;
+  readonly?: boolean;
+  checked?: boolean;
+  selected?: boolean;
+  value?: string | number;
+  type?: string;
+  href?: string;
+  src?: string;
+  alt?: string;
+  title?: string;
+  name?: string;
+  placeholder?: string;
+  for?: string;
+  target?: string;
+  rel?: string;
+  role?: string;
+  tabindex?: number | string;
+  /** Event handlers: function or string */
+  onclick?: ((e: Event) => void) | string;
+  onchange?: ((e: Event) => void) | string;
+  oninput?: ((e: Event) => void) | string;
+  onsubmit?: ((e: Event) => void) | string;
+  onkeydown?: ((e: Event) => void) | string;
+  onkeyup?: ((e: Event) => void) | string;
+  onmouseover?: ((e: Event) => void) | string;
+  onmouseout?: ((e: Event) => void) | string;
+  onfocus?: ((e: Event) => void) | string;
+  onblur?: ((e: Event) => void) | string;
+  /** Any other HTML attribute */
+  [key: string]: any;
+}
+
+/** TACO options object -- lifecycle, state, component handles */
+export interface TacoOptions {
+  /** Component state, stored on el._bw_state */
+  state?: Record<string, any>;
+  /** Called after element created and in DOM */
+  mounted?: (el: HTMLElement, state?: Record<string, any>) => void;
+  /** Called on bw.cleanup() */
+  unmount?: (el: HTMLElement, state?: Record<string, any>) => void;
+  /** Called by bw.update(); stored on el._bw_render */
+  render?: (el: HTMLElement, state?: Record<string, any>) => void;
+  /** Methods attached to el.bw namespace */
+  handle?: Record<string, (el: HTMLElement, ...args: any[]) => any>;
+  /** Slot selectors: auto-generates el.bw.setName()/getName() */
+  slots?: Record<string, string>;
+  /** Component type identifier (used internally by BCCL) */
+  type?: string;
+}
+
+/**
+ * TACO object -- Tag, Attributes, Content, Options.
+ * The core UI primitive in bitwrench.
+ */
+export interface Taco {
+  /** HTML tag name */
+  t: string;
+  /** HTML attributes, event handlers, classes, styles */
+  a?: TacoAttributes;
+  /** Content: text, nested TACO, array, raw HTML */
+  c?: TacoContent;
+  /** Options: lifecycle hooks, state, component handles */
+  o?: TacoOptions;
+}
+
+// ---------------------------------------------------------------------------
+// Styles / theming types
+// ---------------------------------------------------------------------------
+
+/** Color shade object generated by bw.deriveShades() */
+export interface ColorShades {
+  base: string;
+  hover: string;
+  active: string;
+  light: string;
+  darkText: string;
+  border: string;
+  focus: string;
+  textOn: string;
+}
+
+/** Full palette generated by bw.derivePalette() or bw.makeStyles() */
+export interface Palette {
+  primary: ColorShades;
+  secondary: ColorShades;
+  tertiary: ColorShades;
+  success: ColorShades;
+  danger: ColorShades;
+  warning: ColorShades;
+  info: ColorShades;
+  light: ColorShades;
+  dark: ColorShades;
+  /** Plain string, not a ColorShades object */
+  background: string;
+  /** Plain string, not a ColorShades object */
+  surface: string;
+  /** Plain string, not a ColorShades object */
+  surfaceAlt: string;
+}
+
+/** Seed color config for bw.makeStyles() and bw.loadStyles() */
+export interface StyleConfig {
+  primary?: string;
+  secondary?: string;
+  tertiary?: string;
+  success?: string;
+  danger?: string;
+  warning?: string;
+  info?: string;
+  light?: string;
+  dark?: string;
+  background?: string;
+  surface?: string;
+  surfaceAlt?: string;
+  palette?: Partial<Palette>;
+  spacing?: string;
+  radius?: string;
+  typeRatio?: string;
+  elevation?: string;
+  motion?: string;
+  compact?: boolean;
+}
+
+/** Result of bw.makeStyles() */
+export interface StylesResult {
+  css: string;
+  alternateCss: string;
+  palette: Palette;
+  alternatePalette: Palette;
+  rules: Record<string, any>;
+  alternateRules: Record<string, any>;
+  isLightPrimary: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Component config types (BCCL make*() factories)
+// ---------------------------------------------------------------------------
+
+export type Variant =
+  | 'primary' | 'secondary' | 'tertiary'
+  | 'success' | 'danger' | 'warning' | 'info'
+  | 'light' | 'dark';
+
+export interface CardConfig {
+  title?: string | Taco;
+  content?: string | Taco | TacoContent[];
+  footer?: string | Taco;
+  image?: string;
+  variant?: Variant;
+  shadow?: boolean | string;
+  clickable?: boolean;
+  style?: Record<string, string | number>;
+  class?: string;
+}
+
+export interface ButtonConfig {
+  text?: string | Taco;
+  variant?: Variant;
+  size?: 'sm' | 'md' | 'lg';
+  outline?: boolean;
+  disabled?: boolean;
+  block?: boolean;
+  onclick?: (e: Event) => void;
+  type?: string;
+  style?: Record<string, string | number>;
+  class?: string;
+}
+
+export interface NavConfig {
+  items: Array<{ text: string; href?: string; active?: boolean; onclick?: (e: Event) => void }>;
+  variant?: Variant;
+  vertical?: boolean;
+  style?: Record<string, string | number>;
+  class?: string;
+}
+
+export interface TabsConfig {
+  tabs: Array<{ text: string; content: TacoContent; active?: boolean }>;
+  variant?: Variant;
+  style?: Record<string, string | number>;
+  class?: string;
+}
+
+export interface AccordionConfig {
+  items: Array<{ title: string; content: TacoContent }>;
+  multiple?: boolean;
+  variant?: Variant;
+  style?: Record<string, string | number>;
+  class?: string;
+}
+
+export interface ModalConfig {
+  title?: string | Taco;
+  content?: TacoContent;
+  footer?: TacoContent;
+  size?: 'sm' | 'md' | 'lg';
+  closable?: boolean;
+  variant?: Variant;
+  style?: Record<string, string | number>;
+  class?: string;
+}
+
+export interface AlertConfig {
+  content?: string | Taco;
+  variant?: Variant;
+  dismissible?: boolean;
+  style?: Record<string, string | number>;
+  class?: string;
+}
+
+export interface TableConfig {
+  columns?: Array<string | { key: string; label?: string; sortable?: boolean }>;
+  rows?: Array<Record<string, any>>;
+  data?: Array<Record<string, any>>;
+  sortable?: boolean;
+  striped?: boolean;
+  bordered?: boolean;
+  hover?: boolean;
+  style?: Record<string, string | number>;
+  class?: string;
+}
+
+export interface InputConfig {
+  type?: string;
+  label?: string;
+  placeholder?: string;
+  value?: string | number;
+  name?: string;
+  disabled?: boolean;
+  required?: boolean;
+  onchange?: (e: Event) => void;
+  oninput?: (e: Event) => void;
+  style?: Record<string, string | number>;
+  class?: string;
+}
+
+export interface CarouselConfig {
+  items: TacoContent[];
+  autoPlay?: boolean;
+  interval?: number;
+  indicators?: boolean;
+  controls?: boolean;
+  style?: Record<string, string | number>;
+  class?: string;
+}
+
+/** Generic config for BCCL components not individually typed */
+export interface ComponentConfig {
+  [key: string]: any;
+}
+
+// ---------------------------------------------------------------------------
+// Router types
+// ---------------------------------------------------------------------------
+
+export interface RouterConfig {
+  routes: Record<string, (params: Record<string, string>) => Taco>;
+  mode?: 'hash' | 'history';
+  base?: string;
+  target?: string;
+  before?: (path: string) => boolean | void;
+  after?: (path: string) => void;
+}
+
+export interface RouterHandle {
+  navigate: (path: string, opts?: { replace?: boolean }) => void;
+  current: () => string;
+  destroy: () => void;
+}
+
+// ---------------------------------------------------------------------------
+// Main bw namespace
+// ---------------------------------------------------------------------------
+
+export interface Bitwrench {
+  // -- Version & Environment ------------------------------------------------
+  version: string;
+  versionInfo: { version: string; name: string; buildDate: string; gitHash: string };
+  readonly _isBrowser: boolean;
+  _isNode: boolean;
+  debug: boolean;
+
+  // -- TACO Construction & Rendering ----------------------------------------
+  /** Create TACO from positional args */
+  h(tag: string, attrs?: TacoAttributes | null, content?: TacoContent, options?: TacoOptions): Taco;
+  /** Render TACO to HTML string */
+  html(taco: Taco | TacoContent, options?: { raw?: boolean; state?: Record<string, any> }): string;
+  /** Generate complete HTML page string */
+  htmlPage(opts: { title?: string; css?: string; content?: TacoContent; favicon?: string; [key: string]: any }): string;
+  /** Create DOM element from TACO (browser only) */
+  createDOM(taco: Taco | TacoContent, options?: Record<string, any>): HTMLElement | DocumentFragment;
+  /** Mount TACO into target, replacing contents */
+  DOM(target: string | HTMLElement, taco: Taco | TacoContent, options?: Record<string, any>): void;
+  /** Mount TACO and return root element (for el.bw access) */
+  mount(target: string | HTMLElement, taco: Taco | TacoContent, options?: Record<string, any>): HTMLElement;
+  /** Mark string as pre-escaped HTML */
+  raw(str: string): BwRaw;
+  /** Escape HTML special characters */
+  escapeHTML(str: string): string;
+
+  // -- Lifecycle & State ----------------------------------------------------
+  /** Call el._bw_render to re-render element */
+  update(target: string | HTMLElement): void;
+  /** Quick-patch element content or attribute */
+  patch(id: string | HTMLElement, content?: TacoContent, attr?: string): HTMLElement | null;
+  /** Batch patch multiple elements */
+  patchAll(patches: Record<string, TacoContent> | Array<{ id: string; content?: TacoContent; attr?: string }>): Record<string, HTMLElement>;
+  /** Clean up lifecycle hooks, subscriptions, cache */
+  cleanup(element: HTMLElement): void;
+
+  // -- DOM Selection --------------------------------------------------------
+  /** CSS selector to array of elements */
+  $(selector: string | HTMLElement | HTMLElement[]): HTMLElement[];
+  /** Dispatch DOM event */
+  emit(target: string | HTMLElement, eventName: string, detail?: any): void;
+  /** Add event listener */
+  on(target: string | HTMLElement, eventName: string, handler: (e: Event) => void): void;
+
+  // -- Pub/Sub --------------------------------------------------------------
+  /** Publish to topic */
+  pub(topic: string, detail?: any): number;
+  /** Subscribe to topic; returns unsub() */
+  sub(topic: string, handler: (detail: any) => void, el?: HTMLElement): () => void;
+  /** Unsubscribe handler from topic */
+  unsub(topic: string, handler: Function): number;
+
+  // -- UUID & Identity ------------------------------------------------------
+  /** Generate unique ID */
+  uuid(prefix?: string): string;
+  /** Assign UUID class to TACO */
+  assignUUID(taco: Taco, forceNew?: boolean): string | null;
+  /** Read UUID from TACO or DOM element */
+  getUUID(tacoOrElement: Taco | HTMLElement): string | null;
+
+  // -- Component Messages ---------------------------------------------------
+  /** Call method on el.bw: el.bw[action](data) */
+  message(target: string | HTMLElement, action: string, data?: any): any;
+  /** Execute wire-protocol message object */
+  apply(msg: Record<string, any>): any;
+  /** Inspect element properties */
+  inspect(target: string | HTMLElement): Record<string, any>;
+
+  // -- Function Registry ----------------------------------------------------
+  funcRegister(fn: Function, name?: string): string;
+  funcGetById(name: string, errFn?: Function): Function | null;
+  funcGetDispatchStr(name: string, argStr?: string): string;
+  funcUnregister(name: string): void;
+  funcGetRegistry(): Record<string, Function>;
+
+  // -- Component Registry ---------------------------------------------------
+  render(element: HTMLElement, position: string, taco: Taco): string;
+  getComponent(id: string): Record<string, any> | null;
+  getAllComponents(): Map<string, any>;
+
+  // -- CSS & Styles ---------------------------------------------------------
+  /** Generate CSS string from JS object */
+  css(rules: Record<string, any>, options?: { scopeSelector?: string; selector?: string }): string;
+  /** Inject CSS into document */
+  injectCSS(css: string, options?: { id?: string; append?: boolean; scope?: string }): HTMLElement;
+  /** Responsive media query helper */
+  responsive(selector: string, breakpoints: Record<string, Record<string, any>>): string;
+  /** Generate styles from config */
+  makeStyles(config: StyleConfig): StylesResult;
+  /** Inject generated styles */
+  applyStyles(styles: StylesResult, scope?: string): void;
+  /** Generate + apply (no args = structural CSS only) */
+  loadStyles(config?: StyleConfig, scope?: string): StylesResult | void;
+  /** Load CSS reset */
+  loadReset(): void;
+  /** Switch primary/alternate palette */
+  toggleStyles(scope?: string): void;
+  /** Remove injected styles */
+  clearStyles(scope?: string): void;
+  /** Generate type scale from base + ratio */
+  generateTypeScale(baseSize: number, ratio: number, steps: number): Record<string, any>;
+
+  // -- Color Utilities ------------------------------------------------------
+  hexToHsl(hex: string): [number, number, number];
+  hslToHex(hsl: [number, number, number]): string;
+  adjustLightness(hex: string, amount: number): string;
+  mixColor(hex1: string, hex2: string, ratio: number): string;
+  relativeLuminance(hex: string): number;
+  textOnColor(hex: string): string;
+  deriveShades(hex: string): ColorShades;
+  derivePalette(config: StyleConfig): Palette;
+  harmonize(sourceHex: string, targetHex: string, amount: number): string;
+  deriveAlternateSeed(hex: string): string;
+  deriveAlternateConfig(config: StyleConfig): StyleConfig;
+  isLightPalette(config: StyleConfig): boolean;
+  colorParse(str: string, defAlpha?: number): [number, number, number, number, string];
+  colorRgbToHsl(r: number, g: number, b: number, a?: number, rnd?: boolean): [number, number, number, number];
+  colorHslToRgb(h: number, s: number, l: number, a?: number, rnd?: boolean): [number, number, number, number];
+  colorInterp(x: number, in0: number, in1: number, colors: string[], stretch?: boolean): string;
+
+  // -- Router ---------------------------------------------------------------
+  router(config: RouterConfig): RouterHandle;
+  navigate(path: string, opts?: { replace?: boolean }): void;
+  link(path: string, content: TacoContent, attrs?: TacoAttributes): Taco;
+
+  // -- BCCL Component Factories (all return Taco) ---------------------------
+  make(type: string, props?: ComponentConfig): Taco;
+  makeCard(config?: CardConfig | string): Taco;
+  makeButton(config?: ButtonConfig | string): Taco;
+  makeContainer(config?: ComponentConfig): Taco;
+  makeRow(config?: ComponentConfig): Taco;
+  makeCol(config?: ComponentConfig): Taco;
+  makeStack(config?: ComponentConfig): Taco;
+  makeSection(config?: ComponentConfig): Taco;
+  makeNav(config?: NavConfig): Taco;
+  makeNavbar(config?: ComponentConfig): Taco;
+  makeBreadcrumb(config?: ComponentConfig): Taco;
+  makeTabs(config?: TabsConfig): Taco;
+  makePagination(config?: ComponentConfig): Taco;
+  makeAlert(config?: AlertConfig | string): Taco;
+  makeBadge(config?: ComponentConfig | string): Taco;
+  makeProgress(config?: ComponentConfig): Taco;
+  makeSpinner(config?: ComponentConfig): Taco;
+  makeToast(config?: ComponentConfig): Taco;
+  makeTooltip(config?: ComponentConfig): Taco;
+  makePopover(config?: ComponentConfig): Taco;
+  makeListGroup(config?: ComponentConfig): Taco;
+  makeAccordion(config?: AccordionConfig): Taco;
+  makeCarousel(config?: CarouselConfig): Taco;
+  makeTimeline(config?: ComponentConfig): Taco;
+  makeStepper(config?: ComponentConfig): Taco;
+  makeChipInput(config?: ComponentConfig): Taco;
+  makeModal(config?: ModalConfig): Taco;
+  makeDropdown(config?: ComponentConfig): Taco;
+  makeForm(config?: ComponentConfig): Taco;
+  makeFormGroup(config?: ComponentConfig): Taco;
+  makeInput(config?: InputConfig): Taco;
+  makeTextarea(config?: ComponentConfig): Taco;
+  makeSelect(config?: ComponentConfig): Taco;
+  makeCheckbox(config?: ComponentConfig): Taco;
+  makeRadio(config?: ComponentConfig): Taco;
+  makeSwitch(config?: ComponentConfig): Taco;
+  makeRange(config?: ComponentConfig): Taco;
+  makeFileUpload(config?: ComponentConfig): Taco;
+  makeSearchInput(config?: ComponentConfig): Taco;
+  makeButtonGroup(config?: ComponentConfig): Taco;
+  makeHero(config?: ComponentConfig): Taco;
+  makeFeatureGrid(config?: ComponentConfig): Taco;
+  makeCTA(config?: ComponentConfig): Taco;
+  makeCodeDemo(config?: ComponentConfig): Taco;
+  makeSkeleton(config?: ComponentConfig): Taco;
+  makeAvatar(config?: ComponentConfig): Taco;
+  makeStatCard(config?: ComponentConfig): Taco;
+  makeMediaObject(config?: ComponentConfig): Taco;
+  makeTable(config?: TableConfig): Taco;
+  makeTableFromArray(config?: TableConfig): Taco;
+  makeDataTable(config?: TableConfig): Taco;
+  makeBarChart(config?: ComponentConfig): Taco;
+
+  // -- Corresponding create* (return DOM Element) ---------------------------
+  createCard(config?: CardConfig | string): HTMLElement;
+  createButton(config?: ButtonConfig | string): HTMLElement;
+  createContainer(config?: ComponentConfig): HTMLElement;
+  createRow(config?: ComponentConfig): HTMLElement;
+  createCol(config?: ComponentConfig): HTMLElement;
+  createStack(config?: ComponentConfig): HTMLElement;
+  createSection(config?: ComponentConfig): HTMLElement;
+  createNav(config?: NavConfig): HTMLElement;
+  createNavbar(config?: ComponentConfig): HTMLElement;
+  createBreadcrumb(config?: ComponentConfig): HTMLElement;
+  createTabs(config?: TabsConfig): HTMLElement;
+  createPagination(config?: ComponentConfig): HTMLElement;
+  createAlert(config?: AlertConfig | string): HTMLElement;
+  createBadge(config?: ComponentConfig | string): HTMLElement;
+  createProgress(config?: ComponentConfig): HTMLElement;
+  createSpinner(config?: ComponentConfig): HTMLElement;
+  createToast(config?: ComponentConfig): HTMLElement;
+  createTooltip(config?: ComponentConfig): HTMLElement;
+  createPopover(config?: ComponentConfig): HTMLElement;
+  createListGroup(config?: ComponentConfig): HTMLElement;
+  createAccordion(config?: AccordionConfig): HTMLElement;
+  createCarousel(config?: CarouselConfig): HTMLElement;
+  createTimeline(config?: ComponentConfig): HTMLElement;
+  createStepper(config?: ComponentConfig): HTMLElement;
+  createChipInput(config?: ComponentConfig): HTMLElement;
+  createModal(config?: ModalConfig): HTMLElement;
+  createDropdown(config?: ComponentConfig): HTMLElement;
+  createForm(config?: ComponentConfig): HTMLElement;
+  createFormGroup(config?: ComponentConfig): HTMLElement;
+  createInput(config?: InputConfig): HTMLElement;
+  createTextarea(config?: ComponentConfig): HTMLElement;
+  createSelect(config?: ComponentConfig): HTMLElement;
+  createCheckbox(config?: ComponentConfig): HTMLElement;
+  createRadio(config?: ComponentConfig): HTMLElement;
+  createSwitch(config?: ComponentConfig): HTMLElement;
+  createRange(config?: ComponentConfig): HTMLElement;
+  createFileUpload(config?: ComponentConfig): HTMLElement;
+  createSearchInput(config?: ComponentConfig): HTMLElement;
+  createButtonGroup(config?: ComponentConfig): HTMLElement;
+  createHero(config?: ComponentConfig): HTMLElement;
+  createFeatureGrid(config?: ComponentConfig): HTMLElement;
+  createCTA(config?: ComponentConfig): HTMLElement;
+  createCodeDemo(config?: ComponentConfig): HTMLElement;
+  createSkeleton(config?: ComponentConfig): HTMLElement;
+  createAvatar(config?: ComponentConfig): HTMLElement;
+  createStatCard(config?: ComponentConfig): HTMLElement;
+  createMediaObject(config?: ComponentConfig): HTMLElement;
+  createTable(config?: TableConfig): HTMLElement;
+
+  // -- Array Utilities ------------------------------------------------------
+  arrayUniq(arr: any[]): any[];
+  arrayBinA(a: any[], b: any[]): any[];
+  arrayBNotInA(a: any[], b: any[]): any[];
+  multiArray(value: any, dims: number[]): any[];
+
+  // -- Math -----------------------------------------------------------------
+  mapScale(x: number, in0: number, in1: number, out0: number, out1: number, options?: { clamp?: boolean; invert?: boolean; curve?: string }): number;
+  clip(value: number, min: number, max: number): number;
+
+  // -- Text & Selection -----------------------------------------------------
+  choice(x: any, choices: Record<string, any>, def?: any): any;
+  loremIpsum(numChars: number, startSpot?: number, startWithCapitalLetter?: boolean): string;
+  naturalCompare(a: string, b: string): number;
+
+  // -- Timing ---------------------------------------------------------------
+  setIntervalX(callback: Function, delay: number, repetitions: number): number;
+  repeatUntil(testFn: () => boolean, successFn: () => void, failFn?: () => void, delay?: number, maxReps?: number, lastFn?: () => void): void;
+
+  // -- Type Detection -------------------------------------------------------
+  typeOf(value: any, baseTypeOnly?: boolean): string;
+  isNodeJS(): boolean;
+
+  // -- File I/O -------------------------------------------------------------
+  saveClientFile(fname: string, data: any): void;
+  saveClientJSON(fname: string, data: any): void;
+  loadClientFile(fname: string, callback: (data: any, error?: any) => void, options?: { parser?: string }): string;
+  loadClientJSON(fname: string, callback: (data: any, error?: any) => void): string;
+  loadLocalFile(callback: (data: any, filename: string, error?: any) => void, options?: { parser?: string; accept?: string }): void;
+  loadLocalJSON(callback: (data: any, filename: string, error?: any) => void): void;
+
+  // -- Cookies & URL --------------------------------------------------------
+  setCookie(cname: string, cvalue: string, exdays: number, options?: { path?: string; domain?: string; secure?: boolean; sameSite?: string }): void;
+  getCookie(cname: string, defaultValue?: any): any;
+  getURLParam(key?: string, defaultValue?: any): any;
+
+  // -- Clipboard ------------------------------------------------------------
+  copyToClipboard(text: string): Promise<void>;
+
+  // -- JSON Parsing ---------------------------------------------------------
+  parseJSONFlex(str: string): any;
+
+  // -- Presets & Constants --------------------------------------------------
+  SPACING_PRESETS: Record<string, any>;
+  RADIUS_PRESETS: Record<string, any>;
+  TYPE_RATIO_PRESETS: Record<string, any>;
+  ELEVATION_PRESETS: Record<string, any>;
+  MOTION_PRESETS: Record<string, any>;
+  DEFAULT_PALETTE_CONFIG: StyleConfig;
+  THEME_PRESETS: Record<string, StyleConfig>;
+  BCCL: Record<string, any>;
+
+  // -- Variant helper -------------------------------------------------------
+  variantClass(variant: string): string;
+
+  // -- Internal (access at own risk) ----------------------------------------
+  _nodeMap: Record<string, HTMLElement>;
+  _el(id: string): HTMLElement | null;
+  _registerNode(el: HTMLElement, uuid: string): void;
+  _deregisterNode(el: HTMLElement, uuid: string): void;
+  _unmountCallbacks: Map<string, Function>;
+  _topics: Record<string, any[]>;
+  _fnRegistry: Record<string, Function>;
+  _componentRegistry: Map<string, any>;
+  _clientFunctions: Record<string, Function>;
+  _allowExec: boolean;
+}
+
+/** The bw namespace (default export) */
+declare const bw: Bitwrench;
+export default bw;
+
+// Named BCCL exports for ESM tree-shaking:
+//   import { makeCard, makeButton } from 'bitwrench';
+export function makeCard(config?: CardConfig | string): Taco;
+export function makeButton(config?: ButtonConfig | string): Taco;
+export function makeContainer(config?: ComponentConfig): Taco;
+export function makeRow(config?: ComponentConfig): Taco;
+export function makeCol(config?: ComponentConfig): Taco;
+export function makeStack(config?: ComponentConfig): Taco;
+export function makeSection(config?: ComponentConfig): Taco;
+export function makeNav(config?: NavConfig): Taco;
+export function makeNavbar(config?: ComponentConfig): Taco;
+export function makeBreadcrumb(config?: ComponentConfig): Taco;
+export function makeTabs(config?: TabsConfig): Taco;
+export function makePagination(config?: ComponentConfig): Taco;
+export function makeAlert(config?: AlertConfig | string): Taco;
+export function makeBadge(config?: ComponentConfig | string): Taco;
+export function makeProgress(config?: ComponentConfig): Taco;
+export function makeSpinner(config?: ComponentConfig): Taco;
+export function makeToast(config?: ComponentConfig): Taco;
+export function makeTooltip(config?: ComponentConfig): Taco;
+export function makePopover(config?: ComponentConfig): Taco;
+export function makeListGroup(config?: ComponentConfig): Taco;
+export function makeAccordion(config?: AccordionConfig): Taco;
+export function makeCarousel(config?: CarouselConfig): Taco;
+export function makeTimeline(config?: ComponentConfig): Taco;
+export function makeStepper(config?: ComponentConfig): Taco;
+export function makeChipInput(config?: ComponentConfig): Taco;
+export function makeModal(config?: ModalConfig): Taco;
+export function makeDropdown(config?: ComponentConfig): Taco;
+export function makeForm(config?: ComponentConfig): Taco;
+export function makeFormGroup(config?: ComponentConfig): Taco;
+export function makeInput(config?: InputConfig): Taco;
+export function makeTextarea(config?: ComponentConfig): Taco;
+export function makeSelect(config?: ComponentConfig): Taco;
+export function makeCheckbox(config?: ComponentConfig): Taco;
+export function makeRadio(config?: ComponentConfig): Taco;
+export function makeSwitch(config?: ComponentConfig): Taco;
+export function makeRange(config?: ComponentConfig): Taco;
+export function makeFileUpload(config?: ComponentConfig): Taco;
+export function makeSearchInput(config?: ComponentConfig): Taco;
+export function makeButtonGroup(config?: ComponentConfig): Taco;
+export function makeHero(config?: ComponentConfig): Taco;
+export function makeFeatureGrid(config?: ComponentConfig): Taco;
+export function makeCTA(config?: ComponentConfig): Taco;
+export function makeCodeDemo(config?: ComponentConfig): Taco;
+export function makeSkeleton(config?: ComponentConfig): Taco;
+export function makeAvatar(config?: ComponentConfig): Taco;
+export function makeStatCard(config?: ComponentConfig): Taco;
+export function makeMediaObject(config?: ComponentConfig): Taco;
+export function makeTable(config?: TableConfig): Taco;
+export function makeTableFromArray(config?: TableConfig): Taco;
+export function makeDataTable(config?: TableConfig): Taco;
+export function makeBarChart(config?: ComponentConfig): Taco;
+export function make(type: string, props?: ComponentConfig): Taco;
+export function variantClass(variant: string): string;
+export const BCCL: Record<string, any>;

package/src/bitwrench.js

@@ -2478,7 +2478,8 @@ bw.applyStyles = function(styles, scope) {
  *
  * @param {Object} [config] - Style configuration (same as `makeStyles`)
  * @param {string} [scope] - Scope selector (same as `applyStyles`)
- * @returns {Element|null} The `<style>` element, or null in Node.js
+ * @returns {Object} The styles object (same as `makeStyles` return value:
+ *   `{css, alternateCss, palette, alternatePalette, rules, alternateRules, isLightPrimary}`)
  * @category CSS & Styling
  * @see bw.makeStyles
  * @see bw.applyStyles
@@ -2496,9 +2497,27 @@ bw.loadStyles = function(config, scope) {
       bw.injectCSS(structuralCSS, { id: 'bw_structural', append: false });
     }
   }
-  return bw.applyStyles(bw.makeStyles(config), scope);
+  var styles = bw.makeStyles(config);
+  bw.applyStyles(styles, scope);
+  return styles;
 };
 
+/**
+ * Prefix every selector in a rules object with a scope selector.
+ * Useful for wrapping site-level CSS under `.bw_theme_alt` for dark mode.
+ *
+ * @param {Object} rules - CSS rules object (selector -> declarations)
+ * @param {string} prefix - Scope prefix (e.g. '.bw_theme_alt')
+ * @returns {Object} New rules object with scoped selectors
+ * @category CSS & Styling
+ * @see bw.applyStyles
+ * @see bw.css
+ * @example
+ * var altRules = bw.scopeRulesUnder(myRules, '.bw_theme_alt');
+ * bw.injectCSS(bw.css(altRules));
+ */
+bw.scopeRulesUnder = scopeRulesUnder;
+
 /**
  * Inject the CSS reset (box-sizing, html/body font, reduced-motion).
  * Idempotent — if already injected, returns the existing `<style>` element.