retold 4.0.1 → 4.0.3

package/examples/todo-list/web-client/package.json

@@ -0,0 +1,43 @@
+{
+	"name": "retold-example-todo-web-client",
+	"version": "1.0.0",
+	"description": "Retold Example: Todo List Web Client (Pict Application)",
+	"main": "source/TodoList-Application.cjs",
+	"scripts":
+	{
+		"postinstall": "node generate-build-config.cjs",
+		"build": "npx quack build && npx quack copy",
+		"start": "echo 'Build with: npm run build   Then start the server in ../server/'"
+	},
+	"dependencies":
+	{
+		"pict": "^1.0.343",
+		"pict-application": "^1.0.28",
+		"pict-router": "^1.0.4",
+		"pict-view": "^1.0.64",
+		"pict-provider": "^1.0.3"
+	},
+	"devDependencies":
+	{
+		"quackage": "^1.0.41"
+	},
+	"copyFilesSettings":
+	{
+		"whenFileExists": "overwrite"
+	},
+	"copyFiles":
+	[
+		{
+			"from": "./html/*",
+			"to": "./dist/"
+		},
+		{
+			"from": "./css/*",
+			"to": "./dist/css/"
+		},
+		{
+			"from": "./node_modules/pict/dist/*",
+			"to": "./dist/js/"
+		}
+	]
+}

package/examples/todo-list/web-client/source/TodoList-Application-Config.json

@@ -0,0 +1,12 @@
+{
+	"Name": "TodoList Pict Application",
+	"Hash": "TodoList",
+	"MainViewportViewIdentifier": "TodoList-Layout",
+	"AutoSolveAfterInitialize": true,
+	"AutoRenderMainViewportViewAfterInitialize": false,
+	"AutoRenderViewsAfterInitialize": false,
+	"pict_configuration":
+	{
+		"Product": "TodoList-Pict"
+	}
+}

package/examples/todo-list/web-client/source/TodoList-Application.cjs

