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 CHANGED
@@ -1,13 +1,15 @@
1
1
  # sanity-plugin-hotspot-picker
2
2
 
3
- A Sanity Studio array input that places each item as a draggable spot on an image field: shoppable images, annotated diagrams, store maps.
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. Hover to see the item's preview.
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**: the preview uses the image field's crop, so positions match a cropped image on your frontend.
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: [hotspotPicker()],
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
- Add `options.hotspotPicker` to an array of objects, next to the image field the spots sit on. Each item needs `x` and `y` number fields; `hotspotFields()` returns them, hidden and read-only.
39
+ The plugin registers a `hotspotImage` object type. Use it like any other type:
34
40
 
35
41
  ```ts
36
- import {defineArrayMember, defineField, defineType} from 'sanity'
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: 'image', type: 'image', options: {hotspot: true}}),
44
- defineField({
45
- name: 'spots',
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
- ### Options
55
+ Each `hotspotImage` has two fields:
71
56
 
72
- Pass options to the plugin to set defaults for every field. A field's `options.hotspotPicker` overrides them (`hotspotPicker: true` uses the defaults).
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
- | Option | Default | |
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
- Open the preview toward a placement stored on the item:
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
- tooltipPlacement: (item) => {
86
- const placement = item.placement as {vertical?: string; horizontal?: string} | undefined
87
- if (placement?.vertical === 'top' && placement.horizontal === 'right') return 'top-start'
88
- return undefined
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
- ### Without the plugin
94
-
95
- Use the input on one field:
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
- import {HotspotPicker} from 'sanity-plugin-hotspot-picker'
99
-
100
- defineField({
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
- spots: [{_key: 'a1b2c3d4e5f6', _type: 'spot', x: 42.5, y: 61.25, product: {_ref: '…'}}]
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
- image,
122
- spots[]{_key, x, y, "product": product->{title, slug}}
149
+ desktop{
150
+ image,
151
+ items[]{_key, x, y, "product": reference->{title, slug}}
152
+ }
123
153
  }
124
154
  ```
125
155
 
126
- Position each spot with `left: ${x}%; top: ${y}%` over an image rendered with the same crop.
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 (`to` is required), e.g. `{title: 'Product', to: [{type:
130
- * 'product'}]}`. Required by default. The spot's tooltip previews the referenced document.
131
- * Leave out for items without a reference.
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.0",
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
  },