@digital-gravy/etch-public-api 0.6.0 → 0.7.0

package/README.md

@@ -128,6 +128,33 @@ To discard in-memory changes and restore the original block:
 etch.blocks.exitComponentEditMode({ revert: true });
 ```
 
+### Component props
+
+A component **instance** exposes its bound props as block attributes — set them
+with `setAttribute` / `update`, read them with `getAttribute`. Unlike an HTML
+block's free-form attributes, a component's props are a **closed schema**: the
+key must be a property declared by the component definition, or the call throws
+`INVALID_ARGUMENT`.
+
+```ts
+const [cardId] = etch.blocks.find({ type: "etch/component" });
+
+// Set a prop the component declares
+etch.blocks.setAttribute(cardId, "title", "Hello world");
+
+// Read it back
+etch.blocks.getAttribute(cardId, "title"); // "Hello world"
+
+// Or patch several props at once
+etch.blocks.update(cardId, { attributes: { title: "Hi", variant: "primary" } });
+
+// An undeclared key is rejected
+etch.blocks.setAttribute(cardId, "notAProp", "x"); // ✗ throws INVALID_ARGUMENT
+```
+
+> Values are stored as-is. For typed props such as classes or repeater/group
+> data, pass the value in the component's internal format.
+
 ### Error handling
 
 Methods throw a typed `EtchApiError` with a `code`, rather than returning

package/dist/index.d.cts

@@ -256,8 +256,10 @@ interface BlockPatch {
     /** Hide or show the block on the canvas. */
     hidden?: boolean;
     /**
-     * Merge HTML attributes — a key set to `undefined` removes that attribute.
-     * Only valid on HTML blocks.
+     * Merge attributes — a key set to `undefined` removes that attribute. Valid
+     * on HTML blocks (free-form HTML attributes) and on component instances,
+     * whose attributes are their bound props — a closed schema, so each key must
+     * be a property declared by the component (an unknown key is rejected).
      */
     attributes?: Record<string, string | undefined>;
     /** Replace the text content. Only valid on text blocks. */
@@ -299,11 +301,26 @@ interface EtchBlocksApi {
     setText(blockId: string, text: string): void;
     /** Rename a block (sets its label / display name). */
     rename(blockId: string, name: string): void;
-    /** Read an HTML attribute, or `undefined` when it is not set. */
+    /**
+     * Read an attribute, or `undefined` when it is not set. Works on HTML blocks
+     * (HTML attributes) and component instances (bound prop values). Throws
+     * `WRONG_BLOCK_TYPE` for a block that has no attributes (e.g. a text block).
+     */
     getAttribute(blockId: string, key: string): string | undefined;
-    /** Set an HTML attribute; omit `value` for a valueless (boolean) attribute. */
+    /**
+     * Set an attribute; omit `value` for a valueless (boolean) attribute. Works
+     * on HTML blocks and component instances. On a component, `key` must be a
+     * declared property — props are a closed schema — otherwise
+     * `INVALID_ARGUMENT` is thrown (or `OPERATION_FAILED` if the component
+     * definition has not loaded yet). Throws `WRONG_BLOCK_TYPE` for a block with
+     * no attributes.
+     */
     setAttribute(blockId: string, key: string, value?: string): void;
-    /** Remove an HTML attribute. */
+    /**
+     * Remove an attribute. Works on HTML blocks and component instances. On a
+     * component, `key` must be a declared property (see {@link setAttribute}).
+     * Throws `WRONG_BLOCK_TYPE` for a block with no attributes.
+     */
     removeAttribute(blockId: string, key: string): void;
     /** Add a CSS class to the block. */
     addClass(blockId: string, className: string): void;

package/dist/index.d.ts

@@ -256,8 +256,10 @@ interface BlockPatch {
     /** Hide or show the block on the canvas. */
     hidden?: boolean;
     /**
-     * Merge HTML attributes — a key set to `undefined` removes that attribute.
-     * Only valid on HTML blocks.
+     * Merge attributes — a key set to `undefined` removes that attribute. Valid
+     * on HTML blocks (free-form HTML attributes) and on component instances,
+     * whose attributes are their bound props — a closed schema, so each key must
+     * be a property declared by the component (an unknown key is rejected).
      */
     attributes?: Record<string, string | undefined>;
     /** Replace the text content. Only valid on text blocks. */
@@ -299,11 +301,26 @@ interface EtchBlocksApi {
     setText(blockId: string, text: string): void;
     /** Rename a block (sets its label / display name). */
     rename(blockId: string, name: string): void;
-    /** Read an HTML attribute, or `undefined` when it is not set. */
+    /**
+     * Read an attribute, or `undefined` when it is not set. Works on HTML blocks
+     * (HTML attributes) and component instances (bound prop values). Throws
+     * `WRONG_BLOCK_TYPE` for a block that has no attributes (e.g. a text block).
+     */
     getAttribute(blockId: string, key: string): string | undefined;
-    /** Set an HTML attribute; omit `value` for a valueless (boolean) attribute. */
+    /**
+     * Set an attribute; omit `value` for a valueless (boolean) attribute. Works
+     * on HTML blocks and component instances. On a component, `key` must be a
+     * declared property — props are a closed schema — otherwise
+     * `INVALID_ARGUMENT` is thrown (or `OPERATION_FAILED` if the component
+     * definition has not loaded yet). Throws `WRONG_BLOCK_TYPE` for a block with
+     * no attributes.
+     */
     setAttribute(blockId: string, key: string, value?: string): void;
-    /** Remove an HTML attribute. */
+    /**
+     * Remove an attribute. Works on HTML blocks and component instances. On a
+     * component, `key` must be a declared property (see {@link setAttribute}).
+     * Throws `WRONG_BLOCK_TYPE` for a block with no attributes.
+     */
     removeAttribute(blockId: string, key: string): void;
     /** Add a CSS class to the block. */
     addClass(blockId: string, className: string): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digital-gravy/etch-public-api",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "MIT-licensed typed client and contract for the Etch builder scripting API (window.etch). Etch itself is a separate proprietary product governed by its own commercial terms.",
   "license": "MIT",
   "type": "module",