webspresso 0.0.85 → 0.0.87

package/README.md

@@ -808,6 +808,33 @@ Options:
 
 See **`doc/index.html#admin-user-management`** and **Session authentication** in **`.agents/skills/webspresso-usage/REFERENCE-framework.md`** for the split between **`adminUser`** and **`createApp({ auth })`**.
 
+**3-State Table Column Sorting & Configuration:**
+
+Admin Panel table headers support interactive 3-state column sorting:
+- **State 1 (`Unsorted`)**: Default state (`↕` icon).
+- **State 2 (`ASC`)**: 1st click sorts ascending (`▲` icon, `?sort=col&order=asc`).
+- **State 3 (`DESC`)**: 2nd click sorts descending (`▼` icon, `?sort=col&order=desc`).
+- **State 4 (`Unsorted`)**: 3rd click clears sorting and reverts to default primary key ordering.
+
+Configuration options:
+- **Column-level**: Standard scalar columns (`string`, `number`, `boolean`, `timestamp`) are sortable by default. Disable or enable per column:
+  ```javascript
+  schema: zdb.schema({
+    name: zdb.string({ sortable: true }),
+    secret_notes: zdb.text().config({ sortable: false }), // or zdb.text({ sortable: false })
+  })
+  ```
+- **Model-level**: Restrict sortable columns or disable sorting completely on a model in `defineModel`:
+  ```javascript
+  admin: {
+    enabled: true,
+    sortableColumns: ['name', 'price'], // Only name and price are sortable
+    // Or disable all sorting:
+    // sortable: false,
+  }
+  ```
+
+
 
 **Custom Admin Pages (registerModule):**
 
@@ -858,7 +885,7 @@ if (adminApi) {
 | `scripts` | External script URLs, script objects, or inline scripts injected into SSR Admin Panel (`registerScript`) |
 | `styles` | External stylesheet URLs or inline CSS injected into SSR Admin Panel (`registerStyle`) |
 
-Pages support JavaScript client components (`componentFile`, `pagesDir`, `component`) as well as **custom HTML & external URL pages** (`url` or `iframeUrl` for external web apps, and `html` or `htmlFile` for local HTML files like EUIX Engine apps). By default (`layout: true`), custom page views are automatically wrapped in the Admin Layout with Breadcrumbs. Set `layout: false` for full-screen / custom canvas pages.
+Pages support JavaScript client components (`componentFile`, `pagesDir`, `component`), external URLs (`url` or `iframeUrl` inside `<iframe>`), as well as **native custom HTML pages** (`html` or `htmlFile` for local HTML files like EUIX Engine apps, Vue, or Alpine). HTML pages render directly in the page DOM with full Tailwind CSS styling, dark mode, and script execution without iframe overhead. Set `iframe: true` to isolate in an iframe if needed. By default (`layout: true`), custom page views are automatically wrapped in the Admin Layout with Breadcrumbs. Set `layout: false` for full-screen / custom canvas pages.
 
 **Example component file (`admin/reports.js`):**
 

package/core/orm/model.js

@@ -91,6 +91,9 @@ function defineModel(options) {
       icon: admin.icon || null,
       customFields: admin.customFields || {},
       queries: admin.queries || {},
+      sortable: admin.sortable,
+      sortableColumns: admin.sortableColumns,
+      columns: admin.columns,
     },
     rest: {
       enabled: rest.enabled === true,

package/core/orm/schema-helpers.js

@@ -231,6 +231,7 @@ class SchemaBuilder {
     if (options.readonly !== undefined) this._ui.readonly = options.readonly;
     if (options.width !== undefined) this._ui.width = options.width;
     if (options.rows !== undefined) this._ui.rows = options.rows;
+    if (options.sortable !== undefined) this._ui.sortable = options.sortable;
     return this;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.85",
+  "version": "0.0.87",
   "description": "Minimal, production-ready SSR framework for Node.js with file-based routing, Nunjucks templating, built-in i18n, and CLI tooling",
   "main": "index.js",
   "types": "index.d.ts",

package/plugins/admin-panel/api.js

@@ -268,6 +268,28 @@ function createApiHandlers(options) {
     }
   }
 
+/**
+ * Helper to determine if a column is sortable based on model and column configs
+ */
+function isColumnSortable(name, meta, model) {
+  if (!meta) return false;
+  if (model.admin && model.admin.sortable === false) return false;
+  if (model.admin && Array.isArray(model.admin.sortableColumns)) {
+    return model.admin.sortableColumns.includes(name);
+  }
+  if (model.admin?.columns?.[name]?.sortable !== undefined) {
+    return Boolean(model.admin.columns[name].sortable);
+  }
+  if (meta.sortable !== undefined) {
+    return Boolean(meta.sortable);
+  }
+  if (meta.ui?.sortable !== undefined) {
+    return Boolean(meta.ui.sortable);
+  }
+  const nonSortableTypes = ['json', 'array', 'file'];
+  return !nonSortableTypes.includes(meta.type);
+}
+
   /**
    * Get model metadata
    */
@@ -304,6 +326,7 @@ function createApiHandlers(options) {
           validations: meta.validations || null,
           ui: meta.ui ? { ...meta.ui, hidden: isHidden || meta.ui.hidden } : (isHidden ? { hidden: true } : null),
           hidden: isHidden, // Excluded from list display and API responses
+          sortable: isColumnSortable(name, meta, model),
         });
       }
 
