ember-tribe 2.5.1 → 2.5.3

package/README.md

@@ -1,135 +1,475 @@
 # ember-tribe
 
-An addon that connects EmberJS to Tribe API.
-Tribe is a collaborative project management framework - https://github.com/tribe-framework/tribe
+An addon that connects EmberJS to Tribe API, bridging the gap between backend data structures and frontend application development. It helps you make an Ember app based on Junction's Blueprint file, also called `types.json`.
 
-https://junction.express provides an interface to build a Tribe compatibale no-code backend in minutes.
+Tribe is a project management framework built for ease of collaboration - https://github.com/tribe-framework/tribe
 
-## Compatibility
+## Installation and Setup
 
-- Ember.js v6.0 or above
-- Ember CLI v6.0 or above
+### Prerequisites
 
-## Installation
+- Ember CLI v6.0 – v6.4
+- Node.js (latest LTS)
+- Junction (optional) - via https://junction.express (cloud version) or https://tribe-framework.org (open source version)
 
-1. Install
+### Installation
 
-```
+```bash
 ember install ember-tribe
 ```
 
-2. Configure
+- Enter `TRIBE_API_URL` and `TRIBE_API_KEY` in `.env` file (copy of `.env.sample`). You can find these values in the Junction dashboard at [junction.express](https://junction.express) (cloud) or your self-hosted Tribe admin panel.
 
-- Enter TRIBE_API_URL and TRIBE_API_KEY in .env file, copy of .env.sample
+---
 
-# Ember-Tribe Documentation
+The addon automatically configures following essential packages:
 
-## Overview
+**Ember Addons:** `ember-cli-dotenv`, `ember-cli-sass`, `ember-modifier`, `ember-composable-helpers`, `ember-truth-helpers`, `ember-file-upload` , `ember-power-select`
 
-ember-tribe is a powerful Ember.js addon that bridges the gap between backend CMS data structures and frontend application development. It helps you make an Ember app based on storylang.json and simplified-types.json files, if and when these files are availble.
+**NPM Packages:** `bootstrap`, `@popperjs/core`, `animate.css`, `video.js`, `swiper`,  `howler`
 
-## Purpose
+---
 
-Ember-tribe enables rapid application development by:
+## Core File Structure
 
-- Providing pre-configured addon ecosystem for common functionality
-- Implementing standardized patterns for Tribe applications
-- Creating responsive, Bootstrap-based interfaces with minimal configuration
-- Supporting automatic model generation from backend track definitions in simplified-types.json
+```
+app/
+├── routes/
+├── templates/
+├── controllers/
+├── components/
+├── helpers/
+├── modifiers/
+├── services/
+├── styles/app.scss
+└── router.js
+config/
+└── storylang.json
+installer.sh
+```
 
-## Installation and Setup
+---
 
-### Prerequisites
+## Storylang CLI
 
-- Ember.js 6.x
-- Node.js (latest LTS)
-- Junction backend
+ember-tribe ships with a command-line tool called `storylang` that synchronises the `config/storylang.json` specification with the actual Ember project files.
 
-### Installation
+### Usage
 
 ```bash
-ember install ember-tribe
+storylang <command> [options]
 ```
 
-The addon automatically configures following essential packages:
+**Commands:**
+
+| Command | Description |
+|---|---|
+| `storylang pull` | Updates `config/storylang.json` from current project files |
+| `storylang push` | Generates any missing routes, components, services, helpers, modifiers, and controllers |
+| `storylang push -o` | Regenerates all artefacts in `storylang.json`, overwriting existing files |
 
-**Ember Addons:**
+**Example:**
 
-- `ember-cli-dotenv` - Environment configuration
-- `ember-cli-sass` - SCSS support
-- `ember-modifier` - DOM manipulation helpers
-- `ember-composable-helpers` - Template utilities
-- `ember-truth-helpers` - Boolean logic helpers
-- `ember-file-upload` - File handling
-- `ember-power-select` - Advanced select components
-- `ember-table` - Data tables
-- `ember-animated` - Smooth animations
+```bash
+cd /path/to/ember/app
 
-**NPM Packages:**
+storylang pull
+# => config/storylang.json updated from project files
 
