@itwin/itwinui-react 3.0.0-dev.9 → 3.0.1

package/cjs/core/Tabs/Tabs.d.ts

@@ -1,28 +1,5 @@
 import * as React from 'react';
-export type OverflowOptions = {
-    /**
-     * Whether to allow tabs list to scroll when there is overflow,
-     * i.e. when there is not enough space to fit all the tabs.
-     *
-     * Not applicable to types `pill` and `borderless`.
-     */
-    useOverflow?: boolean;
-};
-type TabsOverflowProps = {
-    /**
-     * Options that can be specified to deal with tabs overflowing the allotted space.
-     */
-    overflowOptions?: OverflowOptions;
-    /**
-     * Type of the tabs.
-     *
-     * If `orientation = 'vertical'`, `pill` is not applicable.
-     * @default 'default'
-     */
-    type?: 'default';
-} | {
-    type: 'pill' | 'borderless';
-};
+import type { PolymorphicForwardRefComponent } from '../utils/index.js';
 type TabsOrientationProps = {
     /**
      * Orientation of the tabs.
@@ -40,24 +17,85 @@ type TabsOrientationProps = {
     orientation: 'vertical';
     type?: 'default' | 'borderless';
 };
-type TabsTypeProps = {
+type TabsWrapperOwnProps = {
     /**
-     * Type of the tabs.
+     * Color of the bar on the active tab.
+     * @default 'blue'
+     */
+    color?: 'blue' | 'green';
+    /**
+     * Control whether focusing tabs (using arrow keys) should automatically select them.
+     * Use 'manual' if tab panel content is not preloaded.
+     * @default 'auto'
+     */
+    focusActivationMode?: 'auto' | 'manual';
+    /**
+     * Value of the tab that should be active on initial render.
      *
-     * If `orientation = 'vertical'`, `pill` is not applicable.
-     * @default 'default'
+     * Should be used for uncontrolled state (when no `value` passed).
+     *
+     * If not specified, then first tab will be active by default.
      */
-    type?: 'default' | 'borderless';
+    defaultValue?: string;
+    /**
+     * Value of the active tab for controlled state.
+     */
+    value?: string;
+    /**
+     * Function that gets called when active tab is changed.
+     *
+     * Should be used alongside `value` prop.
+     */
+    onValueChange?: (value: string) => void;
+    /**
+     * @deprecated Do not use.
+     */
+    defaultChecked?: never;
+} & TabsOrientationProps;
+type TabListOwnProps = {
+    /**
+     * Tab items.
+     */
+    children: React.ReactNode[];
+};
+type TabOwnProps = {
+    /**
+     * Value used to associate the tab with a given panel.
+     */
+    value: string;
+    /**
+     * Tab label used for simple Tab construction.
+     * Cannot be used with tabs that have icons or descriptions.
+     */
+    label?: string | React.ReactNode;
+    /**
+     * @deprecated Don't pass `id`, as it will be automatically set.
+     */
+    id?: string;
+};
+type TabsActionsOwnProps = {
+    /**
+     * Passes props to the wrapper component for the actions
+     */
+    wrapperProps?: React.ComponentPropsWithRef<'div'>;
+};
+type TabsPanelOwnProps = {
+    /**
+     * Value used to associate the panel with a given tab.
+     */
+    value: string;
+    /**
+     * @deprecated Don't pass `id`, as it will be automatically set.
+     */
+    id?: string;
+};
+type TabsLegacyProps = {
     /**
      * Content displayed to the right/bottom of the horizontal/vertical tabs
      *
      * If `type = 'pill'`, `actions` is not applicable.
      */
     actions?: React.ReactNode[];
-} | {
-    type: 'pill';
-};
-export type TabsProps = {
     /**
      * Elements shown for each tab.
      * Recommended to pass an array of `Tab` components.
@@ -98,33 +136,165 @@ export type TabsProps = {
      * Content inside the tab panel.
      */
     children?: React.ReactNode;
-} & TabsOrientationProps & TabsTypeProps & TabsOverflowProps;
+    /**
+     * @deprecated Tabs will now overflow by default, so this prop does nothing.
+     */
+    overflowOptions?: {
+        /**
+         * @deprecated Tabs will now overflow by default, so this prop does nothing.
+         */
+        useOverflow?: boolean;
+    };
+    defaultValue?: never;
+    defaultChecked?: never;
+} & TabsOrientationProps;
+type TabLegacyProps = {
+    /**
+     * The main label shown in the tab.
+     */
+    label?: React.ReactNode;
+    /**
+     * Secondary label shown below the main label.
+     */
+    sublabel?: React.ReactNode;
+    /**
+     * Svg icon shown before the labels.
+     */
+    startIcon?: JSX.Element;
+    /**
+     * Control whether the tab is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Custom content appended to the tab.
+     */
+    children?: React.ReactNode;
+    /**
+     * `value` of the tab.
+     *
+     * Will be set by parent `Tabs` component.
+     */
+    value?: string;
+};
 /**
- * Tabs organize and allow navigation between groups of content that are related and at the same level of hierarchy.
+ * Legacy Tab component.
+ * For full functionality use composition API.
+ *
+ * Individual tab component to be used in the `labels` prop of `Tabs`.
  * @example
  * const tabs = [
- *   <Tab label='Label 1' />,
- *   <Tab label='Label 2' />,
- *   <Tab label='Label 3' />,
+ *   <Tab label='Label 1' sublabel='Description 1' />,
+ *   <Tab label='Label 2' startIcon={<SvgPlaceholder />} />,
  * ];
- * <Tabs labels={tabs} />
- *
+ */
+declare const LegacyTab: PolymorphicForwardRefComponent<"button", TabLegacyProps>;
+export { LegacyTab as Tab };
+/**
+ * Tabs organize and allow navigation between groups of content that are related and at the same level of hierarchy.
+ * `Tabs.Tab` and `Tabs.Panel` can be associated with each other by passing them the same `value`.
  * @example
- * <Tabs orientation='vertical' labels={tabs} />
+ * <Tabs.Wrapper>
+ *   <Tabs.TabList>
+ *     <Tabs.Tab value='tab1' label='Label 1' />
+ *     <Tabs.Tab value='tab2' label='Label 2' />
+ *     <Tabs.Tab value='tab3' label='Label 3' />
+ *   </Tabs.TabList>
+ *   <Tabs.ActionsWrapper>
+ *     <Tabs.Actions>
+ *       <Button>Sample Button</Button>
+ *     </Tabs.Actions>
+ *   </Tabs.ActionsWrapper>
+ *   <Tabs.Panel value='tab1'>Content 1</Tabs.Panel>
+ *   <Tabs.Panel value='tab2'>Content 2</Tabs.Panel>
+ *   <Tabs.Panel value='tab3'>Content 3</Tabs.Panel>
+ * </Tabs.Wrapper>
  *
  * @example
- * const tabsWithSublabels = [
- *   <Tab label='Label 1' sublabel='First tab' />,
- *   <Tab label='Label 2' sublabel='Active tab' />,
- * ];
- * <Tabs labels={tabsWithSublabels} activeIndex={1} />
+ * <Tabs orientation='vertical'/>
  *
  * @example
- * const tabsWithIcons = [
- *   <Tab label='Label 1' icon={<SvgPlaceholder />} />,
- *   <Tab label='Label 2' icon={<SvgPlaceholder />} />,
- * ];
- * <Tabs labels={tabsWithIcons} type='pill' />
+ * <Tabs.Wrapper focusActivationMode='manual'>
+ *  <Tabs.Tab value='sample'>
+ *   <Tabs.TabIcon>
+ *     <SvgPlaceholder />
+ *   </Tabs.TabIcon>
+ *   <Tabs.TabLabel>Sample Label</Tabs.TabLabel>
+ *   <Tabs.TabDescription>Sample Description</Tabs.TabDescription>
+ *  </Tabs.Tab>
+ * </Tabs.Wrapper>
  */
