@newschools/sdk 0.1.4 → 0.1.6

package/README.md

@@ -1,29 +1,30 @@
-# @newschools/nuxt
+# @newschools/sdk
 
-Nuxt module for integrating New Schools learning content into your applications.
+Nuxt module for integrating New Schools learning content into your applications with automatic organization theming.
 
 ## Features
 
-✨ **Auto-imported composables** - `useAsyncNewSchools` available everywhere  
+✨ **Auto-imported composables** - `useAsyncNewSchools` and `useOrganization` available everywhere  
+🎨 **Automatic theming** - Organization brand colors applied as CSS variables  
 🔒 **Type-safe** - Full TypeScript support with entity types  
 ⚡ **SSR-compatible** - Built on Nuxt's `useAsyncData`  
-🎯 **Simple API** - Fetch journeys, waypoints, and activities with ease  
-🔑 **API key authentication** - Secure access to your organisation's content
+🎯 **Ready-to-use components** - OrganizationHero, BentoGrid, EntityCard  
+🔑 **API key authentication** - Secure access to your organization's content
 
 ## Installation
 
 ```bash
 # Using npm
-npm install @newschools/nuxt
+npm install @newschools/sdk
 
 # Using yarn
-yarn add @newschools/nuxt
+yarn add @newschools/sdk
 
 # Using pnpm
-pnpm add @newschools/nuxt
+pnpm add @newschools/sdk
 
 # Using bun
-bun add @newschools/nuxt
+bun add @newschools/sdk
 ```
 
 ## Setup
@@ -32,7 +33,12 @@ bun add @newschools/nuxt
 
 ```typescript
 export default defineNuxtConfig({
-  modules: ["@newschools/nuxt"],
+  modules: ["@newschools/sdk"],
+
+  newschools: {
+    apiKey: process.env.NUXT_PUBLIC_NEWSCHOOLS_API_KEY,
+    organizationSlug: "my-organization", // Optional: auto-fetch org data and apply brand colors
+  },
 });
 ```
 
@@ -44,175 +50,314 @@ Add your New Schools API key to `.env`:
 NUXT_PUBLIC_NEWSCHOOLS_API_KEY=ns_live_xxxxxxxxxxxxx
 ```
 
-Or configure directly in `nuxt.config.ts`:
+### 3. (Optional) Configure organization
+
+If you want to automatically load organization data and apply brand theming:
 
 ```typescript
 export default defineNuxtConfig({
-  modules: ["@newschools/nuxt"],
+  modules: ["@newschools/sdk"],
 
   newschools: {
-    apiKey: "ns_live_xxxxxxxxxxxxx",
-    baseUrl: "https://newschools.ai", // optional, defaults to production
+    apiKey: process.env.NUXT_PUBLIC_NEWSCHOOLS_API_KEY,
+    organizationSlug: "webdesignwill", // Loads org data on init
   },
 });
 ```
 
+When `organizationSlug` is set, the SDK will:
+
+- ✅ Auto-fetch organization data on app initialization
+- ✅ Apply brand colors (`primary`, `secondary`, `tertiary`) as CSS variables
+- ✅ Make organization data available via `useOrganization()` composable
+
+## Automatic Brand Theming
+
+The SDK automatically applies your organization's brand colors as CSS variables:
+
+```typescript
+// In nuxt.config.ts
+export default defineNuxtConfig({
+  newschools: {
+    organizationSlug: "my-org", // Has primary: "#FF0000"
+  },
+});
+```
+
+The SDK sets:
+
+- `--ns-color-primary` → `#FF0000`
+- `--ns-color-secondary` → (your secondary color)
+- `--ns-color-tertiary` → (your tertiary color)
+
+If colors are not set or cleared by admin, they revert to SDK defaults:
+
+- `--ns-color-primary` → `#4a3f8f` (Deep Purple)
+- `--ns-color-secondary` → `#ff6b6b` (Vibrant Coral)
+- `--ns-color-tertiary` → `#0fa3b1` (Rich Teal)
+
+Use these variables in your components:
+
+```vue
+<template>
+  <div class="my-component">
+    <h1>Automatically themed!</h1>
+  </div>
+</template>
+
+<style scoped>
+.my-component {
+  background: var(--ns-color-primary);
+  color: white;
+}
+
+h1 {
+  border-bottom: 2px solid var(--ns-color-secondary);
+}
+</style>
+```
+
 ## Usage
 
