HTML Tool PoC spike for fragment defined in type index

docs/elements/components/pos-html-tool/readme.md

@@ -0,0 +1,14 @@
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property   | Attribute  | Description                          | Type     | Default     |
+| ---------- | ---------- | ------------------------------------ | -------- | ----------- |
+| `fragment` | `fragment` | HTML fragment to sanitize and render | `string` | `undefined` |
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

elements/package.json

@@ -33,6 +33,7 @@
     "@tiptap/pm": "^3.10.1",
     "@tiptap/starter-kit": "^3.10.1",
     "@uvdsl/solid-oidc-client-browser": "^0.1.3",
+    "dompurify": "^3.3.0",
     "idb": "^8.0.3",
     "neverthrow": "^8.2.0",
     "pollen-css": "^5.0.2",

elements/src/components.d.ts

@@ -66,6 +66,12 @@ export namespace Components {
     }
     interface PosGettingStarted {
     }
+    interface PosHtmlTool {
+        /**
+          * HTML fragment to sanitize and render
+         */
+        "fragment": string;
+    }
     /**
      * Tries fetch an image with the solid authentication, and can visualize http errors like 403 or 404 if this fails.
      * Falls back to classic `<img src="...">` on network errors like CORS.
@@ -625,6 +631,12 @@ declare global {
         prototype: HTMLPosGettingStartedElement;
         new (): HTMLPosGettingStartedElement;
     };
+    interface HTMLPosHtmlToolElement extends Components.PosHtmlTool, HTMLStencilElement {
+    }
+    var HTMLPosHtmlToolElement: {
+        prototype: HTMLPosHtmlToolElement;
+        new (): HTMLPosHtmlToolElement;
+    };
     interface HTMLPosImageElementEventMap {
         "pod-os:init": any;
         "pod-os:resource-loaded": string;
@@ -1113,6 +1125,7 @@ declare global {
         "pos-error-toast": HTMLPosErrorToastElement;
         "pos-example-resources": HTMLPosExampleResourcesElement;
         "pos-getting-started": HTMLPosGettingStartedElement;
+        "pos-html-tool": HTMLPosHtmlToolElement;
         "pos-image": HTMLPosImageElement;
         "pos-internal-router": HTMLPosInternalRouterElement;
         "pos-label": HTMLPosLabelElement;
@@ -1238,6 +1251,12 @@ declare namespace LocalJSX {
     interface PosGettingStarted {
         "onPod-os:login"?: (event: PosGettingStartedCustomEvent<void>) => void;
     }
+    interface PosHtmlTool {
+        /**
+          * HTML fragment to sanitize and render
+         */
+        "fragment"?: string;
+    }
     /**
      * Tries fetch an image with the solid authentication, and can visualize http errors like 403 or 404 if this fails.
      * Falls back to classic `<img src="...">` on network errors like CORS.
@@ -1476,6 +1495,7 @@ declare namespace LocalJSX {
         "pos-error-toast": PosErrorToast;
         "pos-example-resources": PosExampleResources;
         "pos-getting-started": PosGettingStarted;
+        "pos-html-tool": PosHtmlTool;
         "pos-image": PosImage;
         "pos-internal-router": PosInternalRouter;
         "pos-label": PosLabel;
@@ -1533,6 +1553,7 @@ declare module "@stencil/core" {
             "pos-error-toast": LocalJSX.PosErrorToast & JSXBase.HTMLAttributes<HTMLPosErrorToastElement>;
             "pos-example-resources": LocalJSX.PosExampleResources & JSXBase.HTMLAttributes<HTMLPosExampleResourcesElement>;
             "pos-getting-started": LocalJSX.PosGettingStarted & JSXBase.HTMLAttributes<HTMLPosGettingStartedElement>;
+            "pos-html-tool": LocalJSX.PosHtmlTool & JSXBase.HTMLAttributes<HTMLPosHtmlToolElement>;
             /**
              * Tries fetch an image with the solid authentication, and can visualize http errors like 403 or 404 if this fails.
              * Falls back to classic `<img src="...">` on network errors like CORS.

elements/src/components/pos-html-tool/pos-html-tool.integration.spec.tsx

@@ -0,0 +1,38 @@
+import { newSpecPage } from '@stencil/core/testing';
+import { mockPodOS } from '../../test/mockPodOS';
+import { PosHtmlTool } from './pos-html-tool';
+import { PosApp } from '../pos-app/pos-app';
+import { PosLabel } from '../pos-label/pos-label';
+import { PosResource } from '../pos-resource/pos-resource';
+import { Thing } from '@pod-os/core';
+import { when } from 'jest-when';
+
+describe('pos-html-tool', () => {
+  it('respects the resource event and renders inserted pos-label', async () => {
+    const os = mockPodOS();
+    when(os.store.get)
+      .calledWith('https://resource.test')
+      .mockReturnValue({
+        label: () => 'Test Resource',
+      } as unknown as Thing);
+    const page = await newSpecPage({
+      components: [PosApp, PosResource, PosLabel, PosHtmlTool],
+      html: `<pos-app>
+            <pos-resource uri="https://resource.test" lazy="true">
+              <pos-html-tool/>
+            </pos-resource>
+        </pos-app>`,
+    });
+    const el = page.root?.querySelector('pos-html-tool') as unknown as PosHtmlTool;
+    el.fragment = '<pos-label></pos-label>';
+    await page.waitForChanges();
+    const label = page.root?.querySelector('pos-label');
+    expect(label).toEqualHtml(`
+      <pos-label>
+        <mock:shadow-root>
+          Test Resource
+        </mock:shadow-root>
+      </pos-label>
+  `);
+  });
+});

elements/src/components/pos-html-tool/pos-html-tool.spec.tsx

@@ -0,0 +1,20 @@
+/**
+ * @jest-environment @happy-dom/jest-environment
+ *
+ * => dompurify needs a real DOM to work
+ */
+
+import { newSpecPage } from '@stencil/core/testing';
+import { PosHtmlTool } from './pos-html-tool';
+
+describe('pos-html-tool', () => {
+  it('inserts sanitized HTML into the page', async () => {
+    const page = await newSpecPage({
+      components: [PosHtmlTool],
+      html: `<pos-html-tool/>`,
+    });
+    page.rootInstance.fragment = '<pos-label></pos-label>';
+    await page.waitForChanges();
+    expect(page.root?.innerHTML).toEqualHtml('<pos-label></pos-label>');
+  });
+});

