@byline/host-tanstack-start 0.9.3

package/src/admin-shell/chrome/drawer-toggle.module.css

@@ -0,0 +1,30 @@
+/**
+ * DrawerToggle — fixed-position chevron toggle docked to the menu drawer's edge.
+ *
+ * Override handle: .byline-admin-drawer-toggle
+ */
+
+.root,
+:global(.byline-admin-drawer-toggle) {
+  position: fixed;
+  top: 38px;
+  z-index: 50;
+  transition: all 300ms ease-in-out;
+}
+
+.rootClosed,
+:global(.byline-admin-drawer-toggle-closed) {
+  left: 8px;
+}
+
+.rootOpen,
+:global(.byline-admin-drawer-toggle-open) {
+  left: 160px;
+}
+
+.button,
+:global(.byline-admin-drawer-toggle-button) {
+  outline: none;
+  min-width: 42px;
+  height: 36px;
+}

package/src/admin-shell/chrome/drawer-toggle.tsx

@@ -0,0 +1,62 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { IconButton, Tooltip } from '@infonomic/uikit/react'
+import cx from 'classnames'
+
+import styles from './drawer-toggle.module.css'
+import { useAdminMenu } from './menu-provider.js'
+
+export function DrawerToggle() {
+  const { toggleDrawer, drawerOpen } = useAdminMenu()
+
+  return (
+    <div
+      className={cx('byline-admin-drawer-toggle', styles.root, {
+        'byline-admin-drawer-toggle-open': drawerOpen,
+        [styles.rootOpen]: drawerOpen,
+        'byline-admin-drawer-toggle-closed': !drawerOpen,
+        [styles.rootClosed]: !drawerOpen,
+      })}
+    >
+      <Tooltip
+        text={drawerOpen ? 'Collapse sidebar' : 'Expand sidebar'}
+        side="right"
+        sideOffset={8}
+      >
+        <IconButton
+          type="button"
+          className={cx('byline-admin-drawer-toggle-button', styles.button)}
+          variant="text"
+          intent="noeffect"
+          square={true}
+          size="sm"
+          onClick={toggleDrawer}
+          aria-label={drawerOpen ? 'Collapse admin menu' : 'Expand admin menu'}
+          aria-controls="admin-menu"
+        >
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="18"
+            height="18"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            aria-label={drawerOpen ? 'Collapse sidebar' : 'Expand sidebar'}
+            strokeLinejoin="round"
+          >
+            <rect width="18" height="18" x="3" y="3" rx="2" />
+            <path d="M9 3v18" />
+          </svg>
+        </IconButton>
+      </Tooltip>
+    </div>
+  )
+}

package/src/admin-shell/chrome/hamburger.module.css

@@ -0,0 +1,16 @@
+/**
+ * Hamburger — icon button that toggles the admin menu drawer.
+ *
+ * Override handle: .byline-admin-hamburger
+ *
+ * Uses uikit's pre-existing global `.component--hamburger` styles for
+ * the bar visuals; this module just hosts the wrapper override surface.
+ */
+
+.button,
+:global(.byline-admin-hamburger) {
+  background: transparent;
+  border: 0;
+  padding: 0;
+  cursor: pointer;
+}

package/src/admin-shell/chrome/hamburger.tsx

@@ -0,0 +1,56 @@
+'use client'
+
+import type React from 'react'
+
+import cx from 'classnames'
+
+import styles from './hamburger.module.css'
+import { useAdminMenu } from './menu-provider.js'
+
+interface HamburgerProps {
+  className?: string
+  /** Tailwind/utility class string applied to the inner bar; defaults to a white-on-dark fill. */
+  color?: string
+  activeBorderColor?: string
+}
+
+export function Hamburger({
+  className,
+  color = 'bg-white before:bg-white after:bg-white',
+  activeBorderColor: _activeBorderColor,
+  ...other
+}: HamburgerProps): React.JSX.Element {
+  const { toggleDrawer } = useAdminMenu()
+
+  // Hard code the drawer hamburger to always closed
+  // to prevent the 'X' pattern from being the default
+  // on desktop. For a drawer like this - the hamburger
+  // icon doesn't have to animate.
+  const drawerOpen = false
+
+  const handleClick = (event: React.MouseEvent<HTMLButtonElement>): void => {
+    if (event != null) event.stopPropagation()
+    toggleDrawer()
+  }
+
+  return (
+    <button
+      onClick={handleClick}
+      className={cx(
+        'byline-admin-hamburger',
+        styles.button,
+        `component--hamburger ${drawerOpen ? 'is_active' : ''}`,
+        className
+      )}
+      tabIndex={0}
+      aria-label="Open admin menu"
+      aria-controls="admin-menu"
+      aria-haspopup="true"
+      {...other}
+    >
+      <span className="box" aria-hidden="true">
+        <span className={cx('inner', color)} />
+      </span>
+    </button>
+  )
+}

