ember-tribe 2.6.7 → 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
@@ -26,11 +66,22 @@ The addon automatically configures following essential packages:
 
 **Ember Addons:** `ember-cli-dotenv`, `ember-cli-sass`, `ember-modifier`, `ember-composable-helpers`, `ember-truth-helpers`, `ember-file-upload` , `ember-power-select`
 
-**NPM Packages:** `bootstrap`, `@popperjs/core`, `animate.css`, `video.js`, `swiper`,  `howler`
+**NPM Packages:** `bootstrap`, `@popperjs/core`, `animate.css`, `video.js`, `swiper`,  `howler`, `sortablejs`, `papaparse`
+
+**Built-in features that can be used in routes and components**:
+
+- **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`
+
+**Preinstalled services in ember-tribe**:
+
+- `store`: Ember Data store for CRUD operations
+- `router`: Ember router service for navigation
+- `types`: Automatic model generation from backend tracks
 
 ---
 
-## Core File Structure
+## Folder Structure
 
 ```
 app/
@@ -50,11 +101,125 @@ installer.sh
 
 ---
 
-## Storylang CLI
+## Best Practices for AI generated code
+
+These rules are **mandatory** for all Tribe-compatible code. Follow them strictly and do not deviate unless explicitly instructed.
+
+### Code Rules
+
+1. **EmberJS 6.x Compatibility — Strictly Required**
+   All generated code must be strictly compatible with EmberJS 6.x.
+
+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.
+
+3. **Backend Field Access**
+   Always access backend fields through the `modules` object — e.g. `object.modules.field_name`. Never access backend fields directly.
+
+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.
+
+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.
+
+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.
+
+7. **EmberData Caching**
+   When data has already been loaded into the store, retrieve it with `peekRecord` instead of making a new network request.
+
+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 Rules
+
+Follow this strict order of thinking when designing any feature:
+
+> **Understand Types → Routes → Controllers → Helpers → Modifiers → Services → Components**
+
+Always begin by understanding your data types, then define the routes that load that data, then wire up controllers to handle user actions, then extract reusable template logic into helpers, then isolate DOM behaviour into modifiers, then move app-wide logic into services, and finally — only when the project's scale warrants it — extract repeatable UI into components.
+
+---
+
+**Types**
+
+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**
+
+9. **Route Naming**
+   Match route names to user mental models. Use consistent, predictable naming conventions so that routes are self-documenting.
+
+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.
+
+11. **Route Parameters**
+    Keep `get_vars` minimal and meaningful. Load only the data types that each specific route actually needs — avoid over-fetching.
+
+---
+
+**Controllers**
+
+12. **Controllers Bridge Routes and Templates**
+    Controllers sit between routes and templates, handling query parameters, user actions, and transient UI state that belongs to a specific route. Keep controllers focused — they are not a place for business logic or data fetching.
+
+13. **Keep Controllers Thin**
+    Delegate complex logic to services. A controller should primarily expose tracked properties and actions that the corresponding template needs directly.
+
+---
+
+**Helpers**
+
+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**
+
+15. **Modifiers Own All DOM Interaction**
+    Any direct DOM manipulation or third-party library initialisation must live in a modifier.
+
+---
+
+**Services**
+
+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.
+
+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**
+
+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
+
+### 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
@@ -71,58 +236,44 @@ 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:
 
 ```json
 {
-  "implementation_approach": "...",
   "types": [...],
-  "components": [...],
   "routes": [...],
-  "services": [...],
   "helpers": [...],
-  "modifiers": [...]
+  "modifiers": [...],
+  "services": [...],
+  "components": [...]
 }
 ```
 
-### Section Definitions
 
-### 1. Implementation Approach
+#### Section Definitions
 
-**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
+#### 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.
 
@@ -147,77 +298,72 @@ The storylang.json file contains seven main sections:
 
 ---
 
-### 3. Components
+#### 2. Routes
 
-**Purpose**: Defines reusable UI components that will be built for the application.
+**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
 {
-  "components": [
+  "routes": [
     {
-      "name": "component-name",
-      "type": "component-type",
+      "name": "route-name", //should match Ember router.js
       "tracked_vars": [{ "<variableName>": "<dataType>" }],
-      "inherited_args": [{ "<argumentName>": "<argType>" }],
-      "actions": ["action1", "action2"],
-      "helpers": ["helper1", "helper2"],
-      "modifiers": ["modifier1"],
-      "services": ["service1", "service2"]
+      "get_vars": [{ "<paramName>": "<dataType>" }],
+      "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"],
+      "types": ["type1", "type2"]
     }
   ]
 }
 ```
 
-**Built-in Component Types in ember-tribe**:
+> **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"] }`.
 
