mftsccs-browser 2.2.20-beta → 2.2.22-beta

package/dist/types/Services/Local/MakeTheInstanceConceptLocal.d.ts

@@ -1,18 +1,164 @@
 import { InnerActions } from "../../Constants/general.const";
 /**
- * This is the basic function of the concept connection system. This function let's you create a concept within the constraints of the
- * concept connection system. This function is the building block of the concept connection system.
- * This function automatically passes the concept to be synced to the background. Next time you sync the data this concept will also be created in the backend.
- * @param type this is the type of the concept. You can also think of this as the key of concept. first_name, last_name etc.
- * @param referent the actual value of the concept. The actual name of value of the concept.
- * @param composition this is a boolean that defines if the concept is a composition or not. If this is a composition then other things are also
- * connected internally with this concept. If composition is true then always a new concept is created otherwise it checks if the concept already exists
- * and creates only in the case that the concept does not already exists with its type and value as its unique identifier.
- * @param userId the userId of the creator.
- * @param accessId this is the accessId of the creator. By default should be 4.
- * @param sessionInformationId this is the session that is created by the system.
- * @param referentId In case we need this concept to refer to any other concept.
- * @param actions InnerActions Array for capturing concepts and connection
- * @returns a concept which is either newly created or an older concept that already exists.
+ * Creates or retrieves an instance concept locally - the core building block of the concept-connection system.
+ *
+ * This is THE fundamental function for creating concepts in local storage. It implements an intelligent
+ * get-or-create pattern that checks for existing concepts before creating new ones, preventing duplicates
+ * while supporting both unique instances and composition concepts.
+ *
+ * **Core Behaviors:**
+ * 1. **Composition Mode (composition=true)**: Always creates a new concept
+ *    - Used for containers/objects that need unique instances
+ *    - Marks concept with isComposition flag
+ *    - Example: Each "Project" is unique, even with same name
+ *
+ * 2. **Instance Mode (composition=false)**: Get-or-create pattern
+ *    - Checks if concept with same type and value exists
+ *    - Returns existing if found (deduplication)
+ *    - Creates new only if not found
+ *    - Example: "Published" status concept reused across items
+ *
+ * 3. **Long Text Handling**: Values >255 characters always create new
+ *    - Prevents expensive lookups on large text
+ *    - Each long text gets unique concept
+ *
+ * **Type String Processing:**
+ * - **Best Practice**: Always pass type with "the_" prefix (e.g., "the_name", "the_email")
+ * - Auto-correction: If missing, "the_" is automatically added internally
+ *   - "name" → "the_name" (auto-corrected)
+ *   - "email" → "the_email" (auto-corrected)
+ *   - "the_status" → "the_status" (already correct)
+ * - Creates type concept if it doesn't exist
+ * - **Recommendation**: Use explicit "the_" prefix for code clarity and consistency
+ *
+ * **Sync and Storage:**
+ * - Adds concept to LocalSyncData queue for backend sync
+ * - Stores in LocalConceptsData (IndexedDB)
+ * - Tracks in actions parameter for batch operations
+ * - Assigns negative ID (virtual/local)
+ *
+ * **Process Flow:**
+ * 1. Normalizes type string (adds "the_" prefix)
+ * 2. Creates/retrieves type concept via MakeTheTypeConceptLocal
+ * 3. If composition=true: Creates new concept immediately
+ * 4. If referent length >255: Creates new concept
+ * 5. If regular instance: Checks for existing by type+value
+ * 6. Returns existing or creates new
+ * 7. Attaches type information
+ * 8. Adds to sync queue
+ *
+ * @param type - The type/key of the concept. **Should follow the format "the_xyz"**.
+ *              Represents what kind of data this is.
+ *              Examples: "the_name", "the_email", "the_status", "the_first_name"
+ *
+ *              **Note**: If you pass without "the_" prefix (e.g., "name"), the code will
+ *              automatically add it internally (becomes "the_name"). However, best practice
+ *              is to always include the "the_" prefix for clarity and consistency.
+ *
+ * @param referent - The actual value/content of the concept.
+ *                  The human-readable data (e.g., "Alice", "alice@example.com", "Active").
+ *                  Can be empty string for composition concepts.
+ *
+ * @param composition - Boolean flag determining creation behavior.
+ *                     - true: Always creates new concept (unique instances)
+ *                     - false: Get-or-create pattern (reuses existing)
+ *                     Defaults to false.
+ *
+ * @param userId - The ID of the user creating this concept. Used for ownership and permissions.
+ *
+ * @param accessId - Access control level. Typically 4 (default internal access).
+ *                  Controls who can view/modify this concept.
+ *
+ * @param sessionInformationId - Session identifier for tracking. Defaults to 999 (system).
+ *                              Used for audit logging and session management.
+ *
+ * @param referentId - Optional reference to another concept ID.
+ *                    Used when this concept is an instance of or refers to another concept.
+ *                    Defaults to 0 (no reference).
+ *
+ * @param actions - Action tracking object that accumulates all created concepts and connections.
+ *                 Used for batch operations, rollback, and sync management.
+ *                 Structure: { concepts: Concept[], connections: Connection[] }
+ *
+ * @returns Promise resolving to the created or retrieved Concept object with:
+ *         - Negative ID if newly created locally
+ *         - Attached type information (concept.type)
+ *         - All standard concept properties
+ *
+ * @example
+ * // Create a reusable status concept (get-or-create)
+ * const status = await MakeTheInstanceConceptLocal(
+ *   "the_status",       // type (with "the_" prefix - best practice)
+ *   "Active",           // value
+ *   false,              // not composition - will reuse if exists
+ *   101,                // userId
+ *   4,                  // accessId
+ *   999,                // sessionId
+ *   0                   // no referent
+ * );
+ * // First call creates, subsequent calls return same concept
+ *
+ * @example
+ * // Create a composition concept (always new)
+ * const project = await MakeTheInstanceConceptLocal(
+ *   "the_project",      // type (with "the_" prefix)
+ *   "Project Alpha",    // value
+ *   true,               // composition - always creates new
+ *   101,
+ *   4,
+ *   999,
+ *   0
+ * );
+ * // Each project is unique, even with same name
+ * console.log(project.isComposition); // true
+ *
+ * @example
+ * // Type prefix is added automatically if missing (but prefer explicit)
+ * const email = await MakeTheInstanceConceptLocal(
+ *   "email",            // Missing "the_" - will become "the_email" internally
+ *   "alice@example.com",
+ *   false,
+ *   101, 4
+ * );
+ * console.log(email.typeCharacter); // "the_email" (auto-prefixed)
+ *
+ * // RECOMMENDED: Always include "the_" prefix explicitly
+ * const emailBetter = await MakeTheInstanceConceptLocal(
+ *   "the_email",        // Explicit prefix - clearer and more consistent
+ *   "bob@example.com",
+ *   false,
+ *   101, 4
+ * );
+ *
+ * @example
+ * // Long text always creates new concept
+ * const longDescription = "Lorem ipsum...".repeat(100); // >255 chars
+ * const concept = await MakeTheInstanceConceptLocal(
+ *   "the_description",  // type with "the_" prefix
+ *   longDescription,
+ *   false,              // Even with false, creates new due to length
+ *   101, 4
+ * );
+ *
+ * @example
+ * // Track actions for batch operations
+ * const actions = { concepts: [], connections: [] };
+ * await MakeTheInstanceConceptLocal("the_name", "Alice", false, 101, 4, 999, 0, actions);
+ * await MakeTheInstanceConceptLocal("the_email", "alice@ex.com", false, 101, 4, 999, 0, actions);
+ * console.log(actions.concepts.length); // 2 (plus any type concepts created)
+ *
+ * @example
+ * // Deduplication in action
+ * const status1 = await MakeTheInstanceConceptLocal("the_status", "Published", false, 101, 4);
+ * const status2 = await MakeTheInstanceConceptLocal("the_status", "Published", false, 101, 4);
+ * console.log(status1.id === status2.id); // true - same concept reused
+ *
+ * @throws Logs errors and re-throws for handling by caller.
+ *        Common issues: Type concept creation failures, IndexedDB errors.
+ *
+ * @see {@link CreateTheConceptLocal} for the underlying creation function
+ * @see {@link MakeTheTypeConceptLocal} for type concept creation/retrieval
+ * @see {@link LocalConceptsData.GetConceptByCharacterAndTypeLocal} for existence check
+ * @see {@link LocalSyncData.AddConcept} for sync queue management
  */
 export declare function MakeTheInstanceConceptLocal(type: string, referent: string, composition: boolean | undefined, userId: number, accessId: number, sessionInformationId?: number, referentId?: number, actions?: InnerActions): Promise<any>;

