@learningpool/ui 2.3.6 → 2.4.1

package/components/feedback/FeedbackRating/FeedbackRating.d.ts

@@ -0,0 +1,79 @@
+import React from 'react';
+interface FeedbackRatingProps {
+    /** Required: Unique identifier for the feature this feedback is associated with
+     * Example: enrolment-reasons-sidebar
+     */
+    featureId: string;
+    /** Required: Product identifier to differentiate between different applications in the results
+     * Example: LRS
+     */
+    productId: string;
+    /**
+     * Required only when using the built-in Hub endpoint (i.e., when `token` is provided and `submitRating` is not).
+     * Used as the x-api-key header for authenticating through AWS Gateway for the Hub feedback endpoint.
+     * Example: 'abcd1234efgh5678ijkl9012mnop3456'
+     */
+    apiKey?: string;
+    /**
+     * Auth token for Hub endpoint, if no token is provided then feedback won't be logged.
+     * If not providing, please provide your own `submitRating` to handle Hub API
+     */
+    token?: string;
+    /** Optional callback invoked when the user selects a rating.
+     * If provided, this overrides the built‑in Hub submission logic.
+     */
+    submitRating?: (rating: number, featureId: string) => Promise<void> | void;
+    /** Optional message shown next to the rating control
+     * Defaults to "We've made some changes. Share your feedback with a star rating."
+     */
+    message?: React.ReactNode;
+    /**
+     * Optional user email to forward to the Hub endpoint (validated as an email by the API).
+     */
+    email?: string;
+    /**
+     * Optional Base URL for the external feedback form (e.g., Google Form).
+     * The component will append prefill parameters (rating, featureId, productId, pageUrl).
+     * Defaults to DEFAULT_FEEDBACK_FORM_URL
+     */
+    feedbackFormUrl?: string;
+    /**
+     * Optional Base URL for the Hub, used to build feedback links, so that an environment variable can be used in staging environments
+     * Example: https://api.home-staging.learningpool.com/
+     * Note: must include trailing slash
+     */
+    hubBaseUrl?: string;
+    /**
+     * Customer identifier required by the Hub endpoint when using the built-in submit.
+     * If omitted, an empty string will be sent in the payload. Provide your own `submitRating` to override if you need custom logic.
+     * Example: org-12345
+     */
+    customerId?: string;
+    /**
+     * Optional expiry for showing the component.
+     * When the current time is beyond this timestamp, the component will render null and not show.
+     * Accepts an ISO 8601 date-time string (e.g., '2026-03-01T00:00:00Z').
+     */
+    expiresAt?: string;
+    /**
+     * Optional page URL override used in payloads and links. If omitted, the component will use the current window location when available.
+     */
+    pageUrl?: string;
+    /**
+     * Optional test id prefix to help with testing across apps
+     */
+    testIdPrefix?: string;
+    /**
+     * Optional metadata object to include with the Hub payload.
+     * Keys must be non-empty strings (<=255). Values may be string (<=255), number, or boolean. Max ~10 entries enforced server-side.
+     */
+    metadata?: Record<string, string | number | boolean>;
+}
+/**
+ * A dismissible feedback bar with 5-star rating.
+ * - Saves rating and dismiss state to localStorage, scoped by featureId
+ * - Calls `submitRating` on star click (or a placeholder POST)
+ * - After rating, shows a link to provide more feedback (opens in new tab)
+ */
+export default function FeedbackRating({ featureId, productId, apiKey, token, submitRating, message, email, feedbackFormUrl, hubBaseUrl, customerId, expiresAt, pageUrl, testIdPrefix, metadata }: FeedbackRatingProps): JSX.Element | null;
+export {};

package/components/feedback/FeedbackRating/FeedbackRating.js

