Merge branch 'main' of github.com:devforth/adminforth

Author: ivictbor

README.md

@@ -37,32 +37,43 @@ Why AdminForth:
 
 ## Project initialisation
 
-```
-mkdir myadmin && cd myadmin
+To create an AdminForth project, run:
+
+```bash
 npx adminforth create-app
 ```
 
-## Previews
+During the interactive initialization process, AdminForth will ask you to provide a local database URL.
 
-<a href="https://adminforth.dev/docs/tutorial/Customization/customPages">Custom Dashboard</a>
-<br/>
-<img src="https://github.com/user-attachments/assets/aa899196-f7f3-4582-839c-2267f2e9e197" alt="AdminForth Dashboard demo" width="80%" />
+### Integrating AdminForth into your existing application
 
-<a href="https://adminforth.dev/docs/tutorial/Plugins/chat-gpt">Text completion plugin (Copilot-style) using LLMs</a>
-<br/>
+If you want to build an admin panel for an existing project that already has a database with tables, you can provide the connection URL to your existing development database, such as a local or deployed one.
 
-<img src="https://github.com/user-attachments/assets/cfa17cbd-3a53-4725-ab46-53c7c7666028" alt="AdminForth ChatGPT demo" width="80%" />
+After that, you may want to generate AdminForth resource files from your existing database tables:
 
-<a href="https://adminforth.dev/docs/tutorial/Plugins/upload/#image-generation">Image Generation using image generation models</a>
-<br/>
-<img src="https://github.com/user-attachments/assets/b923e044-7e29-46ff-ab91-eeca5eee2b0a" alt="AdminForth DALE-E image generator demo" width="80%">
+```bash
+npx adminforth resource
+```
+
+Resource files are needed for AdminForth to “know” about your tables and define how to work with them.
+
+Use the command above every time you add new tables or change their schema.
+
+### Starting from scratch
+
+If you do not have a database yet, start an empty local database, for example PostgreSQL in Docker, and provide its URL to the AdminForth CLI.
+
+If the adminforth CLI does not detect any tables, it will suggest adding Prisma as a migration tool. Prisma is not related to AdminForth, but it is one of the most convenient migration tools.
+
+Please follow [getting started](https://adminforth.dev/docs/tutorial/gettingStarted/).
 
+# For AdminForth developers
 
-# For developers
+> Follow this section only if you want to make changes to the AdminForth framework or develop a plugin.
 
-The most convenient way to add new features or fixes is using `dev-demo`. It imports the source code of the repository and plugins so you can edit them and see changes on the fly.
+The most convenient way to add new features or fixes is to use `dev-demo`. It imports the repository source code and plugins, so you can edit them and see changes on the fly.
 
-# Requirements
+## Requirements
 
 - **Node.js 20**
 - **Docker**

adminforth/dataConnectors/sqlite.ts

@@ -101,6 +101,9 @@ class SQLiteConnector extends AdminForthBaseConnector implements IAdminForthData
             const [precision, scale] = baseType.match(/\d+/g);
             field.precision = parseInt(precision);
             field.scale = parseInt(scale);
+          } else if (baseType == 'json' || baseType == 'jsonb') {
+            field.type = AdminForthDataTypes.JSON;
+            field._underlineType = baseType;
           } else if (baseType === 'decimal') {
             field.type = AdminForthDataTypes.DECIMAL;
             field._underlineType = 'decimal';

adminforth/documentation/blog/2025-11-04-k3s-ec2-deployment/index.md

@@ -729,13 +729,14 @@ sed -i 's/certificate-authority-data:.*/insecure-skip-tls-verify: true/g' kubeco
 export KUBECONFIG=$(pwd)/kubeconfig.yaml
 
 cd helm
-export APP_NAMESPACE="myadmin"
-export IMAGE_FULL_TAG="$${ACCOUNT_ID}.dkr.ecr.$${REGION}.amazonaws.com/myadmink3s:$${TAG}"
+export APP_NAMESPACE="myadmin"  # <<< SET YOUR APP NAMESPACE HERE
+export IMAGE_FULL_TAG="$${ACCOUNT_ID}.dkr.ecr.$${REGION}.amazonaws.com/myadmink3s:$${TAG}"  # Change 'myadmink3s' to your app name in 'helmfile.yaml' & 'Chart.yaml' files as well
 helmfile apply
 cd ..
 
 echo "Deployment complete!"
 ```
+You need to change the values of `APP_NAMESPACE` and `IMAGE_FULL_TAG` in the `deploy/deploy.sh` script to match your application name and image tag. Note that `IMAGE_FULL_TAG` is constructed dynamically from the Terraform outputs and the tag, so you only need to change `APP_NAMESPACE`.
 
 Don't forget to make the script executable:
 