package/dist/types/Services/Local/MakeTheTypeLocal.d.ts

@@ -1,16 +1,36 @@
 import { Concept } from "../../DataStructures/Concept";
 import { InnerActions } from "../../Constants/general.const";
 /**
- * There are two types of concepts. One type of concept is a type concept. These concepts have no actual value and do not mean
- * anything unless they are associated with other values. These are placeholders like first_name, last_name, age etc that are required in the system.
- * These types need to be created seperately.
+ * Creates or retrieves a type concept locally - handles hierarchical type system.
  *
+ * Type concepts are placeholders/templates (e.g., "the_first_name", "the_email") that define
+ * what kind of data a concept represents. They have no actual value themselves.
  *
- * @param typeString type of the concept that needs to be created.
- * @param sessionId SessionId of the user
- * @param sessionUserId Not required pass 999
- * @param userId UserId of the user creating this concept
- * @param actions InnerActions|undefined actions to collect
- * @returns
+ * **Hierarchical Processing (Complex Logic)**:
+ * - Single word (e.g., "status"): Creates simple type concept with typeId=51
+ * - Compound words (e.g., "the_person_email"): Splits into parts and creates hierarchy:
+ *   1. Creates category concept from first part ("the_person")
+ *   2. Creates type concept from second part ("email")
+ *   3. Creates final concept with category and type linked
+ *   **Uses recursion** to build multi-level type hierarchies
+ *
+ * Always checks for existing type concept before creating to prevent duplicates.
+ *
+ * @param typeString - The type name to create (e.g., "the_status", "the_person_email")
+ * @param sessionId - Session identifier (typically 999)
+ * @param sessionUserId - Session user ID (typically 999, not used)
+ * @param userId - User creating the type concept
+ * @param actions - Action tracking for batch operations
+ * @returns Type Concept (existing or newly created)
+ *
+ * @example
+ * // Simple type
+ * const statusType = await MakeTheTypeConceptLocal("the_status", 999, 999, 101);
+ * // Creates: "the_status" type concept
+ *
+ * @example
+ * // Hierarchical type (recursive processing)
+ * const emailType = await MakeTheTypeConceptLocal("the_person_email", 999, 999, 101);
+ * // Creates: "the_person" (category) + "email" (type) + "the_person_email" (combined)
  */
 export declare function MakeTheTypeConceptLocal(typeString: string, sessionId: number, sessionUserId: number, userId: number, actions?: InnerActions): Promise<Concept>;

