@avocadostudio-ai/site-sdk 0.3.3 → 0.4.0

package/dist/editor.d.ts

@@ -1,3 +1,4 @@
+import type { FieldKind } from "@avocadostudio-ai/shared";
 export { EditorOverlay } from "./editor-overlay.tsx";
 export { buildEditorQuerySuffix } from "./editor-query.ts";
 export declare function getPreviewWrapperProps(editorMode: boolean, blockId: string, blockType: string): {
@@ -13,6 +14,57 @@ export declare function getPreviewWrapperProps(editorMode: boolean, blockId: str
         readonly viewTransitionName: `block-${string}`;
     };
 };
+/**
+ * Mark the element that draws one editable field.
+ *
+ * This is the second half of instrumenting a preview, and until now it was the
+ * half with no helper. `getPreviewWrapperProps` covers the block boundary and
+ * is named, exported and documented; the per-field attributes were prose in the
+ * integration guide with a link to a renderer to copy from. The predictable
+ * result is an integration that wraps every block and marks no fields — which
+ * frames, renders, selects, scrolls and opens the property panel correctly, and
+ * silently has no inline text editing, no field pills and no image buttons in
+ * the preview, because every one of those is found by walking
+ * `[data-editable-target]`.
+ *
+ * ```tsx
+ * <div className="hero__media" {...editableProps("imageUrl", { kind: "image" })}>
+ *   <Image src={props.imageUrl} … />
+ * </div>
+ * ```
+ *
+ * The path is the same grammar an operation uses — `title`, `cards[0].title`,
+ * `links[0].children[1].label` — because it is the same path: what the overlay
+ * reads here is what it sends back as the field to patch.
+ *
+ * **Put it on an element, not on the image.** For an image field the attribute
+ * belongs on the wrapper around the `<img>`, never on the image itself: the
+ * overlay appends its Change button *into* the marked element, and nothing can
+ * be appended into an `<img>`.
+ *
+ * **`kind` is how a site says what a field is in its own vocabulary.** Without
+ * it the overlay has to guess an image from the prop name, against Avocado's
+ * own naming (`imageUrl`, `*.src`) — so a site whose field is `photoUrl` or
+ * `heroSrc` gets a picker in the property panel and no button in the preview,
+ * with no error on either side. Pass the same word the block manifest uses and
+ * the guess never runs.
+ *
+ * There is no `editorMode` argument on purpose. These are inert data attributes
+ * that cost a few bytes and do nothing unless the overlay is mounted (all of
+ * its styling is scoped under `[data-editor-active]`), and most sites render
+ * their blocks through components shared with the public pages, where threading
+ * a flag down to every field is the step that does not get done.
+ */
+export declare function editableProps(path: string, options?: {
+    /** Text for the hover pill. Defaults to the path. */
+    label?: string;
+    /** What kind of field this is — the same vocabulary as the block manifest. */
+    kind?: FieldKind;
+}): {
+    readonly "data-editable-kind"?: FieldKind | undefined;
+    readonly "data-editable-target": string;
+    readonly "data-editable-target-label": string;
+};
 export { renderBlocks } from "./render-blocks.tsx";
 export { RenderedBlocks, PreviewBlock } from "./live-preview-blocks.tsx";
 export { LivePreviewProvider } from "@avocadostudio-ai/preview-adapter";

package/dist/editor.js

@@ -13,6 +13,54 @@ export function getPreviewWrapperProps(editorMode, blockId, blockType) {
         style: { viewTransitionName: `block-${blockId}` }
     };
 }
