@flamingo-stack/openframe-frontend-core 0.0.524 → 0.0.525-1675.4425.1

package/src/components/ui/dropdown-button.tsx

@@ -3,90 +3,153 @@
 import React from 'react'
 import { cn } from '../../utils/cn'
 import { Chevron02DownIcon } from '../icons-v2-generated'
-import { ActionsMenuDropdown, type ActionsMenuItem } from './actions-menu'
+import { Button, type ButtonProps } from './button'
+import {
+  ActionsMenuDropdown,
+  type ActionsMenuGroup,
+  type ActionsMenuItem
+} from './actions-menu'
 
 export interface DropdownButtonProps {
   /** Button label rendered next to the chevron. */
-  label: string
+  label: React.ReactNode
   /** Optional leading icon rendered before the label. */
   icon?: React.ReactNode
-  /** Items shown in the dropdown. */
-  items: ActionsMenuItem[]
+  /**
+   * Items shown in the dropdown (single flat group). For grouped menus with
+   * separators pass `groups` instead — exactly one of the two is required.
+   */
+  items?: ActionsMenuItem[]
+  /** Grouped items (with optional separators). Takes precedence over `items`. */
+  groups?: ActionsMenuGroup[]
+  /**
+   * Render the trigger as a standard `Button` of this variant (`outline`,
+   * `accent`, …) instead of the default card-colored seam trigger. Use this
+   * when the dropdown sits in a row of ordinary buttons and must match them.
+   */
+  variant?: ButtonProps['variant']
+  /** Button size for the `variant` trigger. Ignored without `variant`. */
+  size?: ButtonProps['size']
+  /** Spinner state for the `variant` trigger. Ignored without `variant`. */
+  loading?: boolean
   disabled?: boolean
   className?: string
   ariaLabel?: string
   align?: 'start' | 'center' | 'end'
   side?: 'top' | 'right' | 'bottom' | 'left'
+  /**
+   * Forwarded to the dropdown content. The standard Radix dropdown→dialog
+   * recipe: pass `(e) => e.preventDefault()` when a menu item opens a modal,
+   * otherwise closing the menu refocuses its trigger AFTER the dialog has
+   * taken focus, yanking focus back OUT of the modal the action just opened.
+   */
+  onCloseAutoFocus?: (event: Event) => void
 }
 
 /**
- * A card-colored trigger button that opens a dropdown of actions. The button
- * has a visual seam between the label and the trailing chevron, but the
- * entire surface is a single click target. The wrapper lightens on hover and
- * while the dropdown is open; the chevron rotates 180° to point up when open.
+ * THE multi-action button — a labeled trigger with a chevron opening an
+ * `ActionsMenu`. One component, so the trigger styling, chevron, and menu
+ * chrome cannot drift between surfaces.
  *
- * Used standalone or via `PageActions` when a `PageActionButton` has
- * `dropdownItems` set.
+ * Two trigger looks:
+ * - default (no `variant`): the card-colored seam trigger — label and chevron
+ *   separated by a divider, whole surface one click target, chevron rotates
+ *   while open. Used standalone or via `PageActions` when a `PageActionButton`
+ *   has `dropdownItems` set.
+ * - `variant="outline"` (or any Button variant): a standard `Button` with the
+ *   chevron as its right icon, so the trigger matches sibling buttons in the
+ *   same row — including `loading` and `leftIcon` support.
+ *
+ * Item clicks close the menu (ActionsMenuDropdown's default; opt out per item
+ * with `closeOnSelect: false`).
  */
 export function DropdownButton({
   label,
   icon,
   items,
+  groups,
+  variant,
+  size = 'small-legacy',
+  loading = false,
   disabled,
   className,
   ariaLabel,
   align = 'end',
-  side = 'bottom'
+  side = 'bottom',
+  onCloseAutoFocus
 }: DropdownButtonProps) {
   const [open, setOpen] = React.useState(false)
 
   const handleOpenChange = React.useCallback(
     (next: boolean) => {
-      if (disabled) return
+      if (disabled || loading) return
       setOpen(next)
     },
-    [disabled]
+    [disabled, loading]
+  )
+
+  const resolvedAriaLabel =
+    ariaLabel || (typeof label === 'string' ? label : undefined)
+
+  const trigger = variant ? (
+    <Button
+      variant={variant}
+      size={size}
+      disabled={disabled}
+      loading={loading}
+      aria-label={resolvedAriaLabel}
+      leftIcon={icon}
+      rightIcon={
+        <Chevron02DownIcon
+          className={cn('h-4 w-4 transition-transform duration-fast', open && 'rotate-180')}
+        />
+      }
+      className={className}
+    >
+      {label}
+    </Button>
+  ) : (
+    <button
+      type="button"
+      disabled={disabled}
+      aria-label={resolvedAriaLabel}
+      onPointerDown={disabled ? (e) => e.preventDefault() : undefined}
+      className={cn(
+        'inline-flex h-12 items-stretch rounded-md border border-ods-border overflow-hidden transition-colors',
+        'text-ods-text-primary',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ods-focus',
+        open ? 'bg-ods-bg-hover' : 'bg-ods-card',
+        !disabled && !open && 'hover:bg-ods-bg-hover',
+        disabled && 'opacity-50 cursor-not-allowed',
+        className
+      )}
+    >
+      <span className="flex items-center gap-[var(--spacing-system-xsf)] px-[var(--spacing-system-m)] py-[var(--spacing-system-sf)] text-h3">
+        {icon && (
+          <span className="flex items-center justify-center [&_svg]:w-6 [&_svg]:h-6">
+            {icon}
+          </span>
+        )}
+        <span className="whitespace-nowrap">{label}</span>
+      </span>
+      <span className="flex items-center justify-center border-l border-ods-border p-[var(--spacing-system-sf)] [&_svg]:w-6 [&_svg]:h-6">
+        <Chevron02DownIcon
+          className={cn('transition-transform duration-fast', open && 'rotate-180')}
+        />
+      </span>
+    </button>
   )
 
   return (
     <ActionsMenuDropdown
-      groups={[{ items }]}
+      groups={groups ?? [{ items: items ?? [] }]}
       open={open}
       onOpenChange={handleOpenChange}
       align={align}
       side={side}
-      triggerAriaLabel={ariaLabel || label}
-      customTrigger={
-        <button
-          type="button"
-          disabled={disabled}
-          aria-label={ariaLabel || label}
-          onPointerDown={disabled ? (e) => e.preventDefault() : undefined}
-          className={cn(
-            'inline-flex h-12 items-stretch rounded-md border border-ods-border overflow-hidden transition-colors',
-            'text-ods-text-primary',
-            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ods-focus',
-            open ? 'bg-ods-bg-hover' : 'bg-ods-card',
-            !disabled && !open && 'hover:bg-ods-bg-hover',
-            disabled && 'opacity-50 cursor-not-allowed',
-            className
-          )}
-        >
-          <span className="flex items-center gap-[var(--spacing-system-xsf)] px-[var(--spacing-system-m)] py-[var(--spacing-system-sf)] text-h3">
-            {icon && (
-              <span className="flex items-center justify-center [&_svg]:w-6 [&_svg]:h-6">
-                {icon}
-              </span>
-            )}
-            <span className="whitespace-nowrap">{label}</span>
-          </span>
-          <span className="flex items-center justify-center border-l border-ods-border p-[var(--spacing-system-sf)] [&_svg]:w-6 [&_svg]:h-6">
-            <Chevron02DownIcon
-              className={cn('transition-transform duration-fast', open && 'rotate-180')}
-            />
-          </span>
-        </button>
-      }
+      onCloseAutoFocus={onCloseAutoFocus}
+      triggerAriaLabel={resolvedAriaLabel}
+      customTrigger={trigger}
     />
   )
 }

