@shapio/visual 0.2.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,36 @@
+# @shapio/visual
+
+Visual editing for sites built on [Shapio](https://github.com/mybrokengnome/shapio): mark the elements that show
+a field, run one script on the preview page, and in Shapio's preview pane a click on the page focuses that field
+in the document. Saves re-render the page. No dependencies, no framework required.
+
+```sh
+npm install @shapio/visual
+```
+
+```tsx
+import { initVisualEditing, shapioAttr } from '@shapio/visual';
+
+// Anywhere a field is rendered (published pages may carry the attributes too):
+<h1 {...shapioAttr(article, 'title')}>{article.title}</h1>
+<h2 {...shapioAttr(page, `sections/${index}/heading`)}>{section.heading}</h2>
+
+// On the preview page, once:
+initVisualEditing({ origin: 'https://cms.example.com', onRefresh: () => renderDraft() });
+```
+
+- `shapioAttr(entry, path, locale?)` returns `data-shapio-entry`, `data-shapio-path` and `data-shapio-locale` as
+  an object to spread. `entry` is a delivery item (`{ id, locale }`) or an entry ID; `path` uses API IDs, with
+  list positions and nested fields after slashes.
+- `initVisualEditing({ origin, onRefresh? })` runs only inside a frame on a URL with `?shapio-visual=1`. It
+  outlines marked elements on hover, posts the clicked field to the parent window with `origin` as the target
+  (the only origin it talks to), and on a refresh request from that origin calls `onRefresh`, or reloads the
+  page when there is none. It returns a function that turns it off.
+- Plain script: `dist/visual.iife.js` (`@shapio/visual/global`) exposes `window.ShapioVisual`, and starts by
+  itself when its `<script>` tag has `data-shapio-origin="https://cms.example.com"`.
+
+The site also sends `Content-Security-Policy: frame-ancestors 'self' https://cms.example.com`, so only it and
+Shapio can frame its pages. The full guide, including the security model:
+[Visual editing](https://github.com/mybrokengnome/shapio/blob/main/documentation/visual-editing.md).
+
+Apache-2.0.

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+//#region src/attributes.d.ts
+/**
+ * The attributes a site puts on an element that shows a field, so Shapio's preview can take a click on it back
+ * to that field: `<h1 {...shapioAttr(article, 'title')}>`. Paths are API IDs, with list positions and nested
+ * fields after slashes (`sections/2/heading`), the same paths the admin uses.
+ */
+export declare const ENTRY_ATTRIBUTE = "data-shapio-entry";
+export declare const PATH_ATTRIBUTE = "data-shapio-path";
+export declare const LOCALE_ATTRIBUTE = "data-shapio-locale";
+type ShapioAttributes = {
+  'data-shapio-entry': string;
+  'data-shapio-path': string;
+  'data-shapio-locale'?: string;
+};
+/** An entry as delivery returns it (`{ id, locale }`), or its ID. */
+type EntryRef = string | {
+  id: string;
+  locale?: string | null | undefined;
+};
+/**
+ * A spreadable attribute object for the element that renders `path` of `entry`. The locale is the one given,
+ * else the entry's own (delivery items carry the locale that served them); it is left out when unknown.
+ */
+export declare const shapioAttr: (entry: EntryRef, path: string, locale?: string) => ShapioAttributes;
+//#endregion
+//#region src/messages.d.ts
+/**
+ * The messages between a site in Shapio's preview frame and the admin around it. Every message carries the
+ * protocol version; anything that does not parse is ignored. Who may send a message (the frame's window from
+ * the preview origin, the parent from the Shapio origin) is checked by each side before parsing.
+ */
+export declare const VISUAL_PROTOCOL_VERSION = 1;
+/** The query parameter the admin adds to a preview URL it frames (`?shapio-visual=1`). */
+export declare const VISUAL_QUERY_PARAM = "shapio-visual";
+type VisualReadyMessage = {
+  type: 'shapio:ready';
+  v: typeof VISUAL_PROTOCOL_VERSION;
+};
+type VisualFocusMessage = {
+  type: 'shapio:focus';
+  v: typeof VISUAL_PROTOCOL_VERSION;
+  entryId: string;
+  /** A JSON pointer of API IDs (`/title`, `/sections/2/heading`). */
+  path: string;
+  locale?: string;
+};
+type VisualRefreshMessage = {
+  type: 'shapio:refresh';
+  v: typeof VISUAL_PROTOCOL_VERSION;
+};
+/** What the site posts to the admin. */
+type SiteMessage = VisualReadyMessage | VisualFocusMessage;
+/** What the admin posts to the site. */
+type AdminMessage = VisualRefreshMessage;
+/** `title`, `/title` or `sections/2/heading` → a JSON pointer (`/sections/2/heading`); undefined if malformed. */
+export declare const normalizeFieldPath: (path: unknown) => string | undefined;
+/** A message from the site, or undefined when the data is not one. */
+export declare const parseSiteMessage: (data: unknown) => SiteMessage | undefined;
+/** A message from the admin, or undefined when the data is not one. */
+export declare const parseAdminMessage: (data: unknown) => AdminMessage | undefined;
+//#endregion
+//#region src/visualEditing.d.ts
+type VisualEditingOptions = {
+  /** Shapio's public URL (or origin). Messages go to this origin only, and only its messages are accepted. */
+  origin: string;
+  /**
+   * Re-renders the page with the current draft after an edit. Without it the page reloads, which is right for a
+   * page that reads its preview token from the URL on every load; a page that drops the token from the address
+   * bar must re-fetch here instead.
+   */
+  onRefresh?: () => void | Promise<void>;
+  /** The window to run in (tests); defaults to the global one. */
+  window?: Window;
+};
+/** Visual editing runs only inside a frame, on a URL the admin opened with `?shapio-visual=1`. */
+export declare const isVisualEditingRequested: (win: Window) => boolean;
+/**
+ * Turns on visual editing when the page is in Shapio's preview frame: outlines elements carrying
+ * `shapioAttr(...)` attributes on hover, tells the admin which field was clicked, and re-renders when the admin
+ * saves. Posts only to the configured Shapio origin and accepts only that origin's messages from the parent
+ * window. Outside the preview frame it does nothing. Returns a function that turns it off.
+ */
+export declare const initVisualEditing: (options: VisualEditingOptions) => (() => void);
+//#endregion
+export type { AdminMessage, EntryRef, ShapioAttributes, SiteMessage, VisualEditingOptions, VisualFocusMessage, VisualReadyMessage, VisualRefreshMessage };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,163 @@
+//#region src/attributes.ts
+/**
+* The attributes a site puts on an element that shows a field, so Shapio's preview can take a click on it back
+* to that field: `<h1 {...shapioAttr(article, 'title')}>`. Paths are API IDs, with list positions and nested
+* fields after slashes (`sections/2/heading`), the same paths the admin uses.
+*/
+const ENTRY_ATTRIBUTE = "data-shapio-entry";
+const PATH_ATTRIBUTE = "data-shapio-path";
+const LOCALE_ATTRIBUTE = "data-shapio-locale";
+/**
+* A spreadable attribute object for the element that renders `path` of `entry`. The locale is the one given,
+* else the entry's own (delivery items carry the locale that served them); it is left out when unknown.
+*/
+const shapioAttr = (entry, path, locale) => {
+	const id = typeof entry === "string" ? entry : entry.id;
+	const entryLocale = locale ?? (typeof entry === "string" ? void 0 : entry.locale ?? void 0);
+	return {
+		[ENTRY_ATTRIBUTE]: id,
+		[PATH_ATTRIBUTE]: path.replace(/^\/+/, ""),
+		...entryLocale ? { [LOCALE_ATTRIBUTE]: entryLocale } : {}
+	};
+};
+//#endregion
+//#region src/messages.ts
+/**
+* The messages between a site in Shapio's preview frame and the admin around it. Every message carries the
+* protocol version; anything that does not parse is ignored. Who may send a message (the frame's window from
+* the preview origin, the parent from the Shapio origin) is checked by each side before parsing.
+*/
+const VISUAL_PROTOCOL_VERSION = 1;
+/** The query parameter the admin adds to a preview URL it frames (`?shapio-visual=1`). */
+const VISUAL_QUERY_PARAM = "shapio-visual";
+const MAX_PATH_LENGTH = 512;
+const MAX_PATH_SEGMENTS = 32;
+const SEGMENT = /^[A-Za-z0-9_~-]+$/;
+const ENTRY_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const LOCALE = /^[A-Za-z0-9-]{1,35}$/;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** `title`, `/title` or `sections/2/heading` → a JSON pointer (`/sections/2/heading`); undefined if malformed. */
+const normalizeFieldPath = (path) => {
+	if (typeof path !== "string" || path.length === 0 || path.length > MAX_PATH_LENGTH) return;
+	const segments = path.replace(/^\//, "").split("/");
+	if (segments.length > MAX_PATH_SEGMENTS || !segments.every((segment) => SEGMENT.test(segment))) return;
+	return `/${segments.join("/")}`;
+};
+/** A message from the site, or undefined when the data is not one. */
+const parseSiteMessage = (data) => {
+	if (!isRecord(data) || data.v !== 1) return;
+	if (data.type === "shapio:ready") return {
+		type: "shapio:ready",
+		v: 1
+	};
+	if (data.type !== "shapio:focus") return;
+	const path = normalizeFieldPath(data.path);
+	if (typeof data.entryId !== "string" || !ENTRY_ID.test(data.entryId) || !path) return;
+	if (data.locale !== void 0 && (typeof data.locale !== "string" || !LOCALE.test(data.locale))) return;
+	return {
+		type: "shapio:focus",
+		v: 1,
+		entryId: data.entryId,
+		path,
+		...typeof data.locale === "string" ? { locale: data.locale } : {}
+	};
+};
+/** A message from the admin, or undefined when the data is not one. */
+const parseAdminMessage = (data) => isRecord(data) && data.v === 1 && data.type === "shapio:refresh" ? {
+	type: "shapio:refresh",
+	v: 1
+} : void 0;
+//#endregion
+//#region src/visualEditing.ts
+/** The attribute on `<html>` while visual editing is on, and on the element under the pointer. */
+const ACTIVE_DOCUMENT_ATTRIBUTE = "data-shapio-visual";
+const HOVER_ATTRIBUTE = "data-shapio-hover";
+const STYLE = `[${ACTIVE_DOCUMENT_ATTRIBUTE}] [${HOVER_ATTRIBUTE}] { outline: 2px dashed #2563eb; outline-offset: 2px; cursor: pointer; }`;
+const NOOP = () => void 0;
+/** Visual editing runs only inside a frame, on a URL the admin opened with `?shapio-visual=1`. */
+const isVisualEditingRequested = (win) => {
+	let framed;
+	try {
+		framed = win.self !== win.top;
+	} catch {
+		framed = true;
+	}
+	return framed && new URL(win.location.href).searchParams.get("shapio-visual") === "1";
+};
+const originOf = (value) => {
+	try {
+		const url = new URL(value);
+		return url.protocol === "http:" || url.protocol === "https:" ? url.origin : void 0;
+	} catch {
+		return;
+	}
+};
+const annotatedFrom = (target) => {
+	const element = target;
+	return typeof element?.closest === "function" ? element.closest(`[${ENTRY_ATTRIBUTE}]`) : null;
+};
+/**
+* Turns on visual editing when the page is in Shapio's preview frame: outlines elements carrying
+* `shapioAttr(...)` attributes on hover, tells the admin which field was clicked, and re-renders when the admin
+* saves. Posts only to the configured Shapio origin and accepts only that origin's messages from the parent
+* window. Outside the preview frame it does nothing. Returns a function that turns it off.
+*/
+const initVisualEditing = (options) => {
+	const win = options.window ?? window;
+	const origin = originOf(options.origin);
+	if (!origin || !isVisualEditingRequested(win)) return NOOP;
+	const doc = win.document;
+	const post = (message) => win.parent.postMessage(message, origin);
+	let hovered = null;
+	const style = doc.createElement("style");
+	style.textContent = STYLE;
+	doc.head.append(style);
+	doc.documentElement.setAttribute(ACTIVE_DOCUMENT_ATTRIBUTE, "");
+	const onPointerOver = (event) => {
+		const element = annotatedFrom(event.target);
+		if (element === hovered) return;
+		hovered?.removeAttribute(HOVER_ATTRIBUTE);
+		hovered = element;
+		hovered?.setAttribute(HOVER_ATTRIBUTE, "");
+	};
+	const onClick = (event) => {
+		const element = annotatedFrom(event.target);
+		const entryId = element?.getAttribute(ENTRY_ATTRIBUTE);
+		const path = element?.getAttribute(PATH_ATTRIBUTE);
+		if (!element || !entryId || !path) return;
+		event.preventDefault();
+		event.stopPropagation();
+		const locale = element.getAttribute(LOCALE_ATTRIBUTE);
+		post({
+			type: "shapio:focus",
+			v: 1,
+			entryId,
+			path,
+			...locale ? { locale } : {}
+		});
+	};
+	const onMessage = (event) => {
+		if (event.source !== win.parent || event.origin !== origin || !parseAdminMessage(event.data)) return;
+		if (options.onRefresh) Promise.resolve().then(options.onRefresh);
+		else win.location.reload();
+	};
+	doc.addEventListener("pointerover", onPointerOver);
+	doc.addEventListener("click", onClick, true);
+	win.addEventListener("message", onMessage);
+	post({
+		type: "shapio:ready",
+		v: 1
+	});
+	return () => {
+		doc.removeEventListener("pointerover", onPointerOver);
+		doc.removeEventListener("click", onClick, true);
+		win.removeEventListener("message", onMessage);
+		hovered?.removeAttribute(HOVER_ATTRIBUTE);
+		doc.documentElement.removeAttribute(ACTIVE_DOCUMENT_ATTRIBUTE);
+		style.remove();
+	};
+};
+//#endregion
+export { ENTRY_ATTRIBUTE, LOCALE_ATTRIBUTE, PATH_ATTRIBUTE, VISUAL_PROTOCOL_VERSION, VISUAL_QUERY_PARAM, initVisualEditing, isVisualEditingRequested, normalizeFieldPath, parseAdminMessage, parseSiteMessage, shapioAttr };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/attributes.ts","../src/messages.ts","../src/visualEditing.ts"],"sourcesContent":["/**\n * The attributes a site puts on an element that shows a field, so Shapio's preview can take a click on it back\n * to that field: `<h1 {...shapioAttr(article, 'title')}>`. Paths are API IDs, with list positions and nested\n * fields after slashes (`sections/2/heading`), the same paths the admin uses.\n */\nexport const ENTRY_ATTRIBUTE = 'data-shapio-entry';\nexport const PATH_ATTRIBUTE = 'data-shapio-path';\nexport const LOCALE_ATTRIBUTE = 'data-shapio-locale';\n\nexport type ShapioAttributes = {\n  'data-shapio-entry': string;\n  'data-shapio-path': string;\n  'data-shapio-locale'?: string;\n};\n\n/** An entry as delivery returns it (`{ id, locale }`), or its ID. */\nexport type EntryRef = string | { id: string; locale?: string | null | undefined };\n\n/**\n * A spreadable attribute object for the element that renders `path` of `entry`. The locale is the one given,\n * else the entry's own (delivery items carry the locale that served them); it is left out when unknown.\n */\nexport const shapioAttr = (entry: EntryRef, path: string, locale?: string): ShapioAttributes => {\n  const id = typeof entry === 'string' ? entry : entry.id;\n  const entryLocale = locale ?? (typeof entry === 'string' ? undefined : (entry.locale ?? undefined));\n  return {\n    [ENTRY_ATTRIBUTE]: id,\n    [PATH_ATTRIBUTE]: path.replace(/^\\/+/, ''),\n    ...(entryLocale ? { [LOCALE_ATTRIBUTE]: entryLocale } : {}),\n  };\n};\n","/**\n * The messages between a site in Shapio's preview frame and the admin around it. Every message carries the\n * protocol version; anything that does not parse is ignored. Who may send a message (the frame's window from\n * the preview origin, the parent from the Shapio origin) is checked by each side before parsing.\n */\nexport const VISUAL_PROTOCOL_VERSION = 1;\n/** The query parameter the admin adds to a preview URL it frames (`?shapio-visual=1`). */\nexport const VISUAL_QUERY_PARAM = 'shapio-visual';\n\nexport type VisualReadyMessage = { type: 'shapio:ready'; v: typeof VISUAL_PROTOCOL_VERSION };\nexport type VisualFocusMessage = {\n  type: 'shapio:focus';\n  v: typeof VISUAL_PROTOCOL_VERSION;\n  entryId: string;\n  /** A JSON pointer of API IDs (`/title`, `/sections/2/heading`). */\n  path: string;\n  locale?: string;\n};\nexport type VisualRefreshMessage = { type: 'shapio:refresh'; v: typeof VISUAL_PROTOCOL_VERSION };\n\n/** What the site posts to the admin. */\nexport type SiteMessage = VisualReadyMessage | VisualFocusMessage;\n/** What the admin posts to the site. */\nexport type AdminMessage = VisualRefreshMessage;\n\nconst MAX_PATH_LENGTH = 512;\nconst MAX_PATH_SEGMENTS = 32;\nconst SEGMENT = /^[A-Za-z0-9_~-]+$/;\nconst ENTRY_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\nconst LOCALE = /^[A-Za-z0-9-]{1,35}$/;\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value);\n\n/** `title`, `/title` or `sections/2/heading` → a JSON pointer (`/sections/2/heading`); undefined if malformed. */\nexport const normalizeFieldPath = (path: unknown): string | undefined => {\n  if (typeof path !== 'string' || path.length === 0 || path.length > MAX_PATH_LENGTH) {\n    return undefined;\n  }\n  const segments = path.replace(/^\\//, '').split('/');\n  if (segments.length > MAX_PATH_SEGMENTS || !segments.every((segment) => SEGMENT.test(segment))) {\n    return undefined;\n  }\n  return `/${segments.join('/')}`;\n};\n\n/** A message from the site, or undefined when the data is not one. */\nexport const parseSiteMessage = (data: unknown): SiteMessage | undefined => {\n  if (!isRecord(data) || data.v !== VISUAL_PROTOCOL_VERSION) {\n    return undefined;\n  }\n  if (data.type === 'shapio:ready') {\n    return { type: 'shapio:ready', v: VISUAL_PROTOCOL_VERSION };\n  }\n  if (data.type !== 'shapio:focus') {\n    return undefined;\n  }\n  const path = normalizeFieldPath(data.path);\n  if (typeof data.entryId !== 'string' || !ENTRY_ID.test(data.entryId) || !path) {\n    return undefined;\n  }\n  if (data.locale !== undefined && (typeof data.locale !== 'string' || !LOCALE.test(data.locale))) {\n    return undefined;\n  }\n  return {\n    type: 'shapio:focus',\n    v: VISUAL_PROTOCOL_VERSION,\n    entryId: data.entryId,\n    path,\n    ...(typeof data.locale === 'string' ? { locale: data.locale } : {}),\n  };\n};\n\n/** A message from the admin, or undefined when the data is not one. */\nexport const parseAdminMessage = (data: unknown): AdminMessage | undefined =>\n  isRecord(data) && data.v === VISUAL_PROTOCOL_VERSION && data.type === 'shapio:refresh'\n    ? { type: 'shapio:refresh', v: VISUAL_PROTOCOL_VERSION }\n    : undefined;\n","import { ENTRY_ATTRIBUTE, LOCALE_ATTRIBUTE, PATH_ATTRIBUTE } from './attributes.js';\nimport {\n  parseAdminMessage,\n  VISUAL_PROTOCOL_VERSION,\n  VISUAL_QUERY_PARAM,\n  type SiteMessage,\n} from './messages.js';\n\nexport type VisualEditingOptions = {\n  /** Shapio's public URL (or origin). Messages go to this origin only, and only its messages are accepted. */\n  origin: string;\n  /**\n   * Re-renders the page with the current draft after an edit. Without it the page reloads, which is right for a\n   * page that reads its preview token from the URL on every load; a page that drops the token from the address\n   * bar must re-fetch here instead.\n   */\n  onRefresh?: () => void | Promise<void>;\n  /** The window to run in (tests); defaults to the global one. */\n  window?: Window;\n};\n\n/** The attribute on `<html>` while visual editing is on, and on the element under the pointer. */\nconst ACTIVE_DOCUMENT_ATTRIBUTE = 'data-shapio-visual';\nconst HOVER_ATTRIBUTE = 'data-shapio-hover';\nconst STYLE = `[${ACTIVE_DOCUMENT_ATTRIBUTE}] [${HOVER_ATTRIBUTE}] { outline: 2px dashed #2563eb; outline-offset: 2px; cursor: pointer; }`;\n\nconst NOOP = () => undefined;\n\n/** Visual editing runs only inside a frame, on a URL the admin opened with `?shapio-visual=1`. */\nexport const isVisualEditingRequested = (win: Window): boolean => {\n  let framed: boolean;\n  try {\n    framed = win.self !== win.top;\n  } catch {\n    // A cross-origin top window can throw on access in some browsers: that is a frame.\n    framed = true;\n  }\n  return framed && new URL(win.location.href).searchParams.get(VISUAL_QUERY_PARAM) === '1';\n};\n\nconst originOf = (value: string): string | undefined => {\n  try {\n    const url = new URL(value);\n    return url.protocol === 'http:' || url.protocol === 'https:' ? url.origin : undefined;\n  } catch {\n    return undefined;\n  }\n};\n\nconst annotatedFrom = (target: EventTarget | null): HTMLElement | null => {\n  const element = target as Element | null;\n  return typeof element?.closest === 'function' ? element.closest<HTMLElement>(`[${ENTRY_ATTRIBUTE}]`) : null;\n};\n\n/**\n * Turns on visual editing when the page is in Shapio's preview frame: outlines elements carrying\n * `shapioAttr(...)` attributes on hover, tells the admin which field was clicked, and re-renders when the admin\n * saves. Posts only to the configured Shapio origin and accepts only that origin's messages from the parent\n * window. Outside the preview frame it does nothing. Returns a function that turns it off.\n */\nexport const initVisualEditing = (options: VisualEditingOptions): (() => void) => {\n  const win = options.window ?? window;\n  const origin = originOf(options.origin);\n  if (!origin || !isVisualEditingRequested(win)) {\n    return NOOP;\n  }\n  const doc = win.document;\n  const post = (message: SiteMessage) => win.parent.postMessage(message, origin);\n  let hovered: HTMLElement | null = null;\n\n  const style = doc.createElement('style');\n  style.textContent = STYLE;\n  doc.head.append(style);\n  doc.documentElement.setAttribute(ACTIVE_DOCUMENT_ATTRIBUTE, '');\n\n  const onPointerOver = (event: Event) => {\n    const element = annotatedFrom(event.target);\n    if (element === hovered) {\n      return;\n    }\n    hovered?.removeAttribute(HOVER_ATTRIBUTE);\n    hovered = element;\n    hovered?.setAttribute(HOVER_ATTRIBUTE, '');\n  };\n  const onClick = (event: Event) => {\n    const element = annotatedFrom(event.target);\n    const entryId = element?.getAttribute(ENTRY_ATTRIBUTE);\n    const path = element?.getAttribute(PATH_ATTRIBUTE);\n    if (!element || !entryId || !path) {\n      return;\n    }\n    // A click on an annotated link or button edits the field instead of navigating inside the frame.\n    event.preventDefault();\n    event.stopPropagation();\n    const locale = element.getAttribute(LOCALE_ATTRIBUTE);\n    post({\n      type: 'shapio:focus',\n      v: VISUAL_PROTOCOL_VERSION,\n      entryId,\n      path,\n      ...(locale ? { locale } : {}),\n    });\n  };\n  const onMessage = (event: MessageEvent) => {\n    if (event.source !== win.parent || event.origin !== origin || !parseAdminMessage(event.data)) {\n      return;\n    }\n    if (options.onRefresh) {\n      // A failing re-render surfaces as an unhandled rejection in the site's console, like any page error.\n      void Promise.resolve().then(options.onRefresh);\n    } else {\n      win.location.reload();\n    }\n  };\n\n  doc.addEventListener('pointerover', onPointerOver);\n  doc.addEventListener('click', onClick, true);\n  win.addEventListener('message', onMessage);\n  post({ type: 'shapio:ready', v: VISUAL_PROTOCOL_VERSION });\n\n  return () => {\n    doc.removeEventListener('pointerover', onPointerOver);\n    doc.removeEventListener('click', onClick, true);\n    win.removeEventListener('message', onMessage);\n    hovered?.removeAttribute(HOVER_ATTRIBUTE);\n    doc.documentElement.removeAttribute(ACTIVE_DOCUMENT_ATTRIBUTE);\n    style.remove();\n  };\n};\n"],"mappings":"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"}

package/dist/visual.iife.js

@@ -0,0 +1,2 @@
+var ShapioVisual=(function(e){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});let t=`data-shapio-entry`,n=`data-shapio-path`,r=`data-shapio-locale`,i=(e,i,a)=>{let o=typeof e==`string`?e:e.id,s=a??(typeof e==`string`?void 0:e.locale??void 0);return{[t]:o,[n]:i.replace(/^\/+/,``),...s?{[r]:s}:{}}},a=e=>typeof e==`object`&&!!e&&!Array.isArray(e),o=e=>a(e)&&e.v===1&&e.type===`shapio:refresh`?{type:`shapio:refresh`,v:1}:void 0,s=`data-shapio-visual`,c=`data-shapio-hover`,l=`[${s}] [${c}] { outline: 2px dashed #2563eb; outline-offset: 2px; cursor: pointer; }`,u=()=>void 0,d=e=>{let t;try{t=e.self!==e.top}catch{t=!0}return t&&new URL(e.location.href).searchParams.get(`shapio-visual`)===`1`},f=e=>{try{let t=new URL(e);return t.protocol===`http:`||t.protocol===`https:`?t.origin:void 0}catch{return}},p=e=>{let n=e;return typeof n?.closest==`function`?n.closest(`[${t}]`):null},m=e=>{let i=e.window??window,a=f(e.origin);if(!a||!d(i))return u;let m=i.document,h=e=>i.parent.postMessage(e,a),g=null,_=m.createElement(`style`);_.textContent=l,m.head.append(_),m.documentElement.setAttribute(s,``);let v=e=>{let t=p(e.target);t!==g&&(g?.removeAttribute(c),g=t,g?.setAttribute(c,``))},y=e=>{let i=p(e.target),a=i?.getAttribute(t),o=i?.getAttribute(n);if(!i||!a||!o)return;e.preventDefault(),e.stopPropagation();let s=i.getAttribute(r);h({type:`shapio:focus`,v:1,entryId:a,path:o,...s?{locale:s}:{}})},b=t=>{t.source===i.parent&&t.origin===a&&o(t.data)&&(e.onRefresh?Promise.resolve().then(e.onRefresh):i.location.reload())};return m.addEventListener(`pointerover`,v),m.addEventListener(`click`,y,!0),i.addEventListener(`message`,b),h({type:`shapio:ready`,v:1}),()=>{m.removeEventListener(`pointerover`,v),m.removeEventListener(`click`,y,!0),i.removeEventListener(`message`,b),g?.removeAttribute(c),m.documentElement.removeAttribute(s),_.remove()}},h=document.currentScript,g=h instanceof HTMLScriptElement?h.dataset.shapioOrigin:void 0;return g&&m({origin:g}),e.initVisualEditing=m,e.shapioAttr=i,e})({});
+//# sourceMappingURL=visual.iife.js.map

package/dist/visual.iife.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual.iife.js","names":["exports","ENTRY_ATTRIBUTE","PATH_ATTRIBUTE","LOCALE_ATTRIBUTE","shapioAttr","id","entry","entryLocale","locale","path","isRecord","value","parseAdminMessage","data","ACTIVE_DOCUMENT_ATTRIBUTE","HOVER_ATTRIBUTE","STYLE","NOOP","isVisualEditingRequested","framed","win","originOf","url","annotatedFrom","element","target","initVisualEditing","options","origin","doc","post","message","hovered","style","onPointerOver","event","onClick","entryId","onMessage","script"],"sources":["../src/attributes.ts","../src/messages.ts","../src/visualEditing.ts","../src/global.ts"],"sourcesContent":["/**\n * The attributes a site puts on an element that shows a field, so Shapio's preview can take a click on it back\n * to that field: `<h1 {...shapioAttr(article, 'title')}>`. Paths are API IDs, with list positions and nested\n * fields after slashes (`sections/2/heading`), the same paths the admin uses.\n */\nexport const ENTRY_ATTRIBUTE = 'data-shapio-entry';\nexport const PATH_ATTRIBUTE = 'data-shapio-path';\nexport const LOCALE_ATTRIBUTE = 'data-shapio-locale';\n\nexport type ShapioAttributes = {\n  'data-shapio-entry': string;\n  'data-shapio-path': string;\n  'data-shapio-locale'?: string;\n};\n\n/** An entry as delivery returns it (`{ id, locale }`), or its ID. */\nexport type EntryRef = string | { id: string; locale?: string | null | undefined };\n\n/**\n * A spreadable attribute object for the element that renders `path` of `entry`. The locale is the one given,\n * else the entry's own (delivery items carry the locale that served them); it is left out when unknown.\n */\nexport const shapioAttr = (entry: EntryRef, path: string, locale?: string): ShapioAttributes => {\n  const id = typeof entry === 'string' ? entry : entry.id;\n  const entryLocale = locale ?? (typeof entry === 'string' ? undefined : (entry.locale ?? undefined));\n  return {\n    [ENTRY_ATTRIBUTE]: id,\n    [PATH_ATTRIBUTE]: path.replace(/^\\/+/, ''),\n    ...(entryLocale ? { [LOCALE_ATTRIBUTE]: entryLocale } : {}),\n  };\n};\n","/**\n * The messages between a site in Shapio's preview frame and the admin around it. Every message carries the\n * protocol version; anything that does not parse is ignored. Who may send a message (the frame's window from\n * the preview origin, the parent from the Shapio origin) is checked by each side before parsing.\n */\nexport const VISUAL_PROTOCOL_VERSION = 1;\n/** The query parameter the admin adds to a preview URL it frames (`?shapio-visual=1`). */\nexport const VISUAL_QUERY_PARAM = 'shapio-visual';\n\nexport type VisualReadyMessage = { type: 'shapio:ready'; v: typeof VISUAL_PROTOCOL_VERSION };\nexport type VisualFocusMessage = {\n  type: 'shapio:focus';\n  v: typeof VISUAL_PROTOCOL_VERSION;\n  entryId: string;\n  /** A JSON pointer of API IDs (`/title`, `/sections/2/heading`). */\n  path: string;\n  locale?: string;\n};\nexport type VisualRefreshMessage = { type: 'shapio:refresh'; v: typeof VISUAL_PROTOCOL_VERSION };\n\n/** What the site posts to the admin. */\nexport type SiteMessage = VisualReadyMessage | VisualFocusMessage;\n/** What the admin posts to the site. */\nexport type AdminMessage = VisualRefreshMessage;\n\nconst MAX_PATH_LENGTH = 512;\nconst MAX_PATH_SEGMENTS = 32;\nconst SEGMENT = /^[A-Za-z0-9_~-]+$/;\nconst ENTRY_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\nconst LOCALE = /^[A-Za-z0-9-]{1,35}$/;\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value);\n\n/** `title`, `/title` or `sections/2/heading` → a JSON pointer (`/sections/2/heading`); undefined if malformed. */\nexport const normalizeFieldPath = (path: unknown): string | undefined => {\n  if (typeof path !== 'string' || path.length === 0 || path.length > MAX_PATH_LENGTH) {\n    return undefined;\n  }\n  const segments = path.replace(/^\\//, '').split('/');\n  if (segments.length > MAX_PATH_SEGMENTS || !segments.every((segment) => SEGMENT.test(segment))) {\n    return undefined;\n  }\n  return `/${segments.join('/')}`;\n};\n\n/** A message from the site, or undefined when the data is not one. */\nexport const parseSiteMessage = (data: unknown): SiteMessage | undefined => {\n  if (!isRecord(data) || data.v !== VISUAL_PROTOCOL_VERSION) {\n    return undefined;\n  }\n  if (data.type === 'shapio:ready') {\n    return { type: 'shapio:ready', v: VISUAL_PROTOCOL_VERSION };\n  }\n  if (data.type !== 'shapio:focus') {\n    return undefined;\n  }\n  const path = normalizeFieldPath(data.path);\n  if (typeof data.entryId !== 'string' || !ENTRY_ID.test(data.entryId) || !path) {\n    return undefined;\n  }\n  if (data.locale !== undefined && (typeof data.locale !== 'string' || !LOCALE.test(data.locale))) {\n    return undefined;\n  }\n  return {\n    type: 'shapio:focus',\n    v: VISUAL_PROTOCOL_VERSION,\n    entryId: data.entryId,\n    path,\n    ...(typeof data.locale === 'string' ? { locale: data.locale } : {}),\n  };\n};\n\n/** A message from the admin, or undefined when the data is not one. */\nexport const parseAdminMessage = (data: unknown): AdminMessage | undefined =>\n  isRecord(data) && data.v === VISUAL_PROTOCOL_VERSION && data.type === 'shapio:refresh'\n    ? { type: 'shapio:refresh', v: VISUAL_PROTOCOL_VERSION }\n    : undefined;\n","import { ENTRY_ATTRIBUTE, LOCALE_ATTRIBUTE, PATH_ATTRIBUTE } from './attributes.js';\nimport {\n  parseAdminMessage,\n  VISUAL_PROTOCOL_VERSION,\n  VISUAL_QUERY_PARAM,\n  type SiteMessage,\n} from './messages.js';\n\nexport type VisualEditingOptions = {\n  /** Shapio's public URL (or origin). Messages go to this origin only, and only its messages are accepted. */\n  origin: string;\n  /**\n   * Re-renders the page with the current draft after an edit. Without it the page reloads, which is right for a\n   * page that reads its preview token from the URL on every load; a page that drops the token from the address\n   * bar must re-fetch here instead.\n   */\n  onRefresh?: () => void | Promise<void>;\n  /** The window to run in (tests); defaults to the global one. */\n  window?: Window;\n};\n\n/** The attribute on `<html>` while visual editing is on, and on the element under the pointer. */\nconst ACTIVE_DOCUMENT_ATTRIBUTE = 'data-shapio-visual';\nconst HOVER_ATTRIBUTE = 'data-shapio-hover';\nconst STYLE = `[${ACTIVE_DOCUMENT_ATTRIBUTE}] [${HOVER_ATTRIBUTE}] { outline: 2px dashed #2563eb; outline-offset: 2px; cursor: pointer; }`;\n\nconst NOOP = () => undefined;\n\n/** Visual editing runs only inside a frame, on a URL the admin opened with `?shapio-visual=1`. */\nexport const isVisualEditingRequested = (win: Window): boolean => {\n  let framed: boolean;\n  try {\n    framed = win.self !== win.top;\n  } catch {\n    // A cross-origin top window can throw on access in some browsers: that is a frame.\n    framed = true;\n  }\n  return framed && new URL(win.location.href).searchParams.get(VISUAL_QUERY_PARAM) === '1';\n};\n\nconst originOf = (value: string): string | undefined => {\n  try {\n    const url = new URL(value);\n    return url.protocol === 'http:' || url.protocol === 'https:' ? url.origin : undefined;\n  } catch {\n    return undefined;\n  }\n};\n\nconst annotatedFrom = (target: EventTarget | null): HTMLElement | null => {\n  const element = target as Element | null;\n  return typeof element?.closest === 'function' ? element.closest<HTMLElement>(`[${ENTRY_ATTRIBUTE}]`) : null;\n};\n\n/**\n * Turns on visual editing when the page is in Shapio's preview frame: outlines elements carrying\n * `shapioAttr(...)` attributes on hover, tells the admin which field was clicked, and re-renders when the admin\n * saves. Posts only to the configured Shapio origin and accepts only that origin's messages from the parent\n * window. Outside the preview frame it does nothing. Returns a function that turns it off.\n */\nexport const initVisualEditing = (options: VisualEditingOptions): (() => void) => {\n  const win = options.window ?? window;\n  const origin = originOf(options.origin);\n  if (!origin || !isVisualEditingRequested(win)) {\n    return NOOP;\n  }\n  const doc = win.document;\n  const post = (message: SiteMessage) => win.parent.postMessage(message, origin);\n  let hovered: HTMLElement | null = null;\n\n  const style = doc.createElement('style');\n  style.textContent = STYLE;\n  doc.head.append(style);\n  doc.documentElement.setAttribute(ACTIVE_DOCUMENT_ATTRIBUTE, '');\n\n  const onPointerOver = (event: Event) => {\n    const element = annotatedFrom(event.target);\n    if (element === hovered) {\n      return;\n    }\n    hovered?.removeAttribute(HOVER_ATTRIBUTE);\n    hovered = element;\n    hovered?.setAttribute(HOVER_ATTRIBUTE, '');\n  };\n  const onClick = (event: Event) => {\n    const element = annotatedFrom(event.target);\n    const entryId = element?.getAttribute(ENTRY_ATTRIBUTE);\n    const path = element?.getAttribute(PATH_ATTRIBUTE);\n    if (!element || !entryId || !path) {\n      return;\n    }\n    // A click on an annotated link or button edits the field instead of navigating inside the frame.\n    event.preventDefault();\n    event.stopPropagation();\n    const locale = element.getAttribute(LOCALE_ATTRIBUTE);\n    post({\n      type: 'shapio:focus',\n      v: VISUAL_PROTOCOL_VERSION,\n      entryId,\n      path,\n      ...(locale ? { locale } : {}),\n    });\n  };\n  const onMessage = (event: MessageEvent) => {\n    if (event.source !== win.parent || event.origin !== origin || !parseAdminMessage(event.data)) {\n      return;\n    }\n    if (options.onRefresh) {\n      // A failing re-render surfaces as an unhandled rejection in the site's console, like any page error.\n      void Promise.resolve().then(options.onRefresh);\n    } else {\n      win.location.reload();\n    }\n  };\n\n  doc.addEventListener('pointerover', onPointerOver);\n  doc.addEventListener('click', onClick, true);\n  win.addEventListener('message', onMessage);\n  post({ type: 'shapio:ready', v: VISUAL_PROTOCOL_VERSION });\n\n  return () => {\n    doc.removeEventListener('pointerover', onPointerOver);\n    doc.removeEventListener('click', onClick, true);\n    win.removeEventListener('message', onMessage);\n    hovered?.removeAttribute(HOVER_ATTRIBUTE);\n    doc.documentElement.removeAttribute(ACTIVE_DOCUMENT_ATTRIBUTE);\n    style.remove();\n  };\n};\n","import { initVisualEditing } from './visualEditing.js';\n\n/**\n * The plain-script build (`window.ShapioVisual`). A `<script>` tag with `data-shapio-origin` turns visual editing\n * on by itself (the page reloads on refresh); otherwise call `ShapioVisual.initVisualEditing({ origin })`.\n */\nconst script = document.currentScript;\nconst origin = script instanceof HTMLScriptElement ? script.dataset.shapioOrigin : undefined;\nif (origin) {\n  initVisualEditing({ origin });\n}\n\nexport { shapioAttr } from './attributes.js';\nexport { initVisualEditing };\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@shapio/visual",
+  "version": "0.2.0",
+  "description": "Visual editing for sites built on Shapio: field attributes and the preview-frame script.",
+  "license": "Apache-2.0",
+  "homepage": "https://shapio.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mybrokengnome/shapio.git",
+    "directory": "packages/visual"
+  },
+  "bugs": {
+    "url": "https://github.com/mybrokengnome/shapio/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "@shapio/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./global": "./dist/visual.iife.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "jsdom": "30.1.1",
+    "tsdown": "0.23.0",
+    "typescript": "6.0.3",
+    "vitest": "5.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}