@visns-studio/visns-components 6.17.1 → 6.20.0

package/src/components/generic/GenericSettings.jsx

@@ -0,0 +1,220 @@
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import { useNavigate, useParams } from 'react-router-dom';
+import { Search } from 'lucide-react';
+
+import styles from '../styles/GenericSettings.module.scss';
+
+/**
+ * The settings hub: a rail of sections beside one panel.
+ *
+ * CONFIG-DRIVEN, like every other Generic in this library. A section is a
+ * config entry, not a route and not a component this file knows about:
+ *
+ *   {
+ *     id: 'integrations',
+ *     label: 'Integrations',
+ *     description: 'Connected systems and their credentials.',
+ *     group: 'Platform',        // optional rail heading
+ *     permission: 'Settings',   // optional; hidden when the user lacks it
+ *     renderer: 'integrations', // key into the `renderers` prop
+ *   }
+ *
+ * The host supplies the actual panels through `renderers`, the same slot
+ * GenericDetail and Navigation use. That is deliberate: the library owns the
+ * layout, the deep-linking and the permission filtering; the application owns
+ * what a section actually shows, so adding one never means editing this file.
+ *
+ * Sections deep-link as `/settings/:section`, so a panel can be linked to and
+ * survives a refresh — which a tab index held only in state cannot.
+ */
+const GenericSettings = ({
+    setting,
+    userProfile,
+    renderers = {},
+    hasPermission,
+    basePath = '/settings',
+}) => {
+    const params = useParams();
+    const navigate = useNavigate();
+
+    const page = setting?.page ?? {};
+    const allSections = useMemo(
+        () => (Array.isArray(setting?.sections) ? setting.sections : []),
+        [setting]
+    );
+
+    /**
+     * Only the sections this user may see.
+     *
+     * A section with no `permission` is open. The check is delegated to the
+     * host via `hasPermission`, because the library has no opinion on how the
+     * application models permissions — and a section hidden here is still
+     * enforced by whatever its panel calls.
+     */
+    const sections = useMemo(
+        () =>
+            allSections.filter((section) => {
+                if (!section?.permission) return true;
+                if (typeof hasPermission !== 'function') return true;
+
+                return hasPermission(userProfile, section.permission);
+            }),
+        [allSections, hasPermission, userProfile]
+    );
+
+    const [query, setQuery] = useState('');
+
+    const visible = useMemo(() => {
+        const term = query.trim().toLowerCase();
+
+        if (!term) return sections;
+
+        return sections.filter((s) =>
+            `${s.label} ${s.description ?? ''} ${s.keywords ?? ''}`
+                .toLowerCase()
+                .includes(term)
+        );
+    }, [sections, query]);
+
+    const activeId = params.section ?? sections[0]?.id;
+    const active = sections.find((s) => s.id === activeId) ?? sections[0];
+
+    // A URL naming a section that does not exist (a stale bookmark, or one the
+    // user lost permission to) lands on the first section rather than a blank
+    // panel with no way forward.
+    useEffect(() => {
+        if (!params.section || sections.length === 0) return;
+
+        if (!sections.some((s) => s.id === params.section)) {
+            navigate(`${basePath}/${sections[0].id}`, { replace: true });
+        }
+    }, [params.section, sections, navigate, basePath]);
+
+    const open = useCallback(
+        (id) => navigate(`${basePath}/${id}`),
+        [navigate, basePath]
+    );
+
+    const grouped = useMemo(() => {
+        const out = new Map();
+
+        visible.forEach((section) => {
+            const key = section.group ?? '';
+
+            if (!out.has(key)) out.set(key, []);
+            out.get(key).push(section);
+        });
+
+        return [...out.entries()];
+    }, [visible]);
+
+    const renderPanel = () => {
+        if (!active) {
+            return <p className={styles.empty}>Nothing to configure here.</p>;
+        }
+
+        const render = renderers[active.renderer];
+
+        if (typeof render !== 'function') {
+            // A named renderer the host did not supply is a config error, and a
+            // blank panel is the one outcome that hides it.
+            return (
+                <p className={styles.empty}>
+                    No panel is registered for “{active.label}”.
+                </p>
+            );
+        }
+
+        return render({ section: active, userProfile });
+    };
+
+    // Enough sections that scanning the rail is slower than typing.
+    const showSearch = sections.length >= 8;
+
+    return (
+        <div className={styles.page}>
+            <div className={styles.layout}>
+                <nav className={styles.rail} aria-label="Settings sections">
+                    {showSearch && (
+                        <div className={styles.railSearch}>
+                            <Search size={14} strokeWidth={2} aria-hidden="true" />
+                            <input
+                                type="text"
+                                value={query}
+                                placeholder="Find a setting…"
+                                aria-label="Find a setting"
+                                onChange={(e) => setQuery(e.target.value)}
+                            />
+                        </div>
+                    )}
+
+                    {grouped.map(([group, list]) => (
+                        <div key={group || 'ungrouped'} className={styles.railGroup}>
+                            {group && (
+                                <p className={styles.railGroupTitle}>{group}</p>
+                            )}
+
+                            <ul>
+                                {list.map((section) => {
+                                    const isActive = section.id === active?.id;
+
+                                    return (
+                                        <li key={section.id}>
+                                            <button
+                                                type="button"
+                                                className={
+                                                    isActive
+                                                        ? styles.railItemActive
+                                                        : styles.railItem
+                                                }
+                                                // The rail is a set of
+                                                // destinations, so the current
+                                                // one is announced as such.
+                                                aria-current={
+                                                    isActive ? 'page' : undefined
+                                                }
+                                                onClick={() => open(section.id)}
+                                            >
+                                                {section.label}
+                                            </button>
+                                        </li>
+                                    );
+                                })}
+                            </ul>
+                        </div>
+                    ))}
+
+                    {visible.length === 0 && (
+                        <p className={styles.railEmpty}>
+                            Nothing matches “{query}”.
+                        </p>
+                    )}
+                </nav>
+
+                <section className={styles.panel} aria-live="polite">
+                    {active && (
+                        <header className={styles.panelHead}>
+                            {/* The only heading on the screen: the page title
+                                is a kicker above the section, rather than a
+                                page header repeating what the rail already
+                                says. `page.description` survives as its
+                                tooltip so hosts still passing one keep it. */}
+                            <p
+                                className={styles.eyebrow}
+                                title={page.description || undefined}
+                            >
+                                {page.title ?? 'Settings'}
+                            </p>
+                            <h1>{active.label}</h1>
+                            {active.description && <p>{active.description}</p>}
+                        </header>
+                    )}
+
+                    <div className={styles.panelBody}>{renderPanel()}</div>
+                </section>
+            </div>
+        </div>
+    );
+};
+
+export default GenericSettings;