package/src/admin-shell/chrome/loose-router.ts

@@ -0,0 +1,47 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ *
+ * Loosely-typed re-exports of TanStack Router primitives. The package
+ * has no view of the host's generated route tree at type-check time, so
+ * the strict generic typing on `Link` and `useNavigate` collapses
+ * `params`/`search`/`to` to `never`. These wrappers relax the call
+ * signature; runtime behaviour is identical.
+ */
+
+import type React from 'react'
+import { Link as TanStackLink, useNavigate as useTanStackNavigate } from '@tanstack/react-router'
+
+export interface LooseLinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  to?: string
+  // biome-ignore lint/suspicious/noExplicitAny: untyped router params
+  params?: Record<string, any>
+  // biome-ignore lint/suspicious/noExplicitAny: untyped router search
+  search?: any
+  resetScroll?: boolean
+  replace?: boolean
+  // biome-ignore lint/suspicious/noExplicitAny: untyped passthrough props
+  [key: string]: any
+}
+
+export const Link = TanStackLink as unknown as (props: LooseLinkProps) => React.JSX.Element
+
+export interface LooseNavigateOpts {
+  to?: string
+  // biome-ignore lint/suspicious/noExplicitAny: untyped router params
+  params?: Record<string, any>
+  // biome-ignore lint/suspicious/noExplicitAny: untyped router search
+  search?: any
+  replace?: boolean
+  // biome-ignore lint/suspicious/noExplicitAny: untyped passthrough
+  [key: string]: any
+}
+
+export type LooseNavigate = (opts: LooseNavigateOpts) => void
+
+export function useNavigate(): LooseNavigate {
+  return useTanStackNavigate() as unknown as LooseNavigate
+}

package/src/admin-shell/chrome/menu-drawer.module.css

