@86d-app/products 0.0.3

package/AGENTS.md

@@ -0,0 +1,65 @@
+# Products Module
+
+Product catalog with variants and hierarchical categories. Full CRUD for admin, read-only browsing and search for storefront.
+
+## Structure
+
+```
+src/
+  index.ts          Factory: products(options?) => Module + admin nav registration
+  schema.ts         Zod models: product, productVariant, category
+  controllers.ts    All business logic (product, variant, category controllers)
+  components/
+    store/          Customer-facing MDX components
+      index.tsx     ProductCard, ProductGrid, CategoryList, CategoryItem (.tsx logic)
+      *.mdx         Store template variants
+    admin/          Store admin MDX components
+      index.tsx     Product table, product editor, category manager (.tsx logic)
+      *.mdx         Admin template variants
+  endpoints/
+    store/          Customer-facing (6 endpoints)
+      list-products.ts      GET  /products
+      get-product.ts        GET  /products/:id (by ID or slug)
+      get-featured.ts       GET  /products/featured
+      search-products.ts    GET  /products/search?q=
+      list-categories.ts    GET  /categories
+      get-category.ts       GET  /categories/:id
+    admin/          Protected (12 endpoints)
+      create-product.ts     POST   /admin/products
+      list-products.ts      GET    /admin/products/list
+      get-product.ts        GET    /admin/products/:id
+      update-product.ts     PUT    /admin/products/:id
+      delete-product.ts     DELETE /admin/products/:id
+      create-variant.ts     POST   /admin/products/:productId/variants
+      update-variant.ts     PUT    /admin/variants/:id
+      delete-variant.ts     DELETE /admin/variants/:id
+      create-category.ts    POST   /admin/categories
+      list-categories.ts    GET    /admin/categories/list
+      update-category.ts    PUT    /admin/categories/:id
+      delete-category.ts    DELETE /admin/categories/:id
+```
+
+## Options
+
+```ts
+ProductsOptions {
+  defaultPageSize?: number   // default 20
+  maxPageSize?: number       // default 100
+  trackInventory?: boolean   // default true
+}
+```
+
+## Data models
+
+- **product**: id, name, slug (unique), price, compareAtPrice, costPrice, sku?, inventory, status (draft|active|archived), categoryId?, images[], tags[], isFeatured, weight/weightUnit
+- **productVariant**: id, productId (FK cascade), name, sku?, price, inventory, options (Record<string,string> for size/color/etc.), position
+- **category**: id, name, slug (unique), parentId? (self-referential for hierarchy), position, isVisible
+
+## Patterns
+
+- Uses core data layer directly (no adapter) — `data.get()`, `data.findMany()`, `data.upsert()`, `data.delete()`
+- Product IDs: `prod_${timestamp}`, variant IDs: `var_${timestamp}`
+- Store endpoints only return active products; admin endpoints return all statuses
+- Variant writes also update parent product's `updatedAt`
+- Category deletion orphans children and products (sets their categoryId to null)
+- `getTree()` builds hierarchical category structure from flat list

package/COMPONENTS.md