package/src/components/ui/field.tsx

@@ -0,0 +1,74 @@
+'use client'
+
+import * as React from 'react'
+import { Label } from './label'
+import { InfoHint } from './info-hint'
+
+/**
+ * Accessibility props handed to the control by the `Field` render-prop.
+ * Spread them onto the input/select/textarea so the label, required flag and
+ * error message are all announced.
+ */
+export interface FieldRenderProps {
+  id: string
+  'aria-required'?: boolean
+  'aria-invalid'?: boolean
+  'aria-describedby'?: string
+}
+
+export interface FieldProps {
+  label: string
+  /** Definition shown in a hover `InfoHint` next to the label. */
+  hint?: React.ReactNode
+  required?: boolean
+  children: React.ReactNode | ((props: FieldRenderProps) => React.ReactNode)
+  error?: string | null
+}
+
+/**
+ * One form field: label, optional hint, control, optional error.
+ *
+ * Labels are a single line (hints live in the hover InfoHint icon, never in
+ * flow), so cells top-align naturally and controls land on the same baseline.
+ * Do NOT reintroduce `h-full` + `mt-auto` here: in a grid row it stretches the
+ * cell to the tallest sibling and shoves this cell's control down to align with
+ * the bottom of the sibling's ERROR text, detaching it from its own label.
+ *
+ * The label is tied to its control with a generated id, so clicking the label
+ * focuses the input and assistive tech announces the field by name. ALWAYS use
+ * the render-prop form — `{(f) => <Input {...f} />}` — and spread what it gives
+ * you onto the control. Passing a plain node leaves `htmlFor` pointing at an id
+ * that exists on no element, which is worse than no association at all: the
+ * label looks wired up and announces nothing.
+ */
+export function Field({ label, hint, required, children, error }: FieldProps) {
+  const controlId = React.useId()
+  const errorId = `${controlId}-error`
+  const renderProps: FieldRenderProps = {
+    id: controlId,
+    // A bare `*` draws a star and tells assistive tech nothing.
+    ...(required ? { 'aria-required': true } : {}),
+    ...(error ? { 'aria-invalid': true, 'aria-describedby': errorId } : {}),
+  }
+  return (
+    <div className="flex flex-col gap-[var(--spacing-system-xxs)]">
+      <div className="flex items-center gap-1.5">
+        <Label htmlFor={controlId} variant="small" className="text-ods-text-primary">
+          {label}
+          {required && ' *'}
+        </Label>
+        {hint && <InfoHint label={label}>{hint}</InfoHint>}
+      </div>
+      <div className="pt-[var(--spacing-system-xxs)]">
+        {typeof children === 'function' ? children(renderProps) : children}
+      </div>
+      {/* `role="alert"` + the id the control points at: a validation message
+          rendered as plain text is never announced. */}
+      {error && (
+        <p id={errorId} role="alert" className="text-h6 text-ods-error">
+          {error}
+        </p>
+      )}
+    </div>
+  )
+}