-- **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**:
+#### 3. Helpers
+
+**Purpose**: Defines custom template helpers — pure functions used in templates to format, compute or transform data for display.
+
+**Format**:
 
 ```json
 {
-  "components": [
+  "helpers": [
     {
-      "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"]
+      "name": "helper-name",
+      "description": "What this helper does",
+      "input_args": [{ "<argumentName>": "<dataType>" }],
+      "return": "<dataType>"
     }
   ]
 }
 ```
 
----
-
-### 4. Routes
-
-**Purpose**: Defines the application's routes and their requirements.
-
-**Format**:
+**Example**:
 
 ```json
 {
-  "routes": [
+  "helpers": [
     {
-      "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"]
+      "name": "format-date",
+      "description": "Formats a raw ISO date string into a human-readable date",
+      "input_args": [{ "isoString": "string" }, { "format": "string" }],
+      "return": "string"
+    },
+    {
+      "name": "truncate-text",
+      "description": "Truncates a string to a given character limit and appends an ellipsis",
+      "input_args": [{ "text": "string" }, { "limit": "int" }],
+      "return": "string"
     }
   ]
 }
@@ -225,56 +371,41 @@ The storylang.json file contains seven main sections:
 
 ---
 
-### 5. Services
+#### 4. Modifiers
 
-**Purpose**: Defines custom Ember services needed by the application.
+**Purpose**: Defines custom Ember modifiers — functions that directly interact with DOM elements to attach behaviour, third-party libraries or event listeners.
 
 **Format**:
 
 ```json
 {
-  "services": [
+  "modifiers": [
     {
-      "name": "service-name",
-      "tracked_vars": [{ "<variableName>": "<dataType>" }],
-      "actions": ["action1", "action2"],
-      "helpers": ["helper1"],
-      "services": ["dependency1", "dependency2"]
+      "name": "modifier-name",
+      "description": "What DOM behaviour this modifier applies",
+      "input_args": [{ "<argumentName>": "<dataType>" }],
+      "services": ["service1"]
     }
   ]
 }
 ```
 
-**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": [
+  "modifiers": [
     {
-      "name": "visualization-builder",
-      "tracked_vars": [
-        { "currentVisualization": "object" },
-        { "availableTypes": "array" }
-      ],
-      "actions": [
-        "createVisualization",
-        "updateVisualization",
-        "deleteVisualization"
-      ],
-      "helpers": ["validateConfig", "generatePreview"],
-      "services": ["store", "router"]
+      "name": "tooltip",
+      "description": "Initialises a Bootstrap tooltip on the target element using the provided label",
+      "input_args": [{ "label": "string" }, { "placement": "string" }],
+      "services": []
+    },
+    {
+      "name": "autofocus",
+      "description": "Sets focus on the target element when it is inserted into the DOM",
+      "input_args": [],
+      "services": []
     }
   ]
 }
@@ -282,48 +413,47 @@ The storylang.json file contains seven main sections:
 
 ---
 
-### 6. Helpers
+#### 5. Services
 
-**Purpose**: Defines custom template helpers — pure functions used in templates to format, compute or transform data for display.
+**Purpose**: Defines custom Ember services needed by the application.
 
 **Format**:
 
 ```json
 {
-  "helpers": [
+  "services": [
     {
-      "name": "helper-name",
-      "description": "What this helper does",
-      "args": [{ "<argumentName>": "<dataType>" }],
-      "return": "<dataType>"
+      "name": "service-name",
+      "tracked_vars": [{ "<variableName>": "<dataType>" }],
+      "getters": ["derived-property-name"],
+      "actions": ["frontend-action", { "backend-action": ["custom/path/file.php"] }],
+      "functions": ["internal-method"],
+      "helpers": ["helper1"],
+      "services": ["dependency1", "dependency2"]
     }
   ]
 }
 ```
 
-**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"
-    },
+  "services": [
     {
-      "name": "truncate-text",
-      "description": "Truncates a string to a given character limit and appends an ellipsis",
-      "args": [{ "text": "string" }, { "limit": "int" }],
-      "return": "string"
+      "name": "visualization-builder",
+      "tracked_vars": [
+        { "dataMatrix": "object" },
+        { "availableTypes": "array" }
+      ],
+      "functions": ["build-visualization"],
+      "actions": [
+        "reset-state",
+        { "assemble-data-for-visualization": ["custom/visualizations/assemble-data.php"] },
+        "updateVisualization"
+      ],
+      "helpers": ["validateConfig", "generatePreview"],
+      "services": ["store", "router"]
     }
   ]
 }
@@ -331,48 +461,51 @@ The storylang.json file contains seven main sections:
 
 ---
 
-### 7. Modifiers
+#### 6. Components
 
-**Purpose**: Defines custom Ember modifiers — functions that directly interact with DOM elements to attach behaviour, third-party libraries or event listeners.
+**Purpose**: Defines reusable UI components that will be built for the application.
 
 **Format**:
 
 ```json
 {
-  "modifiers": [
+  "components": [
     {
-      "name": "modifier-name",
-      "description": "What DOM behaviour this modifier applies",
-      "args": [{ "<argumentName>": "<dataType>" }],
-      "services": ["service1"]
+      "name": "component-name",
+      "type": "component-type",
+      "tracked_vars": [{ "<variableName>": "<dataType>" }],
+      "inherited_args": [{ "<argumentName>": "<argType>" }],
+      "getters": ["derived-property-name"],
+      "actions": ["frontend-action", { "backend-action": ["custom/path/file.php"] }],
+      "functions": ["internal-method"],
+      "helpers": ["helper1", "helper2"],
+      "modifiers": ["modifier1"],
+      "services": ["service1", "service2"]
     }
   ]
 }
 ```
 
-**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": []
-    },
+  "components": [
     {
-      "name": "autofocus",
-      "description": "Sets focus on the target element when it is inserted into the DOM",
-      "args": [],
-      "services": []
+      "name": "file-summary-card",
+      "type": "card",
+      "tracked_vars": [{ "isSelected": "bool" }, { "isExpanded": "bool" }],
+      "inherited_args": [
+        { "file": "var" },
+        { "onEdit": "action" },
+        { "onDelete": "action" }
+      ],
+      "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"]
     }
   ]
 }
@@ -380,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
@@ -390,51 +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)
 
 ---
 
-### 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
-
----
+## EmberJS
 
-## Ember-Tribe Development Guide
+### 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
@@ -448,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.
 
@@ -490,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'}}
@@ -528,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`.
 
@@ -545,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
@@ -558,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:**
@@ -584,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
@@ -615,69 +751,9 @@ post.destroyRecord(); // => DELETE request
 
 ---
 
-## Component Architecture
-
-### Component Structure
-
-```javascript
-// Component class
-import Component from '@glimmer/component';
-import { tracked } from '@glimmer/tracking';
-import { action } from '@ember/object';
-import { service } from '@ember/service';
-
-export default class FileCardComponent extends Component {
-  @service store;
-  @tracked isSelected = false;
-
-  @action
-  toggleSelection() {
-    this.isSelected = !this.isSelected;
-  }
-}
-```
-
-### Template Patterns
-
-```handlebars
-<div
-  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>
-```
-
----
-
-## Services Integration
-
-Make services based on storylang.json service definitions:
-
-```javascript
-// app/services/visualization-builder.js
-import Service from '@ember/service';
-import { tracked } from '@glimmer/tracking';
-import { service } from '@ember/service';
-
-export default class VisualizationBuilderService extends Service {
-  @service store;
-  @tracked supportedTypes = ['network', 'tree', 'sankey'];
-
-  buildVisualization(files, type, config) {
-    // Service logic implementation
-  }
-}
-```
-
----
-
-## Route Generation
+### Route Generation
 
-### Route Creation
+#### Route Creation
 
 Make routes based on storylang.json route definitions:
 
@@ -704,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:
 
@@ -721,7 +797,7 @@ export default helper(function formatDate([date, format = 'short']) {
 });
 ```
 
-### Template Usage
+#### Template Usage
 
 ```handlebars
 <span class='text-muted'>
@@ -731,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:
 
@@ -751,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.
 
@@ -806,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.
 
@@ -852,7 +928,7 @@ export default class CounterComponent extends Component {
 }
 ```
 
-### Component Communication & Modifiers
+#### Component Communication & Modifiers
 
 **Design Pattern:**
 
@@ -900,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.
 
@@ -936,9 +1012,69 @@ export default class CartContentsComponent extends Component {
 
 ---
 
-## Code Generation Process
+### Services Integration
+
+Make services based on storylang.json service definitions:
+
+```javascript
+// app/services/visualization-builder.js
+import Service from '@ember/service';
+import { tracked } from '@glimmer/tracking';
+import { service } from '@ember/service';
+
+export default class VisualizationBuilderService extends Service {
+  @service store;
+  @tracked supportedTypes = ['network', 'tree', 'sankey'];
+
+  buildVisualization(files, type, config) {
+    // Service logic implementation
+  }
+}
+```
+
+---
+
+### Component Architecture
+
+#### Component Structure
+
+```javascript
+// Component class
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { action } from '@ember/object';
+import { service } from '@ember/service';
+
+export default class FileCardComponent extends Component {
+  @service store;
+  @tracked isSelected = false;
+
+  @action
+  toggleSelection() {
+    this.isSelected = !this.isSelected;
+  }
+}
+```
+
+#### Template Patterns
+
+```handlebars
+<div
+  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>
+```
+
+---
+
+### Forms and Input Fields
 
-### File Upload Javascript Example
+#### File upload javascript example
 
 ```javascript
 import ENV from '<your-application-name>/config/environment';
@@ -968,9 +1104,156 @@ async uploadFile(file) {
 }
 ```
 
+#### Input and Textarea fields
+
+Use Ember's built-in `<Input>` component instead of a raw `<input>` tag — it automatically updates bound state via `@value`.
+
+```handlebars
+<div class="mb-3">
+  <label for="input-name" class="form-label">Name:</label>
+  <Input
+    id="input-name"
+    class="form-control"
+    @type="text"
+    @value={{this.name}}
+    disabled={{this.isReadOnly}}
+    maxlength="50"
+    placeholder="Enter your name"
+  />
+</div>
+```
+
+```javascript
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+
+export default class ExampleComponent extends Component {
+  @tracked name = '';
+  @tracked isReadOnly = false;
+}
+```
+
+```handlebars
+<div class="form-check mb-3">
+  <Input
+    id="admin-checkbox"
+    class="form-check-input"
+    @type="checkbox"
+    @checked={{this.isAdmin}}
+    {{on "input" this.validateRole}}
+  />
+  <label for="admin-checkbox" class="form-check-label">Is Admin?</label>
+</div>
+```
+
+```handlebars
+<div class="mb-3">
+  <label for="user-comment" class="form-label">Comment:</label>
+  <Textarea
+    id="user-comment"
+    class="form-control"
+    @value={{this.userComment}}
+    rows="6"
+  />
+</div>
+```
+
+**Key rules for `<Input>` and `<Textarea>`:**
+- `@value`, `@type`, and `@checked` must be passed as **arguments** (with `@`).
+- 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` 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.
+
+**Single select (Bootstrap-compatible wrapper):**
+
+```handlebars
+<div class="mb-3">
+  <label class="form-label">Assign Category:</label>
+  <div class="form-control p-0 border-0">
+    <PowerSelect
+      @options={{this.categories}}
+      @selected={{this.selectedCategory}}
+      @onChange={{this.handleCategoryChange}}
+      @placeholder="Select a category"
+      as |category|
+    >
+      {{category.name}}
+    </PowerSelect>
+  </div>
+</div>
+```
+
+```javascript
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { action } from '@ember/object';
+
+export default class ExampleComponent extends Component {
+  @tracked selectedCategory = null;
+
+  categories = [
+    { id: 1, name: 'Design' },
+    { id: 2, name: 'Engineering' },
+    { id: 3, name: 'Marketing' },
+  ];
+
+  @action
+  handleCategoryChange(category) {
+    this.selectedCategory = category;
+  }
+}
+```
+
+**Multi-select variant:**
+
+```handlebars
+<div class="mb-3">
+  <label class="form-label">Assign Tags:</label>
+  <div class="form-control p-0 border-0">
+    <PowerSelectMultiple
+      @options={{this.availableTags}}
+      @selected={{this.selectedTags}}
+      @onChange={{this.handleTagsChange}}
+      @placeholder="Select tags"
+      as |tag|
+    >
+      {{tag.label}}
+    </PowerSelectMultiple>
+  </div>
+</div>
+```
+
+**Async options loaded from the store:**
+
+```handlebars
+<div class="mb-3">
+  <label class="form-label">Select Project:</label>
+  <div class="form-control p-0 border-0">
+    <PowerSelect
+      @options={{this.projects}}
+      @selected={{this.selectedProject}}
+      @onChange={{this.handleProjectChange}}
+      @searchField="name"
+      @placeholder="Search projects..."
+      as |project|
+    >
+      {{project.modules.name}}
+    </PowerSelect>
+  </div>
+</div>
+```
+
+**Key rules for `<PowerSelect>`:**
+- `@options`, `@selected`, and `@onChange` are always required arguments.
+- Use `@searchField` to specify which object property drives the built-in search filter.
+- For multi-select, use `<PowerSelectMultiple>` — the `@onChange` callback receives the full updated array, so assign it directly to your tracked property.
+
 ---
 
-## 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:
 
@@ -985,19 +1268,6 @@ You can then upload the `dist/` folder to [Junction (open source)](http://localh
 
 ---
 
-## Best Practices
-
-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
-
----
-
 # License
 
 This project is licensed under the [GNU GPL v3 License](LICENSE.md).