@@ -0,0 +1,231 @@
+# Products Module — Store Components
+
+Components exported for use in store MDX templates. Import via the component registry (auto-registered when the module is in `templates/brisa/config.json`).
+
+## ProductCard
+
+Displays a single product card with image, name, price, discount badge, and optional "Add to Cart" button.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `product` | `Product` | — | Product object with id, name, slug, price, images, etc. |
+| `showAddToCart` | `boolean` | `true` | Show the "Add to Cart" button |
+
+### Usage in MDX
+
+```mdx
+<ProductCard product={product} />
+
+<ProductCard product={product} showAddToCart={false} />
+```
+
+## FeaturedProducts
+
+Displays a responsive grid of featured products. Fetches its own data.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `limit` | `number` | — | Max number of featured products to display |
+| `title` | `string` | — | Section heading |
+
+### Usage in MDX
+
+```mdx
+<FeaturedProducts />
+
+<FeaturedProducts limit={4} title="Staff Picks" />
+```
+
+## ProductListing
+
+Full product listing with search, category/price/stock/tag filters, sorting, and pagination. Fetches its own data.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `initialCategory` | `string` | — | Pre-select a category filter |
+| `initialSearch` | `string` | — | Pre-fill the search query |
+| `pageSize` | `number` | — | Products per page |
+
+### Usage in MDX
+
+```mdx
+<ProductListing />
+
+<ProductListing initialCategory="shoes" pageSize={12} />
+```
+
+## ProductDetail
+
+Full product detail page with image gallery, variant selector, pricing, inventory status, reviews, and related products. Fetches its own data.
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `slug` | `string` | Product slug (from URL) |
+| `params` | `Record<string, string>` | Route params (params.slug) |
+
+### Usage
+
+Loaded dynamically by the store catch-all route for `/products/:slug`.
+
+## RelatedProducts
+
+Horizontal grid of related products for a given product. Fetches its own data.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `productId` | `string` | — | Product ID to find related products for |
+| `limit` | `number` | — | Max related products to show |
+| `title` | `string` | — | Section heading |
+
+### Usage in MDX
+
+```mdx
+<RelatedProducts productId={product.id} />
+
+<RelatedProducts productId={product.id} limit={4} title="You may also like" />
+```
+
+## CollectionCard
+
+Displays a single collection card with image, name, and description.
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `collection` | `CollectionCardData` | Collection object with id, name, slug, description, image |
+
+### Usage in MDX
+
+```mdx
+<CollectionCard collection={collection} />
+```
+
+## CollectionGrid
+
+Grid of collections with optional featured-only filtering. Fetches its own data.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | — | Section heading |
+| `featured` | `boolean` | — | Only show featured collections |
+
+### Usage in MDX
+
+```mdx
+<CollectionGrid />
+
+<CollectionGrid title="Shop by Category" featured={true} />
+```
+
+## CollectionDetail
+
+Full collection page with image, description, product count, and products grid. Fetches its own data.
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `slug` | `string` | Collection slug (from URL) |
+| `params` | `Record<string, string>` | Route params (params.slug) |
+
+### Usage
+
+Loaded dynamically by the store catch-all route for `/collections/:slug`.
+
+## FilterChip
+
+Small removable tag displaying an active filter. Used internally by ProductListing.
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `label` | `string` | Filter display text |
+| `onRemove` | `() => void` | Callback when the chip is dismissed |
+
+### Usage in MDX
+
+```mdx
+<FilterChip label="Shoes" onRemove={handleRemove} />
+```
+
+## StarDisplay
+
+Read-only star rating display.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `rating` | `number` | — | Rating value (0–5) |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Star size |
+
+### Usage in MDX
+
+```mdx
+<StarDisplay rating={4.5} />
+
+<StarDisplay rating={product.averageRating} size="sm" />
+```
+
+## StarPicker
+
+Interactive star rating input for review submission.
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `number` | Current rating value |
+| `onChange` | `(n: number) => void` | Callback when user selects a rating |
+
+### Usage in MDX
+
+```mdx
+<StarPicker value={rating} onChange={setRating} />
+```
+
+## StockBadge
+
+Inventory status badge. Shows "Out of stock", "Only X left", or "In stock".
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `inventory` | `number` | Available inventory count |
+
+### Usage in MDX
+
+```mdx
+<StockBadge inventory={product.inventory} />
+```
+
+## ProductReviewsSection
+
+Complete review section with rating summary, review list with pagination, and review submission form. Fetches its own data.
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `productId` | `string` | Product ID to show reviews for |
+
+### Usage in MDX
+
+```mdx
+<ProductReviewsSection productId={product.id} />
+```

package/README.md