package/src/components/ui/index.ts

@@ -11,8 +11,11 @@ export * from './checkbox-block'
 export * from './checkbox-with-description'
 export * from './date-picker'
 export * from './duration-input'
+export * from './field'
 export * from './field-wrapper'
 export * from './honeypot-field'
+export * from './info-hint'
+export * from './json-detail-list'
 export * from './info-card'
 export * from './info-row'
 export * from './info-section'
@@ -39,6 +42,7 @@ export * from './dialog'
 export * from './image-gallery-modal'
 export * from './modal'
 export * from './modal-v2'
+export * from './modal-guarded-close'
 export * from './separator'
 export * from './sheet'
 export * from './drawer'

package/src/components/ui/info-hint.tsx

@@ -0,0 +1,74 @@
+'use client'
+
+import * as React from 'react'
+import { Info } from 'lucide-react'
+import { Button } from './button'
+import { FloatingTooltip } from './floating-tooltip'
+import { cn } from '../../utils/cn'
+
+export interface InfoHintProps {
+  children: React.ReactNode
+  /** What this hint is ABOUT — 15 buttons all named "More information" name nothing. */
+  label?: string
+  side?: 'top' | 'right' | 'bottom' | 'left'
+  className?: string
+}
+
+/**
+ * The "what does this mean?" affordance — an ⓘ icon that reveals a definition
+ * on hover.
+ *
+ * Config-heavy screens carry vocabulary that is obvious to whoever built the
+ * feature and opaque to everyone else — `judged`, `deterministic`, `observe`,
+ * `error`. A term nobody can define is a term nobody configures correctly, so
+ * every one of them gets a hint rather than a wiki page somebody has to go find.
+ *
+ * This is a thin cap over `FloatingTooltip`, not a second tooltip: it fixes the
+ * icon, the trigger element and the sizing so every hint looks and behaves the
+ * same. All the hover/portal/placement behaviour is the shared component's.
+ */
+export function InfoHint({ children, label, side = 'top', className }: InfoHintProps) {
+  const describedById = React.useId()
+  return (
+    <span className={cn('inline-flex shrink-0 items-center', className)}>
+      <FloatingTooltip
+        content={children}
+        side={side}
+        as="span"
+        triggerClassName="inline-flex shrink-0 items-center"
+        className="max-w-[280px] text-h6"
+      >
+        {/*
+          `icon-inline` is a Button variant, not a className stack. The hint sits
+          inside a line of badges, so `icon-sm`'s 32px target would swamp a 10px
+          badge — and shrinking it at the call site is exactly the override the
+          house rule forbids.
+        */}
+        <Button
+          type="button"
+          variant="transparent"
+          size="icon-inline"
+          // A hint lives inside interactive rows (e.g. a role="checkbox" rule
+          // row): asking "what does this mean?" must never toggle the row it
+          // sits in.
+          onClick={(e) => e.stopPropagation()}
+          aria-label={label ? `About ${label}` : 'More information'}
+          aria-describedby={describedById}
+          className="text-ods-text-secondary hover:text-ods-text-primary"
+        >
+          <Info className="h-3.5 w-3.5 shrink-0" />
+        </Button>
+      </FloatingTooltip>
+      {/*
+        The tooltip opens on HOVER only — `FloatingTooltip` composes
+        `useHover`/`useDismiss`/`useRole` and no `useFocus`, so a keyboard user
+        tabbing here would otherwise reach a button that reveals nothing. This
+        visually-hidden copy is the same text, exposed via `aria-describedby`,
+        so assistive tech reads the definition without depending on hover.
+      */}
+      <span id={describedById} className="sr-only">
+        {children}
+      </span>
+    </span>
+  )
+}