-The `useAsyncNewSchools` composable is auto-imported and available in all components, pages, and composables.
+### Organization Data
 
-### List Journeys
+Access organization data loaded by the SDK:
 
 ```vue
 <script setup lang="ts">
-const {
-  data: journeys,
-  pending,
-  error,
-  refresh,
-} = await useAsyncNewSchools("journeys");
+const organization = useOrganization();
 </script>
 
 <template>
-  <div>
-    <div v-if="pending">Loading journeys...</div>
-    <div v-else-if="error">Error: {{ error.message }}</div>
-    <div v-else>
-      <div v-for="journey in journeys" :key="journey.id">
-        <h2>{{ journey.title }}</h2>
-        <p>{{ journey.description }}</p>
-      </div>
-    </div>
+  <div v-if="organization">
+    <h1>{{ organization.name }}</h1>
+    <img v-if="organization.coverImageUrl" :src="organization.coverImageUrl" />
   </div>
 </template>
 ```
 
-### Get Single Journey
+### Pre-built Components
+
+#### OrganizationHero
+
+Display organization header with cover image and branding:
 
 ```vue
-<script setup lang="ts">
-const route = useRoute();
-const slug = route.params.slug as string;
+<template>
+  <OrganizationHero :org="organization">
+    <template #sub-title>
+      <p>Welcome to our learning platform</p>
+    </template>
+
+    <template #content>
+      <div>Custom content area for CTAs, forms, etc.</div>
+    </template>
+  </OrganizationHero>
+</template>
 
-const { data: journey } = await useAsyncNewSchools("journey", { id: slug });
+<script setup lang="ts">
+const organization = useOrganization();
 </script>
+```
+
+#### BentoGrid
+
+Create responsive masonry-style layouts:
 
+```vue
 <template>
-  <div>
-    <h1>{{ journey?.title }}</h1>
-    <p>{{ journey?.summary }}</p>
-    <img v-if="journey?.coverImageUrl" :src="journey.coverImageUrl" />
-  </div>
+  <BentoGrid>
+    <!-- 2x2 Featured card -->
+    <BentoGridItem :col-span="2" :row-span="2">
+      <EntityCard>
+        <h3>Featured Content</h3>
+      </EntityCard>
+    </BentoGridItem>
+
+    <!-- Standard cards -->
+    <BentoGridItem>
+      <EntityCard>
+        <h3>Regular Card</h3>
+      </EntityCard>
+    </BentoGridItem>
+
+    <!-- Wide card -->
+    <BentoGridItem :col-span="3">
+      <EntityCard>
+        <h3>Wide Card</h3>
+      </EntityCard>
+    </BentoGridItem>
+  </BentoGrid>
 </template>
 ```
 
-### List Waypoints for Journey
+### Fetching Learning Content
+
+The `useAsyncNewSchools` composable is auto-imported and available everywhere.
+
+#### Fetch all journeys
 
 ```vue
 <script setup lang="ts">
-const route = useRoute();
-const journeyId = route.params.journeyId as string;
-
-const { data: waypoints } = await useAsyncNewSchools("waypoints", {
-  journeyId,
-});
+const { data: journeys, error } = await useAsyncNewSchools("journeys");
 </script>
 
 <template>
-  <div>
-    <div v-for="waypoint in waypoints" :key="waypoint.id">
-      <h3>{{ waypoint.title }}</h3>
+  <div v-if="journeys">
+    <div v-for="journey in journeys" :key="journey.id">
+      <h2>{{ journey.title }}</h2>
+      <p>{{ journey.description }}</p>
     </div>
   </div>
 </template>
 ```
 
-### Get Single Waypoint
+#### Fetch a specific journey
 
 ```vue
 <script setup lang="ts">
-const { data: waypoint } = await useAsyncNewSchools("waypoint", {
-  journeyId: "journey-123",
-  waypointId: "waypoint-456",
+const route = useRoute();
+const { data: journey } = await useAsyncNewSchools("journey", {
+  id: route.params.slug,
 });
 </script>
+
+<template>
+  <div v-if="journey">
+    <h1>{{ journey.title }}</h1>
+    <p>{{ journey.description }}</p>
+  </div>
+</template>
 ```
 
