@visns-studio/visns-components 6.4.4 → 6.5.1

package/package.json

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

package/src/components/Navigation.jsx

@@ -50,6 +50,32 @@ const NAV_ICONS = {
     users: Users,
 };
 
+// The icons an account action can wear, named by a settings entry's `icon`
+// key. Module scope because two surfaces read it now: the header's action
+// chips and — when a project opts in — the sidebar's pinned action rows.
+const SETTING_ICONS = {
+    bug: Bug,
+    calendar: Calendar,
+    draft: FileText,
+    image: Image,
+    peopleGroup: Users,
+    person: User,
+    phone: Phone,
+    shield: Shield,
+    signOut: LogOut,
+    settings: Settings,
+    search: Search,
+    userSearch: UserSearch,
+    clipboardCheck: ClipboardCheck,
+};
+
+// A rail row carries a visible label. In the header these actions were icon
+// chips with a tooltip, so a settings entry is allowed to have no label of
+// its own — the bell in particular usually doesn't.
+const RAIL_ACTION_LABELS = {
+    notifications: 'Notifications',
+};
+
 const SearchComponent = ({
     navigate,
     search,
@@ -270,21 +296,7 @@ function Navigation({
     };
 
     const renderSetting = (n) => {
-        const iconComponents = {
-            bug: Bug,
-            calendar: Calendar,
-            draft: FileText,
-            image: Image,
-            peopleGroup: Users,
-            person: User,
-            phone: Phone,
-            shield: Shield,
-            signOut: LogOut,
-            settings: Settings,
-            search: Search,
-            userSearch: UserSearch,
-            clipboardCheck: ClipboardCheck,
-        };
+        const iconComponents = SETTING_ICONS;
 
         // Check if the setting's URL matches the current page
         const isActive = n.url && n.url === `/${currentPage}`;
@@ -356,6 +368,93 @@ function Navigation({
         }
     };
 
+    /**
+     * The same account actions, drawn as rows for the sidebar rail.
+     *
+     * Opt-in only — see `actionsInSidebar` below. Every action keeps the
+     * behaviour it had in the header: the same logout handler, the same
+     * links, the same mounted components (notifications, account switcher),
+     * so nothing here re-implements a chip. What changes is the shape: a
+     * full-width row wearing the rail's own language, icon then label, since
+     * a 36px chip in a 216px column reads as a stray button.
+     *
+     * Components mounted here draw their own trigger and can't be handed a
+     * label, so the row publishes one as `--nav-action-label` for their
+     * stylesheet to place. See Notification.module.scss / SwitchAccount.
+     */
+    const renderRailSetting = (n) => {
+        const isActive = n.url && n.url === `/${currentPage}`;
+        const activeClass = isActive ? styles.active : '';
+        const label = n.label || RAIL_ACTION_LABELS[n.id] || '';
+        // A CSS string, quoted and escaped, for `content`.
+        const labelVar = { '--nav-action-label': JSON.stringify(label) };
+        const IconComponent = SETTING_ICONS[n.icon];
+
+        if (n.id === 'notifications') {
+            return (
+                <li style={labelVar}>
+                    <Notification setSystemAuth={setSystemAuth} />
+                </li>
+            );
+        } else if (n.id === 'businessCardOcr') {
+            return (
+                <li>
+                    <button
+                        onClick={() => setShowBusinessCardOcr(true)}
+                        className={activeClass}
+                        type="button"
+                    >
+                        <CreditCard size={19} strokeWidth={2} />
+                        <span>{label}</span>
+                    </button>
+                </li>
+            );
+        } else if (n.id === 'switchAccount') {
+            return (
+                <li style={labelVar}>
+                    <SwitchAccount
+                        setSystemAuth={setSystemAuth}
+                        setting={n}
+                        userProfile={userProfile}
+                    />
+                </li>
+            );
+        } else if (n.id === 'logout') {
+            return (
+                <li>
+                    <button
+                        onClick={handleLogout}
+                        className={activeClass}
+                        type="button"
+                    >
+                        {IconComponent && (
+                            <IconComponent size={19} strokeWidth={2} />
+                        )}
+                        <span>{label}</span>
+                    </button>
+                </li>
+            );
+        }
+
+        return (
+            <li>
+                <Link
+                    to={n.url}
+                    className={`${activeClass}`}
+                    target={n.target ? n.target : '_self'}
+                    // The rail is the mobile drawer below 1024px; navigating
+                    // from it has to close the drawer, as the nav list does.
+                    onClick={() => setOpen(false)}
+                >
+                    {IconComponent && (
+                        <IconComponent size={19} strokeWidth={2} />
+                    )}
+                    <span>{label}</span>
+                </Link>
+            </li>
+        );
+    };
+
     const [, setActiveDropdown] = useState(null); // We only need the setter
     const navWrapRef = useRef(null);
 
@@ -704,14 +803,60 @@ function Navigation({
         };
     }, [debugIcons]);
 
+    /**
+     * `navConfig.actionsPlacement === 'sidebar'` moves the account actions
+     * out of the 50px content header and pins them to the bottom of the
+     * rail, which is otherwise empty space, so the page gets the whole
+     * height of the glass. Every project that publishes nothing — or
+     * 'header' — renders exactly what it rendered before.
+     */
+    const actionsInSidebar =
+        (layout === 'simple' || layout === 'cms') &&
+        navConfig.actionsPlacement === 'sidebar';
+    const searchEnabled = navConfig.search?.enable === true;
+    /**
+     * With the actions gone the header holds a search field the project may
+     * not have enabled and a hamburger that only exists below 1024px. In
+     * that case it stays in the markup — the drawer is anchored under it and
+     * offsets itself by its 50px — but desktop drops it, and the main
+     * container starts at the top of the viewport.
+     */
+    const headerIsMobileOnly = actionsInSidebar && !searchEnabled;
+
+    // Built only when a project asks for it, so the default path does no
+    // work it then throws away.
+    const railActions = !actionsInSidebar ? null : (
+        <div
+            className={styles['rail-actions']}
+            /* Read by the stylesheets of the components mounted in here —
+               the notification panel and the account switcher list both
+               anchor to a header chip by default, which from a rail at the
+               left edge would open off-screen. */
+            data-nav-actions="sidebar"
+            ref={actionItemsRef}
+        >
+            <ul>
+                {navData.settings.map((setting, settingKey) =>
+                    setting.hidden !== true && setting.permission === true ? (
+                        <React.Fragment key={`rail-setting-${settingKey}`}>
+                            {renderRailSetting(setting)}
+                        </React.Fragment>
+                    ) : null
+                )}
+            </ul>
+        </div>
+    );
+
     return layout === 'simple' || layout === 'cms' ? (
         <div className={styles.cwrap}>
             <aside
-                className={
-                    isOpen
-                        ? `${styles['aside--cms']} ${styles['aside--cms--open']}`
-                        : `${styles['aside--cms']}`
-                }
+                className={[
+                    styles['aside--cms'],
+                    isOpen ? styles['aside--cms--open'] : '',
+                    actionsInSidebar ? styles['aside--cms--rail'] : '',
+                ]
+                    .filter(Boolean)
+                    .join(' ')}
             >
                 <div className={styles.logo}>
                     <Link to="/">
@@ -733,6 +878,7 @@ function Navigation({
                         </ul>
                     </nav>
                 </div>
+                {railActions}
             </aside>
             {isOpen ? (
                 <button
@@ -742,8 +888,20 @@ function Navigation({
                     onClick={() => setOpen(false)}
                 />
             ) : null}
-            <main className={styles.content}>
-                <div className={styles['content-header']}>
+            <main
+                className={
+                    headerIsMobileOnly
+                        ? `${styles.content} ${styles['content--full']}`
+                        : styles.content
+                }
+            >
+                <div
+                    className={
+                        headerIsMobileOnly
+                            ? `${styles['content-header']} ${styles['content-header--mobile']}`
+                            : styles['content-header']
+                    }
+                >
                     {navConfig.search?.enable === true && (
                         <SearchComponent
                             navigate={navigate}
@@ -774,25 +932,27 @@ function Navigation({
                             <span></span>
                         </button>
                     </div>
-                    <div
-                        className={`${styles['hactions-alternate']} ${
-                            debugIcons ? styles['debug-icons'] : ''
-                        }`}
-                        ref={actionItemsRef}
-                    >
-                        <ul>
-                            {navData.settings.map((setting, settingKey) =>
-                                setting.hidden !== true &&
-                                setting.permission === true ? (
-                                    <React.Fragment
-                                        key={`setting-${settingKey}`}
-                                    >
-                                        {renderSetting(setting)}
-                                    </React.Fragment>
-                                ) : null
-                            )}
-                        </ul>
-                    </div>
+                    {actionsInSidebar ? null : (
+                        <div
+                            className={`${styles['hactions-alternate']} ${
+                                debugIcons ? styles['debug-icons'] : ''
+                            }`}
+                            ref={actionItemsRef}
+                        >
+                            <ul>
+                                {navData.settings.map((setting, settingKey) =>
+                                    setting.hidden !== true &&
+                                    setting.permission === true ? (
+                                        <React.Fragment
+                                            key={`setting-${settingKey}`}
+                                        >
+                                            {renderSetting(setting)}
+                                        </React.Fragment>
+                                    ) : null
+                                )}
+                            </ul>
+                        </div>
+                    )}
                 </div>
                 {children}
             </main>

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

@@ -707,7 +707,10 @@
     .logo {
         width: 100%;
         position: relative;
-        background: rgba(var(--tertiary-color-rgb), 0.95);
+        /* Near-white by default (the rendering every project has today).
+           A project whose page background is the same colour can merge the
+           plate into the rail instead: `--nav-logo-bg: var(--nav-bg)`. */
+        background: var(--nav-logo-bg, rgba(var(--tertiary-color-rgb), 0.95));
         height: 50px;
         display: flex;
         flex-wrap: nowrap;
@@ -870,6 +873,145 @@
     }
 }
 
+/* ----------------------------------------------------------------------------
+   Sidebar-owned account actions — opt-in
+   ----------------------------------------------------------------------------
+   `navConfig.actionsPlacement: 'sidebar'` moves the notification bell, the
+   profile link, the logout button and anything else a project mounts as a
+   "setting" out of the 50px content header and pins them to the bottom of the
+   rail, which was empty space. The page then gets the full height of the
+   glass. Nothing below applies unless the consumer publishes that key.
+   ------------------------------------------------------------------------- */
+.aside--cms--rail {
+    /* Three bands: the logo plate, the nav list that takes what's left and
+       scrolls, and the actions pinned under it. */
+    display: flex;
+    flex-direction: column;
+
+    /* The rail clips itself so a long nav list can't spill; the panels that
+       open from the action rows — the notification list, the account
+       switcher — would be cut off by that. The nav list keeps its own
+       scroll container, so nothing else depended on this. */
+    overflow: visible;
+
+    .awrap {
+        /* `min-height: 0` or the nav list refuses to shrink below its
+           content and pushes the actions off the bottom of the rail. */
+        flex: 1 1 auto;
+        min-height: 0;
+        display: flex;
+        flex-direction: column;
+
+        .navwrap {
+            flex: 1 1 auto;
+            min-height: 0;
+            /* The fixed `calc(100vh - 50px)` assumed the rail's only other
+               band was the logo plate. The column measures it now. */
+            max-height: none;
+        }
+    }
+}
+
+.rail-actions {
+    flex: 0 0 auto;
+    position: relative;
+    /* Above the content header's sticky 995 so a panel opening from a row
+       is never painted underneath it. */
+    z-index: 996;
+    /* Reads as a footer to the list rather than one more entry in it. */
+    border-top: 1px solid rgba(var(--tertiary-color-rgb), 0.14);
+    padding: var(--padding) 0;
+
+    > ul {
+        list-style: none;
+        margin: 0;
+        padding: 0;
+        display: flex;
+        flex-direction: column;
+        width: 100%;
+
+        > li {
+            /* Same gutter as `.app-nav .nav-item`, so the rows line up with
+               the navigation above them to the pixel. */
+            width: 100%;
+            padding: 0.15rem 0.45rem;
+            box-sizing: border-box;
+            /* The positioning context for the panels a mounted component
+               opens — they anchor to the nearest positioned ancestor. */
+            position: relative;
+        }
+
+        // A row wears the rail's own language: the nav item's padding,
+        // radius and hover tint. Depth-limited on purpose — the panels these
+        // components open live deeper inside the same `li` and must keep
+        // their own styling.
+        > li > a,
+        > li > button,
+        > li > div > a,
+        > li > div > button {
+            width: 100%;
+            display: flex;
+            flex-wrap: nowrap;
+            align-items: center;
+            gap: 0.55rem;
+            box-sizing: border-box;
+            padding: 0.5rem 1rem;
+            margin: 0;
+            line-height: 1.25;
+            text-align: left;
+            text-decoration: none;
+            color: var(--tertiary-color);
+            background: var(--nav-bg);
+            border: none;
+            outline: none;
+            border-radius: var(--br);
+            font: inherit;
+            /* Stated after the `font` shorthand: the nav rows above take
+               these from the shared `.app-nav` rule, and a footer that sets
+               neither reads two sizes larger than the list it footers. */
+            font-size: var(--nav-item-font-size, var(--font-size-sm, 0.8125rem));
+            font-weight: var(--font-weight-medium, 500);
+            cursor: pointer;
+            appearance: none;
+            transition: all 0.65s cubic-bezier(0.25, 0.8, 0.25, 1);
+
+            svg {
+                flex: 0 0 auto;
+                color: var(--secondary-color);
+            }
+        }
+
+        > li > a:hover,
+        > li > button:hover,
+        > li > div > a:hover,
+        > li > div > button:hover,
+        > li > a.active {
+            background: rgba(var(--tertiary-color-rgb), 0.05);
+            color: var(--secondary-color);
+        }
+
+        // Components mounted here wrap their trigger in a div of their own
+        // (`.notificationContainer`, the switcher's wrapper). Left as an
+        // inline-ish block it would collapse the row.
+        > li > div {
+            width: 100%;
+            position: relative;
+        }
+
+        // A mounted component draws its own trigger and takes no label from
+        // us, so the row publishes one as `--nav-action-label` and the
+        // trigger wears it. Empty by default, so a component that already
+        // labels itself is untouched. (The notification bell sets its own
+        // fallback text — see Notification.module.scss.)
+        > li > div > a::after {
+            content: var(--nav-action-label, '');
+            flex: 1 1 auto;
+            min-width: 0;
+            text-align: left;
+        }
+    }
+}
+
 .content {
     margin-left: var(--sidebar-width);
     flex-grow: 1;
@@ -952,6 +1094,21 @@
     }
 }
 
+/* With the actions in the rail and no search field configured, the only
+   thing left in the header is the drawer's hamburger — which exists below
+   1024px and nowhere else. The bar stays in the markup so the drawer keeps
+   the 50px anchor it offsets itself by, and desktop simply drops it. */
+.content .content-header--mobile {
+    display: none;
+}
+
+/* Nothing sits above the page any more, so the main container is the
+   viewport. Without this it is only as tall as its content and the page
+   background stops short on a short screen. */
+.content--full {
+    min-height: 100vh;
+}
+
 /* Rendered only while the mobile drawer is open; the phone block below
    displays it. Desktop never opens the drawer, but the guard costs nothing. */
 .drawer-backdrop {
@@ -1016,6 +1173,41 @@
         }
     }
 
+    /* The account actions sit at the foot of the drawer, above the home
+       indicator, at the same touch size as the nav rows above them. */
+    .rail-actions {
+        padding: 0.35rem 0 calc(0.35rem + env(safe-area-inset-bottom, 0px));
+
+        > ul > li {
+            padding: 0.2rem 0.65rem;
+        }
+
+        // Depth-limited: the panels these rows open live deeper in the same
+        // `li` and size their own icons.
+        > ul > li > a,
+        > ul > li > button,
+        > ul > li > div > a,
+        > ul > li > div > button {
+            padding: 0.85rem 1rem;
+            font-size: 1rem;
+            line-height: 1.3;
+
+            > svg {
+                width: 20px;
+                height: 20px;
+            }
+        }
+    }
+
+    .content .content-header--mobile {
+        display: flex;
+    }
+
+    .content--full {
+        /* The 50px bar is still there below this width. */
+        min-height: calc(100vh - 50px);
+    }
+
     .drawer-backdrop {
         display: block;
         position: fixed;

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

@@ -448,3 +448,86 @@
         width: 300px;
     }
 }
+
+/* ----------------------------------------------------------------------------
+   Mounted in the sidebar rail
+   ----------------------------------------------------------------------------
+   A project can opt its navigation into `actionsPlacement: 'sidebar'`, which
+   pins the account actions to the bottom of the rail instead of the content
+   header. The rail's block advertises itself with `data-nav-actions="sidebar"`
+   (see Navigation.jsx / Navigation.module.scss `.rail-actions`), which is all
+   this file needs to know.
+
+   Two things change. The trigger is a full-width row rather than a 36px chip,
+   so it carries a visible label — published by the row as `--nav-action-label`
+   because the component draws its own trigger and takes no label of its own.
+   And the panel anchors to the row's right edge: `top: 100%; right: 0` would
+   drop it below the foot of the viewport and off the left of the screen.
+
+   The row's own padding, colour and radius come from `.rail-actions`; only
+   what this file would otherwise force back is restated here.
+   ------------------------------------------------------------------------- */
+[data-nav-actions='sidebar'] {
+    .notificationTrigger {
+        justify-content: flex-start;
+        /* The chip was a fixed 40px square; a row is as tall as the padding
+           the rail gives it, which is what the rows beside it measure. */
+        height: auto;
+
+        // The label. `content` reads the row's custom property; the fallback
+        // covers a settings entry that never carried a label — in the header
+        // the bell was an icon with a tooltip, so most don't.
+        &::after {
+            content: var(--nav-action-label, 'Notifications');
+            flex: 1 1 auto;
+            min-width: 0;
+            text-align: left;
+        }
+
+        // The chip's lift read as a stray button in a list of rows. The
+        // focus ring is left alone — it is the only keyboard affordance
+        // these rows have.
+        &:hover,
+        &:focus,
+        &:active {
+            transform: none;
+        }
+
+        &:hover {
+            background-color: rgba(var(--tertiary-color-rgb), 0.05);
+            color: var(--secondary-color);
+        }
+    }
+
+    // Was pinned to the corner of a round chip. On a wide row it belongs at
+    // the end of the line, where the eye lands after the label.
+    .badge {
+        top: 50%;
+        right: 14px;
+        transform: translateY(-50%);
+    }
+
+    // Beside the rail, bottom-aligned with the row that opened it.
+    .dropdownWrapper {
+        top: auto;
+        right: auto;
+        bottom: 0;
+        left: calc(100% + 10px);
+        margin-top: 0;
+    }
+
+    @media (max-width: 1024px) {
+        // Inside the drawer there is nothing to the right, so the panel
+        // opens upward from the row.
+        .dropdownWrapper {
+            left: 0;
+            bottom: calc(100% + 8px);
+        }
+
+        // Keeps the panel inside a phone's viewport when the list is long —
+        // it grows from the foot of the drawer towards the header.
+        .notiscrollwrap {
+            max-height: 40vh;
+        }
+    }
+}

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

@@ -24,6 +24,28 @@
     z-index: 999;
 }
 
+/* Mounted in the sidebar rail — `navConfig.actionsPlacement: 'sidebar'`.
+   The list is sized and shunted 470px left to hang off a chip at the top
+   right of the header; from a rail at the left edge that puts it off-screen.
+   The rail's action block advertises itself with `data-nav-actions`, which is
+   all this file needs to know. See Navigation.module.scss `.rail-actions`. */
+[data-nav-actions='sidebar'] .notibox {
+    width: min(550px, calc(100vw - var(--sidebar-width) - 24px));
+    max-height: 60vh;
+    transform: none;
+    left: calc(100% + 10px);
+    bottom: 0;
+}
+
+@media (max-width: 1024px) {
+    /* Inside the drawer there is nothing to the right of the row. */
+    [data-nav-actions='sidebar'] .notibox {
+        width: min(550px, calc(100vw - 24px));
+        left: 0;
+        bottom: calc(100% + 8px);
+    }
+}
+
 .notibox-item {
     width: 100%;
     display: block;