package/src/components/ui/json-detail-list.tsx

@@ -0,0 +1,112 @@
+'use client'
+
+import * as React from 'react'
+import { formatRelativeTime } from '../../utils/date-utils'
+import { cn } from '../../utils/cn'
+
+/**
+ * THE generic JSON detail renderer — readable key/value prose for machine
+ * payloads whose field names are NOT guaranteed (evidence blobs, audit
+ * payloads, webhook bodies). No schema knowledge: keys are humanised,
+ * ISO-dates become relative times, nested objects indent, and anything
+ * unparseable falls back to raw. Use this instead of `<pre>{JSON.stringify}`
+ * or a per-shape bespoke renderer.
+ */
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/
+
+function humanizeKey(key: string): string {
+  const spaced = key
+    .replace(/[_-]+/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .trim()
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1)
+}
+
+function Value({ value, depth }: { value: unknown; depth: number }) {
+  if (value === null || value === undefined) {
+    return <span className="text-ods-text-secondary">—</span>
+  }
+  if (typeof value === 'string') {
+    if (ISO_DATE.test(value)) {
+      return (
+        <span title={value} className="text-ods-text-secondary">
+          {formatRelativeTime(value)}
+        </span>
+      )
+    }
+    return <span className="whitespace-pre-wrap text-ods-text-primary">{value}</span>
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return <span className="text-code text-ods-text-primary">{String(value)}</span>
+  }
+  if (Array.isArray(value)) {
+    if (value.every(v => typeof v === 'string' || typeof v === 'number')) {
+      return <span className="text-ods-text-primary">{value.join(', ')}</span>
+    }
+    return (
+      <div className="space-y-[var(--spacing-system-xxs)]">
+        {value.map((v, i) => (
+          <Value key={i} value={v} depth={depth + 1} />
+        ))}
+      </div>
+    )
+  }
+  if (typeof value === 'object' && depth < 3) {
+    return <JsonDetailList data={value} depth={depth + 1} />
+  }
+  return (
+    <pre className="whitespace-pre-wrap text-code text-ods-text-secondary">
+      {JSON.stringify(value, null, 2)}
+    </pre>
+  )
+}
+
+export interface JsonDetailListProps {
+  /** Object, array, JSON string, or any scalar — rendered faithfully either way. */
+  data: unknown
+  /** Internal nesting level — leave at the default from call sites. */
+  depth?: number
+}
+
+export function JsonDetailList({ data, depth = 0 }: JsonDetailListProps) {
+  const obj =
+    typeof data === 'string'
+      ? (() => {
+          try {
+            return JSON.parse(data) as unknown
+          } catch {
+            return null
+          }
+        })()
+      : data
+
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+    // Not an object — render whatever it is faithfully.
+    return typeof data === 'string' ? (
+      <p className="whitespace-pre-wrap text-h6 text-ods-text-primary">{data}</p>
+    ) : (
+      <pre className="whitespace-pre-wrap text-code text-ods-text-secondary">
+        {JSON.stringify(data, null, 2)}
+      </pre>
+    )
+  }
+
+  return (
+    <dl
+      className={cn(
+        'space-y-[var(--spacing-system-xsf)]',
+        depth > 0 && 'pl-[var(--spacing-system-sf)] border-l border-ods-border',
+      )}
+    >
+      {Object.entries(obj as Record<string, unknown>).map(([key, value]) => (
+        <div key={key}>
+          <dt className="text-h6 text-ods-text-secondary">{humanizeKey(key)}</dt>
+          <dd className="text-h6">
+            <Value value={value} depth={depth} />
+          </dd>
+        </div>
+      ))}
+    </dl>
+  )
+}

