@enact/sandstone/Panels/index.d.ts

Large-screen/TV support library for Enact, containing a variety of UI components.

// Type definitions for sandstone/Panels

import { RoutableProps as ui_Routable_RoutableProps } from "@enact/ui/Routable";
import { SpotlightContainerDecoratorProps as spotlight_SpotlightContainerDecorator_SpotlightContainerDecoratorProps } from "@enact/spotlight/SpotlightContainerDecorator";
import { SlottableProps as ui_Slottable_SlottableProps } from "@enact/ui/Slottable";
import { SkinnableProps as sandstone_Skinnable_SkinnableProps } from "@enact/sandstone/Skinnable";
import * as React from "react";
import { RouteProps as ui_Routable_RouteProps } from "@enact/ui/Routable";
import { Arranger as ui_ViewManager_Arranger } from "@enact/ui/ViewManager";

type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
type Merge<M, N> = Omit<M, Extract<keyof M, keyof N>> & N;

export interface PanelsProps {
  /**
 * Set of functions that control how the panels are transitioned into and out of the
viewport.
 */
  arranger?: ui_ViewManager_Arranger;
  /**
   * Hint string read when focusing the back button.
   */
  backButtonAriaLabel?: string;
  /**
   * Background opacity of the application back button.
   */
  backButtonBackgroundOpacity?: "opaque" | "transparent";
  /**
   *   to be rendered
   */
  children?: React.ReactNode;
  /**
   * Hint string read when focusing the application close button.
   */
  closeButtonAriaLabel?: string;
  /**
   * Background opacity of the application close button.
   */
  closeButtonBackgroundOpacity?: "opaque" | "transparent";
  /**
 * Customizes the component by mapping the supplied collection of CSS class names to the
corresponding internal elements and states of this component.
 * 
 * The following classes are supported:
 * *  `panels`  - The root class name
 * *  `viewport`  - The node containing the panel instances
 */
  css?: object;
  /**
 * Unique identifier for the Panels instance.
 * 
 * When defined,  `Panels`  will manage the presentation state of  `Panel`  instances in order
to restore it when returning to the  `Panel` . See
   for more details on shared
state.
 */
  id?: string;
  /**
   * Index of the active panel
   */
  index?: number;
  /**
   * Disables panel transitions.
   */
  noAnimation?: boolean;
  /**
   * Omits the back button.
   */
  noBackButton?: boolean;
  /**
   * Omits the close button.
   */
  noCloseButton?: boolean;
  /**
 * Prevents maintaining shared state for framework components within this  `Panels`  instance.
 * 
 * When  `false` , each  `Panel`  will track the state of some framework components in order to
restore that state when the Panel is recreated. For example, the scroll position of a
 `sandstone/Scroller`  within a  `Panel`  will be saved and restored when returning to that
 `Panel` .
 * 
 * This only applied when navigating "back" (to a lower index) to  `Panel` . When navigating
"forwards" (to a higher index), the  `Panel`  and its contained components will use their
default state.
 */
  noSharedState?: boolean;
  /**
   * Called with cancel/back key events.
   */
  onBack?: Function;
  /**
   * Called when the app close button is clicked.
   */
  onClose?: Function;
  /**
   * Called once when all panels have completed their transition.
   */
  onTransition?: Function;
  /**
   * Called once before panels begin their transition.
   */
  onWillTransition?: Function;
}
/**
 * Basic Panels component without a default
 */

export class Panels extends React.Component<
  Merge<React.HTMLProps<HTMLElement>, PanelsProps>
> {}

export interface PanelProps {
  /**
 * The "aria-label" for the Panel.
 * 
 * By default, the panel will be labeled by its   .
When  `aria-label`  is set, it will be used instead to provide an accessibility label for
the panel.
 */
  "aria-label"?: string;
  /**
   * Obtains a reference to the root node.
   */
  componentRef?: Function | object;
  /**
 * Customizes the component by mapping the supplied collection of CSS class names to the
corresponding internal elements and states of this component.
 * 
 * The following classes are supported:
 * *  `panel`  - The root class name
 * *  `body`  - The node containing the panel's children
 */
  css?: object;
  /**
 * Header for the panel.
 * 
 * This is usually passed by the    API by using a
   component as a child of the Panel.
 */
  header?: Header;
  /**
 * Hides the body components.
 * 
 * When a Panel is used within    this property will
be set automatically to  `true`  on render and  `false`  after animating into view.
 */
  hideChildren?: boolean;
  /**
 * Sets the strategy used to automatically focus an element within the panel upon render.
 * *  "none" - Automatic focus is disabled
 * *  "last-focused" - The element last focused in the panel with be restored
 * *  "default-element" - The first spottable component within the body will be focused
 * *  Custom Selector - A custom CSS selector may also be provided which will be used to find
the target within the Panel
 * 
 * When used within   , this prop may be set by
 `Panels`  to "default-element" when navigating "forward" to a higher index. This behavior
may be overridden by setting  `autoFocus`  on the  `Panel`  instance as a child of  `Panels` 
or by wrapping  `Panel`  with a custom component and overriding the value passed by
 `Panels` .
 * ```
// Panel within CustomPanel will always receive "last-focused"
const CustomPanel = (props) => <Panel {...props} autoFocus="last-focused" />;

// The first panel will always receive "last-focused". The second panel will receive
// "default-element" when navigating from the first panel but `autoFocus` will be unset
// when navigating from the third panel and as a result will default to "last-focused".
const MyPanels = () => (
  <Panels>
    <Panel autoFocus="last-focused" />
    <Panel />
    <Panel />
  </Panels>
);
```
 */
  autoFocus?: "default-element" | "last-focused" | "none" | string;
  /**
 * Prevents the component from restoring any framework shared state.
 * 
 * When  `false` , the default, Panel will store state for some framework components in order to
restore that state when returning to the Panel. Setting this prop to  `true`  will suppress that
behavior and not store or retrieve any framework component state.
 */
  noSharedState?: boolean;
  /**
 * The container id for   .
 * 
 * When the  `Panel`  is used within   , this prop will be
generated by  `Panels` . When using the panel alone, you need to specify this prop for restoring focus.
 */
  spotlightId?: string;
}
/**
 * A Panel is the standard view container used inside a    view
manager instance.
 * 
 *   will typically contain several instances of these and
transition between them.
 */