@@ -0,0 +1,201 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "@emotion/react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import CloseIcon from '@mui/icons-material/Close';
+import { Alert, Box, Button, Collapse, Link, Rating, Stack, Typography, useTheme } from '@mui/material';
+import { Constants } from '../../stream/AppSwitcher/constants';
+import { defaultMessages } from '../../../lang/en-us';
+const LOCAL_STORAGE_PREFIX = 'admin-feedback';
+const DISMISS_ANIMATION_DELAY_MS = 300;
+const GOOGLE_FORM_CONFIG = {
+    BASE_URL: 'https://docs.google.com/forms/d/e/1FAIpQLSfKJTrprcJcAKYOykMmx56jC7ajuu9LIq52Uc1u2hqnLmgt0w/viewform',
+    PARAMS: {
+        usp: 'pp_url',
+        rating: 'entry.436394498',
+        email: 'entry.967663492',
+        featureId: 'entry.1339542182',
+        orgAlias: 'entry.444516590',
+        productId: 'entry.398489558',
+        pageUrl: 'entry.1804127593'
+    }
+};
+const DEFAULT_FEEDBACK_FORM_URL = GOOGLE_FORM_CONFIG.BASE_URL;
+const defaultMessageNode = (_jsxs(_Fragment, { children: [_jsx("strong", { children: defaultMessages['feedback-message-prefix'] }), ' ', defaultMessages['feedback-message-suffix']] }));
+/**
+ * A dismissible feedback bar with 5-star rating.
+ * - Saves rating and dismiss state to localStorage, scoped by featureId
+ * - Calls `submitRating` on star click (or a placeholder POST)
+ * - After rating, shows a link to provide more feedback (opens in new tab)
+ */
+export default function FeedbackRating({ featureId, productId, apiKey, token, submitRating, message, email, feedbackFormUrl, hubBaseUrl, customerId, expiresAt, pageUrl, testIdPrefix, metadata }) {
+    const theme = useTheme();
+    const localStorageKeys = useMemo(() => ({
+        rating: `${LOCAL_STORAGE_PREFIX}-rating-${featureId}`,
+        dismissed: `${LOCAL_STORAGE_PREFIX}-dismissed-${featureId}`
+    }), [featureId]);
+    const [open, setOpen] = useState(true);
+    const [isDismissed, setIsDismissed] = useState(false);
+    const [rating, setRating] = useState(null);
+    const hubFeedbackUrl = hubBaseUrl || Constants.BaseUrl;
+    const userMessage = message ?? defaultMessageNode;
+    const resolvedPageUrl = pageUrl ?? (typeof window !== 'undefined' ? window.location.href : '');
+    const testIdPrefixValue = testIdPrefix ?? 'feedback-rating';
+    const buildDefaultFeedbackUrl = useCallback((value) => {
+        const baseFormUrl = feedbackFormUrl || DEFAULT_FEEDBACK_FORM_URL;
+        // Use Google Form entry IDs for prefill
+        const params = new URLSearchParams({
+            [GOOGLE_FORM_CONFIG.PARAMS.usp]: 'pp_url',
+            [GOOGLE_FORM_CONFIG.PARAMS.email]: email || '',
+            [GOOGLE_FORM_CONFIG.PARAMS.featureId]: featureId,
+            [GOOGLE_FORM_CONFIG.PARAMS.orgAlias]: customerId || '',
+            [GOOGLE_FORM_CONFIG.PARAMS.productId]: productId,
+            [GOOGLE_FORM_CONFIG.PARAMS.pageUrl]: resolvedPageUrl
+        });
+        if (value != null && value >= 1 && value <= 5) {
+            params.append(GOOGLE_FORM_CONFIG.PARAMS.rating, value.toString());
+        }
+        return `${baseFormUrl}?${params.toString()}`;
+    }, [feedbackFormUrl, featureId, customerId, productId, resolvedPageUrl, email]);
+    const expiryTimestamp = useMemo(() => {
+        if (expiresAt == null) {
+            return undefined;
+        }
+        const parsed = Date.parse(expiresAt);
+        return Number.isNaN(parsed) ? undefined : parsed;
+    }, [expiresAt]);
+    const isExpired = useMemo(() => {
+        if (expiryTimestamp == null)
+            return false;
+        return Date.now() >= expiryTimestamp;
+    }, [expiryTimestamp]);
+    useEffect(() => {
+        try {
+            const ls = typeof window !== 'undefined' ? window.localStorage : undefined;
+            const storedDismissed = ls?.getItem(localStorageKeys.dismissed);
+            const storedRating = ls?.getItem(localStorageKeys.rating);
+            if (storedDismissed === 'true') {
+                setIsDismissed(true);
+            }
+            if (storedRating) {
+                const parsed = Number(storedRating);
+                if (!Number.isNaN(parsed) && parsed >= 1 && parsed <= 5) {
+                    setRating(parsed);
+                }
+            }
+        }
+        catch {
+            // ignore localStorage errors
+        }
+    }, [localStorageKeys.dismissed, localStorageKeys.rating]);
+    const saveRating = useCallback((value) => {
+        try {
+            const ls = typeof window !== 'undefined' ? window.localStorage : undefined;
+            ls?.setItem(localStorageKeys.rating, String(value));
+        }
+        catch {
+            // ignore localStorage errors
+        }
+    }, [localStorageKeys.rating]);
+    const dismiss = useCallback(() => {
+        try {
+            const ls = typeof window !== 'undefined' ? window.localStorage : undefined;
+            ls?.setItem(localStorageKeys.dismissed, 'true');
+        }
+        catch {
+            // ignore localStorage errors
+        }
+        setIsDismissed(true);
+    }, [localStorageKeys.dismissed]);
+    const defaultSubmit = useCallback(async (value) => {
+        try {
+            if (!productId || !customerId) {
+                console.warn('[FeedbackRating] Missing productId or customerId; skipping default submit. Provide both or pass a custom submitRating.');
+                return;
+            }
+            if (!resolvedPageUrl) {
+                console.warn('[FeedbackRating] pageUrl unavailable; skipping default submit.');
+                return;
+            }
+            if (!token || !apiKey) {
+                console.warn('[FeedbackRating] Invalid token or apiKey prop: feedback won\'t be stored.');
+                return;
+            }
+            const headers = {
+                'Content-Type': 'application/json',
+                'x-api-key': apiKey,
+                Authorization: token
+            };
+            const payload = {
+                rating: value,
+                featureId,
+                productId,
+                customerId,
+                pageUrl: resolvedPageUrl,
+                metadata: metadata ?? {}
+            };
+            if (email) {
+                payload.email = email;
+            }
+            const response = await fetch(`${hubFeedbackUrl}feedback`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(payload)
+            });
+            if (response.ok === false) {
+                console.error('[FeedbackRating] Failed to submit feedback', await response.text());
+            }
+        }
+        catch (error) {
+            console.error('[FeedbackRating] Error submitting feedback', error);
+        }
+    }, [productId, customerId, featureId, hubFeedbackUrl, email, metadata, resolvedPageUrl, token, apiKey]);
+    const handleStarClick = useCallback(async (value) => {
+        setRating(value);
+        saveRating(value);
+        await (submitRating ? submitRating(value, featureId) : defaultSubmit(value));
+    }, [saveRating, submitRating, defaultSubmit, featureId]);
+    const handleDismiss = useCallback(() => {
+        setOpen(false);
+        setTimeout(() => {
+            dismiss();
+        }, DISMISS_ANIMATION_DELAY_MS);
+    }, [dismiss]);
+    if (isDismissed || isExpired) {
+        return null;
+    }
+    const feedbackUrl = buildDefaultFeedbackUrl(rating);
+    return (_jsx(Box, { sx: { marginBottom: theme.spacing(2) }, children: _jsx(Collapse, { in: open, children: _jsx(Alert, { severity: 'info', icon: false, sx: {
+                    display: 'flex',
+                    alignItems: 'center',
+                    overflowX: 'hidden',
+                    '& .MuiAlert-message': {
+                        width: '100%',
+                        minWidth: 0,
+                        overflow: 'hidden',
+                        display: 'block'
+                    }
+                }, "data-testid": `${testIdPrefixValue}-alert-${featureId}`, action: _jsx(Button, { color: 'inherit', size: 'small', onClick: handleDismiss, "data-testid": `${testIdPrefixValue}-dismiss-${featureId}`, sx: { alignSelf: 'center', minWidth: 0, padding: 0 }, "aria-label": defaultMessages.dismiss, children: _jsx(CloseIcon, { fontSize: 'small' }) }), children: _jsxs(Box, { sx: {
+                        display: 'flex',
+                        alignItems: 'center',
+                        justifyContent: 'space-between',
+                        width: '100%',
+                        gap: 2,
+                        minWidth: 0
+                    }, children: [_jsxs(Stack, { children: [_jsx(Typography, { variant: 'subtitle2', sx: {
+                                        flex: 1,
+                                        minWidth: 0,
+                                        whiteSpace: 'normal',
+                                        overflowWrap: 'anywhere',
+                                        wordBreak: 'break-word'
+                                    }, children: userMessage }), _jsx(Link, { href: feedbackUrl, target: '_blank', rel: 'noopener noreferrer', underline: 'hover', variant: 'body2', "data-testid": `${testIdPrefixValue}-more-${featureId}`, children: defaultMessages['feedback-message-more-text'] })] }), _jsx(Rating, { name: `feedback-rating-${featureId}`, value: rating, onChange: (_event, newValue) => {
+                                if (newValue) {
+                                    handleStarClick(newValue);
+                                }
+                            }, sx: {
+                                display: 'flex',
+                                alignSelf: 'center',
+                                alignItems: 'center',
+                                '& .MuiRating-iconFilled': { color: theme.palette.info.main },
+                                '& .MuiRating-iconHover': { color: theme.palette.info.light },
+                                cursor: 'pointer'
+                            }, "data-testid": `${testIdPrefixValue}-stars-${featureId}` })] }) }) }) }));
+}

