Edouard Vanbelle
5afb30ebfd
added group by:
- None (= ordered by folders/file name)
- Type (Folder first, then Image, Vidao, Audio, Document, etc...)
- Owner
- Size (With logarithmic groups))
- Shared date (with groups: today, last 7 days, last 30 days, then year)
470 lines
16 KiB
Markdown
470 lines
16 KiB
Markdown
# Plan: Group-by swimlanes in SharedWithMe
|
|
|
|
## Context
|
|
|
|
The SharedWithMe view now uses `ResourceListComponent` which already accepts an optional `groupFn` in `render()` / `append()`. The task is to expose a **Group by** dropdown in the actions-bar that lets users cluster items into swimlane sections by **Owner** or **Share date**. Changing the grouping restarts the cursor-paginated fetch with the matching `sort_by` query param so the server delivers items pre-sorted for the chosen dimension — the frontend only needs to inject dividers when the key changes.
|
|
|
|
---
|
|
|
|
## Architecture overview
|
|
|
|
```
|
|
main.js (UI) sharedWithMeView.js grants.js / backend
|
|
──────────────────────── ─────────────────── ──────────────────
|
|
[Group by] dropdown ──────→ setGroupBy(key) ──────→ fetchSharedWithMe({ orderBy })
|
|
shows: None / Owner / _groupBy state ↳ GET …?sort_by=granted_by
|
|
Share date resets cursor ↳ GET …?sort_by=granted_at
|
|
_makeGroupFn() ←────── items in server sort order
|
|
render(f, flds, keyFn, labelFn)
|
|
↓
|
|
ResourceListComponent
|
|
injects swimlane dividers
|
|
when keyFn(item) changes
|
|
```
|
|
|
|
---
|
|
|
|
## Extensibility contract (`GroupByDef`)
|
|
|
|
Each view that supports grouping defines a `GroupByDef[]` array locally:
|
|
|
|
```js
|
|
/**
|
|
* @typedef {{ key: string, orderBy: string, keyFn: (item: FileItem|FolderItem) => string|null, labelFn?: (key: string) => string }} GroupByDef
|
|
*/
|
|
```
|
|
|
|
- `key` — internal identifier (`''` = none, `'owner'`, `'shareDate'`)
|
|
- `orderBy` — value forwarded to the API as `sort_by`
|
|
- `keyFn(item)` — returns the grouping key (UUID, bucket name). Same key → same swimlane.
|
|
- `labelFn(key)` — converts the raw key to a human-readable header. Optional (identity if omitted).
|
|
|
|
The separation of `keyFn` / `labelFn` is critical for the Owner case: grouping is keyed by UUID (stable, unique), but the swimlane header shows the resolved display name.
|
|
|
|
---
|
|
|
|
## Changes — Frontend
|
|
|
|
### 1. `static/js/components/resourceList.js`
|
|
|
|
**A. Persist `_lastGroupKey` across `append()` calls**
|
|
|
|
Current bug: `_lastGroupKey` is local to `_appendItems`, so loading page 2 always inserts a redundant swimlane header for the first item even if it belongs to the same group as the last item on page 1.
|
|
|
|
Fix:
|
|
```js
|
|
// constructor
|
|
this._lastGroupKey = /** @type {string|null|undefined} */ (undefined);
|
|
|
|
// render() — reset before first page
|
|
this._lastGroupKey = undefined;
|
|
|
|
// _appendItems() — read and write instance field
|
|
let lastGroupKey = this._lastGroupKey;
|
|
// ... existing loop (unchanged) ...
|
|
this._lastGroupKey = lastGroupKey; // persist for next append()
|
|
```
|
|
|
|
**B. Add optional `groupLabelFn` parameter**
|
|
|
|
```js
|
|
/**
|
|
* @param {FolderItem[]} folders
|
|
* @param {FileItem[]} files
|
|
* @param {((item: FileItem|FolderItem) => string|null)=} groupKeyFn
|
|
* @param {((key: string) => string)=} groupLabelFn — defaults to identity
|
|
*/
|
|
render(folders, files, groupKeyFn, groupLabelFn) { … }
|
|
append(folders, files, groupKeyFn, groupLabelFn) { … }
|
|
```
|
|
|
|
Pass `groupLabelFn` down to `_appendItems` and use it in `_createGroupHeader`:
|
|
```js
|
|
_createGroupHeader(key, labelFn) {
|
|
const label = labelFn ? labelFn(key) : key;
|
|
el.textContent = label;
|
|
…
|
|
}
|
|
```
|
|
|
|
Store `this._groupLabelFn` on the instance between `render()` and `append()` calls (same pattern as `_lastGroupKey`).
|
|
|
|
### 2. `static/css/components/resourceList.css`
|
|
|
|
Add missing swimlane-header styles (block was referenced in JS but had no CSS):
|
|
|
|
```css
|
|
/* ── swimlane group header ─────────────────────────── */
|
|
.resource-list__swimlane-header {
|
|
grid-column: 1 / -1;
|
|
padding: 6px 12px 4px;
|
|
font-size: 0.72rem;
|
|
font-weight: 600;
|
|
text-transform: uppercase;
|
|
letter-spacing: 0.05em;
|
|
color: var(--color-text-faint);
|
|
border-bottom: 1px solid var(--color-border);
|
|
margin-top: 8px;
|
|
}
|
|
.resource-list__swimlane-header:first-child { margin-top: 0; }
|
|
```
|
|
|
|
### 3. `static/js/core/formatters.js`
|
|
|
|
Add `normalizeDateBucket(dateStr)` — pure, no imports needed:
|
|
|
|
```js
|
|
/**
|
|
* Normalize an ISO-8601 date string into a human-readable bucket label.
|
|
* Buckets (newest-first): Today | Last 7 days | Last 30 days | <YYYY>
|
|
* @param {string} dateStr
|
|
* @returns {string}
|
|
*/
|
|
export function normalizeDateBucket(dateStr) {
|
|
const date = new Date(dateStr);
|
|
const diffDays = Math.floor((Date.now() - date.getTime()) / 86_400_000);
|
|
if (diffDays === 0) return i18n.t('dateBucket.today', 'Today');
|
|
if (diffDays <= 7) return i18n.t('dateBucket.last7days', 'Last 7 days');
|
|
if (diffDays <= 30) return i18n.t('dateBucket.last30days','Last 30 days');
|
|
return String(date.getFullYear());
|
|
}
|
|
```
|
|
|
|
(Import `i18n` at top of `formatters.js` if not already present — check first.)
|
|
|
|
### 4. `static/js/model/systemUsers.js`
|
|
|
|
Add synchronous best-effort lookup for use in `groupKeyFn` / swimlane labels:
|
|
|
|
```js
|
|
/**
|
|
* Synchronous best-effort display-name lookup from the pre-fetched cache.
|
|
* Returns a shortened UUID prefix when the cache is not yet loaded.
|
|
* @param {string} userId
|
|
* @returns {string}
|
|
*/
|
|
getDisplayNameSync(userId) {
|
|
if (_index === null) return `${userId.slice(0, 8)}…`;
|
|
return _index.get(userId) ?? `${userId.slice(0, 8)}…`;
|
|
},
|
|
```
|
|
|
|
The cache is loaded by `prefetch()` which `sharedWithMeView.init()` already calls at startup. By the time the first items render, the cache is warm in virtually all cases.
|
|
|
|
### 5. `static/js/model/grants.js`
|
|
|
|
Add `orderBy` param to `fetchSharedWithMe`:
|
|
|
|
```js
|
|
async fetchSharedWithMe({ resourceTypes = ['file', 'folder'], limit = 50, cursor, orderBy } = {}) {
|
|
const params = new URLSearchParams({ limit: String(limit), resource_types: resourceTypes.join(',') });
|
|
if (cursor) params.set('cursor', cursor);
|
|
if (orderBy) params.set('sort_by', orderBy);
|
|
…
|
|
}
|
|
```
|
|
|
|
### 6. `static/js/views/sharedWithMe/sharedWithMeView.js`
|
|
|
|
**New state:**
|
|
```js
|
|
/** @type {string} '' | 'owner' | 'shareDate' */
|
|
_groupBy: '',
|
|
```
|
|
|
|
**`GROUP_BY_DEFS` constant (module-level):**
|
|
```js
|
|
const GROUP_BY_DEFS = [
|
|
{
|
|
key: 'owner',
|
|
orderBy: 'granted_by',
|
|
keyFn: (item) => item.owner_id || null,
|
|
labelFn: (id) => systemUsers.getDisplayNameSync(id)
|
|
},
|
|
{
|
|
key: 'shareDate',
|
|
orderBy: 'granted_at',
|
|
// sort_date is set to item.granted_at in _mapItems()
|
|
keyFn: (item) => {
|
|
const d = /** @type {Record<string,string>} */ (/** @type {unknown} */ (item)).sort_date;
|
|
return d ? normalizeDateBucket(d) : null;
|
|
}
|
|
}
|
|
];
|
|
```
|
|
|
|
**`setGroupBy(key)` public method:**
|
|
```js
|
|
setGroupBy(key) {
|
|
if (this._groupBy === key) return;
|
|
this._groupBy = key;
|
|
this._nextCursor = null; // restart from page 1
|
|
this._component?.clear(); // clear DOM items
|
|
this._loadPage();
|
|
},
|
|
```
|
|
|
|
**`_mapItems()` change:** Set `sort_date: item.granted_at` on both folders and files (replaces `f.modified_at` in files). This is the field the shareDate `keyFn` reads.
|
|
|
|
**`_loadPage()` change:** Derive active def and pass to API + component:
|
|
```js
|
|
const def = GROUP_BY_DEFS.find(d => d.key === this._groupBy);
|
|
const data = await grants.fetchSharedWithMe({
|
|
…,
|
|
orderBy: def?.orderBy // undefined when no grouping
|
|
});
|
|
…
|
|
if (isFirstPage) {
|
|
this._component?.render(folders, files, def?.keyFn, def?.labelFn);
|
|
} else {
|
|
this._component?.append(folders, files, def?.keyFn, def?.labelFn);
|
|
}
|
|
```
|
|
|
|
### 7. `static/js/app/main.js`
|
|
|
|
**A. New `_toggleButtonsWithGroupBy` template (inside `.view-toggle`):**
|
|
```js
|
|
const _toggleButtonsWithGroupBy = `
|
|
<div class="view-toggle">
|
|
<div class="group-by-selector" id="group-by-selector">
|
|
<button class="toggle-btn group-by-btn" id="group-by-btn" title="Group by" data-i18n-title="groupby.title">
|
|
<i class="fas fa-layer-group"></i>
|
|
</button>
|
|
<div class="group-by-menu hidden" id="group-by-menu">
|
|
<button class="group-by-option active" data-group-by="" data-i18n="groupby.none">None</button>
|
|
<button class="group-by-option" data-group-by="owner" data-i18n="groupby.owner">Owner</button>
|
|
<button class="group-by-option" data-group-by="shareDate" data-i18n="groupby.shareDate">Share date</button>
|
|
</div>
|
|
</div>
|
|
<span class="view-toggle-separator"></span>
|
|
<button class="toggle-btn active" id="grid-view-btn" title="Grid view">
|
|
<i class="fas fa-th"></i>
|
|
</button>
|
|
<button class="toggle-btn" id="list-view-btn" title="List view">
|
|
<i class="fas fa-list"></i>
|
|
</button>
|
|
</div>
|
|
`;
|
|
```
|
|
|
|
**B. Update sharedwithme template:** Also add missing `_batchToolbarButons`:
|
|
```js
|
|
sharedwithme: `
|
|
<div class="action-buttons" id="default-buttons"></div>
|
|
${_batchToolbarButons}
|
|
${_toggleButtonsWithGroupBy}
|
|
`
|
|
```
|
|
|
|
**C. `setupActionsBarDelegation()` — add group-by handling before the switch:**
|
|
```js
|
|
// Group-by option selected
|
|
if (btn.classList.contains('group-by-option')) {
|
|
const key = btn.dataset.groupBy ?? '';
|
|
sharedWithMeView.setGroupBy(key);
|
|
document.querySelectorAll('.group-by-option').forEach(b => b.classList.remove('active'));
|
|
btn.classList.add('active');
|
|
document.getElementById('group-by-menu')?.classList.add('hidden');
|
|
document.getElementById('group-by-btn')?.classList.toggle('active', !!key);
|
|
return;
|
|
}
|
|
switch (btn.id) {
|
|
case 'group-by-btn':
|
|
document.getElementById('group-by-menu')?.classList.toggle('hidden');
|
|
break;
|
|
…
|
|
}
|
|
```
|
|
|
|
**D.** Add a `document.addEventListener('click', …)` (or reuse the existing upload-dropdown pattern) to close the group-by menu on outside clicks.
|
|
|
|
### 8. CSS for group-by dropdown
|
|
|
|
Add to `static/css/components/buttons.css` (already contains `.view-toggle` styles):
|
|
|
|
```css
|
|
/* ── Group-by selector (inside .view-toggle) ─────────── */
|
|
.view-toggle-separator {
|
|
width: 1px;
|
|
height: 20px;
|
|
background: var(--color-border);
|
|
align-self: center;
|
|
margin: 0 2px;
|
|
}
|
|
|
|
.group-by-selector {
|
|
position: relative;
|
|
}
|
|
|
|
.group-by-btn.active { color: var(--color-accent); }
|
|
|
|
.group-by-menu {
|
|
position: absolute;
|
|
top: calc(100% + 6px);
|
|
left: 0;
|
|
z-index: 200;
|
|
min-width: 140px;
|
|
background: var(--color-bg-elevated);
|
|
border: 1px solid var(--color-border);
|
|
border-radius: 8px;
|
|
box-shadow: 0 4px 16px var(--color-shadow);
|
|
padding: 4px;
|
|
display: flex;
|
|
flex-direction: column;
|
|
gap: 2px;
|
|
}
|
|
|
|
.group-by-menu.hidden { display: none; }
|
|
|
|
.group-by-option {
|
|
display: flex;
|
|
align-items: center;
|
|
gap: 8px;
|
|
padding: 6px 10px;
|
|
border: none;
|
|
background: transparent;
|
|
border-radius: 6px;
|
|
cursor: pointer;
|
|
font-size: 0.85rem;
|
|
color: var(--color-text);
|
|
text-align: left;
|
|
width: 100%;
|
|
}
|
|
|
|
.group-by-option:hover { background: var(--color-border); }
|
|
.group-by-option.active { color: var(--color-accent); font-weight: 600; }
|
|
```
|
|
|
|
---
|
|
|
|
## Changes — Backend
|
|
|
|
### 9. `src/domain/services/authorization.rs` — update `GrantCursor`
|
|
|
|
```rust
|
|
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
|
|
pub struct GrantCursor {
|
|
/// Sort dimension active when this cursor was issued.
|
|
/// Mis-match with the current `sort_by` param → cursor is discarded.
|
|
#[serde(default = "GrantCursor::default_sort")]
|
|
pub sort_by: String,
|
|
pub granted_at: chrono::DateTime<chrono::Utc>,
|
|
pub resource_id: Uuid,
|
|
/// Present only when `sort_by == "granted_by"`.
|
|
#[serde(skip_serializing_if = "Option::is_none")]
|
|
pub granted_by: Option<Uuid>,
|
|
}
|
|
impl GrantCursor {
|
|
fn default_sort() -> String { "granted_at".to_owned() }
|
|
}
|
|
impl PageCursor for GrantCursor {}
|
|
```
|
|
|
|
Old cursors (which lack `sort_by`) fail serde and are treated as "start from top" — the existing "undecodable cursor → restart" invariant applies.
|
|
|
|
### 10. `src/application/ports/authorization_ports.rs` — add `sort_by` arg
|
|
|
|
```rust
|
|
async fn list_incoming_resources_paged(
|
|
&self,
|
|
subject: Subject,
|
|
kinds: &[ResourceKind],
|
|
limit: u32,
|
|
cursor: Option<GrantCursor>,
|
|
sort_by: &str, // "granted_at" | "granted_by"
|
|
) -> Result<(Vec<IncomingGrantSummary>, Option<GrantCursor>), DomainError>;
|
|
```
|
|
|
|
### 11. `src/infrastructure/services/pg_acl_engine.rs` — branch SQL on sort_by
|
|
|
|
Two separate `sqlx::query_as` calls, selected at runtime:
|
|
|
|
**`sort_by = "granted_by"` SQL:**
|
|
```sql
|
|
WITH agg AS ( … same aggregation … )
|
|
SELECT resource_type, resource_id, permissions, granted_at, granted_by
|
|
FROM agg
|
|
WHERE ( $4::uuid IS NULL -- cursor_by
|
|
OR granted_by > $4::uuid
|
|
OR (granted_by = $4::uuid AND (
|
|
$5::timestamptz IS NULL -- cursor_at
|
|
OR granted_at < $5
|
|
OR (granted_at = $5 AND resource_id < $6::uuid))))
|
|
ORDER BY granted_by ASC, granted_at DESC, resource_id DESC
|
|
LIMIT $7
|
|
```
|
|
Cursor for next page: `GrantCursor { sort_by: "granted_by", granted_at: r.3, resource_id: r.1, granted_by: Some(r.4) }`
|
|
|
|
**`sort_by = "granted_at"` SQL (existing, unchanged except cursor struct gains `sort_by` field):**
|
|
Cursor for next page: `GrantCursor { sort_by: "granted_at", granted_at: r.3, resource_id: r.1, granted_by: None }`
|
|
|
|
### 12. `src/interfaces/api/handlers/grant_handler.rs`
|
|
|
|
```rust
|
|
let sort_by = q.sort_by.as_deref().unwrap_or("granted_at");
|
|
if !matches!(sort_by, "granted_at" | "granted_by") {
|
|
return (StatusCode::BAD_REQUEST, Json(json!({"error": "invalid sort_by"}))).into_response();
|
|
}
|
|
// Invalidate cursor when sort mode changed (prevents keyset confusion)
|
|
let cursor = q.decode_cursor::<GrantCursor>()
|
|
.filter(|c| c.sort_by == sort_by);
|
|
|
|
let (summaries, next_cursor) = state.authorization
|
|
.list_incoming_resources_paged(subject, &kinds, limit, cursor, sort_by)
|
|
.await …;
|
|
```
|
|
|
|
---
|
|
|
|
## Files touched
|
|
|
|
| File | Change |
|
|
|---|---|
|
|
| `static/js/components/resourceList.js` | Persist `_lastGroupKey`; add `groupLabelFn` param to `render`/`append` |
|
|
| `static/css/components/resourceList.css` | Add `.resource-list__swimlane-header` styles |
|
|
| `static/js/core/formatters.js` | Add `normalizeDateBucket()` |
|
|
| `static/js/model/systemUsers.js` | Add `getDisplayNameSync()` |
|
|
| `static/js/model/grants.js` | Add `orderBy` param |
|
|
| `static/js/views/sharedWithMe/sharedWithMeView.js` | Add `_groupBy`, `setGroupBy()`, `GROUP_BY_DEFS`; update `_mapItems`, `_loadPage` |
|
|
| `static/js/app/main.js` | Add `_toggleButtonsWithGroupBy`; add batch toolbar to sharedwithme; wire group-by delegation |
|
|
| `static/css/components/buttons.css` | Add group-by dropdown styles + `.view-toggle-separator` |
|
|
| `src/domain/services/authorization.rs` | Update `GrantCursor` struct |
|
|
| `src/application/ports/authorization_ports.rs` | Add `sort_by` to trait method signature |
|
|
| `src/infrastructure/services/pg_acl_engine.rs` | Branch SQL on `sort_by`; emit new cursor shape |
|
|
| `src/interfaces/api/handlers/grant_handler.rs` | Extract + validate `sort_by`; filter cursor on mismatch |
|
|
|
|
---
|
|
|
|
## Known limitations (out of scope)
|
|
|
|
- **Owner sort order is by UUID, not display name.** Items from the same owner are correctly grouped, but the ORDER of groups is UUID-lexicographic, not alphabetical by name. Alphabetical ordering would require a server-side join to the users table and a different cursor — deferred.
|
|
- **Batch operations from SharedWithMe navigate to Files** — `batchDelete()` calls `loadFiles()`. Pre-existing bug; separate PR.
|
|
- **Group-by is SharedWithMe-only** — the `GroupByDef` contract is extensible but no other view is wired in this PR.
|
|
|
|
---
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
# Backend
|
|
cargo fmt --all
|
|
cargo clippy --all-features --all-targets -- -D warnings
|
|
cargo test --workspace
|
|
|
|
# Frontend
|
|
biome lint static/js/
|
|
stylelint static/css/
|
|
tsc -p jsconfig.json --noEmit
|
|
```
|
|
|
|
Manual smoke tests:
|
|
1. SharedWithMe loads with no group-by → items appear, no swimlane headers
|
|
2. Select "Owner" → page reloads, swimlane headers show resolved display names grouped by granter
|
|
3. "Load more" appends without inserting a redundant header for a continuing group
|
|
4. Select "Share date" → swimlane headers: Today / Last 7 days / Last 30 days / year
|
|
5. Switch back to "None" → plain list, no headers
|
|
6. Cursor cursor changes don't bleed across sort modes (switching group-by resets to page 1)
|
|
7. Grid ↔ list toggle still works in all group-by states
|
|
8. Group-by menu closes when clicking outside
|