@spark-web/box - npm Package Compare versions

Comparing version 6.0.0 to 6.0.1

CLAUDE.md

+# @spark-web/box — AI Context
+
+## What this is
+
+The foundational layout primitive. Every Spark component is built on `Box`. It
+exposes a prop-based API for applying theme-constrained styles to any HTML
+element. Use it when no higher-level layout component (`Stack`, `Row`,
+`Columns`) fits the shape of what you need.
+
+## What this is NOT
+
+- Not a text component — use `Text` for any rendered text content
+- Not a layout shorthand — for vertical stacks use `Stack`, for horizontal rows
+  use `Row`, for CSS grid use `Columns`
+- Not a button — use `Button` or `ButtonLink` for interactive elements
+
+## Props interface
+
+`Box` accepts all `BoxStyleProps` (see below) plus:
+
+| Prop        | Type                          | Notes                                            |
+| ----------- | ----------------------------- | ------------------------------------------------ |
+| `as`        | `keyof HTMLElementTagNameMap` | Changes the rendered element; defaults to `div`  |
+| `asElement` | `keyof HTMLElementTagNameMap` | Tells the reset system what element `as` renders |
+| `children`  | `ReactNode`                   | —                                                |
+| `data`      | `DataAttributeMap`            | Test/analytics attributes                        |
+| `id`        | `string`                      | —                                                |
+| `css`       | `CSSObject`                   | Escape hatch for styles not covered by props     |
+
+### BoxStyleProps — commonly used
+
+Spacing values map to `SparkTheme['spacing']` keys:
+`none | xsmall | small | medium | large | xlarge | xxlarge`
+
+Sizing values map to `SparkTheme['sizing']` keys:
+`xxsmall | xsmall | small | medium | large | xlarge | xxlarge | full`
+
+| Prop                              | Values                                                                       |
+| --------------------------------- | ---------------------------------------------------------------------------- |
+| `padding`                         | spacing token (responsive)                                                   |
+| `paddingX`                        | spacing token (responsive)                                                   |
+| `paddingY`                        | spacing token (responsive)                                                   |
+| `paddingTop/Bottom/Left/Right`    | spacing token (responsive)                                                   |
+| `margin`                          | spacing token (responsive)                                                   |
+| `marginX/Y/Top/Bottom/Left/Right` | spacing token (responsive)                                                   |
+| `gap`                             | spacing token (responsive, excludes `none` and `full`)                       |
+| `width`                           | sizing token or `'full'` (responsive)                                        |
+| `height`                          | sizing token (responsive)                                                    |
+| `display`                         | `'block' \| 'inline' \| 'inline-block' \| 'inline-flex' \| 'flex' \| 'none'` |
+| `flexDirection`                   | `'row' \| 'rowReverse' \| 'column' \| 'columnReverse'`                       |
+| `flexWrap`                        | `'wrap' \| 'nowrap'`                                                         |
+| `alignItems`                      | `'center' \| 'flexStart' \| 'flexEnd' \| 'stretch'`                          |
+| `justifyContent`                  | `'start' \| 'center' \| 'end' \| 'spaceBetween' \| 'stretch'`                |
+| `flexShrink`                      | `0 \| 1`                                                                     |
+| `position`                        | `'relative' \| 'absolute' \| 'fixed' \| 'sticky'`                            |
+| `top/bottom/left/right`           | `number` (responsive)                                                        |
+| `overflow`                        | `'hidden' \| 'auto' \| 'scroll' \| 'visible'`                                |
+| `background`                      | background token (e.g. `'surface' \| 'primary' \| 'primarySoft'`)            |
+| `border`                          | border color token (e.g. `'standard' \| 'primary'`)                          |
+| `borderRadius`                    | `'small' \| 'medium' \| 'large' \| 'full'`                                   |
+| `cursor`                          | `'default' \| 'pointer'`                                                     |
+
+## Token usage
+
+All values come from the theme — never raw hex, px, or Tailwind. Use
+`useTheme()` from `@spark-web/theme` for any value not expressible as a Box prop
+(e.g. inline color from `theme.color.foreground.muted`).
+
+The `background` prop automatically pushes a background context so child `Text`
+components can invert their color tone when placed on dark backgrounds.
+
+## Composition
+
+`Box` is the leaf — it does not compose other Spark components. Every other
+Spark component composes `Box` internally.
+
+## Do NOTs
+
+- NEVER use raw hex, px, em, rem, or Tailwind classes
+- NEVER use `Box` for text content — use `Text`
+- NEVER use `Box` when `Stack`, `Row`, or `Columns` fits the layout — those
+  components encode the correct flex/grid setup automatically
+- NEVER pass `display`, `alignItems`, `flexDirection`, or `justifyContent` to
+  `Stack` or `Row` — those are locked internally; use `Box` if you need custom
+  flex control
+- NEVER use `style={{}}` for theme values — use Box props or `css` prop with
+  theme tokens

CHANGELOG.md

 # @spark-web/box
 