@@ -0,0 +1,196 @@
+/**
+ * Admin menu drawer.
+ *
+ * Override handles:
+ *   .byline-admin-menu-drawer-aside  — outer <aside> wrapper
+ *   .byline-admin-menu-drawer        — <nav> inside the aside
+ *   .byline-admin-menu-item          — each <li.menu-item>
+ *   .byline-admin-menu-separator     — divider <li>
+ *
+ * Inner classnames (`.menu-item`, `.menu-separator`, `.icon`, `.label`,
+ * `.compact`, `.active`) stay as plain string class names so the CSS rule
+ * chains stay readable; targeted via :global in this module.
+ */
+
+.aside,
+:global(.byline-admin-menu-drawer-aside) {
+  display: flex;
+  flex-direction: column;
+  border-right: var(--border-width-thin) var(--border-style-solid) var(--gray-50);
+  background-color: var(--canvas-25);
+  z-index: 15;
+  transition: all 300ms ease-in-out;
+}
+
+:is([data-theme="dark"], :global(.dark)) .aside,
+:is([data-theme="dark"], :global(.dark)) :global(.byline-admin-menu-drawer-aside) {
+  border-right-color: var(--canvas-700);
+  background-color: var(--canvas-800);
+}
+
+.asideMobile,
+:global(.byline-admin-menu-drawer-aside-mobile) {
+  position: fixed;
+  top: 45px;
+  bottom: 0;
+  left: 0;
+}
+
+.asideMobileOpen,
+:global(.byline-admin-menu-drawer-aside-mobile-open) {
+  width: 210px;
+}
+
+.asideMobileClosed,
+:global(.byline-admin-menu-drawer-aside-mobile-closed) {
+  width: 0;
+  overflow: hidden;
+}
+
+.asideDesktop,
+:global(.byline-admin-menu-drawer-aside-desktop) {
+  position: relative;
+  align-self: stretch;
+  flex-shrink: 0;
+}
+
+.asideDesktopOpen,
+:global(.byline-admin-menu-drawer-aside-desktop-open) {
+  width: 210px;
+}
+
+.asideDesktopClosed,
+:global(.byline-admin-menu-drawer-aside-desktop-closed) {
+  width: 60px;
+}
+
+.nav,
+:global(.byline-admin-menu-drawer) {
+  position: sticky;
+  top: 55px;
+  margin: 0;
+  max-height: calc(100vh - 60px);
+  overflow-y: auto;
+}
+
+.nav ul,
+:global(.byline-admin-menu-drawer) ul {
+  margin: 1.4rem 0.5rem 0.5rem;
+  padding: 0;
+  list-style: none;
+  list-style-position: outside;
+}
+
+.nav ul :global(li.menu-item),
+:global(.byline-admin-menu-drawer) ul :global(li.menu-item) {
+  border-radius: 4px;
+  margin: 0;
+  transition: all 200ms ease;
+}
+
+.nav ul :global(li.menu-item .icon),
+:global(.byline-admin-menu-drawer) ul :global(li.menu-item .icon) {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+}
+
+.nav ul :global(li.menu-item .label),
+:global(.byline-admin-menu-drawer) ul :global(li.menu-item .label) {
+  line-height: 0;
+}
+
+.nav ul :global(li.menu-item.compact .label),
+:global(.byline-admin-menu-drawer) ul :global(li.menu-item.compact .label) {
+  display: none;
+}
+
+.nav ul :global(li.menu-item.active),
+.nav ul :global(li.menu-item:hover),
+:global(.byline-admin-menu-drawer) ul :global(li.menu-item.active),
+:global(.byline-admin-menu-drawer) ul :global(li.menu-item:hover) {
+  background-color: var(--canvas-50);
+}
+
+.nav ul :global(li.menu-item) :is(a, button),
+:global(.byline-admin-menu-drawer) ul :global(li.menu-item) :is(a, button) {
+  display: flex;
+  align-items: center;
+  justify-content: flex-start;
+  width: 100%;
+  padding: 7px;
+  gap: 8px;
+  color: #111111;
+  font-size: 0.9rem;
+  font-weight: normal;
+  text-decoration: none;
+  background: none;
+  border: none;
+  cursor: pointer;
+  text-align: left;
+}
+
+.nav ul :global(li.menu-item) :is(a, button):disabled,
+:global(.byline-admin-menu-drawer) ul :global(li.menu-item) :is(a, button):disabled {
+  cursor: not-allowed;
+  opacity: 0.6;
+}
+
+.nav ul :global(li.menu-item.compact) :is(a, button),
+:global(.byline-admin-menu-drawer) ul :global(li.menu-item.compact) :is(a, button) {
+  justify-content: center;
+}
+
+.nav ul :global(li.menu-item.active) :is(a, button),
+:global(.byline-admin-menu-drawer) ul :global(li.menu-item.active) :is(a, button) {
+  color: #111111;
+  text-decoration: none;
+}
+
+.nav ul :global(li.menu-separator),
+:global(.byline-admin-menu-drawer) ul :global(li.menu-separator) {
+  padding-top: 0.5px;
+  margin: 0.75rem auto;
+  width: 90%;
+  background-color: #dddddd;
+}
+
+:is([data-theme="dark"], :global(.dark)) .nav ul :global(li.menu-item) :is(a, button),
+:is([data-theme="dark"], :global(.dark))
+  :global(.byline-admin-menu-drawer)
+  ul
+  :global(li.menu-item)
+  :is(a, button) {
+  color: #dddddd;
+}
+
+:is([data-theme="dark"], :global(.dark)) .nav ul :global(li.menu-item.active) :is(a, button),
+:is([data-theme="dark"], :global(.dark))
+  :global(.byline-admin-menu-drawer)
+  ul
+  :global(li.menu-item.active)
+  :is(a, button) {
+  color: #ffffff;
+}
+
+:is([data-theme="dark"], :global(.dark)) .nav ul :global(li.menu-item.active),
+:is([data-theme="dark"], :global(.dark)) .nav ul :global(li.menu-item:hover),
+:is([data-theme="dark"], :global(.dark))
+  :global(.byline-admin-menu-drawer)
+  ul
+  :global(li.menu-item.active),
+:is([data-theme="dark"], :global(.dark))
+  :global(.byline-admin-menu-drawer)
+  ul
+  :global(li.menu-item:hover) {
+  background-color: oklch(from var(--canvas-700) calc(l * 0.95) c h);
+}
+
+:is([data-theme="dark"], :global(.dark)) .nav ul :global(li.menu-separator),
+:is([data-theme="dark"], :global(.dark))
+  :global(.byline-admin-menu-drawer)
+  ul
+  :global(li.menu-separator) {
+  background-color: #444444;
+}

