Skip to content

Commit de10eb1

Browse files
committed
fix: Update sample documentation links to point to new directory structure
1 parent 2477eee commit de10eb1

1 file changed

Lines changed: 51 additions & 21 deletions

File tree

README.md

Lines changed: 51 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -5,28 +5,32 @@ This directory contains complete, production-ready sample tools demonstrating ho
55
## Available Samples
66

77
### 1. HTML Sample (`html-sample/`)
8+
89
**Technology**: HTML, CSS, TypeScript
910

1011
A vanilla TypeScript implementation demonstrating tool development without any framework dependencies.
1112

1213
**Key Features**:
14+
1315
- Pure TypeScript with no framework overhead
1416
- Modern ES2022 features
1517
- Clean separation of concerns
1618
- Comprehensive API usage examples
1719

1820
**Best For**: Lightweight tools, simple utilities, learning the API basics
1921

20-
[→ View HTML Sample Documentation](./html-sample/README.md)
22+
[→ View HTML Sample Documentation](./new/html-sample/README.md)
2123

2224
---
2325

2426
### 2. React Sample (`react-sample/`)
27+
2528
**Technology**: React 18, TypeScript, Vite
2629

2730
A modern React application using hooks and functional components.
2831

2932
**Key Features**:
33+
3034
- React 18 with concurrent features
3135
- Custom hooks for API integration
3236
- Component-based architecture
@@ -35,16 +39,18 @@ A modern React application using hooks and functional components.
3539

3640
**Best For**: Complex interactive tools, data visualization, tools requiring rich UI
3741

38-
[→ View React Sample Documentation](./react-sample/README.md)
42+
[→ View React Sample Documentation](./new/react-sample/README.md)
3943

4044
---
4145

4246
### 3. Vue Sample (`vue-sample/`)
47+
4348
**Technology**: Vue 3, Composition API, TypeScript, Vite
4449

4550
A Vue 3 application using the Composition API and Single File Components.
4651

4752
**Key Features**:
53+
4854
- Vue 3 with Composition API
4955
- `<script setup>` syntax for cleaner code
5056
- Reactive composables
@@ -53,16 +59,18 @@ A Vue 3 application using the Composition API and Single File Components.
5359

5460
**Best For**: Progressive web apps, form-heavy tools, tools requiring two-way data binding
5561

56-
[→ View Vue Sample Documentation](./vue-sample/README.md)
62+
[→ View Vue Sample Documentation](./new/vue-sample/README.md)
5763

5864
---
5965

6066
### 4. Svelte Sample (`svelte-sample/`)
67+
6168
**Technology**: Svelte 5, TypeScript, Vite
6269

6370
A Svelte application leveraging Svelte's compiler-based reactivity.
6471

6572
**Key Features**:
73+
6674
- Svelte 5 with modern reactivity
6775
- Minimal runtime overhead
6876
- Built-in reactivity (no virtual DOM)
@@ -71,7 +79,7 @@ A Svelte application leveraging Svelte's compiler-based reactivity.
7179

7280
**Best For**: Performance-critical tools, embedded tools, tools with limited screen space
7381

74-
[→ View Svelte Sample Documentation](./svelte-sample/README.md)
82+
[→ View Svelte Sample Documentation](./new/svelte-sample/README.md)
7583

7684
---
7785

@@ -80,28 +88,31 @@ A Svelte application leveraging Svelte's compiler-based reactivity.
8088
All samples include comprehensive examples of:
8189

8290
### ToolBox API Integration
91+
8392
✅ Connection management with real-time updates
8493
✅ Notification system (success, info, warning, error)
8594
✅ Clipboard operations
8695
✅ File save/load dialogs
8796
✅ Theme detection (light/dark)
8897
✅ Terminal creation and command execution
89-
✅ Event subscription and handling
98+
✅ Event subscription and handling
9099

91100
### Dataverse API Integration
101+
92102
✅ FetchXML query execution
93103
✅ CRUD operations (Create, Read, Update, Delete)
94104
✅ Entity metadata retrieval
95-
✅ Error handling and validation
105+
✅ Error handling and validation
96106

97107
### Development Best Practices
108+
98109
✅ TypeScript with full type safety (`@pptb/types`)
99110
✅ Modern build tooling (Vite)
100111
✅ Component-based architecture
101112
✅ State management patterns
102113
✅ Event-driven architecture
103114
✅ Responsive UI design
104-
✅ Production-ready builds
115+
✅ Production-ready builds
105116

106117
### Build Configuration for PPTB Compatibility
107118

@@ -110,31 +121,36 @@ Framework samples (React, Vue, Svelte) use Vite with special configuration for P
110121
**IIFE Format**: Builds use Immediately Invoked Function Expression instead of ES modules for compatibility with PPTB's iframe loading mechanism
111122
**Single Bundle**: All code and CSS bundled into one file to avoid module loading issues
112123
**HTML Optimization**: Custom plugin that:
113-
- Removes `type="module"` and `crossorigin` attributes for proper loading with `file://` URLs
114-
- Moves script tags to end of `<body>` so DOM elements are available when IIFE executes
115-
**No External Dependencies**: All dependencies bundled together for standalone execution
124+
125+
- Removes `type="module"` and `crossorigin` attributes for proper loading with `file://` URLs
126+
- Moves script tags to end of `<body>` so DOM elements are available when IIFE executes
127+
**No External Dependencies**: All dependencies bundled together for standalone execution
116128