-export declare const Tabs: (props: TabsProps) => React.JSX.Element;
+export declare const Tabs: PolymorphicForwardRefComponent<"div", TabsLegacyProps> & {
+    /**
+     * A wrapper component for Tabs
+     */
+    Wrapper: PolymorphicForwardRefComponent<"div", TabsWrapperOwnProps>;
+    /**
+     * Tablist subcomponent which contains all of the tab subcomponents.
+     * @example
+     * <Tabs.TabList>
+     *   <Tabs.Tab value='tab1' label='Label 1' />
+     *   <Tabs.Tab value='tab2' label='Label 2' />
+     *   <Tabs.Tab value='tab3' label='Label 3' />
+     * </Tabs.TabList>
+     *
+     * @example
+     * <Tabs.TabList>
+     *   <Tabs.Tab value='tab1' label='Green Tab' />
+     * </Tabs.TabList>
+     *
+     * @example
+     * <Tabs.TabList focusActivationMode='manual'>
+     *   <Tabs.Tab value='tab1' label='Manual Focus Tab' />
+     * </Tabs.TabList>
+     */
+    TabList: PolymorphicForwardRefComponent<"div", TabListOwnProps>;
+    /**
+     * Tab subcomponent which is used for each of the tabs.
+     * @example
+     * <Tabs.Tab value='tab1' label='Label 1' />
+     *
+     * @example
+     * <Tabs.Tab value='sample'>
+     *   <Tabs.TabIcon>
+     *     <SvgPlaceholder />
+     *   </Tabs.TabIcon>
+     *   <Tabs.TabLabel>Sample Label</Tabs.TabLabel>
+     *   <Tabs.TabDescription>Sample Description</Tabs.TabDescription>
+     * </Tabs.Tab>
+     *
+     */
+    Tab: PolymorphicForwardRefComponent<"button", TabOwnProps>;
+    /**
+     * Tab icon subcomponent which places an icon on the left side of the tab.
+     */
+    TabIcon: PolymorphicForwardRefComponent<"span", Omit<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & {
+        ref?: ((instance: HTMLSpanElement | null) => void) | React.RefObject<HTMLSpanElement> | null | undefined;
+    }, "fill" | "as" | "key" | "size" | keyof React.HTMLAttributes<HTMLSpanElement> | "padded"> & {
+        size?: "small" | "auto" | "medium" | "large" | import("../utils/types.js").AnyString | undefined;
+        fill?: "default" | "informational" | "negative" | "positive" | "warning" | import("../utils/types.js").AnyString | undefined;
+        padded?: boolean | undefined;
+    } & Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & {
+        as?: "span" | undefined;
+    }>;
+    /**
+     * Tab label subcomponent which holds the tab's label.
+     */
+    TabLabel: PolymorphicForwardRefComponent<"span", {}>;
+    /**
+     * Tab description subcomponent which places a description under the tab label.
+     */
+    TabDescription: PolymorphicForwardRefComponent<"span", {}>;
+    /**
+     * Tab actions subcomponent which contains action buttons that are placed at the end of the tabs.
+     */
+    Actions: PolymorphicForwardRefComponent<"div", TabsActionsOwnProps>;
+    /**
+     * Tab panel subcomponent which contains the tab's content.
+     * @example
+     * <Tabs.Panel value='tab1'>
+     *   Sample Panel
+     * </Tabs.Panel>
+     */
+    Panel: PolymorphicForwardRefComponent<"div", TabsPanelOwnProps>;
+};
 export default Tabs;