@viasat/beam-react 2.42.0 → 2.43.0

package/lib/wip/Panel/Panel.types.d.ts

@@ -1,6 +1,7 @@
 import { ComponentPropsWithoutRef, RefObject } from 'react';
+import { BoxBackgroundColor } from '@viasat/beam-shared/components/box';
 import { PanelDividerColor, PanelDividerColors } from '@viasat/beam-shared/components/panel';
-export type { PanelDividerColor };
+export type { BoxBackgroundColor, PanelDividerColor };
 export { PanelDividerColors };
 export type PanelKind = 'inline' | 'overlay';
 export type ResolvedPanelOffset = {
@@ -9,7 +10,8 @@ export type ResolvedPanelOffset = {
 };
 export type PanelPosition = 'start' | 'end' | 'bottom';
 export type PanelModalType = 'nonModal' | 'isModal' | 'alert';
-export type PanelSize = 'sm' | 'md' | 'lg' | (string & {});
+export type PanelWidth = 'sm' | 'md' | 'lg' | (string & {});
+export type PanelHeight = string;
 export type PanelPadding = 'sm' | 'md';
 /**
  * Configuration for resizable panels.
@@ -36,12 +38,12 @@ interface BasePanelProps extends ComponentPropsWithoutRef<'aside'> {
     /**
      * Specify the content of the Panel
      */
-    children: React.ReactNode;
+    'children': React.ReactNode;
     /**
-     * Accessible name for the panel dialog when `Panel.Header.Heading` is not rendered.
-     * When a heading is present, `aria-labelledby` is set automatically.
-     * Provide this prop whenever you build a panel without `Panel.Header.Heading` to satisfy
-     * the WCAG requirement that every `role="dialog"` element has an accessible name.
+     * Accessible name for the panel dialog, required when `Panel.Header.Heading` is not rendered.
+     *
+     * With a heading present, `aria-labelledby` points to it automatically; without one, a
+     * `role="dialog"` needs this so screen readers can announce the Panel.
      *
      * @example
      * ```tsx
@@ -53,94 +55,101 @@ interface BasePanelProps extends ComponentPropsWithoutRef<'aside'> {
      * Controls the Panel's visibility. For inline panels, omitting this prop
      * renders the panel as always-visible (uncontrolled).
      */
-    open?: boolean;
+    'open'?: boolean;
     /**
      * Callback when Panel open state changes
      */
-    onOpenChange?: (open: boolean) => void;
+    'onOpenChange'?: (open: boolean) => void;
     /**
-     * Specify the size of the Panel.
+     * Width of a side Panel.
+     *
+     * Applies only when `position` is `"start"` or `"end"`. Has no effect on
+     * `position="bottom"` panels; use `height` for bottom panels instead.
      *
-     * **Named presets** (`'sm'`, `'md'`, `'lg'`) map to design tokens via the
-     * `.bm-panel--size-{sm|md|lg}` modifier class, which sets `--bm-comp-panel-size`.
+     * Use a named preset (`"sm"`, `"md"`, `"lg"`) or any valid CSS width value
+     * such as `"480px"` or `"30vw"`.
      *
-     * **Arbitrary strings** (e.g. `"480px"`, `"100dvh"`) are applied directly as
-     * `--bm-comp-panel-size` via inline style, giving full CSS flexibility.
+     * When omitted, the Panel uses the `"md"` width preset.
+     * @default 'md'
+     */
+    'width'?: PanelWidth;
+    /**
+     * Height of a bottom Panel.
      *
-     * For `position="bottom"`, the variable drives `height` instead of `width`
-     * (axis-awareness is in SCSS). Width is always `100%` for bottom panels.
+     * Applies only when `position="bottom"`. Has no effect on side panels
+     * (`position="start"` or `position="end"`); use `width` for those instead.
      *
-     * When omitted: non-bottom panels fall back to the `md` token; bottom panels
-     * fall back to `auto` (content-driven height, capped at `90dvh`). Prefer
-     * omitting `size` over `size="auto"` for bottom panels — explicitly passing
-     * `"auto"` sets `max-height: auto`, removing the `90dvh` viewport cap.
+     * Use any valid CSS height value, such as `"50dvh"` or `"480px"`.
+     * When omitted, the Panel sizes to its content and is capped at `90dvh`.
+     * Avoid `height="auto"` because it removes the `90dvh` viewport cap.
      */
-    size?: PanelSize;
+    'height'?: PanelHeight;
     /**
      * Specify the horizontal padding
      * sm=1rem, md=1.5rem
      * @default 'md'
      */
-    padding?: PanelPadding;
+    'padding'?: PanelPadding;
     /**
-     * Whether to show a dismissible button
+     * Specify whether to show the header close button
      * @default true
      */
-    dismissible?: boolean;
+    'dismissible'?: boolean;
     /**
-     * Label for the close button. Used as both the button's `aria-label` (screen reader name)
+     * Label for the close button. Used as both the button's `aria-label`
      * and the visible tooltip text. Provide a value that works in both contexts.
      * @default 'Close panel'
      */
-    closeButtonAriaLabel?: string;
+    'closeButtonAriaLabel'?: string;
     /**
-     * Whether to animate the panel on open/close.
-     * When `false`, floating-ui's transition timing collapses to zero, which clips
-     * the close animation. CSS `transition-duration` values in the stylesheet are
-     * unaffected — use `prefers-reduced-motion` in SCSS for motion-sensitive contexts.
+     * Specify whether to animate the Panel as it opens and closes
      * @default true
      */
-    isAnimated?: boolean;
+    'isAnimated'?: boolean;
     /**
-     * Whether to show an external divider between panel and page content
+     * Specify whether to show an external divider between panel and page content
      * @default true
      */
-    divider?: boolean;
+    'divider'?: boolean;
+    /**
+     * Specify the background color for all panel surfaces (Header, Body, Footer).
+     * A `backgroundColor` set on a section takes priority.
+     */
+    'backgroundColor'?: BoxBackgroundColor;
     /**
-     * Specify the border color of the external divider between panel and page content
+     * Specify the border color of the external divider between the panel and page content. Also sets
+     * the default divider color for the Header and Footer; a `dividerColor` set on a
+     * section takes priority.
      * @default '01'
      */
-    dividerColor?: PanelDividerColor;
+    'dividerColor'?: PanelDividerColor;
     /**
-     * Specify the position of the Panel.
-     * `'start'` | `'end'` | `'bottom'`
-     * @default 'end'
+     * Specify where the Panel is anchored within its container
+     * @default 'start'
      */
-    position?: PanelPosition;
+    'position'?: PanelPosition;
     /**
      * Enables user-resizing via a drag handle at the panel edge.
      * Pass `true` to use default min/max constraints, or an object to set custom
      * values in pixels.
+     *
      * Provide a `storageKey` in the config object to persist the panel's last-used size across sessions.
      * @default false
      */
-    resizable?: PanelResizable;
+    'resizable'?: PanelResizable;
     /**
-     * Called before the Panel closes due to a user interaction. Return `false` (or
-     * `Promise<false>`) to cancel the close — for example, when the panel contains
-     * a form with unsaved changes.
+     * Runs before a user-initiated close and acts as a gate: return `false` (or
+     * `Promise<false>`) to keep the Panel open, for example when a form has unsaved changes.
      *
-     * This callback is **not** invoked when the `open` prop is changed programmatically
-     * by the parent; it only fires for UI-triggered close events (close button, Escape
-     * key, or outside press).
-     *
-     * When `modalType="alert"`, `'escapeKey'` and `'outsidePress'` reasons are
-     * suppressed entirely — this callback will not be invoked for those reasons.
+     * It only fires for UI-triggered closes (close button, Escape, or outside press), never
+     * when the parent changes the `open` prop programmatically. Under `modalType="alert"`,
+     * the `'escapeKey'` and `'outsidePress'` reasons are suppressed, so it won't fire for
+     * those either.
      *
      * @example
      * ```tsx
-     * // Use a stateful confirmation dialog — avoid window.confirm (blocking, breaks iframes).
-     * // See the `onBeforeClose (Unsaved Changes Guard)` story for a full reference implementation.
+     * // Drive a confirmation dialog from state; avoid window.confirm (blocking, breaks iframes).
+     * // See the "Preserving and Guarding State" story for a full reference implementation.
      * <Panel
      *   onBeforeClose={(reason) => {
      *     if (!isDirty) return true;
@@ -152,28 +161,30 @@ interface BasePanelProps extends ComponentPropsWithoutRef<'aside'> {
      * />
      * ```
      */
-    onBeforeClose?: (reason: PanelCloseReason) => boolean | Promise<boolean>;
+    'onBeforeClose'?: (reason: PanelCloseReason) => boolean | Promise<boolean>;
 }
 export interface InlinePanelProps extends BasePanelProps {
     /**
-     * Specify the Panel as inline
+     * Render the Panel inline: it sits in document flow and pushes adjacent content aside
+     * when open. Required to opt into the inline kind; the Panel defaults to `'overlay'`.
      */
-    kind?: 'inline';
+    kind: 'inline';
     modalType?: never;
     offset?: never;
 }
 export interface OverlayPanelProps extends BasePanelProps {
     /**
-     * Specify the Panel as overlay
+     * Render the Panel as an overlay: portalled and floating above the page.
+     * @default 'overlay'
      */
-    kind: 'overlay';
+    kind?: 'overlay';
     /**
-     * Specify the modal type (overlay only).
+     * Modal behavior (overlay panels only).
      *
-     * - `'nonModal'` (default) — page stays interactive; ESC closes the panel;
-     *   outside clicks only close when `closeOnOutsidePress` is set.
-     * - `'isModal'` — backdrop overlay, focus trapped; ESC and backdrop click close the panel.
-     * - `'alert'` — close button hidden, ESC and outside clicks are suppressed.
+     * - `'nonModal'` (default) — page stays interactive; Escape closes the panel; outside
+     *   clicks close it unless `closeOnOutsidePress={false}`.
+     * - `'isModal'` — backdrop overlay with focus trapped; Escape and a backdrop click close it.
+     * - `'alert'` — close button hidden; Escape and outside clicks are suppressed.
      *
      * @default 'nonModal'
      */
@@ -181,19 +192,16 @@ export interface OverlayPanelProps extends BasePanelProps {
     /**
      * When `modalType="nonModal"`, allows the panel to close when the user
      * clicks outside it. Has no effect for `'isModal'` or `'alert'` panels.
-     * @default false
+     * @default true
      */
     closeOnOutsidePress?: boolean;
     /**
-     * Activates the floating/offset visual style for overlay panels.
-     * The panel is inset from the viewport edge, gains border radius,
-     * and hides the outer divider.
-     * Pass `true` to use the default offset (`1rem`), or a CSS length
-     * string (for example, `"2rem"`) for a custom offset on all sides. Pass a
-     * `{ x, y }` object (for example, `{ x: "2rem", y: "0.5rem" }`) for
-     * independent horizontal and vertical offsets.
-     * Setting this prop automatically suppresses the outer divider regardless
-     * of the `divider` prop value.
+     * Insets an overlay Panel from the viewport edge, giving it rounded corners and
+     * removing the outer divider (regardless of the `divider` prop).
+     *
+     * Pass `true` for the default `1rem`, a CSS length like `"2rem"` for a uniform offset,
+     * or a `{ x, y }` object like `{ x: "2rem", y: "0.5rem" }` to offset the axes
+     * independently.
      * @default false
      */
     offset?: boolean | string | {
@@ -201,18 +209,19 @@ export interface OverlayPanelProps extends BasePanelProps {
         y: string;
     };
     /**
-     * Portal target for the overlay. When set, the panel renders inside this
-     * element using `position: absolute` instead of `position: fixed`. The
-     * container must:
+     * Portal target for the overlay. When set, the Panel renders inside this element with
+     * `position: absolute` instead of `position: fixed`. The container needs to:
      * - establish a containing block (e.g. `position: relative`)
-     * - have an appropriate `z-index`
-     * - use `overflow: hidden` (or `clip`) so the panel's slide-in/out
-     *   transform doesn't trigger a transient scrollbar on the container.
+     * - set an appropriate `z-index`
+     * - use `overflow: hidden` (or `clip`), so the slide-in/out transform doesn't flash a
+     *   transient scrollbar
      *
-     * Pass the resolved element (or `null` until it exists) — the consumer owns
-     * resolution. Use a callback ref or state so the value is reactive; when it
-     * flips from `null` to the element, the panel re-renders into the container.
-     * A plain `useRef` whose `.current` is mutated will not trigger that update.
+     * Pass the resolved element, or `null` until it exists — resolution is left to the implementer. Use state
+     * or a callback ref so the value is reactive: when it flips from `null` to the element,
+     * the Panel re-renders into the container. A plain `useRef` whose `.current` is mutated
+     * won't trigger that.
+     *
+     * Has no effect on `kind="inline"`.
      *
      * @example
      * ```tsx
@@ -223,21 +232,14 @@ export interface OverlayPanelProps extends BasePanelProps {
      *   </div>
      * );
      * ```
-     *
-     * Has no effect on `kind="inline"`.
      */
     container?: HTMLElement | null;
     /**
-     * The element that opens the panel; clicks on it are excluded from outside-press
-     * dismissal so it can toggle the panel without the close immediately re-firing.
-     * Focus returns to the previously-focused element (typically this trigger) on close.
-     * No effect on `kind="inline"`.
+     * The element that opens the Panel. Clicks on it are excluded from outside-press
+     * dismissal, so it can toggle the Panel without the close immediately re-firing, and
+     * focus returns to it when the Panel closes. No effect on `kind="inline"`.
      *
-     * Note: the exclusion is implemented as a raw `outsidePress` predicate rather than
-     * a FloatingUI reference registration. This avoids `autoUpdate` re-renders that
-     * interfere with the slide-in CSS transition, but means FloatingUI's nested-floating
-     * tree-scoping (`__outsidePressBubbles`) is bypassed for this panel. Avoid using
-     * `triggerRef` when the panel is nested inside another FloatingUI floating element.
+     * Avoid `triggerRef` when the Panel is nested inside another FloatingUI floating element.
      */
     triggerRef?: RefObject<HTMLElement | null>;
 }

package/lib/wip/Panel/index.d.ts

@@ -1,5 +1,5 @@
 export { Panel } from './Panel';
-export type { PanelProps, InlinePanelProps, OverlayPanelProps, PanelKind, PanelPosition, PanelModalType, PanelSize, PanelPadding, PanelCloseReason, } from './Panel.types';
+export type { PanelProps, InlinePanelProps, OverlayPanelProps, PanelKind, PanelPosition, PanelModalType, PanelWidth, PanelHeight, PanelPadding, PanelCloseReason, } from './Panel.types';
 export type { PanelHeaderProps } from './Header/Panel.Header';
 export type { PanelHeaderRowProps } from './Header/Panel.Header.Row';
 export type { PanelHeaderContentBeforeProps } from './Header/Panel.Header.ContentBefore';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viasat/beam-react",
-  "version": "2.42.0",
+  "version": "2.43.0",
   "description": "React component library for the Beam design system",
   "license": "MIT",
   "author": "Viasat",
@@ -59,11 +59,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@viasat/beam-fonts": "2.42.0",
-    "@viasat/beam-shared": "2.42.0",
-    "@viasat/beam-styles": "2.42.0",
-    "@viasat/beam-tokens": "2.42.0",
-    "@viasat/beam-icons": "2.42.0",
+    "@viasat/beam-fonts": "2.43.0",
+    "@viasat/beam-shared": "2.43.0",
+    "@viasat/beam-styles": "2.43.0",
+    "@viasat/beam-tokens": "2.43.0",
+    "@viasat/beam-icons": "2.43.0",
     "clsx": "^1.2.1",
     "@floating-ui/react": "^0.26.18",
     "@stepperize/react": "^5.1.5",

package/chunks/FloatingUI.arrow.DR8hzVDP.js

@@ -1 +0,0 @@
-var _=require("../assets/FloatingUI.css");const m=require("react/jsx-runtime"),f=require("./classNames.DC8Ra4sw.js");require("./constants.CgMu0_1M.js");const g=require("clsx"),a=require("react"),e={"bm-floatingui":"bm-floatingui","bm-floatingui__arrow":"bm-floatingui__arrow","bm-floatingui__overlay":"bm-floatingui__overlay","bm-floatingui__overlay--transparent":"bm-floatingui__overlay--transparent","bm-dialog":"bm-dialog","bm-panel--contained":"bm-panel--contained"},b=a.forwardRef(({options:r,middleware:t},n)=>{const{subElementClassPrefix:o}=f.getBEMClassNames("floatingui"),{className:i,hide:s}=r,l=g(e[`${o}arrow`],i),u=a.useRef(null),c=n||u;return s?null:m.jsx("span",{ref:c,style:t.arrowStyles,className:l})});exports.Arrow=b;exports.floatinguiStyles=e;

package/chunks/panel.module.BVmRxZHo.js

@@ -1 +0,0 @@
-var n=require("../assets/panel.css");const e={"bm-light":"bm-light","bm-dark":"bm-dark","bm-inverse":"bm-inverse","bm-enterprise":"bm-enterprise","bm-consumer":"bm-consumer","bm-panel":"bm-panel","bm-panel--inline":"bm-panel--inline","bm-panel--overlay":"bm-panel--overlay","bm-panel--position-start":"bm-panel--position-start","bm-panel--position-end":"bm-panel--position-end","bm-panel--position-bottom":"bm-panel--position-bottom","bm-panel--contained":"bm-panel--contained","bm-panel--floating":"bm-panel--floating","bm-panel--size-sm":"bm-panel--size-sm","bm-panel--size-md":"bm-panel--size-md","bm-panel--size-lg":"bm-panel--size-lg","bm-panel__body":"bm-panel__body","bm-panel--padding-sm":"bm-panel--padding-sm","bm-panel__header":"bm-panel__header","bm-panel__footer":"bm-panel__footer","bm-panel--padding-md":"bm-panel--padding-md","bm-panel__header__row":"bm-panel__header__row","bm-panel__header__content-before":"bm-panel__header__content-before","bm-panel__header__content-after":"bm-panel__header__content-after","bm-panel__header__heading":"bm-panel__header__heading","bm-panel__header__description":"bm-panel__header__description","bm-panel__header__close-button":"bm-panel__header__close-button","bm-panel__footer__actions":"bm-panel__footer__actions","bm-panel__footer__actions--start":"bm-panel__footer__actions--start","bm-panel__footer__actions--end":"bm-panel__footer__actions--end","bm-panel__footer__actions--spaceBetween":"bm-panel__footer__actions--spaceBetween","bm-panel__footer__actions--stacked":"bm-panel__footer__actions--stacked","bm-panel__overlay-divider":"bm-panel__overlay-divider","bm-panel__overlay-divider--start":"bm-panel__overlay-divider--start","bm-panel__overlay-divider--end":"bm-panel__overlay-divider--end","bm-panel__overlay-divider--bottom":"bm-panel__overlay-divider--bottom","bm-panel__resize-handle":"bm-panel__resize-handle","bm-panel--resizable":"bm-panel--resizable","bm-panel__inline-wrapper":"bm-panel__inline-wrapper","bm-panel__inline-wrapper--size-sm":"bm-panel__inline-wrapper--size-sm","bm-panel__inline-wrapper--size-md":"bm-panel__inline-wrapper--size-md","bm-panel__inline-wrapper--size-lg":"bm-panel__inline-wrapper--size-lg","bm-panel__inline-wrapper-content":"bm-panel__inline-wrapper-content"};exports.styles=e;