@dani-builder/strapi-plugin-builder 0.1.0 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,152 @@
+# @dani-builder/strapi-plugin-builder
+
+Strapi v5 plugin providing 11 content types, 31 components, and smart API endpoints for a page builder CMS. Installed as a Strapi plugin — not used standalone.
+
+## Installation & Setup
+
+```bash
+# 1. Install the plugin
+pnpm add @dani-builder/strapi-plugin-builder
+
+# 2. Enable in Strapi config (config/plugins.ts)
+export default () => ({
+  builder: { enabled: true },
+});
+
+# 3. Sync content type schemas into your Strapi project
+npx daniworks-builder sync              # Full sync (schemas + routes/controllers/services)
+npx daniworks-builder sync --dry-run    # Preview changes
+npx daniworks-builder sync --only page  # Sync specific content types
+npx daniworks-builder sync --force      # Overwrite local modifications
+```
+
+**Schema sync is required** for REST CRUD endpoints to work. The CLI copies schema.json files and generates routes/controllers/services boilerplate into your project's `src/api/` directory. Changes are tracked via `.daniworks-sync-manifest.json`.
+
+## Content Types (11)
+
+### Collection Types (8)
+
+| singularName | pluralName | REST endpoint | draftAndPublish | i18n |
+|---|---|---|---|---|
+| page | pages | `api/pages` | true | yes |
+| article | articles | `api/articles` | true | yes |
+| faq | faqs | `api/faqs` | true | yes |
+| category | categories | `api/categories` | false | yes |
+| tag | tags | `api/tags` | false | yes |
+| author | authors | `api/authors` | false | no |
+| inquiry | inquiries | `api/inquiries` | false | no |
+| series | all-series | `api/all-series` | false | yes |
+
+### Single Types (3)
+
+| singularName | pluralName | REST endpoint | draftAndPublish | i18n |
+|---|---|---|---|---|
+| navigation | navigations | `api/navigations` | true | yes |
+| global | globals | `api/globals` | true | yes |
+| site-setting | site-settings | `api/site-settings` | false | no |
+
+**Series quirk:** `pluralName` is `all-series` (not `series`) because Strapi requires singular and plural names to differ.
+
+## Components (31)
+
+### Blocks (14) — used in Page.blocks dynamic zone
+
+`blocks.hero`, `blocks.features`, `blocks.cta`, `blocks.slider`, `blocks.inquiry-form`, `blocks.faq`, `blocks.highlights`, `blocks.bento-grid`, `blocks.testimonials`, `blocks.logo-cloud`, `blocks.stats`, `blocks.pricing`, `blocks.content`, `blocks.team`
+
+### Elements (2)
+
+`elements.section`, `elements.footer`
+
+### Shared (15)
+
+`shared.link`, `shared.seo`, `shared.feature-item`, `shared.highlight-item`, `shared.bento-item`, `shared.slider-item`, `shared.stat-item`, `shared.team-member`, `shared.testimonial-item`, `shared.pricing-tier`, `shared.logo-item`, `shared.navigation-group`, `shared.brand-colors`, `shared.analytics-setting`, `shared.chatbot-setting`, `shared.site-verification`
+
+## Smart API Endpoints
+
+Server-side deep populate — no need for client-side populate building.
+
+| Method | Path | Description |
+|---|---|---|
+| GET | `/api/builder/pages` | List pages (minimal populate) |
+| GET | `/api/builder/pages/:documentId` | Single page with all blocks deeply populated |
+| GET | `/api/builder/global` | Global settings (siteWideBlocks + footer, fully populated) |
+
+## Critical Rules
+
+1. **Component registration** — The plugin uses `strapi.get('components').add(map)`. Never assign directly to `strapi.components[uid]`.
+2. **Components require metadata** — Each component JSON must include `__schema__`, `globalId`, and `collectionName` fields.
+3. **`__component` required in dynamic zones** — Every block object needs `"__component": "blocks.hero"` etc.
+4. **Block text lives in `section`** — heading, subheading, and theme are on the `section` sub-component, NOT at block root.
+5. **Section.theme is a Tailwind preset key** — Values like `'dark'`, `'default'`. No arbitrary CSS colors.
+6. **`name` fields are admin-only** — Used for CMS identification. Never display in frontend.
+7. **All media fields are nullable** — Render defensively even for "required" media fields.
+8. **CT directory names match singularName** — `site-setting/` not `site-settings/`.
+
+## Variant-Based Layouts
+
+Blocks use a `variant` enum instead of separate components per layout. Only use values defined in the schema:
+
+| Block | Variants |
+|---|---|
+| hero | `side-by-side`, `media-extending`, `fullscreen-media`, `stacked-media` |
+| features | `simple-grid`, `card-grid`, `icon-grid` |
+| cta | `side-by-side`, `centered` |
+| pricing | `card-grid`, `comparison-table` |
+| testimonials | `card-grid`, `alternating`, `single-highlight` |
+| highlights | `media-aside`, `alternating`, `card-grid` |
+| bento-grid | `auto`, `featured-left`, `featured-right` |
+| stats | `simple-row`, `card-grid` |
+| team | `card-grid`, `simple-grid` |
+| logo-cloud | `simple-grid`, `ticker` |
+| slider | `fullscreen`, `card-carousel` |
+
+**Never invent variant values** — always check the schema definition.
+
+## REST API Rules (for MCP / programmatic content creation)
+
+```json
+// POST api/pages — create a page with blocks
+{
+  "data": {
+    "title": "About",
+    "slug": "about",
+    "locale": "en",
+    "blocks": [
+      {
+        "__component": "blocks.hero",
+        "variant": "side-by-side",
+        "section": {
+          "heading": "About Us",
+          "subheading": "Our story",
+          "theme": "dark"
+        },
+        "ctaLink": { "label": "Learn more", "href": "/contact" }
+      }
+    ]
+  }
+}
+```
+
+1. **`data` wrapper required** — POST/PUT body must be `{ "data": { ... } }`
+2. **`locale` required** — i18n-enabled CTs fail with `Invalid key` without it
+3. **Media uploaded separately** — Upload via Strapi Upload API, then reference by ID
+4. **Deep reads via Smart API** — Standard REST only populates 1 level; use `/api/builder/pages/:docId` for full data
+
+## File Structure
+
+```
+schemas/api/          — Content type schemas (copied to consumer project by sync CLI)
+server/src/
+  register.ts         — Programmatic component registration
+  controllers/        — Smart API controllers (page, global)
+  services/           — Populate service (deep populate definitions for all 14 blocks)
+  routes/             — Smart API route definitions
+  components/         — Component JSON schemas (blocks, elements, shared)
+bin/sync.js           — CLI for schema sync
+```
+
+## Peer Dependencies
+
+- `@strapi/strapi` ^5.0.0
+- `@strapi/plugin-color-picker` ^5.0.0
+- `@d3levvv/strapi-react-icons-plugin` ^1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dani-builder/strapi-plugin-builder",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Daniworks Builder — reusable CMS components, content types, and smart API for Strapi v5",
   "license": "MIT",
   "strapi": {
@@ -22,7 +22,8 @@
     "dist",
     "schemas",
     "bin",
-    "strapi-server.js"
+    "strapi-server.js",
+    "AGENTS.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -35,11 +36,6 @@
   "bin": {
     "daniworks-builder": "./bin/sync.js"
   },
-  "scripts": {
-    "build": "tsc && node -e \"const fs=require('fs'),p=require('path'),src='server/src/components',dst='dist/server/src/components';(function cp(s,d){fs.mkdirSync(d,{recursive:true});fs.readdirSync(s).forEach(f=>{const sp=p.join(s,f),dp=p.join(d,f);fs.statSync(sp).isDirectory()?cp(sp,dp):f.endsWith('.json')&&fs.copyFileSync(sp,dp);})})(src,dst)\"",
-    "watch": "strapi-plugin watch",
-    "verify": "strapi-plugin verify"
-  },
   "dependencies": {},
   "devDependencies": {
     "@strapi/sdk-plugin": "^5.0.0",
@@ -51,5 +47,10 @@
     "@strapi/strapi": "^5.0.0",
     "@strapi/plugin-color-picker": "^5.0.0",
     "@d3levvv/strapi-react-icons-plugin": "^1.0.0"
+  },
+  "scripts": {
+    "build": "tsc && node -e \"const fs=require('fs'),p=require('path'),src='server/src/components',dst='dist/server/src/components';(function cp(s,d){fs.mkdirSync(d,{recursive:true});fs.readdirSync(s).forEach(f=>{const sp=p.join(s,f),dp=p.join(d,f);fs.statSync(sp).isDirectory()?cp(sp,dp):f.endsWith('.json')&&fs.copyFileSync(sp,dp);})})(src,dst)\"",
+    "watch": "strapi-plugin watch",
+    "verify": "strapi-plugin verify"
   }
-}
+}