@flamingo-stack/openframe-frontend-core 0.0.543 → 0.0.544-1804.4776.1

package/src/components/ui/.modal-v2.md

@@ -5,12 +5,27 @@ Accessible, animated modal dialog component with compound sub-components for bui
 
 | Export | Description |
 |---|---|
-| `ModalV2` | Root modal container managing open/close state, backdrop, animations, scroll lock, and Escape key handling |
+| `ModalV2` | Root modal container managing open/close state, backdrop, animations, scroll lock, focus management, and Escape key handling. `size?: ModalV2Size` selects the panel width |
 | `ModalV2Header` | Header row with auto-injected close button (desktop only) via `ModalContext` |
 | `ModalV2Title` | Semantic `<h2>` styled with design system text tokens |
 | `ModalV2Content` | Scrollable body area with `overflow-y-auto` and flex-grow |
+| `ModalV2TwoColumn` | Two-column editor body — use INSTEAD OF `ModalV2Content` on a `size="wide"` modal. Props `{ left, right, className? }` |
 | `ModalV2Footer` | Horizontal action row for buttons or other controls |
 
+## Sizes
+
+`ModalV2Size` = `'default' | 'medium' | 'wide'` (default `'default'`). Every arm keeps a
+`calc(100vw-2rem)` arm so content can never stretch the panel past the viewport on narrow screens.
+
+| Size | Width | Use |
+|---|---|---|
+| `default` | `28rem` | Confirms and short prompts |
+| `medium` | `42rem` | Single-column forms |
+| `wide` | `1400px` | Two-column editors and master-detail panes. Also FIXES the desktop height (`md:h-[min(90dvh,100%-2rem)]`) so the panel doesn't jump as an entity hydrates in |
+
+Prefer the `size` prop over a call-site `max-w-*`. The size class is emitted before `className`,
+so an override still wins where one is genuinely needed.
+
 **Internal:**
 - `ModalContext` — React context passing `onClose` to descendants (used by `ModalV2Header`)
 - `ANIMATION_DURATION` — `200ms` constant kept in sync with Tailwind `duration-200` utilities; controls unmount delay so exit animations complete before DOM removal