-- `bootstrap` - UI framework
-- `@popperjs/core` - Bootstrap dependency
-- `animate.css` - CSS animations
-- `video.js` - Video player
-- `swiper` - Touch sliders
-- `howler` - Audio management
+storylang push
+# => missing routes, components, services, helpers, modifiers, and controllers are generated
+
+storylang push -o
+# => all artefacts in storylang.json are (re)generated, overwriting existing files
+```
 
-## Core Architecture
+### Typical Workflow
 
-### Think in this order
+1. Define your `config/storylang.json` spec (manually or with the help of an AI tool), then run `storylang push` to generate the project files.
+2. Run `storylang pull` periodically to keep the spec in sync as the project evolves.
 
-ember-tribe follows a specific order that includes our learnings and Ember.js best practices, and must be followed exactly:
+---
 
-1. **router.js** - Application routing structure
-2. **app/routes** - Route handlers and data loading
-3. **app/templates & controllers** - UI templates and minimal controllers
-4. **app/components** - Reusable UI components with component specific logic
-5. **app/services** - Application-wide logic and state
+## Storylang.json Documentation
 
-This order ensures proper dependency resolution and optimal code organization.
+### Overview
 
-### Package Philosophy
+Storylang.json is a structured configuration file used in the ember-tribe ecosystem to define the frontend implementation of your application. It is found at `config/storylang.json`. It works in conjunction with your `types.json` (which defines your data types) to create a complete frontend specification.
 
-**Try using npm packages over ember addons because ember addons are sometimes outdated.** Ember-tribe prioritizes npm packages for better compatibility and maintenance.
+### Purpose
+
+The storylang.json file serves as a blueprint for frontend developers to understand:
+
+- What routes, components, services, helpers, modifiers and types are required
+- How data flows through the application
 
 ### File Structure
 
+The storylang.json file contains seven main sections:
+
+```json
+{
+  "implementation_approach": "...",
+  "types": [...],
+  "components": [...],
+  "routes": [...],
+  "services": [...],
+  "helpers": [...],
+  "modifiers": [...]
+}
 ```
-app/
-├── routes/
-├── templates/
-├── controllers/
-├── components/
-├── helpers/
-├── modifiers/
-├── services/
-├── styles/app.scss
-└── router.js
-installer.sh
+
+### Section Definitions
+
+### 1. Implementation Approach
+
+**Purpose**: Provides a high-level technical overview of how the frontend interface would work.
+
+**Format**:
+
+```json
+{
+  "implementation_approach": "Two-paragraph description explaining technical approach and key functionality."
+}
+```
+
+---
+
+### 2. Types
+
+**Purpose**: Declares which data types from `types.json` and maps them to the components, routes, services, helpers and modifiers that consume them. This creates a traceable link between your data layer and your UI implementation.
+
+**Format**:
+
+```json
+{
+  "types": [
+    {
+      "slug": "type-slug", //type slug as defined in `types.json` blueprint
+      "used_in": { //where this type is used
+        "routes": ["route-name"],
+        "components": ["component-name"],
+        "services": ["service-name"],
+        "helpers": ["helper-name"],
+        "modifiers": ["modifier-name"]
+      }
+    }
+  ]
+}
 ```
 
-## Required File Outputs
+---
+
+### 3. Components
+
+**Purpose**: Defines reusable UI components that will be built for the application.
+
+**Format**:
+
+```json
+{
+  "components": [
+    {
+      "name": "component-name",
+      "type": "component-type",
+      "tracked_vars": [{ "<variableName>": "<dataType>" }],
+      "inherited_args": [{ "<argumentName>": "<argType>" }],
+      "actions": ["action1", "action2"],
+      "helpers": ["helper1", "helper2"],
+      "modifiers": ["modifier1"],
+      "services": ["service1", "service2"]
+    }
+  ]
+}
+```
+
+**Built-in Component Types in ember-tribe**:
+
+- **Layout**: `table`, `figure`, `accordion`, `card`, `list-group`, `navbar`, `nav`, `tab`, `breadcrumb`
+- **Interactive**: `button`, `button-group`, `dropdown`, `modal`, `collapse`, `offcanvas`, `pagination`, `popover`, `tooltip`, `swiper-carousel`, `videojs-player`, `howlerjs-player`, `input-field`, `input-group`, `textarea`, `checkbox`, `radio`, `range`, `select`, `multi-select`, `date`, `file-uploader`, `alert`, `badge`, `toast`, `placeholder`, `progress`, `spinner`, `scrollspy`
+
+**Example**:
+
+```json
+{
+  "components": [
+    {
+      "name": "file-summary-card",
+      "type": "card",
+      "tracked_vars": [{ "isSelected": "bool" }, { "isExpanded": "bool" }],
+      "inherited_args": [
+        { "file": "var" },
+        { "onEdit": "action" },
+        { "onDelete": "action" }
+      ],
+      "actions": ["toggleSelection", "expandDetails", "editFile", "deleteFile"],
+      "helpers": ["formatDate", "truncateText"],
+      "modifiers": ["tooltip"],
+      "services": ["store", "router"]
+    }
+  ]
+}
+```
+
+---
+
+### 4. Routes
+
+**Purpose**: Defines the application's routes and their requirements.
+
+**Format**:
+
+```json
+{
+  "routes": [
+    {
+      "name": "route-name", //should match Ember router.js
+      "tracked_vars": [{ "<variableName>": "<dataType>" }],
+      "get_vars": [{ "<paramName>": "<dataType>" }],
+      "actions": ["action1", "action2"],
+      "helpers": ["helper1"],
+      "services": ["service1"],
+      "components": ["component1", "component2"],
+      "types": ["type1", "type2"]
+    }
+  ]
+}
+```
+
+---
+
+### 5. Services
+
+**Purpose**: Defines custom Ember services needed by the application.
+
+**Format**:
+
+```json
+{
+  "services": [
+    {
+      "name": "service-name",
+      "tracked_vars": [{ "<variableName>": "<dataType>" }],
+      "actions": ["action1", "action2"],
+      "helpers": ["helper1"],
+      "services": ["dependency1", "dependency2"]
+    }
+  ]
+}
+```
+
+**Built-in Services in ember-tribe**:
+
+- `store`: Ember Data store for CRUD operations
+- `router`: Ember router service for navigation
+- `types`: Automatic model generation from backend tracks
+- `bootstrap`: Bootstrap CSS framework with Popper.js
+- `papaparse`: CSV parsing library
+- `sortablejs`: Drag-and-drop sorting
+- `swiperjs`: Touch slider/carousel
+- `videojs`: Video player
+- `howlerjs`: Audio player
+
+**Example**:
+
+```json
+{
+  "services": [
+    {
+      "name": "visualization-builder",
+      "tracked_vars": [
+        { "currentVisualization": "object" },
+        { "availableTypes": "array" }
+      ],
+      "actions": [
+        "createVisualization",
+        "updateVisualization",
+        "deleteVisualization"
+      ],
+      "helpers": ["validateConfig", "generatePreview"],
+      "services": ["store", "router"]
+    }
+  ]
+}
+```
+
+---
+
+### 6. Helpers
+
+**Purpose**: Defines custom template helpers — pure functions used in templates to format, compute or transform data for display.
+
+**Format**:
+
+```json
+{
+  "helpers": [
+    {
+      "name": "helper-name",
+      "description": "What this helper does",
+      "args": [{ "<argumentName>": "<dataType>" }],
+      "return": "<dataType>"
+    }
+  ]
+}
+```
+
+**Helper Properties**:
+
+- `name`: Kebab-case name of the helper
+- `description`: Brief description of what the helper computes or transforms
+- `args`: Input arguments the helper accepts
+- `return`: The data type the helper outputs
+
+**Example**:
+
+```json
+{
+  "helpers": [
+    {
+      "name": "format-date",
+      "description": "Formats a raw ISO date string into a human-readable date",
+      "args": [{ "isoString": "string" }, { "format": "string" }],
+      "return": "string"
+    },
+    {
+      "name": "truncate-text",
+      "description": "Truncates a string to a given character limit and appends an ellipsis",
+      "args": [{ "text": "string" }, { "limit": "int" }],
+      "return": "string"
+    }
+  ]
+}
+```
+
+---
+
+### 7. Modifiers
+
+**Purpose**: Defines custom Ember modifiers — functions that directly interact with DOM elements to attach behaviour, third-party libraries or event listeners.
+
+**Format**:
+
+```json
+{
+  "modifiers": [
+    {
+      "name": "modifier-name",
+      "description": "What DOM behaviour this modifier applies",
+      "args": [{ "<argumentName>": "<dataType>" }],
+      "services": ["service1"]
+    }
+  ]
+}
+```
+
+**Modifier Properties**:
+
+- `name`: Kebab-case name of the modifier
+- `description`: Brief description of the DOM behaviour it attaches
+- `args`: Arguments passed into the modifier from the template
+- `services`: Ember services injected if needed
+
+**Example**:
+
+```json
+{
+  "modifiers": [
+    {
+      "name": "tooltip",
+      "description": "Initialises a Bootstrap tooltip on the target element using the provided label",
+      "args": [{ "label": "string" }, { "placement": "string" }],
+      "services": []
+    },
+    {
+      "name": "autofocus",
+      "description": "Sets focus on the target element when it is inserted into the DOM",
+      "args": [],
+      "services": []
+    }
+  ]
+}
+```
+
+---
+
+### Data Types Reference
+
+### Data Types (dataType)
+
+- `string`: Text values
+- `int`: Integer numbers
+- `bool`: Boolean true/false
+- `array`: List of items
+- `object`: Complex data structure
+
+### Argument Types (argType)
+
+- `var`: Passed data/state
+- `fn`: Callback function
+- `get`: Get function
+- `action`: User interaction handler
+
+---
+
+### Integration with Other Files
+
+### With types.json
+
+- Type names used in routes should match type names from `types.json`
+- The `types` section in storylang.json is the explicit bridge between your data types and your UI — always keep it in sync with `types.json`
+- Types are the gateway to persistent storage on the backend
+
+---
+
+### Storylang Best Practices
+
+**Always begin your thought process with routes → then move repeatable template logic into components → then move repeatable app-wide logic from components and routes to services → then extract reusable template and component functions into helpers → then extract template and component DOM behaviour into modifiers**
+
+1. **Start with Routes**: Match route names to user mental models and use consistent naming conventions
+2. **Minimize Route Logic**: Preferably fetch (read) type data in routes and then pass that data to components or services. Other than fetching type data, minimize the use of javascript in routes — Javascript is meant to be in components and services more than in routes
+3. **Route Parameters**: Keep get_vars minimal and meaningful, and load only necessary types for each route
+4. **Component Focus**: Keep components focused on single responsibilities and use descriptive, kebab-case names. Names should indicate which built-in ember-tribe component to use.
+5. **Data Flow**: Receive backend data down from routes (via inherited_args) rather than fetching (reading) in components
+6. **Component Actions**: Non-read functions — create, update, delete — can all happen well at component-level
+7. **Service Integration**: Use services directly in both components and routes for app-wide logic
+8. **Service Architecture**: Keep services stateless when possible and use dependency injection for service composition
+9. **Service Role**: Services interact with both routes and components and store the core logic of the application
+10. **Helpers**: Keep helpers pure and stateless — they should only receive input and return output with no side effects
+11. **Modifiers**: Use modifiers to isolate all direct DOM manipulation and third-party library initialisation from component logic
+12. **Types Mapping**: Populate the `types` section as you define your routes and components — it is your traceability layer between data types and UI
+
+---
+
+## Ember-Tribe Development Guide
+
+### Required File Outputs
 
 Make separate, complete code files for each category:
 
-### installer.sh
+### Example installer.sh
 
 ```bash