@@ -0,0 +1,383 @@
+const libPictApplication = require('pict-application');
+const libPictRouter = require('pict-router');
+
+const libProviderTaskData = require('./providers/Provider-TaskData.cjs');
+
+const libViewLayout = require('./views/View-Layout.cjs');
+const libViewTaskList = require('./views/View-TaskList.cjs');
+const libViewTaskForm = require('./views/View-TaskForm.cjs');
+const libViewWeekView = require('./views/calendar/View-WeekView.cjs');
+const libViewMonthView = require('./views/calendar/View-MonthView.cjs');
+const libViewYearView = require('./views/calendar/View-YearView.cjs');
+
+class TodoListApplication extends libPictApplication
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		// Register the router provider
+		this.pict.addProvider('PictRouter', require('./providers/Router-Config.json'), libPictRouter);
+
+		// Register the data provider
+		this.pict.addProvider('TodoList-TaskData', libProviderTaskData.default_configuration, libProviderTaskData);
+
+		// Register views
+		this.pict.addView('TodoList-Layout', libViewLayout.default_configuration, libViewLayout);
+		this.pict.addView('TodoList-TaskList', libViewTaskList.default_configuration, libViewTaskList);
+		this.pict.addView('TodoList-TaskForm', libViewTaskForm.default_configuration, libViewTaskForm);
+		this.pict.addView('TodoList-WeekView', libViewWeekView.default_configuration, libViewWeekView);
+		this.pict.addView('TodoList-MonthView', libViewMonthView.default_configuration, libViewMonthView);
+		this.pict.addView('TodoList-YearView', libViewYearView.default_configuration, libViewYearView);
+	}
+
+	onAfterInitializeAsync(fCallback)
+	{
+		// Initialize shared application state
+		this.pict.AppData.TodoList =
+		{
+			Tasks: [],
+			AllTasks: [],
+			TotalCount: 0,
+			FilteredCount: 0,
+			SelectedTask: null,
+			EditMode: false,
+			FormTitle: 'New Task',
+
+			// List state drives server-side sort and pagination
+			ListState:
+			{
+				SortColumn: 'DueDate',
+				SortDirection: 'DESC',
+				SearchText: '',
+				Begin: 0,
+				Cap: 250
+			},
+
+			// Calendar view state for week/month/year views
+			CalendarState:
+			{
+				// The anchor date for the current calendar view (ISO string YYYY-MM-DD)
+				AnchorDate: new Date().toISOString().substring(0, 10),
+				// Computed summary rows populated by the calendar views
+				WeekRows: [],
+				MonthRows: [],
+				YearRows: [],
+				// Labels for the navigation header
+				WeekLabel: '',
+				MonthLabel: '',
+				YearLabel: ''
+			}
+		};
+
+		// Load tasks from the API, then render the layout
+		this.pict.providers['TodoList-TaskData'].loadTasks(
+			(pError) =>
+			{
+				if (pError)
+				{
+					this.log.error('Failed to load tasks: ' + pError.message);
+				}
+
+				// Render the layout (which triggers child view renders)
+				this.pict.views['TodoList-Layout'].render();
+
+				return super.onAfterInitializeAsync(fCallback);
+			});
+	}
+
+	/**
+	 * Navigate to a hash route.
+	 *
+	 * @param {string} pRoute - The route path (e.g., '/TaskList').
+	 */
+	navigateTo(pRoute)
+	{
+		this.pict.providers.PictRouter.navigate(pRoute);
+	}
+
+	/**
+	 * Render a named view into the content area.
+	 *
+	 * @param {string} pViewIdentifier - The view to render.
+	 */
+	showView(pViewIdentifier)
+	{
+		if (pViewIdentifier in this.pict.views)
+		{
+			this.pict.views[pViewIdentifier].render();
+		}
+	}
+
+	/**
+	 * Change the sort order from the toolbar dropdown and reload.
+	 *
+	 * Called from the sort <select> element in the TaskList filter bar.
+	 * The value is a "Column~Direction" string (e.g. "DueDate~DESC").
+	 *
+	 * @param {string} pSortValue - "Column~Direction" from the dropdown.
+	 */
+	changeSortOrder(pSortValue)
+	{
+		let tmpParts = pSortValue.split('~');
+		if (tmpParts.length === 2)
+		{
+			this.pict.AppData.TodoList.ListState.SortColumn = tmpParts[0];
+			this.pict.AppData.TodoList.ListState.SortDirection = tmpParts[1];
+		}
+
+		let tmpProvider = this.pict.providers['TodoList-TaskData'];
+		tmpProvider.loadTasks(
+			() =>
+			{
+				this.pict.views['TodoList-TaskList'].render();
+			});
+	}
+
+	/**
+	 * Search tasks by name or description.
+	 *
+	 * Reads the search input value, stores it in ListState, and reloads.
+	 * Called from the search input in the TaskList toolbar on Enter or
+	 * from the search button click.
+	 */
+	searchTasks()
+	{
+		let tmpInput = document.getElementById('tl-search-input');
+		this.pict.AppData.TodoList.ListState.SearchText = tmpInput ? tmpInput.value : '';
+
+		let tmpProvider = this.pict.providers['TodoList-TaskData'];
+		tmpProvider.loadTasks(
+			() =>
+			{
+				this.pict.views['TodoList-TaskList'].render();
+			});
+	}
+
+	/**
+	 * Clear the search filter and reload the full list.
+	 */
+	clearSearch()
+	{
+		this.pict.AppData.TodoList.ListState.SearchText = '';
+
+		let tmpProvider = this.pict.providers['TodoList-TaskData'];
+		tmpProvider.loadTasks(
+			() =>
+			{
+				this.pict.views['TodoList-TaskList'].render();
+			});
+	}
+
+	/**
+	 * Show the task form in "add" mode.
+	 */
+	addTask()
+	{
+		this.pict.AppData.TodoList.SelectedTask =
+		{
+			IDTask: 0,
+			Name: '',
+			Description: '',
+			DueDate: '',
+			LengthInHours: 0,
+			Status: 'Pending'
+		};
+		this.pict.AppData.TodoList.EditMode = false;
+		this.pict.AppData.TodoList.FormTitle = 'New Task';
+		this.pict.views['TodoList-TaskForm'].render();
+	}
+
+	/**
+	 * Show the task form in "edit" mode for a given task ID.
+	 *
+	 * @param {number|string} pIDTask - The task ID to edit.
+	 */
+	editTask(pIDTask)
+	{
+		let tmpIDTask = parseInt(pIDTask, 10);
+		let tmpTasks = this.pict.AppData.TodoList.Tasks;
+		let tmpTask = null;
+
+		for (let i = 0; i < tmpTasks.length; i++)
+		{
+			if (tmpTasks[i].IDTask === tmpIDTask)
+			{
+				tmpTask = tmpTasks[i];
+				break;
+			}
+		}
+
+		if (!tmpTask)
+		{
+			this.log.warn('Task not found: ' + pIDTask);
+			return;
+		}
+
+		// Clone the task so edits don't modify the list data directly
+		this.pict.AppData.TodoList.SelectedTask = JSON.parse(JSON.stringify(tmpTask));
+		this.pict.AppData.TodoList.EditMode = true;
+		this.pict.AppData.TodoList.FormTitle = 'Edit Task';
+		this.pict.views['TodoList-TaskForm'].render();
+	}
+
+	/**
+	 * Save the task from the form (create or update based on EditMode).
+	 */
+	saveTask()
+	{
+		let tmpTaskData =
+		{
+			Name: document.getElementById('taskName').value,
+			Description: document.getElementById('taskDescription').value,
+			DueDate: document.getElementById('taskDueDate').value,
+			LengthInHours: parseFloat(document.getElementById('taskHours').value) || 0,
+			Status: document.getElementById('taskStatus').value
+		};
+
+		let tmpProvider = this.pict.providers['TodoList-TaskData'];
+		let tmpSelf = this;
+
+		let tmpAfterSave = (pError) =>
+		{
+			if (pError)
+			{
+				tmpSelf.log.error('Save failed: ' + pError.message);
+				return;
+			}
+			// Reload tasks and show the list
+			tmpProvider.loadTasks(
+				() =>
+				{
+					tmpSelf.pict.views['TodoList-TaskList'].render();
+				});
+		};
+
+		if (this.pict.AppData.TodoList.EditMode)
+		{
+			tmpTaskData.IDTask = this.pict.AppData.TodoList.SelectedTask.IDTask;
+			tmpProvider.updateTask(tmpTaskData, tmpAfterSave);
+		}
+		else
+		{
+			tmpProvider.createTask(tmpTaskData, tmpAfterSave);
+		}
+	}
+
+	// ──────────────────────────────────────────────────────────────
+	// Calendar view helpers
+	// ──────────────────────────────────────────────────────────────
+
+	/**
+	 * Show a calendar view.  Loads all tasks if they haven't been
+	 * fetched yet, then renders the requested view.
+	 *
+	 * @param {string} pViewIdentifier - 'TodoList-WeekView', etc.
+	 */
+	showCalendarView(pViewIdentifier)
+	{
+		let tmpProvider = this.pict.providers['TodoList-TaskData'];
+		let tmpSelf = this;
+
+		// Only fetch once per session; subsequent navigations reuse the cache
+		if (this.pict.AppData.TodoList.AllTasks.length > 0)
+		{
+			tmpSelf.pict.views[pViewIdentifier].render();
+			return;
+		}
+
+		tmpProvider.loadAllTasks(
+			(pError) =>
+			{
+				if (pError)
+				{
+					tmpSelf.log.error('Failed to load all tasks: ' + pError.message);
+				}
+				tmpSelf.pict.views[pViewIdentifier].render();
+			});
+	}
+
+	/**
+	 * Navigate the calendar anchor date by a delta and re-render the view.
+	 *
+	 * @param {string} pUnit   - 'week', 'month', or 'year'
+	 * @param {number} pDelta  - Number of units to shift (negative = back, positive = forward)
+	 */
+	calendarNavigate(pUnit, pDelta)
+	{
+		let tmpCal = this.pict.AppData.TodoList.CalendarState;
+		let tmpDate = new Date(tmpCal.AnchorDate + 'T00:00:00');
+
+		if (pUnit === 'week')
+		{
+			tmpDate.setDate(tmpDate.getDate() + (pDelta * 7));
+		}
+		else if (pUnit === 'month')
+		{
+			tmpDate.setMonth(tmpDate.getMonth() + pDelta);
+		}
+		else if (pUnit === 'year')
+		{
+			tmpDate.setFullYear(tmpDate.getFullYear() + pDelta);
+		}
+
+		tmpCal.AnchorDate = tmpDate.toISOString().substring(0, 10);
+
+		let tmpViewMap =
+		{
+			week: 'TodoList-WeekView',
+			month: 'TodoList-MonthView',
+			year: 'TodoList-YearView'
+		};
+
+		this.pict.views[tmpViewMap[pUnit]].render();
+	}
+
+	/**
+	 * Jump the calendar anchor to today and re-render the current calendar view.
+	 *
+	 * @param {string} pUnit - 'week', 'month', or 'year'
+	 */
+	calendarToday(pUnit)
+	{
+		this.pict.AppData.TodoList.CalendarState.AnchorDate = new Date().toISOString().substring(0, 10);
+
+		let tmpViewMap =
+		{
+			week: 'TodoList-WeekView',
+			month: 'TodoList-MonthView',
+			year: 'TodoList-YearView'
+		};
+
+		this.pict.views[tmpViewMap[pUnit]].render();
+	}
+
+	/**
+	 * Delete a task and refresh the list.
+	 *
+	 * @param {number|string} pIDTask - The task ID to delete.
+	 */
+	deleteTask(pIDTask)
+	{
+		let tmpProvider = this.pict.providers['TodoList-TaskData'];
+		let tmpSelf = this;
+
+		tmpProvider.deleteTask(pIDTask,
+			(pError) =>
+			{
+				if (pError)
+				{
+					tmpSelf.log.error('Delete failed: ' + pError.message);
+					return;
+				}
+				tmpProvider.loadTasks(
+					() =>
+					{
+						tmpSelf.pict.views['TodoList-TaskList'].render();
+					});
+			});
+	}
+}
+
+module.exports = TodoListApplication;
+module.exports.default_configuration = require('./TodoList-Application-Config.json');