-### List Activities
+#### Fetch waypoints for a journey
 
 ```vue
 <script setup lang="ts">
-const { data: activities } = await useAsyncNewSchools("activities", {
-  journeyId: "journey-123",
-  waypointId: "waypoint-456",
+const { data: waypoints } = await useAsyncNewSchools("waypoints", {
+  journeyId: "my-journey-slug",
 });
 </script>
 ```
 
-### Get Single Activity
+#### Fetch a specific waypoint
 
 ```vue
 <script setup lang="ts">
-const { data: activity } = await useAsyncNewSchools("activity", {
-  journeyId: "journey-123",
-  waypointId: "waypoint-456",
-  activityId: "activity-789",
+const { data: waypoint } = await useAsyncNewSchools("waypoint", {
+  journeyId: "journey-slug",
+  waypointId: "waypoint-slug",
 });
 </script>
 ```
 
-## API Reference
-
-### `useAsyncNewSchools(resource, params?)`
-
-Fetch data from New Schools v1 API with SSR support.
-
-**Parameters:**
-
-- `resource` - Resource type to fetch:
-  - `'journeys'` - List all journeys
-  - `'journey'` - Get single journey
-  - `'waypoints'` - List waypoints for journey
-  - `'waypoint'` - Get single waypoint
-  - `'activities'` - List activities for waypoint
-  - `'activity'` - Get single activity
-
-- `params` - Resource-specific parameters (optional for lists):
-  - Journey: `{ id: string }`
-  - Waypoint: `{ journeyId: string, waypointId?: string }`
-  - Activity: `{ journeyId: string, waypointId: string, activityId?: string }`
-
-**Returns:**
-
-`AsyncData` object with:
-
-- `data` - Fetched data (reactive)
-- `pending` - Loading state (reactive)
-- `error` - Error object if request failed (reactive)
-- `refresh()` - Function to refetch data
-
 ## TypeScript Support
 
 Full type safety for all entities:
 
 ```typescript
 import type {
+  Organisation,
+  OrganisationBrand,
   Journey,
   Waypoint,
   Activity,
   JourneyTheme,
   WaypointType,
   LayoutMode,
-} from "@newschools/nuxt";
+} from "@newschools/sdk";
+
+// Types are automatically inferred in composables
+const organization = useOrganization();
+// organization is typed as Ref<Organisation | null>
 
-// Types are automatically inferred in useAsyncNewSchools
 const { data: journeys } = await useAsyncNewSchools("journeys");
 // journeys is typed as Journey[] | null
+```
 
-const { data: journey } = await useAsyncNewSchools("journey", { id: "slug" });
-// journey is typed as Journey | null
+## Module Configuration
+
+All configuration options for `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  newschools: {
+    /**
+     * New Schools API key (required)
+     * Can also be set via NUXT_PUBLIC_NEWSCHOOLS_API_KEY env variable
+     */
+    apiKey: string;
+
+    /**
+     * Base URL for New Schools API
+     * Default: "https://newschools.ai"
+     */
+    baseUrl?: string;
+
+    /**
+     * Organization slug for auto-fetch and theming
+     * When set, SDK will:
+     * - Automatically fetch organization data on init
+     * - Apply brand colors as CSS variables
+     * - Make data available via useOrganization()
+     *
+     * Example: "my-organization"
+     */
+    organizationSlug?: string;
+  },
+});
 ```
 
+### Do you need `baseUrl`?
+
+**No**, unless you're using a custom API endpoint or testing against a development server.
+
+The default value is `"https://newschools.ai"`, which points to production.
+
+```typescript
+// ✅ Minimal config (most common)
+export default defineNuxtConfig({
+  newschools: {
+    apiKey: process.env.NUXT_PUBLIC_NEWSCHOOLS_API_KEY,
+  },
+});
+
+// ✅ With organization theming
+export default defineNuxtConfig({
+  newschools: {
+    apiKey: process.env.NUXT_PUBLIC_NEWSCHOOLS_API_KEY,
+    organizationSlug: "webdesignwill",
+  },
+});
+
+// ⚠️ Only needed for custom environments
+export default defineNuxtConfig({
+  newschools: {
+    apiKey: process.env.NUXT_PUBLIC_NEWSCHOOLS_API_KEY,
+    baseUrl: "https://staging.newschools.ai", // Testing against staging
+  },
+});
+```
+
+## Available CSS Variables
+
+The SDK provides themeable CSS tokens:
+
+### Brand Colors (Automatically set from organization)
+
+- `--ns-color-primary` - Primary brand color
+- `--ns-color-secondary` - Secondary brand color
+- `--ns-color-tertiary` - Tertiary brand color
+
+### Additional Tokens
+
+- `--ns-color-grey-800`, `--ns-color-grey-900`
+- `--ns-spacing-xs` through `--ns-spacing-3xl`
+- `--ns-border-radius-sm` through `--ns-border-radius-2xl`
+- `--ns-shadow-sm` through `--ns-shadow-xl`
+
+See [tokens.css](./nuxt/src/runtime/styles/tokens.css) for the complete list.
+
 ## Advanced Usage
 
 ### Manual Client (Without Nuxt Composables)
