@upstart.gg/sdk 0.0.134 → 0.0.136

package/src/shared/bricks/manifests/box.manifest.ts

@@ -3,13 +3,13 @@ import { defineProps } from "../props/helpers";
 import { Type } from "@sinclair/typebox";
 import { borderRef, roundingRef } from "../props/border";
 import { shadowRef } from "../props/effects";
-import type { BrickProps } from "../props/types";
 import { cssLengthRef } from "../props/css-length";
 import { directionRef } from "../props/direction";
 import { RxBox } from "react-icons/rx";
 import { alignItemsRef, justifyContentRef } from "../props/align";
 import { colorPresetRef } from "../props/color-preset";
 import { loopRef } from "../props/dynamic";
+import type { BrickExample } from "./_types";
 
 // Generic container can hold any type of array data source
 export const manifest = defineBrickManifest({
@@ -17,8 +17,45 @@ export const manifest = defineBrickManifest({
   category: "container",
   name: "Box",
   description: "A container for stacking bricks horizontally or vertically.",
-  aiInstructions:
-    "A box is a container for other bricks. A box cannot contain other boxes as children. A box should contain at least 2 bricks to be useful, otherwise use a simple brick instead.",
+  aiInstructions: `Use the box component as a flexible container for organizing and arranging multiple bricks in horizontal or vertical layouts.
+
+WHEN TO USE:
+- Grouping related content elements (text + image + button)
+- Creating card-like layouts with multiple components
+- Building responsive grid systems with wrapping
+- Organizing form elements or input groups
+- Displaying repeated data from queries (products, team members, blog posts)
+- Creating structured layouts with consistent spacing
+
+LAYOUT GUIDELINES:
+- direction: "flex-col" for vertical stacking, "flex-row" for horizontal arrangement
+- gap: "0.5rem" for tight spacing, "1rem" for standard, "2rem" for spacious layouts
+- padding: "1rem" for standard padding, "2rem" for generous spacing, "0" for edge-to-edge
+- wrap: true for responsive grids that wrap on smaller screens, false for fixed layouts
+- justifyContent: "justify-start" for left-align, "justify-center" for center, "justify-between" for space-between
+- alignItems: "items-stretch" for equal heights, "items-center" for center-align, "items-start" for top-align
+
+STYLING OPTIONS:
+- colorPreset: Use light backgrounds like "primary-50", "neutral-100", "secondary-100" for content containers
+- rounding: "rounded-md" for standard, "rounded-lg" for friendly, "rounded-xl"/"rounded-2xl" for modern
+- border: Add subtle borders with "border" width and colors like "border-gray-200", "border-primary-300"
+- shadow: "shadow-sm" for subtle depth, "shadow-md" for cards, "shadow-lg" for prominence
+
+CONTENT RULES:
+- Must contain at least 2 child bricks to be useful
+- Cannot contain other box components as direct children
+- Commonly contains: text, image, button, icon combinations
+- Perfect for repeating patterns using loop data
+
+DYNAMIC CONTENT:
+- Use loop property to repeat the box itself over data queries
+- Template variables work in all child components: "{{ product.name}}", "{{user.email}}"
+- Great for: product catalogs, team directories, blog listings
+
+AVOID:
+- Single child elements (use individual brick instead)
+- Nesting boxes inside boxes (use single box with proper layout)
+- Complex nested structures (break into separate boxes)`,
   isContainer: true,
   defaultWidth: {
     desktop: "auto",
@@ -113,130 +150,141 @@ export const manifest = defineBrickManifest({
 
 export type Manifest = typeof manifest;
 
-export const examples: {
-  description: string;
-  type: string;
-  props: BrickProps<Manifest>["brick"]["props"];
-}[] = [
+export const examples: BrickExample<Manifest>[] = [
+  // BASIC LAYOUTS
   {
-    description: "A simple box with 2 text bricks aligned vertically",
+    description: "Simple vertical layout - Basic text and image combination",
     type: "box",
     props: {
       direction: "flex-col",
       gap: "1rem",
+      padding: "1.5rem",
       $children: [
         {
           type: "text",
           props: {
-            $children: [
-              {
-                type: "text",
-                props: {
-                  content: "Hello World",
-                },
-              },
-              {
-                type: "text",
-                props: {
-                  content: "Hello World",
-                },
-              },
-            ],
+            content:
+              "<h3>Welcome to Our Service</h3><p>We provide innovative solutions for modern businesses.</p>",
+          },
+        },
+        {
+          type: "image",
+          props: {
+            src: "https://via.placeholder.com/300x200",
+            alt: "Service showcase",
+          },
+        },
+        {
+          type: "button",
+          props: {
+            label: "Learn More",
+            link: "/services",
           },
         },
       ],
     },
   },
+
   {
-    description: "A horizontal box with wrapping enabled - images will wrap to new rows if they overflow",
+    description: "Horizontal layout with wrapping - Perfect for responsive image galleries",
     type: "box",
     props: {
       direction: "flex-row",
       gap: "1rem",
       wrap: true,
+      justifyContent: "justify-center",
+      padding: "1rem",
       $children: [
         {
           type: "image",
           props: {
             src: "https://via.placeholder.com/150",
-            alt: "Placeholder Image",
-          },
-        },
-        {
-          type: "image",
-          props: {
-            src: "https://via.placeholder.com/150",
-            alt: "Placeholder Image",
+            alt: "Gallery image 1",
           },
         },
         {
           type: "image",
           props: {
             src: "https://via.placeholder.com/150",
-            alt: "Placeholder Image",
+            alt: "Gallery image 2",
           },
         },
         {
           type: "image",
           props: {
             src: "https://via.placeholder.com/150",
-            alt: "Placeholder Image",
+            alt: "Gallery image 3",
           },
         },
         {
           type: "image",
           props: {
             src: "https://via.placeholder.com/150",
-            alt: "Placeholder Image",
+            alt: "Gallery image 4",
           },
         },
       ],
     },
   },
+
+  // STYLED CONTAINERS
   {
-    description: "A vertical box with 2 text bricks and 1 image",
+    description: "Content card with background and border - Professional presentation style",
     type: "box",
     props: {
       direction: "flex-col",
       gap: "1rem",
+      padding: "2rem",
+      colorPreset: { color: "primary-50" },
+      border: { width: "border", color: "border-primary-200" },
+      rounding: "rounded-lg",
+      shadow: "shadow-md",
       $children: [
         {
           type: "text",
           props: {
-            content: "Hello World",
+            content:
+              "<h3>Featured Article</h3><p>Discover the latest trends in technology and innovation that are shaping our future.</p>",
           },
         },
         {
           type: "image",
           props: {
-            src: "https://via.placeholder.com/150",
-            alt: "Placeholder Image",
+            src: "https://via.placeholder.com/400x250",
+            alt: "Technology trends",
           },
         },
         {
-          type: "text",
+          type: "button",
           props: {
-            content: "Hello World",
+            label: "Read Full Article",
+            link: "/articles/tech-trends",
           },
         },
       ],
     },
   },
+
+  // DYNAMIC CONTENT EXAMPLES
   {
-    description: "Employee directory using allEmployees query with vertical layout",
+    description: "Employee directory using dynamic data - Shows team member profiles",
     type: "box",
     props: {
       direction: "flex-col",
       gap: "1.5rem",
       padding: "2rem",
-      colorPreset: {
-        color: "neutral-100",
-      },
+      colorPreset: { color: "neutral-100" },
       rounding: "rounded-lg",
-      loop: {
-        over: "allEmployees",
-      },
+      border: { width: "border", color: "border-neutral-300" },
+      loop: { over: "allEmployees" },
       $children: [
+        {
+          type: "image",
+          props: {
+            src: "{{allEmployees.photo}}",
+            alt: "Photo of {{allEmployees.name}}",
+          },
+        },
         {
           type: "text",
           props: {
@@ -245,27 +293,29 @@ export const examples: {
           },
         },
         {
-          type: "image",
+          type: "button",
           props: {
-            src: "{{allEmployees.photo}}",
-            alt: "Photo of {{allEmployees.name}}",
+            label: "Contact {{allEmployees.name}}",
+            link: "mailto:{{allEmployees.email}}",
           },
         },
       ],
     },
   },
+
   {
-    description: "Blog posts grid using blogPosts query with horizontal cards",
+    description: "Blog post cards with horizontal layout - Great for article previews",
     type: "box",
     props: {
       direction: "flex-row",
       gap: "2rem",
-      padding: "1rem",
+      padding: "1.5rem",
       justifyContent: "justify-start",
       alignItems: "items-stretch",
-      loop: {
-        over: "blogPosts",
-      },
+      colorPreset: { color: "secondary-50" },
+      rounding: "rounded-lg",
+      shadow: "shadow-sm",
+      loop: { over: "blogPosts" },
       $children: [
         {
           type: "image",
@@ -281,28 +331,31 @@ export const examples: {
               "<h4>{{blogPosts.title}}</h4><p>{{blogPosts.excerpt}}</p><p><em>By {{blogPosts.author}} • {{blogPosts.publishDate}}</em></p>",
           },
         },
+        {
+          type: "button",
+          props: {
+            label: "Read More",
+            link: "/blog/{{blogPosts.slug}}",
+          },
+        },
       ],
     },
   },
+
   {
-    description: "Featured products showcase using featuredProducts query",
+    description: "Product showcase cards with pricing - Perfect for e-commerce displays",
     type: "box",
     props: {
       direction: "flex-col",
       gap: "1rem",
       padding: "1.5rem",
-      colorPreset: {
-        color: "primary-50",
-      },
-      border: {
-        width: "border",
-        color: "border-primary-200",
-      },
+      justifyContent: "justify-center",
+      alignItems: "items-center",
+      colorPreset: { color: "accent-50" },
+      border: { width: "border-2", color: "border-accent-200" },
       rounding: "rounded-xl",
       shadow: "shadow-md",
-      loop: {
-        over: "featuredProducts",
-      },
+      loop: { over: "featuredProducts" },
       $children: [
         {
           type: "image",
@@ -321,16 +374,17 @@ export const examples: {
         {
           type: "button",
           props: {
-            text: "Add to Cart",
+            label: "Add to Cart",
             link: "/cart/add/{{featuredProducts.id}}",
           },
         },
       ],
     },
   },
+
+  // RESPONSIVE GRID LAYOUTS
   {
-    description:
-      "Team members horizontal layout with wrapping - members will wrap to multiple rows on smaller screens",
+    description: "Team members with wrapping - Responsive grid that adapts to screen size",
     type: "box",
     props: {
       direction: "flex-row",
@@ -338,13 +392,10 @@ export const examples: {
       padding: "2rem",
       wrap: true,
       justifyContent: "justify-center",
-      alignItems: "items-center",
-      colorPreset: {
-        color: "secondary-100",
-      },
-      loop: {
-        over: "teamMembers",
-      },
+      alignItems: "items-start",
+      colorPreset: { color: "secondary-100" },
+      rounding: "rounded-lg",
+      loop: { over: "teamMembers" },
       $children: [
         {
           type: "image",
@@ -356,31 +407,43 @@ export const examples: {
         {
           type: "text",
           props: {
-            content: "<h4>{{teamMembers.fullName}}</h4><p>{{teamMembers.role}}</p><p>{{teamMembers.bio}}</p>",
+            content:
+              "<h4>{{teamMembers.fullName}}</h4><p><strong>{{teamMembers.role}}</strong></p><p>{{teamMembers.bio}}</p>",
+          },
+        },
+        {
+          type: "button",
+          props: {
+            label: "View Profile",
+            link: "/team/{{teamMembers.slug}}",
           },
         },
       ],
     },
   },
+
   {
-    description: "Event listings using upcomingEvents query with accent styling",
+    description: "Event listings with accent styling - Prominent call-to-action design",
     type: "box",
     props: {
       direction: "flex-col",
       gap: "1.25rem",
       padding: "2.5rem",
-      colorPreset: {
-        color: "accent-100",
-      },
-      border: {
-        width: "border-2",
-        color: "border-accent-300",
-      },
+      alignItems: "items-center",
+      colorPreset: { color: "accent-100" },
+      border: { width: "border-2", color: "border-accent-300" },
       rounding: "rounded-lg",
-      loop: {
-        over: "upcomingEvents",
-      },
+      shadow: "shadow-lg",
+      loop: { over: "upcomingEvents" },
       $children: [
+        {
+          type: "icon",
+          props: {
+            icon: "mdi:calendar-event",
+            size: "2rem",
+            color: "#f59e0b",
+          },
+        },
         {
           type: "text",
           props: {
@@ -391,15 +454,17 @@ export const examples: {
         {
           type: "button",
           props: {
-            text: "Register Now",
+            label: "Register Now",
             link: "/events/{{upcomingEvents.slug}}/register",
           },
         },
       ],
     },
   },
+
+  // TESTIMONIALS & REVIEWS
   {
-    description: "Testimonials carousel using customerTestimonials query",
+    description: "Customer testimonials with star ratings - Social proof presentation",
     type: "box",
     props: {
       direction: "flex-col",
@@ -407,20 +472,24 @@ export const examples: {
       padding: "3rem",
       justifyContent: "justify-center",
       alignItems: "items-center",
-      colorPreset: {
-        color: "neutral-50",
-      },
+      colorPreset: { color: "neutral-50" },
       shadow: "shadow-lg",
       rounding: "rounded-2xl",
-      loop: {
-        over: "customerTestimonials",
-      },
+      loop: { over: "customerTestimonials" },
       $children: [
+        {
+          type: "icon",
+          props: {
+            icon: "mdi:format-quote-open",
+            size: "2rem",
+            color: "#6b7280",
+          },
+        },
         {
           type: "text",
           props: {
             content:
-              '<blockquote>"{{customerTestimonials.quote}}"</blockquote><p><strong>{{customerTestimonials.customerName}}</strong></p><p>{{customerTestimonials.company}} • {{customerTestimonials.position}}</p>',
+              '<p style="text-align: center"><em>"{{customerTestimonials.quote}}"</em></p><p style="text-align: center"><strong>{{customerTestimonials.customerName}}</strong></p><p style="text-align: center">{{customerTestimonials.company}} • {{customerTestimonials.position}}</p>',
           },
         },
         {
@@ -434,18 +503,20 @@ export const examples: {
       ],
     },
   },
+
   {
-    description: "Portfolio projects using portfolioProjects query with horizontal layout",
+    description: "Portfolio project showcase - Creative work presentation with client details",
     type: "box",
     props: {
       direction: "flex-row",
       gap: "1.5rem",
-      padding: "1rem",
+      padding: "2rem",
       alignItems: "items-start",
       justifyContent: "justify-start",
-      loop: {
-        over: "portfolioProjects",
-      },
+      colorPreset: { color: "primary-50" },
+      border: { width: "border", color: "border-primary-200" },
+      rounding: "rounded-lg",
+      loop: { over: "portfolioProjects" },
       $children: [
         {
           type: "image",
@@ -458,36 +529,32 @@ export const examples: {
           type: "text",
           props: {
             content:
-              "<h4>{{portfolioProjects.projectName}}</h4><p>{{portfolioProjects.client}}</p><p>{{portfolioProjects.category}} • {{portfolioProjects.year}}</p><p>{{portfolioProjects.shortDescription}}</p>",
+              "<h4>{{portfolioProjects.projectName}}</h4><p><strong>{{portfolioProjects.client}}</strong></p><p>{{portfolioProjects.category}} • {{portfolioProjects.year}}</p><p>{{portfolioProjects.shortDescription}}</p>",
           },
         },
         {
           type: "button",
           props: {
-            text: "View Project",
+            label: "View Project",
             link: "/portfolio/{{portfolioProjects.slug}}",
           },
         },
       ],
     },
   },
+
+  // NEWS & ARTICLES
   {
-    description: "News articles using latestNews query with vertical stacking",
+    description: "News article previews with categories - Clean editorial layout",
     type: "box",
     props: {
       direction: "flex-col",
-      gap: "2rem",
+      gap: "1.5rem",
       padding: "2rem",
-      colorPreset: {
-        color: "primary-100",
-      },
-      border: {
-        width: "border",
-        color: "border-primary-300",
-      },
-      loop: {
-        over: "latestNews",
-      },
+      colorPreset: { color: "neutral-100" },
+      border: { width: "border", color: "border-neutral-300" },
+      rounding: "rounded-md",
+      loop: { over: "latestNews" },
       $children: [
         {
           type: "text",
@@ -497,16 +564,19 @@ export const examples: {
           },
         },
         {
-          type: "text",
+          type: "button",
           props: {
-            content: "<a href='/news/{{latestNews.slug}}'>Read full article →</a>",
+            label: "Read Full Article",
+            link: "/news/{{latestNews.slug}}",
           },
         },
       ],
     },
   },
+
+  // SERVICE OFFERINGS
   {
-    description: "Service offerings using companyServices query with centered layout",
+    description: "Service packages with icons and pricing - Professional service presentation",
     type: "box",
     props: {
       direction: "flex-col",
@@ -514,20 +584,16 @@ export const examples: {
       padding: "2rem",
       justifyContent: "justify-center",
       alignItems: "items-center",
-      colorPreset: {
-        color: "secondary-200",
-      },
+      colorPreset: { color: "secondary-200" },
       rounding: "rounded-xl",
       shadow: "shadow-md",
-      loop: {
-        over: "companyServices",
-      },
+      loop: { over: "companyServices" },
       $children: [
         {
           type: "icon",
           props: {
             icon: "{{companyServices.iconName}}",
-            size: "2rem",
+            size: "2.5rem",
             color: "{{companyServices.iconColor}}",
           },
         },
@@ -535,13 +601,13 @@ export const examples: {
           type: "text",
           props: {
             content:
-              "<h4>{{companyServices.serviceName}}</h4><p>{{companyServices.description}}</p><p><strong>Starting at ${{companyServices.price}}</strong></p>",
+              "<h4 style='text-align: center'>{{companyServices.serviceName}}</h4><p style='text-align: center'>{{companyServices.description}}</p><p style='text-align: center'><strong>Starting at ${{companyServices.price}}</strong></p>",
           },
         },
         {
           type: "button",
           props: {
-            text: "Learn More",
+            label: "Learn More",
             link: "/services/{{companyServices.serviceSlug}}",
           },
         },