@quazardous/qdadm 2.51.0 → 2.53.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.
- package/dist/node/cards/tools/cardsTool.d.ts +32 -0
- package/dist/node/cards/tools/cardsTool.js +151 -0
- package/dist/node/cards/tools/cli.d.ts +2 -0
- package/dist/node/cards/tools/cli.js +38 -0
- package/dist/node/cards/validate.d.ts +35 -0
- package/dist/node/cards/validate.js +94 -0
- package/dist/styles/qdadm.css +1 -1
- package/package.json +7 -2
- package/src/board/QdBoardBlock.vue +67 -0
- package/src/board/QdDomainBoard.vue +64 -0
- package/src/board/blocks/BreakdownBlock.vue +44 -0
- package/src/board/blocks/KpiBlock.vue +31 -0
- package/src/board/blocks/TimelineBlock.vue +63 -0
- package/src/board/blocks/TopBlock.vue +57 -0
- package/src/board/blocks/schemas.ts +107 -0
- package/src/board/index.ts +31 -0
- package/src/board/registry.ts +33 -0
- package/src/board/types.ts +32 -0
- package/src/cards/QdCard.vue +175 -0
- package/src/cards/QdCardView.vue +53 -0
- package/src/cards/QdCardsGallery.vue +103 -0
- package/src/cards/QdFavoritesCard.vue +50 -0
- package/src/cards/QdRecentCard.vue +44 -0
- package/src/cards/builtin/agenda/AgendaCard.vue +37 -0
- package/src/cards/builtin/agenda/meta.json +60 -0
- package/src/cards/builtin/agenda/schema.json +48 -0
- package/src/cards/builtin/bullet/BulletCard.vue +76 -0
- package/src/cards/builtin/bullet/meta.json +38 -0
- package/src/cards/builtin/bullet/schema.json +18 -0
- package/src/cards/builtin/cards-index.json +1694 -0
- package/src/cards/builtin/compare/CompareCard.vue +47 -0
- package/src/cards/builtin/compare/meta.json +79 -0
- package/src/cards/builtin/compare/schema.json +40 -0
- package/src/cards/builtin/favorites/FavoritesCard.vue +50 -0
- package/src/cards/builtin/favorites/meta.json +33 -0
- package/src/cards/builtin/favorites/schema.json +20 -0
- package/src/cards/builtin/feed/FeedCard.vue +39 -0
- package/src/cards/builtin/feed/meta.json +64 -0
- package/src/cards/builtin/feed/schema.json +54 -0
- package/src/cards/builtin/funnel/FunnelCard.vue +44 -0
- package/src/cards/builtin/funnel/meta.json +53 -0
- package/src/cards/builtin/funnel/schema.json +37 -0
- package/src/cards/builtin/goal/GoalCard.vue +73 -0
- package/src/cards/builtin/goal/meta.json +43 -0
- package/src/cards/builtin/goal/schema.json +12 -0
- package/src/cards/builtin/heat/HeatCard.vue +46 -0
- package/src/cards/builtin/heat/meta.json +101 -0
- package/src/cards/builtin/heat/schema.json +39 -0
- package/src/cards/builtin/index.ts +71 -0
- package/src/cards/builtin/metric/MetricCard.vue +82 -0
- package/src/cards/builtin/metric/meta.json +109 -0
- package/src/cards/builtin/metric/schema.json +35 -0
- package/src/cards/builtin/pills.ts +36 -0
- package/src/cards/builtin/queue/QueueCard.vue +65 -0
- package/src/cards/builtin/queue/meta.json +47 -0
- package/src/cards/builtin/queue/schema.json +32 -0
- package/src/cards/builtin/ranking/RankingCard.vue +37 -0
- package/src/cards/builtin/ranking/meta.json +71 -0
- package/src/cards/builtin/ranking/schema.json +35 -0
- package/src/cards/builtin/recent/RecentCard.vue +41 -0
- package/src/cards/builtin/recent/meta.json +32 -0
- package/src/cards/builtin/recent/schema.json +21 -0
- package/src/cards/builtin/shared.ts +83 -0
- package/src/cards/builtin/split/SplitCard.vue +52 -0
- package/src/cards/builtin/split/meta.json +72 -0
- package/src/cards/builtin/split/schema.json +40 -0
- package/src/cards/builtin/trend/TrendCard.vue +75 -0
- package/src/cards/builtin/trend/meta.json +81 -0
- package/src/cards/builtin/trend/schema.json +58 -0
- package/src/cards/index.ts +29 -0
- package/src/cards/registry.ts +57 -0
- package/src/cards/tools/cardsTool.ts +181 -0
- package/src/cards/tools/cli.ts +35 -0
- package/src/cards/types.ts +111 -0
- package/src/cards/validate.ts +111 -0
- package/src/components/edit/FormActions.vue +9 -5
- package/src/components/edit/FormPage.vue +17 -2
- package/src/components/layout/AppLayout.vue +4 -0
- package/src/components/layout/BaseLayout.vue +4 -0
- package/src/components/layout/CardParamsForm.vue +157 -0
- package/src/components/layout/CardsDashboard.vue +276 -57
- package/src/components/layout/PageHeader.vue +22 -1
- package/src/components/layout/QdFavoriteStar.vue +71 -0
- package/src/components/layout/Zone.vue +2 -1
- package/src/components/lists/ListPage.vue +9 -1
- package/src/components/lists/QdSaveSearch.vue +79 -0
- package/src/components/pages/NotFoundPage.vue +5 -2
- package/src/components/run/QdRunBar.vue +99 -0
- package/src/components/show/ShowPage.vue +10 -1
- package/src/composables/useBreadcrumb.ts +1 -1
- package/src/composables/useCardsArrangement.ts +297 -27
- package/src/composables/useEntityItemFormPage.ts +39 -3
- package/src/composables/useEntityItemFormPage.types.ts +8 -0
- package/src/composables/useEntityItemShowPage.ts +22 -0
- package/src/composables/useListPage.ts +71 -0
- package/src/composables/useListPage.types.ts +6 -0
- package/src/composables/useUnsavedChangesGuard.ts +17 -1
- package/src/domain/QdBadge.vue +36 -0
- package/src/domain/QdDomainBar.vue +213 -0
- package/src/domain/QdDomainBarZone.vue +19 -0
- package/src/domain/index.ts +6 -0
- package/src/domain/registry.ts +122 -0
- package/src/favorites/index.ts +7 -0
- package/src/favorites/store.ts +172 -0
- package/src/favorites/useFavorites.ts +217 -0
- package/src/i18n/defaults/core.en.generated.ts +132 -0
- package/src/i18n/defaults/core.en.yml +132 -0
- package/src/i18n/defaults/core.fr.generated.ts +132 -0
- package/src/i18n/defaults/core.fr.yml +132 -0
- package/src/index.ts +23 -0
- package/src/kernel/Kernel.routing.ts +4 -15
- package/src/kernel/Kernel.types.ts +5 -1
- package/src/kernel/Kernel.vue.ts +2 -2
- package/src/kernel/KernelContext.routing.ts +10 -1
- package/src/kernel/KernelContext.ts +7 -0
- package/src/kernel/KernelContext.types.ts +2 -0
- package/src/kernel/homeRoute.ts +45 -0
- package/src/module/moduleRegistry.ts +4 -0
- package/src/run/index.ts +6 -0
- package/src/run/run.ts +162 -0
- package/src/run/useRun.ts +207 -0
- package/src/styles/_cards-dashboard.scss +190 -0
- package/src/styles/_qd-board.scss +359 -0
- package/src/styles/_qd-cards.scss +1197 -0
- package/src/styles/_qd-domain-bar.scss +159 -0
- package/src/styles/_qd-run.scss +135 -0
- package/src/styles/index.scss +4 -0
- package/src/zones/ZoneRegistry.ts +16 -0
- package/src/zones/index.ts +1 -0
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
{
|
|
2
|
+
"type": "trend",
|
|
3
|
+
"title": "Trend",
|
|
4
|
+
"question": "Is this normal?",
|
|
5
|
+
"readings": [
|
|
6
|
+
"the curve: the values over time, the last one written",
|
|
7
|
+
"the band: where the values usually sit",
|
|
8
|
+
"the marked points: the ones outside the band, counted in words"
|
|
9
|
+
],
|
|
10
|
+
"strengths": [
|
|
11
|
+
"says at once whether today is unusual",
|
|
12
|
+
"the band carries the context a bare curve lacks"
|
|
13
|
+
],
|
|
14
|
+
"avoid": [
|
|
15
|
+
"without a notion of normal: use metric",
|
|
16
|
+
"for two moments only: use compare"
|
|
17
|
+
],
|
|
18
|
+
"sizes": [
|
|
19
|
+
"m",
|
|
20
|
+
"l"
|
|
21
|
+
],
|
|
22
|
+
"options": {
|
|
23
|
+
"unit": {
|
|
24
|
+
"type": "string",
|
|
25
|
+
"description": "Written after the last value"
|
|
26
|
+
},
|
|
27
|
+
"decimals": {
|
|
28
|
+
"type": "integer",
|
|
29
|
+
"minimum": 0,
|
|
30
|
+
"maximum": 4,
|
|
31
|
+
"default": 0,
|
|
32
|
+
"description": "Digits after the decimal point"
|
|
33
|
+
}
|
|
34
|
+
},
|
|
35
|
+
"action": "mode list: the points outside the normal",
|
|
36
|
+
"example": {
|
|
37
|
+
"envelope": {
|
|
38
|
+
"title": "Orders per hour",
|
|
39
|
+
"status": "watch",
|
|
40
|
+
"source": "shop",
|
|
41
|
+
"to": "/orders",
|
|
42
|
+
"size": "m"
|
|
43
|
+
},
|
|
44
|
+
"data": {
|
|
45
|
+
"label": "orders this hour",
|
|
46
|
+
"normal": {
|
|
47
|
+
"low": 20,
|
|
48
|
+
"high": 40
|
|
49
|
+
},
|
|
50
|
+
"series": [
|
|
51
|
+
{
|
|
52
|
+
"value": 28
|
|
53
|
+
},
|
|
54
|
+
{
|
|
55
|
+
"value": 31
|
|
56
|
+
},
|
|
57
|
+
{
|
|
58
|
+
"value": 26
|
|
59
|
+
},
|
|
60
|
+
{
|
|
61
|
+
"value": 35
|
|
62
|
+
},
|
|
63
|
+
{
|
|
64
|
+
"value": 44
|
|
65
|
+
},
|
|
66
|
+
{
|
|
67
|
+
"value": 38
|
|
68
|
+
},
|
|
69
|
+
{
|
|
70
|
+
"value": 17
|
|
71
|
+
},
|
|
72
|
+
{
|
|
73
|
+
"value": 29
|
|
74
|
+
}
|
|
75
|
+
]
|
|
76
|
+
},
|
|
77
|
+
"options": {
|
|
78
|
+
"decimals": 0
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
}
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
{
|
|
2
|
+
"type": "object",
|
|
3
|
+
"required": [
|
|
4
|
+
"series"
|
|
5
|
+
],
|
|
6
|
+
"additionalProperties": false,
|
|
7
|
+
"properties": {
|
|
8
|
+
"label": {
|
|
9
|
+
"type": "string",
|
|
10
|
+
"description": "What the last value is: \"orders this hour\""
|
|
11
|
+
},
|
|
12
|
+
"normal": {
|
|
13
|
+
"type": "object",
|
|
14
|
+
"required": [
|
|
15
|
+
"low",
|
|
16
|
+
"high"
|
|
17
|
+
],
|
|
18
|
+
"additionalProperties": false,
|
|
19
|
+
"properties": {
|
|
20
|
+
"low": {
|
|
21
|
+
"type": "number"
|
|
22
|
+
},
|
|
23
|
+
"high": {
|
|
24
|
+
"type": "number"
|
|
25
|
+
}
|
|
26
|
+
},
|
|
27
|
+
"description": "One band for the whole curve"
|
|
28
|
+
},
|
|
29
|
+
"series": {
|
|
30
|
+
"type": "array",
|
|
31
|
+
"items": {
|
|
32
|
+
"type": "object",
|
|
33
|
+
"required": [
|
|
34
|
+
"value"
|
|
35
|
+
],
|
|
36
|
+
"additionalProperties": false,
|
|
37
|
+
"properties": {
|
|
38
|
+
"value": {
|
|
39
|
+
"type": "number"
|
|
40
|
+
},
|
|
41
|
+
"at": {
|
|
42
|
+
"type": [
|
|
43
|
+
"string",
|
|
44
|
+
"number"
|
|
45
|
+
]
|
|
46
|
+
},
|
|
47
|
+
"low": {
|
|
48
|
+
"type": "number",
|
|
49
|
+
"description": "This point's own band"
|
|
50
|
+
},
|
|
51
|
+
"high": {
|
|
52
|
+
"type": "number"
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Cards (#5337, #5339): the envelope, the registration of a card type with
|
|
3
|
+
* its sheet and schema, the gallery, and qdadm's generic cards (metric,
|
|
4
|
+
* queue, goal, bullet), registered when qdadm loads.
|
|
5
|
+
*/
|
|
6
|
+
import { registerBuiltinCards } from './builtin'
|
|
7
|
+
|
|
8
|
+
export { default as QdCard } from './QdCard.vue'
|
|
9
|
+
export { default as QdCardView } from './QdCardView.vue'
|
|
10
|
+
export { default as QdCardsGallery } from './QdCardsGallery.vue'
|
|
11
|
+
export { default as QdFavoritesCard } from './QdFavoritesCard.vue'
|
|
12
|
+
export { default as QdRecentCard } from './QdRecentCard.vue'
|
|
13
|
+
export { registerCard, getCard, listCards, checkCardInput, resolveCardOptions, optionsSchema } from './registry'
|
|
14
|
+
export { validateCardData, type CardSchema, type SchemaProblem } from './validate'
|
|
15
|
+
export { BUILTIN_CARDS } from './builtin'
|
|
16
|
+
export type {
|
|
17
|
+
CardStatus,
|
|
18
|
+
CardSize,
|
|
19
|
+
CardState,
|
|
20
|
+
CardAction,
|
|
21
|
+
CardEnvelope,
|
|
22
|
+
CardMeta,
|
|
23
|
+
CardOptionSheet,
|
|
24
|
+
CardDefinition,
|
|
25
|
+
CardBodyProps,
|
|
26
|
+
CardPill,
|
|
27
|
+
} from './types'
|
|
28
|
+
|
|
29
|
+
registerBuiltinCards()
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The card types known to the app (#5339). qdadm registers its generic cards
|
|
3
|
+
* (metric, queue, goal, bullet) when '@quazardous/qdadm' loads; an app adds
|
|
4
|
+
* its own with registerCard().
|
|
5
|
+
*/
|
|
6
|
+
import { markRaw } from 'vue'
|
|
7
|
+
import type { CardDefinition, CardMeta } from './types'
|
|
8
|
+
import { validateCardData, type CardSchema, type SchemaProblem } from './validate'
|
|
9
|
+
|
|
10
|
+
const cards = new Map<string, CardDefinition>()
|
|
11
|
+
|
|
12
|
+
/** Register a card type: its body, its sheet and the schema of its data */
|
|
13
|
+
export function registerCard(definition: CardDefinition): void {
|
|
14
|
+
const { type, meta } = definition
|
|
15
|
+
if (!type) throw new Error('[qdadm] registerCard: a card needs a type')
|
|
16
|
+
if (meta?.type && meta.type !== type) {
|
|
17
|
+
console.warn(`[qdadm] registerCard('${type}'): its sheet says type '${meta.type}'`)
|
|
18
|
+
}
|
|
19
|
+
if (cards.has(type)) console.warn(`[qdadm] registerCard('${type}'): replaces the card already registered`)
|
|
20
|
+
cards.set(type, { ...definition, component: markRaw(definition.component) })
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
export function getCard(type: string): CardDefinition | null {
|
|
24
|
+
return cards.get(type) ?? null
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** Every registered type, in registration order */
|
|
28
|
+
export function listCards(): CardDefinition[] {
|
|
29
|
+
return [...cards.values()]
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** The schema of a type's options, from its sheet */
|
|
33
|
+
export function optionsSchema(meta: CardMeta): CardSchema {
|
|
34
|
+
return { type: 'object', properties: meta.options }
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** The problems of a card's data and options; empty when both fit */
|
|
38
|
+
export function checkCardInput(definition: CardDefinition, data: unknown, options: Record<string, unknown> = {}): SchemaProblem[] {
|
|
39
|
+
return [
|
|
40
|
+
...validateCardData(data, definition.schema, 'data'),
|
|
41
|
+
...validateCardData(options, optionsSchema(definition.meta), 'options'),
|
|
42
|
+
]
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** The options with the sheet's defaults filled in */
|
|
46
|
+
export function resolveCardOptions(meta: CardMeta, options: Record<string, unknown> = {}): Record<string, unknown> {
|
|
47
|
+
const out: Record<string, unknown> = {}
|
|
48
|
+
for (const [name, sheet] of Object.entries(meta.options)) {
|
|
49
|
+
if (sheet.default !== undefined) out[name] = sheet.default
|
|
50
|
+
}
|
|
51
|
+
return { ...out, ...options }
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** Tests only: forget the app's cards (qdadm's own stay) */
|
|
55
|
+
export function resetCards(keep: string[] = []): void {
|
|
56
|
+
for (const type of [...cards.keys()]) if (!keep.includes(type)) cards.delete(type)
|
|
57
|
+
}
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The cards' tooling (#5339), for qdadm's cards and an app's own: read the
|
|
3
|
+
* card folders, write the index and the bestiary, and check them.
|
|
4
|
+
*
|
|
5
|
+
* A card is a folder: `meta.json` (its sheet), `schema.json` (the JSON
|
|
6
|
+
* Schema of its data) and its body (a .vue file).
|
|
7
|
+
*
|
|
8
|
+
* import { writeCardsIndex, checkCards } from '@quazardous/qdadm/cards/tools'
|
|
9
|
+
* writeCardsIndex('src/cards', { index: 'src/cards/cards-index.json', bestiary: 'docs/cards.md' })
|
|
10
|
+
* expect(checkCards('src/cards', { index: …, bestiary: … })).toEqual([])
|
|
11
|
+
*
|
|
12
|
+
* Node only: it reads and writes files.
|
|
13
|
+
*/
|
|
14
|
+
import fs from 'node:fs'
|
|
15
|
+
import path from 'node:path'
|
|
16
|
+
import { validateCardData, type CardSchema } from '../validate.js'
|
|
17
|
+
|
|
18
|
+
export interface CardFolder {
|
|
19
|
+
/** The folder's name, which is the card's type */
|
|
20
|
+
type: string
|
|
21
|
+
dir: string
|
|
22
|
+
meta: Record<string, unknown> | null
|
|
23
|
+
schema: CardSchema | null
|
|
24
|
+
/** The body's file name, or null */
|
|
25
|
+
component: string | null
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export interface CardsOutputs {
|
|
29
|
+
/** Where the index (JSON) is written */
|
|
30
|
+
index?: string
|
|
31
|
+
/** Where the bestiary (Markdown) is written */
|
|
32
|
+
bestiary?: string
|
|
33
|
+
/** The bestiary's first heading (default "Cards") */
|
|
34
|
+
title?: string
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
const SHEET_FIELDS = ['type', 'title', 'question', 'readings', 'strengths', 'avoid', 'sizes', 'options', 'action', 'example'] as const
|
|
38
|
+
|
|
39
|
+
function readJson(file: string): Record<string, unknown> | null {
|
|
40
|
+
if (!fs.existsSync(file)) return null
|
|
41
|
+
return JSON.parse(fs.readFileSync(file, 'utf8')) as Record<string, unknown>
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** The card folders under `dir`, sorted by type */
|
|
45
|
+
export function readCards(dir: string): CardFolder[] {
|
|
46
|
+
return fs
|
|
47
|
+
.readdirSync(dir, { withFileTypes: true })
|
|
48
|
+
.filter((e) => e.isDirectory())
|
|
49
|
+
.map((e) => {
|
|
50
|
+
const folder = path.join(dir, e.name)
|
|
51
|
+
const files = fs.readdirSync(folder)
|
|
52
|
+
return {
|
|
53
|
+
type: e.name,
|
|
54
|
+
dir: folder,
|
|
55
|
+
meta: readJson(path.join(folder, 'meta.json')),
|
|
56
|
+
schema: readJson(path.join(folder, 'schema.json')) as CardSchema | null,
|
|
57
|
+
component: files.find((f) => f.endsWith('.vue')) ?? null,
|
|
58
|
+
}
|
|
59
|
+
})
|
|
60
|
+
.filter((c) => c.meta || c.schema || c.component)
|
|
61
|
+
.sort((a, b) => a.type.localeCompare(b.type))
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** The index: every card's sheet and schema, for agents and tools */
|
|
65
|
+
export function buildIndex(cards: CardFolder[]): string {
|
|
66
|
+
const index = {
|
|
67
|
+
generatedBy: 'qdadm-cards index',
|
|
68
|
+
cards: cards.filter((c) => c.meta).map((c) => ({ ...c.meta, schema: c.schema })),
|
|
69
|
+
}
|
|
70
|
+
return JSON.stringify(index, null, 2) + '\n'
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
const list = (items: unknown) => (Array.isArray(items) ? items.map((i) => `- ${String(i)}`).join('\n') : '')
|
|
74
|
+
|
|
75
|
+
/** The bestiary: the same sheets, written for a reader choosing a card */
|
|
76
|
+
export function renderBestiary(cards: CardFolder[], title = 'Cards'): string {
|
|
77
|
+
const out: string[] = [
|
|
78
|
+
'<!-- Generated by `qdadm-cards index` from each card\'s meta.json and schema.json: do not edit by hand. -->',
|
|
79
|
+
'',
|
|
80
|
+
`# ${title}`,
|
|
81
|
+
'',
|
|
82
|
+
'Each card answers one question. Pick the card by its question, then give it data of the shape its schema says: the card draws it, the envelope is the same for all.',
|
|
83
|
+
'',
|
|
84
|
+
'## The envelope',
|
|
85
|
+
'',
|
|
86
|
+
'| Field | What it says |',
|
|
87
|
+
'|---|---|',
|
|
88
|
+
'| `title` | What the card counts |',
|
|
89
|
+
'| `status` | `critical`, `watch`, `good` or `info`: a side bar, a hue and a word |',
|
|
90
|
+
'| `source`, `freshness` | Where the data comes from, and when it was read |',
|
|
91
|
+
'| `to` | The surface: the whole card opens the domain\'s board |',
|
|
92
|
+
'| `action` | `{ verb, count, mode, to \\| run \\| onClick }`: the one gesture. `mode: next` opens the most urgent item, `list` the filtered list; `run` walks the items behind the card with the run bar |',
|
|
93
|
+
'| `state` | `ready`, or `loading`, `unreachable` (with `error`), `empty` (with `emptyText`): drawn instead of the body |',
|
|
94
|
+
'| `size` | `s`, `m` or `l`: 1, 2 or 3 columns, among the card\'s sizes |',
|
|
95
|
+
'',
|
|
96
|
+
'Data that does not fit the schema draws the `invalid` state with the path and the reason; the rest of the board keeps working.',
|
|
97
|
+
'',
|
|
98
|
+
]
|
|
99
|
+
for (const c of cards) {
|
|
100
|
+
const m = c.meta
|
|
101
|
+
if (!m) continue
|
|
102
|
+
const options = (m.options ?? {}) as Record<string, Record<string, unknown>>
|
|
103
|
+
const example = m.example as Record<string, unknown> | undefined
|
|
104
|
+
const required = (c.schema?.required ?? []).map((r) => `\`${r}\``).join(', ')
|
|
105
|
+
out.push(
|
|
106
|
+
`## \`${c.type}\`: ${String(m.question)}`,
|
|
107
|
+
'',
|
|
108
|
+
`**Readings**`,
|
|
109
|
+
'',
|
|
110
|
+
list(m.readings),
|
|
111
|
+
'',
|
|
112
|
+
`**Strengths**`,
|
|
113
|
+
'',
|
|
114
|
+
list(m.strengths),
|
|
115
|
+
'',
|
|
116
|
+
`**Avoid it**`,
|
|
117
|
+
'',
|
|
118
|
+
list(m.avoid),
|
|
119
|
+
'',
|
|
120
|
+
`**Sizes**: ${(m.sizes as string[] | undefined)?.join(', ') ?? 's'}. **Main action**: ${String(m.action)}`,
|
|
121
|
+
''
|
|
122
|
+
)
|
|
123
|
+
if (Object.keys(options).length) {
|
|
124
|
+
out.push('| Option | Type | Default | What it does |', '|---|---|---|---|')
|
|
125
|
+
for (const [name, o] of Object.entries(options)) {
|
|
126
|
+
const type = Array.isArray(o.enum) ? (o.enum as unknown[]).map((v) => `\`${String(v)}\``).join(' \\| ') : String(o.type ?? '')
|
|
127
|
+
out.push(`| \`${name}\` | ${type} | ${o.default === undefined ? '' : `\`${JSON.stringify(o.default)}\``} | ${String(o.description ?? '')} |`)
|
|
128
|
+
}
|
|
129
|
+
out.push('')
|
|
130
|
+
}
|
|
131
|
+
out.push(`**Data**: required ${required || 'nothing'}; the full shape is in \`${c.type}/schema.json\`.`, '')
|
|
132
|
+
if (example) {
|
|
133
|
+
out.push('**Example**', '', '```json', JSON.stringify({ type: c.type, data: example.data, options: example.options ?? {} }, null, 2), '```', '')
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
return out.join('\n').replace(/\n{3,}/g, '\n\n')
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/** Write the index and the bestiary from the card folders */
|
|
140
|
+
export function writeCardsIndex(dir: string, outputs: CardsOutputs): void {
|
|
141
|
+
const cards = readCards(dir)
|
|
142
|
+
if (outputs.index) fs.writeFileSync(outputs.index, buildIndex(cards))
|
|
143
|
+
if (outputs.bestiary) fs.writeFileSync(outputs.bestiary, renderBestiary(cards, outputs.title))
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/**
|
|
147
|
+
* What is wrong with the card folders, as sentences; empty when all is well.
|
|
148
|
+
* A card without a sheet or a schema, a sheet missing a field, an example
|
|
149
|
+
* that fails its own schema, an index or a bestiary out of date.
|
|
150
|
+
*/
|
|
151
|
+
export function checkCards(dir: string, outputs: CardsOutputs = {}): string[] {
|
|
152
|
+
const problems: string[] = []
|
|
153
|
+
const cards = readCards(dir)
|
|
154
|
+
for (const c of cards) {
|
|
155
|
+
if (!c.meta) {
|
|
156
|
+
problems.push(`${c.type}: no meta.json (the card's sheet)`)
|
|
157
|
+
continue
|
|
158
|
+
}
|
|
159
|
+
if (!c.schema) problems.push(`${c.type}: no schema.json`)
|
|
160
|
+
if (!c.component) problems.push(`${c.type}: no .vue body`)
|
|
161
|
+
for (const field of SHEET_FIELDS) {
|
|
162
|
+
if (c.meta[field] === undefined) problems.push(`${c.type}: the sheet has no "${field}"`)
|
|
163
|
+
}
|
|
164
|
+
if (c.meta.type !== undefined && c.meta.type !== c.type) problems.push(`${c.type}: the sheet says type "${String(c.meta.type)}"`)
|
|
165
|
+
const example = c.meta.example as { data?: unknown; options?: Record<string, unknown> } | undefined
|
|
166
|
+
if (example && c.schema) {
|
|
167
|
+
for (const p of validateCardData(example.data, c.schema, 'example.data')) problems.push(`${c.type}: ${p.path} ${p.message}`)
|
|
168
|
+
}
|
|
169
|
+
if (example?.options) {
|
|
170
|
+
const optionsSchema: CardSchema = { type: 'object', properties: (c.meta.options ?? {}) as Record<string, CardSchema>, additionalProperties: false }
|
|
171
|
+
for (const p of validateCardData(example.options, optionsSchema, 'example.options')) problems.push(`${c.type}: ${p.path} ${p.message}`)
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
const stale = (file: string, expected: string, what: string) => {
|
|
175
|
+
if (!fs.existsSync(file)) problems.push(`${what} ${file} is missing: run qdadm-cards index`)
|
|
176
|
+
else if (fs.readFileSync(file, 'utf8') !== expected) problems.push(`${what} ${file} is out of date: run qdadm-cards index`)
|
|
177
|
+
}
|
|
178
|
+
if (outputs.index) stale(outputs.index, buildIndex(cards), 'the index')
|
|
179
|
+
if (outputs.bestiary) stale(outputs.bestiary, renderBestiary(cards, outputs.title), 'the bestiary')
|
|
180
|
+
return problems
|
|
181
|
+
}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* qdadm-cards (#5339): the index and the bestiary of a folder of cards.
|
|
4
|
+
*
|
|
5
|
+
* qdadm-cards index <dir> [--index <file>] [--bestiary <file>] [--title <text>]
|
|
6
|
+
* qdadm-cards check <dir> [--index <file>] [--bestiary <file>] [--title <text>]
|
|
7
|
+
*
|
|
8
|
+
* `check` exits 1 and lists what is wrong: a card without a sheet or a
|
|
9
|
+
* schema, an example that fails its schema, an index or a bestiary out of date.
|
|
10
|
+
*/
|
|
11
|
+
import { writeCardsIndex, checkCards, type CardsOutputs } from './cardsTool.js'
|
|
12
|
+
|
|
13
|
+
const [command, dir, ...rest] = process.argv.slice(2)
|
|
14
|
+
const outputs: CardsOutputs = {}
|
|
15
|
+
for (let i = 0; i < rest.length; i += 2) {
|
|
16
|
+
const value = rest[i + 1]
|
|
17
|
+
if (rest[i] === '--index') outputs.index = value
|
|
18
|
+
else if (rest[i] === '--bestiary') outputs.bestiary = value
|
|
19
|
+
else if (rest[i] === '--title') outputs.title = value
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
if (!dir || (command !== 'index' && command !== 'check')) {
|
|
23
|
+
console.error('usage: qdadm-cards index|check <dir> [--index <file>] [--bestiary <file>] [--title <text>]')
|
|
24
|
+
process.exit(2)
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
if (command === 'index') {
|
|
28
|
+
writeCardsIndex(dir, outputs)
|
|
29
|
+
console.log(`qdadm-cards: wrote ${[outputs.index, outputs.bestiary].filter(Boolean).join(' and ') || 'nothing (no --index nor --bestiary)'}`)
|
|
30
|
+
} else {
|
|
31
|
+
const problems = checkCards(dir, outputs)
|
|
32
|
+
for (const p of problems) console.error(`✗ ${p}`)
|
|
33
|
+
if (problems.length) process.exit(1)
|
|
34
|
+
console.log('qdadm-cards: all cards check out')
|
|
35
|
+
}
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The card contract (#5339): what qdadm draws (the envelope), what a card
|
|
3
|
+
* type draws (the body), and the sheet each type ships so a person or an
|
|
4
|
+
* agent can choose it without a screen.
|
|
5
|
+
*/
|
|
6
|
+
import type { Component } from 'vue'
|
|
7
|
+
import type { RouteLocationRaw } from 'vue-router'
|
|
8
|
+
import type { RunInit } from '../run/run'
|
|
9
|
+
import type { CardSchema } from './validate'
|
|
10
|
+
|
|
11
|
+
/** How things stand: a hue, a side bar and a word, never the hue alone */
|
|
12
|
+
export type CardStatus = 'critical' | 'watch' | 'good' | 'info'
|
|
13
|
+
|
|
14
|
+
/** 1, 2 or 3 columns of the grid */
|
|
15
|
+
export type CardSize = 's' | 'm' | 'l'
|
|
16
|
+
|
|
17
|
+
/** What the envelope draws instead of the body, or `ready` */
|
|
18
|
+
export type CardState = 'ready' | 'loading' | 'unreachable' | 'empty' | 'invalid'
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* The main action: a verb with its count, one gesture.
|
|
22
|
+
* `mode: 'next'` opens the most urgent item, `'list'` the filtered list.
|
|
23
|
+
*/
|
|
24
|
+
export interface CardAction {
|
|
25
|
+
/** The button's words, e.g. "Traiter la 1re" */
|
|
26
|
+
verb: string
|
|
27
|
+
count?: number
|
|
28
|
+
mode?: 'next' | 'list'
|
|
29
|
+
to?: RouteLocationRaw
|
|
30
|
+
/** `mode: 'next'`: the items behind the card, walked one after the other with the run bar (#5343) */
|
|
31
|
+
run?: RunInit
|
|
32
|
+
/** A gesture of the app's own, instead of a route or a run */
|
|
33
|
+
onClick?: () => void | Promise<void>
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** What the envelope shows around the body */
|
|
37
|
+
export interface CardEnvelope {
|
|
38
|
+
title: string
|
|
39
|
+
status?: CardStatus
|
|
40
|
+
/** Where the data comes from ("boutique") */
|
|
41
|
+
source?: string
|
|
42
|
+
/** When it was read: a Date, an ISO string or a timestamp */
|
|
43
|
+
freshness?: string | number | Date
|
|
44
|
+
/** The surface: opens the domain's board */
|
|
45
|
+
to?: RouteLocationRaw
|
|
46
|
+
action?: CardAction
|
|
47
|
+
state?: CardState
|
|
48
|
+
size?: CardSize
|
|
49
|
+
/** `unreachable`: why */
|
|
50
|
+
error?: string
|
|
51
|
+
/** `empty`: what to say instead of "Nothing to report" */
|
|
52
|
+
emptyText?: string
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** One declared option of a card type */
|
|
56
|
+
export interface CardOptionSheet extends CardSchema {
|
|
57
|
+
description: string
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** A card type's sheet: read by the gallery, the index and the bestiary */
|
|
61
|
+
export interface CardMeta {
|
|
62
|
+
type: string
|
|
63
|
+
/** A short name, "Metric" */
|
|
64
|
+
title: string
|
|
65
|
+
/** The question it answers */
|
|
66
|
+
question: string
|
|
67
|
+
/** What each visual channel says */
|
|
68
|
+
readings: string[]
|
|
69
|
+
strengths: string[]
|
|
70
|
+
/** When to choose another card */
|
|
71
|
+
avoid: string[]
|
|
72
|
+
sizes: CardSize[]
|
|
73
|
+
options: Record<string, CardOptionSheet>
|
|
74
|
+
/** The typical main action */
|
|
75
|
+
action: string
|
|
76
|
+
/** A complete example: envelope, data and options */
|
|
77
|
+
example: {
|
|
78
|
+
envelope: CardEnvelope
|
|
79
|
+
data: unknown
|
|
80
|
+
options?: Record<string, unknown>
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* A card reduced to a pill (#5389): what the domain bar shows of it. `count`
|
|
86
|
+
* is the badge's number, `null` when the card counts nothing.
|
|
87
|
+
*/
|
|
88
|
+
export interface CardPill {
|
|
89
|
+
/** The value as written: "14", "68 / 100" */
|
|
90
|
+
value: string
|
|
91
|
+
count: number | null
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** A card type, as registerCard takes it */
|
|
95
|
+
export interface CardDefinition {
|
|
96
|
+
type: string
|
|
97
|
+
/** The body: props `data`, `options`, `size` */
|
|
98
|
+
component: Component
|
|
99
|
+
meta: CardMeta
|
|
100
|
+
/** The JSON Schema of `data` */
|
|
101
|
+
schema: CardSchema
|
|
102
|
+
/** Its pill form, for the domain bar (#5389); without it, the type is not offered there */
|
|
103
|
+
pill?: (data: unknown, options: Record<string, unknown>, locale: string) => CardPill
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/** What a body receives */
|
|
107
|
+
export interface CardBodyProps<D = unknown, O = Record<string, unknown>> {
|
|
108
|
+
data: D
|
|
109
|
+
options: O
|
|
110
|
+
size: CardSize
|
|
111
|
+
}
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A card's data against its JSON Schema (#5339): the subset cards need, with
|
|
3
|
+
* no dependency, so the browser and the node tooling share it.
|
|
4
|
+
*
|
|
5
|
+
* Supported: type (one or a list), enum, const, required, properties,
|
|
6
|
+
* additionalProperties (false or a schema), items, minItems, maxItems,
|
|
7
|
+
* minimum, maximum, minLength, maxLength, anyOf. Other keywords are ignored.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
export interface CardSchema {
|
|
11
|
+
type?: string | string[]
|
|
12
|
+
enum?: unknown[]
|
|
13
|
+
const?: unknown
|
|
14
|
+
required?: string[]
|
|
15
|
+
properties?: Record<string, CardSchema>
|
|
16
|
+
additionalProperties?: boolean | CardSchema
|
|
17
|
+
items?: CardSchema
|
|
18
|
+
minItems?: number
|
|
19
|
+
maxItems?: number
|
|
20
|
+
minimum?: number
|
|
21
|
+
maximum?: number
|
|
22
|
+
minLength?: number
|
|
23
|
+
maxLength?: number
|
|
24
|
+
anyOf?: CardSchema[]
|
|
25
|
+
title?: string
|
|
26
|
+
description?: string
|
|
27
|
+
default?: unknown
|
|
28
|
+
[key: string]: unknown
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export interface SchemaProblem {
|
|
32
|
+
/** Where, as `data.items[0].age` */
|
|
33
|
+
path: string
|
|
34
|
+
message: string
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
function typeOf(value: unknown): string {
|
|
38
|
+
if (value === null) return 'null'
|
|
39
|
+
if (Array.isArray(value)) return 'array'
|
|
40
|
+
if (typeof value === 'number') return Number.isInteger(value) ? 'integer' : 'number'
|
|
41
|
+
return typeof value
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
function matchesType(value: unknown, type: string): boolean {
|
|
45
|
+
const actual = typeOf(value)
|
|
46
|
+
if (type === 'number') return actual === 'number' || actual === 'integer'
|
|
47
|
+
return actual === type
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** The problems of `value` against `schema`; empty when it fits */
|
|
51
|
+
export function validateCardData(value: unknown, schema: CardSchema, path = 'data'): SchemaProblem[] {
|
|
52
|
+
const problems: SchemaProblem[] = []
|
|
53
|
+
check(value, schema, path, problems)
|
|
54
|
+
return problems
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
function check(value: unknown, schema: CardSchema, path: string, out: SchemaProblem[]): void {
|
|
58
|
+
if (!schema || typeof schema !== 'object') return
|
|
59
|
+
|
|
60
|
+
if (schema.anyOf) {
|
|
61
|
+
const fits = schema.anyOf.some((s) => validateCardData(value, s, path).length === 0)
|
|
62
|
+
if (!fits) out.push({ path, message: 'matches none of the allowed shapes' })
|
|
63
|
+
return
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
if (schema.type !== undefined) {
|
|
67
|
+
const types = Array.isArray(schema.type) ? schema.type : [schema.type]
|
|
68
|
+
if (!types.some((t) => matchesType(value, t))) {
|
|
69
|
+
out.push({ path, message: `expected ${types.join(' or ')}, got ${typeOf(value)}` })
|
|
70
|
+
return
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
if ('const' in schema && value !== schema.const) out.push({ path, message: `must be ${JSON.stringify(schema.const)}` })
|
|
74
|
+
if (schema.enum && !schema.enum.some((e) => e === value)) {
|
|
75
|
+
out.push({ path, message: `must be one of ${schema.enum.map((e) => JSON.stringify(e)).join(', ')}` })
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
if (typeof value === 'number') {
|
|
79
|
+
if (schema.minimum !== undefined && value < schema.minimum) out.push({ path, message: `must be ≥ ${schema.minimum}` })
|
|
80
|
+
if (schema.maximum !== undefined && value > schema.maximum) out.push({ path, message: `must be ≤ ${schema.maximum}` })
|
|
81
|
+
}
|
|
82
|
+
if (typeof value === 'string') {
|
|
83
|
+
if (schema.minLength !== undefined && value.length < schema.minLength) out.push({ path, message: `must have at least ${schema.minLength} characters` })
|
|
84
|
+
if (schema.maxLength !== undefined && value.length > schema.maxLength) out.push({ path, message: `must have at most ${schema.maxLength} characters` })
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
if (Array.isArray(value)) {
|
|
88
|
+
if (schema.minItems !== undefined && value.length < schema.minItems) out.push({ path, message: `must have at least ${schema.minItems} items` })
|
|
89
|
+
if (schema.maxItems !== undefined && value.length > schema.maxItems) out.push({ path, message: `must have at most ${schema.maxItems} items` })
|
|
90
|
+
if (schema.items) value.forEach((item, i) => check(item, schema.items!, `${path}[${i}]`, out))
|
|
91
|
+
return
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
if (value && typeof value === 'object') {
|
|
95
|
+
const record = value as Record<string, unknown>
|
|
96
|
+
for (const key of schema.required ?? []) {
|
|
97
|
+
if (record[key] === undefined) out.push({ path: `${path}.${key}`, message: 'is required' })
|
|
98
|
+
}
|
|
99
|
+
const props = schema.properties ?? {}
|
|
100
|
+
for (const [key, sub] of Object.entries(props)) {
|
|
101
|
+
if (record[key] !== undefined) check(record[key], sub, `${path}.${key}`, out)
|
|
102
|
+
}
|
|
103
|
+
if (schema.additionalProperties !== undefined && schema.additionalProperties !== true) {
|
|
104
|
+
for (const key of Object.keys(record)) {
|
|
105
|
+
if (key in props) continue
|
|
106
|
+
if (schema.additionalProperties === false) out.push({ path: `${path}.${key}`, message: 'is not allowed' })
|
|
107
|
+
else check(record[key], schema.additionalProperties, `${path}.${key}`, out)
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
}
|