-ember g route <name>;
-ember g controller <name>;
-ember g component <name> -gc;
-ember g helper <name>;
-ember g modifier <name>;
-ember g service <name>;
+npm i chart.js
+npm i lodash
+ember install ember-table
+ember g route files
+ember g controller files
+ember g component file-card -gc
+ember g helper format-date
+ember g modifier tooltip
+ember g service visualization-builder
 ```
 
-### app/styles/app.scss
+### Default styling
 
-```scss
+Following is the default style that comes with tribe. Use the app.scss file for all style code. Change this based on your design styling requirements.
+
+```app/styles/app.scss
 @import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;1,100;1,200;1,300;1,400;1,500;1,600;1,700&display=swap');
 
-$font-family-sans-serif: 'IBM Plex Mono', serif !default;
-$display-font-family: 'IBM Plex Mono', serif !default;
+$font-family-sans-serif: 'IBM Plex Mono', monospace !default;
+$display-font-family: 'IBM Plex Mono', monospace !default;
 
 $primary: #000000 !default;
 $secondary: #cccccc !default;
@@ -146,59 +486,68 @@ $enable-cssgrid: true !default;
 
 $spacer: 1rem !default;
 $spacers: (
-	0: 0,
-	1: $spacer * 0.25,
-	2: $spacer * 0.5,
-	3: $spacer,
-	4: $spacer * 1.5,
-	5: $spacer * 3,
-	6: $spacer * 4.5,
-	7: $spacer * 6,
-	8: $spacer * 7.5,
-	9: $spacer * 9,
-	10: $spacer * 12,
+  0: 0,
+  1: $spacer * 0.25,
+  2: $spacer * 0.5,
+  3: $spacer,
+  4: $spacer * 1.5,
+  5: $spacer * 3,
+  6: $spacer * 4.5,
+  7: $spacer * 6,
+  8: $spacer * 7.5,
+  9: $spacer * 9,
+  10: $spacer * 12,
 ) !default;
 
 @import 'node_modules/bootstrap/scss/bootstrap';
 @import 'node_modules/animate.css/animate';
 ```
 