package/src/admin-shell/chrome/menu-drawer.tsx

@@ -0,0 +1,155 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type React from 'react'
+import { useRouterState } from '@tanstack/react-router'
+
+import { ADMIN_PERMISSIONS_ABILITIES } from '@byline/admin/admin-permissions'
+import { ADMIN_ROLES_ABILITIES } from '@byline/admin/admin-roles'
+import { ADMIN_USERS_ABILITIES } from '@byline/admin/admin-users'
+import {
+  HomeIcon,
+  RolesIcon,
+  SettingsSlidersIcon,
+  UserIcon,
+  UsersIcon,
+} from '@infonomic/uikit/react'
+import cx from 'classnames'
+import { useSwipeable } from 'react-swipeable'
+
+import { useAbilities } from '../../integrations/abilities.js'
+import { Link } from './loose-router.js'
+import styles from './menu-drawer.module.css'
+import { useAdminMenu } from './menu-provider.js'
+import { PreviewToggle } from './preview-toggle.js'
+
+const isActive = (currentPath: string, linkHref: string): boolean => {
+  // Root admin highlights only on exact match so it doesn't stay lit on
+  // every admin subpath.
+  if (linkHref === '/admin') return currentPath === '/admin'
+  return currentPath.startsWith(linkHref)
+}
+
+interface MenuItemProps {
+  to: string
+  label: string
+  icon: React.ReactNode
+  pathname: string
+  compact: boolean
+}
+
+function MenuItem({ to, label, icon, pathname, compact }: MenuItemProps) {
+  return (
+    <li className={cx('menu-item', { active: isActive(pathname, to), compact })}>
+      <Link to={to}>
+        <span className="icon">{icon}</span>
+        <span className="label">{label}</span>
+      </Link>
+    </li>
+  )
+}
+
+export function AdminMenuDrawer(): React.JSX.Element | null {
+  const pathname = useRouterState({ select: (s) => s.location.pathname })
+  const { mobile, drawerOpen, closeDrawer } = useAdminMenu()
+
+  // Cosmetic ability cues — hide the admin-management section entirely
+  // when the user holds none of its read abilities. Server-side
+  // `assertAdminActor` is the actual gate for each module's commands;
+  // these checks just keep the drawer from advertising areas the user
+  // can't enter.
+  const { has } = useAbilities()
+  const canReadUsers = has(ADMIN_USERS_ABILITIES.read)
+  const canReadRoles = has(ADMIN_ROLES_ABILITIES.read)
+  const canReadPermissions = has(ADMIN_PERMISSIONS_ABILITIES.read)
+  const showAdminSection = canReadUsers || canReadRoles || canReadPermissions
+
+  const handlers = useSwipeable({
+    onSwipedLeft: () => {
+      closeDrawer()
+    },
+  })
+
+  // Compact = icon-only. Only applies to the desktop-closed state; the
+  // mobile overlay always renders with full labels for readability.
+  const compact = mobile === false && drawerOpen === false
+
+  return (
+    <aside
+      id="admin-menu"
+      className={cx('byline-admin-menu-drawer-aside', styles.aside, {
+        'byline-admin-menu-drawer-aside-mobile': mobile === true,
+        [styles.asideMobile]: mobile === true,
+        'byline-admin-menu-drawer-aside-mobile-open': mobile === true && drawerOpen === true,
+        [styles.asideMobileOpen]: mobile === true && drawerOpen === true,
+        'byline-admin-menu-drawer-aside-mobile-closed': mobile === true && drawerOpen === false,
+        [styles.asideMobileClosed]: mobile === true && drawerOpen === false,
+        'byline-admin-menu-drawer-aside-desktop': mobile === false,
+        [styles.asideDesktop]: mobile === false,
+        'byline-admin-menu-drawer-aside-desktop-open': mobile === false && drawerOpen === true,
+        [styles.asideDesktopOpen]: mobile === false && drawerOpen === true,
+        'byline-admin-menu-drawer-aside-desktop-closed': mobile === false && drawerOpen === false,
+        [styles.asideDesktopClosed]: mobile === false && drawerOpen === false,
+      })}
+      {...handlers}
+    >
+      <nav className={cx('byline-admin-menu-drawer admin-menu-drawer', styles.nav)}>
+        <ul>
+          <MenuItem
+            to="/admin"
+            label="Dashboard"
+            icon={<HomeIcon width="20px" height="20px" />}
+            pathname={pathname}
+            compact={compact}
+          />
+          {showAdminSection && (
+            <>
+              <li className="menu-separator" />
+              {canReadUsers && (
+                <MenuItem
+                  to="/admin/users"
+                  label="Admin Users"
+                  icon={<UsersIcon width="20px" height="20px" />}
+                  pathname={pathname}
+                  compact={compact}
+                />
+              )}
+              {canReadRoles && (
+                <MenuItem
+                  to="/admin/roles"
+                  label="Admin Roles"
+                  icon={<RolesIcon width="20px" height="20px" />}
+                  pathname={pathname}
+                  compact={compact}
+                />
+              )}
+              {canReadPermissions && (
+                <MenuItem
+                  to="/admin/permissions"
+                  label="Permissions"
+                  icon={<SettingsSlidersIcon width="20px" height="20px" />}
+                  pathname={pathname}
+                  compact={compact}
+                />
+              )}
+            </>
+          )}
+          <li className="menu-separator" />
+          <PreviewToggle compact={compact} />
+          <MenuItem
+            to="/admin/account"
+            label="Account"
+            icon={<UserIcon />}
+            pathname={pathname}
+            compact={compact}
+          />
+        </ul>
+      </nav>
+    </aside>
+  )
+}

