@nimbus-ds/patterns 1.36.0 → 1.38.0

package/dist/index.d.ts

@@ -133,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.
@@ -734,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.
 	 */
@@ -758,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;