package/src/components/ui/modal-guarded-close.tsx

@@ -0,0 +1,133 @@
+'use client'
+
+import * as React from 'react'
+import { cn } from '../../utils/cn'
+import { Button } from './button'
+import {
+  ModalV2,
+  ModalV2Content,
+  ModalV2Footer,
+  ModalV2Header,
+  ModalV2Title
+} from './modal-v2'
+
+/**
+ * The unified dirty-state contract for modals: a promise-based house confirm
+ * (`useConfirm`), a close guard that asks before discarding unsaved edits
+ * (`useGuardedClose`), and the standing "Unsaved changes" footer chip
+ * (`UnsavedChangesChip`). Form-modal shells compose these three instead of
+ * reimplementing the affordance — closing a dirty form must never silently
+ * discard the edits, and the chip is the standing signal that edits exist.
+ */
+
+/**
+ * State-driven confirm dialog using `ModalV2` — the house replacement for
+ * `window.confirm`. `ask(title, body)` returns a `Promise<boolean>`; the
+ * consumer awaits the user's choice and then proceeds. The returned `dialog`
+ * element MUST be rendered in the host's JSX (inside the host modal is fine —
+ * `ModalV2` stacks).
+ *
+ * Concurrency: a second `ask` while a dialog is already open resolves `false`
+ * immediately — without the guard the second `setPending` would overwrite the
+ * first entry and the first Promise would hang forever. The ref-based
+ * in-flight flag also covers two synchronous `ask()` calls in the same render
+ * tick, which `useState` alone races.
+ */
+export function useConfirm() {
+  const [open, setOpen] = React.useState(false)
+  const [pending, setPending] = React.useState<{
+    title: string
+    body: string
+    resolve: (ok: boolean) => void
+  } | null>(null)
+  const askingRef = React.useRef(false)
+  const ask = React.useCallback((title: string, body: string) => {
+    return new Promise<boolean>((resolve) => {
+      if (askingRef.current) {
+        resolve(false)
+        return
+      }
+      askingRef.current = true
+      setPending({ title, body, resolve })
+      setOpen(true)
+    })
+  }, [])
+  const decide = React.useCallback(
+    (ok: boolean) => {
+      askingRef.current = false
+      setOpen(false)
+      pending?.resolve(ok)
+      setPending(null)
+    },
+    [pending]
+  )
+
+  const dialog = pending ? (
+    <ModalV2 isOpen={open} onClose={() => decide(false)}>
+      <ModalV2Header>
+        <ModalV2Title>{pending.title}</ModalV2Title>
+      </ModalV2Header>
+      <ModalV2Content>
+        <p className="text-h6 text-ods-text-secondary">{pending.body}</p>
+      </ModalV2Content>
+      <ModalV2Footer>
+        <Button variant="outline" onClick={() => decide(false)}>
+          Cancel
+        </Button>
+        <Button variant="destructive" onClick={() => decide(true)}>
+          Confirm
+        </Button>
+      </ModalV2Footer>
+    </ModalV2>
+  ) : null
+
+  return { ask, dialog }
+}
+
+export interface UseGuardedCloseOptions {
+  /** Confirm dialog title. */
+  title?: string
+  /** Confirm dialog body. */
+  body?: string
+}
+
+/**
+ * Close guard for dirty forms: `guardedClose` runs `onClose` directly while
+ * clean, and asks the house confirm first once `dirty` — wire it to the
+ * modal's `onClose` AND the Cancel button so every dismissal path is guarded.
+ * Render the returned `dialog` in the host's JSX.
+ */
+export function useGuardedClose(
+  dirty: boolean,
+  onClose: () => void,
+  {
+    title = 'Discard unsaved changes?',
+    body = 'Your edits have not been saved. Close and discard them?'
+  }: UseGuardedCloseOptions = {}
+) {
+  const { ask, dialog } = useConfirm()
+  const guardedClose = React.useCallback(async () => {
+    if (dirty && !(await ask(title, body))) return
+    onClose()
+  }, [dirty, ask, title, body, onClose])
+  return { guardedClose, dialog }
+}
+
+export interface UnsavedChangesChipProps {
+  /** Names WHAT is dirty (hover tooltip) — turns "why is this dirty?!" into a hover. */
+  detail?: string
+  className?: string
+}
+
+/** The standing "Unsaved changes" signal for a dirty modal's footer. */
+export function UnsavedChangesChip({ detail, className }: UnsavedChangesChipProps) {
+  return (
+    <span
+      className={cn('text-h6 text-ods-warning', className)}
+      role="status"
+      title={detail}
+    >
+      Unsaved changes
+    </span>
+  )
+}

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

