feat: initial setup of skiplink widget

HedwigJDoets · HedwigJDoets · commit b0791c5b4d5c · 2025-07-11T10:25:29.000+02:00
diff --git a/packages/pluggableWidgets/skiplink-web/README.md b/packages/pluggableWidgets/skiplink-web/README.md
@@ -0,0 +1,27 @@
+# SkipLink Web Widget
+
+A simple accessibility widget that adds a skip link to the top of the page. The link is only visible when focused and allows users to jump directly to the main content.
+
+## Usage
+
+1. Place the `<SkipLink />` component at the very top of your page or layout.
+2. Ensure your main content container has `id="main-content"`.
+
+    ```jsx
+    <SkipLink />
+    <main id="main-content">Main content here</main>
+    ```
+
+## Accessibility
+
+- The skip link is visually hidden except when focused, making it accessible for keyboard and screen reader users.
+
+## End-to-End Testing
+
+E2E tests are located in the `e2e/` folder and use Playwright. Run them with:
+
+```
+npm install
+npx playwright install
+npm test
+```
diff --git a/packages/pluggableWidgets/skiplink-web/e2e/SkipLink.spec.ts b/packages/pluggableWidgets/skiplink-web/e2e/SkipLink.spec.ts
@@ -0,0 +1,23 @@
+import { expect, test } from "@playwright/test";
+
+// Assumes the test project renders <SkipLink /> and a <main id="main-content"> element
+
+test.describe("SkipLink", () => {
+    test("should be hidden by default and visible on focus, and should skip to main content", async ({ page }) => {
+        await page.goto("/");
+        const skipLink = page.locator(".skip-link");
+        // Should be hidden by default
+        await expect(skipLink).toHaveCSS("transform", "matrix(1, 0, 0, 1, 0, -120)");
+        // Tab to focus the skip link
+        await page.keyboard.press("Tab");
+        await expect(skipLink).toBeVisible();
+        // Check if skipLink is the active element
+        const isFocused = await skipLink.evaluate(node => node === document.activeElement);
+        expect(isFocused).toBe(true);
+        // Press Enter to activate the link
+        await page.keyboard.press("Enter");
+        // The main content should be focused or scrolled into view
+        const main = page.locator("#main-content");
+        await expect(main).toBeVisible();
+    });
+});
diff --git a/packages/pluggableWidgets/skiplink-web/package.json b/packages/pluggableWidgets/skiplink-web/package.json
@@ -0,0 +1,50 @@
+{
+    "name": "@mendix/pluggable-widget-skiplink-web",
+    "widgetName": "SkipLink",
+    "version": "1.0.0",
+    "description": "Adds a skip link to the top of the page for accessibility.",
+    "copyright": "© Mendix Technology BV 2025. All rights reserved.",
+    "license": "Apache-2.0",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/mendix/web-widgets.git"
+    },
+    "config": {},
+    "mxpackage": {
+        "name": "SkipLink",
+        "type": "widget",
+        "mpkName": "com.mendix.widget.web.SkipLink.mpk"
+    },
+    "packagePath": "com.mendix.widget.web",
+    "marketplace": {
+        "minimumMXVersion": "9.6.0",
+        "appNumber": 119999,
+        "appName": "SkipLink",
+        "reactReady": true
+    },
+    "scripts": {
+        "build": "pluggable-widgets-tools build:web",
+        "create-gh-release": "rui-create-gh-release",
+        "create-translation": "rui-create-translation",
+        "dev": "pluggable-widgets-tools start:web",
+        "e2e": "run-e2e ci",
+        "e2edev": "run-e2e dev --with-preps",
+        "format": "prettier --ignore-path ./node_modules/@mendix/prettier-config-web-widgets/global-prettierignore --write .",
+        "lint": "eslint src/ package.json",
+        "publish-marketplace": "rui-publish-marketplace",
+        "release": "pluggable-widgets-tools release:web",
+        "start": "pluggable-widgets-tools start:server",
+        "test": "jest --projects jest.config.js",
+        "update-changelog": "rui-update-changelog-widget",
+        "verify": "rui-verify-package-format"
+    },
+    "devDependencies": {
+        "@mendix/automation-utils": "workspace:*",
+        "@mendix/eslint-config-web-widgets": "workspace:*",
+        "@mendix/pluggable-widgets-tools": "*",
+        "@mendix/prettier-config-web-widgets": "workspace:*",
+        "@mendix/run-e2e": "workspace:*",
+        "@mendix/widget-plugin-hooks": "workspace:*",
+        "@mendix/widget-plugin-platform": "workspace:*"
+    }
+}
diff --git a/packages/pluggableWidgets/skiplink-web/src/SkipLink.css b/packages/pluggableWidgets/skiplink-web/src/SkipLink.css
@@ -0,0 +1,20 @@
+.skip-link {
+    position: absolute;
+    top: 0;
+    left: 0;
+    background: #fff;
+    color: #0078d4;
+    padding: 8px 16px;
+    z-index: 1000;
+    transform: translateY(-120%);
+    transition: transform 0.2s;
+    text-decoration: none;
+    border: 2px solid #0078d4;
+    border-radius: 4px;
+    font-weight: bold;
+}
+
+.skip-link:focus {
+    transform: translateY(0);
+    outline: none;
+}
diff --git a/packages/pluggableWidgets/skiplink-web/src/SkipLink.tsx b/packages/pluggableWidgets/skiplink-web/src/SkipLink.tsx
@@ -0,0 +1,66 @@
+import "./SkipLink.css";
+import { useEffect } from "react";
+
+export interface SkipLinkProps {
+    /**
+     * The text displayed for the skip link.
+     */
+    linkText: string;
+    /**
+     * The id of the main content element to jump to.
+     */
+    mainContentId: string;
+}
+
+/**
+ * Inserts a skip link as the first child of the element with ID 'root'.
+ * When activated, focus is programmatically set to the main content.
+ */
+export function SkipLink({ linkText, mainContentId }: SkipLinkProps): null {
+    useEffect(() => {
+        // Create the skip link element
+        const link = document.createElement("a");
+        link.href = `#${mainContentId}`;
+        link.className = "skip-link";
+        link.textContent = linkText;
+        link.tabIndex = 0;
+
+        // Handler to move focus to the main content
+        function handleClick(event: MouseEvent) {
+            event.preventDefault();
+            const main = document.getElementById(mainContentId);
+            if (main) {
+                // Store previous tabindex
+                const prevTabIndex = main.getAttribute("tabindex");
+                // Ensure main is focusable
+                if (!main.hasAttribute("tabindex")) {
+                    main.setAttribute("tabindex", "-1");
+                }
+                main.focus();
+                // Clean up tabindex if it was not present before
+                if (prevTabIndex === null) {
+                    main.addEventListener("blur", () => main.removeAttribute("tabindex"), { once: true });
+                }
+            }
+        }
+
+        link.addEventListener("click", handleClick);
+
+        // Insert as the first child of the element with ID 'root'
+        const root = document.getElementById("root");
+        if (root) {
+            root.insertBefore(link, root.firstChild);
+        }
+
+        // Cleanup on unmount
+        return () => {
+            link.removeEventListener("click", handleClick);
+            if (link.parentNode) {
+                link.parentNode.removeChild(link);
+            }
+        };
+    }, [linkText, mainContentId]);
+
+    // This component does not render anything in the React tree
+    return null;
+}
diff --git a/packages/pluggableWidgets/skiplink-web/src/SkipLink.xml b/packages/pluggableWidgets/skiplink-web/src/SkipLink.xml
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<widget id="com.mendix.widget.web.skiplink.SkipLink" pluginWidget="true" offlineCapable="true" xmlns="http://www.mendix.com/widget/1.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.mendix.com/widget/1.0/ ../../../../node_modules/mendix/custom_widget.xsd">
+    <name>SkipLink</name>
+    <description>A skip link for accessibility, allowing users to jump directly to the main content.</description>
+    <studioProCategory>Accessibility</studioProCategory>
+    <studioCategory>Accessibility</studioCategory>
+    <helpUrl>https://docs.mendix.com/appstore/widgets/skiplink</helpUrl>
+    <properties>
+        <propertyGroup caption="General">
+            <property key="linkText" type="string" defaultValue="Skip to main content">
+                <caption>Link text</caption>
+                <description>The text displayed for the skip link.</description>
+            </property>
+            <property key="mainContentId" type="string" defaultValue="main-content">
+                <caption>Main content ID</caption>
+                <description>The id of the main content element to jump to.</description>
+            </property>
+        </propertyGroup>
+    </properties>
+</widget>
diff --git a/packages/pluggableWidgets/skiplink-web/src/package.xml b/packages/pluggableWidgets/skiplink-web/src/package.xml
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<package xmlns="http://www.mendix.com/package/1.0/">
+    <clientModule name="SkipLink" version="1.0.0" xmlns="http://www.mendix.com/clientModule/1.0/">
+        <widgetFiles>
+            <widgetFile path="SkipLink.xml" />
+        </widgetFiles>
+        <files>
+            <file path="com/mendix/widget/web/skiplink" />
+        </files>
+    </clientModule>
+</package>
diff --git a/packages/pluggableWidgets/skiplink-web/tsconfig.json b/packages/pluggableWidgets/skiplink-web/tsconfig.json
@@ -0,0 +1,25 @@
+{
+    "include": ["./src", "./typings"],
+    "compilerOptions": {
+        "baseUrl": "./",
+        "noEmitOnError": true,
+        "sourceMap": true,
+        "module": "esnext",
+        "target": "es6",
+        "lib": ["esnext", "dom"],
+        "types": ["jest", "node"],
+        "moduleResolution": "node",
+        "declaration": false,
+        "noLib": false,
+        "forceConsistentCasingInFileNames": true,
+        "noFallthroughCasesInSwitch": true,
+        "strict": true,
+        "strictFunctionTypes": false,
+        "skipLibCheck": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "jsx": "react-jsx",
+        "outDir": "dist",
+        "rootDir": "src"
+    }
+}
diff --git a/packages/pluggableWidgets/skiplink-web/typings/SkipLinkProps.d.ts b/packages/pluggableWidgets/skiplink-web/typings/SkipLinkProps.d.ts
@@ -0,0 +1,30 @@
+/**
+ * This file was generated from SkipLink.xml
+ * WARNING: All changes made to this file will be overwritten
+ * @author Mendix Widgets Framework Team
+ */
+import { CSSProperties } from "react";
+
+export interface SkipLinkContainerProps {
+    name: string;
+    class: string;
+    style?: CSSProperties;
+    tabIndex?: number;
+    linkText: string;
+    mainContentId: string;
+}
+
+export interface SkipLinkPreviewProps {
+    /**
+     * @deprecated Deprecated since version 9.18.0. Please use class property instead.
+     */
+    className: string;
+    class: string;
+    style: string;
+    styleObject?: CSSProperties;
+    readOnly: boolean;
+    renderMode: "design" | "xray" | "structure";
+    translate: (text: string) => string;
+    linkText: string;
+    mainContentId: string;
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