-### app/templates/application.hbs
+### Default application structure
 
-```handlebars
+```app/templates/application.hbs
 {{page-title 'Your Application Name'}}
 {{outlet}}
 <BasicDropdownWormhole />
 ```
 
-**Application.hbs Extension Guidelines:**
+```app/routes/application.js
+import Route from '@ember/routing/route';
+import * as bootstrap from 'bootstrap';
+import { service } from '@ember/service';
+import { later } from '@ember/runloop';
+import { action } from '@ember/object';
+
+export default class ApplicationRoute extends Route {
+  @service types;
+
+  //auto-sync backend types
+  async beforeModel() { await this.types.fetchAgain() }
+
+  @action
+  didTransition() { later( this, () => { document.querySelector('#loading').classList.add('d-none') }, 50 ) }
+
+  @action
+  willTransition() { document.querySelector('#loading').classList.remove('d-none') }
+}
+```
+
+**Application Extension Guidelines:**
 
 - Extend when adding global navigation components
 - Include shared modals or dropdowns
 - Add application-wide notification systems
 - Insert global loading states or overlays
 
-## EmberData Integration
+---
 
-### Automatic Model Generation
+## EmberData Integration
 
-Ember-tribe automatically generates models from backend track definitions through the `types` service:
-
-```javascript
-// app/routes/application.js
-export default class ApplicationRoute extends Route {
-	@service types;
-
-	async beforeModel() {
-		// Auto-generates models from backend
-		await this.types.fetchAgain();
-	}
-}
-```
+ember-tribe automatically generates models from backend track definitions through the `types` service:
 
 ### Data Access Patterns
 
-All backend data uses the `modules` key for field access:
+EmberData operations always use a "modules" key for field access, except for `.id` and `.slug` properties. All field names from backend storage use underscore notation: `modules.any_field`.
 
 ```javascript
 // Accessing track data
@@ -214,61 +563,72 @@ console.log(post.modules.content_privacy); // Universal field
 ```javascript
 // Complex queries
 this.store.query('post', {
-	modules: { status: 'published' }, // AND conditions
-	filter: { category: 'tech' }, // OR conditions
-	sort: 'title,-created_date', // Sort (- for desc)
-	page: { offset: 0, limit: 10 }, // Pagination
-	show_public_objects_only: false, // Include drafts
+  modules: { status: 'published' }, // AND conditions
+  filter: { category: 'tech' }, // OR conditions
+  sort: 'title,-created_date', // Sort (- for desc)
+  page: { offset: 0, limit: 10 }, // Pagination
+  show_public_objects_only: false, // Include drafts
 });
 ```
 
