@feeef.dev/cli 0.2.0

package/scaffolds/blank/docs/14-FILTERATOR.md

@@ -0,0 +1,433 @@
+# Filterator & Product / Category Lists
+
+> Theme package copy — paths assume this theme folder is the project root.
+
+Canonical contract for **structured queries** and **list APIs** so AI can build creative PLPs, related products, search, carousels, and admin-grade filters.
+
+---
+
+## 1. Mental model
+
+Two ways to query products:
+
+```text
+A) Flat query params   →  ProductFilter methods (q, category_id, price_min, in_stock, …)
+B) Filterator JSON     →  nested AND/OR tree + ordering + paging  (?filterator=<json>)
+```
+
+Categories use **flat params only** (no filterator today).
+
+In **custom / Dawn JSX** (react-live):
+
+```jsx
+const ff = useFeeef();
+const storeCtx = useStore();
+const store = storeCtx?.store;
+if (!ff || !store) return null;
+
+const res = await ff.products.list({
+  params: {
+    store_id: store.id,
+    limit: 24,
+    page: 1,
+    // flat filters and/or:
+    filterator: JSON.stringify({ filtering: { … }, ordering: […], paging: {…} }),
+  },
+});
+const products = res?.data || res || [];
+```
+
+Always pass **`store_id`**. Prefer flat params for simple UIs; use **filterator** for nested OR/AND, `inList`, null checks, multi-field sorts.
+
+---
+
+## 2. Filterator query shape
+
+```ts
+type ProductFilteratorQuery = {
+  filtering?: {
+    condition: 'and' | 'or'
+    filters?: FilteratorFilter[]
+    groups?: FilteratorFilteringGroup[]   // nested trees
+  }
+  ordering?: Array<{ field: string; dir: 'asc' | 'desc' }>
+  paging?: { limit?: number; offset?: number; cursor?: string }
+}
+
+type FilteratorFilter = {
+  field: string                 // camelCase → snake_case DB column
+  operation: QueryOperation
+  value?: unknown               // single-value ops
+  values?: unknown[]            // inList / notIn
+}
+```
+
+Send as query param:
+
+```
+GET /products?store_id=…&filterator=<URL-encoded JSON string>
+```
+
+Via SDK:
+
+```js
+ff.products.list({
+  params: {
+    store_id: store.id,
+    filterator: JSON.stringify(query),
+  },
+})
+```
+
+### Operators (prefer long names in AI output)
+
+| Operation | Aliases | SQL | Notes |
+|---|---|---|---|
+| `equals` | `eq` | `=` | Prefer for exact match |
+| `notEquals` | `neq` | `!=` | |
+| `contains` | — | `LIKE %v%` | Text |
+| `startsWith` | — | `LIKE v%` | |
+| `endsWith` | — | `LIKE %v` | |
+| `greaterThan` | `gt` | `>` | Numbers / dates |
+| `greaterOrEqual` / `greaterThanOrEqual` | `gte` | `>=` | |
+| `lessThan` | `lt` | `<` | |
+| `lessOrEqual` / `lessThanOrEqual` | `lte` | `<=` | |
+| `inList` | `in` | `IN (…)`, use **`values`** | |
+| `notIn` | — | `NOT IN (…)`, use **`values`** | |
+| `isNull` | — | `IS NULL` | No value needed |
+| `isNotNull` | — | `IS NOT NULL` | |
+
+**Products filterator** (`ProductFilter.filterator`) accepts short + long aliases.  
+**Generic `filterator_apply.ts`** prefers **long** names — when in doubt use `equals`, `greaterThan`, `inList`.
+
+### Field mapping
+
+- `categoryId` → `category_id`, `createdAt` → `created_at`, etc. (`string.snakeCase`)
+- Exception: `type` / `productType` → column **`type`** (not `product_type`)
+
+Useful product fields: `id`, `slug`, `name`, `sku`, `price`, `cost`, `discount`, `stock`, `sold`, `views`, `likes`, `status`, `type`, `categoryId`, `storeId`, `createdAt`, `updatedAt`, `photoUrl`, …
+
+### Nested AND / OR
+
+```json
+{
+  "filtering": {
+    "condition": "or",
+    "filters": [
+      { "field": "name", "operation": "contains", "value": "shirt" }
+    ],
+    "groups": [
+      {
+        "condition": "and",
+        "filters": [
+          { "field": "price", "operation": "greaterThan", "value": 1000 },
+          { "field": "sold", "operation": "greaterThan", "value": 10 }
+        ]
+      }
+    ]
+  },
+  "ordering": [{ "field": "sold", "dir": "desc" }],
+  "paging": { "limit": 24, "offset": 0 }
+}
+```
+
+Meaning: *(name contains shirt) **OR** (price > 1000 **AND** sold > 10)*, sorted by sold desc.
+
+---
+
+## 3. Products — flat query params
+
+`GET /products` — implemented in `ProductFilter`. camelCase / snake_case aliases exist for most.
+
+| Param | Also | Meaning |
+|---|---|---|
+| `store_id` | `storeId`, `store_ids` | **Required** for storefront |
+| `q` | `search` | Search name, slug, id, description, sku |
+| `status` / `statuses` | | `published` / `draft` / `archived` / `deleted`; `!published` excludes |
+| `category_id` | `categoryId` | Category id (preferred) |
+| `category` | | id **or** embedded slug (compat) |
+| `category_slug` | `categorySlug` | Embedded slug only |
+| `price_min` / `price_max` | `priceMin` / `priceMax` | Price range |
+| `stock_min` / `stock_max` | | Stock range |
+| `in_stock` | `inStock` | `true` → stock > 0; `!true` → out |
+| `has_media` / `has_photo` | | Media / cover present |
+| `variant` | `variantPresent` | Has variants |
+| `sku` / `barcode` | | Partial match |
+| `sold_min` | | Min sold (or `true` → sold > 0) |
+| `created_after` / `before` | | ISO dates |
+| `updated_after` / `before` | | |
+| `ids` | `products` | Whitelist ids |
+| `published` | | Exclude archived |
+| `random` | | `ORDER BY RANDOM()` (+ media) |
+| `order_by` | `orderBy` | `field:dir` e.g. `price:desc` |
+| `page` / `limit` | | Pagination (limit often default 20) |
+| `filterator` | | JSON string — §2 |
+
+### SDK helpers (`feeef.js`)
+
+```ts
+ff.products.list({
+  storeId, categoryId, status, q,
+  minPrice, maxPrice, inStock,   // maps to min_price / max_price — prefer params.price_min for backend certainty
+  sortBy: 'price' | 'createdAt' | 'sold' | 'views',
+  sortOrder: 'asc' | 'desc',
+  page, limit,
+  params: { /* escape hatch — price_min, filterator, … */ },
+})
+
+ff.products.random(12)
+ff.products.find({ id: slug, by: 'slug' })
+```
+
+**Gotcha:** SDK `minPrice` → `min_price`, but Lucid filter methods are `price_min` / `priceMax`. In custom JSX prefer:
+
+```js
+params: { store_id, price_min: 1000, price_max: 5000, in_stock: true }
+```
+
+### Response
+
+```ts
+{ data: ProductEntity[], meta?: { total, currentPage, perPage, … } }
+// or ProductEntity[] depending on client path — always normalize:
+const list = Array.isArray(res) ? res : (res?.data ?? [])
+```
+
+### ProductEntity (UI-critical)
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` / `slug` | string | Links: `/products/${slug \|\| id}` |
+| `name` / `title` | string\|null | |
+| `photoUrl` | string\|null | Cover |
+| `media` | **`string[]`** | URL strings — **not** `{url}` objects |
+| `price` / `discount` / `stock` / `sold` | number | |
+| `categoryId` / `category` | | |
+| `offers` / `variant` / `addons` | | Upsell / COD |
+| `status` | | Guests usually only see published |
+| `body` | | Markdown only |
+
+---
+
+## 4. Categories — list request
+
+```
+GET /categories?store_id=…&parent_id=…&page&limit
+GET /categories/tree?store_id=…
+```
+
+| Param | Meaning |
+|---|---|
+| `store_id` | **Required** |
+| `parent_id` | Parent id; `null` / `'null'` → roots |
+| `q` | Search (SDK) |
+| `page` / `limit` | Pagination (default limit often 50) |
+
+**No `filterator` on categories.**
+
+SDK:
+
+```js
+ff.categories.list({ storeId: store.id, parentId: null, limit: 50 })
+ff.categories.listRootCategories(store.id)
+ff.categories.listChildren(store.id, parentId)
+```
+
+Entity: `id`, `name`, `photoUrl`, `parentId`, `metadata`, children/parent when tree/show.
+
+---
+
+## 5. Creative recipes (AI playbook)
+
+### A. Products page (PLP) with URL filters
+
+```jsx
+const searchParams = useSearchParams();
+const categoryId = searchParams?.get('category_id') || '';
+const q = searchParams?.get('q') || '';
+const page = Number(searchParams?.get('page') || 1);
+
+ff.products.list({
+  params: {
+    store_id: store.id,
+    limit: 24,
+    page,
+    category_id: categoryId || undefined,
+    q: q || undefined,
+    search: q || undefined,       // dual-send for compat
+    in_stock: true,               // server-side availability
+    price_min: priceFrom || undefined,
+    price_max: priceTo || undefined,
+    order_by: 'sold:desc',
+  },
+});
+```
+
+Prefer **server** `in_stock` / `price_min` / `price_max` over filtering the array in memory (Dawn grid historically did client-side — avoid for large catalogs).
+
+### B. Related products (same category)
+
+There is **no** `/related` endpoint. Pattern:
+
+```jsx
+const { product } = useCurrentProduct();
+const cat = product?.categoryId;
+const res = await ff.products.list({
+  params: {
+    store_id: store.id,
+    category_id: cat,
+    limit: 8,
+    in_stock: true,
+  },
+});
+const related = (res?.data || []).filter((p) => p.id !== product.id);
+```
+
+Fallbacks: `ff.products.random(8)` or bestsellers `order_by: 'sold:desc'`.
+
+### C. “Bestsellers under 5000”
+
+```js
+filterator: JSON.stringify({
+  filtering: {
+    condition: 'and',
+    filters: [
+      { field: 'price', operation: 'lessOrEqual', value: 5000 },
+      { field: 'stock', operation: 'greaterThan', value: 0 },
+      { field: 'status', operation: 'equals', value: 'published' },
+    ],
+  },
+  ordering: [{ field: 'sold', dir: 'desc' }],
+  paging: { limit: 12 },
+})
+```
+
+### D. Multi-category spotlight (`inList`)
+
+```js
+{
+  field: 'categoryId',
+  operation: 'inList',
+  values: [idA, idB, idC],
+}
+```
+
+### E. New arrivals with media
+
+```js
+params: {
+  store_id: store.id,
+  has_media: true,
+  order_by: 'created_at:desc',
+  limit: 12,
+}
+```
+
+### F. Category nav + product grid
+
+1. `ff.categories.listRootCategories(store.id)` → chips  
+2. On select → set `?category_id=` via `router.push` / `useSearchParams`  
+3. Reload products with `category_id`
+
+### G. Search as you type
+
+Debounce `q` (≥300ms), keep `limit` modest (12–24), show loading skeleton. Send both `q` and `search`.
+
+### H. Infinite scroll
+
+Use `page` + `meta.lastPage` / `meta.total`, or TanStack `useInfiniteProductsQuery` in native TSX. In react-live, track `page` in `React.useState` and append `data`.
+
+---
+
+## 6. Custom JSX rules
+
+| Do | Don’t |
+|---|---|
+| Null-check `ff` / `store` | Assume hooks always return data |
+| `store_id: store.id` on every list | Omit store scope |
+| `product.media` as `string[]` | `product.media[0].url` |
+| `RouterNav` / `Link` to `/p/${slug}` | Hardcode `/products/${slug}` for PDP (alias only; prefer `/p/`) |
+| Server filters (`in_stock`, `price_min`, filterator) | Fetch 200 and filter in JS for PLP |
+| `React.useEffect` for fetches + cancel/ignore flag | Fire list on every render without deps |
+
+Fetch skeleton:
+
+```jsx
+function App() {
+  const ff = useFeeef();
+  const storeCtx = useStore();
+  const store = storeCtx?.store;
+  const [items, setItems] = React.useState([]);
+  const [loading, setLoading] = React.useState(true);
+
+  React.useEffect(() => {
+    let alive = true;
+    if (!ff || !store?.id) { setLoading(false); return; }
+    setLoading(true);
+    ff.products.list({
+      params: { store_id: store.id, limit: 12, in_stock: true, order_by: 'sold:desc' },
+    }).then((res) => {
+      if (!alive) return;
+      setItems(Array.isArray(res) ? res : (res?.data ?? []));
+      setLoading(false);
+    }).catch(() => { if (alive) setLoading(false); });
+    return () => { alive = false; };
+  }, [ff, store?.id]);
+
+  if (loading) return <div>…</div>;
+  return (
+    <div>
+      {items.map((p) => (
+        <RouterNav key={p.id} href={'/products/' + (p.slug || p.id)}>
+          <img src={p.photoUrl || (p.media && p.media[0]) || ''} alt={p.name || ''} />
+          <span>{p.name}</span>
+        </RouterNav>
+      ))}
+    </div>
+  );
+}
+```
+
+---
+
+## 7. Guest visibility & security
+
+- Unauthenticated storefront typically **hides archived** products.
+- Never expose owner-only draft tooling in public custom JSX.
+- Filterator is a query language, not auth — still scoped by `store_id` and backend policies.
+
+---
+
+## 8. Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| Client-only availability/price on full catalog | `in_stock`, `price_min`/`price_max`, or filterator |
+| `min_price` from SDK without verifying | Use `params.price_min` |
+| Related = copy Shopify recommendations API | Same-category list / random / sold |
+| `product.media[i].url` | `product.media[i]` string |
+| Missing `store_id` | Always set |
+| Huge `limit` (500+) for decorative carousels | Cap 8–24; use random/bestsellers |
+| Short ops only on shared apply helper | Prefer long op names |
+
+---
+
+## 9. Quick reference — when to use what
+
+| Goal | Tool |
+|---|---|
+| Simple category + search PLP | Flat `category_id` + `q` + `page`/`limit` |
+| In stock / price band | `in_stock`, `price_min`, `price_max` |
+| Nested logic / multi-id / null checks | **filterator** |
+| Related on PDP | Same `category_id`, exclude current id |
+| Surprise grid | `random=true` or `ff.products.random(n)` |
+| Category menu | `ff.categories.listRootCategories` / tree |
+| Featured / offers | List then `p.offers?.length` **or** filterator on known fields |
+
+---
+
+## Related
+
+- Scope API: `docs/03-CUSTOM-COMPONENTS.md`
+- Product PDP pages: [11-PAGES-CHECKOUT-THANKS-PRODUCT.md](./11-PAGES-CHECKOUT-THANKS-PRODUCT.md)
+- Theme porting PLP notes: [09-THEME-PORTING.md](./09-THEME-PORTING.md)

package/scaffolds/blank/docs/16-AUTHORING-TS-IMPORTS.md

@@ -0,0 +1,73 @@
+# Authoring with TypeScript & imports
+
+> Theme package copy — paths assume this theme folder is the project root.
+
+Theme components can use **TypeScript** and **ESM imports**. At `feeef template build`
+(or `npm run build`), the kit compiles them into a react-live `code` string that still
+exposes top-level `function App()` — the same contract as plain JSX.
+
+## What you write
+
+```
+# Preferred (page-level → sections.main)
+pages/home/components/hero.tsx
+
+# Folder when you need colocated helpers or slots/children
+pages/home/components/hero/
+  component.tsx
+  labels.ts
+
+# Legacy multi-section (still supported)
+pages/home/sections/main/components/hero.tsx
+```
+
+```tsx
+import clsx from "clsx";
+import { bannerLabel } from "./labels";
+
+function App(): JSX.Element {
+  const text: string = bannerLabel("Feeef");
+  return <div className={clsx("hero")}>{text}</div>;
+}
+```
+
+## What the storefront receives
+
+Build emits bundled / transpiled JS with:
+
+- No top-level `import` / `export` (react-live cannot resolve modules)
+- Top-level `function App()` (wrapper around the bundled module when imports exist)
+- `react` / `react-dom` **external** — CustomLive injects `React` in scope
+
+Do **not** `import React from "react"` for JSX; use the live scope (or rely on the
+classic `React.createElement` transform from the bundler).
+
+## npm dependencies
+
+1. Theme folder is a Node package (`package.json` from `feeef template init`).
+2. Install deps at the **theme root**:
+
+```bash
+cd my-theme
+npm install clsx          # example
+```
+
+3. Import normally in the component file. The compiler walks up to `feeef.template.json`
+   and resolves from that theme’s `node_modules`.
+
+`react` stays provided by the storefront — add it only if you need types
+(`npm i -D @types/react`), not as a runtime bundle target.
+
+## Plain JSX (legacy)
+
+`component.jsx` with **no** imports is copied into `code` unchanged (fast path).
+
+## Init
+
+This package came from `feeef template init`. Re-read `AGENTS.md` after upgrading the CLI.
+
+## Do not
+
+- Expect browser-side bundling of theme `node_modules` — only build-time inlining
+- Bundle `react` into component `code`
+- Rely on Node builtins or server-only packages inside components

package/scaffolds/blank/feeef.template.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://feeef.org/schemas/template.schema.json",
+  "name": "my-theme",
+  "version": "0.1.0",
+  "defaultLocale": "en",
+  "pages": ["home"]
+}

package/scaffolds/blank/locales/README.md

@@ -0,0 +1,4 @@
+# Theme locales
+
+One JSON file per language. Built into `data.i18n` / uploaded to `store_template_locales`.
+Use `t('home.heroHeading')` in component JSX.

package/scaffolds/blank/locales/ar.json

@@ -0,0 +1,10 @@
+{
+  "home": {
+    "heroHeading": "مرحبا",
+    "heroText": "ثيم Feeef الخاص بك",
+    "shopNow": "تسوق الآن"
+  },
+  "common": {
+    "loading": "جاري التحميل…"
+  }
+}

package/scaffolds/blank/locales/en.json

@@ -0,0 +1,10 @@
+{
+  "home": {
+    "heroHeading": "Welcome",
+    "heroText": "Your Feeef theme",
+    "shopNow": "Shop now"
+  },
+  "common": {
+    "loading": "Loading…"
+  }
+}