@@ -54,9 +69,12 @@ function MyDialog() {
 
 ## Behavior Notes
 
-- **Scroll lock** — uses `@react-aria/overlays` `usePreventScroll` (ref-counted, restores prior `overflow` styles)
-- **Escape key** — document-level listener active only while `isOpen` is `true`
+- **Scroll lock** — `react-remove-scroll` (the same library Radix primitives use internally, so it composes with the lock a Select opened inside the modal adds on top). Rendered with `forwardProps` so no extra wrapper `<div>` lands in a flex/grid parent's flow
+- **Escape key** — document-level listener, but top-of-stack only: with stacked modals (a confirm above a form) one Escape closes just the top one, and a nested Radix layer's `preventDefault`ed Escape closes only that layer
+- **Focus** — focus moves into the panel on open, is CONTAINED there while it is topmost (with bounded re-asserts for focus dropped by node removal), Tab cycles inside it, and focus returns to the opener on close. Portaled Radix layers (`[data-radix-popper-content-wrapper]`, `[role=listbox]`, `[role=menu]`) are exempt
 - **Backdrop click** — calls `onClose`
+- **Two-column scroll model** — below `lg` there is one column and the outer region scrolls (identical to a single-column modal on a phone); from `lg` up the outer region is `overflow-hidden` and each column scrolls independently
+- **Software keyboard** — the wrapper pads by `--of-keyboard-inset` rather than shrinking, since neither mobile shell shrinks the layout viewport when the IME opens
 - **Animations** — slide-up on mobile, zoom on desktop; `fill-mode-forwards` prevents opacity flash between animation end and unmount
 - **Close button** — rendered inside `ModalV2Header`, visible on `md:` breakpoint and above only
 

package/src/components/ui/modal-v2.tsx

@@ -12,11 +12,28 @@ const ANIMATION_DURATION = 200
 
 const ModalContext = React.createContext<{ onClose?: () => void }>({})
 
+/**
+ * Panel width, as a named variant rather than a per-call-site `max-w-*`.
+ * `medium` is the single-column form width; `wide` is the two-column editor
+ * width and pairs with `ModalV2TwoColumn`.
+ *
+ * Every arm keeps the `calc(100vw-2rem)` arm so content can never stretch the
+ * panel past the viewport (minus the `mx-4` margins) on narrow screens.
+ */
+export type ModalV2Size = "default" | "medium" | "wide"
+
+const MODAL_V2_SIZE_CLASSES: Record<ModalV2Size, string> = {
+  default: "max-w-[min(28rem,calc(100vw-2rem))]",
+  medium: "max-w-[min(42rem,calc(100vw-2rem))]",
+  wide: "max-w-[min(1400px,calc(100vw-2rem))]",
+}
+
 interface ModalProps {
   isOpen: boolean
   onClose: () => void
   children: React.ReactNode
   className?: string
+  size?: ModalV2Size
 }
 
 interface ModalContentProps {
@@ -39,6 +56,12 @@ interface ModalFooterProps {
   className?: string
 }
 
+interface ModalTwoColumnProps {
+  left: React.ReactNode
+  right: React.ReactNode
+  className?: string
+}
+
 // Topmost-modal stack: with stacked modals (confirm above a form) only the
 // TOP one may contain focus, or they fight each other.
 const modalStack: symbol[] = []
@@ -58,7 +81,7 @@ const isInPortaledLayer = (node: Node | null): boolean =>
   ) !== null
 
 const Modal = React.forwardRef<HTMLDivElement, ModalProps>(
-  ({ isOpen, onClose, children, className }, ref) => {
+  ({ isOpen, onClose, children, className, size = "default" }, ref) => {
     // Keep the modal mounted while the exit animation plays.
     const [isMounted, setIsMounted] = useState(isOpen)
     const panelRef = React.useRef<HTMLDivElement | null>(null)
@@ -247,11 +270,17 @@ const Modal = React.forwardRef<HTMLDivElement, ModalProps>(
           tabIndex={-1}
           data-state={state}
           className={cn(
-            // min() keeps the desktop cap at 28rem while never letting content
-            // stretch the panel past the viewport (minus the mx-4 margins) on
-            // narrow screens. A single base utility (not md:max-w-md) so consumer
+            // A single base utility per size (not md:max-w-*) so consumer
             // max-w-* overrides via className still win at every breakpoint.
-            "relative z-10 w-full min-w-0 max-w-[min(28rem,calc(100vw-2rem))] flex flex-col",
+            "relative z-10 w-full min-w-0 flex flex-col",
+            // The panel is a focus TARGET (tabIndex -1), not a control: focus
+            // moves here on open so the dialog owns the keyboard, and the UA
+            // then paints its default ring around the whole modal. Opening by
+            // click hides it via :focus-visible heuristics, but a modal opened
+            // from a URL on page load has no preceding pointer event, so the
+            // ring showed on every refresh. Fields inside keep their own rings.
+            "outline-none",
+            MODAL_V2_SIZE_CLASSES[size],
             "mx-4 mb-4 md:mb-0",
             // dvh, not vh: vh ignores a mobile browser's retracting URL bar, so
             // 90vh already overflowed behind Safari's toolbar. The `100%-2rem`
@@ -261,6 +290,11 @@ const Modal = React.forwardRef<HTMLDivElement, ModalProps>(
             // stay pinned, ModalV2Content scrolls. min() picks 90dvh on any
             // viewport over 320px tall, so desktop is untouched.
             "max-h-[min(90dvh,100%-2rem)]",
+            // `wide` also FIXES the desktop height rather than only capping it:
+            // its columns scroll independently, and a height that tracks
+            // content makes the panel jump as an entity hydrates in. Mobile
+            // keeps the bottom-sheet's content-sized height.
+            size === "wide" && "md:h-[min(90dvh,100%-2rem)]",
             "bg-ods-bg md:bg-ods-card",
             "border border-ods-border rounded-md shadow-xl",
             "p-[var(--spacing-system-xl)] gap-[var(--spacing-system-l)]",
@@ -297,6 +331,41 @@ const ModalContent = React.forwardRef<HTMLDivElement, ModalContentProps>(
 )
 ModalContent.displayName = "ModalV2Content"
 
+/**
+ * The two-column editor body. Use INSTEAD OF `ModalV2Content` (not inside it)
+ * on a `size="wide"` modal — it owns the same `flex-1 min-h-0` slot.
+ *
+ * Scroll model, which is the whole reason this is a component and not a pair
+ * of copy-pasted class strings: below `lg` there is ONE column and the outer
+ * region scrolls, so a phone behaves exactly like every single-column modal.
+ * From `lg` up the outer region is `overflow-hidden` and each column scrolls
+ * independently, so a long left column never drags the right one out of view.
+ */
+const ModalTwoColumn = React.forwardRef<HTMLDivElement, ModalTwoColumnProps>(
+  ({ left, right, className }, ref) => (
+    <div
+      ref={ref}
+      className={cn("flex-1 min-h-0 overflow-y-auto lg:overflow-hidden", className)}
+    >
+      {/* `lg:grid-rows-[minmax(0,1fr)]` is what makes the columns scroll: an
+          implicit `auto` row sizes to the TALLER column, so the columns had no
+          bounded height to scroll inside and the outer `overflow-hidden`
+          silently clipped them instead. minmax(0,…) also beats the default
+          `min-height:auto` on the row, which would otherwise refuse to shrink
+          below content height. */}
+      <div className="grid grid-cols-1 gap-[var(--spacing-system-xl)] lg:h-full lg:min-h-0 lg:grid-cols-2 lg:grid-rows-[minmax(0,1fr)]">
+        <div className="min-h-0 space-y-[var(--spacing-system-lf)] lg:overflow-y-auto lg:pr-[var(--spacing-system-sf)]">
+          {left}
+        </div>
+        <div className="min-h-0 space-y-[var(--spacing-system-lf)] lg:overflow-y-auto lg:pr-[var(--spacing-system-sf)]">
+          {right}
+        </div>
+      </div>
+    </div>
+  )
+)
+ModalTwoColumn.displayName = "ModalV2TwoColumn"
+
 const ModalHeader = React.forwardRef<HTMLDivElement, ModalHeaderProps>(
   ({ children, className }, ref) => {
     const { onClose } = React.useContext(ModalContext)
@@ -352,5 +421,6 @@ export {
   ModalContent as ModalV2Content,
   ModalFooter as ModalV2Footer,
   ModalHeader as ModalV2Header,
-  ModalTitle as ModalV2Title
+  ModalTitle as ModalV2Title,
+  ModalTwoColumn as ModalV2TwoColumn
 }

package/src/components/ui/modal.tsx

@@ -6,40 +6,18 @@ import { usePreventScroll } from "@react-aria/overlays"
 import { cn } from "../../utils/cn"
 
 /**
- * Modal width presets — the SSOT for admin modal sizing. Pick a preset via
- * `size` instead of stacking `max-w-*` className overrides per call site.
- *  - default: compact dialogs (confirmations, small forms)
- *  - wide:    two-column editor modals (interview / case study / release …)
+ * Sizing and the two-column editor layout moved to `ModalV2` (`size` prop +
+ * `ModalV2TwoColumn`), which is where the focus trap, Escape stacking and
+ * keyboard-inset handling already live. The class-string constants this file
+ * used to export were copied per call site and drifted; a component owns the
+ * scroll model instead. What remains here is the compact legacy dialog used by
+ * the confirm modals that have not moved yet.
  */
-export const MODAL_SIZE_CLASSES = {
-  default: 'max-w-md',
-  wide: 'max-w-[1400px]',
-} as const
-export type ModalSize = keyof typeof MODAL_SIZE_CLASSES
-
-/**
- * Two-column editor-modal layout SSOT (body wrapper → grid → column).
- * Every dual-column admin modal composes these three, so the shell can't
- * drift per entity:
- *
- *   <div className={TWO_COLUMN_MODAL_BODY_CLASS}>
- *     <div className={TWO_COLUMN_MODAL_GRID_CLASS}>
- *       <div className={TWO_COLUMN_MODAL_COLUMN_CLASS}>…left…</div>
- *       <div className={TWO_COLUMN_MODAL_COLUMN_CLASS}>…right…</div>
- *     </div>
- *   </div>
- */
-export const TWO_COLUMN_MODAL_BODY_CLASS = 'px-6 py-4 flex-1 min-h-0 flex flex-col max-h-[70vh]'
-export const TWO_COLUMN_MODAL_GRID_CLASS = 'grid grid-cols-1 lg:grid-cols-2 gap-8 flex-1 min-h-0'
-export const TWO_COLUMN_MODAL_COLUMN_CLASS = 'space-y-6 overflow-y-auto pr-4'
-
 interface ModalProps {
   isOpen: boolean
   onClose: () => void
   children: React.ReactNode
   className?: string
-  /** Width preset from MODAL_SIZE_CLASSES. Default 'default' (max-w-md). */
-  size?: ModalSize
 }
 
 interface ModalContentProps {
@@ -64,7 +42,7 @@ interface ModalFooterProps {
 
 /** @deprecated Use ModalV2 from './modal-v2' instead. */
 const Modal = React.forwardRef<HTMLDivElement, ModalProps>(
-  ({ isOpen, onClose, children, className, size = 'default' }, ref) => {
+  ({ isOpen, onClose, children, className }, ref) => {
     // Shared ref-counted scroll lock (react-aria) — restores prior styles on
     // release instead of clobbering to 'unset'.
     usePreventScroll({ isDisabled: !isOpen })
@@ -95,8 +73,7 @@ const Modal = React.forwardRef<HTMLDivElement, ModalProps>(
         <div 
           ref={ref}
           className={cn(
-            "relative z-10 w-full mx-4 max-h-[90vh] flex flex-col overflow-hidden bg-ods-card border border-ods-border rounded-lg shadow-xl",
-            MODAL_SIZE_CLASSES[size],
+            "relative z-10 w-full mx-4 max-w-md max-h-[90vh] flex flex-col overflow-hidden bg-ods-card border border-ods-border rounded-lg shadow-xl",
             className
           )}
           role="dialog"