@purple-brock/burrow-web 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luke Price (The Purple Brock)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,14 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lrprice79/badger-burrow/HEAD/assets/purple-brock-icon.png" width="120" alt="BadgerBurrow">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @purple-brock/burrow-web
+
+BadgerBurrow for React on the web — `<Chamber>` and `<Tunnel>` with pseudo states (`_hover`, `_focus`…), responsive props and SSR style collection.
+
+**Needs:** React ≥ 18. ESM only.
+
+Part of **BadgerBurrow** by The Purple Brock — see the
+[main README and usage guide](https://github.com/lrprice79/badger-burrow#readme).
+
+MIT © 2026 Luke Price (The Purple Brock)

package/dist/index.d.mts

@@ -0,0 +1,116 @@
+import { BurrowSnapshot, ColorMode, BurrowBoxProps, BurrowTextProps } from '@purple-brock/burrow-core';
+import React from 'react';
+
+interface UseBurrowResult extends BurrowSnapshot {
+    setMode: (mode: ColorMode) => void;
+}
+/**
+ * Returns the current BadgerBurrow token snapshot and a setMode helper.
+ *
+ * Subscribes to BadgerBase via useSyncExternalStore — renders only when
+ * tokens or mode actually change. No ThemeProvider required anywhere in
+ * the tree.
+ *
+ * @example
+ * function MyButton() {
+ *   const { tokens, mode, setMode } = useBurrow()
+ *   return (
+ *     <button style={{ background: tokens.primitive.color.primary[500] }}>
+ *       Switch to {mode === 'light' ? 'dark' : 'light'}
+ *     </button>
+ *   )
+ * }
+ */
+declare function useBurrow(): UseBurrowResult;
+
+type ChamberTag = 'div' | 'section' | 'article' | 'aside' | 'header' | 'footer' | 'main' | 'nav' | 'button' | 'a' | 'form' | 'fieldset' | 'ul' | 'ol' | 'li' | 'figure' | 'figcaption' | 'label' | 'dialog' | 'details' | 'summary' | 'span';
+interface ChamberProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'>, BurrowBoxProps {
+    /** Element tag to render — defaults to div */
+    as?: ChamberTag;
+    /** Required when as="a" */
+    href?: string;
+}
+/**
+ * A styled box component backed by BadgerBurrow tokens.
+ * Accepts shorthand token props alongside all standard HTML props.
+ * Use `as` to render as any semantic element — button, nav, section, etc.
+ *
+ * Priority (lowest → highest): sx → named props → style
+ *
+ * Pseudo-state styling via _hover, _focus, _active, _focusVisible, _disabled.
+ * Smart hover bg: if `bg` is a primitive path, hover bg auto-steps one shade darker.
+ * Use `hoverScale` to specify which colour scale to step on, `hoverShade` for an
+ * exact shade, or `hoverScale={false}` to disable the smart default entirely.
+ *
+ * @example
+ * <Chamber
+ *   as="button"
+ *   bg="color.interactive.primary"
+ *   px="space.4" py="space.2"
+ *   radius="radius.md"
+ *   _hover={{ bg: 'color.interactive.primary.hover', cursor: 'pointer' }}
+ *   _disabled={{ opacity: 0.4, cursor: 'not-allowed' }}
+ *   onClick={handleClick}
+ * />
+ */
+declare const Chamber: React.ForwardRefExoticComponent<ChamberProps & React.RefAttributes<HTMLElement>>;
+
+type TunnelTag = 'span' | 'p' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'label';
+interface TunnelProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'>, BurrowTextProps {
+    /** Element tag to render — defaults to span */
+    as?: TunnelTag;
+}
+/**
+ * The text component. Every piece of visible text in your UI goes in a Tunnel —
+ * headings, body copy, labels, captions, error messages.
+ *
+ * Tunnel has no layout props. Use a Chamber to position or space text alongside
+ * other elements.
+ *
+ * Priority (lowest → highest): sx → named props → style
+ *
+ * @example
+ * <Tunnel as="h1" fontSize="fontSize.2xl" fontWeight="fontWeight.bold" color="color.text.primary">
+ *   Page title
+ * </Tunnel>
+ *
+ * <Tunnel as="p" color="color.text.secondary" lineHeight="lineHeight.relaxed">
+ *   Body copy here.
+ * </Tunnel>
+ */
+declare const Tunnel: React.ForwardRefExoticComponent<TunnelProps & React.RefAttributes<HTMLElement>>;
+
+interface BurrowStyleRegistry {
+    /** Run a synchronous render with this registry active; returns its result. */
+    collect<T>(fn: () => T): T;
+    /** A single `<style>` tag string with every collected rule — emit in <head>. */
+    styleTags(): string;
+    /** Forget all collected rules (reuse the registry for another request). */
+    clear(): void;
+}
+/**
+ * Server-side style collection (provider-less, framework-agnostic). Pseudo and
+ * responsive rules aren't injected on the server (there's no DOM), so collect
+ * them during `renderToString` and emit them into the document `<head>`:
+ *
+ *   const registry = createStyleRegistry()
+ *   const html = registry.collect(() => renderToString(<App />))
+ *   // <head> … {registry.styleTags()} … </head><body>{html}</body>
+ *
+ * On the client, the emitted tag carries `data-bb-ids`; `adoptServerStyles()`
+ * (run automatically on import) seeds the cache from it so hydration never
+ * re-injects or duplicates those rules.
+ *
+ * Synchronous SSR only (`renderToString`) — the active registry is a module
+ * global set around `collect`, which is safe because Node runs sync code without
+ * interleaving. Not for streaming/async SSR.
+ */
+declare function createStyleRegistry(): BurrowStyleRegistry;
+/**
+ * Seed the injection cache from a server-rendered `[data-bb-ssr]` tag so the
+ * client skips re-injecting (and thus never duplicates) SSR'd rules. Runs once
+ * automatically on import; exported for tests.
+ */
+declare function adoptServerStyles(): void;
+
+export { type BurrowStyleRegistry, Chamber, type ChamberProps, Tunnel, type TunnelProps, type UseBurrowResult, adoptServerStyles, createStyleRegistry, useBurrow };

