@silk-hq/components
Version:
UI Components by Silk
1,406 lines (1,405 loc) • 143 kB
TypeScript
/* @silk-hq/components | (c) 2025 Bruno Stasse | SEE LICENSE FILE */
import React from "react";
export declare namespace mapping {
namespace Sheet {
const componentName: string;
namespace elementNames {
const root: number;
const view: number;
const backdrop: number;
const backdropTrap: number;
const primaryScrollTrapRoot: number;
const secondaryScrollTrapRoot: number;
const scrollContainer: number;
const frontSpacer: number;
const backSpacer: number;
const detentMarker: number;
const contentWrapper: number;
const content: number;
const bleedingBackground: number;
const stickyContainer: number;
const sticky: number;
const leftEdge: number;
const trigger: number;
const handle: number;
const outlet: number;
}
namespace variationSetsNames {
const openness: string;
const staging: string;
const opennessClosedStatus: string;
const position: string;
const positionCoveredStatus: string;
const placement: string;
const track: string;
const swipeDisabled: string;
const swipeOutDisabledWithDetent: string;
const swipeOvershootDisabled: string;
const bleedDisabled: string;
const inertOutside: string;
const backdropSwipeable: string;
const scrollContainerShouldBePassThrough: string;
const swipeTrap: string;
}
const variationValuesNames: {
open: string;
opening: string;
closed: string;
closing: string;
none: string;
top: string;
bottom: string;
left: string;
right: string;
horizontal: string;
vertical: string;
front: string;
covered: string;
true: string;
false: string;
auto: string;
center: string;
pending: string;
"flushing-to-preparing-open": string;
"flushing-to-preparing-opening": string;
"preparing-open": string;
"preparing-opening": string;
"safe-to-unmount": string;
content: string;
root: string;
"going-down": string;
"going-up": string;
indeterminate: string;
idle: string;
"come-back": string;
out: string;
stepping: string;
both: string;
};
}
namespace ScrollTrap {
const componentName_1: string;
export { componentName_1 as componentName };
export namespace elementNames_1 {
const root_1: number;
export { root_1 as root };
export const stabiliser: number;
}
export { elementNames_1 as elementNames };
export namespace variationSetsNames_1 {
const active: string;
const axis: string;
const automaticallyDisabledForOptimisation: string;
}
export { variationSetsNames_1 as variationSetsNames };
export namespace variationValuesNames_1 {
const _true: string;
export { _true as true };
const _false: string;
export { _false as false };
export const horizontal: string;
export const vertical: string;
export const both: string;
export const none: string;
}
export { variationValuesNames_1 as variationValuesNames };
}
namespace Scroll {
const componentName_2: string;
export { componentName_2 as componentName };
export namespace elementNames_2 {
const root_2: number;
export { root_2 as root };
const view_1: number;
export { view_1 as view };
const scrollContainer_1: number;
export { scrollContainer_1 as scrollContainer };
const content_1: number;
export { content_1 as content };
export const UAScrollbarMeasurer: number;
export const spy: number;
export const startSpacer: number;
export const endSpacer: number;
}
export { elementNames_2 as elementNames };
export namespace variationSetsNames_2 {
const axis_1: string;
export { axis_1 as axis };
export const contentPlacement: string;
export const scrollTrapX: string;
export const scrollTrapY: string;
export const scrollGestureOvershoot: string;
export const scrollDisabled: string;
export const side: string;
export const pageScroll: string;
export const overflowX: string;
export const overflowY: string;
export const skipScrollAnimation: string;
export const scrollAnchoring: string;
export const scrollSnapType: string;
export const scrollPadding: string;
export const scrollTimelineName: string;
export const nativeScrollbar: string;
export const scrollOngoing: string;
}
export { variationSetsNames_2 as variationSetsNames };
export namespace variationValuesNames_2 {
const _true_1: string;
export { _true_1 as true };
const _false_1: string;
export { _false_1 as false };
export const x: string;
export const y: string;
const both_1: string;
export { both_1 as both };
export const unset: string;
export const contain: string;
export const start: string;
export const end: string;
export const center: string;
export const auto: string;
const _default: string;
export { _default as default };
const none_1: string;
export { none_1 as none };
export const mandatoryX: string;
export const mandatoryY: string;
export const proximityX: string;
export const proximityY: string;
}
export { variationValuesNames_2 as variationValuesNames };
}
namespace SlideShow {
const componentName_3: string;
export { componentName_3 as componentName };
const elementNames_3: {};
export { elementNames_3 as elementNames };
const variationSetsNames_3: {};
export { variationSetsNames_3 as variationSetsNames };
const variationValuesNames_3: {};
export { variationValuesNames_3 as variationValuesNames };
}
namespace VisuallyHidden {
const componentName_4: string;
export { componentName_4 as componentName };
export namespace elementNames_4 {
const root_3: number;
export { root_3 as root };
}
export { elementNames_4 as elementNames };
const variationSetsNames_4: {};
export { variationSetsNames_4 as variationSetsNames };
const variationValuesNames_4: {};
export { variationValuesNames_4 as variationValuesNames };
}
namespace SpecialWrapper {
const componentName_5: string;
export { componentName_5 as componentName };
export namespace elementNames_5 {
const root_4: number;
export { root_4 as root };
const content_2: number;
export { content_2 as content };
}
export { elementNames_5 as elementNames };
const variationSetsNames_5: {};
export { variationSetsNames_5 as variationSetsNames };
const variationValuesNames_5: {};
export { variationValuesNames_5 as variationValuesNames };
}
namespace Fixed {
const componentName_6: string;
export { componentName_6 as componentName };
export namespace elementNames_6 {
const root_5: number;
export { root_5 as root };
}
export { elementNames_6 as elementNames };
const variationSetsNames_6: {};
export { variationSetsNames_6 as variationSetsNames };
const variationValuesNames_6: {};
export { variationValuesNames_6 as variationValuesNames };
}
namespace SheetStack {
const componentName_7: string;
export { componentName_7 as componentName };
export namespace elementNames_7 {
const root_6: number;
export { root_6 as root };
const outlet_1: number;
export { outlet_1 as outlet };
}
export { elementNames_7 as elementNames };
const variationSetsNames_7: {};
export { variationSetsNames_7 as variationSetsNames };
const variationValuesNames_7: {};
export { variationValuesNames_7 as variationValuesNames };
}
namespace AutoFocusTarget {
const componentName_8: string;
export { componentName_8 as componentName };
export namespace elementNames_8 {
const root_7: number;
export { root_7 as root };
}
export { elementNames_8 as elementNames };
const variationSetsNames_8: {};
export { variationSetsNames_8 as variationSetsNames };
const variationValuesNames_8: {};
export { variationValuesNames_8 as variationValuesNames };
}
}
type Track = "top" | "bottom" | "left" | "right";
type TrackProp = Track | ["top", "bottom"] | ["bottom", "top"] | ["right", "left"] | ["left", "right"];
type SheetId = React.Context<any>;
type SheetStackId = React.Context<any>;
type ScrollId = React.Context<any>;
type ComponentId = React.Context<any>;
type TravelStatus = "entering" | "idleInside" | "stepping" | "exiting" | "idleOutside";
type DetentIndex = number;
type TravelRange = {
start: DetentIndex;
end: DetentIndex;
};
type TravelProgress = number;
type TravelProgressAtDetents = Array<TravelProgress>;
type ValidCSSValue = string | number;
type ValidNumericalCSSValue = string | number;
type TweenFunction = (start: ValidNumericalCSSValue, end: ValidNumericalCSSValue) => string;
interface CssValueTemplateParams {
progress: TravelProgress;
tween: TweenFunction;
}
type CssValueTemplate = (param: CssValueTemplateParams) => ValidCSSValue;
type CSSPropertySupportedInValueKeyframes = "opacity" | "translate" | "translateX" | "translateY" | "translateZ" | "scale" | "scaleX" | "scaleY" | "scaleZ" | "rotate" | "rotateX" | "rotateY" | "rotateZ" | "skew" | "skewX" | "skewY";
type CSSPropertiesSupportedInValueKeyframesAnimationDeclarations = {
[properties in CSSPropertySupportedInValueKeyframes]?: [ValidCSSValue, ValidCSSValue] | CssValueTemplate | string | null | undefined;
};
type AllPropertiesAnimationDeclarations = {
[property: string]: CssValueTemplate | string | null | undefined;
};
type AnimationDeclarations = CSSPropertiesSupportedInValueKeyframesAnimationDeclarations | AllPropertiesAnimationDeclarations;
type TravelAnimationPropValue = AnimationDeclarations;
type StackingAnimationPropValue = AnimationDeclarations;
type SpringPreset = "gentle" | "smooth" | "snappy" | "brisk" | "bouncy" | "elastic";
type StaticAnimationOptions = {
preset?: SpringPreset;
skip?: boolean;
contentMove?: boolean;
};
type SpringConfig = {
easing: "spring";
stiffness: number;
damping: number;
mass: number;
initialVelocity?: number;
precision?: number;
delay?: number;
};
type CSSEasingConfig = {
easing: "ease" | "ease-in" | "ease-out" | "ease-in-out" | "linear" | `cubic-bezier(${string})`;
duration: number;
delay?: number;
};
type EnteringAnimationSettings = SpringPreset | ((SpringConfig & StaticAnimationOptions & {
track?: Track;
}) | (CSSEasingConfig & StaticAnimationOptions & {
track?: Track;
}) | (StaticAnimationOptions & {
track?: Track;
}));
type ExitingAnimationSettings = SpringPreset | ((SpringConfig & StaticAnimationOptions & {
track?: Track;
}) | (CSSEasingConfig & StaticAnimationOptions & {
track?: Track;
}) | (StaticAnimationOptions & {
track?: Track;
}));
type SteppingAnimationSettings = SpringPreset | ((SpringConfig & StaticAnimationOptions) | (CSSEasingConfig & StaticAnimationOptions) | StaticAnimationOptions);
type PresentedState = boolean;
type Detent = number;
interface ClickOutsideHandlerOptions {
dismiss?: boolean;
stopOverlayPropagation?: boolean;
}
interface ClickOutsideCustomEvent extends ClickOutsideHandlerOptions {
nativeEvent?: Event | React.SyntheticEvent;
changeDefault: (changedBehavior: ClickOutsideHandlerOptions) => void;
}
type ClickOutsideHandlerValue = ((customEvent: ClickOutsideCustomEvent) => void) | ClickOutsideHandlerOptions;
interface EscapeKeyDownHandlerOptions {
nativePreventDefault?: boolean;
dismiss?: boolean;
stopOverlayPropagation?: boolean;
}
interface EscapeKeyDownCustomEvent extends EscapeKeyDownHandlerOptions {
nativeEvent?: Event | React.SyntheticEvent;
changeDefault: (changedBehavior: EscapeKeyDownHandlerOptions) => void;
}
type EscapeKeyDownHandlerValue = ((customEvent: EscapeKeyDownCustomEvent) => void) | EscapeKeyDownHandlerOptions;
type SafeArea = "none" | "layout-viewport" | "visual-viewport";
interface OutletExclusiveProps {
/**
* ---
* ## `travelAnimation`
*
* - **Presence**: Optional
* - **Default**: `undefined`
*
* ### Description:
*
* Declaratively defines animations on any CSS property of the
* underlying element driven by the Sheet’s travel.
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `[string \| number, string \| number]` | **Keyframes array syntax.** As the Sheet travels from its first detent (index 0) to its last detent, the underlying element will have its related CSS property animated from the first to the second value in the array, each value in-between being interpolated linearly. |
* | `({ progress: number; tween: (start: number \| string, end: number \| string) => string; }) => string \| number` | **Function syntax.** As the Sheet travels from its first detent (index 0) to its last detent, the underlying element will have its related CSS property animated based on the value returned by the function. The progress value goes from 0 to 1. |
* | `string` | **String syntax.** As the Sheet travels, the underlying element will have its related CSS property set to the defined value. |
* | `null \| undefined` | The underlying element related CSS property will not be animated or set. |
*
* ### Notes:
*
* - CSS properties must be written in camelcase form (e.g.
* `borderRadius`).
* - All individual components of the `transform` CSS property
* can be used separately.
* - The keyframes array syntax is only supported with individual
* `transform` properties and `opacity`.
*/
travelAnimation?: TravelAnimationPropValue;
/**
* ---
* ## `stackingAnimation`
*
* - **Presence**: Optional
* - **Default**: `undefined`
*
* ### Description:
*
* Declaratively defines animations on any CSS property of the
* underlying element driven by the aggregated travel of
* Sheets stacked above the Sheet associated with this Outlet
* and belonging to the same SheetStack.
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `[string \| number, string \| number]` | **Keyframes array syntax.** As Sheets travel and get stacked on top of the associated Sheet, the underlying element will have its related CSS property animated from the first to the second value in the array, each value in-between being interpolated linearly. |
* | `({ progress: number; tween: (start: number \| string, end: number \| string) => string; }) => string \| number` | **Function syntax.** As Sheets travel and get stacked on top of the associated Sheet, the underlying element will have its related CSS property animated based on the value returned by the function. The progress value goes from 0 to n (n being the number of Sheets stacked on top of the associated Sheet). |
* | `string` | **String syntax.** As the Sheets get stacked on top of the associated Sheet, the underlying element will have its related CSS property set to the defined value. |
* | `null \| undefined` | The underlying element related CSS property will not be animated or set. |
*
* ### Notes:
*
* - CSS properties must be written in camelcase form (e.g.
* `borderRadius`).
* - All individual components of the `transform` CSS property
* can be used separately.
* - The keyframes array syntax is only supported with individual
* `transform` properties and `opacity`.
*/
stackingAnimation?: StackingAnimationPropValue;
}
export interface FixedRootProps extends React.HTMLAttributes<HTMLDivElement> {
/**
* ---
* ## `asChild`
*
* - **Presence**: Optional
* - **Default**: `undefined`
*
* ### Description:
*
* Defines whether the sub-component underlying element is the
* default one or the one passed as child of the
* sub-component.
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `true` | The underlying element rendered is the child.
* | `false` | The underlying element rendered is the default one.
*
* ### Notes:
* - If the child is a React component rendering an element:
* - it must accept props and spread all received props onto
* the rendered element;
* - in React < 19, it must use `React.forwardRef()` and
* pass the received ref to the rendered element.
*/
asChild?: boolean;
"data-silk"?: string;
}
export interface FixedContentProps extends React.HTMLAttributes<HTMLDivElement> {
/**
* ---
* ## `asChild`
*
* - **Presence**: Optional
* - **Default**: `undefined`
*
* ### Description:
*
* Defines whether the sub-component underlying element is the
* default one or the one passed as child of the
* sub-component.
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `true` | The underlying element rendered is the child.
* | `false` | The underlying element rendered is the default one.
*
* ### Notes:
* - If the child is a React component rendering an element:
* - it must accept props and spread all received props onto
* the rendered element;
* - in React < 19, it must use `React.forwardRef()` and
* pass the received ref to the rendered element.
*/
asChild?: boolean;
"data-silk"?: string;
}
/**
* ---
* ## `Fixed`
*
* ### Description:
*
* A primitive component that handles positioning in relation to
* the viewport. It provides extra features compared to normal
* CSS `position: fixed`. It:
*
* - traps scroll gestures when scrolling over it;
* - preserves its visual position when it is a descendant of a
* `<Sheet.Outlet>` or `<SheetStack.Outlet>` underlying
* element and those have their transform CSS property
* animated during a travel or stacking animation;
* - exposes `--x-collapsed-scrollbar-thickness` and
* `--y-collapsed-scrollbar-thickness` CSS custom properties
* when page scrolling is temporarily disabled.
*
* ### Anatomy:
*
* ```
* <Fixed.Root> (required)
* <Fixed.Content> (required)
* ...
* </Fixed.Content>
* </Fixed.Root>
* ```
*/
export const Fixed: {
/**
* ---
* ## `<Fixed.Root>`
*
* - **Presence**: Required
* - **Composition**: Contains `<Fixed.Content>`
* - **Underlying element**: `<div>`
*
* ### Description:
*
* The Root sub-component wraps the `<Fixed.Content>` of the
* same Fixed instance, as it contains shared logic.
*
* ### Notes:
* - If you are setting a value to the `bottom` CSS property
* without using the `top` property, and/or the `right`
* property without using the `left` CSS property, you have
* to declare the property used in the `--silk-fixed-side`
* value.
* - If you need to apply CSS transform styles to the
* underlying element, you should do it on a descendant
* element to avoid any conflict.
*
* ### Anatomy & default props:
*
* ```
* <Fixed.Root
* asChild={false}
* > (required)
* <Fixed.Content> (required)
* ...
* </Fixed.Content>
* </Fixed.Root>
* ```
*/
Root: React.ForwardRefExoticComponent<FixedRootProps & React.RefAttributes<any>>;
/**
* ---
* ## `<Fixed.Content>`
*
* - **Presence**: Required
* - **Composition**: Child of `<Fixed.Root>`
* - **Underlying element**: `<div>`
*
* ### Description:
*
* The Content sub-component represents the content of the
* Fixed component.
*
* ### Anatomy & default props:
*
* ```
* <Fixed.Root> (required)
* <Fixed.Content
* asChild={false}
* > (required)
* ...
* </Fixed.Content>
* </Fixed.Root>
* ```
*/
Content: React.ForwardRefExoticComponent<FixedContentProps & React.RefAttributes<any>>;
};
export interface VisuallyHiddenRootProps extends React.HTMLAttributes<HTMLSpanElement> {
/**
* ---
* ## `asChild`
*
* - **Presence**: Optional
* - **Default**: `undefined`
*
* ### Description:
*
* Defines whether the sub-component underlying element is the
* default one or the one passed as child of the
* sub-component.
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `true` | The underlying element rendered is the child.
* | `false` | The underlying element rendered is the default one.
*
* ### Notes:
* - If the child is a React component rendering an element:
* - it must accept props and spread all received props onto
* the rendered element;
* - in React < 19, it must use `React.forwardRef()` and
* pass the received ref to the rendered element.
*/
asChild?: boolean;
"data-silk"?: string;
}
/**
* ---
* ## `VisuallyHidden`
*
* ### Description:
*
* A component that visually hides elements and their content but
* keep them accessible to screen-readers. This is useful for
* example in combination with `<Sheet.Title>` or a
* `<Sheet.Description>`.
*
* ### Anatomy:
*
* ```
* <VisuallyHidden.Root> (required)
* ...
* </VisuallyHidden.Root>
* ```
*/
export const VisuallyHidden: {
/**
* ---
* ## `<VisuallyHidden.Root>`
*
* - **Presence**: Required
* - **Composition**: Anywhere
* - **Underlying element**: `<span>`
*
* ### Description:
*
* The Root sub-component wraps content to be made visually
* hidden.
*
* ### Anatomy & default props:
*
* ```
* <VisuallyHidden.Root
* asChild={false}
* > (required)
* ...
* <VisuallyHidden.Root>
* ```
*/
Root: React.ForwardRefExoticComponent<VisuallyHiddenRootProps & React.RefAttributes<any>>;
};
export interface SheetOutletProps extends OutletExclusiveProps, React.HTMLAttributes<HTMLDivElement> {
/**
* ---
* ## `forComponent`
*
* - **Presence**: Optional
* - **Default**: The `SheetId` of the closest `<Sheet.Root>` ancestor.
*
* ### Description:
*
* Associates this sub-component with the desired Sheet
* instance.
*/
forComponent?: SheetId;
/**
* ---
* ## `asChild`
*
* - **Presence**: Optional
* - **Default**: `undefined`
*
* ### Description:
*
* Defines whether the sub-component underlying element is the
* default one or the one passed as child of the
* sub-component.
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `true` | The underlying element rendered is the child.
* | `false` | The underlying element rendered is the default one.
*
* ### Notes:
* - If the child is a React component rendering an element:
* - it must accept props and spread all received props onto
* the rendered element;
* - in React < 19, it must use `React.forwardRef()` and
* pass the received ref to the rendered element.
*/
asChild?: boolean;
}
interface TriggerPressHandlerOptions {
forceFocus?: boolean;
runAction?: boolean;
}
interface TriggerPressCustomEvent extends TriggerPressHandlerOptions {
changeDefault: (changedBehavior: TriggerPressHandlerOptions) => void;
nativeEvent: React.MouseEvent<HTMLElement, MouseEvent>;
}
type TriggerPressHandlerValue = TriggerPressHandlerOptions | ((customEvent: TriggerPressCustomEvent) => void);
interface StepActionWithOptions {
type: "step";
direction?: "up" | "down";
detent?: number;
}
export interface SheetTriggerProps extends OutletExclusiveProps, React.ButtonHTMLAttributes<HTMLButtonElement> {
"data-silk"?: string;
/**
* ---
* ## `forComponent`
*
* - **Presence**: Optional
* - **Default**: The `SheetId` of the closest `<Sheet.Root>` ancestor.
*
* ### Description:
*
* Associates this sub-component with the desired Sheet
* instance.
*/
forComponent?: SheetId;
/**
* ---
* ## `action`
*
* - **Presence**: Optional
* - **Default**: `"present"`
*
* ### Description:
*
* Defines the action that will execute when the Trigger is
* pressed.
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `"present"` | The Sheet will be presented. |
* | `"dismiss"` | The Sheet will be dismissed. |
* | `"step"` | The Sheet will step to the next detent in the upward direction, and cycle after reaching the last detent. |
* | `{ type: "step"; direction?: "up" \| "down"; detent?: number; }` | The Sheet will step to a detent: - if the `direction` key is used, it will step to the next detent in that direction and cycle after reaching the last detent; - if the `detent` key is used, it will step to the detent matching that detent index. |
*/
action?: "present" | "dismiss" | "step" | StepActionWithOptions;
/**
* ---
* ## `onPress`
*
* - **Presence**: Optional
* - **Default**: `{ forceFocus: true, runAction: true }`
*
* ### Description:
*
* An event handler that runs when the Trigger is pressed
* (equivalent to clicked).
*
* The underlying custom event has a default behavior that can
* be changed either by calling its `changeDefault` method
* with an option object as parameter, or by directly passing
* the option object to the prop.
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `{ forceFocus: true }` | The underlying element will be focused on press in all browsers (by default Safari doesn’t do it, causing issues with focus management). This is the recommended setting. |
* | `{ forceFocus: false }` | The underlying element will only receive focus on press in browsers where this is the default behavior (i.e. Safari will not do it). |
* | `{ runAction: true }` | The Trigger action will be run. |
* | `{ runAction: false }` | The Trigger action will not be run. |
*/
onPress?: TriggerPressHandlerValue;
onClick?: (e: React.MouseEvent<HTMLElement>) => void;
/**
* ---
* ## `asChild`
*
* - **Presence**: Optional
* - **Default**: `undefined`
*
* ### Description:
*
* Defines whether the sub-component underlying element is the
* default one or the one passed as child of the
* sub-component.
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `true` | The underlying element rendered is the child.
* | `false` | The underlying element rendered is the default one.
*
* ### Notes:
* - If the child is a React component rendering an element:
* - it must accept props and spread all received props onto
* the rendered element;
* - in React < 19, it must use `React.forwardRef()` and
* pass the received ref to the rendered element.
*/
asChild?: boolean;
}
interface HandleStepActionWithOptions {
type: "step";
direction?: "up" | "down";
}
interface HandleProps extends Omit<SheetTriggerProps, "action"> {
/**
* ---
* ## `action`
*
* - **Presence**: Optional
* - **Default**: `"step"`
*
* ### Description:
*
* Defines the action that will execute when the Handle is
* pressed.
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `"dismiss"` | The Sheet will be dismissed. |
* | `"step"` | The Sheet will step to the next detent in the upward direction, and cycle after reaching the last detent. |
* | `{ type: "step"; direction?: "up" \| "down"; detent?: number; }` | The Sheet will step to a detent: - if the `direction` key is used, it will step to the next detent in that direction and cycle after reaching the last detent; - if the `detent` key is used, it will step to the detent matching that detent index. |
*/
action?: "step" | HandleStepActionWithOptions | "dismiss";
}
export interface SheetPortalProps {
/**
* ---
* ## `container`
*
* - **Presence**: Optional
* - **Default**: `document.body`
*
* ### Description:
*
* Defines inside of which element the Portal’s child will be
* rendered.
*/
container?: HTMLElement | null;
children: React.ReactNode;
}
export interface SheetRootProps extends React.HTMLAttributes<HTMLDivElement> {
"data-silk"?: string;
/**
* ---
* ## `license`
*
* - **Presence**: Required
* - **Default**: `undefined`
*
* ### Description:
*
* Indicates under what license you are using the library.
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `"commercial"` | You declare using the library under the commercial license.
* | `"non-commercial"` | You declare using the library under the non-commercial license.
*
* ### Notes:
* - The purchase of a commercial license is needed for
* commercial use. More information
* [here](https://silkhq.com/access).
*/
license: "commercial" | "non-commercial";
/**
* ---
* ## `componentId`
*
* - **Presence**: Optional
* - **Default**: `undefined`
*
* ### Description:
*
* Defines the id of this Sheet instance. This id can then be
* passed to other Sheet sub-components `forComponent` prop to
* associate them with it.
*/
componentId?: SheetId;
/**
* ---
* ## `forComponent`
*
* - **Presence**: Optional
* - **Default**: `undefined`
*
* ### Description:
*
* Associates this Sheet instance with the desired SheetStack
* instance.
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `undefined` | This Sheet is not associated with any SheetStack.
* | `SheetStackId` | Associates this Sheet with the SheetStack whose id is passed.
* | `"closest"` | Associates this Sheet with the closest ancestor SheetStack.
*/
forComponent?: SheetStackId | "closest";
/**
* ---
* ## `sheetRole`
*
* - **Presence**: Optional
* - **Default**: `undefined`
*
* ### Description:
*
* Defines the WAI-ARIA role attribute set on the
* `<Sheet.View>` underlying element.
*
* This value is also used to define the presence of the
* `aria-haspopup` attribute on the `<Sheet.Trigger>`
* underlying element.
*
* ### Notes:
* - If `sheetRole` is set to `"alertdialog"`, then on `<Sheet.View>`:
* - `swipeDismissal` computes to `false`;
* - `onClickOutside` computes to `{ dismiss: false, stopOverlayPropagation: true }`;
* - `onEscapeKeyDown` computes to `{ dismiss: false, stopOverlayPropagation: true }`.
*/
sheetRole?: React.AriaRole;
/**
* ---
* ## `defaultPresented`
*
* - **Presence**: Optional
* - **Default**: `false`
*
* ### Description:
*
* Defines whether the Sheet is initially presented or not.
*
* ### Notes:
* - On page load, it is presented **after** hydration occurs
* when set to `true`.
*/
defaultPresented?: boolean;
/**
* ---
* ## `presented`
*
* - **Presence**: Optional
* - **Default**: `undefined`
* - **Requirements**: When this prop is used, passing the state setter function to the onPresentedChange is also required.
*
* ### Description:
*
* Controls the presented state of the Sheet.
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `undefined` | The `presented` state is uncontrolled, the Sheet will only be presented and dismissed based on user interactions handled internally (e.g. press on a `<Sheet.Trigger>`).
* | `true` | Will cause the Sheet to be presented if it is not currently.
* | `false` | Will cause the Sheet to be dismissed if it is currently presented. |
*
* ### Notes:
* - This is an alternative method to the `defaultPresented`
* prop.
*/
presented?: PresentedState;
/**
* ---
* ## `onPresentedChange`
*
* - **Presence**: Required if `presented` is used
* - **Default**: `undefined`
*
* ### Description:
*
* Setter for the state passed in the `presented` prop. It
* will be called with the `presented` state value as
* parameter when it is changed internally (e.g. press on a
* `<Sheet.Trigger>` sub-component).
*
* ### Notes:
* - This is an alternative method to the `defaultPresented`
* prop.
*/
onPresentedChange?: (presented: PresentedState) => void;
/**
* ---
* ## `defaultActiveDetent`
*
* - **Presence**: Optional
* - **Default**: `undefined`
*
* ### Description:
*
* Defines the index of the detent the Sheet should initially
* rest on after it gets presented.
*
* ### Notes:
* - Detents indexes are defined as follow:
* - when the Sheet is fully outside of the view, it rests
* on the detent with index `0`;
* - all declared intermediate detents indexes go from `1`
* to `n-1`;
* - when the Sheet is fully expanded inside of
* `<Sheet.View>`, it rests on the last detent, numbered
* `n` (e.g. index `1` if there is no intermediate
* detents; index `2` if there is one intermediate
* detent);
* - If `defaultActiveDetent` is set to `undefined`, the
* initial detent the Sheet rests on is the detent with
* the index `1`.
*/
defaultActiveDetent?: Detent;
/**
* ---
* ## `activeDetent`
*
* - **Presence**: Optional
* - **Default**: `undefined`
* - **Requirements**: When this prop is used, passing the state setter function to the `onPresentedChange` is also required.
*
* ### Description:
*
* Controls the `activeDetent` underlying state of the Sheet.
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `undefined` | The `activeDetent` state is uncontrolled, it will only change based on user interactions handled internally (e.g. swipe, or press on a `<Sheet.Trigger>`).
* | `number` | The `activeDetent` state is controlled, and this value reflects the index of the detent the Sheet is resting on or traveling towards.
*
* ### Notes:
* - This is an alternative method to the
* `defaultActiveDetent` prop.
*/
activeDetent?: Detent;
/**
* ---
* ## `onActiveDetentChange`
*
* - **Presence**: Required if `activeDetent` is used
* - **Default**: `undefined`
*
* ### Description:
*
* Setter for the state passed in the `activeDetent` prop. It
* will be called with the `activeDetent` state value as
* parameter when it is changed internally (e.g. swipe, or
* press on a `<Sheet.Trigger>`).
*
* ### Notes:
* - This is an alternative method to the `defaultActiveDetent`
* prop.
*/
onActiveDetentChange?: (detent: Detent) => void;
onSafeToUnmountChange?: (safeToUnmount: boolean) => void;
/**
* ---
* ## `asChild`
*
* - **Presence**: Optional
* - **Default**: `undefined`
*
* ### Description:
*
* Defines whether the sub-component underlying element is the
* default one or the one passed as child of the
* sub-component.
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `true` | The underlying element rendered is the child.
* | `false` | The underlying element rendered is the default one.
*
* ### Notes:
* - If the child is a React component rendering an element:
* - it must accept props and spread all received props onto
* the rendered element;
* - in React < 19, it must use `React.forwardRef()` and
* pass the received ref to the rendered element.
*/
asChild?: boolean;
children: React.ReactNode;
}
type Travelhandler = ({ progress, range, progressAtDetents, }: {
progress: TravelProgress;
range: TravelRange;
progressAtDetents: TravelProgressAtDetents;
}) => void | (() => void);
type SheetViewFocusInsideCustomEvent = {
nativeEvent: Event;
};
interface ViewAutoFocusHandlerOptions {
focus?: boolean;
}
interface ViewAutoFocusCustomEvent extends ViewAutoFocusHandlerOptions {
nativeEvent: null;
changeDefault: (changedBehavior: ViewAutoFocusHandlerOptions) => void;
}
type ViewAutoFocusHandlerValue = ViewAutoFocusHandlerOptions | ((customEvent: ViewAutoFocusCustomEvent) => void);
export interface SheetViewProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "role"> {
/**
* ---
* ## `forComponent`
*
* - **Presence**: Optional
* - **Default**: The `SheetId` of the closest `<Sheet.Root>` ancestor.
*
* ### Description:
*
* Associates this sub-component with the desired Sheet
* instance.
*/
forComponent?: SheetId;
children: React.ReactNode;
/**
* ---
* ## `contentPlacement`
*
* - **Presence**: Optional
* - **Default**: `"bottom"` if `tracks` is not set, otherwise
* it matches the value of `tracks`.
*
* ### Description:
*
* Defines the placement of `<Sheet.Content>` inside of
* `<Sheet.View>` on the travel axis. On the cross axis, it is
* always centered.
*/
contentPlacement?: "top" | "bottom" | "left" | "right" | "center";
/**
* ---
* ## `tracks`
*
* - **Presence**: Optional
* - **Default**: `"bottom"` if `contentPlacement` is not set,
* otherwise it matches the value of the `contentPlacement`.
*
* ### Description:
*
* Defines the track(s) `<Sheet.Content>` can travel on, from
* its last detent (index `n`) to its origin detent (index
* `0`).
*/
tracks?: TrackProp;
/**
* ---
* ## `detents`
*
* - **Presence**: Optional
* - **Default**: `undefined`
*
* ### Description:
*
* Defines one or several intermediate detents on which
* `<Sheet.Content>` can rest on the track between the origin
* detent (index `0`) and the last detent (index `n`).
*/
detents?: string | Array<string>;
/**
* ---
* ## `swipeTrap`
*
* - **Presence**: Optional
* - **Default**: `{ x: true, y: false }` on Android in
* non-standalone mode, `true` otherwise.
*
* ### Description:
*
* Defines whether swipes on the specified axis or axes are
* trapped within `<Sheet.View>` or not.
*
* When not trapped, when swiping in a direction where further
* travel is not possible, the swipe will propagate to the
* closest ancestor Sheet, scroll container, or window
* (triggering swipe to go back in history in browsers that
* support it).
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `true` | Traps swipe both on both the x and y axis. |
* | `{ x: true }` | Traps swipe on the x axis. |
* | `{ y: true }` | Traps swipe on the y axis. |
*
* ### Notes:
* - Always computes to `true` if `inertOutside` is set to
* `true`.
* - On Android in non-standalone mode, `swipeTrap` on the y
* axis always computes to `false` not to prevent the
* browser UI from being revealed.
* - If `swipeOvershoot` is set to `false`, `swipeTrap` on the
* travel axis always computes to `true`.
* - Safari has a bug causing swipe to always be trapped when
* swiping over a vertically swipeable Sheet or Scroll which
* is inside of a horizontally swipeable Sheet or Scroll
* (and vice versa). We hope to see that issue resolved
* quickly.
*/
swipeTrap?: boolean | {
x?: boolean;
y?: boolean;
};
/**
* ---
* ## `swipeOvershoot`
*
* - **Presence**: Optional
* - **Default**: `true`
*
* ### Description:
*
* Defines the behavior when the user performs a swipe that
* would cause `<Sheet.Content>` to move further than its last
* detent (index `n`).
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `true` | Overshoot will occur, causing `<Sheet.Content>` to move further than the last detent, and snap back into place when released. |
* | `false` | Overshoot will not occur, `<Sheet.Content>` will stop right away when being swiped past the last detent. |
*
* ### Notes:
* - Overshoot will works in browsers that support elastic
* overscroll (i.e. Safari, and Firefox on macOS).
*/
swipeOvershoot?: boolean;
/**
* ---
* ## `swipeDismissal`
*
* - **Presence**: Optional
* - **Default**: `false` if `sheetRole` is set to `"alertdialog"`, `true` otherwise.
*
* ### Description:
*
* Defines whether it is possible to swipe `<Sheet.Content>`
* out of the `<Sheet.View>` and cause the Sheet to be
* dismissed.
*
* ### Notes:
* - Always computes to `false` if `sheetRole` is set to
* `"alertdialog"`.
* - When set to `false` and `swipeOvershoot` is set to
* `true`, the Sheet remains swipeable but will snap back
* into place when a swipe occurs.
*/
swipeDismissal?: boolean;
/**
* ---
* ## `swipe`
*
* - **Presence**: Optional
* - **Default**: `true`
*
* ### Description:
*
* Defines whether swiping along the travel axis over
* `<Sheet.Content>` — or `<Sheet.Backdrop>` if swipeable —
* causes the Sheet to travel.
*
* ### Notes:
* - The value can only be updated when the Sheet is resting
* on a detent, not while it is traveling.
*/
swipe?: boolean;
/**
* ---
* ## `nativeEdgeSwipePrevention`
*
* - **Presence**: Optional
* - **Default**: `true`
*
* ### Description:
*
* Defines whether a horizontal swipe from the left edge of
* the screen on iOS Safari triggers the browser’s "go back"
* navigation gesture.
*
* ### Notes:
* - This mechanism relies on a `28px`-wide element positioned
* at the left edge of the screen. By default it appears
* above all elements inside `<Sheet.View>`, blocking
* interaction with anything underneath. If this causes
* issues, you can lift your elements above it by applying
* `position: relative` (or any non-static positioning) and
* a `z-index` value greater than `0`.
* - This element will also capture click outside events,
* preventing dismissal if the user clicks on it, even if
* visually outside of `<View.Content>`.
*/
nativeEdgeSwipePrevention?: boolean;
/**
* ---
* ## `enteringAnimationSettings`
*
* - **Presence**: Optional
* - **Default**: `{ preset: "smooth", contentMove: true, skip: prefersReducedMotion }`
*
* ### Description:
*
* Defines the configuration for the programmatic entering
* travel animation.
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `"gentle" \| { preset: "gentle" }` | Use the `"gentle"` preset. |
* | `{ track: "top" }` | For Sheet with two tracks defined, picks the track on which travel occurs (e.g. the `"top"` track here). |
* | `{ contentMove: false }` | The `<Sheet.Content>` underlying element will not be animated, instead it will be placed on its destination detent immediately. All other sub-components underlying elements are animated normally. |
* | `{ skip: true }` | The animation is skipped entirely and the Sheet doesn’t go through the corresponding state. |
*/
enteringAnimationSettings?: EnteringAnimationSettings;
/**
* ---
* ## `exitingAnimationSettings`
*
* - **Presence**: Optional
* - **Default**: `{ preset: "smooth", contentMove: true, skip: prefersReducedMotion }`
*
* ### Description:
*
* Defines the configuration for the programmatic exiting
* travel animation.
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `"gentle" \| { preset: "gentle" }` | Use the `"gentle"` preset. |
* | `{ track: "top" }` | For Sheet with two tracks defined, picks the track on which travel occurs (e.g. the `"top"` track here). |
* | `{ contentMove: false }` | The `<Sheet.Content>` underlying element will not be animated, instead it will be placed on its destination detent immediately. All other sub-components underlying elements are animated normally. |
* | `{ skip: true }` | The animation is skipped entirely and the Sheet doesn’t go through the corresponding state. |
*/
exitingAnimationSettings?: ExitingAnimationSettings;
/**
* ---
* ## `steppingAnimationSettings`
*
* - **Presence**: Optional
* - **Default**: `{ preset: "smooth", skip: prefersReducedMotion }`
*
* ### Description:
*
* Defines the configuration for the programmatic exiting
* travel animation.
*
* ### Values description:
*
* | Value | Description
* | :---- | :----------
* | `"gentle" \| { preset: "gentle" }` | Use the `"gentle"` preset. |
* | `{ skip: true }` | The animation is skipped entirely and the Sheet doesn’t go through the corresponding state. |
*/
steppingAnimationSettings?: SteppingAnimationSettings;
/**
* ---
* ## `onTravelStatusChange`
*
* - **Presence**: Optional
* - **Default**: `undefined`
*
* ### Description:
*
* An event handler that runs when the travel status changes.
*/
onTravelStatusChange?: (travelStatus: TravelStatus) => void;
/**
* ---
* ## `onTravelRangeChange`
*
* - **Presence**: Optional
* - **Default**: `undefined`
*
* ### Description:
* An event handler that runs when the travel range changes.
*
* ### Notes:
* - A range is defined by a start detent and an end detent.
* - The Sheet is considered to be within a range when the
* side of `<Sheet.Content>` opposite to the dismiss
* direction is located between the start and end detent of
* that range.
* - When the Sheet is resting on a specific detent, the start
* and end detent are equal to the index of that detent.
* - The range does not reflect overshoot. Therefore, if the
* Sheet is overshooting after the detent with index `1`,
* its travel range will be `{ start: 1, end: 1 }`.
*/
onTravelRangeChange?: (range: TravelRange) => void;
/**
* ---
* ## `onTravel`
*
* - **Presence**: Optional
* - **Default**: `undefined`
*
* ### Description:
*
* An event handler that runs on every frame when travel
* occurs, whether it is caused by swipe or programmatically.
*
* ### Parameters description:
*
* | Value | Description
* | :---- | :----------
* | `progress` | The progress value of the Sheet travel, going from `0` to `1`. It is `0` when the Sheet is fully out, and `1` when it is resting on the last detent. |
* | `range` | The travel range the Sheet is currently within. |
* | `p