package/dist/types/Services/Local/UpdateCompositionLocal.d.ts

@@ -1,3 +1,42 @@
 import { PatcherStructure } from "../../DataStructures/PatcherStructure";
 import { InnerActions } from "../../app";
+/**
+ * Updates/patches a composition in local storage with new or modified properties.
+ *
+ * **Complex Patching Logic** (197 lines):
+ * 1. Fetches latest composition data from backend (all connections and concepts)
+ * 2. Iterates through patchObject properties to add/update
+ * 3. For each property:
+ *    - If value is object/array: Creates composition concept and nested composition
+ *    - If value is primitive: Creates instance concept with value
+ *    - Checks if concept type already exists in composition
+ *    - If exists: Marks old connections for deletion (replaces old value)
+ *    - If new: Simply adds new connection
+ * 4. Creates connections between parent composition and new/updated concepts
+ * 5. Deletes old connections (cleanup)
+ * 6. Syncs changes to backend
+ *
+ * **Use Case**: Updating fields in an existing composition without recreating it entirely.
+ *
+ * @param patcherStructure - Object containing:
+ *   - compositionId: The composition to update
+ *   - ofTheCompositionId: Optional parent composition for nested updates
+ *   - patchObject: Object with key-value pairs to add/update
+ *   - userId, sessionId, accessId: User context
+ * @param actions - Action tracking for batch operations and rollback
+ *
+ * @example
+ * // Update a person's email and phone
+ * await UpdateCompositionLocal({
+ *   compositionId: personId,
+ *   patchObject: {
+ *     the_email: "newemail@example.com",
+ *     the_phone: "555-1234"
+ *   },
+ *   userId: 101,
+ *   sessionId: 999,
+ *   accessId: 4
+ * });
+ * // Old email connection deleted, new email connection created
+ */
 export declare function UpdateCompositionLocal(patcherStructure: PatcherStructure, actions?: InnerActions): Promise<any>;

