@harbortouch/skytab-analytics-report-utils 0.3.0 → 0.4.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/README.md +137 -56
- package/dist/index.cjs +1 -6
- package/dist/index.js +1 -6
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,93 +1,174 @@
|
|
|
1
1
|
# skytab-analytics-report-utils
|
|
2
2
|
|
|
3
|
+
A **framework-agnostic TypeScript library** that centralises all report column presentation configuration for SkyTab Analytics. It is the **shared source of truth** consumed by frontend, backend, and export services — ensuring column definitions, types, widths, footers, and i18n keys stay consistent across all applications.
|
|
3
4
|
|
|
5
|
+
## What it provides
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
- Which columns exist in each report
|
|
8
|
+
- How each column is typed (`money`, `percent`, `string`, etc.)
|
|
9
|
+
- Column widths and alignment rules
|
|
10
|
+
- Footer aggregation logic (sum / percent-change / average)
|
|
11
|
+
- Column group structure (for multi-level headers)
|
|
12
|
+
- i18n translation key references for column labels and tooltips
|
|
6
13
|
|
|
7
|
-
|
|
14
|
+
**No React. No i18n runtime. No API dependencies.** Consumers apply the configuration using their own framework.
|
|
8
15
|
|
|
9
|
-
|
|
16
|
+
---
|
|
10
17
|
|
|
11
|
-
##
|
|
18
|
+
## Installation
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
# Local development (consuming project's package.json)
|
|
22
|
+
{
|
|
23
|
+
"dependencies": {
|
|
24
|
+
"@harbortouch/skytab-analytics-report-utils": "file:../skytab-analytics-report-utils"
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Requires **Node ≥ 22.6.0** and **pnpm ≥ 9.0.0**.
|
|
30
|
+
|
|
31
|
+
---
|
|
12
32
|
|
|
13
|
-
|
|
14
|
-
* [Add files using the command line](https://docs.gitlab.com/topics/git/add_files/#add-files-to-a-git-repository) or push an existing Git repository with the following command:
|
|
33
|
+
## Usage
|
|
15
34
|
|
|
35
|
+
```typescript
|
|
36
|
+
// Import everything from the main entry point
|
|
37
|
+
import {
|
|
38
|
+
salesSummaryConfig,
|
|
39
|
+
COLUMN_REGISTRY,
|
|
40
|
+
getColumnAlignment,
|
|
41
|
+
calculateReportTotals,
|
|
42
|
+
} from '@harbortouch/skytab-analytics-report-utils';
|
|
43
|
+
|
|
44
|
+
// Sub-path imports for smaller bundles
|
|
45
|
+
import { COLUMN_REGISTRY } from '@harbortouch/skytab-analytics-report-utils/columns';
|
|
46
|
+
import { salesSummaryConfig } from '@harbortouch/skytab-analytics-report-utils/reports';
|
|
16
47
|
```
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
48
|
+
|
|
49
|
+
### Integrating with the frontend (React + TanStack Table)
|
|
50
|
+
|
|
51
|
+
```typescript
|
|
52
|
+
import { salesSummaryConfig } from '@harbortouch/skytab-analytics-report-utils';
|
|
53
|
+
import { type FieldConfig } from '@hooks/useReportBuilder';
|
|
54
|
+
|
|
55
|
+
const FIELD_CONFIG = salesSummaryConfig.fields as Record<keyof SalesSummaryRecord, FieldConfig<SalesSummaryRecord>>;
|
|
21
56
|
```
|
|
22
57
|
|
|
23
|
-
|
|
58
|
+
### Computing totals rows
|
|
24
59
|
|
|
25
|
-
|
|
60
|
+
```typescript
|
|
61
|
+
import { calculateReportTotals, salesSummaryConfig } from '@harbortouch/skytab-analytics-report-utils';
|
|
26
62
|
|
|
27
|
-
|
|
63
|
+
const totals = calculateReportTotals(
|
|
64
|
+
data, // row data array
|
|
65
|
+
salesSummaryConfig.fields, // field config from this library
|
|
66
|
+
{ labelField: 'groupByName', label: 'Total' },
|
|
67
|
+
);
|
|
68
|
+
```
|
|
28
69
|
|
|
29
|
-
|
|
30
|
-
* [Create a new merge request](https://docs.gitlab.com/user/project/merge_requests/creating_merge_requests/)
|
|
31
|
-
* [Automatically close issues from merge requests](https://docs.gitlab.com/user/project/issues/managing_issues/#closing-issues-automatically)
|
|
32
|
-
* [Enable merge request approvals](https://docs.gitlab.com/user/project/merge_requests/approvals/)
|
|
33
|
-
* [Set auto-merge](https://docs.gitlab.com/user/project/merge_requests/auto_merge/)
|
|
70
|
+
---
|
|
34
71
|
|
|
35
|
-
##
|
|
72
|
+
## Repository structure
|
|
36
73
|
|
|
37
|
-
|
|
74
|
+
```
|
|
75
|
+
src/
|
|
76
|
+
├── types.ts — Core interfaces (FieldType, ColumnPresentationConfig, ReportConfig, …)
|
|
77
|
+
├── columns/
|
|
78
|
+
│ └── index.ts — ReportColumnKey union type + COLUMN_REGISTRY (i18n keys)
|
|
79
|
+
├── reports/
|
|
80
|
+
│ ├── salesSummary.ts
|
|
81
|
+
│ ├── ticketSummary.ts
|
|
82
|
+
│ ├── ticketLive.ts
|
|
83
|
+
│ ├── productMix.ts
|
|
84
|
+
│ ├── modifierMix.ts
|
|
85
|
+
│ ├── itemTax.ts
|
|
86
|
+
│ └── index.ts — Re-exports all report configs
|
|
87
|
+
├── totals.ts — calculateReportTotals() utility
|
|
88
|
+
├── utils/
|
|
89
|
+
│ └── alignment.ts — getColumnAlignment(), isNumericType()
|
|
90
|
+
└── index.ts — Main entry point
|
|
91
|
+
```
|
|
38
92
|
|
|
39
|
-
|
|
40
|
-
* [Analyze your code for known vulnerabilities with Static Application Security Testing (SAST)](https://docs.gitlab.com/user/application_security/sast/)
|
|
41
|
-
* [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/topics/autodevops/requirements/)
|
|
42
|
-
* [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/user/clusters/agent/)
|
|
43
|
-
* [Set up protected environments](https://docs.gitlab.com/ci/environments/protected_environments/)
|
|
93
|
+
---
|
|
44
94
|
|
|
45
|
-
|
|
95
|
+
## Available reports
|
|
46
96
|
|
|
47
|
-
|
|
97
|
+
| Export | Report |
|
|
98
|
+
|---|---|
|
|
99
|
+
| `salesSummaryConfig` | Sales Summary |
|
|
100
|
+
| `ticketSummaryConfig` | Ticket Summary |
|
|
101
|
+
| `ticketLiveConfig` | Ticket Live |
|
|
102
|
+
| `productMixConfig` | Product Mix |
|
|
103
|
+
| `modifierMixConfig` | Modifier Mix |
|
|
104
|
+
| `itemTaxConfig` | Item Tax |
|
|
48
105
|
|
|
49
|
-
|
|
106
|
+
---
|
|
50
107
|
|
|
51
|
-
##
|
|
108
|
+
## Core concepts
|
|
52
109
|
|
|
53
|
-
|
|
110
|
+
### `FieldType`
|
|
54
111
|
|
|
55
|
-
|
|
56
|
-
Choose a self-explaining name for your project.
|
|
112
|
+
Governs both formatting and alignment for a column:
|
|
57
113
|
|
|
58
|
-
|
|
59
|
-
|
|
114
|
+
| Type | Alignment | Description |
|
|
115
|
+
|---|---|---|
|
|
116
|
+
| `string` | left | Plain text |
|
|
117
|
+
| `date` | left | Calendar date |
|
|
118
|
+
| `time` | left | Time of day |
|
|
119
|
+
| `boolean` | right | True/false flag |
|
|
120
|
+
| `money` | right | Currency value |
|
|
121
|
+
| `number` | right | Integer or generic numeric |
|
|
122
|
+
| `fixedNumber` | right | Decimal with fixed precision |
|
|
123
|
+
| `percent` | right | Ratio displayed as percentage (×100) |
|
|
60
124
|
|
|
61
|
-
|
|
62
|
-
On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
|
|
125
|
+
### `FooterCalculation`
|
|
63
126
|
|
|
64
|
-
|
|
65
|
-
Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
|
|
127
|
+
Declarative aggregation for totals rows:
|
|
66
128
|
|
|
67
|
-
|
|
68
|
-
|
|
129
|
+
| Type | Formula |
|
|
130
|
+
|---|---|
|
|
131
|
+
| `sum` | `Σ row[field]` |
|
|
132
|
+
| `percentChange` | `(Σ numerator − Σ denominator) / Σ denominator` |
|
|
133
|
+
| `average` | `Σ numerator / Σ denominator` |
|
|
69
134
|
|
|
70
|
-
|
|
71
|
-
Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
|
|
135
|
+
### Column Registry
|
|
72
136
|
|
|
73
|
-
|
|
74
|
-
Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
|
|
137
|
+
Every column key maps to three i18n keys via `COLUMN_REGISTRY`:
|
|
75
138
|
|
|
76
|
-
|
|
77
|
-
|
|
139
|
+
```typescript
|
|
140
|
+
{
|
|
141
|
+
titleKey: 'common.report-col.net-sales',
|
|
142
|
+
shortTitleKey: 'common.report-col.net-sales.short',
|
|
143
|
+
infoTextKey: 'common.report-col.net-sales.info',
|
|
144
|
+
}
|
|
145
|
+
```
|
|
78
146
|
|
|
79
|
-
|
|
80
|
-
State if you are open to contributions and what your requirements are for accepting them.
|
|
147
|
+
Consumers resolve these keys through their own i18n framework.
|
|
81
148
|
|
|
82
|
-
|
|
149
|
+
---
|
|
83
150
|
|
|
84
|
-
|
|
151
|
+
## Adding a new report
|
|
85
152
|
|
|
86
|
-
|
|
87
|
-
|
|
153
|
+
1. Create `src/reports/<reportName>.ts` with a `FIELDS` record and a `ReportConfig` export.
|
|
154
|
+
2. Re-export from `src/reports/index.ts`.
|
|
155
|
+
3. Re-export from `src/index.ts`.
|
|
156
|
+
4. Add any new column keys to `src/columns/index.ts` (`ReportColumnKey` union + `COLUMN_REGISTRY` entry).
|
|
157
|
+
5. Build and verify:
|
|
88
158
|
|
|
89
|
-
|
|
90
|
-
|
|
159
|
+
```bash
|
|
160
|
+
pnpm build
|
|
161
|
+
pnpm typecheck
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
---
|
|
91
165
|
|
|
92
|
-
##
|
|
93
|
-
|
|
166
|
+
## Development
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
pnpm build # Build ESM + CJS outputs to dist/
|
|
170
|
+
pnpm dev # Watch mode
|
|
171
|
+
pnpm typecheck # TypeScript type check (no emit)
|
|
172
|
+
pnpm lint:js # ESLint
|
|
173
|
+
pnpm lint:js:fix # ESLint with auto-fix
|
|
174
|
+
```
|
package/dist/index.cjs
CHANGED
|
@@ -1081,12 +1081,7 @@ var FIELDS5 = {
|
|
|
1081
1081
|
}
|
|
1082
1082
|
}
|
|
1083
1083
|
};
|
|
1084
|
-
var MODIFIER_MIX_AVAILABLE_COLUMNS = [
|
|
1085
|
-
"modifiersSales",
|
|
1086
|
-
"modifiersQuantity",
|
|
1087
|
-
"avgGross",
|
|
1088
|
-
"attachRate"
|
|
1089
|
-
];
|
|
1084
|
+
var MODIFIER_MIX_AVAILABLE_COLUMNS = ["modifiersSales", "modifiersQuantity", "avgGross"];
|
|
1090
1085
|
var MODIFIER_MIX_DEFAULT_VISIBLE_COLUMNS = MODIFIER_MIX_AVAILABLE_COLUMNS;
|
|
1091
1086
|
var modifierMixConfig = {
|
|
1092
1087
|
fields: FIELDS5,
|
package/dist/index.js
CHANGED
|
@@ -1032,12 +1032,7 @@ var FIELDS5 = {
|
|
|
1032
1032
|
}
|
|
1033
1033
|
}
|
|
1034
1034
|
};
|
|
1035
|
-
var MODIFIER_MIX_AVAILABLE_COLUMNS = [
|
|
1036
|
-
"modifiersSales",
|
|
1037
|
-
"modifiersQuantity",
|
|
1038
|
-
"avgGross",
|
|
1039
|
-
"attachRate"
|
|
1040
|
-
];
|
|
1035
|
+
var MODIFIER_MIX_AVAILABLE_COLUMNS = ["modifiersSales", "modifiersQuantity", "avgGross"];
|
|
1041
1036
|
var MODIFIER_MIX_DEFAULT_VISIBLE_COLUMNS = MODIFIER_MIX_AVAILABLE_COLUMNS;
|
|
1042
1037
|
var modifierMixConfig = {
|
|
1043
1038
|
fields: FIELDS5,
|