adminforth/documentation/docs/tutorial/03-Customization/10-menuConfiguration.md

@@ -304,3 +304,129 @@ menu: [
 
 ```
 > 👆 Please note start internal URLs with a leading / to ensure correct routing.
+
+
+## Adding menu items from plugins
+
+Plugins can add top-level menu items without mutating the user-defined `config.menu`. This keeps the application menu owned by the app configuration, while plugins can contribute their own entries.
+
+Use `registerMenuContribution` from a plugin's `modifyResourceConfig`:
+
+```ts title='./plugins/adminforth-dashboard/index.ts'
+async modifyResourceConfig(adminforth, resourceConfig) {
+  super.modifyResourceConfig(adminforth, resourceConfig);
+
+  adminforth.registerMenuContribution({
+    item: {
+      itemId: 'dashboard',
+      type: 'page',
+      label: 'Dashboard',
+      icon: 'flowbite:chart-pie-solid',
+      path: '/dashboard',
+      component: this.componentPath('Dashboard.vue'),
+    },
+    placement: { before: { resourceId: 'adminuser' } },
+  });
+}
+```
+
+Supported placements:
+
+```ts
+adminforth.registerMenuContribution({
+  item: {
+    itemId: 'dashboard',
+    type: 'page',
+    label: 'Dashboard',
+    path: '/dashboard',
+    component: this.componentPath('Dashboard.vue'),
+  },
+  placement: { position: 'first' },
+});
+
+adminforth.registerMenuContribution({
+  item: {
+    itemId: 'reports',
+    type: 'page',
+    label: 'Reports',
+    path: '/reports',
+    component: this.componentPath('Reports.vue'),
+  },
+  placement: { after: { resourceId: 'orders' } },
+});
+```
+
+`placement` can be:
+
+- `{ position: 'first' }`
+- `{ position: 'last' }`
+- `{ before: 'usersMenuItemId' }`
+- `{ after: 'usersMenuItemId' }`
+- `{ before: { itemId: 'usersMenuItemId' } }`
+- `{ after: { resourceId: 'adminuser' } }`
+- `{ before: { path: '/reports' } }`
+
+If placement is omitted, or if the target item is not found, AdminForth appends the contributed item to the end of the top-level menu.
+
+Plugin menu contributions are additive only:
+
+- user-defined `config.menu` is not changed
+- plugins cannot remove or edit existing menu items through this API
+- contributed `itemId` must not duplicate an existing top-level menu item
+- this first version inserts only top-level menu items
+
+### Dynamic menu items from plugin state
+
+If a plugin needs to add menu items at runtime, for example after a user clicks a button and creates a new dashboard, register a menu contribution provider. AdminForth calls providers every time it fetches the menu.
+
+```ts title='./plugins/adminforth-dashboard/index.ts'
+async modifyResourceConfig(adminforth, resourceConfig) {
+  super.modifyResourceConfig(adminforth, resourceConfig);
+
+  adminforth.registerMenuContributionProvider(async ({ adminUser, adminforth }) => {
+    const dashboards = await adminforth.resource('dashboards').list();
+
+    return [
+      {
+        item: {
+          itemId: 'dashboardsMenu',
+          type: 'group',
+          label: 'Dashboards',
+          icon: 'flowbite:chart-pie-solid',
+          children: dashboards.map((dashboard) => ({
+            itemId: `dashboard-${dashboard.id}`,
+            type: 'page',
+            label: dashboard.name,
+            path: `/dashboards/${dashboard.id}`,
+          })),
+        },
+        placement: { position: 'first' },
+      },
+    ];
+  });
+}
+```
+
+After the plugin changes the state used by the provider, call `refreshMenu` on the backend:
+
+```ts
+await adminforth.resource('dashboards').create({
+  name: 'Sales',
+});
+
+await adminforth.refreshMenu(adminUser);
+```
+
+AdminForth sends a websocket event to the current user, and the frontend refetches the menu without a page reload.
+
+Frontend components can also refresh the menu directly:
+
+```ts
+import { useAdminforth } from '@/adminforth';
+
+const { menu } = useAdminforth();
+
+await menu.refresh();
+```
+
+Dynamic menu items should point to routes that are already available in the SPA. If a provider returns a brand-new custom `component` path that was not known during AdminForth build, the menu item can appear, but the route will not be registered until the app is rebuilt.

adminforth/documentation/docs/tutorial/05-Adapters/09-chat-surface-adapters.md

@@ -1,5 +1,5 @@
 ---
-title: Telegram Chat Surface Adapter (WIP)
+title: Telegram Chat Surface Adapter
 description: "Reference page for AdminForth Agent chat surface adapters, including Telegram bot setup and webhook configuration."
 slug: /tutorial/Adapters/chat-surface-adapter-telegram
 sidebar_position: 8