-## Styling System
+Smart use of EmberData can significantly reduce size of the codebase. Make sure you take advantage of that.
 
-### Default Configuration (app.scss)
+**Universal Default Module:**
+All objects include: `"content_privacy": "string | public, private, pending, draft"`
 
-```scss
-// Typography
-@import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Mono...');
-$font-family-sans-serif: 'IBM Plex Mono', serif !default;
+**Single Record Operations:**
 
-// Color Palette
-$primary: #000000 !default;
-$secondary: #cccccc !default;
-$success: #00ff00 !default;
-// ... additional colors
+```javascript
+// Find by ID or slug
+this.store.findRecord('track', 30);
+this.store.findRecord('track', 'some-slug-here');
 
-// Bootstrap Configuration
-$enable-rounded: false !default;
-$enable-negative-margins: true !default;
-$enable-cssgrid: true !default;
+// Access without network request (if already in store)
+let post = this.store.peekRecord('post', 1);
 
-@import 'node_modules/bootstrap/scss/bootstrap';
-@import 'node_modules/animate.css/animate';
+// Usage pattern
+this.store.findRecord('post', 1).then((post) => {
+  // Access: post.id, post.slug, post.modules.<field_name>
+});
 ```
 
-### Design Principles
-
-- **Minimal Controllers**: Logic should reside in components and services
-- **Bootstrap 5.x Foundation**: Responsive, accessible design system
-- **Subtle Animations**: animate.css for enhanced user experience
-- **FontAwesome 6.x**: Comprehensive icon library
+**Multiple Records:**
 
-## Component Architecture
+```javascript
+this.store
+  .query('person', {
+    modules: { name: 'Peter', location: 'delhi' }, //results with AND
+    /*
+    filter: { name: 'Peter', location: 'delhi' } //results with OR
+    sort: "location,-age,name", //minus for descending order of that field, default is -id
+    page: { offset:0, limit:-1 }, //for pagination or smart uses, -1 means everything
+    ignore_ids: [10,14] //excludes these IDs from results
+    show_public_objects_only: false, //default = true, if set false results include content_privacy = drafts, private or pending
+    */
+  })
+  .then((results) => {
+    // Process results
+  });
+```
 
-### Component Types
+Prefer using backend (this.store.query) for search, filter and sort, over front-end JS functions to achieve the same thing. Avoid using this.store.findAll altogether, use this.store.query with page: { offset:0, limit:-1 } instead.
 
-Based on storylang.json component definitions:
+**CRUD Operations:**
 
-**Layout Components:**
+```javascript
+// Update
+let post = await this.store.findRecord('post', 1);
+post.modules.title = 'A new title';
+await post.save(); // => PATCH request
 
-- `table`, `figure`, `accordion`, `card`, `list-group`
-- `navbar`, `nav`, `tab`, `breadcrumb`
+// Delete
+let post = this.store.peekRecord('post', 2);
+post.destroyRecord(); // => DELETE request
+```
 
-**Interactive Components:**
+---
 
-- `button`, `button-group`, `dropdown`, `modal`
-- `input-field`, `select`, `file-uploader`
-- `pagination`, `popover`, `tooltip`
+## Component Architecture
 
 ### Component Structure
 
@@ -280,13 +640,13 @@ import { action } from '@ember/object';
 import { service } from '@ember/service';
 
 export default class FileCardComponent extends Component {
-	@service store;
-	@tracked isSelected = false;
+  @service store;
+  @tracked isSelected = false;
 
-	@action
-	toggleSelection() {
-		this.isSelected = !this.isSelected;
-	}
+  @action
+  toggleSelection() {
+    this.isSelected = !this.isSelected;
+  }
 }
 ```
 