+/**
+ * Mark the element that draws one editable field.
+ *
+ * This is the second half of instrumenting a preview, and until now it was the
+ * half with no helper. `getPreviewWrapperProps` covers the block boundary and
+ * is named, exported and documented; the per-field attributes were prose in the
+ * integration guide with a link to a renderer to copy from. The predictable
+ * result is an integration that wraps every block and marks no fields — which
+ * frames, renders, selects, scrolls and opens the property panel correctly, and
+ * silently has no inline text editing, no field pills and no image buttons in
+ * the preview, because every one of those is found by walking
+ * `[data-editable-target]`.
+ *
+ * ```tsx
+ * <div className="hero__media" {...editableProps("imageUrl", { kind: "image" })}>
+ *   <Image src={props.imageUrl} … />
+ * </div>
+ * ```
+ *
+ * The path is the same grammar an operation uses — `title`, `cards[0].title`,
+ * `links[0].children[1].label` — because it is the same path: what the overlay
+ * reads here is what it sends back as the field to patch.
+ *
+ * **Put it on an element, not on the image.** For an image field the attribute
+ * belongs on the wrapper around the `<img>`, never on the image itself: the
+ * overlay appends its Change button *into* the marked element, and nothing can
+ * be appended into an `<img>`.
+ *
+ * **`kind` is how a site says what a field is in its own vocabulary.** Without
+ * it the overlay has to guess an image from the prop name, against Avocado's
+ * own naming (`imageUrl`, `*.src`) — so a site whose field is `photoUrl` or
+ * `heroSrc` gets a picker in the property panel and no button in the preview,
+ * with no error on either side. Pass the same word the block manifest uses and
+ * the guess never runs.
+ *
+ * There is no `editorMode` argument on purpose. These are inert data attributes
+ * that cost a few bytes and do nothing unless the overlay is mounted (all of
+ * its styling is scoped under `[data-editor-active]`), and most sites render
+ * their blocks through components shared with the public pages, where threading
+ * a flag down to every field is the step that does not get done.
+ */
+export function editableProps(path, options) {
+    return {
+        "data-editable-target": path,
+        "data-editable-target-label": options?.label ?? path,
+        ...(options?.kind ? { "data-editable-kind": options.kind } : {})
+    };
+}
 // Block rendering helper
 export { renderBlocks } from "./render-blocks.js";
 // Live-preview store renderer (streams field drafts through React)

package/dist/server/orchestrator.d.ts

@@ -1 +1 @@
-export { createOrchestrator, jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaLabel, type CreateOrchestratorConfig, type OrchestratorHandler, type OrchestratorAuth, type AuthContext, type CmsAdapter, type CmsCapabilities, type CmsInlineAsset, type CmsPublishContext, type CmsPublishResult, type CmsPerspective, type CmsReadOptions, type CmsMediaItem, type CmsMediaPage, type CmsMediaQuery, type CmsMediaSource, type CmsMediaSourceConfig, type ResolvedCapabilities } from "@avocadostudio-ai/orchestrator-core";
+export { createOrchestrator, jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaUploader, cmsMediaLabel, type CreateOrchestratorConfig, type OrchestratorHandler, type OrchestratorAuth, type AuthContext, type CmsAdapter, type CmsCapabilities, type CmsInlineAsset, type CmsPublishContext, type CmsPublishResult, type CmsPerspective, type CmsReadOptions, type CmsMediaItem, type CmsMediaPage, type CmsMediaQuery, type CmsMediaUpload, type CmsMediaSource, type CmsMediaUploader, type CmsMediaSourceConfig, type ResolvedCapabilities } from "@avocadostudio-ai/orchestrator-core";

package/dist/server/orchestrator.js

@@ -11,4 +11,4 @@
 //
 // This file stays so `@avocadostudio-ai/site-sdk/server` — the entry point
 // every example, README and docs page uses — keeps resolving unchanged.
-export { createOrchestrator, jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaLabel } from "@avocadostudio-ai/orchestrator-core";
+export { createOrchestrator, jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaUploader, cmsMediaLabel } from "@avocadostudio-ai/orchestrator-core";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/site-sdk",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -107,16 +107,16 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/blocks": "^0.3.3",
-    "@avocadostudio-ai/preview-adapter": "^0.3.3",
-    "@avocadostudio-ai/shared": "^0.3.3"
+    "@avocadostudio-ai/blocks": "^0.4.0",
+    "@avocadostudio-ai/preview-adapter": "^0.4.0",
+    "@avocadostudio-ai/shared": "^0.4.0"
   },
   "peerDependencies": {
     "next": ">=15.0.0",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
     "better-sqlite3": ">=12.0.0",
-    "@avocadostudio-ai/orchestrator-core": "^0.3.3"
+    "@avocadostudio-ai/orchestrator-core": "^0.4.0"
   },
   "peerDependenciesMeta": {
     "@avocadostudio-ai/orchestrator-core": {