@creaditor/web-starterkit 1.0.31 → 1.0.32

package/PUBLISH-HOOK.md

@@ -0,0 +1,136 @@
+# Publish hook — `onPublish`
+
+On the **web** channel, clicking **Publish** runs a fixed sequence:
+
+```
+SEO modal  →  loader up  →  editor publishes  →  onPublish(...)  →  loader down  →  confetti
+                                                 └── your work happens here ──┘
+```
+
+The **editor owns the publish**. `onPublish` is the notification that it
+succeeded, fired while the loader is still up, so you can do your own follow-up
+before the user sees the success card. Nothing is celebrated until you say you
+are finished.
+
+If you do not supply `onPublish`, the editor simply publishes and celebrates.
+
+## Signature
+
+```js
+onPublish(details, { loading, success, confetti, error, commands })
+```
+
+### `details` — what the user typed in the SEO modal
+
+```js
+{ title: string, description: string, keywords: string[] }
+```
+
+The editor has already saved this via `patchSite` before calling you; it is
+passed along so you can mirror it into your own system.
+
+### Closing the loop — required
+
+The loader stays up until you signal. Do exactly one of:
+
+| Signal | Effect |
+|---|---|
+| `success()` or `confetti()` | Loader down, success card + confetti, `creaditor:publish` fires. |
+| `error(message?)` | Loader down, failure snackbar, `creaditor:publish-error` fires. |
+| return a promise | Resolution counts as `success()`, rejection as `error()`. |
+
+`success()` and `confetti()` are the same call — invoking both yields one card.
+Whichever signal lands first wins; the rest are ignored, so exactly one terminal
+event fires per publish.
+
+**If you never signal**, the editor gives up after 60 seconds, drops the loader
+and celebrates anyway, with a console warning. Do not rely on this.
+
+### `loading(on = true)`
+
+Mounts / dismisses the loader. You rarely need it: the loader is already up when
+you are called, and the editor drops it on your first completion signal. A
+trailing `loading(false)` after `success()` is a harmless no-op.
+
+### `commands` — offline hosts only
+
+The editor can only publish when it has an access token (online mode). Hosts
+running offline/embedded must publish themselves:
+
+| Command | What it does |
+|---|---|
+| `patchSite(props)` | PATCH the site record. Pass `{ seo }` to store the SEO. |
+| `publishSite()` | Publish the saved state. No argument needed — the endpoint takes the site id from the URL and has no body schema. |
+| `toHTML()` / `toJSON()` | The same serializers handed to `onNextStep`. |
+
+`patchSite` must land **before** `publishSite`. Online hosts should ignore
+`commands` entirely — calling them there publishes a second time.
+
+## Example
+
+```js
+onPublish: (details, { confetti, success, loading, error }) => {
+  // the site is already live; rebuild it on our side, then celebrate
+  fetch(`${myHost}/CreV3.ashx?mn=rebuildPage&pageLink=${showInMyDomain}`)
+    .then(() => { success(); confetti(); loading(false); })
+    .catch(() => { error(); loading(false); });
+}
+```
+
+Or, equivalently, by returning a promise:
+
+```js
+onPublish: async () => {
+  await fetch(`${myHost}/CreV3.ashx?mn=rebuildPage&pageLink=${showInMyDomain}`);
+}
+```
+
+## Testing it without a host page
+
+`packages/core/publish-harness.html` boots the starterkit with an `onPublish`
+handler and prints a timestamped timeline of the whole flow, so the hook can be
+exercised without the ASPX host:
+
+```bash
+cd packages/core
+npm run build:web:starterkit
+python3 -m http.server 8899 --directory .
+# open http://localhost:8899/publish-harness.html
+```
+
+Pick what the host does — `success()`, `error()`, return a promise, or signal
+nothing (which exercises the 60s guard) — and watch the loader/card state at
+each step. Leave the token box empty to run offline: everything except the
+network publish still happens.
+
+To exercise the real thing, paste an edit token. The production bundle targets
+`api.creaditor.ai` regardless of where the page is served from (`isLocalhost()`
+is a build-time `NODE_ENV` flag, not the hostname), so a local page plus a real
+token is a genuine publish — **use a throwaway site**. The page documents both
+ways to get a token.
+
+## Window events
+
+Fired whether or not `onPublish` is wired, for hosts that would rather listen:
+
+```js
+window.addEventListener("creaditor:publish", (e) => {
+  e.detail.seo;         // { title, description, keywords }
+  e.detail.url;         // live site URL, when the editor knows it
+  e.detail.channel;     // "web"
+  e.detail.selfPublish; // true when the editor did the publishing
+  e.detail.toHTML;      // serializers
+  e.detail.toJSON;
+});
+
+window.addEventListener("creaditor:publish-error", (e) => e.detail.error);
+```
+
+## Gotchas
+
+- **Web channel only.** Newsletter/email keeps `onNextStep`; no SEO modal.
+- **Cancelling the SEO modal aborts the publish.** `onPublish` is not called.
+- **`onPublish` wins over `onNextStep`** on the web channel — if you supply
+  both, only `onPublish` runs.
+- **Do not call `commands.publishSite()` from an online host.** The editor
+  already published before calling you.

