feat(utils): add wokwi-show-pins element for debugging

Author: urish

CONTRIBUTING.md

@@ -1,18 +1,18 @@
 # Contributing to Wokwi Elements
 
-First of all, thank you for considering contributing to Wokwi Elements! 
+First of all, thank you for considering contributing to Wokwi Elements!
 Please go over these guidelines to ensure that your contribution lands
 successfully.
 
 ## Creating a New Element
 
-Before starting to work on a new element, please 
+Before starting to work on a new element, please
 [file an issue](https://github.com/wokwi/wokwi-elements/issues/new/choose)
-to discuss the implementation. 
+to discuss the implementation.
 
 Also, please make sure that any 3d-party graphics that you use
 for the element is released under a permissive license (such as
-MIT, BSD, Apache, or CC-BY), and that you give credits to the 
+MIT, BSD, Apache, or CC-BY), and that you give credits to the
 original authors as required.
 
 To create the element, use our hygen generator, by running:
@@ -45,14 +45,50 @@ Please make sure to follow these guidelines when working on your new element:
 3. Add docstring to the element class and any public properties/methods. These
    doc strings will appear in the Docs tag in storybook. Check out the [Resistor
    Element](src/resistor-element.ts) for an example.
-4. Your commit messages should follow the [conventional commits 
+4. Include a `pinInfo` property in your elements. This property defines the pins
+   of the element, specifying at least the name and x/y position of each pin.
+
+   Example (from the [LED element](src/led-element.ts)):
+
+   ```typescript
+   readonly pinInfo: ElementPin[] = [
+     { name: 'A', x: 24, y: 42, signals: [], description: 'Anode' },
+     { name: 'C', x: 16, y: 42, signals: [], description: 'Cathode' },
+   ];
+   ```
+
+5. Create a storybook story for each element configuration. For example, check the [LCD1602
+   stories](src/lcd1602-element.stories.ts)
+6. Your commit messages should follow the [conventional commits
    standard](https://www.conventionalcommits.org/), e.g.:
    `feat: add neopixel element`
 
+## Debugging Pin Info
+
+When working on the `pinInfo` property, it is often useful to visually see the
+pins that you define. To see the pin locations, add the `<wokwi-show-pins>`
+utility element to your story:
+
+1. Import the element definition into your story, by adding this line at the top
+   of the story file:
+   ```
+   import './utils/show-pins-element';
+   ```
+2. Wrap your element with the <wokwi-show-pins> element, e.g.
+   ```
+   export const HCSR04 = () => html`
+     <wokwi-show-pins>
+       <wokwi-hc-sr04></wokwi-hc-sr04>
+     </wokwi-show-pins>
+   `;
+   ```
+3. When you are happy with the pin definition, please remove the `<wokwi-show-pins>`
+   from your story. It is only a debugging tool, and shouldn't be present in the final story.
+
 ## Video Tutorial and Blog Post
 
 The [Membrane keypad element live-coding video tutorial](https://www.youtube.com/watch?v=gh27icNatwA) walks
 through the complete process behind creating an element: research, drawing, and writing the code /
-stories. 
+stories.
 
 If you prefer reading over watching a video, please check out [Recreating The Arduino Pushbutton Using SVG And &lt;lit-element&gt;](https://www.smashingmagazine.com/2020/01/recreating-arduino-pushbutton-svg/).

src/utils/show-pins-element.ts

@@ -0,0 +1,49 @@
+import { customElement, html, LitElement, property, query, svg } from 'lit-element';
+import { ElementPin } from '../pin';
+
+export interface ElementWithPinInfo extends Element {
+  pinInfo?: ElementPin[];
+}
+
+/**
+ * Utility element to debug the pinInfo property. Pin locations are displayed using red dots.
+ * Moving your mouse over one of the red dots shows a tooltip with the pin's name.
+ *
+ *
+ * Usage:
+ * 1. Import this file in your element's story file, e.g.
+ *    ```
+ *    import './utils/show-pins-element';
+ *    ```
+ * 2. Wrap your element with the <wokwi-show-pins> element, e.g.
+ *    ```
+ *    export const HCSR04 = () => html`
+ *      <wokwi-show-pins>
+ *        <wokwi-hc-sr04></wokwi-hc-sr04>
+ *      </wokwi-show-pins>
+ *    `;
+ *    ```
+ */
+@customElement('wokwi-show-pins')
+export class ShowPinsElement extends LitElement {
+  @property() pinColor = 'red';
+  @query('#content') elementSlot!: HTMLSlotElement;
+
+  get slotChild() {
+    return this.elementSlot?.assignedElements()[0] as ElementWithPinInfo | undefined;
+  }
+
+  render() {
+    const pinInfo = this.slotChild?.pinInfo ?? [];
+    const { pinColor } = this;
+    return html`<div style="position: relative">
+      <slot id="content" @slotchange=${() => this.requestUpdate()}></slot>
+
+      <svg style="position: absolute; top: 0; left: 0" width="100%" height="100%" fill=${pinColor}>
+        ${pinInfo.map(
+          (pin) => svg`<circle cx=${pin.x} cy=${pin.y} r=2><title>${pin.name}</title></circle>`
+        )}
+      </svg>
+    </div>`;
+  }
+}