117129
---
118130

119131
## Quick Start
120132

121133
### Prerequisites
134+
122135
- Node.js 18 or higher
123136
- Power Platform Tool Box desktop application
124137

125138
### Installation Steps
126139

127140
1. **Navigate to sample directory**:
141+
128142
```bash
129143
cd sample/[html|react|vue|svelte]-sample
130144
```
131145

132146
2. **Install dependencies**:
147+
133148
```bash
134149
npm install
135150
```
136151

137152
3. **Build the sample**:
153+
138154
```bash
139155
npm run build
140156
```
@@ -150,24 +166,28 @@ Framework samples (React, Vue, Svelte) use Vite with special configuration for P
150166
## Choosing the Right Framework
151167

152168
### Choose **HTML/TypeScript** if you:
169+
153170
- Want minimal dependencies
154171
- Need the smallest possible bundle size
155172
- Are building a simple utility tool
156173
- Want to learn the API without framework complexity
157174

158175
### Choose **React** if you:
176+
159177
- Need rich, complex user interfaces
160178
- Want to leverage the React ecosystem
161179
- Are familiar with React patterns
162180
- Need extensive third-party component libraries
163181

164182
### Choose **Vue** if you:
183+
165184
- Want a progressive framework
166185
- Prefer template-based syntax
167186
- Need strong TypeScript support
168187
- Want excellent documentation and tooling
169188

170189
### Choose **Svelte** if you:
190+
171191
- Want the smallest runtime bundle
172192
- Need maximum performance
173193
- Prefer compiler-based reactivity
@@ -177,36 +197,42 @@ Framework samples (React, Vue, Svelte) use Vite with special configuration for P
177197

178198
## Sample Comparison
179199

180-
| Feature | HTML | React | Vue | Svelte |
181-
|---------|------|-------|-----|--------|
182-
| **Bundle Size** | ~50KB | ~158KB | ~77KB | ~45KB |
183-
| **Runtime Overhead** | Minimal | Medium | Medium | Minimal |
184-
| **Learning Curve** | Easy | Moderate | Easy | Easy |
185-
| **TypeScript Support** | Excellent | Excellent | Excellent | Excellent |
186-
| **Build Time** | Fast | Fast | Fast | Fast |
187-
| **HMR Support** | No | Yes | Yes | Yes |
188-
| **Ecosystem** | Standard Web | Large | Large | Growing |
200+
| Feature | HTML | React | Vue | Svelte |
201+
| ---------------------- | ------------ | --------- | --------- | --------- |
202+
| **Bundle Size** | ~50KB | ~158KB | ~77KB | ~45KB |
203+
| **Runtime Overhead** | Minimal | Medium | Medium | Minimal |
204+
| **Learning Curve** | Easy | Moderate | Easy | Easy |
205+
| **TypeScript Support** | Excellent | Excellent | Excellent | Excellent |
206+
| **Build Time** | Fast | Fast | Fast | Fast |
207+
| **HMR Support** | No | Yes | Yes | Yes |
208+
| **Ecosystem** | Standard Web | Large | Large | Growing |
189209

190-
*Bundle sizes for HTML sample include compiled TypeScript; framework samples are IIFE bundles with all features included*
210+
_Bundle sizes for HTML sample include compiled TypeScript; framework samples are IIFE bundles with all features included_
191211

192212
---
193213

194214
## Development Workflow
195215

196216
### Development Mode (React/Vue/Svelte only)
217+
197218
```bash
198219
npm run dev
199220
```
221+
200222
Starts development server with hot module replacement. Note: ToolBox APIs are only available when loaded within the application.
201223

202224
### Production Build
225+
203226
```bash
204227
npm run build
205228
```
229+
206230
Creates optimized production build in `dist/` directory.
207231

208232
### Type Checking
233+
209234
All samples include TypeScript for type safety:
235+
210236
```bash
211237
# React/Vue/Svelte
212238
npm run check # or tsc for HTML
@@ -240,18 +266,22 @@ Each sample follows a consistent structure:
240266
## Common Issues & Solutions
241267

242268
### Build Errors
269+
243270
**Problem**: TypeScript errors during build
244271
**Solution**: Ensure all dependencies are installed with `npm install`
245272

246273
### API Not Available
274+
247275
**Problem**: `window.toolboxAPI` is undefined
248276
**Solution**: The tool must be loaded within Power Platform Tool Box, not a standalone browser
249277

250278
### Connection Null
279+
251280
**Problem**: Connection is always null
252281
**Solution**: Create a connection in Power Platform Tool Box first
253282

254283
### HMR Not Working
284+
255285
**Problem**: Changes don't reflect immediately
256286
**Solution**: Restart dev server with `npm run dev`
257287

@@ -268,7 +298,7 @@ Each sample follows a consistent structure:
268298

269299
## Contributing
270300

271-
Found an issue or want to improve the samples?
301+
Found an issue or want to improve the samples?
272302

273303
1. Fork the repository
274304
2. Create a feature branch

0 commit comments

Comments
 (0)