@blockprotocol/core - npm Package Compare versions

Comparing version 0.0.8-canary.0 to 0.0.8-canary.1

dist/cjs/html.d.ts

@@ -8,6 +8,46 @@ import { HtmlBlockDefinition } from "./types";
 } | ScriptRef | null | undefined;
+/**
+ * Retrieve the HTML containing node the block is being rendered within, which
+ * can be used by a block to identify itself on the page and apply dynamic
+ * behaviours to its elements.
+ * @param ref Used to identify the block on the page. Usually `import.meta.url`
+ *            or `document.currentScript` depending on if executing a module or
+ *            a script. Should be omitted for inline modules
+ *            (`<script type="module">...</script>`)
+ */
 export declare const getBlockContainer: (ref?: BlockIdentifier) => HTMLElement;
+/**
+ * Retrieve the URL for the HTML entry point, in order to resolve relative
+ * URLs to assets within the block.
+ * @param ref Used to identify the block on the page. Usually `import.meta.url`
+ *            or `document.currentScript` depending on if executing a module or
+ *            a script. Should be omitted for inline modules
+ *            (`<script type="module">...</script>`)
+ */
 export declare const getBlockUrl: (ref?: BlockIdentifier) => string;
+/**
+ * Used to mark dynamically inserted script tags as belonging to a certain block,
+ * identified by `ref`.
+ * @param script The script you want to mark as belonging to a block
+ * @param ref Used to identify the block on the page. Usually `import.meta.url`
+ *            or `document.currentScript` depending on if executing a module or
+ *            a script. Should be omitted for inline modules
+ *            (`<script type="module">...</script>`)
+ */
 export declare const markScript: (script: HTMLScriptElement, ref: BlockIdentifier) => void;
+/**
+ * Used to mark all the scripts within a block's containing node as belonging
+ * to that block. It should only be used once per block. It will also resolve
+ * any relative URLs in import statements for inline scripts, and in the src
+ * parameter.
+ * @param container The containing node the block is being rendered into
+ * @param url The HTML entry point for the block
+ */
 export declare const markBlockScripts: (container: HTMLElement, url: URL | string) => void;
+/**
+ * Render an HTML block into a specified target node.
+ * @param node The containing node to render the HTML block into
+ * @param definition The description of where to find the HTML block
+ * @param signal Used to abort the fetch of a block
+ */
 export declare const renderHtmlBlock: (node: HTMLElement, definition: HtmlBlockDefinition, signal?: AbortSignal) => Promise<void>;
@@ -19,2 +59,6 @@ declare const blockProtocolGlobals: {
 };
+/**
+ * Reset the global state and forget any registered blocks. Useful when about
+ * to change page in a single page app.
+ */
 export declare const teardownBlockProtocol: () => void;
@@ -26,3 +70,6 @@ declare global {
 }
+/**
+ * Assign the required blockprotocol APIs for HTML blocks to the global context.
+ */
 export declare const assignBlockProtocolGlobals: () => void;
 export {};

dist/cjs/html.js

@@ -41,2 +41,11 @@ "use strict";
 };
