npm - @flamingo-stack/openframe-frontend-core - Versions diffs - 0.0.499 → 0.0.500 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (156) hide show

package/src/components/navigation/navigation-sidebar.tsx CHANGED Viewed

@@ -1,18 +1,115 @@
 "use client"
-import { useCallback, useEffect, useLayoutEffect, useMemo, useState } from 'react'
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { useIsomorphicLayoutEffect } from '../../hooks/ui/use-isomorphic-layout-effect'
 import { useLocalStorage } from '../../hooks/ui/use-local-storage'
 import { useLgUp, useMdUp } from '../../hooks/ui/use-media-query'
 import { NavigationSidebarConfig, NavigationSidebarItem } from '../../types/navigation'
 import { cn } from '../../utils'
 import { NavigationSidebarHeader } from './navigation-sidebar-header'
-import { NavigationSidebarItemButton } from './navigation-sidebar-item'
+import { NavigationSidebarItemButton, NavigationSidebarItemSkeleton } from './navigation-sidebar-item'
 import { NavigationSidebarToggle } from './navigation-sidebar-toggle'
 const MINIMIZED_WIDTH = 56 // 3.5rem = 56px
 const EXPANDED_WIDTH = 224 // 14rem = 224px
 const STORAGE_KEY = 'of.navigationSidebar.minimized'
