ember-tribe 2.6.8 → 2.6.9

package/README.md

@@ -4,6 +4,46 @@ An addon that connects EmberJS to Tribe API, bridging the gap between backend da
 
 Tribe is a project management framework built for ease of collaboration - https://github.com/tribe-framework/tribe
 
+---
+
+## Table of Contents
+
+- [Installation and Setup](#installation-and-setup)
+- [Folder Structure](#folder-structure)
+- [Best Practices for AI Generated Code](#best-practices-for-ai-generated-code)
+  - [Code Rules](#code-rules)
+  - [Storylang Rules](#storylang-rules)
+    - [Types](#types)
+    - [Routes](#routes)
+    - [Controllers](#controllers)
+    - [Helpers](#helpers)
+    - [Modifiers](#modifiers)
+    - [Services](#services)
+    - [Components](#components)
+- [Storylang](#storylang)
+  - [Storylang CLI](#storylang-cli)
+  - [Storylang.json Documentation](#storylangjson-documentation)
+    - [Types](#1-types)
+    - [Routes](#2-routes)
+    - [Helpers](#3-helpers)
+    - [Modifiers](#4-modifiers)
+    - [Services](#5-services)
+    - [Components](#6-components)
+    - [Data Types Reference](#data-types-reference)
+    - [Integration with Other Files](#integration-with-other-files)
+- [EmberJS](#emberjs)
+  - [Ember-Tribe Development Guide](#ember-tribe-development-guide)
+    - [EmberData Integration](#emberdata-integration)
+    - [Route Generation](#route-generation)
+    - [Helper System](#helper-system)
+    - [Modifier System](#modifier-system)
+    - [Services Integration](#services-integration)
+    - [Component Architecture](#component-architecture)
+    - [Forms and Input Fields](#forms-and-input-fields)
+  - [Deploying to Junction (Self-Hosted)](#deploying-to-junction-self-hosted)
+
+---
+
 ## Installation and Setup
 
 ### Prerequisites
@@ -41,7 +81,7 @@ The addon automatically configures following essential packages:
 
 ---
 
-## Core File Structure
+## Folder Structure
 
 ```
 app/
@@ -65,32 +105,35 @@ installer.sh
 
 These rules are **mandatory** for all Tribe-compatible code. Follow them strictly and do not deviate unless explicitly instructed.
 
-### General Rules
+### Code Rules
+
+1. **EmberJS 6.x Compatibility — Strictly Required**
+   All generated code must be strictly compatible with EmberJS 6.x.
 
-1. **Bootstrap 5.x — Required Foundation**
+2. **Bootstrap 5.x — Required Foundation**
    Use Bootstrap 5.x as the sole design system for all layout, spacing, and responsive behaviour. Do not introduce custom CSS frameworks or utility libraries that conflict with Bootstrap. Follow Bootstrap conventions strictly.
 
-2. **Backend Field Access**
+3. **Backend Field Access**
    Always access backend fields through the `modules` object — e.g. `object.modules.field_name`. Never access backend fields directly.
 
-3. **npm Packages over Ember Addons**
+4. **npm Packages over Ember Addons**
    When an npm package and an Ember addon offer equivalent functionality, always prefer the npm package for better long-term compatibility.
 
-4. **Icons — FontAwesome 6.x Only**
+5. **Icons — FontAwesome 6.x Only**
    Use FontAwesome 6.x for all icons. Do not use any other icon library unless the project description explicitly specifies one.
 
-5. **Animations — Subtle and Purposeful**
+6. **Animations — Subtle and Purposeful**
    If animations are needed, use `animate.css`. Keep animations subtle — prefer fades and minimal slides. Avoid anything that feels flashy or distracting.
 
-6. **EmberData Caching**
+7. **EmberData Caching**
    When data has already been loaded into the store, retrieve it with `peekRecord` instead of making a new network request.
 
-7. **Backend Filtering over Frontend Filtering**
+8. **Backend Filtering over Frontend Filtering**
    For sorting and filtering data, always use `this.store.query` with backend query parameters. Do not filter or sort arrays on the frontend when the backend can do it.
 
 ---
 
-### Storylang Architecture Rules
+### Storylang Rules
 
 Follow this strict order of thinking when designing any feature:
 
@@ -102,20 +145,20 @@ Always begin by understanding your data types, then define the routes that load
 
 **Types**
 
-11. **Start by Understanding Your Data**
+8. **Start by Understanding Your Data**
     Before writing any code, read the project description and `types.json` to understand the data model. Every architectural decision that follows — which routes to create, which services to build, whether components are even needed — depends on a clear understanding of the underlying types.
 
 ---
 
 **Routes**
 
-8. **Route Naming**
+9. **Route Naming**
    Match route names to user mental models. Use consistent, predictable naming conventions so that routes are self-documenting.
 
-9. **Routes Are for Fetching, Not Logic**
+10. **Routes Are for Fetching, Not Logic**
    Routes should primarily perform read/fetch operations and pass data down to components or services. Keep JavaScript in routes to a minimum — business logic belongs in components and services, not routes.
 
-10. **Route Parameters**
+11. **Route Parameters**
     Keep `get_vars` minimal and meaningful. Load only the data types that each specific route actually needs — avoid over-fetching.
 
 ---
@@ -132,40 +175,51 @@ Always begin by understanding your data types, then define the routes that load
 
 **Helpers**
 
-17. **Helpers Must Be Pure and Stateless**
+14. **Helpers Must Be Pure and Stateless**
     A helper receives input and returns output — nothing else. Helpers must have no side effects and must not interact with the store, services, or DOM.
 
 ---
 
 **Modifiers**
 
-18. **Modifiers Own All DOM Interaction**
+15. **Modifiers Own All DOM Interaction**
     Any direct DOM manipulation or third-party library initialisation must live in a modifier.
 
 ---
 
 **Services**
 
-15. **Services Are the Core Logic Layer**
+16. **Services Are the Core Logic Layer**
     Services hold the primary business logic of the application. They interact with both routes and components and are the single source of truth for app-wide behaviour.
 
-16. **Keep Services Stateless When Possible**
+17. **Keep Services Stateless When Possible**
     Avoid storing transient state in services. Where services must depend on one another, use dependency injection.
 
+18. **All Backend Calls Must Live Inside `@action` Functions**
+    Any call to a `/custom/*.php` script must be made from within an `@action` function. This rule makes backend interactions explicit, traceable, and user-initiated by design.
+
+19. **Plain Methods Belong in `functions`, Not `actions`**
+    Internal methods, which carry no special Ember semantics, should be traced automatically under the `functions` key in `storylang.json`. Do not decorate them with `@action`. Keeping `actions` reserved for user-facing interactions makes the intent of each method immediately clear to anyone reading the spec.
+
+20. **Getters Are Derived Properties — Not Actions or Functions**
+    Native JavaScript `get` accessors (e.g. `get trustScoreColor()`) derive a display value, CSS class, or conditional flag from `this.args` or other state. They carry no side effects and require no `@action` decorator. Storylang captures them under the `getters` key, separate from `actions` and `functions`, so the distinction between user-facing interactions, internal logic, and pure derived state is always explicit in the spec.
+
 ---
 
 **Components**
 
-14. **Components are not always required**
+21. **Components are not always required**
     Before creating components, assess the scale of the project from its description. On small projects, fewer files means higher code readability — collapsing template logic directly into route templates is often the right call. On larger projects, the opposite is true: extracting repeatable UI into named components improves clarity, maintainability, and testability. Make this decision deliberately at the start, not as an afterthought.
 
 ---
 
-## Storylang CLI
+## Storylang
+
+### Storylang CLI
 
 ember-tribe ships with a command-line tool called `storylang` that synchronises the `config/storylang.json` specification with the actual Ember project files.
 
-### Usage
+#### Usage
 
 ```bash
 node storylang
@@ -182,26 +236,26 @@ node storylang
 # => config/storylang.json updated from project files
 ```
 
-### Typical Workflow
+#### Typical Workflow
 
 Run `node storylang` periodically to keep `config/storylang.json` in sync as the project evolves.
 
 ---
 
-## Storylang.json Documentation
+### Storylang.json Documentation
 
-### Overview
+#### Overview
 
 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.
 
-### Purpose
+#### 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
+#### File Structure
 
 The storylang.json file contains seven main sections:
 
@@ -216,9 +270,10 @@ The storylang.json file contains seven main sections:
 }
 ```
 
-### Section Definitions
 
-### 1. Types
+#### Section Definitions
+
+#### 1. 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.
 
@@ -243,10 +298,12 @@ The storylang.json file contains seven main sections:
 
 ---
 
-### 2. Routes
+#### 2. Routes
 
 **Purpose**: Defines the application's routes and their requirements.
 
+> **Note on controllers**: In `storylang.json`, controllers are not listed as a separate top-level section. Instead, each controller is considered part of its corresponding route — just as a component's backing JavaScript class is part of its component entry. Controller actions, tracked variables, and query parameters should be specified within the route definition they belong to.
+
 **Format**:
 
 ```json
@@ -256,7 +313,9 @@ The storylang.json file contains seven main sections:
       "name": "route-name", //should match Ember router.js
       "tracked_vars": [{ "<variableName>": "<dataType>" }],
       "get_vars": [{ "<paramName>": "<dataType>" }],
-      "actions": ["action1", "action2"],
+      "getters": ["derived-property-name"],
+      "actions": ["frontend-action", { "backend-action": ["custom/path/file.php"] }],
+      "functions": ["helper-method", "compute-something"],
       "helpers": ["helper1"],
       "services": ["service1"],
       "components": ["component1", "component2"],
@@ -266,9 +325,11 @@ The storylang.json file contains seven main sections:
 }
 ```
 
+> **Actions format**: `actions` is a mixed array. Pure frontend actions are plain strings. Actions that call one or more `/custom/*.php` scripts are objects whose key is the action name and whose value is the list of PHP paths called — e.g. `{ "save-record": ["custom/records/save.php"] }`.
+
 ---
 
-### 3. Helpers
+#### 3. Helpers
 
 **Purpose**: Defines custom template helpers — pure functions used in templates to format, compute or transform data for display.
 
@@ -310,7 +371,7 @@ The storylang.json file contains seven main sections:
 
 ---
 
-### 4. Modifiers
+#### 4. Modifiers
 
 **Purpose**: Defines custom Ember modifiers — functions that directly interact with DOM elements to attach behaviour, third-party libraries or event listeners.
 
@@ -352,7 +413,7 @@ The storylang.json file contains seven main sections:
 
 ---
 
-### 5. Services
+#### 5. Services
 
 **Purpose**: Defines custom Ember services needed by the application.
 
@@ -364,7 +425,9 @@ The storylang.json file contains seven main sections:
     {
       "name": "service-name",
       "tracked_vars": [{ "<variableName>": "<dataType>" }],
-      "actions": ["action1", "action2"],
+      "getters": ["derived-property-name"],
+      "actions": ["frontend-action", { "backend-action": ["custom/path/file.php"] }],
+      "functions": ["internal-method"],
       "helpers": ["helper1"],
       "services": ["dependency1", "dependency2"]
     }
@@ -380,13 +443,14 @@ The storylang.json file contains seven main sections:
     {
       "name": "visualization-builder",
       "tracked_vars": [
-        { "currentVisualization": "object" },
+        { "dataMatrix": "object" },
         { "availableTypes": "array" }
       ],
+      "functions": ["build-visualization"],
       "actions": [
-        "createVisualization",
-        "updateVisualization",
-        "deleteVisualization"
+        "reset-state",
+        { "assemble-data-for-visualization": ["custom/visualizations/assemble-data.php"] },
+        "updateVisualization"
       ],
       "helpers": ["validateConfig", "generatePreview"],
       "services": ["store", "router"]
@@ -397,7 +461,7 @@ The storylang.json file contains seven main sections:
 
 ---
 
-### 6. Components
+#### 6. Components
 
 **Purpose**: Defines reusable UI components that will be built for the application.
 
@@ -411,7 +475,9 @@ The storylang.json file contains seven main sections:
       "type": "component-type",
       "tracked_vars": [{ "<variableName>": "<dataType>" }],
       "inherited_args": [{ "<argumentName>": "<argType>" }],
-      "actions": ["action1", "action2"],
+      "getters": ["derived-property-name"],
+      "actions": ["frontend-action", { "backend-action": ["custom/path/file.php"] }],
+      "functions": ["internal-method"],
       "helpers": ["helper1", "helper2"],
       "modifiers": ["modifier1"],
       "services": ["service1", "service2"]
@@ -420,6 +486,7 @@ The storylang.json file contains seven main sections:
 }
 ```
 
+
 **Example**:
 
 ```json
@@ -434,7 +501,8 @@ The storylang.json file contains seven main sections:
         { "onEdit": "action" },
         { "onDelete": "action" }
       ],
-      "actions": ["toggleSelection", "expandDetails", "editFile", "deleteFile"],
+      "getters": ["trust-score-color", "display-label"],
+      "actions": ["toggle-selection", "expand-details", { "save-file": ["custom/files/save.php"] }, { "delete-file": ["custom/files/delete.php"] }],
       "helpers": ["formatDate", "truncateText"],
       "modifiers": ["tooltip"],
       "services": ["store", "router"]
@@ -445,9 +513,9 @@ The storylang.json file contains seven main sections:
 
 ---
 
-### Data Types Reference
+#### Data Types Reference
 
-### Data Types (dataType)
+#### Data Types (dataType)
 
 - `string`: Text values
 - `int`: Integer numbers
@@ -455,32 +523,35 @@ The storylang.json file contains seven main sections:
 - `array`: List of items
 - `object`: Complex data structure
 
-### Argument Types (argType)
+#### Argument Types (argType)
 
 - `var`: Passed data/state
-- `fn`: Callback function
+- `function`: Callback function
 - `get`: Get function
 - `action`: User interaction handler
 
 ---
 
-### Integration with Other Files
+#### Integration with Other Files
 
-### With types.json
+#### 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
+- For a full reference on the `types.json` format and its field definitions, see the official documentation at [https://github.com/tribe-framework/types.json](https://github.com/tribe-framework/types.json)
 
 ---
 
-## Ember-Tribe Development Guide
+## EmberJS
+
+### Ember-Tribe Development Guide
 
-### Required File Outputs
+#### Required File Outputs
 
 Make separate, complete code files for each category:
 
-### Example installer.sh
+#### Example installer.sh
 
 ```bash
 npm i chart.js
@@ -494,7 +565,7 @@ ember g modifier tooltip
 ember g service visualization-builder
 ```
 
-### Default styling
+#### Default styling
 
 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.
 
@@ -536,7 +607,7 @@ $spacers: (
 @import 'node_modules/animate.css/animate';
 ```
 
-### Default application structure
+#### Default application structure
 
 ```app/templates/application.hbs
 {{page-title 'Your Application Name'}}
@@ -574,11 +645,11 @@ export default class ApplicationRoute extends Route {
 
 ---
 
-## EmberData Integration
+### EmberData Integration
 
 ember-tribe automatically generates models from backend track definitions through the `types` service:
 
-### Data Access Patterns
+#### Data Access Patterns
 
 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`.
 
@@ -591,7 +662,7 @@ console.log(post.modules.title); // Field access
 console.log(post.modules.content_privacy); // Universal field
 ```
 
-### Query Operations
+#### Query Operations
 
 ```javascript
 // Complex queries
@@ -604,6 +675,25 @@ this.store.query('post', {
 });
 ```
 
+#### `modules` vs `filter`: AND vs OR Queries
+
+When querying records, `modules` and `filter` serve distinct purposes that map directly to how the backend constructs its SQL or query logic.
+
+**`modules`** applies **AND** logic: every key-value pair in the object must match for a record to be included. Use this when you want to narrow results to records that simultaneously satisfy all of the given conditions — for example, posts that are both `published` and belong to a specific `author_id`.
+
+**`filter`** applies **OR** logic: a record is included if it matches *any* of the key-value pairs. Use this when you want to broaden results across multiple values of a field — for example, items whose `category` is either `tech` or `design`.
+
+The two can be combined in the same query. For instance, to find all published posts that are tagged as either `news` or `feature`:
+
+```javascript
+this.store.query('post', {
+  modules: { status: 'published' }, // must be published
+  filter: { tag: 'news', section: 'feature' }, // tagged news OR in feature section
+});
+```
+
+Always prefer expressing these constraints via `modules` and `filter` over post-processing results in JavaScript — the backend handles this far more efficiently.
+
 Smart use of EmberData can significantly reduce size of the codebase. Make sure you take advantage of that.
 
 **Universal Default Module:**
@@ -630,9 +720,9 @@ this.store.findRecord('post', 1).then((post) => {
 ```javascript
 this.store
   .query('person', {
-    modules: { name: 'Peter', location: 'delhi' }, //results with AND
+    modules: { name: 'Peter', location: 'delhi' }, //AND: both conditions must match
     /*
-    filter: { name: 'Peter', location: 'delhi' } //results with OR
+    filter: { name: 'Peter', location: 'delhi' } //OR: either condition can match
     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
@@ -661,9 +751,9 @@ post.destroyRecord(); // => DELETE request
 
 ---
 
-## Route Generation
+### Route Generation
 
-### Route Creation
+#### Route Creation
 
 Make routes based on storylang.json route definitions:
 
@@ -690,9 +780,9 @@ export default class FilesRoute extends Route {
 
 ---
 
-## Helper System
+### Helper System
 
-### Global Helpers
+#### Global Helpers
 
 Make helpers based on storylang.json helper requirements:
 
@@ -707,7 +797,7 @@ export default helper(function formatDate([date, format = 'short']) {
 });
 ```
 
-### Template Usage
+#### Template Usage
 
 ```handlebars
 <span class='text-muted'>
@@ -717,9 +807,9 @@ export default helper(function formatDate([date, format = 'short']) {
 
 ---
 
-## Modifier System
+### Modifier System
 
-### DOM Interaction Modifiers
+#### DOM Interaction Modifiers
 
 Make modifiers for specific DOM manipulation needs:
 
@@ -737,7 +827,7 @@ export default modifier((element, [content]) => {
 });
 ```
 
-## Writing 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.
 
@@ -792,7 +882,7 @@ export default function formatCurrency(amount, currency = 'USD') {
 - Local: Component-specific logic, simple transformations
 - Global: Reusable functionality across multiple components (formatting, calculations)
 
-### Component Architecture & Principle of Substitution
+#### Component Architecture & Principle of Substitution
 
 Ember components should be thought of as templates that re-execute from scratch whenever data changes. Write templates that produce correct output for any given input; Ember efficiently updates only what has changed.
 
@@ -838,7 +928,7 @@ export default class CounterComponent extends Component {
 }
 ```
 
-### Component Communication & Modifiers
+#### Component Communication & Modifiers
 
 **Design Pattern:**
 
@@ -886,7 +976,7 @@ Modifiers applied to components pass through via `...attributes`:
 <div ...attributes>...</div>
 ```
 
-### Services
+#### Services
 
 Services are Ember objects that persist for the entire application duration, providing shared state or persistent connections across different parts of your app.
 
@@ -922,7 +1012,7 @@ export default class CartContentsComponent extends Component {
 
 ---
 
-## Services Integration
+### Services Integration
 
 Make services based on storylang.json service definitions:
 
@@ -944,9 +1034,9 @@ export default class VisualizationBuilderService extends Service {
 
 ---
 
-## Component Architecture
+### Component Architecture
 
-### Component Structure
+#### Component Structure
 
 ```javascript
 // Component class
@@ -966,7 +1056,7 @@ export default class FileCardComponent extends Component {
 }
 ```
 
-### Template Patterns
+#### Template Patterns
 
 ```handlebars
 <div
@@ -982,9 +1072,9 @@ export default class FileCardComponent extends Component {
 
 ---
 
-## Forms and Input Fields
+### Forms and Input Fields
 
-### File upload javascript example
+#### File upload javascript example
 
 ```javascript
 import ENV from '<your-application-name>/config/environment';
@@ -1014,7 +1104,7 @@ async uploadFile(file) {
 }
 ```
 
-### Input and Textarea fields
+#### Input and Textarea fields
 
 Use Ember's built-in `<Input>` component instead of a raw `<input>` tag — it automatically updates bound state via `@value`.
 
@@ -1073,7 +1163,7 @@ export default class ExampleComponent extends Component {
 - Use the `{{on}}` modifier for event handling (e.g. `{{on "input" this.handler}}`).
 - Bootstrap styles `form-control` correctly when `disabled` is present
 
-### ember-power-select example
+#### ember-power-select example
 
 `ember-power-select` is the recommended way to implement searchable, single, and multi-select dropdowns in ember-tribe. It is pre-installed and works alongside Bootstrap 5.x. Use it wherever a native `<select>` would be insufficient — e.g. when you need search/filter, async options, or multi-select.
 
@@ -1163,7 +1253,7 @@ export default class ExampleComponent extends Component {
 
 ---
 
-## Deploying to Junction (Self-Hosted)
+### Deploying to Junction (Self-Hosted)
 
 After building your Ember app, run `php-dist` to prepare the `dist/` folder for PHP middleware: