@quazardous/qdadm 2.37.0 → 2.39.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,395 @@
1
+ <script setup lang="ts">
2
+ /**
3
+ * CardsDashboard — a zone's blocks as cards each user arranges (#4320):
4
+ * reorder (drag or keyboard), hide, pin at the top. The arrangement is kept in
5
+ * localStorage per dashboard and per user (useCardsArrangement).
6
+ *
7
+ * A card is any block with an id, so one block serves both a classic Zone and
8
+ * this dashboard. Its optional `card` field adds the title and what the app
9
+ * forces:
10
+ *
11
+ * ctx.block(DASHBOARD_ZONES.WIDGETS, {
12
+ * id: 'sales', component: SalesCard, weight: 10,
13
+ * card: { title: 'Sales', required: true, span: 2 },
14
+ * })
15
+ *
16
+ * <CardsDashboard /> // the dashboard widgets zone
17
+ * <CardsDashboard zone="home-cards" id="home" min-card-width="16rem" />
18
+ *
19
+ * Edit mode ("Customise") shows a handle (arrows, Home/End, or drag with
20
+ * mouse, touch or pen), pin and hide on each card, and the hidden cards'
21
+ * tray with Reset. Outside it, only the cards show.
22
+ */
23
+ import { computed, inject, nextTick, onBeforeUnmount, ref, watch, h, defineComponent, type Component, type VNode } from 'vue'
24
+ import QdButton from '../base/QdButton.vue'
25
+ import { DASHBOARD_ZONES } from '../../zones/zones'
26
+ import { useAuth } from '../../composables/useAuth'
27
+ import { useI18n } from '../../i18n/useI18n'
28
+ import { useCardsArrangement, moveCard, type CardDef, type CardsArrangement } from '../../composables/useCardsArrangement'
29
+ import type { ZoneRegistry, BlockConfig } from '../../zones/ZoneRegistry'
30
+
31
+ const props = withDefaults(
32
+ defineProps<{
33
+ /** The zone whose blocks are the cards */
34
+ zone?: string
35
+ /** The dashboard's name in the storage key (default: the zone's) */
36
+ id?: string | null
37
+ /** The narrowest a card gets before the grid drops a column */
38
+ minCardWidth?: string
39
+ /** Show the "Customise" button */
40
+ editable?: boolean
41
+ /** How the edit mode's tray shows hidden cards by default: whole, or as chips; the user's toggle wins */
42
+ hiddenView?: 'cards' | 'compact'
43
+ }>(),
44
+ { zone: DASHBOARD_ZONES.WIDGETS, id: null, minCardWidth: '18rem', editable: true, hiddenView: 'cards' }
45
+ )
46
+
47
+ const registry = inject<ZoneRegistry | null>('qdadmZoneRegistry', null)
48
+ const version = registry?.getVersionRef?.()
49
+ const { user } = useAuth()
50
+ const { tOr } = useI18n()
51
+
52
+ const blocks = computed<BlockConfig[]>(() => {
53
+ if (version) void version.value
54
+ return registry?.getBlocks(props.zone) ?? []
55
+ })
56
+ const blockById = computed(() => new Map(blocks.value.filter((b) => b.id).map((b) => [b.id as string, b])))
57
+ // Any block with an id is a card: the same block serves a classic Zone and
58
+ // this dashboard. `card` only adds what arranging needs; without it the title
59
+ // comes from the block's `title` prop, else its id.
60
+ const cards = computed<CardDef[]>(() =>
61
+ blocks.value.filter((b) => b.id).map((b) => {
62
+ const fallback = typeof b.props?.title === 'string' ? (b.props.title as string) : (b.id as string)
63
+ return { id: b.id as string, card: { ...b.card, title: b.card?.title ?? fallback } }
64
+ })
65
+ )
66
+ // A block without an id has no key to save: shown after the cards, as declared
67
+ const plainBlocks = computed(() => blocks.value.filter((b) => !b.id))
68
+ if ((import.meta as { env?: { DEV?: boolean } }).env?.DEV && plainBlocks.value.length) {
69
+ console.warn(`[qdadm] CardsDashboard "${props.zone}": blocks without an id cannot be arranged`)
70
+ }
71
+
72
+ const userKey = computed(() => {
73
+ const u = user.value as { id?: unknown; username?: unknown } | null
74
+ return String(u?.id ?? u?.username ?? 'anonymous')
75
+ })
76
+ const storageKey = computed(() => `qdadm.dashboard.${props.id ?? props.zone}.${userKey.value}`)
77
+ const state = useCardsArrangement(storageKey, cards)
78
+
79
+ const editing = ref(false)
80
+
81
+ // The hidden tray's view (#4320): whole cards or chips, the user's choice kept beside the arrangement
82
+ const trayKey = computed(() => `${storageKey.value}.tray`)
83
+ function readTray(): 'cards' | 'compact' {
84
+ try {
85
+ const v = globalThis.localStorage?.getItem(trayKey.value)
86
+ return v === 'cards' || v === 'compact' ? v : props.hiddenView
87
+ } catch {
88
+ return props.hiddenView
89
+ }
90
+ }
91
+ const trayView = ref<'cards' | 'compact'>(readTray())
92
+ watch(trayKey, () => (trayView.value = readTray()))
93
+ function setTrayView(view: 'cards' | 'compact'): void {
94
+ trayView.value = view
95
+ try {
96
+ globalThis.localStorage?.setItem(trayKey.value, view)
97
+ } catch {
98
+ // No storage: the choice lasts the page
99
+ }
100
+ }
101
+ const announcement = ref('')
102
+ const root = ref<HTMLElement | null>(null)
103
+
104
+ /** The selector of a card's slot: ids are app strings, quoted safely */
105
+ const slotSelector = (id: string) => `[data-card-id="${id.replace(/["\\]/g, '\\$&')}"]`
106
+ const title = (c: CardDef) => tOr(c.card.title, c.card.title)
107
+ const span = (c: CardDef) => Math.max(1, Math.min(3, Math.round(c.card.span ?? 1)))
108
+ const isPinned = (c: CardDef) => state.arrangement.value.pinned.includes(c.id)
109
+ const visible = computed(() => [...state.groups.value.pinned, ...state.groups.value.rest])
110
+ const groupFor = (c: CardDef) => (isPinned(c) ? state.groups.value.pinned : state.groups.value.rest)
111
+
112
+ function announce(text: string): void {
113
+ // Same text twice must still be read: clear, then set
114
+ announcement.value = ''
115
+ void nextTick(() => (announcement.value = text))
116
+ }
117
+
118
+ function announcePosition(c: CardDef): void {
119
+ const group = groupFor(c)
120
+ announce(tOr('core.cardsDashboard.moved', '{title}: card {position} of {total}', {
121
+ title: title(c),
122
+ position: group.findIndex((g) => g.id === c.id) + 1,
123
+ total: group.length,
124
+ }))
125
+ }
126
+
127
+ async function focusHandle(id: string): Promise<void> {
128
+ await nextTick()
129
+ root.value?.querySelector<HTMLElement>(`${slotSelector(id)} .qd-cards-handle`)?.focus()
130
+ }
131
+
132
+ function onHandleKey(event: KeyboardEvent, c: CardDef): void {
133
+ const group = groupFor(c)
134
+ const from = group.findIndex((g) => g.id === c.id)
135
+ const to = { ArrowUp: from - 1, ArrowLeft: from - 1, ArrowDown: from + 1, ArrowRight: from + 1, Home: 0, End: group.length - 1 }[event.key]
136
+ if (to === undefined) return
137
+ event.preventDefault()
138
+ if (state.move(c.id, to)) {
139
+ announcePosition(c)
140
+ void focusHandle(c.id)
141
+ }
142
+ }
143
+
144
+ function togglePin(c: CardDef): void {
145
+ const pinned = !isPinned(c)
146
+ state.pin(c.id, pinned)
147
+ announce(pinned ? tOr('core.cardsDashboard.pinnedOne', '{title} pinned at the top', { title: title(c) }) : tOr('core.cardsDashboard.unpinnedOne', '{title} unpinned', { title: title(c) }))
148
+ void focusHandle(c.id)
149
+ }
150
+
151
+ function hide(c: CardDef): void {
152
+ state.hide(c.id, true)
153
+ announce(tOr('core.cardsDashboard.hiddenOne', '{title} hidden', { title: title(c) }))
154
+ }
155
+
156
+ function restore(c: CardDef): void {
157
+ state.hide(c.id, false)
158
+ announce(tOr('core.cardsDashboard.restoredOne', '{title} shown', { title: title(c) }))
159
+ void focusHandle(c.id)
160
+ }
161
+
162
+ function reset(): void {
163
+ state.reset()
164
+ announce(tOr('core.cardsDashboard.resetDone', 'Default arrangement restored'))
165
+ }
166
+
167
+ // ── Drag with pointer events: mouse, touch and pen, no dependency ─────────
168
+ // Followed on window, not with pointer capture: the preview moves the slot in
169
+ // the DOM, which drops a capture and would lose the pointerup.
170
+ const dragging = ref<string | null>(null)
171
+ let snapshot: CardsArrangement | null = null
172
+ let dragged: CardDef | null = null
173
+
174
+ function onPointerDown(event: PointerEvent, c: CardDef): void {
175
+ if (c.card.fixed || (event.pointerType === 'mouse' && event.button !== 0)) return
176
+ event.preventDefault()
177
+ // A plain copy: the arrangement's arrays are reactive proxies, which structuredClone refuses
178
+ const { order, hidden, pinned } = state.arrangement.value
179
+ snapshot = { v: 1, order: [...order], hidden: [...hidden], pinned: [...pinned] }
180
+ dragging.value = c.id
181
+ dragged = c
182
+ window.addEventListener('pointermove', onPointerMove)
183
+ window.addEventListener('pointerup', onPointerUp)
184
+ window.addEventListener('pointercancel', onPointerCancel)
185
+ window.addEventListener('keydown', onDragKey)
186
+ }
187
+
188
+ function stopDrag(): void {
189
+ window.removeEventListener('pointermove', onPointerMove)
190
+ window.removeEventListener('pointerup', onPointerUp)
191
+ window.removeEventListener('pointercancel', onPointerCancel)
192
+ window.removeEventListener('keydown', onDragKey)
193
+ dragging.value = null
194
+ dragged = null
195
+ snapshot = null
196
+ }
197
+
198
+ function onPointerMove(event: PointerEvent): void {
199
+ const c = dragged
200
+ if (!c) return
201
+ // The card of the same group under the pointer is the drop place
202
+ const group = groupFor(c)
203
+ for (let i = 0; i < group.length; i++) {
204
+ if (group[i]!.id === c.id || group[i]!.card.fixed) continue
205
+ const r = root.value?.querySelector<HTMLElement>(slotSelector(group[i]!.id))?.getBoundingClientRect()
206
+ if (r && event.clientX >= r.left && event.clientX <= r.right && event.clientY >= r.top && event.clientY <= r.bottom) {
207
+ state.preview(moveCard(state.arrangement.value, cards.value, c.id, i))
208
+ return
209
+ }
210
+ }
211
+ }
212
+
213
+ function onPointerUp(): void {
214
+ const c = dragged
215
+ if (!c) return
216
+ stopDrag()
217
+ state.commit()
218
+ announcePosition(c)
219
+ }
220
+
221
+ function cancelDrag(): void {
222
+ if (snapshot) state.preview(snapshot)
223
+ stopDrag()
224
+ announce(tOr('core.cardsDashboard.dragCancelled', 'Move cancelled'))
225
+ }
226
+
227
+ function onPointerCancel(): void {
228
+ if (dragged) cancelDrag()
229
+ }
230
+
231
+ function onDragKey(event: KeyboardEvent): void {
232
+ if (event.key === 'Escape' && dragged) cancelDrag()
233
+ }
234
+
235
+ onBeforeUnmount(stopDrag)
236
+
237
+ // A block with wrappers renders through them, as in Zone
238
+ function render(block: BlockConfig): Component {
239
+ if (!block.wrappers?.length) return block.component
240
+ return defineComponent({
241
+ name: 'WrappedCard',
242
+ render(): VNode {
243
+ let current: VNode = h(block.component, block.props ?? {})
244
+ for (const wrapper of [...block.wrappers!].reverse()) {
245
+ const inner = current
246
+ current = h(wrapper.component, wrapper.props || {}, { default: () => inner })
247
+ }
248
+ return current
249
+ },
250
+ })
251
+ }
252
+ </script>
253
+
254
+ <template>
255
+ <div ref="root" class="qd-cards-dashboard" :class="{ 'qd-cards-editing': editing }" :data-zone="zone">
256
+ <div v-if="editable && cards.length" class="qd-cards-toolbar">
257
+ <template v-if="editing">
258
+ <QdButton
259
+ type="button"
260
+ size="small"
261
+ text
262
+ icon="pi pi-undo"
263
+ :label="tOr('core.cardsDashboard.reset', 'Reset')"
264
+ @click="reset"
265
+ />
266
+ <QdButton type="button" size="small" icon="pi pi-check" :label="tOr('core.cardsDashboard.done', 'Done')" @click="editing = false" />
267
+ </template>
268
+ <QdButton
269
+ v-else
270
+ type="button"
271
+ size="small"
272
+ outlined
273
+ icon="pi pi-th-large"
274
+ :label="tOr('core.cardsDashboard.customise', 'Customise')"
275
+ @click="editing = true"
276
+ />
277
+ </div>
278
+
279
+ <div class="qd-cards-grid" :style="{ '--qd-card-min': minCardWidth }">
280
+ <div
281
+ v-for="c in visible"
282
+ :key="c.id"
283
+ class="qd-cards-slot"
284
+ :class="{ 'qd-cards-pinned': isPinned(c), 'qd-cards-dragging': dragging === c.id }"
285
+ :style="{ '--qd-card-span': span(c) }"
286
+ :data-card-id="c.id"
287
+ :data-zone-block="c.id"
288
+ >
289
+ <div v-if="editing" class="qd-cards-bar">
290
+ <button
291
+ v-if="!c.card.fixed"
292
+ type="button"
293
+ class="qd-cards-handle"
294
+ :aria-label="tOr('core.cardsDashboard.move', 'Move {title}', { title: title(c) })"
295
+ :aria-describedby="`qd-cards-help-${zone}`"
296
+ @keydown="onHandleKey($event, c)"
297
+ @pointerdown="onPointerDown($event, c)"
298
+ >
299
+ <i class="pi pi-arrows-alt" aria-hidden="true"></i>
300
+ </button>
301
+ <span class="qd-cards-title">{{ title(c) }}</span>
302
+ <button
303
+ v-if="!c.card.fixed"
304
+ type="button"
305
+ class="qd-cards-action"
306
+ :aria-pressed="isPinned(c)"
307
+ :aria-label="isPinned(c) ? tOr('core.cardsDashboard.unpin', 'Unpin {title}', { title: title(c) }) : tOr('core.cardsDashboard.pin', 'Pin {title} at the top', { title: title(c) })"
308
+ :title="isPinned(c) ? tOr('core.cardsDashboard.unpin', 'Unpin {title}', { title: title(c) }) : tOr('core.cardsDashboard.pin', 'Pin {title} at the top', { title: title(c) })"
309
+ @click="togglePin(c)"
310
+ >
311
+ <i :class="isPinned(c) ? 'pi pi-thumbtack qd-cards-on' : 'pi pi-thumbtack'" aria-hidden="true"></i>
312
+ </button>
313
+ <button
314
+ v-if="!c.card.required"
315
+ type="button"
316
+ class="qd-cards-action"
317
+ :aria-label="tOr('core.cardsDashboard.hide', 'Hide {title}', { title: title(c) })"
318
+ :title="tOr('core.cardsDashboard.hide', 'Hide {title}', { title: title(c) })"
319
+ @click="hide(c)"
320
+ >
321
+ <i class="pi pi-eye-slash" aria-hidden="true"></i>
322
+ </button>
323
+ </div>
324
+ <component :is="render(blockById.get(c.id)!)" v-bind="blockById.get(c.id)!.props ?? {}" />
325
+ </div>
326
+ <div v-for="(b, i) in plainBlocks" :key="`plain-${i}`" class="qd-cards-slot">
327
+ <component :is="render(b)" v-bind="b.props ?? {}" />
328
+ </div>
329
+ </div>
330
+
331
+ <div v-if="editing" class="qd-cards-tray" :class="`qd-cards-tray-${trayView}`">
332
+ <div class="qd-cards-tray-head">
333
+ <span class="qd-cards-tray-label">{{ tOr('core.cardsDashboard.hidden', 'Hidden cards') }}</span>
334
+ <span v-if="!state.groups.value.hidden.length" class="qd-cards-tray-empty">{{ tOr('core.cardsDashboard.noneHidden', 'None') }}</span>
335
+ <div class="qd-cards-tray-view" role="group" :aria-label="tOr('core.cardsDashboard.trayView', 'Show hidden cards as')">
336
+ <button
337
+ v-for="view in (['cards', 'compact'] as const)"
338
+ :key="view"
339
+ type="button"
340
+ class="qd-cards-tray-view-option"
341
+ :aria-pressed="trayView === view"
342
+ @click="setTrayView(view)"
343
+ >
344
+ {{ view === 'cards' ? tOr('core.cardsDashboard.viewCards', 'Cards') : tOr('core.cardsDashboard.viewCompact', 'Compact') }}
345
+ </button>
346
+ </div>
347
+ </div>
348
+ <!-- Whole cards: the same grid, dimmed and inert; only "Show" acts -->
349
+ <div v-if="trayView === 'cards' && state.groups.value.hidden.length" class="qd-cards-grid" :style="{ '--qd-card-min': minCardWidth }">
350
+ <div
351
+ v-for="c in state.groups.value.hidden"
352
+ :key="c.id"
353
+ class="qd-cards-slot qd-cards-hidden"
354
+ :style="{ '--qd-card-span': span(c) }"
355
+ :data-hidden-card-id="c.id"
356
+ >
357
+ <div class="qd-cards-bar">
358
+ <span class="qd-cards-title">{{ title(c) }}</span>
359
+ <QdButton
360
+ type="button"
361
+ size="small"
362
+ text
363
+ icon="pi pi-eye"
364
+ class="qd-cards-restore"
365
+ :label="tOr('core.cardsDashboard.show', 'Show')"
366
+ :aria-label="tOr('core.cardsDashboard.restore', 'Show {title}', { title: title(c) })"
367
+ @click="restore(c)"
368
+ />
369
+ </div>
370
+ <div class="qd-cards-hidden-body" inert>
371
+ <component :is="render(blockById.get(c.id)!)" v-bind="blockById.get(c.id)!.props ?? {}" />
372
+ </div>
373
+ </div>
374
+ </div>
375
+ <div v-else-if="trayView === 'compact'" class="qd-cards-chips">
376
+ <QdButton
377
+ v-for="c in state.groups.value.hidden"
378
+ :key="c.id"
379
+ type="button"
380
+ size="small"
381
+ outlined
382
+ rounded
383
+ icon="pi pi-eye"
384
+ class="qd-cards-restore"
385
+ :label="title(c)"
386
+ :aria-label="tOr('core.cardsDashboard.restore', 'Show {title}', { title: title(c) })"
387
+ @click="restore(c)"
388
+ />
389
+ </div>
390
+ </div>
391
+
392
+ <span :id="`qd-cards-help-${zone}`" class="qd-cards-sr">{{ tOr('core.cardsDashboard.help', 'Arrow keys move the card, Home and End to the start or the end') }}</span>
393
+ <span class="qd-cards-sr" role="status" aria-live="polite">{{ announcement }}</span>
394
+ </div>
395
+ </template>
@@ -22,6 +22,10 @@
22
22
  * <!-- Optional: Override specific zones via slots -->