export class Panel extends React.Component<
  Merge<React.HTMLProps<HTMLElement>, PanelProps>
> {}

export interface HeaderProps {
  /**
   * Sets the hint string read when focusing the back button.
   */
  backButtonAriaLabel?: string;
  /**
   * Background opacity of the application back button.
   */
  backButtonBackgroundOpacity?: "opaque" | "transparent";
  /**
   * Centers the contents of the Header.
   *
   * This setting does not affect  `slotBefore`  or  `slotAfter` .
   */
  centered?: boolean;
  /**
   * Children provided are added to the header-components area.
   *
   * A space for controls which live in the header, apart from the body of the panel view.
   */
  children?: JSX.Element | JSX.Element[];
  /**
   * Hint string read when focusing the application close button.
   */
  closeButtonAriaLabel?: string;
  /**
   * Background opacity of the application close button.
   */
  closeButtonBackgroundOpacity?: "opaque" | "transparent";
  /**
 * Customizes the component by mapping the supplied collection of CSS class names to the
corresponding internal elements and states of this component.
 * 
 * The following classes are supported:
 * *  `header`  - The root class name
 */
  css?: object;
  /**
   * Determines what triggers the header content to start its animation.
   */
  marqueeOn?: "focus" | "hover" | "render";
  /**
   * Omits the back button.
   */
  noBackButton?: boolean;
  /**
   * Omits the close button.
   */
  noCloseButton?: boolean;
  /**
   * Omits the subtitle area.
   */
  noSubtitle?: boolean;
  /**
   * Called with cancel/back key events.
   */
  onBack?: Function;
  /**
   * Called when the app close button is clicked.
   */
  onClose?: Function;
  /**
   * Adds shadow to the text contents.
   */
  shadowed?: boolean;
  /**
 * A location for arbitrary elements to be placed above the title
 * 
 * This is a   , so it can be used as a tag-name inside
this component.
 * ```
<Header>
	<slotAbove><Button /></slotAbove>
	<title>My Title</title>
</Header>
```
 */
  slotAbove?: React.ReactNode;
  /**
 * A location for arbitrary elements to be placed to the right the title in LTR locales and
to the left in RTL locales
 * 
 * This is a   , so it can be used as a tag-name inside
this component.
 * ```
<Header>
	<title>My Title</title>
	<slotAfter><Button /></slotAfter>
</Header>
```
 */
  slotAfter?: React.ReactNode;
  /**
 * A location for arbitrary elements to be placed to the left the title in LTR locales and
to the right in RTL locales
 * 
 * This is a   , so it can be used as a tag-name inside
this component.
 * ```
<Header>
	<slotBefore><Button /></slotBefore>
	<title>My Title</title>
</Header>
```
 */
  slotBefore?: React.ReactNode;
  /**
 * Text displayed below the title.
 * 
 * This is a   , so it can be used as a tag-name inside
this component.
If    is  `true` , this prop is ignored.
 */
  subtitle?: string | string[];
  /**
 * Title of the header.
 * 
 * This is a   , so it can be used as a tag-name inside
this component.
 * 
 * Example:
 * ```
 <Header>
 	<title>Example Header Title</title>
 	<subtitle>The Adventure Continues</subtitle>
 </Header>
```
 */
  title?: string | string[];
  /**
   * Set the type of header to be used.
   */
  type?: "compact" | "mini" | "standard" | "wizard";
}
/**
 * A header component for a Panel with a  `title`  and  `subtitle` , supporting several configurable
   for components.
 */

export class Header extends React.Component<
  Merge<React.HTMLProps<HTMLElement>, HeaderProps>
> {}

export interface RoutableProps extends ui_Routable_RoutableProps {}
export function Routable<P>(
  Component: React.ComponentType<P> | string,
): React.ComponentType<P & RoutableProps>;

export interface RouteProps extends ui_Routable_RouteProps {}
/**
 * Used with    to define the  `path`  segment and the
 `component`  to render.
 */

export class Route extends React.Component<
  Merge<React.HTMLProps<HTMLElement>, RouteProps>
> {}

export interface PanelDecoratorProps
  extends Merge<
    Merge<
      spotlight_SpotlightContainerDecorator_SpotlightContainerDecoratorProps,
      ui_Slottable_SlottableProps
    >,
    sandstone_Skinnable_SkinnableProps
  > {}
export function PanelDecorator<P>(
  Component: React.ComponentType<P> | string,
): React.ComponentType<P & PanelDecoratorProps>;

export default Panels;