astrogators-shared-ui 0.14.0 → 0.16.0

package/dist/src/components/forms/AllyCodeDropdown.d.ts

@@ -2,6 +2,16 @@ import { default as React } from 'react';
 export interface AllyCodeDropdownProps {
     onAllyCodeSelected?: (allyCode: string | null) => void;
     className?: string;
+    /** Controlled manage-panel open state, so a parent (NavBar) can enforce
+     *  "only one popover open at a time" across the whole bar. Falls back to
+     *  self-managed state when omitted. */
+    isOpen?: boolean;
+    onOpenChange?: (isOpen: boolean) => void;
+    /** 'floating' (default): an absolutely-positioned popover, for the desktop
+     *  bar. 'inline': a plain block in normal flow — used when this is nested
+     *  inside MobileNavPanel's own scroll container, where a floating popover
+     *  could get clipped by an ancestor's `overflow`. */
+    variant?: 'floating' | 'inline';
 }
 /**
  * AllyCodeDropdown component

package/dist/src/components/layout/AccountCluster.d.ts

@@ -0,0 +1,13 @@
+import { default as React } from 'react';
+export interface AccountClusterProps {
+    /** Render the username/Admin/Logout (or Login/Sign Up) cluster. Default
+     *  true. Set false for a static page that wants no auth UI. */
+    showAuth?: boolean;
+}
+/**
+ * The suite's account block: username/Profile + Admin-if-admin + Logout, or
+ * Login + Sign Up when logged out. Identical on every app — this is the one
+ * place the Admin link lives now, gated directly on `user.role === 'admin'`,
+ * so no app opts in or out of it individually.
+ */
+export declare const AccountCluster: React.FC<AccountClusterProps>;

package/dist/src/components/layout/MobileNavPanel.d.ts

@@ -0,0 +1,24 @@
+import { default as React } from 'react';
+import { SuiteAppId, SuiteNavSection } from '../../navigation/suiteNav';
+export interface MobileNavPanelProps {
+    isOpen: boolean;
+    onClose: () => void;
+    currentApp: SuiteAppId;
+    activeSectionId?: string;
+    onSectionClick?: (section: SuiteNavSection, event: React.MouseEvent<HTMLAnchorElement>) => void;
+    rightExtras?: React.ReactNode;
+    showAuth?: boolean;
+    panelId: string;
+    /** The burger button — focus returns here when Escape closes the panel. */
+    returnFocusRef: React.RefObject<HTMLElement | null>;
+}
+/**
+ * Portalled to `document.body`: TopBar's `backdrop-filter` makes the header
+ * a containing block for `position: fixed` descendants, which would clip a
+ * fixed panel/backdrop rendered inside it. This escapes that entirely.
+ *
+ * Unlike the lightweight desktop NavMenu disclosures, this behaves like a
+ * modal — focus moves in on open, Escape closes and returns focus to the
+ * burger, body scroll is locked while open.
+ */
+export declare const MobileNavPanel: React.FC<MobileNavPanelProps>;

package/dist/src/components/layout/NavBar.d.ts

@@ -1,48 +1,41 @@
 import { default as React } from 'react';
