@aphexcms/visual-editing 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.
@@ -0,0 +1,32 @@
1
+ <script lang="ts">
2
+ import type { Snippet } from 'svelte';
3
+ import { setLivePreviewContext } from './live-preview.svelte.js';
4
+ import { enableAphexPreview } from './core.js';
5
+
6
+ interface Props {
7
+ /**
8
+ * Whether to use stega encoding for auto-detecting fields.
9
+ * Must match the setting in DocumentEditor / aphex.config.ts. Default: true.
10
+ */
11
+ stega?: boolean;
12
+ children?: Snippet;
13
+ }
14
+
15
+ let { stega = true, children }: Props = $props();
16
+
17
+ const preview = setLivePreviewContext();
18
+
19
+ $effect(() => {
20
+ if (typeof window === 'undefined') return;
21
+ if (!new URLSearchParams(window.location.search).has('aphex-preview')) return;
22
+
23
+ return enableAphexPreview({
24
+ stega,
25
+ onData: (doc) => {
26
+ preview.current = doc;
27
+ }
28
+ });
29
+ });
30
+ </script>
31
+
32
+ {@render children?.()}
@@ -0,0 +1,13 @@
1
+ import type { Snippet } from 'svelte';
2
+ interface Props {
3
+ /**
4
+ * Whether to use stega encoding for auto-detecting fields.
5
+ * Must match the setting in DocumentEditor / aphex.config.ts. Default: true.
6
+ */
7
+ stega?: boolean;
8
+ children?: Snippet;
9
+ }
10
+ declare const AphexVisualOverlay: import("svelte").Component<Props, {}, "">;
11
+ type AphexVisualOverlay = ReturnType<typeof AphexVisualOverlay>;
12
+ export default AphexVisualOverlay;
13
+ //# sourceMappingURL=AphexVisualOverlay.svelte.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AphexVisualOverlay.svelte.d.ts","sourceRoot":"","sources":["../src/lib/AphexVisualOverlay.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAKrC,UAAU,KAAK;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACnB;AA4BF,QAAA,MAAM,kBAAkB,2CAAwC,CAAC;AACjE,KAAK,kBAAkB,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAChE,eAAe,kBAAkB,CAAC"}
package/dist/core.d.ts ADDED
@@ -0,0 +1,24 @@
1
+ export interface AphexPreviewOptions {
2
+ /**
3
+ * Whether to scan DOM text nodes for stega markers and auto-stamp data-aphex-field.
4
+ * Set to false if you add data-aphex-field attributes manually. Default: true.
5
+ */
6
+ stega?: boolean;
7
+ /** Called whenever the CMS pushes a new document snapshot via postMessage. */
8
+ onData?: (doc: Record<string, unknown>) => void;
9
+ }
10
+ /**
11
+ * Vanilla JS entry point for Aphex live preview.
12
+ * Call this once in your frontend (framework-agnostic).
13
+ * Returns a cleanup function — call it on unmount.
14
+ *
15
+ * @example
16
+ * // SvelteKit
17
+ * $effect(() => enableAphexPreview({ onData: (doc) => { preview.current = doc; } }));
18
+ *
19
+ * // Vanilla / React useEffect
20
+ * const cleanup = enableAphexPreview({ onData: setPost });
21
+ * return cleanup;
22
+ */
23
+ export declare function enableAphexPreview(options?: AphexPreviewOptions): () => void;
24
+ //# sourceMappingURL=core.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/lib/core.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,mBAAmB;IACnC;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CAChD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,MAAM,IAAI,CAqNhF"}
package/dist/core.js ADDED
@@ -0,0 +1,204 @@
1
+ import { stegaDecode } from './stega.js';
2
+ /**
3
+ * Vanilla JS entry point for Aphex live preview.
4
+ * Call this once in your frontend (framework-agnostic).
5
+ * Returns a cleanup function — call it on unmount.
6
+ *
7
+ * @example
8
+ * // SvelteKit
9
+ * $effect(() => enableAphexPreview({ onData: (doc) => { preview.current = doc; } }));
10
+ *
11
+ * // Vanilla / React useEffect
12
+ * const cleanup = enableAphexPreview({ onData: setPost });
13
+ * return cleanup;
14
+ */
15
+ export function enableAphexPreview(options = {}) {
16
+ const { stega = true, onData } = options;
17
+ if (typeof window === 'undefined' || window.parent === window)
18
+ return () => { };
19
+ // Accent matches the studio's --primary (orange) so the preview overlay and the
20
+ // editor's field-focus ring read as the same highlight.
21
+ const ACCENT = 'oklch(0.62 0.14 39.04)';
22
+ const ACCENT_FADE = 'oklch(0.62 0.14 39.04 / 0)';
23
+ // Cursor style for all field elements
24
+ const style = document.createElement('style');
25
+ style.textContent = '[data-aphex-field] { cursor: pointer !important; }';
26
+ document.head.appendChild(style);
27
+ // Floating overlay
28
+ const overlay = document.createElement('div');
29
+ const label = document.createElement('span');
30
+ overlay.style.cssText = [
31
+ 'position:fixed',
32
+ 'pointer-events:none',
33
+ `border:2px solid ${ACCENT}`,
34
+ 'border-radius:4px',
35
+ 'z-index:2147483647',
36
+ 'display:none',
37
+ 'box-sizing:border-box',
38
+ 'transition:top 60ms,left 60ms,width 60ms,height 60ms'
39
+ ].join(';');
40
+ label.style.cssText = [
41
+ 'position:absolute',
42
+ 'top:0',
43
+ 'left:0',
44
+ 'transform:translateY(-100%)',
45
+ `background:${ACCENT}`,
46
+ 'color:#fff',
47
+ 'font-size:10px',
48
+ 'font-weight:600',
49
+ 'line-height:1',
50
+ 'padding:3px 7px',
51
+ 'border-radius:3px 3px 0 0',
52
+ 'white-space:nowrap',
53
+ 'font-family:ui-monospace,monospace',
54
+ 'text-transform:uppercase',
55
+ 'letter-spacing:0.05em'
56
+ ].join(';');
57
+ overlay.appendChild(label);
58
+ document.body.appendChild(overlay);
59
+ // Stamp decoded navigation data onto an element (only if not already set, so the
60
+ // first/outermost source wins and re-scans stay idempotent).
61
+ function stamp(el, decoded) {
62
+ if (!el.dataset.aphexField)
63
+ el.dataset.aphexField = decoded.field;
64
+ if (decoded.blockIndex != null && !el.dataset.aphexBlockIndex) {
65
+ el.dataset.aphexBlockIndex = String(decoded.blockIndex);
66
+ }
67
+ if (decoded.blockKey && !el.dataset.aphexBlockKey) {
68
+ el.dataset.aphexBlockKey = decoded.blockKey;
69
+ }
70
+ if (decoded.arrayIndex != null && !el.dataset.aphexArrayIndex) {
71
+ el.dataset.aphexArrayIndex = String(decoded.arrayIndex);
72
+ }
73
+ if (decoded.objectPath && !el.dataset.aphexObjectPath) {
74
+ el.dataset.aphexObjectPath = decoded.objectPath;
75
+ }
76
+ }
77
+ // Stega rides in two places: text node content, and a few attributes carrying human
78
+ // text. Images have no text node, so they become click-to-edit via their `alt`; dates
79
+ // via `datetime`; otherwise-textless elements via `aria-label`.
80
+ const ATTR_TARGETS = [
81
+ ['img[alt]', 'alt'],
82
+ ['time[datetime]', 'datetime'],
83
+ ['[aria-label]', 'aria-label']
84
+ ];
85
+ // Walk text nodes + scan attributes for stega markers and stamp navigation data.
86
+ function scanStega() {
87
+ if (!stega)
88
+ return;
89
+ const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
90
+ let node;
91
+ while ((node = walker.nextNode())) {
92
+ const decoded = stegaDecode(node.textContent ?? '');
93
+ if (decoded?.field && node.parentElement)
94
+ stamp(node.parentElement, decoded);
95
+ }
96
+ for (const [selector, attr] of ATTR_TARGETS) {
97
+ document.querySelectorAll(selector).forEach((el) => {
98
+ const decoded = stegaDecode(el.getAttribute(attr) ?? '');
99
+ if (decoded?.field)
100
+ stamp(el, decoded);
101
+ });
102
+ }
103
+ }
104
+ scanStega();
105
+ let editMode = true;
106
+ let activeEl = null;
107
+ function positionOn(el) {
108
+ const r = el.getBoundingClientRect();
109
+ overlay.style.left = `${r.left - 2}px`;
110
+ overlay.style.top = `${r.top - 2}px`;
111
+ overlay.style.width = `${r.width + 4}px`;
112
+ overlay.style.height = `${r.height + 4}px`;
113
+ }
114
+ function showOn(el) {
115
+ activeEl = el;
116
+ label.textContent = el.dataset.aphexField ?? '';
117
+ positionOn(el);
118
+ overlay.style.display = 'block';
119
+ }
120
+ function hide() {
121
+ activeEl = null;
122
+ overlay.style.display = 'none';
123
+ }
124
+ const onMouseOver = (e) => {
125
+ if (!editMode)
126
+ return;
127
+ const el = e.target.closest('[data-aphex-field]');
128
+ el ? showOn(el) : hide();
129
+ };
130
+ const onClick = (e) => {
131
+ // Always prevent default — links/buttons must not navigate in preview
132
+ e.preventDefault();
133
+ if (!editMode)
134
+ return;
135
+ const el = e.target.closest('[data-aphex-field]');
136
+ if (el?.dataset.aphexField) {
137
+ e.stopPropagation();
138
+ const d = el.dataset;
139
+ // If the click landed on (or inside) a link, pass its href so the editor
140
+ // can drop the cursor inside that link and open the link editor instead
141
+ // of just focusing the block.
142
+ const anchor = e.target.closest('a');
143
+ const linkHref = anchor?.getAttribute('href') ?? undefined;
144
+ window.parent.postMessage({
145
+ type: 'aphex:field-click',
146
+ fieldPath: d.aphexField,
147
+ blockIndex: d.aphexBlockIndex != null ? parseInt(d.aphexBlockIndex, 10) : undefined,
148
+ blockKey: d.aphexBlockKey ?? undefined,
149
+ arrayIndex: d.aphexArrayIndex != null ? parseInt(d.aphexArrayIndex, 10) : undefined,
150
+ objectPath: d.aphexObjectPath ?? undefined,
151
+ linkHref
152
+ }, '*');
153
+ }
154
+ };
155
+ const onScroll = () => {
156
+ if (activeEl)
157
+ positionOn(activeEl);
158
+ };
159
+ const onMessage = (e) => {
160
+ if (!e.data || typeof e.data !== 'object')
161
+ return;
162
+ const { type, fieldPath, document: doc } = e.data;
163
+ if (type === 'aphex:edit-mode') {
164
+ editMode = e.data.enabled;
165
+ if (!editMode) {
166
+ hide();
167
+ style.textContent = '';
168
+ }
169
+ else {
170
+ style.textContent = '[data-aphex-field] { cursor: pointer !important; }';
171
+ }
172
+ }
173
+ else if (type === 'aphex:data' && doc) {
174
+ onData?.(doc);
175
+ // Re-scan after the framework re-renders with the new stega-encoded values
176
+ requestAnimationFrame(scanStega);
177
+ }
178
+ else if (type === 'aphex:field-focus' && fieldPath) {
179
+ const el = document.querySelector(`[data-aphex-field="${fieldPath}"]`);
180
+ if (!el)
181
+ return;
182
+ el.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
183
+ showOn(el);
184
+ el.animate([
185
+ { outline: `3px solid ${ACCENT}`, outlineOffset: '4px' },
186
+ { outline: `3px solid ${ACCENT_FADE}`, outlineOffset: '8px' }
187
+ ], { duration: 1200, easing: 'ease-out', fill: 'none' });
188
+ setTimeout(hide, 1200);
189
+ }
190
+ };
191
+ document.addEventListener('mouseover', onMouseOver);
192
+ document.addEventListener('click', onClick, true);
193
+ window.addEventListener('scroll', onScroll, true);
194
+ window.addEventListener('message', onMessage);
195
+ window.parent.postMessage({ type: 'aphex:ready', stega }, '*');
196
+ return () => {
197
+ document.removeEventListener('mouseover', onMouseOver);
198
+ document.removeEventListener('click', onClick, true);
199
+ window.removeEventListener('scroll', onScroll, true);
200
+ window.removeEventListener('message', onMessage);
201
+ overlay.remove();
202
+ style.remove();
203
+ };
204
+ }
@@ -0,0 +1,8 @@
1
+ export { default as AphexVisualOverlay } from './AphexVisualOverlay.svelte';
2
+ export { isPreviewMode } from './preview.js';
3
+ export { enableAphexPreview, type AphexPreviewOptions } from './core.js';
4
+ export { getLivePreviewDocument } from './live-preview.svelte.js';
5
+ export { usePreview, setPortableTextField, type PreviewApi, type EncodePayload, type ResolvedImage } from './use-preview.svelte.js';
6
+ export { stegaClean, stegaDecode, stegaEncode, type StegaPayload } from './stega.js';
7
+ export type { AphexOutboundMessage, AphexInboundMessage } from './types.js';
8
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACzE,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EACN,UAAU,EACV,oBAAoB,EACpB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACrF,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,6 @@
1
+ export { default as AphexVisualOverlay } from './AphexVisualOverlay.svelte';
2
+ export { isPreviewMode } from './preview.js';
3
+ export { enableAphexPreview } from './core.js';
4
+ export { getLivePreviewDocument } from './live-preview.svelte.js';
5
+ export { usePreview, setPortableTextField } from './use-preview.svelte.js';
6
+ export { stegaClean, stegaDecode, stegaEncode } from './stega.js';
@@ -0,0 +1,11 @@
1
+ export declare class LivePreviewContext {
2
+ current: Record<string, unknown> | null;
3
+ }
4
+ export declare function setLivePreviewContext(): LivePreviewContext;
5
+ /**
6
+ * Returns the live preview document context set by <AphexVisualOverlay>.
7
+ * `preview.current` is null until the CMS pushes data via postMessage.
8
+ * Use as: `const post = $derived(preview.current ?? data.post)`
9
+ */
10
+ export declare function getLivePreviewDocument(): LivePreviewContext;
11
+ //# sourceMappingURL=live-preview.svelte.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"live-preview.svelte.d.ts","sourceRoot":"","sources":["../src/lib/live-preview.svelte.ts"],"names":[],"mappings":"AAIA,qBAAa,kBAAkB;IAC9B,OAAO,iCAAgD;CACvD;AAED,wBAAgB,qBAAqB,IAAI,kBAAkB,CAI1D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,kBAAkB,CAE3D"}
@@ -0,0 +1,18 @@
1
+ import { getContext, setContext } from 'svelte';
2
+ const KEY = Symbol('aphex:live-preview');
3
+ export class LivePreviewContext {
4
+ current = $state(null);
5
+ }
6
+ export function setLivePreviewContext() {
7
+ const ctx = new LivePreviewContext();
8
+ setContext(KEY, ctx);
9
+ return ctx;
10
+ }
11
+ /**
12
+ * Returns the live preview document context set by <AphexVisualOverlay>.
13
+ * `preview.current` is null until the CMS pushes data via postMessage.
14
+ * Use as: `const post = $derived(preview.current ?? data.post)`
15
+ */
16
+ export function getLivePreviewDocument() {
17
+ return getContext(KEY) ?? new LivePreviewContext();
18
+ }
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Whether the current URL is in preview mode (has the `aphex-preview` marker).
3
+ * Safe to call client-side — it only reports the param's presence and does NOT
4
+ * grant access to draft content.
5
+ *
6
+ * To resolve the actual content perspective (draft vs published) use
7
+ * `getPreviewPerspective(locals.auth, url)` from `@aphexcms/cms-core/server`
8
+ * inside a load function — draft access is gated on an authenticated session,
9
+ * so appending `?aphex-preview` alone never exposes drafts.
10
+ */
11
+ export declare function isPreviewMode(url: URL): boolean;
12
+ //# sourceMappingURL=preview.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../src/lib/preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAE/C"}
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Whether the current URL is in preview mode (has the `aphex-preview` marker).
3
+ * Safe to call client-side — it only reports the param's presence and does NOT
4
+ * grant access to draft content.
5
+ *
6
+ * To resolve the actual content perspective (draft vs published) use
7
+ * `getPreviewPerspective(locals.auth, url)` from `@aphexcms/cms-core/server`
8
+ * inside a load function — draft access is gated on an authenticated session,
9
+ * so appending `?aphex-preview` alone never exposes drafts.
10
+ */
11
+ export function isPreviewMode(url) {
12
+ return url.searchParams.has('aphex-preview');
13
+ }
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Remove all stega-encoded data from a string or deep JSON structure.
3
+ * Use in <svelte:head> (title, meta), alt text, aria-labels, comparisons.
4
+ */
5
+ export declare function stegaClean<T>(value: T): T;
6
+ export type StegaPayload = {
7
+ field: string;
8
+ blockIndex?: number;
9
+ blockKey?: string;
10
+ arrayIndex?: number;
11
+ objectPath?: string;
12
+ };
13
+ /**
14
+ * Stamp a navigation payload onto a string as invisible stega characters.
15
+ *
16
+ * The CMS auto-encodes a document's own string fields, but values that aren't
17
+ * literally in the document — a resolved `reference` label, a denormalized
18
+ * title — have nothing to stamp. Encode those at render time so the overlay
19
+ * treats them like any other clickable field. Returns the value unchanged if
20
+ * it's empty.
21
+ */
22
+ export declare function stegaEncode(value: string, payload: StegaPayload): string;
23
+ /** Decode the stega payload from a string. Returns null if not encoded. */
24
+ export declare function stegaDecode(value: string): StegaPayload | null;
25
+ //# sourceMappingURL=stega.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"stega.d.ts","sourceRoot":"","sources":["../src/lib/stega.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAEzC;AAED,MAAM,MAAM,YAAY,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,CAGxE;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAE9D"}
package/dist/stega.js ADDED
@@ -0,0 +1,26 @@
1
+ import { vercelStegaClean, vercelStegaCombine, vercelStegaDecode } from '@vercel/stega';
2
+ /**
3
+ * Remove all stega-encoded data from a string or deep JSON structure.
4
+ * Use in <svelte:head> (title, meta), alt text, aria-labels, comparisons.
5
+ */
6
+ export function stegaClean(value) {
7
+ return vercelStegaClean(value);
8
+ }
9
+ /**
10
+ * Stamp a navigation payload onto a string as invisible stega characters.
11
+ *
12
+ * The CMS auto-encodes a document's own string fields, but values that aren't
13
+ * literally in the document — a resolved `reference` label, a denormalized
14
+ * title — have nothing to stamp. Encode those at render time so the overlay
15
+ * treats them like any other clickable field. Returns the value unchanged if
16
+ * it's empty.
17
+ */
18
+ export function stegaEncode(value, payload) {
19
+ if (!value)
20
+ return value;
21
+ return vercelStegaCombine(value, payload);
22
+ }
23
+ /** Decode the stega payload from a string. Returns null if not encoded. */
24
+ export function stegaDecode(value) {
25
+ return vercelStegaDecode(value) ?? null;
26
+ }
@@ -0,0 +1,27 @@
1
+ export type AphexOutboundMessage = {
2
+ type: 'aphex:ready';
3
+ stega: boolean;
4
+ } | {
5
+ type: 'aphex:field-click';
6
+ fieldPath: string;
7
+ blockIndex?: number;
8
+ blockKey?: string;
9
+ arrayIndex?: number;
10
+ objectPath?: string;
11
+ /** href of the clicked link, when the click landed on an anchor. */
12
+ linkHref?: string;
13
+ documentId?: string;
14
+ };
15
+ export type AphexInboundMessage = {
16
+ type: 'aphex:field-focus';
17
+ fieldPath: string;
18
+ } | {
19
+ type: 'aphex:data';
20
+ document: Record<string, unknown>;
21
+ } | {
22
+ type: 'aphex:edit-mode';
23
+ enabled: boolean;
24
+ } | {
25
+ type: 'aphex:refresh';
26
+ };
27
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/lib/types.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,oBAAoB,GAC7B;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACvC;IACA,IAAI,EAAE,mBAAmB,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAGL,MAAM,MAAM,mBAAmB,GAC5B;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC"}
package/dist/types.js ADDED
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,61 @@
1
+ import { type StegaPayload } from './stega.js';
2
+ /**
3
+ * Declare which document field a Portable Text body belongs to (e.g. `'content'`), so inline
4
+ * blocks rendered by your Portable Text library can encode click-to-edit markers without
5
+ * defining their own context plumbing. Call it in the component that renders the body.
6
+ * Accepts a value or a getter (use a getter to stay reactive to a prop).
7
+ */
8
+ export declare function setPortableTextField(field: string | (() => string)): void;
9
+ /** A payload like {@link StegaPayload} but with `field` optional — it falls back to the
10
+ * Portable Text field context, so inline blocks can omit it. */
11
+ export type EncodePayload = Partial<StegaPayload>;
12
+ type ImageLike = {
13
+ alt?: string;
14
+ asset?: {
15
+ _ref?: string;
16
+ url?: string;
17
+ alt?: string;
18
+ };
19
+ } | null | undefined;
20
+ /** An image field resolved for rendering. */
21
+ export interface ResolvedImage {
22
+ /** Public URL, or `null` if the image/asset is unset. */
23
+ src: string | null;
24
+ /** Effective alt text: per-placement override → asset default → `''`. */
25
+ alt: string;
26
+ }
27
+ export interface PreviewApi {
28
+ /** True while the visual editor is driving this page (a live document has been received). */
29
+ readonly inPreview: boolean;
30
+ /** The live document pushed by the editor, or `null` outside preview. */
31
+ readonly document: Record<string, unknown> | null;
32
+ /** The live document merged over your server fallback: `const post = $derived(ve.live(data.post))`. */
33
+ live<T>(fallback: T): T;
34
+ /**
35
+ * Make a value click-to-edit. In preview it returns the value stega-encoded with the
36
+ * navigation payload; outside preview it returns the value unchanged. `field` defaults to
37
+ * the Portable Text field context when omitted (for inline blocks).
38
+ */
39
+ encode(value: string | null | undefined, payload?: EncodePayload): string;
40
+ /**
41
+ * Resolve an image field to `{ src, alt }` in one call — destructure it:
42
+ * `const { src, alt } = $derived(ve.image(post.coverImage))`. Reads `asset.url`/`asset.alt`,
43
+ * which the server injects at load time and the editor injects into the live document, so
44
+ * the same call works for SSR and for newly-added/swapped images in preview.
45
+ */
46
+ image(img: ImageLike): ResolvedImage;
47
+ }
48
+ /**
49
+ * One-call visual-editing helper for a page or component. Reads the context set by
50
+ * `<AphexVisualOverlay>` (and any Portable Text field context). Call once during init.
51
+ *
52
+ * @example
53
+ * const ve = usePreview();
54
+ * const post = $derived(ve.live(data.post));
55
+ * const cover = $derived(ve.image(post.coverImage));
56
+ * // <time datetime={ve.encode(post.postDate, { field: 'postDate' })}>
57
+ * // <img src={cover.src} alt={ve.encode(cover.alt, { field: 'coverImage' })} />
58
+ */
59
+ export declare function usePreview(): PreviewApi;
60
+ export {};
61
+ //# sourceMappingURL=use-preview.svelte.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"use-preview.svelte.d.ts","sourceRoot":"","sources":["../src/lib/use-preview.svelte.ts"],"names":[],"mappings":"AAEA,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAI5D;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,GAAG,IAAI,CAEzE;AAED;gEACgE;AAChE,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;AAElD,KAAK,SAAS,GACX;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACvE,IAAI,GACJ,SAAS,CAAC;AAEb,6CAA6C;AAC7C,MAAM,WAAW,aAAa;IAC7B,yDAAyD;IACzD,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,UAAU;IAC1B,6FAA6F;IAC7F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAClD,uGAAuG;IACvG,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;IACxB;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC;IAC1E;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,SAAS,GAAG,aAAa,CAAC;CACrC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,IAAI,UAAU,CA4BvC"}
@@ -0,0 +1,54 @@
1
+ import { getContext, setContext } from 'svelte';
2
+ import { getLivePreviewDocument } from './live-preview.svelte.js';
3
+ import { stegaEncode } from './stega.js';
4
+ const PT_FIELD_KEY = Symbol('aphex:pt-field');
5
+ /**
6
+ * Declare which document field a Portable Text body belongs to (e.g. `'content'`), so inline
7
+ * blocks rendered by your Portable Text library can encode click-to-edit markers without
8
+ * defining their own context plumbing. Call it in the component that renders the body.
9
+ * Accepts a value or a getter (use a getter to stay reactive to a prop).
10
+ */
11
+ export function setPortableTextField(field) {
12
+ setContext(PT_FIELD_KEY, typeof field === 'function' ? field : () => field);
13
+ }
14
+ /**
15
+ * One-call visual-editing helper for a page or component. Reads the context set by
16
+ * `<AphexVisualOverlay>` (and any Portable Text field context). Call once during init.
17
+ *
18
+ * @example
19
+ * const ve = usePreview();
20
+ * const post = $derived(ve.live(data.post));
21
+ * const cover = $derived(ve.image(post.coverImage));
22
+ * // <time datetime={ve.encode(post.postDate, { field: 'postDate' })}>
23
+ * // <img src={cover.src} alt={ve.encode(cover.alt, { field: 'coverImage' })} />
24
+ */
25
+ export function usePreview() {
26
+ const ctx = getLivePreviewDocument();
27
+ const ptField = getContext(PT_FIELD_KEY);
28
+ return {
29
+ get inPreview() {
30
+ return ctx.current != null;
31
+ },
32
+ get document() {
33
+ return ctx.current;
34
+ },
35
+ live(fallback) {
36
+ return ctx.current ?? fallback;
37
+ },
38
+ encode(value, payload = {}) {
39
+ const raw = value ?? '';
40
+ if (ctx.current == null)
41
+ return raw; // not in preview — leave the value clean
42
+ const field = payload.field ?? ptField?.();
43
+ if (!field)
44
+ return raw; // nothing to navigate to
45
+ return stegaEncode(raw || ' ', { ...payload, field });
46
+ },
47
+ image(img) {
48
+ return {
49
+ src: img?.asset?.url ?? null, // injected at load (server) or into the live doc (editor)
50
+ alt: img?.alt || img?.asset?.alt || '' // per-placement override → asset default
51
+ };
52
+ }
53
+ };
54
+ }
package/package.json ADDED
@@ -0,0 +1,49 @@
1
+ {
2
+ "name": "@aphexcms/visual-editing",
3
+ "version": "0.1.1",
4
+ "description": "Visual editing overlay for AphexCMS — add click-to-edit overlays to your frontend",
5
+ "license": "MIT",
6
+ "publishConfig": {
7
+ "access": "public",
8
+ "provenance": true
9
+ },
10
+ "repository": {
11
+ "type": "git",
12
+ "url": "https://github.com/IcelandicIcecream/aphex.git",
13
+ "directory": "packages/visual-editing"
14
+ },
15
+ "type": "module",
16
+ "main": "./dist/index.js",
17
+ "types": "./dist/index.d.ts",
18
+ "svelte": "./dist/index.js",
19
+ "exports": {
20
+ ".": {
21
+ "types": "./dist/index.d.ts",
22
+ "svelte": "./dist/index.js",
23
+ "default": "./dist/index.js"
24
+ }
25
+ },
26
+ "files": [
27
+ "dist"
28
+ ],
29
+ "scripts": {
30
+ "dev": "tsc --watch --preserveWatchOutput",
31
+ "build": "svelte-package",
32
+ "check": "svelte-check --tsconfig ./tsconfig.json",
33
+ "dev:local": "node ../../scripts/swap-package-paths.js ./package.json src lib",
34
+ "prepack": "node ../../scripts/swap-package-paths.js ./package.json dist lib",
35
+ "postpack": "node ../../scripts/swap-package-paths.js ./package.json src lib"
36
+ },
37
+ "devDependencies": {
38
+ "@sveltejs/package": "^2.5.6",
39
+ "svelte": "^5.0.0",
40
+ "svelte-check": "^4.0.0",
41
+ "typescript": "^5.9.3"
42
+ },
43
+ "peerDependencies": {
44
+ "svelte": "^5.0.0"
45
+ },
46
+ "dependencies": {
47
+ "@vercel/stega": "^1.1.0"
48
+ }
49
+ }