+/**
+ * The desktop width, as a custom property on `:root`. Read by the `lg:` rule in
+ * {@link SIDEBAR_GEOMETRY_CLASSES} and written by this component whenever the
+ * user toggles — but NEVER during render.
+ *
+ * It has to be a global variable rather than an inline style because of WHEN the
+ * value is knowable. The width follows a preference in `localStorage`, which the
+ * server cannot read: any markup derived from it differs between the server's
+ * HTML and the client's hydration render, and React tears the tree down and
+ * regenerates it. Seeding this property from a tiny script in `<head>` moves the
+ * preference OUT of React's rendered output — the markup becomes identical on
+ * both sides, while the width is already correct on the very first paint.
+ *
+ * Consumers are expected to seed it before first paint; unseeded, the fallback
+ * in the class below paints the expanded width until this component's effect
+ * catches up, which is the flash the seed exists to remove.
+ */
+export const NAVIGATION_SIDEBAR_WIDTH_VAR = '--of-navigation-sidebar-width'
+/**
+ * The rail as a query container, so the parts of the sidebar that follow its
+ * collapsed state can read that state off the rail's own width — currently the
+ * collapse chevron's direction, in `navigation-sidebar-toggle.tsx`.
+ *
+ * There is no second source of truth for "is it collapsed", and that is the
+ * point: the width already has to be correct on the first paint and at every
+ * breakpoint, so anything derived from it is too — the seeded desktop
+ * preference, the tablet rail and an overlay opened on tablet all come along for
+ * free. A parallel copy would have to be kept in step with each of the three
+ * separately, and the custom property that used to live here fell out of step on
+ * the last one: it could not see the tablet rail, so that case got its own media
+ * query, which in turn could not see an open overlay and pointed the chevron
+ * backwards under it.
+ *
+ * Queried as `@[140px]/of-nav-sidebar:` — 140px is the midpoint between the 56px
+ * rail and the 224px expanded sidebar, so the width only crosses it mid-toggle.
+ * Container queries are min-width, so a follower styles its COLLAPSED look as the
+ * default and lets the query take it back. Written out literally at each use
+ * rather than interpolated from a constant: Tailwind scans source text, and a
+ * class it cannot see spelled out is a class it never generates.
+ */
+const SIDEBAR_CONTAINER = '@container/of-nav-sidebar'
+/**
+ * Where the sidebar sits and how wide it is, per breakpoint — as literal classes,
+ * because this cannot be decided in JavaScript in time.
+ *
+ * `useMdUp`/`useLgUp` answer `undefined` until an effect has run, so `isTablet`
+ * is false on the first render — the SERVER's render included. A tablet
+ * therefore received the desktop branch in its HTML (`relative`, `width:224px`,
+ * an inline style no class could outrank) and only snapped to the 56px rail once
+ * hydration and an effect had both completed. That is the wide sidebar that
+ * flashed on every load, and no amount of JS could fix it: the server has no
+ * viewport to consult, so the answer has to be deferred to the one consumer that
+ * always knows — the browser's own media evaluation.
+ *
+ * The state that a viewport CANNOT determine still lives outside the render: the
+ * persisted desktop preference reaches the `lg:` rule through
+ * {@link NAVIGATION_SIDEBAR_WIDTH_VAR}. An inline width would be simpler than a
+ * custom property, but it would also override the tablet rail on the very first
+ * paint, which is the bug being fixed.
+ *
+ * The tablet WIDTH is deliberately not here — see {@link SIDEBAR_TABLET_WIDTH}.
+ *
+ * Widths are `w-14`/`w-56` — the class equivalents of `MINIMIZED_WIDTH` and
+ * `EXPANDED_WIDTH`, as is the `14rem` fallback below. Keep them in step; a class
+ * string cannot interpolate a constant.
+ */
+const SIDEBAR_GEOMETRY_CLASSES = [
+  // Tablet: float over the content, anchored to the layout row (`absolute`
+  // within AppLayout's `relative` row) — NOT the viewport — so an optional
+  // `topBar` above the row is not overlapped. With no topBar the row spans the
+  // full viewport, so this is visually identical to a viewport-fixed sidebar.
+  'md:absolute md:inset-y-0 md:left-0 md:z-[45]',
+  // Desktop: back in the flex flow, width from the persisted preference. The
+  // fallback IS the default, so the property needs no global declaration and an
+  // unseeded consumer gets the full sidebar rather than a rail with no labels.
+  'lg:relative lg:inset-auto lg:z-auto lg:h-full lg:w-[var(--of-navigation-sidebar-width,14rem)]',
+].join(' ')
+/**
+ * The tablet width, as ONE `md:` class rather than a rail plus an override.
+ *
+ * Tablet is a 56px rail by design and only widens for an overlay the user has
+ * opened — state no viewport can imply, so it has to come from JS. Written as
+ * `md:w-14` + `max-lg:w-56` the two rules both match between md and lg at equal
+ * specificity, and Tailwind emits the `max-lg` block BEFORE the `md` one, so
+ * source order hands the tablet straight back to the rail. Picking one class
+ * removes the contest instead of trying to win it — and keeps the `!important`
+ * that winning it would need out of the tree.
+ *
+ * `lg:` still governs desktop either way: it is emitted after `md:`, so an
+ * overlay left open while the window widens does not leak into the desktop width.
+ */
+const SIDEBAR_TABLET_WIDTH = { rail: 'md:w-14', overlay: 'md:w-56' } as const
 /** A click the browser will resolve itself — new tab, new window, middle button. */
 const isModifiedClick = (event?: React.MouseEvent): boolean =>
   !!event && (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || event.button !== 0)
@@ -47,7 +144,22 @@ export function NavigationSidebar({ config, disabled = false }: NavigationSideba
     if (isTablet) setTabletMinimized(true)
   }, [isTablet])
-  const minimized = isTablet ? tabletMinimized : desktopMinimized
+  // `useLocalStorage` reads the store SYNCHRONOUSLY in its initializer, so on the
+  // hydration render it already knows a preference the server could not. Anything
+  // derived from it — labels, `aria-hidden`, the chevron, the placeholder rows —
+  // then differs from the server's HTML, and React throws out the whole tree and
+  // regenerates it. So until hydration is done, this renders the server's answer
+  // and nothing else.
+  //
+  // That costs nothing visually. The width is already correct at that point (it
+  // comes from the seeded CSS var, not from here), and at the minimized width
+  // every label is a `flex-1` in a rail with no room to give — zero-wide whatever
+  // this says. What flips on the next commit is opacity and margin on boxes that
+  // were never visible.
+  const [hydrated, setHydrated] = useState(false)
+  useEffect(() => setHydrated(true), [])
+  const minimized = hydrated ? (isTablet ? tabletMinimized : desktopMinimized) : (config.minimized ?? false)
   // Enable transitions only after the correct width is painted
   const [transitionsEnabled, setTransitionsEnabled] = useState(false)