23
23
  * </DashboardLayout>
24
24
  *
25
+ * customizable (#4320): the widgets zone's blocks become cards each user
26
+ * arranges (CardsDashboard):
27
+ * <DashboardLayout customizable />
28
+ *
25
29
  * Or register blocks via ZoneRegistry:
26
30
  * registry.registerBlock(DASHBOARD_ZONES.STATS, {
27
31
  * component: StatsWidget,
@@ -32,8 +36,14 @@
32
36
  import { useSlots } from 'vue'
33
37
  import BaseLayout from './BaseLayout.vue'
34
38
  import Zone from './Zone.vue'
39
+ import CardsDashboard from './CardsDashboard.vue'
35
40
  import { DASHBOARD_ZONES } from '../../zones/zones'
36
41
 
42
+ defineProps<{
43
+ /** The widgets zone as cards each user reorders, hides and pins (#4320) */
44
+ customizable?: boolean
45
+ }>()
46
+
37
47
  const slots = useSlots()
38
48
  </script>
39
49
 
@@ -54,7 +64,8 @@ const slots = useSlots()
54
64
  <slot name="widgets" />
55
65
  </section>
56
66
  <section v-else class="dashboard-widgets">
57
- <Zone :name="DASHBOARD_ZONES.WIDGETS" />
67
+ <CardsDashboard v-if="customizable" :zone="DASHBOARD_ZONES.WIDGETS" />
68
+ <Zone v-else :name="DASHBOARD_ZONES.WIDGETS" />
58
69
  </section>
59
70
 
60
71
  <!-- Recent activity zone: activity log, recent changes -->