@andsam/shopify-grab 0.1.0

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 (17) hide show
  1. package/LICENSE +22 -0
  2. package/README.md +113 -0
  3. package/dist/chunk-EWJGBTPU.cjs +42 -0
  4. package/dist/chunk-RV3NLUST.js +42 -0
  5. package/dist/core/index.cjs +1 -0
  6. package/dist/core/index.d.cts +1 -0
  7. package/dist/core/index.d.ts +1 -0
  8. package/dist/core/index.js +1 -0
  9. package/dist/index-uQ7Gd3eQ.d.cts +448 -0
  10. package/dist/index-uQ7Gd3eQ.d.ts +448 -0
  11. package/dist/index.cjs +7 -0
  12. package/dist/index.d.cts +24 -0
  13. package/dist/index.d.ts +24 -0
  14. package/dist/index.global.js +42 -0
  15. package/dist/index.js +7 -0
  16. package/dist/styles.css +2 -0
  17. package/package.json +74 -0
package/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Aiden Bai (original react-grab)
4
+ Copyright (c) 2026 Shopify Grab Contributors
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,113 @@
1
+ # Shopify Grab
2
+
3
+ Select context for coding agents directly from your Shopify theme.
4
+
5
+ Based on [react-grab](https://github.com/aidenybai/react-grab) by Aiden Bai (MIT licensed), adapted for Shopify Liquid themes instead of React apps.
6
+
7
+ ## How it works
8
+
9
+ Point at any element on your Shopify store and press **Cmd+C** (Mac) or **Ctrl+C** (Windows/Linux) to copy the element's HTML, section type, block type, and file path context to your clipboard, ready to paste into your coding agent (Cursor, Claude Code, Copilot, etc.).
10
+
11
+ Example output:
12
+
13
+ ```
14
+ <div class="product-card" data-section-id="template--123__featured-collection">
15
+ Product Title
16
+ $29.99
17
+ </div>
18
+ in section "featured-collection" (sections/featured-collection.liquid)
19
+ in block "product" [block-abc123]
20
+ ```
21
+
22
+ ## Install
23
+
24
+ ### Script tag (recommended for Shopify themes)
25
+
26
+ Add this to your `theme.liquid` layout file inside `<head>`:
27
+
28
+ ```liquid
29
+ {% if request.design_mode or settings.enable_dev_tools %}
30
+ <script src="https://unpkg.com/shopify-grab/dist/index.global.js" crossorigin="anonymous"></script>
31
+ {% endif %}
32
+ ```
33
+
34
+ ### Snippet approach
35
+
36
+ Create a snippet `snippets/shopify-grab.liquid`:
37
+
38
+ ```liquid
39
+ {% if request.design_mode %}
40
+ <script src="https://unpkg.com/shopify-grab/dist/index.global.js" crossorigin="anonymous"></script>
41
+ {% endif %}
42
+ ```
43
+
44
+ Then render it in your layout: `{% render 'shopify-grab' %}`
45
+
46
+ ### Theme App Extension
47
+
48
+ If you're building a Shopify app, include the script in your theme app extension's block:
49
+
50
+ ```liquid
51
+ <script src="https://unpkg.com/shopify-grab/dist/index.global.js" crossorigin="anonymous"></script>
52
+ ```
53
+
54
+ ## Usage
55
+
56
+ Once installed, hover over any UI element and press:
57
+
58
+ - **Cmd+C** on Mac
59
+ - **Ctrl+C** on Windows/Linux
60
+
61
+ This copies the element's context to your clipboard, including:
62
+
63
+ - **HTML preview** of the element with key attributes
64
+ - **Section type** and file path (e.g., `sections/header.liquid`)
65
+ - **Block type** if inside a section block
66
+ - **Snippet name** if using data-snippet attributes
67
+
68
+ ## What gets detected
69
+
70
+ Shopify Grab detects theme structure from:
71
+
72
+ - `data-shopify-editor-section` attributes (JSON with section type, settings, blocks)
73
+ - `data-shopify-editor-block` attributes (JSON with block type)
74
+ - `data-section-id` and `data-section-type` attributes
75
+ - `.shopify-section` class and `#shopify-section-*` IDs
76
+ - `.shopify-block` class and `#shopify-block-*` IDs
77
+ - `data-snippet` custom attributes (for snippet identification)
78
+
79
+ These attributes are automatically present in the Shopify Theme Editor and on storefront preview pages.
80
+
81
+ ## Features
82
+
83
+ - Same overlay UI as react-grab (crosshair, selection highlight, floating label)
84
+ - Shopify green color scheme
85
+ - Canvas-based overlay for smooth 60fps animations
86
+ - Shadow DOM isolation (doesn't conflict with theme styles)
87
+ - Drag to select multiple elements
88
+ - Right-click context menu with Copy, Copy HTML, Copy Screenshot
89
+ - Cursor IDE Lexical editor clipboard format support
90
+ - Plugin system for customization
91
+
92
+ ## API
93
+
94
+ ```javascript
95
+ // Access the global API
96
+ const api = window.__SHOPIFY_GRAB__;
97
+
98
+ // Programmatic control
99
+ api.activate();
100
+ api.deactivate();
101
+ api.toggle();
102
+ api.isActive();
103
+
104
+ // Copy an element's context
105
+ api.copyElement(document.querySelector('.product-card'));
106
+
107
+ // Get display name for an element
108
+ api.getDisplayName(element); // "featured-collection" or "header/menu"
109
+ ```
110
+
111
+ ## License
112
+
113
+ MIT. Based on react-grab by Aiden Bai.