package/dist/index.mjs

@@ -0,0 +1,330 @@
+// src/useBurrow.ts
+import { useSyncExternalStore } from "react";
+import { BadgerBase } from "@purple-brock/burrow-core";
+function useBurrow() {
+  const snapshot = useSyncExternalStore(
+    BadgerBase.subscribe,
+    BadgerBase.getSnapshot,
+    BadgerBase.getSnapshot
+  );
+  return {
+    tokens: snapshot.tokens,
+    mode: snapshot.mode,
+    setMode: BadgerBase.setMode
+  };
+}
+
+// src/Chamber.tsx
+import React2 from "react";
+import {
+  resolveSx,
+  buildBoxStyles,
+  buildPseudoStyles,
+  toClassName,
+  BURROW_BOX_KEYS,
+  splitResponsiveProps,
+  getBreakpointOrder
+} from "@purple-brock/burrow-core";
+
+// src/styleInjector.ts
+var ATTR = "data-bb";
+var RESPONSIVE_ATTR = "data-bb-responsive";
+var _injected = /* @__PURE__ */ new Set();
+var _registry = null;
+function createStyleRegistry() {
+  const map = /* @__PURE__ */ new Map();
+  return {
+    collect(fn) {
+      const prev = _registry;
+      _registry = map;
+      try {
+        return fn();
+      } finally {
+        _registry = prev;
+      }
+    },
+    styleTags() {
+      if (map.size === 0) return "";
+      const ids = [...map.keys()].join(" ");
+      const css = [...map.values()].join("\n");
+      return `<style data-bb-ssr data-bb-ids="${ids}">${css}</style>`;
+    },
+    clear() {
+      map.clear();
+    }
+  };
+}
+function adoptServerStyles() {
+  if (typeof document === "undefined") return;
+  const ssr = document.querySelector("style[data-bb-ssr]");
+  const ids = ssr?.getAttribute("data-bb-ids");
+  if (ids) for (const id of ids.split(" ")) _injected.add(id);
+}
+adoptServerStyles();
+function stableStringify(obj) {
+  const sorted = {};
+  for (const key of Object.keys(obj).sort()) {
+    const value = obj[key];
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      const inner = {};
+      for (const k of Object.keys(value).sort()) {
+        inner[k] = value[k];
+      }
+      sorted[key] = inner;
+    } else {
+      sorted[key] = value;
+    }
+  }
+  return JSON.stringify(sorted);
+}
+function toKebab(prop) {
+  return prop.replace(/([A-Z])/g, "-$1").toLowerCase();
+}
+function styleObjectToCss(styles, important = false) {
+  const suffix = important ? " !important" : "";
+  return Object.entries(styles).filter(([, v]) => v !== void 0 && v !== "").map(([k, v]) => `${toKebab(k)}: ${v}${suffix};`).join(" ");
+}
+function pseudoSelector(pseudo) {
+  if (pseudo === "focusVisible") return "focus-visible";
+  return pseudo;
+}
+function injectPseudoRule(className, pseudo, styles) {
+  const id = `${className}:${pseudo}`;
+  if (_registry) {
+    if (_registry.has(id)) return;
+    const css2 = styleObjectToCss(styles, true);
+    if (css2) _registry.set(id, `.${className}:${pseudoSelector(pseudo)} { ${css2} }`);
+    return;
+  }
+  if (typeof document === "undefined") return;
+  if (_injected.has(id)) return;
+  const css = styleObjectToCss(styles, true);
+  if (!css) return;
+  const rule = `.${className}:${pseudoSelector(pseudo)} { ${css} }`;
+  const existing = document.head.querySelector(`[${ATTR}="${id}"]`);
+  _injected.add(id);
+  if (existing) {
+    if (existing.textContent !== rule) existing.textContent = rule;
+    return;
+  }
+  const tag = document.createElement("style");
+  tag.setAttribute(ATTR, id);
+  tag.textContent = rule;
+  document.head.appendChild(tag);
+}
+function injectPseudoStyles(className, pseudoStyles) {
+  for (const [pseudo, styles] of Object.entries(pseudoStyles)) {
+    injectPseudoRule(className, pseudo, styles);
+  }
+}
+function injectResponsiveStyles(className, bpStyles, breakpoints) {
+  const id = `resp:${className}`;
+  const rules = [];
+  const baseStyles = bpStyles.base;
+  if (baseStyles) {
+    const css = styleObjectToCss(baseStyles);
+    if (css) rules.push(`.${className} { ${css} }`);
+  }
+  const ordered = Object.entries(breakpoints).map(([bp, minWidth]) => ({ bp, minWidth, px: parseInt(minWidth, 10) })).sort((a, b) => a.px - b.px);
+  for (const { bp, minWidth } of ordered) {
+    const styles = bpStyles[bp];
+    if (!styles) continue;
+    const css = styleObjectToCss(styles);
+    if (!css) continue;
+    rules.push(`@media (min-width: ${minWidth}) { .${className} { ${css} } }`);
+  }
+  if (rules.length === 0) return;
+  const content = rules.join("\n");
+  if (_registry) {
+    if (!_registry.has(id)) _registry.set(id, content);
+    return;
+  }
+  if (typeof document === "undefined") return;
+  if (_injected.has(id)) return;
+  const existing = document.head.querySelector(`[${RESPONSIVE_ATTR}="${className}"]`);
+  _injected.add(id);
+  if (existing) {
+    if (existing.textContent !== content) existing.textContent = content;
+    return;
+  }
+  const tag = document.createElement("style");
+  tag.setAttribute(RESPONSIVE_ATTR, className);
+  tag.textContent = content;
+  document.head.appendChild(tag);
+}
+
+// src/useDebug.ts
+import { useRef, useLayoutEffect } from "react";
+var DEBUG_COLOR = "#c026d3";
+function useDebug(enabled, info) {
+  const ref = useRef(null);
+  const renders = useRef(0);
+  renders.current += 1;
+  const on = process.env.NODE_ENV !== "production" && !!enabled;
+  useLayoutEffect(() => {
+    if (!on) return;
+    const el = ref.current;
+    const r = el?.getBoundingClientRect();
+    const size = r ? `${Math.round(r.width)}\xD7${Math.round(r.height)}` : "?";
+    console.groupCollapsed(
+      `%c[bb] ${info.component} <${info.tag}>  \u27F3${renders.current} \xB7 ${size} \xB7 ${info.mode}`,
+      `color:${DEBUG_COLOR};font-weight:bold`
+    );
+    console.table(info.style);
+    console.groupEnd();
+  });
+  if (!on) return { debugRef: ref };
+  return { debugRef: ref, outline: `1px dashed ${DEBUG_COLOR}`, attr: `\u27F3${renders.current}` };
+}
+function mergeRefs(...refs) {
+  return (node) => {
+    for (const ref of refs) {
+      if (!ref) continue;
+      if (typeof ref === "function") ref(node);
+      else ref.current = node;
+    }
+  };
+}
+
+// src/Chamber.tsx
+import { jsx } from "react/jsx-runtime";
+var Chamber = React2.forwardRef(function Chamber2({ as: Tag = "div", sx, style, children, __debug, ...props }, ref) {
+  const { tokens, mode } = useBurrow();
+  const burrowProps = {};
+  const htmlProps = {};
+  for (const [key, value] of Object.entries(props)) {
+    if (BURROW_BOX_KEYS.has(key)) burrowProps[key] = value;
+    else htmlProps[key] = value;
+  }
+  const { baseProps, responsiveProps } = splitResponsiveProps(burrowProps, tokens.breakpoints);
+  const boxPropsTyped = baseProps;
+  const inlineProps = {};
+  for (const key in baseProps) {
+    if (!(key in responsiveProps)) inlineProps[key] = baseProps[key];
+  }
+  const tokenStyles = buildBoxStyles(inlineProps, tokens, mode);
+  const sxStyles = sx ? resolveSx(sx, tokens, mode) : {};
+  const pseudoStyles = buildPseudoStyles(boxPropsTyped, tokens, mode);
+  const hasPseudo = Object.keys(pseudoStyles).length > 0;
+  const hasResponsive = Object.keys(responsiveProps).length > 0;
+  const breakpoints = tokens.breakpoints ?? {};
+  let bpStyles;
+  if (hasResponsive) {
+    const bpOrder = getBreakpointOrder(breakpoints);
+    bpStyles = {};
+    for (const bp of bpOrder) {
+      const bpProps = {};
+      for (const [key, obj] of Object.entries(responsiveProps)) {
+        const bpObj = obj;
+        if (bp in bpObj && bpObj[bp] !== void 0) bpProps[key] = bpObj[bp];
+      }
+      if (Object.keys(bpProps).length > 0) {
+        bpStyles[bp] = buildBoxStyles(bpProps, tokens, mode);
+      }
+    }
+  }
+  const className = hasPseudo || hasResponsive ? toClassName(JSON.stringify(pseudoStyles) + stableStringify(bpStyles ?? {}) + mode) : void 0;
+  if (hasPseudo && className) {
+    injectPseudoStyles(className, pseudoStyles);
+  }
+  if (hasResponsive && className && bpStyles) {
+    injectResponsiveStyles(className, bpStyles, breakpoints);
+  }
+  const resolvedStyle = { ...sxStyles, ...tokenStyles, ...style };
+  const dbg = useDebug(__debug, { component: "Chamber", tag: String(Tag), mode, style: resolvedStyle });
+  const Component = Tag;
+  const { className: userClassName, ...restHtmlProps } = htmlProps;
+  const mergedClassName = [className, userClassName].filter(Boolean).join(" ") || void 0;
+  const combinedRef = React2.useMemo(() => mergeRefs(ref, dbg.debugRef), [ref, dbg.debugRef]);
+  return /* @__PURE__ */ jsx(
+    Component,
+    {
+      ref: combinedRef,
+      className: mergedClassName,
+      style: dbg.outline ? { ...resolvedStyle, outline: dbg.outline } : resolvedStyle,
+      ...dbg.attr ? { "data-bb-debug": dbg.attr } : {},
+      ...restHtmlProps,
+      children
+    }
+  );
+});
+
+// src/Tunnel.tsx
+import React3 from "react";
+import {
+  resolveSx as resolveSx2,
+  buildTextStyles,
+  buildTextPseudoStyles,
+  toClassName as toClassName2,
+  BURROW_TEXT_KEYS,
+  splitResponsiveProps as splitResponsiveProps2,
+  getBreakpointOrder as getBreakpointOrder2
+} from "@purple-brock/burrow-core";
+import { jsx as jsx2 } from "react/jsx-runtime";
+var Tunnel = React3.forwardRef(function Tunnel2({ as: Tag = "span", sx, style, children, __debug, ...props }, ref) {
+  const { tokens, mode } = useBurrow();
+  const burrowProps = {};
+  const htmlProps = {};
+  for (const [key, value] of Object.entries(props)) {
+    if (BURROW_TEXT_KEYS.has(key)) burrowProps[key] = value;
+    else htmlProps[key] = value;
+  }
+  const { baseProps, responsiveProps } = splitResponsiveProps2(burrowProps, tokens.breakpoints);
+  const textPropsTyped = baseProps;
+  const inlineProps = {};
+  for (const key in baseProps) {
+    if (!(key in responsiveProps)) inlineProps[key] = baseProps[key];
+  }
+  const tokenStyles = buildTextStyles(inlineProps, tokens, mode);
+  const sxStyles = sx ? resolveSx2(sx, tokens, mode) : {};
+  const pseudoStyles = buildTextPseudoStyles(textPropsTyped, tokens, mode);
+  const hasPseudo = Object.keys(pseudoStyles).length > 0;
+  const hasResponsive = Object.keys(responsiveProps).length > 0;
+  const breakpoints = tokens.breakpoints ?? {};
+  let bpStyles;
+  if (hasResponsive) {
+    const bpOrder = getBreakpointOrder2(breakpoints);
+    bpStyles = {};
+    for (const bp of bpOrder) {
+      const bpProps = {};
+      for (const [key, obj] of Object.entries(responsiveProps)) {
+        const bpObj = obj;
+        if (bp in bpObj && bpObj[bp] !== void 0) bpProps[key] = bpObj[bp];
+      }
+      if (Object.keys(bpProps).length > 0) {
+        bpStyles[bp] = buildTextStyles(bpProps, tokens, mode);
+      }
+    }
+  }
+  const className = hasPseudo || hasResponsive ? toClassName2(JSON.stringify(pseudoStyles) + stableStringify(bpStyles ?? {}) + mode) : void 0;
+  if (hasPseudo && className) {
+    injectPseudoStyles(className, pseudoStyles);
+  }
+  if (hasResponsive && className && bpStyles) {
+    injectResponsiveStyles(className, bpStyles, breakpoints);
+  }
+  const resolvedStyle = { ...sxStyles, ...tokenStyles, ...style };
+  const dbg = useDebug(__debug, { component: "Tunnel", tag: String(Tag), mode, style: resolvedStyle });
+  const Component = Tag;
+  const { className: userClassName, ...restHtmlProps } = htmlProps;
+  const mergedClassName = [className, userClassName].filter(Boolean).join(" ") || void 0;
+  const combinedRef = React3.useMemo(() => mergeRefs(ref, dbg.debugRef), [ref, dbg.debugRef]);
+  return /* @__PURE__ */ jsx2(
+    Component,
+    {
+      ref: combinedRef,
+      className: mergedClassName,
+      style: dbg.outline ? { ...resolvedStyle, outline: dbg.outline } : resolvedStyle,
+      ...dbg.attr ? { "data-bb-debug": dbg.attr } : {},
+      ...restHtmlProps,
+      children
+    }
+  );
+});
+export {
+  Chamber,
+  Tunnel,
+  adoptServerStyles,
+  createStyleRegistry,
+  useBurrow
+};

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@purple-brock/burrow-web",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "@purple-brock/burrow-core": "0.1.0",
+    "@purple-brock/burrow-tokens": "0.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^14.3.1",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^18.3.31",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "ts-jest": "^29.4.15",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lrprice79/badger-burrow.git",
+    "directory": "packages/web"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "test": "jest --passWithNoTests",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
 }