elements/src/components/pos-html-tool/pos-html-tool.tsx

@@ -0,0 +1,17 @@
+import { Component, h, Host, Prop } from '@stencil/core';
+import { sanitizeHtmlTool } from './sanitizeHtmlTool';
+
+@Component({
+  tag: 'pos-html-tool',
+  shadow: false,
+})
+export class PosHtmlTool {
+  /**
+   * HTML fragment to sanitize and render
+   */
+  @Prop() fragment: string;
+
+  render() {
+    return <Host innerHTML={sanitizeHtmlTool(this.fragment)}></Host>;
+  }
+}

elements/src/components/pos-html-tool/sanitizeHtmlTool.spec.tsx

@@ -0,0 +1,19 @@
+/**
+ * @jest-environment @happy-dom/jest-environment
+ *
+ * => dompurify needs a real DOM to work
+ */
+
+import { sanitizeHtmlTool } from './sanitizeHtmlTool';
+
+describe('sanitizeHtmlTool', () => {
+  it('keeps whitelisted elements', () => {
+    const sanitized = sanitizeHtmlTool('<pos-label></pos-label>');
+    expect(sanitized).toEqual('<pos-label></pos-label>');
+  });
+
+  it('removes unknown HTML elements from fragment', () => {
+    const sanitized = sanitizeHtmlTool('<unknown-element>');
+    expect(sanitized).toEqual('');
+  });
+});

elements/src/components/pos-html-tool/sanitizeHtmlTool.tsx

@@ -0,0 +1,5 @@
+import DOMPurify from 'dompurify';
+
+export function sanitizeHtmlTool(htmlToolFragment: string) {
+  return DOMPurify.sanitize(htmlToolFragment, { ADD_TAGS: ['pos-label'] });
+}

elements/src/components/pos-label/pos-label.sanitizeHtmlTool.spec.tsx

@@ -0,0 +1,13 @@
+/**
+ * @jest-environment @happy-dom/jest-environment
+ *
+ * => dompurify needs a real DOM to work
+ */
+import { sanitizeHtmlTool } from '../pos-html-tool/sanitizeHtmlTool';
+
+describe('pos-label', () => {
+  it('is whitelisted by sanitizeHtmlTool', () => {
+    const sanitized = sanitizeHtmlTool('<pos-label/>');
+    expect(sanitized).toEqual('<pos-label></pos-label>');
+  });
+});

elements/src/components/pos-type-router/pos-type-router.spec.tsx