package/examples/todo-list/web-client/source/providers/Provider-TaskData.cjs

@@ -0,0 +1,243 @@
+const libPictProvider = require('pict-provider');
+
+const _ProviderConfiguration =
+{
+	ProviderIdentifier: 'TodoList-TaskData',
+	AutoInitialize: true,
+	AutoInitializeOrdinal: 0
+};
+
+class TaskDataProvider extends libPictProvider
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+	}
+
+	/**
+	 * Build the Meadow Reads URL from the current ListState.
+	 *
+	 * Uses the FSF (Filter Sort Field) instruction in the FilteredTo path
+	 * segment so the sort happens server-side in SQL.
+	 *
+	 * @returns {string} The API URL for the Reads endpoint.
+	 */
+	buildReadsURL()
+	{
+		let tmpListState = this.pict.AppData.TodoList.ListState;
+
+		let tmpSortColumn = tmpListState.SortColumn || 'IDTask';
+		let tmpSortDirection = tmpListState.SortDirection || 'DESC';
+		let tmpBegin = tmpListState.Begin || 0;
+		let tmpCap = tmpListState.Cap || 250;
+
+		// Build the filter stanzas -- search first, then sort
+		let tmpFilterParts = [];
+
+		// If a search term is present, add LIKE filters on Name and Description (OR-connected)
+		let tmpSearchText = (tmpListState.SearchText || '').trim();
+		if (tmpSearchText.length > 0)
+		{
+			// Encode % for the LIKE wildcards around the search term
+			let tmpEncodedTerm = encodeURIComponent(tmpSearchText);
+			tmpFilterParts.push('FBVOR~Name~LK~%25' + tmpEncodedTerm + '%25');
+			tmpFilterParts.push('FBVOR~Description~LK~%25' + tmpEncodedTerm + '%25');
+		}
+
+		// Always add the sort stanza last
+		tmpFilterParts.push('FSF~' + tmpSortColumn + '~' + tmpSortDirection + '~0');
+
+		let tmpFilter = tmpFilterParts.join('~');
+
+		return '/1.0/Tasks/FilteredTo/' + tmpFilter + '/' + tmpBegin + '/' + tmpCap;
+	}
+
+	/**
+	 * Build the filter-only portion (no sort, no pagination) for the Count endpoint.
+	 *
+	 * @returns {string|null} The filter stanza string, or null if no search is active.
+	 */
+	buildSearchFilter()
+	{
+		let tmpListState = this.pict.AppData.TodoList.ListState;
+		let tmpSearchText = (tmpListState.SearchText || '').trim();
+
+		if (tmpSearchText.length === 0)
+		{
+			return null;
+		}
+
+		let tmpEncodedTerm = encodeURIComponent(tmpSearchText);
+		let tmpFilterParts = [];
+		tmpFilterParts.push('FBVOR~Name~LK~%25' + tmpEncodedTerm + '%25');
+		tmpFilterParts.push('FBVOR~Description~LK~%25' + tmpEncodedTerm + '%25');
+
+		return tmpFilterParts.join('~');
+	}
+
+	/**
+	 * Load tasks from the API using current sort and pagination state.
+	 *
+	 * Also fetches the total record count (unfiltered) and, when a search
+	 * is active, the filtered count so the toolbar can display
+	 * "showing X of Y records".
+	 *
+	 * @param {Function} fCallback - Callback(pError, pTasks)
+	 */
+	loadTasks(fCallback)
+	{
+		let tmpURL = this.buildReadsURL();
+		let tmpSearchFilter = this.buildSearchFilter();
+
+		// Always fetch the overall total count
+		let tmpCountURL = '/1.0/Tasks/Count';
+
+		// When a search filter is active, also fetch the filtered count
+		let tmpFilteredCountURL = tmpSearchFilter
+			? '/1.0/Tasks/Count/FilteredTo/' + tmpSearchFilter
+			: null;
+
+		let tmpFetches = [fetch(tmpURL), fetch(tmpCountURL)];
+		if (tmpFilteredCountURL)
+		{
+			tmpFetches.push(fetch(tmpFilteredCountURL));
+		}
+
+		Promise.all(tmpFetches)
+			.then(
+				(pResponses) =>
+				{
+					return Promise.all(pResponses.map((pR) => { return pR.json(); }));
+				})
+			.then(
+				(pResults) =>
+				{
+					let tmpTasks = pResults[0];
+					let tmpTotalCount = pResults[1];
+					let tmpFilteredCount = pResults[2];
+
+					if (Array.isArray(tmpTasks))
+					{
+						this.pict.AppData.TodoList.Tasks = tmpTasks;
+					}
+
+					// Store the total record count
+					if (tmpTotalCount && typeof tmpTotalCount.Count === 'number')
+					{
+						this.pict.AppData.TodoList.TotalCount = tmpTotalCount.Count;
+					}
+
+					// Store the filtered count (or fall back to total when not searching)
+					if (tmpFilteredCount && typeof tmpFilteredCount.Count === 'number')
+					{
+						this.pict.AppData.TodoList.FilteredCount = tmpFilteredCount.Count;
+					}
+					else
+					{
+						this.pict.AppData.TodoList.FilteredCount = this.pict.AppData.TodoList.TotalCount;
+					}
+
+					return fCallback(null, tmpTasks);
+				})
+			.catch(
+				(pError) =>
+				{
+					this.log.error('Error loading tasks: ' + pError.message);
+					return fCallback(pError);
+				});
+	}
+
+	/**
+	 * Load ALL tasks sorted by DueDate ascending.
+	 *
+	 * Used by the calendar views (week, month, year) which need the full
+	 * data set to compute per-period summaries.  Stores the result in
+	 * AppData.TodoList.AllTasks.
+	 *
+	 * @param {Function} fCallback - Callback(pError, pTasks)
+	 */
+	loadAllTasks(fCallback)
+	{
+		let tmpURL = '/1.0/Tasks/FilteredTo/FSF~DueDate~ASC~0/0/10000';
+
+		fetch(tmpURL)
+			.then(
+				(pResponse) =>
+				{
+					return pResponse.json();
+				})
+			.then(
+				(pTasks) =>
+				{
+					if (Array.isArray(pTasks))
+					{
+						this.pict.AppData.TodoList.AllTasks = pTasks;
+					}
+					return fCallback(null, pTasks);
+				})
+			.catch(
+				(pError) =>
+				{
+					this.log.error('Error loading all tasks: ' + pError.message);
+					return fCallback(pError);
+				});
+	}
+
+	/**
+	 * Create a new task.
+	 *
+	 * @param {Object} pTaskData - The task record to create.
+	 * @param {Function} fCallback - Callback(pError, pRecord)
+	 */
+	createTask(pTaskData, fCallback)
+	{
+		fetch('/1.0/Task',
+			{
+				method: 'POST',
+				headers: { 'Content-Type': 'application/json' },
+				body: JSON.stringify(pTaskData)
+			})
+			.then((pResponse) => { return pResponse.json(); })
+			.then((pRecord) => { return fCallback(null, pRecord); })
+			.catch((pError) => { return fCallback(pError); });
+	}
+
+	/**
+	 * Update an existing task.
+	 *
+	 * @param {Object} pTaskData - The task record to update (must include IDTask).
+	 * @param {Function} fCallback - Callback(pError, pRecord)
+	 */
+	updateTask(pTaskData, fCallback)
+	{
+		fetch('/1.0/Task',
+			{
+				method: 'PUT',
+				headers: { 'Content-Type': 'application/json' },
+				body: JSON.stringify(pTaskData)
+			})
+			.then((pResponse) => { return pResponse.json(); })
+			.then((pRecord) => { return fCallback(null, pRecord); })
+			.catch((pError) => { return fCallback(pError); });
+	}
+
+	/**
+	 * Delete a task by ID.
+	 *
+	 * @param {number} pIDTask - The ID of the task to delete.
+	 * @param {Function} fCallback - Callback(pError, pResult)
+	 */
+	deleteTask(pIDTask, fCallback)
+	{
+		fetch('/1.0/Task/' + pIDTask,
+			{
+				method: 'DELETE'
+			})
+			.then((pResponse) => { return pResponse.json(); })
+			.then((pResult) => { return fCallback(null, pResult); })
+			.catch((pError) => { return fCallback(pError); });
+	}
+}
+
+module.exports = TaskDataProvider;
+module.exports.default_configuration = _ProviderConfiguration;

package/examples/todo-list/web-client/source/providers/Router-Config.json

@@ -0,0 +1,32 @@
+{
+	"ProviderIdentifier": "Pict-Router",
+	"AutoInitialize": true,
+	"AutoInitializeOrdinal": 0,
+	"Routes":
+	[
+		{
+			"path": "/TaskList",
+			"template": "{~LV:Pict.PictApplication.showView(`TodoList-TaskList`)~}"
+		},
+		{
+			"path": "/TaskForm",
+			"template": "{~LV:Pict.PictApplication.addTask()~}"
+		},
+		{
+			"path": "/TaskForm/:id",
+			"template": "{~LV:Pict.PictApplication.editTask(`{~D:RouteData.id~}`)~}"
+		},
+		{
+			"path": "/WeekView",
+			"template": "{~LV:Pict.PictApplication.showCalendarView(`TodoList-WeekView`)~}"
+		},
+		{
+			"path": "/MonthView",
+			"template": "{~LV:Pict.PictApplication.showCalendarView(`TodoList-MonthView`)~}"
+		},
+		{
+			"path": "/YearView",
+			"template": "{~LV:Pict.PictApplication.showCalendarView(`TodoList-YearView`)~}"
+		}
+	]
+}