package/index.d.ts

@@ -135,3 +135,4 @@ export { default as AppSwitcher } from './components/stream/AppSwitcher/AppSwitc
 export { default as Header } from './components/landmarks/Header/Header';
 export { default as MobileNavigation } from './components/navigation/MobileNavigation/MobileNavigation';
 export { default as VerticalNavigation } from './components/navigation/VerticalNavigation/VerticalNavigation';
+export { default as FeedbackRating } from './components/feedback/FeedbackRating/FeedbackRating';

package/index.js

@@ -146,3 +146,4 @@ export { default as AppSwitcher } from './components/stream/AppSwitcher/AppSwitc
 export { default as Header } from './components/landmarks/Header/Header';
 export { default as MobileNavigation } from './components/navigation/MobileNavigation/MobileNavigation';
 export { default as VerticalNavigation } from './components/navigation/VerticalNavigation/VerticalNavigation';
+export { default as FeedbackRating } from './components/feedback/FeedbackRating/FeedbackRating';

package/lang/en-us.d.ts

@@ -28,4 +28,8 @@ export const defaultMessages: {
     'help-center': string;
     'submit-feedback': string;
     'contact-us': string;
+    'feedback-message-prefix': string;
+    'feedback-message-suffix': string;
+    'feedback-message-more-text': string;
+    dismiss: string;
 };

package/lang/en-us.js

@@ -30,5 +30,10 @@ export const defaultMessages = {
     support: 'Support',
     'help-center': 'Help Centre',
     'submit-feedback': 'Submit Feedback',
-    'contact-us': 'Contact Us'
+    'contact-us': 'Contact Us',
+    // Feedback Rating
+    'feedback-message-prefix': "We've made some changes.",
+    'feedback-message-suffix': 'Share your feedback with a star rating.',
+    'feedback-message-more-text': 'Give Further Feedback',
+    dismiss: 'Dismiss'
 };

package/package.json

@@ -9,7 +9,7 @@
     "components",
     "ui"
   ],
-  "version": "2.3.6",
+  "version": "2.4.1",
   "private": false,
   "main": "index.js",
   "module": "index.js",