@freelygive/canvas-utils 0.1.0

package/dist/canvas-slots.d.ts

@@ -0,0 +1,21 @@
+import React from 'react';
+
+/**
+ * Helper to create canvas island props in the ["raw", value] format
+ * Canvas stores prop values as tuples: ["raw", actualValue]
+ */
+declare const rawProp: (value: unknown) => [string, unknown];
+/**
+ * Helper to create a canvas-island element HTML string
+ * Canvas uses these custom elements to represent components in slot content
+ */
+declare const createCanvasIsland: (props: Record<string, unknown>) => string;
+/**
+ * Helper to create a Canvas slot as a React element.
+ * The returned element has props.value containing the HTML string,
+ * which parseCanvasSlot reads to extract canvas-island data.
+ * When rendered directly (editor mode), it outputs the raw HTML.
+ */
+declare const createCanvasSlot: (html: string) => React.ReactElement;
+
+export { createCanvasIsland, createCanvasSlot, rawProp };

package/dist/canvas-slots.js

@@ -0,0 +1,19 @@
+// src/testing/canvas-slots.ts
+import React from "react";
+var rawProp = (value) => ["raw", value];
+var createCanvasIsland = (props) => {
+  const rawProps = {};
+  for (const [key, value] of Object.entries(props)) {
+    rawProps[key] = rawProp(value);
+  }
+  const propsJson = JSON.stringify(rawProps).replace(/"/g, """);
+  return `<canvas-island props="${propsJson}"></canvas-island>`;
+};
+var CanvasSlot = ({ value }) => React.createElement("div", { dangerouslySetInnerHTML: { __html: value } });
+var createCanvasSlot = (html) => React.createElement(CanvasSlot, { value: html });
+export {
+  createCanvasIsland,
+  createCanvasSlot,
+  rawProp
+};
+//# sourceMappingURL=canvas-slots.js.map

package/dist/canvas-slots.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/testing/canvas-slots.ts"],"sourcesContent":["import React from 'react';\n\n/**\n * Helper to create canvas island props in the [\"raw\", value] format\n * Canvas stores prop values as tuples: [\"raw\", actualValue]\n */\nexport const rawProp = (value: unknown): [string, unknown] => ['raw', value];\n\n/**\n * Helper to create a canvas-island element HTML string\n * Canvas uses these custom elements to represent components in slot content\n */\nexport const createCanvasIsland = (props: Record<string, unknown>): string => {\n  const rawProps: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(props)) {\n    rawProps[key] = rawProp(value);\n  }\n  const propsJson = JSON.stringify(rawProps).replace(/\"/g, '&quot;');\n  return `<canvas-island props=\"${propsJson}\"></canvas-island>`;\n};\n\n/**\n * React component that simulates a Canvas slot element.\n * Renders the slot HTML via dangerouslySetInnerHTML so canvas-island\n * custom elements appear in the DOM when rendered directly (editor mode).\n * Also exposes `value` as a prop so parseCanvasSlot can read it.\n */\nconst CanvasSlot = ({ value }: { value: string }) =>\n  React.createElement('div', { dangerouslySetInnerHTML: { __html: value } });\n\n/**\n * Helper to create a Canvas slot as a React element.\n * The returned element has props.value containing the HTML string,\n * which parseCanvasSlot reads to extract canvas-island data.\n * When rendered directly (editor mode), it outputs the raw HTML.\n */\nexport const createCanvasSlot = (html: string): React.ReactElement =>\n  React.createElement(CanvasSlot, { value: html });\n"],"mappings":";AAAA,OAAO,WAAW;AAMX,IAAM,UAAU,CAAC,UAAsC,CAAC,OAAO,KAAK;AAMpE,IAAM,qBAAqB,CAAC,UAA2C;AAC5E,QAAM,WAAoC,CAAC;AAC3C,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,aAAS,GAAG,IAAI,QAAQ,KAAK;AAAA,EAC/B;AACA,QAAM,YAAY,KAAK,UAAU,QAAQ,EAAE,QAAQ,MAAM,QAAQ;AACjE,SAAO,yBAAyB,SAAS;AAC3C;AAQA,IAAM,aAAa,CAAC,EAAE,MAAM,MAC1B,MAAM,cAAc,OAAO,EAAE,yBAAyB,EAAE,QAAQ,MAAM,EAAE,CAAC;AAQpE,IAAM,mBAAmB,CAAC,SAC/B,MAAM,cAAc,YAAY,EAAE,OAAO,KAAK,CAAC;","names":[]}

