@freelygive/canvas-utils 0.1.0 → 0.2.0-dev.6dad937b

package/README.md

@@ -0,0 +1,112 @@
+# @freelygive/canvas-utils
+
+Canvas utility components and test helpers for Drupal Canvas projects.
+
+## Components
+
+Utility components are scaffolded into your project via
+[@freelygive/npm-scaffold](https://www.npmjs.com/package/@freelygive/npm-scaffold).
+
+| Component | Description |
+|---|---|
+| `utils_editor_note` | Editor note component and `isCanvasEditorMode()` detection |
+| `utils_slots` | `getSlotChildren()` for parsing Canvas slot content |
+| `utils_entity` | `useMainEntity()` hook for fetching the page's main entity |
+
+## Test Helpers
+
+Built JS entry points for use in Storybook test stories.
+
+### Simulating Canvas Slots
+
+Canvas delivers slot content as HTML containing `<canvas-island>` custom
+elements. In Storybook, use the canvas-slots helpers to replicate this format
+so components can be tested under realistic conditions.
+
+```js
+import {
+  createCanvasIsland,
+  createCanvasSlot,
+} from '@freelygive/canvas-utils/testing/canvas-slots';
+
+// Build the HTML that Canvas would produce for a slot containing two items
+const slotHtml = [
+  createCanvasIsland({ heading: 'First item', text: '<p>Content one.</p>' }),
+  createCanvasIsland({ heading: 'Second item', text: '<p>Content two.</p>' }),
+].join('');
+
+// Wrap it in a React element that getSlotChildren() can parse
+const canvasContent = createCanvasSlot(slotHtml);
+
+// Pass to the component as the slot prop
+export const WithCanvasSlot: Story = {
+  args: {
+    content: canvasContent,
+  },
+};
+```
+
+`rawProp(value)` is also exported for cases where you need to construct the
+`["raw", value]` tuple format manually.
+
+### Simulating Editor Mode
+
+Canvas editor mode changes component behaviour (e.g. expanding all accordion
+items for editing). Use the `withEditorMode` decorator to enable editor mode
+for the lifetime of a story:
+
+```js
+import { withEditorMode } from '@freelygive/canvas-utils/testing/editor-mode';
+
+export const InEditorMode: Story = {
+  args: { /* ... */ },
+  decorators: [withEditorMode],
+};
+```
+
+The decorator enables editor mode before the first render and cleans up on
+unmount via `useEffect`, so state is restored even when tests are interrupted
+or Storybook navigates away.
+
+`enableEditorMode()` and `disableEditorMode()` are also exported for cases
+that need direct control.
+
+## Setup
+
+Add the package and configure npm-scaffold in your project's `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@freelygive/canvas-utils": "^0.1.0"
+  },
+  "scripts": {
+    "postinstall": "npm-scaffold"
+  },
+  "npmScaffold": {
+    "allowed-packages": ["@freelygive/canvas-utils"],
+    "base-path": "src"
+  }
+}
+```
+
+Running `npm install` will scaffold the utility components into
+`src/components/` as symlinks and add them to `.gitignore`.
+
+## API Reference
+
+### canvas-slots
+
+| Export | Description |
+|---|---|
+| `rawProp(value)` | Wraps a value in the `["raw", value]` tuple format used by Canvas island props |
+| `createCanvasIsland(props)` | Creates a `<canvas-island>` HTML string from a props object |
+| `createCanvasSlot(html)` | Creates a React element simulating a Canvas slot for `getSlotChildren()` to parse |
+
+### editor-mode
+
+| Export | Description |
+|---|---|
+| `withEditorMode` | Storybook decorator — enables editor mode before render, cleans up on unmount |
+| `enableEditorMode()` | Sets `window.drupalSettings.canvas` to simulate Canvas editor mode |
+| `disableEditorMode()` | Removes `window.drupalSettings.canvas` |

package/dist/editor-mode.d.ts

@@ -1,6 +1,8 @@
+import React from 'react';
+
 /**
- * Enable Canvas editor mode for a story
- * Sets drupalSettings.canvas and cleans up on unmount
+ * Enable Canvas editor mode
+ * Sets drupalSettings.canvas to simulate the Canvas page editor
  */
 declare const enableEditorMode: () => void;
 /**
@@ -8,5 +10,15 @@ declare const enableEditorMode: () => void;
  * Removes drupalSettings.canvas
  */
 declare const disableEditorMode: () => void;
+/**
+ * Storybook decorator that enables Canvas editor mode for the lifetime of a
+ * story. Enables before the first render and cleans up on unmount, so editor
+ * state is restored even when tests are interrupted or Storybook navigates
+ * away.
+ *
+ * Usage:
+ *   decorators: [withEditorMode]
+ */
+declare const withEditorMode: (Story: React.ComponentType) => React.ReactElement<{}, string | React.JSXElementConstructor<any>> | null;
 
-export { disableEditorMode, enableEditorMode };
+export { disableEditorMode, enableEditorMode, withEditorMode };

package/dist/editor-mode.js

@@ -1,4 +1,5 @@
 // src/testing/editor-mode.ts
+import React, { useEffect, useState } from "react";
 var enableEditorMode = () => {
   window.drupalSettings = {
     ...window.drupalSettings,
@@ -11,8 +12,18 @@ var disableEditorMode = () => {
     delete win.drupalSettings.canvas;
   }
 };
+var withEditorMode = (Story) => {
+  const [ready] = useState(() => {
+    enableEditorMode();
+    return true;
+  });
+  useEffect(() => disableEditorMode, []);
+  if (!ready) return null;
+  return React.createElement(Story);
+};
 export {
   disableEditorMode,
-  enableEditorMode
+  enableEditorMode,
+  withEditorMode
 };
 //# sourceMappingURL=editor-mode.js.map

package/dist/editor-mode.js.map

@@ -1 +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":[]}
+{"version":3,"sources":["../src/testing/editor-mode.ts"],"sourcesContent":["import React, { useEffect, useState } from 'react';\n\n/**\n * Enable Canvas editor mode\n * Sets drupalSettings.canvas to simulate the Canvas page editor\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\n/**\n * Storybook decorator that enables Canvas editor mode for the lifetime of a\n * story. Enables before the first render and cleans up on unmount, so editor\n * state is restored even when tests are interrupted or Storybook navigates\n * away.\n *\n * Usage:\n *   decorators: [withEditorMode]\n */\nexport const withEditorMode = (Story: React.ComponentType) => {\n  const [ready] = useState(() => {\n    enableEditorMode();\n    return true;\n  });\n  useEffect(() => disableEditorMode, []);\n  if (!ready) return null;\n  return React.createElement(Story);\n};\n"],"mappings":";AAAA,OAAO,SAAS,WAAW,gBAAgB;AAMpC,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;AAWO,IAAM,iBAAiB,CAAC,UAA+B;AAC5D,QAAM,CAAC,KAAK,IAAI,SAAS,MAAM;AAC7B,qBAAiB;AACjB,WAAO;AAAA,EACT,CAAC;AACD,YAAU,MAAM,mBAAmB,CAAC,CAAC;AACrC,MAAI,CAAC,MAAO,QAAO;AACnB,SAAO,MAAM,cAAc,KAAK;AAClC;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freelygive/canvas-utils",
-  "version": "0.1.0",
+  "version": "0.2.0-dev.6dad937b",
   "description": "Canvas utility components and test helpers for Drupal Canvas projects.",
   "type": "module",
   "files": [

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

@@ -1,32 +0,0 @@
-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_entity/dist/index.js

@@ -1,74 +0,0 @@
-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_slots/dist/index.js

@@ -1,79 +0,0 @@
-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;