@thorprovider/blocks 0.1.0 → 0.1.2

package/docs/standards/theming.md

@@ -8,11 +8,26 @@ tags: [blocks, theming, tokens, contrast, a11y]
 
 # Theme token contract
 
-`@thorprovider/blocks` ships **zero CSS**. Block styling resolves against the
-consumer's own theme tokens at build time (Tailwind `@source` points at the
-library source). This document is the contract between the library and every
-theme that renders it: the tokens blocks may reference, the status rule, and
-the documented exceptions.
+`@thorprovider/blocks` ships **no component CSS** — the package declares no
+design and defines no `:root` tokens. Block classes are utility classes that
+resolve against the consumer's own theme tokens at build time. What the package
+does ship is a **one-line Tailwind source-registration entry** so the consumer's
+build scans the library's compiled class names. Register it from the consumer
+stylesheet:
+
+```css
+@import "@thorprovider/blocks/styles.css";
+```
+
+The entry contains only `@source "./dist";` (a path relative to the entry file,
+so it resolves in any install layout — monorepo, pnpm, npm). This is the
+canonical Tailwind v4 pattern for a UI library: `@source` registers the files the
+consumer's Tailwind scans, and it survives the package manager because it never
+assumes the consumer's filesystem layout.
+
+This document is the contract between the library and every theme that renders
+it: the tokens blocks may reference, the status rule, and the documented
+exceptions.
 
 ## Contract tokens
 
@@ -72,6 +87,18 @@ Adding a color class not in this contract is a review-time violation. Theme
 authors verify pairs with `scripts/contrast-check.mjs` in the Thor Commerce
 repo, which asserts every pair in both themes meets AA.
 
+### Rule 5: The consumer registers the library source, and declares dark mode
+
+A conformant theme:
+
+- imports the package registration entry (`@import "@thorprovider/blocks/styles.css";`)
+  so block classes compile — never a monorepo-relative `@source "../../../packages/blocks/src"`;
+- defines the `dark` custom variant (`@custom-variant dark (&:is(.dark *));`) so
+  the library's `dark:` utilities activate.
+
+The scaffold template shipped by `@thorprovider/create-storefront` already does
+both; a hand-rolled theme MUST add them.
+
 ## Documented exceptions
 
 Two cases are legitimate and MUST NOT be converted to theme tokens:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thorprovider/blocks",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Reusable, framework-agnostic React component blocks for Thor Commerce storefronts.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,7 +18,8 @@
       "import": "./dist/contracts.mjs",
       "require": "./dist/contracts.js",
       "default": "./dist/contracts.mjs"