package/src/components/generic/StandardModal.jsx

@@ -1,7 +1,29 @@
-import React, { useState, useEffect, useCallback } from 'react';
+import React, { useState, useEffect, useCallback, useId, useRef } from 'react';
 import { X } from 'lucide-react';
 import formStyles from '../styles/Form.module.scss';
 
+/**
+ * The sheet's entry animation.
+ *
+ * Inline rather than in the stylesheet because everything else about this
+ * component's geometry is inline too, and splitting the two means a consumer
+ * overriding one gets the other from somewhere else. The reduced-motion query
+ * is not optional: a panel flying in from the edge is exactly the vestibular
+ * trigger the preference exists for.
+ */
+const SHEET_KEYFRAMES = `
+@keyframes visnsSheetIn {
+    from { transform: translateX(24px); opacity: 0.6; }
+    to   { transform: translateX(0);    opacity: 1; }
+}
+@media (prefers-reduced-motion: reduce) {
+    @keyframes visnsSheetIn {
+        from { opacity: 1; }
+        to   { opacity: 1; }
+    }
+}
+`;
+
 /**
  * StandardModal Component
  * 
@@ -13,7 +35,8 @@ import formStyles from '../styles/Form.module.scss';
  * @param {Function} props.onClose - Function to call when modal should close
  * @param {string} props.title - Modal title (only used if showHeader is true)
  * @param {React.ReactNode} props.children - Modal content
- * @param {string} props.size - Modal size: 'small', 'medium', 'large' (default: 'medium')
+ * @param {string} props.size - Size: 'small', 'medium', 'large' (default: 'medium')
+ * @param {string} props.variant - 'modal' (centred) or 'sheet' (side panel)
  * @param {boolean} props.closeOnDocumentClick - Whether to close on outside click (default: true)
  * @param {boolean} props.closeOnEscape - Whether to close on escape key (default: true)
  * @param {string} props.verticalAlign - Vertical alignment: 'center', 'top' (default: 'center')
@@ -26,6 +49,22 @@ const StandardModal = ({
     title,
     children,
     size = 'medium',
+    /**
+     * 'modal' — centred dialog. Correct for a short, atomic task: a
+     *           confirmation, a destructive action, a handful of fields.
+     * 'sheet'  — a panel sliding in from the right. The 2026 default for CRUD
+     *           on a record reached from a list, and what every comparable
+     *           product (Linear, Stripe, Shopify, Salesforce) settled on.
+     *
+     * The reason is not fashion. A centred dialog over a table hides the row
+     * you are editing and the rows around it, and a tall form makes the dialog
+     * grow until it fights the viewport — which is exactly what a `medium`
+     * modal at `80vw` was doing here. A sheet keeps the list visible, gives a
+     * long form a natural vertical scroll, and has a fixed width, so the form
+     * inside has one column measure instead of a width that changes with the
+     * window.
+     */
+    variant = 'modal',
     closeOnDocumentClick = true,
     closeOnEscape = true,
     verticalAlign = 'center',