@@ -220,7 +365,7 @@ const { data: journey } = await useAsyncNewSchools("journey", { id: "slug" });
 For use in server routes, plugins, or non-component contexts:
 
 ```typescript
-import { createClient } from "@newschools/nuxt";
+import { createClient } from "@newschools/sdk";
 
 const client = createClient({
   apiKey: "ns_live_xxxxxxxxxxxxx",
@@ -231,59 +376,83 @@ const journeys = await client.get<Journey[]>("/journeys");
 const journey = await client.get<Journey>("/journeys/my-slug");
 ```
 
-### Custom Path Resolution
+## Environment Variables
 
-For advanced integrations:
+| Variable                          | Description              | Required | Default               |
+| --------------------------------- | ------------------------ | -------- | --------------------- |
+| `NUXT_PUBLIC_NEWSCHOOLS_API_KEY`  | Your New Schools API key | Yes      | -                     |
+| `NUXT_PUBLIC_NEWSCHOOLS_BASE_URL` | API base URL             | No       | https://newschools.ai |
 
-```typescript
-import { NewSchoolsPathResolver } from "@newschools/nuxt";
+## Components Reference
 
-const path = NewSchoolsPathResolver.resolve("journey", "list");
-// Returns: '/journeys'
+### `<OrganizationHero>`
 
-const path2 = NewSchoolsPathResolver.resolve("waypoint", "get", {
-  journeyId: "123",
-  waypointId: "456",
-});
-// Returns: '/journeys/123/waypoints/456'
-```
+Display organization header with cover image and branding
 
-## Local Development (Testing with bun link)
+**Props:**
 
-For testing the SDK locally before publishing:
+- `org: Organisation` - Organization object (required)
 
-```bash
-# In the SDK package directory
-cd packages/nuxt
-bun link
+**Slots:**
 
-# In your test project
-cd ~/my-test-project
-bun link @newschools/nuxt
-```
+- `sub-title` - Content below organization name
+- `content` - Right-side content area
+- `background` - Custom background component
 
-Add to your test project's `nuxt.config.ts`:
+### `<BentoGrid>`
 
-```typescript
-export default defineNuxtConfig({
-  modules: ["@newschools/nuxt"],
-});
-```
+Responsive masonry-style grid layout
 
-## Environment Variables
+### `<BentoGridItem>`
 
-| Variable                          | Description                           | Required |
-| --------------------------------- | ------------------------------------- | -------- |
-| `NUXT_PUBLIC_NEWSCHOOLS_API_KEY`  | Your New Schools API key              | Yes      |
-| `NUXT_PUBLIC_NEWSCHOOLS_BASE_URL` | API base URL (defaults to production) | No       |
+Grid item with flexible sizing
 
-## License
+**Props:**
 
-MIT
+- `col-span?: number` - Column span (1-3)
+- `row-span?: number` - Row span (1-2)
+
+### `<EntityCard>`
+
+Card component for displaying content
+
+**Slots:**
 
-## Support
+- `default` - Card content
+- `background` - Background layer
 
-For issues or questions:
+### `<EntityImage>`
 