@@ -147,11 +259,35 @@ export function NavigationSidebar({ config, disabled = false }: NavigationSideba
     secondaryItems: config.items.filter(item => item.section === 'secondary'),
   }), [config.items])
+  // Placeholder rows while the host cannot know its entries yet — see
+  // `NavigationSidebarConfig.loading`. Only the ROWS are stood in for: the header,
+  // the collapse toggle, the widths and the tablet overlay all behave exactly as
+  // when loaded, so this is the loaded rail with unknown contents rather than a
+  // separate skeleton sidebar to keep in sync.
+  const loadingRows = useMemo(() => {
+    if (!config.loading) return null
+    const primary = config.loadingRows?.primary ?? 7
+    const secondary = config.loadingRows?.secondary ?? 2
+    return {
+      primary: Array.from({ length: Math.max(0, primary) }, (_, i) => `primary-${i}`),
+      secondary: Array.from({ length: Math.max(0, secondary) }, (_, i) => `secondary-${i}`),
+    }
+  }, [config.loading, config.loadingRows?.primary, config.loadingRows?.secondary])
   const sidebarWidth = useMemo(
     () => (minimized ? `${MINIMIZED_WIDTH}px` : `${EXPANDED_WIDTH}px`),
     [minimized],
   )
+  // Published to CSS from an EFFECT, never from render. Before hydration the
+  // width belongs to whatever seeded `NAVIGATION_SIDEBAR_WIDTH_VAR` in `<head>`
+  // — put it in the markup instead and it becomes part of what React hydrates,
+  // which is precisely what cannot agree across the server boundary. Afterwards
+  // this is what a toggle moves.
+  useIsomorphicLayoutEffect(() => {
+    document.documentElement.style.setProperty(NAVIGATION_SIDEBAR_WIDTH_VAR, sidebarWidth)
+  }, [sidebarWidth])
   // There used to be an `isHydrated` gate here — `isMdUp !== undefined && ...`
   // — meant to hold the sidebar's contents back until the media queries
   // resolved. It could never be false: the `?? false` above had already