@@ -54,6 +93,69 @@ const StandardModal = ({
     };
     
     const { isMobile, isTablet } = getDeviceType();
+
+    const titleId = useId();
+    const panelRef = useRef(null);
+    const returnFocusRef = useRef(null);
+
+    /**
+     * Move focus into the panel on open, and put it back where it came from on
+     * close.
+     *
+     * Neither happened before. Opening left focus on the row behind the
+     * dialog, so the first Tab walked the table underneath instead of the
+     * form; closing dropped focus to <body>, which sends a keyboard user back
+     * to the top of the page every time they edit a record.
+     */
+    useEffect(() => {
+        if (!isOpen) {
+            return undefined;
+        }
+
+        returnFocusRef.current =
+            typeof document !== 'undefined' ? document.activeElement : null;
+
+        const focusable = panelRef.current?.querySelector(
+            'input:not([type="hidden"]):not([disabled]), select, textarea, button, [href], [tabindex]:not([tabindex="-1"])'
+        );
+
+        // The panel itself as a fallback, so focus is never left outside it.
+        (focusable ?? panelRef.current)?.focus?.({ preventScroll: true });
+
+        return () => {
+            returnFocusRef.current?.focus?.({ preventScroll: true });
+        };
+    }, [isOpen]);
+
+    /** Keep Tab inside the dialog while it is open. */
+    const handleTabKey = useCallback((event) => {
+        if (event.key !== 'Tab' || !panelRef.current) {
+            return;
+        }
+
+        const items = [
+            ...panelRef.current.querySelectorAll(
+                'input:not([type="hidden"]):not([disabled]), select:not([disabled]), textarea:not([disabled]), button:not([disabled]), [href], [tabindex]:not([tabindex="-1"])'
+            ),
+        ].filter((el) => el.offsetParent !== null);
+
+        if (items.length === 0) {
+            return;
+        }
+
+        const first = items[0];
+        const last = items[items.length - 1];
+
+        // Wrap at both ends, or Tab escapes to the browser chrome and the user
+        // has no way back into the dialog without a mouse.
+        if (event.shiftKey && document.activeElement === first) {
+            event.preventDefault();
+            last.focus();
+        } else if (!event.shiftKey && document.activeElement === last) {
+            event.preventDefault();
+            first.focus();
+        }
+    }, []);
     
     // Handle window resize
     useEffect(() => {
@@ -106,6 +208,8 @@ const StandardModal = ({
         return classes;
     };
 
+    const isSheet = variant === 'sheet';
+
     // Get overlay styles
     const getOverlayStyle = () => {
         const baseStyle = {
@@ -114,24 +218,66 @@ const StandardModal = ({
             left: 0,
             right: 0,
             bottom: 0,
-            backgroundColor: 'rgba(0, 0, 0, 0.5)',
+            // Was a flat 50% black. A scrim that heavy on a sheet buries the
+            // list the sheet exists to keep visible, so the sheet dims less.
+            backgroundColor: isSheet
+                ? 'rgba(15, 23, 32, 0.32)'
+                : 'rgba(0, 0, 0, 0.5)',
             display: 'flex',
-            alignItems: verticalAlign === 'top' ? 'flex-start' : 'center',
-            justifyContent: 'center',
+            alignItems: isSheet
+                ? 'stretch'
+                : verticalAlign === 'top'
+                  ? 'flex-start'
+                  : 'center',
+            // A sheet is pinned to the right edge; a modal is centred.
+            justifyContent: isSheet ? 'flex-end' : 'center',
             zIndex: 1000,
-            padding: '20px',
+            padding: isSheet ? 0 : '20px',
             ...customStyles.overlay
         };
 
-        if (verticalAlign === 'top') {
+        if (!isSheet && verticalAlign === 'top') {
             baseStyle.paddingTop = '5%';
         }
 
         return baseStyle;
     };
 
+    /**
+     * A sheet's width is FIXED, not a share of the window.
+     *
+     * A form wants one comfortable measure. `80vw` gave it a different measure
+     * on every monitor and stretched two-column rows into something unreadable
+     * on a wide screen. Below the tablet breakpoint the sheet becomes
+     * full-width, which is the only sensible shape on a phone.
+     */
+    const getSheetStyle = () => {
+        const width = { small: 420, medium: 560, large: 800 }[size] ?? 560;
+
+        return {
+            position: 'relative',
+            backgroundColor: 'white',
+            width: isMobile ? '100vw' : `min(${width}px, 96vw)`,
+            maxWidth: '100vw',
+            height: '100vh',
+            display: 'flex',
+            flexDirection: 'column',
+            borderRadius: 0,
+            boxShadow: '-12px 0 40px -12px rgba(0, 0, 0, 0.28)',
+            overflowY: 'auto',
+            // Honours prefers-reduced-motion via the media query below; the
+            // transform is the entry, and it is deliberately short.
+            animation: 'visnsSheetIn 180ms cubic-bezier(0.32, 0.72, 0, 1)',
+            ...customStyles.modal,
+        };
+    };
+
     // Get size-based styles for the modal content with device-aware positioning
     const getContentStyle = () => {
+        if (isSheet) {
+            return getSheetStyle();
+        }
+
         const baseStyle = {
             position: 'relative',
             backgroundColor: 'white',
@@ -190,9 +336,20 @@ const StandardModal = ({
             style={getOverlayStyle()}
             onClick={handleBackdropClick}
         >
+            <style>{SHEET_KEYFRAMES}</style>
             <div 
+                ref={panelRef}
                 style={getContentStyle()}
                 onClick={(e) => e.stopPropagation()}
+                /* This had none of these. Without `role="dialog"` and
+                   `aria-modal` a screen reader treats the panel as ordinary
+                   page content and keeps reading the table behind it; without
+                   the label it announces an unnamed dialog. */
+                role="dialog"
+                aria-modal="true"
+                aria-label={!showHeader && title ? title : undefined}
+                aria-labelledby={showHeader && title ? titleId : undefined}
+                onKeyDown={handleTabKey}
             >
                 <div className={formStyles.modalwrap}>
                     <div 
@@ -200,7 +357,7 @@ const StandardModal = ({
                     >
                         {showHeader && (
                             <div className={formStyles.modal__header} style={customStyles.header}>
-                                <h1 style={customStyles.title}>{title}</h1>
+                                <h1 id={titleId} style={customStyles.title}>{title}</h1>
                                 <button
                                     className={formStyles.modal__close}
                                     onClick={onClose}

package/src/components/generic/dashboardChartDefaults.js

@@ -0,0 +1,230 @@
+/**
+ * Chart defaults for GenericDashboard — 2026.
+ *
+ * The widget renderers used to spread `widget.props` straight into the nivo
+ * component with nothing underneath, so any dashboard.json that did not spell
+ * out a palette got nivo's default `nivo` scheme: a rainbow, cycled, with no
+ * colour-vision guarantee and a heavy dashed grid. These defaults sit BENEATH
+ * the spread, so every existing config keeps whatever it set and only the gaps
+ * are filled.
+ *
+ * ---------------------------------------------------------------------------
+ * The palette is validated, not chosen by eye.
+ * ---------------------------------------------------------------------------
+ * Six categorical hues, slot 1 the brand green. Assigned in fixed order and
+ * never cycled — a seventh series folds into "Other" or becomes small
+ * multiples rather than inventing a hue.
+ *
+ *   light  worst adjacent CVD ΔE 9.2 (deutan) · normal-vision ΔE 27.6
+ *   dark   worst adjacent CVD ΔE 9.4 (deutan) · normal-vision ΔE 19.7
+ *
+ * Both clear the ≥8 CVD target and the ≥15 normal-vision floor. The dark row
+ * is the same six hues re-stepped for a dark surface and validated against it,
+ * not an inversion of the light row.
+ *
+ * Three light-mode hues sit below 3:1 against white. That is a contrast WARN,
+ * not a pass — it obliges relief, which is why `defaultsFor` turns legends on
+ * for every multi-series chart and the table widget exists as the text view.
+ */
+
+export const DASHBOARD_SERIES_LIGHT = [
+    '#1baf7a', // 1 · green (brand)
+    '#eb6834', // 2 · orange
+    '#2a78d6', // 3 · blue
+    '#eda100', // 4 · yellow
+    '#4a3aa7', // 5 · violet
+    '#e87ba4', // 6 · magenta
+];
+
+export const DASHBOARD_SERIES_DARK = [
+    '#199e70',
+    '#d95926',
+    '#3987e5',
+    '#c98500',
+    '#9085e9',
+    '#d55181',
+];
+
+/**
+ * Status colours are reserved. They mean a state, never "series 4", and always
+ * ship with a label or an icon rather than carrying meaning by colour alone.
+ */
+export const DASHBOARD_STATUS = {
+    good: '#1f7a47',
+    warning: '#a36a14',
+    critical: '#be3e3e',
+};
+
+const prefersDark = () =>
+    typeof window !== 'undefined' &&
+    typeof window.matchMedia === 'function' &&
+    (document?.documentElement?.dataset?.theme === 'dark' ||
+        (document?.documentElement?.dataset?.theme !== 'light' &&
+            window.matchMedia('(prefers-color-scheme: dark)').matches));
+
+export const seriesColors = () =>
+    prefersDark() ? DASHBOARD_SERIES_DARK : DASHBOARD_SERIES_LIGHT;
+
+/**
+ * The nivo theme. Grid and axes are one step off the surface, hairline and
+ * SOLID — a dashed grid competes with the data for attention, and there is
+ * nothing for the dashes to mean.
+ */
+export const dashboardTheme = () => {
+    const dark = prefersDark();
+    const ink = dark ? '#e6e9e8' : '#2b2b2b';
+    const muted = dark ? 'rgba(230,233,232,0.62)' : 'rgba(43,43,43,0.62)';
+    const line = dark ? 'rgba(230,233,232,0.14)' : 'rgba(43,43,43,0.10)';
+    const surface = dark ? '#171b1a' : '#ffffff';
+
+    return {
+        background: 'transparent',
+        text: {
+            // Text wears text tokens, never a series colour.
+            fill: muted,
+            fontSize: 11,
+            fontFamily: 'inherit',
+        },
+        axis: {
+            domain: { line: { stroke: line, strokeWidth: 1 } },
+            ticks: {
+                line: { stroke: line, strokeWidth: 1 },
+                text: { fill: muted, fontSize: 11 },
+            },
+            legend: { text: { fill: muted, fontSize: 11, fontWeight: 600 } },
+        },
+        grid: { line: { stroke: line, strokeWidth: 1 } },
+        legends: { text: { fill: ink, fontSize: 11 } },
+        tooltip: {
+            container: {
+                background: surface,
+                color: ink,
+                fontSize: 12,
+                borderRadius: 8,
+                boxShadow: '0 4px 16px rgba(0,0,0,0.18)',
+                padding: '6px 10px',
+            },
+        },
+    };
+};
+
+const legendBelow = (count) =>
+    count >= 2
+        ? [
+              {
+                  // A legend is always present for two or more series: identity
+                  // must never rest on colour alone.
+                  anchor: 'bottom',
+                  direction: 'row',
+                  translateY: 56,
+                  itemWidth: 96,
+                  itemHeight: 16,
+                  symbolSize: 10,
+                  symbolShape: 'circle',
+                  itemTextColor: 'inherit',
+              },
+          ]
+        : [];
+
+/**
+ * Per-type defaults. `seriesCount` decides only whether a legend is drawn — a
+ * single series needs none, because the card's own heading names it.
+ */
+export const defaultsFor = (type, seriesCount = 1) => {
+    const colors = seriesColors();
+    const theme = dashboardTheme();
+    const legends = legendBelow(seriesCount);
+
+    switch (type) {
+        case 'bar':
+            return {
+                theme,
+                colors,
+                // 4px rounded data-end, square at the baseline is nivo's
+                // behaviour for a positive bar with a radius.
+                borderRadius: 4,
+                // A 2px gap in the surface colour separates adjacent bars.
+                // padding is a fraction of the band; innerPadding is the pixel
+                // gap between grouped bars.
+                padding: 0.45,
+                innerPadding: 2,
+                enableGridX: false,
+                enableGridY: true,
+                enableLabel: false,
+                axisTop: null,
+                axisRight: null,
+                margin: {
+                    top: 12,
+                    right: 16,
+                    bottom: legends.length ? 72 : 40,
+                    left: 48,
+                },
+                legends,
+                animate: true,
+                motionConfig: 'gentle',
+            };
+
+        case 'line':
+            return {
+                theme,
+                colors,
+                lineWidth: 2,
+                pointSize: 8,
+                pointBorderWidth: 2,
+                // The 2px ring is in the SURFACE colour so a marker stays
+                // legible where it crosses another line.
+                pointBorderColor: {
+                    from: 'color',
+                    modifiers: [['brighter', 3]],
+                },
+                pointColor: { from: 'color' },
+                enableArea: false,
+                areaOpacity: 0.1,
+                useMesh: true,
+                enableGridX: false,
+                enableGridY: true,
+                curve: 'monotoneX',
+                axisTop: null,
+                axisRight: null,
+                margin: {
+                    top: 12,
+                    right: 20,
+                    bottom: legends.length ? 72 : 40,
+                    left: 48,
+                },
+                legends,
+                animate: true,
+                motionConfig: 'gentle',
+            };
+
+        case 'pie':
+            return {
+                theme,
+                colors,
+                innerRadius: 0.62,
+                padAngle: 1.2,
+                cornerRadius: 3,
+                activeOuterRadiusOffset: 6,
+                borderWidth: 0,
+                // Direct labels on the arcs, which is the relief the light
+                // palette's contrast WARN requires.
+                enableArcLinkLabels: true,
+                arcLinkLabelsThickness: 1,
+                arcLinkLabelsColor: { from: 'color' },
+                arcLinkLabelsTextColor: 'inherit',
+                arcLabelsSkipAngle: 12,
+                arcLabelsTextColor: {
+                    from: 'color',
+                    modifiers: [['darker', 3]],
+                },
+                margin: { top: 16, right: 90, bottom: 16, left: 90 },
+                animate: true,
+                motionConfig: 'gentle',
+            };
+
+        default:
+            return { theme, colors };
+    }
+};
+
+export default defaultsFor;