@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.
Files changed (129) hide show
  1. package/dist/node/cards/tools/cardsTool.d.ts +32 -0
  2. package/dist/node/cards/tools/cardsTool.js +151 -0
  3. package/dist/node/cards/tools/cli.d.ts +2 -0
  4. package/dist/node/cards/tools/cli.js +38 -0
  5. package/dist/node/cards/validate.d.ts +35 -0
  6. package/dist/node/cards/validate.js +94 -0
  7. package/dist/styles/qdadm.css +1 -1
  8. package/package.json +7 -2
  9. package/src/board/QdBoardBlock.vue +67 -0
  10. package/src/board/QdDomainBoard.vue +64 -0
  11. package/src/board/blocks/BreakdownBlock.vue +44 -0
  12. package/src/board/blocks/KpiBlock.vue +31 -0
  13. package/src/board/blocks/TimelineBlock.vue +63 -0
  14. package/src/board/blocks/TopBlock.vue +57 -0
  15. package/src/board/blocks/schemas.ts +107 -0
  16. package/src/board/index.ts +31 -0
  17. package/src/board/registry.ts +33 -0
  18. package/src/board/types.ts +32 -0
  19. package/src/cards/QdCard.vue +175 -0
  20. package/src/cards/QdCardView.vue +53 -0
  21. package/src/cards/QdCardsGallery.vue +103 -0
  22. package/src/cards/QdFavoritesCard.vue +50 -0
  23. package/src/cards/QdRecentCard.vue +44 -0
  24. package/src/cards/builtin/agenda/AgendaCard.vue +37 -0
  25. package/src/cards/builtin/agenda/meta.json +60 -0
  26. package/src/cards/builtin/agenda/schema.json +48 -0
  27. package/src/cards/builtin/bullet/BulletCard.vue +76 -0
  28. package/src/cards/builtin/bullet/meta.json +38 -0
  29. package/src/cards/builtin/bullet/schema.json +18 -0
  30. package/src/cards/builtin/cards-index.json +1694 -0
  31. package/src/cards/builtin/compare/CompareCard.vue +47 -0
  32. package/src/cards/builtin/compare/meta.json +79 -0
  33. package/src/cards/builtin/compare/schema.json +40 -0
  34. package/src/cards/builtin/favorites/FavoritesCard.vue +50 -0
  35. package/src/cards/builtin/favorites/meta.json +33 -0
  36. package/src/cards/builtin/favorites/schema.json +20 -0
  37. package/src/cards/builtin/feed/FeedCard.vue +39 -0
  38. package/src/cards/builtin/feed/meta.json +64 -0
  39. package/src/cards/builtin/feed/schema.json +54 -0
  40. package/src/cards/builtin/funnel/FunnelCard.vue +44 -0
  41. package/src/cards/builtin/funnel/meta.json +53 -0
  42. package/src/cards/builtin/funnel/schema.json +37 -0
  43. package/src/cards/builtin/goal/GoalCard.vue +73 -0
  44. package/src/cards/builtin/goal/meta.json +43 -0
  45. package/src/cards/builtin/goal/schema.json +12 -0
  46. package/src/cards/builtin/heat/HeatCard.vue +46 -0
  47. package/src/cards/builtin/heat/meta.json +101 -0
  48. package/src/cards/builtin/heat/schema.json +39 -0
  49. package/src/cards/builtin/index.ts +71 -0
  50. package/src/cards/builtin/metric/MetricCard.vue +82 -0
  51. package/src/cards/builtin/metric/meta.json +109 -0
  52. package/src/cards/builtin/metric/schema.json +35 -0
  53. package/src/cards/builtin/pills.ts +36 -0
  54. package/src/cards/builtin/queue/QueueCard.vue +65 -0
  55. package/src/cards/builtin/queue/meta.json +47 -0
  56. package/src/cards/builtin/queue/schema.json +32 -0
  57. package/src/cards/builtin/ranking/RankingCard.vue +37 -0
  58. package/src/cards/builtin/ranking/meta.json +71 -0
  59. package/src/cards/builtin/ranking/schema.json +35 -0
  60. package/src/cards/builtin/recent/RecentCard.vue +41 -0
  61. package/src/cards/builtin/recent/meta.json +32 -0
  62. package/src/cards/builtin/recent/schema.json +21 -0
  63. package/src/cards/builtin/shared.ts +83 -0
  64. package/src/cards/builtin/split/SplitCard.vue +52 -0
  65. package/src/cards/builtin/split/meta.json +72 -0
  66. package/src/cards/builtin/split/schema.json +40 -0
  67. package/src/cards/builtin/trend/TrendCard.vue +75 -0
  68. package/src/cards/builtin/trend/meta.json +81 -0
  69. package/src/cards/builtin/trend/schema.json +58 -0
  70. package/src/cards/index.ts +29 -0
  71. package/src/cards/registry.ts +57 -0
  72. package/src/cards/tools/cardsTool.ts +181 -0
  73. package/src/cards/tools/cli.ts +35 -0
  74. package/src/cards/types.ts +111 -0
  75. package/src/cards/validate.ts +111 -0
  76. package/src/components/edit/FormActions.vue +9 -5
  77. package/src/components/edit/FormPage.vue +17 -2
  78. package/src/components/layout/AppLayout.vue +4 -0
  79. package/src/components/layout/BaseLayout.vue +4 -0
  80. package/src/components/layout/CardParamsForm.vue +157 -0
  81. package/src/components/layout/CardsDashboard.vue +276 -57
  82. package/src/components/layout/PageHeader.vue +22 -1
  83. package/src/components/layout/QdFavoriteStar.vue +71 -0
  84. package/src/components/layout/Zone.vue +2 -1
  85. package/src/components/lists/ListPage.vue +9 -1
  86. package/src/components/lists/QdSaveSearch.vue +79 -0
  87. package/src/components/pages/NotFoundPage.vue +5 -2
  88. package/src/components/run/QdRunBar.vue +99 -0
  89. package/src/components/show/ShowPage.vue +10 -1
  90. package/src/composables/useBreadcrumb.ts +1 -1
  91. package/src/composables/useCardsArrangement.ts +297 -27
  92. package/src/composables/useEntityItemFormPage.ts +39 -3
  93. package/src/composables/useEntityItemFormPage.types.ts +8 -0
  94. package/src/composables/useEntityItemShowPage.ts +22 -0
  95. package/src/composables/useListPage.ts +71 -0
  96. package/src/composables/useListPage.types.ts +6 -0
  97. package/src/composables/useUnsavedChangesGuard.ts +17 -1
  98. package/src/domain/QdBadge.vue +36 -0
  99. package/src/domain/QdDomainBar.vue +213 -0
  100. package/src/domain/QdDomainBarZone.vue +19 -0
  101. package/src/domain/index.ts +6 -0
  102. package/src/domain/registry.ts +122 -0
  103. package/src/favorites/index.ts +7 -0
  104. package/src/favorites/store.ts +172 -0
  105. package/src/favorites/useFavorites.ts +217 -0
  106. package/src/i18n/defaults/core.en.generated.ts +132 -0
  107. package/src/i18n/defaults/core.en.yml +132 -0
  108. package/src/i18n/defaults/core.fr.generated.ts +132 -0
  109. package/src/i18n/defaults/core.fr.yml +132 -0
  110. package/src/index.ts +23 -0
  111. package/src/kernel/Kernel.routing.ts +4 -15
  112. package/src/kernel/Kernel.types.ts +5 -1
  113. package/src/kernel/Kernel.vue.ts +2 -2
  114. package/src/kernel/KernelContext.routing.ts +10 -1
  115. package/src/kernel/KernelContext.ts +7 -0
  116. package/src/kernel/KernelContext.types.ts +2 -0
  117. package/src/kernel/homeRoute.ts +45 -0
  118. package/src/module/moduleRegistry.ts +4 -0
  119. package/src/run/index.ts +6 -0
  120. package/src/run/run.ts +162 -0
  121. package/src/run/useRun.ts +207 -0
  122. package/src/styles/_cards-dashboard.scss +190 -0
  123. package/src/styles/_qd-board.scss +359 -0
  124. package/src/styles/_qd-cards.scss +1197 -0
  125. package/src/styles/_qd-domain-bar.scss +159 -0
  126. package/src/styles/_qd-run.scss +135 -0
  127. package/src/styles/index.scss +4 -0
  128. package/src/zones/ZoneRegistry.ts +16 -0
  129. 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
+ }