maze-blockly-wrapper 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 SmartBooksDev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+# @maze/blockly-wrapper
+
+A React-based Blockly wrapper for creating interactive maze programming games. This package provides a complete maze game environment where users can program a spider to navigate through mazes using visual programming blocks.
+
+## Features
+
+- **Interactive Maze Game**: Program a spider to navigate through mazes
+- **Visual Programming**: Uses Google Blockly for drag-and-drop programming
+- **Editable Mazes**: Create and customize mazes with an intuitive editor
+- **Real-time Execution**: Watch your code execute step-by-step
+- **Responsive Design**: Works on desktop and mobile devices
+- **TypeScript Support**: Full TypeScript definitions included
+
+## Installation
+
+```bash
+npm install @maze/blockly-wrapper
+```
+
+## Peer Dependencies
+
+This package requires the following peer dependencies:
+
+```json
+{
+  "react": "^18.0.0 || ^19.0.0",
+  "react-dom": "^18.0.0 || ^19.0.0",
+  "blockly": "^12.0.0"
+}
+```
+
+## Quick Start
+
+```tsx
+import React from 'react';
+import { MazeGame } from '@maze/blockly-wrapper';
+
+function App() {
+  const handleRunFinish = (result) => {
+    console.log('Game finished!', result);
+    // result contains: steps, reachedFinish, maxMovesExceeded, finalPosition, path, executionTime
+  };
+
+  return (
+    <MazeGame
+      isEditable={true}
+      onRunFinish={handleRunFinish}
+      maxMoves={100}
+    />
+  );
+}
+```
+
+## Components
+
+### MazeGame
+
+The main component that combines the maze, programming interface, and game logic.
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isEditable` | `boolean` | `false` | Enable maze editing mode |
+| `configuration` | `MazeConfig` | `undefined` | Initial maze configuration |
+| `onChange` | `(config: MazeConfig) => void` | `undefined` | Callback when maze configuration changes |
+| `onRunFinish` | `(result: RunResult) => void` | `undefined` | Callback when game execution finishes |
+| `maxMoves` | `number` | `50` | Maximum moves allowed |
+| `showControls` | `boolean` | `true` | Show game control buttons |
+| `className` | `string` | `undefined` | Additional CSS classes |
+
+### EditableMazeGrid
+
+A standalone component for editing maze configurations.
+
+```tsx
+import { EditableMazeGrid } from '@maze/blockly-wrapper';
+
+<EditableMazeGrid
+  config={mazeConfig}
+  onConfigChange={handleConfigChange}
+/>
+```
+
+### MazeBlocklyContainer
+
+The Blockly programming interface component.
+
+```tsx
+import { MazeBlocklyContainer } from '@maze/blockly-wrapper';
+
+<MazeBlocklyContainer
+  config={blocklyConfig}
+  onCodeChange={handleCodeChange}
+  onExecuteCode={handleExecuteCode}
+/>
+```
+
+## Types
+
+### MazeConfig
+
+```typescript
+interface MazeConfig {
+  width: number;
+  height: number;
+  spiderStart: Position;
+  finishPosition: Position;
+  walls: Position[];
+  estimatedSteps?: number;
+}
+```
+
+### RunResult
+
+```typescript
+interface RunResult {
+  steps: number;
+  reachedFinish: boolean;
+  maxMovesExceeded: boolean;
+  finalPosition: Position;
+  path: Position[];
+  executionTime: number;
+  error?: string;
+}
+```
+
+### Position
+
+```typescript
+interface Position {
+  x: number;
+  y: number;
+}
+```
+
+## Usage Examples
+
+### Basic Game
+
+```tsx
+import { MazeGame } from '@maze/blockly-wrapper';
+
+<MazeGame />
+```
+
+### Editable Maze with Configuration
+
+```tsx
+import { MazeGame } from '@maze/blockly-wrapper';
+
+const initialConfig = {
+  width: 12,
+  height: 10,
+  spiderStart: { x: 1, y: 1 },
+  finishPosition: { x: 10, y: 8 },
+  walls: [
+    { x: 3, y: 2 },
+    { x: 4, y: 3 },
+    { x: 7, y: 5 }
+  ]
+};
+
+<MazeGame
+  isEditable={true}
+  configuration={initialConfig}
+  onChange={(config) => console.log('Maze changed:', config)}
+  onRunFinish={(result) => console.log('Game result:', result)}
+  maxMoves={75}
+/>
+```
+
+### Custom Blockly Configuration
+
+```tsx
+import { MazeBlocklyContainer } from '@maze/blockly-wrapper';
+
+const customConfig = {
+  allowedTypes: new Set(['maze_move_forward', 'maze_turn_left']),
+  limits: { maze_move_forward: 10, maze_turn_left: 5 },
+  toolbox: `<xml>...</xml>`,
+  initialXml: `<xml>...</xml>`
+};
+
+<MazeBlocklyContainer
+  config={customConfig}
+  onCodeChange={(code) => console.log('Code:', code)}
+  onExecuteCode={(commands) => console.log('Commands:', commands)}
+/>
+```
+
+## Development
+
+### Building the Package
+
+```bash
+# Build library for distribution
+npm run build:lib
+
+# Build types
+npm run build:types
+
+# Build both library and app
+npm run build
+```
+
+### Development Mode
+
+```bash
+npm run dev
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+For issues and questions, please use the GitLab issue tracker at:
+https://gitlab.com/smartbooksdev/blocklysbwrapper