-    }
+    },
+    "./styles.css": "./styles.css"
   },
   "scripts": {
     "build": "tsup",
@@ -39,7 +40,7 @@
   "license": "MIT",
   "dependencies": {
     "@base-ui/react": "^1.8.0",
-    "@thorprovider/types": "^5.7.7",
+    "@thorprovider/types": "^5.7.9",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cn": "^0.4.0",

package/src/blocks/e-commerce/category-filters/category-filter-2-filter-panel.tsx

@@ -9,6 +9,7 @@ import { CheckboxCheck } from '../checkout-forms/checkbox-check'
 
 import type {
   CategoryFilter2Category,
+  CategoryFilter2Collection,
   CategoryFilter2Color,
   CategoryFilter2PriceRange,
 } from './category-filter-2'
@@ -18,14 +19,23 @@ interface CategoryFilter2FilterPanelProps {
   clearAllLabel?: string
   priceRangeTitle?: string
   priceRange: number[]
-  priceRangeConfig: CategoryFilter2PriceRange
+  /**
+   * Real backend-provided range only. When absent the price section is not
+   * rendered — the block never fabricates a `0..1000` range (E2 design
+   * Decision 8 / spec "Price controls require real price metadata").
+   */
+  priceRangeConfig?: CategoryFilter2PriceRange
   minLabel?: string
   maxLabel?: string
+  onPriceChange: (range: number[]) => void
   categoriesTitle?: string
   categories: CategoryFilter2Category[]
   selectedCategories: string[]
   onCategoryChange: (category: string, checked: boolean) => void
-  onPriceChange: (range: number[]) => void
+  collectionsTitle?: string
+  collections: CategoryFilter2Collection[]
+  selectedCollections: string[]
+  onCollectionChange: (collection: string, checked: boolean) => void
   sizesTitle?: string
   sizes: string[]
   selectedSize: string | null
@@ -45,11 +55,15 @@ export function CategoryFilter2FilterPanel({
   priceRangeConfig,
   minLabel = 'Mínimo',
   maxLabel = 'Máximo',
+  onPriceChange,
   categoriesTitle = 'Categoría',
   categories,
   selectedCategories,
   onCategoryChange,
-  onPriceChange,
+  collectionsTitle = 'Colección',
+  collections,
+  selectedCollections,
+  onCollectionChange,
   sizesTitle = 'Tamaño',
   sizes,
   selectedSize,
@@ -62,6 +76,7 @@ export function CategoryFilter2FilterPanel({
 }: CategoryFilter2FilterPanelProps) {
   const priceInputId = useId()
   const categoryInputId = useId()
+  const collectionInputId = useId()
 
   return (
     <>
@@ -74,106 +89,134 @@ export function CategoryFilter2FilterPanel({
         </div>
       </div>
 
-      <div className="mt-4 flex flex-col gap-4">
-        <CardTitle className="font-semibold">{priceRangeTitle}</CardTitle>
-        <div className="flex items-center gap-3">
-          <div className="flex flex-1 flex-col gap-1">
-            <label htmlFor={`${priceInputId}-min`}>{minLabel}</label>
-            <Input
-              id={`${priceInputId}-min`}
-              type="number"
-              value={priceRange[0]}
-              onChange={e => {
-                const value = parseInt(e.target.value)
-                if (!isNaN(value) && value >= priceRangeConfig.min) {
-                  onPriceChange([value, priceRange[1]])
-                }
-              }}
-              min={priceRangeConfig.min}
-              max={priceRange[1]}
-              step={priceRangeConfig.step}
-              className="h-9"
-            />
+      {priceRangeConfig ? (
+        <div className="mt-4 flex flex-col gap-4">
+          <CardTitle className="font-semibold">{priceRangeTitle}</CardTitle>
+          <div className="flex items-center gap-3">
+            <div className="flex flex-1 flex-col gap-1">
+              <label htmlFor={`${priceInputId}-min`}>{minLabel}</label>
+              <Input
+                id={`${priceInputId}-min`}
+                type="number"
+                value={priceRange[0] ?? priceRangeConfig.min}
+                onChange={e => {
+                  const value = parseInt(e.target.value)
+                  if (!isNaN(value) && value >= priceRangeConfig.min) {
+                    onPriceChange([value, priceRange[1] ?? priceRangeConfig.max])
+                  }
+                }}
+                min={priceRangeConfig.min}
+                max={priceRange[1] ?? priceRangeConfig.max}
+                step={priceRangeConfig.step}
+                className="h-9"
+              />
+            </div>
+            <div className="mt-5 flex-none">-</div>
+            <div className="flex flex-1 flex-col gap-1">
+              <label htmlFor={`${priceInputId}-max`}>{maxLabel}</label>
+              <Input
+                id={`${priceInputId}-max`}
+                type="number"
+                value={priceRange[1] ?? priceRangeConfig.max}
+                onChange={e => {
+                  const value = parseInt(e.target.value)
+                  if (!isNaN(value) && value <= priceRangeConfig.max) {
+                    onPriceChange([priceRange[0] ?? priceRangeConfig.min, value])
+                  }
+                }}
+                min={priceRange[0] ?? priceRangeConfig.min}
+                max={priceRangeConfig.max}
+                step={priceRangeConfig.step}
+                className="h-9"
+              />
+            </div>
           </div>
-          <div className="mt-5 flex-none">-</div>
-          <div className="flex flex-1 flex-col gap-1">
-            <label htmlFor={`${priceInputId}-max`}>{maxLabel}</label>
-            <Input
-              id={`${priceInputId}-max`}
-              type="number"
-              value={priceRange[1]}
-              onChange={e => {
-                const value = parseInt(e.target.value)
-                if (!isNaN(value) && value <= priceRangeConfig.max) {
-                  onPriceChange([priceRange[0], value])
-                }
-              }}
-              min={priceRange[0]}
-              max={priceRangeConfig.max}
-              step={priceRangeConfig.step}
-              className="h-9"
-            />
+        </div>
+      ) : null}
+
+      {categories.length > 0 ? (
+        <div className="mt-4 flex flex-col gap-4">
+          <CardTitle className="font-semibold">{categoriesTitle}</CardTitle>
+          <div className="flex flex-col gap-2">
+            {categories.map(category => (
+              <div key={category.id} className="flex items-center gap-2">
+                <CheckboxCheck
+                  id={`${categoryInputId}-${category.id}`}
+                  checked={selectedCategories.includes(category.id)}
+                  onCheckedChange={checked => onCategoryChange(category.id, checked as boolean)}
+                />
+                <label htmlFor={`${categoryInputId}-${category.id}`} className="text-sm">
+                  {category.label}
+                </label>
+              </div>
+            ))}
           </div>
         </div>
-      </div>
+      ) : null}
 
-      <div className="mt-4 flex flex-col gap-4">
-        <CardTitle className="font-semibold">{categoriesTitle}</CardTitle>
-        <div className="flex flex-col gap-2">
-          {categories.map(category => (
-            <div key={category.id} className="flex items-center gap-2">
-              <CheckboxCheck
-                id={`${categoryInputId}-${category.id}`}
-                checked={selectedCategories.includes(category.id)}
-                onCheckedChange={checked => onCategoryChange(category.id, checked as boolean)}
-              />
-              <label htmlFor={`${categoryInputId}-${category.id}`} className="text-sm">
-                {category.label}
-              </label>
-            </div>
-          ))}
+      {collections.length > 0 ? (
+        <div className="mt-4 flex flex-col gap-4">
+          <CardTitle className="font-semibold">{collectionsTitle}</CardTitle>
+          <div className="flex flex-col gap-2">
+            {collections.map(collection => (
+              <div key={collection.id} className="flex items-center gap-2">
+                <CheckboxCheck
+                  id={`${collectionInputId}-${collection.id}`}
+                  checked={selectedCollections.includes(collection.id)}
+                  onCheckedChange={checked => onCollectionChange(collection.id, checked as boolean)}
+                />
+                <label htmlFor={`${collectionInputId}-${collection.id}`} className="text-sm">
+                  {collection.label}
+                </label>
+              </div>
+            ))}
+          </div>
         </div>
-      </div>
+      ) : null}
 
-      <div className="mt-4 flex flex-col gap-4">
-        <CardTitle className="font-semibold">{sizesTitle}</CardTitle>
-        <div className="flex flex-wrap gap-2">
-          {sizes.map(size => (
-            <Button
-              key={size}
-              variant={selectedSize === size ? 'default' : 'outline'}
-              size="sm"
-              className="h-8 cursor-pointer px-3 text-xs"
-              onClick={() => onSizeChange(size === selectedSize ? null : size)}
-              aria-pressed={selectedSize === size}
-            >
-              {size}
-            </Button>
-          ))}
+      {sizes.length > 0 ? (
+        <div className="mt-4 flex flex-col gap-4">
+          <CardTitle className="font-semibold">{sizesTitle}</CardTitle>
+          <div className="flex flex-wrap gap-2">
+            {sizes.map(size => (
+              <Button
+                key={size}
+                variant={selectedSize === size ? 'default' : 'outline'}
+                size="sm"
+                className="h-8 cursor-pointer px-3 text-xs"
+                onClick={() => onSizeChange(size === selectedSize ? null : size)}
+                aria-pressed={selectedSize === size}
+              >
+                {size}
+              </Button>
+            ))}
+          </div>
         </div>
-      </div>
+      ) : null}
 
-      <div className="mt-4 flex flex-col gap-4">
-        <CardTitle className="font-semibold">{colorsTitle}</CardTitle>
-        <div className="flex flex-wrap gap-2">
-          {colors.map(color => (
-            <Button
-              key={color.id}
-              onClick={() => onColorChange(color.id === selectedColor ? null : color.id)}
-              className={`relative size-8 cursor-pointer rounded-sm transition-transform duration-200 ${
-                selectedColor === color.id ? 'ring-primary scale-105 ring-2' : 'hover:ring-foreground/20 hover:ring-1'
-              } ${color.id === 'white' ? 'border-border border' : ''}`}
-              style={{ backgroundColor: color.color }}
-              aria-pressed={selectedColor === color.id}
-              aria-label={color.id}
-            >
-              {selectedColor === color.id && <div className="border-background absolute inset-0 rounded-sm border-2" />}
-            </Button>
-          ))}
+      {colors.length > 0 ? (
+        <div className="mt-4 flex flex-col gap-4">
+          <CardTitle className="font-semibold">{colorsTitle}</CardTitle>
+          <div className="flex flex-wrap gap-2">
+            {colors.map(color => (
+              <Button
+                key={color.id}
+                onClick={() => onColorChange(color.id === selectedColor ? null : color.id)}
+                className={`relative size-8 cursor-pointer rounded-sm transition-transform duration-200 ${
+                  selectedColor === color.id ? 'ring-primary scale-105 ring-2' : 'hover:ring-foreground/20 hover:ring-1'
+                } ${color.id === 'white' ? 'border-border border' : ''}`}
+                style={{ backgroundColor: color.color }}
+                aria-pressed={selectedColor === color.id}
+                aria-label={color.id}
+              >
+                {selectedColor === color.id && <div className="border-background absolute inset-0 rounded-sm border-2" />}
+              </Button>
+            ))}
+          </div>
         </div>
-      </div>
+      ) : null}
     </>
   )
 }
 
-export default CategoryFilter2FilterPanel
+export default CategoryFilter2FilterPanel