package/dist/editor-mode.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Enable Canvas editor mode for a story
+ * Sets drupalSettings.canvas and cleans up on unmount
+ */
+declare const enableEditorMode: () => void;
+/**
+ * Disable Canvas editor mode
+ * Removes drupalSettings.canvas
+ */
+declare const disableEditorMode: () => void;
+
+export { disableEditorMode, enableEditorMode };

package/dist/editor-mode.js

@@ -0,0 +1,18 @@
+// src/testing/editor-mode.ts
+var enableEditorMode = () => {
+  window.drupalSettings = {
+    ...window.drupalSettings,
+    canvas: {}
+  };
+};
+var disableEditorMode = () => {
+  const win = window;
+  if (win.drupalSettings?.canvas !== void 0) {
+    delete win.drupalSettings.canvas;
+  }
+};
+export {
+  disableEditorMode,
+  enableEditorMode
+};
+//# sourceMappingURL=editor-mode.js.map

package/dist/editor-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/testing/editor-mode.ts"],"sourcesContent":["/**\n * Enable Canvas editor mode for a story\n * Sets drupalSettings.canvas and cleans up on unmount\n */\nexport const enableEditorMode = () => {\n  (\n    window as Window & { drupalSettings?: Record<string, unknown> }\n  ).drupalSettings = {\n    ...(window as Window & { drupalSettings?: Record<string, unknown> })\n      .drupalSettings,\n    canvas: {},\n  };\n};\n\n/**\n * Disable Canvas editor mode\n * Removes drupalSettings.canvas\n */\nexport const disableEditorMode = () => {\n  const win = window as Window & { drupalSettings?: { canvas?: unknown } };\n  if (win.drupalSettings?.canvas !== undefined) {\n    delete win.drupalSettings.canvas;\n  }\n};\n"],"mappings":";AAIO,IAAM,mBAAmB,MAAM;AACpC,EACE,OACA,iBAAiB;AAAA,IACjB,GAAI,OACD;AAAA,IACH,QAAQ,CAAC;AAAA,EACX;AACF;AAMO,IAAM,oBAAoB,MAAM;AACrC,QAAM,MAAM;AACZ,MAAI,IAAI,gBAAgB,WAAW,QAAW;AAC5C,WAAO,IAAI,eAAe;AAAA,EAC5B;AACF;","names":[]}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@freelygive/canvas-utils",
+  "version": "0.1.0",
+  "description": "Canvas utility components and test helpers for Drupal Canvas projects.",
+  "type": "module",
+  "files": [
+    "src/components",
+    "dist"
+  ],
+  "exports": {
+    "./testing/canvas-slots": {
+      "types": "./dist/canvas-slots.d.ts",
+      "default": "./dist/canvas-slots.js"
+    },
+    "./testing/editor-mode": {
+      "types": "./dist/editor-mode.d.ts",
+      "default": "./dist/editor-mode.js"
+    }
+  },
+  "npmScaffold": {
+    "file-mapping": {
+      "components/utils_editor_note": "src/components/utils_editor_note",
+      "components/utils_slots": "src/components/utils_slots",
+      "components/utils_entity": "src/components/utils_entity"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "echo \"No tests yet\""
+  },
+  "dependencies": {
+    "@freelygive/npm-scaffold": "^0.3.1"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.2.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "license": "GPL-2.0-or-later"
+}

package/src/components/utils_editor_note/component.yml

@@ -0,0 +1,7 @@
+name: 'Utility: Editor Note'
+machineName: utils_editor_note
+status: false
+required: []
+props:
+  properties: []
+slots: []

package/src/components/utils_editor_note/dist/index.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Detect if we're in Canvas page editor mode
+ * Returns true when the component is being edited in the Canvas UI
+ */ export const isCanvasEditorMode = ()=>{
+    var _window_drupalSettings;
+    if (typeof window === 'undefined') return false;
+    // Check for drupalSettings.canvas (set in editor mode)
+    if (((_window_drupalSettings = window.drupalSettings) === null || _window_drupalSettings === void 0 ? void 0 : _window_drupalSettings.canvas) !== undefined) {
+        return true;
+    }
+    try {
+        var _window_top_location, _window_top;
+        const pathname = ((_window_top = window.top) === null || _window_top === void 0 ? void 0 : (_window_top_location = _window_top.location) === null || _window_top_location === void 0 ? void 0 : _window_top_location.pathname) || '';
+        // Check if in Canvas editor (but not in component code editor)
+        if (pathname.startsWith('/canvas/')) {
+            return true;
+        }
+    } catch (unused) {
+        // Cross-origin access blocked - likely in an iframe
+        return false;
+    }
+    return false;
+};
+/**
+ * Editor note component for displaying messages only visible in Canvas editor mode
+ * Used to explain runtime behavior that differs from editor preview
+ */ const EditorNote = ({ children })=>/*#__PURE__*/ _jsx("div", {
+        className: "border-2 border-dashed border-black/30 bg-cream/50 px-6 py-4 text-sm text-black/70",
+        children: children
+    });
+export default EditorNote;

package/src/components/utils_editor_note/index.jsx

@@ -0,0 +1,37 @@
+/**
+ * Detect if we're in Canvas page editor mode
+ * Returns true when the component is being edited in the Canvas UI
+ */
+export const isCanvasEditorMode = () => {
+  if (typeof window === 'undefined') return false;
+
+  // Check for drupalSettings.canvas (set in editor mode)
+  if (window.drupalSettings?.canvas !== undefined) {
+    return true;
+  }
+
+  try {
+    const pathname = window.top?.location?.pathname || '';
+    // Check if in Canvas editor (but not in component code editor)
+    if (pathname.startsWith('/canvas/')) {
+      return true;
+    }
+  } catch {
+    // Cross-origin access blocked - likely in an iframe
+    return false;
+  }
+
+  return false;
+};
+
+/**
+ * Editor note component for displaying messages only visible in Canvas editor mode
+ * Used to explain runtime behavior that differs from editor preview
+ */
+const EditorNote = ({ children }) => (
+  <div className="border-2 border-dashed border-black/30 bg-cream/50 px-6 py-4 text-sm text-black/70">
+    {children}
+  </div>
+);
+
+export default EditorNote;

package/src/components/utils_entity/component.yml

@@ -0,0 +1,7 @@
+name: 'Utility: Entity'
+machineName: utils_entity
+status: false
+required: []
+props:
+  properties: []
+slots: []

package/src/components/utils_entity/dist/index.js

@@ -0,0 +1,74 @@
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+import { getPageData, JsonApiClient } from 'drupal-canvas';
+import { DrupalJsonApiParams } from 'drupal-jsonapi-params';
+import useSWR from 'swr';
+/**
+ * Fetch the main entity for the current page using SWR.
+ * Uses Canvas mainEntity (when available) with fallback to title-based lookup.
+ * @param {string} entityType - The JSON:API entity type (e.g., 'node--news_article')
+ * @param {object} options - Fetch options
+ * @param {string[]} options.includes - Relationships to include
+ * @param {object} options.fields - Sparse fieldset map (e.g., { 'node--news_article': ['title'] })
+ * @returns {{ data: object|undefined, error: Error|undefined, isLoading: boolean }}
+ */ export const useMainEntity = (entityType, { includes = [], fields = {} } = {})=>{
+    const pageData = getPageData();
+    const { pageTitle } = pageData;
+    // mainEntity will be available in future Canvas versions
+    const mainEntity = pageData.mainEntity;
+    const entityId = (mainEntity === null || mainEntity === void 0 ? void 0 : mainEntity.uuid) || pageTitle || null;
+    return useSWR(entityId ? [
+        'mainEntity',
+        entityType,
+        entityId
+    ] : null, ()=>_async_to_generator(function*() {
+            const params = new DrupalJsonApiParams();
+            if (mainEntity === null || mainEntity === void 0 ? void 0 : mainEntity.uuid) {
+                params.addFilter('id', mainEntity.uuid);
+            } else {
+                params.addFilter('title', pageTitle);
+            }
+            if (includes.length > 0) {
+                params.addInclude(includes);
+            }
+            for (const [type, fieldList] of Object.entries(fields)){
+                params.addFields(type, fieldList);
+            }
+            const client = new JsonApiClient();
+            const queryString = params.getQueryString();
+            const data = yield client.getCollection(entityType, {
+                queryString
+            });
+            return (data === null || data === void 0 ? void 0 : data[0]) || null;
+        })());
+};
+// Empty default export for component compatibility
+const UtilsEntity = ()=>null;
+export default UtilsEntity;

package/src/components/utils_entity/index.jsx

@@ -0,0 +1,53 @@
+import { getPageData, JsonApiClient } from 'drupal-canvas';
+import { DrupalJsonApiParams } from 'drupal-jsonapi-params';
+import useSWR from 'swr';
+
+/**
+ * Fetch the main entity for the current page using SWR.
+ * Uses Canvas mainEntity (when available) with fallback to title-based lookup.
+ * @param {string} entityType - The JSON:API entity type (e.g., 'node--news_article')
+ * @param {object} options - Fetch options
+ * @param {string[]} options.includes - Relationships to include
+ * @param {object} options.fields - Sparse fieldset map (e.g., { 'node--news_article': ['title'] })
+ * @returns {{ data: object|undefined, error: Error|undefined, isLoading: boolean }}
+ */
+export const useMainEntity = (
+  entityType,
+  { includes = [], fields = {} } = {},
+) => {
+  const pageData = getPageData();
+  const { pageTitle } = pageData;
+  // mainEntity will be available in future Canvas versions
+  const mainEntity = pageData.mainEntity;
+  const entityId = mainEntity?.uuid || pageTitle || null;
+
+  return useSWR(
+    entityId ? ['mainEntity', entityType, entityId] : null,
+    async () => {
+      const params = new DrupalJsonApiParams();
+
+      if (mainEntity?.uuid) {
+        params.addFilter('id', mainEntity.uuid);
+      } else {
+        params.addFilter('title', pageTitle);
+      }
+
+      if (includes.length > 0) {
+        params.addInclude(includes);
+      }
+
+      for (const [type, fieldList] of Object.entries(fields)) {
+        params.addFields(type, fieldList);
+      }
+
+      const client = new JsonApiClient();
+      const queryString = params.getQueryString();
+      const data = await client.getCollection(entityType, { queryString });
+      return data?.[0] || null;
+    },
+  );
+};
+
+// Empty default export for component compatibility
+const UtilsEntity = () => null;
+export default UtilsEntity;

package/src/components/utils_slots/component.yml

@@ -0,0 +1,7 @@
+name: 'Utility: Slots'
+machineName: utils_slots
+status: false
+required: []
+props:
+  properties: []
+slots: []

package/src/components/utils_slots/dist/index.js

@@ -0,0 +1,79 @@
+import React from 'react';
+/**
+ * Flatten React children, handling nested fragments
+ * Useful for processing slot content that may contain fragments
+ * @param {React.ReactNode} children - React children to flatten
+ * @returns {Array} - Flattened array of children
+ */ const flattenChildren = (children)=>{
+    const result = [];
+    React.Children.forEach(children, (child)=>{
+        if (!child) return;
+        // Check if it's a Fragment (type is Symbol(react.fragment))
+        if ((child === null || child === void 0 ? void 0 : child.type) === React.Fragment) {
+            result.push(...flattenChildren(child.props.children));
+        } else {
+            result.push(child);
+        }
+    });
+    return result;
+};
+/**
+ * Parse Canvas slot format to extract component props
+ * Canvas slots contain HTML with canvas-island elements that hold component data
+ * @param {object} slot - The Canvas slot object
+ * @returns {Array|null} - Array of parsed component objects with props, or null
+ */ const parseCanvasSlot = (slot)=>{
+    var _slot_props;
+    // Check if this is Canvas slot format (object with props.value containing HTML)
+    if (typeof slot !== 'object' || !(slot === null || slot === void 0 ? void 0 : (_slot_props = slot.props) === null || _slot_props === void 0 ? void 0 : _slot_props.value)) {
+        return null;
+    }
+    const html = slot.props.value;
+    if (typeof html !== 'string' || typeof window === 'undefined') {
+        return null;
+    }
+    try {
+        // Use DOMParser for reliable HTML parsing
+        const parser = new DOMParser();
+        const doc = parser.parseFromString(html, 'text/html');
+        const islands = doc.querySelectorAll('canvas-island[props]');
+        if (islands.length === 0) return null;
+        const results = [];
+        islands.forEach((island)=>{
+            try {
+                const propsAttr = island.getAttribute('props');
+                if (!propsAttr) return;
+                const rawProps = JSON.parse(propsAttr);
+                // Convert from ["raw", value] format to just value
+                const props = {};
+                for (const [key, val] of Object.entries(rawProps)){
+                    if (Array.isArray(val) && val[0] === 'raw') {
+                        props[key] = val[1];
+                    } else {
+                        props[key] = val;
+                    }
+                }
+                results.push({
+                    props
+                });
+            } catch (unused) {
+            // Skip malformed entries
+            }
+        });
+        return results.length > 0 ? results : null;
+    } catch (unused) {
+        return null;
+    }
+};
+/**
+ * Get children from a slot - handles both Canvas slot format and React children
+ * @param {object|React.ReactNode} slot - The slot content
+ * @returns {Array} - Array of children (parsed objects or React elements)
+ */ export const getSlotChildren = (slot)=>{
+    if (!slot) return [];
+    const parsed = parseCanvasSlot(slot);
+    return parsed || flattenChildren(slot);
+};
+// Empty default export for component compatibility
+const UtilsSlots = ()=>null;
+export default UtilsSlots;

package/src/components/utils_slots/index.jsx

@@ -0,0 +1,91 @@
+import React from 'react';
+
+/**
+ * Flatten React children, handling nested fragments
+ * Useful for processing slot content that may contain fragments
+ * @param {React.ReactNode} children - React children to flatten
+ * @returns {Array} - Flattened array of children
+ */
+const flattenChildren = (children) => {
+  const result = [];
+  React.Children.forEach(children, (child) => {
+    if (!child) return;
+    // Check if it's a Fragment (type is Symbol(react.fragment))
+    if (child?.type === React.Fragment) {
+      result.push(...flattenChildren(child.props.children));
+    } else {
+      result.push(child);
+    }
+  });
+  return result;
+};
+
+/**
+ * Parse Canvas slot format to extract component props
+ * Canvas slots contain HTML with canvas-island elements that hold component data
+ * @param {object} slot - The Canvas slot object
+ * @returns {Array|null} - Array of parsed component objects with props, or null
+ */
+const parseCanvasSlot = (slot) => {
+  // Check if this is Canvas slot format (object with props.value containing HTML)
+  if (typeof slot !== 'object' || !slot?.props?.value) {
+    return null;
+  }
+
+  const html = slot.props.value;
+  if (typeof html !== 'string' || typeof window === 'undefined') {
+    return null;
+  }
+
+  try {
+    // Use DOMParser for reliable HTML parsing
+    const parser = new DOMParser();
+    const doc = parser.parseFromString(html, 'text/html');
+    const islands = doc.querySelectorAll('canvas-island[props]');
+
+    if (islands.length === 0) return null;
+
+    const results = [];
+    islands.forEach((island) => {
+      try {
+        const propsAttr = island.getAttribute('props');
+        if (!propsAttr) return;
+
+        const rawProps = JSON.parse(propsAttr);
+
+        // Convert from ["raw", value] format to just value
+        const props = {};
+        for (const [key, val] of Object.entries(rawProps)) {
+          if (Array.isArray(val) && val[0] === 'raw') {
+            props[key] = val[1];
+          } else {
+            props[key] = val;
+          }
+        }
+
+        results.push({ props });
+      } catch {
+        // Skip malformed entries
+      }
+    });
+
+    return results.length > 0 ? results : null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Get children from a slot - handles both Canvas slot format and React children
+ * @param {object|React.ReactNode} slot - The slot content
+ * @returns {Array} - Array of children (parsed objects or React elements)
+ */
+export const getSlotChildren = (slot) => {
+  if (!slot) return [];
+  const parsed = parseCanvasSlot(slot);
+  return parsed || flattenChildren(slot);
+};
+
+// Empty default export for component compatibility
+const UtilsSlots = () => null;
+export default UtilsSlots;