Scott.Idem/OSIT-AE-App-Svelte
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Double checking things and letting Gemini make some notes.

Browse Source
This commit is contained in:
Scott Idem
2025-12-08 17:29:59 -05:00
parent 098fc94a5a
commit 9d5c079935
4 changed files with 66 additions and 103 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
GEMINI.md
View File

@@ -60,6 +60,26 @@ This project uses Svelte v5 with runes enabled. This introduces significant diff
## Refactoring Notes
### UI Library Compatibility Re-evaluation (2025-12-08)
**Context:** The project has been rolled back to a "mostly working" commit (`90ee6bb1`) after numerous failed attempts to update and integrate UI libraries (`@skeletonlabs/skeleton` and `flowbite-svelte`) with the current Svelte 5 and Tailwind CSS v4 environment.
**Key Issues Identified:**
1. **SkeletonLabs (`@skeletonlabs/skeleton`):** Attempts to upgrade to Skeleton v4.7.4 (which declares compatibility with Svelte 5 and Tailwind 4) consistently failed with a blocking build error: `[@tailwindcss/vite:generate:build] Cannot use @variant with unknown variant: md`. This error originates from Skeleton's pre-compiled CSS and indicates a fundamental incompatibility with the project's Tailwind/Vite build process.
2. **Flowbite-Svelte (`flowbite-svelte`):** Previous versions had peer dependency conflicts with Svelte 5. The currently installed version (`1.28.1`) allows `npm install` to complete, but its runtime compatibility in a Svelte 5 environment with Tailwind 4 is untested.
3. **Missing Components:** Previous attempts to abandon these libraries led to `ReferenceError`s (e.g., for `<Modal>`), confirming their use throughout the codebase.
**New Strategic Direction (Approved by User):**
1. **Hold off on upgrading `flowbite-svelte`:** Keep the current `1.28.1` version for now, as it doesn't block installation. Its functionality will be tested after SkeletonLabs is removed.
2. **Abandon `skeletonlabs/skeleton`:** Due to the persistent, unresolvable build error, we have decided to abandon SkeletonLabs and migrate away from it entirely.
3. **Systematically Replace UI Components:** Prioritize creating custom, drop-in replacements for essential UI components previously provided by SkeletonLabs (and potentially Flowbite-Svelte in the future). This will be done using pure Tailwind CSS and native Svelte components.
* The highest priority is the `<Modal>` component.
**Current State:**
* The `ae_app_3x_llm` branch has been reset to commit `90ee6bb1` to provide a stable, buildable base.
* The `feature/re_evaluate_ui_libs` branch contains the research and failed attempts to integrate Skeleton v4, and is saved for reference.
* The immediate next step is to verify that the `ae_app_3x_llm` branch builds and runs correctly before proceeding with the SkeletonLabs removal and component replacement plan.
### Data Fetching & Processing Pattern (2025-11-20)
A standard pattern for fetching, processing, and caching data has been established to ensure consistency and separation of concerns.
@@ -72,104 +92,4 @@ A standard pattern for fetching, processing, and caching data has been establish
- **Example (`event_badge`):** The `search__event_badge` API endpoint does not include the `event_id` in its results. The `process_ae_obj__event_badge_props` function now accepts the `event_id` as a parameter and injects it into each badge object before it's saved. This centralizes the fix and keeps the API-calling function clean.
4. **Database Caching (`db_save_ae_obj_li__ae_obj`):** After processing, the clean and consistent data is passed to the generic `db_save` function to be cached in IndexedDB.
This pattern isolates API logic from data shaping logic, making the code more modular, predictable, and easier to debug.
### `process_ae_obj__*_props()` Refactoring (2025-11-13)
The `process_ae_obj__*_props()` family of functions, which are responsible for transforming API data for frontend use, have been refactored to standardize their structure and improve maintainability.
The refactoring strategy involved creating a local, non-exported `_process_generic_props` helper function within each module (`ae_journals`, `ae_events`, `ae_archives`, `ae_posts`, `ae_core`). This approach was chosen to avoid altering the module import graph, which had previously caused a critical `InternalError: module record has unexpected status: New` in the SvelteKit development server when a shared utility file was introduced.
**Key aspects of the refactoring:**
- **In-file Generic Helper (`_process_generic_props`):** This function handles common data transformations:
- **`*_random` ID Aliasing:** It automatically iterates over object keys and creates a non-suffixed alias for any key ending in `_random` (e.g., `person_id_random` becomes `person_id`). This is crucial for client-side logic that expects standard ID fields.
- **`tmp_sort` Field Generation:** It creates a set of basic `tmp_sort` fields for client-side sorting.
- **`specific_processor` Callback:** Module-specific logic is handled by a `specific_processor` callback function passed to the `_process_generic_props` helper. This allows for:
- **Unique `tmp_sort` Logic:** Modules can override the default `tmp_sort` fields with their own specific sorting requirements.
- **Content Processing:** Asynchronous operations like Markdown parsing (using `marked.parse`) are handled within the `specific_processor` for the relevant modules (e.g., `ae_journals__journal_entry.ts`).
- **Other Special Cases:** Any other module-specific data transformations are handled in this callback.
- **`core__crud_generic.ts` Cleanup:** The generic CRUD functions in `src/lib/ae_core/core__crud_generic.ts` were simplified:
- The `process_ae_obj__props` function in this file was deprecated.
- All calls to `process_ae_obj__props` and `db_save_ae_obj_li__ae_obj` were removed from the generic CRUD functions (`load_ae_obj_id`, `load_ae_obj_li`, etc.).
- These functions are now responsible only for API interaction, delegating all data processing and caching to the module-specific functions that call them. This enforces a cleaner separation of concerns.
### Tiptap to CodeMirror Migration (2025-11-17)
The rich text editor component, previously based on Tiptap (`shad-editor`), has been replaced with a CodeMirror-based solution. This change was driven by the complexity of Tiptap and its compatibility issues with Tailwind CSS, aiming for a simpler, markdown-focused editing experience.
**Key aspects of the migration:**
- **Removal of Tiptap:** All `@tiptap/*` and `svelte-tiptap` dependencies were removed from `package.json`, and the `src/lib/components/shad-editor/` directory was deleted.
- **CodeMirror Integration:** A new CodeMirror component (`src/lib/elements/element_codemirror_editor.svelte`) was created, providing basic markdown formatting capabilities.
- **Wrapper Component Update:** The existing editor wrapper (`src/lib/elements/element_tiptap_editor.svelte`) was renamed to `src/lib/elements/element_codemirror_wrapper.svelte` and refactored to utilize the new CodeMirror component. Tiptap-specific logic and props were removed.
- **Component Usage Updates:** All Svelte components that previously imported and used the Tiptap wrapper were updated to import `element_codemirror_wrapper.svelte`. Unsupported props such as `default_minimal`, `show_button_kv`, `bind:new_html`, and `bind:changed` were removed from their usage.
- **Dependency Cleanup:** `npm install` was run to remove unneeded packages, and `npm run format` was executed to ensure consistent code style.
### CodeMirror Bug Fixes (2025-11-18)
Following the initial migration to CodeMirror, several issues were identified and resolved:
- **Initialization Errors:** An "Unrecognized extension value" error was fixed by refactoring `codemirror_modules.ts` to explicitly import individual CodeMirror extensions instead of relying on the `basicSetup` bundle. This ensures proper singleton usage and prevents module duplication.
- **Text Wrapping:** The `EditorView.lineWrapping` extension was added to `element_codemirror_editor.svelte` and `e_app_codemirror_v5.svelte` to enable text wrapping.
- **Content Saving:** Content binding issues were resolved in various IDAA components by correctly binding the `html_text` prop of the CodeMirror wrapper to the corresponding state variables.
- **Save Button Enablement:** The logic for enabling the "Save" button was fixed in `ae_idaa_comp__post_obj_id_edit.svelte` to correctly detect changes in the CodeMirror editor.
- **Editor Buttons:** A `TypeError` in the editor's formatting buttons was fixed by using `EditorSelection.range()` to correctly create selection ranges.
- **Component Renaming:** The `Tiptap_editor` component alias was renamed to `CodeMirror_wrapper` across the project for clarity, and the wrapper file was renamed to `element_codemirror_editor_wrapper.svelte`.
### Badge Search Refactoring (2025-11-18)
The new Badge Search functionality was refactored to resolve several issues related to Svelte 5 reactivity and IndexedDB schema design.
- **Svelte 5 Reactivity Fixes:**
- A `store_invalid_shape` error was fixed by removing the `$` prefix from Svelte 5 state variables in templates.
- A Svelte 5 compilation error (`illegal variable name`) was resolved by using `$derived` to create a local reactive variable from a store.
- A 500 Internal Error was resolved by moving Dexie `liveQuery` calls into an `onMount` block to ensure they only run on the client-side.
- **IndexedDB Schema Refactoring:**
- The primary key for the `badge` table was changed from a numeric `id` to the string-based `event_badge_id_random`.
- All related components were updated to use the new primary key for data retrieval, allowing for more efficient lookups using `get()` and `bulkGet()`.
- **Data Flow Simplification:**
- The badge search data flow was refactored to pass full badge objects from the search component to the list component, simplifying the logic and resolving reactivity issues.
- **Link Generation:**
- Badge links were updated to use the string-based random IDs for both the event and the badge, ensuring consistency and avoiding the exposure of internal numeric IDs.
### Event Settings Page (2025-11-18)
A new event settings page was created at `/events/[event_id]/settings` to provide a user-friendly interface for managing event configurations.
**Key features:**
- **Form-Based UI:** Instead of raw JSON editing, the page uses form-based components for editing event properties. This includes basic event fields (name, code, dates, etc.) and the JSON configuration fields (`cfg_json`, `mod_pres_mgmt_json`, `mod_badges_json`, `mod_abstracts_json`).
- **Collapsible Sections:** Each configuration section is wrapped in a `<details>` element, allowing them to be collapsed and expanded for better organization.
- **View Toggling:** For the JSON configuration fields, a toggle switch allows the user to switch between the form-based UI and a raw JSON editor (using CodeMirror), providing flexibility for both simple and advanced editing.
- **Svelte 5 Reactivity:** The components were built using Svelte 5's `bindable` props to ensure proper two-way data binding between the parent page and the child form components. This corrected an issue where changes in the child components were not being reflected in the parent's state.
### API Payload Cleaning (2025-11-19)
To address issues with the Aether API's strict handling of `POST` and `PATCH` request payloads, a more robust solution for cleaning data on the frontend has been implemented.
- **Svelte 5 Event Handlers:** Corrected the use of `on:click` to `onclick` in the event settings components to align with Svelte 5 conventions.
- **Payload Cleaning:**
- The `update_ae_obj__event` function in `src/lib/ae_events/ae_events__event.ts` was modified to remove read-only fields (`id`, `event_id`, `created_on`, `updated_on`, etc.) from the payload before sending it to the API.
- The function now also correctly renames `account_id` to `account_id_random` to match the API's expectations.
- **Editable Fields Whitelist:**
- A new file, `src/lib/ae_events/ae_events__event.editable_fields.ts`, was created to define a whitelist of fields that are allowed to be sent in `POST` and `PATCH` requests for an event.
- The `create_ae_obj__event` and `update_ae_obj__event` functions now use this whitelist to filter the `data_kv` object, ensuring only allowed fields are sent to the API. This provides a more maintainable and less error-prone way to manage which fields are sent to the API.
- **Component Cleanup:** The temporary pre-cleaning logic from the `handle_save` function in `src/routes/events/[event_id]/settings/+page.svelte` has been removed, as the filtering is now handled centrally in `ae_events__event.ts`.
- **Future Work:** This pattern of using a whitelist for editable fields will be applied to all other Aether object types to ensure consistent and correct API interactions across the application.
### Badge Search v3 Bug-Fixing Session (2025-11-19)
This session focused on resolving a series of cascading build and runtime errors that prevented the new "Badges v3" feature from loading and functioning correctly.
- **Initial State:** The page was failing with a `Cannot use @variant with unknown variant: md` error, caused by a conflict between Skeleton UI's CSS and the project's Tailwind CSS v4 configuration.
- **Misguided Fix & Reversal:** An initial attempt to fix this by removing all global Skeleton UI CSS imports from `app.css` resolved the `@variant` error but broke site-wide styling, causing errors like `Cannot apply unknown utility class 'preset-tonal-secondary'`. The Skeleton imports were subsequently restored to stabilize the application.
- **Svelte v5 Event Syntax:** A significant amount of time was spent incorrectly attempting to "fix" Svelte v5 event handlers. The correct understanding was eventually established:
- **DOM Events:** Use the `onevent` prefix (e.g., `onclick`).
- **Component Events:** Continue to use the `on:event` directive (e.g., `on:success`).
- **Invalid Attribute Name Error:** An error (`'onsubmit|preventDefault' is not a valid attribute name`) was discovered in the new badge forms. This was resolved by removing the `|preventDefault` modifier from the `onsubmit` attribute and instead calling `event.preventDefault()` inside the handler function. This appears to be a nuance or bug in how the Svelte v5 compiler handles modifiers with the new `on` prefix.
- **Svelte 5 Binding Error:** A runtime error, `props_invalid_value: Cannot do bind:prop={undefined}`, was fixed. It was caused by binding a parent component's `undefined` store value to a child component's prop that had a fallback. The fix involved adding a defensive initialization check directly in the parent component's `<script>` block to ensure the store value was not `undefined` before rendering. Using `onMount` was attempted first but proved incorrect as it runs too late in the lifecycle.
- **API Fetch Error:** The final blocker was a `TypeError: NetworkError` during badge searches. This was traced to the `order_by_li` parameter being sent to the API in a format that was causing the `fetch` request to be aborted by the browser (likely due to a CORS preflight failure). The immediate fix, identified by the user, was to comment out the `order_by_li` parameter in the `search__event_badge` function call within `src/lib/ae_events/ae_events__event_badge.ts`.
- **Git Issues:** A strange issue was encountered where `git add` commands were not successfully staging files, leading to multiple failed commit attempts. This resolved itself without a clear cause.
This pattern isolates API logic from data shaping logic, making the code more modular, predictable, and easier to debug.

