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

package/src/components/ui/data-table/data-table-header.tsx

@@ -2,7 +2,6 @@
 
 import type { ReactNode } from 'react'
 import { flexRender, type Header } from '@tanstack/react-table'
-import { useLgUp } from '../../../hooks/ui/use-media-query'
 import { cn } from '../../../utils/cn'
 import {
   Arrow01DownIcon,
@@ -11,7 +10,8 @@ import {
 } from '../../icons-v2-generated'
 import { DataTableColumnFilter } from './data-table-column-filter'
 import { useDataTableContext } from './data-table'
-import { alignJustify, getHideClasses } from './utils'
+import type { TailwindBreakpoint } from './types'
+import { alignJustify, BREAKPOINT_ORDER, getHideAtVisibility } from './utils'
 
 /** Single-column sort descriptor consumed by the header. */
 export interface DataTableSortState {
@@ -56,22 +56,21 @@ export function DataTableHeader({
   onSortChange,
 }: DataTableHeaderProps) {
   const table = useDataTableContext()
-  const isLgUp = useLgUp() ?? false
 
   // Flat header group (nested headers can be added later if needed).
   const headerGroup = table.getHeaderGroups()[0]
   if (!headerGroup) return null
 
-  // On tablet (md, below lg), only filterable columns render. If none exist,
-  // every HeaderCell returns null and the flex row collapses — which would
-  // break the absolutely-positioned rightSlot. Detect that case and render
-  // rightSlot in-flow instead.
-  const hasVisibleHeaderCell = headerGroup.headers.some(header => {
-    if (header.isPlaceholder) return false
-    if (isLgUp) return true
-    const meta = header.column.columnDef.meta
-    return Boolean(meta?.filter) || meta?.alwaysShowHeader === true
-  })
+  // Below lg only filterable columns (and explicit opt-ins) are visible — the same
+  // `keepsCellOnTablet` predicate the cells themselves use, so the two cannot drift.
+  // If a table has none, every cell is hidden there, the flex row has no height, and
+  // an absolutely-positioned rightSlot has nothing to sit in — so that slot goes
+  // in-flow instead. Derived from column META, never from the viewport: the same
+  // answer on the server, on the first client paint and after, which is the whole
+  // point of this file no longer reading a media query.
+  const hasTabletVisibleCell = headerGroup.headers.some(
+    header => !header.isPlaceholder && keepsCellOnTablet(header.column.columnDef.meta),
+  )
 
   return (
     <div
@@ -83,27 +82,26 @@ export function DataTableHeader({
     >
       <div className="flex items-stretch gap-[var(--spacing-system-mf)] px-[var(--spacing-system-mf)] relative">
         {headerGroup.headers.map(header => (
-          <HeaderCell
-            key={header.id}
-            header={header}
-            isLgUp={isLgUp}
-            sort={sort}
-            onSortChange={onSortChange}
-          />
+          <HeaderCell key={header.id} header={header} sort={sort} onSortChange={onSortChange} />
         ))}
-        {rightSlot &&
-          (hasVisibleHeaderCell ? (
-            <div className="absolute right-[var(--spacing-system-mf)] inset-y-0 flex items-center">
-              {rightSlot}
-            </div>
-          ) : (
-            // In-flow fallback: with no visible header cell this slot is the
-            // only thing giving the row height, so it carries the same fixed 48
-            // rather than padding out to 44.
-            <div className="ml-auto flex items-center h-12">
-              {rightSlot}
-            </div>
-          ))}
+        {rightSlot && (
+          <div
+            className={cn(
+              'flex items-center',
+              hasTabletVisibleCell
+                ? 'absolute right-[var(--spacing-system-mf)] inset-y-0'
+                : // No cell is visible below lg, so there this slot is the only thing
+                  // giving the row height and carries the same fixed 48 rather than
+                  // padding out to 44. From lg the cells are back and it returns to
+                  // the absolute placement. Safe as a `max-lg:` override: nothing
+                  // else in this string sets margin or height, so it competes only
+                  // with unprefixed defaults, never with a `md:`/`lg:` class.
+                  'max-lg:ml-auto max-lg:h-12 lg:absolute lg:right-[var(--spacing-system-mf)] lg:inset-y-0',
+            )}
+          >
+            {rightSlot}
+          </div>
+        )}
       </div>
     </div>
   )
@@ -115,19 +113,92 @@ type AnyHeader = Header<unknown, unknown>
 
 interface HeaderCellProps {
   header: AnyHeader
-  isLgUp: boolean
   sort: DataTableSortState | null
   onSortChange?: (columnId: string) => void
 }
 
-function HeaderCell({ header, isLgUp, sort, onSortChange }: HeaderCellProps) {
+type ColumnMeta = AnyHeader['column']['columnDef']['meta']
+
+/**
+ * Whether a column's header stays visible below `lg`, where the row is narrow
+ * enough that only the controls a user can act on earn their space: the filter
+ * dropdowns, plus anything explicitly opted in via `meta.alwaysShowHeader`.
+ */
+function keepsCellOnTablet(meta: ColumnMeta): boolean {
+  return Boolean(meta?.filter) || meta?.alwaysShowHeader === true
+}
+
+// Literal class maps — Tailwind's scanner needs the full class strings, which a
+// `${bp}:flex` template would not give it.
+const SHOW_FROM: Record<TailwindBreakpoint, string> = {
+  md: 'md:flex',
+  lg: 'lg:flex',
+  xl: 'xl:flex',
+  '2xl': '2xl:flex',
+}
+const HIDE_FROM: Record<TailwindBreakpoint, string> = {
+  md: 'md:hidden',
+  lg: 'lg:hidden',
+  xl: 'xl:hidden',
+  '2xl': '2xl:hidden',
+}
+/** Index of `lg` in the `[base, md, lg, xl, 2xl]` visibility array. */
+const LG_STEP = BREAKPOINT_ORDER.indexOf('lg') + 1
+
+/**
+ * Visibility classes for one header cell, as a plain min-width ladder.
+ *
+ * Two rules stack here: the column's own `hideAt`, and "below `lg` only the
+ * cells a user can act on". Layering them as classes does not work — a
+ * `max-lg:` override cannot cancel a `md:hidden` from `hideAt`, because Tailwind
+ * emits the `max-lg` block BEFORE the `md` one and equal-specificity rules are
+ * decided by source order. So both rules are resolved on booleans first, and only
+ * the result is turned into classes: at most one utility per breakpoint, each a
+ * `min-width` variant, no ordering left to chance.
+ */
+function getCellVisibilityClasses(
+  keepOnTablet: boolean,
+  hideAt: TailwindBreakpoint | TailwindBreakpoint[] | undefined,
+): string {
+  const fromHideAt = getHideAtVisibility(hideAt)
+  const visible = fromHideAt.map((shown, step) =>
+    keepOnTablet
+      ? // Reachable below lg whatever `hideAt` says; from lg it governs again.
+        step < LG_STEP || shown
+      : // Otherwise lg is a floor `hideAt` can raise but never lower.
+        shown && step >= LG_STEP,
+  )
+
+  const classes = [visible[0] ? 'flex' : 'hidden']
+  for (let step = 1; step < visible.length; step++) {
+    if (visible[step] === visible[step - 1]) continue
+    const breakpoint = BREAKPOINT_ORDER[step - 1]
+    classes.push(visible[step] ? SHOW_FROM[breakpoint] : HIDE_FROM[breakpoint])
+  }
+  return classes.join(' ')
+}
+
+/**
+ * One header cell.
+ *
+ * Everything responsive here is a CSS class, deliberately. This used to branch on
+ * `useLgUp() ?? false`, which answers `undefined` until an effect has run — so the
+ * FIRST render (server included) took the "not lg" path on every viewport: each
+ * non-filterable cell returned `null`, and the survivors rendered with no width and
+ * no alignment. One frame later the real values arrived, so the header visibly
+ * filled in and the columns snapped into place — while `DataTableRow` and
+ * `DataTableSkeleton`, which have always used plain `hideAt` classes, were correct
+ * from the start. Header and body therefore disagreed about which columns exist and
+ * how wide they are for exactly one frame, which is the flicker-and-jump on every
+ * table's load.
+ */
+function HeaderCell({ header, sort, onSortChange }: HeaderCellProps) {
   if (header.isPlaceholder) return null
 
   const column = header.column
   const meta = column.columnDef.meta
   const hasFilter = Boolean(meta?.filter)
-  // Tablet visibility: filterable columns and explicit opt-ins stay rendered.
-  const keepOnTablet = hasFilter || meta?.alwaysShowHeader === true
+  const keepOnTablet = keepsCellOnTablet(meta)
   const align = meta?.align ?? 'left'
   // Sort is opt-in via `meta.sortable`. Direction is fully consumer-driven via
   // the `sort` prop; we do not consult TanStack's sort APIs here.
@@ -135,17 +206,33 @@ function HeaderCell({ header, isLgUp, sort, onSortChange }: HeaderCellProps) {
   const sortDir: false | 'asc' | 'desc' =
     sort?.id === column.id ? (sort.desc ? 'desc' : 'asc') : false
 
-  // Mobile (md, below lg): hide non-filter columns so only filters are accessible.
-  if (!isLgUp && !keepOnTablet) return null
-
   return (
     <div
       className={cn(
-        'flex items-stretch',
-        isLgUp && (meta?.width || 'flex-1 min-w-0'),
+        'items-stretch',
+        // Cells are hidden rather than dropped from the tree, so which columns
+        // exist never depends on when an effect ran.
+        getCellVisibilityClasses(keepOnTablet, meta?.hideAt),
+        // Width applies from lg only. Stated as "always, neutralized below lg"
+        // because `meta.width` is an opaque consumer string that cannot be
+        // prefixed. Only `keepOnTablet` cells need the override — the rest are
+        // hidden below lg anyway.
+        //
+        // `[&&]` doubles the class in the selector (`.cls.cls`, specificity 0-2-0),
+        // and it is load-bearing: consumers routinely write a RESPONSIVE width
+        // (`w-[80px] md:w-1/5` is the common shape), and between md and lg that
+        // `md:` rule and this `max-lg:` one both match. At equal specificity source
+        // order decides, and Tailwind emits the `max-lg` block BEFORE the `md` one
+        // — the same ordering documented for visibility above — so the tablet would
+        // keep a width the design drops there, leaving the cells spread across the
+        // row instead of packed beside their filters. An opaque consumer string
+        // cannot be outranked by ordering, so this wins on the cascade's other axis.
+        // Specificity rather than `!important`: it stays a normal declaration, so a
+        // consumer that genuinely needs a tablet width can still take it back with a
+        // more specific rule — `!important` could only be answered with another one.
+        meta?.width || 'flex-1 min-w-0',
+        keepOnTablet && 'max-lg:[&&]:w-auto max-lg:[&&]:flex-none max-lg:[&&]:basis-auto',
         meta?.headerClassName,
-        // Don't apply hide classes if column is filterable on tablet (keep filter accessible)
-        !(keepOnTablet && !isLgUp) && getHideClasses(meta?.hideAt),
       )}
     >
       {hasFilter ? (
@@ -162,7 +249,9 @@ function HeaderCell({ header, isLgUp, sort, onSortChange }: HeaderCellProps) {
             // Fixed 48px header height per design (20px label centered inside)
             // instead of the padding-driven 44px.
             'flex w-full items-center gap-[var(--spacing-system-xsf)] h-12 rounded-sm select-none transition-colors duration-200',
-            isLgUp && alignJustify(align),
+            // Same "always, neutralized below lg" shape as the width above.
+            alignJustify(align),
+            keepOnTablet && 'max-lg:justify-start',
             canSort && 'group cursor-pointer',
           )}
           onClick={canSort ? () => onSortChange?.(column.id) : undefined}

package/src/components/ui/data-table/data-table-row.tsx

@@ -4,7 +4,7 @@ import Link from '../../../embed-shims/next-link'
 import React, { memo, useCallback, useRef, type ReactNode } from 'react'
 import { flexRender, type Row } from '@tanstack/react-table'
 import { cn } from '../../../utils/cn'
-import { ROW_HEIGHT_DESKTOP } from './data-table-skeleton'
+import { ROW_HEIGHT_DESKTOP, ROW_SHELL_CLASSES } from './data-table-skeleton'
 import { alignJustify, getHideClasses } from './utils'
 
 export interface DataTableRowProps<T> {
@@ -106,7 +106,8 @@ function DataTableRowImpl<T>({
   const cells = (
     <div
       className={cn(
-        'flex items-center gap-[var(--spacing-system-mf)] px-[var(--spacing-system-mf)]',
+        'flex',
+        ROW_SHELL_CLASSES,
         compact
           ? 'py-[var(--spacing-system-xsf)]'
           : autoHeight

package/src/components/ui/data-table/data-table-skeleton.tsx

@@ -12,6 +12,19 @@ import { getHideClasses } from './utils'
 export const ROW_HEIGHT_DESKTOP = 'h-[66px] md:h-[78px]'
 export const ROW_HEIGHT_MOBILE = 'h-[66px]'
 
+/**
+ * The row shell's inset and column gap.
+ *
+ * Shared by the real row (`data-table-row`), the skeleton rows below and the
+ * pad rows in `data-table-body`, because a difference between them is a visible
+ * shift on load — and there WAS one: all three placeholders used
+ * `--spacing-system-sf` (12px) in their mobile variant while the real row uses
+ * `--spacing-system-mf` (16px) at every width, so a loading table sat 4px closer
+ * to the card edge than the loaded one and its content nudged over when data
+ * arrived. Kept as a constant rather than three copies so that cannot drift again.
+ */
+export const ROW_SHELL_CLASSES = 'items-center gap-[var(--spacing-system-mf)] px-[var(--spacing-system-mf)]'
+
 export interface DataTableSkeletonProps {
   rows?: number
   className?: string
@@ -39,7 +52,8 @@ export function DataTableSkeleton({
         >
           <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,
               rowClassName,
             )}
@@ -70,7 +84,8 @@ export function DataTableSkeleton({
           </div>
           <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,
               rowClassName,
             )}

package/src/components/ui/data-table/index.ts

@@ -50,7 +50,7 @@ export {
 
 export { useDataTableContext } from './data-table'
 export { useDataTable } from './use-data-table'
-export { ROW_HEIGHT_DESKTOP, ROW_HEIGHT_MOBILE } from './data-table-skeleton'
+export { ROW_HEIGHT_DESKTOP, ROW_HEIGHT_MOBILE, ROW_SHELL_CLASSES } from './data-table-skeleton'
 export { alignJustify, getHideClasses, multiSelectFilterFn } from './utils'
 
 export type { DataTableFilterOption, TailwindBreakpoint } from './types'

package/src/components/ui/data-table/utils.ts

@@ -1,6 +1,9 @@
 import type { FilterFn } from '@tanstack/react-table'
 import type { TailwindBreakpoint } from './types'
 
+/** Ascending breakpoint scale `hideAt` is expressed in. */
+export const BREAKPOINT_ORDER: TailwindBreakpoint[] = ['md', 'lg', 'xl', '2xl']
+
 /**
  * Generates Tailwind hide classes based on breakpoint configuration.
  *
@@ -14,18 +17,61 @@ export function getHideClasses(
   if (!hideAt) return ''
 
   const breakpoints = Array.isArray(hideAt) ? hideAt : [hideAt]
-  const order: TailwindBreakpoint[] = ['md', 'lg', 'xl', '2xl']
 
   if (breakpoints.length === 1) {
     return `hidden ${breakpoints[0]}:flex`
   }
 
-  const maxIdx = Math.max(...breakpoints.map(bp => order.indexOf(bp)))
+  const maxIdx = Math.max(...breakpoints.map(bp => BREAKPOINT_ORDER.indexOf(bp)))
   const hideClasses = breakpoints.map(bp => `${bp}:hidden`).join(' ')
-  const showBreakpoint = order[maxIdx + 1]
+  const showBreakpoint = BREAKPOINT_ORDER[maxIdx + 1]
   return showBreakpoint ? `${hideClasses} ${showBreakpoint}:flex` : hideClasses
 }
 
+/**
+ * The visibility `getHideClasses(hideAt)` actually produces, evaluated per
+ * breakpoint: `[base, md, lg, xl, 2xl]`.
+ *
+ * The header needs to *know* this rather than emit it, because its cells carry a
+ * second rule on top (only filterable columns show below `lg`) and the two cannot
+ * be layered as classes — Tailwind orders `max-*` media queries BEFORE `min-*`
+ * ones, so a `max-lg:` override loses to any `md:`/`lg:` class it is meant to
+ * cancel. Combining the two rules here, on plain booleans, sidesteps that
+ * entirely: the header emits one unambiguous min-width ladder.
+ *
+ * Must stay in step with `getHideClasses` — the body rows and the skeleton apply
+ * those classes directly, and a disagreement is a header that shows a different
+ * set of columns than the rows beneath it.
+ */
+export function getHideAtVisibility(
+  hideAt?: TailwindBreakpoint | TailwindBreakpoint[],
+): boolean[] {
+  const steps = BREAKPOINT_ORDER.length + 1
+  if (!hideAt) return Array.from({ length: steps }, () => true)
+
+  const breakpoints = Array.isArray(hideAt) ? hideAt : [hideAt]
+
+  // Single breakpoint → `hidden <bp>:flex`: hidden below it, visible from it.
+  if (breakpoints.length === 1) {
+    const showFrom = BREAKPOINT_ORDER.indexOf(breakpoints[0]) + 1
+    return Array.from({ length: steps }, (_, step) => step >= showFrom)
+  }
+
+  // Array → one `<bp>:hidden` per entry plus a single `<next>:flex`, and no bare
+  // `hidden`, so the base step stays visible. Walk the scale upwards: later
+  // classes win, and the show breakpoint always sits past every hide one.
+  const maxIdx = Math.max(...breakpoints.map(bp => BREAKPOINT_ORDER.indexOf(bp)))
+  const showBreakpoint = BREAKPOINT_ORDER[maxIdx + 1]
+  const visible = [true]
+  for (const bp of BREAKPOINT_ORDER) {
+    let state = visible[visible.length - 1]
+    if (breakpoints.includes(bp)) state = false
+    if (bp === showBreakpoint) state = true
+    visible.push(state)
+  }
+  return visible
+}
+
 /** Maps `meta.align` to flex justify classes. */
 export function alignJustify(align?: 'left' | 'center' | 'right'): string {
   switch (align) {

package/src/hooks/ui/index.ts

@@ -7,6 +7,7 @@ export * from './use-header-height'
 export * from './use-horizontal-scrollbar'
 export * from './use-image-edge-color'
 export * from './use-is-truncated'
+export * from './use-isomorphic-layout-effect'
 export * from './use-local-storage'
 export * from './use-marquee-engine'
 export * from './use-media-query'

package/src/hooks/ui/use-isomorphic-layout-effect.ts

@@ -0,0 +1,20 @@
+'use client'
+
+import { useEffect, useLayoutEffect } from 'react'
+
+/**
+ * `useLayoutEffect` in the browser, `useEffect` on the server.
+ *
+ * `useLayoutEffect` never runs during server rendering — React cannot measure or
+ * mutate a layout that has not been laid out — so calling it in a component that
+ * SSRs logs a warning on every render pass. Client components still render on the
+ * server in Next.js, so `'use client'` alone does not avoid it.
+ *
+ * Use this wherever the effect writes something the FIRST paint depends on (a CSS
+ * custom property, a scroll position, a measured size). A plain `useEffect` there
+ * runs after paint, which shows one frame of the pre-effect value; a plain
+ * `useLayoutEffect` gets the timing right and pays for it with the warning. This
+ * gets both: paint-blocking where there is a paint, a no-op where there is not.
+ */
+export const useIsomorphicLayoutEffect =
+  typeof window !== 'undefined' ? useLayoutEffect : useEffect

package/src/types/navigation.ts

@@ -92,6 +92,27 @@ 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