@@ -136,6 +136,29 @@ describe('pos-type-router', () => {
 `);
   });
 
+  it('renders HTML tool if available', async () => {
+    const page = await newSpecPage({
+      components: [PosTypeRouter],
+      html: `<pos-type-router />`,
+      supportsShadowDom: false,
+    });
+    await page.rootInstance.receiveResource({
+      types: () => [{ uri: 'https://schema.org/Recipe', label: 'Recipe' }],
+    });
+    await page.waitForChanges();
+
+    expect(page.root).toEqualHtml(`
+    <pos-type-router>
+      <section>
+        <pos-tool-select></pos-tool-select>
+        <div class="tools">
+          <pos-html-tool class="tool visible" fragment="<pos-label/>"></pos-html-tool>
+        </div>
+      </section>
+    </pos-type-router>
+`);
+  });
+
   it('renders the selected tool and updates query param', async () => {
     const page = await newSpecPage({
       components: [PosTypeRouter],

elements/src/components/pos-type-router/pos-type-router.tsx

@@ -1,7 +1,7 @@
 import { Thing } from '@pod-os/core';
 import { Component, Event, EventEmitter, h, Listen, State } from '@stencil/core';
 import { ResourceAware, subscribeResource } from '../events/ResourceAware';
-import { selectToolsForTypes, ToolConfig } from './selectToolsForTypes';
+import { HTMLToolConfig, selectToolsForTypes, ToolConfig } from './selectToolsForTypes';
 
 /**
  * This component is responsible for rendering tools that are useful to interact with the current resource.
@@ -43,7 +43,21 @@ export class PosTypeRouter implements ResourceAware {
 
   receiveResource = (resource: Thing) => {
     const types = resource.types();
-    this.availableTools = selectToolsForTypes(types);
+    const registeredTools = [
+      {
+        element: 'pos-html-tool',
+        label: 'Example tool',
+        icon: 'list-ul',
+        types: [
+          {
+            uri: 'https://schema.org/Recipe',
+            priority: 20,
+          },
+        ],
+        fragment: '<pos-label/>',
+      },
+    ];
+    this.availableTools = selectToolsForTypes(types, registeredTools);
     this.currentTool = this.availableTools.find(it => it.element === this.initialTool) ?? this.availableTools[0];
   };
 
@@ -59,7 +73,14 @@ export class PosTypeRouter implements ResourceAware {
         <pos-tool-select selected={this.currentTool} tools={this.availableTools}></pos-tool-select>
         <div class={{ tools: true, transition: this.transitioning }} onAnimationEnd={() => this.removeOldTool()}>
           {OldTool && <OldTool class="tool hidden"></OldTool>}
-          <SelectedTool class="tool visible"></SelectedTool>
+          {SelectedTool == 'pos-html-tool' ? (
+            <pos-html-tool
+              fragment={(this.currentTool as HTMLToolConfig).fragment}
+              class="tool visible"
+            ></pos-html-tool>
+          ) : (
+            <SelectedTool class="tool visible"></SelectedTool>
+          )}
         </div>
       </section>
     );

elements/src/components/pos-type-router/selectToolsForTypes.spec.ts

@@ -97,4 +97,23 @@ describe('select tools for types', () => {
       AvailableTools.Generic,
     ]);
   });
+
+  it('favours HTML tool over generic if one is available', () => {
+    const registeredTools = [
+      {
+        element: 'pos-html-tool',
+        label: 'Example tool',
+        icon: 'list-ul',
+        types: [
+          {
+            uri: 'https://schema.org/Recipe',
+            priority: 20,
+          },
+        ],
+      },
+    ];
+    const types = [{ uri: 'https://schema.org/Recipe', label: 'Recipe' }];
+    const tools = selectToolsForTypes(types, registeredTools);
+    expect(tools).toEqual([registeredTools[0], AvailableTools.Generic]);
+  });
 });

elements/src/components/pos-type-router/selectToolsForTypes.ts

@@ -24,6 +24,13 @@ export interface ToolConfig {
   types: TypePriority[];
 }
 
+/**
+ * Describes a tool that can be used implemented as a HTML fragment
+ */
+export interface HTMLToolConfig extends ToolConfig {
+  fragment: string;
+}
+
 /**
  * Describes how well a given RDF type can be handled
  */
@@ -52,10 +59,10 @@ interface ToolPriority {
   priority: number;
 }
 
-export function selectToolsForTypes(types: RdfType[]) {
+export function selectToolsForTypes(types: RdfType[], registeredTools: ToolConfig[] = []) {
   const typeUris = new Set(types.map(type => type.uri));
 
-  return Object.values(AvailableTools)
+  return [...Object.values(AvailableTools), ...registeredTools]
     .map(maxPriorityFor(typeUris))
     .filter(onlyRelevant)
     .toSorted(byPriority)