{"_id":"@ayo-core/puck-kit","_rev":"4-ab0e31c8f81fc48688f31116269aec80","name":"@ayo-core/puck-kit","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.0":{"name":"@ayo-core/puck-kit","version":"0.1.0","keywords":["puck","page-builder","ayo","components","configuration"],"author":{"name":"Ayo Team"},"license":"UNLICENSED","_id":"@ayo-core/puck-kit@0.1.0","maintainers":[{"name":"ayodev1","email":"techadmin@ayo.cool"}],"dist":{"shasum":"3ef8225268224c0082b2418c55c9abff4e36755c","tarball":"https://registry.npmjs.org/@ayo-core/puck-kit/-/puck-kit-0.1.0.tgz","fileCount":65,"integrity":"sha512-sl0gfNeP9DSZVMOoyVY0jnriiDwfMkxJE+JNfr47tkHn9WJWIt+iizsIJqg8ZYWjI/JDrtvOT4s8sMVhdA708Q==","signatures":[{"sig":"MEUCIQDV3LEnI0HNZUc7Nft6jPwkrzyQ06+8ZETAYpykOpJPXAIgLOl+2uvLXof1zxuidwhkIS1DrqSKZ8fmBlCgNbgpu5Y=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":203432},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./types":{"types":"./dist/types/index.d.ts","import":"./dist/types/index.js"},"./config":{"types":"./dist/config/index.d.ts","import":"./dist/config/index.js"},"./tokens":{"types":"./dist/tokens/index.d.ts","import":"./dist/tokens/index.js"},"./schemas":{"types":"./dist/schemas/index.d.ts","import":"./dist/schemas/index.js"},"./resolver":{"types":"./dist/resolver/index.d.ts","import":"./dist/resolver/index.js"},"./components":{"types":"./dist/components/index.d.ts","import":"./dist/components/index.js"}},"gitHead":"707f9cb6dba2d3e429b19dc1321ea3a5616f8c63","scripts":{"dev":"tsc --watch","lint":"eslint src/**/*.{ts,tsx}","test":"vitest","build":"tsc","test:ui":"vitest --ui","type-check":"tsc --noEmit"},"_npmUser":{"name":"ayodev1","email":"techadmin@ayo.cool"},"_npmVersion":"10.8.2","description":"Shared Puck components, configuration, and resolver for ayo-frontend and ayo-microsite-frontend","directories":{},"_nodeVersion":"20.19.3","dependencies":{"lucide-react":"^0.563.0","@puckeditor/core":"^0.21.1"},"_hasShrinkwrap":false,"devDependencies":{"zod":"^3.22.4","react":"^19.0.0","eslint":"^8.56.0","vitest":"^1.1.0","react-dom":"^19.0.0","typescript":"^5.3.3","@types/node":"^20.10.6","@types/react":"^19.0.0","@types/react-dom":"^19.0.0","@typescript-eslint/parser":"^6.17.0","@typescript-eslint/eslint-plugin":"^6.17.0"},"peerDependencies":{"react":"^19.0.0","react-dom":"^19.0.0"},"_npmOperationalInternal":{"tmp":"tmp/puck-kit_0.1.0_1769948948740_0.05752847608171163","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@ayo-core/puck-kit","version":"0.1.1","keywords":["puck","page-builder","ayo","components","configuration"],"author":{"name":"Ayo Team"},"license":"UNLICENSED","_id":"@ayo-core/puck-kit@0.1.1","maintainers":[{"name":"ayodev1","email":"techadmin@ayo.cool"}],"dist":{"shasum":"26e619176110d9ca8c7d8bd2cad069b78777208c","tarball":"https://registry.npmjs.org/@ayo-core/puck-kit/-/puck-kit-0.1.1.tgz","fileCount":167,"integrity":"sha512-zLNmxTRJ1KTtMMjiiWn0tbzVtt9hnOrEqI/RPun/nhbJ0x6nVhQlPZA0KO+HpK+tPMd2kyXPM/STq1yezG5UpA==","signatures":[{"sig":"MEUCIQD3HUz7/RV7KXcrmjUFOLfJLCqnRUGQk6cGyMvkJl6WrgIgO0m1rMGuBS70z+LF81/jRzvIzY1y0MEht+OSyTZrACU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":292404},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./types":{"types":"./dist/types/index.d.ts","import":"./dist/types/index.js"},"./config":{"types":"./dist/config/index.d.ts","import":"./dist/config/index.js"},"./tokens":{"types":"./dist/tokens/index.d.ts","import":"./dist/tokens/index.js"},"./schemas":{"types":"./dist/schemas/index.d.ts","import":"./dist/schemas/index.js"},"./resolver":{"types":"./dist/resolver/index.d.ts","import":"./dist/resolver/index.js"},"./components":{"types":"./dist/components/index.d.ts","import":"./dist/components/index.js"}},"gitHead":"13107e0659d004114bada1f3a9b5b5d160752bc5","scripts":{"dev":"tsc --watch","lint":"eslint src/**/*.{ts,tsx}","test":"vitest","build":"tsc","test:ui":"vitest --ui","type-check":"tsc --noEmit"},"_npmUser":{"name":"ayodev1","email":"techadmin@ayo.cool"},"_npmVersion":"10.8.2","description":"Shared Puck components, configuration, and resolver for ayo-frontend and ayo-microsite-frontend","directories":{},"_nodeVersion":"20.19.3","dependencies":{"lucide-react":"^0.563.0","@puckeditor/core":"^0.21.1"},"_hasShrinkwrap":false,"devDependencies":{"zod":"^3.22.4","react":"^19.0.0","eslint":"^8.56.0","vitest":"^1.1.0","react-dom":"^19.0.0","typescript":"^5.3.3","@types/node":"^20.10.6","@types/react":"^19.0.0","@types/react-dom":"^19.0.0","@typescript-eslint/parser":"^6.17.0","@typescript-eslint/eslint-plugin":"^6.17.0"},"peerDependencies":{"react":"^19.0.0","react-dom":"^19.0.0"},"_npmOperationalInternal":{"tmp":"tmp/puck-kit_0.1.1_1769949383488_0.012860749439765007","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@ayo-core/puck-kit","version":"0.1.2","keywords":["puck","page-builder","ayo","components","configuration"],"author":{"name":"Ayo Team"},"license":"UNLICENSED","_id":"@ayo-core/puck-kit@0.1.2","maintainers":[{"name":"ayodev1","email":"techadmin@ayo.cool"}],"dist":{"shasum":"60b434dc7d05f10147c1379c38f734ffaf07d5ec","tarball":"https://registry.npmjs.org/@ayo-core/puck-kit/-/puck-kit-0.1.2.tgz","fileCount":167,"integrity":"sha512-eCNDacCQ95RZu7SUtdJ1UeUVs/IC4IIRqOvom5C7rQiAsU0v4MUsPwX8aJYb7e2nYrGgobmmsEJzKer6wKWYiQ==","signatures":[{"sig":"MEUCIFqYvrp4elmKHxsvXoA/q+79roTHUGOvo1EkXGfHp9ZrAiEAwNXGhDhAsWlOZ1EyIufak+eqp4Hzvi3awHVUftw7O4M=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":292398},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./types":{"types":"./dist/types/index.d.ts","import":"./dist/types/index.js"},"./config":{"types":"./dist/config/index.d.ts","import":"./dist/config/index.js"},"./tokens":{"types":"./dist/tokens/index.d.ts","import":"./dist/tokens/index.js"},"./schemas":{"types":"./dist/schemas/index.d.ts","import":"./dist/schemas/index.js"},"./resolver":{"types":"./dist/resolver/index.d.ts","import":"./dist/resolver/index.js"},"./components":{"types":"./dist/components/index.d.ts","import":"./dist/components/index.js"}},"gitHead":"13107e0659d004114bada1f3a9b5b5d160752bc5","scripts":{"dev":"tsc --watch","lint":"eslint src/**/*.{ts,tsx}","test":"vitest","build":"tsc","test:ui":"vitest --ui","type-check":"tsc --noEmit"},"_npmUser":{"name":"ayodev1","email":"techadmin@ayo.cool"},"_npmVersion":"10.8.2","description":"Shared Puck components, configuration, and resolver for ayo-frontend and ayo-microsite-frontend","directories":{},"_nodeVersion":"20.19.3","dependencies":{"lucide-react":"^0.563.0","@puckeditor/core":"^0.21.1"},"_hasShrinkwrap":false,"devDependencies":{"zod":"^3.22.4","react":"^19.0.0","eslint":"^8.56.0","vitest":"^1.1.0","react-dom":"^19.0.0","typescript":"^5.3.3","@types/node":"^20.10.6","@types/react":"^19.0.0","@types/react-dom":"^19.0.0","@typescript-eslint/parser":"^6.17.0","@typescript-eslint/eslint-plugin":"^6.17.0"},"peerDependencies":{"react":"^19.0.0","react-dom":"^19.0.0"},"_npmOperationalInternal":{"tmp":"tmp/puck-kit_0.1.2_1769949503953_0.4599451564897785","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@ayo-core/puck-kit","version":"0.1.3","description":"Shared Puck components, configuration, and resolver for ayo-frontend and ayo-microsite-frontend","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./components":{"import":"./dist/components/index.js","types":"./dist/components/index.d.ts"},"./config":{"import":"./dist/config/index.js","types":"./dist/config/index.d.ts"},"./resolver":{"import":"./dist/resolver/index.js","types":"./dist/resolver/index.d.ts"},"./tokens":{"import":"./dist/tokens/index.js","types":"./dist/tokens/index.d.ts"},"./schemas":{"import":"./dist/schemas/index.js","types":"./dist/schemas/index.d.ts"},"./types":{"import":"./dist/types/index.js","types":"./dist/types/index.d.ts"}},"scripts":{"dev":"tsc --watch","build":"tsc","type-check":"tsc --noEmit","lint":"eslint src/**/*.{ts,tsx}","test":"vitest","test:ui":"vitest --ui"},"dependencies":{"@puckeditor/core":"^0.21.1","lucide-react":"^0.563.0"},"peerDependencies":{"react":"^19.0.0","react-dom":"^19.0.0"},"devDependencies":{"@types/node":"^20.10.6","@types/react":"^19.0.0","@types/react-dom":"^19.0.0","@typescript-eslint/eslint-plugin":"^6.17.0","@typescript-eslint/parser":"^6.17.0","eslint":"^8.56.0","react":"^19.0.0","react-dom":"^19.0.0","typescript":"^5.3.3","vitest":"^1.1.0","zod":"^3.22.4"},"keywords":["puck","page-builder","ayo","components","configuration"],"author":{"name":"Ayo Team"},"license":"UNLICENSED","_id":"@ayo-core/puck-kit@0.1.3","gitHead":"13107e0659d004114bada1f3a9b5b5d160752bc5","_nodeVersion":"20.19.3","_npmVersion":"10.8.2","dist":{"integrity":"sha512-qU6BCBL8pd7bflh+GXSonTlMwsXaYISrqTWmzYC1dsNaF1hCoSQGWf8I8wFkdv7SdgJurjJSzjY3kDxWbhrFhw==","shasum":"a434636c3edaa1133207dc3d69e2a54c1d6e944c","tarball":"https://registry.npmjs.org/@ayo-core/puck-kit/-/puck-kit-0.1.3.tgz","fileCount":222,"unpackedSize":333214,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDLCk9hM+Cix3OY2S/Fc/DZ59aPYAlPOn8y57cGM1gpAAIgR3O6W4aiKRvpB5DWuBK6ljpYWX1ygqgjOl6+bwgaCxU="}]},"_npmUser":{"name":"ayodev1","email":"techadmin@ayo.cool"},"directories":{},"maintainers":[{"name":"ayodev1","email":"techadmin@ayo.cool"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/puck-kit_0.1.3_1769949676908_0.502308161748271"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-01T12:29:08.681Z","modified":"2026-02-01T12:41:17.295Z","0.1.0":"2026-02-01T12:29:08.884Z","0.1.1":"2026-02-01T12:36:23.666Z","0.1.2":"2026-02-01T12:38:24.132Z","0.1.3":"2026-02-01T12:41:17.148Z"},"author":{"name":"Ayo Team"},"license":"UNLICENSED","keywords":["puck","page-builder","ayo","components","configuration"],"description":"Shared Puck components, configuration, and resolver for ayo-frontend and ayo-microsite-frontend","maintainers":[{"name":"ayodev1","email":"techadmin@ayo.cool"}],"readme":"# @ayo/puck-kit\n\nShared Puck components, configuration, and utilities for both `ayo-frontend` (creator studio) and `ayo-microsite-frontend` (live rendering).\n\n## Overview\n\nThis package ensures that published Puck JSON renders identically in both the creator preview and the live microsite. It provides:\n\n- **Component Registry**: Unified set of Puck blocks used across both apps\n- **Configuration Builder**: Factory for creating Puck config in editor or render mode\n- **Theme Tokens**: Shared CSS variables and design tokens\n- **Resolver**: Data hydration system for API-powered blocks\n- **Services Interface**: Contract for environment-specific API implementations\n- **Schemas & Validation**: Zod schemas for type safety\n\n## Installation\n\n### Option A: Local workspace dependency (development)\n\nIn both `ayo-frontend` and `ayo-microsite-frontend`:\n\n```json\n{\n  \"dependencies\": {\n    \"@ayo/puck-kit\": \"file:../ayo-puck-kit\"\n  }\n}\n```\n\nThen run `npm install` or `yarn install`.\n\n### Option B: Private npm registry (production)\n\nPublish to GitHub Packages or a private npm registry and install normally:\n\n```bash\nnpm install @ayo/puck-kit\n```\n\n## Directory Structure\n\n```\nsrc/\n├── types/                    # Shared type definitions\n│   ├── index.ts\n│   ├── microsite.ts         # MicrositeServices, MicrositeData\n│   └── puck.ts              # Puck-specific types\n├── components/               # Puck block implementations\n│   ├── index.ts\n│   ├── branding/            # TopNav, BannerHeader, etc.\n│   ├── streaming/           # LiveStreamCard, IvsPlayer, etc.\n│   ├── videos/              # VideosGrid, VideoPlayerModal\n│   ├── games/               # GamesGrid, GameLauncher\n│   ├── quests/              # QuestsList, QuestTracking\n│   ├── economy/             # Rewards, Leaderboard, Badges\n│   └── layout/              # Container, Section, Spacer\n├── config/\n│   ├── index.ts\n│   ├── createMicrositePuckConfig.ts\n│   └── fieldDefinitions.ts\n├── resolver/                 # Data hydration\n│   ├── index.ts\n│   ├── resolvePuckData.ts\n│   └── resolvers/           # Module-specific resolvers\n├── tokens/                   # Theme & design tokens\n│   ├── index.ts\n│   ├── theme.ts\n│   ├── colors.ts\n│   └── tailwind.preset.ts\n├── schemas/                  # Zod validation\n│   ├── index.ts\n│   ├── puck.ts\n│   └── microsite.ts\n└── index.ts                 # Main export\n```\n\n## Usage\n\n### 1. Basic Setup in `ayo-frontend` (Creator Studio)\n\n```tsx\nimport { createMicrositePuckConfig } from '@ayo/puck-kit/config';\nimport { applyThemeTokens } from '@ayo/puck-kit/tokens';\n\nconst creatorServices = {\n  getVideos: async (params) => { /* authenticated creator endpoint */ },\n  getGames: async (params) => { /* ... */ },\n  // ... other service methods\n};\n\nexport const puckConfig = createMicrositePuckConfig({\n  mode: 'editor',\n  services: creatorServices,\n  featureFlags: { /* ... */ }\n});\n```\n\n### 2. Basic Setup in `ayo-microsite-frontend` (Live Rendering)\n\n```tsx\nimport { createMicrositePuckConfig, resolvePuckData } from '@ayo/puck-kit';\nimport { applyThemeTokens } from '@ayo/puck-kit/tokens';\n\nconst publicServices = {\n  getVideos: async (params) => { /* public API endpoint */ },\n  getGames: async (params) => { /* ... */ },\n  // ... other service methods\n};\n\n// Fetch published Puck JSON from API\nconst puckData = await fetchPublishedPuckData(subdomain);\n\n// Resolve data (fetch any external data blocks need)\nconst resolvedData = await resolvePuckData(puckData, publicServices);\n\n// Render\nconst config = createMicrositePuckConfig({\n  mode: 'render',\n  services: publicServices,\n});\n\nexport function MicrositePage() {\n  return (\n    <div style={applyThemeTokens(puckData.root?.props?.theme)}>\n      <Render config={config} data={resolvedData} />\n    </div>\n  );\n}\n```\n\n## Key Concepts\n\n### Services Interface\n\nAll data fetching goes through a `MicrositeServices` interface:\n\n```typescript\nexport interface MicrositeServices {\n  // Microsite config\n  getMicrosite(subdomain: string): Promise<Microsite>;\n  \n  // Streaming\n  getActiveLiveStream(micrositeId: string): Promise<LiveStream | null>;\n  \n  // Videos\n  getMicrositeVideos(micrositeId: string): Promise<Video[]>;\n  \n  // Quests\n  getMicrositeQuests(micrositeId: string): Promise<Quest[]>;\n  \n  // Rewards\n  getMicrositeRewards(micrositeId: string): Promise<Reward[]>;\n  \n  // ... more methods\n}\n```\n\nEach app implements this interface differently:\n- **Creator**: Uses authenticated endpoints, preview data\n- **Microsite**: Uses public endpoints, caching, guest auth\n\n### Puck Config Modes\n\n```typescript\n// Editor mode: full fields + editing helpers\nconst editorConfig = createMicrositePuckConfig({ mode: 'editor', ... });\n\n// Render mode: stripped down, production-ready\nconst renderConfig = createMicrositePuckConfig({ mode: 'render', ... });\n```\n\nBoth use **identical component names** — this is critical for JSON compatibility.\n\n### Data Resolver\n\nBefore rendering, resolve external data:\n\n```typescript\nconst resolvedData = await resolvePuckData(puckData, services);\n// Now puckData blocks have props.resolved with fetched data\n```\n\nThis ensures:\n- Creator preview ≈ live output\n- No loading jank during render\n- Deterministic testing\n\n### Theme Tokens\n\nApply theme via CSS variables:\n\n```typescript\nconst themeStyle = applyThemeTokens({\n  primaryColor: '#6366f1',\n  backgroundColor: '#ffffff',\n  radius: 'md'\n});\n\n<div style={themeStyle}>\n  <Render config={config} data={data} />\n</div>\n```\n\n## Migration Checklist\n\n- [ ] Move existing Puck components into `src/components/`\n- [ ] Extract theme tokens and Tailwind preset\n- [ ] Create `MicrositeServices` implementations in both apps\n- [ ] Build resolver for priority data-powered blocks (Videos, Quests, Rewards)\n- [ ] Add snapshot tests for key components\n- [ ] Publish initial version\n- [ ] Update both apps to import from `@ayo/puck-kit`\n- [ ] Verify no \"unknown block type\" errors in published data\n- [ ] Add schema version + migrations (phase 2)\n\n## Testing\n\n```bash\nnpm run build      # TypeScript compilation\nnpm run type-check # Type checking only\nnpm run test       # Run vitest suite\nnpm run test:ui    # Interactive test UI\n```\n\n## Development\n\n```bash\nnpm run dev        # Watch mode TypeScript compilation\nnpm run lint       # ESLint\n```\n\n## Versioning & Breaking Changes\n\nSince Puck JSON is stored long-term:\n\n1. **Never rename component types** without a migration\n2. Use `schemaVersion` in root props to track migrations\n3. Maintain migration functions in `src/schemas/`\n4. Always backward-compatible resolver\n\n## Contributing\n\n- Keep components framework-light (avoid Next.js-only APIs)\n- If something is Next-specific, provide two implementations\n- All new blocks should have TypeScript interfaces\n- Add tests for resolver changes\n- Update this README with new exports\n\n## License\n\nUNLICENSED (Internal to Ayo)\n","readmeFilename":"README.md"}