@@ -0,0 +1,201 @@
+<p align="center">
+  <a href="https://86d.app">
+    <img src="https://86d.app/logo" height="96" alt="86d" />
+  </a>
+</p>
+
+<p align="center">
+  Dynamic Commerce
+</p>
+
+<p align="center">
+  <a href="https://vercel.com/changelog"><strong>npm</strong></a> ·
+  <a href="https://x.com/86d_app"><strong>X</strong></a> ·
+  <a href="https://vercel.com/templates"><strong>LinkedIn</strong></a>
+</p>
+<br/>
+
+> [!WARNING]
+> This project is under active development and is not ready for production use. Please proceed with caution. Use at your own risk.
+
+# @86d-app/products
+
+Product catalog module with variants and hierarchical categories. Full CRUD for the admin panel and read-only browsing with search and filtering for the storefront.
+
+## Installation
+
+```sh
+npm install @86d-app/products
+```
+
+## Usage
+
+```ts
+import products from "@86d-app/products";
+
+const module = products({
+  defaultPageSize: 20,
+  maxPageSize: 100,
+  trackInventory: true,
+});
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `defaultPageSize` | `number` | `20` | Default number of products per page |
+| `maxPageSize` | `number` | `100` | Maximum products per page |
+| `trackInventory` | `boolean` | `true` | Enable inventory tracking by default |
+
+## Store Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/products` | List active products (paginated, filterable) |
+| `GET` | `/products/featured` | Get featured products |
+| `GET` | `/products/:slug` | Get a single product by slug (includes variants) |
+| `GET` | `/products/search?q=` | Search products by name, description, or SKU |
+| `GET` | `/categories` | List visible categories |
+| `GET` | `/categories/:slug` | Get a single category by slug |
+
+Query parameters for `GET /products`:
+
+| Param | Type | Description |
+|---|---|---|
+| `page` | `number` | Page number (default `1`) |
+| `limit` | `number` | Items per page (capped at `maxPageSize`) |
+| `category` | `string` | Filter by category slug |
+| `status` | `string` | Product status (storefront always uses `active`) |
+| `featured` | `boolean` | Filter featured products |
+
+## Admin Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| `POST` | `/admin/products` | Create a new product |
+| `GET` | `/admin/products/list` | List all products (all statuses) |
+| `GET` | `/admin/products/:id` | Get a product by ID |
+| `PUT` | `/admin/products/:id` | Update a product |
+| `DELETE` | `/admin/products/:id` | Delete a product |
+| `POST` | `/admin/products/:productId/variants` | Add a variant to a product |
+| `PUT` | `/admin/variants/:id` | Update a variant |
+| `DELETE` | `/admin/variants/:id` | Delete a variant |
+| `POST` | `/admin/categories` | Create a category |
+| `GET` | `/admin/categories/list` | List all categories |
+| `PUT` | `/admin/categories/:id` | Update a category |
+| `DELETE` | `/admin/categories/:id` | Delete a category |
+
+## Controller API
+
+Controllers are accessed via the runtime context. Three sub-controllers are available: `product`, `variant`, and `category`.
+
+```ts
+// product controller
+context.controllers.product.getById(ctx)        // Product | null
+context.controllers.product.getBySlug(ctx)       // Product | null
+context.controllers.product.getWithVariants(ctx) // ProductWithVariants | null
+context.controllers.product.list(ctx)            // { products: Product[]; total: number }
+context.controllers.product.create(ctx)          // Product
+context.controllers.product.update(ctx)          // Product | null
+context.controllers.product.delete(ctx)          // void
+
+// variant controller
+context.controllers.variant.create(ctx)          // ProductVariant
+context.controllers.variant.update(ctx)          // ProductVariant | null
+context.controllers.variant.delete(ctx)          // void
+
+// category controller
+context.controllers.category.getById(ctx)        // Category | null
+context.controllers.category.getBySlug(ctx)      // Category | null
+context.controllers.category.list(ctx)           // { categories: Category[]; total: number }
+context.controllers.category.getTree(ctx)        // Category[]  (hierarchical)
+context.controllers.category.create(ctx)         // Category
+context.controllers.category.update(ctx)         // Category | null
+context.controllers.category.delete(ctx)         // void
+```
+
+Each controller method receives a `ctx` object:
+
+```ts
+{
+  context: { data: ModuleDataService };
+  params: Record<string, string>;
+  query: Record<string, string>;
+  body: Record<string, unknown>;
+}
+```
+
+## Types
+
+```ts
+interface Product {
+  id: string;
+  name: string;
+  slug: string;
+  description?: string;
+  shortDescription?: string;
+  price: number;               // in cents
+  compareAtPrice?: number;
+  costPrice?: number;
+  sku?: string;
+  barcode?: string;
+  inventory: number;
+  trackInventory: boolean;
+  allowBackorder: boolean;
+  status: "draft" | "active" | "archived";
+  categoryId?: string;
+  images: string[];
+  tags: string[];
+  isFeatured: boolean;
+  weight?: number;
+  weightUnit?: "kg" | "lb" | "oz" | "g";
+  metadata?: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+interface ProductVariant {
+  id: string;
+  productId: string;
+  name: string;
+  sku?: string;
+  price: number;
+  compareAtPrice?: number;
+  costPrice?: number;
+  inventory: number;
+  options: Record<string, string>; // e.g. { size: "M", color: "Blue" }
+  images: string[];
+  position: number;
+  weight?: number;
+  weightUnit?: "kg" | "lb" | "oz" | "g";
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+interface Category {
+  id: string;
+  name: string;
+  slug: string;
+  description?: string;
+  parentId?: string;           // Self-referential for nested categories
+  image?: string;
+  position: number;
+  isVisible: boolean;
+  metadata?: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+interface ProductWithVariants extends Product {
+  variants: ProductVariant[];
+  category?: Category;
+}
+```
+
+## Notes
+
+- Store endpoints return only `active` products; admin endpoints return all statuses (`draft`, `active`, `archived`).
+- Product IDs are prefixed: `prod_${timestamp}`. Variant IDs: `var_${timestamp}`.
+- Deleting a category orphans its child categories and products (sets `categoryId` to `null`) rather than cascading.
+- `getTree()` builds a hierarchical category tree from the flat list using `parentId` references.

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@86d-app/products",
+	"version": "0.0.3",
+	"description": "Product catalog module for 86d commerce platform",
+	"keywords": [
+		"commerce",
+		"products",
+		"catalog",
+		"categories",
+		"86d"
+	],
+	"license": "MIT",
+	"author": "86d <chat@86d.app>",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/86d-app/86d.git",
+		"directory": "modules/products"
+	},
+	"homepage": "https://github.com/86d-app/86d/tree/main/modules/products",
+	"type": "module",
+	"exports": {
+		"./components": "./src/store/components",
+		"./admin-components": "./src/admin/components",
+		"./*": "./src/*"
+	},
+	"scripts": {
+		"build": "tsc",
+		"check": "biome check src",
+		"check:fix": "biome check --write src",
+		"clean": "git clean -xdf .cache .turbo dist node_modules",
+		"dev": "tsc",
+		"test": "vitest run",
+		"test:watch": "vitest watch",
+		"typecheck": "tsc --noEmit --emitDeclarationOnly false"
+	},
+	"dependencies": {
+		"@86d-app/core": "workspace:*"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "catalog:",
+		"@types/mdx": "catalog:mdx",
+		"@types/react": "catalog:react",
+		"typescript": "catalog:",
+		"vitest": "catalog:vite"
+	}
+}