13
GEMINI_Flowbite_upgrade_2025-12.md
View File

@@ -36,3 +36,16 @@ A clear understanding of Flowbite-Svelte's compatibility with our current stack.
2. **If no compatible version exists or issues persist:**
* **Decision:** Abandon Flowbite-Svelte.
* **Action:** Systematically replace its components with custom-built Svelte/Tailwind components, starting with critical ones like `Modal` (using our `element_modal_v1.svelte` if not using Skeleton's `Dialog`).
## Final Decision (2025-12-08)
**Outcome:** Hold off on upgrading Flowbite-Svelte.
**Reasoning:**
The changelog indicates that experimental Svelte 5 support was added in version `0.45.0`. However, there is no mention of compatibility with Tailwind CSS v4. Since SkeletonLabs (the other major UI library) is being removed due to build failures, our immediate priority is to stabilize the project and replace Skeleton's components. Introducing another potential variable by upgrading Flowbite-Svelte at the same time is not advisable.
**Path Forward:**
1. The currently installed version of `flowbite-svelte` (`1.28.1`) will be kept for now.
2. After SkeletonLabs is removed and the project builds successfully, we will test the functionality of existing Flowbite-Svelte components.
3. If they work, we will continue to use them.
4. If they cause build or runtime errors after SkeletonLabs is removed, we will then evaluate either upgrading to `v0.45.0` (with careful testing against Tailwind v4) or abandoning Flowbite-Svelte and replacing its components with custom ones.

14
GEMINI_SkeletonLabs_upgrade_2025-12.md
View File

@@ -46,3 +46,17 @@ A detailed, step-by-step plan for migrating SkeletonLabs from v3 to v4, specific
5. **Run `npm run build` and `npm run dev`** to verify the build and functionality.
6. **Replace `Modal` components:** Update existing components that used an older `<Modal>` (e.g., from `flowbite-svelte` or previous custom efforts) with Skeleton's new `Dialog` component.
7. **Address Svelte 5 reactivity warnings:** Fix any warnings related to data handling or non-reactive updates.
## Final Decision (2025-12-08)
**Outcome:** Abandoning SkeletonLabs.
**Reasoning:**
Despite following the official migration guide and attempting various configurations, the upgrade from SkeletonLabs v3 to v4.7.4 consistently fails with a blocking build error: `[@tailwindcss/vite:generate:build] Cannot use @variant with unknown variant: md`. This error points to a fundamental incompatibility between SkeletonLabs' pre-compiled CSS and the Tailwind CSS v4 build process in this Vite project.
Given the significant time spent debugging this issue without a clear resolution path through configuration, the most pragmatic decision is to remove SkeletonLabs entirely and proceed with custom UI component implementation.
**Path Forward:**
1. All SkeletonLabs dependencies (`@skeletonlabs/skeleton`, `@skeletonlabs/skeleton-svelte`) will be removed from `package.json`.
2. All SkeletonLabs configurations (e.g., in `tailwind.config.ts`, `app.css`) will be removed.
3. UI components previously provided by SkeletonLabs will be replaced with custom Svelte components styled with pure Tailwind CSS.

20
package-lock.json generated
View File

@@ -1,12 +1,12 @@
{
"name": "osit-aether-app-svelte",
"version": "3.11.18",
"version": "3.12.08",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "osit-aether-app-svelte",
"version": "3.11.18",
"version": "3.12.08",
"dependencies": {
"@codemirror/autocomplete": "^6.20.0",
"@codemirror/commands": "^6.10.0",
@@ -7697,6 +7697,22 @@
"integrity": "sha512-JKhqTOwSrqNA1NY5lSztJ1GrBiUodLMmIZuLiDaMRJ+itFd+ABVE8XBjOvIWL+rSqNDC74LCSFmlb/U4UZ4hJQ==",
"license": "ISC"
},
"node_modules/yaml": {
"version": "2.8.2",
"resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.2.tgz",
"integrity": "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==",
"extraneous": true,
"license": "ISC",
"bin": {
"yaml": "bin.mjs"
},
"engines": {
"node": ">= 14.6"
},
"funding": {
"url": "https://github.com/sponsors/eemeli"
}
},
"node_modules/yargs": {
"version": "15.4.1",
"resolved": "https://registry.npmjs.org/yargs/-/yargs-15.4.1.tgz",