@@ -2,7 +2,7 @@
 
 import * as React from "react"
 import { useEffect, useState } from "react"
-import { usePreventScroll } from "@react-aria/overlays"
+import { RemoveScroll } from "react-remove-scroll"
 import { XmarkIcon } from "../icons-v2-generated"
 import { cn } from "../../utils/cn"
 
@@ -142,14 +142,19 @@ const Modal = React.forwardRef<HTMLDivElement, ModalProps>(
       return () => clearTimeout(timeout)
     }, [isOpen])
 
-    // Shared ref-counted scroll lock (react-aria) — restores prior styles on
-    // release instead of clobbering to 'unset'.
-    usePreventScroll({ isDisabled: !isOpen })
+    // Scroll lock via the SAME library Radix primitives use internally
+    // (react-remove-scroll is ref-counted and composes with itself). The
+    // previous react-aria lock FOUGHT the lock a Radix Select opened inside
+    // the modal added on top — body jumped and the page behind went black
+    // while the select was open.
 
     // Escape key (document-level: top-of-stack semantics for modals)
     useEffect(() => {
       const handleKeyDown = (event: KeyboardEvent) => {
-        if (event.key === 'Escape') {
+        // A nested Radix layer (Select, DropdownMenu) preventDefaults the
+        // Escape it consumes — without this check, closing a select inside
+        // the modal closed the WHOLE modal.
+        if (event.key === 'Escape' && !event.defaultPrevented) {
           onClose()
         }
       }
@@ -165,6 +170,7 @@ const Modal = React.forwardRef<HTMLDivElement, ModalProps>(
     const state = isOpen ? "open" : "closed"
 
     return (
+      <RemoveScroll enabled={isOpen} removeScrollBar={false}>
       <div className="fixed inset-0 z-[1300] flex items-end md:items-center justify-center">
         <div
           data-state={state}
@@ -218,6 +224,7 @@ const Modal = React.forwardRef<HTMLDivElement, ModalProps>(
           </ModalContext.Provider>
         </div>
       </div>
+      </RemoveScroll>
     )
   }
 )