+## 6.0.1
+
+### Patch Changes
+
+- [#782](https://github.com/brighte-labs/spark-web/pull/782)
+  [`bb41800`](https://github.com/brighte-labs/spark-web/commit/bb418004d21165f72f4bf2456afea844ee04a21c)
+  Thanks [@jacobporci-brighte](https://github.com/jacobporci-brighte)! -
+  **docs:** add CLAUDE.md AI context files to foundation and form packages;
+  patch data-table with manual sort and spinner overlay patterns
+
 ## 6.0.0
@@ -4,0 +14,0 @@

dist/declarations/src/box.d.ts

@@ -24,3 +24,3 @@ import type { CSSObject } from '@emotion/react';
     as?: Comp | undefined;
-    ref?: import("react").Ref<Comp extends "symbol" | "svg" | "animate" | "animateMotion" | "animateTransform" | "circle" | "clipPath" | "defs" | "desc" | "ellipse" | "feBlend" | "feColorMatrix" | "feComponentTransfer" | "feComposite" | "feConvolveMatrix" | "feDiffuseLighting" | "feDisplacementMap" | "feDistantLight" | "feDropShadow" | "feFlood" | "feFuncA" | "feFuncB" | "feFuncG" | "feFuncR" | "feGaussianBlur" | "feImage" | "feMerge" | "feMergeNode" | "feMorphology" | "feOffset" | "fePointLight" | "feSpecularLighting" | "feSpotLight" | "feTile" | "feTurbulence" | "filter" | "foreignObject" | "g" | "image" | "line" | "linearGradient" | "marker" | "mask" | "metadata" | "mpath" | "path" | "pattern" | "polygon" | "polyline" | "radialGradient" | "rect" | "set" | "stop" | "switch" | "text" | "textPath" | "tspan" | "use" | "view" | keyof HTMLElementTagNameMap ? (HTMLElementTagNameMap & Pick<SVGElementTagNameMap, "symbol" | "svg" | "animate" | "animateMotion" | "animateTransform" | "circle" | "clipPath" | "defs" | "desc" | "ellipse" | "feBlend" | "feColorMatrix" | "feComponentTransfer" | "feComposite" | "feConvolveMatrix" | "feDiffuseLighting" | "feDisplacementMap" | "feDistantLight" | "feDropShadow" | "feFlood" | "feFuncA" | "feFuncB" | "feFuncG" | "feFuncR" | "feGaussianBlur" | "feImage" | "feMerge" | "feMergeNode" | "feMorphology" | "feOffset" | "fePointLight" | "feSpecularLighting" | "feSpotLight" | "feTile" | "feTurbulence" | "filter" | "foreignObject" | "g" | "image" | "line" | "linearGradient" | "marker" | "mask" | "metadata" | "mpath" | "path" | "pattern" | "polygon" | "polyline" | "radialGradient" | "rect" | "set" | "stop" | "switch" | "text" | "textPath" | "tspan" | "use" | "view">)[Comp] : Comp extends new (...args: any) => any ? InstanceType<Comp> : undefined> | undefined;
+    ref?: import("react").Ref<Comp extends "symbol" | "text" | "clipPath" | "filter" | "mask" | "marker" | "svg" | "animate" | "animateMotion" | "animateTransform" | "circle" | "defs" | "desc" | "ellipse" | "feBlend" | "feColorMatrix" | "feComponentTransfer" | "feComposite" | "feConvolveMatrix" | "feDiffuseLighting" | "feDisplacementMap" | "feDistantLight" | "feDropShadow" | "feFlood" | "feFuncA" | "feFuncB" | "feFuncG" | "feFuncR" | "feGaussianBlur" | "feImage" | "feMerge" | "feMergeNode" | "feMorphology" | "feOffset" | "fePointLight" | "feSpecularLighting" | "feSpotLight" | "feTile" | "feTurbulence" | "foreignObject" | "g" | "image" | "line" | "linearGradient" | "metadata" | "mpath" | "path" | "pattern" | "polygon" | "polyline" | "radialGradient" | "rect" | "set" | "stop" | "switch" | "textPath" | "tspan" | "use" | "view" | keyof HTMLElementTagNameMap ? (HTMLElementTagNameMap & Pick<SVGElementTagNameMap, "symbol" | "text" | "clipPath" | "filter" | "mask" | "marker" | "svg" | "animate" | "animateMotion" | "animateTransform" | "circle" | "defs" | "desc" | "ellipse" | "feBlend" | "feColorMatrix" | "feComponentTransfer" | "feComposite" | "feConvolveMatrix" | "feDiffuseLighting" | "feDisplacementMap" | "feDistantLight" | "feDropShadow" | "feFlood" | "feFuncA" | "feFuncB" | "feFuncG" | "feFuncR" | "feGaussianBlur" | "feImage" | "feMerge" | "feMergeNode" | "feMorphology" | "feOffset" | "fePointLight" | "feSpecularLighting" | "feSpotLight" | "feTile" | "feTurbulence" | "foreignObject" | "g" | "image" | "line" | "linearGradient" | "metadata" | "mpath" | "path" | "pattern" | "polygon" | "polyline" | "radialGradient" | "rect" | "set" | "stop" | "switch" | "textPath" | "tspan" | "use" | "view">)[Comp] : Comp extends new (...args: any) => any ? InstanceType<Comp> : undefined> | undefined;
 } & Omit<import("react").PropsWithoutRef<import("react").ComponentProps<Comp>>, "as"> & {
@@ -27,0 +27,0 @@ /** Children element to be rendered inside the component. */

package.json

 {
   "name": "@spark-web/box",
-  "version": "6.0.0",
+  "version": "6.0.1",
   "homepage": "https://github.com/brighte-labs/spark-web#readme",
@@ -14,2 +14,3 @@ "repository": {
     "CHANGELOG.md",
+    "CLAUDE.md",
     "dist",
@@ -16,0 +17,0 @@ "README.md"

No alert changes

Improved metrics

Total package byte prevSize

84038

7.72%

Number of package files

14

7.69%

No dependency changes