package/src/admin-shell/chrome/menu-provider.tsx

@@ -0,0 +1,95 @@
+'use client'
+
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type React from 'react'
+import { createContext, useContext, useEffect, useMemo, useRef, useState } from 'react'
+import { useRouterState } from '@tanstack/react-router'
+
+import { useMediaQuery } from './use-media-query.js'
+
+interface AdminMenuContextType {
+  mobile: boolean
+  drawerOpen: boolean
+  toggleDrawer: () => void
+  closeDrawer: () => void
+}
+const MenuContext = createContext<AdminMenuContextType | undefined>(undefined)
+
+interface AdminMenuProviderProps {
+  children: React.ReactNode
+}
+
+/**
+ * Routes that want the drawer closed by default to maximise workspace.
+ * Currently collection list / detail / history / api views — a non-admin
+ * editor is rarely looking at the left nav while laying out a document.
+ *
+ * The rule fires on *transitions* into and out of the wide region: entering
+ * closes the drawer, leaving restores it open. Moving between pages inside
+ * the region preserves whatever the user last did with the hamburger, so a
+ * deliberate open stays open.
+ */
+function isWideRoute(pathname: string): boolean {
+  return pathname.startsWith('/admin/collections')
+}
+
+export function AdminMenuProvider({ children }: AdminMenuProviderProps): React.JSX.Element {
+  const pathname = useRouterState({ select: (s) => s.location.pathname })
+  // Mobile-first: assume mobile until the media query resolves so the drawer
+  // doesn't flash open before closing on small screens.
+  const mobile = useMediaQuery('(max-width: 800px)') ?? true
+  const [drawerOpen, setDrawerState] = useState(false)
+  // `null` = first effect run; after that we only reset drawer state on
+  // narrow ↔ wide transitions so manual toggles survive same-area navigation.
+  const prevIsWideRef = useRef<boolean | null>(null)
+
+  useEffect(() => {
+    const nowWide = isWideRoute(pathname)
+    const prevWide = prevIsWideRef.current
+    prevIsWideRef.current = nowWide
+
+    if (mobile) {
+      setDrawerState(false)
+      return
+    }
+
+    if (prevWide === null || prevWide !== nowWide) {
+      // Mount, or a wide ↔ narrow transition.
+      setDrawerState(!nowWide)
+    }
+    // Same-area navigation — preserve the user's manual toggle.
+  }, [pathname, mobile])
+
+  const contextValue = useMemo(() => {
+    const toggleDrawer = (): void => {
+      setDrawerState((prev) => !prev)
+    }
+
+    const closeDrawer = (): void => {
+      if (mobile === true) {
+        setDrawerState(false)
+      }
+    }
+
+    return { mobile, drawerOpen, toggleDrawer, closeDrawer }
+  }, [mobile, drawerOpen])
+
+  return <MenuContext.Provider value={contextValue}>{children}</MenuContext.Provider>
+}
+
+function useAdminMenu(): AdminMenuContextType {
+  const context = useContext(MenuContext)
+  if (context === undefined) {
+    throw new Error('useAdminMenu must be used within an AdminMenuProvider')
+  }
+  return context
+}
+
+export { useAdminMenu }