@@ -294,26 +654,19 @@ export default class FileCardComponent extends Component {
 
 ```handlebars
 <div
-	class='card {{if this.isSelected "border-primary"}}'
-	{{on 'click' this.toggleSelection}}
+  class='card {{if this.isSelected "border-primary"}}'
+  {{on 'click' this.toggleSelection}}
 >
-	<div class='card-body'>
-		<h5 class='card-title'>{{@file.modules.title}}</h5>
-		<p class='card-text'>{{@file.modules.description}}</p>
-	</div>
+  <div class='card-body'>
+    <h5 class='card-title'>{{@file.modules.title}}</h5>
+    <p class='card-text'>{{@file.modules.description}}</p>
+  </div>
 </div>
 ```
 
-## Services Integration
-
-### Built-in Services
+---
 
-- `store` - EmberData for CRUD operations
-- `router` - Navigation and route management
-- `types` - Automatic model generation
-- `bootstrap` - Bootstrap component initialization
-
-### Custom Services
+## Services Integration
 
 Make services based on storylang.json service definitions:
 
@@ -324,15 +677,17 @@ import { tracked } from '@glimmer/tracking';
 import { service } from '@ember/service';
 
 export default class VisualizationBuilderService extends Service {
-	@service store;
-	@tracked supportedTypes = ['network', 'tree', 'sankey'];
+  @service store;
+  @tracked supportedTypes = ['network', 'tree', 'sankey'];
 
-	buildVisualization(files, type, config) {
-		// Service logic implementation
-	}
+  buildVisualization(files, type, config) {
+    // Service logic implementation
+  }
 }
 ```
 
+---
+
 ## Route Generation
 
 ### Route Creation
@@ -344,22 +699,24 @@ import Route from '@ember/routing/route';
 import { service } from '@ember/service';
 
 export default class FilesRoute extends Route {
-	@service store;
-
-	queryParams = {
-		page: { refreshModel: true },
-		search: { refreshModel: true },
-	};
-
-	model(params) {
-		return this.store.query('json_file', {
-			page: { offset: (params.page - 1) * 10, limit: 10 },
-			modules: params.search ? { title: params.search } : {},
-		});
-	}
+  @service store;
+
+  queryParams = {
+    page: { refreshModel: true },
+    search: { refreshModel: true },
+  };
+
+  async model(params) {
+    return await this.store.query('json_file', {
+      page: { offset: (params.page - 1) * 10, limit: 10 },
+      modules: params.search ? { title: params.search } : {},
+    });
+  }
 }
 ```
 
+---
+
 ## Helper System
 
 ### Global Helpers
@@ -371,9 +728,9 @@ Make helpers based on storylang.json helper requirements:
 import { helper } from '@ember/component/helper';
 
 export default helper(function formatDate([date, format = 'short']) {
-	return new Intl.DateTimeFormat('en-US', {
-		dateStyle: format,
-	}).format(new Date(date));
+  return new Intl.DateTimeFormat('en-US', {
+    dateStyle: format,
+  }).format(new Date(date));
 });
 ```
 
@@ -381,10 +738,12 @@ export default helper(function formatDate([date, format = 'short']) {
 
 ```handlebars
 <span class='text-muted'>
-	{{format-date @post.modules.created_date 'medium'}}
+  {{format-date @post.modules.created_date 'medium'}}
 </span>
 ```
 
+---
+
 ## Modifier System
 
 ### DOM Interaction Modifiers
@@ -397,76 +756,15 @@ import { modifier } from 'ember-modifier';
 import { Tooltip } from 'bootstrap';
 
 export default modifier((element, [content]) => {
-	const tooltip = new bootstrap.Tooltip(element, {
-		title: content,
-	});
-
-	return () => tooltip.dispose();
-});
-```
-
-## Ember.js Reference Guide
-
-### EmberData Patterns
-
-Smart use of EmberData can significantly reduce size of the codebase. Make sure you take advantage of that.
-
-EmberData operations always use a "modules" key for field access, except for `.id` and `.slug` properties. All field names from backend storage use underscore notation: `modules.any_field`.
-
-**Universal Default Module:**
-All objects include: `"content_privacy": "string | public, private, pending, draft"`
-
-**Single Record Operations:**
+  const tooltip = new Tooltip(element, {
+    title: content,
+  });
 
-```javascript
-// Find by ID or slug
-this.store.findRecord('track', 30);
-this.store.findRecord('track', 'some-slug-here');
-
-// Access without network request (if already in store)
-let post = this.store.peekRecord('post', 1);
-
-// Usage pattern
-this.store.findRecord('post', 1).then((post) => {
-	// Access: post.id, post.slug, post.modules.<field_name>
+  return () => tooltip.dispose();
 });
 ```
 
-**Multiple Records:**
-
-```javascript
-this.store
-	.query('person', {
-		modules: { name: 'Peter', location: 'delhi' }, //results with AND
-		/*
-	  filter: { name: 'Peter', location: 'delhi' } //results with OR
-	  sort: "location,-age,name", //minus for descending order of that field, default is -id
-	  page: { offset:0, limit:-1 }, //for pagination or smart uses, -1 means everything
-	  ignore_ids: [10,14] //excludes these IDs from results
-	  show_public_objects_only: false, //default = true, if set false results include content_privacy = drafts, private or pending
-  	*/
-	})
-	.then((results) => {
-		// Process results
-	});
-```
-
-Prefer using backend (this.store.query) for search, filter and sort, over front-end JS functions to achieve the same thing. Avoid using this.store.findAll altogether, use this.store.query with page: { offset:0, limit:-1 } instead.
-
-**CRUD Operations:**
-
-```javascript
-// Update
-let post = await this.store.findRecord('post', 1);
-post.modules.title = 'A new title';
-await post.save(); // => PATCH request
-
-// Delete
-let post = this.store.peekRecord('post', 2);
-post.destroyRecord(); // => DELETE request
-```
-
-### Helpers
+## Writing Helpers
 
 Helper functions are JavaScript functions callable from Ember templates that perform computations or operations beyond basic template syntax, keeping templates clean while adding dynamic functionality.
 
@@ -479,8 +777,8 @@ Helper functions are JavaScript functions callable from Ember templates that per
 ```javascript
 // app/components/user-card.js
 export default class UserCard extends Component {
-	formatName = (firstName, lastName) =>
-		`${firstName} ${lastName}`.toUpperCase();
+  formatName = (firstName, lastName) =>
+    `${firstName} ${lastName}`.toUpperCase();
 }
 ```
 
@@ -529,8 +827,8 @@ Ember components should be thought of as templates that re-execute from scratch
 
 ```handlebars
 <article title='{{@article.modules.title}}'>
-	<header><h1>{{@article.modules.title}}</h1></header>
-	<section>{{@article.modules.body}}</section>
+  <header><h1>{{@article.modules.title}}</h1></header>
+  <section>{{@article.modules.body}}</section>
 </article>
 ```
 
@@ -541,7 +839,7 @@ Ember components should be thought of as templates that re-execute from scratch
 
 ```handlebars
 <div class={{if @user.modules.is_admin 'superuser' 'standard'}}>
-	Welcome to my app.
+  Welcome to my app.
 </div>
 ```
 
@@ -558,12 +856,12 @@ import { action } from '@ember/object';
 import { tracked } from '@glimmer/tracking';
 
 export default class CounterComponent extends Component {
-	@tracked count = 0;
+  @tracked count = 0;
 
-	@action
-	increment() {
-		this.count++;
-	}
+  @action
+  increment() {
+    this.count++;
+  }
 }
 ```
 
@@ -598,11 +896,11 @@ play() {
 import { modifier } from 'ember-modifier';
 
 export default modifier((element, [isPlaying]) => {
-	if (isPlaying) {
-		element.play();
-	} else {
-		element.pause();
-	}
+  if (isPlaying) {
+    element.play();
+  } else {
+    element.pause();
+  }
 });
 ```
 
@@ -627,19 +925,13 @@ import { TrackedArray } from 'tracked-built-ins';
 import Service from '@ember/service';
 
 export default class ShoppingCartService extends Service {
-	items = new TrackedArray([]);
+  items = new TrackedArray([]);
 
-	add(item) {
-		this.items.push(item);
-	}
+  add(item) { this.items.push(item) }
 
-	remove(item) {
-		this.items.splice(this.items.indexOf(item), 1);
-	}
+  remove(item) { this.items.splice(this.items.indexOf(item), 1) }
 
-	empty() {
-		this.items.splice(0, this.items.length);
-	}
+  empty() { this.items.splice(0, this.items.length) }
 }
 ```
 
@@ -650,16 +942,12 @@ import Component from '@glimmer/component';
 import { service } from '@ember/service';
 
 export default class CartContentsComponent extends Component {
-	// Loads service from: app/services/shopping-cart.js
-	@service shoppingCart;
+  // Loads service from: app/services/shopping-cart.js
+  @service shoppingCart;
 }
 ```
 
-**Usage Guidelines:**
-
-- Use for application-wide state management
-- Share functionality across multiple routes/components
-- Maintain data that survives route transitions
+---
 
 ## Code Generation Process
 
@@ -693,113 +981,21 @@ async uploadFile(file) {
 }
 ```
 
-### Installation Commands
-
-```bash
-# Write all installer.sh commands
-ember g route files
-ember g controller files
-ember g component file-card -gc
-ember g helper format-date
-ember g modifier tooltip
-ember g service visualization-builder
-```
-
-### Pre-approval Process
-
-Before code generation, ember-tribe requests approval for additional packages:
-
-```bash
-# Example approval request
-npm i chart.js
-npm i lodash
-ember install ember-table
-```
-
-## Application Structure
-
-### Application Template
-
-```handlebars
-{{page-title 'Your Application Name'}}
-{{outlet}}
-<BasicDropdownWormhole />
-```
+---
 
 ## Best Practices
 
-### Controller Minimization
-
-- Keep controllers minimal - prefer component logic
-- Use controllers only for query params and route-level actions
-- Move business logic to services
-
-### Animation Guidelines
-
-- Use animate.css for enhanced UX
-- Prefer subtle animations (fadeIn, slideIn)
-- Avoid overwhelming users with excessive animation
-
-### Data Flow
-
-1. **Routes**: Fetch and prepare data
-2. **Components**: Display and interact with data
-3. **Services**: Handle business logic and state
-4. **Helpers**: Transform data for display
-
-### Performance Considerations
-
-- Leverage EmberData caching with `peekRecord`
-- Use backend filtering over frontend array manipulation
-- Implement pagination for large datasets
-- Minimize controller file count
-
-## Integration Examples
+1. **Module Access**: Remember to use `modules.field_name` for backend fields
+2. **npm packages vs ember addons**: Prioritize npm packages over ember addons for better compatibility, when both are offering similar functionality
+3. **Minimal Controllers**: Logic should ideally reside in components and services
+4. **Bootstrap 5.x Foundation**: Responsive, accessible design system
+5. **Use FontAwesome 6.x**: Comprehensive icon library
+6. **Animations**: If required, use animate.css for enhanced user experience. Prefer subtle animations (fadeIn, slideIn). Avoid overwhelming users with excessive animation
+7. **Access Cache**: Leverage EmberData caching with `peekRecord`
+8. **Avoid array manipulations of backend data**: Use backend filtering over frontend array manipulation
 
-### With Junction CMS
-
-```javascript
-// Automatic sync with Junction tracks
-async beforeModel() {
-  await this.types.fetchAgain(); // Syncs with backend types
-}
-```
-
-### With External APIs
-
-```javascript
-// Service for external integrations
-@service externalApi;
-
-async model() {
-  const localData = await this.store.query('post', {});
-  const externalData = await this.externalApi.fetch('/posts');
-  return { local: localData, external: externalData };
-}
-```
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Model Not Found**: Ensure `types.fetchAgain()` completes in application route
-2. **Module Access**: Remember to use `modules.field_name` for backend fields
-3. **Bootstrap Components**: Initialize through modifier or service
-4. **Animation Conflicts**: Check animate.css class conflicts
-
-### Debug Commands
-
-```javascript
-// Check loaded models
-this.store.peekAll('your-model-name');
-
-// Verify service registration
-this.owner.lookup('service:your-service');
-
-// Route debugging
-console.log(this.router.currentRouteName);
-```
+---
 
 # License
 
-This project is licensed under the [GNU GPL v3 License](LICENSE.md).
+This project is licensed under the [GNU GPL v3 License](LICENSE.md).

package/blueprints/ember-tribe/files/app/components/welcome-flame.gjs

@@ -0,0 +1,11 @@
+import Component from '@glimmer/component';
+
+export default class WelcomeFlameComponent extends Component {
+  <template>
+    <section class="flame-bg d-flex align-items-center justify-content-center">
+      <div class="py-6 container px-0 text-center text-dark">
+        <img src="/assets/img/flame.png" width="200">
+      </div>
+    </section>
+  </template>
+}

package/blueprints/ember-tribe/files/app/templates/application.gjs

@@ -0,0 +1,6 @@
+import { pageTitle } from 'ember-page-title';
+
+<template>
+  {{pageTitle "<%= classifiedPackageName %>"}}
+  {{outlet}}
+</template>

package/blueprints/ember-tribe/files/app/templates/index.gjs

@@ -0,0 +1,11 @@
+import WelcomeFlame from '../components/welcome-flame';
+
+<template>
+  {{! Remove the WelcomeFlame component and write your HTML code here }}
+
+  <WelcomeFlame />
+
+  {{! / }}
+
+  {{outlet}}
+</template>

package/blueprints/ember-tribe/index.js

@@ -17,20 +17,19 @@ module.exports = {
         { name: 'ember-math-helpers' },
         { name: 'ember-cli-string-helpers' },
         { name: 'ember-promise-helpers' },
-        { name: '@ember/test-waiters', target: '^3.1.0' },
+        { name: '@ember/test-waiters' },
         { name: 'ember-tag-input' },
         { name: 'ember-file-upload' },
         { name: 'ember-toggle' },
-        { name: 'ember-basic-dropdown' },
-        { name: 'ember-power-select' },
+        { name: 'ember-concurrency' },
         { name: 'ember-click-outside' },
         { name: 'ember-web-app' },
         { name: 'tracked-built-ins' },
         { name: 'ember-keyboard' },
         { name: 'ember-router-scroll' },
-        { name: 'ember-concurrency' },
         { name: 'ember-table' },
         { name: 'ember-animated' },
+        { name: 'ember-power-select' },
       ],
     }).then(() => {
       return this.addPackagesToProject([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ember-tribe",
-  "version": "2.5.1",
+  "version": "2.5.3",
   "description": "The default blueprint for using Tribe API and Junction within EmberJS.",
   "keywords": [
     "ember-addon"
@@ -38,7 +38,7 @@
     "babel-eslint": "^10.1.0",
     "broccoli-asset-rev": "^3.0.0",
     "ember-auto-import": "^2.2.4",
-    "ember-cli": "^6.0.0",
+    "ember-cli": "^6.4.0",
     "ember-cli-dependency-checker": "^3.2.0",
     "ember-cli-inject-live-reload": "^2.1.0",
     "ember-cli-sri": "^2.1.1",
@@ -66,6 +66,9 @@
     "qunit-dom": "^2.0.0",
     "webpack": "^5.65.0"
   },
+  "peerDependencies": {
+    "ember-cli": "<=6.4.0"
+  },
   "engines": {
     "node": "12.* || 14.* || >= 16"
   },

package/blueprints/ember-tribe/files/app/components/welcome-flame.hbs

@@ -1,5 +0,0 @@
-<section class="flame-bg d-flex align-items-center justify-content-center">
-  <div class="py-6 container px-0 text-center text-dark">
-    <img src="/assets/img/flame.png" width="200">
-  </div>
-</section>

package/blueprints/ember-tribe/files/app/templates/application.hbs

@@ -1,2 +0,0 @@
-{{page-title "<%= classifiedPackageName %>"}}
-{{outlet}}

package/blueprints/ember-tribe/files/app/templates/index.hbs

@@ -1,7 +0,0 @@
-{{!-- Remove the WelcomeFlame component and write your HTML code here --}}
-
-  <WelcomeFlame />
-
-{{!-- / --}}
-
-{{outlet}}