@digital-gravy/etch-connector 0.2.2 → 0.3.0

package/README.md

@@ -132,7 +132,7 @@ return groups.length;
 `etch-connector tabs` reports, per tab, which Etch runtime it is and which
 surfaces that runtime backs (read off `etch.environment`), then prints the
 authoring rules that follow from it: the dynamic-data model (data sources vs
-loops), the media lookup, the namespaces that throw `NOT_AVAILABLE`, and the
+loops), the route tree, the content model, the media lookup, the namespaces that throw `NOT_AVAILABLE`, and the
 block types the runtime can construct. Not every runtime backs every surface, so
 read that before writing scripts — and branch on a capability, never on the
 product name. `eval` names the runtime it targets on stderr as a reminder, and

package/dist/cli.js

@@ -522,7 +522,7 @@ hand-written eval.
 
 AGENT: \`etch-connector tabs\` prints, per connected tab, which runtime it is and
 which surfaces that runtime backs (from \`etch.environment\`), followed by the
-authoring rules for it — the dynamic-data model, the media lookup, the
+authoring rules for it — the dynamic-data model, the route tree, the content model, the media lookup, the
 namespaces that throw, and the block types it can construct. Read that before
 writing scripts: not every runtime backs every surface, so the same script does
 not work everywhere. Branch on a capability, never on the product name.
@@ -602,12 +602,10 @@ render what you author):
     (specialized "image" is the URL-based picker — NOT for mediaId.) Instances
     then pass the numeric media ID, e.g. image: "10" — not the file URL.
 
-  Classes. A block's classes ARE its read-only \`styles\` array, not an HTML
-    attribute. Setting attributes.class in authored JSON is silently dropped, and
-    \`styles\` is rejected on authoring. Assign classes with etch.blocks.addClass()
-    — for component blocks, inside enterComponentEditMode() →
-    saveComponentEditModeAsync() → exitComponentEditMode(). An existing class
-    name re-links to its style record automatically (styling is preserved).
+  Classes. Set attributes.class in authored JSON (blocks.create(), replace(),
+    components.updateAsync()): each class links its style record, and a missing
+    one is created empty. A block's \`styles\` array is read-only; ids passed in
+    it are ignored. etch.blocks.addClass() works on existing blocks.
 
   Sections. When you create a top-level section, always tag it
     data-etch-element="section" and nest ONE container inside it as its inner —
@@ -630,8 +628,9 @@ render what you author):
     • Component instance props are attributes: set them at create()/replace()
       time, or update an existing instance in place with
           etch.blocks.update(instanceId, { attributes: { image: "10" } })
-    • updateAsync({ blocks }) requires styles:[] on every element block
-      (validation differs from blocks.create(), which omits styles entirely).
+    • components.updateAsync({ blocks }) takes the same block JSON as
+      blocks.create(). Older Etch builds reject it without \`styles\` on every
+      element block; there, pass the class style ids from etch.styles.list().
     • No etch.media API. Where the runtime backs the WordPress media library
       (capability \`wpMedia\` — see \`tabs\`), resolve a URL → media ID via the WP
       REST API:

package/dist/guidance.js

@@ -16,7 +16,10 @@ import { hasCapability } from './protocol.js';
 /** Namespaces that are declared on every runtime but backed only on some. */
 const GATED_NAMESPACES = [
     { capability: 'loops', namespace: 'etch.loops.*' },
-    { capability: 'fields', namespace: 'etch.fields.*' },
+    {
+        capability: 'fields',
+        namespace: 'etch.fields.* (content fields are on etch.content where backed)'
+    },
     { capability: 'templates', namespace: "etch.navigation.goTo('templates')" }
 ];
 const UNKNOWN_RUNTIME = [
@@ -59,6 +62,65 @@ function dynamicDataGuidance(environment) {
         '  sources — do not author etch/loop blocks against it.'
     ];
 }
+function routesGuidance(environment) {
+    if (!hasCapability(environment, 'routes')) {
+        return [
+            'Routes: etch.routes is absent here — the property does not exist, so',
+            '  feature-detect it rather than calling it and catching.'
+        ];
+    }
+    return [
+        'Routes — the site URLs are a route tree, managed through etch.routes.*:',
+        '  listAsync(), createAsync({ segment, parentId?, source?, templateId? }),',
+        '  updateAsync(id, patch) and deleteAsync(id) persist immediately. A',
+        "  segment is static ('about'), a group ('(marketing)') that adds nothing",
+        "  to the URL, or dynamic ('{this.title.toSlug()}'), served once per",
+        '  record of its source: record ids in postIds, content type keys in',
+        '  postTypes. Templates are records listed by',
+        '  etch.navigation.listTemplatesAsync(); a route renders through its',
+        "  templateId, or its nearest ancestor's (templateId: null in a patch",
+        '  inherits again). Read getPathsAsync() after a change — only',
+        '  `published` paths are built.',
+        '  Do not build links from .slug (this.slug, item.slug in a loop, or',
+        '  PostSummary.slug): only a record a static route serves has one. A',
+        '  record served by a dynamic route has none, and listPostsAsync() reports',
+        "  '' for it, which reads like the homepage. Spell the link from the",
+        "  route's own segment instead — /locations/{loc.title.toSlug()}/ under",
+        "  a 'locations' route with segment '{this.title.toSlug()}' — and check it",
+        '  against getPathsAsync().',
+        '  Vocabulary: what users call a content type is a postType in the API',
+        '  (its key), and a record or page is a post (postId, listPostsAsync()).'
+    ];
+}
+function contentGuidance(environment) {
+    if (!hasCapability(environment, 'content')) {
+        return [
+            'Content: etch.content is absent here — the property does not exist, so',
+            '  feature-detect it rather than calling it and catching.'
+        ];
+    }
+    return [
+        'Content — content types, their fields and items, through etch.content.*',
+        '  (writes persist immediately): listTypesAsync(), getTypeAsync(key),',
+        '  createTypeAsync({ name, key?, isTemplate?, fields? }), updateTypeAsync(key,',
+        '  { name?, key? }), deleteTypeAsync(key); addFieldAsync(typeKey, field),',
+        '  updateFieldAsync(typeKey, fieldKey, patch) — a new key renames and keeps',
+        '  values — removeFieldAsync(typeKey, fieldKey); listItemsAsync(postType?),',
+        '  getItemAsync(id), createItemAsync({ postType, title, fields? }),',
+        '  updateItemAsync(id, { title?, fields? }) — fields merge per key, null',
+        '  clears — deleteItemAsync(id). Relationship values are item ids.',
+        '  Templates are items of a type created with isTemplate: true.',
+        '  Items carry title and field values only: build their blocks by opening',
+        '  them (etch.navigation.openPostAsync(id) / openTemplateAsync(id)) and',
+        '  using etch.blocks.',
+        "  Refused: fields on a template type, changing isTemplate or an item's",
+        '  postType, deleting the page type, a template type as relation target,',
+        '  any write to a relationshipBacklink (READONLY), unknown field keys,',
+        '  and values their field rejects.',
+        '  Vocabulary: a content type is a postType (its key), an item is a post',
+        '  (its id is the postId).'
+    ];
+}
 function mediaGuidance(environment) {
     const binding = '  Bind an etch/dynamic-image by a numeric `mediaId` attribute, never a URL.';
     if (hasCapability(environment, 'wpMedia')) {
@@ -128,6 +190,8 @@ export function environmentGuidance(environment) {
             `Runtime: ${environment.product} — backs ${backed.length > 0 ? backed.join(', ') : 'no optional surface'}.`
         ],
         dynamicDataGuidance(environment),
+        routesGuidance(environment),
+        contentGuidance(environment),
         mediaGuidance(environment),
         unavailableGuidance(environment),
         blockTypeGuidance(environment)

package/dist/protocol.js

@@ -16,7 +16,9 @@ const CAPABILITY_NAMES = [
     'dataSources',
     'fields',
     'templates',
-    'wpMedia'
+    'wpMedia',
+    'routes',
+    'content'
 ];
 /** Whether a runtime backs a capability. Absent or unknown counts as no. */
 export function hasCapability(environment, capability) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@digital-gravy/etch-connector",
-	"version": "0.2.2",
+	"version": "0.3.0",
 	"publishConfig": {
 		"access": "public"
 	},