+/**
+ * Retrieve the HTML containing node the block is being rendered within, which
+ * can be used by a block to identify itself on the page and apply dynamic
+ * behaviours to its elements.
+ * @param ref Used to identify the block on the page. Usually `import.meta.url`
+ *            or `document.currentScript` depending on if executing a module or
+ *            a script. Should be omitted for inline modules
+ *            (`<script type="module">...</script>`)
+ */
 const getBlockContainer = (ref) => {
@@ -52,2 +61,10 @@ var _a;
 exports.getBlockContainer = getBlockContainer;
+/**
+ * Retrieve the URL for the HTML entry point, in order to resolve relative
+ * URLs to assets within the block.
+ * @param ref Used to identify the block on the page. Usually `import.meta.url`
+ *            or `document.currentScript` depending on if executing a module or
+ *            a script. Should be omitted for inline modules
+ *            (`<script type="module">...</script>`)
+ */
 const getBlockUrl = (ref) => {
@@ -63,2 +80,11 @@ var _a;
 exports.getBlockUrl = getBlockUrl;
+/**
+ * Used to mark dynamically inserted script tags as belonging to a certain block,
+ * identified by `ref`.
+ * @param script The script you want to mark as belonging to a block
+ * @param ref Used to identify the block on the page. Usually `import.meta.url`
+ *            or `document.currentScript` depending on if executing a module or
+ *            a script. Should be omitted for inline modules
+ *            (`<script type="module">...</script>`)
+ */
 const markScript = (script, ref) => {
@@ -93,2 +119,10 @@ const blockId = getIdForRef(ref);
 const replaceBetween = (origin, startIndex, endIndex, insertion) => `${origin.substring(0, startIndex)}${insertion}${origin.substring(endIndex)}`;
+/**
+ * Used to mark all the scripts within a block's containing node as belonging
+ * to that block. It should only be used once per block. It will also resolve
+ * any relative URLs in import statements for inline scripts, and in the src
+ * parameter.
+ * @param container The containing node the block is being rendered into
+ * @param url The HTML entry point for the block
+ */
 const markBlockScripts = (container, url) => {
@@ -126,2 +160,8 @@ const blockId = (0, uuid_1.v4)();
 exports.markBlockScripts = markBlockScripts;
+/**
+ * Render an HTML block into a specified target node.
+ * @param node The containing node to render the HTML block into
+ * @param definition The description of where to find the HTML block
+ * @param signal Used to abort the fetch of a block
+ */
 const renderHtmlBlock = (node, definition, signal) => __awaiter(void 0, void 0, void 0, function* () {
@@ -138,3 +178,2 @@ var _a;
     parent.append(frag);
-    (0, exports.markBlockScripts)(parent, baseUrl);
     if (!window.blockprotocol) {
@@ -144,2 +183,3 @@ // eslint-disable-next-line @typescript-eslint/no-use-before-define
     }
+    (0, exports.markBlockScripts)(parent, baseUrl);
     node.appendChild(parent);
@@ -157,2 +197,6 @@ });
 };
+/**
+ * Reset the global state and forget any registered blocks. Useful when about
+ * to change page in a single page app.
+ */
 const teardownBlockProtocol = () => {
@@ -166,2 +210,5 @@ if (!window.blockprotocol) {
 exports.teardownBlockProtocol = teardownBlockProtocol;
+/**
+ * Assign the required blockprotocol APIs for HTML blocks to the global context.
+ */
 const assignBlockProtocolGlobals = () => {
@@ -168,0 +215,0 @@ if (typeof window === "undefined") {

dist/cjs/types.d.ts

@@ -160,5 +160,18 @@ import { CoreHandler } from "./core-handler";
 export declare type HtmlBlockDefinition = {
+    /**
+     * The url to the block's HTML file entry point, e.g. `https://example.com/my-block.html`
+     * The path is used as the base to resolve relative URLs in scripts/imports, and
+     * is made available to blocks through `blockprotocol.getBlockUrl`. It is also
+     * used by `renderHtmlBlock` to fetch the block's HTML source (the entry point),
+     * if this is not provided.
+     */
     url: string;
+    /**
+     * An HTML string equivalent to the file hosted at `url`.
+     * If `source` is provided, `renderHtmlBlock` doesn't need to fetch the HTML
+     * source, which can save time if you already have it available. `url` will
+     * still be used to resolve relative URLs inside scripts.
+     */
     source?: string;
 };
 export {};

dist/esm/html.d.ts

@@ -8,6 +8,46 @@ import { HtmlBlockDefinition } from "./types";
 } | ScriptRef | null | undefined;
+/**
+ * Retrieve the HTML containing node the block is being rendered within, which
+ * can be used by a block to identify itself on the page and apply dynamic
+ * behaviours to its elements.
+ * @param ref Used to identify the block on the page. Usually `import.meta.url`
+ *            or `document.currentScript` depending on if executing a module or
+ *            a script. Should be omitted for inline modules
+ *            (`<script type="module">...</script>`)
+ */
 export declare const getBlockContainer: (ref?: BlockIdentifier) => HTMLElement;
+/**
+ * Retrieve the URL for the HTML entry point, in order to resolve relative
+ * URLs to assets within the block.
+ * @param ref Used to identify the block on the page. Usually `import.meta.url`
+ *            or `document.currentScript` depending on if executing a module or
+ *            a script. Should be omitted for inline modules
+ *            (`<script type="module">...</script>`)
+ */
 export declare const getBlockUrl: (ref?: BlockIdentifier) => string;
+/**
+ * Used to mark dynamically inserted script tags as belonging to a certain block,
+ * identified by `ref`.
+ * @param script The script you want to mark as belonging to a block
+ * @param ref Used to identify the block on the page. Usually `import.meta.url`
+ *            or `document.currentScript` depending on if executing a module or
+ *            a script. Should be omitted for inline modules
+ *            (`<script type="module">...</script>`)
+ */
 export declare const markScript: (script: HTMLScriptElement, ref: BlockIdentifier) => void;
+/**
+ * Used to mark all the scripts within a block's containing node as belonging
+ * to that block. It should only be used once per block. It will also resolve
+ * any relative URLs in import statements for inline scripts, and in the src
+ * parameter.
+ * @param container The containing node the block is being rendered into
+ * @param url The HTML entry point for the block
+ */
 export declare const markBlockScripts: (container: HTMLElement, url: URL | string) => void;
+/**
+ * Render an HTML block into a specified target node.
+ * @param node The containing node to render the HTML block into
+ * @param definition The description of where to find the HTML block
+ * @param signal Used to abort the fetch of a block
+ */
 export declare const renderHtmlBlock: (node: HTMLElement, definition: HtmlBlockDefinition, signal?: AbortSignal) => Promise<void>;
@@ -19,2 +59,6 @@ declare const blockProtocolGlobals: {
 };
+/**
+ * Reset the global state and forget any registered blocks. Useful when about
+ * to change page in a single page app.
+ */
 export declare const teardownBlockProtocol: () => void;
@@ -26,3 +70,6 @@ declare global {
 }
+/**
+ * Assign the required blockprotocol APIs for HTML blocks to the global context.
+ */
 export declare const assignBlockProtocolGlobals: () => void;
 export {};

dist/esm/html.js

@@ -38,2 +38,11 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
 };
+/**
+ * Retrieve the HTML containing node the block is being rendered within, which
+ * can be used by a block to identify itself on the page and apply dynamic
+ * behaviours to its elements.
+ * @param ref Used to identify the block on the page. Usually `import.meta.url`
+ *            or `document.currentScript` depending on if executing a module or
+ *            a script. Should be omitted for inline modules
+ *            (`<script type="module">...</script>`)
+ */
 export const getBlockContainer = (ref) => {
@@ -48,2 +57,10 @@ var _a;
 };
+/**
+ * Retrieve the URL for the HTML entry point, in order to resolve relative
+ * URLs to assets within the block.
+ * @param ref Used to identify the block on the page. Usually `import.meta.url`
+ *            or `document.currentScript` depending on if executing a module or
+ *            a script. Should be omitted for inline modules
+ *            (`<script type="module">...</script>`)
+ */
 export const getBlockUrl = (ref) => {
@@ -58,2 +75,11 @@ var _a;
 };
+/**
+ * Used to mark dynamically inserted script tags as belonging to a certain block,
+ * identified by `ref`.
+ * @param script The script you want to mark as belonging to a block
+ * @param ref Used to identify the block on the page. Usually `import.meta.url`
+ *            or `document.currentScript` depending on if executing a module or
+ *            a script. Should be omitted for inline modules
+ *            (`<script type="module">...</script>`)
+ */
 export const markScript = (script, ref) => {
@@ -87,2 +113,10 @@ const blockId = getIdForRef(ref);
 const replaceBetween = (origin, startIndex, endIndex, insertion) => `${origin.substring(0, startIndex)}${insertion}${origin.substring(endIndex)}`;
+/**
+ * Used to mark all the scripts within a block's containing node as belonging
+ * to that block. It should only be used once per block. It will also resolve
+ * any relative URLs in import statements for inline scripts, and in the src
+ * parameter.
+ * @param container The containing node the block is being rendered into
+ * @param url The HTML entry point for the block
+ */
 export const markBlockScripts = (container, url) => {
@@ -119,2 +153,8 @@ const blockId = uuid();
 };
+/**
+ * Render an HTML block into a specified target node.
+ * @param node The containing node to render the HTML block into
+ * @param definition The description of where to find the HTML block
+ * @param signal Used to abort the fetch of a block
+ */
 export const renderHtmlBlock = (node, definition, signal) => __awaiter(void 0, void 0, void 0, function* () {
@@ -131,3 +171,2 @@ var _a;
     parent.append(frag);
-    markBlockScripts(parent, baseUrl);
     if (!window.blockprotocol) {
@@ -137,2 +176,3 @@ // eslint-disable-next-line @typescript-eslint/no-use-before-define
     }
+    markBlockScripts(parent, baseUrl);
     node.appendChild(parent);
@@ -149,2 +189,6 @@ });
 };
+/**
+ * Reset the global state and forget any registered blocks. Useful when about
+ * to change page in a single page app.
+ */
 export const teardownBlockProtocol = () => {
@@ -157,2 +201,5 @@ if (!window.blockprotocol) {
 };
+/**
+ * Assign the required blockprotocol APIs for HTML blocks to the global context.
+ */
 export const assignBlockProtocolGlobals = () => {
@@ -159,0 +206,0 @@ if (typeof window === "undefined") {

dist/esm/types.d.ts

@@ -160,5 +160,18 @@ import { CoreHandler } from "./core-handler";
 export declare type HtmlBlockDefinition = {
+    /**
+     * The url to the block's HTML file entry point, e.g. `https://example.com/my-block.html`
+     * The path is used as the base to resolve relative URLs in scripts/imports, and
+     * is made available to blocks through `blockprotocol.getBlockUrl`. It is also
+     * used by `renderHtmlBlock` to fetch the block's HTML source (the entry point),
+     * if this is not provided.
+     */
     url: string;
+    /**
+     * An HTML string equivalent to the file hosted at `url`.
+     * If `source` is provided, `renderHtmlBlock` doesn't need to fetch the HTML
+     * source, which can save time if you already have it available. `url` will
+     * still be used to resolve relative URLs inside scripts.
+     */
     source?: string;
 };
 export {};

package.json

 {
   "name": "@blockprotocol/core",
-  "version": "0.0.8-canary.0",
+  "version": "0.0.8-canary.1",
   "description": "Implementation of the Block Protocol Core specification for blocks and embedding applications",
@@ -5,0 +5,0 @@ "keywords": [

No alert changes

Improved metrics

Total package byte prevSize

127288

increased by8.74%

Lines of code

2151

increased by11.05%

No dependency changes