@nimbus-ds/patterns 1.36.0-rc.9 → 1.38.0

package/dist/index.d.ts

@@ -38,8 +38,17 @@ export interface AppShellChatProperties {
 	 * The overlay auto-detects the parent bounds (respecting menu and header).
 	 */
 	expanded?: boolean;
+	/**
+	 * Width of the chat panel in collapsed (non-expanded) mode.
+	 * Accepts any valid CSS length value (e.g. "300px", "25vw") or a responsive
+	 * object keyed by breakpoint (e.g. `{ xs: "300px", xxl: "378px" }`).
+	 * Useful for consumer-controlled resize interactions such as a drag handle.
+	 * When omitted, defaults to the responsive `{ xs: "300px", xxl: "378px" }`.
+	 */
+	collapsedWidth?: NonNullable<BoxProps["maxWidth"]>;
 }
 export type AppShellChatProps = AppShellChatProperties & Omit<BoxProps, "position">;
+export declare const APPSHELL_CHAT_DEFAULT_WIDTH = "360px";
 declare const AppShellChat: React.FC<AppShellChatProps>;
 export interface AppShellComponents {
 	Header: typeof AppShellHeader;
@@ -124,6 +133,191 @@ export type AppShellMenuContextValue = {
  * @throws If `enforce=true` and used without a provider.
  */
 export declare const useAppShellMenuContext: (enforce?: boolean) => AppShellMenuContextValue;
+export type BottomSheetPadding = "none" | "base";
+/**
+ * A snap point expressed as a viewport-height percentage (e.g. "60%") or the
+ * keyword "full" (edge-to-edge, covering the full viewport height).
+ */
+export type BottomSheetSnapPoint = `${number}%` | "full";
+/**
+ * Predicate variant of `closeOnOutsidePress`: receives the DOM event and
+ * returns `true` to allow closing, `false` to ignore the press.
+ */
+export type CloseOnOutsidePress = (event: PointerEvent | MouseEvent) => boolean;
+export interface BottomSheetProperties {
+	/**
+	 * Determines if the bottom sheet is shown or not.
+	 * @default false
+	 */
+	open?: boolean;
+	/**
+	 * Callback fired when the component requests to be closed (overlay press,
+	 * close control, Escape, or a downward dismiss gesture).
+	 * () => void;
+	 */
+	onRemove?: () => void;
+	/**
+	 * Ordered list of heights the sheet can snap to. Each entry is a
+	 * viewport-height percentage (e.g. "60%") or the keyword "full".
+	 * @default ["60%", "90%", "full"]
+	 */
+	snapPoints?: BottomSheetSnapPoint[];
+	/**
+	 * Index within `snapPoints` used as the initial snap point.
+	 * @default 0
+	 */
+	defaultSnap?: number;
+	/**
+	 * Content of the sheet. Compose with BottomSheet.Header, BottomSheet.Body
+	 * and BottomSheet.Footer.
+	 * @TJS-type React.ReactNode
+	 */
+	children?: ReactNode;
+	/**
+	 * Controls whether pressing outside should close the sheet.
+	 * - boolean: enable/disable dismissal on outside press
+	 * - function: receive the DOM event and return true to allow closing
+	 * @default true
+	 */
+	closeOnOutsidePress?: boolean | CloseOnOutsidePress;
+	/**
+	 * The attribute name to ignore when checking for outside presses, so
+	 * portaled Popover/Modal content does not close the sheet.
+	 * @default "data-nimbus-outside-press-ignore"
+	 */
+	ignoreAttributeName?: string;
+	/**
+	 * Determines if background scroll is locked while the sheet is open.
+	 * @default true
+	 */
+	needRemoveScroll?: boolean;
+	/**
+	 * Accessible name (`aria-label`) for the drag grabber. Override for
+	 * non-English locales, since the built-in default is English-only.
+	 * @default "Drag to resize or dismiss"
+	 */
+	grabberLabel?: string;
+	/**
+	 * Explicit z-index for the sheet layer. Omitted by default: like Nimbus's
+	 * own Sidebar/Modal/Popover, the sheet relies on DOM mount order rather
+	 * than a z-index. Its portal mounts into the nearest Nimbus
+	 * <ThemeProvider>'s own wrapper element (the same container
+	 * Sidebar/Modal/Popover portal into), falling back to document.body only
+	 * when no ThemeProvider is present. In both cases, later-mounted siblings
+	 * paint on top of earlier ones as long as neither sets a z-index, so this
+	 * keeps the sheet correctly stacked against Popover and other BottomSheet
+	 * instances. Only set this to force a specific stacking order against
+	 * something outside that convention.
+	 */
+	zIndex?: number;
+}
+/**
+ * Public props for `BottomSheet`. Combines `BottomSheetProperties` (the
+ * sheet's own behavior — visibility, snap points, dismissal, stacking) with
+ * `root` and every native `div` attribute except `color`.
+ */
+export type BottomSheetProps = BottomSheetProperties & {
+	/**
+	 * Root element where the portal should be mounted. When provided and not
+	 * null, the portal renders inside this element. Otherwise it renders into
+	 * the nearest Nimbus <ThemeProvider>'s own wrapper element (same as
+	 * Sidebar/Modal/Popover), so it inherits the active theme's CSS custom
+	 * properties and stacks correctly against them; it falls back to
+	 * document.body only when no ThemeProvider is present. Useful to scope the
+	 * sheet within a container (e.g., AppShell.Chat).
+	 */
+	root?: HTMLElement | null;
+} & Omit<HTMLAttributes<HTMLDivElement>, "color">;
+export interface BottomSheetHeaderProperties {
+	/**
+	 * The content of the sheet header. Accepts any node (title, actions, icons).
+	 * @TJS-type React.ReactNode
+	 */
+	children?: ReactNode;
+	/**
+	 * The padding around the header content area.
+	 * @default base
+	 */
+	padding?: BottomSheetPadding;
+}
+/**
+ * Public props for `BottomSheet.Header`. Combines `BottomSheetHeaderProperties`
+ * with every native element attribute except `color` (same reason as
+ * `BottomSheetProps`: it conflicts with Box's own color-token sprinkle).
+ */
+export type BottomSheetHeaderProps = BottomSheetHeaderProperties & Omit<HTMLAttributes<HTMLElement>, "color">;
+export interface BottomSheetBodyProperties {
+	/**
+	 * The scrollable content of the sheet.
+	 * @TJS-type React.ReactNode
+	 */
+	children: ReactNode;
+	/**
+	 * The padding around the body content area.
+	 * @default base
+	 */
+	padding?: BottomSheetPadding;
+}
+/**
+ * Public props for `BottomSheet.Body`. Combines `BottomSheetBodyProperties`
+ * (`children` is required, unlike `Header`'s) with every native element
+ * attribute except `color`.
+ */
+export type BottomSheetBodyProps = BottomSheetBodyProperties & Omit<HTMLAttributes<HTMLElement>, "color">;
+export interface BottomSheetFooterProperties {
+	/**
+	 * The content of the sheet footer.
+	 * @TJS-type React.ReactNode
+	 */
+	children: ReactNode;
+	/**
+	 * The padding around the footer content area.
+	 * @default base
+	 */
+	padding?: BottomSheetPadding;
+}
+/**
+ * Public props for `BottomSheet.Footer`. Combines `BottomSheetFooterProperties`
+ * (`children` is required, same as `Body`) with every native element
+ * attribute except `color`. `BottomSheet.Footer` itself is optional to
+ * render at all — omitting it entirely is how a sheet renders without a
+ * footer region.
+ */
+export type BottomSheetFooterProps = BottomSheetFooterProperties & Omit<HTMLAttributes<HTMLElement>, "color">;
+/**
+ * The composable subcomponents attached to `BottomSheet`
+ * (`BottomSheet.Header`, `BottomSheet.Body`, `BottomSheet.Footer`), used to
+ * compose the sheet's `children`.
+ */
+export interface BottomSheetComponents {
+	/** Chrome region above the body; the drag grabber is pinned above it. */
+	Header: FC<BottomSheetHeaderProps>;
+	/** The scrollable content region. */
+	Body: FC<BottomSheetBodyProps>;
+	/** Optional chrome region below the body (e.g. action buttons). */
+	Footer: FC<BottomSheetFooterProps>;
+}
+declare const BottomSheetBase: React.FC<BottomSheetProps>;
+/**
+ * A mobile-first modal sheet that slides up from the bottom edge, with
+ * configurable snap points and a pointer-driven drag gesture to resize
+ * between them or dismiss by dragging down.
+ *
+ * Controlled via `open`/`onRemove`, the same contract as `Sidebar`: the
+ * component never changes its own visibility, it only requests to close (via
+ * overlay press, Escape, or a downward dismiss gesture) — the consumer sets
+ * `open` to `false` in response.
+ *
+ * Compose with `BottomSheet.Header` (optional), `BottomSheet.Body`
+ * (required), and `BottomSheet.Footer` (optional) as `children`.
+ *
+ * Behaves as a modal: renders as `role="dialog"`/`aria-modal="true"`, dims
+ * and blocks the background, traps focus while open, and restores it to the
+ * previously focused element on close. Automatically labels the dialog via
+ * `aria-labelledby` pointing at `BottomSheet.Header` when one is present;
+ * pass an explicit `aria-label`/`aria-labelledby` to override that.
+ */
+export declare const BottomSheet: typeof BottomSheetBase & BottomSheetComponents;
 export interface CalloutCardProperties {
 	/**
 	 * CalloutCard color.
@@ -725,12 +919,7 @@ export interface MenuProperties {
 }
 export type MenuProps = MenuProperties & Omit<HTMLAttributes<HTMLElement>, "color">;
 export declare const Menu: React.FC<MenuProps> & MenuComponents;
-export interface NavTabsItemProperties {
-	/**
-	 * Icon element to be rendered inside the button.
-	 * @TJS-type React.ReactNode
-	 */
-	icon: ReactNode;
+export interface NavTabsItemBaseProperties {
 	/**
 	 * Controls whether the button is active or not.
 	 */
@@ -749,7 +938,30 @@ export interface NavTabsItemProperties {
 	 */
 	ariaLabel: string;
 }
-export type NavTabsItemProps = NavTabsItemProperties & Omit<BoxProperties, "onClick"> & Omit<HTMLAttributes<HTMLElement>, "color">;
+export interface NavTabsItemNeutralProperties extends NavTabsItemBaseProperties {
+	/**
+	 * Visual variant of the button.
+	 * "ai-generative" renders a fixed AI icon with a gradient border and does not accept a custom `icon`.
+	 * @default "neutral"
+	 */
+	appearance?: "neutral";
+	/**
+	 * Icon element to be rendered inside the button.
+	 * @TJS-type React.ReactNode
+	 */
+	icon: ReactNode;
+}
+export interface NavTabsItemAIGenerativeProperties extends Omit<NavTabsItemBaseProperties, "active"> {
+	/**
+	 * Visual variant of the button.
+	 * "ai-generative" renders a fixed AI icon with a gradient border and does not accept a custom `icon`.
+	 */
+	appearance: "ai-generative";
+	icon?: never;
+	active?: never;
+}
+export type NavTabsItemVariantProperties = NavTabsItemNeutralProperties | NavTabsItemAIGenerativeProperties;
+export type NavTabsItemProps = NavTabsItemVariantProperties & Omit<BoxProperties, "onClick"> & Omit<HTMLAttributes<HTMLElement>, "color">;
 declare const NavTabsItem: React.FC<NavTabsItemProps>;
 export interface NavTabsComponents {
 	Item: typeof NavTabsItem;
@@ -1136,82 +1348,28 @@ export type InitialScreenProps = InitialScreenProperties & Omit<BoxProps, "width
  */
 export declare const InitialScreen: React.FC<InitialScreenProps> & InitialScreenComponents;
 export interface PlanDisplayCardProperties {
-	/**
-	 * Renders the card with the Plans 2.0 gradient background (primary-surface → neutral-background).
-	 * Ignored when `ribbonLabel` is provided.
-	 */
-	gradient?: boolean;
-	/**
-	 * Label shown in a ribbon on top of the card (e.g. "Más escogido"). When provided, the card
-	 * is rendered with the featured style (primary ribbon + 2px primary border, no shadow),
-	 * taking precedence over `gradient`.
-	 * @TJS-type React.ReactNode
-	 */
-	ribbonLabel?: ReactNode;
+	highlighted?: boolean;
 }
 export type PlanDisplayCardProps = PropsWithChildren<PlanDisplayCardProperties> & Omit<BoxProps, "borderColor" | "borderRadius" | "borderStyle" | "borderWidth" | "boxShadow">;
 declare const PlanDisplayCard: React.FC<PlanDisplayCardProps>;
 export type PlanDisplayCardHeaderProperties = {
 	subtitle: string;
 	title: ReactNode;
-	/**
-	 * Optional slot rendered to the right of the subtitle (e.g. a `<Tag>` like "Plan actual").
-	 * When provided, the subtitle row is laid out with space between the subtitle and the tag.
-	 * @TJS-type React.ReactNode
-	 */
-	tag?: ReactNode;
 };
 export type PlanDisplayCardHeaderProps = PropsWithChildren<PlanDisplayCardHeaderProperties>;
 declare const PlanDisplayCardHeader: React.FC<PlanDisplayCardHeaderProps>;
 export type PlanDisplayCardContentProperties = PropsWithChildren;
 declare const PlanDisplayCardContent: React.FC<PlanDisplayCardContentProperties>;
-export type PlanDisplayCardFooterProperties = PropsWithChildren<{
-	/**
-	 * Optional leading icon for an add-on style footer row (e.g. a point-of-sale icon next to a link).
-	 * When provided, the footer renders the icon and children side by side.
-	 * @TJS-type React.ReactNode
-	 */
-	icon?: ReactNode;
-}>;
+export type PlanDisplayCardFooterProperties = PropsWithChildren;
 declare const PlanDisplayCardFooter: React.FC<PlanDisplayCardFooterProperties>;
 export type PlanDisplayCardSpacingProps = Omit<BoxProps, "children" | "borderTopWidth" | "borderColor" | "borderStyle" | "my">;
 declare const PlanDisplayCardSpacing: React.FC<PlanDisplayCardSpacingProps>;
 export type PlanDisplayBulletProperties = {
 	icon: ReactNode;
 	disabled?: boolean;
-	/**
-	 * Optional slot rendered inline after the bullet text (e.g. a `<Tag>` like "Nuevo").
-	 * @TJS-type React.ReactNode
-	 */
-	badge?: ReactNode;
 };
 export type PlanDisplayBulletProps = PropsWithChildren<PlanDisplayBulletProperties>;
 declare const PlanDisplayBullet: React.FC<PlanDisplayBulletProps>;
-export type PlanDisplayCardPriceProperties = {
-	/**
-	 * The current price of the plan (e.g. "$999"). Rendered as the main, prominent value.
-	 * @TJS-type React.ReactNode
-	 */
-	price: ReactNode;
-	/**
-	 * Optional previous price, rendered with a line-through next to the current price.
-	 * @TJS-type React.ReactNode
-	 */
-	previousPrice?: ReactNode;
-	/**
-	 * Optional billing period suffix (e.g. "/mes") rendered next to the price.
-	 * @TJS-type React.ReactNode
-	 */
-	period?: ReactNode;
-	/**
-	 * Optional annual note rendered below the price (e.g. "R$696/año. Economiza R$132.").
-	 * Accepts a ReactNode so it can mix colors (e.g. an emphasized savings span).
-	 * @TJS-type React.ReactNode
-	 */
-	annualNote?: ReactNode;
-};
-export type PlanDisplayCardPriceProps = PlanDisplayCardPriceProperties;
-declare const PlanDisplayCardPrice: React.FC<PlanDisplayCardPriceProps>;
 /**
  * Interface representing the internal components used in the PlanDisplay.
  */
@@ -1226,10 +1384,6 @@ export interface PlanDisplayComponents {
 	 * an optional children where additional information can be displayed.
 	 */
 	Header: typeof PlanDisplayCardHeader;
-	/**
-	 * The price component of the plan display card. It renders the current price and optionally a previous price (with line-through), a billing period suffix and an annual note.
-	 */
-	Price: typeof PlanDisplayCardPrice;
 	/**
 	 * The content component of the plan display card. This component is used to display the main content of the plan, such as the plan bullet points.
 	 */