package/README.md

@@ -75,6 +75,14 @@ The key differences are:
 > sections). `sections` is currently empty for web and will be populated as
 > web section templates are added under `engines/web/sections`.
 
+### Publish
+
+On the web channel the **Publish** button opens the SEO modal, publishes, then
+calls your `onPublish` hook — with the loader still up — so you can run your own
+follow-up before the user sees the success card. See
+[PUBLISH-HOOK.md](./PUBLISH-HOOK.md) for the signature, how to signal
+completion, and the `creaditor:publish` window event.
+
 ## 🏗️ How it's built
 
 This package is a thin wrapper. The bundle is produced from `@creaditor/core`:

package/dist/5909.creaditor.bundle.js

@@ -582,7 +582,7 @@
       width: 15px;
       height: 15px;
     }
-  `,u.properties={message:{type:String},sub:{type:String},url:{type:String},seoTitle:{type:String},seoDescription:{type:String},copied:{type:Boolean}},customElements.define("cdtr-publish-success",u);const f="creaditor:publish",g="creaditor:publish-error";class b extends o.WF{constructor(){super(),this.channel="",this.isLoading=!1,this.isLocked=!1,this.lockTimer=null}connectedCallback(){super.connectedCallback(),this.onNextStep||(this.onNextStep=s.M.get("config","onNextStep")),this.channel||(this.channel=s.M.get("config","channel")||"")}disconnectedCallback(){super.disconnectedCallback(),this.clearTimers()}clearTimers(){this.lockTimer&&(clearTimeout(this.lockTimer),this.lockTimer=null)}async handleClick(){if(this.isLocked||this.isLoading)return;const e=!!s.M.get("config","access"),t="web"===this.channel,i=e&&t;let o=null;if(!t||(o=await p.open(),o)){this.isLoading=!0,this.isLocked=!0,this.lockTimer=setTimeout(()=>{this.clearTimers(),this.isLoading=!1,this.isLocked=!1},1e4);try{if(t){const e=this.showBuildingLoader();try{i&&o&&(await(0,n.YE)({seo:o}),await(0,n.bK)({})),"function"==typeof this.onNextStep&&await this.onNextStep({toHTML:r.FE,toJSON:r.U2,seo:o??void 0})}finally{e()}return this.emitPublished(i,o),void this.celebratePublish(o)}"function"==typeof this.onNextStep&&await this.onNextStep({toHTML:r.FE,toJSON:r.U2}),this.emitPublished(i,o)}catch(e){console.error("Error in publish/onNextStep:",e),this.emitPublishError(i,o,e),this.snackbar(s.M.get("lang","publishError")||"Publish failed")}finally{this.clearTimers(),this.isLoading=!1,this.isLocked=!1}}}snackbar(e){const t=s.M.get("commands");t?.snackbar?.(e)}showBuildingLoader(){const e=(0,h.A)();document.body.appendChild(e);let t=!1;return()=>{t||(t=!0,e.style.transition="opacity 300ms ease",e.style.opacity="0",e.style.pointerEvents="none",setTimeout(()=>e.remove(),320))}}siteUrl(){const e=s.M.get("app","domains"),t=e?.[0]?.name;if(t)return/^https?:\/\//.test(t)?t:`https://${t}`}emitPublished(e,t){const i={channel:this.channel,selfPublish:e,seo:t??void 0,url:this.siteUrl(),toHTML:r.FE,toJSON:r.U2};window.dispatchEvent(new CustomEvent(f,{detail:i}))}emitPublishError(e,t,i){const o={channel:this.channel,selfPublish:e,seo:t??void 0,error:i};window.dispatchEvent(new CustomEvent(g,{detail:o}))}celebratePublish(e){const t=document.createElement("cdtr-publish-success");e&&(t.seoTitle=e.title,t.seoDescription=e.description);const i=this.siteUrl();i&&(t.url=i),document.body.appendChild(t)}render(){const e=!!s.M.get("config","access");if(!(this.onNextStep||"web"===this.channel&&e))return null;const t="web"===this.channel?"publish":"next";return o.qy`
+  `,u.properties={message:{type:String},sub:{type:String},url:{type:String},seoTitle:{type:String},seoDescription:{type:String},copied:{type:Boolean}},customElements.define("cdtr-publish-success",u);const f="creaditor:publish",g="creaditor:publish-error";class b extends o.WF{constructor(){super(),this.channel="",this.isLoading=!1,this.isLocked=!1,this.lockTimer=null}connectedCallback(){super.connectedCallback(),this.onNextStep||(this.onNextStep=s.M.get("config","onNextStep")),this.onPublish||(this.onPublish=s.M.get("config","onPublish")),this.channel||(this.channel=s.M.get("config","channel")||"")}disconnectedCallback(){super.disconnectedCallback(),this.clearTimers()}clearTimers(){this.lockTimer&&(clearTimeout(this.lockTimer),this.lockTimer=null)}async handleClick(){if(this.isLocked||this.isLoading)return;const e=!!s.M.get("config","access"),t="web"===this.channel,i=e&&t;let o=null;if(!t||(o=await p.open(),o)){this.isLoading=!0,this.isLocked=!0,this.lockTimer=setTimeout(()=>{this.clearTimers(),this.isLoading=!1,this.isLocked=!1},1e4);try{if(t){const e=this.showBuildingLoader();let t=!1;try{i&&o&&(await(0,n.YE)({seo:o}),await(0,n.bK)({})),"function"==typeof this.onPublish?t=await this.runHostPublish(this.onPublish,o,i,e):"function"==typeof this.onNextStep&&await this.onNextStep({toHTML:r.FE,toJSON:r.U2,seo:o??void 0})}finally{e()}return void(t||(this.emitPublished(i,o),this.celebratePublish(o)))}"function"==typeof this.onNextStep&&await this.onNextStep({toHTML:r.FE,toJSON:r.U2}),this.emitPublished(i,o)}catch(e){console.error("Error in publish/onNextStep:",e),this.emitPublishError(i,o,e),this.snackbar(s.M.get("lang","publishError")||"Publish failed")}finally{this.clearTimers(),this.isLoading=!1,this.isLocked=!1}}}runHostPublish(e,t,i,o){var a=this;return new Promise(l=>{let c=!1,d=o;const p=function(){arguments.length>0&&void 0!==arguments[0]&&!arguments[0]?(d?.(),d=null):d||(d=a.showBuildingLoader())},h=(e,o,r)=>{c||(c=!0,clearTimeout(u),p(!1),e?(this.celebratePublish(t),this.emitPublished(i,t)):(this.snackbar(r||s.M.get("lang","publishError")||"Publish failed"),this.emitPublishError(i,t,o)),l(!0))},u=setTimeout(()=>{c||(console.warn("config.onPublish never signalled completion — finishing the publish without it. Call success() or error() (or return a promise) so the loader can come down."),c=!0,p(!1),l(!1))},6e4),f={title:t.title,description:t.description,keywords:t.keywords},g={loading:p,success:()=>h(!0),confetti:()=>h(!0),error:e=>h(!1,new Error(e||"host publish failed"),e),commands:{patchSite:e=>(0,n.YE)(e??{}),publishSite:e=>(0,n.bK)(e??{}),toHTML:r.FE,toJSON:r.U2}};let b;try{b=e(f,g)}catch(e){return console.error("Error in config.onPublish:",e),void h(!1,e)}b&&"function"==typeof b.then&&Promise.resolve(b).then(()=>h(!0),e=>{console.error("Error in config.onPublish:",e),h(!1,e)})})}snackbar(e){const t=s.M.get("commands");t?.snackbar?.(e)}showBuildingLoader(){const e=(0,h.A)();document.body.appendChild(e);let t=!1;return()=>{t||(t=!0,e.style.transition="opacity 300ms ease",e.style.opacity="0",e.style.pointerEvents="none",setTimeout(()=>e.remove(),320))}}siteUrl(){const e=s.M.get("app","domains"),t=e?.[0]?.name;if(t)return/^https?:\/\//.test(t)?t:`https://${t}`}emitPublished(e,t){const i={channel:this.channel,selfPublish:e,seo:t??void 0,url:this.siteUrl(),toHTML:r.FE,toJSON:r.U2};window.dispatchEvent(new CustomEvent(f,{detail:i}))}emitPublishError(e,t,i){const o={channel:this.channel,selfPublish:e,seo:t??void 0,error:i};window.dispatchEvent(new CustomEvent(g,{detail:o}))}celebratePublish(e){const t=document.createElement("cdtr-publish-success");e&&(t.seoTitle=e.title,t.seoDescription=e.description);const i=this.siteUrl();i&&(t.url=i),document.body.appendChild(t)}render(){const e=!!s.M.get("config","access");if(!(this.onNextStep||"function"==typeof this.onPublish||"web"===this.channel&&e))return null;const t="web"===this.channel?"publish":"next";return o.qy`
       <paper-button
         @click=${this.handleClick}
         class="next-button"
@@ -648,4 +648,4 @@
     }
 
 
-  `,b.properties={onNextStep:{type:Function},channel:{type:String},isLoading:{type:Boolean},isLocked:{type:Boolean},lockTimer:{type:Number}},customElements.define("cdtr-next-button",b)}}]);
+  `,b.properties={onNextStep:{type:Function},onPublish:{type:Function},channel:{type:String},isLoading:{type:Boolean},isLocked:{type:Boolean},lockTimer:{type:Number}},customElements.define("cdtr-next-button",b)}}]);