@trops/dash-core 0.1.3 → 0.1.5

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 (2) hide show
  1. package/README.md +170 -0
  2. package/package.json +1 -1
package/README.md ADDED
@@ -0,0 +1,170 @@
1
+ # @trops/dash-core
2
+
3
+ Core framework for Dash dashboard applications. Provides the widget system, provider architecture, context providers, layout engine, and Electron main process layer used by all Dash apps.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @trops/dash-core
9
+ ```
10
+
11
+ **Peer dependencies:**
12
+
13
+ ```json
14
+ {
15
+ "@trops/dash-react": ">=0.1.187",
16
+ "react": "^18.2.0",
17
+ "react-dom": "^18.2.0"
18
+ }
19
+ ```
20
+
21
+ ## Two Export Paths
22
+
23
+ ### Renderer (React)
24
+
25
+ Platform-agnostic UI framework — contexts, hooks, models, components, widget system.
26
+
27
+ ```javascript
28
+ import {
29
+ ComponentManager,
30
+ DashboardPublisher,
31
+ ErrorBoundary,
32
+ // Contexts
33
+ AppContext,
34
+ DashboardContext,
35
+ ThemeWrapper,
36
+ ProviderContext,
37
+ // Hooks
38
+ useDashboard,
39
+ useMcpProvider,
40
+ useWidgetProviders,
41
+ useInstalledWidgets,
42
+ // Models
43
+ DashboardModel,
44
+ LayoutModel,
45
+ ThemeModel,
46
+ // Components
47
+ LayoutBuilder,
48
+ SettingsPanel,
49
+ NavigationBar,
50
+ // Widget
51
+ Widget,
52
+ WidgetFactory,
53
+ ExternalWidget,
54
+ } from "@trops/dash-core";
55
+ ```
56
+
57
+ ### Electron (Main Process)
58
+
59
+ Controllers, IPC handlers, events, and widget pipeline for Electron apps.
60
+
61
+ ```javascript
62
+ const {
63
+ // Factory
64
+ createMainApi,
65
+ // Controllers
66
+ providerController,
67
+ mcpController,
68
+ workspaceController,
69
+ themeController,
70
+ registryController,
71
+ // Widget pipeline
72
+ widgetRegistry,
73
+ widgetCompiler,
74
+ dynamicWidgetLoader,
75
+ // Events
76
+ events,
77
+ } = require("@trops/dash-core/electron");
78
+ ```
79
+
80
+ ## Architecture
81
+
82
+ ```
83
+ @trops/dash-core
84
+ ├── src/ Renderer layer (ESM + CJS)
85
+ │ ├── Api/ IPC API clients
86
+ │ ├── Components/ Dashboard, Layout, Settings, Navigation, etc.
87
+ │ ├── Context/ React Context providers
88
+ │ ├── Models/ Data models (Dashboard, Layout, Theme, etc.)
89
+ │ ├── Widget/ Widget, WidgetFactory, ExternalWidget
90
+ │ ├── hooks/ useDashboard, useMcpProvider, useWidgetProviders
91
+ │ └── utils/ Bundle loader, layout helpers, validation
92
+ │
93
+ └── electron/ Electron layer (CJS only)
94
+ ├── api/ IPC handlers + createMainApi factory
95
+ ├── controller/ Business logic (providers, MCP, themes, etc.)
96
+ ├── events/ Event definitions
97
+ ├── mcp/ MCP server catalog
98
+ └── utils/ File, color, browser utilities
99
+ ```
100
+
101
+ ## Key Patterns
102
+
103
+ ### createMainApi Factory
104
+
105
+ Template apps use `createMainApi(extensions)` to combine core APIs with custom ones:
106
+
107
+ ```javascript
108
+ const { createMainApi } = require("@trops/dash-core/electron");
109
+
110
+ const api = createMainApi({
111
+ myCustomApi: require("./myCustomApi"),
112
+ });
113
+ ```
114
+
115
+ ### Provider System
116
+
117
+ Providers are read from `AppContext.providers`, **not** `DashboardContext.providers`. This is due to component tree ordering — DashboardWrapper renders before providers are loaded.
118
+
119
+ ### ThemeContext Import Rule
120
+
121
+ Always import `ThemeContext` from `@trops/dash-react` to avoid dual context instances:
122
+
123
+ ```javascript
124
+ // CORRECT
125
+ import { ThemeContext } from "@trops/dash-react";
126
+
127
+ // WRONG — creates separate context
128
+ import { ThemeContext } from "./Context/ThemeContext";
129
+ ```
130
+
131
+ ## Documentation
132
+
133
+ See [docs/INDEX.md](docs/INDEX.md) for the full documentation index:
134
+
135
+ - [Widget System](docs/WIDGET_SYSTEM.md) — Architecture, auto-registration, hot reload
136
+ - [Widget API](docs/WIDGET_API.md) — Management methods reference
137
+ - [Widget Development](docs/WIDGET_DEVELOPMENT.md) — Create and test widgets
138
+ - [Widget Registry](docs/WIDGET_REGISTRY.md) — Packaging and distribution
139
+ - [Provider Architecture](docs/PROVIDER_ARCHITECTURE.md) — Three-tier storage model
140
+ - [Widget Provider Configuration](docs/WIDGET_PROVIDER_CONFIGURATION.md) — Configure providers in widgets
141
+ - [Testing](docs/TESTING.md) — Provider and widget testing guides
142
+
143
+ ## Related Packages
144
+
145
+ | Package | Purpose | Location |
146
+ |---|---|---|
147
+ | `@trops/dash-react` | UI component library | [dash-react](https://github.com/trops/dash-react) |
148
+ | `dash-electron` | Electron app template | [dash-electron](https://github.com/trops/dash-electron) |
149
+
150
+ ## Development
151
+
152
+ ```bash
153
+ # Build both layers
154
+ npm run build
155
+
156
+ # Build renderer only
157
+ npm run build:renderer
158
+
159
+ # Build electron only
160
+ npm run build:electron
161
+
162
+ # Format code
163
+ npm run prettify
164
+ ```
165
+
166
+ Publishing is automated via GitHub Actions on push to `master`.
167
+
168
+ ## License
169
+
170
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trops/dash-core",
3
- "version": "0.1.3",
3
+ "version": "0.1.5",
4
4
  "description": "Core framework for Dash dashboard applications",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.esm.js",