-- API documentation: https://newschools.ai/docs
-- Contact: support@newschools.ai
+Optimized image component with loading states
+
+**Props:**
+
+- `src?: string` - Image URL
+- `alt: string` - Alt text
+
+## Composables Reference
+
+### `useOrganization()`
+
+Access globally loaded organization data
+
+**Returns:** `Ref<Organisation | null>`
+
+### `useAsyncNewSchools(resource, params?)`
+
+Fetch data from New Schools v1 API with SSR support
+
+**Resources:**
+
+- `'journeys'` - List all journeys
+- `'journey'` - Get single journey
+- `'waypoints'` - List waypoints
+- `'waypoint'` - Get single waypoint
+- `'activities'` - List activities
+- `'activity'` - Get single activity
+
+**Returns:** `AsyncData<T>`
+
+## License
+
+MIT

package/nuxt/src/runtime/components/BentoGrid.vue

@@ -14,7 +14,7 @@ const props = defineProps<Props>();
   </div>
 </template>
 
-<style lang="scss" scoped>
+<style scoped>
 /**
  * Bento Grid Component
  * Asymmetric grid layout inspired by Japanese bento boxes
@@ -27,9 +27,11 @@ const props = defineProps<Props>();
   display: flex;
   flex-direction: column;
   gap: var(--ns-spacing-md);
+}
 
-  /* Tablet and up: 3 column bento grid with auto rows */
-  @media (min-width: 768px) {
+/* Tablet and up: 3 column bento grid with auto rows */
+@media (min-width: 768px) {
+  .ns-bento-grid {
     display: grid;
     grid-template-columns: repeat(3, 1fr);
     grid-auto-rows: 18rem;

package/nuxt/src/runtime/components/BentoGridItem.vue

@@ -7,12 +7,32 @@ interface Props {
   rowSpan?: number;
   /** Number of columns to span (default: 1) */
   colSpan?: number;
+  /** Column start position (1-3, optional for explicit positioning) */
+  colStart?: number;
+  /** Row start position (1+, optional for explicit positioning) */
+  rowStart?: number;
 }
 
 const props = withDefaults(defineProps<Props>(), {
   rowSpan: 1,
   colSpan: 1,
 });
+
+// Compute grid-column value based on whether explicit positioning is provided
+const gridColumnValue = computed(() => {
+  if (props.colStart) {
+    return `${props.colStart} / span ${props.colSpan}`;
+  }
+  return `span ${props.colSpan}`;
+});
+
+// Compute grid-row value based on whether explicit positioning is provided
+const gridRowValue = computed(() => {
+  if (props.rowStart) {
+    return `${props.rowStart} / span ${props.rowSpan}`;
+  }
+  return `span ${props.rowSpan}`;
+});
 </script>
 
 <template>
@@ -20,15 +40,15 @@ const props = withDefaults(defineProps<Props>(), {
     class="ns-bento-grid-item"
     :class="[props.class]"
     :style="{
-      gridRow: `span ${props.rowSpan}`,
-      gridColumn: `span ${props.colSpan}`,
+      gridRow: gridRowValue,
+      gridColumn: gridColumnValue,
     }"
   >
     <slot />
   </div>
 </template>
 
-<style lang="scss" scoped>
+<style scoped>
 /**
  * Bento Grid Item Component
  * Individual item within bento grid with span control

package/nuxt/src/runtime/components/EntityCard.vue

@@ -11,18 +11,23 @@
 
       <!-- Cover image if available -->
       <EntityImage :src="imageUrl" :alt="imageAlt || 'Card image'" />
+    </div>
 
-      <!-- Content overlay at bottom -->
-      <div class="ns-entity-card__content">
-        <slot />
-      </div>
+    <!-- Content overlay at bottom -->
+    <div class="ns-entity-card__content">
+      <h3 class="ns-entity-card__title" v-if="$slots['title']">
+        <slot name="title" />
+      </h3>
+      <p class="ns-entity-card__description" v-if="$slots['description']">
+        <slot name="description" />
+      </p>
     </div>
   </motion.div>
 </template>
 
 <script setup lang="ts">
 import { motion } from "motion-v";
-import FlickeringGridBackground from "../internal/FlickeringGridBackground.vue";
+import FlickeringGridBackground from "../internal/components/FlickeringGridBackground.vue";
 import EntityImage from "./EntityImage.vue";
 
 interface Props {
@@ -36,7 +41,7 @@ interface Props {
 defineProps<Props>();
 </script>
 
-<style lang="scss" scoped>
+<style scoped>
 /**
  * Entity Card Component
  * Glassy card with image container and text overlay
@@ -60,19 +65,19 @@ defineProps<Props>();
   /* Smooth interactions */
   transition: all 0.3s cubic-bezier(0.19, 1, 0.22, 1);
   cursor: pointer;
+}
+
+/* Hover effect */
+.ns-entity-card:hover {
+  background: rgba(255, 255, 255, 0.12);
+  border-color: rgba(255, 255, 255, 0.25);
+  box-shadow: 0 12px 48px 0 rgba(0, 0, 0, 0.15);
+  transform: translateY(-4px);
+}
 
-  /* Hover effect */
-  &:hover {
-    background: rgba(255, 255, 255, 0.12);
-    border-color: rgba(255, 255, 255, 0.25);
-    box-shadow: 0 12px 48px 0 rgba(0, 0, 0, 0.15);
-    transform: translateY(-4px);
-  }
-
-  /* Active state */
-  &:active {
-    transform: translateY(-2px);
-  }
+/* Active state */
+.ns-entity-card:active {
+  transform: translateY(-2px);
 }
 
 /* ============================================ */
@@ -84,15 +89,6 @@ defineProps<Props>();
   width: 100%;
   height: 100%; /* Fill parent height (works for bento grid cells) */
   border-radius: var(--ns-border-radius-md);
-  min-height: clamp(
-    280px,
-    50dvh,
-    600px
-  ); /* Responsive to viewport height on mobile */
-
-  @media (min-width: 768px) {
-    min-height: auto; /* Remove min-height on tablet+ */
-  }
 
   /* Layout */
   display: flex;
@@ -112,15 +108,40 @@ defineProps<Props>();
 /* ============================================ */
 
 .ns-entity-card__content {
+  position: absolute;
   padding: var(--ns-spacing-lg);
+  bottom: var(--ns-spacing-sm);
+  left: var(--ns-spacing-sm);
+  right: var(--ns-spacing-sm);
+  z-index: 10;
 
   /* White text - same as OrganizationHero */
   color: var(--ns-color-white);
+}
+
+/* Text shadow for readability */
+.ns-entity-card__content > * {
+  margin: 0;
+  text-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
+}
+
+.ns-entity-card__title,
+.ns-entity-card__description {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* Title slot - clamp to 2 lines */
+.ns-entity-card__title {
+  line-clamp: 2;
+  -webkit-line-clamp: 2;
+}
 
-  /* Text shadow for readability */
-  & > * {
-    margin: 0;
-    text-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
-  }
+/* Description slot - clamp to 3 lines */
+.ns-entity-card__description {
+  line-clamp: 3;
+  -webkit-line-clamp: 3;
 }
 </style>

package/nuxt/src/runtime/components/OrganizationHero.vue

@@ -32,7 +32,7 @@
 
 <script setup lang="ts">
 import { motion } from "motion-v";
-import FlickeringGridBackground from "../internal/FlickeringGridBackground.vue";
+import FlickeringGridBackground from "../internal/components/FlickeringGridBackground.vue";
 import EntityImage from "./EntityImage.vue";
 import type { Organisation } from "../../types/entities";
 

package/nuxt/src/runtime/internal/services/bento-layout.service.ts

@@ -0,0 +1,123 @@
+/**
+ * Bento Layout Service
+ * Generates responsive bento grid layouts based on item count
+ * Provides asymmetric patterns for visual interest with repeating patterns for scalability
+ */
+
+/**
+ * Configuration for a single bento grid item
+ */
+export interface BentoItemConfig {
+  /** Column span (1-3, default 1) */
+  colSpan?: number;
+  /** Row span (1-2, default 1) */
+  rowSpan?: number;
+  /** Column start position (1-3, optional for explicit positioning) */
+  colStart?: number;
+  /** Row start position (1+, optional for explicit positioning) */
+  rowStart?: number;
+}
+
+/**
+ * Get bento grid layout configuration based on number of items
+ *
+ * Patterns:
+ * - 1 item: Full width
+ * - 2 items: 2/3 + 1/3 for hierarchy
+ * - 3 items: 1 large (2x2) + 2 small stacked
+ * - 4 items: 1 large (2x2) + 2 small + 1 tall (1x2)
+ * - 5 items: 1 large (2x2) + 4 small in corners
+ * - 6 items: Mixed pattern (becomes repeating block)
+ * - 7+: Repeats 6-item pattern
+ *
+ * @param itemCount - Number of items to display in grid
+ * @returns Array of layout configurations for each item
+ *
+ * @example
+ * ```typescript
+ * const layouts = getBentoLayout(3);
+ * // Returns: [
+ * //   { colSpan: 2, rowSpan: 2 }, // Large featured
+ * //   { colSpan: 1, rowSpan: 1 }, // Small
+ * //   { colSpan: 1, rowSpan: 1 }  // Small
+ * // ]
+ * ```
+ */
+export function getBentoLayout(itemCount: number): BentoItemConfig[] {
+  if (itemCount <= 0) return [];
+
+  // Pattern for 1 item: Full width
+  if (itemCount === 1) {
+    return [{ colSpan: 3, rowSpan: 1 }];
+  }
+
+  // Pattern for 2 items: 2/3 width + 1/3 width (creates hierarchy)
+  if (itemCount === 2) {
+    return [
+      { colSpan: 2, rowSpan: 1 }, // Featured (larger)
+      { colSpan: 1, rowSpan: 1 }, // Secondary
+    ];
+  }
+
+  // Pattern for 3 items: 1 large (2x2) + 2 small stacked on right
+  if (itemCount === 3) {
+    return [
+      { colSpan: 2, rowSpan: 2 }, // Large featured (left)
+      { colSpan: 1, rowSpan: 1 }, // Small (top right)
+      { colSpan: 1, rowSpan: 1 }, // Small (bottom right)
+    ];
+  }
+
+  // Pattern for 4 items: 1 large (2x2) + 2 small + 1 wide bottom
+  if (itemCount === 4) {
+    return [
+      { colSpan: 2, rowSpan: 2 }, // Large featured (top left)
+      { colSpan: 1, rowSpan: 1 }, // Small (top right)
+      { colSpan: 1, rowSpan: 1 }, // Small (middle right)
+      { colSpan: 3, rowSpan: 1 }, // Wide (bottom, full width)
+    ];
+  }
+
+  // Pattern for 5 items: 1 large center + 4 small in corners
+  if (itemCount === 5) {
+    return [
+      { colSpan: 2, rowSpan: 2 }, // Large featured (top left)
+      { colSpan: 1, rowSpan: 1 }, // Small (top right)
+      { colSpan: 1, rowSpan: 1 }, // Small (middle right)
+      { colSpan: 1, rowSpan: 1 }, // Wide (bottom left + center)
+      { colSpan: 2, rowSpan: 1 }, // Small (bottom right)
+    ];
+  }
+
+  // Pattern for 6 items: First 3 + mirrored 3 (featured left, then featured right)
+  // Uses explicit positioning to ensure correct layout
+  const sixItemPattern: BentoItemConfig[] = [
+    { colSpan: 2, rowSpan: 2, colStart: 1, rowStart: 1 }, // Large featured (top left)
+    { colSpan: 1, rowSpan: 1, colStart: 3, rowStart: 1 }, // Small (top right)
+    { colSpan: 1, rowSpan: 1, colStart: 3, rowStart: 2 }, // Small (middle right)
+    { colSpan: 1, rowSpan: 1, colStart: 1, rowStart: 3 }, // Small (bottom left)
+    { colSpan: 1, rowSpan: 1, colStart: 1, rowStart: 4 }, // Small (far bottom left)
+    { colSpan: 2, rowSpan: 2, colStart: 2, rowStart: 3 }, // Large featured (bottom right)
+  ];
+
+  if (itemCount === 6) {
+    return sixItemPattern;
+  }
+
+  // For 7+ items: Repeat the 6-item pattern
+  const layouts: BentoItemConfig[] = [];
+  const fullPatterns = Math.floor(itemCount / 6);
+  const remainder = itemCount % 6;
+
+  // Add full 6-item pattern blocks
+  for (let i = 0; i < fullPatterns; i++) {
+    layouts.push(...sixItemPattern);
+  }
+
+  // Add partial pattern for remaining items
+  if (remainder > 0) {
+    layouts.push(...getBentoLayout(remainder));
+  }
+
+  return layouts;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newschools/sdk",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "New Schools SDK - Multi-framework components and modules for integrating New Schools learning content",
   "type": "module",
   "main": "./nuxt/src/module.ts",