@@ -159,7 +295,7 @@ export function NavigationSidebar({ config, disabled = false }: NavigationSideba
   // because repairing it would be the regression: the contents are server-
   // rendered today, and gating them behind a client-only media query would
   // trade a first paint of the real navigation for an empty rail.
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     if (!transitionsEnabled) {
       const id = requestAnimationFrame(() => {
         setTransitionsEnabled(true)
@@ -183,61 +319,68 @@ export function NavigationSidebar({ config, disabled = false }: NavigationSideba
       />
       {/* Flex-flow placeholder — reserves the collapsed 56px slot on tablet so
-          the main content keeps its position while the sidebar floats above it */}
-      {isTablet && (
-        <div
-          className="h-full hidden md:block flex-shrink-0"
-          style={{ width: `${MINIMIZED_WIDTH}px` }}
-          aria-hidden="true"
-        />
-      )}
+          the main content keeps its position while the sidebar floats above it.
+          Rendered unconditionally and scoped by classes for the same reason the
+          geometry is: gated on `isTablet`, it was missing from the server HTML
+          and from the first client paint — exactly when the sidebar it
+          compensates for has already gone `absolute`. */}
+      <div className="h-full hidden md:block lg:hidden w-14 flex-shrink-0" aria-hidden="true" />
       <aside
         className={cn(
+          SIDEBAR_CONTAINER,
           "flex-col hidden md:flex flex-shrink-0",
           "bg-ods-card border-r border-ods-border",
-          // Tablet: float the sidebar over content. Anchored to the layout row
-          // (`absolute` within AppLayout's `relative` row) — NOT the viewport —
-          // so an optional `topBar` above the row is not overlapped. With no
-          // topBar the row spans the full viewport, so this is visually
-          // identical to a viewport-fixed sidebar.
-          isTablet ? "absolute inset-y-0 left-0 z-[45]" : "relative h-full",
+          SIDEBAR_GEOMETRY_CLASSES,
+          // The one width a viewport cannot imply: an overlay the user opened on
+          // tablet. Only ever true after a click, so the first paint always gets
+          // the rail.
+          isOverlayOpen ? SIDEBAR_TABLET_WIDTH.overlay : SIDEBAR_TABLET_WIDTH.rail,
           transitionsEnabled && "transition-[width] duration-300",
           config.className,
         )}
-        style={{ width: sidebarWidth }}
         aria-label="Main navigation sidebar"
       >
         <NavigationSidebarHeader minimized={minimized} />
         <div className="flex-1 flex flex-col justify-between py-4 overflow-y-auto">
-          <nav className="flex flex-col" aria-label="Primary navigation">
-            {primaryItems.map(item => (
-              <NavigationSidebarItemButton
-                key={item.id}
-                item={item}
-                isActive={item.id === committedActiveId}
-                isPending={item.id === pendingItemId}
-                showLabel={showLabel}
-                disabled={disabled}
-                onClick={handleItemClick}
-              />
-            ))}
+          {/* `aria-busy` on the nav, not the rows: the region is what is loading,
+              and each placeholder row is already `aria-hidden`. */}
+          <nav className="flex flex-col" aria-label="Primary navigation" aria-busy={!!loadingRows}>
+            {loadingRows
+              ? loadingRows.primary.map(key => (
+                  <NavigationSidebarItemSkeleton key={key} showLabel={showLabel} />
+                ))
+              : primaryItems.map(item => (
+                  <NavigationSidebarItemButton
+                    key={item.id}
+                    item={item}
+                    isActive={item.id === committedActiveId}
+                    isPending={item.id === pendingItemId}
+                    showLabel={showLabel}
+                    disabled={disabled}
+                    onClick={handleItemClick}
+                  />
+                ))}
           </nav>
-          {secondaryItems.length > 0 && (
-            <nav className="flex flex-col" aria-label="Secondary navigation">
-              {secondaryItems.map(item => (
-                <NavigationSidebarItemButton
-                  key={item.id}
-                  item={item}
-                  isActive={item.id === committedActiveId}
-                isPending={item.id === pendingItemId}
-                  showLabel={showLabel}
-                  disabled={disabled}
-                  onClick={handleItemClick}
-                />
-              ))}
+          {(loadingRows ? loadingRows.secondary.length > 0 : secondaryItems.length > 0) && (
+            <nav className="flex flex-col" aria-label="Secondary navigation" aria-busy={!!loadingRows}>
+              {loadingRows
+                ? loadingRows.secondary.map(key => (
+                    <NavigationSidebarItemSkeleton key={key} showLabel={showLabel} />
+                  ))
+                : secondaryItems.map(item => (
+                    <NavigationSidebarItemButton
+                      key={item.id}
+                      item={item}
+                      isActive={item.id === committedActiveId}
+                      isPending={item.id === pendingItemId}
+                      showLabel={showLabel}
+                      disabled={disabled}
+                      onClick={handleItemClick}
+                    />
+                  ))}
             </nav>
           )}
         </div>

package/src/components/ui/button/button-styles.ts CHANGED Viewed

@@ -32,6 +32,17 @@ export const buttonSurfaceClasses = {
 export const outlineBorderClasses =
   "border border-ods-border hover:border-ods-border-hover active:border-ods-border-active disabled:border-ods-border aria-disabled:border-ods-border"
+// Glyph scale for the split-layout button family: 16px below md, 24px from md.
+//
+// Shared because the same page-header action renders through EITHER of the two
+// split layouts depending on its shape — `SplitButton` for two click targets, and
+// `Button` + `splitIcon` for one with a decorative trailing glyph — and the two sit
+// side by side in the same row. They used to disagree: `SplitButton` carried this
+// responsive scale while the `Button` split slots re-declared a flat 20px, so a
+// "submenu" action's icons rendered 4px smaller than its neighbour's on desktop.
+// `Button`'s own flat `[&_svg]:h-5` stays as it is for ordinary (non-split) buttons.
+export const splitGlyphSizeClasses = "[&_svg]:h-4 [&_svg]:w-4 md:[&_svg]:h-6 md:[&_svg]:w-6"
 // Color of the vertical seam between the main and icon halves (split layouts).
 export const splitDividerColorClasses = {
   accent: "border-ods-accent-active",

package/src/components/ui/button/button.tsx CHANGED Viewed

@@ -6,7 +6,7 @@ import Link from "../../../embed-shims/next-link"
 import React from "react"
 import { cn } from "../../../utils/cn"
-import { buttonSurfaceClasses, outlineBorderClasses, splitDividerColorClasses } from "./button-styles"
+import { buttonSurfaceClasses, outlineBorderClasses, splitDividerColorClasses, splitGlyphSizeClasses } from "./button-styles"
 // Default layout: centered single content area, padding/gap on the button itself.
 const buttonVariants = cva(
@@ -104,14 +104,17 @@ const splitShellVariants = cva(
 )
 const splitSlotVariants = cva(
-  ["inline-flex items-center justify-center", "[&_svg]:shrink-0 [&_svg]:h-5 [&_svg]:w-5"],
+  // Glyph size lives per-size, not in the base: cva concatenates base + variant
+  // without tailwind-merge, so a base `[&_svg]:h-5` and a variant `[&_svg]:h-4`
+  // would both ship and the winner would come down to stylesheet order.
+  ["inline-flex items-center justify-center", "[&_svg]:shrink-0"],
   {
     variants: {
       slot: {
         main: "gap-[var(--spacing-system-xsf)]",
         icon: "border-l",
       },
-      size: { default: "", small: "[&_svg]:h-4 [&_svg]:w-4" },
+      size: { default: splitGlyphSizeClasses, small: "[&_svg]:h-4 [&_svg]:w-4" },
       variant: { accent: "", outline: "", transparent: "", destructive: "", warning: "" },
     },
     compoundVariants: [

package/src/components/ui/button/split-button.tsx CHANGED Viewed

@@ -5,7 +5,7 @@ import Link from "../../../embed-shims/next-link"
 import React from "react"
 import { cn } from "../../../utils/cn"
-import { buttonSurfaceClasses, splitDividerColorClasses } from "./button-styles"
+import { buttonSurfaceClasses, splitDividerColorClasses, splitGlyphSizeClasses } from "./button-styles"
 // Two independent interactive halves: each a `<button>` or `<a>`. The seam is
 // a 1px border on the left edge of the icon half, colored per variant. For a
@@ -29,7 +29,7 @@ const splitHalfVariants = cva(splitHalfBase, {
       warning: buttonSurfaceClasses.warning,
     },
     size: {
-      default: "h-10 md:h-12 px-[var(--spacing-system-m)] py-[var(--spacing-system-sf)] text-h3 [&_svg]:h-4 [&_svg]:w-4 md:[&_svg]:h-6 md:[&_svg]:w-6",
+      default: `h-10 md:h-12 px-[var(--spacing-system-m)] py-[var(--spacing-system-sf)] text-h3 ${splitGlyphSizeClasses}`,
       small: "h-6 md:h-8 px-[var(--spacing-system-xs)] text-h5 [&_svg]:h-3 [&_svg]:w-3 md:[&_svg]:h-4 md:[&_svg]:w-4",
     },
     side: { main: "", icon: "" },

package/src/components/ui/data-table/data-table-body.tsx CHANGED Viewed

@@ -10,6 +10,7 @@ import {
   DataTableSkeleton,
   ROW_HEIGHT_DESKTOP,
   ROW_HEIGHT_MOBILE,
+  ROW_SHELL_CLASSES,
 } from './data-table-skeleton'
 export interface DataTableBodyProps<T = any> {
@@ -133,13 +134,15 @@ export function DataTableBody<T = any>({
           >
             <div
               className={cn(
-                'hidden md:flex items-center gap-[var(--spacing-system-mf)] px-[var(--spacing-system-mf)] py-0',
+                'hidden md:flex py-0',
+                ROW_SHELL_CLASSES,
                 ROW_HEIGHT_DESKTOP,
               )}
             />
             <div
               className={cn(
-                'flex md:hidden gap-[var(--spacing-system-sf)] items-center justify-start px-[var(--spacing-system-sf)] py-0',
+                'flex md:hidden justify-start py-0',
+                ROW_SHELL_CLASSES,
                 ROW_HEIGHT_MOBILE,
               )}
             />

package/src/components/ui/data-table/data-table-column-filter.tsx CHANGED Viewed

@@ -62,34 +62,63 @@ export function DataTableColumnFilter({
     column.setFilterValue(undefined)
   }, [column])
+  // A filterable column whose choices have not arrived yet. Declaring the filter
+  // with no options is how a caller says "this column filters, ask me later" —
+  // the alternative, dropping `meta.filter` until the query resolves, takes the
+  // header cell with it: below `lg` only filterable cells are shown at all, so
+  // every header on a tablet vanished on reload and came back when the options
+  // landed. It also moved the labels, since the funnel is only drawn for a
+  // filterable column.
+  const isPending = options.length === 0
+  const trigger = (
+    <div
+      className={cn(
+        // Fixed 48px per design, same as the plain header cell next to it —
+        // NOT padding around the label. The two were drifting: 12px+20px+12px
+        // came out 44px here while the sibling was pinned to 48, so in a
+        // header mixing filterable and plain columns the labels sat on
+        // different centre lines and the filter's hit area was 4px short of
+        // the row it belongs to.
+        'group flex w-full items-center gap-[var(--spacing-system-xsf)] h-12 rounded-sm transition-colors duration-200 select-none',
+        alignJustify(align),
+        isPending ? 'cursor-default' : 'cursor-pointer',
+      )}
+      aria-label={`Filter by ${label}`}
+      aria-disabled={isPending || undefined}
+    >
+      <span
+        className={cn(
+          'text-h5 text-ods-text-secondary whitespace-nowrap transition-colors duration-200',
+          !isPending && 'group-hover:text-ods-text-primary',
+        )}
+      >
+        {label}
+      </span>
+      {/* Rendered while pending too, and that is the point: it holds its own
+          width, so the label does not shift sideways the moment the options
+          resolve. */}
+      <Filter02Icon
+        className={cn(
+          'w-4 h-4 transition-colors',
+          activeCount > 0 && 'text-ods-accent',
+          activeCount === 0 && 'text-ods-text-secondary',
+          activeCount === 0 && !isPending && 'group-hover:text-ods-text-primary',
+        )}
+      />
+    </div>
+  )
+  // Same box, no dropdown: opening onto an empty list would be a worse answer
+  // than not opening at all.
+  if (isPending) {
+    return <div className="block w-full">{trigger}</div>
+  }
   return (
     <FiltersDropdown
       className="!block w-full"
-      triggerElement={
-        <div
-          className={cn(
-            // Fixed 48px per design, same as the plain header cell next to it —
-            // NOT padding around the label. The two were drifting: 12px+20px+12px
-            // came out 44px here while the sibling was pinned to 48, so in a
-            // header mixing filterable and plain columns the labels sat on
-            // different centre lines and the filter's hit area was 4px short of
-            // the row it belongs to.
-            'group flex w-full items-center gap-[var(--spacing-system-xsf)] h-12 rounded-sm cursor-pointer transition-colors duration-200 select-none',
-            alignJustify(align),
-          )}
-          aria-label={`Filter by ${label}`}
-        >
-          <span className="text-h5 text-ods-text-secondary whitespace-nowrap transition-colors duration-200 group-hover:text-ods-text-primary">
-            {label}
-          </span>
-          <Filter02Icon
-            className={cn(
-              'w-4 h-4 transition-colors',
-              activeCount > 0 ? 'text-ods-accent' : 'text-ods-text-secondary group-hover:text-ods-text-primary',
-            )}
-          />
-        </div>
-      }
+      triggerElement={trigger}
       sections={sections}
       currentFilters={currentFilters}
       onApply={handleApply}