@@ -486,9 +509,22 @@ function createApiHandlers(options) {
       // Apply pagination
       query = query.offset(offset).limit(perPage);
 
-      // Apply sorting (newest first by default)
+      // Apply sorting
       const primaryKey = model.primaryKey || 'id';
-      query = query.orderBy(primaryKey, 'desc');
+      const sortParam = req.query.sort;
+      const orderParam = (req.query.order || 'desc').toLowerCase();
+      const sortOrder = orderParam === 'asc' ? 'asc' : 'desc';
+
+      if (sortParam && model.columns.has(sortParam)) {
+        const colMeta = model.columns.get(sortParam);
+        if (isColumnSortable(sortParam, colMeta, model)) {
+          query = query.orderBy(sortParam, sortOrder);
+        } else {
+          query = query.orderBy(primaryKey, 'desc');
+        }
+      } else {
+        query = query.orderBy(primaryKey, 'desc');
+      }
 
       // Get records
       const records = await query.list();

package/plugins/admin-panel/client/parts/01-state-api-breadcrumb.js

@@ -96,6 +96,8 @@ const state = {
   formData: {}, // Form field values
   editing: false,
   filters: {}, // Active filters { column: { op, value, from, to } }
+  sortColumn: null, // Currently sorted column name
+  sortDirection: null, // Sort direction: 'asc' | 'desc' | null
   filterPanelOpen: false, // Filter panel visibility (deprecated)
   filterDrawerOpen: false, // Filter drawer visibility
   bulkFields: [], // Bulk-updatable fields (enum/boolean/date/datetime/timestamp)

package/plugins/admin-panel/client/parts/04-field-renderers.js

@@ -300,7 +300,15 @@ const FieldRenderers = {
     const label = ui.label || formatColumnLabel(col.name);
     const placeholder = ui.placeholder || '';
     const hint = ui.hint || '';
-    const dateValue = value ? new Date(value).toISOString().split('T')[0] : '';
+    let dateValue = '';
+    if (value) {
+      try {
+        const d = new Date(value);
+        if (!isNaN(d.getTime())) {
+          dateValue = d.toISOString().split('T')[0];
+        }
+      } catch {}
+    }
     
     return m('.mb-4', [
       m('label.block.text-sm.font-medium.text-gray-700 dark:text-slate-300.mb-1', { for: col.name }, label),
@@ -329,7 +337,15 @@ const FieldRenderers = {
     const label = ui.label || formatColumnLabel(col.name);
     const placeholder = ui.placeholder || '';
     const hint = ui.hint || '';
-    const dateTimeValue = value ? new Date(value).toISOString().slice(0, 16) : '';
+    let dateTimeValue = '';
+    if (value) {
+      try {
+        const d = new Date(value);
+        if (!isNaN(d.getTime())) {
+          dateTimeValue = d.toISOString().slice(0, 16);
+        }
+      } catch {}
+    }
     
     return m('.mb-4', [
       m('label.block.text-sm.font-medium.text-gray-700 dark:text-slate-300.mb-1', { for: col.name }, label),

package/plugins/admin-panel/client/parts/07-model-list.js

@@ -90,13 +90,13 @@ function formatCellValue(value, col, record = null) {
     case 'timestamp':
       try {
         const date = new Date(value);
-        return date.toLocaleString();
+        return isNaN(date.getTime()) ? String(value) : date.toLocaleString();
       } catch { return String(value); }
     
     case 'date':
       try {
         const date = new Date(value);
-        return date.toLocaleDateString();
+        return isNaN(date.getTime()) ? String(value) : date.toLocaleDateString();
       } catch { return String(value); }
     
     case 'json':
@@ -523,21 +523,31 @@ function parseFilterQuery(queryString) {
   return filters;
 }
 
-// Load records with pagination and filters
-function loadRecords(modelName, page = 1, filters = null) {
+// Load records with pagination, filters, and sorting
+function loadRecords(modelName, page = 1, filters = null, sortColumn = undefined, sortDirection = undefined) {
   state.loading = true;
   state.error = null;
   
   const perPage = state.pagination.perPage || 20;
   const activeFilters = filters !== null ? filters : state.filters;
+  const activeSortCol = sortColumn !== undefined ? sortColumn : state.sortColumn;
+  const activeSortDir = sortDirection !== undefined ? sortDirection : state.sortDirection;
+  
+  state.sortColumn = activeSortCol;
+  state.sortDirection = activeSortDir;
+  
   const filterQuery = buildFilterQuery(activeFilters);
   
-  // Update URL with filters
+  // Update URL with filters and sort params
   const queryParams = new URLSearchParams();
   queryParams.set('page', page);
   if (state.trashedView) {
     queryParams.set('trashed', 'only');
   }
+  if (activeSortCol && activeSortDir) {
+    queryParams.set('sort', activeSortCol);
+    queryParams.set('order', activeSortDir);
+  }
   if (Object.keys(activeFilters).length > 0) {
     for (const [col, filter] of Object.entries(activeFilters)) {
       if (!filter || !filterPayloadIsActive(filter)) continue;
@@ -566,7 +576,8 @@ function loadRecords(modelName, page = 1, filters = null) {
   window.history.replaceState({}, '', newUrl);
   
   const trashedParam = state.trashedView ? '&trashed=only' : '';
-  return api.get('/models/' + modelName + '/records?page=' + page + '&perPage=' + perPage + trashedParam + filterQuery)
+  const sortParam = activeSortCol && activeSortDir ? '&sort=' + encodeURIComponent(activeSortCol) + '&order=' + encodeURIComponent(activeSortDir) : '';
+  return api.get('/models/' + modelName + '/records?page=' + page + '&perPage=' + perPage + trashedParam + filterQuery + sortParam)
     .then(result => {
       state.records = result.data || [];
       state.pagination = {
@@ -601,11 +612,16 @@ function initializeModelView(modelName) {
   state.selectedBulkField = null;
   state._currentModelName = modelName;
   
-  // Parse filters from URL query string
+  // Parse filters and sorting from URL query string
   const urlParams = new URLSearchParams(window.location.search);
   const page = parseInt(urlParams.get('page')) || 1;
   state.filters = parseFilterQuery(window.location.search);
   
+  const rawSort = urlParams.get('sort');
+  const rawOrder = (urlParams.get('order') || '').toLowerCase();
+  state.sortColumn = rawSort || null;
+  state.sortDirection = rawOrder === 'asc' ? 'asc' : rawOrder === 'desc' ? 'desc' : null;
+  
   // Load model metadata first, then records
   state.loading = true;
   api.get('/models/' + modelName)
@@ -614,7 +630,7 @@ function initializeModelView(modelName) {
       state.currentModel = modelMeta;
       // Load bulk-updatable fields for this model
       loadBulkFields(modelName);
-      return loadRecords(modelName, page, state.filters);
+      return loadRecords(modelName, page, state.filters, state.sortColumn, state.sortDirection);
     })
     .catch(err => {
       state.error = err.message;

package/plugins/admin-panel/client/parts/08-record-list.js

@@ -441,12 +441,54 @@ const RecordList = {
                       }),
                     ]),
                     // Dynamic column headers (first column sticky left with box-shadow)
-                    ...displayColumns.map((col, i) => 
-                      m('th.px-4.py-3.text-left.text-xs.font-medium.text-gray-500 dark:text-slate-400.uppercase.tracking-wider.whitespace-nowrap.bg-gray-50 dark:bg-slate-900.border-b.border-gray-200 dark:border-slate-700', 
-                        i === 0 ? { style: 'position: sticky; left: 40px; z-index: 15; box-shadow: 4px 0 8px -4px rgba(0,0,0,0.08);' } : {},
-                        formatColumnLabel(col.name)
-                      )
-                    ),
+                    ...displayColumns.map((col, i) => {
+                      const isSortable = col.sortable !== false;
+                      const isSorted = isSortable && state.sortColumn === col.name;
+                      const dir = isSorted ? state.sortDirection : null;
+                      const stickyStyle = i === 0 ? 'position: sticky; left: 40px; z-index: 15; box-shadow: 4px 0 8px -4px rgba(0,0,0,0.08);' : '';
+
+                      if (!isSortable) {
+                        return m('th.px-4.py-3.text-left.text-xs.font-medium.text-gray-500.dark:text-slate-400.uppercase.tracking-wider.whitespace-nowrap.bg-gray-50.dark:bg-slate-900.border-b.border-gray-200.dark:border-slate-700',
+                          stickyStyle ? { style: stickyStyle } : {},
+                          formatColumnLabel(col.name)
+                        );
+                      }
+
+                      return m('th.px-4.py-3.text-left.text-xs.font-medium.text-gray-500.dark:text-slate-400.uppercase.tracking-wider.whitespace-nowrap.bg-gray-50.dark:bg-slate-900.border-b.border-gray-200.dark:border-slate-700.cursor-pointer.select-none.hover:bg-gray-100.dark:hover:bg-slate-800/80.transition-colors.group',
+                        {
+                          style: stickyStyle || undefined,
+                          onclick: () => {
+                            let nextSort = col.name;
+                            let nextDir = 'asc';
+                            if (state.sortColumn === col.name) {
+                              if (state.sortDirection === 'asc') {
+                                nextDir = 'desc';
+                              } else if (state.sortDirection === 'desc') {
+                                nextSort = null;
+                                nextDir = null;
+                              }
+                            }
+                            state.sortColumn = nextSort;
+                            state.sortDirection = nextDir;
+                            loadRecords(modelName, 1, state.filters, nextSort, nextDir);
+                          },
+                        },
+                        m('.flex.items-center.gap-1.5', [
+                          m('span', formatColumnLabel(col.name)),
+                          dir === 'asc'
+                            ? m('svg.w-3.5.h-3.5.text-indigo-600.dark:text-indigo-400.flex-shrink-0', { fill: 'currentColor', viewBox: '0 0 20 20' },
+                                m('path', { 'fill-rule': 'evenodd', d: 'M14.707 12.707a1 1 0 01-1.414 0L10 9.414l-3.293 3.293a1 1 0 01-1.414-1.414l4-4a1 1 0 011.414 0l4 4a1 1 0 010 1.414z', 'clip-rule': 'evenodd' })
+                              )
+                            : dir === 'desc'
+                              ? m('svg.w-3.5.h-3.5.text-indigo-600.dark:text-indigo-400.flex-shrink-0', { fill: 'currentColor', viewBox: '0 0 20 20' },
+                                  m('path', { 'fill-rule': 'evenodd', d: 'M5.293 7.293a1 1 0 011.414 0L10 10.586l3.293-3.293a1 1 0 111.414 1.414l-4 4a1 1 0 01-1.414 0l-4-4a1 1 0 010-1.414z', 'clip-rule': 'evenodd' })
+                                )
+                              : m('svg.w-3.5.h-3.5.text-gray-300.dark:text-slate-600.group-hover:text-gray-400.flex-shrink-0', { fill: 'currentColor', viewBox: '0 0 20 20' },
+                                  m('path', { d: 'M5 12a1 1 0 100 2h10a1 1 0 100-2H5zM5 6a1 1 0 100 2h10a1 1 0 100-2H5z' })
+                                )
+                        ])
+                      );
+                    }),
                     // Sticky actions header (sticky right, box-shadow on left)
                     m('th.px-4.py-3.text-right.text-xs.font-medium.text-gray-500 dark:text-slate-400.uppercase.tracking-wider.bg-gray-50 dark:bg-slate-900.border-b.border-gray-200 dark:border-slate-700', {
                       style: 'position: sticky; right: 0; min-width: 120px; z-index: 15; box-shadow: -4px 0 8px -4px rgba(0,0,0,0.08);',

package/plugins/admin-panel/core/admin-module.js

@@ -272,6 +272,7 @@ function registerPages(moduleId, pages, deps) {
       description: page.description,
       permission: page.permission,
       layout: page.layout !== undefined ? page.layout : true,
+      iframe: page.iframe,
       url: page.url || page.iframeUrl || undefined,
       html: htmlContent || undefined,
     });

package/plugins/admin-panel/core/registry.js

@@ -479,6 +479,7 @@ class AdminRegistry {
         description: p.description,
         permission: p.permission,
         layout: p.layout !== undefined ? p.layout : true,
+        iframe: p.iframe,
         url: p.url || p.iframeUrl,
         html: p.html,
         hasClientComponent: this.clientComponents.has(p.id),

package/plugins/admin-panel/field-renderers/basic.js

@@ -121,7 +121,15 @@ module.exports = {
   DateField: {
     view: (vnode) => {
       const { name, value = '', meta = {}, required = false } = vnode.attrs;
-      const dateValue = value ? new Date(value).toISOString().split('T')[0] : '';
+      let dateValue = '';
+      if (value) {
+        try {
+          const d = new Date(value);
+          if (!isNaN(d.getTime())) {
+            dateValue = d.toISOString().split('T')[0];
+          }
+        } catch {}
+      }
       return m('.mb-4', [
         m('label.block.text-sm.font-medium.mb-2', { for: name },
           meta.label || name,
@@ -149,7 +157,15 @@ module.exports = {
   DateTimeField: {
     view: (vnode) => {
       const { name, value = '', meta = {}, required = false } = vnode.attrs;
-      const dateTimeValue = value ? new Date(value).toISOString().slice(0, 16) : '';
+      let dateTimeValue = '';
+      if (value) {
+        try {
+          const d = new Date(value);
+          if (!isNaN(d.getTime())) {
+            dateTimeValue = d.toISOString().slice(0, 16);
+          }
+        } catch {}
+      }
       return m('.mb-4', [
         m('label.block.text-sm.font-medium.mb-2', { for: name },
           meta.label || name,

package/plugins/admin-panel/modules/custom-pages.js

@@ -156,7 +156,7 @@ function generateCustomPageComponent() {
   return `
 // Custom Page Component Factory
 function createCustomPage(pageConfig) {
-  if (pageConfig && (pageConfig.url || pageConfig.html)) {
+  if (pageConfig && (pageConfig.url || (pageConfig.html && pageConfig.iframe))) {
     var iframeAttrs = {
       src: pageConfig.url || undefined,
       srcdoc: pageConfig.html || undefined,
@@ -187,6 +187,46 @@ function createCustomPage(pageConfig) {
     };
   }
 
+  if (pageConfig && pageConfig.html) {
+    var executeScripts = function(vnode) {
+      if (!vnode.dom) return;
+      var scripts = vnode.dom.querySelectorAll('script');
+      scripts.forEach(function(oldScript) {
+        if (oldScript.dataset && oldScript.dataset.executed) return;
+        var newScript = document.createElement('script');
+        Array.from(oldScript.attributes).forEach(function(attr) {
+          newScript.setAttribute(attr.name, attr.value);
+        });
+        newScript.dataset.executed = 'true';
+        newScript.appendChild(document.createTextNode(oldScript.innerHTML));
+        oldScript.parentNode.replaceChild(newScript, oldScript);
+      });
+    };
+    if (pageConfig.layout === false) {
+      return {
+        oncreate: executeScripts,
+        view: function() {
+          return m('div.custom-html-container', m.trust(pageConfig.html));
+        }
+      };
+    }
+    return {
+      oncreate: executeScripts,
+      view: function() {
+        return m(Layout, [
+          m(Breadcrumb, { items: [{ label: pageConfig.title, href: pageConfig.path }] }),
+          m('div.mb-4.flex.items-start.justify-between.gap-4', [
+            m('div', [
+              m('h1.text-2xl.font-bold.text-gray-900.dark:text-slate-100', pageConfig.title),
+              pageConfig.description && m('p.text-gray-500.dark:text-slate-400.mt-1', pageConfig.description)
+            ])
+          ]),
+          m('div.custom-html-container', m.trust(pageConfig.html))
+        ]);
+      }
+    };
+  }
+
   return {
     oninit(vnode) {
       vnode.state.data = null;