package/dist/types/Services/MakeTheName.d.ts

@@ -0,0 +1,2 @@
+import { Concept } from "../DataStructures/Concept";
+export declare function MakeTheName(theCharacterData: string, userId: number, securityId: number, securityUserId: number, accessId: number, accessUserId: number, sessionInformationId: number, sessionInformationUserId: number, typeId: number, typeUserId: number, existingConcept: Concept): Promise<Concept>;

package/dist/types/Services/auth/AuthService.d.ts

@@ -0,0 +1 @@
+export declare const getServerJwtToken: () => string;

package/dist/types/Widgets/BaseObserver.d.ts

@@ -1,22 +1,25 @@
+/**
+ * Observable base class implementing the Observer pattern for reactive widgets.
+ *
+ * Provides data change notification system allowing subscribers to react to state updates.
+ */
 export declare class BaseObserver {
-    /**
-     * This is where the data of the widget needs to be stored.
-     */
+    /** Widget data that can be observed for changes */
     data: any;
+    /** Flag to enable development mode features */
     inDevelopment: boolean;
-    /**
-     * This is the subscribers of the data. If any thing on this widget changes then all the functions
-     * in the subscribers are called.
-     */
+    /** Array of callback functions subscribed to data changes */
     subscribers: any;
     /**
-    * This is called by any data change. So that any data change will notify all the callback functions to execute.
+    * Notifies all subscribers when data changes.
+    *
+    * @param passedData - Optional data to pass to subscribers. Uses this.data if not provided.
     */
     notify(passedData?: any): void;
     /**
-     * This function is used to register the callback into the function in case of any dataChange.
-     * @param callback sets this callback to the subscribers list in the widget. So that in any change we can call this callback
-     * @returns execution of the callback passed.
+     * Registers a callback function to be invoked on data changes.
+     *
+     * @param callback - Function to execute when data changes
      */
     dataChange(callback: any): void;
 }

package/dist/types/Widgets/BaseWidget.d.ts

@@ -1,24 +1,37 @@
 import { BaseObserver } from "./BaseObserver";
+/**
+ * Base widget class providing core DOM element management and identification.
+ *
+ * Extends BaseObserver to provide reactive data capabilities along with fundamental
+ * widget element operations and unique identification.
+ */
 export declare class BaseWidget extends BaseObserver {
-    /**
-     * This is the element that is a copy of the element that is mounted.
-     */
+    /** The mounted DOM element wrapper for this widget */
     element: HTMLElement | null;
-    /**
-     * This is a random identifier to the widget that is used to identify the widget and other elements
-     * inside of it.
-     */
+    /** Unique numeric identifier for this widget instance */
     elementIdentifier: number;
+    /** Flag indicating whether the widget has been mounted to the DOM */
+    widgetMounted: boolean;
     /**
-     * This flag is set to denote that that widget has been mounted
+     * Gets the root component element of this widget.
+     *
+     * @returns The widget's root HTML element or null if not mounted
      */
-    widgetMounted: boolean;
     getComponent(): HTMLElement | null;
+    /**
+     * Finds an element by ID within this widget's scope.
+     *
+     * @param identifier - The element ID to search for (without '#' prefix)
+     * @returns The found HTML element or null if not found
+     */
     getElementById(identifier: string): HTMLElement | null;
     /**
+     * Generates a unique identifier for this widget's wrapper element.
+     *
+     * Creates a random number to uniquely identify the widget and its children
+     * from other widgets in the DOM.
      *
-     * @returns random number that will be used to put into the main widget div so that we can uniqely identify
-     * the widget and its children from others.
+     * @returns The generated identifier as a string
      */
     createWidgetWrapperIdentifier(): string;
 }

package/dist/types/Widgets/BuilderSpeceficFunctions.d.ts

@@ -1,2 +1,11 @@
 import { BuilderStatefulWidget } from "./BuilderStatefulWidget";
+/**
+ * Opens the type editor interface for a widget in development mode.
+ *
+ * Creates an input field allowing developers to change the widget type
+ * dynamically. Updates the widget when type value changes.
+ *
+ * @param event - The click event that triggered the editor
+ * @param that - The BuilderStatefulWidget instance to edit
+ */
 export declare function TypeEditor(event: any, that: BuilderStatefulWidget): void;