domma-cms 1.6.60 → 1.7.0

package/docs/plans/2026-02-28-domma-ui-polish.md

@@ -0,0 +1,286 @@
+# Domma UI Polish - Reveals, Counters, Ripple, Tooltips
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Spruce up the admin panel with Domma's built-in animation and interaction APIs - counter animation on stats, scroll-reveal on card grids, ripple on buttons, and tooltips on icon buttons and sidebar nav items.
+
+**Architecture:** All enhancements are additive - no structural changes. Each view's `onMount` calls the relevant Domma APIs (`E.counter`, `E.reveal`, `E.ripple`, `E.tooltip`) after its content is rendered. Sidebar tooltips are applied post-render in `app.js` via a helper that scans `.sidebar-link` elements.
+
+**Tech Stack:** Domma JS (`E.counter`, `E.reveal`, `E.ripple`, `E.tooltip`), all already loaded via `domma.min.js`.
+
+---
+
+### Task 1: Dashboard - animated counters on stat values
+
+**Files:**
+- Modify: `admin/js/views/dashboard.js`
+
+The stat value elements (`#stat-total`, `#stat-published`, `#stat-drafts`) are currently set with `.text(n)`. Replace with setting the text first, then calling `E.counter()` so the numbers animate from 0 to their real value on mount.
+
+**Step 1: Replace the three `.text()` calls with counter animation**
+
+In `dashboard.js`, replace:
+```javascript
+$container.find('#stat-total').text(total);
+$container.find('#stat-published').text(published);
+$container.find('#stat-drafts').text(drafts);
+```
+With:
+```javascript
+$container.find('#stat-total').text(total);
+$container.find('#stat-published').text(published);
+$container.find('#stat-drafts').text(drafts);
+
+E.counter('#stat-total, #stat-published, #stat-drafts', {
+    trigger: 'immediate',
+    duration: 1000,
+    stagger: 120,
+    easing: 'ease-out'
+});
+```
+
+`E.counter()` reads the current text content of each element as the `to` value and animates from 0. `trigger: 'immediate'` starts on mount (not scroll, since stats are always visible). `stagger: 120` means each counter starts 120ms after the previous.
+
+**Step 2: Verify**
+
+Start/reload the server and visit `#/` (dashboard). The three stat numbers should tick up from 0 on page load instead of appearing instantly.
+
+---
+
+### Task 2: Dashboard - reveal animation on stat cards and recent pages card
+
+**Files:**
+- Modify: `admin/js/views/dashboard.js`
+
+After all content is rendered (after `T.create()`), add reveal calls.
+
+**Step 1: Add reveals after T.create() in dashboard.js**
+
+At the end of `onMount`, after the `T.create()` call and `Domma.icons.scan()`, add:
+```javascript
+E.reveal('.stat-card', { animation: 'fade', stagger: 80, duration: 400 });
+E.reveal('.card.mt-4',  { animation: 'fade', delay: 200,  duration: 400 });
+```
+
+The stat cards stagger in sequence. The recent-pages card fades in 200ms after mount (after the stats).
+
+**Step 2: Verify**
+
+Hard-refresh the dashboard. Stat cards should fade in one after another, then the recent pages card fades in beneath them.
+
+---
+
+### Task 3: Media - reveal on grid cards + ripple on upload button
+
+**Files:**
+- Modify: `admin/js/views/media.js`
+
+**Step 1: Add reveal after renderGrid populates cards**
+
+Inside `renderGrid()`, at the very end (after `Domma.icons.scan()`), add:
+```javascript
+E.reveal('.media-card', { animation: 'fade', stagger: 40, duration: 350 });
+```
+
+**Step 2: Add ripple to the upload button**
+
+In `onMount`, after `Domma.icons.scan()` is called, add:
+```javascript
+E.ripple('#upload-btn');
+```
+
+**Step 3: Add data-tooltip to icon buttons in renderGrid**
+
+In `renderGrid()`, update the two icon buttons from `title="…"` to `data-tooltip="…"`:
+```javascript
+// Was:
+<button class="btn btn-sm btn-ghost btn-copy" data-url="${file.url}" title="Copy URL">
+<button class="btn btn-sm btn-danger btn-delete-media" data-name="${file.name}" title="Delete">
+
+// Becomes:
+<button class="btn btn-sm btn-ghost btn-copy" data-url="${file.url}" data-tooltip="Copy URL">
+<button class="btn btn-sm btn-danger btn-delete-media" data-name="${file.name}" data-tooltip="Delete file">
+```
+
+Then after `Domma.icons.scan()` in renderGrid, add:
+```javascript
+E.tooltip('[data-tooltip]', { placement: 'top' });
+```
+
+**Step 4: Verify**
+
+Visit `#/media`. Cards should fade in with stagger. Hover over the copy/delete icon buttons - proper Domma tooltips should appear instead of browser native title tooltips. Clicking Upload should show a ripple.
+
+---
+
+### Task 4: Plugins - reveal on plugin cards + ripple on toggle buttons
+
+**Files:**
+- Modify: `admin/js/views/plugins.js`
+
+**Step 1: Add reveal and ripple at the end of renderPlugins()**
+
+After `Domma.icons.scan()` in `renderPlugins()`, add:
+```javascript
+E.reveal('.plugin-card', { animation: 'fade', stagger: 60, duration: 400 });
+E.ripple('.btn-toggle-plugin');
+```
+
+**Step 2: Verify**
+
+Visit `#/plugins`. Plugin cards should reveal with stagger. Clicking Enable/Disable should show a ripple effect.
+
+---
+
+### Task 5: Pages and Users list - reveal on the card wrapper
+
+**Files:**
+- Modify: `admin/js/views/pages.js`
+- Modify: `admin/js/views/users.js`
+
+**Step 1: Add reveal in pages.js after renderTable()**
+
+The `renderTable()` function calls `T.create()`. After `Domma.icons.scan()` inside `renderTable()`, add:
+```javascript
+E.reveal('.card', { animation: 'fade', duration: 350 });
+```
+
+**Step 2: Check users.js - add same pattern**
+
+Read `admin/js/views/users.js` and add the same `E.reveal('.card', { animation: 'fade', duration: 350 })` call after the table is rendered.
+
+**Step 3: Verify**
+
+Visit `#/pages` and `#/users`. The card wrapper should fade in smoothly after the table populates.
+
+---
+
+### Task 6: Tooltips on topbar icon buttons
+
+**Files:**
+- Modify: `admin/js/app.js`
+
+The `injectUserMenu()` function injects the Settings link and Sign out button into `#topbar-actions`. Add `data-tooltip` to both and call `E.tooltip()` after the icons are scanned.
+
+**Step 1: Add data-tooltip to topbar actions in injectUserMenu()**
+
+In `app.js`, in `injectUserMenu()`, update the `$('#topbar-actions').html(...)` call:
+
+```javascript
+$('#topbar-actions').html(`
+    <a href="#/settings" class="topbar-action-link" data-tooltip="Settings" data-tooltip-placement="bottom">
+        <span data-icon="settings"></span>
+        <span>Settings</span>
+    </a>
+    <button id="topbar-logout-btn" class="btn btn-sm btn-ghost topbar-signout" data-tooltip="Sign out" data-tooltip-placement="bottom">
+        <span data-icon="log-out"></span>
+        <span>Sign out</span>
+    </button>
+`);
+
+$('#topbar-logout-btn').on('click', () => logout());
+Domma.icons.scan('#admin-topbar');
+E.tooltip('[data-tooltip]', { placement: 'bottom' });
+```
+
+**Step 2: Verify**
+
+Log in. Hover over the Settings link and Sign out button in the topbar - tooltips should appear below them.
+
+---
+
+### Task 7: Sidebar nav item tooltips (shown when collapsed)
+
+**Files:**
+- Modify: `admin/js/app.js`
+
+After the sidebar is built, scan its `.sidebar-link` elements and attach `data-tooltip` values from the item text. This means when the sidebar collapses at ≤992px (icon-only mode), hovering a nav icon shows the page name.
+
+**Step 1: Add a helper function attachSidebarTooltips() in app.js**
+
+Add this function after `buildSidebar()`:
+
+```javascript
+function attachSidebarTooltips() {
+    $('#admin-sidebar .sidebar-link').each(function () {
+        const label = $(this).find('.sidebar-text').text().trim();
+        if (label) $(this).attr('data-tooltip', label);
+    });
+    E.tooltip('#admin-sidebar [data-tooltip]', { placement: 'right' });
+}
+```
+
+**Step 2: Call attachSidebarTooltips() after each buildSidebar() call**
+
+There are two call sites for `buildSidebar()`:
+1. `buildSidebar(null)` at boot (line ~48)
+2. `buildSidebar(user.role)` inside `router:afterChange` when coming from login
+3. `buildSidebar(user.role)` in the boot sequence IIFE
+
+After each, call `attachSidebarTooltips()`.
+
+The `buildSidebar()` function itself can call it internally - add `attachSidebarTooltips()` at the end of `buildSidebar()`:
+
+```javascript
+function buildSidebar(role) {
+    if (sidebar) $('#admin-sidebar').empty();
+    sidebar = Domma.elements.sidebar('#admin-sidebar', {
+        header: { title: 'CMS Admin', icon: 'layout' },
+        items: getSidebarConfig(role),
+        collapsible: true,
+        collapseAt: 992,
+        push: true,
+        contentSelector: '.dashboard-main',
+        top: '60px'
+    });
+    attachSidebarTooltips();
+}
+```
+
+**Step 3: Verify**
+
+Narrow the browser to ≤992px so the sidebar collapses to icon-only mode. Hover over each nav icon - the page name should appear in a tooltip to the right.
+
+---
+
+### Task 8: Global ripple on primary action buttons via router hook
+
+**Files:**
+- Modify: `admin/js/app.js`
+
+Rather than adding `E.ripple()` in every view individually, apply it globally after each route renders by hooking into `router:afterChange`.
+
+**Step 1: Add ripple subscription in app.js**
+
+In the `M.subscribe('router:afterChange', ...)` block (or add a new one), after showing chrome, add a short timeout to let the view render before applying ripple:
+
+```javascript
+M.subscribe('router:afterChange', () => {
+    // Apply ripple to primary/danger buttons after view renders
+    setTimeout(() => {
+        E.ripple('.btn-primary, .btn-danger');
+    }, 50);
+});
+```
+
+The 50ms timeout ensures the view's `onMount` has injected its HTML before `E.ripple()` scans for buttons. `E.ripple()` is idempotent - it skips elements already marked with `.dm-ripple-container`.
+
+**Step 2: Verify**
+
+Navigate to Dashboard, Pages, Settings. Click any primary button (New Page, Save, etc.) - a ripple effect should radiate from the click point.
+
+---
+
+## Verification Checklist
+
+- [ ] Dashboard stat numbers count up from 0 on load
+- [ ] Dashboard stat cards fade in with stagger, then recent pages card fades in
+- [ ] Media grid cards reveal with stagger after upload or initial load
+- [ ] Media icon buttons show Domma tooltips on hover (not browser title)
+- [ ] Upload button shows ripple on click
+- [ ] Plugin cards reveal with stagger
+- [ ] Plugin Enable/Disable buttons show ripple on click
+- [ ] Pages card fades in on load
+- [ ] Topbar Settings and Sign out show tooltip below on hover
+- [ ] Sidebar nav items show tooltips on right when collapsed (≤992px)
+- [ ] All `.btn-primary` and `.btn-danger` buttons across all views show ripple