-/**
- * A single top-level section link in the NavBar tab strip.
- *
- * NavBar is intentionally router-agnostic: shared-ui takes no react-router
- * dependency. The consumer decides whether a tab is `active` (e.g. from its own
- * `useLocation`) and may supply `render` to inject a router `<Link>` for soft
- * client-side navigation. Without `render`, the tab is a plain `<a href>`.
- */
-export interface NavItem {
-    label: string;
-    href: string;
-    active?: boolean;
-    render?: (props: {
-        className: string;
-        children: React.ReactNode;
-    }) => React.ReactNode;
-}
+import { SuiteAppId, SuiteNavSection } from '../../navigation/suiteNav';
 export interface NavBarProps {
-    /** Target for the ⟵ "The Astrogator's Table" logo — always the hub. Default '/'. */
-    hubUrl?: string;
-    /** This app's display name, e.g. "Mod Ledger". Omit on the hub (the logo is
-     *  already the suite identity) for a logo-only left section. */
-    appName?: string;
-    /** Link target for the app name — the app's own root. Default '/'. */
-    appHref?: string;
-    /** Top-level section tabs. Omit (or empty) for apps with no sections. */
-    navItems?: NavItem[];
-    /** Render the shared AllyCodeDropdown in the right cluster. Default false. */
-    showAllyCode?: boolean;
-    /** Render the baked username/login/logout cluster. Default true. Set false for
-     *  static pages (e.g. docs) that want no auth UI. */
-    showAuth?: boolean;
-    /** App-specific controls, rendered immediately left of the ally dropdown. */
+    /** Which app is rendering the bar — drives which trigger is highlighted
+     *  and which app's sections `onNavigate` fires for. */
+    currentApp: SuiteAppId;
+    /** Which of currentApp's own sections is active, e.g. from the app's own
+     *  router. Apps detect "where am I" differently (some have no router at
+     *  all), so this is supplied by the consumer, not computed by NavBar. */
+    activeSectionId?: string;
+    /** Fires only for sections belonging to currentApp — cross-app links are
+     *  always real `<a href>` full page loads, never intercepted. Call
+     *  `event.preventDefault()` to soft-navigate instead; the menu closes
+     *  either way, since no page load will unmount it for you. */
+    onNavigate?: (section: SuiteNavSection, event: React.MouseEvent<HTMLAnchorElement>) => void;
+    /** The one per-app element allowed in the bar: RosterRefresh. Always in
+     *  the same slot, just left of the ally-code dropdown on desktop, and
+     *  moves into the mobile panel on small screens. Its position never
+     *  varies — only its presence/content does. */
     rightExtras?: React.ReactNode;
+    /** Render the account cluster (username/Admin/Logout, or Login/Sign Up).
+     *  Default true. Set false only for a fully static page. */
+    showAuth?: boolean;
+    /** Non-layout hooks only (e.g. a data attribute for tests). Nothing
+     *  passed here may change the bar's width, height, padding, or item
+     *  positions — that capability doesn't exist on this component. */
     className?: string;
 }
 /**
- * NavBar — the opinionated, suite-wide top bar built on top of the dumb `TopBar`
- * primitive. It bakes the blessed layout so every app's chrome is identical:
- *
- *   [ logo → hub ] · [ appName ]  [ section tabs ] ···· [ rightExtras ] [ ally ] [ auth cluster ]
- *
- * The username/profile/login/register/logout cluster is owned here (via useAuth);
- * apps no longer hand-roll it. Auth links point at the hub origin as plain anchors
- * because the auth UI lives in the hub and everything is served single-origin.
+ * NavBar — the suite-wide top bar. It is built from exactly one source,
+ * `SUITE_NAV` (`../../navigation/suiteNav.ts`), and exactly one component.
+ * No app passes in its own nav structure, name, or logo target — that
+ * capability was removed, not just left unused, because per-app
+ * configurability of the bar is what caused it to look different in every
+ * app before this component existed. The logo always targets `/`. If a
+ * future app needs something the manifest can't express, the manifest's
+ * shape grows to cover it; this component does not grow an escape-hatch
+ * prop instead. See `../../../CLAUDE.md`'s NavBar note for the full
+ * rationale.
  */
 export declare const NavBar: React.FC<NavBarProps>;

package/dist/src/components/layout/NavBurger.d.ts

@@ -0,0 +1,11 @@
+export interface NavBurgerProps {
+    isOpen: boolean;
+    onClick: () => void;
+    controlsId: string;
+}
+/**
+ * Mobile-only burger/✕ toggle. Stateless — NavBar owns whether the mobile
+ * panel is open; this just renders the current state and reports clicks.
+ * Forwards its ref so MobileNavPanel can return focus here on Escape.
+ */
+export declare const NavBurger: import('react').ForwardRefExoticComponent<NavBurgerProps & import('react').RefAttributes<HTMLButtonElement>>;

package/dist/src/components/layout/NavMenu.d.ts

@@ -0,0 +1,17 @@
+import { default as React } from 'react';
+import { SuiteNavApp, SuiteNavSection } from '../../navigation/suiteNav';
+export interface NavMenuProps {
+    app: SuiteNavApp;
+    isCurrentApp: boolean;
+    activeSectionId?: string;
+    isOpen: boolean;
+    onOpenChange: (isOpen: boolean) => void;
+    onSectionClick?: (section: SuiteNavSection, event: React.MouseEvent<HTMLAnchorElement>) => void;
+}
+/**
+ * One trigger + dropdown panel per SUITE_NAV app. Disclosure pattern, not
+ * `role="menu"` — these are page links, so Tab moves through them like any
+ * other link list; arrow keys are an additive convenience, not a
+ * replacement for Tab.
+ */
+export declare const NavMenu: React.FC<NavMenuProps>;

