@flamingo-stack/openframe-frontend-core 0.0.499 → 0.0.500

package/dist/index.js

@@ -394,6 +394,7 @@ import {
   MspOrganizationCard,
   MspOrganizationCardSkeleton,
   MultiLevelNavigation,
+  NAVIGATION_SIDEBAR_WIDTH_VAR,
   NETWORK_CONFIG,
   NEW_TAB_FEATURES,
   NavLinkAnchorViaRuntime,
@@ -475,6 +476,7 @@ import {
   ROADMAP_STATUS_OPTIONS,
   ROW_HEIGHT_DESKTOP,
   ROW_HEIGHT_MOBILE,
+  ROW_SHELL_CLASSES,
   RadioGroup,
   RadioGroupBlock,
   RadioGroupItem,
@@ -989,7 +991,7 @@ import {
   walkthroughDismissCookieName,
   withFirstTouchAttribution,
   writeDismissCookie
-} from "./chunk-QUFB5SDZ.js";
+} from "./chunk-SOX7CGFX.js";
 import {
   CommandApprovalToast,
   DEFAULT_MIN_FILL_MS,
@@ -1079,6 +1081,7 @@ import {
   useHumanitySignals,
   useImageEdgeColor,
   useIsTruncated,
+  useIsomorphicLayoutEffect,
   useLgUp,
   useLocalStorage,
   useMarqueeEngine,
@@ -1109,7 +1112,7 @@ import {
   validateSchema,
   validateVariables,
   variablesToUrlParams
-} from "./chunk-QL5YB4F7.js";
+} from "./chunk-P7IOCYGD.js";
 import {
   PLAY_ICON_PATH
 } from "./chunk-OYGFWWLQ.js";
@@ -1148,7 +1151,7 @@ import {
   SkeletonText,
   SplitButton,
   buttonVariants
-} from "./chunk-QKWOBV55.js";
+} from "./chunk-WHJGRRK2.js";
 import "./chunk-6U3IUD57.js";
 import "./chunk-OHPI2HRK.js";
 import {
@@ -1823,6 +1826,7 @@ export {
   MspOrganizationCard,
   MspOrganizationCardSkeleton,
   MultiLevelNavigation,
+  NAVIGATION_SIDEBAR_WIDTH_VAR,
   NEAR_VIEWPORT_ROOT_MARGIN,
   NETWORK_CONFIG,
   NEW_TAB_FEATURES,
@@ -1927,6 +1931,7 @@ export {
   ROADMAP_STATUS_OPTIONS,
   ROW_HEIGHT_DESKTOP,
   ROW_HEIGHT_MOBILE,
+  ROW_SHELL_CLASSES,
   RadioGroup,
   RadioGroupBlock,
   RadioGroupItem,
@@ -2550,6 +2555,7 @@ export {
   useHumanitySignals,
   useImageEdgeColor,
   useIsTruncated,
+  useIsomorphicLayoutEffect,
   useJetStreamDialogSubscription,
   useLgUp,
   useLoading,

package/dist/types/navigation.d.ts

@@ -87,6 +87,30 @@ export interface SlidingSidebarConfig {
  */
 export interface NavigationSidebarConfig {
     items: NavigationSidebarItem[];
+    /**
+     * Draw placeholder rows instead of `items`.
+     *
+     * For hosts whose navigation is not knowable at first paint — entries gated by
+     * server-loaded feature flags, permissions, or tenant config. Such a host has no
+     * good option without this: rendering the items it has yet means a nav that grows
+     * and shifts as answers arrive, and guessing the gated ones wrong shows entries
+     * that don't belong to the user (a flag that HIDES a legacy entry when enabled
+     * makes "not answered yet" indistinguishable from "off").
+     *
+     * The rows reuse the real entry's geometry and the sidebar's own minimized state,
+     * so the placeholder is correct in both the expanded and the minimized rail with
+     * nothing to pass in — and the handoff to the real nav moves nothing.
+     */
+    loading?: boolean;
+    /**
+     * How many placeholder rows `loading` draws, per section. Defaults to 7 primary
+     * and 2 secondary — the shape of a typical console nav. Pass the counts the host
+     * expects so the placeholder and the loaded nav are the same height.
+     */
+    loadingRows?: {
+        primary?: number;
+        secondary?: number;
+    };
     minimized?: boolean;
     onNavigate?: (path: string) => void;
     onToggleMinimized?: () => void;

package/dist/types/navigation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/types/navigation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/types/navigation.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.499",
+  "version": "0.0.500",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/features/filters-dropdown.tsx

@@ -212,6 +212,19 @@ export const FiltersDropdown: React.FC<FiltersDropdownProps> = ({
     }
   }, [currentFiltersStr])
 
+  // Closing must NOT reset `actualPlacement`.
+  //
+  // The panel stays mounted through its exit transition (see `shouldRender`), so
+  // a reset here lands on something still on screen: a dropdown that had flipped
+  // to the opposite side snaps back the moment it starts fading, sliding roughly
+  // its own width sideways on the way out. It showed up on whichever filter sits
+  // nearest an edge — the last column on tablet, and the same column on desktop
+  // once the window is narrow enough to force the flip.
+  //
+  // Nothing is lost by dropping it: opening recomputes the placement from the
+  // trigger's current rect (see the effect above), so the value left behind is
+  // never read again.
+
   // Close dropdown when clicking outside
   useEffect(() => {
     const handleClickOutside = (event: MouseEvent) => {
@@ -221,7 +234,6 @@ export const FiltersDropdown: React.FC<FiltersDropdownProps> = ({
         !containerRef.current.contains(event.target as Node)
       ) {
         setIsOpen(false)
-        setActualPlacement(placement)
       }
     }
 
@@ -236,19 +248,18 @@ export const FiltersDropdown: React.FC<FiltersDropdownProps> = ({
         document.removeEventListener('mousedown', handleClickOutside)
       }
     }
-  }, [isOpen, placement])
+  }, [isOpen])
 
   // Handle escape key
   useEffect(() => {
     const handleEscape = (e: KeyboardEvent) => {
       if (e.key === 'Escape' && isOpen) {
         setIsOpen(false)
-        setActualPlacement(placement)
       }
     }
     document.addEventListener('keydown', handleEscape)
     return () => document.removeEventListener('keydown', handleEscape)
-  }, [isOpen, placement])
+  }, [isOpen])
 
   const handleToggleOption = (sectionId: string, optionId: string, sectionType: string) => {
     setSelectedFilters(prev => {
@@ -298,8 +309,9 @@ export const FiltersDropdown: React.FC<FiltersDropdownProps> = ({
 
   const handleApply = () => {
     onApply(selectedFilters)
+    // No placement reset — see the note above the outside-click effect. `Reset`
+    // never did one, which is why only Apply and the dismiss paths slid.
     setIsOpen(false)
-    setActualPlacement(placement)
   }
 
   const getActiveFiltersCount = () => {

package/src/components/navigation/app-header.tsx

@@ -50,8 +50,57 @@ export interface AppHeaderProps {
    * EXCEPT the mobile burger menu toggle, which remains interactive.
    */
   disabled?: boolean;
+  /**
+   * Draw placeholder cells instead of the live controls.
+   *
+   * Solves a problem this header cannot solve on its own: its mobile/desktop split
+   * is decided by `useMdUp()`, which answers `undefined` until an effect has run —
+   * and `?? false` turns that into "mobile". The first render is therefore always
+   * the phone header (burger + wordmark, no side actions), which on a desktop load
+   * is a visible flash before the real layout appears. It is also what a host has
+   * to show while the user and the action flags are still loading.
+   *
+   * The placeholder decides mobile vs desktop in CSS instead, so it is correct at
+   * every width on the very first paint, server-rendered included.
+   */
+  loading?: boolean;
+  /**
+   * Shape of the trailing action cells `loading` reserves.
+   *
+   * Needed because the `show*` props are usually the very thing the host is still
+   * waiting on — they are typically driven by feature flags or permissions, so during
+   * `loading` they all read `false` and the placeholder collapses to whatever is
+   * hardcoded on (often just the avatar), which looks nothing like the loaded header.
+   *
+   * Pass the cells the header settles on, in order — see `HeaderLoadingCell` for the
+   * footprints. A bare number is accepted as shorthand for all-`'icon'`.
+   *
+   * Unlike the sidebar's rows, a cell that turns out not to exist is cheap here: the
+   * cells are a right-aligned cluster in otherwise empty space, so one disappearing
+   * shifts nothing else on the page.
+   *
+   * Defaults to the shape implied by the `show*` props, which is right for a host whose
+   * header composition is known up front.
+   */
+  loadingActionCells?: number | ReadonlyArray<HeaderLoadingCell>;
 }
 
+/**
+ * A trailing header cell's footprint while loading — see `loadingActionCells`.
+ *
+ * The breakpoint-scoped members exist because several live cells are themselves
+ * responsive, and a placeholder that ignores that is wider than the header it hands
+ * off to on exactly the viewports where the cluster is tightest:
+ *
+ * - `'icon'` — a fixed 48/56px cell at every width (time tracker, notifications).
+ * - `'icon-md'` — the same cell, from md only (the avatar: `isMdUp && showUser`).
+ * - `'icon-lg'` — the same cell, from lg only (the organization filter, which the
+ *   live header renders `hidden lg:flex`).
+ * - `'wide'` — the Mingo launcher: a 48px square below md, where the live button is
+ *   `iconOnly`, and the fixed 140px labelled cell from md.
+ */
+export type HeaderLoadingCell = 'icon' | 'icon-md' | 'icon-lg' | 'wide';
+
 export const AppHeader = React.memo(function AppHeader({
   showSearch,
   onSearch,
@@ -75,9 +124,36 @@ export const AppHeader = React.memo(function AppHeader({
   isMobileMenuOpen,
   onToggleMobileMenu,
   disabled = false,
+  loading = false,
+  loadingActionCells,
 }: AppHeaderProps) {
   const isMdUp = useMdUp() ?? false;
 
+  // After the only hook above, so the hook order is identical in both branches.
+  if (loading) {
+    return (
+      <AppHeaderSkeleton
+        showSearch={showSearch}
+        actionCells={
+          loadingActionCells ??
+          // Fallback: what the `show*` props imply, in the order the live cells are
+          // mounted below. Only correct for a host that knows its header composition
+          // before it starts loading. The cell types carry each control's own
+          // breakpoint — the organization filter is `hidden lg:flex`, the avatar is
+          // gated on `isMdUp`, and Mingo is `iconOnly` below md.
+          ([
+            showOrganizations && 'icon-lg',
+            showTimeTracker && 'icon',
+            showNotifications && 'icon',
+            showUser && 'icon-md',
+            showMingoAI && 'wide',
+          ].filter(Boolean) as HeaderLoadingCell[])
+        }
+        className={className}
+      />
+    );
+  }
+
   const dimmedClass = disabled ? 'pointer-events-none opacity-50' : '';
   // Cells carry their own dividers in the unified TopNavigation model
   // (the shell no longer applies divide-x).
@@ -268,3 +344,105 @@ function NotificationsHeaderButton({ fallbackUnreadCount, disabled, dimmedClass
 }
 
 export default AppHeader;
+
+// Literal class strings — Tailwind's scanner needs to see them spelled out.
+const CELL_VISIBILITY: Record<Exclude<HeaderLoadingCell, 'wide'>, string | undefined> = {
+  icon: undefined,
+  'icon-md': 'hidden md:flex',
+  'icon-lg': 'hidden lg:flex',
+};
+
+/** One trailing action cell placeholder — mirrors the live cells' 48/56px box. */
+function HeaderCellSkeleton({ className }: { className?: string }) {
+  return (
+    <div
+      className={cn(
+        'flex h-full w-12 shrink-0 items-center justify-center border-l border-ods-border md:w-14',
+        className,
+      )}
+    >
+      <div className="h-4 w-4 animate-pulse rounded bg-ods-border md:h-6 md:w-6" />
+    </div>
+  );
+}
+
+/**
+ * Wide cell placeholder — mirrors `HeaderMingoButton` at both widths, which are
+ * two different shapes: the live button gets `iconOnly={!isMdUp}`, so below md it
+ * drops its wordmark and collapses to the same 48px square as any other cell, and
+ * from md it is the fixed 140px labelled cell. Reserving 140px-worth of icon,
+ * label, gap and padding on a phone would make the placeholder cluster ~70px
+ * wider than the header it hands off to.
+ */
+function HeaderWideCellSkeleton() {
+  return (
+    <div className="flex h-full w-12 shrink-0 items-center justify-center gap-2 border-l border-ods-border md:w-[140px] md:px-4">
+      <div className="h-4 w-4 shrink-0 animate-pulse rounded bg-ods-border md:h-6 md:w-6" />
+      <div className="hidden h-5 animate-pulse rounded bg-ods-border md:block md:w-[72px]" />
+    </div>
+  );
+}
+
+/**
+ * `AppHeader`'s loading state — see `AppHeaderProps.loading`.
+ *
+ * Keep in sync with `AppHeader` above; a diverging placeholder makes the handoff
+ * jump. Every breakpoint decision here is a Tailwind variant on purpose: this is the
+ * one thing the live header cannot do (its split runs through `useMdUp()`), and it
+ * is the whole reason this branch exists.
+ */
+function AppHeaderSkeleton({
+  showSearch,
+  actionCells,
+  className,
+}: {
+  showSearch?: boolean;
+  actionCells: number | ReadonlyArray<HeaderLoadingCell>;
+  className?: string;
+}) {
+  const cells: ReadonlyArray<HeaderLoadingCell> =
+    typeof actionCells === 'number'
+      ? Array.from({ length: Math.max(0, actionCells) }, () => 'icon' as const)
+      : actionCells;
+  return (
+    <TopNavigation
+      className={cn('sticky top-0 z-40', className)}
+      centerBreakpoint="md"
+      aria-busy="true"
+      leading={
+        // Burger cell: mobile only, in CSS.
+        <div className="flex h-full w-12 shrink-0 items-center justify-center border-r border-ods-border md:hidden">
+          <div className="h-4 w-4 animate-pulse rounded bg-ods-border" />
+        </div>
+      }
+      logo={
+        <>
+          <div className="h-6 w-6 shrink-0 animate-pulse rounded bg-ods-border" />
+          <div className="h-4 w-24 animate-pulse rounded bg-ods-border" />
+        </>
+      }
+      // `md:hidden` belongs on the WRAPPER, not the placeholder inside it:
+      // `TopNavigation` builds its padded logo zone whenever `logo` is truthy, and
+      // that padding runs to 24px at md and 80px at lg. The live header passes
+      // `false` here from md up, so the zone does not exist at all — leaving the
+      // wrapper visible would inset the search field by 80px on desktop and shift
+      // it back on handoff, which is the exact jump this branch removes.
+      logoClassName="gap-2 md:hidden"
+      // `TopNavigation` already hides the center zone below `centerBreakpoint`.
+      center={showSearch ? <div className="h-10 w-full animate-pulse rounded-md bg-ods-border" /> : undefined}
+      sideActions={
+        <>
+          {/* Mobile-only search trigger; from md the search lives in the center zone. */}
+          {showSearch && <HeaderCellSkeleton className="md:hidden" />}
+          {cells.map((cell, i) =>
+            cell === 'wide' ? (
+              <HeaderWideCellSkeleton key={i} />
+            ) : (
+              <HeaderCellSkeleton key={i} className={CELL_VISIBILITY[cell]} />
+            ),
+          )}
+        </>
+      }
+    />
+  );
+}

package/src/components/navigation/header-mingo-button.tsx

@@ -39,6 +39,11 @@ export function HeaderMingoButton({
       aria-pressed={isActive}
       className={cn(
         'flex items-center shrink-0 h-full gap-2 px-4',
+        // Fixed 140px cell from md, so the header's right-hand cluster has a
+        // known width and a loading placeholder can reserve it exactly
+        // (`AppHeaderProps.loadingActionCells` → `'wide'`). Content-width below
+        // md, and in `iconOnly` mode, where the control is a square affordance.
+        !iconOnly && 'md:w-[140px] md:justify-center',
         'transition-colors duration-200',
         'focus:outline-none focus-visible:ring-2 focus-visible:ring-ods-accent',
         // Transparent at rest so the cell inherits the bar's background

package/src/components/navigation/index.ts

@@ -22,11 +22,11 @@ export type { SlidingSidebarProps } from './sliding-sidebar'
 export { StickySectionNav, useSectionNavigation } from './sticky-section-nav'
 export type { StickyNavSection } from './sticky-section-nav'
 
-export { NavigationSidebar } from './navigation-sidebar'
+export { NAVIGATION_SIDEBAR_WIDTH_VAR, NavigationSidebar } from './navigation-sidebar'
 export type { NavigationSidebarProps } from './navigation-sidebar'
 
 export { AppHeader } from './app-header'
-export type { AppHeaderProps } from './app-header'
+export type { AppHeaderProps, HeaderLoadingCell } from './app-header'
 
 export { AppLayout, useAppLayoutDrawerContainer } from './app-layout'
 export type { AppLayoutProps } from './app-layout'

package/src/components/navigation/navigation-sidebar-item.tsx

@@ -130,3 +130,25 @@ export const NavigationSidebarItemButton = memo(function NavigationSidebarItemBu
     </Link>
   )
 })
+
+/**
+ * One placeholder entry, for `NavigationSidebarConfig.loading`.
+ *
+ * Deliberately in this file, beside `NavigationSidebarItemButton`: the two must
+ * agree on `h-14`, the `p-[var(--spacing-system-m)]` inset, the 24px icon box and
+ * the label column, or the nav resizes on the handoff. Same reason
+ * `header-skeleton.tsx` sits beside `header.tsx`.
+ *
+ * `showLabel` is the sidebar's own minimized state, so the caller passes what it
+ * already passes the real row — no separate width handling.
+ */
+export function NavigationSidebarItemSkeleton({ showLabel }: { showLabel: boolean }) {
+  return (
+    <div className="w-full flex items-center justify-start h-14 p-[var(--spacing-system-m)]" aria-hidden="true">
+      <div className="relative flex items-center justify-center flex-shrink-0">
+        <div className="h-6 w-6 animate-pulse rounded bg-ods-border" />
+      </div>
+      {showLabel && <div className="h-4 flex-1 ml-[var(--spacing-system-xs)] animate-pulse rounded bg-ods-border" />}
+    </div>
+  )
+}

package/src/components/navigation/navigation-sidebar-toggle.tsx

@@ -30,12 +30,16 @@ export function NavigationSidebarToggle({
         aria-label={"Hide Menu"}
       >
         <div className="flex items-center justify-center flex-shrink-0">
-          <Chevrons03LeftIcon
-            className={cn(
-              "text-ods-text-secondary w-6 h-6 transition-transform duration-300",
-              minimized && "rotate-180",
-            )}
-          />
+          {/* Direction follows the rail's measured width (the `of-nav-sidebar`
+              container declared in `navigation-sidebar.tsx`), not `minimized`:
+              before hydration that prop can only carry the server's answer, and
+              a chevron pointing the wrong way in a 56px rail is the one piece of
+              sidebar state a user actually notices arriving late.
+
+              Collapsed is the default because container queries are min-width —
+              the rail is narrower than every threshold, so it needs no query of
+              its own. */}
+          <Chevrons03LeftIcon className="rotate-180 @[140px]/of-nav-sidebar:rotate-0 text-ods-text-secondary w-6 h-6 transition-transform duration-300" />
         </div>
 
         <span