Example: 7GUIs-circleDrawer-react

examples/7GUIs-circle-drawer-react/.eslintrc.cjs

@@ -0,0 +1,18 @@
+module.exports = {
+  root: true,
+  env: { browser: true, es2020: true },
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:react-hooks/recommended'
+  ],
+  ignorePatterns: ['dist', '.eslintrc.cjs'],
+  parser: '@typescript-eslint/parser',
+  plugins: ['react-refresh'],
+  rules: {
+    'react-refresh/only-export-components': [
+      'warn',
+      { allowConstantExport: true }
+    ]
+  }
+};

examples/7GUIs-circle-drawer-react/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

examples/7GUIs-circle-drawer-react/README.md

@@ -0,0 +1,81 @@
+# XState v5 + React - 7GUIs Circle Drawer
+
+This is an example of using XState v5 with React. It's based loosely on the 7GUIs Circle Drawer task.
+
+Built with:
+
+- Stately Studio
+- XState 5
+- React 18
+- Typescript
+- Vite
+
+## The 7GUIs Project
+
+The 7GUIs project is a programming benchmark to compare implementations in terms of their notation. 7GUIs defines seven tasks that represent typical challenges in GUI programming. The Circle Drawer project is the sixth of the seven challenges.
+
+Circle Drawer’s goal is, among other things, to test how well the challenge of implementing undo/redo functionality for a GUI application can be solved. Moreover, Circle Drawer tests how dialog control, i.e. keeping the relevant context between several successive GUI interaction steps, is achieved in the source code. Lastly, the ease of custom drawing is tested. The task is to implement a simple drawing application with the following features:
+
+### Criteria:
+
+- Build a frame containing an undo and redo button as well as a canvas area underneath.
+- Left-clicking inside an empty area inside the canvas will create an unfilled circle with a fixed diameter whose center is the left-clicked point.
+- The circle nearest to the mouse pointer such that the distance from its center to the pointer is less than its radius, if it exists, is filled with the color gray.
+- The gray circle is the selected circle.
+- Right-clicking a selected circle will make a popup menu appear with one entry “Adjust diameter..”.
+- Clicking on this entry will open another frame with a slider inside that adjusts the diameter of selected circle (changes are applied immediately).
+- Closing this frame will mark the last diameter as significant for the undo/redo history.
+- Clicking undo will undo the last significant change (i.e. circle creation or diameter adjustment).
+- Clicking redo will reapply the last undone change unless new changes were made by the user in the meantime.
+
+Visit the [7GUIs project](https://eugenkiss.github.io/7guis/tasks#circle 'Circle Drawer') for more info.
+
+<img src="public/original-circle-drawer.png" alt="Circle Drawer" />
+
+Original GUI: Panel obstructs view of item being edited.
+
+## This Version
+
+The original GUI for this project is pretty outdated. Accessing the diameter control required a number of unnecessary steps as described in this excerpt from the 7GUIs project page:
+
+> 1. Right-clicking a selected circle will make a popup menu appear with one entry “Adjust diameter..”.
+> 2. Clicking on this entry will open another frame with a slider inside that adjusts the diameter of selected circle.
+> 3. Closing this frame will mark the last diameter as significant for the undo/redo history.
+
+This version has been modified for easier editing of the circles. Much of the original criteria has been kept and more features have been added. The controls are at the top of the page and can be accessed without having to open panels. The functionality has been extended to allow for dragging circles to new positions, changing their color, and deleting them. This version is responsive and can be used on any device. The original GUI had a fixed width and height which didn't adapt to different environments or recognize touch events. Below is a screenshot of the updated GUI.
+
+<img src="public/circle-drawer.png" alt="Circle Drawer iPad" />
+
+<img src="public/circle-drawer-iphone.png" alt="Circle Drawer iPhone" />
+
+### CSS, Canvas, or SVG?
+
+This version uses CSS instead of canvas for drawing the circles. Partly because it's easier to test. Also, most developers are more familiar with CSS than canvas, and this is primarily a demonstration of using XState. Canvas is designed for complex graphics used in gaming and heavy bitmap manipulation, like animation. In this project, the circles are not being animated heavily, so CSS is more than sufficient for the task.
+
+SVG is another option for creating web graphics. It's what I started this project with but there is no way to change the layer order of SVG elements, which causes bugs when attempting to select circles that overlap. CSS has a `z-index` property that controls the stacking order of DOM elements. With the `z-index` property and a bit of JavaScript, that problem is easily solved.
+
+### State Machine\*
+
+This state machine, called "Circle Drawer," is a tool that allows users to draw and manipulate circles on a screen. It keeps track of the circles' size, color, and position. Here's a summary of how it works:
+
+1. **Ready state**: This is the initial state where the machine waits for user interaction. From here, the user can perform various actions:
+   - Edit a circle's **size** or **color**.
+   - Drag a circle to change its **position**.
+   - **Undo** the previous action if there is one.
+   - **Redo** an action that was undone.
+   - **Add** a new circle or **select** an existing one by clicking on it.
+2. **Editing state**: When the user starts editing a circle, the machine enters this state. Here, the user can make changes to the size and color of the selected circle. The changes are immediately visible without being added to the undo history. When editing is finished, the changes are saved.
+3. **Dragging state**: When the user touches a circle, the machine enters this state. Here, the user can change the position of the selected circle by dragging it. The changes are immediately visible without being added to the undo history. The user can end the dragging state which saves the final position of the circle. If the circle is dragged of the stage, it will be deleted. Throughout the process, the machine keeps track of the user's actions, allowing them to undo and redo previous changes. It also ensures that the circles stay within the bounds of the screen.
+
+**Note**: The undo/redo functionality is implemented using a stack data structure. Each time the user makes a change, it is pushed onto the undo stack. When the user undoes an action, the change is popped off the undo stack and pushed onto the redo stack. If the user redoes an action, the change is popped off the redo stack and pushed back onto the undo stack.
+
+You can find the source code for this state machine on GitHub: [Circle Drawer State Machine (code)](https://github.com/stevebarakat/circle-drawer/blob/main/src/machine.ts)
+
+_\* Description generated by [Stately.ai](https://stately.ai/ 'Stately.ai')_.
+
+<img src="public/machine.jpg" alt="Circle Drawer" />
+<p align="center">
+    <a href="https://stately.ai/registry/editor/f28b6355-588e-4c93-8699-80fa3f7fc507?machineId=6feb2f0a-f571-47d0-a3ec-d00f8953f956">Circle Drawer State Machine</a>
+</p>
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github.com/stevebarakat/circle-drawer)

examples/7GUIs-circle-drawer-react/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/circle.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Circle Drawer</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>