package/dist/src/components/layout/index.d.ts

@@ -3,6 +3,6 @@ export type { ContainerProps } from './Container';
 export { TopBar } from './TopBar';
 export type { TopBarProps } from './TopBar';
 export { NavBar } from './NavBar';
-export type { NavBarProps, NavItem } from './NavBar';
+export type { NavBarProps } from './NavBar';
 export { Footer } from './Footer';
 export type { FooterProps } from './Footer';

package/dist/src/hooks/useDismissableMenu.d.ts

@@ -0,0 +1,18 @@
+import { RefObject } from 'react';
+export interface UseDismissableMenuOptions {
+    isOpen: boolean;
+    onClose: () => void;
+    /** The trigger button — clicks on it don't count as "outside", and Escape
+     *  returns focus here. */
+    triggerRef: RefObject<HTMLElement | null>;
+    /** The open panel — clicks inside it don't count as "outside" either. */
+    panelRef: RefObject<HTMLElement | null>;
+}
+/**
+ * Shared outside-click + Escape-to-close-and-refocus behavior for the
+ * suite's small header popovers (per-app NavMenu, AllyCodeDropdown in its
+ * floating variant). Not used by MobileNavPanel: portalled to
+ * `document.body`, it has its own backdrop element to click and a full-panel
+ * focus-trap concern this hook doesn't try to cover.
+ */
+export declare function useDismissableMenu({ isOpen, onClose, triggerRef, panelRef, }: UseDismissableMenuOptions): void;

package/dist/src/index.d.ts

@@ -1,5 +1,7 @@
 export { Container, TopBar, NavBar, Footer } from './components/layout';
-export type { ContainerProps, TopBarProps, NavBarProps, NavItem, FooterProps } from './components/layout';
+export type { ContainerProps, TopBarProps, NavBarProps, FooterProps } from './components/layout';
+export { SUITE_NAV } from './navigation/suiteNav';
+export type { SuiteAppId, SuiteNavApp, SuiteNavSection } from './navigation/suiteNav';
 export { Button, Input, Select, AllyCodeDropdown, RosterRefresh } from './components/forms';
 export type { ButtonProps, InputProps, SelectProps, SelectOption, AllyCodeDropdownProps, RosterRefreshProps } from './components/forms';
 export { Card, Badge, Modal } from './components/display';

package/dist/src/navigation/suiteNav.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The single source of truth for the suite-wide NavBar's contents.
+ *
+ * No app passes its own name, sections, or logo target into `NavBar` — it all
+ * comes from here. If a future app needs something this shape can't express,
+ * grow the shape (a new field on `SuiteNavApp`/`SuiteNavSection`); an app
+ * never gets its own bypass prop instead. See `NavBar`'s doc comment and
+ * `../../CLAUDE.md`'s NavBar note for the full rationale.
+ */
+export type SuiteAppId = 'hub' | 'mod-ledger' | 'navicharts' | 'nightwatcher';
+export interface SuiteNavSection {
+    id: string;
+    label: string;
+    /** Absolute, same-origin path, e.g. '/mod-ledger/evaluations'. */
+    href: string;
+    /** Hidden when logged out. */
+    requiresAuth?: boolean;
+    /** Hidden unless the current user's role is in this list. */
+    roles?: string[];
+}
+export interface SuiteNavApp {
+    id: Exclude<SuiteAppId, 'hub'>;
+    label: string;
+    href: string;
+    status: 'available' | 'coming-soon';
+    sections: SuiteNavSection[];
+}
+export declare const SUITE_NAV: SuiteNavApp[];

package/dist/src/services/tokenRefresh.d.ts

@@ -19,6 +19,11 @@ export declare const refreshAccessToken: () => Promise<string>;
  * refresh is needed but fails (e.g. the refresh token is also expired), the
  * original 401 Response is returned so the caller can surface a re-login state.
  *
+ * Transient unavailability (a backend swapped mid-deploy, a 502/503/504, a
+ * dropped connection) is retried a couple of times — see `fetchWithRetry` for
+ * the exact, deliberately-narrow policy (non-idempotent writes are only
+ * retried when no response was ever received).
+ *
  * Works against ANY resource URL; only the refresh hop uses the configured
  * auth base URL.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astrogators-shared-ui",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Shared UI components and utilities for Astrogator's Table applications",
   "type": "module",
   "main": "./dist/index.js",