@visns-studio/visns-components 6.0.5 → 6.1.0

package/package.json

@@ -91,7 +91,7 @@
         "react-dom": "^17.0.0 || ^18.0.0"
     },
     "name": "@visns-studio/visns-components",
-    "version": "6.0.5",
+    "version": "6.1.0",
     "description": "Various packages to assist in the development of our Custom Applications.",
     "main": "src/index.js",
     "files": [

package/src/components/DataGrid.jsx

@@ -1305,6 +1305,11 @@ const DataGrid = forwardRef(
 
         const handleSettingClick = (s, d) => {
             switch (s.id) {
+                case 'cloudDownload':
+                    // File download: open the URL directly and let the
+                    // browser handle the response's content disposition.
+                    window.open(`${s.url}/${d[s.key]}`, '_blank');
+                    break;
                 case 'activate':
                 case 'arrowCycle':
                 case 'cloudUpload':
@@ -3231,6 +3236,8 @@ const DataGrid = forwardRef(
                         return getIconComponent(RefreshCw);
                     case 'cloudUpload':
                         return getIconComponent(Upload);
+                    case 'cloudDownload':
+                        return getIconComponent(DownloadIcon);
                     case 'oauth2':
                         return getIconComponent(Lock);
                     case 'clone':

package/src/components/Navigation.jsx

@@ -361,6 +361,7 @@ function Navigation({
                     <ul className={styles.navDropdown}>
                         {n.children.map(
                             (child, childKey) =>
+                                child.hidden !== true &&
                                 child.permission === true && (
                                     <li key={`nav-child-${childKey}`}>
                                         <Link
@@ -422,11 +423,57 @@ function Navigation({
         return [];
     };
 
+    /**
+     * Feature switches, if the consuming app publishes any.
+     *
+     * A platform owner can retire a half-finished feature from the menu
+     * without a deploy, so the profile response may carry a map of feature
+     * ids that are switched off. Apps that publish nothing get `null` and
+     * behave exactly as before — this filter is additive, and every unknown
+     * id stays visible, so a stale or missing map can never empty a menu.
+     */
+    const getFeatureFlags = () => {
+        const flags = userProfile?.feature_visibility;
+
+        if (!flags || typeof flags !== 'object') {
+            return null;
+        }
+
+        // The map is keyed by app; this component only ever draws the console.
+        const appFlags = flags.backend;
+
+        return appFlags && typeof appFlags === 'object' ? appFlags : null;
+    };
+
     useEffect(() => {
         const permissions = getUserPermissions();
+        const featureFlags = getFeatureFlags();
+
+        // Carried as its own flag rather than folded into `permission`: an
+        // item with an empty permissionKey renders whatever its permission
+        // says, and this state has to be reversible — switching a feature
+        // back on must restore the menu item without a page reload, which
+        // dropping it from the list would not.
+        const isSwitchedOff = (nav) =>
+            featureFlags !== null &&
+            Boolean(nav.id) &&
+            featureFlags[nav.id] === false;
 
         setNavData((prevNavData) => {
             const updatePermissions = (nav) => {
+                const hidden = isSwitchedOff(nav);
+
+                // Reserved for the platform owner — a privilege that sits
+                // above the roles an administrator can hand out, so it is
+                // never expressed as a permission key.
+                if (nav.superAdminOnly === true) {
+                    return {
+                        ...nav,
+                        hidden,
+                        permission: Boolean(userProfile?.is_super_admin),
+                    };
+                }
+
                 if (nav.children && nav.children.length > 0) {
                     const updatedChildren = nav.children
                         .map(updatePermissions)
@@ -439,12 +486,14 @@ function Navigation({
                         );
                         return {
                             ...nav,
+                            hidden,
                             permission: matchingPermission,
                             children: updatedChildren,
                         };
                     } else {
                         return {
                             ...nav,
+                            hidden,
                             permission: childPermission,
                             children: updatedChildren,
                         };
@@ -457,12 +506,14 @@ function Navigation({
                     );
                     return {
                         ...nav,
+                        hidden,
                         permission: matchingPermission,
                     };
                 }
 
                 return {
                     ...nav,
+                    hidden,
                     permission: true,
                 };
             };
@@ -620,8 +671,9 @@ function Navigation({
                     <nav className={styles.navwrap} ref={navWrapRef}>
                         <ul className={appNavClasses}>
                             {navData.navigations.map((nav, navKey) =>
-                                nav.permission === true ||
-                                nav.permissionKey === '' ? (
+                                nav.hidden !== true &&
+                                (nav.permission === true ||
+                                    nav.permissionKey === '') ? (
                                     <React.Fragment key={`nav-item-${navKey}`}>
                                         {renderNav(nav)}
                                     </React.Fragment>
@@ -671,6 +723,7 @@ function Navigation({
                     >
                         <ul>
                             {navData.settings.map((setting, settingKey) =>
+                                setting.hidden !== true &&
                                 setting.permission === true ? (
                                     <React.Fragment
                                         key={`setting-${settingKey}`}
@@ -711,7 +764,9 @@ function Navigation({
             <div className={styles.navwrap} ref={navWrapRef}>
                 <ul className={appNavClasses}>
                     {navData.navigations.map((nav, navKey) =>
-                        nav.permission === true || nav.permissionKey === '' ? (
+                        nav.hidden !== true &&
+                        (nav.permission === true ||
+                            nav.permissionKey === '') ? (
                             <React.Fragment key={`nav-item-${navKey}`}>
                                 {renderNav(nav)}
                             </React.Fragment>
@@ -729,6 +784,7 @@ function Navigation({
             >
                 <ul>
                     {navData.settings.map((setting, settingKey) =>
+                        setting.hidden !== true &&
                         setting.permission === true ? (
                             <React.Fragment key={`setting-${settingKey}`}>
                                 {renderSetting(setting)}

package/src/components/auth/Login.jsx

@@ -190,8 +190,8 @@ const Login = ({
                 aria-hidden="true"
             >
                 <div className={styles.brandInk}>
-                    <p className={styles.eyebrow}>Prime Builders</p>
-                    <p className={styles.brandLine}>Prime Projects</p>
+                    <p className={styles.eyebrow}>Construction Management</p>
+                    <p className={styles.brandLine}>Prime Builders</p>
                     <p className={styles.brandSub}>
                         Job tracking, inspections, site forms and labour
                         scheduling — in one place.

package/src/components/generic/GenericDashboard.jsx

@@ -575,6 +575,9 @@ function GenericDashboard({ setting, userProfile, dynamicDashboard = false }) {
         )
     );
     const [data, setData] = useState({});
+    // Per-widget load state ('loading' | 'ready' | 'failed') keyed by widget.id.
+    // Tracked per widget so one slow/failed request only affects its own tile.
+    const [widgetStatus, setWidgetStatus] = useState({});
     const [dropdowns, setDropdowns] = useState({});
     const [filters, setFilters] = useState({});
     const [editMode, setEditMode] = useState(false);
@@ -631,8 +634,23 @@ function GenericDashboard({ setting, userProfile, dynamicDashboard = false }) {
         updateDashboardSetting(dashboardSetting);
     }, [dashboardSetting]);
 
+    // A widget only fetches when it has both a url and a method — anything else
+    // never loads, so it must never be marked 'loading'.
+    const widgetFetches = (widget) => Boolean(widget.api?.url && widget.api?.method);
+
     const fetchData = async (appliedFilters = {}) => {
         try {
+            const loadingStatus = dashboardSetting.widgets.reduce(
+                (acc, widget) => {
+                    acc[widget.id] = widgetFetches(widget)
+                        ? 'loading'
+                        : 'ready';
+                    return acc;
+                },
+                {}
+            );
+            setWidgetStatus((prev) => ({ ...prev, ...loadingStatus }));
+
             const promises = dashboardSetting.widgets.map(async (widget) => {
                 const widgetFilters = appliedFilters[widget.id] || {};
 
@@ -714,9 +732,40 @@ function GenericDashboard({ setting, userProfile, dynamicDashboard = false }) {
                 },
                 {}
             );
+            // Resolve each widget's status from the same settled results: a
+            // rejected promise or an API-error payload is a failure, anything
+            // else has finished loading.
+            const nextStatus = dashboardSetting.widgets.reduce(
+                (acc, widget, index) => {
+                    if (!widgetFetches(widget)) {
+                        acc[widget.id] = 'ready';
+                        return acc;
+                    }
+
+                    const result = results[index];
+                    acc[widget.id] =
+                        result?.status === 'rejected' ||
+                        result?.value?.data?.value
+                            ? 'failed'
+                            : 'ready';
+                    return acc;
+                },
+                {}
+            );
+
             setData(fetchedData);
+            setWidgetStatus((prev) => ({ ...prev, ...nextStatus }));
         } catch (error) {
             console.error('Error fetching dashboard data:', error);
+            // Never leave a widget stuck on a skeleton — a hard failure of the
+            // whole fetch marks everything still in flight as failed.
+            setWidgetStatus((prev) =>
+                Object.keys(prev).reduce((acc, widgetId) => {
+                    acc[widgetId] =
+                        prev[widgetId] === 'loading' ? 'failed' : prev[widgetId];
+                    return acc;
+                }, {})
+            );
         }
     };
 
@@ -1085,6 +1134,137 @@ function GenericDashboard({ setting, userProfile, dynamicDashboard = false }) {
         );
     };
 
+    // Placeholder shaped like the widget's real content. Every block reserves
+    // the dimensions the loaded content occupies so nothing shifts on arrival.
+    const renderWidgetSkeleton = (widget) => {
+        const chartHeight = widget.height || '600px';
+        const block = (extraClass, style, key) => (
+            <div
+                key={key}
+                className={`${styles.skeletonBlock} ${extraClass}`}
+                style={style}
+            />
+        );
+
+        const renderBody = () => {
+            switch (widget.type) {
+                case 'counter':
+                    return (
+                        <>
+                            <div className={styles.skeletonCounter}>
+                                {block(styles.skeletonCounterValue)}
+                            </div>
+                            {widget.button && (
+                                <div className={styles.skeletonButtonRow}>
+                                    {block(styles.skeletonButton)}
+                                </div>
+                            )}
+                        </>
+                    );
+                case 'pie':
+                    return (
+                        <div
+                            className={styles.skeletonChart}
+                            style={{ height: chartHeight }}
+                        >
+                            {block(styles.skeletonCircle)}
+                        </div>
+                    );
+                case 'bar':
+                case 'line':
+                    return (
+                        <div
+                            className={`${styles.skeletonChart} ${styles.skeletonChartStrips}`}
+                            style={{ height: chartHeight }}
+                        >
+                            {[70, 45, 88, 58, 34].map((width, index) =>
+                                block(
+                                    styles.skeletonStrip,
+                                    { width: `${width}%` },
+                                    `${widget.id}-skeleton-strip-${index}`
+                                )
+                            )}
+                        </div>
+                    );
+                case 'table':
+                    return (
+                        <div
+                            className={styles.skeletonTable}
+                            style={
+                                widget.height
+                                    ? {
+                                          maxHeight: widget.height,
+                                          overflow: 'hidden',
+                                      }
+                                    : undefined
+                            }
+                        >
+                            {block(styles.skeletonTableHeader)}
+                            {[0, 1, 2, 3, 4].map((index) =>
+                                block(
+                                    styles.skeletonTableRow,
+                                    undefined,
+                                    `${widget.id}-skeleton-row-${index}`
+                                )
+                            )}
+                        </div>
+                    );
+                case 'list':
+                    return (
+                        <div className={styles.skeletonList}>
+                            {[0, 1, 2, 3].map((index) =>
+                                block(
+                                    styles.skeletonListRow,
+                                    undefined,
+                                    `${widget.id}-skeleton-list-${index}`
+                                )
+                            )}
+                        </div>
+                    );
+                case 'timeline':
+                    return block(styles.skeletonTimeline, {
+                        height: widget.height || '500px',
+                    });
+                default:
+                    return block(styles.skeletonGeneric);
+            }
+        };
+
+        return (
+            <div
+                className={styles.skeleton}
+                role="status"
+                aria-busy="true"
+                aria-label={`Loading ${widget.title || 'widget'}`}
+            >
+                {renderBody()}
+            </div>
+        );
+    };
+
+    // Skeletons show only until a widget has data for the first time: a
+    // background auto-refresh must never blank a value someone is reading.
+    const renderWidgetBody = (widget) => {
+        const status = widgetStatus[widget.id];
+        const hasLoadedOnce = data[widget.id] !== undefined;
+
+        if (!hasLoadedOnce) {
+            if (status === 'loading') {
+                return renderWidgetSkeleton(widget);
+            }
+
+            if (status === 'failed') {
+                return (
+                    <div className={styles.noData}>
+                        Couldn&apos;t load this widget.
+                    </div>
+                );
+            }
+        }
+
+        return renderWidget(widget);
+    };
+
     const renderWidget = (widget) => {
         const widgetData = data[widget.id] || [];
 
@@ -1914,7 +2094,7 @@ function GenericDashboard({ setting, userProfile, dynamicDashboard = false }) {
                         )}
                     </div>
                     {renderFilters(widget)}
-                    <div>{renderWidget(widget)}</div>
+                    <div>{renderWidgetBody(widget)}</div>
                     {editMode && (
                         <div className={styles.widgetTools}>
                             <div className={styles.resizeTools}>

package/src/components/generic/GenericFormBuilder.jsx

@@ -50,6 +50,16 @@ import Breadcrumb from '../Breadcrumb';
 import CustomFetch from '../Fetch';
 import SketchConfig from '../sketch/json/config.json';
 import ConditionalDisplayEditor from './ConditionalDisplayEditor';
+import {
+    OutstandingOptionToggle,
+    OutstandingRuleHint,
+    applyOutstandingRule,
+    deriveOutstandingSelection,
+    isOutstandingConfigurable,
+    remapOutstandingWhen,
+    staleOutstandingIds,
+    summariseOutstandingRule,
+} from './OutstandingRuleEditor';
 
 import styles from '../styles/GenericFormBuilder.module.scss'; // Import the CSS module
 
@@ -57,8 +67,19 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
     const editorRef = useRef(null);
     const routeParams = useParams();
 
-    const { dynamicDropdowns, fetchUrl, fields, parentUrl, formTitle } =
-        setting;
+    const {
+        dynamicDropdowns,
+        fetchUrl,
+        fields,
+        parentUrl,
+        formTitle,
+        /**
+         * Opt-in, per-question "outstanding item" rules. Absent for every app
+         * that does not model outstanding items, in which case none of the
+         * `outstanding_when` handling below does anything at all.
+         */
+        outstandingItems,
+    } = setting;
 
     const { dataId } = useParams();
     const [data, setData] = useState({});
@@ -115,6 +136,17 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
         key: '',
     });
     const [modalFormShow, setModalFormShow] = useState(false);
+    /**
+     * The open field modal's outstanding-item switch. `touched` is false until
+     * the author actually flips one, and until then the displayed state is
+     * derived from the field on every render — so a brand-new question picks up
+     * the standard rule as soon as its answers exist, rather than being frozen
+     * at whatever was true when the modal opened.
+     */
+    const [outstandingRule, setOutstandingRule] = useState({
+        touched: false,
+        id: null,
+    });
     const [roles, setRoles] = useState([]);
     const [hoveredField, setHoveredField] = useState(null);
     const [activeId, setActiveId] = useState(null);
@@ -148,6 +180,37 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
      */
     const dynamicFields = data.field_source === 'dynamic';
 
+    /** Does the open field carry an editable outstanding-item rule at all? */
+    const outstandingEnabled = isOutstandingConfigurable(
+        outstandingItems,
+        dataField.type
+    );
+
+    /**
+     * Which answer currently has its "Outstanding" switch on. Always sanitised
+     * against the answers the field offers right now, so renaming or deleting
+     * an answer can never leave a dangling id to be saved.
+     */
+    const outstandingSelection = useMemo(() => {
+        if (!outstandingEnabled) return null;
+
+        const candidate = outstandingRule.touched
+            ? outstandingRule.id
+            : deriveOutstandingSelection(dataField);
+
+        return (dataField.options || []).some(
+            (option) => option && option.id === candidate
+        )
+            ? candidate
+            : null;
+    }, [outstandingEnabled, outstandingRule, dataField]);
+
+    /** Stored ids the field no longer offers — drives the amber warning. */
+    const outstandingStaleIds = useMemo(
+        () => (outstandingEnabled ? staleOutstandingIds(dataField) : []),
+        [outstandingEnabled, dataField]
+    );
+
     // Generate compact field info for display in the center top
     const getFieldInfo = (field) => {
         const fieldTypeLabel =
@@ -182,6 +245,14 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
             info.push('Conditional');
         }
 
+        // Only surfaced for apps that opted into outstanding-item rules.
+        if (outstandingItems?.enabled) {
+            const outstandingSummary = summariseOutstandingRule(field);
+            if (outstandingSummary) {
+                info.push(outstandingSummary);
+            }
+        }
+
         return info.join(' • ');
     };
 
@@ -229,6 +300,13 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
             tooltip += `Show when "${field.conditional_field}" = "${field.conditional_value}"\n`;
         }
 
+        if (outstandingItems?.enabled) {
+            const outstandingSummary = summariseOutstandingRule(field);
+            if (outstandingSummary) {
+                tooltip += `\nOutstanding rule: ${outstandingSummary}\n`;
+            }
+        }
+
         // Add other conditional properties if they exist
         if (field.conditionalOperator) {
             tooltip += `Operator: ${field.conditionalOperator}\n`;
@@ -1027,7 +1105,11 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
             textareaHeight: 'normal',
             conditional_field: '',
             conditional_value: '',
+            // `outstanding_when` is deliberately NOT seeded here: absent must
+            // stay absent so a field that was never configured never gains the
+            // key just by being opened.
         }));
+        setOutstandingRule({ touched: false, id: null });
         setModalType(() => ({
             type: 'create',
             key: '',
@@ -1047,10 +1129,28 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
             const { name, value } = e.target;
             const updatedValue = name === 'id' ? slugify(value) : value;
 
-            setDataField((items) => ({
-                ...items,
-                [name]: updatedValue,
-            }));
+            setDataField((items) => {
+                const next = { ...items, [name]: updatedValue };
+
+                // Switching to a type that cannot carry an outstanding rule
+                // would strand the key with no UI left to edit it.
+                if (
+                    name === 'type' &&
+                    'outstanding_when' in next &&
+                    !isOutstandingConfigurable(outstandingItems, updatedValue)
+                ) {
+                    delete next.outstanding_when;
+                }
+
+                return next;
+            });
+
+            if (
+                name === 'type' &&
+                !isOutstandingConfigurable(outstandingItems, updatedValue)
+            ) {
+                setOutstandingRule({ touched: false, id: null });
+            }
 
             if (name === 'label') {
                 setDataField((items) => ({
@@ -1080,6 +1180,10 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                 ...detail[key],
             }));
 
+            // Untouched: the switch shows whatever the stored rule — or the
+            // standard rule — implies, recomputed as the author edits.
+            setOutstandingRule({ touched: false, id: null });
+
             setModalType(() => ({
                 type: 'update',
                 key: key,
@@ -1158,6 +1262,11 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
 
         field.id = formatFieldId(field.id);
 
+        // No-op unless the consuming app enabled outstanding-item rules. Writes
+        // `outstanding_when` only when the switch differs from the standard
+        // rule, so opening and saving an untouched field changes nothing.
+        field = applyOutstandingRule(field, outstandingSelection, outstandingItems);
+
         let errorMessage = validateField(field);
 
         if (errorMessage === '') {
@@ -2378,6 +2487,14 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                                                     </span>
                                                 )}
                                             </div>
+                                            {outstandingEnabled ? (
+                                                <OutstandingRuleHint
+                                                    config={outstandingItems}
+                                                    staleIds={
+                                                        outstandingStaleIds
+                                                    }
+                                                />
+                                            ) : null}
                                             {dataField.options.length >
                                             0 ? (
                                                 <div
@@ -2415,6 +2532,15 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                                                                     onChange={(
                                                                         e
                                                                     ) => {
+                                                                        // Captured before the id is regenerated so any
+                                                                        // outstanding rule pointing at it can follow.
+                                                                        const previousOptionId =
+                                                                            dataField
+                                                                                .options[
+                                                                                optionKey
+                                                                            ]
+                                                                                ?.id;
+                                                                        const nextOptionId = `${slugify(e.target.value)}-`;
                                                                         const newOptions =
                                                                             [
                                                                                 ...dataField.options,
@@ -2426,18 +2552,65 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                                                                         newOptions[
                                                                             optionKey
                                                                         ].id =
-                                                                            `${slugify(e.target.value)}-`;
+                                                                            nextOptionId;
                                                                         setDataField(
                                                                             (
                                                                                 items
-                                                                            ) => ({
-                                                                                ...items,
-                                                                                options:
-                                                                                    newOptions,
-                                                                            })
+                                                                            ) =>
+                                                                                remapOutstandingWhen(
+                                                                                    {
+                                                                                        ...items,
+                                                                                        options:
+                                                                                            newOptions,
+                                                                                    },
+                                                                                    previousOptionId,
+                                                                                    nextOptionId
+                                                                                )
+                                                                        );
+
+                                                                        // An unsaved switch has to follow the
+                                                                        // rename too, or it would be sanitised
+                                                                        // away as a dangling id.
+                                                                        setOutstandingRule(
+                                                                            (
+                                                                                rule
+                                                                            ) =>
+                                                                                rule.touched &&
+                                                                                rule.id ===
+                                                                                    previousOptionId
+                                                                                    ? {
+                                                                                          ...rule,
+                                                                                          id: nextOptionId,
+                                                                                      }
+                                                                                    : rule
                                                                         );
                                                                     }}
                                                                 />
+                                                                {outstandingEnabled ? (
+                                                                    <OutstandingOptionToggle
+                                                                        optionId={
+                                                                            option.id
+                                                                        }
+                                                                        label={
+                                                                            option.label ||
+                                                                            option.id
+                                                                        }
+                                                                        checked={
+                                                                            outstandingSelection ===
+                                                                            option.id
+                                                                        }
+                                                                        onToggle={(
+                                                                            id
+                                                                        ) =>
+                                                                            setOutstandingRule(
+                                                                                {
+                                                                                    touched: true,
+                                                                                    id,
+                                                                                }
+                                                                            )
+                                                                        }
+                                                                    />
+                                                                ) : null}
                                                                 <button
                                                                     className={
                                                                         styles.optionDelete

package/src/components/generic/OutstandingRuleEditor.jsx

@@ -0,0 +1,313 @@
+import React from 'react';
+import styles from '../styles/GenericFormBuilder.module.scss';
+
+/**
+ * Per-question "outstanding item" rules.
+ *
+ * OPT-IN for consuming apps that model outstanding/defect follow-up items.
+ * Everything here is inert unless the app's builder config carries
+ * `outstandingItems: { enabled: true, ... }`, so no other project is affected.
+ *
+ * The stored schema is one optional per-field key, `outstanding_when`:
+ *
+ *   key absent    the app's own legacy convention applies (see legacyTriggerId)
+ *   []            this question can never raise an outstanding item
+ *   ['no-']       outstanding when the answer is this OPTION ID
+ *
+ * Option ids are stored, never labels, because editing an option label
+ * regenerates its id — exactly as `conditional_value` does.
+ *
+ * The UI is a single "Outstanding" switch on each row of the field's existing
+ * options editor, with radio semantics: at most one answer may be marked.
+ */
+
+/** Field types the editor offers when the config does not name any. */
+export const DEFAULT_OUTSTANDING_TYPES = ['checkbox'];
+
+/** Types the legacy (unconfigured) convention applies to. */
+export const LEGACY_OUTSTANDING_TYPES = ['checkbox'];
+
+/**
+ * The one label whose sense is inverted under the legacy convention: a "Yes"
+ * here means there IS something else affecting the build.
+ *
+ * Mirrors App\Support\OutstandingRule::SPECIAL_LABEL / ::SPECIAL_SIMILARITY.
+ */
+export const SPECIAL_LABEL =
+    'Other features affecting the build (provide details and photos)';
+export const SPECIAL_SIMILARITY = 85;
+
+// --------------------------------------------------------------- similar_text
+
+/**
+ * Longest common substring, PHP's php_similar_str() — first-found wins on ties,
+ * scanning the first string outermost.
+ */
+const similarStr = (s1, s2) => {
+    let max = 0;
+    let count = 0;
+    let pos1 = 0;
+    let pos2 = 0;
+
+    for (let p = 0; p < s1.length; p++) {
+        for (let q = 0; q < s2.length; q++) {
+            let l = 0;
+            while (
+                p + l < s1.length &&
+                q + l < s2.length &&
+                s1[p + l] === s2[q + l]
+            ) {
+                l++;
+            }
+            if (l > max) {
+                max = l;
+                count++;
+                pos1 = p;
+                pos2 = q;
+            }
+        }
+    }
+
+    return { pos1, pos2, max, count };
+};
+
+/** PHP's php_similar_char(): the common substring, then recurse either side. */
+const similarChar = (s1, s2) => {
+    const { pos1, pos2, max, count } = similarStr(s1, s2);
+    let sum = max;
+
+    if (sum) {
+        if (pos1 && pos2 && count > 1) {
+            sum += similarChar(s1.slice(0, pos1), s2.slice(0, pos2));
+        }
+        if (pos1 + max < s1.length && pos2 + max < s2.length) {
+            sum += similarChar(s1.slice(pos1 + max), s2.slice(pos2 + max));
+        }
+    }
+
+    return sum;
+};
+
+/**
+ * PHP's similar_text($first, $second, $percent) percentage.
+ *
+ * Verified byte-for-byte against PHP 8.5 over the real label corpus plus 400
+ * random strings. The argument order is load-bearing — the function is not
+ * symmetric — and must match the backend's call exactly.
+ *
+ * (PHP compares bytes; this compares UTF-16 code units. Identical for the
+ * ASCII labels in use, and only ever used against an ASCII constant.)
+ */
+export const similarTextPercent = (first, second) => {
+    const s1 = typeof first === 'string' ? first : '';
+    const s2 = typeof second === 'string' ? second : '';
+    const total = s1.length + s2.length;
+
+    if (total === 0) return 0;
+
+    return (similarChar(s1, s2) * 2 * 100) / total;
+};
+
+// ---------------------------------------------------------------- the config
+
+export const outstandingTypesOf = (config) => {
+    const types = config?.types;
+    return Array.isArray(types) ? types : DEFAULT_OUTSTANDING_TYPES;
+};
+
+/** The single gate: config must enable it AND the type must store one option id. */
+export const isOutstandingConfigurable = (config, fieldType) =>
+    !!(config && config.enabled) &&
+    outstandingTypesOf(config).includes(fieldType);
+
+// ------------------------------------------------------------- the rule state
+
+const optionsOf = (field) =>
+    (Array.isArray(field?.options) ? field.options : []).filter(Boolean);
+
+const storedIds = (field) =>
+    Array.isArray(field?.outstanding_when) ? field.outstanding_when : null;
+
+/**
+ * The legacy trigger for a field: 'yes-' for the special "Other features
+ * affecting the build" question, 'no-' for any other checkbox, and null for
+ * every other type (the legacy convention never reached them).
+ *
+ * Mirrors App\Support\OutstandingRule::legacyTrigger().
+ */
+export const legacyTriggerId = (field) => {
+    if (!LEGACY_OUTSTANDING_TYPES.includes(field?.type)) return null;
+
+    return similarTextPercent(field?.label, SPECIAL_LABEL) >=
+        SPECIAL_SIMILARITY
+        ? 'yes-'
+        : 'no-';
+};
+
+/**
+ * What the legacy convention would show as toggled, which is only meaningful
+ * when the field actually offers that answer. A checkbox with no 'no-' option
+ * (or no options yet) has no legacy toggle, and the backend agrees: its trigger
+ * can never match a stored value.
+ */
+export const legacyDefaultOptionId = (field) => {
+    const trigger = legacyTriggerId(field);
+    if (!trigger) return null;
+
+    return optionsOf(field).some((option) => option.id === trigger)
+        ? trigger
+        : null;
+};
+
+/**
+ * Which option should show toggled when the modal opens.
+ *
+ * Configured → the first stored id the field still offers. (No template today
+ * carries more than one; a multi-entry array shows its first and is normalised
+ * to a single id on save.) An explicit `[]` shows nothing toggled.
+ * Unconfigured → whatever the legacy convention would flag.
+ */
+export const deriveOutstandingSelection = (field) => {
+    const stored = storedIds(field);
+
+    if (stored) {
+        const options = optionsOf(field);
+        return (
+            stored.find((id) => options.some((option) => option.id === id)) ??
+            null
+        );
+    }
+
+    return legacyDefaultOptionId(field);
+};
+
+/** Stored ids the field no longer offers — the rename/delete hazard. */
+export const staleOutstandingIds = (field) => {
+    const stored = storedIds(field);
+    if (!stored) return [];
+
+    const options = optionsOf(field);
+    return stored.filter((id) => !options.some((option) => option.id === id));
+};
+
+/**
+ * Fold the toggle state back into the field.
+ *
+ * The key is written only when the outcome differs from what the legacy
+ * convention would produce, so a field nobody configured never gains it just
+ * because its modal was opened and saved:
+ *
+ *   selection === legacy default  → key deleted (including both being null)
+ *   an answer toggled             → ['<id>']
+ *   nothing toggled, legacy would → []  (an explicit "never")
+ *
+ * A stale stored id is not toggleable, so saving normalises it to [] (checkbox)
+ * or an absent key (dropdown) — both meaning "never flags", which is precisely
+ * what an id no answer can produce already meant.
+ */
+export const applyOutstandingRule = (field, selectedId, config) => {
+    if (!isOutstandingConfigurable(config, field?.type)) return field;
+
+    const selection = selectedId || null;
+    const next = { ...field };
+
+    if (selection === legacyDefaultOptionId(field)) {
+        delete next.outstanding_when;
+    } else {
+        next.outstanding_when = selection ? [selection] : [];
+    }
+
+    return next;
+};
+
+/**
+ * One-line summary for field-list chips and tooltips. Returns null when the
+ * field carries no rule, so callers can skip falsy results.
+ */
+export const summariseOutstandingRule = (field) => {
+    const stored = storedIds(field);
+    if (!stored) return null;
+    if (stored.length === 0) return 'Never outstanding';
+
+    const options = optionsOf(field);
+    const labels = stored.map((id) => {
+        const match = options.find((option) => option.id === id);
+        return match ? match.label || match.id : `${id} (missing)`;
+    });
+
+    return `Outstanding: ${labels.join(', ')}`;
+};
+
+/**
+ * Remap a stored id after an option's id was regenerated from an edited label.
+ * Returns the field untouched (same reference) when there is nothing to remap.
+ */
+export const remapOutstandingWhen = (field, previousId, nextId) => {
+    const stored = storedIds(field);
+
+    if (!stored || previousId === nextId) return field;
+    if (!stored.includes(previousId)) return field;
+
+    return {
+        ...field,
+        outstanding_when: stored.map((id) => (id === previousId ? nextId : id)),
+    };
+};
+
+// ------------------------------------------------------------------------ UI
+
+/**
+ * The per-row switch. Radio semantics live in the caller: `onToggle` receives
+ * the id to select, or null when the row was switched off.
+ */
+export function OutstandingOptionToggle({ optionId, label, checked, onToggle }) {
+    return (
+        <label
+            className={`${styles.outstandingFlag} ${
+                checked ? styles.outstandingFlagOn : ''
+            }`}
+            title={
+                checked
+                    ? `An answer of "${label}" raises an outstanding item`
+                    : `Mark "${label}" as the answer that raises an outstanding item`
+            }
+        >
+            <input
+                type="checkbox"
+                checked={checked}
+                onChange={() => onToggle(checked ? null : optionId)}
+            />
+            <span>Outstanding</span>
+        </label>
+    );
+}
+
+/**
+ * The hint shown once above the option rows, plus the amber stale-reference
+ * warning. Renders nothing when there is nothing to say.
+ */
+export function OutstandingRuleHint({ config, staleIds = [] }) {
+    const help = config?.help;
+
+    if (!help && staleIds.length === 0) return null;
+
+    return (
+        <>
+            {help ? (
+                <div className={styles.outstandingHint}>{help}</div>
+            ) : null}
+
+            {staleIds.length > 0 ? (
+                <div className={styles.outstandingStale}>
+                    {staleIds.length === 1
+                        ? 'The answer this question’s outstanding rule refers to no longer exists'
+                        : 'Answers this question’s outstanding rule refers to no longer exist'}{' '}
+                    ({staleIds.join(', ')}) — editing an answer’s label gives it
+                    a new id. Set the switch on the right answer, or leave every
+                    switch off to mean “never outstanding”. Saving tidies this
+                    up.
+                </div>
+            ) : null}
+        </>
+    );
+}

package/src/components/styles/GenericDashboard.module.scss

@@ -814,3 +814,158 @@
     color: #888;
     padding: 20px;
 }
+
+/* ---------------------------------------------------------------------------
+   Loading skeletons
+   Neutral greys only (no brand colours) so every tenant gets a safe default.
+   Keyframes are uniquely prefixed to avoid colliding with host app globals.
+--------------------------------------------------------------------------- */
+@keyframes visns-dash-skeleton-sweep {
+    0% {
+        background-position: 150% 0;
+    }
+    100% {
+        background-position: -150% 0;
+    }
+}
+
+.skeleton {
+    width: 100%;
+    box-sizing: border-box;
+}
+
+.skeletonBlock {
+    display: block;
+    box-sizing: border-box;
+    border-radius: var(--br, 5px);
+    background-color: rgba(0, 0, 0, 0.06);
+    background-image: linear-gradient(
+        90deg,
+        rgba(0, 0, 0, 0) 0%,
+        rgba(0, 0, 0, 0.05) 50%,
+        rgba(0, 0, 0, 0) 100%
+    );
+    background-repeat: no-repeat;
+    background-size: 150% 100%;
+    animation: visns-dash-skeleton-sweep 1.4s ease-in-out infinite;
+}
+
+/* Counter: matches .widgetNo (2rem bottom padding, 3em value) */
+.skeletonCounter {
+    width: 100%;
+    padding: 0 0 2rem 0;
+    box-sizing: border-box;
+}
+
+.skeletonCounterValue {
+    width: 55%;
+    max-width: 220px;
+    height: 3.6rem;
+    margin: 0 auto;
+}
+
+/* Counter button: matches .widgetLink .btn */
+.skeletonButtonRow {
+    width: 100%;
+    display: block;
+}
+
+.skeletonButton {
+    width: 180px;
+    max-width: 100%;
+    height: 34px;
+    margin: 0 auto;
+}
+
+/* Charts: the wrapper takes widget.height (or the 600px chart default) inline */
+.skeletonChart {
+    width: 100%;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    box-sizing: border-box;
+    padding: 20px 0;
+}
+
+.skeletonChartStrips {
+    align-items: flex-start;
+    gap: 14px;
+}
+
+.skeletonStrip {
+    height: 16px;
+    min-height: 16px;
+}
+
+.skeletonCircle {
+    width: 60%;
+    max-width: 260px;
+    aspect-ratio: 1 / 1;
+    border-radius: 50%;
+}
+
+/* Table: header 44px / rows 38px, matching .table-container th and td */
+.skeletonTable {
+    width: 100%;
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+    box-sizing: border-box;
+    border: 1px solid #dadce0;
+    border-radius: var(--br, 5px);
+    overflow: hidden;
+}
+
+.skeletonTableHeader {
+    width: 100%;
+    height: 44px;
+    border-radius: 0;
+}
+
+.skeletonTableRow {
+    width: 100%;
+    height: 38px;
+    border-radius: 0;
+}
+
+/* List: rows sized like .dashList li button */
+.skeletonList {
+    width: 100%;
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+    font-size: 0.875rem;
+}
+
+.skeletonListRow {
+    width: 100%;
+    height: 30px;
+    border-radius: 0;
+
+    &:first-child {
+        border-top-left-radius: var(--br, 5px);
+        border-top-right-radius: var(--br, 5px);
+    }
+
+    &:last-child {
+        border-bottom-left-radius: var(--br, 5px);
+        border-bottom-right-radius: var(--br, 5px);
+    }
+}
+
+.skeletonTimeline {
+    width: 100%;
+}
+
+.skeletonGeneric {
+    width: 100%;
+    height: 120px;
+}
+
+/* Keep the shape, drop the motion */
+@media (prefers-reduced-motion: reduce) {
+    .skeletonBlock {
+        animation: none;
+    }
+}

package/src/components/styles/GenericFormBuilder.module.scss

@@ -2275,6 +2275,66 @@ select:not(:placeholder-shown) + .fi__span {
     }
 }
 
+// Outstanding item rule — a per-answer switch inside the options editor, plus
+// its hint and stale-reference warning. All of it renders only when the
+// consuming app enables `outstandingItems` in its builder config.
+.outstandingHint {
+    font-size: 0.78rem;
+    line-height: 1.45;
+    color: rgba(var(--paragraph-color-rgb), 0.65);
+    padding: 0 0 6px;
+}
+
+.outstandingStale {
+    background: #fff8e1;
+    border: 1px solid #f4c544;
+    border-radius: 6px;
+    padding: 8px 12px;
+    margin-bottom: 6px;
+    color: #7a5c00;
+    font-size: 0.8rem;
+    line-height: 1.45;
+}
+
+.outstandingFlag {
+    flex-shrink: 0;
+    display: inline-flex;
+    align-items: center;
+    gap: 5px;
+    padding: 4px 9px;
+    border: 1px solid rgba(var(--primary-rgb), 0.15);
+    border-radius: 6px;
+    background: white;
+    font-size: 0.72rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: rgba(var(--paragraph-color-rgb), 0.45);
+    cursor: pointer;
+    user-select: none;
+    transition: all 0.2s ease;
+
+    &:hover {
+        border-color: var(--primary-color);
+        color: var(--paragraph-color);
+    }
+
+    // The modal forces a 44px min-height on every input; a tick box must opt out.
+    input[type='checkbox'] {
+        margin: 0;
+        width: auto !important;
+        height: auto !important;
+        min-height: 0 !important;
+        cursor: pointer;
+    }
+}
+
+.outstandingFlagOn {
+    border-color: #e0a800;
+    background: #fff8e1;
+    color: #7a5c00;
+}
+
 .btnCancel {
     background: rgba(var(--paragraph-color-rgb), 0.08) !important;
     color: var(--paragraph-color) !important;