@medemagroup/bgc-viewer-components 0.3.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
ADDED
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# BGC Viewer Web Components
|
|
2
|
+
|
|
3
|
+
Framework-agnostic web components for visualizing biosynthetic gene cluster data.
|
|
4
|
+
|
|
5
|
+
For more details about the project structure and the stand-alone BGC Viewer, have a look at the project's [main readme](https://github.com/medema-group/bgc-viewer).
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @medemagroup/bgc-viewer-components d3
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
**Note:** D3.js v7+ is a peer dependency and must be installed separately.
|
|
14
|
+
|
|
15
|
+
## Quick Start
|
|
16
|
+
|
|
17
|
+
### Using with ES Modules
|
|
18
|
+
|
|
19
|
+
```html
|
|
20
|
+
<!DOCTYPE html>
|
|
21
|
+
<html>
|
|
22
|
+
<head>
|
|
23
|
+
<link rel="stylesheet" href="node_modules/@medemagroup/bgc-viewer-components/dist/web-components/style.css">
|
|
24
|
+
</head>
|
|
25
|
+
<body>
|
|
26
|
+
<bgc-region-viewer-container id="viewer"></bgc-region-viewer-container>
|
|
27
|
+
|
|
28
|
+
<script src="https://d3js.org/d3.v7.min.js"></script>
|
|
29
|
+
|
|
30
|
+
<script type="module">
|
|
31
|
+
import { JSONFileProvider } from '@medemagroup/bgc-viewer-components';
|
|
32
|
+
|
|
33
|
+
// Load your antiSMASH JSON data
|
|
34
|
+
const response = await fetch('path/to/antismash-output.json');
|
|
35
|
+
const data = await response.json();
|
|
36
|
+
|
|
37
|
+
// Create a data provider
|
|
38
|
+
const provider = new JSONFileProvider(data);
|
|
39
|
+
|
|
40
|
+
// Get the viewer element and configure it
|
|
41
|
+
const viewer = document.getElementById('viewer');
|
|
42
|
+
viewer.dataProvider = provider;
|
|
43
|
+
viewer.setAttribute('record-id', data.records[0].id);
|
|
44
|
+
</script>
|
|
45
|
+
</body>
|
|
46
|
+
</html>
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
### Using with a Bundler (Webpack, Vite, etc.)
|
|
50
|
+
|
|
51
|
+
```javascript
|
|
52
|
+
import '@medemagroup/bgc-viewer-components';
|
|
53
|
+
import '@medemagroup/bgc-viewer-components/style.css';
|
|
54
|
+
|
|
55
|
+
// The web components are now registered and ready to use
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Components
|
|
59
|
+
|
|
60
|
+
### `<bgc-region-viewer-container>`
|
|
61
|
+
|
|
62
|
+
The main container component that handles data loading and region selection.
|
|
63
|
+
|
|
64
|
+
**Properties:**
|
|
65
|
+
- `dataProvider` - Instance of a data provider (JSONFileProvider or BGCViewerAPIProvider)
|
|
66
|
+
- `record-id` - ID of the record to display
|
|
67
|
+
- `record-data` - Full record metadata (optional, for API provider)
|
|
68
|
+
- `initial-region-id` - ID of region to select initially (optional)
|
|
69
|
+
|
|
70
|
+
**Events:**
|
|
71
|
+
- `region-changed` - Emitted when user selects a different region
|
|
72
|
+
- `annotation-clicked` - Emitted when user clicks an annotation
|
|
73
|
+
- `error` - Emitted when an error occurs
|
|
74
|
+
|
|
75
|
+
## Data Providers
|
|
76
|
+
|
|
77
|
+
### JSONFileProvider
|
|
78
|
+
|
|
79
|
+
Load data directly from antiSMASH JSON output files:
|
|
80
|
+
|
|
81
|
+
```javascript
|
|
82
|
+
import { JSONFileProvider } from '@medemagroup/bgc-viewer-components';
|
|
83
|
+
|
|
84
|
+
const response = await fetch('data.json');
|
|
85
|
+
const jsonData = await response.json();
|
|
86
|
+
const provider = new JSONFileProvider(jsonData);
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
### BGCViewerAPIProvider
|
|
90
|
+
|
|
91
|
+
Connect to a BGC Viewer backend API:
|
|
92
|
+
|
|
93
|
+
```javascript
|
|
94
|
+
import { BGCViewerAPIProvider } from '@medemagroup/bgc-viewer-components';
|
|
95
|
+
|
|
96
|
+
const provider = new BGCViewerAPIProvider({
|
|
97
|
+
baseURL: 'http://localhost:5000'
|
|
98
|
+
});
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## TrackViewer
|
|
102
|
+
|
|
103
|
+
The package also exports a standalone `TrackViewer` class for creating custom genomic track visualizations with D3.js.
|
|
104
|
+
|
|
105
|
+
### Basic Usage
|
|
106
|
+
|
|
107
|
+
```javascript
|
|
108
|
+
import { TrackViewer } from '@medemagroup/bgc-viewer-components';
|
|
109
|
+
|
|
110
|
+
const viewer = new TrackViewer({
|
|
111
|
+
container: '#viewer-container',
|
|
112
|
+
domain: [0, 100],
|
|
113
|
+
trackHeight: 30
|
|
114
|
+
});
|
|
115
|
+
|
|
116
|
+
viewer.setData({
|
|
117
|
+
tracks: [
|
|
118
|
+
{ id: 'genes', label: 'Genes', height: 40 }
|
|
119
|
+
],
|
|
120
|
+
annotations: [
|
|
121
|
+
{
|
|
122
|
+
id: 'gene1',
|
|
123
|
+
trackId: 'genes',
|
|
124
|
+
type: 'arrow',
|
|
125
|
+
classes: ['gene'],
|
|
126
|
+
label: 'geneA',
|
|
127
|
+
start: 10,
|
|
128
|
+
end: 30,
|
|
129
|
+
direction: 'right'
|
|
130
|
+
}
|
|
131
|
+
]
|
|
132
|
+
});
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### TrackViewer API
|
|
136
|
+
|
|
137
|
+
See the [TrackViewer TypeScript types](src/TrackViewer.ts) for the complete API documentation.
|
|
138
|
+
|
|
139
|
+
## Example
|
|
140
|
+
|
|
141
|
+
See the [demos directory](https://github.com/medema-group/bgc-viewer/tree/main/demos/viewer-web-component) for a complete working example.
|
|
142
|
+
|
|
143
|
+
## Requirements
|
|
144
|
+
|
|
145
|
+
- D3.js v7 or higher (peer dependency)
|
|
146
|
+
- Modern browser with Web Components support
|
|
147
|
+
|
|
148
|
+
## Development
|
|
149
|
+
|
|
150
|
+
### Building from Source
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
# Install dependencies
|
|
154
|
+
npm install
|
|
155
|
+
|
|
156
|
+
# Build web components
|
|
157
|
+
npm run build:web-components
|
|
158
|
+
|
|
159
|
+
# Run tests
|
|
160
|
+
npm test
|
|
161
|
+
|
|
162
|
+
# Run tests with coverage
|
|
163
|
+
npm run test:coverage
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
### Project Structure
|
|
167
|
+
|
|
168
|
+
- `src/components/` - Vue components (RegionViewer, RegionViewerContainer)
|
|
169
|
+
- `src/services/dataProviders/` - Data provider implementations
|
|
170
|
+
- `src/TrackViewer.ts` - TrackViewer class for genomic track visualization
|
|
171
|
+
- `src/web-components.ts` - Web components entry point
|
|
172
|
+
- `dist/web-components/` - Built web components (after build)
|
|
173
|
+
- `demos/` - Example usage demonstrations
|
|
174
|
+
|
|
175
|
+
### Running the Demo
|
|
176
|
+
|
|
177
|
+
See the [demo README](../demos/viewer-web-component/README.md) for instructions on running a demo of the viewer component.
|
|
178
|
+
|
|
179
|
+
## License
|
|
180
|
+
|
|
181
|
+
Apache-2.0
|
|
182
|
+
|
|
183
|
+
## Links
|
|
184
|
+
|
|
185
|
+
- [GitHub Repository](https://github.com/medema-group/bgc-viewer)
|
|
186
|
+
- [Issue Tracker](https://github.com/medema-group/bgc-viewer/issues)
|
|
187
|
+
- [Full Documentation](https://github.com/medema-group/bgc-viewer#readme)
|