sanity-plugin-hotspot-picker 0.1.0 → 0.1.1
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.
- package/README.md +129 -59
- package/dist/index.d.ts +3 -3
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,13 +1,15 @@
|
|
|
1
1
|
# sanity-plugin-hotspot-picker
|
|
2
2
|
|
|
3
|
-
A Sanity Studio
|
|
3
|
+
A Sanity Studio field for shoppable images, annotated diagrams and store maps: an image with draggable spots on it, each spot an item that can reference a document.
|
|
4
4
|
|
|
5
5
|
- **Click the image** to add a spot where you clicked.
|
|
6
6
|
- **Drag a spot** to move it. Its position is stored as `x`/`y` percentages of the image.
|
|
7
|
-
- **Click a spot** to edit its item.
|
|
7
|
+
- **Click a spot** to edit its item.
|
|
8
|
+
- **Hover a spot** to preview its referenced document (with its draft/published status). Click the preview to open the document in the next pane; the spot stays highlighted while it's open.
|
|
9
|
+
- **Edit image**: the pencil button swaps the spots for the native image input (upload, crop, hotspot). With no image set, the native input always shows.
|
|
8
10
|
- **Spots with validation errors** show a warning icon and turn red.
|
|
9
|
-
- **Crop-aware**:
|
|
10
|
-
- The Studio's own array list stays under the image, so reordering, removing and editing work as usual.
|
|
11
|
+
- **Crop-aware**: spots are placed on the cropped image, so positions match a cropped image on your frontend.
|
|
12
|
+
- The Studio's own array list stays under the image, so adding, reordering, removing and editing work as usual.
|
|
11
13
|
|
|
12
14
|
## Install
|
|
13
15
|
|
|
@@ -24,106 +26,174 @@ import {hotspotPicker} from 'sanity-plugin-hotspot-picker'
|
|
|
24
26
|
|
|
25
27
|
export default defineConfig({
|
|
26
28
|
// ...
|
|
27
|
-
plugins: [
|
|
29
|
+
plugins: [
|
|
30
|
+
hotspotPicker({
|
|
31
|
+
reference: {title: 'Product', to: [{type: 'product'}]},
|
|
32
|
+
}),
|
|
33
|
+
],
|
|
28
34
|
})
|
|
29
35
|
```
|
|
30
36
|
|
|
31
37
|
## Usage
|
|
32
38
|
|
|
33
|
-
|
|
39
|
+
The plugin registers a `hotspotImage` object type. Use it like any other type:
|
|
34
40
|
|
|
35
41
|
```ts
|
|
36
|
-
import {
|
|
37
|
-
import {hotspotFields} from 'sanity-plugin-hotspot-picker'
|
|
42
|
+
import {defineField, defineType} from 'sanity'
|
|
38
43
|
|
|
39
44
|
export default defineType({
|
|
40
45
|
name: 'shoppableImage',
|
|
41
46
|
type: 'object',
|
|
42
47
|
fields: [
|
|
43
|
-
defineField({name: '
|
|
44
|
-
defineField({
|
|
45
|
-
|
|
46
|
-
type: 'array',
|
|
47
|
-
options: {hotspotPicker: {imagePath: 'image'}},
|
|
48
|
-
of: [
|
|
49
|
-
defineArrayMember({
|
|
50
|
-
name: 'spot',
|
|
51
|
-
type: 'object',
|
|
52
|
-
title: 'Product',
|
|
53
|
-
fields: [
|
|
54
|
-
...hotspotFields(),
|
|
55
|
-
defineField({
|
|
56
|
-
name: 'product',
|
|
57
|
-
type: 'reference',
|
|
58
|
-
to: [{type: 'product'}],
|
|
59
|
-
validation: (rule) => rule.required(),
|
|
60
|
-
}),
|
|
61
|
-
],
|
|
62
|
-
preview: {select: {title: 'product.title', media: 'product.image'}},
|
|
63
|
-
}),
|
|
64
|
-
],
|
|
65
|
-
}),
|
|
48
|
+
defineField({name: 'title', type: 'string'}),
|
|
49
|
+
defineField({name: 'desktop', title: 'Desktop', type: 'hotspotImage'}),
|
|
50
|
+
defineField({name: 'mobile', title: 'Mobile', type: 'hotspotImage'}),
|
|
66
51
|
],
|
|
67
52
|
})
|
|
68
53
|
```
|
|
69
54
|
|
|
70
|
-
|
|
55
|
+
Each `hotspotImage` has two fields:
|
|
71
56
|
|
|
72
|
-
|
|
57
|
+
- `image`: a native image field (crop and hotspot on). It renders without its own label, under the `hotspotImage` field's title.
|
|
58
|
+
- `items`: the spots. Each item has a `reference` (if configured), any extra `fields` you add, and its hidden `x`/`y` position.
|
|
73
59
|
|
|
74
|
-
|
|
75
|
-
| ------------------ | --------- | ------------------------------------------------------------------------------------------ |
|
|
76
|
-
| `imagePath` | `'image'` | Field-level only. The image field, relative to the array's parent. Dots for nested fields. |
|
|
77
|
-
| `imageWidth` | `1200` | Width of the preview image requested from the Sanity CDN. |
|
|
78
|
-
| `icon` | Pin | Icon component on each spot. |
|
|
79
|
-
| `tooltipPlacement` | automatic | `(item) => Placement`: where a spot's preview opens, e.g. from a field on the item. |
|
|
60
|
+
## Options
|
|
80
61
|
|
|
81
|
-
|
|
62
|
+
Everything about the type is configured on the plugin:
|
|
82
63
|
|
|
83
64
|
```ts
|
|
65
|
+
import {PinIcon} from '@sanity/icons'
|
|
66
|
+
import {defineField} from 'sanity'
|
|
67
|
+
import {hotspotPicker} from 'sanity-plugin-hotspot-picker'
|
|
68
|
+
|
|
84
69
|
hotspotPicker({
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
70
|
+
// The object type
|
|
71
|
+
name: 'hotspotImage', // type name
|
|
72
|
+
title: 'Hotspot image',
|
|
73
|
+
|
|
74
|
+
// The `image` field: anything an image field takes. Passing `options` replaces the default
|
|
75
|
+
// `{hotspot: true}`, so include it.
|
|
76
|
+
image: {
|
|
77
|
+
fields: [defineField({name: 'alt', type: 'string', title: 'Alternative text'})],
|
|
78
|
+
},
|
|
79
|
+
|
|
80
|
+
// Each item's `reference` field: anything a reference field takes. Required by default.
|
|
81
|
+
reference: {
|
|
82
|
+
title: 'Product',
|
|
83
|
+
to: [{type: 'product'}],
|
|
84
|
+
options: {filter: 'store.status == "active"'},
|
|
85
|
+
},
|
|
86
|
+
|
|
87
|
+
// The items
|
|
88
|
+
item: {
|
|
89
|
+
name: 'spot', // item type name
|
|
90
|
+
title: 'Product', // defaults to the reference's title
|
|
91
|
+
listTitle: 'Products', // title of the `items` field
|
|
92
|
+
icon: PinIcon,
|
|
93
|
+
fields: [defineField({name: 'label', type: 'string'})], // after `reference`
|
|
94
|
+
preview: {select: {title: 'reference.title', media: 'reference.image'}},
|
|
89
95
|
},
|
|
96
|
+
|
|
97
|
+
// The spots
|
|
98
|
+
icon: PinIcon, // icon on each spot
|
|
99
|
+
imageWidth: 1200, // width of the preview image requested from the Sanity CDN
|
|
100
|
+
tooltipPlacement: (item) => undefined, // where a spot's popover opens; see below
|
|
90
101
|
})
|
|
91
102
|
```
|
|
92
103
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
104
|
+
| Option | Default | |
|
|
105
|
+
| ------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------- |
|
|
106
|
+
| `name` | `'hotspotImage'` | Name of the object type. |
|
|
107
|
+
| `title` | `'Hotspot image'` | Title of the object type. |
|
|
108
|
+
| `image` | `{options: {hotspot: true}}` | Overrides for the `image` field (`fields`, `options`, `title`...). `options` replaces the default. |
|
|
109
|
+
| `reference` | none | The item's `reference` field (`to` is required). Required unless you pass your own `validation`. |
|
|
110
|
+
| `item.name` | `'spot'` | Type name of each item. |
|
|
111
|
+
| `item.title` | reference title, else `'Spot'` | Title of each item. |
|
|
112
|
+
| `item.listTitle` | `'Items'` | Title of the `items` field. |
|
|
113
|
+
| `item.icon` | none | Icon of each item. |
|
|
114
|
+
| `item.fields` | none | Extra fields on each item, after `reference`. |
|
|
115
|
+
| `item.preview` | the reference's `title` | Preview of each item in the list. |
|
|
116
|
+
| `icon` | Pin | Icon component on each spot. |
|
|
117
|
+
| `imageWidth` | `1200` | Width of the preview image requested from the Sanity CDN. |
|
|
118
|
+
| `tooltipPlacement` | automatic | `(item) => Placement`: where a spot's popover opens, e.g. from a field on the item. |
|
|
119
|
+
|
|
120
|
+
Open the popover toward a placement stored on the item:
|
|
96
121
|
|
|
97
122
|
```ts
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
name: 'spots',
|
|
102
|
-
type: 'array',
|
|
103
|
-
options: {hotspotPicker: {imagePath: 'image'}},
|
|
104
|
-
components: {input: HotspotPicker},
|
|
105
|
-
of: [/* ... */],
|
|
123
|
+
hotspotPicker({
|
|
124
|
+
item: {fields: [defineField({name: 'placement', type: 'string'})]},
|
|
125
|
+
tooltipPlacement: (item) => (item.placement === 'left' ? 'left' : undefined),
|
|
106
126
|
})
|
|
107
127
|
```
|
|
108
128
|
|
|
109
129
|
## Stored value
|
|
110
130
|
|
|
111
131
|
```ts
|
|
112
|
-
|
|
132
|
+
desktop: {
|
|
133
|
+
_type: 'hotspotImage',
|
|
134
|
+
image: {_type: 'image', asset: {_ref: 'image-…'}, crop: {…}, hotspot: {…}},
|
|
135
|
+
items: [
|
|
136
|
+
{_key: 'a1b2c3d4e5f6', _type: 'spot', reference: {_ref: '…', _type: 'reference'}, x: 42.5, y: 61.25},
|
|
137
|
+
],
|
|
138
|
+
}
|
|
113
139
|
```
|
|
114
140
|
|
|
115
141
|
`x` and `y` are percentages (0–100, two decimals) from the image's top-left corner, measured on the cropped image.
|
|
116
142
|
|
|
117
143
|
## GROQ
|
|
118
144
|
|
|
145
|
+
The query mirrors the schema:
|
|
146
|
+
|
|
119
147
|
```groq
|
|
120
148
|
*[_type == "page"][0]{
|
|
121
|
-
|
|
122
|
-
|
|
149
|
+
desktop{
|
|
150
|
+
image,
|
|
151
|
+
items[]{_key, x, y, "product": reference->{title, slug}}
|
|
152
|
+
}
|
|
123
153
|
}
|
|
124
154
|
```
|
|
125
155
|
|
|
126
|
-
|
|
156
|
+
Render the image with its crop, then position each spot over it with `left: ${x}%; top: ${y}%`.
|
|
157
|
+
|
|
158
|
+
## On your own array field
|
|
159
|
+
|
|
160
|
+
Without the object type, any array of objects can be a spot picker over a sibling image field. Add `options.hotspotPicker`, and give each item `x`/`y` fields with `hotspotFields()`:
|
|
161
|
+
|
|
162
|
+
```ts
|
|
163
|
+
import {defineArrayMember, defineField} from 'sanity'
|
|
164
|
+
import {hotspotFields} from 'sanity-plugin-hotspot-picker'
|
|
165
|
+
|
|
166
|
+
// in an object or document type
|
|
167
|
+
fields: [
|
|
168
|
+
defineField({name: 'image', type: 'image', options: {hotspot: true}}),
|
|
169
|
+
defineField({
|
|
170
|
+
name: 'spots',
|
|
171
|
+
type: 'array',
|
|
172
|
+
options: {hotspotPicker: {imagePath: 'image'}}, // relative to the array's parent; dots for nesting
|
|
173
|
+
of: [
|
|
174
|
+
defineArrayMember({
|
|
175
|
+
name: 'spot',
|
|
176
|
+
type: 'object',
|
|
177
|
+
fields: [
|
|
178
|
+
...hotspotFields(),
|
|
179
|
+
defineField({name: 'product', type: 'reference', to: [{type: 'product'}]}),
|
|
180
|
+
],
|
|
181
|
+
}),
|
|
182
|
+
],
|
|
183
|
+
}),
|
|
184
|
+
]
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
The plugin's `icon`, `imageWidth` and `tooltipPlacement` apply here too; a field's `options.hotspotPicker` overrides them (`hotspotPicker: true` uses the plugin's). Without the plugin, set the input yourself with `components: {input: HotspotPicker}`.
|
|
188
|
+
|
|
189
|
+
## Releasing
|
|
190
|
+
|
|
191
|
+
Publishing runs from GitHub Actions; nobody runs `npm publish` locally.
|
|
192
|
+
|
|
193
|
+
1. Bump `version` in `package.json` in your PR (`1.2.0-beta.1` style versions publish under `next`).
|
|
194
|
+
2. Merge to `main`. The Publish workflow publishes that version to npm with provenance, then tags it and creates the GitHub release `v<version>`. A merge without a version bump publishes nothing.
|
|
195
|
+
|
|
196
|
+
CI runs lint, typecheck and the build on every PR and push to `main`, and `prepublishOnly` runs them again before publishing.
|
|
127
197
|
|
|
128
198
|
## License
|
|
129
199
|
|
package/dist/index.d.ts
CHANGED
|
@@ -126,9 +126,9 @@ export declare interface HotspotPickerPluginOptions extends Omit<
|
|
|
126
126
|
/** Overrides for the `image` field (`fields`, `options`, `title`...). Hotspot/crop is on. */
|
|
127
127
|
image?: Partial<Omit<ImageDefinition, 'name' | 'type'>>
|
|
128
128
|
/**
|
|
129
|
-
* Each item's `reference` field
|
|
130
|
-
*
|
|
131
|
-
*
|
|
129
|
+
* Each item's `reference` field; `to` is required (e.g. a Product reference to the `product`
|
|
130
|
+
* type). Required by default. The spot's popover previews the referenced document. Leave out
|
|
131
|
+
* for items without a reference.
|
|
132
132
|
*/
|
|
133
133
|
reference?: Omit<ReferenceDefinition, 'name' | 'type'>
|
|
134
134
|
/** The items in the `items` array. */
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "sanity-plugin-hotspot-picker",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "A Sanity Studio array input that places each item as a draggable spot on a sibling image field.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"sanity",
|
|
@@ -40,7 +40,7 @@
|
|
|
40
40
|
"format": "prettier --write --cache --ignore-unknown .",
|
|
41
41
|
"link-watch": "plugin-kit link-watch",
|
|
42
42
|
"lint": "eslint .",
|
|
43
|
-
"prepublishOnly": "npm run build",
|
|
43
|
+
"prepublishOnly": "npm run lint && npm run typecheck && npm run build",
|
|
44
44
|
"typecheck": "tsc --noEmit",
|
|
45
45
|
"watch": "pkg-utils watch --strict"
|
|
46
46
|
},
|