report-studio 1.1.0 → 1.2.1

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,179 @@
1
+ /**
2
+ * The layout file the designer saves, and the page list buildPages makes of it.
3
+ *
4
+ * Hand-written to match src/engine/validate.js. Every object also accepts
5
+ * properties not named here, because the designer adds its own (guides, for
6
+ * one) and a layout from a newer version should still type-check.
7
+ */
8
+
9
+ export type BandType =
10
+ | 'reportHeader'
11
+ | 'pageHeader'
12
+ | 'groupHeader'
13
+ | 'detail'
14
+ | 'groupFooter'
15
+ | 'pageFooter'
16
+ | 'reportFooter';
17
+
18
+ export type ItemType = 'text' | 'table' | 'line' | 'box' | 'image';
19
+
20
+ export type Align = 'left' | 'center' | 'right';
21
+
22
+ export type LineStyle = 'solid' | 'dashed' | 'dotted' | 'double';
23
+
24
+ /** a table's grid and a box's border may also be turned off */
25
+ export type RuleStyle = LineStyle | 'none';
26
+
27
+ export type ImageFit = 'contain' | 'cover' | 'fill';
28
+
29
+ export interface Margin {
30
+ top: number;
31
+ right: number;
32
+ bottom: number;
33
+ left: number;
34
+ }
35
+
36
+ /** sizes in CSS pixels; A4 at 96dpi is 794 x 1123 */
37
+ export interface PageSetup {
38
+ width: number;
39
+ height: number;
40
+ margin: Margin;
41
+ [key: string]: unknown;
42
+ }
43
+
44
+ export interface TextStyle {
45
+ fontFamily?: string;
46
+ fontSize?: number;
47
+ fontWeight?: string;
48
+ fontStyle?: string;
49
+ color?: string;
50
+ align?: Align;
51
+ background?: string | null;
52
+ border?: string | null;
53
+ padding?: number;
54
+ [key: string]: unknown;
55
+ }
56
+
57
+ interface ItemBase {
58
+ id: string;
59
+ x?: number;
60
+ y?: number;
61
+ w?: number;
62
+ h?: number;
63
+ [key: string]: unknown;
64
+ }
65
+
66
+ export interface TextItem extends ItemBase {
67
+ type: 'text';
68
+ /** literal text and `{placeholders}`, such as `Total: {sum(amount)}` */
69
+ value: string;
70
+ style?: TextStyle;
71
+ }
72
+
73
+ export interface TableColumn {
74
+ /** the row property this column shows */
75
+ field: string;
76
+ label?: string;
77
+ width?: number;
78
+ align?: Align;
79
+ [key: string]: unknown;
80
+ }
81
+
82
+ export interface TableStyle extends TextStyle {
83
+ borderStyle?: RuleStyle;
84
+ borderWidth?: number;
85
+ borderColor?: string;
86
+ headerColor?: string;
87
+ headerBackground?: string;
88
+ }
89
+
90
+ export interface TableItem extends ItemBase {
91
+ type: 'table';
92
+ columns: TableColumn[];
93
+ rowHeight: number;
94
+ headerHeight?: number;
95
+ showHeader?: boolean;
96
+ /** the dataset this table reads rows from; the layout's when absent */
97
+ dataset?: string | null;
98
+ /** group this table's rows by a field. One table per report may */
99
+ groupBy?: string | null;
100
+ /** false keeps each cell to one line with an ellipsis */
101
+ wrap?: boolean;
102
+ style?: TableStyle;
103
+ }
104
+
105
+ export interface LineItem extends ItemBase {
106
+ type: 'line';
107
+ orientation?: 'horizontal' | 'vertical';
108
+ style?: {
109
+ thickness?: number;
110
+ lineStyle?: LineStyle;
111
+ color?: string;
112
+ [key: string]: unknown;
113
+ };
114
+ }
115
+
116
+ export interface BoxItem extends ItemBase {
117
+ type: 'box';
118
+ style?: {
119
+ borderStyle?: RuleStyle;
120
+ borderWidth?: number;
121
+ borderColor?: string;
122
+ radius?: number;
123
+ background?: string | null;
124
+ [key: string]: unknown;
125
+ };
126
+ }
127
+
128
+ export interface ImageItem extends ItemBase {
129
+ type: 'image';
130
+ /** a picture stored in the layout: a URL or a `data:` URI */
131
+ src?: string | null;
132
+ /** a data path, such as `company.logo`, whose value is the picture's URL */
133
+ field?: string | null;
134
+ fit?: ImageFit;
135
+ alt?: string;
136
+ }
137
+
138
+ export type ReportItem = TextItem | TableItem | LineItem | BoxItem | ImageItem;
139
+
140
+ export interface Band {
141
+ type: BandType;
142
+ /** pixels, or a percentage of the printable height such as `'10%'` */
143
+ height?: number | string;
144
+ items: ReportItem[];
145
+ [key: string]: unknown;
146
+ }
147
+
148
+ /** what the designer saves as `<name>.json` */
149
+ export interface Layout {
150
+ version?: number;
151
+ name?: string;
152
+ page: PageSetup;
153
+ /** the dataset tables read from when they name none of their own */
154
+ dataset?: string | null;
155
+ /** group the first table's rows by this field */
156
+ groupBy?: string | null;
157
+ bands: Band[];
158
+ [key: string]: unknown;
159
+ }
160
+
161
+ /**
162
+ * The host application's data, keyed by dataset name: arrays of rows for
163
+ * tables, and objects or values for text placeholders.
164
+ */
165
+ export type ReportData = Record<string, unknown>;
166
+
167
+ /** one page of a built report */
168
+ export interface Page {
169
+ /** 1-based */
170
+ pageNO: number;
171
+ bands: Array<Band & Record<string, unknown>>;
172
+ regions: Record<string, unknown>;
173
+ [key: string]: unknown;
174
+ }
175
+
176
+ /** what buildPages returns: the layout, with every page laid out */
177
+ export interface PaginatedReport extends Layout {
178
+ pages: Page[];
179
+ }
@@ -0,0 +1,29 @@
1
+ /**
2
+ * report-studio/react/designer - the designer as a React component.
3
+ */
4
+
5
+ import type { CSSProperties, ForwardRefExoticComponent, RefAttributes } from 'react';
6
+ import type { Layout } from './layout.js';
7
+ import type { DesignerHandle, ReportStore } from './designer.js';
8
+
9
+ export type * from './layout.js';
10
+ export type { DesignerHandle, ReportStore } from './designer.js';
11
+
12
+
13
+ export interface ReportDesignerProps {
14
+ /** where the designer starts, like an input's defaultValue */
15
+ layout?: Layout;
16
+ /** the report's filename stem. Changing it opens a fresh designer */
17
+ id?: string | null;
18
+ store?: ReportStore;
19
+ /** confirm before a tab with unsaved changes closes; default true */
20
+ guardUnload?: boolean;
21
+ /** the layout after every edit. The designer's own object: clone it */
22
+ onChange?: (layout: Layout) => void;
23
+ className?: string;
24
+ style?: CSSProperties;
25
+ }
26
+
27
+ export const ReportDesigner: ForwardRefExoticComponent<
28
+ ReportDesignerProps & RefAttributes<DesignerHandle>
29
+ >;
@@ -0,0 +1,30 @@
1
+ /**
2
+ * report-studio/react - the viewer as a React component.
3
+ */
4
+
5
+ import type { CSSProperties, ForwardRefExoticComponent, RefAttributes } from 'react';
6
+ import type { Layout, PaginatedReport, ReportData } from './layout.js';
7
+ import type { ViewerHandle } from './index.js';
8
+
9
+ export type * from './layout.js';
10
+
11
+
12
+ export interface ReportViewerProps {
13
+ /** a layout the designer saved */
14
+ layout?: Layout;
15
+ /** the data for it, keyed by dataset name. Keep it stable between renders */
16
+ data?: ReportData;
17
+ /** a buildPages result, in place of layout and data */
18
+ paginated?: PaginatedReport;
19
+ title?: string;
20
+ className?: string;
21
+ /** give the viewer a height; it fills it and scrolls inside */
22
+ style?: CSSProperties;
23
+ }
24
+
25
+ /** what a ref on ReportViewer receives */
26
+ export type ReportViewerHandle = Omit<ViewerHandle, 'destroy' | 'exportOpen'>;
27
+
28
+ export const ReportViewer: ForwardRefExoticComponent<
29
+ ReportViewerProps & RefAttributes<ReportViewerHandle>
30
+ >;
@@ -0,0 +1,18 @@
1
+ /**
2
+ * report-studio/vite - mounts the designer's file routes in a Vite dev server.
3
+ */
4
+
5
+ import type { Plugin } from 'vite';
6
+
7
+
8
+ export interface ReportStudioPluginOptions {
9
+ /** where report files live, relative to the project; default `'reports'` */
10
+ dir?: string;
11
+ /** the URL the routes are served under */
12
+ prefix?: string;
13
+ }
14
+
15
+ /** dev only: the routes write files, so they are never mounted for a build */
16
+ export function reportStudio(options?: ReportStudioPluginOptions): Plugin;
17
+
18
+ export default reportStudio;